amulet-core 2.0a5__cp311-cp311-macosx_10_9_universal2.whl

amulet/utils/typed_property.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+from typing import TypeVar, Any, Generic, Callable, overload
+
+GetT = TypeVar("GetT")
+SetT = TypeVar("SetT")
+
+
+class TypedProperty(Generic[GetT, SetT]):
+    """
+    Type hinting with the vanilla property does not support having a different type on the setter.
+    See https://github.com/python/mypy/issues/3004
+    This is a custom property implementation that supports independently typing the getter and setter to appease mypy.
+
+    Note that the getter, setter and deleter return the method they were given and not a property instance.
+    This was to appease mypy complaining about overriding variables.
+    This has a side effect that a setter can be used as a setter or the method
+
+    >>> class MyClass:
+    >>>     def __init__(self) -> None:
+    >>>         self._value = 1
+    >>>
+    >>>     @TypedProperty[int, int | float]
+    >>>     def value(self) -> int:
+    >>>         return self._value
+    >>>
+    >>>     @value.setter
+    >>>     def set_value(self, val: int | float) -> None:
+    >>>         self._value = int(val)
+    >>>
+    >>>     @value.deleter
+    >>>     def del_value(self) -> None:
+    >>>         del self._value
+    >>>
+    >>>
+    >>> inst = MyClass()
+    >>> assert inst.value == 1
+    >>> inst.value = 2
+    >>> assert inst.value == 2
+    >>> inst.set_value(3)
+    >>> assert inst.value == 3
+    >>> del inst.value
+    >>> try:
+    >>>     inst.value
+    >>> except AttributeError:
+    >>>     pass
+    >>> else:
+    >>>     raise Exception
+    >>> inst.value = 4
+    >>> assert inst.value == 4
+
+    If you want the original methods to be private then just prefix them with an underscore.
+    """
+
+    fget: Callable[[Any], GetT] | None
+    fset: Callable[[Any, SetT], None] | None
+    fdel: Callable[[Any], None] | None
+
+    def __init__(
+        self,
+        fget: Callable[[Any], GetT] | None = None,
+        fset: Callable[[Any, SetT], None] | None = None,
+        fdel: Callable[[Any], None] | None = None,
+        doc: str | None = None,
+    ) -> None:
+        self.fget = fget
+        self.fset = fset
+        self.fdel = fdel
+        if doc is None and fget is not None:
+            doc = fget.__doc__
+        self.__doc__ = doc
+        self._name = ""
+
+    def __set_name__(self, owner: Any, name: str) -> None:
+        self._name = name
+
+    @overload
+    def __get__(self, obj: None, objtype: None) -> TypedProperty[GetT, SetT]: ...
+
+    @overload
+    def __get__(self, obj: object, objtype: type[object]) -> GetT: ...
+
+    def __get__(
+        self, obj: Any, objtype: Any = None
+    ) -> GetT | TypedProperty[GetT, SetT]:
+        if obj is None:
+            return self
+        if self.fget is None:
+            raise AttributeError(f"property '{self._name}' has no getter")
+        return self.fget(obj)
+
+    def __set__(self, obj: Any, value: SetT) -> None:
+        if self.fset is None:
+            raise AttributeError(f"property '{self._name}' has no setter")
+        self.fset(obj, value)
+
+    def __delete__(self, obj: Any) -> None:
+        if self.fdel is None:
+            raise AttributeError(f"property '{self._name}' has no deleter")
+        self.fdel(obj)
+
+    def getter(self, fget: Callable[[Any], GetT]) -> Callable[[Any], GetT]:
+        self.fget = fget
+        return fget
+
+    def setter(self, fset: Callable[[Any, SetT], None]) -> Callable[[Any, SetT], None]:
+        self.fset = fset
+        return fset
+
+    def deleter(self, fdel: Callable[[Any], None]) -> Callable[[Any], None]:
+        self.fdel = fdel
+        return fdel

amulet/utils/typing.py

