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

amsdal/contrib/frontend_configs/models/frontent_config_control_action/properties/action_validate.py

@@ -4,6 +4,22 @@ from pydantic import field_validator
 @field_validator('action', mode='after')  # type: ignore[misc]
 @classmethod
 def validate_action(cls, v: str) -> str:  # type: ignore[no-untyped-def] # noqa: ARG001
+    """
+    Validates the action string to ensure it is one of the allowed values.
+
+    This method checks if the action string starts with 'navigate::' or is one of the predefined
+    actions. If the action string is invalid, it raises a ValueError.
+
+    Args:
+        cls: The class this method is attached to.
+        v (str): The action string to validate.
+
+    Returns:
+        str: The validated action string.
+
+    Raises:
+        ValueError: If the action string is not valid.
+    """
     if not v.startswith('navigate::') and v not in [
         'goPrev',
         'goNext',

amsdal/contrib/frontend_configs/utils.py

@@ -3,7 +3,18 @@ from typing import Any
 
 def merge_ui_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
     """
-    Merge two UI configs together. The override config will take precedence over the base config.
+    Merges two UI configs together. The override config will take precedence over the base config.
+
+    This function recursively merges two dictionaries representing UI configurations.
+    If a key exists in both dictionaries, the value from the override dictionary will be used.
+    If the value is a dictionary or a list, the function will merge them recursively.
+
+    Args:
+        base (dict[str, Any]): The base UI configuration dictionary.
+        override (dict[str, Any]): The override UI configuration dictionary.
+
+    Returns:
+        dict[str, Any]: The merged UI configuration dictionary.
     """
     for key, value in override.items():
         if key not in base:

amsdal/contrib/frontend_configs/utils.pyi

@@ -2,5 +2,16 @@ from typing import Any
 
 def merge_ui_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
     """
-    Merge two UI configs together. The override config will take precedence over the base config.
+    Merges two UI configs together. The override config will take precedence over the base config.
+
+    This function recursively merges two dictionaries representing UI configurations.
+    If a key exists in both dictionaries, the value from the override dictionary will be used.
+    If the value is a dictionary or a list, the function will merge them recursively.
+
+    Args:
+        base (dict[str, Any]): The base UI configuration dictionary.
+        override (dict[str, Any]): The override UI configuration dictionary.
+
+    Returns:
+        dict[str, Any]: The merged UI configuration dictionary.
     """

amsdal/fixtures/manager.pyi

@@ -16,6 +16,13 @@ class FixtureData(BaseModel):
     data: dict[str, Any]
 
 class FixturesManager:
+    """
+    Manager class for handling fixture data.
+
+    This class is responsible for loading, processing, and applying fixture data
+    to the database. It supports nested object construction, data processing,
+    and file fixture handling.
+    """
     fixtures_path: Incomplete
     fixtures: Incomplete
     _created_cache: Incomplete
@@ -24,13 +31,88 @@ class FixturesManager:
     _config_manager: Incomplete
     _schema_manager: Incomplete
     def __init__(self, fixtures_path: Path, class_manager: ClassManager, config_manager: AmsdalConfigManager, schema_manager: SchemaManager) -> None: ...
-    def load_fixtures(self) -> None: ...
-    def construct_nested_object(self, external_id: Any) -> Any: ...
+    def load_fixtures(self) -> None:
+        """
+        Loads fixture data from the specified path.
+
+        This method reads fixture data from a JSON file located at the `fixtures_path`.
+        It populates the `fixtures` dictionary with the loaded data, where each fixture
+        is indexed by its external ID.
+
+        Returns:
+            None
+        """
+    def construct_nested_object(self, external_id: Any) -> Any:
+        """
+        Constructs a nested object reference from the given external ID.
+
+        This method takes an external ID and constructs a nested object reference
+        dictionary. If the external ID is a dictionary containing an '_object_id' key,
+        it extracts the ID. If the external ID is not a string or integer, it returns
+        the external ID as is.
+
+        Args:
+            external_id (Any): The external ID to construct the nested object reference from.
+
+        Returns:
+            Any: A dictionary representing the nested object reference or the original
+            external ID if it is not a string or integer.
+        """
     def _process_object_data(self, model_properties: dict[str, PropertyData], data: dict[str, Any]) -> dict[str, Any]: ...
     def _process_object_value(self, field_configuration: PropertyData | DictSchema | TypeData, value: Any) -> Any: ...
-    def process_fixture_object_data(self, class_name: str, external_id: str, data: dict[str, Any]) -> None: ...
-    def process_fixture(self, fixture: dict[str, Any]) -> None: ...
-    def apply_fixtures(self) -> None: ...
+    def process_fixture_object_data(self, class_name: str, external_id: str, data: dict[str, Any]) -> None:
+        """
+        Processes and saves fixture object data to the database.
+
+        This method takes the class name, external ID, and data dictionary of a fixture object,
+        processes the data according to the class schema, and saves the object to the database.
+        If the object already exists, it updates the existing object with the new data.
+
+        Args:
+            class_name (str): The name of the class to which the fixture object belongs.
+            external_id (str): The external ID of the fixture object.
+            data (dict[str, Any]): The data dictionary of the fixture object.
+
+        Returns:
+            None
+        """
+    def process_fixture(self, fixture: dict[str, Any]) -> None:
+        """
+        Processes a single fixture and adds it to the processing queue.
+
+        This method takes a fixture dictionary, checks if the fixture already exists in the database,
+        and either updates the existing fixture or creates a new one. It then adds the fixture data
+        to the processing queue for further processing.
+
+        Args:
+            fixture (dict[str, Any]): The fixture dictionary containing the external ID, class name,
+            and data of the fixture.
+
+        Returns:
+            None
+        """
+    def apply_fixtures(self) -> None:
+        """
+        Applies all loaded fixtures to the database.
+
+        This method processes each fixture in the `fixtures` dictionary in the order
+        specified by their 'order' value. It calls the `process_fixture` method for
+        each fixture and then processes the data in the processing queue.
+
+        Returns:
+            None
+        """
     def _process_data(self) -> None: ...
-    def apply_file_fixtures(self) -> None: ...
+    def apply_file_fixtures(self) -> None:
+        """
+        Applies file fixtures from the specified directory.
+
+        This method processes file fixtures located in the 'files' directory adjacent to the
+        `fixtures_path`. It iterates through each file, reads its content, and processes it
+        as a fixture. If the file fixture already exists in the database, it updates the
+        existing fixture; otherwise, it creates a new one.
+
+        Returns:
+            None
+        """
     def _process_file_fixture(self, file_path: Path, file_key: str) -> None: ...

amsdal/manager.pyi

@@ -15,6 +15,13 @@ from amsdal_utils.utils.singleton import Singleton
 from pathlib import Path
 
 class AmsdalManager(BuildMixin, ClassVersionsMixin, metaclass=Singleton):
+    """
+    Manages the AMSDAL framework components and operations.
+
+    This class is responsible for initializing, setting up, and managing various components
+    of the AMSDAL framework, including connections, data management, schema management,
+    and authentication. It also provides methods for building and tearing down the framework.
+    """
     _class_manager: ClassManager
     _config_manager: Incomplete
     _connections_manager: Incomplete
@@ -28,68 +35,157 @@ class AmsdalManager(BuildMixin, ClassVersionsMixin, metaclass=Singleton):
     def __init__(self, *, raise_on_new_signup: bool = False) -> None:
         """
         Initializes all sub managers. Reads the configuration.
+
+        Returns:
+            None
         """
     @property
     def is_setup(self) -> bool: ...
     @property
     def is_authenticated(self) -> bool:
         """
-        Indicates if you have passed the AMSDAL license authentication process.
+        Indicates if the AMSDAL license authentication process has been passed.
+
+        This property returns a boolean value indicating whether the AMSDAL license
+        authentication process has been successfully completed.
+
+        Returns:
+            bool: True if authenticated, False otherwise.
         """
     def pre_setup(self) -> None:
         """
-        Initiates models root path and adds it into sys.path
+        Initiates models root path and adds it into sys.path.
+
+        This method initializes the class manager and sets up the models root path
+        as specified in the settings. It ensures that the models root path is added
+        to the system path for proper module resolution.
+
+        Returns:
+            None
         """
     def setup(self) -> None:
         """
-        Initiates models root path and the connections
+        Initiates models root path and the connections.
+
+        This method sets up the AMSDAL framework by initializing the models root path and
+        establishing connections. It ensures that the setup process is only performed once.
+
+        Raises:
+            AmsdalRuntimeError: If the AMSDAL manager is already set up.
+
+        Returns:
+            None
         """
     def build(self, source_models_path: Path, source_transactions_path: Path, source_static_files_path: Path, source_fixtures_path: Path, source_migrations_path: Path) -> None:
         """
-        Build method
-
-        :param source_models_path: Path to the directory where the source models are located.
-        :param source_transactions_path: Path to the directory where the source transactions are located.
-        :param source_static_files_path: Path to the directory where the source static files are located.
-        :param source_fixtures_path: Path to the directory where the source fixtures are located.
-        :param source_migrations_path: Path to the directory where the source migrations are located.
-        :return: None
+        Builds the necessary components for the Amsdal framework.
 
         This method is used to build the necessary components for the Amsdal framework.
-        It takes four parameters which are all of type `Path`.
+        It takes five parameters which are all of type `Path`.
         These parameters represent the paths to the directories where the corresponding components are located.
 
+        Args:
+            source_models_path (Path): Path to the directory where the source models are located.
+            source_transactions_path (Path): Path to the directory where the source transactions are located.
+            source_static_files_path (Path): Path to the directory where the source static files are located.
+            source_fixtures_path (Path): Path to the directory where the source fixtures are located.
+            source_migrations_path (Path): Path to the directory where the source migrations are located.
+
+        Returns:
+            None
+
         The method performs the following build steps in order:
         - Builds the models from the `source_models_path` by calling the `build_models` method.
         - Builds the transactions from the `source_transactions_path` by calling the `build_transactions` method.
         - Builds the static files from the `source_static_files_path` by calling the `build_static_files` method.
         - Builds the fixtures from the `source_fixtures_path` by calling the `build_fixtures` method.
 
-        Note: This method is part of the `AmsdalManager` class which includes mixins for `BuildMixin`
-        and `ClassVersionsMixin`. It is intended to be used in the Amsdal framework for managing
-        and building components.
+        Note:
+            This method is part of the `AmsdalManager` class which includes mixins for `BuildMixin`
+            and `ClassVersionsMixin`. It is intended to be used in the Amsdal framework for managing
+            and building components.
         """
     def post_setup(self) -> None:
         """
         Registers internal classes and prepares connections (creates internal tables).
+
+        This method registers the internal classes required by the AMSDAL framework and
+        prepares the connections by creating the necessary internal tables.
+
+        Returns:
+            None
         """
     def migrate(self) -> None:
         """
         DEPRECATED: Check changes in the models and apply them to the database.
+
+        This method is deprecated and should not be used. It checks for changes in the models
+        and applies them to the database. Use `amsdal.migration.file_migration_generator.FileMigrationGenerator`
+            instead.
+
+        Raises:
+            DeprecationWarning: Always raised to indicate that this method is deprecated.
+
+        Returns:
+            None
         """
     def _check_auth(self) -> None: ...
     @property
-    def cloud_actions_manager(self) -> CloudActionsManager: ...
+    def cloud_actions_manager(self) -> CloudActionsManager:
+        """
+        Provides access to the CloudActionsManager.
+
+        This property checks if the AMSDAL manager is authenticated and then returns
+        an instance of the CloudActionsManager.
+
+        Returns:
+            CloudActionsManager: An instance of the CloudActionsManager.
+
+        Raises:
+            AmsdalAuthenticationError: If the AMSDAL manager is not authenticated.
+        """
     def authenticate(self) -> None:
         """
         Run AMSDAL license authentication process.
+
+        This method runs the AMSDAL license authentication process and sets the
+        authentication status accordingly.
+
+        Returns:
+            None
         """
     def apply_fixtures(self) -> None:
         """
         Loads and applies fixtures defined in your application.
+
+        This method loads the fixtures from the specified path and applies them to the
+        AMSDAL framework. It uses the `FixturesManager` to manage the loading and application
+        of the fixtures.
+
+        Returns:
+            None
+        """
+    def init_classes(self) -> None:
+        """
+        Initializes and imports classes based on the schema manager's class schemas.
+
+        This method iterates over the class schemas provided by the schema manager and imports
+        the classes into the class manager, excluding those of type `SchemaTypes.TYPE`.
+
+        Returns:
+            None
         """
-    def init_classes(self) -> None: ...
     def teardown(self) -> None:
         """
         Clean up everything on the application exit.
+
+        This method performs a cleanup of all components managed by the AMSDAL framework
+        when the application exits. It disconnects and invalidates connections, clears caches,
+        and resets the setup status.
+
+        Raises:
+            AmsdalRuntimeError: If the AMSDAL manager is not set up.
+
+        Returns:
+            None
         """

amsdal/migration/base_migration_schemas.pyi

@@ -9,11 +9,27 @@ from amsdal_utils.models.enums import SchemaTypes as SchemaTypes, Versions
 from pathlib import Path
 
 class BaseMigrationSchemas(ABC, metaclass=abc.ABCMeta):
+    """
+    Abstract base class for migration schemas.
+
+    This class provides the interface for managing and compiling database schema migrations.
+    It includes methods for registering, unregistering, and compiling classes, as well as
+    managing class versions.
+    """
     _classes: Incomplete
     _classes_versions: Incomplete
     _buffered_classes: Incomplete
     def __init__(self) -> None: ...
-    def get_model(self, name: str) -> type[Model]: ...
+    def get_model(self, name: str) -> type[Model]:
+        """
+        Retrieves the model type for the given class name.
+
+        Args:
+            name (str): The name of the class whose model type is to be retrieved.
+
+        Returns:
+            type[Model]: The model type associated with the given class name.
+        """
     @abstractmethod
     def register_model(self, class_name: str, object_schema: ObjectSchema, schema_type: SchemaTypes) -> None: ...
     @abstractmethod
@@ -21,16 +37,76 @@ class BaseMigrationSchemas(ABC, metaclass=abc.ABCMeta):
     @abstractmethod
     def compile_buffered_classes(self) -> None: ...
     @staticmethod
-    def register_model_version(class_name: str, class_version: str | Versions) -> None: ...
+    def register_model_version(class_name: str, class_version: str | Versions) -> None:
+        """
+        Registers a specific version of a model class.
+
+        This method registers a specific version of a model class using the ClassVersionManager.
+
+        Args:
+            class_name (str): The name of the class to register the version for.
+            class_version (str | Versions): The version of the class to be registered.
+
+        Returns:
+            None
+        """
 
 class DefaultMigrationSchemas(BaseMigrationSchemas):
+    """
+    Default implementation of the BaseMigrationSchemas.
+
+    This class provides the default implementation for managing and compiling database schema migrations.
+    It includes methods for registering, unregistering, and compiling classes, as well as managing class versions.
+
+    Attributes:
+        model_class_template_layout (Path): Path to the model class layout template.
+        model_class_template (Path): Path to the model class template.
+        dict_validator_template (Path): Path to the dictionary validator template.
+        options_validator_template (Path): Path to the options validator template.
+    """
     model_class_template_layout: Path
     model_class_template: Path
     dict_validator_template: Path
     options_validator_template: Path
-    def register_model(self, class_name: str, object_schema: ObjectSchema, schema_type: SchemaTypes) -> None: ...
-    def compile_buffered_classes(self) -> None: ...
-    def unregister_model(self, class_name: str) -> None: ...
+    def register_model(self, class_name: str, object_schema: ObjectSchema, schema_type: SchemaTypes) -> None:
+        """
+        Registers a model class for migration.
+
+        This method registers a model class for migration by adding it to the buffered classes
+        and registering its latest version.
+
+        Args:
+            class_name (str): The name of the class to be registered.
+            object_schema (ObjectSchema): The schema of the object to be registered.
+            schema_type (SchemaTypes): The type of the schema.
+
+        Returns:
+            None
+        """
+    def compile_buffered_classes(self) -> None:
+        """
+        Compiles all buffered classes for migration.
+
+        This method compiles all classes that have been buffered for migration and updates the
+        internal class dictionary with the compiled class types. It clears the buffer after
+        compilation.
+
+        Returns:
+            None
+        """
+    def unregister_model(self, class_name: str) -> None:
+        """
+        Unregisters a model class from the migration schemas.
+
+        This method removes the specified model class from the internal class dictionary,
+        effectively unregistering it from the migration schemas.
+
+        Args:
+            class_name (str): The name of the class to be unregistered.
+
+        Returns:
+            None
+        """
     def _compile_buffered_classes(self) -> list[tuple[str, type[Model]]]: ...
     def _build_class_source(self, class_name: str, schema: ObjectSchema, schema_type: SchemaTypes) -> tuple[str, str]: ...
     @staticmethod

amsdal/migration/data_classes.pyi

@@ -7,36 +7,85 @@ from enum import Enum
 from pathlib import Path
 
 class Action(str, Enum):
+    """
+    Enumeration for different types of actions.
+
+    Attributes:
+        CREATED (str): Represents a created action.
+        UPDATED (str): Represents an updated action.
+        NO_ACTION (str): Represents no action.
+    """
     CREATED = 'CREATED'
     UPDATED = 'UPDATED'
     NO_ACTION = 'NO_ACTION'
 
 @dataclass
 class ClassSaveResult:
+    """
+    Data class representing the result of a class save operation.
+
+    Attributes:
+        action (Action): The action performed during the save operation.
+        instance (Model): The instance of the model that was saved.
+    """
     action: Action
     instance: Model
     def __init__(self, action, instance) -> None: ...
 
 @dataclass
 class ClassUpdateResult:
+    """
+    Data class representing the result of a class update operation.
+
+    Attributes:
+        is_updated (bool): Indicates whether the class was updated.
+        class_instance (Model): The instance of the model that was updated.
+    """
     is_updated: bool
     class_instance: Model
     def __init__(self, is_updated, class_instance) -> None: ...
 
 @dataclass
 class MigrateResult:
+    """
+    Data class representing the result of a migration operation.
+
+    Attributes:
+        class_instance (Model): The instance of the model that was migrated.
+        is_table_created (bool): Indicates whether the table was created during the migration.
+        is_data_migrated (bool): Indicates whether the data was migrated.
+    """
     class_instance: Model
     is_table_created: bool
     is_data_migrated: bool
     def __init__(self, class_instance, is_table_created, is_data_migrated) -> None: ...
 
 class ModuleTypes(str, Enum):
+    """
+    Enumeration for different types of modules.
+
+    Attributes:
+        APP (str): Represents an application module.
+        CORE (str): Represents a core module.
+        CONTRIB (str): Represents a contributed module.
+    """
     APP = 'APP'
     CORE = 'CORE'
     CONTRIB = 'CONTRIB'
 
 @dataclass
 class MigrationFile:
+    """
+    Data class representing a migration file.
+
+    Attributes:
+        path (Path): The file path of the migration.
+        type (ModuleTypes): The type of module the migration belongs to.
+        number (int): The migration number.
+        module (str | None): The module name, if applicable.
+        applied_at (float | None): The timestamp when the migration was applied.
+        stored_address (Address | None): The stored address associated with the migration.
+    """
     path: Path
     type: ModuleTypes
     number: int
@@ -44,22 +93,53 @@ class MigrationFile:
     applied_at: float | None = ...
     stored_address: Address | None = ...
     @property
-    def is_initial(self) -> bool: ...
+    def is_initial(self) -> bool:
+        """
+        Indicates whether this migration is the initial migration.
+
+        Returns:
+            bool: True if this is the initial migration, False otherwise.
+        """
     def __init__(self, path, type, number, module=..., applied_at=..., stored_address=...) -> None: ...
 
 @dataclass
 class ClassSchema:
+    """
+    Data class representing a class schema.
+
+    Attributes:
+        object_schema (ObjectSchema): The object schema associated with the class.
+        type (ModuleTypes): The type of module the class belongs to.
+    """
     object_schema: ObjectSchema
     type: ModuleTypes
     def __init__(self, object_schema, type) -> None: ...
 
 class OperationTypes(str, Enum):
+    """
+    Enumeration for different types of operations.
+
+    Attributes:
+        CREATE_CLASS (str): Represents the operation to create a class.
+        UPDATE_CLASS (str): Represents the operation to update a class.
+        DELETE_CLASS (str): Represents the operation to delete a class.
+    """
     CREATE_CLASS = 'CREATE_CLASS'
     UPDATE_CLASS = 'UPDATE_CLASS'
     DELETE_CLASS = 'DELETE_CLASS'
 
 @dataclass
 class MigrateOperation:
+    """
+    Data class representing a migration operation.
+
+    Attributes:
+        type (OperationTypes): The type of operation being performed.
+        class_name (str): The name of the class involved in the migration.
+        schema_type (SchemaTypes): The type of schema associated with the migration.
+        old_schema (ObjectSchema | PropertyData | None): The old schema before the migration, if applicable.
+        new_schema (ObjectSchema | PropertyData | None): The new schema after the migration, if applicable.
+    """
     type: OperationTypes
     class_name: str
     schema_type: SchemaTypes
@@ -68,11 +148,25 @@ class MigrateOperation:
     def __init__(self, type, class_name, schema_type, old_schema=..., new_schema=...) -> None: ...
 
 class MigrationDirection(str, Enum):
+    """
+    Enumeration for the direction of a migration.
+
+    Attributes:
+        FORWARD (str): Represents a forward migration.
+        BACKWARD (str): Represents a backward migration.
+    """
     FORWARD = 'forward'
     BACKWARD = 'backward'
 
 @dataclass
 class MigrationResult:
+    """
+    Data class representing the result of a migration.
+
+    Attributes:
+        direction (MigrationDirection): The direction of the migration.
+        migration (MigrationFile): The migration file associated with the migration.
+    """
     direction: MigrationDirection
     migration: MigrationFile
     def __init__(self, direction, migration) -> None: ...