Utilities¶
sqlalchemy_history.utils
¶
Utility Functions
changeset(obj)
¶
Return a humanized changeset for given SQLAlchemy declarative object. With this function you can easily check the changeset of given object in current transaction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
|
required |
Returns:
| Type | Description |
|---|---|
dict[str, list[Any]]
|
this function you can easily check the changeset of given object in current transaction. |
count_versions(obj)
¶
Return the number of versions given object has. This function works even
when obj has create_models and create_tables versioned settings
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
SQLAlchemy declarative model object |
required |
Returns:
| Type | Description |
|---|---|
int
|
when obj has |
get_association_proxies(klass)
¶
Get Association proxy mappings for ORM Models
get_versioning_manager(item)
¶
Return the associated SQLAlchemy-History VersioningManager for given SQLAlchemy declarative model class or object or table.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
item
|
A declarative ORM object, declarative ORM class, or SQL table. |
required |
Returns:
| Type | Description |
|---|---|
VersioningManager
|
The versioning manager associated with |
is_internal_column(model, column_name)
¶
Return whether or not given column of given SQLAlchemy declarative classs is considered an internal column (a column whose purpose is mainly for SQLA-History's internal use).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
SQLAlchemy declarative model object or class. |
required | |
column_name
|
str
|
Name of the column. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Whether the column is managed internally by SQLAlchemy-History. |
is_modified(obj)
¶
Return whether or not the versioned properties of given object have been modified.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
SQLAlchemy declarative model object |
required |
Returns:
| Type | Description |
|---|---|
bool
|
modified. |
is_modified_or_deleted(obj)
¶
Return whether or not some of the versioned properties of given SQLAlchemy declarative object have been modified or if the object has been deleted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
SQLAlchemy declarative model object |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Bool |
is_session_modified(session)
¶
Return whether or not any of the versioned objects in given session have been either modified or deleted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
Session
|
SQLAlchemy session object |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Bool |
is_table_column(column)
¶
Return wheter of not give field is a column over the database table.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
column
|
SQLAclhemy model field |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Bool |
is_versioned(obj_or_class)
¶
Return whether or not given object is versioned.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_class
|
SQLAlchemy declarative model object or class. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Whether versioning is enabled for the object or class. |
option(obj_or_class, option_name)
¶
Return the option value of given option for given versioned object or class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_class
|
SQLAlchemy declarative model object or class |
required | |
option_name
|
str
|
The name of an option to return |
required |
parent_class(version_cls)
¶
Return the parent class for given version model class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
version_cls
|
SQLAlchemy declarative version model class. |
required |
Returns:
| Type | Description |
|---|---|
|
The corresponding parent model class. |
parent_table(version_table)
¶
Return corresponding parent table for any given parent table.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
version_table
|
Table
|
A versioned table table which could be either association_table or model_table. |
required |
transaction_class(cls)
¶
Return the associated transaction class for given versioned SQLAlchemy declarative class or version class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cls
|
SQLAlchemy versioned declarative class or version model class |
required |
Returns:
| Type | Description |
|---|---|
|
declarative class or version class. |
vacuum(session, model, yield_per=1000)
¶
When making structural changes to version tables (for example dropping columns) there are sometimes situations where some old version records become futile.
Vacuum deletes all futile version rows which had no changes compared to previous version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
Session
|
SQLAlchemy session object |
required |
model
|
SQLAlchemy declarative model class |
required | |
yield_per
|
int
|
how many rows to process at a time (Default value = 1000) |
1000
|
version_class(model)
¶
Return the version class for given SQLAlchemy declarative model class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
SQLAlchemy declarative model class |
required |
Returns:
| Type | Description |
|---|---|
|
|
version_table(table)
¶
Return associated version table for given SQLAlchemy Table object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
table
|
Table
|
SQLAlchemy Table object |
required |
versioned_column_properties(obj_or_class)
¶
Yield the versioned column properties for a model object or class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_class
|
SQLAlchemy declarative model object or class. |
required |
Returns:
| Type | Description |
|---|---|
Iterator[ColumnProperty]
|
An iterator of versioned column properties. |
versioned_objects(session)
¶
Return all versioned objects in given session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
Session
|
SQLAlchemy session object |
required |
changeset¶
sqlalchemy_history.utils.changeset(obj)
¶
Return a humanized changeset for given SQLAlchemy declarative object. With this function you can easily check the changeset of given object in current transaction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
|
required |
Returns:
| Type | Description |
|---|---|
dict[str, list[Any]]
|
this function you can easily check the changeset of given object in current transaction. |
count_versions¶
sqlalchemy_history.utils.count_versions(obj)
¶
Return the number of versions given object has. This function works even
when obj has create_models and create_tables versioned settings
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
SQLAlchemy declarative model object |
required |
Returns:
| Type | Description |
|---|---|
int
|
when obj has |
get_versioning_manager¶
sqlalchemy_history.utils.get_versioning_manager(item)
¶
Return the associated SQLAlchemy-History VersioningManager for given SQLAlchemy declarative model class or object or table.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
item
|
A declarative ORM object, declarative ORM class, or SQL table. |
required |
Returns:
| Type | Description |
|---|---|
VersioningManager
|
The versioning manager associated with |
is_modified¶
sqlalchemy_history.utils.is_modified(obj)
¶
Return whether or not the versioned properties of given object have been modified.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
SQLAlchemy declarative model object |
required |
Returns:
| Type | Description |
|---|---|
bool
|
modified. |
is_modified_or_deleted¶
sqlalchemy_history.utils.is_modified_or_deleted(obj)
¶
Return whether or not some of the versioned properties of given SQLAlchemy declarative object have been modified or if the object has been deleted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
SQLAlchemy declarative model object |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Bool |
is_session_modified¶
sqlalchemy_history.utils.is_session_modified(session)
¶
Return whether or not any of the versioned objects in given session have been either modified or deleted.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
Session
|
SQLAlchemy session object |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Bool |
is_versioned¶
sqlalchemy_history.utils.is_versioned(obj_or_class)
¶
Return whether or not given object is versioned.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj_or_class
|
SQLAlchemy declarative model object or class. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Whether versioning is enabled for the object or class. |
parent_class¶
sqlalchemy_history.utils.parent_class(version_cls)
¶
Return the parent class for given version model class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
version_cls
|
SQLAlchemy declarative version model class. |
required |
Returns:
| Type | Description |
|---|---|
|
The corresponding parent model class. |
transaction_class¶
sqlalchemy_history.utils.transaction_class(cls)
¶
Return the associated transaction class for given versioned SQLAlchemy declarative class or version class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cls
|
SQLAlchemy versioned declarative class or version model class |
required |
Returns:
| Type | Description |
|---|---|
|
declarative class or version class. |
version_class¶
sqlalchemy_history.utils.version_class(model)
¶
Return the version class for given SQLAlchemy declarative model class.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
SQLAlchemy declarative model class |
required |
Returns:
| Type | Description |
|---|---|
|
|
versioned_objects¶
sqlalchemy_history.utils.versioned_objects(session)
¶
Return all versioned objects in given session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
session
|
Session
|
SQLAlchemy session object |
required |
version_table¶
sqlalchemy_history.utils.version_table(table)
¶
Return associated version table for given SQLAlchemy Table object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
table
|
Table
|
SQLAlchemy Table object |
required |