amsdal 0.1.26__cp311-cp311-macosx_10_9_universal2.whl → 0.2.0__cp311-cp311-macosx_10_9_universal2.whl

amsdal/context/manager.pyi

@@ -4,9 +4,47 @@ from typing import Any
 _CONTEXT: ContextVar[dict[str, Any] | None]
 
 class AmsdalContextManager:
+    """
+    Manages a context for storing and retrieving data.
+
+    This class provides methods to get, set, and add to a context stored in a
+    `ContextVar`. The context is a dictionary that can hold any key-value pairs.
+    """
     @classmethod
-    def get_context(cls) -> dict[str, Any]: ...
+    def get_context(cls) -> dict[str, Any]:
+        """
+        Retrieves the current context or creates a new one if none exists.
+
+        This method gets the current context from the `_CONTEXT` variable. If no
+        context exists, it creates a new empty context and sets it.
+
+        Returns:
+            dict[str, Any]: The current context.
+        """
     @classmethod
-    def set_context(cls, context: dict[str, Any]) -> None: ...
+    def set_context(cls, context: dict[str, Any]) -> None:
+        """
+        Sets the context to the provided dictionary.
+
+        This method sets the `_CONTEXT` variable to the provided context.
+
+        Args:
+            context (dict[str, Any]): The context to set.
+
+        Returns:
+            None
+        """
     @classmethod
-    def add_to_context(cls, key: str, value: Any) -> None: ...
+    def add_to_context(cls, key: str, value: Any) -> None:
+        """
+        Adds a key-value pair to the current context.
+
+        This method adds the provided key-value pair to the current context.
+
+        Args:
+            key (str): The key to add to the context.
+            value (Any): The value to associate with the key.
+
+        Returns:
+            None
+        """

amsdal/contrib/auth/app.py

@@ -5,7 +5,19 @@ from amsdal.contrib.app_config import AppConfig
 
 
 class AuthAppConfig(AppConfig):
+    """
+    Configuration class for the authentication application.
+
+    This class sets up the necessary listeners for various lifecycle events
+    related to authentication and permission checks.
+    """
+
     def on_ready(self) -> None:
+        """
+        Sets up listeners for various lifecycle events.
+
+        This method adds listeners for server startup, user authentication, and permission checks.
+        """
         from amsdal.contrib.auth.lifecycle.consumer import AuthenticateUserConsumer
         from amsdal.contrib.auth.lifecycle.consumer import CheckAndCreateSuperUserConsumer
         from amsdal.contrib.auth.lifecycle.consumer import CheckPermissionConsumer

amsdal/contrib/auth/app.pyi

@@ -1,4 +1,15 @@
 from amsdal.contrib.app_config import AppConfig as AppConfig
 
 class AuthAppConfig(AppConfig):
-    def on_ready(self) -> None: ...
+    """
+    Configuration class for the authentication application.
+
+    This class sets up the necessary listeners for various lifecycle events
+    related to authentication and permission checks.
+    """
+    def on_ready(self) -> None:
+        """
+        Sets up listeners for various lifecycle events.
+
+        This method adds listeners for server startup, user authentication, and permission checks.
+        """

amsdal/contrib/auth/lifecycle/consumer.py

@@ -15,8 +15,22 @@ logger = logging.getLogger(__name__)
 
 
 class CheckAndCreateSuperUserConsumer(LifecycleConsumer):
+    """
+    Ensures the existence of a super user in the system.
+
+    This consumer checks if a super user exists based on the provided email and password
+    in the authentication settings. If the super user does not exist, it creates one.
+    """
+
     @transaction
     def on_event(self) -> None:
+        """
+        Checks for the existence of a super user and creates one if necessary.
+
+        This method ensures that a super user exists by checking the email and password
+        in the authentication settings. If the super user does not exist, it creates one
+        with the necessary permissions.
+        """
         from amsdal.contrib.auth.settings import auth_settings
         from models.contrib.permission import Permission  # type: ignore[import-not-found]
         from models.contrib.user import User  # type: ignore[import-not-found]
@@ -58,7 +72,26 @@ class CheckAndCreateSuperUserConsumer(LifecycleConsumer):
 
 
 class AuthenticateUserConsumer(LifecycleConsumer):
+    """
+    Authenticates a user based on a provided JWT token.
+
+    This consumer decodes the JWT token from the authorization header and retrieves
+    the corresponding user from the database. If the token is invalid or expired,
+    it raises an `AuthenticationError`.
+    """
+
     def on_event(self, auth_header: str, authentication_info: Any) -> None:
