GeneralManager 0.10.3__py3-none-any.whl → 0.10.5__py3-none-any.whl

general_manager/api/graphql.py

@@ -102,9 +102,9 @@ class GraphQL:
     @classmethod
     def createGraphqlInterface(cls, generalManagerClass: GeneralManagerMeta) -> None:
         """
-        Generates and registers a GraphQL ObjectType for the specified GeneralManager class.
+        Generates and registers a GraphQL ObjectType for a given GeneralManager class.
         
-        This method maps interface attributes and GraphQLProperty attributes to Graphene fields, creates corresponding resolvers, registers the resulting type in the internal registry, and attaches relevant query fields to the schema.
+        This method maps interface and GraphQLProperty attributes to Graphene fields, creates resolvers for each field, registers the resulting type in the internal registry, and adds corresponding query fields to the schema.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -348,14 +348,7 @@ class GraphQL:
         base_getter: Callable[[Any], Any], fallback_manager_class: type[GeneralManager]
     ) -> Callable[..., Any]:
         """
-        Creates a resolver function for list fields that applies permission filters, query filters, sorting, pagination, and optional grouping to a queryset.
-        
-        Parameters:
-            base_getter (Callable): Function to obtain the base queryset from the parent instance.
-            fallback_manager_class (type[GeneralManager]): Manager class to use if the queryset does not specify one.
-        
-        Returns:
-            Callable: A resolver function for use in GraphQL list fields.
+        Returns a resolver function for GraphQL list fields that retrieves a queryset, applies permission-based filtering, query filters, sorting, pagination, and optional grouping, and returns the resulting data.
         """
 
         def resolver(
@@ -370,19 +363,19 @@ class GraphQL:
             group_by: list[str] | None = None,
         ) -> Any:
             """
-            Resolves a list field by applying permission filters, query parameters, sorting, pagination, and optional grouping to a queryset.
+            Resolves a list field by returning a queryset filtered by permissions, query parameters, sorting, pagination, and optional grouping.
             
             Parameters:
-                filter: Optional filter criteria as a dictionary or JSON string.
-                exclude: Optional exclusion criteria as a dictionary or JSON string.
-                sort_by: Optional sorting field as a Graphene Enum.
-                reverse: If True, reverses the sort order.
-                page: Optional page number for pagination.
-                page_size: Optional number of items per page.
-                group_by: Optional list of field names to group results by.
+                filter: Filter criteria as a dictionary or JSON string.
+                exclude: Exclusion criteria as a dictionary or JSON string.
+                sort_by: Field to sort by, as a Graphene Enum.
+                reverse: Whether to reverse the sort order.
+                page: Page number for pagination.
+                page_size: Number of items per page.
+                group_by: List of field names to group results by.
             
             Returns:
-                The filtered, sorted, paginated, and optionally grouped queryset.
+                A queryset with applied permission filters, filtering, sorting, pagination, and grouping.
             """
             base_queryset = base_getter(self)
             # use _manager_class from the attribute if available, otherwise fallback
@@ -460,7 +453,7 @@ class GraphQL:
         """
         Adds list and single-item query fields for a GeneralManager-derived class to the GraphQL schema.
         
-        This method registers both a list query (with filtering, sorting, pagination, and grouping) and a single-item query (using identification fields) for the specified manager class. The corresponding resolvers are also attached to the schema.
+        Registers a list query supporting filtering, sorting, pagination, and grouping, as well as a single-item query using identification fields for the specified manager class. The corresponding resolvers are attached to the schema.
         """
         if not issubclass(generalManagerClass, GeneralManager):
             raise TypeError(
@@ -526,10 +519,10 @@ class GraphQL:
         """
         Generate a dictionary of Graphene input fields for mutations based on the attributes of the provided interface class.
         
