Intermediate changes

commit_hash:ab55b3b972e940f79570e58af046841fae66b70c

1 files changed, 91 insertions, 103 deletions

diff --git a/contrib/python/contourpy/src/wrap.cpp b/contrib/python/contourpy/src/wrap.cpp
index b784f814a5..fede228095 100644
--- a/contrib/python/contourpy/src/wrap.cpp
+++ b/contrib/python/contourpy/src/wrap.cpp
@@ -13,18 +13,19 @@
 #define MACRO_STRINGIFY(x) STRINGIFY(x)
 
 namespace py = pybind11;
+using namespace pybind11::literals;
 
 static contourpy::LineType mpl20xx_line_type = contourpy::LineType::SeparateCode;
 static contourpy::FillType mpl20xx_fill_type = contourpy::FillType::OuterCode;
 
-PYBIND11_MODULE(_contourpy, m) {
+PYBIND11_MODULE(_contourpy, m, py::mod_gil_not_used()) {
     m.doc() =
         "C++11 extension module wrapped using `pybind11`_.\n\n"
         "It should not be necessary to access classes and functions in this extension module "
-        "directly. Instead, :func:`contourpy.contour_generator` should be used to create "
-        ":class:`~contourpy.ContourGenerator` objects, and the enums "
-        "(:class:`~contourpy.FillType`, :class:`~contourpy.LineType` and "
-        ":class:`~contourpy.ZInterp`) and :func:`contourpy.max_threads` function are all available "
+        "directly. Instead, :func:`~contourpy.contour_generator` should be used to create "
+        ":class:`~.ContourGenerator` objects, and the enums "
+        "(:class:`~.FillType`, :class:`~.LineType` and "
+        ":class:`~.ZInterp`) and :func:`.max_threads` function are all available "
         "in the :mod:`contourpy` module.";
 
     m.attr("__version__") = MACRO_STRINGIFY(CONTOURPY_VERSION);
@@ -38,9 +39,9 @@ PYBIND11_MODULE(_contourpy, m) {
 #endif
 
     py::enum_<contourpy::FillType>(m, "FillType",
-        "Enum used for ``fill_type`` keyword argument in :func:`~contourpy.contour_generator`.\n\n"
+        "Enum used for ``fill_type`` keyword argument in :func:`~.contour_generator`.\n\n"
         "This controls the format of filled contour data returned from "
-        ":meth:`~contourpy.ContourGenerator.filled`.")
+        ":meth:`~.ContourGenerator.filled`.")
         .value("OuterCode", contourpy::FillType::OuterCode)
         .value("OuterOffset", contourpy::FillType::OuterOffset)
         .value("ChunkCombinedCode", contourpy::FillType::ChunkCombinedCode)
@@ -50,9 +51,9 @@ PYBIND11_MODULE(_contourpy, m) {
         .export_values();
 
     py::enum_<contourpy::LineType>(m, "LineType",
-        "Enum used for ``line_type`` keyword argument in :func:`~contourpy.contour_generator`.\n\n"
+        "Enum used for ``line_type`` keyword argument in :func:`~.contour_generator`.\n\n"
         "This controls the format of contour line data returned from "
-        ":meth:`~contourpy.ContourGenerator.lines`.\n\n"
+        ":meth:`~.ContourGenerator.lines`.\n\n"
         "``LineType.ChunkCombinedNan`` added in version 1.2.0")
         .value("Separate", contourpy::LineType::Separate)
         .value("SeparateCode", contourpy::LineType::SeparateCode)
@@ -62,7 +63,7 @@ PYBIND11_MODULE(_contourpy, m) {
         .export_values();
 
     py::enum_<contourpy::ZInterp>(m, "ZInterp",
-        "Enum used for ``z_interp`` keyword argument in :func:`~contourpy.contour_generator`\n\n"
+        "Enum used for ``z_interp`` keyword argument in :func:`~.contour_generator`\n\n"
         "This controls the interpolation used on ``z`` values to determine where contour lines "
         "intersect the edges of grid quads, and ``z`` values at quad centres.")
         .value("Linear", contourpy::ZInterp::Linear)
@@ -73,47 +74,88 @@ PYBIND11_MODULE(_contourpy, m) {
         "Return the maximum number of threads, obtained from "
         "``std::thread::hardware_concurrency()``.\n\n"
         "This is the number of threads used by a multithreaded ContourGenerator if the kwarg "
-        "``threads=0`` is passed to :func:`~contourpy.contour_generator`.");
+        "``threads=0`` is passed to :func:`~.contour_generator`.");
 
     const char* chunk_count_doc = "Return tuple of (y, x) chunk counts.";
     const char* chunk_size_doc = "Return tuple of (y, x) chunk sizes.";
     const char* corner_mask_doc = "Return whether ``corner_mask`` is set or not.";
     const char* create_contour_doc =
-        "Synonym for :func:`~contourpy.ContourGenerator.lines` to provide backward compatibility "
+        "Synonym for :meth:`~.ContourGenerator.lines` to provide backward compatibility "
         "with Matplotlib.";
     const char* create_filled_contour_doc =
-        "Synonym for :func:`~contourpy.ContourGenerator.filled` to provide backward compatibility "
+        "Synonym for :meth:`~.ContourGenerator.filled` to provide backward compatibility "
         "with Matplotlib.";
-    const char* default_fill_type_doc = "Return the default ``FillType`` used by this algorithm.";
-    const char* default_line_type_doc = "Return the default ``LineType`` used by this algorithm.";
-    const char* fill_type_doc = "Return the ``FillType``.";
+    const char* default_fill_type_doc =
+        "Return the default :class:`~.FillType` used by this algorithm.";
+    const char* default_line_type_doc =
+        "Return the default :class:`~.LineType` used by this algorithm.";
+    const char* fill_type_doc = "Return the :class:`~.FillType`.";
     const char* filled_doc =
         "Calculate and return filled contours between two levels.\n\n"
         "Args:\n"
-        "    lower_level (float): Lower z-level of the filled contours.\n"
-        "    upper_level (float): Upper z-level of the filled contours.\n"
+        "    lower_level (float): Lower z-level of the filled contours, cannot be ``np.nan``.\n"
+        "    upper_level (float): Upper z-level of the filled contours, cannot be ``np.nan``.\n"
         "Return:\n"
-        "    Filled contour polygons as one or more sequences of numpy arrays. The exact format is "
-        "determined by the ``fill_type`` used by the ``ContourGenerator``.\n\n"
-        "Raises a ``ValueError`` if ``lower_level >= upper_level``.\n\n"
+        "    Filled contour polygons as nested sequences of numpy arrays. The exact format is "
+        "determined by the :attr:`~.ContourGenerator.fill_type` used by the ``ContourGenerator`` "
+        "and the options are explained at :ref:`fill_type`.\n\n"
+        "Raises a ``ValueError`` if ``lower_level >= upper_level`` or if\n"
+        "``lower_level`` or ``upper_level`` are ``np.nan``.\n\n"
         "To return filled contours below a ``level`` use ``filled(-np.inf, level)``.\n"
         "To return filled contours above a ``level`` use ``filled(level, np.inf)``";
-    const char* line_type_doc = "Return the ``LineType``.";
+    const char* line_type_doc = "Return the :class:`~.LineType`.";
     const char* lines_doc =
         "Calculate and return contour lines at a particular level.\n\n"
         "Args:\n"
         "    level (float): z-level to calculate contours at.\n\n"
         "Return:\n"
-        "    Contour lines (open line strips and closed line loops) as one or more sequences of "
-        "numpy arrays. The exact format is determined by the ``line_type`` used by the "
-        "``ContourGenerator``.";
+        "    Contour lines (open line strips and closed line loops) as nested sequences of "
+        "numpy arrays. The exact format is determined by the :attr:`~.ContourGenerator.line_type` "
+        "used by the ``ContourGenerator`` and the options are explained at :ref:`line_type`.\n\n"
+        "``level`` may be ``np.nan``, ``np.inf`` or ``-np.inf``; they all return the same result "
+        "which is an empty line set.";
+    const char* multi_filled_doc =
+        "Calculate and return filled contours between multiple pairs of adjacent levels.\n\n"
+        "Args:\n"
+        "    levels (array-like of floats): z-levels to calculate filled contours between. "
+        "There must be at least 2 levels, they cannot be NaN, and each level must be larger than "
+        "the previous level.\n\n"
+        "Return:\n"
+        "    List of filled contours, one per pair of levels. The length of the returned list is "
+        "one less than ``len(levels)``. The format of returned contours is determined by the "
+        "``fill_type`` used by the ``ContourGenerator`` and the options are explained at "
+        ":ref:`fill_type`.\n\n"
+        "Raises a ``ValueError`` if ``levels`` are not increasing, or contain a NaN, or there are "
+        "fewer than 2 ``levels``.\n\n"
+        "Calling:\n\n"
+        ".. code-block:: python\n\n"
+        "    ret = cont_gen.multi_filled(levels)\n\n"
+        "is equivalent to:\n\n"
+        ".. code-block:: python\n\n"
+        "    ret = [cont_gen.filled(lower, upper) for lower, upper in zip(levels[:-1], levels[1:])]\n\n"
+        ".. versionadded:: 1.3.0";
+    const char* multi_lines_doc =
+        "Calculate and return contour lines at multiple levels.\n\n"
+        "Args:\n"
+        "    levels (array-like of floats): z-levels to calculate contours at.\n\n"
+        "Return:\n"
+        "    List of contour lines, one per level. The format of returned lines is determined by "
+        "the ``line_type`` used by the ``ContourGenerator`` and the options are explained at "
+        ":ref:`line_type`.\n\n"
+        "Calling:\n\n"
+        ".. code-block:: python\n\n"
+        "    ret = cont_gen.multi_lines(levels)\n\n"
+        "is equivalent to:\n\n"
+        ".. code-block:: python\n\n"
+        "    ret = [cont_gen.lines(level) for level in levels]\n\n"
+        ".. versionadded:: 1.3.0";
     const char* quad_as_tri_doc = "Return whether ``quad_as_tri`` is set or not.";
     const char* supports_corner_mask_doc =
         "Return whether this algorithm supports ``corner_mask``.";
     const char* supports_fill_type_doc =
-        "Return whether this algorithm supports a particular ``FillType``.";
+        "Return whether this algorithm supports a particular :class:`~.FillType`.";
     const char* supports_line_type_doc =
-        "Return whether this algorithm supports a particular ``LineType``.";
+        "Return whether this algorithm supports a particular :class:`~.LineType`.";
     const char* supports_quad_as_tri_doc =
         "Return whether this algorithm supports ``quad_as_tri``.";
     const char* supports_threads_doc =
@@ -127,18 +169,15 @@ PYBIND11_MODULE(_contourpy, m) {
     py::class_<contourpy::ContourGenerator>(m, "ContourGenerator",
         "Abstract base class for contour generator classes, defining the interface that they all "
         "implement.")
-        .def("create_contour",
-            [](py::object /* self */, double level) {return py::make_tuple();},
-            py::arg("level"), create_contour_doc)
-        .def("create_filled_contour",
-            [](py::object /* self */, double lower_level, double upper_level) {return py::make_tuple();},
-            py::arg("lower_level"), py::arg("upper_level"), create_filled_contour_doc)
-        .def("filled",
-            [](py::object /* self */, double lower_level, double upper_level) {return py::make_tuple();},
-            py::arg("lower_level"), py::arg("upper_level"), filled_doc)
-        .def("lines",
-            [](py::object /* self */, double level) {return py::make_tuple();},
-            py::arg("level"), lines_doc)
+        .def("create_contour", &contourpy::ContourGenerator::lines, create_contour_doc, "level"_a)
+        .def("create_filled_contour", &contourpy::ContourGenerator::filled,
+             create_filled_contour_doc, "lower_level"_a, "upper_level"_a)
+        .def("filled", &contourpy::ContourGenerator::filled, filled_doc,
+             "lower_level"_a, "upper_level"_a)
+        .def("lines", &contourpy::ContourGenerator::lines, lines_doc, "level"_a)
+        .def("multi_filled", &contourpy::ContourGenerator::multi_filled, multi_filled_doc,
+             "levels"_a)
+        .def("multi_lines", &contourpy::ContourGenerator::multi_lines, multi_lines_doc, "levels"_a)
         .def_property_readonly(
             "chunk_count", [](py::object /* self */) {return py::make_tuple(1, 1);},
             chunk_count_doc)
@@ -169,10 +208,10 @@ PYBIND11_MODULE(_contourpy, m) {
         .def_static("supports_corner_mask", []() {return false;}, supports_corner_mask_doc)
         .def_static(
             "supports_fill_type", [](contourpy::FillType /* fill_type */) {return false;},
-            py::arg("fill_type"), supports_fill_type_doc)
+            "fill_type"_a, supports_fill_type_doc)
         .def_static(
             "supports_line_type", [](contourpy::LineType /* line_type */) {return false;},
-            py::arg("line_type"), supports_line_type_doc)
+            "line_type"_a, supports_line_type_doc)
         .def_static("supports_quad_as_tri", []() {return false;}, supports_quad_as_tri_doc)
         .def_static("supports_threads", []() {return false;}, supports_threads_doc)
         .def_static("supports_z_interp", []() {return false;}, supports_z_interp_doc);
@@ -193,18 +232,8 @@ PYBIND11_MODULE(_contourpy, m) {
                       const contourpy::MaskArray&,
                       contourpy::index_t,
                       contourpy::index_t>(),
-             py::arg("x"),
-             py::arg("y"),
-             py::arg("z"),
-             py::arg("mask"),
-             py::kw_only(),
-             py::arg("x_chunk_size") = 0,
-             py::arg("y_chunk_size") = 0)
-        .def("create_contour", &contourpy::Mpl2005ContourGenerator::lines, create_contour_doc)
-        .def("create_filled_contour", &contourpy::Mpl2005ContourGenerator::filled,
-            create_filled_contour_doc)
-        .def("filled", &contourpy::Mpl2005ContourGenerator::filled, filled_doc)
-        .def("lines", &contourpy::Mpl2005ContourGenerator::lines, lines_doc)
+             "x"_a, "y"_a, "z"_a, "mask"_a, py::kw_only(), "x_chunk_size"_a = 0,
+             "y_chunk_size"_a = 0)
         .def_property_readonly(
             "chunk_count", &contourpy::Mpl2005ContourGenerator::get_chunk_count, chunk_count_doc)
         .def_property_readonly(
@@ -247,20 +276,8 @@ PYBIND11_MODULE(_contourpy, m) {
                       bool,
                       contourpy::index_t,
                       contourpy::index_t>(),
-             py::arg("x"),
-             py::arg("y"),
-             py::arg("z"),
-             py::arg("mask"),
-             py::kw_only(),
-             py::arg("corner_mask"),
-             py::arg("x_chunk_size") = 0,
-             py::arg("y_chunk_size") = 0)
-        .def("create_contour", &contourpy::mpl2014::Mpl2014ContourGenerator::lines,
-            create_contour_doc)
-        .def("create_filled_contour", &contourpy::mpl2014::Mpl2014ContourGenerator::filled,
-            create_filled_contour_doc)
-        .def("filled", &contourpy::mpl2014::Mpl2014ContourGenerator::filled, filled_doc)
-        .def("lines", &contourpy::mpl2014::Mpl2014ContourGenerator::lines, lines_doc)
+             "x"_a, "y"_a, "z"_a, "mask"_a, py::kw_only(), "corner_mask"_a, "x_chunk_size"_a = 0,
+             "y_chunk_size"_a = 0)
         .def_property_readonly(
             "chunk_count", &contourpy::mpl2014::Mpl2014ContourGenerator::get_chunk_count,
             chunk_count_doc)
@@ -307,24 +324,10 @@ PYBIND11_MODULE(_contourpy, m) {
                       contourpy::ZInterp,
                       contourpy::index_t,
                       contourpy::index_t>(),
-             py::arg("x"),
-             py::arg("y"),
-             py::arg("z"),
-             py::arg("mask"),
-             py::kw_only(),
-             py::arg("corner_mask"),
-             py::arg("line_type"),
-             py::arg("fill_type"),
-             py::arg("quad_as_tri"),
-             py::arg("z_interp"),
-             py::arg("x_chunk_size") = 0,
-             py::arg("y_chunk_size") = 0)
+             "x"_a, "y"_a, "z"_a, "mask"_a, py::kw_only(), "corner_mask"_a, "line_type"_a,
+             "fill_type"_a, "quad_as_tri"_a, "z_interp"_a, "x_chunk_size"_a = 0,
+             "y_chunk_size"_a = 0)
         .def("_write_cache", &contourpy::SerialContourGenerator::write_cache)
-        .def("create_contour", &contourpy::SerialContourGenerator::lines, create_contour_doc)
-        .def("create_filled_contour", &contourpy::SerialContourGenerator::filled,
-            create_filled_contour_doc)
-        .def("filled", &contourpy::SerialContourGenerator::filled, filled_doc)
-        .def("lines", &contourpy::SerialContourGenerator::lines, lines_doc)
         .def_property_readonly(
             "chunk_count", &contourpy::SerialContourGenerator::get_chunk_count, chunk_count_doc)
         .def_property_readonly(
@@ -359,7 +362,7 @@ PYBIND11_MODULE(_contourpy, m) {
     py::class_<contourpy::ThreadedContourGenerator, contourpy::ContourGenerator>(
         m, "ThreadedContourGenerator",
         "ContourGenerator corresponding to ``name=\"threaded\"``, the multithreaded version of "
-        ":class:`~contourpy._contourpy.SerialContourGenerator`.\n\n"
+        ":class:`~.SerialContourGenerator`.\n\n"
         "Supports ``corner_mask``, ``quad_as_tri`` and ``z_interp`` and ``threads``. "
         "Supports all options for ``line_type`` and ``fill_type``.")
         .def(py::init<const contourpy::CoordinateArray&,
@@ -374,25 +377,10 @@ PYBIND11_MODULE(_contourpy, m) {
                       contourpy::index_t,
                       contourpy::index_t,
                       contourpy::index_t>(),
-             py::arg("x"),
-             py::arg("y"),
-             py::arg("z"),
-             py::arg("mask"),
-             py::kw_only(),
-             py::arg("corner_mask"),
-             py::arg("line_type"),
-             py::arg("fill_type"),
-             py::arg("quad_as_tri"),
-             py::arg("z_interp"),
-             py::arg("x_chunk_size") = 0,
-             py::arg("y_chunk_size") = 0,
-             py::arg("thread_count") = 0)
+             "x"_a, "y"_a, "z"_a, "mask"_a, py::kw_only(), "corner_mask"_a, "line_type"_a,
+             "fill_type"_a, "quad_as_tri"_a, "z_interp"_a, "x_chunk_size"_a = 0,
+             "y_chunk_size"_a = 0, "thread_count"_a = 0)
         .def("_write_cache", &contourpy::ThreadedContourGenerator::write_cache)
-        .def("create_contour", &contourpy::ThreadedContourGenerator::lines, create_contour_doc)
-        .def("create_filled_contour", &contourpy::ThreadedContourGenerator::filled,
-            create_filled_contour_doc)
-        .def("filled", &contourpy::ThreadedContourGenerator::filled, filled_doc)
-        .def("lines", &contourpy::ThreadedContourGenerator::lines, lines_doc)
         .def_property_readonly(
             "chunk_count", &contourpy::ThreadedContourGenerator::get_chunk_count, chunk_count_doc)
         .def_property_readonly(