Core API

general_manager.manager.general_manager.GeneralManager

identification property

identification

Return the identification dictionary used to fetch the managed object.

__init__

__init__(*args, **kwargs)

Create a manager by constructing its Interface and record the resulting identification.

Parameters:

Name	Type	Description	Default
*args	Any	Positional arguments forwarded to the Interface constructor.	()
**kwargs	Any	Keyword arguments forwarded to the Interface constructor.	{}

__str__

__str__()

Return a user-friendly representation showing the identification.

__repr__

__repr__()

Return a detailed representation of the manager instance.

__reduce__

__reduce__()

Provide pickling support for the manager instance.

Returns:

Type	Description
str | tuple[Any, ...]	tuple[Any, ...]: Reconstruction data consisting of the class and identification tuple.

__or__

__or__(other)

Combine this manager with another manager or a Bucket into a Bucket representing their union.

Parameters:

Name	Type	Description	Default
other	Self | Bucket[Self]	A manager of the same class or a Bucket to union with.	required

Returns:

Type	Description
Bucket[Self]	Bucket[Self]: A Bucket containing the union of the managed objects represented by this manager and other.

Raises:

Type	Description
UnsupportedUnionOperandError	If other is not a Bucket and not a GeneralManager instance of the same class.

__eq__

__eq__(other)

Determine whether another object represents the same managed entity.

Returns:

Type	Description
bool	true if other is a GeneralManager whose identification equals this manager's, false otherwise.

__iter__

__iter__()

Iterate over attribute names and resolved values for the managed object.

create classmethod

create(
    creator_id=None,
    history_comment=None,
    ignore_permission=False,
    **kwargs
)

Create a new managed object through the interface.

Parameters:

Name	Type	Description	Default
creator_id	int | None	Optional identifier of the creating user.	None
history_comment	str | None	Audit comment stored with the change.	None
ignore_permission	bool	When True, skip permission validation.	False
**kwargs	Any	Additional fields forwarded to the interface create method.	{}

Returns:

Name	Type	Description
Self	Self	Manager instance representing the created object.

Raises:

Type	Description
PermissionError	Propagated if the permission check fails.

update

update(
    creator_id=None,
    history_comment=None,
    ignore_permission=False,
    **kwargs
)

Update the managed object, refresh this manager in place, and return it.

Parameters:

Name	Type	Description	Default
creator_id	int | None	Optional identifier of the user performing the update.	None
history_comment	str | None	Optional audit comment recorded with the update.	None
ignore_permission	bool	If True, skip permission validation.	False
**kwargs	Any	Field updates forwarded to the interface.	{}

Returns:

Name	Type	Description
Self	Self	This manager instance after reloading its backing interface state.

Raises:

Type	Description
PermissionError	If the permission check fails when ignore_permission is False.

delete

delete(
    creator_id=None,
    history_comment=None,
    ignore_permission=False,
)

Delete the managed object; performs a soft delete when the underlying interface is configured accordingly.

Parameters:

Name	Type	Description	Default
creator_id	int | None	Optional identifier of the user performing the action.	None
history_comment	str | None	Audit comment recorded with the deletion.	None
ignore_permission	bool	When True, skip permission validation.	False

Raises:

Type	Description
PermissionError	If permission validation fails.

filter classmethod

filter(**kwargs)

Get a Bucket of managers matching the provided lookup expressions.

Lookup expressions may include GeneralManager instances (or iterables of them), which are substituted with their identification mappings before being forwarded to the Interface for filtering.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Lookup expressions (Django-style) used to filter managers.	{}

Returns:

Type	Description
Bucket[Self]	Bucket[Self]: Bucket containing manager instances that match the lookups.

exclude classmethod

exclude(**kwargs)

Return a bucket excluding managers that match the provided lookups.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Django-style exclusion expressions forwarded to the interface.	{}

Returns:

Type	Description
Bucket[Self]	Bucket[Self]: Bucket of manager instances that do not satisfy the lookups.

all classmethod

all()

Return a bucket containing every managed object of this class.

__parse_identification staticmethod

__parse_identification(kwargs)

Replace manager instances within a filter mapping by their identifications.

