amsdal 0.5.23__cp311-cp311-macosx_10_9_universal2.whl

amsdal/services/transaction_execution.pyi

@@ -0,0 +1,93 @@
+import ast
+from _typeshed import Incomplete
+from amsdal.configs.main import settings as settings
+from amsdal.errors import TransactionNotFoundError as TransactionNotFoundError
+from amsdal_utils.utils.singleton import Singleton
+from collections.abc import Callable as Callable, Generator
+from pathlib import Path
+from typing import Any
+
+logger: Incomplete
+
+def is_transaction(statement: ast.AST) -> bool:
+    """
+    Determines if a given AST statement is a transaction function.
+
+    This function checks if the provided AST statement is an asynchronous or synchronous function
+    definition that is decorated with the `transaction` decorator.
+
+    Args:
+        statement (ast.AST): The AST statement to check.
+
+    Returns:
+        bool: True if the statement is a transaction function, False otherwise.
+    """
+def annotation_is_model(annotation: Any) -> bool: ...
+
+class TransactionExecutionService(metaclass=Singleton):
+    """
+    Service for executing transactions.
+
+    This class provides methods to execute transactions, load transaction functions,
+    and handle asynchronous transactions. It ensures that transactions are executed
+    with the correct arguments and handles any necessary preprocessing of arguments.
+    """
+    _transactions: dict[str, Callable[..., Any]]
+    def __init__(self) -> None: ...
+    def execute_transaction(self, transaction_name: str, args: dict[str, Any], *, load_references: bool = True) -> Any:
+        """
+        Executes a transaction with the given name and arguments.
+
+        This method retrieves the transaction function by its name, processes the arguments,
+        and executes the transaction. It handles both synchronous and asynchronous transactions
+        and performs necessary preprocessing of arguments, such as loading references.
+
+        Args:
+            transaction_name (str): The name of the transaction to execute.
+            args (dict[str, Any]): The arguments to pass to the transaction function.
+            load_references (bool, optional): Whether to load references in the arguments. Defaults to True.
+
+        Returns:
+            Any: The result of the transaction execution.
+        """
+    async def async_execute_transaction(self, transaction_name: str, args: dict[str, Any], *, load_references: bool = True) -> Any:
+        """
+        Executes a transaction with the given name and arguments.
+
+        This method retrieves the transaction function by its name, processes the arguments,
+        and executes the transaction. It handles both synchronous and asynchronous transactions
+        and performs necessary preprocessing of arguments, such as loading references.
+
+        Args:
+            transaction_name (str): The name of the transaction to execute.
+            args (dict[str, Any]): The arguments to pass to the transaction function.
+            load_references (bool, optional): Whether to load references in the arguments. Defaults to True.
+
+        Returns:
+            Any: The result of the transaction execution.
+        """
+    def get_transaction_func(self, transaction_name: str) -> Callable[..., Any]:
+        """
+        Retrieves the transaction function by its name.
+
+        This method checks if the transaction function is already loaded in the `_transactions` dictionary.
+        If not, it attempts to load the transaction function from the available transaction definitions.
+
+        Args:
+            transaction_name (str): The name of the transaction function to retrieve.
+
+        Returns:
+            Callable[..., Any]: The transaction function corresponding to the given name.
+
+        Raises:
+            TransactionNotFoundError: If the transaction function with the specified name is not found.
+        """
+    @staticmethod
+    def _run_async_transaction(transaction_func: Callable[..., Any], args: dict[str, Any]) -> Any: ...
+    def _load_transaction(self, transaction_name: str) -> Callable[..., Any]: ...
+    @classmethod
+    def _get_transaction_definitions(cls) -> Generator[tuple[ast.FunctionDef | ast.AsyncFunctionDef, Path], None, None]: ...
+    @classmethod
+    def _iterate_module(cls, module_path: Path) -> Generator[tuple[ast.FunctionDef | ast.AsyncFunctionDef, Path], None, None]: ...
+    @classmethod
+    def _iterate_file(cls, file_path: Path) -> Generator[tuple[ast.FunctionDef | ast.AsyncFunctionDef, Path], None, None]: ...

amsdal/storages/__init__.py

