xcoll 0.5.12__py3-none-any.whl → 0.6.1__py3-none-any.whl

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/advanced/embedding.rst

@@ -1,262 +0,0 @@
-.. _embedding:
-
-Embedding the interpreter
-#########################
-
-While pybind11 is mainly focused on extending Python using C++, it's also
-possible to do the reverse: embed the Python interpreter into a C++ program.
-All of the other documentation pages still apply here, so refer to them for
-general pybind11 usage. This section will cover a few extra things required
-for embedding.
-
-Getting started
-===============
-
-A basic executable with an embedded interpreter can be created with just a few
-lines of CMake and the ``pybind11::embed`` target, as shown below. For more
-information, see :doc:`/compiling`.
-
-.. code-block:: cmake
-
-    cmake_minimum_required(VERSION 3.4)
-    project(example)
-
-    find_package(pybind11 REQUIRED)  # or `add_subdirectory(pybind11)`
-
-    add_executable(example main.cpp)
-    target_link_libraries(example PRIVATE pybind11::embed)
-
-The essential structure of the ``main.cpp`` file looks like this:
-
-.. code-block:: cpp
-
-    #include <pybind11/embed.h> // everything needed for embedding
-    namespace py = pybind11;
-
-    int main() {
-        py::scoped_interpreter guard{}; // start the interpreter and keep it alive
-
-        py::print("Hello, World!"); // use the Python API
-    }
-
-The interpreter must be initialized before using any Python API, which includes
-all the functions and classes in pybind11. The RAII guard class ``scoped_interpreter``
-takes care of the interpreter lifetime. After the guard is destroyed, the interpreter
-shuts down and clears its memory. No Python functions can be called after this.
-
-Executing Python code
-=====================
-
-There are a few different ways to run Python code. One option is to use ``eval``,
-``exec`` or ``eval_file``, as explained in :ref:`eval`. Here is a quick example in
-the context of an executable with an embedded interpreter:
-
-.. code-block:: cpp
-
-    #include <pybind11/embed.h>
-    namespace py = pybind11;
-
-    int main() {
-        py::scoped_interpreter guard{};
-
-        py::exec(R"(
-            kwargs = dict(name="World", number=42)
-            message = "Hello, {name}! The answer is {number}".format(**kwargs)
-            print(message)
-        )");
-    }
-
-Alternatively, similar results can be achieved using pybind11's API (see
-:doc:`/advanced/pycpp/index` for more details).
-
-.. code-block:: cpp
-
-    #include <pybind11/embed.h>
-    namespace py = pybind11;
-    using namespace py::literals;
-
-    int main() {
-        py::scoped_interpreter guard{};
-
-        auto kwargs = py::dict("name"_a="World", "number"_a=42);
-        auto message = "Hello, {name}! The answer is {number}"_s.format(**kwargs);
-        py::print(message);
-    }
-
-The two approaches can also be combined:
-
-.. code-block:: cpp
-
-    #include <pybind11/embed.h>
-    #include <iostream>
-
-    namespace py = pybind11;
-    using namespace py::literals;
-
-    int main() {
-        py::scoped_interpreter guard{};
-
-        auto locals = py::dict("name"_a="World", "number"_a=42);
-        py::exec(R"(
-            message = "Hello, {name}! The answer is {number}".format(**locals())
-        )", py::globals(), locals);
-
-        auto message = locals["message"].cast<std::string>();
-        std::cout << message;
-    }
-
-Importing modules
-=================
-
-Python modules can be imported using ``module_::import()``:
-
-.. code-block:: cpp
-
-    py::module_ sys = py::module_::import("sys");
-    py::print(sys.attr("path"));
-
-For convenience, the current working directory is included in ``sys.path`` when
-embedding the interpreter. This makes it easy to import local Python files:
-
-.. code-block:: python
-
-    """calc.py located in the working directory"""
-
-
-    def add(i, j):
-        return i + j
-
-
-.. code-block:: cpp
-
-    py::module_ calc = py::module_::import("calc");
-    py::object result = calc.attr("add")(1, 2);
-    int n = result.cast<int>();
-    assert(n == 3);
-
-Modules can be reloaded using ``module_::reload()`` if the source is modified e.g.
-by an external process. This can be useful in scenarios where the application
-imports a user defined data processing script which needs to be updated after
-changes by the user. Note that this function does not reload modules recursively.
-
-.. _embedding_modules:
-
-Adding embedded modules
-=======================
-
-Embedded binary modules can be added using the ``PYBIND11_EMBEDDED_MODULE`` macro.
-Note that the definition must be placed at global scope. They can be imported
-like any other module.
-
-.. code-block:: cpp
-
-    #include <pybind11/embed.h>
-    namespace py = pybind11;
-
-    PYBIND11_EMBEDDED_MODULE(fast_calc, m) {
-        // `m` is a `py::module_` which is used to bind functions and classes
-        m.def("add", [](int i, int j) {
-            return i + j;
-        });
-    }
-
-    int main() {
-        py::scoped_interpreter guard{};
-
-        auto fast_calc = py::module_::import("fast_calc");
-        auto result = fast_calc.attr("add")(1, 2).cast<int>();
-        assert(result == 3);
-    }
-
-Unlike extension modules where only a single binary module can be created, on
-the embedded side an unlimited number of modules can be added using multiple
-``PYBIND11_EMBEDDED_MODULE`` definitions (as long as they have unique names).
-
-These modules are added to Python's list of builtins, so they can also be
-imported in pure Python files loaded by the interpreter. Everything interacts
-naturally:
-
-.. code-block:: python
-
-    """py_module.py located in the working directory"""
-    import cpp_module
-
-    a = cpp_module.a
-    b = a + 1
-
-
-.. code-block:: cpp
-
-    #include <pybind11/embed.h>
-    namespace py = pybind11;
-
-    PYBIND11_EMBEDDED_MODULE(cpp_module, m) {
-        m.attr("a") = 1;
-    }
-
-    int main() {
-        py::scoped_interpreter guard{};
-
-        auto py_module = py::module_::import("py_module");
-
-        auto locals = py::dict("fmt"_a="{} + {} = {}", **py_module.attr("__dict__"));
-        assert(locals["a"].cast<int>() == 1);
-        assert(locals["b"].cast<int>() == 2);
-
-        py::exec(R"(
-            c = a + b
-            message = fmt.format(a, b, c)
-        )", py::globals(), locals);
-
-        assert(locals["c"].cast<int>() == 3);
-        assert(locals["message"].cast<std::string>() == "1 + 2 = 3");
-    }
-
-
-Interpreter lifetime
-====================
-
-The Python interpreter shuts down when ``scoped_interpreter`` is destroyed. After
-this, creating a new instance will restart the interpreter. Alternatively, the
-``initialize_interpreter`` / ``finalize_interpreter`` pair of functions can be used
-to directly set the state at any time.
-
-Modules created with pybind11 can be safely re-initialized after the interpreter
-has been restarted. However, this may not apply to third-party extension modules.
-The issue is that Python itself cannot completely unload extension modules and
-there are several caveats with regard to interpreter restarting. In short, not
-all memory may be freed, either due to Python reference cycles or user-created
-global data. All the details can be found in the CPython documentation.
-
-.. warning::
-
-    Creating two concurrent ``scoped_interpreter`` guards is a fatal error. So is
-    calling ``initialize_interpreter`` for a second time after the interpreter
-    has already been initialized.
-
-    Do not use the raw CPython API functions ``Py_Initialize`` and
-    ``Py_Finalize`` as these do not properly handle the lifetime of
-    pybind11's internal data.
-
-
-Sub-interpreter support
-=======================
-
-Creating multiple copies of ``scoped_interpreter`` is not possible because it
-represents the main Python interpreter. Sub-interpreters are something different
-and they do permit the existence of multiple interpreters. This is an advanced
-feature of the CPython API and should be handled with care. pybind11 does not
-currently offer a C++ interface for sub-interpreters, so refer to the CPython
-documentation for all the details regarding this feature.
-
-We'll just mention a couple of caveats the sub-interpreters support in pybind11:
-
- 1. Sub-interpreters will not receive independent copies of embedded modules.
-    Instead, these are shared and modifications in one interpreter may be
-    reflected in another.
-
- 2. Managing multiple threads, multiple interpreters and the GIL can be
-    challenging and there are several caveats here, even within the pure
-    CPython API (please refer to the Python docs for details). As for
-    pybind11, keep in mind that ``gil_scoped_release`` and ``gil_scoped_acquire``
-    do not take sub-interpreters into account.

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/advanced/exceptions.rst