-        Skips fields that are system-managed (`changed_by`, `created_at`, `updated_at`) or marked as derived. For attributes referencing `GeneralManager` subclasses, uses ID fields; for list references, uses a list of IDs. All other types are mapped to their corresponding Graphene scalar types. Each field is annotated with an `editable` attribute indicating if it can be modified. Adds an optional `history_comment` field marked as editable.
+        Skips system-managed fields and derived attributes. For attributes referencing `GeneralManager` subclasses, uses ID or list of IDs as appropriate. Other types are mapped to their corresponding Graphene scalar types. Each field is annotated with an `editable` attribute. Adds an optional `history_comment` field marked as editable.
         
         Returns:
-            dict[str, Any]: A dictionary mapping attribute names to Graphene input fields for use in mutation arguments.
+            dict[str, Any]: Mapping of attribute names to Graphene input fields for mutation arguments.
         """
         fields: dict[str, Any] = {}
 
@@ -579,12 +572,12 @@ class GraphQL:
         default_return_values: dict[str, Any],
     ) -> type[graphene.Mutation] | None:
         """
-        Generates a Graphene mutation class for creating an instance of the specified GeneralManager subclass.
+        Dynamically generates a Graphene mutation class for creating an instance of the specified GeneralManager subclass.
         
-        The generated mutation class defines a `mutate` method that filters out fields with `NOT_PROVIDED` values, invokes the `create` method on the manager class with the provided arguments and the current user's ID, and returns a dictionary indicating success or failure along with any errors and the created instance.
+        The generated mutation class includes a `mutate` method that filters out fields with `NOT_PROVIDED` values, invokes the manager's `create` method with the provided arguments and the current user's ID, and returns a dictionary indicating success, any errors, and the created instance. Returns None if the manager class does not define an interface.
         
         Returns:
-            The generated Graphene mutation class, or None if the manager class does not define an interface.
+            The generated Graphene mutation class, or None if no interface is defined for the manager class.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -595,12 +588,12 @@ class GraphQL:
         def create_mutation(
             self,
             info: GraphQLResolveInfo,
-            **kwargs: dict[str, Any],
+            **kwargs: Any,
         ) -> dict:
             """
-            Creates a new instance of the specified manager class using provided input arguments.
+            Creates a new instance of the manager class with the provided arguments.
             
-            Filters out fields with default "not provided" values before creation. Returns a dictionary indicating success status, any errors encountered, and the created instance under a key named after the manager class.
+            Filters out fields with values marked as `NOT_PROVIDED` before creation. Returns a dictionary containing a success flag, a list of errors (if any), and the created instance under a key named after the manager class.
             """
             try:
                 kwargs = {
@@ -651,9 +644,9 @@ class GraphQL:
         default_return_values: dict[str, Any],
     ) -> type[graphene.Mutation] | None:
         """
-        Generates a GraphQL mutation class for updating an instance of a GeneralManager subclass.
+        Generates a GraphQL mutation class for updating instances of a GeneralManager subclass.
         
-        The generated mutation accepts editable fields as arguments, calls the `update` method on the manager instance, and returns a dictionary indicating success, errors, and the updated instance. If the manager class does not define an `Interface`, returns None.
+        The generated mutation accepts editable fields as arguments, invokes the manager's `update` method with the provided values, and returns a dictionary indicating success, any errors, and the updated instance. Returns None if the manager class does not define an `Interface`.
         
         Returns:
             The generated Graphene mutation class, or None if no interface is defined.
@@ -667,17 +660,17 @@ class GraphQL:
         def update_mutation(
             self,
             info: GraphQLResolveInfo,
-            **kwargs: dict[str, Any],
+            **kwargs: Any,
         ) -> dict:
             """
-            Handles the update mutation for a GeneralManager instance, applying provided field updates and returning the operation result.
+            Performs an update mutation on a GeneralManager instance with the specified fields.
             
             Parameters:
-                info (GraphQLResolveInfo): GraphQL resolver context containing user and request information.
+                info (GraphQLResolveInfo): The GraphQL resolver context, typically containing user and request information.
                 **kwargs: Fields to update, including the required 'id' of the instance.
             
             Returns:
-                dict: A dictionary containing the success status, any error messages, and the updated instance keyed by its class name.
+                dict: Contains the operation's success status, a list of error messages if any, and the updated instance keyed by its class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)
@@ -725,7 +718,7 @@ class GraphQL:
         """
         Generates a GraphQL mutation class for deleting (deactivating) an instance of a GeneralManager subclass.
         
-        The generated mutation accepts input fields defined in the manager's interface, deactivates the specified instance, and returns a dictionary indicating success or failure, along with any errors and the deleted instance.
+        The generated mutation accepts input fields defined in the manager's interface, deactivates the specified instance using its ID, and returns a dictionary with the operation's success status, any error messages, and the deactivated instance.
         """
         interface_cls: InterfaceBase | None = getattr(
             generalManagerClass, "Interface", None
@@ -736,13 +729,13 @@ class GraphQL:
         def delete_mutation(
             self,
             info: GraphQLResolveInfo,
-            **kwargs: dict[str, Any],
+            **kwargs: Any,
         ) -> dict:
             """
-            Deletes (deactivates) an instance of the specified GeneralManager class and returns the operation result.
+            Deactivates an instance of the specified GeneralManager class and returns the result.
             
             Returns:
-                dict: A dictionary containing the success status, any error messages, and the deactivated instance under the class name key.
+                dict: Contains the operation's success status, a list of error messages if any, and the deactivated instance keyed by the class name.
             """
             try:
                 manager_id = kwargs.pop("id", None)

general_manager/apps.py

@@ -43,12 +43,12 @@ class GeneralmanagerConfig(AppConfig):
 
     @staticmethod
     def handleReadOnlyInterface(
-        read_only_classes: list[Type[GeneralManager[Any, ReadOnlyInterface]]],
+        read_only_classes: list[Type[GeneralManager]],
     ):
         """
-        Configures synchronization and schema validation for the provided read-only interface classes.
-
-        Ensures that each read-only interface is synchronized before Django management commands run, and registers system checks to validate that their schemas are up to date.
+        Configures synchronization and schema validation for the given read-only GeneralManager classes.
+        
+        For each provided class, ensures that its data is synchronized before any Django management command executes, and registers a system check to verify that the associated schema remains up to date.
         """
         GeneralmanagerConfig.patchReadOnlyInterfaceSync(read_only_classes)
         from general_manager.interface.readOnlyInterface import ReadOnlyInterface
@@ -68,11 +68,11 @@ class GeneralmanagerConfig(AppConfig):
 
     @staticmethod
     def patchReadOnlyInterfaceSync(
-        general_manager_classes: list[Type[GeneralManager[Any, ReadOnlyInterface]]],
+        general_manager_classes: list[Type[GeneralManager]],
     ):
         """
         Monkey-patches Django's management command runner to synchronize all provided read-only interfaces before executing any management command, except during autoreload subprocesses of 'runserver'.
-
+        
         For each class in `general_manager_classes`, the associated read-only interface's `syncData` method is called prior to command execution, ensuring data consistency before management operations.
         """
         from general_manager.interface.readOnlyInterface import ReadOnlyInterface

general_manager/bucket/baseBucket.py

@@ -58,17 +58,14 @@ class Bucket(ABC, Generic[GeneralManagerType]):
     @abstractmethod
     def __or__(
         self,
-        other: (
-            Bucket[GeneralManagerType]
-            | GeneralManager[GeneralManagerType, InterfaceBase]
-        ),
+        other: Bucket[GeneralManagerType] | GeneralManagerType,
     ) -> Bucket[GeneralManagerType]:
         """
-        Returns a new bucket representing the union of this bucket and another bucket or manager instance.
-
-        Args:
+        Return a new bucket containing the union of this bucket and another bucket or manager instance.
+        
+        Parameters:
             other: Another bucket or a single manager instance to combine with this bucket.
-
+        
         Returns:
             A new bucket containing all unique items from both sources.
         """

general_manager/bucket/calculationBucket.py

@@ -92,19 +92,18 @@ class CalculationBucket(Bucket[GeneralManagerType]):
 
     def __or__(
         self,
-        other: (
-            Bucket[GeneralManagerType]
-            | GeneralManager[GeneralManagerType, CalculationInterface]
-        ),
+        other: Bucket[GeneralManagerType] | GeneralManagerType,
     ) -> CalculationBucket[GeneralManagerType]:
         """
-        Combines this CalculationBucket with another bucket or manager of the same type.
-
-        If combined with a manager instance, returns a bucket filtered to that manager's identification.
-        If combined with another CalculationBucket of the same manager class, returns a new bucket with filters and excludes that are present and identical in both.
-
+        Combine this CalculationBucket with another bucket or manager instance of the same manager class.
+        
+        If combined with a manager instance, returns a bucket filtered to that manager's identification. If combined with another CalculationBucket of the same manager class, returns a new bucket containing only the filters and excludes that are present and identical in both buckets.
+        
         Raises:
             ValueError: If the other object is not a CalculationBucket or manager of the same class.
+            
+        Returns:
+            CalculationBucket[GeneralManagerType]: A new CalculationBucket representing the intersection of filters and excludes, or a filtered bucket for the given manager instance.
         """
         from general_manager.manager.generalManager import GeneralManager
 

general_manager/bucket/databaseBucket.py

@@ -1,11 +1,5 @@
 from __future__ import annotations
-from typing import (
-    Type,
-    Any,
-    Generator,
-    TypeVar,
-    TYPE_CHECKING,
-)
+from typing import Type, Any, Generator, TypeVar, TYPE_CHECKING
 from django.db import models
 from general_manager.interface.baseInterface import (
     GeneralManagerType,
@@ -30,16 +24,15 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         exclude_definitions: dict[str, list[Any]] | None = None,
     ):
         """
-        Initializes a DatabaseBucket with a queryset, manager class, and optional filter and exclude definitions.
+        Initialize a DatabaseBucket with a Django queryset, a manager class, and optional filter and exclude definitions.
 
-        If no queryset is provided, constructs one using the manager class and the given filters and excludes. Stores the queryset, manager class, and copies of the filter and exclude definitions for further operations.
+        Parameters:
+            data (QuerySet): The Django queryset containing model instances to be managed.
+            manager_class (Type[GeneralManagerType]): The manager class used to wrap model instances.
+            filter_definitions (dict[str, list[Any]], optional): Initial filter criteria for the queryset.
+            exclude_definitions (dict[str, list[Any]], optional): Initial exclude criteria for the queryset.
         """
-        if data is None:
-            data = manager_class.Interface._model.objects.filter(
-                **filter_definitions
-            ).exclude(**exclude_definitions)
         self._data = data
-
         self._manager_class = manager_class
         self.filters = {**(filter_definitions or {})}
         self.excludes = {**(exclude_definitions or {})}
@@ -55,18 +48,15 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
 
     def __or__(
         self,
-        other: (
-            Bucket[GeneralManagerType]
-            | GeneralManager[GeneralManagerType, DatabaseInterface]
-        ),
+        other: Bucket[GeneralManagerType] | GeneralManagerType,
     ) -> DatabaseBucket[GeneralManagerType]:
         """
-        Combines this bucket with another bucket or manager instance using the union operator.
+        Return a new bucket containing the union of this bucket and another bucket or manager instance.
 
-        If `other` is a manager instance of the same class, creates a bucket containing only that instance and combines it. If `other` is a compatible bucket, returns a new bucket containing the union of both buckets' querysets. Raises a `ValueError` if the types or manager classes are incompatible.
+        If `other` is a manager instance of the same class, it is converted to a bucket before combining. If `other` is a compatible bucket, the resulting bucket contains all unique items from both. Raises a `ValueError` if the types or manager classes are incompatible.
 
         Returns:
-            A new `DatabaseBucket` containing the combined items.
+            DatabaseBucket[GeneralManagerType]: A new bucket with the combined items.
         """
         if isinstance(other, GeneralManager) and other.__class__ == self._manager_class:
             return self.__or__(
@@ -202,10 +192,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
 
     def __contains__(self, item: GeneralManagerType | models.Model) -> bool:
         """
-        Checks if a manager instance or model instance is present in the bucket.
-
-        Args:
-            item: A manager instance or Django model instance to check for membership.
+        Determine whether a manager instance or Django model instance is present in the bucket.
 
         Returns:
             True if the item's primary key exists in the underlying queryset; otherwise, False.
@@ -216,7 +203,7 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
             return item.identification.get("id", None) in self._data.values_list(
                 "pk", flat=True
             )
-        return item in self._data
+        return item.pk in self._data.values_list("pk", flat=True)
 
     def sort(
         self,
@@ -224,14 +211,14 @@ class DatabaseBucket(Bucket[GeneralManagerType]):
         reverse: bool = False,
     ) -> DatabaseBucket:
         """
-        Returns a new DatabaseBucket sorted by the specified field or fields.
+        Return a new DatabaseBucket sorted by the specified field or fields.
 
-        Args:
-            key: A field name or tuple of field names to sort by.
-            reverse: If True, sorts in descending order.
+        Parameters:
+            key (str or tuple of str): Field name or tuple of field names to sort by.
+            reverse (bool): If True, sort in descending order.
 
         Returns:
-            A new DatabaseBucket instance with the sorted queryset.
+            DatabaseBucket: A new bucket instance containing the sorted queryset.
         """
         if isinstance(key, str):
             key = (key,)

general_manager/cache/signals.py

@@ -1,19 +1,30 @@
 from django.dispatch import Signal
-from typing import Callable, Any
+from typing import Callable, TypeVar, ParamSpec, cast
+
 from functools import wraps
 
 post_data_change = Signal()
 
 pre_data_change = Signal()
 
+P = ParamSpec("P")
+R = TypeVar("R")
+
 
-def dataChange(func: Callable[..., Any]) -> Callable:
+def dataChange(func: Callable[P, R]) -> Callable[P, R]:
     """
-    Signal to indicate that data has changed.
+    Decorator that emits pre- and post-data change signals around the execution of the decorated function.
+    
+    Sends the `pre_data_change` signal before the wrapped function is called and the `post_data_change` signal after it completes. The signals include information about the sender, action, and relevant instance state before and after the change. Handles both regular functions and classmethods. Intended for use with functions that modify data to enable signal-based hooks for data change events.
     """
 
     @wraps(func)
-    def wrapper(*args, **kwargs):
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        """
+        Wraps a function to emit pre- and post-data change signals around its execution.
+        
+        Sends the `pre_data_change` signal before the wrapped function is called and the `post_data_change` signal after, providing context such as the sender, action name, and relevant instance data. Handles both regular functions and classmethods, and distinguishes the "create" action by omitting a pre-existing instance.
+        """
         action = func.__name__
         if func.__name__ == "create":
             sender = args[0]
@@ -29,11 +40,12 @@ def dataChange(func: Callable[..., Any]) -> Callable:
             **kwargs,
         )
         old_relevant_values = getattr(instance_before, "_old_values", {})
-        result = (
-            func.__func__(*args, **kwargs)
-            if isinstance(func, classmethod)
-            else func(*args, **kwargs)
-        )
+        if isinstance(func, classmethod):
+            inner = cast(Callable[P, R], func.__func__)
+            result = inner(*args, **kwargs)
+        else:
+            result = func(*args, **kwargs)
+
         instance = result
 
         post_data_change.send(

general_manager/factory/autoFactory.py

@@ -3,7 +3,7 @@ from typing import TYPE_CHECKING, Type, Callable, Union, Any, TypeVar, Literal
 from django.db import models
 from factory.django import DjangoModelFactory
 from general_manager.factory.factories import getFieldValue, getManyToManyFieldValue
-
+from django.contrib.contenttypes.fields import GenericForeignKey
 
 if TYPE_CHECKING:
     from general_manager.interface.databaseInterface import (
@@ -29,16 +29,16 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, strategy: Literal["build", "create"], params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Generates and populates a Django model instance or list of instances with automatic field value assignment.
+        Generates and populates one or more Django model instances with automatic field value assignment.
         
-        Automatically assigns values to unset model fields, including handling custom and special fields, and processes many-to-many relationships after instance creation or building. Raises a ValueError if the model is not a subclass of Django's Model.
+        Automatically fills unset model fields, excluding generic foreign keys and auto-created fields, and handles custom and special fields as defined by the interface. After instance creation or building, processes many-to-many relationships. Raises a ValueError if the model is not a subclass of Django's Model.
         
-        Args:
-            strategy: Specifies whether to build (unsaved) or create (saved) the instance(s).
-            params: Field values to use for instance generation; missing fields are auto-filled.
+        Parameters:
+            strategy (Literal["build", "create"]): Determines whether to build (unsaved) or create (saved) the instance(s).
+            params (dict[str, Any]): Field values to use for instance generation; missing fields are auto-filled.
         
         Returns:
-            A single model instance or a list of model instances, depending on the input parameters and strategy.
+            models.Model or list[models.Model]: The generated model instance or list of instances.
         """
         cls._original_params = params
         model = cls._meta.model
@@ -50,6 +50,7 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
             field
             for field in model._meta.get_fields()
             if field.name not in to_ignore_list
+            and not isinstance(field, GenericForeignKey)
         ]
         special_fields: list[models.Field[Any, Any]] = [
             getattr(model, field_name) for field_name in field_name_list
@@ -72,7 +73,7 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
 
         obj: list[models.Model] | models.Model = super()._generate(strategy, params)
         if isinstance(obj, list):
-            for item in obj:  # type: ignore
+            for item in obj:
                 if not isinstance(item, models.Model):
                     raise ValueError("Model must be a type")
                 cls._handleManyToManyFieldsAfterCreation(item, params)
@@ -85,9 +86,9 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, obj: models.Model, attrs: dict[str, Any]
     ) -> None:
         """
-        Sets many-to-many field values on a Django model instance after creation.
+        Assigns related objects to all many-to-many fields of a Django model instance after it has been created.
         
-        For each many-to-many field, assigns related objects from the provided attributes if available; otherwise, generates values using `getManyToManyFieldValue`. The related objects are set using the Django ORM's `set` method.
+        For each many-to-many field, sets the related objects from the provided attributes if available; otherwise, generates related objects automatically. Uses the Django ORM's `set` method to establish the relationships.
         """
         for field in obj._meta.many_to_many:
             if field.name in attrs:
@@ -101,10 +102,10 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
     def _adjust_kwargs(cls, **kwargs: dict[str, Any]) -> dict[str, Any]:
         # Remove ManyToMany fields from kwargs before object creation
         """
-        Removes many-to-many field entries from keyword arguments before model instance creation.
+        Removes many-to-many fields from the provided keyword arguments before creating or building a model instance.
         
         Returns:
-            The keyword arguments dictionary with many-to-many fields removed.
+            dict[str, Any]: The keyword arguments with any many-to-many fields excluded.
         """
         model: Type[models.Model] = cls._meta.model
         m2m_fields = {field.name for field in model._meta.many_to_many}
@@ -117,15 +118,12 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, model_class: Type[models.Model], *args: list[Any], **kwargs: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Creates and saves a Django model instance or instances, applying optional adjustment logic.
-        
-        If an adjustment method is defined, it is used to generate or modify field values before creation. Otherwise, the model is instantiated and saved with the provided attributes.
+        Create and save a Django model instance or multiple instances, optionally applying custom adjustment logic to field values.
         
-        Args:
-            model_class: The Django model class to instantiate.
+        If an adjustment method is defined, it is used to generate or modify field values before instance creation. Otherwise, the model is instantiated and saved with the provided attributes.
         
         Returns:
-            A saved model instance or a list of instances.
+            A saved model instance or a list of saved instances.
         """
         kwargs = cls._adjust_kwargs(**kwargs)
         if cls._adjustmentMethod is not None:
@@ -137,9 +135,12 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, model_class: Type[models.Model], *args: list[Any], **kwargs: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Constructs an unsaved instance or list of instances of the given Django model class.
+        Builds an unsaved instance or list of instances of the specified Django model class.
         
-        If an adjustment method is defined, it is used to generate or modify field values before building the instance(s). Many-to-many fields are removed from the keyword arguments prior to instantiation.
+        If an adjustment method is defined, it is used to generate or modify field values before building. Many-to-many fields are excluded from the keyword arguments prior to instantiation.
+        
+        Returns:
+            models.Model or list[models.Model]: The unsaved model instance or list of instances.
         """
         kwargs = cls._adjust_kwargs(**kwargs)
         if cls._adjustmentMethod is not None:
@@ -153,9 +154,9 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, model_class: Type[models.Model], **kwargs: dict[str, Any]
     ) -> models.Model:
         """
-        Creates and saves a Django model instance with the provided field values.
+        Create, validate, and save a Django model instance with the specified field values.
         
-        Initializes the model, assigns attributes from keyword arguments, validates the instance using `full_clean()`, and saves it to the database.
+        Initializes the model, assigns attributes from keyword arguments, performs validation with `full_clean()`, and saves the instance to the database.
         
         Returns:
             The saved Django model instance.
@@ -172,14 +173,14 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, model_class: Type[models.Model], **kwargs: dict[str, Any]
     ) -> models.Model:
         """
