User Management Utilities
Relevant source files
The following files were used as context for generating this wiki page:
User Management Utilities provide the core logic for handling user identities, permissions, and roles within the FLEXT Auth system. These utilities are structured as a series of specialized manager classes that handle different aspects of the user lifecycle, including creation, retrieval (read), and modification (write).
The system follows a clean architecture pattern where operations are segregated into distinct modules to ensure high maintainability and type safety. These utilities interface with the internal storage mechanisms (typically a MutableMapping) to persist and manipulate user data, ensuring that all changes are tracked and validated.
Sources: src/flext_auth/_utilities/_managers/user_write.py, src/flext_auth/_utilities/_managers/user_read.py, src/flext_auth/_utilities/_managers/user_create.py
Architecture and Manager Hierarchy
The User Management system is built on a hierarchical inheritance model. This structure allows for the incremental addition of functionality while maintaining a shared base for data access.
Class Inheritance Structure
The hierarchy starts with the base user manager and extends into specific read and write operations.
This diagram illustrates how specific mutation and creation logic inherits from the core read and management base.
Sources: src/flext_auth/_utilities/_managers/user_write.py:15, src/flext_auth/_utilities/_managers/user_read.py:10, src/flext_auth/_utilities/_managers/user_create.py:10, src/flext_auth/_utilities/_managers/user.py:10
Mutation and Write Operations
The FlextAuthUserManagerWrite class handles all modifications to existing user records. It includes methods for updating scalar fields and managing list-based attributes like roles and permissions.
User Data Modification Flow
When a user attribute is updated, the system filters for non-null values and automatically updates the updated_at timestamp using internal utility helpers.
The flow ensures that only valid data is persisted and that metadata remains accurate.
Sources: src/flext_auth/_utilities/_managers/user_write.py:53-65
Key Write Functions
| Function | Purpose | Return Type |
|---|---|---|
add_user_role | Adds a specific role string to the user's role list. | p.Result[bool] |
remove_user_permission | Removes a permission string from the user's permission list. | p.Result[bool] |
update_user | Performs a bulk update of user attributes (name, contact, etc.). | p.Result[m.Auth.AuthIdentity] |
delete_user | Permanently removes a user from the internal storage mapping. | p.Result[bool] |
Sources: src/flext_auth/_utilities/_managers/user_write.py:20-51
Shared Utility Logic
The system utilizes a generic list modifier to handle various list-based fields (roles, permissions) without duplicating logic.
def _modify_user_list_field(
self,
user_id: str,
field: str,
value: str,
*,
add: bool = True,
) -> p.Result[bool]:
"""Add or remove value from user list field (roles/permissions)."""
user_result = self._find_user_by_id(user_id)
if user_result.failure:
return r[bool].fail(user_result.error or "User not found")
_, user_data = user_result.unwrap()
self._apply_list_modification(user_data, field, value, add=add)
return r[bool].ok(True)
Sources: src/flext_auth/_utilities/_managers/user_write.py:89-105
Lazy Loading and Exporting
To optimize performance and resource usage, the User Management Utilities are integrated into a lazy loading system via flext_core.lazy. This ensures that manager classes are only instantiated when actually requested by the application.
- Lazy Import Map: Maps internal paths like
._managers.user_writeto the public class nameFlextAuthUserManagerWrite. - Module Namespace: The
__init__.pyfile in the utilities package manages these exports while excluding internal diagnostic or testing hooks.
Sources: src/flext_auth/_utilities/init.py:42-72
Summary
The User Management Utilities form a robust backbone for identity operations in FLEXT Auth. By segregating read, write, and create responsibilities into a typed hierarchy, the system maintains strict control over user data integrity. Features like automatic timestamping, atomic list modifications, and lazy loading ensure that the utilities are both performant and reliable for enterprise-grade authentication workflows.