amsdal 0.1.26__cp310-cp310-macosx_10_9_universal2.whl → 0.1.27__cp310-cp310-macosx_10_9_universal2.whl

amsdal/migration/migrations.pyi

@@ -16,15 +16,60 @@ class Operation(ABC, metaclass=abc.ABCMeta):
     def backward(self, executor: BaseMigrationExecutor) -> None: ...
 
 class SchemaOperation(Operation):
+    """
+    Base class for schema operations.
+
+    Attributes:
+        forward_args (list[Any]): Arguments for the forward operation.
+        backward_args (list[Any]): Arguments for the backward operation.
+        forward_method_name (str): Name of the method to call for the forward operation.
+        backward_method_name (str): Name of the method to call for the backward operation.
+    """
     forward_args: list[Any]
     backward_args: list[Any]
     forward_method_name: str
     backward_method_name: str
-    def forward(self, executor: BaseMigrationExecutor) -> None: ...
-    def forward_schema(self, executor: BaseMigrationExecutor) -> None: ...
-    def backward(self, executor: BaseMigrationExecutor) -> None: ...
+    def forward(self, executor: BaseMigrationExecutor) -> None:
+        """
+        Executes the forward operation.
+
+        Args:
+            executor (BaseMigrationExecutor): The executor responsible for running migrations.
+
+        Returns:
+            None
+        """
+    def forward_schema(self, executor: BaseMigrationExecutor) -> None:
+        """
+        Executes the forward schema operation.
+
+        Args:
+            executor (BaseMigrationExecutor): The executor responsible for running migrations.
+
+        Returns:
+            None
+        """
+    def backward(self, executor: BaseMigrationExecutor) -> None:
+        """
+        Executes the backward operation.
+
+        Args:
+            executor (BaseMigrationExecutor): The executor responsible for running migrations.
+
+        Returns:
+            None
+        """
 
 class CreateClass(SchemaOperation):
+    """
+    Represents an operation to create a class schema.
+
+    Attributes:
+        forward_method_name (str): The name of the method to call for the forward operation.
+        backward_method_name (str): The name of the method to call for the backward operation.
+        forward_args (list[Any]): Arguments for the forward operation.
+        backward_args (list[Any]): Arguments for the backward operation.
+    """
     forward_method_name: str
     backward_method_name: str
     forward_args: Incomplete
@@ -32,6 +77,15 @@ class CreateClass(SchemaOperation):
     def __init__(self, class_name: str, new_schema: dict[str, Any], schema_type: SchemaTypes) -> None: ...
 
 class UpdateClass(SchemaOperation):
+    """
+    Represents an operation to update a class schema.
+
+    Attributes:
+        forward_method_name (str): The name of the method to call for the forward operation.
+        backward_method_name (str): The name of the method to call for the backward operation.
+        forward_args (list[Any]): Arguments for the forward operation.
+        backward_args (list[Any]): Arguments for the backward operation.
+    """
     forward_method_name: str
     backward_method_name: str
     forward_args: Incomplete
@@ -39,6 +93,15 @@ class UpdateClass(SchemaOperation):
     def __init__(self, class_name: str, old_schema: dict[str, Any], new_schema: dict[str, Any], schema_type: SchemaTypes) -> None: ...
 
 class DeleteClass(SchemaOperation):
+    """
+    Represents an operation to delete a class schema.
+
+    Attributes:
+        forward_method_name (str): The name of the method to call for the forward operation.
+        backward_method_name (str): The name of the method to call for the backward operation.
+        forward_args (list[Any]): Arguments for the forward operation.
+        backward_args (list[Any]): Arguments for the backward operation.
+    """
     forward_method_name: str
     backward_method_name: str
     forward_args: Incomplete
@@ -48,14 +111,56 @@ class DeleteClass(SchemaOperation):
 class MigrationSchemas(DefaultMigrationSchemas): ...
 
 class MigrateData(Operation):