+        """
+        Authenticates the user using the provided JWT token.
+
+        This method decodes the JWT token from the authorization header and retrieves
+        the corresponding user from the database. If the token is invalid or expired,
+        it raises an `AuthenticationError`.
+
+        Args:
+            auth_header (str): The JWT token from the authorization header.
+            authentication_info (Any): The authentication information object to update with the user.
+        """
         from amsdal.contrib.auth.settings import auth_settings
         from models.contrib.user import User  # type: ignore[import-not-found]
 
@@ -89,6 +122,13 @@ class AuthenticateUserConsumer(LifecycleConsumer):
 
 
 class CheckPermissionConsumer(LifecycleConsumer):
+    """
+    Checks and manages permissions for a given user and object.
+
+    This consumer prepopulates default permissions, checks class-level permissions,
+    and object-level permissions for a given user and object.
+    """
+
     def _prepopulate_default_permissions(self, object_class: type[Model], permissions_info: Any) -> None:
         from amsdal.contrib.auth.settings import auth_settings
         from models.contrib.permission import Permission  # type: ignore[import-not-found]
@@ -160,6 +200,19 @@ class CheckPermissionConsumer(LifecycleConsumer):
         permissions_info: Any,
         obj: Model | None = None,
     ) -> None:
+        """
+        Main method to check permissions for a given user and object.
+
+        This method prepopulates default permissions, checks class-level permissions,
+        and object-level permissions for the given user and object.
+
+        Args:
+            object_class (type[Model]): The class of the object to check permissions for.
+            user (Any): The user to check permissions for.
+            access_types (list[Any]): The list of access types to check.
+            permissions_info (Any): The permissions information object to update.
+            obj (Model | None): The object to check permissions for, if any.
+        """
         self._prepopulate_default_permissions(object_class, permissions_info)
         self._check_class_permissions(object_class, user, permissions_info)
 

amsdal/contrib/auth/lifecycle/consumer.pyi

@@ -7,13 +7,63 @@ from typing import Any
 logger: Incomplete
 
 class CheckAndCreateSuperUserConsumer(LifecycleConsumer):
-    def on_event(self) -> None: ...
+    """
+    Ensures the existence of a super user in the system.
+
+    This consumer checks if a super user exists based on the provided email and password
+    in the authentication settings. If the super user does not exist, it creates one.
+    """
+    def on_event(self) -> None:
+        """
+        Checks for the existence of a super user and creates one if necessary.
+
+        This method ensures that a super user exists by checking the email and password
+        in the authentication settings. If the super user does not exist, it creates one
+        with the necessary permissions.
+        """
 
 class AuthenticateUserConsumer(LifecycleConsumer):
-    def on_event(self, auth_header: str, authentication_info: Any) -> None: ...
+    """
+    Authenticates a user based on a provided JWT token.
+
+    This consumer decodes the JWT token from the authorization header and retrieves
+    the corresponding user from the database. If the token is invalid or expired,
+    it raises an `AuthenticationError`.
+    """
+    def on_event(self, auth_header: str, authentication_info: Any) -> None:
+        """
+        Authenticates the user using the provided JWT token.
+
+        This method decodes the JWT token from the authorization header and retrieves
+        the corresponding user from the database. If the token is invalid or expired,
+        it raises an `AuthenticationError`.
+
+        Args:
+            auth_header (str): The JWT token from the authorization header.
+            authentication_info (Any): The authentication information object to update with the user.
+        """
 
 class CheckPermissionConsumer(LifecycleConsumer):
+    """
+    Checks and manages permissions for a given user and object.
+
+    This consumer prepopulates default permissions, checks class-level permissions,
+    and object-level permissions for a given user and object.
+    """
     def _prepopulate_default_permissions(self, object_class: type[Model], permissions_info: Any) -> None: ...
     def _check_class_permissions(self, object_class: type[Model], user: Any, permissions_info: Any) -> None: ...
     def _check_object_permissions(self, obj: Model, user: Any, permissions_info: Any) -> None: ...
-    def on_event(self, object_class: type[Model], user: Any, access_types: list[Any], permissions_info: Any, obj: Model | None = None) -> None: ...
+    def on_event(self, object_class: type[Model], user: Any, access_types: list[Any], permissions_info: Any, obj: Model | None = None) -> None:
+        """
+        Main method to check permissions for a given user and object.
+
+        This method prepopulates default permissions, checks class-level permissions,
+        and object-level permissions for the given user and object.
+
+        Args:
+            object_class (type[Model]): The class of the object to check permissions for.
+            user (Any): The user to check permissions for.
+            access_types (list[Any]): The list of access types to check.
+            permissions_info (Any): The permissions information object to update.
+            obj (Model | None): The object to check permissions for, if any.
+        """