-        Constructs an unsaved instance of the specified Django model with provided field values.
+        Constructs an unsaved Django model instance with the specified field values.
         
-        Args:
-            model_class: The Django model class to instantiate.
-            **kwargs: Field values to set on the model instance.
+        Parameters:
+            model_class (Type[models.Model]): The Django model class to instantiate.
+            **kwargs: Field values to assign to the model instance.
         
         Returns:
-            An unsaved Django model instance with attributes set from kwargs.
+            models.Model: An unsaved instance of the specified model with attributes set from kwargs.
         """
         obj = model_class()
         for field, value in kwargs.items():
@@ -191,17 +192,16 @@ class AutoFactory(DjangoModelFactory[modelsModel]):
         cls, use_creation_method: bool, params: dict[str, Any]
     ) -> models.Model | list[models.Model]:
         """
-        Generates one or more model instances using the adjustment method for field values.
+        Creates or builds one or more model instances using the adjustment method to generate field values.
         
-        If the adjustment method returns a single dictionary, creates or builds a single model instance.
-        If it returns a list of dictionaries, creates or builds multiple instances accordingly.
+        If the adjustment method returns a single dictionary, a single instance is created or built. If it returns a list of dictionaries, multiple instances are created or built accordingly.
         
-        Args:
-            use_creation_method: If True, saves instances to the database; otherwise, builds unsaved instances.
-            params: Parameters to pass to the adjustment method for generating field values.
+        Parameters:
+            use_creation_method (bool): If True, instances are saved to the database; if False, instances are built but not saved.
+            params (dict[str, Any]): Arguments passed to the adjustment method for generating field values.
         
         Returns:
-            A single model instance or a list of model instances, depending on the adjustment method's output.
+            models.Model or list[models.Model]: The created or built model instance(s).
         
         Raises:
             ValueError: If the adjustment method is not defined.