Parameters:

Name	Type	Description	Default
kwargs	dict[str, Any]	Mapping containing potential manager instances.	required

Returns:

Type	Description
dict[str, Any] | None	dict[str, Any] | None: Mapping with managers substituted by identification dictionaries, or None if no substitutions occurred.

general_manager.bucket.base_bucket.Bucket

Bases: ABC, Generic[GeneralManagerType]

Abstract interface for lazily evaluated GeneralManager collections.

__init__

__init__(manager_class)

Create a bucket bound to a specific manager class.

Parameters:

Name	Type	Description	Default
manager_class	type[GeneralManagerType]	GeneralManager subclass whose instances this bucket represents.	required

Returns:

Type	Description
None	None

__eq__

__eq__(other)

Compare two buckets for equality.

Parameters:

Name	Type	Description	Default
other	object	Object tested for equality with this bucket.	required

Returns:

Name	Type	Description
bool	bool	True when the buckets share the same class, manager class, and data payload.

__reduce__

__reduce__()

Provide pickling support by returning the constructor and arguments.

Returns:

Type	Description
str | tuple[Any, ...]	tuple[Any, ...]: Data allowing the bucket to be reconstructed during unpickling.

__or__ abstractmethod

__or__(other)

Return a bucket containing the union of this bucket and another input.

Parameters:

Name	Type	Description	Default
other	Bucket[GeneralManagerType] | GeneralManagerType	Bucket or single manager instance to merge.	required

Returns:

Type	Description
Bucket[GeneralManagerType]	Bucket[GeneralManagerType]: New bucket with the combined contents.

__iter__ abstractmethod

__iter__()

Iterate over items in the bucket.

Yields:

Name	Type	Description
GeneralManagerType	GeneralManagerType	Items stored in the bucket.

filter abstractmethod

filter(**kwargs)

Return a bucket reduced to items matching the provided filters.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Field lookups applied to the underlying query.	{}

Returns:

Type	Description
Bucket[GeneralManagerType]	Bucket[GeneralManagerType]: Filtered bucket instance.

exclude abstractmethod

exclude(**kwargs)

Return a bucket that excludes items matching the provided filters.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Field lookups specifying records to remove from the result.	{}

Returns:

Type	Description
Bucket[GeneralManagerType]	Bucket[GeneralManagerType]: Bucket with the specified records excluded.

first abstractmethod

first()

Return the first item contained in the bucket.

Returns:

Type	Description
GeneralManagerType | None	GeneralManagerType | None: First entry if present, otherwise None.

last abstractmethod

last()

Return the last item contained in the bucket.

Returns:

Type	Description
GeneralManagerType | None	GeneralManagerType | None: Last entry if present, otherwise None.

count abstractmethod

count()

Return the number of items represented by the bucket.

Returns:

Name	Type	Description
int	int	Count of items.

all abstractmethod

all()

Return a bucket encompassing every item managed by this instance.

Returns:

Type	Description
Bucket[GeneralManagerType]	Bucket[GeneralManagerType]: Bucket without filters or exclusions.

get abstractmethod

get(**kwargs)

Retrieve a single item matching the provided criteria.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Field lookups identifying the target record.	{}

Returns:

Name	Type	Description
GeneralManagerType	GeneralManagerType	Matching item.

__getitem__ abstractmethod

__getitem__(item)

Retrieve an item or slice from the bucket.

Parameters:

Name	Type	Description	Default
item	int | slice	Index or slice specifying the desired record(s).	required

Returns:

Type	Description
GeneralManagerType | Bucket[GeneralManagerType]	GeneralManagerType | Bucket[GeneralManagerType]: Resulting item or bucket slice.

__len__ abstractmethod

__len__()

Return the number of items contained in the bucket.

Returns:

Name	Type	Description
int	int	Count of elements.

__contains__ abstractmethod

__contains__(item)

Checks whether the specified item is present in the bucket.

Parameters:

Name	Type	Description	Default
item	GeneralManagerType	Manager instance evaluated for membership.	required

Returns:

Name	Type	Description
bool	bool	True if the bucket contains the provided instance.

sort abstractmethod

sort(key, reverse=False)

