amulet-core 2.0a8__cp312-cp312-win_amd64.whl → 2.0.1a2.post250529084747__cp312-cp312-win_amd64.whl

amulet/core/selection/box.pyi

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import types
+import typing
+
+import amulet.core.selection.group
+
+__all__ = ["SelectionBox"]
+
+class SelectionBox:
+    """
+    The SelectionBox class represents a single cuboid selection.
+
+    When combined with :class:`~amulet.api.selection.SelectionGroup` it can represent any arbitrary shape.
+    """
+
+    @typing.overload
+    def __eq__(self, arg0: SelectionBox) -> bool: ...
+    @typing.overload
+    def __eq__(self, arg0: typing.Any) -> bool | types.NotImplementedType: ...
+    def __ge__(self, arg0: SelectionBox) -> bool: ...
+    def __gt__(self, arg0: SelectionBox) -> bool: ...
+    def __hash__(self) -> int: ...
+    @typing.overload
+    def __init__(
+        self, min_x: int, min_y: int, min_z: int, size_x: int, size_y: int, size_z: int
+    ) -> None:
+        """
+        Construct a new SelectionBox instance.
+
+        >>> # a selection box that selects one block.
+        >>> box = SelectionBox(0, 0, 0, 1, 1, 1)
+
+        :param min_x: The minimum x coordinate of the box.
+        :param min_y: The minimum y coordinate of the box.
+        :param min_z: The minimum z coordinate of the box.
+        :param size_x: The size of the box in the x axis.
+        :param size_y: The size of the box in the y axis.
+        :param size_z: The size of the box in the z axis.
+        """
+
+    @typing.overload
+    def __init__(
+        self, point_1: tuple[int, int, int], point_2: tuple[int, int, int]
+    ) -> None:
+        """
+        Construct a new SelectionBox instance.
+
+        >>> # a selection box that selects one block.
+        >>> box = SelectionBox((0, 0, 0), (1, 1, 1))
+
+        :param point_1: The first coordinate of the box.
+        :param point_2: The second coordinate of the box.
+        """
+
+    def __le__(self, arg0: SelectionBox) -> bool: ...
+    def __lt__(self, arg0: SelectionBox) -> bool: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+    def contains_block(self, x: int, y: int, z: int) -> bool:
+        """
+        Is the block contained within the selection.
+
+        >>> selection1: AbstractBaseSelection
+        >>> (1, 2, 3) in selection1
+        True
+
+        :param x: The x coordinate of the block. Defined by the most negative corner.
+        :param y: The y coordinate of the block. Defined by the most negative corner.
+        :param z: The z coordinate of the block. Defined by the most negative corner.
+        :return: True if the block is in the selection.
+        """
+
+    def contains_box(self, other: SelectionBox) -> bool:
+        """
+        Does the other SelectionBox other fit entirely within this SelectionBox.
+
+        :param other: The SelectionBox to test.
+        :return: True if other fits in self, False otherwise.
+        """
+
+    def contains_point(self, x: float, y: float, z: float) -> bool:
+        """
+        Is the point contained within the selection.
+
+        >>> selection1: AbstractBaseSelection
+        >>> (1.5, 2.5, 3.5) in selection1
+        True
+
+        :param x: The x coordinate of the point.
+        :param y: The y coordinate of the point.
+        :param z: The z coordinate of the point.
+        :return: True if the point is in the selection.
+        """
+
+    @typing.overload
+    def intersects(self, other: SelectionBox) -> bool:
+        """
+        Does this selection intersect ``other``.
+
+        :param other: The other selection.
+        :return: True if the selections intersect, False otherwise.
+        """
+
+    @typing.overload
+    def intersects(self, other: amulet.core.selection.group.SelectionGroup) -> bool: ...
+    def touches(self, other: SelectionBox) -> bool:
+        """
+        Method to check if this instance of :class:`SelectionBox` touches but does not intersect another SelectionBox.
+
+        :param other: The other SelectionBox
+        :return: True if the two :class:`SelectionBox` instances touch, False otherwise
+        """
+
+    def touches_or_intersects(self, other: SelectionBox) -> bool:
+        """
+        Does this SelectionBox touch or intersect the other SelectionBox.
+
+        :param other: The other SelectionBox.
+        :return: True if the two :class:`SelectionBox` instances touch or intersect, False otherwise.
+        """
+
+    def translate(self, x: int, y: int, z: int) -> SelectionBox:
+        """
+        Create a new :class:`SelectionBox` based on this one with the coordinates moved by the given offset.
+
+        :param x: The x offset.
+        :param y: The y offset.
+        :param z: The z offset.
+        :return: The new selection with the given offset.
+        """
+
+    @property
+    def max(self) -> tuple[int, int, int]:
+        """
+        The maximum coordinate of the box.
+        """
+
+    @property
+    def max_x(self) -> int:
+        """
+        The maximum x coordinate of the box.
+        """
+
+    @property
+    def max_y(self) -> int:
+        """
+        The maximum y coordinate of the box.
+        """
+
+    @property
+    def max_z(self) -> int:
+        """
+        The maximum z coordinate of the box.
+        """
+
+    @property
+    def min(self) -> tuple[int, int, int]:
+        """
+        The minimum coordinate of the box.
+        """
+
+    @property
+    def min_x(self) -> int:
+        """
+        The minimum x coordinate of the box.
+        """
+
+    @property
+    def min_y(self) -> int:
+        """
+        The minimum y coordinate of the box.
+        """
+
+    @property
+    def min_z(self) -> int:
+        """
+        The minimum z coordinate of the box.
+        """
+
+    @property
+    def shape(self) -> tuple[int, int, int]:
+        """
+        The length of the box in the x, y and z axis.
+
+        >>> SelectionBox(0, 0, 0, 1, 1, 1).shape
+        (1, 1, 1)
+        """
+
+    @property
+    def size_x(self) -> int:
+        """
+        The length of the box in the x axis.
+        """
+
+    @property
+    def size_y(self) -> int:
+        """
+        The length of the box in the y axis.
+        """
+
+    @property
+    def size_z(self) -> int:
+        """
+        The length of the box in the z axis.
+        """
+
+    @property
+    def volume(self) -> int:
+        """
+        The number of blocks in the box.
+
+        >>> SelectionBox(0, 0, 0, 1, 1, 1).volume
+        1
+        """

