Merge branch 'master' into doc

README.md

@@ -15,10 +15,9 @@ Just add include path to `include` directory of this project.
 
 ## Syntax
 
-- `void` functions can be called in almost the same way as python code (remind yourself to append `_a` literal to keyword arguments).
-- For `non-void` functions that return some objects, basically the user will need to capsulate *arguments* in `args_(arg1, arg2, ...) == pybind11:tuple` and *keyword arguments* in `kwargs_("k1"_a = v1, "k2"_a = v2, ...) == pybind11::dict`. The returned value is a corresponding wrapper class. Please refer to the examples below.
-  - exception: `subplots`, 
-  - conversion: Wrapper class of matplotlibcpp17 like [::container::BarContainer](https://github.com/soblin/matplotlibcpp17/blob/master/include/matplotlibcpp17/container.h) needs to be passed to python interpreter using `unwrap()` method in *args* and *kwargs*.
+The user will need to capsulate *arguments* in `args_(arg1, arg2, ...) == pybind11:tuple` and *keyword arguments* in `kwargs_("k1"_a = v1, "k2"_a = v2, ...) == pybind11::dict`. The returned value is either a `pybind11::object` or a corresponding wrapper class. Please refer to the reference and examples below.
+- exception: `subplots`, `TBD`s
+- conversion: Wrapper class of matplotlibcpp17 like [::container::BarContainer](https://github.com/soblin/matplotlibcpp17/blob/master/include/matplotlibcpp17/container.h) needs to be passed to python interpreter using `unwrap()` method in *args* and *kwargs*.
 
 ## Examples
 
@@ -46,14 +45,12 @@ From [gallery/subplots_axes_and_figures/align_labels_demo.cpp](https://github.co
   /// gs is of type gridspec::GridSpec
   auto gs = GridSpec(2, 2);
 
-  // non-void function: capsulate args and kwargs in py::tuple and py::dict
   /// pass wrapper class object like gs[0, :] of ::gridspec::SubplotSpec to the interpreter using .unwrap() method as python object
   auto ax = fig.add_subplot(args_(gs(0, py::slice(0, 2, 1)).unwrap()));
 
-  // void function: no need to capsulate args and kwargs
-  ax.plot(arange(0, 1000000, 10000));
-  ax.set_ylabel("YLabel0");
-  ax.set_xlabel("XLabel0");
+  ax.plot(args_(arange(0, 1000000, 10000)));
+  ax.set_ylabel(args_("YLabel0"));
+  ax.set_xlabel(args_("XLabel0"));
 ```
 
 ![subplots_axes_and_figures](./gallery/images/align_labels_demo.png)
@@ -66,22 +63,22 @@ From [gallery/lines_bars_and_markers/bar_label_demo.cpp](https://github.com/sobl
 
 ```cpp
   auto [fig, ax] = plt.subplots();
-  // non-void function: capsulate args and kwargs in py::tuple and py::dict
   auto p1 = ax.bar(args_(ind, menMeans, width),
                    kwargs_("yerr"_a = menStd, "label"_a = "Men"));
   auto p2 = ax.bar(
       args_(ind, womenMeans, width),
       kwargs_("bottom"_a = menMeans, "yerr"_a = womenStd, "label"_a = "Women"));
-  ax.axhline(0, "color"_a = "grey", "linewidth"_a = 0.8);
-  ax.set_ylabel("Scores");
-  ax.set_title("Scores by group and gender");
-  ax.set_xticks(ind, py::make_tuple("G1", "G2", "G3", "G4", "G5"));
+  ax.axhline(args_(0), kwargs_("color"_a = "grey", "linewidth"_a = 0.8));
+  ax.set_ylabel(args_("Scores"));
+  ax.set_title(args_("Scores by group and gender"));
+
+  ax.set_xticks(args_(ind, py::make_tuple("G1", "G2", "G3", "G4", "G5")));
   ax.legend();
 
   // pass wrapper class object like p1 of ::container::BarContainer to the interpreter using .unwrap() method as python object
-  ax.bar_label(p1.unwrap(), "label_type"_a = "center");
-  ax.bar_label(p2.unwrap(), "label_type"_a = "center");
-  ax.bar_label(p2.unwrap());
+  ax.bar_label(args_(p1.unwrap()), kwargs_("label_type"_a = "center"));
+  ax.bar_label(args_(p2.unwrap()), kwargs_("label_type"_a = "center"));
+  ax.bar_label(args_(p2.unwrap()));
   plt.show();
 ```
 
@@ -116,7 +113,7 @@ From [gallery/images_contours_and_fields/quiver_demo.cpp](https://github.com/sob
 ```cpp
   auto plt = matplotlibcpp17::pyplot::import();
   auto [fig1, ax1] = plt.subplots();
-  ax1.set_title("pivot='tip'; scales with x view");
+  ax1.set_title(args_("Arrows scale with plot width, not view"));
   auto Q = ax1.quiver(args_(X, Y, U, V, M),
                       kwargs_("units"_a = "x", "pivot"_a = "tip",
                               "width"_a = 0.022, "scale"_a = 1.0 / 0.15));

gallery/artist_animation/animate_decay.cpp

@@ -22,8 +22,8 @@ int main() {
   const int N = 200;
   vector<double> ts, ys;
   auto [fig, ax] = plt.subplots();
-  ax.set_xlim(0, 10);
-  ax.set_ylim(-1.1, 1.1);
+  ax.set_xlim(args_(0, 10));
+  ax.set_ylim(args_(-1.1, 1.1));
   py::list artist_list;
   for (int i = 0; i < N; ++i) {
     double t = i * 1.0 / 10;
@@ -32,16 +32,17 @@ int main() {
     ys.push_back(y);
     auto [xmin, xmax] = ax.get_xlim();
     if (t >= xmax)
-      ax.set_xlim(xmin, 2 * xmax);
-    py::object line = ax.plot(ts, ys, "color"_a = "blue", "lw"_a = 1);
+      ax.set_xlim(args_(xmin, 2 * xmax));
+    py::object line =
+        ax.plot(args_(ts, ys), kwargs_("color"_a = "blue", "lw"_a = 1));
     artist_list.append(line);
   }
   auto ani = ArtistAnimation(args_(fig.unwrap(), artist_list),
                              kwargs_("interval"_a = 10));
 #if USE_GUI
   plt.show();
 #else
-  ani.save("animate_decay.gif", "writer"_a = "pillow");
+  ani.save(args_("animate_decay.gif"), kwargs_("writer"_a = "pillow"));
 #endif
   return 0;
 }

gallery/artist_animation/cla_pause.cpp

@@ -18,11 +18,11 @@ int main() {
   vector<int> data;
   const int N = 10;
   for (int i = 0; i <= N; ++i) {
-    plt.xlim(0, 10);
-    plt.ylim(0, 10);
+    plt.xlim(args_(0, 10));
+    plt.ylim(args_(0, 10));
     data.push_back(i);
-    plt.plot(data);
-    plt.pause(1);
+    plt.plot(args_(data));
+    plt.pause(args_(1));
     plt.cla();
   }
   return 0;

gallery/artist_animation/random_walk.cpp

@@ -34,7 +34,7 @@ int main() {
   py::scoped_interpreter guard{};
   auto plt = matplotlibcpp17::pyplot::import();
   auto fig = plt.figure();
-  auto ax = fig.add_subplot(py::tuple(), kwargs_("projection"_a = "3d"));
+  auto ax = fig.add_subplot(py::make_tuple(), kwargs_("projection"_a = "3d"));
   py::list artist_list;
   const int M = 4;
   const int N = 30;
@@ -55,7 +55,7 @@ int main() {
                  ys.push_back(pos[1]);
                  zs.push_back(pos[2]);
                });
-      ax.plot(xs, ys, zs, "color"_a = colors[i]);
+      ax.plot(args_(xs, ys, zs), kwargs_("color"_a = colors[i]));
     }
     artist_list.append(ax.get_lines());
   }
@@ -64,7 +64,7 @@ int main() {
 #if USE_GUI
   plt.show();
 #else
-  ani.save("random_walk.gif", "writer"_a = "pillow");
+  ani.save(args_("random_walk.gif"), kwargs_("writer"_a = "pillow"));
 #endif
   return 0;
 }

gallery/images_contours_and_fields/quiver_demo.cpp

@@ -30,15 +30,15 @@ int main1() {
             [](double y) { return sin(y); });
   auto plt = matplotlibcpp17::pyplot::import();
   auto [fig1, ax1] = plt.subplots();
-  ax1.set_title("Arrows scale with plot width, not view");
+  ax1.set_title(args_("Arrows scale with plot width, not view"));
   auto Q = ax1.quiver(args_(X, Y, U, V), kwargs_("units"_a = "width"));
   auto qk =
       ax1.quiverkey(args_(Q.unwrap(), 0.9, 0.9, 2, R"($2 \frac{m}{s}$)"),
                     kwargs_("labelpos"_a = "E", "coordinates"_a = "figure"));
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("quiver_demo_1.png");
+  plt.savefig(args_("quiver_demo_1.png"));
 #endif
   return 0;
 }
@@ -58,7 +58,7 @@ int main2() {
             [](double y) { return sin(y); });
   auto plt = matplotlibcpp17::pyplot::import();
   auto [fig1, ax1] = plt.subplots();
-  ax1.set_title("pivot='mid'; every third arrow; units='inches'");
+  ax1.set_title(args_("pivot='mid'; every third arrow; units='inches'"));
   auto Q = ax1.quiver(args_(X, Y, U, V),
                       kwargs_("pivot"_a = "mid", "units"_a = "inches"));
   auto qk =
@@ -69,7 +69,7 @@ int main2() {
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("quiver_demo_2.png");
+  plt.savefig(args_("quiver_demo_2.png"));
 #endif
   return 0;
 }
@@ -92,7 +92,7 @@ int main3() {
   }
   auto plt = matplotlibcpp17::pyplot::import();
   auto [fig1, ax1] = plt.subplots();
-  ax1.set_title("pivot='tip'; scales with x view");
+  ax1.set_title(args_("pivot='tip'; scales with x view"));
   auto Q = ax1.quiver(args_(X, Y, U, V, M),
                       kwargs_("units"_a = "x", "pivot"_a = "tip",
                               "width"_a = 0.022, "scale"_a = 1.0 / 0.15));
@@ -104,7 +104,7 @@ int main3() {
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("quiver_demo_3.png");
+  plt.savefig(args_("quiver_demo_3.png"));
 #endif
 
   return 0;

gallery/lines_bars_and_markers/bar_label_demo.cpp

@@ -33,20 +33,20 @@ int main1() {
   auto p2 = ax.bar(
       args_(ind, womenMeans, width),
       kwargs_("bottom"_a = menMeans, "yerr"_a = womenStd, "label"_a = "Women"));
-  ax.axhline(0, "color"_a = "grey", "linewidth"_a = 0.8);
-  ax.set_ylabel("Scores");
-  ax.set_title("Scores by group and gender");
-  ax.set_xticks(ind, py::make_tuple("G1", "G2", "G3", "G4", "G5"));
+  ax.axhline(args_(0), kwargs_("color"_a = "grey", "linewidth"_a = 0.8));
+  ax.set_ylabel(args_("Scores"));
+  ax.set_title(args_("Scores by group and gender"));
+  ax.set_xticks(args_(ind, py::make_tuple("G1", "G2", "G3", "G4", "G5")));
   ax.legend();
 
   // Label with label_type 'center' instead of the default 'edge'
-  ax.bar_label(p1.unwrap(), "label_type"_a = "center");
-  ax.bar_label(p2.unwrap(), "label_type"_a = "center");
-  ax.bar_label(p2.unwrap());
+  ax.bar_label(args_(p1.unwrap()), kwargs_("label_type"_a = "center"));
+  ax.bar_label(args_(p2.unwrap()), kwargs_("label_type"_a = "center"));
+  ax.bar_label(args_(p2.unwrap()));
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("bar_label_demo1.png");
+  plt.savefig(args_("bar_label_demo1.png"));
 #endif
   return 0;
 }
@@ -62,18 +62,18 @@ int main2() {
   auto [fig, ax] = plt.subplots();
   auto hbars = ax.barh(args_(y_pos, performance),
                        kwargs_("xerr"_a = error, "align"_a = "center"));
-  ax.set_yticks(y_pos, "labels"_a = people);
+  ax.set_yticks(args_(y_pos), kwargs_("labels"_a = people));
   ax.invert_yaxis(); // labels read top-to-bottom
-  ax.set_xlabel("Performance");
-  ax.set_title("How fast do you want to go today?");
+  ax.set_xlabel(args_("Performance"));
+  ax.set_title(args_("How fast do you want to go today?"));
 
   // Label with specially formatted floats
-  ax.bar_label(hbars.unwrap(), "fmt"_a = "%.2f");
-  ax.set_xlim("right"_a = 15); // adjust xlim to fit labels
+  ax.bar_label(args_(hbars.unwrap()), kwargs_("fmt"_a = "%.2f"));
+  ax.set_xlim(args_(), kwargs_("right"_a = 15)); // adjust xlim to fit labels
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("bar_label_demo2.png");
+  plt.savefig(args_("bar_label_demo2.png"));
 #endif
   return 0;
 }
@@ -89,10 +89,10 @@ int main3() {
   auto [fig, ax] = plt.subplots();
   auto hbars = ax.barh(args_(y_pos, performance),
                        kwargs_("xerr"_a = error, "align"_a = "center"));
-  ax.set_yticks(y_pos, "labels"_a = people);
+  ax.set_yticks(args_(y_pos), kwargs_("labels"_a = people));
   ax.invert_yaxis(); // labels read top-to-bottom
-  ax.set_xlabel("Performance");
-  ax.set_title("How fast do you want to go today?");
+  ax.set_xlabel(args_("Performance"));
+  ax.set_title(args_("How fast do you want to go today?"));
 
   // Label with specially formatted floats
   vector<string> labels;
@@ -101,13 +101,13 @@ int main3() {
     stm << std::fixed << std::setprecision(2) << e;
     return "±" + stm.str();
   });
-  ax.bar_label(hbars.unwrap(), "labels"_a = labels, "padding"_a = 8,
-               "color"_a = "b", "fontsize"_a = 14);
-  ax.set_xlim("right"_a = 15); // adjust xlim to fit labels
+  ax.bar_label(args_(hbars.unwrap()), kwargs_("labels"_a = labels, "padding"_a = 8,
+               "color"_a = "b", "fontsize"_a = 14));
+  ax.set_xlim(args_(), kwargs_("right"_a = 15)); // adjust xlim to fit labels
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("bar_label_demo3.png");
+  plt.savefig(args_("bar_label_demo3.png"));
 #endif
   return 0;
 }

gallery/lines_bars_and_markers/fill.cpp

@@ -36,15 +36,15 @@ int main() {
                    kwargs_("figsize"_a = py::make_tuple(9, 3),
                            "subplot_kw"_a = py::dict("aspect"_a = "equal")));
   auto ax1 = axes[0], ax2 = axes[1], ax3 = axes[2];
-  ax1.fill(x, y);
-  ax2.fill(x, y, "facecolor"_a = "lightsalmon", "edgecolor"_a = "orangered",
-           "linewidth"_a = 3);
-  ax3.fill(x, y, "facecolor"_a = "none", "edgecolor"_a = "purple",
-           "linewidth"_a = 3);
+  ax1.fill(args_(x, y));
+  ax2.fill(args_(x, y), kwargs_("facecolor"_a = "lightsalmon", "edgecolor"_a = "orangered",
+           "linewidth"_a = 3));
+  ax3.fill(args_(x, y), kwargs_("facecolor"_a = "none", "edgecolor"_a = "purple",
+           "linewidth"_a = 3));
 #if USE_GUI
   plt.show();
 #else
-  plt.savefig("fill.png");
+  plt.savefig(args_("fill.png"));
 #endif
   return 0;
 }