@@ -0,0 +1,4 @@
+# There are cases where it would be useful to type hint a class that must inherit from two or more ABCs.
+# Python doesn't currently have an intersection type but all cases that need it should refer here to make renaming
+# easier if Python implements it.
+from typing import Union as Intersection  # noqa

amulet/utils/typing.pyi

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+import typing
+
+__all__ = ["Intersection"]
+Intersection: typing._SpecialForm  # value = typing.Union

amulet/utils/weakref.py

@@ -0,0 +1,70 @@
+"""Extension to the builtin weakref module."""
+
+from __future__ import annotations
+from typing import Any, TypeVar, Generic, Callable, final
+from weakref import WeakMethod as _WeakMethod, ReferenceType as _ReferenceType
+
+T = TypeVar("T")
+
+
+# Classes have an __del__ method to run code at object destruction.
+# This is usually sufficient if the object gets deleted before the interpreter exits.
+# In some cases global variables are set to None causing the __del__ to fail if run after interpreter shutdown.
+# I have noticed this while debugging.
+#
+# In the following example when debugging sys is None when __del__ is called after interpreter shutdown.
+#
+# >>> import sys
+# >>>
+# >>> class Cls:
+# >>>     def __init__(self) -> None:
+# >>>         self._sys_modules = sys.modules
+# >>>         print(self._sys_modules)
+# >>>
+# >>>     def __del__(self) -> None:
+# >>>         print(self._sys_modules)
+# >>>         print(sys)
+# >>>
+# >>> t = Cls()
+#
+# weakref.finalize takes care of this. It can be manually called in the __del__ method if the object is garbage
+# collected before interpreter shutdown or automatically run at interpreter exit. It can only be called once.
+# It must be given a weak method otherwise the instance will be kept alive until interpreter exit.
+# weakref.WeakMethod is not directly callable so CallableWeakMethod is implemented to allow this.
+
+
+@final
+class CallableWeakMethod(_WeakMethod):
+    """
+    A wrapper around WeakMethod that makes the method directly callable.
+    If the method no longer exists, this does nothing.
+    """
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        meth = super().__call__()
+        if meth is not None:
+            return meth(*args, **kwargs)
+
+
+@final
+class DetachableWeakRef(Generic[T]):
+    """A weak reference that can be detached by the creator before the object is deleted."""
+
+    _ref: Callable[[], T | None]
+
+    @classmethod
+    def new(cls, obj: T) -> tuple[DetachableWeakRef[T], Callable[[], None]]:
+        """Get a new weak reference and a callable to detach the object.
+        Once called the reference will always return None.
+        """
+        self = cls(obj)
+        return self, self._detach
+
+    def __init__(self, obj: T) -> None:
+        self._ref = _ReferenceType(obj)
+
+    def __call__(self) -> T | None:
+        return self._ref()
+
+    def _detach(self) -> None:
+        self._ref = lambda: None

amulet/utils/weakref.pyi

@@ -0,0 +1,50 @@
+"""
+Extension to the builtin weakref module.
+"""
+
+from __future__ import annotations
+
+import typing
+import weakref
+from typing import Any, Generic, TypeVar, final
+
+__all__ = [
+    "Any",
+    "CallableWeakMethod",
+    "DetachableWeakRef",
+    "Generic",
+    "T",
+    "TypeVar",
+    "final",
+]
+
+class CallableWeakMethod(weakref.WeakMethod):
+    """
+
+    A wrapper around WeakMethod that makes the method directly callable.
+    If the method no longer exists, this does nothing.
+
+    """
+
+    __final__: typing.ClassVar[bool] = True
+    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> typing.Any: ...
+
+class DetachableWeakRef(typing.Generic):
+    """
+    A weak reference that can be detached by the creator before the object is deleted.
+    """
+
+    __final__: typing.ClassVar[bool] = True
+    @classmethod
+    def new(cls, obj: T) -> tuple[DetachableWeakRef[T], typing.Callable[[], None]]:
+        """
+        Get a new weak reference and a callable to detach the object.
+                Once called the reference will always return None.
+
+        """
+
+    def __call__(self) -> T | None: ...
+    def __init__(self, obj: T) -> None: ...
+    def _detach(self) -> None: ...
+
+T: typing.TypeVar  # value = ~T

