amulet-pybind11-extensions 1.0.0__py3-none-any.whl

amulet/pybind11_extensions/__init__.py

@@ -0,0 +1,3 @@
+from . import _version
+
+__version__ = _version.get_versions()["version"]

amulet/pybind11_extensions/_version.py

@@ -0,0 +1,21 @@
+
+# This file was generated by 'versioneer.py' (0.29) from
+# revision-control system data, or from the parent directory name of an
+# unpacked source archive. Distribution tarballs contain a pre-generated copy
+# of this file.
+
+import json
+
+version_json = '''
+{
+ "date": "2025-05-07T14:02:54+0100",
+ "dirty": false,
+ "error": null,
+ "full-revisionid": "2ce41a7d7c1118b04f1bf6035e2304b5dc8077b6",
+ "version": "1.0.0"
+}
+'''  # END VERSION_JSON
+
+
+def get_versions():
+    return json.loads(version_json)

amulet/pybind11_extensions/amulet_pybind11_extensionsConfig.cmake

@@ -0,0 +1,8 @@
+if (NOT TARGET amulet_pybind11_extensions)
+    set(amulet_pybind11_extensions_INCLUDE_DIR "${CMAKE_CURRENT_LIST_DIR}/../..")
+
+    add_library(amulet_pybind11_extensions IMPORTED INTERFACE)
+    set_target_properties(amulet_pybind11_extensions PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${amulet_pybind11_extensions_INCLUDE_DIR}"
+    )
+endif()

amulet/pybind11_extensions/builtins.hpp

@@ -0,0 +1,54 @@
+#pragma once
+#include <pybind11/pybind11.h>
+#include <pybind11/detail/descr.h>
+
+// Type hints for builtin types.
+
+
+namespace Amulet {
+namespace pybind11_extensions {
+    // Type hint for a native python object.
+    namespace detail {
+        template<size_t N>
+        struct FixedString {
+            char buf[N + 1]{};
+            constexpr FixedString(char const* s) {
+                for (unsigned i = 0; i != N; ++i) buf[i] = s[i];
+            }
+        };
+        template<unsigned N>
+        FixedString(char const (&)[N])->FixedString<N - 1>;
+    }
+
+    // A python object with a user defined string type hint for an arbitrary python object.
+    // This is useful if a C++ function needs to interact with a native python object.
+    template <detail::FixedString T>
+    class PyObjectStr : public pybind11::object {
+        PYBIND11_OBJECT_DEFAULT(PyObjectStr, object, PyObject_Type)
+            using object::object;
+    };
+
+    // A python object with a type hint from a C++ object.
+    // This is useful if you don't want to cast the python object to the C++ object and want to keep the type hint.
+    template <typename cppT>
+    class PyObjectCpp : public pybind11::object {
+        PYBIND11_OBJECT_DEFAULT(PyObjectCpp, object, PyObject_Type)
+            using object::object;
+    };
+} // namespace pybind11_extensions
+} // namespace Amulet
+
+
+namespace pybind11 {
+	namespace detail {
+		template <Amulet::pybind11_extensions::detail::FixedString T>
+		struct handle_type_name<Amulet::pybind11_extensions::PyObjectStr<T>> {
+			static constexpr auto name = pybind11::detail::const_name(T.buf);
+		};
+
+		template <typename cppT>
+		struct handle_type_name<Amulet::pybind11_extensions::PyObjectCpp<cppT>> {
+			static constexpr auto name = make_caster<cppT>::name;
+		};
+	}
+}

amulet/pybind11_extensions/collections.hpp