Return a sorted bucket.

Parameters:

Name	Type	Description	Default
key	str | tuple[str, ...]	Attribute name(s) used for sorting.	required
reverse	bool	Whether to sort in descending order.	False

Returns:

Type	Description
Bucket[GeneralManagerType]	Bucket[GeneralManagerType]: Sorted bucket instance.

group_by

group_by(*group_by_keys)

Materialise a grouped view of the bucket.

Parameters:

Name	Type	Description	Default
*group_by_keys	str	Attribute names used to form groups.	()

Returns:

Type	Description
GroupBucket[GeneralManagerType]	GroupBucket[GeneralManagerType]: Bucket grouping items by the provided keys.

none

none()

Return an empty bucket instance.

Returns:

Type	Description
Bucket[GeneralManagerType]	Bucket[GeneralManagerType]: Empty bucket.

Raises:

Type	Description
NotImplementedError	Always raised by the base implementation; subclasses must provide a concrete version.

general_manager.bucket.database_bucket.DatabaseBucket

Bases: Bucket[GeneralManagerType]

Bucket implementation backed by Django ORM querysets.

__init__

__init__(
    data,
    manager_class,
    filter_definitions=None,
    exclude_definitions=None,
    *,
    search_date=None
)

Instantiate a database-backed bucket with optional filter state.

Parameters:

Name	Type	Description	Default
data	QuerySet[modelsModel]	Queryset providing the underlying data.	required
manager_class	type[GeneralManagerType]	GeneralManager subclass used to wrap rows.	required
filter_definitions	dict[str, list[Any]] | None	Pre-existing filter expressions captured from parent buckets.	None
exclude_definitions	dict[str, list[Any]] | None	Pre-existing exclusion expressions captured from parent buckets.	None
search_date	datetime | date | None	Optional timestamp applied when instantiating manager instances.	None

Returns:

Type	Description
None	None

__iter__

__iter__()

Iterate over manager instances corresponding to the queryset rows.

Yields:

Name	Type	Description
GeneralManagerType	GeneralManagerType	Manager instance for each primary key in the queryset.

__or__

__or__(other)

Produce a new DatabaseBucket representing the union of this bucket with another DatabaseBucket or a GeneralManager instance of the same manager class.

Parameters:

Name	Type	Description	Default
other	Bucket[GeneralManagerType] | GeneralManagerType	The bucket or manager instance to merge with this bucket.	required

Returns:

Type	Description
DatabaseBucket[GeneralManagerType]	DatabaseBucket[GeneralManagerType]: A new bucket containing the combined items from both operands.

Raises:

Type	Description
DatabaseBucketTypeMismatchError	If other is not a DatabaseBucket of the same class and not a compatible GeneralManager.
DatabaseBucketManagerMismatchError	If other is a DatabaseBucket but uses a different manager class.

__merge_filter_definitions

__merge_filter_definitions(basis, **kwargs)

Merge stored filter definitions with additional lookup values.

Parameters:

Name	Type	Description	Default
basis	dict[str, list[Any]]	Existing lookup definitions copied into the result.	required
**kwargs	Any	New lookups whose values are appended to the result mapping.	{}

Returns:

Type	Description
dict[str, list[Any]]	dict[str, list[Any]]: Combined mapping of lookups to value lists.

__parse_filter_definitions

__parse_filter_definitions(**kwargs)

Split provided filter kwargs into three parts: query annotations required by properties, ORM-compatible lookup mappings, and Python-evaluated filter specifications.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Filter lookups supplied to filter or exclude.	{}

Returns:

Name	Type	Description
tuple	tuple[dict[str, Any], dict[str, Any], list[tuple[str, Any, str]]]	annotations (dict[str, Any]): Mapping from property name to its query_annotation (callable or annotation object) for properties that require ORM annotations. orm_kwargs (dict[str, list[Any]]): Mapping of ORM lookup strings (e.g., "field__lookup") to their values to be passed to the queryset. python_filters (list[tuple[str, Any, str]]): List of tuples (lookup, value, root_property_name) for properties that must be evaluated in Python.

Raises:

Type	Description
NonFilterablePropertyError	If a lookup targets a property that is not allowed to be filtered.