amulet/core/selection/group.hpp

@@ -0,0 +1,80 @@
+#pragma once
+
+#include <array>
+#include <concepts>
+#include <ranges>
+#include <set>
+
+#include <amulet/core/dll.hpp>
+
+#include "box.hpp"
+
+namespace Amulet {
+
+class SelectionBox;
+
+class SelectionGroup {
+private:
+    std::set<SelectionBox> _boxes;
+
+public:
+    // Constructors
+    SelectionGroup() {};
+    SelectionGroup(const SelectionBox& box)
+    {
+        _boxes.insert(box);
+    }
+
+    template <typename Iterable>
+        requires std::ranges::input_range<Iterable> && std::convertible_to<std::ranges::range_value_t<Iterable>, const SelectionBox&>
+    SelectionGroup(const Iterable& boxes)
+    {
+        for (const SelectionBox& box : boxes) {
+            _boxes.emplace(box);
+        }
+    }
+
+    // Accessors
+    const std::set<SelectionBox>& selection_boxes() const
+    {
+        return _boxes;
+    }
+    size_t size() const
+    {
+        return _boxes.size();
+    }
+
+    // Bounds
+    AMULET_CORE_EXPORT std::int64_t min_x() const;
+    AMULET_CORE_EXPORT std::int64_t min_y() const;
+    AMULET_CORE_EXPORT std::int64_t min_z() const;
+    AMULET_CORE_EXPORT std::int64_t max_x() const;
+    AMULET_CORE_EXPORT std::int64_t max_y() const;
+    AMULET_CORE_EXPORT std::int64_t max_z() const;
+    AMULET_CORE_EXPORT std::array<std::int64_t, 3> min() const;
+    AMULET_CORE_EXPORT std::array<std::int64_t, 3> max() const;
+    AMULET_CORE_EXPORT std::pair<
+        std::array<std::int64_t, 3>,
+        std::array<std::int64_t, 3>>
+    bounds() const;
+    AMULET_CORE_EXPORT SelectionBox bounding_box() const;
+
+    // Contains and intersects
+    AMULET_CORE_EXPORT bool contains_block(std::int64_t x, std::int64_t y, std::int64_t z) const;
+    AMULET_CORE_EXPORT bool contains_point(double x, double y, double z) const;
+    AMULET_CORE_EXPORT bool intersects(const SelectionBox& other) const;
+    AMULET_CORE_EXPORT bool intersects(const SelectionGroup& other) const;
+
+    // Transform
+    AMULET_CORE_EXPORT SelectionGroup translate(std::int64_t dx, std::int64_t dy, std::int64_t dz) const;
+
+    // Operators
+    operator bool() const
+    {
+        return !_boxes.empty();
+    }
+    bool operator==(const SelectionGroup& rhs) const = default;
+    bool operator!=(const SelectionGroup& rhs) const = default;
+};
+
+}