+    """
+    Represents a data migration operation.
+
+    Attributes:
+        forward_migration (Callable[[MigrationSchemas \\| BaseMigrationSchemas], None]): The function to call for
+            the forward migration.
+        backward_migration (Callable[[MigrationSchemas \\| BaseMigrationSchemas], None]): The function to call for
+            the backward migration.
+    """
     @staticmethod
     def noop(schemas: MigrationSchemas) -> None: ...
     forward_migration: Incomplete
     backward_migration: Incomplete
     def __init__(self, forward_migration: Callable[[MigrationSchemas | BaseMigrationSchemas], None], backward_migration: Callable[[MigrationSchemas | BaseMigrationSchemas], None]) -> None: ...
-    def forward(self, executor: BaseMigrationExecutor) -> None: ...
-    def backward(self, executor: BaseMigrationExecutor) -> None: ...
-    def forward_schema(self, executor: BaseMigrationExecutor) -> None: ...
+    def forward(self, executor: BaseMigrationExecutor) -> None:
+        """
+        Executes the forward data migration.
+
+        Args:
+            executor (BaseMigrationExecutor): The executor responsible for running migrations.
+
+        Returns:
+            None
+        """
+    def backward(self, executor: BaseMigrationExecutor) -> None:
+        """
+        Executes the backward data migration.
+
+        Args:
+            executor (BaseMigrationExecutor): The executor responsible for running migrations.
+
+        Returns:
+            None
+        """
+    def forward_schema(self, executor: BaseMigrationExecutor) -> None:
+        """
+        No-op for forward schema in data migration.
+
+        Args:
+            executor (BaseMigrationExecutor): The executor responsible for running migrations.
+
+        Returns:
+            None
+        """
 
 class Migration:
+    """
+    Represents a collection of migration operations.
+
+    Attributes:
+        operations (list[Operation]): The list of migration operations.
+    """
     operations: list[Operation]

amsdal/migration/migrations_loader.pyi

@@ -4,14 +4,29 @@ from collections.abc import Iterator
 from pathlib import Path
 
 class MigrationsLoader:
+    """
+    Loads and manages migration files from a specified directory.
+    """
     _migrations_path: Incomplete
     _module_type: Incomplete
     _module_name: Incomplete
     _migrations_files: Incomplete
     def __init__(self, migrations_dir: Path, module_type: ModuleTypes, module_name: str | None = None) -> None: ...
     @property
-    def has_initial_migration(self) -> bool: ...
+    def has_initial_migration(self) -> bool:
+        """
+        Checks if there is an initial migration file.
+
+        Returns:
+            bool: True if there is an initial migration file, False otherwise.
+        """
     @property
-    def last_migration_number(self) -> int: ...
+    def last_migration_number(self) -> int:
+        """
+        Gets the number of the last migration file.
+
+        Returns:
+            int: The number of the last migration file, or -1 if there are no migration files.
+        """
     def __iter__(self) -> Iterator[MigrationFile]: ...
     def _load_migration_files(self) -> None: ...

amsdal/migration/schemas_loaders.pyi

@@ -14,10 +14,23 @@ class BaseClassSchemaLoader(ABC, metaclass=abc.ABCMeta):
     def iter_app_schemas(self) -> Iterator[ClassSchema]: ...
 
 class JsonClassSchemaLoader(EnrichSchemasMixin, BaseClassSchemaLoader):
+    """
+    Loads and enriches JSON class schemas from a specified root path.
+
+    Attributes:
+        schemas_root_path (Path): The root path to the JSON schemas.
+        module_type (ModuleTypes): The type of the module for the schemas.
+    """
     schemas_root_path: Incomplete
     module_type: Incomplete
     def __init__(self, schemas_root_path: Path, module_type: ModuleTypes = ...) -> None: ...