__parse_python_filters

__parse_python_filters(query_set, python_filters)

Evaluate Python-only filters and return the primary keys that satisfy them.

Parameters:

Name	Type	Description	Default
query_set	QuerySet	Queryset to inspect.	required
python_filters	list[tuple[str, Any, str]]	Filters requiring Python evaluation, each containing the lookup, value, and property root.	required

Returns:

Type	Description
list[int]	list[int]: Primary keys of rows that meet all Python-evaluated filters.

filter

filter(**kwargs)

Return a new DatabaseBucket refined by the given Django-style lookup expressions.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Django-style lookup expressions to apply to the underlying queryset.	{}

Returns:

Type	Description
DatabaseBucket[GeneralManagerType]	DatabaseBucket[GeneralManagerType]: New bucket containing items matching the existing state combined with the provided lookups.

Raises:

Type	Description
NonFilterablePropertyError	If a provided property is not filterable for this manager.
InvalidQueryAnnotationTypeError	If a query-annotation callback returns a non-QuerySet.
QuerysetFilteringError	If the ORM rejects the filter arguments or filtering fails.

exclude

exclude(**kwargs)

Produce a bucket that excludes rows matching the provided Django-style lookup expressions.

Accepts ORM lookups, query annotation entries, and Python-only filters; annotation callables will be applied to the underlying queryset as needed.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Django-style lookup expressions, annotation entries, or property-based filters used to identify records to exclude.	{}

Returns:

Type	Description
DatabaseBucket[GeneralManagerType]	DatabaseBucket[GeneralManagerType]: A new bucket whose queryset omits rows matching the provided lookups.

Raises:

Type	Description
InvalidQueryAnnotationTypeError	If an annotation callable is applied and does not return a Django QuerySet.

first

first()

Return the first row in the queryset as a manager instance.

Returns:

Type	Description
GeneralManagerType | None	GeneralManagerType | None: First manager instance if available.

last

last()

Return the last row in the queryset as a manager instance.

Returns:

Type	Description
GeneralManagerType | None	GeneralManagerType | None: Last manager instance if available.

count

count()

Count the number of rows represented by the bucket.

Returns:

Name	Type	Description
int	int	Number of queryset rows.

all

all()

Return a bucket materialising the queryset without further filtering.

Returns:

Type	Description
DatabaseBucket[GeneralManagerType]	DatabaseBucket[GeneralManagerType]: Bucket encapsulating self._data.all().

get

get(**kwargs)

Retrieve a single manager instance matching the provided lookups.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Field lookups resolved via QuerySet.get.	{}

Returns:

Name	Type	Description
GeneralManagerType	GeneralManagerType	Manager instance wrapping the matched model.

Raises:

Type	Description
ObjectDoesNotExist	Propagated from the underlying queryset when no row matches.
MultipleObjectsReturned	Propagated when multiple rows satisfy the lookup.

__getitem__

__getitem__(item)

Access manager instances by index or obtain a sliced bucket.

Parameters:

Name	Type	Description	Default
item	int | slice	Index of the desired row or slice object describing a range.	required

Returns:

Type	Description
GeneralManagerType | DatabaseBucket[GeneralManagerType]	GeneralManagerType | DatabaseBucket[GeneralManagerType]: Manager instance for single indices or bucket wrapping the sliced queryset.

__len__

__len__()

Return the number of rows represented by the bucket.

Returns:

Name	Type	Description
int	int	Size of the queryset.

__str__

__str__()

Return a user-friendly representation of the bucket.

Returns:

Name	Type	Description
str	str	Human-readable description of the queryset and manager class.

__repr__

__repr__()

Return a debug representation of the bucket.

Returns:

Name	Type	Description
str	str	Detailed description including queryset, manager class, filters, and excludes.

__contains__

__contains__(item)

Determine whether the provided instance belongs to the bucket.

Parameters:

Name	Type	Description	Default
item	GeneralManagerType | Model	Manager or model instance whose primary key is checked.	required

Returns:

Name	Type	Description
bool	bool	True when the primary key exists in the queryset.

sort

sort(key, reverse=False)