@@ -1,396 +0,0 @@
-Exceptions
-##########
-
-Built-in C++ to Python exception translation
-============================================
-
-When Python calls C++ code through pybind11, pybind11 provides a C++ exception handler
-that will trap C++ exceptions, translate them to the corresponding Python exception,
-and raise them so that Python code can handle them.
-
-pybind11 defines translations for ``std::exception`` and its standard
-subclasses, and several special exception classes that translate to specific
-Python exceptions. Note that these are not actually Python exceptions, so they
-cannot be examined using the Python C API. Instead, they are pure C++ objects
-that pybind11 will translate the corresponding Python exception when they arrive
-at its exception handler.
-
-.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
-
-+--------------------------------------+--------------------------------------+
-|  Exception thrown by C++             |  Translated to Python exception type |
-+======================================+======================================+
-| :class:`std::exception`              | ``RuntimeError``                     |
-+--------------------------------------+--------------------------------------+
-| :class:`std::bad_alloc`              | ``MemoryError``                      |
-+--------------------------------------+--------------------------------------+
-| :class:`std::domain_error`           | ``ValueError``                       |
-+--------------------------------------+--------------------------------------+
-| :class:`std::invalid_argument`       | ``ValueError``                       |
-+--------------------------------------+--------------------------------------+
-| :class:`std::length_error`           | ``ValueError``                       |
-+--------------------------------------+--------------------------------------+
-| :class:`std::out_of_range`           | ``IndexError``                       |
-+--------------------------------------+--------------------------------------+
-| :class:`std::range_error`            | ``ValueError``                       |
-+--------------------------------------+--------------------------------------+
-| :class:`std::overflow_error`         | ``OverflowError``                    |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::stop_iteration`    | ``StopIteration`` (used to implement |
-|                                      | custom iterators)                    |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::index_error`       | ``IndexError`` (used to indicate out |
-|                                      | of bounds access in ``__getitem__``, |
-|                                      | ``__setitem__``, etc.)               |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::key_error`         | ``KeyError`` (used to indicate out   |
-|                                      | of bounds access in ``__getitem__``, |
-|                                      | ``__setitem__`` in dict-like         |
-|                                      | objects, etc.)                       |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::value_error`       | ``ValueError`` (used to indicate     |
-|                                      | wrong value passed in                |
-|                                      | ``container.remove(...)``)           |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::type_error`        | ``TypeError``                        |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::buffer_error`      | ``BufferError``                      |
-+--------------------------------------+--------------------------------------+
-| :class:`pybind11::import_error`      | ``import_error``                     |
-+--------------------------------------+--------------------------------------+
-| Any other exception                  | ``RuntimeError``                     |
-+--------------------------------------+--------------------------------------+
-
-Exception translation is not bidirectional. That is, *catching* the C++
-exceptions defined above above will not trap exceptions that originate from
-Python. For that, catch :class:`pybind11::error_already_set`. See :ref:`below
-<handling_python_exceptions_cpp>` for further details.
-
-There is also a special exception :class:`cast_error` that is thrown by
-:func:`handle::call` when the input arguments cannot be converted to Python
-objects.
-
-Registering custom translators
-==============================
-
-If the default exception conversion policy described above is insufficient,
-pybind11 also provides support for registering custom exception translators.
-Similar to pybind11 classes, exception translators can be local to the module
-they are defined in or global to the entire python session.  To register a simple
-exception conversion that translates a C++ exception into a new Python exception
-using the C++ exception's ``what()`` method, a helper function is available:
-
-.. code-block:: cpp
-
-    py::register_exception<CppExp>(module, "PyExp");
-
-This call creates a Python exception class with the name ``PyExp`` in the given
-module and automatically converts any encountered exceptions of type ``CppExp``
-into Python exceptions of type ``PyExp``.
-
-A matching function is available for registering a local exception translator:
-
-.. code-block:: cpp
-
-    py::register_local_exception<CppExp>(module, "PyExp");
-
-
-It is possible to specify base class for the exception using the third
-parameter, a ``handle``:
-
-.. code-block:: cpp
-
-    py::register_exception<CppExp>(module, "PyExp", PyExc_RuntimeError);
-    py::register_local_exception<CppExp>(module, "PyExp", PyExc_RuntimeError);
-
-Then ``PyExp`` can be caught both as ``PyExp`` and ``RuntimeError``.
-
-The class objects of the built-in Python exceptions are listed in the Python
-documentation on `Standard Exceptions <https://docs.python.org/3/c-api/exceptions.html#standard-exceptions>`_.
-The default base class is ``PyExc_Exception``.
-
-When more advanced exception translation is needed, the functions
-``py::register_exception_translator(translator)`` and
-``py::register_local_exception_translator(translator)`` can be used to register
-functions that can translate arbitrary exception types (and which may include
-additional logic to do so).  The functions takes a stateless callable (e.g. a
-function pointer or a lambda function without captured variables) with the call
-signature ``void(std::exception_ptr)``.
-
-When a C++ exception is thrown, the registered exception translators are tried
-in reverse order of registration (i.e. the last registered translator gets the
-first shot at handling the exception). All local translators will be tried
-before a global translator is tried.
-
-Inside the translator, ``std::rethrow_exception`` should be used within
-a try block to re-throw the exception.  One or more catch clauses to catch
-the appropriate exceptions should then be used with each clause using
-``PyErr_SetString`` to set a Python exception or ``ex(string)`` to set
-the python exception to a custom exception type (see below).
-
-To declare a custom Python exception type, declare a ``py::exception`` variable
-and use this in the associated exception translator (note: it is often useful
-to make this a static declaration when using it inside a lambda expression
-without requiring capturing).
-
-The following example demonstrates this for a hypothetical exception classes
-``MyCustomException`` and ``OtherException``: the first is translated to a
-custom python exception ``MyCustomError``, while the second is translated to a
-standard python RuntimeError:
-
-.. code-block:: cpp
-
-    static py::exception<MyCustomException> exc(m, "MyCustomError");
-    py::register_exception_translator([](std::exception_ptr p) {
-        try {
-            if (p) std::rethrow_exception(p);
-        } catch (const MyCustomException &e) {
-            exc(e.what());
-        } catch (const OtherException &e) {
-            PyErr_SetString(PyExc_RuntimeError, e.what());
-        }
-    });
-
-Multiple exceptions can be handled by a single translator, as shown in the
-example above. If the exception is not caught by the current translator, the
-previously registered one gets a chance.
-
-If none of the registered exception translators is able to handle the
-exception, it is handled by the default converter as described in the previous
-section.
-
-.. seealso::
-
-    The file :file:`tests/test_exceptions.cpp` contains examples
-    of various custom exception translators and custom exception types.
-
-.. note::
-
-    Call either ``PyErr_SetString`` or a custom exception's call
-    operator (``exc(string)``) for every exception caught in a custom exception
-    translator.  Failure to do so will cause Python to crash with ``SystemError:
-    error return without exception set``.
-
-    Exceptions that you do not plan to handle should simply not be caught, or
-    may be explicitly (re-)thrown to delegate it to the other,
-    previously-declared existing exception translators.
-
-    Note that ``libc++`` and ``libstdc++`` `behave differently <https://stackoverflow.com/questions/19496643/using-clang-fvisibility-hidden-and-typeinfo-and-type-erasure/28827430>`_
-    with ``-fvisibility=hidden``. Therefore exceptions that are used across ABI boundaries need to be explicitly exported, as exercised in ``tests/test_exceptions.h``.
-    See also: "Problems with C++ exceptions" under `GCC Wiki <https://gcc.gnu.org/wiki/Visibility>`_.
-
-
-Local vs Global Exception Translators
-=====================================
-
-When a global exception translator is registered, it will be applied across all
-modules in the reverse order of registration. This can create behavior where the
-order of module import influences how exceptions are translated.
-
-If module1 has the following translator:
-
-.. code-block:: cpp
-
-      py::register_exception_translator([](std::exception_ptr p) {
-        try {
-            if (p) std::rethrow_exception(p);
-        } catch (const std::invalid_argument &e) {
-            PyErr_SetString("module1 handled this")
-        }
-      }
-
-and module2 has the following similar translator:
-
-.. code-block:: cpp
-
-      py::register_exception_translator([](std::exception_ptr p) {
-        try {
-            if (p) std::rethrow_exception(p);
-        } catch (const std::invalid_argument &e) {
-            PyErr_SetString("module2 handled this")
-        }
-      }
-
-then which translator handles the invalid_argument will be determined by the
-order that module1 and module2 are imported. Since exception translators are
-applied in the reverse order of registration, which ever module was imported
-last will "win" and that translator will be applied.
-
-If there are multiple pybind11 modules that share exception types (either
-standard built-in or custom) loaded into a single python instance and
-consistent error handling behavior is needed, then local translators should be
-used.
-
-Changing the previous example to use ``register_local_exception_translator``
-would mean that when invalid_argument is thrown in the module2 code, the
-module2 translator will always handle it, while in module1, the module1
-translator will do the same.
-
-.. _handling_python_exceptions_cpp:
-
-Handling exceptions from Python in C++
-======================================
-
-When C++ calls Python functions, such as in a callback function or when
-manipulating Python objects, and Python raises an ``Exception``, pybind11
-converts the Python exception into a C++ exception of type
-:class:`pybind11::error_already_set` whose payload contains a C++ string textual
-summary and the actual Python exception. ``error_already_set`` is used to
-propagate Python exception back to Python (or possibly, handle them in C++).
-
-.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}|
-
-+--------------------------------------+--------------------------------------+
-|  Exception raised in Python          |  Thrown as C++ exception type        |
-+======================================+======================================+
-| Any Python ``Exception``             | :class:`pybind11::error_already_set` |
-+--------------------------------------+--------------------------------------+
-
-For example:
-
-.. code-block:: cpp
-
-    try {
-        // open("missing.txt", "r")
-        auto file = py::module_::import("io").attr("open")("missing.txt", "r");
-        auto text = file.attr("read")();
-        file.attr("close")();
-    } catch (py::error_already_set &e) {
-        if (e.matches(PyExc_FileNotFoundError)) {
-            py::print("missing.txt not found");
-        } else if (e.matches(PyExc_PermissionError)) {
-            py::print("missing.txt found but not accessible");
-        } else {
-            throw;
-        }
-    }
-
-Note that C++ to Python exception translation does not apply here, since that is
-a method for translating C++ exceptions to Python, not vice versa. The error raised
-from Python is always ``error_already_set``.
-
-This example illustrates this behavior:
-
-.. code-block:: cpp
-
-    try {
-        py::eval("raise ValueError('The Ring')");
-    } catch (py::value_error &boromir) {
-        // Boromir never gets the ring
-        assert(false);
-    } catch (py::error_already_set &frodo) {
-        // Frodo gets the ring
-        py::print("I will take the ring");
-    }
-
-    try {
-        // py::value_error is a request for pybind11 to raise a Python exception
-        throw py::value_error("The ball");
-    } catch (py::error_already_set &cat) {
-        // cat won't catch the ball since
-        // py::value_error is not a Python exception
-        assert(false);
-    } catch (py::value_error &dog) {
-        // dog will catch the ball
-        py::print("Run Spot run");
-        throw;  // Throw it again (pybind11 will raise ValueError)
-    }
-
-Handling errors from the Python C API
-=====================================
-
-Where possible, use :ref:`pybind11 wrappers <wrappers>` instead of calling
-the Python C API directly. When calling the Python C API directly, in
-addition to manually managing reference counts, one must follow the pybind11
-error protocol, which is outlined here.
-
-After calling the Python C API, if Python returns an error,
-``throw py::error_already_set();``, which allows pybind11 to deal with the
-exception and pass it back to the Python interpreter. This includes calls to
-the error setting functions such as ``PyErr_SetString``.
-
-.. code-block:: cpp
-
-    PyErr_SetString(PyExc_TypeError, "C API type error demo");
-    throw py::error_already_set();
-
-    // But it would be easier to simply...
-    throw py::type_error("pybind11 wrapper type error");
-
-Alternately, to ignore the error, call `PyErr_Clear
-<https://docs.python.org/3/c-api/exceptions.html#c.PyErr_Clear>`_.
-
-Any Python error must be thrown or cleared, or Python/pybind11 will be left in
-an invalid state.
-
-Chaining exceptions ('raise from')
-==================================
-
-In Python 3.3 a mechanism for indicating that exceptions were caused by other
-exceptions was introduced:
-
-.. code-block:: py
-
-    try:
-        print(1 / 0)
-    except Exception as exc:
-        raise RuntimeError("could not divide by zero") from exc
-
-To do a similar thing in pybind11, you can use the ``py::raise_from`` function. It
-sets the current python error indicator, so to continue propagating the exception
-you should ``throw py::error_already_set()`` (Python 3 only).
-
-.. code-block:: cpp
-
-    try {
-        py::eval("print(1 / 0"));
-    } catch (py::error_already_set &e) {
-        py::raise_from(e, PyExc_RuntimeError, "could not divide by zero");
-        throw py::error_already_set();
-    }
-
-.. versionadded:: 2.8
-
-.. _unraisable_exceptions:
-
-Handling unraisable exceptions
-==============================
-
-If a Python function invoked from a C++ destructor or any function marked
-``noexcept(true)`` (collectively, "noexcept functions") throws an exception, there
-is no way to propagate the exception, as such functions may not throw.
-Should they throw or fail to catch any exceptions in their call graph,
-the C++ runtime calls ``std::terminate()`` to abort immediately.
-
-Similarly, Python exceptions raised in a class's ``__del__`` method do not
-propagate, but are logged by Python as an unraisable error. In Python 3.8+, a
-`system hook is triggered
-<https://docs.python.org/3/library/sys.html#sys.unraisablehook>`_
-and an auditing event is logged.
-
-Any noexcept function should have a try-catch block that traps
-class:`error_already_set` (or any other exception that can occur). Note that
-pybind11 wrappers around Python exceptions such as
-:class:`pybind11::value_error` are *not* Python exceptions; they are C++
-exceptions that pybind11 catches and converts to Python exceptions. Noexcept
-functions cannot propagate these exceptions either. A useful approach is to
-convert them to Python exceptions and then ``discard_as_unraisable`` as shown
-below.
-
-.. code-block:: cpp
-
-    void nonthrowing_func() noexcept(true) {
-        try {
-            // ...
-        } catch (py::error_already_set &eas) {
-            // Discard the Python error using Python APIs, using the C++ magic
-            // variable __func__. Python already knows the type and value and of the
-            // exception object.
-            eas.discard_as_unraisable(__func__);
-        } catch (const std::exception &e) {
-            // Log and discard C++ exceptions.
-            third_party::log(e);
-        }
-    }
-
-.. versionadded:: 2.6