amulet-core 2.0a8__cp312-cp312-win_amd64.whl → 2.0.1a3.post250529101330__cp312-cp312-win_amd64.whl

amulet/level/abc/_level/_level.py

@@ -1,449 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Optional, TypeVar, Type, Generic, Iterator, Callable
-from contextlib import contextmanager, AbstractContextManager as ContextManager
-import logging
-from weakref import finalize
-
-from runtime_final import final
-from PIL import Image
-
-from amulet.version import PlatformType, VersionNumber
-from amulet.data_types import DimensionId
-from amulet.img import missing_world_icon_path
-
-from amulet.chunk import Chunk
-
-from amulet.utils.shareable_lock import ShareableRLock
-from amulet.utils.signal import Signal, SignalInstanceCacheName
-from amulet.utils.task_manager import AbstractCancelManager, VoidCancelManager
-
-from amulet.level.abc._history import HistoryManager
-from amulet.utils.weakref import CallableWeakMethod
-
-
-if TYPE_CHECKING:
-    from amulet.level.abc import Dimension  # noqa
-    from amulet.level.abc import PlayerStorage
-    from amulet.level.abc import RawLevel  # noqa
-
-log = logging.getLogger(__name__)
-
-missing_world_icon: Optional[Image.Image] = None
-
-
-RawLevelT = TypeVar("RawLevelT", bound="RawLevel")
-DimensionT = TypeVar("DimensionT", bound="Dimension")
-
-
-class LevelOpenData:
-    """Private level attributes that only exist when the level is open."""
-
-    history_manager: HistoryManager
-
-    def __init__(self) -> None:
-        self.history_manager = HistoryManager()
-
-
-OpenLevelDataT = TypeVar("OpenLevelDataT", bound=LevelOpenData)
-
-
-class Level(ABC, Generic[OpenLevelDataT, DimensionT, RawLevelT]):
-    """Base class for all levels."""
-
-    __finalise: finalize
-    _open_data: OpenLevelDataT | None
-    _level_lock: ShareableRLock
-    _history_enabled: bool
-
-    __slots__ = (
-        "__weakref__",
-        "__finalise",
-        SignalInstanceCacheName,
-        "_open_data",
-        "_level_lock",
-        "_history_enabled",
-    )
-
-    def __init__(self) -> None:
-        """
-        This cannot be called directly.
-        You must use one of the constructor classmethods
-        """
-        # Private attributes
-        self._open_data = None
-        self._level_lock = ShareableRLock()
-        self._history_enabled = True
-        self.__finalise = finalize(self, CallableWeakMethod(self.close))
-
-    def __del__(self) -> None:
-        self.__finalise()
-
-    opened = Signal[()]()
-
-    @final
-    def open(self, task_manager: AbstractCancelManager = VoidCancelManager()) -> None:
-        """Open the level.
-
-        If the level is already open, this does nothing.
-
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :raises amulet.utils.task_manager.TaskCancelled: If the task is cancelled.
-        """
-        with self.lock_unique(task_manager=task_manager):
-            if self.is_open(task_manager=task_manager):
-                # Do nothing if already open
-                return
-            self._open()
-            if self._open_data is None:
-                raise RuntimeError("_open_data has not been set")
-            self._open_data.history_manager.history_changed.connect(
-                self.history_changed
-            )
-            self.opened.emit()
-
-    @abstractmethod
-    def _open(self) -> None:
-        raise NotImplementedError
-
-    @final
-    def is_open(
-        self, task_manager: AbstractCancelManager = VoidCancelManager()
-    ) -> bool:
-        """Has the level been opened.
-
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :return: True if the level is open otherwise False.
-        :raises amulet.utils.task_manager.TaskCancelled: If the task is cancelled.
-        """
-        with self.lock_shared(task_manager=task_manager):
-            return self._open_data is not None
-
-    @final
-    @property
-    def _o(self) -> OpenLevelDataT:
-        o = self._open_data
-        if o is None:
-            raise RuntimeError("Level is not open")
-        return o
-
-    # Has the internal state changed
-    changed = Signal[()]()
-    # Has the external state been changed without our knowledge
-    external_changed = Signal[()]()
-
-    @abstractmethod
-    def save(self) -> None:
-        raise NotImplementedError
-
-    # Signal to notify all listeners that the data they hold is no longer valid
-    purged = Signal[()]()
-
-    def purge(self) -> None:
-        """
-        Unload all loaded data.
-        This is a nuclear function and must be used with :meth:`lock_unique`
-
-        This is functionally the same as closing and reopening the level.
-        """
-        self._o.history_manager.reset()
-        self.purged.emit()
-        self.history_changed.emit()
-
-    # Signal to notify all listeners that the level has been closed.
-    closing = Signal[()]()
-    closed = Signal[()]()
-
-    @final
-    def close(self, task_manager: AbstractCancelManager = VoidCancelManager()) -> None:
-        """Close the level.
-
-        If the level is not open, this does nothing.
-
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :raises amulet.utils.task_manager.TaskCancelled: If the task is cancelled.
-        """
-        with self.lock_unique(task_manager=task_manager):
-            if not self.is_open(task_manager=task_manager):
-                # Do nothing if already closed
-                return
-            self.closing.emit()
-            self._close()
-            if self._open_data is not None:
-                raise RuntimeError("_open_data is still set")
-            self.closed.emit()
-
-    @abstractmethod
-    def _close(self) -> None:
-        raise NotImplementedError
-
-    @property
-    @abstractmethod
-    def platform(self) -> PlatformType:
-        raise NotImplementedError
-
-    @property
-    @abstractmethod
-    def max_game_version(self) -> VersionNumber:
-        raise NotImplementedError
-
-    # Emitted when the undo or redo count has changed
-    history_changed = Signal[()]()
-
-    @property
-    def undo_count(self) -> int:
-        return self._o.history_manager.undo_count
-
-    def undo(self) -> None:
-        with self.lock_unique(blocking=False):
-            self._o.history_manager.undo()
-
-    @property
-    def redo_count(self) -> int:
-        return self._o.history_manager.redo_count
-
-    def redo(self) -> None:
-        with self.lock_unique(blocking=False):
-            self._o.history_manager.redo()
-
-    @contextmanager
-    def _lock(
-        self,
-        *,
-        edit: bool,
-        parallel: bool,
-        blocking: bool,
-        timeout: float,
-        task_manager: AbstractCancelManager = VoidCancelManager(),
-    ) -> Iterator[None]:
-        if parallel:
-            lock = self._level_lock.shared(blocking, timeout, task_manager)
-        else:
-            lock = self._level_lock.unique(blocking, timeout, task_manager)
-        with lock:
-            if edit and self.history_enabled:
-                self._o.history_manager.create_undo_bin()
-            yield
-
-    def lock_unique(
-        self,
-        *,
-        blocking: bool = True,
-        timeout: float = -1,
-        task_manager: AbstractCancelManager = VoidCancelManager(),
-    ) -> ContextManager[None]:
-        """
-        Get exclusive access to the level without editing it.
-        If you want to edit the level with exclusive access, use :meth:`edit_serial` instead.
-        If the level is being used by other threads, this will block until they are done.
-        Once acquired it will block other threads from accessing the level until this is released.
-
-        >>> level: Level
-        >>> with level.lock_unique():
-        >>>     # Lock is acquired before entering this block
-        >>>     ...
-        >>>     # Lock is released before exiting this block
-
-        :param blocking: Should this block until the lock can be acquired. Default is True.
-        :param timeout: Maximum amount of time to block for. Has no effect is blocking is False. Default is forever.
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :return: A context manager to acquire the lock.
-        :raises amulet.utils.shareable_lock.LockNotAcquired: If timeout was reached or cancel was called.
-        """
-        return self._lock(
-            edit=False,
-            parallel=False,
-            blocking=blocking,
-            timeout=timeout,
-            task_manager=task_manager,
-        )
-
-    def lock_shared(
-        self,
-        *,
-        blocking: bool = True,
-        timeout: float = -1,
-        task_manager: AbstractCancelManager = VoidCancelManager(),
-    ) -> ContextManager[None]:
-        """
-        Share the level without editing it.
-        If you want to edit the level in parallel with other threads, use :meth:`edit_parallel` instead.
-
-        >>> level: Level
-        >>> with level.lock_shared():
-        >>>     # Lock is acquired before entering this block
-        >>>     ...
-        >>>     # Lock is released before exiting this block
-
-        :param blocking: Should this block until the lock can be acquired. Default is True.
-        :param timeout: Maximum amount of time to block for. Has no effect is blocking is False. Default is forever.
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :return: A context manager to acquire the lock.
-        :raises amulet.utils.shareable_lock.LockNotAcquired: If timeout was reached or cancel was called.
-        """
-        return self._lock(
-            edit=False,
-            parallel=True,
-            blocking=blocking,
-            timeout=timeout,
-            task_manager=task_manager,
-        )
-
-    def edit_serial(
-        self,
-        *,
-        blocking: bool = True,
-        timeout: float = -1,
-        task_manager: AbstractCancelManager = VoidCancelManager(),
-    ) -> ContextManager[None]:
-        """
-        Get exclusive editing permissions for this level.
-        This is useful if you are doing something nuclear to the level and you don't want other code editing it at
-        the same time. Usually :meth:`edit_parallel` is sufficient when used with other locks.
-
-        >>> level: Level
-        >>> with level.edit_serial():  # This will block the thread until all other threads have finished with the level
-        >>>     # Lock is acquired before entering this block
-        >>>     # any code here will be run without any other threads touching the level
-        >>>     ...
-        >>>     # Lock is released before exiting this block
-        >>> # Other threads can modify the level here
-
-        :param blocking: Should this block until the lock can be acquired. Default is True.
-        :param timeout: Maximum amount of time to block for. Has no effect is blocking is False. Default is forever.
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :return: A context manager to acquire the lock.
-        :raises amulet.utils.shareable_lock.LockNotAcquired: If timeout was reached or cancel was called.
-        """
-        return self._lock(
-            edit=True,
-            parallel=False,
-            blocking=blocking,
-            timeout=timeout,
-            task_manager=task_manager,
-        )
-
-    def edit_parallel(
-        self,
-        *,
-        blocking: bool = True,
-        timeout: float = -1,
-        task_manager: AbstractCancelManager = VoidCancelManager(),
-    ) -> ContextManager[None]:
-        """
-        Edit the level in parallal with other threads.
-        This allows multiple threads that don't make nuclear changes to work in parallel.
-        Before modifying the level data, you must use this or :meth:`edit_serial`.
-        Using this ensures that no nuclear changes are made by other threads while your code is running.
-        If another thread has exclusive access to the level, this will block until it has finished and vice versa.
-        If you are going to make any nuclear changes to the level you must use :meth:`edit_serial` instead.
-
-        >>> level: Level
-        >>> with level.edit_serial():  # This will block the thread until all other unique calls have finished with the level
-        >>>     # Lock is acquired before entering this block
-        >>>     # any code here will be run in parallel with other parallel calls.
-        >>>     ...
-        >>>     # Lock is released before exiting this block
-        >>> # Other threads can modify the level here
-
-        :param blocking: Should this block until the lock can be acquired. Default is True.
-        :param timeout: Maximum amount of time to block for. Has no effect is blocking is False. Default is forever.
-        :param task_manager: The cancel manager through which cancel can be requested.
-        :return: A context manager to acquire the lock.
-        :raises amulet.utils.shareable_lock.LockNotAcquired: If timeout was reached or cancel was called.
-        """
-        return self._lock(
-            edit=True,
-            parallel=True,
-            blocking=blocking,
-            timeout=timeout,
-            task_manager=task_manager,
-        )
-
-    history_enabled_changed = Signal[()]()
-
-    @property
-    def history_enabled(self) -> bool:
-        """Should edit_serial and edit_parallel create undo points and should setting data load the original state."""
-        return self._history_enabled
-
-    @history_enabled.setter
-    def history_enabled(self, history_enabled: bool) -> None:
-        self._history_enabled = history_enabled
-        self.history_enabled_changed.emit()
-
-    @property
-    def thumbnail(self) -> Image.Image:
-        global missing_world_icon
-        if missing_world_icon is None:
-            missing_world_icon = Image.open(missing_world_icon_path)
-        return missing_world_icon
-
-    @property
-    @abstractmethod
-    def level_name(self) -> str:
-        """The human-readable name of the level"""
-        raise NotImplementedError
-
-    @property
-    @abstractmethod
-    def modified_time(self) -> float:
-        """The unix float timestamp of when the level was last modified."""
-        raise NotImplementedError
-
-    @property
-    def sub_chunk_size(self) -> int:
-        """
-        The dimensions of a sub-chunk.
-        """
-        return 16
-
-    @abstractmethod
-    def dimension_ids(self) -> frozenset[DimensionId]:
-        raise NotImplementedError
-
-    @abstractmethod
-    def get_dimension(self, dimension_id: DimensionId) -> DimensionT:
-        raise NotImplementedError
-
-    @property
-    @abstractmethod
-    def raw(self) -> RawLevelT:
-        """
-        Direct access to the level data.
-        Only use this if you know what you are doing.
-        """
-        raise NotImplementedError
-
-    @property
-    @abstractmethod
-    def player(self) -> PlayerStorage:
-        """Methods to interact with the player data for the level."""
-        raise NotImplementedError
-
-    @property
-    @abstractmethod
-    def native_chunk_class(self) -> Type[Chunk]:
-        raise NotImplementedError
-
-
-LevelT = TypeVar("LevelT", bound=Level)
-
-
-class LevelFriend(Generic[LevelT]):
-    """A base class for friends of the level that need to store a pointer to the level"""
-
-    _l_ref: Callable[[], LevelT | None]
-
-    __slots__ = ("_level_ref",)
-
-    def __init__(self, level_ref: Callable[[], LevelT | None]):
-        self._l_ref = level_ref
-
-    @property
-    def _l(self) -> LevelT:
-        level = self._l_ref()
-        if level is None:
-            raise RuntimeError("The level is no longer accessible")
-        return level

