Layers

Layers (atlas.layers) is the package containing the data access and business logic abstraction layers' base classes. It defines the foundation for structuring domain operations through repositories and services, ensuring a clean separation between persistence and application logic.

Below are the descriptions of both service and repository abstractions.

Service

Bases: Generic[T]

Service is the abstract base class from which all domain-specific services must inherit. It is responsible for implementing domain-level business logic and providing structured access to the given domain persistence (via default methods) through a dynamically bound repository. Custom methods can be implemented in the given domain-specific subclass as needed.

Attributes:

Name	Type	Description
`repository`	`Repository[T]`	The dynamically generated repository bound to the model class associated with this service.

`delete_by_uuid(uuid)`

Deletes an entity by its UUID.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	The UUID of the entity to delete.	required

Raises:

Type	Description
`NotFoundError`	If the entity does not exist.

`get_by_uuid(uuid, ret_dto_type=None)`

Retrieves an entity by its UUID. Raises a NotFoundError if no matching entity exists.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	The UUID of the entity to retrieve.	required
`ret_dto_type`	`Optional[Type[RetDTO]]`	The DTO type to map the result to.	`None`

Returns:

Type	Description
`RetDTO \| T`	RetDTO \| T: The retrieved entity or its DTO representation.

Raises:

Type	Description
`NotFoundError`	If the entity cannot be found.

`get_hierarchy_unassignable_uuids(parent_uuid_field_name, children_field_name, assign_target_uuid_ref, assign_type, intended_parent_uuid_ref=None, intended_children_to_add_uuid_refs=None, intended_children_to_remove_uuid_refs=None)`

Determines which UUIDs cannot be assigned to the assign target as its parent/children in a hierarchical relationship, considering its current hierarchy state and any hierarchy changes intended to be made (e.g., to prevent cyclic dependencies or invalid parent/child associations).

Parameters:

Name	Type	Description	Default
`parent_uuid_field_name`	`str`	The name of the model's field responsible for containing the parent entity's UUID.	required
`children_field_name`	`str`	The name of the model's field responsible for containing its child entities.	required
`assign_target_uuid_ref`	`InputDTO`	The reference to the target entity whose hierarchy and intended hierarchy changes will be evaluated to determine which parent or child (depending on `assign_type`) entities cannot be assigned to it.	required
`assign_type`	`Literal['parent', 'children']`	Indicates whether the evaluation is about unassignable parents or unassignable children.	required
`intended_parent_uuid_ref`	`Optional[InputDTO]`	The intended parent reference.	`None`
`intended_children_to_add_uuid_refs`	`Optional[List[InputDTO]]`	List of children references intended to be added.	`None`
`intended_children_to_remove_uuid_refs`	`Optional[List[InputDTO]]`	List of children references intended to be removed.	`None`

Returns:

Type	Description
`List[str]`	List[str]: List of UUIDs that cannot be assigned to the assign target within the current hierarchy and intended hierarchy changes.

Raises:

Type	Description
`NotFoundError`	If any of the given field names are invalid for the model or if any of the given references are invalid.

`map_or_self(instance, ret_dto_type)`

Maps a model instance to the specified DTO type, or returns the original instance if no type is provided.

Parameters:

Name	Type	Description	Default
`instance`	`object`	The source model instance to be mapped.	required
`ret_dto_type`	`Optional[Type[RetDTO]]`	The DTO type to map to.	required

Returns:

Name	Type	Description
`object`	`object`	The mapped DTO instance or the original model instance.

`resolve_referring_instance(referring_instance)`

Resolves and retrieves the referenced entity instance from a referring DTO-like object.

Parameters:

Name	Type	Description	Default
`referring_instance`	`object`	The object containing the UUID reference.	required

Returns:

Name	Type	Description
`T`	`T`	The resolved entity instance.

Raises:

Type	Description
`InconsistentStateError`	If the referring instance is invalid or lacks a UUID.
`NotFoundError`	If no entity matches the provided UUID.

`resolve_referring_instances(referring_instances)`

Resolves and retrieves multiple referenced entity instances from a list of referring objects.

Parameters:

Name	Type	Description	Default
`referring_instances`	`List[object]`	The list of objects containing UUID references.	required

Returns:

Type	Description
`List[T]`	List[T]: List of resolved entity instances.

Raises:

Type	Description
`InconsistentStateError`	If any referring instance is invalid.
`NotFoundError`	If one or more entities could not be found.

`set_hierarchy(uuid, parent_uuid_field_name, parent_field_name, children_field_name, parent_uuid_ref=None, children_uuid_refs_to_add=None, children_uuid_refs_to_remove=None)`

Establishes or updates parent–child relationships between entities in a hierarchy. Validates structure consistency and prevents cyclic dependencies.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	The UUID of the entity whose hierarchy is being modified.	required
`parent_uuid_field_name`	`str`	The name of the model's field responsible for containing the parent entity's UUID.	required
`parent_field_name`	`str`	The name of the model's field responsible for containing the parent entity.	required
`children_field_name`	`str`	The name of the model's field responsible for containing its child entities.	required
`parent_uuid_ref`	`Optional[InputDTO]`	The parent reference.	`None`
`children_uuid_refs_to_add`	`Optional[List[InputDTO]]`	List of children references to be added.	`None`
`children_uuid_refs_to_remove`	`Optional[List[InputDTO]]`	List of children references intended to be removed.	`None`

Raises:

Type	Description
`NotFoundError`	If any of the given field names are invalid for the model or if any of the given references are invalid.
`ConflictError`	If cyclic or inconsistent hierarchy states are detected.

`validate_uniqueness_by_fields(instance, fields, uuid_to_exclude=None, case_sensitive=False)`

Ensures that no existing entity violates uniqueness constraints based on a set of fields.

Parameters:

Name	Type	Description	Default
`instance`	`object`	The entity instance to validate.	required
`fields`	`List[str]`	The list of field names that must be unique.	required
`uuid_to_exclude`	`Optional[str]`	An optional UUID to exclude from validation.	`None`
`case_sensitive`	`bool`	Whether the uniqueness check should be case-sensitive.	`False`

Raises:

Type	Description
`ConflictError`	If another entity already exists with the same field value(s).

Repository

Bases: Generic[T]

Repository is the abstract base class from which all domain-specific repositories must inherit. It serves as the data access layer for domain entities, encapsulating SQLAlchemy queries and persistence logic. Custom methods can be implemented in the given domain-specific subclass as needed.

Attributes:

Name	Type	Description
`model_class`	`Type[T]`	The SQLAlchemy model class dynamically bound to the repository based on the generic parameter.

`add(instance)`

Adds an entity instance to the current session for persistence.

Parameters:

Name	Type	Description	Default
`instance`	`T`	The entity instance to add.	required

Returns:

Name	Type	Description
`T`	`T`	The added entity instance (useful for chaining or inspection).

`delete(instance)`

Deletes an entity instance from the current session.

Parameters:

Name	Type	Description	Default
`instance`	`T`	The entity instance to delete.	required

`execute(query)`

Executes a SQLAlchemy query within the current session.

Parameters:

Name	Type	Description	Default
`query`	`Select`	The SQLAlchemy query to execute.	required

Returns:

Name	Type	Description
`Result`	`Result`	The raw SQLAlchemy `Result` object returned by the session.

`flush()`

Flushes all pending changes in the current session to the database.

This ensures that all pending inserts, updates, or deletes are executed immediately, without committing the transaction.

`get_all(query)`

Executes a query and returns all resulting entities as a list.

Parameters:

Name	Type	Description	Default
`query`	`Select`	The SQLAlchemy query to execute.	required

Returns:

Type	Description
`list[T]`	List[T]: A list of all entities matching the query.

`get_ancestors(uuid, parent_uuid_field_name, include_self=False)`

Retrieves all ancestor entities of a given entity in a recursive hierarchy (father, grandfather, great-grandfather, etc).

Parameters:

Name	Type	Description	Default
`uuid`	`str`	The UUID of the target entity.	required
`parent_uuid_field_name`	`str`	The name of the field representing the parent entity’s UUID.	required
`include_self`	`bool`	Whether to include the target entity itself in the result.	`False`

Returns:

Type	Description
`List[T]`	List[T]: The list of ancestor entities in the hierarchy.

Raises:

Type	Description
`NotFoundError`	If the model does not have a field named `parent_uuid_field_name`.

`get_by_uuid(uuid)`

Retrieves a single entity by its UUID.

Parameters:

Name	Type	Description	Default
`uuid`	`str`	The UUID of the entity to retrieve.	required

Returns:

Type	Description
`T \| None`	Optional[T]: The entity with the given UUID, or `None` if not found.

`get_by_uuids(uuids)`

Retrieves multiple entities by their UUIDs.

Parameters:

Name	Type	Description	Default
`uuids`	`List[str]`	A list of UUIDs corresponding to the entities to fetch.	required

Returns:

Type	Description
`List[T]`	List[T]: A list of all entities matching the given UUIDs.

`get_descendants(uuids, parent_uuid_field_name, include_selves=False)`

Retrieves all descendant entities of the given entities in a recursive hierarchy (sons, grandsons, great-grandsons, etc).

Parameters:

Name	Type	Description	Default
`uuids`	`List[str]`	The UUIDs of the root entities.	required
`parent_uuid_field_name`	`str`	The name of the field representing the parent entity’s UUID.	required
`include_selves`	`bool`	Whether to include the root entities themselves in the result.	`False`

Returns:

Type	Description
`List[T]`	List[T]: The list of descendant entities in the hierarchy.

Raises:

Type	Description
`NotFoundError`	If the model does not have a field named `parent_uuid_field_name`.

`get_first(query)`

Executes a query and returns the first entity from the results.

Parameters:

Name	Type	Description	Default
`query`	`Select`	The SQLAlchemy query to execute.	required

Returns:

Type	Description
`T \| None`	Optional[T]: The first entity in the result set, or `None` if no results exist.

`get_paginated_results(query, pageable)`

Executes a query and returns a paginated result set, including total element count.

Parameters:

Name	Type	Description	Default
`query`	`Select`	The SQLAlchemy query to paginate.	required
`pageable`	`Pageable`	The pagination configuration (page number, size, and sorting).	required

Returns:

Name	Type	Description
`Page`	`Page`	A `Page` object containing paginated results and metadata.

`get_scalars(query)`

Executes a query and returns its scalar results (mapped entities).

Parameters:

Name	Type	Description	Default
`query`	`Select`	The SQLAlchemy query to execute.	required

Returns:

Name	Type	Description
`ScalarResult`	`ScalarResult`	The `ScalarResult` containing mapped entities or scalar values.

`model_query()`

Creates a SELECT query for the bound model class.

Returns:

Name	Type	Description
`Select`	`Select`	A SQLAlchemy `Select` object targeting the repository’s model class.