Hierarchy

The account hierarchy, and the resources that it shares.

Accounts form a tree (ADR-036). Each Account has a parent, and the Smarter account is the root: an account whose parent is null is directly under it. Separately from the tree, an account’s share_scope names the audience of its resources: itself or one of its ancestors, whose whole subtree may then read them. Null means that the account shares nothing.

A user profile may read the resources of an account X if the profile’s account is X, or descends from X.share_scope. This module computes that list of accounts, nearest first, caches it, and resolves a resource’s name against it.

from smarter.apps.account.hierarchy import readable_account_ids, resolve_by_name

account_ids = readable_account_ids(user_profile.account_id)
connection = resolve_by_name(SqlConnection.objects, "stackademy_hr", user_profile)
smarter.apps.account.hierarchy.MAX_ACCOUNT_TREE_DEPTH = 32

The deepest that the account tree may be.

An organization’s chart is a handful of levels deep. The limit guards the walk up the tree against a cycle that a direct database edit could create.

smarter.apps.account.hierarchy.READABLE_ACCOUNTS_CACHE_TIMEOUT = 3600

How long, in seconds, an account’s readable accounts are cached.

Account invalidates them whenever the tree or its sharing changes, so the timeout only bounds how long a direct database edit that bypasses Account.save() goes unnoticed.

smarter.apps.account.hierarchy.ancestor_ids(account_id)[source]

The account and its ancestors, nearest first, ending with the root.

It reads the database, not the cache, so that Account.save() can validate a change to the tree against the tree as it is.

Parameters:

account_id (int) – The account’s id.

Return type:

list[int]

Returns:

[account_id, parent_id, grandparent_id, ..., root_id]. An account whose parent is null is directly under the root. The root’s own list is [root_id].

Raises:

ValueError – if the walk up the tree meets an account twice, or goes deeper than MAX_ACCOUNT_TREE_DEPTH.

smarter.apps.account.hierarchy.invalidate_readable_account_ids()[source]

Forget every account’s readable accounts.

A change to one account’s parent or share_scope can change what the members of any other account may read, so every entry goes. The tree changes rarely, so this is cheap enough.

Return type:

None

smarter.apps.account.hierarchy.readable_account_ids(account_id)[source]

The accounts whose resources a member of this account may read, nearest first.

The account itself comes first. Then each account whose share_scope is this account or one of its ancestors, ordered by how near that share_scope is: an IT department that shares with its company comes before the Smarter account, which shares with everyone. Ties go to the lower id, so that the order is stable.

Cached until invalidate_readable_account_ids(), which Account calls whenever the tree or its sharing changes.

Parameters:

account_id (int) – The account’s id.

Return type:

tuple[int, ...]

Returns:

The ids of the readable accounts, nearest first.

smarter.apps.account.hierarchy.resolve_by_name(queryset, name, user_profile)[source]

The resource that a user profile means by name, in its account tree.

Nearest wins: the profile’s own resource, else its account’s, else that of the nearest account that shares with it (readable_account_ids()). Ties go to the most recently updated.

Only the profile’s own account tree counts, never what the user may read otherwise. A superuser reads every account, and a user with profiles in several accounts reads all of them, but a resource that names another, e.g. an HR department’s plugin that names a Connection, must find the same one whoever wrote it. Otherwise the members of HR would read, through the plugin, whatever its author can.

Parameters:
  • queryset (SmarterQuerySetWithPermissions) – The resources of one kind, e.g. SqlConnection.objects.

  • name (str) – The resource’s name.

  • user_profile (UserProfile) – The profile that names it, e.g. a plugin’s owner.

Return type:

TypeVar(_RT, bound= MetaDataWithOwnershipModel)

Returns:

The resource.

Raises:

django.core.exceptions.ObjectDoesNotExist – the model’s own DoesNotExist, which subclasses it, if no account in the profile’s tree has a resource of that name.

smarter.apps.account.hierarchy.root_account_id()[source]

The id of the root of the account tree, the Smarter account.

Return type:

int | None

Returns:

The Smarter account’s id, or None if this platform has not created it yet.