@@ -0,0 +1,183 @@
+#pragma once
+#include <iterator>
+#include <ranges>
+
+#include <pybind11/pybind11.h>
+
+// I have found cases where I want to accept or return a python object matching a collections.abc class.
+// This extension adds subclasses of py::object with type hints for the collections.abc classes.
+// This allows C++ functions to accept or return python objects that match the collection.abc classes.
+// Note that these are handled in the same way as py::object thus there is no type validation.
+
+namespace Amulet {
+namespace pybind11_extensions {
+    namespace collections {
+        template <typename T>
+        class Iterator : public pybind11::object {
+        public:
+            PYBIND11_OBJECT_DEFAULT(Iterator, object, PyIter_Check)
+
+            using iterator_category = std::input_iterator_tag;
+            using difference_type = pybind11::ssize_t;
+            using value_type = T;
+
+            Iterator& operator++()
+            {
+                advance();
+                return *this;
+            }
+
+            Iterator operator++(int)
+            {
+                auto rv = *this;
+                advance();
+                return rv;
+            }
+
+            T operator*() const
+            {
+                return obj().template cast<T>();
+            }
+
+            std::unique_ptr<T> operator->() const
+            {
+                return std::make_unique<T>(obj().template cast<T>());
+            }
+
+            static Iterator sentinel() { return {}; }
+
+            friend bool operator==(const Iterator& a, const Iterator& b) { return a.obj().ptr() == b.obj().ptr(); }
+            friend bool operator!=(const Iterator& a, const Iterator& b) { return a.obj().ptr() != b.obj().ptr(); }
+
+        private:
+            void advance()
+            {
+                value = pybind11::reinterpret_steal<pybind11::object>(PyIter_Next(m_ptr));
+                if (value.ptr() == nullptr && PyErr_Occurred()) {
+                    throw pybind11::error_already_set();
+                }
+            }
+
+            const pybind11::object& obj() const
+            {
+                if (m_ptr && !value.ptr()) {
+                    auto& self = const_cast<Iterator&>(*this);
+                    self.advance();
+                }
+                return value;
+            }
+
+        private:
+            pybind11::object value = {};
+        };
+        static_assert(std::input_iterator<Iterator<int>>);
+
+        template <typename T>
+        class Iterable : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(Iterable, object, pybind11::detail::PyIterable_Check)
+
+            Iterator<T> begin() const
+            {
+                return Iterator<T>(pybind11::object::begin());
+            }
+            Iterator<T> end() const
+            {
+                return Iterator<T>(pybind11::object::end());
+            }
+        };
+        static_assert(std::ranges::input_range<Iterable<int>>);
+        static_assert(std::convertible_to<std::ranges::range_value_t<Iterable<int>>, const int&>);
+
+        template <typename T>
+        class Sequence : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(Sequence, object, PySequence_Check)
+
+            Iterator<T> begin() const
+            {
+                return Iterator<T>(pybind11::object::begin());
+            }
+
+            Iterator<T> end() const
+            {
+                return Iterator<T>(pybind11::object::end());
+            }
+
+            Py_ssize_t size() const
+            {
+                return PyObject_Size(ptr());
+            }
+        };
+
+        template <typename K, typename V>
+        class Mapping : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(Mapping, object, PyMapping_Check)
+        };
+
+        template <typename K, typename V>
+        class MutableMapping : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(MutableMapping, object, PyMapping_Check)
+        };
+
+        template <typename K>
+        class KeysView : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(KeysView, object, PyObject_Type)
+        };
+
+        template <typename V>
+        class ValuesView : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(ValuesView, object, PyObject_Type)
+        };
+
+        template <typename K, typename V>
+        class ItemsView : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(ItemsView, object, PyObject_Type)
+        };
+    } // namespace collections
+} // namespace pybind11_extensions
+} // namespace Amulet
+
+namespace pybind11 {
+namespace detail {
+    template <typename T>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::Iterator<T>> {
+        static constexpr auto name = const_name("collections.abc.Iterator[") + make_caster<T>::name + const_name("]");
+    };
+
+    template <typename T>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::Iterable<T>> {
+        static constexpr auto name = const_name("collections.abc.Iterable[") + make_caster<T>::name + const_name("]");
+    };
+
+    template <typename T>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::Sequence<T>> {
+        static constexpr auto name = const_name("collections.abc.Sequence[") + make_caster<T>::name + const_name("]");
+    };
+
+    template <typename K, typename V>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::Mapping<K, V>> {
+        static constexpr auto name = const_name("collections.abc.Mapping[") + make_caster<K>::name + const_name(", ") + make_caster<V>::name + const_name("]");
+    };
+
+    template <typename K, typename V>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::MutableMapping<K, V>> {
+        static constexpr auto name = const_name("collections.abc.MutableMapping[") + make_caster<K>::name + const_name(", ")
+            + make_caster<V>::name + const_name("]");
+    };
+
+    template <typename K>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::KeysView<K>> {
+        static constexpr auto name = const_name("collections.abc.KeysView[") + make_caster<K>::name + const_name("]");
+    };
+
+    template <typename V>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::ValuesView<V>> {
+        static constexpr auto name = const_name("collections.abc.ValuesView[") + make_caster<V>::name + const_name("]");
+    };
+
+    template <typename K, typename V>
+    struct handle_type_name<Amulet::pybind11_extensions::collections::ItemsView<K, V>> {
+        static constexpr auto name = const_name("collections.abc.ItemsView[") + make_caster<K>::name + const_name(", ")
+            + make_caster<V>::name + const_name("]");
+    };
+}
+}