amulet/level/abc/_level/_loadable_level.py

@@ -1,42 +0,0 @@
-from __future__ import annotations
-
-from typing import Any
-from abc import ABC, abstractmethod
-
-from ._level import Level
-
-
-class LoadableLevel(Level, ABC):
-    """Level extension class for levels that can be loaded from existing data."""
-
-    __slots__ = ()
-
-    @staticmethod
-    @abstractmethod
-    def can_load(token: Any) -> bool:
-        """
-        Returns whether this level class is able to load the given data.
-
-        :param token: The token to check. Usually a file or directory path.
-        :return: True if the level can be loaded by this format wrapper, False otherwise.
-        """
-        raise NotImplementedError
-
-    @classmethod
-    @abstractmethod
-    def load(cls, token: Any) -> LoadableLevel:
-        """
-        Create a new instance from existing data.
-        You must call :meth:`~amulet.level.abc.Level.open` to open the level for editing.
-        :param token: The token to use to load the data.
-        :return: A new Level instance
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    def reload(self) -> None:
-        """
-        Reload the metadata in the existing instance.
-        This can only be done when the level is not open.
-        """
-        raise NotImplementedError

amulet/level/abc/_player_storage.py

@@ -1,7 +0,0 @@
-from __future__ import annotations
-
-from ._level import LevelFriend
-
-
-class PlayerStorage(LevelFriend):
-    __slots__ = ()

amulet/level/abc/_raw_level.py

@@ -1,187 +0,0 @@
-from __future__ import annotations
-
-from typing import Iterable, TypeVar, Generic, Callable
-from abc import ABC, abstractmethod
-from weakref import ref
-
-from amulet.data_types import ChunkCoordinates, DimensionId
-from amulet.chunk import Chunk
-from amulet.block import BlockStack
-from amulet.biome import Biome
-from amulet.selection import SelectionGroup
-
-PlayerIDT = TypeVar("PlayerIDT")
-RawPlayerT = TypeVar("RawPlayerT")
-ChunkT = TypeVar("ChunkT", bound=Chunk)
-RawChunkT = TypeVar("RawChunkT")
-
-
-class RawDimension(ABC, Generic[RawChunkT, ChunkT]):
-    __slots__ = ()
-
-    @property
-    @abstractmethod
-    def dimension_id(self) -> DimensionId:
-        raise NotImplementedError
-
-    @abstractmethod
-    def bounds(self) -> SelectionGroup:
-        """The editable region of the dimension."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def default_block(self) -> BlockStack:
-        """The default block for this dimension"""
-        raise NotImplementedError
-
-    @abstractmethod
-    def default_biome(self) -> Biome:
-        """The default biome for this dimension"""
-        raise NotImplementedError
-
-    @abstractmethod
-    def all_chunk_coords(self) -> Iterable[ChunkCoordinates]:
-        """Get an iterable of all the chunk coordinates that exist in the raw level data."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def has_chunk(self, cx: int, cz: int) -> bool:
-        """Check if the chunk exists in the raw level data."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def delete_chunk(self, cx: int, cz: int) -> None:
-        raise NotImplementedError
-
-    @abstractmethod
-    def get_raw_chunk(self, cx: int, cz: int) -> RawChunkT:
-        """Get the chunk data in its raw format.
-
-        This is usually the exact data that exists on disk.
-        The raw chunk format varies between each level class.
-        Each call to this method will return a unique object.
-
-        :param cx: The chunk x coordinate
-        :param cz: The chunk z coordinate
-        :return: The raw chunk.
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    def set_raw_chunk(self, cx: int, cz: int, chunk: RawChunkT) -> None:
-        """Set the chunk in its raw format."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def raw_chunk_to_native_chunk(
-        self, raw_chunk: RawChunkT, cx: int, cz: int
-    ) -> ChunkT:
-        """Unpack data from the raw chunk format (as stored on disk) into editable classes.
-
-        This takes ownership of the raw_chunk object.
-
-        :param cx: The chunk x coordinate
-        :param cz: The chunk z coordinate
-        :param raw_chunk: The raw chunk to unpack.
-        :return: The unpacked chunk.
-        """
-        raise NotImplementedError
-
-    @abstractmethod
-    def native_chunk_to_raw_chunk(self, chunk: ChunkT, cx: int, cz: int) -> RawChunkT:
-        """Pack the data from the editable classes into the raw format.
-
-        This takes ownership of the chunk object.
-
-        :param cx: The chunk x coordinate
-        :param cz: The chunk z coordinate
-        :param chunk: The native chunk to pack
-        :return: The packed chunk.
-        """
-        raise NotImplementedError
-
-
-RawDimensionT = TypeVar("RawDimensionT", bound=RawDimension)
-
-
-class RawLevel(ABC, Generic[RawDimensionT]):
-    """
-    A class with raw access to the level.
-    All of these methods directly read from or write to the level.
-    There is no way to undo changes made with these methods.
-    """
-
-    __slots__ = ("__weakref__",)
-
-    @abstractmethod
-    def dimension_ids(self) -> frozenset[DimensionId]:
-        raise NotImplementedError
-
-    @abstractmethod
-    def get_dimension(self, dimension_id: DimensionId) -> RawDimensionT:
-        raise NotImplementedError
-
-
-RawLevelT = TypeVar("RawLevelT", bound=RawLevel)
-
-
-class RawLevelFriend(Generic[RawLevelT]):
-    """A base class for friends of the raw level that need to store a pointer to the raw level"""
-
-    _r_ref: Callable[[], RawLevelT | None]
-
-    __slots__ = ("_r_ref",)
-
-    def __init__(self, raw_level_ref: Callable[[], RawLevelT | None]) -> None:
-        self._r_ref = raw_level_ref
-
-    @property
-    def _r(self) -> RawLevelT:
-        r = self._r_ref()
-        if r is None:
-            raise RuntimeError("Cannot access raw level")
-        return r
-
-
-class RawLevelPlayerComponent(ABC, Generic[PlayerIDT, RawPlayerT]):
-    """An extension for the RawLevel class for implementations that have player data."""
-
-    __slots__ = ()
-
-    @abstractmethod
-    def players(self) -> Iterable[PlayerIDT]:
-        raise NotImplementedError
-
-    @abstractmethod
-    def has_player(self, player_id: PlayerIDT) -> bool:
-        raise NotImplementedError
-
-    @abstractmethod
-    def get_raw_player(self, player_id: PlayerIDT) -> RawPlayerT:
-        raise NotImplementedError
-
-    @abstractmethod
-    def set_raw_player(self, player_id: PlayerIDT, player: RawPlayerT) -> None:
-        raise NotImplementedError
-
-
-class RawLevelBufferedComponent(ABC):
-    """
-    An extension for the RawLevel class for implementations that need a data buffer.
-
-    This should be used for formats that cannot stream data and must read and write the data in one go.
-    """
-
-    __slots__ = ()
-
-    @abstractmethod
-    def pre_save(self) -> None:
-        """A method to run before data is pushed to the raw level.
-        This is useful to save the level.dat before pushing chunk data."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def save(self) -> None:
-        """A method to run after data is pushed to the raw level.
-        This is useful for structure files to write the actual data to disk."""
-        raise NotImplementedError