amulet/utils/world_utils.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import math
+from typing import Tuple, Optional
+import numpy
+from numpy import ndarray, zeros, uint8
+from amulet.data_types import ChunkCoordinates
+
+
+def block_coords_to_chunk_coords(
+    *args: int, sub_chunk_size: int = 16
+) -> Tuple[int, ...]:
+    """
+    Converts the supplied block coordinates into chunk coordinates
+
+    :param args: The coordinate of the block(s)
+    :param sub_chunk_size: The dimension of the chunk (Optional. Default 16)
+    :return: The resulting chunk coordinates in (x, z) order
+    """
+    return tuple(int(math.floor(coord / sub_chunk_size)) for coord in args)
+
+
+def chunk_coords_to_block_coords(
+    x: int, z: int, chunk_x_size: int = 16, chunk_z_size: int = 16
+) -> ChunkCoordinates:
+    """
+    Converts the supplied chunk coordinates into block coordinates
+
+    :param x: The x coordinate of the chunk
+    :param z: The z coordinate of the chunk
+    :param chunk_x_size: The dimension of the chunk in the x direction (Optional. Default 16)
+    :param chunk_z_size: The dimension of the chunk in the z direction (Optional. Default 16)
+    :return: The resulting block coordinates in (x, z) order
+    """
+    return x * chunk_x_size, z * chunk_z_size
+
+
+def chunk_coords_to_region_coords(cx: int, cz: int) -> ChunkCoordinates:
+    """
+    Converts the supplied chunk coordinates into region coordinates
+
+    :param cx: The x coordinate of the chunk
+    :param cz: The z coordinate of the chunk
+    :return: The resulting region coordinates in (x, z) order
+    """
+    return cx >> 5, cz >> 5
+
+
+def region_coords_to_chunk_coords(rx: int, rz: int) -> ChunkCoordinates:
+    """
+    Converts the supplied region coordinates into the minimum chunk coordinates of that region
+
+    :param rx: The x coordinate of the region
+    :param rz: The y coordinate of the region
+    :return: The resulting minimum chunk coordinates of that region in (x, z) order
+    """
+    return rx << 5, rz << 5
+
+
+def blocks_slice_to_chunk_slice(
+    blocks_slice: slice, chunk_shape: int, chunk_coord: int
+) -> slice:
+    """
+    Converts the supplied blocks slice into chunk slice
+
+    :param blocks_slice: The slice of the blocks
+    :param chunk_shape: The shape of the chunk in this direction
+    :param chunk_coord: The coordinate of the chunk in this direction
+    :return: The resulting chunk slice
+    """
+    return slice(
+        min(max(0, blocks_slice.start - chunk_coord * chunk_shape), chunk_shape),
+        min(max(0, blocks_slice.stop - chunk_coord * chunk_shape), chunk_shape),
+    )
+
+
+def from_nibble_array(arr: ndarray) -> ndarray:
+    """
+    Unpacks a flat nibble array into a full size numpy array
+
+    :param arr: The nibble array
+    :return: The resulting array
+    """
+    shape = arr.size
+
+    new_arr = zeros((shape * 2), dtype=uint8)
+
+    new_arr[::2] = arr & 0xF
+    new_arr[1::2] = arr >> 4
+
+    return new_arr
+
+
+def to_nibble_array(arr: ndarray) -> ndarray:
+    """
+    packs a full size numpy array into a nibble array.
+
+    :param arr: Full numpy array
+    :return: The nibble array
+    """
+    arr = arr.ravel()
+    return (arr[::2] + (arr[1::2] << 4)).astype(uint8)  # type: ignore