amulet/pybind11_extensions/compatibility.hpp

@@ -0,0 +1,55 @@
+#pragma once
+
+#include <filesystem>
+#include <string>
+
+#include <pybind11/pybind11.h>
+
+static std::string get_version_top(std::string version)
+{
+    return version.substr(0, version.find('.', version.find('.') + 1));
+}
+
+namespace Amulet {
+namespace pybind11_extensions {
+
+    inline void init_compiler_config(pybind11::module m)
+    {
+        pybind11::dict compiler_config;
+        compiler_config["pybind11_version"] = PYBIND11_VERSION;
+        compiler_config["compiler_id"] = COMPILER_ID;
+        compiler_config["compiler_version"] = COMPILER_VERSION;
+        m.attr("compiler_config") = compiler_config;
+    }
+
+    inline void check_compatibility(pybind11::module a, pybind11::module b)
+    {
+        std::string a_name = a.attr("__name__").cast<std::string>();
+        std::string b_name = b.attr("__name__").cast<std::string>();
+        pybind11::dict a_config = a.attr("compiler_config");
+        pybind11::dict b_config = b.attr("compiler_config");
+
+        std::string a_pybind11_version = a_config["pybind11_version"].cast<std::string>();
+        std::string b_pybind11_version = b_config["pybind11_version"].cast<std::string>();
+        if (a_pybind11_version != b_pybind11_version) {
+            throw std::runtime_error(
+                "pybind11 version mismatch. " + a_name + " is compiled for pybind11==" + a_pybind11_version + " and " + b_name + " is compiled for pybind11==" + b_pybind11_version);
+        }
+
+        std::string a_compiler_id = a_config["compiler_id"].cast<std::string>();
+        std::string b_compiler_id = b_config["compiler_id"].cast<std::string>();
+        if (a_compiler_id != b_compiler_id) {
+            throw std::runtime_error(
+                "compiler mismatch. " + a_name + " is compiled by " + a_compiler_id + " and " + b_name + " is compiled by " + b_compiler_id);
+        }
+
+        std::string a_compiler_version = a_config["compiler_version"].cast<std::string>();
+        std::string b_compiler_version = b_config["compiler_version"].cast<std::string>();
+        if (get_version_top(a_compiler_version) != get_version_top(b_compiler_version)) {
+            throw std::runtime_error(
+                "compiler version mismatch. " + a_name + " is compiled by " + a_compiler_id + " " + a_compiler_version + " and " + b_name + " is compiled by " + b_compiler_id + " " + b_compiler_version);
+        }
+    }
+
+} // namespace pybind11_extensions
+} // namespace Amulet