@@ -0,0 +1,20 @@
+from amsdal_models.storage.base import Storage
+
+from amsdal.configs.main import settings
+
+_DEFAULT_STORAGE = None
+
+
+def set_default_storage(storage: Storage) -> None:
+    global _DEFAULT_STORAGE  # noqa: PLW0603
+    _DEFAULT_STORAGE = storage
+
+
+def default_storage() -> Storage:
+    global _DEFAULT_STORAGE  # noqa: PLW0603
+
+    if _DEFAULT_STORAGE is None:
+        # Determine backend from settings
+        class_path = settings.DEFAULT_FILE_STORAGE
+        _DEFAULT_STORAGE = Storage.from_storage_spec({'storage_class': class_path})
+    return _DEFAULT_STORAGE

amsdal/storages/__init__.pyi

@@ -0,0 +1,8 @@
+from _typeshed import Incomplete
+from amsdal.configs.main import settings as settings
+from amsdal_models.storage.base import Storage
+
+_DEFAULT_STORAGE: Incomplete
+
+def set_default_storage(storage: Storage) -> None: ...
+def default_storage() -> Storage: ...

amsdal/storages/file_system.py

@@ -0,0 +1,214 @@
+import asyncio
+import os
+from contextlib import suppress
+from pathlib import Path
+from typing import IO
+from typing import Any
+from typing import BinaryIO
+
+from amsdal_models.storage.base import Storage
+from amsdal_models.storage.errors import StorageError
+from amsdal_models.storage.helpers import build_storage_address
+from amsdal_models.storage.types import FileProtocol
+from amsdal_utils.config.manager import AmsdalConfigManager
+
+CHUNK_SIZE = 8 * 1024
+
+
+class FileSystemStorage(Storage):
+    """
+    Simple filesystem-based storage backend.
+
+    - base_dir: root directory for stored files
+    - base_url: URL prefix for building public URLs (optional)
+    """
+
+    keeps_local_copy = False
+
+    def __init__(
+        self,
+        base_dir: str | os.PathLike[Any] | None = None,
+        base_url: str | None = None,
+        *,
+        serialize_base_dir: bool = True,
+        serialize_base_url: bool = True,
+    ) -> None:
+        from amsdal.configs.main import settings
+
+        # If AMSDAL is configured to run in async mode, ensure aiofiles is installed.
+        if AmsdalConfigManager().get_config().async_mode:
+            try:
+                import aiofiles  # noqa: F401
+            except ImportError as e:
+                msg = (
+                    "AMSDAL is configured to run in async mode, but the 'aiofiles' package is not installed.\n"
+                    'Please install it to enable async file operations.\n\n'
+                    'Example:\n'
+                    '    pip install aiofiles\n\n'
+                    f'Original error: {e}'
+                )
+                raise ImportError(msg) from e
+
+        _base_dir = base_dir or settings.MEDIA_ROOT
+        _base_url = base_url or settings.MEDIA_URL
+
+        self.base_dir = Path(_base_dir).resolve()
+        self.base_url = _base_url
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        self.serialize_base_dir = serialize_base_dir
+        self.serialize_base_url = serialize_base_url
+
+    def save(self, file: FileProtocol, content: BinaryIO) -> str:
+        suggested = file.filename
+        final_name = self._get_available_name(suggested)
+        full_path = self._full_path(final_name)
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with full_path.open('wb') as f:
+            # Ensure reading from start
+            with suppress(Exception):
+                if hasattr(content, 'seek'):
+                    content.seek(0)
+
+            chunk = content.read(CHUNK_SIZE)
+
+            while chunk:
+                f.write(chunk)
+                chunk = content.read(CHUNK_SIZE)
+
+        file.storage_address = build_storage_address(self, final_name)
+        return final_name
+
+    def open(self, file: FileProtocol, mode: str = 'rb') -> IO[Any]:
+        name = self._name_for(file)
+        full_path = self._full_path(name)
+
+        if not full_path.exists():
+            msg = f'File not found: {name}'
+            raise StorageError(msg)
+        return full_path.open(mode)
+
+    def delete(self, file: FileProtocol) -> None:
+        name = self._name_for(file)
+        try:
+            self._full_path(name).unlink(missing_ok=True)
+        except Exception as e:
+            msg = f"Failed to delete '{name}': {e}"
+            raise StorageError(msg) from e
+
+    def exists(self, file: FileProtocol) -> bool:
+        name = self._name_for(file)
+        return self._full_path(name).exists()
+
+    def url(self, file: FileProtocol) -> str:
+        name = self._name_for(file)
+        if not self.base_url:
+            # Return file path as fallback
+            return self._full_path(name).as_uri()
+
+        prefix = self.base_url.rstrip('/')
+        name_posix = Path(name).as_posix().lstrip('/')
+
+        return f'{prefix}/{name_posix}'
+
+    # ---- async counterparts ----
+    async def asave(self, file: FileProtocol, content: BinaryIO) -> str:
+        import aiofiles.os
+
+        suggested = file.filename
+        final_name = self._get_available_name(suggested)
+        full_path = self._full_path(final_name)
+        # Ensure directory exists
+        await aiofiles.os.makedirs(str(full_path.parent), exist_ok=True)
+
+        # Ensure reading from start
+        with suppress(Exception):
+            if hasattr(content, 'seek'):
+                with suppress(Exception):
+                    await asyncio.to_thread(content.seek, 0)
+
+        async with aiofiles.open(str(full_path), 'wb') as f:  # type: ignore[call-arg]
+            while True:
+                chunk = await asyncio.to_thread(content.read, CHUNK_SIZE)
+                if not chunk:
+                    break
+                await f.write(chunk)
+
+        file.storage_address = build_storage_address(self, final_name)
+
+        return final_name
+
+    async def aopen(self, file: FileProtocol, mode: str = 'rb') -> Any:
+        import aiofiles.ospath
+
+        name = self._name_for(file)
+        full_path = self._full_path(name)
+
+        if not await aiofiles.ospath.exists(str(full_path)):
+            msg = f'File not found: {name}'
+            raise StorageError(msg)
+
+        return aiofiles.open(str(full_path), mode)  # type: ignore[call-overload]
+
+    async def adelete(self, file: FileProtocol) -> None:
+        import aiofiles.os
+        import aiofiles.ospath
+
+        name = self._name_for(file)
+        full_path = self._full_path(name)
+
+        if await aiofiles.ospath.exists(str(full_path)):
+            try:
+                await aiofiles.os.remove(str(full_path))
+            except Exception as e:  # pragma: no cover - error path
+                msg = f"Failed to delete '{name}': {e}"
+                raise StorageError(msg) from e
+
+    async def aexists(self, file: FileProtocol) -> bool:
+        import aiofiles.ospath
+
+        name = self._name_for(file)
+        return await aiofiles.ospath.exists(str(self._full_path(name)))
+
+    async def aurl(self, file: FileProtocol) -> str:
+        # Pure computation; no disk I/O.
+        return self.url(file)
+
+    def _full_path(self, name: str) -> Path:
+        # Sanitize name to avoid path traversal
+        norm = Path(name).as_posix().lstrip('/')
+
+        return (self.base_dir / norm).resolve()
+
+    def _get_available_name(self, name: str) -> str:
+        # If file exists, add suffixes to avoid collision
+        candidate = Path(name)
+        base = candidate.stem
+        suffix = candidate.suffix
+        parent = candidate.parent.as_posix()
+        i = 0
+        final = candidate.as_posix()
+
+        # Check filesystem directly to avoid relying on public exists signature
+        while self._full_path(final).exists():
+            i += 1
+            new_name = f'{base}_{i}{suffix}'
+            final = str(Path(parent) / new_name) if parent and parent != '.' else new_name
+        return final
+
+    def _name_for(self, file: FileProtocol) -> str:
+        if getattr(file, 'storage_address', None) and getattr(file.storage_address, 'ref', None) is not None:
+            if getattr(file.storage_address.ref, 'object_id', None) is not None:  # type: ignore[union-attr]
+                return str(file.storage_address.ref.object_id)  # type: ignore[union-attr]
+        return file.filename
+
+    def _export_kwargs(self) -> dict[str, Any]:
+        kwargs = {}
+
+        if self.serialize_base_dir:
+            kwargs['base_dir'] = str(self.base_dir)
+
+        if self.serialize_base_url:
+            kwargs['base_url'] = self.base_url
+
+        return kwargs