amsdal/contrib/auth/models/login_session/hooks/pre_init.py

@@ -9,6 +9,19 @@ from amsdal_utils.models.enums import Versions
 
 
 def pre_init(self, *, is_new_object: bool, kwargs: dict[str, Any]) -> None:  # type: ignore[no-untyped-def]  # noqa: ARG001
+    """
+    Pre-initializes a user object by validating email and password, and generating a JWT token.
+
+    This method checks if the object is new and validates the provided email and password.
+    If the email and password are valid, it generates a JWT token and adds it to the kwargs.
+
+    Args:
+        is_new_object (bool): Indicates if the object is new.
+        kwargs (dict[str, Any]): The keyword arguments containing user details.
+
+    Raises:
+        AuthenticationError: If the email or password is invalid.
+    """
     if not is_new_object or '_metadata' in kwargs:
         return
 

amsdal/contrib/auth/models/login_session/modifiers/display_name.py

@@ -1,3 +1,11 @@
 @property  # type: ignore[misc]
 def display_name(self) -> str:  # type: ignore[no-untyped-def]
+    """
+    Returns the display name of the user.
+
+    This method returns the email of the user as their display name.
+
+    Returns:
+        str: The email of the user.
+    """
     return self.email

amsdal/contrib/auth/models/permission/modifiers/display_name.py

@@ -1,3 +1,11 @@
 @property  # type: ignore[misc]
 def display_name(self) -> str:  # type: ignore[no-untyped-def]
+    """
+    Returns the display name of the user.
+
+    This method returns a formatted string combining the model and action of the user.
+
+    Returns:
+        str: The formatted display name in the format 'model:action'.
+    """
     return f'{self.model}:{self.action}'

amsdal/contrib/auth/models/user/hooks/post_init.py

@@ -2,6 +2,19 @@ from typing import Any
 
 
 def post_init(self, *, is_new_object: bool, kwargs: dict[str, Any]) -> None:  # type: ignore[no-untyped-def]
+    """
+    Post-initializes a user object by validating email and password, and hashing the password.
+
+    This method checks if the email and password are provided and valid. If the object is new,
+    it hashes the password and sets the object ID to the lowercased email.
+
+    Args:
+        is_new_object (bool): Indicates if the object is new.
+        kwargs (dict[str, Any]): The keyword arguments containing user details.
+
+    Raises:
+        UserCreationError: If the email or password is invalid.
+    """
     import bcrypt
 
     from amsdal.contrib.auth.errors import UserCreationError

amsdal/contrib/auth/models/user/hooks/pre_create.py

@@ -1,2 +1,8 @@
 def pre_create(self) -> None:  # type: ignore[no-untyped-def]
+    """
+    Pre-creates a user object.
+
+    This method is a placeholder for any pre-creation logic that needs to be executed
+    before a user object is created.
+    """
     pass

amsdal/contrib/auth/models/user/modifiers/display_name.py

@@ -1,5 +1,13 @@
 @property  # type: ignore[misc]
 def display_name(self) -> str:  # type: ignore[no-untyped-def]
+    """
+    Returns the display name of the user.
+
+    This method returns the email of the user as their display name.
+
+    Returns:
+        str: The email of the user.
+    """
     return self.email
 
 

amsdal/contrib/auth/settings.py

@@ -3,6 +3,21 @@ from pydantic_settings import SettingsConfigDict
 
 
 class Settings(BaseSettings):
