Utils

Account Utilities

This module provides foundational utilities for accessing, managing, and caching account and user data in the Smarter platform. It is the base model for all Django ORM operations in the project, and is designed for both performance and reliability.

Caching Overview

Two caching strategies are used:

LRU In-Memory Caching: Fast, per-process caching for frequently accessed objects such as User, Account, and UserProfile. Scope: Only available within the current process; short-lived.
Redis-Based ORM Caching: Persistent, cross-process caching for Django ORM objects. Scope: Shared across all processes; cache lifetime is controlled by expiration settings.

smarter.apps.account.utils.account_number_from_url(invalidate=False, url=None)[source]

Extract the account number from a Smarter platform URL, using caching for performance.

Parameters:

url (Optional[str]) – String. The URL to parse for an account number.
invalidate (Optional[bool]) – Boolean, optional. If True, invalidates the cache before fetching.

Return type:

Optional[str]

Returns:

The extracted account number as a string, or None if not found.

Note

The function validates the URL format before extraction.

Warning

If the URL does not contain a valid account number, None is returned.

Tip

Use invalidate=True after updating URLs or account number patterns to ensure cache consistency.

Example usage:

# Extract account number from a URL
account_number = account_number_from_url("https://hr.3141-5926-5359.alpha.api.example.com/")

# Result: '3141-5926-5359'

# Invalidate cache before fetching
account_number = account_number_from_url("https://hr.3141-5926-5359.alpha.api.example.com/", invalidate=True)

smarter.apps.account.utils.get_cached_account_for_user(invalidate=False, user=None)[source]

Locate the Account associated with a given user, using caching for performance.

Parameters:

user (Optional[User]) – User instance. The user whose account should be located.
invalidate (Optional[bool]) – Boolean, optional. If True, invalidates the cache before fetching.

Return type:

Account

Returns:

Account instance if found, otherwise None.

Warning

If no account is found for the user, None is returned and a warning is logged.

Tip

Use invalidate=True after updating user or account data to ensure cache consistency.

Example usage:

# Locate account for a user
account = get_cached_account_for_user(user)
# Invalidate cache before fetching
account = get_cached_account_for_user(user, invalidate=True)

smarter.apps.account.utils.get_cached_admin_user_for_account(account, invalidate=False)[source]

Retrieve the admin user for a given account, creating one if necessary.

Parameters:

account (Account) – Account instance. The account for which to retrieve the admin user.
invalidate (Optional[bool]) – Boolean, optional. If True, invalidates the cache before fetching.

Return type:

User

Returns:

User instance representing the account admin.

Important

If no admin user exists for the account, a new staff user and UserProfile will be created automatically.

Warning

If the account is missing or misconfigured, an exception is raised.

Tip

Use invalidate=True after updating admin user data to ensure cache consistency.

Example usage:

# Retrieve the admin user for an account
admin_user = get_cached_admin_user_for_account(account=account)

# Invalidate cache before fetching
admin_user = get_cached_admin_user_for_account(invalidate=True, account=account)

smarter.apps.account.utils.get_cached_default_account(invalidate=False)[source]

Retrieve the default account instance, using caching for performance.

Parameters:: invalidate (bool) – Boolean, optional. If True, invalidates the cache before fetching.
Return type:: Account
Returns:: The default Account instance.

Important

The default account is determined by the is_default_account=True flag in the database.

Warning

If no default account exists, an exception may be raised.

Example usage:

# Get the default account
default_account = get_cached_default_account()

# Invalidate cache before fetching
default_account = get_cached_default_account(invalidate=True)

smarter.apps.account.utils.get_cached_smarter_admin_user_profile()[source]

Retrieve the admin UserProfile for the smarter account, using caching for performance.

Return type:: UserProfile
Returns:: UserProfile instance for the smarter admin user.

Note

The smarter admin user is typically a superuser or staff user associated with the platform’s main account.

Example usage:

# Retrieve the smarter admin user profile
admin_profile = get_cached_smarter_admin_user_profile()

# Invalidate cache before fetching
admin_profile = get_cached_smarter_admin_user_profile(invalidate=True)

smarter.apps.account.utils.get_cached_user_for_user_id(invalidate=False, user_id=None)[source]

Retrieve a User instance by its primary key, using caching for performance.

Parameters:

user_id (Optional[int]) – Integer. The primary key of the user to retrieve.
invalidate (Optional[bool]) – Boolean, optional. If True, invalidates the cache before fetching.

Return type:

User

Returns:

User instance if found, otherwise None.

Warning

If no user exists for the given ID, None is returned and an error is logged.

Tip

Use invalidate=True after updating user data to ensure cache consistency.

Example usage:

# Retrieve user by ID
user = get_cached_user_for_user_id(user_id=123)

# Invalidate cache before fetching
user = get_cached_user_for_user_id(user_id=123, invalidate=True)

smarter.apps.account.utils.get_cached_user_for_username(invalidate=False, username=None)[source]

Retrieve a User instance by its username, using caching for performance.

Parameters:

username (Optional[str]) – String. The username of the user to retrieve.
invalidate (Optional[bool]) – Boolean, optional. If True, invalidates the cache before fetching.

Return type:

User

Returns:

User instance if found, otherwise None.

Warning

If no user exists for the given username, a User.DoesNotExist exception is raised and an error is logged.

Tip

Use invalidate=True after updating user data to ensure cache consistency.

Example usage:

# Retrieve user by username
user = get_cached_user_for_username("johndoe")

# Invalidate cache before fetching
user = get_cached_user_for_username("johndoe", invalidate=True)

smarter.apps.account.utils.get_user_profiles_for_account(account)[source]

Retrieve a list of user profiles associated with a given account.

Parameters:: account (Account) – Account instance. The account for which to retrieve user profiles.
Return type:: list[UserProfile]
Returns:: List of UserProfile instances, or None if no profiles exist.

Important

The account parameter is required. If not provided, an exception is raised.

Warning

If the account has no associated user profiles, None is returned.

Example usage:

# Get all user profiles for an account
profiles = get_user_profiles_for_account(account)

smarter.apps.account.utils.get_users_for_account(account)[source]

Retrieve a list of users associated with a given account.

Parameters:: account (Account) – Account instance. The account for which to retrieve users.
Return type:: list[User]
Returns:: List of User instances.

Important

The account parameter is required. If not provided, an exception is raised.

Warning

If the account has no associated users, an empty list is returned.

Example usage:

# Get all users for an account
users = get_users_for_account(account)

smarter.apps.account.utils.valid_resource_owners_for_user(user_profile)[source]

Get a list of valid owners for the given user profile.

This function retrieves all user profiles associated with the same account as the provided user profile. These profiles are considered valid owners for ORM resources created by the user.

Parameters:: user_profile (Optional[UserProfile]) – The UserProfile instance representing the user.
Returns:: A list of UserProfile instances that are valid ORM resource owners.
Return type:: list[UserProfile]