-    def iter_app_schemas(self) -> Iterator[ClassSchema]: ...
+    def iter_app_schemas(self) -> Iterator[ClassSchema]:
+        """
+        Iterates over the application schemas.
+
+        Yields:
+            ClassSchema: The next class schema in the iteration.
+        """
     def _enriched_user_schemas(self) -> list[ObjectSchema]: ...
     @staticmethod
     def _load_schemas(schemas_path: Path) -> list[ObjectSchema]: ...

amsdal/migration/utils.pyi

@@ -10,9 +10,49 @@ from pathlib import Path
 
 reference_schema: Incomplete
 
-def object_schema_to_table_schema(object_schema: ObjectSchema) -> TableSchema: ...
+def object_schema_to_table_schema(object_schema: ObjectSchema) -> TableSchema:
+    """
+    Converts an ObjectSchema to a TableSchema.
+
+    Args:
+        object_schema (ObjectSchema): The object schema to convert.
+
+    Returns:
+        TableSchema: The converted table schema.
+    """
 def _process_properties(properties: dict[str, PropertyData] | None, required: list[str]) -> list[TableColumnSchema]: ...
 def _process_property_type(property_type: str, items: TypeData | DictSchema | LegacyDictSchema | None = None, context: dict[str, type | Model | NestedSchemaModel] | None = None) -> type | NestedSchemaModel | ArraySchemaModel | DictSchemaModel | type[JsonSchemaModel]: ...
-def schema_to_nested_column_schema(schema: ObjectSchema, context: dict[str, type | Model | NestedSchemaModel]) -> NestedSchemaModel | type: ...
-def contrib_to_module_root_path(contrib: str) -> Path: ...
-def map_module_type_to_schema_type(module_type: ModuleTypes) -> SchemaTypes: ...
+def schema_to_nested_column_schema(schema: ObjectSchema, context: dict[str, type | Model | NestedSchemaModel]) -> NestedSchemaModel | type:
+    """
+    Converts an ObjectSchema to a NestedSchemaModel or type.
+
+    Args:
+        schema (ObjectSchema): The schema to convert.
+        context (dict[str, type | Model | NestedSchemaModel]): The context for the conversion.
+
+    Returns:
+        NestedSchemaModel | type: The converted nested schema model or type.
+    """
+def contrib_to_module_root_path(contrib: str) -> Path:
+    """
+    Converts a contrib string to the root path of the module.
+
+    Args:
+        contrib (str): The contrib string to convert.
+
+    Returns:
+        Path: The root path of the module.
+    """
+def map_module_type_to_schema_type(module_type: ModuleTypes) -> SchemaTypes:
+    """
+    Maps a ModuleTypes value to a SchemaTypes value.
+
+    Args:
+        module_type (ModuleTypes): The module type to map.
+
+    Returns:
+        SchemaTypes: The corresponding schema type.
+
+    Raises:
+        ValueError: If the module type is unknown.
+    """

amsdal/mixins/build_mixin.pyi

@@ -5,22 +5,74 @@ from amsdal_models.schemas.loaders.cli_fixtures_loader import CliFixturesLoader
 from pathlib import Path
 
 class CliMultiFixturesLoader(CliFixturesLoader):
+    """
+    Loads multiple fixtures from specified schema directories.
+
+    Attributes:
+        models_with_fixtures (list[tuple[Path, ObjectSchema]]): List of tuples containing the path and object schema
+            of models with fixtures.
+    """
     models_with_fixtures: Incomplete
     def __init__(self, schema_dirs: list[Path]) -> None: ...
 
 class BuildMixin:
+    """
+    Provides methods to build models, transactions, static files, migrations, and fixtures for a CLI application.
+    """
     @classmethod
-    def build_models(cls, user_schemas_path: Path) -> None: ...
-    @staticmethod
-    def build_transactions(cli_app_path: Path) -> None: ...
+    def build_models(cls, user_schemas_path: Path) -> None:
+        """
+        Builds models from the specified user schemas path and predefined schema directories.
+
+        Args:
+            user_schemas_path (Path): The path to the user schemas directory.
+
+        Returns:
+            None
+        """
     @staticmethod