+    """
+    Settings configuration for the application.
+
+    This class uses Pydantic's BaseSettings to manage application settings
+    from environment variables and a .env file.
+
+    Attributes:
+        model_config (SettingsConfigDict): Configuration for Pydantic settings.
+        ADMIN_USER_EMAIL (str | None): The email of the admin user.
+        ADMIN_USER_PASSWORD (str | None): The password of the admin user.
+        AUTH_JWT_KEY (str | None): The key used for JWT authentication.
+        AUTH_TOKEN_EXPIRATION (int): The expiration time for authentication tokens in seconds.
+        REQUIRE_DEFAULT_AUTHORIZATION (bool): Flag to require default authorization.
+    """
+
     model_config = SettingsConfigDict(
         case_sensitive=True,
         env_prefix='AMSDAL_',

amsdal/contrib/auth/settings.pyi

@@ -2,6 +2,20 @@ from _typeshed import Incomplete
 from pydantic_settings import BaseSettings
 
 class Settings(BaseSettings):
+    """
+    Settings configuration for the application.
+
+    This class uses Pydantic's BaseSettings to manage application settings
+    from environment variables and a .env file.
+
+    Attributes:
+        model_config (SettingsConfigDict): Configuration for Pydantic settings.
+        ADMIN_USER_EMAIL (str | None): The email of the admin user.
+        ADMIN_USER_PASSWORD (str | None): The password of the admin user.
+        AUTH_JWT_KEY (str | None): The key used for JWT authentication.
+        AUTH_TOKEN_EXPIRATION (int): The expiration time for authentication tokens in seconds.
+        REQUIRE_DEFAULT_AUTHORIZATION (bool): Flag to require default authorization.
+    """
     model_config: Incomplete
     ADMIN_USER_EMAIL: str | None
     ADMIN_USER_PASSWORD: str | None

amsdal/contrib/frontend_configs/app.py

@@ -6,5 +6,19 @@ from amsdal.contrib.frontend_configs.lifecycle.consumer import ProcessResponseCo
 
 
 class FrontendConfigAppConfig(AppConfig):
+    """
+    Application configuration class for frontend configurations.
+
+    This class extends the AppConfig and sets up listeners for lifecycle events
+    to process frontend configurations.
+    """
+
     def on_ready(self) -> None:
+        """
+        Registers a listener for the ON_RESPONSE_EVENT to process responses
+        using the ProcessResponseConsumer.
+
+        Returns:
+            None
+        """
         LifecycleProducer.add_listener(ON_RESPONSE_EVENT, ProcessResponseConsumer)  # type: ignore[arg-type]

amsdal/contrib/frontend_configs/app.pyi

@@ -3,4 +3,17 @@ from amsdal.contrib.frontend_configs.constants import ON_RESPONSE_EVENT as ON_RE
 from amsdal.contrib.frontend_configs.lifecycle.consumer import ProcessResponseConsumer as ProcessResponseConsumer
 
 class FrontendConfigAppConfig(AppConfig):
-    def on_ready(self) -> None: ...
+    """
+    Application configuration class for frontend configurations.
+
+    This class extends the AppConfig and sets up listeners for lifecycle events
+    to process frontend configurations.
+    """
+    def on_ready(self) -> None:
+        """
+        Registers a listener for the ON_RESPONSE_EVENT to process responses
+        using the ProcessResponseConsumer.
+
+        Returns:
+            None
+        """

amsdal/contrib/frontend_configs/conversion/convert.py

@@ -45,6 +45,20 @@ def _process_union(value: UnionType, *, is_transaction: bool = False) -> dict[st
 
 
 def convert_to_frontend_config(value: Any, *, is_transaction: bool = False) -> dict[str, Any]:
+    """
+    Converts a given value to a frontend configuration dictionary.
+
+    This function takes a value and converts it into a dictionary that represents
+    the configuration for a frontend form control. It handles various types such as
+    Union, list, dict, BaseModel, and custom types.
+
+    Args:
+        value (Any): The value to be converted to frontend configuration.
+        is_transaction (bool, optional): Indicates if the conversion is for a transaction. Defaults to False.
+
+    Returns:
+        dict[str, Any]: A dictionary representing the frontend configuration for the given value.
+    """
     if hasattr(value, '__origin__'):
         origin_class = value.__origin__
 

amsdal/contrib/frontend_configs/conversion/convert.pyi

@@ -6,4 +6,18 @@ from typing import Any
 default_types_map: Incomplete
 
 def _process_union(value: UnionType, *, is_transaction: bool = False) -> dict[str, Any]: ...
-def convert_to_frontend_config(value: Any, *, is_transaction: bool = False) -> dict[str, Any]: ...
+def convert_to_frontend_config(value: Any, *, is_transaction: bool = False) -> dict[str, Any]:
+    """
+    Converts a given value to a frontend configuration dictionary.
+
+    This function takes a value and converts it into a dictionary that represents
+    the configuration for a frontend form control. It handles various types such as
+    Union, list, dict, BaseModel, and custom types.
+
+    Args:
+        value (Any): The value to be converted to frontend configuration.
+        is_transaction (bool, optional): Indicates if the conversion is for a transaction. Defaults to False.
+
+    Returns:
+        dict[str, Any]: A dictionary representing the frontend configuration for the given value.
+    """

amsdal/contrib/frontend_configs/lifecycle/consumer.py

@@ -3,11 +3,11 @@ import logging
 from typing import Any
 
 from amsdal_models.classes.errors import AmsdalClassNotFoundError
-from amsdal_models.schemas.data_models.core import LegacyDictSchema
-from amsdal_models.schemas.data_models.schema import PropertyData
-from amsdal_models.schemas.enums import CoreTypes
 from amsdal_utils.lifecycle.consumer import LifecycleConsumer
 from amsdal_utils.models.data_models.address import Address
+from amsdal_utils.models.data_models.core import LegacyDictSchema
+from amsdal_utils.models.data_models.enums import CoreTypes
+from amsdal_utils.models.data_models.schema import PropertyData
 from amsdal_utils.models.enums import SchemaTypes
 from amsdal_utils.models.enums import Versions
 
@@ -25,6 +25,20 @@ core_to_frontend_types = {
 
 
 def process_property(field_name: str, property_data: PropertyData) -> dict[str, Any]:
+    """
+    Processes a property and converts it to a frontend configuration dictionary.
+
+    This function takes a field name and property data, and converts them into a dictionary
+    that represents the configuration for a frontend form control. It handles various types
+    such as core types, arrays, dictionaries, and files.
+
+    Args:
+        field_name (str): The name of the field to be processed.
+        property_data (PropertyData): The property data to be processed.
+
+    Returns:
+        dict[str, Any]: A dictionary representing the frontend configuration for the given property.
+    """
     type_definition: dict[str, Any]
     if property_data.type in core_to_frontend_types:
         type_definition = {
@@ -92,6 +106,20 @@ def process_property(field_name: str, property_data: PropertyData) -> dict[str,
 
 
 def populate_frontend_config_with_values(config: dict[str, Any], values: dict[str, Any]) -> dict[str, Any]:
+    """
+    Populates a frontend configuration dictionary with values.
+
+    This function takes a frontend configuration dictionary and a dictionary of values,
+    and populates the configuration with the corresponding values. It recursively processes
+    nested controls to ensure all values are populated.
+
+    Args:
+        config (dict[str, Any]): The frontend configuration dictionary to be populated.
+        values (dict[str, Any]): The dictionary of values to populate the configuration with.
+
+    Returns:
+        dict[str, Any]: The populated frontend configuration dictionary.
+    """
     if config.get('controls') and isinstance(config['controls'], list):
         for control in config['controls']:
             populate_frontend_config_with_values(control, values)
@@ -102,6 +130,19 @@ def populate_frontend_config_with_values(config: dict[str, Any], values: dict[st
 
 
 def get_values_from_response(response: dict[str, Any] | list[dict[str, Any]]) -> dict[str, Any]:
+    """
+    Extracts values from a response dictionary or list of dictionaries.
+
+    This function processes a response to extract the relevant values. It checks if the response
+    is a dictionary containing a 'rows' key and processes the rows to find the appropriate values.
+    If the response is not in the expected format, it returns an empty dictionary.
+
+    Args:
+        response (dict[str, Any] | list[dict[str, Any]]): The response to extract values from.
+
+    Returns:
+        dict[str, Any]: A dictionary containing the extracted values.
+    """
     if not isinstance(response, dict) or 'rows' not in response or not response['rows']:
         return {}
 
@@ -113,6 +154,19 @@ def get_values_from_response(response: dict[str, Any] | list[dict[str, Any]]) ->
 
 
 def get_default_control(class_name: str) -> dict[str, Any]:
+    """
+    Retrieves the default frontend control configuration for a given class name.
+
+    This function attempts to import a class by its name from various schema types.
+    If the class is found, it converts it to a frontend configuration dictionary
+    and returns it. If the class is not found, it returns an empty dictionary.
+
+    Args:
+        class_name (str): The name of the class to retrieve the default control for.
+
+    Returns:
+        dict[str, Any]: A dictionary representing the frontend control configuration for the given class.
+    """
     from amsdal_models.classes.manager import ClassManager
 
     from amsdal.contrib.frontend_configs.conversion import convert_to_frontend_config
@@ -135,11 +189,29 @@ def get_default_control(class_name: str) -> dict[str, Any]:
 
 
 class ProcessResponseConsumer(LifecycleConsumer):
+    """
+    Consumer class for processing responses and populating frontend configurations.
+
+    This class extends the LifecycleConsumer and processes responses to populate
+    frontend configurations based on the class name and values extracted from the response.
+    """
+
     def on_event(
         self,
         request: Any,
         response: dict[str, Any],
     ) -> None:
+        """
+        Handles the event by extracting the class name and values from the request and response,
+        and populates the frontend configuration accordingly.
+
+        Args:
+            request (Any): The request object containing query and path parameters.
+            response (dict[str, Any]): The response dictionary to be processed.
+
+        Returns:
+            None
+        """
         from models.contrib.frontend_model_config import FrontendModelConfig  # type: ignore[import-not-found]
 
         class_name = None