Return a new DatabaseBucket ordered by the given property name(s).

Accepts a single property name or a tuple of property names. Properties with ORM annotations are applied at the database level; properties without ORM annotations are evaluated in Python and the resulting records are re-ordered while preserving a queryset result. Stable ordering and preservation of manager wrapping are maintained.

Parameters:

Name	Type	Description	Default
key	str | tuple[str, ...]	Property name or sequence of property names to sort by, applied in order of appearance.	required
reverse	bool	If True, sort each specified key in descending order.	False

Returns:

Name	Type	Description
DatabaseBucket	DatabaseBucket	A new bucket whose underlying queryset is ordered according to the requested keys.

Raises:

Type	Description
NonSortablePropertyError	If any requested property is not marked as sortable on the manager's GraphQL properties.
InvalidQueryAnnotationTypeError	If a property query annotation callable returns a non-QuerySet value.
QuerysetOrderingError	If the ORM rejects the constructed ordering (e.g., invalid field or incompatible ordering expression).

none

none()

Return an empty bucket sharing the same manager class.

Returns:

Type	Description
DatabaseBucket[GeneralManagerType]	DatabaseBucket[GeneralManagerType]: Empty bucket retaining filter and exclude state.

general_manager.manager.group_manager.GroupManager

Bases: Generic[GeneralManagerType]

Represent aggregated results for grouped GeneralManager records.

__init__

__init__(manager_class, group_by_value, data)

Initialise a grouped manager with the underlying bucket and grouping keys.

Parameters:

Name	Type	Description	Default
manager_class	type[GeneralManagerType]	Manager subclass whose records were grouped.	required
group_by_value	dict[str, Any]	Key values describing this group.	required
data	Bucket[GeneralManagerType]	Bucket of records belonging to the group.	required

Returns:

Type	Description
None	None

__hash__

__hash__()

Return a stable hash based on the manager class, keys, and grouped data.

Returns:

Name	Type	Description
int	int	Hash value combining class, keys, and data.

__eq__

__eq__(other)

Compare grouped managers by manager class, keys, and grouped data.

Parameters:

Name	Type	Description	Default
other	object	Object to compare against.	required

Returns:

Name	Type	Description
bool	bool	True when both grouped managers describe the same data.

__repr__

__repr__()

Return a debug representation showing grouped keys and data.

Returns:

Name	Type	Description
str	str	Debug string summarising the grouped manager.

__iter__

__iter__()

Iterate over attribute names and their aggregated values.

Yields:

Type	Description
tuple[str, Any]	tuple[str, Any]: Attribute name and aggregated value pairs.

__getattr__

__getattr__(item)

Lazily compute aggregated attribute values when accessed.

Parameters:

Name	Type	Description	Default
item	str	Attribute name requested by the caller.	required

Returns:

Name	Type	Description
Any	Any	Aggregated value stored for the given attribute.

Raises:

Type	Description
AttributeError	If the attribute cannot be resolved from group data.

combine_value

combine_value(item)

Aggregate the values of a named attribute across all records in the group.

Parameters:

Name	Type	Description	Default
item	str	Attribute name to aggregate from each grouped record.	required

Returns:

Name	Type	Description
Any	Any	The aggregated value for item according to its type (e.g., merged Bucket/GeneralManager, concatenated list, merged dict, deduplicated comma-separated string, boolean OR, numeric sum, or latest datetime). Returns None if all values are None or if item is "id".

Raises:

Type	Description
MissingGroupAttributeError	If the attribute does not exist or its type cannot be determined on the manager.

general_manager.manager.input.Input

Bases: Generic[INPUT_TYPE]

Descriptor describing the expected type and constraints for an interface input.

__init__

__init__(
    type,
    possible_values=None,
    depends_on=None,
    *,
    required=True,
    min_value=None,
    max_value=None,
    validator=None,
    normalizer=None
)

Create an Input specification with type information, constraints, and dependency metadata.

Parameters:

Name	Type	Description	Default
type	INPUT_TYPE	Expected Python type for the input value.	required
possible_values	PossibleValues | None	Allowed values as a domain, iterable, bucket, or callable returning one.	None
depends_on	list[str] | None	Names of other inputs required for dynamic constraints.	None
required	bool	Whether callers must provide a value for this input.	True
min_value	ScalarConstraint | None	Inclusive lower bound for scalar values.	None
max_value	ScalarConstraint | None	Inclusive upper bound for scalar values.	None
validator	Validator | None	Extra validation callback returning True/False or None.	None
normalizer	Normalizer | None	Optional callback used to canonicalize values after casting.	None

date_range classmethod

date_range(
    *,
    start,
    end,
    frequency="day",
    step=1,
    depends_on=None,
    required=True
)

Create a date input backed by a structured date range domain.

monthly_date classmethod

monthly_date(
    *,
    start,
    end,
    anchor="month_end",
    step=1,
    depends_on=None,
    required=True
)

Create a date input constrained to canonical monthly dates.

yearly_date classmethod

yearly_date(
    *,
    start,
    end,
    anchor="year_end",
    step=1,
    depends_on=None,
    required=True
)

Create a date input constrained to canonical yearly dates.

from_manager_query classmethod

from_manager_query(
    manager_type,
    *,
    query=None,
    depends_on=None,
    required=True
)

Create a manager input whose possible values come from a manager query.

resolve_possible_values

resolve_possible_values(identification=None)

Resolve the configured possible values for the current dependency context.

normalize

normalize(value, identification=None)

Canonicalize a cast value using domain or explicit normalization rules.

validate_bounds

validate_bounds(value)

Return whether a value satisfies configured scalar bounds.

validate_with_callable

validate_with_callable(value, identification=None)

Return whether a value satisfies the configured validator callback.

cast

cast(value, identification=None)

Convert a raw value to the configured input type.

Parameters:

Name	Type	Description	Default
value	Any	Raw value supplied by the caller.	required
identification	dict[str, Any] | None	Dependency values used by normalizers.	None

Returns:

Name	Type	Description
Any	Any	Value converted to the target type.

Raises:

Type	Description
ValueError	If the value cannot be converted to the target type.

general_manager.rule.rule.Rule

Bases: Generic[GeneralManagerType]

Encapsulate a boolean predicate and derive contextual error messages from its AST.

When the predicate evaluates to False, the rule inspects the parsed abstract syntax tree to determine which variables failed and crafts either autogenerated or custom error messages.

__init__

__init__(
    func, custom_error_message=None, ignore_if_none=True
)

Initialize a Rule that wraps a predicate function, captures its source AST to discover referenced variables, and prepares handlers for generating error messages.

Parameters:

Name	Type	Description	Default
func	Callable[[GeneralManagerType], bool]	Predicate that evaluates a GeneralManager instance.	required
custom_error_message	Optional[str]	Optional template used to format generated error messages; placeholders must match variables referenced by the predicate.	None
ignore_if_none	bool	If True, evaluation will be skipped (result recorded as None) when any referenced variable resolves to None.	True

evaluate

evaluate(x)

Evaluate the rule's predicate against a GeneralManager instance and record evaluation context.

Binds the primary parameter to the provided input, extracts referenced variable values, and sets the last evaluation result to the predicate outcome. If ignore_if_none is true and any referenced variable value is None, the evaluation is skipped and the last result is set to None.

Parameters:

Name	Type	Description	Default
x	GeneralManagerType	Manager instance supplied to the predicate.	required

Returns:

Type	Description
Optional[bool]	True if the predicate evaluates to true, False if it evaluates to false, None if evaluation was skipped because a referenced value was None and ignore_if_none is enabled.

validate_custom_error_message

validate_custom_error_message()

Validate that a provided custom error message template includes placeholders for every variable referenced by the rule.

Raises:

Type	Description
MissingErrorTemplateVariableError	If one or more extracted variables are not present as {name} placeholders in the custom template.

get_error_message

get_error_message()

Constructs error messages for the last failed evaluation and returns them keyed by variable name.

Returns:

Type	Description
Optional[Dict[str, str]]	dict[str, str] | None: Mapping from each referenced variable name to its error message, or None if the predicate passed or was not evaluated.

Raises:

Type	Description
ErrorMessageGenerationError	If called before any input has been evaluated.