-    def build_static_files(cli_app_path: Path) -> None: ...
+    def build_transactions(cli_app_path: Path) -> None:
+        """
+        Builds transactions from the specified CLI application path.
+
+        Args:
+            cli_app_path (Path): The path to the CLI application directory.
+
+        Returns:
+            None
+        """
     @staticmethod
-    def build_migrations(cli_app_path: Path) -> None: ...
+    def build_static_files(cli_app_path: Path) -> None:
+        """
+        Builds static files from the specified CLI application path.
+
+        Args:
+            cli_app_path (Path): The path to the CLI application directory.
+
+        Returns:
+            None
+        """
     @staticmethod
-    def build_fixtures(cli_app_path: Path) -> None: ...
+    def build_migrations(cli_app_path: Path) -> None:
+        """
+        Builds migrations from the specified CLI application path.
+
+        Args:
+            cli_app_path (Path): The path to the CLI application directory.
+
+        Returns:
+            None
+        """
     @staticmethod
-    def _reimport_models() -> None:
+    def build_fixtures(cli_app_path: Path) -> None:
         """
-        Imports all generated models. Important for cases when models are generated already
+        Builds fixtures from the specified CLI application path.
+
+        Args:
+            cli_app_path (Path): The path to the CLI application directory.
+
+        Returns:
+            None
         """
+    @staticmethod
+    def _reimport_models() -> None: ...

amsdal/mixins/class_versions_mixin.pyi

@@ -2,9 +2,27 @@ from amsdal.migration.utils import object_schema_to_table_schema as object_schem
 from amsdal_models.classes.model import Model
 
 class ClassVersionsMixin:
+    """
+    Mixin class to manage class versions and related table schemas.
+    """
     @classmethod
     def _create_table(cls, class_object: Model, *, skip_class_meta: bool = False) -> None: ...
     @classmethod
-    def init_class_versions(cls, *, create_tables: bool = False) -> None: ...
+    def init_class_versions(cls, *, create_tables: bool = False) -> None:
+        """
+        Initializes class versions and optionally creates tables.
+
+        Args:
+            create_tables (bool, optional): Whether to create tables. Defaults to False.
+
+        Returns:
+            None
+        """
     @staticmethod
-    def register_internal_classes() -> None: ...
+    def register_internal_classes() -> None:
+        """
+        Registers internal classes with the class version manager.
+
+        Returns:
+            None
+        """

amsdal/operations/manager.pyi

@@ -10,15 +10,43 @@ from amsdal_utils.models.data_models.metadata import Metadata as Metadata
 from typing import Any
 
 class OperationsManager(OperationsManagerBase):
+    """
+    Manages operations for models, including state and historical operations.
+    """
     def _get_connections(self, obj: Model, using: str | None) -> list[ConnectionBase]: ...
     def _perform_state_operation(self, obj: Model, data_dump: dict[str, Any], operation: OperationType, connection: StateConnectionBase) -> None: ...
     @classmethod
-    def clear_data(cls, _value: Any) -> Any: ...
+    def clear_data(cls, _value: Any) -> Any:
+        """
+        Clears data by recursively processing dictionaries, lists, and enums.
+
+        Returns:
+            Any: The cleared value.
+        """
     def _is_reference(self, _value: Any) -> bool: ...
     def _perform_historical_operation(self, obj: Model, data_dump: dict[str, Any], operation: OperationType, connection: HistoricalConnectionBase) -> None: ...
     def _preprocess_object(self, obj: Model, operation: OperationType) -> None: ...
