amulet-core 2.0a3__cp312-cp312-win_amd64.whl

amulet/utils/call_spec/_call_spec.py

@@ -0,0 +1,262 @@
+"""This modules contains classes to notify other code of the call specification for a function.
+The aim is to support generating GUIs without having to manually program a GUI to handle the function call.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    Any,
+    Callable,
+    Hashable,
+    Protocol,
+    TypeVar,
+    cast,
+    ParamSpec,
+    overload,
+    Concatenate,
+    runtime_checkable,
+)
+from collections.abc import Sequence
+from abc import ABC, abstractmethod
+
+
+class AbstractArg(ABC):
+    """The base class for all arguments."""
+
+    @abstractmethod
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        raise NotImplementedError
+
+
+class AbstractHashableArg(AbstractArg, ABC):
+    """A base class for all arguments that are hashable."""
+
+
+class DocumentationArg(AbstractArg):
+    """A way to add documentation for an argument."""
+
+    def __init__(
+        self, arg: AbstractArg, name: str | None = None, description: str | None = None
+    ) -> None:
+        """Construct a DocumentationArg instance.
+
+        :param arg: The argument this documentation relates to.
+        :param name: The short name for the argument.
+        :param description: A longer description for the argument.
+        """
+        self.arg = arg
+        self.name = name
+        self.description = description
+
+
+class ConstantArg(AbstractArg):
+    """A constant argument.
+    Use this for fixed values.
+    """
+
+    def __init__(self, value: Any) -> None:
+        self.value = value
+
+
+class StringArg(AbstractHashableArg):
+    """A string argument"""
+
+    def __init__(self, default: str = "") -> None:
+        self.default = default
+
+
+class FilePathArg(StringArg):
+    """A path to a file on disk. Converts to a string."""
+
+
+class DirectoryPathArg(StringArg):
+    """A path to a directory on disk. Converts to a string."""
+
+
+class BytesArg(AbstractHashableArg):
+    """A bytes argument"""
+
+    def __init__(self, default: bytes = b"") -> None:
+        self.default = default
+
+
+class BoolArg(AbstractHashableArg):
+    """A bool argument"""
+
+    def __init__(self, default: bool = False) -> None:
+        self.default = default
+
+
+class IntArg(AbstractHashableArg):
+    """An int argument"""
+
+    def __init__(
+        self,
+        default: int = 0,
+        min_value: int | None = None,
+        max_value: int | None = None,
+    ) -> None:
+        self.default = default
+        self.min_value = min_value
+        self.max_value = max_value
+
+
+class FloatArg(AbstractHashableArg):
+    """A float argument"""
+
+    def __init__(
+        self,
+        default: float = 0,
+        min_value: float | None = None,
+        max_value: float | None = None,
+    ) -> None:
+        self.default = default
+        self.min_value = min_value
+        self.max_value = max_value
+
+
+class TupleArg(AbstractArg):
+    """A tuple argument"""
+
+    def __init__(self, *args: AbstractArg) -> None:
+        self.args = args
+
+
+class HashableTupleArg(AbstractArg):
+    """A tuple argument where all elements are hashable."""
+
+    def __init__(self, *args: AbstractHashableArg) -> None:
+        self.args = args
+
+
+class SequenceArg(AbstractArg):
+    """
+    A sequence of other arguments.
+    Each element must match element_type.
+    length must be a positive integer for a fixed length or None for unbounded length.
+    """
+
+    def __init__(
+        self,
+        element_type: AbstractArg,
+        default: Sequence[AbstractArg] = (),
+        min_length: int | None = None,
+        max_length: int | None = None,
+    ) -> None:
+        self.element_type = element_type
+        self.default = default
+        self.min_length = min_length
+        self.max_length = max_length
+
+
+class PositionalArgs(SequenceArg):
+    """A sequence of arguments that should be unpacked into the container.
+    This is useful when a CallableArg can take a variable number of an argument.
+    """
+
+
+class DictArg(AbstractArg):
+    """A dictionary argument"""
+
+    def __init__(self, key: AbstractHashableArg, value: AbstractArg) -> None:
+        self.key = key
+        self.value = value
+
+
+class UnionArg(AbstractArg):
+    """The object must match one of the types in args"""
+
+    def __init__(self, *args: AbstractArg) -> None:
+        self.args = args
+
+
+class HashableUnionArg(AbstractArg):
+    """The object must match one of the types in args"""
+
+    def __init__(self, *args: AbstractHashableArg) -> None:
+        self.args = args
+
+
+class CallableArg(AbstractArg):
+    """An argument generated by a function.
+    This can be used to create instances of classes.
+    kwargs specify the arguments to pass to the function.
+    """
+
+    def __init__(
+        self, func: Callable[..., Any], *args: AbstractArg, **kwargs: AbstractArg
+    ) -> None:
+        self.func = func
+        self.call_spec = CallSpec(*args, **kwargs)
+
+
+class HashableCallableArg(AbstractHashableArg):
+    """An argument generated by a function.
+    This can be used to create instances of classes.
+    kwargs specify the arguments to pass to the function.
+    """
+
+    def __init__(self, func: Callable[..., Hashable], call_spec: CallSpec) -> None:
+        self.func = func
+        self.call_spec = call_spec
+
+
+class CallSpec:
+    """Arguments and keyword arguments that should be unpacked to call a function."""
+
+    def __init__(self, *args: AbstractArg, **kwargs: AbstractArg) -> None:
+        self.args = args
+        self.kwargs = kwargs
+
+
+# The following is a really janky workaround to add a variable to a function or method in a way that mypy likes.
+# This would be made so much simpler if Python had an Intersection type hint.
+
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
+
+
+@runtime_checkable
+class TypedCallable(Protocol[P, R]):
+    call_spec: CallSpec
+
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
+
+
+@runtime_checkable
+class TypedMethod(Protocol[P, R]):
+    call_spec: CallSpec
+
+    def __call__(self, self_: Any, *args: P.args, **kwargs: P.kwargs) -> R: ...
+
+    @overload
+    def __get__(self, instance: None, owner: None) -> TypedMethod[P, R]: ...
+
+    @overload
+    def __get__(self, instance: object, owner: object) -> TypedCallable[P, R]: ...
+
+
+def callable_spec(
+    *args: AbstractArg, **kwargs: AbstractArg
+) -> Callable[[Callable[P, R]], TypedCallable[P, R]]:
+    call_spec: CallSpec = CallSpec(*args, **kwargs)
+
+    def wrap(func: Callable[P, R]) -> TypedCallable[P, R]:
+        func_ = cast(TypedCallable[P, R], func)
+        func_.call_spec = call_spec
+        return func_
+
+    return wrap
+
+
+def method_spec(
+    *args: AbstractArg, **kwargs: AbstractArg
+) -> Callable[[Callable[Concatenate[Any, P], R]], TypedMethod[P, R]]:
+    call_spec: CallSpec = CallSpec(*args, **kwargs)
+
+    def wrap(func: Callable[Concatenate[Any, P], R]) -> TypedMethod[P, R]:
+        func_ = cast(TypedMethod[P, R], func)
+        func_.call_spec = call_spec
+        return func_
+
+    return wrap

amulet/utils/call_spec/_call_spec.pyi

@@ -0,0 +1,272 @@
+"""
+This modules contains classes to notify other code of the call specification for a function.
+The aim is to support generating GUIs without having to manually program a GUI to handle the function call.
+"""
+
+from __future__ import annotations
+
+import abc
+import typing
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any, ParamSpec, Protocol, TypeVar, cast, overload, runtime_checkable
+
+__all__ = [
+    "ABC",
+    "AbstractArg",
+    "AbstractHashableArg",
+    "Any",
+    "BoolArg",
+    "BytesArg",
+    "CallSpec",
+    "CallableArg",
+    "ConstantArg",
+    "DictArg",
+    "DirectoryPathArg",
+    "DocumentationArg",
+    "FilePathArg",
+    "FloatArg",
+    "HashableCallableArg",
+    "HashableTupleArg",
+    "HashableUnionArg",
+    "IntArg",
+    "P",
+    "ParamSpec",
+    "PositionalArgs",
+    "Protocol",
+    "R",
+    "Sequence",
+    "SequenceArg",
+    "StringArg",
+    "TupleArg",
+    "TypeVar",
+    "TypedCallable",
+    "TypedMethod",
+    "UnionArg",
+    "abstractmethod",
+    "callable_spec",
+    "cast",
+    "method_spec",
+    "overload",
+    "runtime_checkable",
+]
+
+class AbstractArg(abc.ABC):
+    """
+    The base class for all arguments.
+    """
+
+    def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None: ...
+
+class AbstractHashableArg(AbstractArg, abc.ABC):
+    """
+    A base class for all arguments that are hashable.
+    """
+
+class BoolArg(AbstractHashableArg):
+    """
+    A bool argument
+    """
+
+    def __init__(self, default: bool = False) -> None: ...
+
+class BytesArg(AbstractHashableArg):
+    """
+    A bytes argument
+    """
+
+    def __init__(self, default: bytes = ...) -> None: ...
+
+class CallSpec:
+    """
+    Arguments and keyword arguments that should be unpacked to call a function.
+    """
+
+    def __init__(self, *args: AbstractArg, **kwargs: AbstractArg) -> None: ...
+
+class CallableArg(AbstractArg):
+    """
+    An argument generated by a function.
+        This can be used to create instances of classes.
+        kwargs specify the arguments to pass to the function.
+
+    """
+
+    def __init__(
+        self,
+        func: typing.Callable[..., typing.Any],
+        *args: AbstractArg,
+        **kwargs: AbstractArg,
+    ) -> None: ...
+
+class ConstantArg(AbstractArg):
+    """
+    A constant argument.
+        Use this for fixed values.
+
+    """
+
+    def __init__(self, value: typing.Any) -> None: ...
+
+class DictArg(AbstractArg):
+    """
+    A dictionary argument
+    """
+
+    def __init__(self, key: AbstractHashableArg, value: AbstractArg) -> None: ...
+
+class DirectoryPathArg(StringArg):
+    """
+    A path to a directory on disk. Converts to a string.
+    """
+
+class DocumentationArg(AbstractArg):
+    """
+    A way to add documentation for an argument.
+    """
+
+    def __init__(
+        self, arg: AbstractArg, name: str | None = None, description: str | None = None
+    ) -> None:
+        """
+        Construct a DocumentationArg instance.
+
+                :param arg: The argument this documentation relates to.
+                :param name: The short name for the argument.
+                :param description: A longer description for the argument.
+
+        """
+
+class FilePathArg(StringArg):
+    """
+    A path to a file on disk. Converts to a string.
+    """
+
+class FloatArg(AbstractHashableArg):
+    """
+    A float argument
+    """
+
+    def __init__(
+        self,
+        default: float = 0,
+        min_value: float | None = None,
+        max_value: float | None = None,
+    ) -> None: ...
+
+class HashableCallableArg(AbstractHashableArg):
+    """
+    An argument generated by a function.
+        This can be used to create instances of classes.
+        kwargs specify the arguments to pass to the function.
+
+    """
+
+    def __init__(
+        self, func: typing.Callable[..., Hashable], call_spec: CallSpec
+    ) -> None: ...
+
+class HashableTupleArg(AbstractArg):
+    """
+    A tuple argument where all elements are hashable.
+    """
+
+    def __init__(self, *args: AbstractHashableArg) -> None: ...
+
+class HashableUnionArg(AbstractArg):
+    """
+    The object must match one of the types in args
+    """
+
+    def __init__(self, *args: AbstractHashableArg) -> None: ...
+
+class IntArg(AbstractHashableArg):
+    """
+    An int argument
+    """
+
+    def __init__(
+        self,
+        default: int = 0,
+        min_value: int | None = None,
+        max_value: int | None = None,
+    ) -> None: ...
+
+class PositionalArgs(SequenceArg):
+    """
+    A sequence of arguments that should be unpacked into the container.
+        This is useful when a CallableArg can take a variable number of an argument.
+
+    """
+
+class SequenceArg(AbstractArg):
+    """
+
+    A sequence of other arguments.
+    Each element must match element_type.
+    length must be a positive integer for a fixed length or None for unbounded length.
+
+    """
+
+    def __init__(
+        self,
+        element_type: AbstractArg,
+        default: typing.Sequence[AbstractArg] = tuple(),
+        min_length: int | None = None,
+        max_length: int | None = None,
+    ) -> None: ...
+
+class StringArg(AbstractHashableArg):
+    """
+    A string argument
+    """
+
+    def __init__(self, default: str) -> None: ...
+
+class TupleArg(AbstractArg):
+    """
+    A tuple argument
+    """
+
+    def __init__(self, *args: AbstractArg) -> None: ...
+
+class TypedCallable(typing.Protocol):
+    __non_callable_proto_members__: typing.ClassVar[set] = {"call_spec"}
+    _is_runtime_protocol: typing.ClassVar[bool] = True
+    @classmethod
+    def __subclasshook__(cls, other): ...
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> R: ...
+    def __init__(self, *args, **kwargs): ...
+
+class TypedMethod(typing.Protocol):
+    __non_callable_proto_members__: typing.ClassVar[set] = {"call_spec"}
+    _is_runtime_protocol: typing.ClassVar[bool] = True
+    @staticmethod
+    def __get__(*args, **kwds):
+        """
+        Helper for @overload to raise when called.
+        """
+
+    @classmethod
+    def __subclasshook__(cls, other): ...
+    def __call__(self, self_: typing.Any, *args: P.args, **kwargs: P.kwargs) -> R: ...
+    def __init__(self, *args, **kwargs): ...
+
+class UnionArg(AbstractArg):
+    """
+    The object must match one of the types in args
+    """
+
+    def __init__(self, *args: AbstractArg) -> None: ...
+
+def callable_spec(
+    *args: AbstractArg, **kwargs: AbstractArg
+) -> typing.Callable[[typing.Callable[P, R]], TypedCallable[P, R]]: ...
+def method_spec(
+    *args: AbstractArg, **kwargs: AbstractArg
+) -> typing.Callable[
+    [typing.Callable[Concatenate[typing.Any, P], R]], TypedMethod[P, R]
+]: ...
+
+P: typing.ParamSpec  # value = ~P
+R: typing.TypeVar  # value = +R

amulet/utils/format_utils.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import os
+import warnings
+
+from amulet_nbt import read_nbt, NamedTag
+
+
+def check_all_exist(in_dir: str, *args: str) -> bool:
+    """
+    Check that all files exist in a parent directory
+
+    :param in_dir: The parent directory
+    :param args: file or folder names to look for
+    :return: Boolean value indicating whether all were found
+    """
+
+    return all(os.path.exists(os.path.join(in_dir, child)) for child in args)
+
+
+def check_one_exists(in_dir: str, *args: str) -> bool:
+    """
+    Check that at least one file exists in a parent directory
+
+    :param in_dir: The parent directory
+    :param args: file or folder names to look for
+    :return: Boolean value indicating whether at least one was found
+    """
+
+    return any(os.path.exists(os.path.join(in_dir, child)) for child in args)
+
+
+def load_leveldat(in_dir: str) -> NamedTag:
+    """
+    Load the root tag of the level.dat file in the directory
+
+    :param in_dir: The world directory containing the level.dat file
+    :return: The NBT root tag
+    """
+    warnings.warn("load_leveldat is depreciated.", DeprecationWarning)
+    return read_nbt(os.path.join(in_dir, "level.dat"))

amulet/utils/generator.py

@@ -0,0 +1,18 @@
+from typing import Generator, TypeVar, Any
+
+
+T = TypeVar("T")
+
+
+def generator_unpacker(gen: Generator[Any, Any, T]) -> T:
+    """
+    Unpack a generator and return the value returned by the generator.
+
+    :param gen: The generator to unpack.
+    :return: The value that was returned by the generator.
+    """
+    try:
+        while True:
+            next(gen)
+    except StopIteration as e:
+        return e.value  # type: ignore