amsdal/storages/file_system.pyi

@@ -0,0 +1,36 @@
+import os
+from _typeshed import Incomplete
+from amsdal_models.storage.base import Storage
+from amsdal_models.storage.types import FileProtocol
+from pathlib import Path
+from typing import Any, BinaryIO, IO
+
+CHUNK_SIZE: Incomplete
+
+class FileSystemStorage(Storage):
+    """
+    Simple filesystem-based storage backend.
+
+    - base_dir: root directory for stored files
+    - base_url: URL prefix for building public URLs (optional)
+    """
+    keeps_local_copy: bool
+    base_dir: Incomplete
+    base_url: Incomplete
+    serialize_base_dir: Incomplete
+    serialize_base_url: Incomplete
+    def __init__(self, base_dir: str | os.PathLike[Any] | None = None, base_url: str | None = None, *, serialize_base_dir: bool = True, serialize_base_url: bool = True) -> None: ...
+    def save(self, file: FileProtocol, content: BinaryIO) -> str: ...
+    def open(self, file: FileProtocol, mode: str = 'rb') -> IO[Any]: ...
+    def delete(self, file: FileProtocol) -> None: ...
+    def exists(self, file: FileProtocol) -> bool: ...
+    def url(self, file: FileProtocol) -> str: ...
+    async def asave(self, file: FileProtocol, content: BinaryIO) -> str: ...
+    async def aopen(self, file: FileProtocol, mode: str = 'rb') -> Any: ...
+    async def adelete(self, file: FileProtocol) -> None: ...
+    async def aexists(self, file: FileProtocol) -> bool: ...
+    async def aurl(self, file: FileProtocol) -> str: ...
+    def _full_path(self, name: str) -> Path: ...
+    def _get_available_name(self, name: str) -> str: ...
+    def _name_for(self, file: FileProtocol) -> str: ...
+    def _export_kwargs(self) -> dict[str, Any]: ...