amulet/utils/world_utils.pyi

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import math as math
+import types
+
+import numpy as numpy
+from numpy import ndarray, uint8, zeros
+
+__all__ = [
+    "ChunkCoordinates",
+    "block_coords_to_chunk_coords",
+    "blocks_slice_to_chunk_slice",
+    "chunk_coords_to_block_coords",
+    "chunk_coords_to_region_coords",
+    "from_nibble_array",
+    "math",
+    "ndarray",
+    "numpy",
+    "region_coords_to_chunk_coords",
+    "to_nibble_array",
+    "uint8",
+    "zeros",
+]
+
+def block_coords_to_chunk_coords(
+    *args: int, sub_chunk_size: int = 16
+) -> tuple[int, ...]:
+    """
+
+    Converts the supplied block coordinates into chunk coordinates
+
+    :param args: The coordinate of the block(s)
+    :param sub_chunk_size: The dimension of the chunk (Optional. Default 16)
+    :return: The resulting chunk coordinates in (x, z) order
+
+    """
+
+def blocks_slice_to_chunk_slice(
+    blocks_slice: slice, chunk_shape: int, chunk_coord: int
+) -> slice:
+    """
+
+    Converts the supplied blocks slice into chunk slice
+
+    :param blocks_slice: The slice of the blocks
+    :param chunk_shape: The shape of the chunk in this direction
+    :param chunk_coord: The coordinate of the chunk in this direction
+    :return: The resulting chunk slice
+
+    """
+
+def chunk_coords_to_block_coords(
+    x: int, z: int, chunk_x_size: int = 16, chunk_z_size: int = 16
+) -> ChunkCoordinates:
+    """
+
+    Converts the supplied chunk coordinates into block coordinates
+
+    :param x: The x coordinate of the chunk
+    :param z: The z coordinate of the chunk
+    :param chunk_x_size: The dimension of the chunk in the x direction (Optional. Default 16)
+    :param chunk_z_size: The dimension of the chunk in the z direction (Optional. Default 16)
+    :return: The resulting block coordinates in (x, z) order
+
+    """
+
+def chunk_coords_to_region_coords(cx: int, cz: int) -> ChunkCoordinates:
+    """
+
+    Converts the supplied chunk coordinates into region coordinates
+
+    :param cx: The x coordinate of the chunk
+    :param cz: The z coordinate of the chunk
+    :return: The resulting region coordinates in (x, z) order
+
+    """
+
+def from_nibble_array(arr: ndarray) -> ndarray:
+    """
+
+    Unpacks a flat nibble array into a full size numpy array
+
+    :param arr: The nibble array
+    :return: The resulting array
+
+    """
+
+def region_coords_to_chunk_coords(rx: int, rz: int) -> ChunkCoordinates:
+    """
+
+    Converts the supplied region coordinates into the minimum chunk coordinates of that region
+
+    :param rx: The x coordinate of the region
+    :param rz: The y coordinate of the region
+    :return: The resulting minimum chunk coordinates of that region in (x, z) order
+
+    """
+
+def to_nibble_array(arr: ndarray) -> ndarray:
+    """
+
+    packs a full size numpy array into a nibble array.
+
+    :param arr: Full numpy array
+    :return: The nibble array
+
+    """
+
+ChunkCoordinates: types.GenericAlias  # value = tuple[int, int]

amulet/version.cpp