amulet/core/selection/group.pyi

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+import collections.abc
+import types
+import typing
+
+import amulet.core.selection.box
+
+__all__ = ["SelectionGroup"]
+
+class SelectionGroup:
+    """
+    A container for zero or more :class:`SelectionBox` instances.
+
+    This allows for non-rectangular and non-contiguous selections.
+    """
+
+    __hash__: typing.ClassVar[None] = None  # type: ignore
+    def __bool__(self) -> bool:
+        """
+        The number of :class:`SelectionBox` classes in the group.
+        """
+
+    @typing.overload
+    def __eq__(self, arg0: SelectionGroup) -> bool:
+        """
+        Does the contents of this :class:`SelectionGroup` match the other :class:`SelectionGroup`.
+
+        Note if the boxes do not exactly match this will return False even if the volume represented is the same.
+
+        :param other: The other :class:`SelectionGroup` to compare with.
+        :return: True if the boxes contained match.
+        """
+
+    @typing.overload
+    def __eq__(self, arg0: typing.Any) -> bool | types.NotImplementedType: ...
+    @typing.overload
+    def __init__(self) -> None:
+        """
+        Create an empty SelectionGroup.
+
+        >>> SelectionGroup()
+        """
+
+    @typing.overload
+    def __init__(self, box: amulet.core.selection.box.SelectionBox) -> None:
+        """
+        Create a SelectionGroup containing the given box.
+
+        >>> SelectionGroup(SelectionBox(0, 0, 0, 1, 1, 1))
+        """
+
+    @typing.overload
+    def __init__(
+        self, boxes: collections.abc.Iterable[amulet.core.selection.box.SelectionBox]
+    ) -> None:
+        """
+        Create a SelectionGroup from the boxes in the iterable.
+
+        >>> SelectionGroup([
+        >>>     SelectionBox(0, 0, 0, 1, 1, 1),
+        >>>     SelectionBox(1, 1, 1, 1, 1, 1)
+        >>> ])
+        """
+
+    def __iter__(self) -> typing.Iterator[amulet.core.selection.box.SelectionBox]:
+        """
+        An iterable of all the :class:`SelectionBox` classes in the group.
+        """
+
+    def __len__(self) -> int:
+        """
+        The number of :class:`SelectionBox` classes in the group.
+        """
+
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+    def contains_block(self, x: int, y: int, z: int) -> bool:
+        """
+        Is the block contained within the selection.
+
+        >>> selection1: AbstractBaseSelection
+        >>> (1, 2, 3) in selection1
+        True
+
+        :param x: The x coordinate of the block. Defined by the most negative corner.
+        :param y: The y coordinate of the block. Defined by the most negative corner.
+        :param z: The z coordinate of the block. Defined by the most negative corner.
+        :return: True if the block is in the selection.
+        """
+
+    def contains_point(self, x: float, y: float, z: float) -> bool:
+        """
+        Is the point contained within the selection.
+
+        >>> selection1: AbstractBaseSelection
+        >>> (1.5, 2.5, 3.5) in selection1
+        True
+
+        :param x: The x coordinate of the point.
+        :param y: The y coordinate of the point.
+        :param z: The z coordinate of the point.
+        :return: True if the point is in the selection.
+        """
+
+    @typing.overload
+    def intersects(self, other: amulet.core.selection.box.SelectionBox) -> bool:
+        """
+        Does this selection intersect ``other``.
+
+        :param other: The other selection.
+        :return: True if the selections intersect, False otherwise.
+        """
+
+    @typing.overload
+    def intersects(self, other: SelectionGroup) -> bool: ...
+    def translate(self, x: int, y: int, z: int) -> SelectionGroup:
+        """
+        Create a new :class:`SelectionGroup` based on this one with the coordinates moved by the given offset.
+
+        :param x: The x offset.
+        :param y: The y offset.
+        :param z: The z offset.
+        :return: The new selection with the given offset.
+        """
+
+    @property
+    def bounding_box(self) -> amulet.core.selection.box.SelectionBox:
+        """
+        A SelectionBox containing this entire selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def bounds(self) -> tuple[tuple[int, int, int], tuple[int, int, int]]:
+        """
+        The minimum and maximum x, y and z coordinates in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def max(self) -> tuple[int, int, int]:
+        """
+        The maximum x, y and z coordinates in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def max_x(self) -> int:
+        """
+        The maximum x coordinate in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def max_y(self) -> int:
+        """
+        The maximum y coordinate in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def max_z(self) -> int:
+        """
+        The maximum z coordinate in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def min(self) -> tuple[int, int, int]:
+        """
+        The minimum x, y and z coordinates in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def min_x(self) -> int:
+        """
+        The minimum x coordinate in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def min_y(self) -> int:
+        """
+        The minimum y coordinate in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def min_z(self) -> int:
+        """
+        The minimum z coordinate in the selection.
+
+        :raises RuntimeError: If there are no boxes in the selection.
+        """
+
+    @property
+    def selection_boxes(
+        self,
+    ) -> typing.Iterator[amulet.core.selection.box.SelectionBox]:
+        """
+        An iterator of the :class:`SelectionBox` instances stored for this group.
+        """

amulet/{version.pyi → core/version/__init__.pyi}

@@ -13,16 +13,32 @@ __all__ = [
 ]
 
 class PlatformVersionContainer:
+    """
+    A class storing platform identifier and version number.
+    Thread safe.
+    """
+
     def __init__(self, platform: str, version: VersionNumber) -> None: ...
     def __repr__(self) -> str: ...
     @property
-    def platform(self) -> str: ...
+    def platform(self) -> str:
+        """
+        Get the platform identifier.
+        """
+
     @property
-    def version(self) -> VersionNumber: ...
+    def version(self) -> VersionNumber:
+        """
+        Get the version number.
+        """
 
 class VersionNumber:
     """
     This class is designed to store semantic versions and data versions and allow comparisons between them.