amsdal/transactions/__init__.py

@@ -0,0 +1,13 @@
+from amsdal_data.transactions import async_transaction
+from amsdal_data.transactions import transaction
+from amsdal_data.transactions.background.schedule import SCHEDULE_TYPE
+from amsdal_data.transactions.background.schedule import Crontab
+from amsdal_data.transactions.background.schedule import ScheduleConfig
+
+__all__ = [
+    'SCHEDULE_TYPE',
+    'Crontab',
+    'ScheduleConfig',
+    'async_transaction',
+    'transaction',
+]

amsdal/transactions/__init__.pyi

@@ -0,0 +1,4 @@
+from amsdal_data.transactions import async_transaction as async_transaction, transaction as transaction
+from amsdal_data.transactions.background.schedule import Crontab as Crontab, SCHEDULE_TYPE as SCHEDULE_TYPE, ScheduleConfig as ScheduleConfig
+
+__all__ = ['SCHEDULE_TYPE', 'Crontab', 'ScheduleConfig', 'async_transaction', 'transaction']

amsdal/utils/contrib_paths.py

@@ -0,0 +1,23 @@
+from collections.abc import Generator
+from importlib import import_module
+from pathlib import Path
+
+
+def get_contrib_schemas_paths() -> Generator[Path, None, None]:
+    """
+    Retrieves paths to contribution schemas.
+
+    This function iterates over the configured contributions in the settings and yields
+    the paths to the 'models' directories for each contribution.
+
+    Returns:
+        Generator[Path, None, None]: A generator that yields paths to the 'models' directories
+        of the configured contributions.
+    """
+    from amsdal.configs.main import settings
+
+    for contrib in settings.CONTRIB:
+        module_name, *_ = contrib.rsplit('.', 2)
+        module = import_module(module_name)
+
+        yield Path(module.__file__).parent / 'models'  # type: ignore[arg-type]

amsdal/utils/contrib_paths.pyi

@@ -0,0 +1,14 @@
+from collections.abc import Generator
+from pathlib import Path
+
+def get_contrib_schemas_paths() -> Generator[Path, None, None]:
+    """
+    Retrieves paths to contribution schemas.
+
+    This function iterates over the configured contributions in the settings and yields
+    the paths to the 'models' directories for each contribution.
+
+    Returns:
+        Generator[Path, None, None]: A generator that yields paths to the 'models' directories
+        of the configured contributions.
+    """