@@ -0,0 +1,136 @@
+#include <stdexcept>
+#include <cstdint>
+#include <compare>
+
+#include <amulet/version.hpp>
+
+
+namespace Amulet {
+    void VersionNumber::serialise(BinaryWriter& writer) const {
+        writer.writeNumeric<std::uint8_t>(1);
+        writer.writeNumeric<std::uint64_t>(vec.size());
+        for (const std::int64_t& v : vec){
+            writer.writeNumeric<std::int64_t>(v);
+        }
+    }
+    std::shared_ptr<VersionNumber> VersionNumber::deserialise(BinaryReader& reader){
+        auto version_number = reader.readNumeric<std::uint8_t>();
+        switch (version_number) {
+            case 1:
+            {
+                std::uint64_t count;
+                reader.readNumericInto(count);
+                std::vector<std::int64_t> vec(count);
+                for (size_t i = 0; i < count; i++) {
+                    reader.readNumericInto<std::int64_t>(vec[i]);
+                }
+                return std::make_shared<VersionNumber>(vec);
+            }
+            default:
+                throw std::invalid_argument("Unsupported version " + std::to_string(version_number));
+        }
+    }
+
+    std::int64_t VersionNumber::operator[](size_t index) const {
+        if (index >= vec.size()) {
+            return 0;
+        }
+        return vec[index];
+    }
+
+    std::string VersionNumber::toString() const {
+        std::ostringstream oss;
+        for (size_t i = 0; i < vec.size(); ++i) {
+            if (i > 0){
+                oss << '.';
+            }
+            oss << vec[i];
+        }
+        return oss.str();
+    }
+
+    std::vector<std::int64_t> VersionNumber::cropped_version() const {
+        bool found_non_zero = false;
+        std::vector<std::int64_t> out;
+        for (auto it = vec.rbegin(); it != vec.rend(); ++it) {
+            if (found_non_zero){
+                out.push_back(*it);
+            } else if (*it != 0) {
+                found_non_zero = true;
+                out.push_back(*it);
+            }
+        }
+        std::reverse(out.begin(), out.end());
+        return out;
+    }
+
+    std::vector<std::int64_t> VersionNumber::padded_version(size_t len) const {
+        std::vector<std::int64_t> out(len);
+        for (size_t i = 0; i < len; i++){
+            out[i] = (*this)[i];
+        }
+        return out;
+    }
+
+    void PlatformVersionContainer::serialise(BinaryWriter& writer) const {
+        writer.writeNumeric<std::uint8_t>(1);
+        writer.writeSizeAndBytes(platform);
+        version->serialise(writer);
+    }
+    std::shared_ptr<PlatformVersionContainer> PlatformVersionContainer::deserialise(BinaryReader& reader){
+        auto version_number = reader.readNumeric<std::uint8_t>();
+        switch (version_number) {
+        case 1:
+        {
+            std::string platform = reader.readSizeAndBytes();
+            auto version = VersionNumber::deserialise(reader);
+            return std::make_shared<PlatformVersionContainer>(platform, version);
+        }
+        default:
+            throw std::invalid_argument("Unsupported version " + std::to_string(version_number));
+        }
+    }
+
+    void VersionRange::serialise(BinaryWriter& writer) const {
+        writer.writeNumeric<std::uint8_t>(1);
+        writer.writeSizeAndBytes(platform);
+        min_version->serialise(writer);
+        max_version->serialise(writer);
+    }
+    std::shared_ptr<VersionRange> VersionRange::deserialise(BinaryReader& reader) {
+        auto version_number = reader.readNumeric<std::uint8_t>();
+        switch (version_number) {
+        case 1:
+        {
+            std::string platform = reader.readSizeAndBytes();
+            auto min_version = VersionNumber::deserialise(reader);
+            auto max_version = VersionNumber::deserialise(reader);
+            return std::make_shared<VersionRange>(platform, min_version, max_version);
+        }
+        default:
+            throw std::invalid_argument("Unsupported version " + std::to_string(version_number));
+        }
+    }
+
+    bool VersionRange::contains(const PlatformType& platform_, const VersionNumber& version) const {
+        return platform == platform_ && *min_version <= version && version <= *max_version;
+    }
+
+    void VersionRangeContainer::serialise(BinaryWriter& writer) const {
+        writer.writeNumeric<std::uint8_t>(1);
+        version_range->serialise(writer);
+    }
+    std::shared_ptr<VersionRangeContainer> VersionRangeContainer::deserialise(BinaryReader& reader) {
+        auto version_number = reader.readNumeric<std::uint8_t>();
+        switch (version_number) {
+        case 1:
+        {
+            return std::make_shared<VersionRangeContainer>(
+                VersionRange::deserialise(reader)
+            );
+        }
+        default:
+            throw std::invalid_argument("Unsupported version " + std::to_string(version_number));
+        }
+    }
+}