+    It is a wrapper around std::vector<std::int64_t> with special comparison handling.
+    The version can contain zero to max(int64) values.
+    Undefined trailing values are implied zeros. 1.1 == 1.1.0
+    All methods are thread safe.
 
     >>> v1 = VersionNumber(1, 0, 0)
     >>> v2 = VersionNumber(1, 0)
@@ -53,7 +69,7 @@ class VersionNumber:
     def __reversed__(self) -> typing.Iterator[int]: ...
     def __str__(self) -> str: ...
     def count(self, value: int) -> int: ...
-    def cropped_version(self) -> tuple:
+    def cropped_version(self) -> list[int]:
         """
         The version number with trailing zeros cut off.
         """
@@ -61,26 +77,58 @@ class VersionNumber:
     def index(
         self, value: int, start: int = 0, stop: int = 18446744073709551615
     ) -> int: ...
-    def padded_version(self, len: int) -> tuple:
+    def padded_version(self, len: int) -> list[int]:
         """
-        Get the version number padded with zeros to the given length.
+        Get the version number cropped or padded with zeros to the given length.
         """
 
 class VersionRange:
+    """
+    A class storing platform identifier and minimum and maximum version numbers.
+    Thread safe.
+    """
+
+    __hash__: typing.ClassVar[None] = None  # type: ignore
+    @typing.overload
+    def __eq__(self, arg0: VersionRange) -> bool: ...
+    @typing.overload
+    def __eq__(self, arg0: typing.Any) -> bool | types.NotImplementedType: ...
     def __init__(
         self, platform: str, min_version: VersionNumber, max_version: VersionNumber
     ) -> None: ...
     def __repr__(self) -> str: ...
-    def contains(self, arg0: str, arg1: VersionNumber) -> bool: ...
+    def contains(self, arg0: str, arg1: VersionNumber) -> bool:
+        """
+        Check if the platform is equal and the version number is within the range.
+        """
+
     @property
-    def max_version(self) -> VersionNumber: ...
+    def max_version(self) -> VersionNumber:
+        """
+        The maximum version number
+        """
+
     @property
-    def min_version(self) -> VersionNumber: ...
+    def min_version(self) -> VersionNumber:
+        """
+        The minimum version number
+        """
+
     @property
-    def platform(self) -> str: ...
+    def platform(self) -> str:
+        """
+        The platform identifier.
+        """
 
 class VersionRangeContainer:
+    """
+    A class that contains a version range.
+    """
+
     def __init__(self, version_range: VersionRange) -> None: ...
     def __repr__(self) -> str: ...
     @property
-    def version_range(self) -> VersionRange: ...
+    def version_range(self) -> VersionRange:
+        """
+        The version range.
+        """