-    def perform_operation(self, obj: Model, operation: OperationType, using: str | None = None) -> None: ...
+    def perform_operation(self, obj: Model, operation: OperationType, using: str | None = None) -> None:
+        """
+        Performs the specified operation on the given model object.
+
+        Args:
+            obj (Model): The model object.
+            operation (OperationType): The type of operation to perform.
+            using (str | None, optional): The database alias to use. Defaults to None.
+
+        Returns:
+            None
+        """
     def _generate_references(self, address: Address, data: Any, reference_buffer: list[tuple[Address, dict[str, Any]]]) -> None: ...
     def _perform_historical_bulk_operation(self, objects_data: list[tuple[Model, dict[str, Any]]], operation: OperationType, connection: HistoricalConnectionBase) -> None: ...
     def _perform_state_bulk_operation(self, objects_data: list[tuple[Model, dict[str, Any]]], operation: OperationType, connection: StateConnectionBase) -> None: ...
-    def perform_bulk_operation(self, objs: list[Model], operation: OperationType, using: str | None = None) -> None: ...
+    def perform_bulk_operation(self, objs: list[Model], operation: OperationType, using: str | None = None) -> None:
+        """
+        Performs the specified bulk operation on the given model objects.
+
+        Args:
+            objs (list[Model]): The list of model objects.
+            operation (OperationType): The type of operation to perform.
+            using (str | None, optional): The database alias to use. Defaults to None.
+        """

amsdal/schemas/core/class_object/properties/display_name.py

@@ -1,3 +1,9 @@
 @property  # type: ignore[misc]
 def display_name(self) -> str:  # type: ignore[no-untyped-def]
+    """
+    Returns the display name of the object.
+
+    Returns:
+        str: The display name, which is the title of the object.
+    """
     return self.title

amsdal/schemas/core/file/hooks/pre_create.py

@@ -1,2 +1,11 @@
 def pre_create(self) -> None:  # type: ignore[no-untyped-def]
+    """
+    Prepares the object for creation by setting its size attribute.
+
+    This method calculates the size of the object's data and assigns it to the size attribute.
+    If the data is None, it defaults to an empty byte string.
+
+    Args:
+        None
+    """
     self.size = len(self.data or b'')

amsdal/schemas/core/file/hooks/pre_update.py

@@ -1,2 +1,11 @@
 def pre_update(self):  # type: ignore[no-untyped-def]
+    """
+    Prepares the object for update by setting its size attribute.
+
+    This method calculates the size of the object's data and assigns it to the size attribute.
+    If the data is None, it defaults to an empty byte string.
+
+    Args:
+        None
+    """
     self.size = len(self.data or b'')

amsdal/schemas/core/file/properties/from_file.py

@@ -7,6 +7,18 @@ def from_file(
     cls,
     file_or_path: Path | BinaryIO,
 ) -> 'File':  # type: ignore[name-defined]  # noqa: F821
+    """
+    Creates a `File` object from a file path or a binary file object.
+
+    Args:
+        file_or_path (Path | BinaryIO): The file path or binary file object.
+
+    Returns:
+        File: The created `File` object.
+
+    Raises:
+        ValueError: If the provided path is a directory.
+    """
     if isinstance(file_or_path, Path):
         if file_or_path.is_dir():
             msg = f'{file_or_path} is a directory'

amsdal/schemas/core/file/properties/mimetype.py

@@ -1,5 +1,13 @@
 @property  # type: ignore[misc]
 def mimetype(self) -> str | None:  # type: ignore[no-untyped-def]
+    """
+    Returns the MIME type of the file based on its filename.
+
+    This method uses the `mimetypes` module to guess the MIME type of the file.
+
+    Returns:
+        str | None: The guessed MIME type of the file, or None if it cannot be determined.
+    """
     import mimetypes
 
     return mimetypes.guess_type(self.filename)[0]

amsdal/schemas/core/file/properties/to_file.py

@@ -3,6 +3,18 @@ from typing import BinaryIO
 
 
 def to_file(self, file_or_path: Path | BinaryIO) -> None:  # type: ignore[no-untyped-def]
+    """
+    Writes the object's data to a file path or a binary file object.
+
+    Args:
+        file_or_path (Path | BinaryIO): The file path or binary file object where the data will be written.
+
+    Returns:
+        None
+
+    Raises:
+        ValueError: If the provided path is a directory.
+    """
     if isinstance(file_or_path, Path):
         if file_or_path.is_dir():
             file_or_path = file_or_path / self.name

