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

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/advanced/pycpp/object.rst

@@ -1,286 +0,0 @@
-Python types
-############
-
-.. _wrappers:
-
-Available wrappers
-==================
-
-All major Python types are available as thin C++ wrapper classes. These
-can also be used as function parameters -- see :ref:`python_objects_as_args`.
-
-Available types include :class:`handle`, :class:`object`, :class:`bool_`,
-:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`,
-:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`,
-:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`,
-:class:`array`, and :class:`array_t`.
-
-.. warning::
-
-    Be sure to review the :ref:`pytypes_gotchas` before using this heavily in
-    your C++ API.
-
-.. _instantiating_compound_types:
-
-Instantiating compound Python types from C++
-============================================
-
-Dictionaries can be initialized in the :class:`dict` constructor:
-
-.. code-block:: cpp
-
-    using namespace pybind11::literals; // to bring in the `_a` literal
-    py::dict d("spam"_a=py::none(), "eggs"_a=42);
-
-A tuple of python objects can be instantiated using :func:`py::make_tuple`:
-
-.. code-block:: cpp
-
-    py::tuple tup = py::make_tuple(42, py::none(), "spam");
-
-Each element is converted to a supported Python type.
-
-A `simple namespace`_ can be instantiated using
-
-.. code-block:: cpp
-
-    using namespace pybind11::literals;  // to bring in the `_a` literal
-    py::object SimpleNamespace = py::module_::import("types").attr("SimpleNamespace");
-    py::object ns = SimpleNamespace("spam"_a=py::none(), "eggs"_a=42);
-
-Attributes on a namespace can be modified with the :func:`py::delattr`,
-:func:`py::getattr`, and :func:`py::setattr` functions. Simple namespaces can
-be useful as lightweight stand-ins for class instances.
-
-.. _simple namespace: https://docs.python.org/3/library/types.html#types.SimpleNamespace
-
-.. _casting_back_and_forth:
-
-Casting back and forth
-======================
-
-In this kind of mixed code, it is often necessary to convert arbitrary C++
-types to Python, which can be done using :func:`py::cast`:
-
-.. code-block:: cpp
-
-    MyClass *cls = ...;
-    py::object obj = py::cast(cls);
-
-The reverse direction uses the following syntax:
-
-.. code-block:: cpp
-
-    py::object obj = ...;
-    MyClass *cls = obj.cast<MyClass *>();
-
-When conversion fails, both directions throw the exception :class:`cast_error`.
-
-.. _python_libs:
-
-Accessing Python libraries from C++
-===================================
-
-It is also possible to import objects defined in the Python standard
-library or available in the current Python environment (``sys.path``) and work
-with these in C++.
-
-This example obtains a reference to the Python ``Decimal`` class.
-
-.. code-block:: cpp
-
-    // Equivalent to "from decimal import Decimal"
-    py::object Decimal = py::module_::import("decimal").attr("Decimal");
-
-.. code-block:: cpp
-
-    // Try to import scipy
-    py::object scipy = py::module_::import("scipy");
-    return scipy.attr("__version__");
-
-
-.. _calling_python_functions:
-
-Calling Python functions
-========================
-
-It is also possible to call Python classes, functions and methods
-via ``operator()``.
-
-.. code-block:: cpp
-
-    // Construct a Python object of class Decimal
-    py::object pi = Decimal("3.14159");
-
-.. code-block:: cpp
-
-    // Use Python to make our directories
-    py::object os = py::module_::import("os");
-    py::object makedirs = os.attr("makedirs");
-    makedirs("/tmp/path/to/somewhere");
-
-One can convert the result obtained from Python to a pure C++ version
-if a ``py::class_`` or type conversion is defined.
-
-.. code-block:: cpp
-
-    py::function f = <...>;
-    py::object result_py = f(1234, "hello", some_instance);
-    MyClass &result = result_py.cast<MyClass>();
-
-.. _calling_python_methods:
-
-Calling Python methods
-========================
-
-To call an object's method, one can again use ``.attr`` to obtain access to the
-Python method.
-
-.. code-block:: cpp
-
-    // Calculate e^π in decimal
-    py::object exp_pi = pi.attr("exp")();
-    py::print(py::str(exp_pi));
-
-In the example above ``pi.attr("exp")`` is a *bound method*: it will always call
-the method for that same instance of the class. Alternately one can create an
-*unbound method* via the Python class (instead of instance) and pass the ``self``
-object explicitly, followed by other arguments.
-
-.. code-block:: cpp
-
-    py::object decimal_exp = Decimal.attr("exp");
-
-    // Compute the e^n for n=0..4
-    for (int n = 0; n < 5; n++) {
-        py::print(decimal_exp(Decimal(n));
-    }
-
-Keyword arguments
-=================
-
-Keyword arguments are also supported. In Python, there is the usual call syntax:
-
-.. code-block:: python
-
-    def f(number, say, to):
-        ...  # function code
-
-
-    f(1234, say="hello", to=some_instance)  # keyword call in Python
-
-In C++, the same call can be made using:
-
-.. code-block:: cpp
-
-    using namespace pybind11::literals; // to bring in the `_a` literal
-    f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++
-
-Unpacking arguments
-===================
-
-Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with
-other arguments:
-
-.. code-block:: cpp
-
-    // * unpacking
-    py::tuple args = py::make_tuple(1234, "hello", some_instance);
-    f(*args);
-
-    // ** unpacking
-    py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance);
-    f(**kwargs);
-
-    // mixed keywords, * and ** unpacking
-    py::tuple args = py::make_tuple(1234);
-    py::dict kwargs = py::dict("to"_a=some_instance);
-    f(*args, "say"_a="hello", **kwargs);
-
-Generalized unpacking according to PEP448_ is also supported:
-
-.. code-block:: cpp
-
-    py::dict kwargs1 = py::dict("number"_a=1234);
-    py::dict kwargs2 = py::dict("to"_a=some_instance);
-    f(**kwargs1, "say"_a="hello", **kwargs2);
-
-.. seealso::
-
-    The file :file:`tests/test_pytypes.cpp` contains a complete
-    example that demonstrates passing native Python types in more detail. The
-    file :file:`tests/test_callbacks.cpp` presents a few examples of calling
-    Python functions from C++, including keywords arguments and unpacking.
-
-.. _PEP448: https://www.python.org/dev/peps/pep-0448/
-
-.. _implicit_casting:
-
-Implicit casting
-================
-
-When using the C++ interface for Python types, or calling Python functions,
-objects of type :class:`object` are returned. It is possible to invoke implicit
-conversions to subclasses like :class:`dict`. The same holds for the proxy objects
-returned by ``operator[]`` or ``obj.attr()``.
-Casting to subtypes improves code readability and allows values to be passed to
-C++ functions that require a specific subtype rather than a generic :class:`object`.
-
-.. code-block:: cpp
-
-    #include <pybind11/numpy.h>
-    using namespace pybind11::literals;
-
-    py::module_ os = py::module_::import("os");
-    py::module_ path = py::module_::import("os.path");  // like 'import os.path as path'
-    py::module_ np = py::module_::import("numpy");  // like 'import numpy as np'
-
-    py::str curdir_abs = path.attr("abspath")(path.attr("curdir"));
-    py::print(py::str("Current directory: ") + curdir_abs);
-    py::dict environ = os.attr("environ");
-    py::print(environ["HOME"]);
-    py::array_t<float> arr = np.attr("ones")(3, "dtype"_a="float32");
-    py::print(py::repr(arr + py::int_(1)));
-
-These implicit conversions are available for subclasses of :class:`object`; there
-is no need to call ``obj.cast()`` explicitly as for custom classes, see
-:ref:`casting_back_and_forth`.
-
-.. note::
-    If a trivial conversion via move constructor is not possible, both implicit and
-    explicit casting (calling ``obj.cast()``) will attempt a "rich" conversion.
-    For instance, ``py::list env = os.attr("environ");`` will succeed and is
-    equivalent to the Python code ``env = list(os.environ)`` that produces a
-    list of the dict keys.
-
-..  TODO: Adapt text once PR #2349 has landed
-
-Handling exceptions
-===================
-
-Python exceptions from wrapper classes will be thrown as a ``py::error_already_set``.
-See :ref:`Handling exceptions from Python in C++
-<handling_python_exceptions_cpp>` for more information on handling exceptions
-raised when calling C++ wrapper classes.
-
-.. _pytypes_gotchas:
-
-Gotchas
-=======
-
-Default-Constructed Wrappers
-----------------------------
-
-When a wrapper type is default-constructed, it is **not** a valid Python object (i.e. it is not ``py::none()``). It is simply the same as
-``PyObject*`` null pointer. To check for this, use
-``static_cast<bool>(my_wrapper)``.
-
-Assigning py::none() to wrappers
---------------------------------
-
-You may be tempted to use types like ``py::str`` and ``py::dict`` in C++
-signatures (either pure C++, or in bound signatures), and assign them default
-values of ``py::none()``. However, in a best case scenario, it will fail fast
-because ``None`` is not convertible to that type (e.g. ``py::dict``), or in a
-worse case scenario, it will silently work but corrupt the types you want to
-work with (e.g. ``py::str(py::none())`` will yield ``"None"`` in Python).

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/advanced/pycpp/utilities.rst

@@ -1,155 +0,0 @@
-Utilities
-#########
-
-Using Python's print function in C++
-====================================
-
-The usual way to write output in C++ is using ``std::cout`` while in Python one
-would use ``print``. Since these methods use different buffers, mixing them can
-lead to output order issues. To resolve this, pybind11 modules can use the
-:func:`py::print` function which writes to Python's ``sys.stdout`` for consistency.
-
-Python's ``print`` function is replicated in the C++ API including optional
-keyword arguments ``sep``, ``end``, ``file``, ``flush``. Everything works as
-expected in Python:
-
-.. code-block:: cpp
-
-    py::print(1, 2.0, "three"); // 1 2.0 three
-    py::print(1, 2.0, "three", "sep"_a="-"); // 1-2.0-three
-
-    auto args = py::make_tuple("unpacked", true);
-    py::print("->", *args, "end"_a="<-"); // -> unpacked True <-
-
-.. _ostream_redirect:
-
-Capturing standard output from ostream
-======================================
-
-Often, a library will use the streams ``std::cout`` and ``std::cerr`` to print,
-but this does not play well with Python's standard ``sys.stdout`` and ``sys.stderr``
-redirection. Replacing a library's printing with ``py::print <print>`` may not
-be feasible. This can be fixed using a guard around the library function that
-redirects output to the corresponding Python streams:
-
-.. code-block:: cpp
-
-    #include <pybind11/iostream.h>
-
-    ...
-
-    // Add a scoped redirect for your noisy code
-    m.def("noisy_func", []() {
-        py::scoped_ostream_redirect stream(
-            std::cout,                               // std::ostream&
-            py::module_::import("sys").attr("stdout") // Python output
-        );
-        call_noisy_func();
-    });
-
-.. warning::
-
-    The implementation in ``pybind11/iostream.h`` is NOT thread safe. Multiple
-    threads writing to a redirected ostream concurrently cause data races
-    and potentially buffer overflows. Therefore it is currently a requirement
-    that all (possibly) concurrent redirected ostream writes are protected by
-    a mutex. #HelpAppreciated: Work on iostream.h thread safety. For more
-    background see the discussions under
-    `PR #2982 <https://github.com/pybind/pybind11/pull/2982>`_ and
-    `PR #2995 <https://github.com/pybind/pybind11/pull/2995>`_.
-
-This method respects flushes on the output streams and will flush if needed
-when the scoped guard is destroyed. This allows the output to be redirected in
-real time, such as to a Jupyter notebook. The two arguments, the C++ stream and
-the Python output, are optional, and default to standard output if not given. An
-extra type, ``py::scoped_estream_redirect <scoped_estream_redirect>``, is identical
-except for defaulting to ``std::cerr`` and ``sys.stderr``; this can be useful with
-``py::call_guard``, which allows multiple items, but uses the default constructor:
-
-.. code-block:: cpp
-
-    // Alternative: Call single function using call guard
-    m.def("noisy_func", &call_noisy_function,
-          py::call_guard<py::scoped_ostream_redirect,
-                         py::scoped_estream_redirect>());
-
-The redirection can also be done in Python with the addition of a context
-manager, using the ``py::add_ostream_redirect() <add_ostream_redirect>`` function:
-
-.. code-block:: cpp
-
-    py::add_ostream_redirect(m, "ostream_redirect");
-
-The name in Python defaults to ``ostream_redirect`` if no name is passed.  This
-creates the following context manager in Python:
-
-.. code-block:: python
-
-    with ostream_redirect(stdout=True, stderr=True):
-        noisy_function()
-
-It defaults to redirecting both streams, though you can use the keyword
-arguments to disable one of the streams if needed.
-
-.. note::
-
-    The above methods will not redirect C-level output to file descriptors, such
-    as ``fprintf``. For those cases, you'll need to redirect the file
-    descriptors either directly in C or with Python's ``os.dup2`` function
-    in an operating-system dependent way.
-
-.. _eval:
-
-Evaluating Python expressions from strings and files
-====================================================
-
-pybind11 provides the ``eval``, ``exec`` and ``eval_file`` functions to evaluate
-Python expressions and statements. The following example illustrates how they
-can be used.
-
-.. code-block:: cpp
-
-    // At beginning of file
-    #include <pybind11/eval.h>
-
-    ...
-
-    // Evaluate in scope of main module
-    py::object scope = py::module_::import("__main__").attr("__dict__");
-
-    // Evaluate an isolated expression
-    int result = py::eval("my_variable + 10", scope).cast<int>();
-
-    // Evaluate a sequence of statements
-    py::exec(
-        "print('Hello')\n"
-        "print('world!');",
-        scope);
-
-    // Evaluate the statements in an separate Python file on disk
-    py::eval_file("script.py", scope);
-
-C++11 raw string literals are also supported and quite handy for this purpose.
-The only requirement is that the first statement must be on a new line following
-the raw string delimiter ``R"(``, ensuring all lines have common leading indent:
-
-.. code-block:: cpp
-
-    py::exec(R"(
-        x = get_answer()
-        if x == 42:
-            print('Hello World!')
-        else:
-            print('Bye!')
-        )", scope
-    );
-
-.. note::
-
-    `eval` and `eval_file` accept a template parameter that describes how the
-    string/file should be interpreted. Possible choices include ``eval_expr``
-    (isolated expression), ``eval_single_statement`` (a single statement, return
-    value is always ``none``), and ``eval_statements`` (sequence of statements,
-    return value is always ``none``). `eval` defaults to  ``eval_expr``,
-    `eval_file` defaults to ``eval_statements`` and `exec` is just a shortcut
-    for ``eval<eval_statements>``.

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