amulet/pybind11_extensions/contextlib.hpp

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include <functional>
+#include <optional>
+#include <type_traits>
+
+#include <amulet/pybind11_extensions/pybind11.hpp>
+
+namespace Amulet {
+namespace pybind11_extensions {
+    namespace contextlib {
+        template <typename T, typename ExitT = std::optional<bool>>
+        class ContextManager : public pybind11::object {
+            PYBIND11_OBJECT_DEFAULT(ContextManager, object, PyObject_Type)
+            using object::object;
+        };
+
+        namespace detail {
+            template <typename T, typename ExitT = std::optional<bool>>
+            class ContextManager {
+            public:
+                std::function<T()> enter;
+                std::function<ExitT(pybind11::object, pybind11::object, pybind11::object)> exit;
+                ContextManager(
+                    std::function<T()> enter,
+                    std::function<ExitT(pybind11::object, pybind11::object, pybind11::object)> exit)
+                    : enter(enter)
+                    , exit(exit)
+                {
+                }
+            };
+        }
+
+        template <typename T, typename ExitT = std::optional<bool>>
+        auto make_context_manager(
+            std::function<T()> enter,
+            std::function<ExitT(pybind11::object, pybind11::object, pybind11::object)> exit) -> ContextManager<T, ExitT>
+        {
+            using ContextManagerT = detail::ContextManager<T, ExitT>;
+            if (!pybind11_extensions::is_class_bound<ContextManagerT>()) {
+                pybind11::class_<ContextManagerT>(pybind11::handle(), "ContextManager", pybind11::module_local())
+                    .def(
+                        "__enter__",
+                        [](const ContextManagerT& self) -> T {
+                            return self.enter();
+                        })
+                    .def(
+                        "__exit__",
+                        [](const ContextManagerT& self, pybind11::object exc_type, pybind11::object exc_val, pybind11::object exc_tb) -> ExitT {
+                            return self.exit(exc_type, exc_val, exc_tb);
+                        });
+            }
+            return pybind11::cast(ContextManagerT(enter, exit));
+        }
+    } // namespace contextlib
+} // namespace pybind11_extensions
+} // namespace Amulet
+
+namespace pybind11 {
+namespace detail {
+    template <typename T, typename ExitT>
+    struct handle_type_name<Amulet::pybind11_extensions::contextlib::ContextManager<T, ExitT>> {
+        static constexpr auto name = const_name("contextlib.AbstractContextManager[")
+            + make_caster<std::conditional_t<std::is_same_v<void, T>, pybind11::none, T>>::name
+            + const_name(", ") + make_caster<ExitT>::name + const_name("]");
+    };
+}
+}

amulet/pybind11_extensions/hash.hpp

@@ -0,0 +1,31 @@
+#pragma once
+
+#include <pybind11/pybind11.h>
+
+namespace Amulet {
+namespace pybind11_extensions {
+
+    template <typename clsT>
+    void def_hash_identity(clsT cls)
+    {
+        auto PyId = pybind11::module::import("builtins").attr("id");
+        cls.def(
+            "__hash__",
+            [PyId](pybind11::object self) -> pybind11::int_ {
+                return PyId(self);
+            });
+    }
+
+    template <typename clsT>
+    void def_unhashable(clsT cls)
+    {
+        auto cls_name = cls.attr("__name__").template cast<std::string>();
+        cls.def(
+            "__hash__",
+            [cls_name](pybind11::object self) -> size_t {
+                throw pybind11::type_error("unhashable type: '" + cls_name + "'");
+            });
+    }
+
+} // namespace pybind11_extensions
+} // namespace Amulet

amulet/pybind11_extensions/iterator.hpp

@@ -0,0 +1,37 @@
+#pragma once
+#include <pybind11/pybind11.h>
+
+#include <amulet/pybind11_extensions/pybind11.hpp>
+#include <amulet/pybind11_extensions/builtins.hpp>
+#include <amulet/pybind11_extensions/collections.hpp>
+
+namespace Amulet {
+namespace pybind11_extensions {
+
+    // Create a python iterator around a C++ class that implements method next()
+    // Next must throw py::stop_iteration() to signal the end of the iterator.
+    template <
+        pybind11::return_value_policy Policy = pybind11::return_value_policy::automatic,
+        typename Iterator,
+        typename... Extra>
+    auto make_iterator(Iterator it, Extra&&... extra) -> pybind11_extensions::collections::Iterator<decltype(it.next())>
+    {
+        if (!is_class_bound<Iterator>()) {
+            pybind11::class_<Iterator>(pybind11::handle(), "iterator", pybind11::module_local())
+                .def(
+                    "__iter__",
+                    [](
+                        pybind11_extensions::PyObjectCpp<Iterator>& self) -> pybind11_extensions::PyObjectCpp<Iterator>& { return self; })
+                .def(
+                    "__next__",
+                    [](Iterator& self) -> decltype(it.next()) {
+                        return self.next();
+                    },
+                    std::forward<Extra>(extra)...,
+                    Policy);
+        }
+        return pybind11::cast(std::forward<Iterator>(it));
+    }
+
+} // namespace pybind11_extensions
+} // namespace Amulet