amsdal/schemas/core/file/properties/validate_data.py

@@ -6,6 +6,19 @@ from pydantic import field_validator
 @field_validator('data')  # type: ignore[misc]
 @classmethod
 def data_base64_decode(cls, v: bytes) -> bytes:  # type: ignore[no-untyped-def]  # noqa: ARG001
+    """
+    Decodes a base64-encoded byte string if it is base64-encoded.
+
+    This method checks if the provided byte string is base64-encoded and decodes it if true.
+    If the byte string is not base64-encoded, it returns the original byte string.
+
+    Args:
+        cls: The class this method belongs to.
+        v (bytes): The byte string to be checked and potentially decoded.
+
+    Returns:
+        bytes: The decoded byte string if it was base64-encoded, otherwise the original byte string.
+    """
     is_base64: bool = False
 
     try:

amsdal/schemas/manager.py

@@ -8,13 +8,39 @@ from amsdal.configs.main import settings
 
 
 class SchemaManager(metaclass=Singleton):
+    """
+    Manages schema operations including retrieval, invalidation, and sorting.
+
+    This class handles various schema-related operations such as invalidating user schemas,
+    retrieving schemas by name or type, and sorting schemas based on predefined rules.
+    """
+
     def __init__(self) -> None:
         self._schema_manager_handler = SchemaManagerHandler(settings.schemas_root_path)
 
     def invalidate_user_schemas(self) -> None:
+        """
+        Invalidates user schemas.
+
+        This method calls the handler to invalidate all user schemas, ensuring that any cached or outdated schemas
+            are refreshed.
+
+        Returns:
+            None
+        """
         self._schema_manager_handler.invalidate_user_schemas()
 
     def class_schemas(self) -> list[tuple[ObjectSchema, SchemaTypes]]:
+        """
+        Returns a list of tuples containing object schemas and their types.
+
+        This method retrieves and sorts various schemas managed by the schema manager handler.
+        The schemas are categorized into types, core, user, and contrib schemas.
+
+        Returns:
+            list[tuple[ObjectSchema, SchemaTypes]]: A list of tuples where each tuple contains an object schema
+                and its corresponding type.
+        """
         return (
             [
                 (type_schema, SchemaTypes.TYPE)
@@ -41,6 +67,19 @@ class SchemaManager(metaclass=Singleton):
             return 2
 
     def get_schema_by_name(self, title: str, schema_type: SchemaTypes | None = None) -> ObjectSchema | None:
+        """
+        Retrieves a schema by its title and optional type.
+
+        This method searches for a schema with the specified title and optional type
+        among the schemas managed by the schema manager handler.
+
+        Args:
+            title (str): The title of the schema to be retrieved.
+            schema_type (SchemaTypes | None, optional): The type of the schema to be retrieved. Defaults to None.
+
+        Returns:
+            ObjectSchema | None: The schema with the specified title and type, or None if not found.
+        """
         _schemas = self.get_schemas(schema_type)
 
         for schema in _schemas:
@@ -50,6 +89,18 @@ class SchemaManager(metaclass=Singleton):
         return None
 
     def get_schemas(self, schema_type: SchemaTypes | None = None) -> list[ObjectSchema]:
+        """
+        Retrieves schemas based on the provided type.
+
+        This method returns a list of schemas filtered by the specified type. If no type is provided,
+        it returns all schemas managed by the schema manager handler.
+
+        Args:
+            schema_type (SchemaTypes | None, optional): The type of schemas to retrieve. Defaults to None.
+
+        Returns:
+            list[ObjectSchema]: A list of schemas filtered by the specified type, or all schemas if no type is provided.
+        """
         if schema_type == SchemaTypes.CONTRIB:
             return self._schema_manager_handler.contrib_schemas