@@ -1,174 +0,0 @@
-Smart pointers
-##############
-
-std::unique_ptr
-===============
-
-Given a class ``Example`` with Python bindings, it's possible to return
-instances wrapped in C++11 unique pointers, like so
-
-.. code-block:: cpp
-
-    std::unique_ptr<Example> create_example() { return std::unique_ptr<Example>(new Example()); }
-
-.. code-block:: cpp
-
-    m.def("create_example", &create_example);
-
-In other words, there is nothing special that needs to be done. While returning
-unique pointers in this way is allowed, it is *illegal* to use them as function
-arguments. For instance, the following function signature cannot be processed
-by pybind11.
-
-.. code-block:: cpp
-
-    void do_something_with_example(std::unique_ptr<Example> ex) { ... }
-
-The above signature would imply that Python needs to give up ownership of an
-object that is passed to this function, which is generally not possible (for
-instance, the object might be referenced elsewhere).
-
-std::shared_ptr
-===============
-
-The binding generator for classes, :class:`class_`, can be passed a template
-type that denotes a special *holder* type that is used to manage references to
-the object.  If no such holder type template argument is given, the default for
-a type named ``Type`` is ``std::unique_ptr<Type>``, which means that the object
-is deallocated when Python's reference count goes to zero.
-
-It is possible to switch to other types of reference counting wrappers or smart
-pointers, which is useful in codebases that rely on them. For instance, the
-following snippet causes ``std::shared_ptr`` to be used instead.
-
-.. code-block:: cpp
-
-    py::class_<Example, std::shared_ptr<Example> /* <- holder type */> obj(m, "Example");
-
-Note that any particular class can only be associated with a single holder type.
-
-One potential stumbling block when using holder types is that they need to be
-applied consistently. Can you guess what's broken about the following binding
-code?
-
-.. code-block:: cpp
-
-    class Child { };
-
-    class Parent {
-    public:
-       Parent() : child(std::make_shared<Child>()) { }
-       Child *get_child() { return child.get(); }  /* Hint: ** DON'T DO THIS ** */
-    private:
-        std::shared_ptr<Child> child;
-    };
-
-    PYBIND11_MODULE(example, m) {
-        py::class_<Child, std::shared_ptr<Child>>(m, "Child");
-
-        py::class_<Parent, std::shared_ptr<Parent>>(m, "Parent")
-           .def(py::init<>())
-           .def("get_child", &Parent::get_child);
-    }
-
-The following Python code will cause undefined behavior (and likely a
-segmentation fault).
-
-.. code-block:: python
-
-   from example import Parent
-
-   print(Parent().get_child())
-
-The problem is that ``Parent::get_child()`` returns a pointer to an instance of
-``Child``, but the fact that this instance is already managed by
-``std::shared_ptr<...>`` is lost when passing raw pointers. In this case,
-pybind11 will create a second independent ``std::shared_ptr<...>`` that also
-claims ownership of the pointer. In the end, the object will be freed **twice**
-since these shared pointers have no way of knowing about each other.
-
-There are two ways to resolve this issue:
-
-1. For types that are managed by a smart pointer class, never use raw pointers
-   in function arguments or return values. In other words: always consistently
-   wrap pointers into their designated holder types (such as
-   ``std::shared_ptr<...>``). In this case, the signature of ``get_child()``
-   should be modified as follows:
-
-.. code-block:: cpp
-
-    std::shared_ptr<Child> get_child() { return child; }
-
-2. Adjust the definition of ``Child`` by specifying
-   ``std::enable_shared_from_this<T>`` (see cppreference_ for details) as a
-   base class. This adds a small bit of information to ``Child`` that allows
-   pybind11 to realize that there is already an existing
-   ``std::shared_ptr<...>`` and communicate with it. In this case, the
-   declaration of ``Child`` should look as follows:
-
-.. _cppreference: http://en.cppreference.com/w/cpp/memory/enable_shared_from_this
-
-.. code-block:: cpp
-
-    class Child : public std::enable_shared_from_this<Child> { };
-
-.. _smart_pointers:
-
-Custom smart pointers
-=====================
-
-pybind11 supports ``std::unique_ptr`` and ``std::shared_ptr`` right out of the
-box. For any other custom smart pointer, transparent conversions can be enabled
-using a macro invocation similar to the following. It must be declared at the
-top namespace level before any binding code:
-
-.. code-block:: cpp
-
-    PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>);
-
-The first argument of :func:`PYBIND11_DECLARE_HOLDER_TYPE` should be a
-placeholder name that is used as a template parameter of the second argument.
-Thus, feel free to use any identifier, but use it consistently on both sides;
-also, don't use the name of a type that already exists in your codebase.
-
-The macro also accepts a third optional boolean parameter that is set to false
-by default. Specify
-
-.. code-block:: cpp
-
-    PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>, true);
-
-if ``SmartPtr<T>`` can always be initialized from a ``T*`` pointer without the
-risk of inconsistencies (such as multiple independent ``SmartPtr`` instances
-believing that they are the sole owner of the ``T*`` pointer). A common
-situation where ``true`` should be passed is when the ``T`` instances use
-*intrusive* reference counting.
-
-Please take a look at the :ref:`macro_notes` before using this feature.
-
-By default, pybind11 assumes that your custom smart pointer has a standard
-interface, i.e. provides a ``.get()`` member function to access the underlying
-raw pointer. If this is not the case, pybind11's ``holder_helper`` must be
-specialized:
-
-.. code-block:: cpp
-
-    // Always needed for custom holder types
-    PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>);
-
-    // Only needed if the type's `.get()` goes by another name
-    namespace pybind11 { namespace detail {
-        template <typename T>
-        struct holder_helper<SmartPtr<T>> { // <-- specialization
-            static const T *get(const SmartPtr<T> &p) { return p.getPointer(); }
-        };
-    }}
-
-The above specialization informs pybind11 that the custom ``SmartPtr`` class
-provides ``.get()`` functionality via ``.getPointer()``.
-
-.. seealso::
-
-    The file :file:`tests/test_smart_ptr.cpp` contains a complete example
-    that demonstrates how to work with custom reference-counting holder types
-    in more detail.