Models 

Creates a new items of type INVENTORY.

Parameters:

name (str) – The name of the new service.
item_type (str) – The type of expense. A choice of ItemModel.ITEM_TYPE_CHOICES
uom_model – The UOM UUID or UnitOfMeasureModel of the Service. Will be validated if provided.
inventory_account (AccountModel) – Optional ASSET_CA_INVENTORY AccountModel associated with the new Expense Item. Defaults to ASSET_CA_INVENTORY default AccountModel role.
coa_model (ChartOfAccountModel) – Optional ChartOfAccountsModel to use when fetching default role AccountModels.
commit (bool) – Commits the ItemModel in the DB. Defaults to True.

Return type:

create_item_product(name: str, item_type: str, uom_model: UUID | UnitOfMeasureModel, coa_model: ChartOfAccountModel | UUID | str | None = None, commit: bool = True) → ItemModel

Creates a new items of type PRODUCT.

Parameters:

name (str) – Name of the new service.
item_type (str) – The type of product. A choice of ItemModel.ITEM_TYPE_CHOICES
uom_model – The UOM UUID or UnitOfMeasureModel of the Service. Will be validated if provided.
coa_model (ChartOfAccountModel) – Optional ChartOfAccountsModel to use when fetching default role AccountModels.
commit (bool) – Commits the ItemModel in the DB. Defaults to True.

Returns:

The created Product.

Return type:

create_item_service(name: str, uom_model: UUID | UnitOfMeasureModel, coa_model: ChartOfAccountModel | UUID | str | None = None, commit: bool = True) → ItemModel

Creates a new items of type SERVICE.

Parameters:

name (str) – Name of the new service.
uom_model – The UOM UUID or UnitOfMeasureModel of the Service. Will be validated if provided.
coa_model (ChartOfAccountModel) – Optional ChartOfAccountsModel to use when fetching default role AccountModels.
commit (bool) – Commits the ItemModel in the DB. Defaults to True.

Returns:

The created Service.

Return type:

create_purchase_order(po_title: str | None = None, estimate_model=None, date_draft: date | None = None, commit: bool = True)

Creates a new PurchaseOrderModel for the EntityModel instance. PO will have DRAFT status.

Parameters:

po_title (str) – The user defined title for the new Purchase Order Model.
date_draft (date) – Optional date to use as Draft Date. Defaults to localdate() if None.
estimate_model (EstimateModel) – The EstimateModel to associate the PO for tracking.
commit (bool) – If True, commits the new PO in the Database. Defaults to True.

Returns:

The newly created PurchaseOrderModel in DRAFT state.

Return type:

PurchaseOrderModel

create_uom(name: str, unit_abbr: str, active: bool = True, commit: bool = True) → UnitOfMeasureModel

Creates a new Unit of Measure Model associated with the EntityModel instance

Parameters:

name (str) – The user defined name of the new Unit of Measure Model instance.
unit_abbr (str) – The unique slug abbreviation of the UoM model. Will be indexed.
active (bool) – Mark this UoM as active.
commit (bool) – Saves the model in the DB if True. Defaults to True

Return type:

UnitOfMeasureModel

create_vendor(vendor_model_kwargs: Dict, commit: bool = True) → VendorModel

Creates a new VendorModel associated with the EntityModel instance.

Parameters:

vendor_model_kwargs (dict) – The kwargs to be used for the new VendorModel.
commit (bool) – Saves the VendorModel instance in the Database.

Return type:

VendorModel

generate_slug(commit: bool = False, raise_exception: bool = True, force_update: bool = False) → str

Convenience method to create the EntityModel slug.

Parameters:

force_update (bool) – If True, will update the EntityModel slug.
raise_exception (bool) – Raises ValidationError if EntityModel already has a slug.
commit (bool) – If True,

static generate_slug_from_name(name: str) → str

Uses Django’s slugify function to create a valid slug from any given string.

Parameters:: name (str) – The name or string to slugify.
Return type:: The slug as a String.

get_accounts_url() → str

The EntityModel Code of Accounts llist import URL.

Returns:: EntityModel Code of Accounts llist import URL as a string.
Return type:: str

Fetches the AccountModelQuerySet with provided code list.

Parameters:

coa_model (ChartOfAccountModel, UUID, str) – The ChartOfAccountsModel UUID, model instance or slug to pull accounts from. Uses default Coa if not provided.
code_list (list or str) – Code or list of codes to fetch.

Returns:

The requested AccountModelQuerySet with applied code filter.

Return type:

get_all_accounts(active: bool = True, order_by: Tuple[str] | None = ('code',)) → AccountModelQuerySet

Fetches all AccountModelQuerySet associated with the EntityModel.

Parameters:

active (bool) – Selects only active accounts.
order_by (list of strings.) – Optional list of fields passed to the order_by QuerySet method.

Returns:

The AccountModelQuerySet of the assigned default CoA.

Return type:

get_all_coa_accounts(order_by: Tuple[str] | None = ('code',), active: bool = True) → Tuple[ChartOfAccountModelQuerySet, Dict[ChartOfAccountModel, AccountModelQuerySet]]

Fetches all the AccountModels associated with the EntityModel grouped by ChartOfAccountModel.

Parameters:

active (bool) – Selects only active accounts.
order_by (list of strings.) – Optional list of fields passed to the order_by QuerySet method.

Returns:

Tuple – The ChartOfAccountModelQuerySet and a grouping of AccountModels by ChartOfAccountModel as keys.

Return type:

Tuple[ChartOfAccountModelQuerySet, Dict[ChartOfAccountModel, AccountModelQuerySet]

get_balance_sheet_url() → str

The EntityModel Balance Sheet Statement URL.

Returns:: EntityModel Balance Sheet Statement URL as a string.
Return type:: str

get_bank_accounts(active: bool = True) → BankAccountModelQuerySet

Fetches a QuerySet of BankAccountModels associated with the EntityModel instance.

Parameters:: active (bool) – If True, returns only active Bank Accounts. Defaults to True.
Return type:: BankAccountModelQuerySet

get_banks_url() → str

The EntityModel bank account list URL.

Returns:: EntityModel bank account list URL as a string.
Return type:: str

get_bills()

Fetches a QuerySet of BillModels associated with the EntityModel instance.

Return type:: BillModelQuerySet

get_bills_url() → str

The EntityModel bill list URL.

Returns:: EntityModel bill list URL as a string.
Return type:: str

get_cashflow_statement_url() → str

The EntityModel Cashflow Statement URL.

Returns:: EntityModel Cashflow Statement URL as a string.
Return type:: str

get_coa_accounts(coa_model: ChartOfAccountModel | UUID | str | None = None, active: bool = True, locked: bool = False, order_by: Tuple | None = ('code',), return_coa_model: bool = False) → AccountModelQuerySet | Tuple[ChartOfAccountModel, AccountModelQuerySet]

Fetches the AccountModelQuerySet for a specific ChartOfAccountModel.

Parameters:

coa_model (ChartOfAccountModel, UUID, str) – The ChartOfAccountsModel UUID, model instance or slug to pull accounts from. If None, will use default CoA.
active (bool) – Selects only active accounts.
locked (bool) – Selects only locked accounts.
order_by (list of strings.) – Optional list of fields passed to the order_by QuerySet method.

Returns:

The AccountModelQuerySet of the assigned default CoA.

Return type:

get_coa_model_qs(active: bool = True)

Fetches the current Entity Model instance Chart of Accounts Model Queryset.

Parameters:: active (bool) – Returns only active Chart of Account Models. Defaults to True.
Return type:: ChartOfAccountModelQuerySet

get_customers(active: bool = True) → CustomerModelQueryset

Fetches the CustomerModel associated with the EntityModel instance.

Parameters:: active (bool) – Active CustomerModel only. Defaults to True.
Returns:: The EntityModel instance CustomerModelQueryset with applied filters.
Return type:: CustomerModelQueryset

get_customers_url() → str

The EntityModel customers list URL.

Returns:: EntityModel customers list URL as a string.
Return type:: str

get_dashboard_url() → str

The EntityModel Dashboard URL.

Returns:: EntityModel dashboard URL as a string.
Return type:: str

get_data_import_url() → str

The EntityModel transaction import URL.

Returns:: EntityModel transaction import URL as a string.
Return type:: str

get_default_account_for_role(role: str, coa_model: ChartOfAccountModel | None = None) → AccountModel

Gets the given role default AccountModel from the provided CoA. CoA will be validated against the EntityModel instance.

Parameters:

role (str) – The CoA role to fetch the corresponding default Account Model.
coa_model (ChartOfAccountModel) – The CoA Model to pull default account from. If not provided, will use EntityModel default CoA.

Returns:

The default account model for the specified CoA role.

Return type:

get_default_coa(raise_exception: bool = True) → ChartOfAccountModel | None

Fetches the EntityModel default Chart of Account.

Parameters:: raise_exception (bool) – Raises exception if no default CoA has been assigned.
Returns:: The EntityModel default ChartOfAccount.
Return type:: ChartOfAccountModel

get_default_coa_accounts(active: bool = True, order_by: Tuple[str] | None = ('code',), raise_exception: bool = True) → AccountModelQuerySet | None

Fetches the default AccountModelQuerySet.

Parameters:

active (bool) – Selects only active accounts.
order_by (list of strings.) – Optional list of fields passed to the order_by QuerySet method.
raise_exception (bool) – Raises EntityModelValidationError if no default_coa found.

Returns:

The AccountModelQuerySet of the assigned default CoA.

Return type:

get_delete_url() → str

The EntityModel delete URL.

Returns:: EntityModel delete URL as a string.
Return type:: str

get_estimates()

Fetches a QuerySet of EstimateModels associated with the EntityModel instance.

Return type:: EstimateModelQuerySet

get_income_statement_url() → str

The EntityModel Income Statement URL.

Returns:: EntityModel Income Statement URL as a string.
Return type:: str

get_invoices()

Fetches a QuerySet of InvoiceModels associated with the EntityModel instance.

Return type:: InvoiceModelQuerySet

get_invoices_url() → str

The EntityModel invoice list URL.

Returns:: EntityModel invoice list URL as a string.
Return type:: str

get_items_all(active: bool = True) → ItemModelQuerySet

Fetches all EntityModel instance ItemModel’s. QuerySet selects relevant related fields to avoid additional DB queries for most use cases.

Parameters:: active (bool) – Filters the QuerySet to active accounts only. Defaults to True.
Return type:: ItemModelQuerySet

get_items_expenses(active: bool = True) → ItemModelQuerySet

Fetches all EntityModel instance ItemModel’s that qualify as Products. QuerySet selects relevant related fields to avoid additional DB queries for most use cases.

Parameters:: active (bool) – Filters the QuerySet to active accounts only. Defaults to True.
Return type:: ItemModelQuerySet

get_items_inventory(active: bool = True)

Fetches all EntityModel instance ItemModel’s that qualify as inventory. QuerySet selects relevant related fields to avoid additional DB queries for most use cases.

Parameters:: active (bool) – Filters the QuerySet to active accounts only. Defaults to True.
Return type:: ItemModelQuerySet

get_items_inventory_wip(active: bool = True)

Fetches all EntityModel instance ItemModel’s that qualify as work in progress inventory. QuerySet selects relevant related fields to avoid additional DB queries for most use cases.

Parameters:: active (bool) – Filters the QuerySet to active accounts only. Defaults to True.
Return type:: ItemModelQuerySet

get_items_products(active: bool = True) → ItemModelQuerySet

Fetches all EntityModel instance ItemModel’s that qualify as Products. QuerySet selects relevant related fields to avoid additional DB queries for most use cases.

Parameters:: active (bool) – Filters the QuerySet to active accounts only. Defaults to True.
Return type:: ItemModelQuerySet

get_items_services(active: bool = True) → ItemModelQuerySet

Fetches all EntityModel instance ItemModel’s that qualify as Services. QuerySet selects relevant related fields to avoid additional DB queries for most use cases.

Parameters:: active (bool) – Filters the QuerySet to active accounts only. Defaults to True.
Return type:: ItemModelQuerySet

get_ledgers_url() → str

The EntityModel Ledger List URL.

Returns:: EntityModel ledger list URL as a string.
Return type:: str

get_manage_url() → str

The EntityModel Manage URL.

Returns:: EntityModel manage URL as a string.
Return type:: str

get_purchase_orders()

Fetches a QuerySet of PurchaseOrderModels associated with the EntityModel instance.

Return type:: PurchaseOrderModelQuerySet

get_uom_all() → UnitOfMeasureModelQuerySet

Fetches the EntityModel instance Unit of Measures QuerySet.

Return type:: UnitOfMeasureModelQuerySet

get_vendors(active: bool = True) → VendorModelQuerySet

Fetches the VendorModels associated with the EntityModel instance.

Parameters:: active (bool) – Active VendorModels only. Defaults to True.
Returns:: The EntityModel instance VendorModelQuerySet with applied filters.
Return type:: VendorModelQuerySet

get_vendors_url() → str

The EntityModel vendors list URL.

Returns:: EntityModel vendors list URL as a string.
Return type:: str

has_default_coa() → bool

Determines if the EntityModel instance has a Default CoA.

Returns:: True if EntityModel instance has a Default CoA.
Return type:: bool

static inventory_adjustment(counted_qs, recorded_qs) → defaultdict

Computes the necessary inventory adjustment to update balance sheet.

Parameters:

counted_qs (ItemTransactionModelQuerySet) – Inventory recount queryset from Purchase Order received inventory. See ItemTransactionModelManager.inventory_count. Expects ItemTransactionModelQuerySet to be formatted “as values”.
recorded_qs (ItemModelQuerySet) – Inventory received currently recorded for each inventory item. See ItemTransactionModelManager.inventory_count Expects ItemModelQuerySet to be formatted “as values”.

Returns:

A dictionary with necessary adjustments with keys as tuple:

item_model_id
item_model__name
item_model__uom__name

Return type:

defaultdict

populate_default_coa(activate_accounts: bool = False, force: bool = False, ignore_if_default_coa: bool = True, coa_model: ChartOfAccountModel | None = None, commit: bool = True)

Populates the EntityModel default CoA with the default Chart of Account list provided by Django Ledger or user defined. See DJANGO_LEDGER_DEFAULT_COA setting.

Parameters:

activate_accounts (bool) – Activates all AccountModels for immediate use. Defaults to False.
force (bool) – Forces the creation of accounts even if other accounts are present. Defaults to False.
ignore_if_default_coa (bool) – Raises exception if EntityModel already has a default CoA. Defaults to True.
coa_model (ChartOfAccountModel) – Optional CoA Model to populate. Will be validated against EntityModel if provided.
commit (bool)
True. (' Commits the newly created CoA into the Database. Defaults to)

recorded_inventory(item_qs: ItemModelQuerySet | None = None, as_values: bool = True) → ItemModelQuerySet

Recorded inventory on the books marked as received. PurchaseOrderModel drives the ordering and receiving of inventory. Once inventory is marked as “received” recorded inventory of each item is updated by calling update_inventory. This function returns relevant values of the recoded inventory, including Unit of Measures.

Parameters:

item_qs (ItemModelQuerySet) – Pre fetched ItemModelQuerySet. Avoids additional DB Query.
as_values (bool) – Returns a list of dictionaries by calling the Django values() QuerySet function.

Returns:

The ItemModelQuerySet containing inventory ItemModels with additional Unit of Measure information.

Return type:

update_inventory(commit: bool = False) → Tuple[defaultdict, ItemTransactionModelQuerySet, ItemModelQuerySet]

Triggers an inventory recount with optional commitment of transaction.

Parameters:

commit – Updates all inventory ItemModels with the new inventory count.

Returns:

Return a tuple as follows:

All necessary inventory adjustments as a dictionary.
The recounted inventory.
The recorded inventory on Balance Sheet.

Return type:

Tuple[defaultdict, ItemTransactionModelQuerySet, ItemModelQuerySet]

validate_account_model_for_coa(account_model: AccountModel, coa_model: ChartOfAccountModel, raise_exception: bool = True) → bool

Validates that the AccountModel provided belongs to the CoA Model provided.

Parameters:

account_model (AccountModel) – The AccountModel to validate.
coa_model (ChartOfAccountModel) – The ChartOfAccountModel to validate against.
raise_exception (bool) – Raises EntityModelValidationError if AccountModel is invalid for the EntityModel and CoA instance.

Returns:

True if valid, else False.

Return type:

bool

validate_chart_of_accounts_for_entity(coa_model: ChartOfAccountModel, raise_exception: bool = True) → bool

Validates the CoA Model against the EntityModel instance.

Parameters:

coa_model (ChartOfAccountModel) – The CoA Model to validate.
raise_exception (bool) – Raises EntityModelValidationError if CoA Model is not valid for the EntityModel instance.

Returns:

True if valid, else False.

Return type:

bool

validate_item_qs(item_qs: ItemModelQuerySet, raise_exception: bool = True) → bool

Validates the given ItemModelQuerySet against the EntityModel instance. :param item_qs: The ItemModelQuerySet to validate. :type item_qs: ItemModelQuerySet :param raise_exception: Raises EntityModelValidationError if ItemModelQuerySet is not valid. :type raise_exception: bool

Returns:: True if valid, else False.
Return type:: bool

class django_ledger.models.entity.EntityModelClosingEntryMixIn: Closing Entries provide

class django_ledger.models.entity.EntityModelFiscalPeriodMixIn

This class encapsulates the functionality needed to determine the start and end of all financial periods of an EntityModel. At the moment of creation, an EntityModel must be assigned a calendar month which is going to determine the start of the Fiscal Year.

get_fiscal_quarter_dates(year: int, quarter: int, fy_start_month: int = None) → Tuple[date, date]

Convenience method to get in one shot both, fiscal year quarter start and end dates.

Parameters:

year (int) – The fiscal year associated with the requested start and end date.
quarter (int) – The quarter number associated with the requested start and end date.
fy_start_month (int) – Optional fiscal year month start. If passed, it will override the EntityModel setting.

Returns:

Both, the date when the requested EntityModel fiscal year quarter start and end date as a tuple. The start date will be first.

Return type:

tuple

get_fiscal_year_dates(year: int, fy_start_month: int = None) → Tuple[date, date]

Convenience method to get in one shot both, fiscal year start and end dates.

Parameters:

year (int) – The fiscal year associated with the requested start and end date.
fy_start_month (int) – Optional fiscal year month start. If passed, it will override the EntityModel setting.

Returns:

Both, the date when the requested EntityModel fiscal year start and end date as a tuple. The start date will be first.

Return type:

tuple

get_fy_end(year: int, fy_start_month: int = None) → date

The fiscal year ending date of the EntityModel, according to its settings.

Parameters:

year (int) – The fiscal year associated with the requested end date.
fy_start_month (int) – Optional fiscal year month start. If passed, it will override the EntityModel setting.

Returns:

The date when the requested EntityModel fiscal year ends.

Return type:

date

get_fy_for_date(dt: date | datetime, as_str: bool = False) → str | int

Given a known date, returns the EntityModel fiscal year associated with the given date.

Parameters:

dt (date) – Date to evaluate.
as_str (bool) – If True, return date as a string.

Returns:

Fiscal year as an integer or string, depending on as_str parameter.

Return type:

str or date

get_fy_start(year: int, fy_start_month: int | None = None) → date

The fiscal year start date of the EntityModel, according to its settings.

Parameters:

year (int) – The fiscal year associated with the requested start date.
fy_start_month (int) – Optional fiscal year month start. If passed, it will override the EntityModel setting.

Returns:

The date when the requested EntityModel fiscal year starts.

Return type:

date

get_fy_start_month() → int

The fiscal year start month represents the month (as an integer) when the assigned fiscal year of the EntityModel starts.

Returns:: An integer representing the month that the fiscal year starts.
Return type:: int

Examples

1 -> January.
4 -> April.
9 -> September.

get_quarter_end(year: int, quarter: int, fy_start_month: int = None) → date

The fiscal year quarter ending date of the EntityModel, according to its settings.

Parameters:

year (int) – The fiscal year associated with the requested end date.
quarter (int) – The quarter number associated with the requested end date.
fy_start_month (int) – Optional fiscal year month start. If passed, it will override the EntityModel setting.

Returns:

The date when the requested EntityModel quarter ends.

Return type:

date

get_quarter_start(year: int, quarter: int, fy_start_month: int = None) → date

The fiscal year quarter starting date of the EntityModel, according to its settings.

Parameters:

year (int) – The fiscal year associated with the requested start date.
quarter (int) – The quarter number associated with the requested start date.
fy_start_month (int) – Optional fiscal year month start. If passed, it will override the EntityModel setting.

Returns:

The date when the requested EntityModel quarter starts.

Return type:

date

validate_month(month: int)

Validates the month as a valid parameter for other functions. Makes sure that only integers between 1 and 12 are used to refer to a particular month. Prevents injection of invalid values from views into the IOMixIn.

Parameters:: month (int) – The month number to validate.
Raises:: ValidationError – If month is not valid.

validate_quarter(quarter: int)

Validates the quarter as a valid parameter for other functions. Makes sure that only integers 1,2,3, or 4 are used to refer to a particular Quarter. Prevents injection of invalid values from views into the IOMixIn.

Parameters:: quarter (int) – The quarter number to validate.
Raises:: ValidationError – If quarter is not valid.

class django_ledger.models.entity.EntityModelManager(*args, **kwargs)

A custom defined EntityModel Manager. This ModelManager uses the custom defined EntityModelQuerySet as default. Inherits from the Materialized Path Node Manager to include the necessary methods to manage tree-like models. This Model Manager keeps track and maintains a root/parent/child relationship between Entities for the purposes of producing consolidated financial statements.

Examples

>>> user = request.user
>>> entity_model_qs = EntityModel.objects.for_user(user_model=user)

for_user(user_model, authorized_superuser: bool = False)

This QuerySet guarantees that Users do not access or operate on EntityModels that don’t have access to. This is the recommended initial QuerySet.

Parameters:

user_model – The Django User Model making the request.
authorized_superuser – Allows any superuser to access the EntityModel. Default is False.

Returns:

A filtered QuerySet of EntityModels that the user has access. The user has access to an Entity if:

Is the Administrator.
Is a manager.

Return type:

EntityModelQuerySet

get_queryset(): Sets the custom queryset as the default.

class django_ledger.models.entity.EntityModelQuerySet(model=None, query=None, using=None, hints=None)

A custom defined EntityModel QuerySet. Inherits from the Materialized Path Node QuerySet Class from Django Treebeard.

hidden()

A QuerySet of all hidden EntityModel.

Returns:: A filtered QuerySet of hidden EntityModels only.
Return type:: EntityModelQuerySet

visible()

A Queryset of all visible EntityModel.

Returns:: A filtered QuerySet of visible EntityModels only.
Return type:: EntityModelQuerySet

exception django_ledger.models.entity.EntityModelValidationError(message, code=None, params=None)

class django_ledger.models.entity.EntityStateModel(*args, **kwargs)

Entity State Model Base Class from Abstract.

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.entity.EntityStateModelAbstract(*args, **kwargs)

Entity Unit Model

An EntityUnit is a logical, user-defined grouping assigned to JournalEntryModels, helping to segregate business operations into distinct components. Examples of EntityUnits may include departments (e.g., Human Resources, IT), office locations, real estate properties, or any other labels relevant to the business.

EntityUnits are self-contained entities, meaning that double-entry accounting rules apply to all transactions associated with them. When an Invoice or Bill is updated, the migration process generates the corresponding Journal Entries for each relevant unit. This allows invoices or bills to split specific items into different units, with the migration process allocating costs to each unit accordingly.

Key advantages of EntityUnits:

EntityUnits can generate their own financial statements, providing deeper insights into the specific operations of the business.
EntityUnits can be assigned to specific items on Bills and Invoices, offering flexibility to track inventory, expenses, or income associated with distinct business units.

class django_ledger.models.unit.EntityUnitModel(*args, **kwargs)

Base Model Class for EntityUnitModel

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.unit.EntityUnitModelAbstract(*args, **kwargs)

Base implementation of the EntityUnitModel.

uuid

This is a unique primary key generated for the table. The default value of this field is uuid4().

Type:: UUID

slug

A unique, indexed identifier for the EntityUnitModel instance used in URLs and queries.

Type:: str

entity

The EntityModel associated with this EntityUnitModel.

Type:: EntityModel

document_prefix

A predefined prefix automatically incorporated into JournalEntryModel document numbers. Max Length 3. May be user defined. Must be unique for the EntityModel.

Type:: str

active

Active EntityUnits may transact. Inactive units are considered archived. Defaults to True.

Type:: bool

hidden

Hidden Units will not show on drop down menus on the UI. Defaults to False.

Type:: bool

class Meta

clean(): Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

create_entity_unit_slug(name: str | None = None, force: bool = False, add_suffix: bool = True, k: int = 5) → str

Automatically generates a EntityUnitModel slug. If slug is present, will not be replaced. Called during the clean() method.

Parameters:

force (bool) – Forces generation of new slug if already present.
name (str) – The name used to create slug. If none, the unit name will be used.
add_suffix (bool) – Adds a random suffix to the slug. Defaults to True.
k (int) – Length of the suffix if add_suffix is True. Defaults to 5.

Returns:

The EntityUnitModel slug, regardless if generated or not.

Return type:

str

get_dashboard_url() → str

The dashboard URL of the EntityModelUnit.

Returns:: The EntityModelUnit instance dashboard URL.
Return type:: str

class django_ledger.models.unit.EntityUnitModelManager(*args, **kwargs)

for_entity(entity_slug: str, user_model)

Fetches a QuerySet of EntityUnitModels associated with a specific EntityModel & UserModel. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – Logged in and authenticated django UserModel instance.

Returns:

Returns a EntityUnitModelQuerySet with applied filters.

Return type:

EntityUnitModelQuerySet

get_queryset(): Sets the custom queryset as the default.

class django_ledger.models.unit.EntityUnitModelQuerySet(model=None, query=None, using=None, hints=None): A custom defined EntityUnitModel Queryset.

exception django_ledger.models.unit.EntityUnitModelValidationError(message, code=None, params=None)

Account Model

AccountModel

The AccountModel is a fundamental component of the Django Ledger system, responsible for categorizing and organizing financial transactions related to an entity’s assets, liabilities, and equity.

Account Types

In accordance with accounting principles, each AccountModel must be classified as either:

DEBIT-type balance account
CREDIT-type balance account

The account type determines how transactions affect the account’s balance.

Double Entry Accounting

The AccountModel is crucial in implementing double entry accounting systems:

For DEBIT-type accounts: - A DEBIT increases the balance - A CREDIT decreases the balance
For CREDIT-type accounts: - A CREDIT increases the balance - A DEBIT decreases the balance

Chart of Accounts

Users have the flexibility to adopt a chart of accounts that best suits their EntityModel. Django Ledger provides a default Chart of Accounts when creating a new EntityModel, which can be customized as needed.

Account Roles

All AccountModels must be assigned a role from the ACCOUNT_ROLES function in django_ledger.io.roles. Roles serve several purposes:

Group accounts into common namespaces
Provide consistency across user-defined fields
Enable accurate generation of financial statements
Facilitate financial ratio calculations

class django_ledger.models.accounts.AccountModel(*args, **kwargs)

Base Account Model from Account Model Abstract Class

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.accounts.AccountModelAbstract(*args, **kwargs)

Abstract class representing an Account Model.

BALANCE_TYPE

List of choices for the balance type of the account. Options include ‘Credit’ and ‘Debit’.

Type:: list

uuid

Unique identifier for each account instance.

Type:: UUIDField

code

Code representing the account, constrained by length and specific validation rules.

Type:: CharField

name

Name of the account, constrained by length.

Type:: CharField

role

Role associated with the account, with specific predefined choices.

Type:: CharField

role_default

Flag indicating if this account is the default for its role.

Type:: BooleanField

balance_type

Type of balance the account holds, must be either ‘debit’ or ‘credit’.

Type:: CharField

locked

Indicates whether the account is locked.

Type:: BooleanField

active

Indicates whether the account is active.

Type:: BooleanField

coa_model

Reference to the associated ChartOfAccountModel.

Type:: ForeignKey

class Meta

activate(commit: bool = True, raise_exception: bool = True, **kwargs)

Checks if the Account Model instance can be activated, then Activates the AccountModel instance. Raises exception if AccountModel cannot be activated.

Parameters:

commit (bool, optional) – If True, commit the changes to the database by calling the save method.
raise_exception (bool, optional) – If True, raises an AccountModelValidationError if the account cannot be activated.
kwargs (dict) – Additional parameters that can be passed for further customization.

can_activate()

Determines if the object can be activated.

Returns:: True if the object is inactive, otherwise False.
Return type:: bool

can_deactivate()

Determine if the object can be deactivated.

Checks if the active attribute is set to True.

Returns:: True if the object is currently active and can be deactivated, otherwise False.
Return type:: bool

can_transact() → bool

Determines if a transaction can be performed based on multiple conditions.

Returns:

bool – True if all conditions are met, enabling a transaction; False otherwise.
Conditions
1. The chart of accounts (coa_model) must be active.
2. The entity must not be locked.
3. The entity itself must be active.

clean(): Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

classmethod create_account(name: str, role: bool, balance_type: str, is_role_default: bool = False, locked: bool = False, active: bool = False, **kwargs)

Create a new AccountModel instance, managing parent/child relationships properly.

This convenience method ensures correct creation of new accounts, handling the intricate logic needed for maintaining hierarchical relationships between accounts.

Parameters:

name (str) – Name of the new account entity.
role (str) – Role assigned to the account.
balance_type (str) – Type of balance associated with the account. Must be either ‘debit’ or ‘credit’.
is_role_default (bool, optional) – Indicates if the account should be the default for its role. Only one default account per role is allowed. Defaults to False.
locked (bool, optional) – Flags the account as locked. Defaults to False.
active (bool, optional) – Flags the account as active. Defaults to True.
**kwargs (dict, optional) – Additional attributes for account creation.

Returns:

The newly created AccountModel instance.

Return type:

deactivate(commit: bool = True, raise_exception: bool = True, **kwargs)

Checks if the Account Model instance can be de-activated, then De-activates the AccountModel instance. Raises exception if AccountModel cannot be de-activated.

Parameters:

commit (bool, optional) – If True, commit the changes to the database by calling the save method.
raise_exception (bool, optional) – If True, raises an AccountModelValidationError if the account cannot be activated.
kwargs (dict) – Additional parameters that can be passed for further customization.

generate_random_code()

Generates a random code for the account adding a prefix 1-6 depending on account role.

Raises:: AccountModelValidationError – If the account role is not assigned before code generation.
Returns:: A randomly generated code prefixed with a role-based prefix.
Return type:: str

get_account_move_choice_queryset()

Retrieves a filtered queryset of account models that the current Account Model instance can be a child of.

The queryset is filtered based on the specified role and its hierarchical parent roles. Account models with a UUID matching the current instance’s UUID are excluded from the results.

Returns:: A filtered set of account models suitable for moving the current instance under.
Return type:: QuerySet

get_code_prefix() → str

Returns the code prefix based on the account type.

This method determines the account type by calling the respective account type methods and returns the corresponding code prefix based on Accounting best practices..

Returns:: The code prefix for the account type. The possible values are: ‘1’ for assets, ‘2’ for liabilities, ‘3’ for capital, ‘4’ for income, ‘5’ for cost of goods sold (COGS), ‘6’ for expenses.
Return type:: str
Raises:: AccountModelValidationError – If the account role does not match any of the predefined categories.

get_html_pixel_indent()

Calculates the pixel indentation for HTML elements based on the depth attribute for UI purposes

Returns:: The calculated pixel indentation as a string with ‘px’ suffix.
Return type:: str

get_root_role() → str

Returns the root role corresponding to the account type.

Returns:: The root role corresponding to the account type.
Return type:: str
Raises:: AccountModelValidationError – If no valid role match is found for the account’s role.

is_active() → bool

Determines if the current instance is active.

Returns:: True if the instance is active, otherwise False
Return type:: bool

is_asset() → bool

Determines if the current Account Model role of the instance is considered an asset.

Returns:: True if the role is part of the GROUP_ASSETS, False otherwise.
Return type:: bool

is_capital() → bool

Checks if the current Account Model role is in the capital group.

Returns:: True if the role is in GROUP_CAPITAL, otherwise False.
Return type:: bool

is_coa_root()

Check if the current Account Model role is ‘ROOT_COA’.

Returns:: True if the role is ‘ROOT_COA’, False otherwise.
Return type:: bool

is_cogs() → bool

Determines if the role of the object is part of the GROUP_COGS.

Returns:: True if the object’s role is part of the GROUP_COGS, False otherwise.
Return type:: bool

is_credit()

Checks if the Account Model has a CREDIT balance type.

Returns:: True if account has a CREDIT balance, else False.
Return type:: bool

is_debit() → bool

Checks if the account has a DEBIT balance type.

Returns:: True if account has a DEBIT balance, else False.
Return type:: bool

is_expense() → bool

Checks if the current Account Model role is categorized under GROUP_EXPENSES.

Parameters:: None
Returns:: True if role is in GROUP_EXPENSES, otherwise False.
Return type:: bool

is_income() → bool

Determines whether the current Account Model role belongs to the income group.

Parameters:: self (object) – The instance of the class containing attribute ‘role’.
Returns:: True if the role is in the GROUP_INCOME list, False otherwise.
Return type:: bool

is_indented()

Check if the current depth level is greater than 2.

Returns:: True if the depth is greater than 2, False otherwise.
Return type:: bool

is_liability() → bool

Determines if the current Account Model role is considered a liability.

Returns:: True if the role is part of GROUP_LIABILITIES, otherwise False.
Return type:: bool

is_locked() → bool

Determines if the current object is locked.

Returns:: True if the object is locked, False otherwise.
Return type:: bool

is_root_account()

Checks if the current user’s role belongs to the ROOT_GROUP.

Returns:: True if the role is in the ROOT_GROUP, False otherwise
Return type:: bool

property role_bs: str

Returns the principal role of the account on the balance sheet.

The principal role can be one of the following: - ‘asset’ - ‘liability’ - ‘equity’

Returns:: A string representing the principal role of the account on the balance sheet.
Return type:: str

class django_ledger.models.accounts.AccountModelManager(*args, **kwargs)

AccountModelManager class provides methods to manage and retrieve AccountModel objects. It inherits from MP_NodeManager for tree-like model implementation.

for_entity(user_model, entity_model, coa_slug: str | None = None) → AccountModelQuerySet

Retrieve accounts associated with a specified EntityModel and Chart of Accounts.

Parameters:

user_model (User) – The Django User instance initiating the request. Used to check for required permissions.
entity_model (Union[EntityModel, str]) – An instance of EntityModel or its slug. This determines the entity whose accounts are being retrieved. A database query will be carried out to identify the default Chart of Accounts.
coa_slug (Optional[str], default=None) – The slug for a specific Chart of Accounts to be used. If None, the default Chart of Accounts will be selected.

Returns:

A QuerySet containing accounts associated with the specified EntityModel and Chart of Accounts.

Return type:

JournalEntryModelQuerySet

Raises:

AccountModelValidationError – If the entity_model is neither an instance of EntityModel nor a string.

for_user(user_model) → AccountModelQuerySet

Parameters:: user_model (UserModel) – The user model instance to use for filtering.
Returns:: The filtered queryset based on the user’s permissions. Superusers get the complete queryset whereas other users get a filtered queryset based on their role as admin or manager in the entity.
Return type:: AccountModelQuerySet

get_queryset() → AccountModelQuerySet

Retrieve and return athe default AccountModel QuerySet.

The query set is ordered by the ‘path’ field and uses ‘select_related’ to reduce the number of database queries by retrieving the related ‘coa_model’.

Returns:: An instance of AccountModelQuerySet ordered by ‘path’ and prefetching related ‘coa_model’.
Return type:: AccountModelQuerySet

class django_ledger.models.accounts.AccountModelQuerySet(model=None, query=None, using=None, hints=None)

Custom QuerySet for AccountModel inheriting from MP_NodeQuerySet.

active()

Filters the queryset to include only active items.

Returns:: A filtered queryset containing only the items marked as active.
Return type:: AccountModelQuerySet

can_transact()

Filter the queryset to include only accounts that can accept new transactions.

Returns:: A QuerySet containing the filtered results.
Return type:: QuerySet

expenses()

Retrieve a queryset containing expenses filtered by specified roles.

This method filters the expenses based on roles defined in the GROUP_EXPENSES constant. It ensures that only the relevant expenses associated with the specified roles are included in the queryset.

Returns:: A queryset consisting of expenses filtered according to the roles in GROUP_EXPENSES.
Return type:: AccountModelQuerySet

for_bill()

Retrieves only available and unlocked AccountModels for a specific EntityModel, specifically for the creation and management of Bills. Roles within the ‘GROUP_BILL’ context include: ASSET_CA_CASH, ASSET_CA_PREPAID, and LIABILITY_CL_ACC_PAYABLE.

Returns:: A QuerySet of the requested EntityModel’s chart of accounts.
Return type:: AccountModelQuerySet

for_invoice()

Retrieves available and unlocked AccountModels for a specific EntityModel, specifically for the creation and management of Invoices.

This method ensures that only relevant accounts are pulled, as defined under the roles in GROUP_INVOICE. These roles include: ASSET_CA_CASH, ASSET_CA_RECEIVABLES, and LIABILITY_CL_DEFERRED_REVENUE.

Returns:: A QuerySet containing the AccountModels relevant for the specified EntityModel and the roles defined in GROUP_INVOICE.
Return type:: AccountModelQuerySet

gb_bs_role()

Groups accounts by Balance Sheet Bucket and then further groups them by role.

Returns:: A list where each element is a tuple. The first element of the tuple is the BS bucket, and the second element is a list of tuples where each sub-tuple contains a role display and a list of accounts that fall into that role within the BS bucket.
Return type:: List[Tuple]

inactive()

Filters and returns queryset entries where the active field is set to False.

Returns:: A queryset containing entries with active=False.
Return type:: AccountModelQuerySet

is_coa_root()

Retrieves the Chart of Accounts (CoA) root node queryset.

A Chart of Accounts Root is a foundational element indicating the primary node in the account hierarchy. This method filters the queryset to include only the Chart of Accounts (CoA) root node.

Return type:: AccountModelQuerySet

is_role_default()

Filter the queryset to include only entries where role_default is set to True, excluding entries marked as ‘coa_root’.

Returns:: Filtered queryset with role_default set to True and excluding ‘coa_root’ entries.
Return type:: AccountModelQuerySet

locked()

Filters the queryset to include only locked AccountModels.

Returns:: A queryset containing only the objects with locked set to True.
Return type:: AccountModelQuerySet

not_coa_root()

Exclude AccountModels with ROOT_GROUP role from the QuerySet.

Returns:: A QuerySet excluding users with role in ROOT_GROUP.
Return type:: AccountModelQuerySet

unlocked()

Returns a filtered list of items where the ‘locked’ attribute is set to False.

Returns:: A queryset of items with ‘locked’ attribute set to False
Return type:: AccountModelQuerySet

with_roles(roles: List | str)

Filter the accounts based on the specified roles. This method helps to retrieve accounts associated with a particular role or a list of roles.

For example, to get all accounts categorized under the role “asset_ppe_build” (which might include fixed assets like Buildings), you can utilize this method.

Parameters:: roles (Union[List[str], str]) – The role or a list of roles to filter the accounts by. If a single string is provided, it is converted into a list containing that role.
Returns:: A QuerySet of accounts filtered by the provided roles.
Return type:: AccountModelQuerySet

exception django_ledger.models.accounts.AccountModelValidationError(message, code=None, params=None)

django_ledger.models.accounts.CREDIT = 'credit': A constant, identifying a CREDIT Account or CREDIT transaction in the respective database fields

django_ledger.models.accounts.DEBIT = 'debit': A constant, identifying a DEBIT Account or DEBIT transaction in the respective database fields

Ledger Model

The LedgerModel is the heart of Django Ledger. It is a self-contained unit of accounting that implements a double-entry accounting system capable of creating and managing transactions into the ledger and producing any financial statements. In essence, an EntityModel is made of a collection of LedgerModels that drive the whole bookkeeping process. Each LedgerModel is independent and they can operate as an individual or as a group.

Each LedgerModel encapsulates a collection of JournalEntryModels, which in turn hold a collection of TransactionModels. LedgerModels can be used to represent any part of the EntityModel and can be extended to add additional functionality and custom logic that drives how transactions are recorded into the books. One example of this is the LedgerWrapperMixIn (see django_ledger.models.mixins.LedgerWrapperMixIn), which is the foundation of LedgerModel abstractions such as the BillModel, InvoiceModel, PurchaseOrderModel and EstimateModel. Extending the LedgerModel can add additional functionality necessary to implement industry-specific functionality to almost anything you can think of. Examples: Farming Equipment, Real Estate, Investment Portfolio, etc.

Also, the LedgerModel inherits functionality from the all mighty IOMixIn (see django_ledger.io.io_mixin.IOMixIn), which is the class responsible for making accounting queries to the Database in an efficient and performing way. The digest() method executes all necessary aggregations and optimizations in order to push as much work to the Database layer as possible in order to minimize the amount of data being pulled for analysis into the Python memory.

The Django Ledger core model follows the following structure: EntityModel -< LedgerModel -< JournalEntryModel -< TransactionModel

class django_ledger.models.ledger.LedgerModel(*args, **kwargs)

Base LedgerModel from Abstract.

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.ledger.LedgerModelAbstract(*args, **kwargs)

Base implementation of the LedgerModel.

uuid

This is a unique primary key generated for the table. The default value of this field is uuid4().

Type:: UUID

name

Human-readable name of the LedgerModel. Maximum 150 characters.

Type:: str

ledger_xid

A unique user-defined identifier for the LedgerModel. Unique for the Entity Model.

Type:: str

entity

The EntityModel associated with the LedgerModel instance.

Type:: EntityModel

posted

Determines if the LedgerModel is posted. Defaults to False. Mandatory.

Type:: bool

locked

Determines if the LedgerModel is locked. Defaults to False. Mandatory.

Type:: bool

hidden

Determines if the LedgerModel is hidden. Defaults to False. Mandatory.

Type:: bool

can_hide() → bool

Determines if the LedgerModel can be hidden.

Returns:: True if can be hidden, else False.
Return type:: bool

can_lock() → bool

Determines if the LedgerModel can be locked.

Returns:: True if can be locked, else False.
Return type:: bool

can_post() → bool

Determines if the LedgerModel can be marked as posted.

Returns:: True if can be posted, else False.
Return type:: bool

can_unhide() → bool

Determines if the LedgerModel can be un-hidden.

Returns:: True if can be un-hidden, else False.
Return type:: bool

can_unlock() → bool

Determines if the LedgerModel can be un-locked.

Returns:: True if can be un-locked, else False.
Return type:: bool

can_unpost() → bool

Determines if the LedgerModel can be un-posted.

Returns:: True if can be un-posted, else False.
Return type:: bool

get_absolute_url() → str

Determines the absolute URL of the LedgerModel instance. Results in additional Database query if entity field is not selected in QuerySet.

Returns:: URL as a string.
Return type:: str

get_create_url() → str

Determines the update URL of the LedgerModel instance. Results in additional Database query if entity field is not selected in QuerySet.

Returns:: URL as a string.
Return type:: str

get_list_url() → str

Determines the list URL of the LedgerModel instances. Results in additional Database query if entity field is not selected in QuerySet.

Returns:: URL as a string.
Return type:: str

get_update_url() → str

Determines the update URL of the LedgerModel instance. Results in additional Database query if entity field is not selected in QuerySet.

Returns:: URL as a string.
Return type:: str

is_hidden() → bool

Determines if the LedgerModel instance is hidden.

Returns:: True if hidden, else False.
Return type:: bool

is_locked() → bool

Determines if the LedgerModel instance is locked.

Returns:: True if locked, else False.
Return type:: bool

is_posted() → bool

Determines if the LedgerModel instance is posted.

Returns:: True if posted, else False.
Return type:: bool

lock(commit: bool = False, raise_exception: bool = True, **kwargs)

Locks the LedgerModel.

Parameters:

commit (bool) – If True, saves the LedgerModel instance instantly. Defaults to False.
raise_exception (bool) – Raises LedgerModelValidationError if locking not allowed.

post(commit: bool = False, raise_exception: bool = True, **kwargs)

Posts the LedgerModel.

Parameters:

commit (bool) – If True, saves the LedgerModel instance instantly. Defaults to False.
raise_exception (bool) – Raises LedgerModelValidationError if posting not allowed.

unlock(commit: bool = False, raise_exception: bool = True, **kwargs)

Un-locks the LedgerModel.

Parameters:: commit (bool) – If True, saves the LedgerModel instance instantly. Defaults to False.

unpost(commit: bool = False, raise_exception: bool = True, **kwargs)

Un-posts the LedgerModel.

Parameters:

commit (bool) – If True, saves the LedgerModel instance instantly. Defaults to False.
raise_exception (bool) – Raises LedgerModelValidationError if un-posting not allowed.

class django_ledger.models.ledger.LedgerModelManager(*args, **kwargs)

A custom-defined LedgerModelManager that implements custom QuerySet methods related to the LedgerModel.

for_entity(entity_slug, user_model)

Returns a QuerySet of LedgerModels associated with a specific EntityModel & UserModel. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered LedgerModelQuerySet.

Return type:

LedgerModelQuerySet

get_queryset(): Return a new QuerySet object. Subclasses can override this method to customize the behavior of the Manager.

class django_ledger.models.ledger.LedgerModelQuerySet(model=None, query=None, using=None, hints=None)

Custom defined LedgerModel QuerySet.

locked()

Filters the QuerySet to only locked LedgerModel.

Returns:: A QuerySet with applied filters.
Return type:: LedgerModelQuerySet

posted()

Filters the QuerySet to only posted LedgerModel.

Returns:: A QuerySet with applied filters.
Return type:: LedgerModelQuerySet

unlocked()

Filters the QuerySet to only un-locked LedgerModel.

Returns:: A QuerySet with applied filters.
Return type:: LedgerModelQuerySet

unposted()

Filters the QuerySet to only un-posted LedgerModel.

Returns:: A QuerySet with applied filters.
Return type:: LedgerModelQuerySet

exception django_ledger.models.ledger.LedgerModelValidationError(message, code=None, params=None)

Transaction Model

The TransactionModel serves as the foundational accounting entity where all financial transactions are recorded. Every transaction must be associated with a JournalEntryModel, which represents a collection of related transactions. This strict association ensures that standalone TransactionModels—or orphan transactions—do not exist, a constraint enforced at the database level.

Each transaction performs either a CREDIT or a DEBIT operation on the designated AccountModel, upholding standard accounting principles. The TransactionModel API integrates the IOMixIn, a critical component for generating financial statements. This mixin facilitates efficient querying and aggregation directly at the database level, eliminating the need to load all TransactionModels into memory. This database-driven approach significantly improves performance and simplifies the process of generating accurate financial reports.

The TransactionModel, together with the IOMixIn, is essential for ensuring seamless, efficient, and reliable financial statement production in the Django Ledger framework.

class django_ledger.models.transactions.TransactionModel(*args, **kwargs)

Base Transaction Model From Abstract.

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.transactions.TransactionModelAbstract(*args, **kwargs)

Abstract model for representing a financial transaction in the ledger system.

This model defines the core structure and behavior that every transaction record is expected to have, including fields like transaction type, associated account, amount, and additional metadata used for validation and functionality.

Attributes:

Constants: - CREDIT: Constant representing a credit transaction. - DEBIT: Constant representing a debit transaction. - TX_TYPE: A list of choices providing options for transaction types, including CREDIT and DEBIT.

Fields: - uuid (UUIDField): The unique identifier for the transaction. Automatically generated, non-editable, and primary key. - tx_type (CharField): Specifies the transaction type (CREDIT or DEBIT). Choices are based on the TX_TYPE constant. Maximum length is 10 characters. - journal_entry (ForeignKey): References the related journal entry from the django_ledger.JournalEntryModel.

This field is not editable and is essential for linking transactions to journal entries.

account (ForeignKey): References the associated account from django_ledger.AccountModel. Protected from being deleted.
amount (DecimalField): Represents the transaction amount, up to 20 digits and 2 decimal places. The default value is 0.00, and it enforces a minimum value of 0.
description (CharField): Optional field for a brief description of the transaction. The maximum length is 100 characters.
cleared (BooleanField): Indicates whether the transaction has been cleared. Defaults to False.
reconciled (BooleanField): Indicates whether the transaction has been reconciled. Defaults to False.
objects (TransactionModelManager): Custom model manager providing advanced helper methods for querying and filtering transactions.

property coa_id: Fetch the Chart of Accounts (CoA) ID associated with the transaction’s account. Returns None if the account is not set.

class django_ledger.models.transactions.TransactionModelManager(*args, **kwargs)

A custom manager for TransactionModel designed to add helper methods for querying and filtering TransactionModel objects efficiently based on use cases like user permissions, associated entities, ledgers, journal entries, and more.

This manager leverages TransactionModelQuerySet for complex query construction and integrates advanced filtering options based on user roles, entities, and other relationships.

for_entity(entity_slug: EntityModel | str | UUID, user_model: User | None = None) → TransactionModelQuerySet

Filters transactions for a specific entity, optionally scoped to a specific user.

Parameters:

entity_slug (Union[EntityModel, str, UUID]) – Identifier for the entity. This can be an EntityModel object, a slug (str), or a UUID.
user_model (Optional[UserModel], optional) – The user for whom transactions should be filtered. If provided, applies user-specific filtering. Defaults to None.

Returns:

A queryset containing transactions associated with the specified entity.

Return type:

TransactionModelQuerySet

Notes

If user_model is provided, only transactions accessible by the user are included.
Supports flexible filtering by accepting different forms of entity_slug.

for_user(user_model) → TransactionModelQuerySet

Filters transactions accessible to a specific user based on their permissions.

Parameters:

user_model (UserModel) – The user object for which the transactions should be filtered.

Returns:

TransactionModelQuerySet – A queryset containing transactions filtered by the user’s access level.
Description
———–
- Returns all TransactionModel objects for superusers.
- For regular users, it filters transactions where –
- The user is an admin of the entity associated with the ledger in the transaction.
- The user is a manager of the entity associated with the ledger in the transaction.

get_queryset() → TransactionModelQuerySet

Retrieves the base queryset for TransactionModel, annotated and pre-loaded with commonly used related fields.

Returns:: A custom queryset with essential annotations and relationships preloaded.
Return type:: TransactionModelQuerySet

class django_ledger.models.transactions.TransactionModelQuerySet(model=None, query=None, using=None, hints=None)

A custom QuerySet class tailored for TransactionModel objects. It includes a collection of methods to efficiently and safely retrieve and filter transactions from the database based on common use cases.

for_accounts(account_list: List[str])

Filters transactions based on the accounts they are associated with.

Parameters:: account_list (list of str or AccountModel) – A list containing account codes (strings) or AccountModel instances. Transactions will be filtered to match these accounts.
Returns:: A QuerySet filtered for transactions associated with the specified accounts.
Return type:: TransactionModelQuerySet

for_activity(activity_list: str | List[str] | Set[str])

Filters transactions based on their associated activity or activities.

Parameters:: activity_list (str or list of str) – A single activity or a list of activities to filter transactions by.
Returns:: A QuerySet filtered for transactions linked to the specified activity or activities.
Return type:: TransactionModelQuerySet

for_bill(bill_model: BillModel | str | UUID)

Filters transactions for a specific bill under a given entity.

Parameters:: bill_model (Union[BillModel, str, UUID]) – The bill model or its UUID to filter by.
Returns:: A queryset containing transactions related to the specified bill.
Return type:: TransactionModelQuerySet

for_invoice(invoice_model: InvoiceModel | str | UUID)

Filters transactions for a specific invoice under a given entity.

Parameters:: invoice_model (Union[InvoiceModel, str, UUID]) – The invoice model or its UUID to filter by.
Returns:: A queryset containing transactions related to the specified invoice.
Return type:: TransactionModelQuerySet

for_journal_entry(je_model)

Filters transactions for a specific journal entry under a given ledger and entity.

Parameters:: je_model (Union[JournalEntryModel, UUID]) – The journal entry model or its UUID to filter by.
Returns:: A queryset containing transactions associated with the given journal entry.
Return type:: TransactionModelQuerySet

for_ledger(ledger_model: LedgerModel | UUID | str)

Filters transactions for a specific ledger under a given entity.

Parameters:: ledger_model (Union[LedgerModel, UUID]) – The ledger model or its UUID to filter by.
Returns:: A queryset containing transactions associated with the given ledger and entity.
Return type:: TransactionModelQuerySet

for_roles(role_list: str | List[str] | Set[str])

Fetches a QuerySet of TransactionModels which AccountModel has a specific role.

Parameters:: role_list (str or list) – A string or list of strings representing the roles to be used as filter.
Returns:: Returns a TransactionModelQuerySet with applied filters.
Return type:: TransactionModelQuerySet

for_unit(unit_slug: str | EntityUnitModel)

Filters transactions based on their associated entity unit.

Parameters:: unit_slug (str or EntityUnitModel) – A string representing the slug of the entity unit or an EntityUnitModel instance.
Returns:: A QuerySet filtered for transactions linked to the specified unit.
Return type:: TransactionModelQuerySet

from_date(from_date: str | date | datetime)

Filters transactions occurring on or after a specific date or timestamp.

If from_date is a naive datetime (no timezone), it is assumed to be in local time based on Django settings.

Parameters:: from_date (str, date, or datetime) – The minimum date or timestamp for filtering. When using a date (not datetime), the filter is inclusive (e.g., “2022-12-20” includes all transactions from that day).
Returns:: A QuerySet filtered to include transactions from the specified date or timestamp onwards.
Return type:: TransactionModelQuerySet

is_closing_entry()

Filters transactions that are part of a closing journal entry.

Returns:: A QuerySet with transactions where the journal_entry__is_closing_entry field is True.
Return type:: TransactionModelQuerySet

not_closing_entry()

Filters transactions that are not part of a closing journal entry.

Returns:: A QuerySet with transactions where the journal_entry__is_closing_entry field is False.
Return type:: TransactionModelQuerySet

posted() → QuerySet

Retrieves transactions that are part of a posted journal entry and ledger.

A transaction is considered “posted” if: - It belongs to a journal entry marked as posted. - Its associated journal entry is part of a ledger marked as posted.

Returns:: A QuerySet containing only transactions that meet the “posted” criteria.
Return type:: TransactionModelQuerySet

to_date(to_date: str | date | datetime)

Filters transactions occurring on or before a specific date or timestamp.

If to_date is a naive datetime (no timezone), it is assumed to be in local time based on Django settings.

Parameters:: to_date (str, date, or datetime) – The maximum date or timestamp for filtering. When using a date (not datetime), the filter is inclusive (e.g., “2022-12-20” includes all transactions from that day).
Returns:: A QuerySet filtered to include transactions up to the specified date or timestamp.
Return type:: TransactionModelQuerySet

exception django_ledger.models.transactions.TransactionModelValidationError(message, code=None, params=None)

django_ledger.models.transactions.transactionmodel_presave(instance: TransactionModel, **kwargs)

Pre-save validation for the TransactionModel instance.

This function is executed before saving a TransactionModel instance, ensuring that certain conditions are met to maintain data integrity.

Parameters:

instance (TransactionModel) – The TransactionModel instance that is about to be saved.
kwargs (dict) – Additional keyword arguments, such as the optional bypass_account_state.
Validations
-----------
validations (The function performs the following)
Transactionality (1. Account) – If the bypass_account_state flag is not provided or set to False, it verifies whether the associated account can process transactions by calling instance.account.can_transact(). If the account cannot process transactions, the save operation is interrupted to prevent invalid data.
Lock (2. Journal Entry) – If the associated journal entry (instance.journal_entry) is locked, the transaction cannot be modified. The save process is halted if the journal entry is marked as locked.

Raises:

TransactionModelValidationError – Raised in the following scenarios: - Account Transactionality Failure: When bypass_account_state is False or not provided, and the associated account (instance.account) cannot process transactions. The exception contains a message identifying the account. - Locked Journal Entry: When the associated journal entry (instance.journal_entry) is locked, preventing modification of any related transactions. The error message describes the locked journal entry constraint.

Example

```python instance = TransactionModel(…) try:

transactionmodel_presave(instance) instance.save() # Save proceeds if no validation error occurs

except TransactionModelValidationError as e:: handle_error(str(e)) # Handle validation exception

```

Journal Entry Model

A Journal Entry (JE) is the foundation of all double entry accounting and financial data of any EntityModel. A JE encapsulates a collection of TransactionModel, which must contain two transactions at a minimum. Each transaction must perform a DEBIT or a CREDIT to an AccountModel. The JE Model performs additional validation to make sure that the sum of all DEBITs and the sum of all CREDITs are equal to keep the books balanced.

A JE by default will be un-posted, which means that simply creating a JE will have no effect on the EntityModel books. This behavior allows for constant refinement and persistence of JEs in the database without any impact on the books. Only Journal Entries contained within a POSTED LedgerModel (see LedgerModel for documentation) will have an impact in the EntityModel finances.

The JournalEntryModel also carries an optional EntityUnitModel, which are logical user-defined labels which help segregate the different financial statements into different business operations (see EntityUnitModel for documentation). Examples of EntityModelUnits are offices, departments, divisions, etc. The user may request financial statements by unit.

All JEs automatically generate a sequential Journal Entry Number, which takes into consideration the Fiscal Year of the JournalEntryModel instance. This functionality enables a human-readable tracking mechanism which helps with audits. It is also searchable and indexed to support quick searches and queries.

The JournalEntryModel is also responsible for validating the Financial Activity involved in the operations of the business. Whenever an account with ASSET_CA_CASH role is involved in a Journal Entry (see roles for more details), the JE is responsible for programmatically determine the kind of operation for the JE (Operating, Financing, Investing).

class django_ledger.models.journal_entry.ActivityEnum(*values)

Represents the database prefixes used for different types of accounting activities.

OPERATING

Prefix for a Journal Entry categorized as an Operating Activity.

Type:: str

INVESTING

Prefix for a Journal Entry categorized as an Investing Activity.

Type:: str

FINANCING

Prefix for a Journal Entry categorized as a Financing Activity.

Type:: str

class django_ledger.models.journal_entry.JournalEntryModel(*args, **kwargs)

Journal Entry Model Base Class From Abstract

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.journal_entry.JournalEntryModelAbstract(*args, **kwargs)

Abstract base model for handling journal entries in the bookkeeping system.

uuid

A unique identifier (primary key) for the journal entry, generated using uuid4().

Type:: UUID

je_number

A human-readable, unique, alphanumeric identifier for the journal entry (e.g., Voucher or Document Number). Includes the fiscal year as a prefix for organizational purposes.

Type:: str

timestamp

The date of the journal entry, used for financial statements. This timestamp applies to associated transactions.

Type:: datetime

description

An optional user-defined description for the journal entry.

Type:: str

entity_unit

A reference to a logical and self-contained structure within the EntityModel. Provides context for the journal entry. See EntityUnitModel documentation for details.

Type:: EntityUnitModel

activity

Indicates the nature of the activity associated with the journal entry. Must be one of the predefined ACTIVITIES (e.g., Operating, Financing, Investing) and is programmatically determined.

Type:: str

origin

Describes the origin or trigger for the journal entry (e.g., reconciliations, migrations, auto-generated). Max length: 30 characters.

Type:: str

posted

Determines whether the journal entry has been posted (affecting the books). Defaults to False.

Type:: bool

locked

Indicates whether the journal entry is locked, preventing further modifications. Defaults to False.

Type:: bool

ledger

A reference to the LedgerModel associated with this journal entry. This field is mandatory.

Type:: LedgerModel

is_closing_entry

Indicates if the journal entry is a closing entry. Defaults to False.

Type:: bool

can_delete() → bool: Checks if the journal entry can be deleted.

can_edit() → bool: Checks if the journal entry is editable.

can_generate_je_number() → bool

Checks if a Journal Entry Number can be generated.

Returns:: True if the Journal Entry can generate a JE number, otherwise False.
Return type:: bool

can_lock() → bool: Determines if the journal entry can be locked.

can_post(ignore_verify: bool = True) → bool: Determines if the journal entry can be posted.

can_unlock() → bool: Checks if the journal entry can be unlocked.

can_unpost() → bool: Checks if the journal entry can be un-posted.

clean(verify: bool = False, raise_exception: bool = True, txs_qs: TransactionModelQuerySet | None = None) → Tuple[TransactionModelQuerySet, bool]

Cleans the JournalEntryModel instance, optionally verifying it and generating a Journal Entry (JE) number if required.

Parameters:

verify (bool, optional) – If True, attempts to verify the JournalEntryModel during the cleaning process. Default is False.
raise_exception (bool, optional) – If True, raises an exception when the instance fails verification. Default is True.
txs_qs (TransactionModelQuerySet, optional) – A pre-fetched TransactionModelQuerySet. If provided, avoids additional database queries. The provided queryset is validated against the JournalEntryModel instance.

Returns:

A tuple containing: - The validated TransactionModelQuerySet for the JournalEntryModel instance. - A boolean indicating whether the instance passed verification.

Return type:

Tuple[TransactionModelQuerySet, bool]

Raises:

JournalEntryValidationError – If the instance has a timestamp in the future and is posted, or if verification fails and raise_exception is True.

delete(**kwargs)

Deletes the JournalEntryModel instance, ensuring it is allowed to be deleted.

Parameters:: **kwargs (dict) – Additional arguments passed to the parent delete method.
Raises:: JournalEntryValidationError – If the instance is not eligible for deletion.

property entity_last_closing_date: date | None

Retrieves the last closing date for an entity, if available.

This property returns the date of the most recent closing event associated with the entity. If no closing date exists, the result will be None.

Returns:: The date of the last closing event, or None if no closing date is available.
Return type:: Optional[date]

property entity_model: EntityModel

Provides access to the EntityModel related to the JournalEntryModel.

Returns:: The EntityModel instance linked to the instance LedgerModel.
Return type:: EntityModel

property entity_slug

Retrieves the unique slug associated with the entity.

The property first attempts to return the value stored in the _entity_slug attribute if it exists. If _entity_slug is not set, it falls back to the ledger.entity.slug attribute.

Returns:: The slug value from _entity_slug if available, or ledger.entity.slug otherwise.
Return type:: str

generate_activity(txs_qs: TransactionModelQuerySet | None = None, raise_exception: bool = True, force_update: bool = False) → str | None

Generates the activity for the Journal Entry model based on its transactions.

Parameters:

txs_qs (Optional[TransactionModelQuerySet], default None) – Queryset of TransactionModel instances for validation. If None, transactions are queried.
raise_exception (bool, default True) – Determines whether exceptions are raised during processing.
force_update (bool, default False) – Forces the regeneration of activity even if it exists.

Returns:

Generated activity or None if not applicable.

Return type:

Optional[str]

generate_je_number(commit: bool = False) → str

Generates the Journal Entry number in an atomic transaction.

Parameters:: commit (bool, default False) – Saves the generated JE number in the database.
Returns:: The generated or existing JE number.
Return type:: str

get_absolute_url() → str

Generates the URL to view the details of the journal entry.

Returns:: The absolute URL for the journal entry details.
Return type:: str

get_action_lock_url() → str

Generates the URL used to mark the journal entry as locked.

Returns:: The generated URL for marking the journal entry as locked.
Return type:: str

get_action_post_url() → str

Generates the URL used to mark the journal entry as posted.

Returns:: The generated URL for marking the journal entry as posted.
Return type:: str

get_action_unlock_url() → str

Generates the URL used to mark the journal entry as unlocked.

Returns:: The generated URL for marking the journal entry as unlocked.
Return type:: str

get_action_unpost_url() → str

Generates the URL used to mark the journal entry as unposted.

Returns:: The generated URL for marking the journal entry as unposted.
Return type:: str

classmethod get_activity_from_roles(role_set: List[str] | Set[str], validate: bool = False, raise_exception: bool = True) → str | None

Determines the financial activity type (e.g., operating, investing, financing) based on a set of account roles.

Parameters:

role_set (Union[List[str], Set[str]]) – The set of roles to analyze.
validate (bool, optional) – If True, validates the roles before analysis. Defaults to False.
raise_exception (bool, optional) – If True, raises an exception if multiple activities are detected. Defaults to True.

Returns:

The detected activity name, or None if no activity type is matched.

Return type:

Optional[str]

Raises:

JournalEntryValidationError – If multiple activities are detected and raise_exception is True.

get_activity_name() → str | None

Gets the name of the activity associated with this journal entry.

The activity indicates its categorization based on GAAP (e.g., operating, investing, financing).

Returns:: The activity name if defined, otherwise None.
Return type:: Optional[str]

get_delete_message() → str

Generates a confirmation message for deleting the JournalEntryModel instance.

Returns:: A confirmation message including the Journal Entry number and Ledger name.
Return type:: str

get_detail_txs_url() → str

Generates the URL to view transaction details of the journal entry.

Returns:: The URL for transaction details of the journal entry.
Return type:: str

get_detail_url() → str

Generates the detail URL for the journal entry.

Returns:: The URL for updating or viewing journal entry details.
Return type:: str

get_entity_last_closing_date() → date | None

Retrieves the last closing date for the entity associated with the Journal Entry.

Returns:: The last closing date if one exists, otherwise None.
Return type:: Optional[date]

get_entity_unit_name(no_unit_name: str = '') → str

Retrieves the name of the entity unit associated with the Journal Entry.

Parameters:: no_unit_name (str) – The fallback name to return if no unit is associated.
Returns:: The name of the entity unit, or the fallback provided.
Return type:: str

get_journal_entry_create_url() → str

Constructs the URL to create a new journal entry associated with a specific ledger and entity.

Returns:: The URL to create a journal entry.
Return type:: str

get_journal_entry_list_url() → str

Constructs the URL to access the list of journal entries associated with a specific ledger and entity.

Returns:: The URL for the journal entry list.
Return type:: str

get_lock_url() → str

Generates the URL to mark the journal entry as locked.

Returns:: The URL for locking the journal entry.
Return type:: str

get_post_url() → str

Generates the URL to mark the journal entry as posted.

Returns:: The URL for posting the journal entry.
Return type:: str

get_transaction_queryset(select_accounts: bool = True) → TransactionModelQuerySet

Retrieves the TransactionModelQuerySet associated with this JournalEntryModel instance.

Parameters:: select_accounts (bool, optional) – If True, prefetches the related AccountModel for each transaction. Defaults to True.
Returns:: A queryset containing transactions related to this journal entry. If select_accounts is True, the accounts are included in the query as well.
Return type:: TransactionModelQuerySet

get_txs_balances(txs_qs: TransactionModelQuerySet | None = None, as_dict: bool = False) → TransactionModelQuerySet | Dict[str, Decimal]

Calculates the total CREDIT and DEBIT balances for the journal entry.

This method performs an aggregate database query to compute the sum of CREDITs and DEBITs across the transactions related to this journal entry. Optionally, a pre-fetched TransactionModelQuerySet can be supplied for efficiency. Validation is performed to ensure that all transactions belong to this journal entry.

Parameters:

txs_qs (TransactionModelQuerySet, optional) – A pre-fetched queryset of transactions. If None, the queryset is fetched automatically.
as_dict (bool, optional) – If True, returns the results as a dictionary with keys “credit” and “debit”. Defaults to False.

Returns:

If as_dict is False, returns a queryset of aggregated balances. If as_dict is True, returns a dictionary containing the CREDIT and DEBIT totals.

Return type:

Union[TransactionModelQuerySet, Dict[str, Decimal]]

Raises:

JournalEntryValidationError – If the provided queryset is invalid or does not belong to this journal entry.

get_txs_roles(txs_qs: TransactionModelQuerySet | None = None, exclude_cash_role: bool = False) → Set[str]

Retrieves the set of account roles involved in the journal entry’s transactions.

This method extracts the roles associated with the accounts linked to each transaction. Optionally, the CASH role can be excluded from the results.

Parameters:

txs_qs (TransactionModelQuerySet, optional) – A pre-fetched queryset of transactions. If None, the queryset is fetched automatically.
exclude_cash_role (bool, optional) – If True, excludes the CASH role from the result. Defaults to False.

Returns:

A set of account roles associated with this journal entry’s transactions.

Return type:

Set[str]

get_unlock_url() → str

Generates the URL to mark the journal entry as unlocked.

Returns:: The URL for unlocking the journal entry.
Return type:: str

get_unpost_url() → str

Generates the URL to mark the journal entry as unposted.

Returns:: The URL for unposting the journal entry.
Return type:: str

has_activity() → bool

Checks if the journal entry has an associated activity.

Returns:: True if an activity is defined for the journal entry, otherwise False.
Return type:: bool

is_balance_valid(txs_qs: TransactionModelQuerySet, raise_exception: bool = True) → bool

Validates whether the DEBITs and CREDITs of the transactions balance correctly.

Parameters:

txs_qs (TransactionModelQuerySet) – A QuerySet containing transactions to validate.
raise_exception (bool) – Whether to raise a JournalEntryValidationError if the validation fails.

Returns:

True if the transactions are balanced, otherwise False.

Return type:

bool

Raises:

JournalEntryValidationError – If the transactions are not balanced and raise_exception is True.

is_cash_involved(txs_qs: TransactionModelQuerySet | None = None) → bool

Checks if the transactions involve cash assets.

Parameters:: txs_qs (Optional[TransactionModelQuerySet]) – Transactions to evaluate. If None, defaults to class behavior.
Returns:: True if cash assets are involved, otherwise False.
Return type:: bool

is_financing() → bool

Checks if the Journal Entry is categorized as a financing activity.

Returns:: True if the activity is financing, otherwise False.
Return type:: bool

is_in_locked_period(new_timestamp: datetime | date | None = None) → bool

Checks if the current Journal Entry falls within a locked period.

Parameters:: new_timestamp (Optional[Union[date, datetime]])) – An optional date or timestamp to be checked instead of the current timestamp.
Returns:: bool
Return type:: True if the Journal Entry is in a locked period, otherwise False.

is_investing() → bool

Checks if the Journal Entry is categorized as an investing activity.

Returns:: True if the activity is investing, otherwise False.
Return type:: bool

is_locked() → bool

Determines if the Journal Entry is locked.

A Journal Entry is considered locked if it is posted, explicitly marked as locked, falls within a locked period, or the associated ledger is locked.

Returns:: True if the Journal Entry is locked, otherwise False.
Return type:: bool

is_operating() → bool

Checks if the Journal Entry is categorized as an operating activity.

Returns:: True if the activity is operating, otherwise False.
Return type:: bool

is_posted() → bool: Returns whether the journal entry has been posted.

is_txs_qs_coa_valid(txs_qs: TransactionModelQuerySet, raise_exception: bool = True) → bool

Validates that all transactions in the QuerySet are associated with the same Chart of Accounts (COA).

Parameters:: txs_qs (TransactionModelQuerySet) – A QuerySet containing transactions to validate.
Returns:: True if all transactions have the same Chart of Accounts, otherwise False.
Return type:: bool

is_txs_qs_valid(txs_qs: TransactionModelQuerySet, raise_exception: bool = True) → bool

Validates whether the given Transaction QuerySet belongs to the current Journal Entry.

Parameters:

txs_qs (TransactionModelQuerySet) – A QuerySet containing transactions to validate.
raise_exception (bool) – Whether to raise a JournalEntryValidationError if the validation fails.

Returns:

True if all transactions belong to the Journal Entry, otherwise False.

Return type:

bool

Raises:

JournalEntryValidationError – If validation fails and raise_exception is True.

is_verified() → bool

Checks if the Journal Entry is verified.

Returns:: True if the Journal Entry is verified, otherwise False.
Return type:: bool

ledger_is_locked()

Determines whether the ledger is locked.

This method checks the current state of the ledger to determine if it is locked and unavailable for further operations. It looks for an annotated attribute _ledger_is_locked and returns its value if found. If the attribute is not set, it delegates the check to the actual is_locked method of the ledger object.

Returns:: A boolean value indicating whether the ledger is locked.
Return type:: bool

lock(**kwargs): Proxy function for mark_as_locked method.

mark_as_locked(commit: bool = False, raise_exception: bool = False, **kwargs)

Locked JournalEntryModels do not allow transactions to be edited.

Parameters:

commit (bool) – Commits changes into the Database, Defaults to False.
raise_exception (bool) – Raises JournalEntryValidationError if cannot lock. Defaults to False.
kwargs (dict) – Additional keyword arguments.

mark_as_posted(commit: bool = False, verify: bool = True, force_lock: bool = False, raise_exception: bool = False, **kwargs): Posted transactions show on the EntityModel ledger and financial statements. :param commit: Commits changes into the Database, Defaults to False. :type commit: bool :param verify: Verifies JournalEntryModel before marking as posted. Defaults to False. :type verify: bool :param force_lock: Forces to lock the JournalEntry before is posted. :type force_lock: bool :param raise_exception: Raises JournalEntryValidationError if cannot post. Defaults to False. :type raise_exception: bool :param kwargs: Additional keyword arguments. :type kwargs: dict

mark_as_unlocked(commit: bool = False, raise_exception: bool = False, **kwargs)

Unlocked JournalEntryModels allow transactions to be edited.

Parameters:

commit (bool) – Commits changes into the Database, Defaults to False.
raise_exception (bool) – Raises JournalEntryValidationError if cannot lock. Defaults to False.
kwargs (dict) – Additional keyword arguments.

mark_as_unposted(commit: bool = False, raise_exception: bool = False, **kwargs)

Un-posted JournalEntryModels do not show on the EntityModel ledger and financial statements.

Parameters:

commit (bool) – Commits changes into the Database, Defaults to False.
raise_exception (bool) – Raises JournalEntryValidationError if cannot post. Defaults to False.
kwargs (dict) – Additional keyword arguments.

post(**kwargs): Proxy function for mark_as_posted method.

save(verify: bool = True, post_on_verify: bool = False, *args, **kwargs)

Saves the JournalEntryModel instance, with optional verification and posting prior to saving.

Parameters:

verify (bool, optional) – If True, verifies the transactions of the JournalEntryModel before saving. Default is True.
post_on_verify (bool, optional) – If True, posts the JournalEntryModel if verification is successful and can_post() is True. Default is False.

Returns:

The saved JournalEntryModel instance.

Return type:

JournalEntryModel

Raises:

JournalEntryValidationError – If the instance fails verification or encounters an issue during save.

unlock(**kwargs): Proxy function for mark_as_unlocked method.

unpost(**kwargs): Proxy function for mark_as_unposted method.

validate_for_entity(entity_model: EntityModel | str | UUID, raise_exception: bool = True) → bool

Validates whether the given entity_model owns thr Journal Entry instance.

This method checks if the provided entity_model owns the Journal Entry model instance. The entity_model can be of type EntityModel, str, or UUID. The method performs type-specific checks to ensure proper validation and returns the validation result.

Parameters:: entity_model (Union[EntityModel, str, UUID]) – The entity to validate against. It can either be an instance of the EntityModel, a string representation of a UUID, or a UUID object.
Returns:: A boolean value. True if the given entity_model corresponds to the current entity’s UUID, otherwise False.
Return type:: bool

verify(txs_qs: TransactionModelQuerySet | None = None, force_verify: bool = False, raise_exception: bool = True, **kwargs) → Tuple[TransactionModelQuerySet, bool]

Verifies the validity of the Journal Entry model instance.

Parameters:

txs_qs (Optional[TransactionModelQuerySet], default None) – Queryset of TransactionModel instances to validate. If None, transactions are queried.
force_verify (bool, default False) – Forces re-verification even if already verified.
raise_exception (bool, default True) – Determines if exceptions are raised on validation failure.
kwargs (dict) – Additional options.

Returns:

The TransactionModelQuerySet associated with the JournalEntryModel.
A boolean indicating whether verification was successful.

Return type:

Tuple[TransactionModelQuerySet, bool]

class django_ledger.models.journal_entry.JournalEntryModelManager(*args, **kwargs)

A custom manager for the JournalEntryModel that extends Django’s default Manager with additional query features. It allows complex query handling based on relationships to the EntityModel and the authenticated UserModel.

This manager provides utility methods for generating filtered querysets (e.g., entries associated with specific users or entities), as well as annotations for convenience in query results.

for_entity(entity_slug: str | EntityModel, user_model) → JournalEntryModelQuerySet

Filters the JournalEntryModel queryset for a specific entity and user.

This method provides a way to fetch journal entries related to a specific EntityModel, identified by its slug or model instance, with additional filtering scoped to the user.

Parameters:

entity_slug (str or EntityModel) – The slug of the entity (or an instance of EntityModel) used for filtering.
user_model (UserModel) – An authenticated Django user object.

Returns:

A customized queryset containing journal entries associated with the given entity and restricted by the user’s access permissions.

Return type:

for_user(user_model) → JournalEntryModelQuerySet

Filters the JournalEntryModel queryset for the given user.

Superusers will have access to all journal entries.
Other authenticated users will only see entries for entities where they are admins or managers.

Parameters:: user_model (UserModel) – An authenticated Django user object.
Returns:: A filtered queryset restricted by the user’s entity relationships.
Return type:: JournalEntryModelQuerySet

get_queryset() → JournalEntryModelQuerySet

Returns the default queryset for JournalEntryModel with additional annotations applied.

Annotations: - _entity_slug: The slug of the related EntityModel. - txs_count: The count of transactions (related TransactionModel instances)

for each journal entry.

Returns:: A custom queryset enhanced with annotations.
Return type:: JournalEntryModelQuerySet

class django_ledger.models.journal_entry.JournalEntryModelQuerySet(model=None, query=None, using=None, hints=None)

A custom QuerySet for working with Journal Entry models, providing additional convenience methods and validations for specific use cases.

This class enhances Django’s default QuerySet by adding tailored methods to manage and filter Journal Entries, such as handling posted, unposted, locked entries, and querying entries associated with specific ledgers.

create(verify_on_save: bool = False, force_create: bool = False, **kwargs)

Creates a new Journal Entry while enforcing business logic validations.

This method overrides Django’s default create() to ensure that Journal Entries cannot be created in a “posted” state unless explicitly overridden. Additionally, it offers optional pre-save verification.

Parameters:

verify_on_save (bool) – If True, performs a verification step before saving. This avoids additional database queries for validation when creating new entries. Should be used when the Journal Entry needs no transactional validation.
force_create (bool) – If True, allows the creation of a Journal Entry even in a “posted” state. Use with caution and only if you are certain of the consequences.
**kwargs (dict) – Additional keyword arguments passed to instantiate the Journal Entry model.

Returns:

The newly created Journal Entry.

Return type:

JournalEntryModel

Raises:

FieldError – Raised if attempting to create a “posted” Journal Entry without setting force_create=True.

for_ledger(ledger_pk: str | UUID | LedgerModel)

Filters the QuerySet to include Journal Entries associated with a specific Ledger.

Parameters:: ledger_pk (str, UUID, or LedgerModel) – The LedgerModel instance, its UUID, or a string representation of the UUID to identify the Ledger.
Returns:: A filtered QuerySet of Journal Entries associated with the specified Ledger.
Return type:: JournalEntryModelQuerySet

locked()

Filters the QuerySet to include only “locked” Journal Entries.

Returns:: A filtered QuerySet containing only locked Journal Entries.
Return type:: JournalEntryModelQuerySet

posted()

Filters the QuerySet to include only “posted” Journal Entries.

Returns:: A filtered QuerySet containing only posted Journal Entries.
Return type:: JournalEntryModelQuerySet

unlocked()

Filters the QuerySet to include only “unlocked” Journal Entries.

Returns:: A filtered QuerySet containing only unlocked Journal Entries.
Return type:: JournalEntryModelQuerySet

unposted()

Filters the QuerySet to include only “unposted” Journal Entries.

Returns:: A filtered QuerySet containing only unposted Journal Entries.
Return type:: JournalEntryModelQuerySet

exception django_ledger.models.journal_entry.JournalEntryValidationError(message, code=None, params=None)

Bank Account Model

A Bank Account refers to the financial institution which holds financial assets for the EntityModel. A bank account usually holds cash, which is a Current Asset. Transactions may be imported using the open financial format specification OFX into a staging area for final disposition into the EntityModel ledger.

class django_ledger.models.bank_account.BankAccountModel(*args, **kwargs)

Base Bank Account Model Implementation

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.bank_account.BankAccountModelAbstract(*args, **kwargs)

This is the main abstract class which the BankAccountModel database will inherit from. The BankAccountModel inherits functionality from the following MixIns:

BankAccountInfoMixIn

CreateUpdateMixIn

uuid

This is a unique primary key generated for the table. The default value of this field is uuid4().

Type:: UUID

name

A user defined name for the bank account as a String.

Type:: str

entity_model

The EntityModel associated with the BankAccountModel instance.

Type:: EntityModel

account_model

The AccountModel associated with the BankAccountModel instance. Must be an account with role ASSET_CA_CASH.

Type:: AccountModel

active

Determines whether the BackAccountModel instance bank account is active. Defaults to True.

Type:: bool

hidden

Determines whether the BackAccountModel instance bank account is hidden. Defaults to False.

Type:: bool

class django_ledger.models.bank_account.BankAccountModelManager(*args, **kwargs)

Custom defined Model Manager for the BankAccountModel.

for_entity(entity_slug, user_model) → BankAccountModelQuerySet

Allows only the authorized user to query the BankAccountModel for a given EntityModel. This is the recommended initial QuerySet.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – Logged in and authenticated django UserModel instance.

get_queryset() → BankAccountModelQuerySet: Return a new QuerySet object. Subclasses can override this method to customize the behavior of the Manager.

class django_ledger.models.bank_account.BankAccountModelQuerySet(model=None, query=None, using=None, hints=None)

A custom defined QuerySet for the BankAccountModel.

active() → QuerySet

Active bank accounts which can be used to create new transactions.

Returns:: A filtered BankAccountModelQuerySet of active accounts.
Return type:: BankAccountModelQuerySet

hidden() → QuerySet

Hidden bank accounts which can be used to create new transactions. but will not show in drop down menus in the UI.

Returns:: A filtered BankAccountModelQuerySet of active accounts.
Return type:: BankAccountModelQuerySet

exception django_ledger.models.bank_account.BankAccountValidationError(message, code=None, params=None)

Chart of Accounts Model

Chart Of Accounts

A Chart of Accounts (CoA) is a fundamental component of financial management in Django Ledger. It serves as the backbone of financial statements and is organized within a ChartOfAccountModel.

### Key Features

Account Roles: The CoA includes various account types such as: - Cash - Accounts Receivable - Expenses - Liabilities - Income
Hierarchical Structure: Accounts are logically grouped to form financial statements. For example, the Balance

Sheet may have a structure like this:

Fixed Assets - Tangible Assets
- Building
- Plant & Equipment
- Machinery
- Intangible Assets

Financial Statement Preparation: Individual account balances are aggregated based on the CoA and AccountModel

roles to create comprehensive financial statements.

### Usage in EntityModel

Every EntityModel must have a default CoA to create any type of transaction.
If no explicit CoA is specified, the EntityModel’s default CoA is used.
Only ONE Chart of Accounts can be used when creating Journal Entries.
Commingling between different CoAs is not allowed to maintain the integrity of Journal Entries.

This structure ensures a clear and organized approach to financial management within Django Ledger, facilitating accurate record-keeping and reporting.

class django_ledger.models.chart_of_accounts.ChartOfAccountModel(*args, **kwargs)

Base ChartOfAccounts Model

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.chart_of_accounts.ChartOfAccountModelAbstract(*args, **kwargs)

Abstract base class for the Chart of Account model.

uuid

UUID field for the chart of account model (primary key).

Type:: UUIDField

entity

ForeignKey to the EntityModel.

Type:: ForeignKey

active

BooleanField indicating whether the chart of account is active or not.

Type:: BooleanField

description

TextField storing the description of the chart of account.

Type:: TextField

objects

Manager for the ChartOfAccountModel.

Type:: ChartOfAccountModelManager

can_activate() → bool

Check if the ChartOffAccountModel instance can be activated.

Return type:: True if the object can be activated, False otherwise.

can_deactivate() → bool

Check if the ChartOffAccountModel instance can be deactivated.

Return type:: True if the object can be deactivated, False otherwise.

clean(): Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

configure(raise_exception: bool = True)

A method that properly configures the ChartOfAccounts model and creates the appropriate hierarchy boilerplate to support the insertion of new accounts into the chart of account model tree. This method must be called every time the ChartOfAccounts model is created.

Parameters:: raise_exception (bool, optional) – Whether to raise an exception if root nodes already exist in the Chart of Accounts (default is True). This indicates that the ChartOfAccountModel instance is already configured.

create_account(code: str, role: str, name: str, balance_type: str, active: bool, root_account_qs: AccountModelQuerySet | None = None)

Proper method for inserting a new Account Model into a CoA. Use this in liu of the direct instantiation of the AccountModel of using the django related manager.

Parameters:

code (str) – The code of the account to be created.
role (str) – The role of the account. This can be a user-defined value.
name (str) – The name of the account.
balance_type (str) – The balance type of the account. This can be a user-defined value.
active (bool) – Specifies whether the account is active or not.
root_account_qs (Optional[AccountModelQuerySet], optional) – The query set of root accounts to which the created account should be linked. Defaults to None.

Returns:

The created account model instance.

Return type:

generate_slug(commit: bool = False, raise_exception: bool = False) → str

Generates and assigns a slug based on the ChartOfAccounts model instance EntityModel information.

Parameters:: raise_exception (bool, optional) – If set to True, it will raise a ChartOfAccountsModelValidationError if the self.slug is already set.
Returns:: The generated slug for the Chart of Accounts.
Return type:: str
Raises:: ChartOfAccountsModelValidationError – If raise_exception is set to True and self.slug is already set.

get_account_root_node(account_model: AccountModel, root_account_qs: AccountModelQuerySet | None = None, as_queryset: bool = False) → AccountModel

Fetches the root node of the ChartOfAccountModel instance. The root node is the highest level of the CoA hierarchy. It can be used to traverse the hierarchy of the CoA structure downstream.

Parameters:

account_model (AccountModel) – The account model for which to find the root node.
root_account_qs (Optional[AccountModelQuerySet], optional) – The queryset of root accounts. If not provided, it will be retrieved using get_coa_root_accounts_qs method.
as_queryset (bool, optional) – If True, return the root account queryset instead of a single root account. Default is False.

Returns:

If as_queryset is True, returns the root account queryset. Otherwise, returns a single root account.

Return type:

Union[AccountModelQuerySet, AccountModel]

Raises:

ChartOfAccountsModelValidationError – If the account model is not part of the chart of accounts.

get_coa_account_tree() → Dict

Performs a bulk dump of the ChartOfAccounts model instance accounts to a dictionary. The method invokes the`dump_bulk` method on the ChartOfAccount model instance root node. See Django Tree Beard documentation for more information.

Returns:: A dictionary containing all accounts from the chart of accounts in a nested structure.
Return type:: Dict

get_coa_accounts(active_only: bool = True) → AccountModelQuerySet

Returns the AccountModelQuerySet associated with the ChartOfAccounts model instance.

Parameters:: active_only (bool, optional) – Flag to indicate whether to retrieve only active accounts or all accounts. Default is True.
Returns:: A queryset containing accounts from the chart of accounts.
Return type:: AccountModelQuerySet

get_coa_root_accounts_qs() → AccountModelQuerySet

Retrieves the root accounts in the chart of accounts.

Returns:: A queryset containing the root accounts in the chart of accounts.
Return type:: AccountModelQuerySet

get_coa_root_node() → AccountModel

Retrieves the root node of the chart of accounts.

Returns:: The root node of the chart of accounts.
Return type:: AccountModel

get_non_root_coa_accounts_qs() → AccountModelQuerySet

Returns a query set of non-root accounts in the chart of accounts.

Returns:: A query set of non-root accounts in the chart of accounts.
Return type:: AccountModelQuerySet

insert_account(account_model: AccountModel, root_account_qs: AccountModelQuerySet | None = None)

This method inserts the given account model into the chart of accounts (COA) instance. It first verifies if the account model’s COA model ID matches the COA’s UUID. If not, it raises a ChartOfAccountsModelValidationError. If the root_account_qs is not provided, it retrieves the root account query set using the get_coa_root_accounts_qs method. Providing a pre-fetched root_account_qs avoids unnecessary retrieval of the root account query set every an account model is inserted into the CoA.

Next, it validates the provided root_account_qs if it is not None. Then, it obtains the root node for the account model using the get_account_root_node method and assigns it to account_root_node.

Finally, it adds the account model as a child to the account_root_node and retrieves the updated COA accounts query set using the get_non_root_coa_accounts_qs method. It returns the inserted account model found in the COA accounts query set.

Parameters:

account_model (AccountModel) – The account model to be inserted into the chart of accounts.
root_account_qs (Optional[AccountModelQuerySet], default=None) – The root account query set. If not provided, it will be obtained using the get_coa_root_accounts_qs method.

Returns:

The inserted account model.

Return type:

Raises:

ChartOfAccountsModelValidationError – If the provided account model has an invalid COA model ID for the current COA.

is_active() → bool

Check if the ChartOfAccountModel instance is active.

Returns:: True if the ChartOfAccountModel instance is active, False otherwise.
Return type:: bool

is_default() → bool

Check if the ChartOfAccountModel instance is set as the default for the EntityModel.

Returns:: True if the ChartOfAccountModel instance is set as the default for the EntityModel. Else, False.
Return type:: bool

mark_as_active(commit: bool = False, raise_exception: bool = False, **kwargs)

Marks the current Chart of Accounts as Active.

Parameters:

commit (bool) – Commit the action into the Database. Default is False.
raise_exception (bool) – Raises exception if Chart of Account model instance is already active. Default is False.

mark_as_active_url() → str

Returns the URL to mark the current Chart of Accounts instances as active.

Returns:: The URL as a String.
Return type:: str

mark_as_default(commit: bool = False, raise_exception: bool = False, **kwargs)

Marks the current Chart of Accounts instances as default for the EntityModel.

Parameters:

commit (bool) – Commit the action into the Database. Default is False.
raise_exception (bool) – Raises exception if Chart of Account model instance is already marked as default.

mark_as_default_url() → str

Returns the URL to mark the current Chart of Accounts instances as Default for the EntityModel.

Returns:: The URL as a String.
Return type:: str

mark_as_inactive(commit: bool = False, raise_exception: bool = False, **kwargs)

Marks the current Chart of Accounts as Active.

Parameters:

commit (bool) – Commit the action into the Database. Default is False.
raise_exception (bool) – Raises exception if Chart of Account model instance is already active. Default is False.

mark_as_inactive_url() → str

Returns the URL to mark the current Chart of Accounts instances as inactive.

Returns:: The URL as a String.
Return type:: str

validate_account_model_qs(account_model_qs: AccountModelQuerySet)

Validates the given AccountModelQuerySet for the ChartOfAccountsModel.

Parameters:: account_model_qs (AccountModelQuerySet) – The AccountModelQuerySet to validate.
Raises:: ChartOfAccountsModelValidationError – If the account_model_qs is not an instance of AccountModelQuerySet or if it contains an account model with a different coa_model_id than the current CoA model.

class django_ledger.models.chart_of_accounts.ChartOfAccountModelManager(*args, **kwargs)

A custom defined ChartOfAccountModelManager that will act as an interface to handling the initial DB queries to the ChartOfAccountModel.

for_entity(entity_model, user_model) → ChartOfAccountModelQuerySet

Fetches a QuerySet of ChartOfAccountsModel associated with a specific EntityModel & UserModel. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – Logged in and authenticated django UserModel instance.

Returns:

Returns a ChartOfAccountQuerySet with applied filters.

Return type:

ChartOfAccountQuerySet

for_user(user_model) → ChartOfAccountModelQuerySet

Fetches a QuerySet of ChartOfAccountModel that the UserModel as access to. May include ChartOfAccountModel from multiple Entities. The user has access to bills if: 1. Is listed as Manager of Entity. 2. Is the Admin of the Entity.

Parameters:: user_model – Logged in and authenticated django UserModel instance.
Returns:: Returns a ChartOfAccountQuerySet with applied filters.
Return type:: ChartOfAccountQuerySet

get_queryset(): Return a new QuerySet object. Subclasses can override this method to customize the behavior of the Manager.

class django_ledger.models.chart_of_accounts.ChartOfAccountModelQuerySet(model=None, query=None, using=None, hints=None)

active(): QuerySet method to retrieve active items.

exception django_ledger.models.chart_of_accounts.ChartOfAccountsModelValidationError(message, code=None, params=None)

Default Chart of Accounts

This is the base Chart of Accounts that has all the possible accounts that are useful for the preparation of the Financial Statements. A user may choose to use the default CoA at the creation of each EntityModel but it is not required. The default CoA is intended to provide a QuickStart solution for most use cases.

The Chart of Accounts is broadly bifurcated into 5 different Sections:

Assets:
Liabilities
Shareholder’s Equity
Income
COGS
Expenses

The Django Ledger Default Chart of Accounts must include the following fields:

Code - String
Role - A choice from any of the possible account roles (see django_ledger.roles module).
Balance Type - A CREDIT or DEBIT balance account setting.
Name - A human readable name.
Parent - The parent account of the AccountModel instance.

If the DEFAULT_CHART_OF_ACCOUNTS setting is present, the default CoA will be replace by such setting.

Default Chart of Accounts Table

code	role	balance_type	name	root_group
1910	asset_adjustment	debit	Securities Unrealized Gains/Losses	root_assets
1920	asset_adjustment	debit	PPE Unrealized Gains/Losses	root_assets
1010	asset_ca_cash	debit	Cash	root_assets
1050	asset_ca_mkt_sec	debit	Short Term Investments	root_assets
1200	asset_ca_inv	debit	Inventory	root_assets
1300	asset_ca_prepaid	debit	Prepaid Expenses	root_assets
1100	asset_ca_recv	debit	Accounts Receivable	root_assets
1110	asset_ca_uncoll	credit	Uncollectibles	root_assets
1810	asset_ia	debit	Goodwill	root_assets
1820	asset_ia	debit	Intellectual Property	root_assets
1830	asset_ia_accum_amort	credit	Less: Intangible Assets Accumulated Amortization	root_assets
1520	asset_lti_land	debit	Land	root_assets
1510	asset_lti_notes	debit	Notes Receivable	root_assets
1530	asset_lti_sec	debit	Securities	root_assets
1610	asset_ppe_build	debit	Buildings	root_assets
1611	asset_ppe_build_accum_depr	credit	Less: Buildings Accumulated Depreciation	root_assets
1630	asset_ppe_equip	debit	Equipment	root_assets
1631	asset_ppe_equip_accum_depr	credit	Less: Equipment Accumulated Depreciation	root_assets
1620	asset_ppe_plant	debit	Plant	root_assets
1640	asset_ppe_plant	debit	Vehicles	root_assets
1650	asset_ppe_plant	debit	Furniture & Fixtures	root_assets
1621	asset_ppe_plant_depr	credit	Less: Plant Accumulated Depreciation	root_assets
1641	asset_ppe_plant_depr	credit	Less: Vehicles Accumulated Depreciation	root_assets
1651	asset_ppe_plant_depr	credit	Less: Furniture & Fixtures Accumulated Depreciation	root_assets
3910	eq_adjustment	credit	Available for Sale	root_capital
3920	eq_adjustment	credit	PPE Unrealized Gains/Losses	root_capital
3010	eq_capital	credit	Capital Account 1	root_capital
3020	eq_capital	credit	Capital Account 2	root_capital
3030	eq_capital	credit	Capital Account 3	root_capital
3930	eq_dividends	debit	Dividends & Distributions	root_capital
3110	eq_stock_common	credit	Common Stock	root_capital
3120	eq_stock_preferred	credit	Preferred Stock	root_capital
5010	cogs_regular	debit	Cost of Goods Sold	root_cogs
6075	ex_amortization	debit	Amortization Expense	root_expenses
6070	ex_depreciation	debit	Depreciation Expense	root_expenses
6130	ex_interest	debit	Interest Expense	root_expenses
6500	ex_other	debit	Misc. Expense	root_expenses
6010	ex_regular	debit	Advertising	root_expenses
6020	ex_regular	debit	Amortization	root_expenses
6030	ex_regular	debit	Auto Expense	root_expenses
6040	ex_regular	debit	Bad Debt	root_expenses
6050	ex_regular	debit	Bank Charges	root_expenses
6060	ex_regular	debit	Commission Expense	root_expenses
6080	ex_regular	debit	Employee Benefits	root_expenses
6081	ex_regular	debit	Employee Wages	root_expenses
6090	ex_regular	debit	Freight	root_expenses
6110	ex_regular	debit	Gifts	root_expenses
6120	ex_regular	debit	Insurance	root_expenses
6140	ex_regular	debit	Professional Fees	root_expenses
6150	ex_regular	debit	License Expense	root_expenses
6170	ex_regular	debit	Maintenance Expense	root_expenses
6180	ex_regular	debit	Meals & Entertainment	root_expenses
6190	ex_regular	debit	Office Expense	root_expenses
6220	ex_regular	debit	Printing	root_expenses
6230	ex_regular	debit	Postage	root_expenses
6240	ex_regular	debit	Rent	root_expenses
6250	ex_regular	debit	Maintenance & Repairs	root_expenses
6251	ex_regular	debit	Maintenance	root_expenses
6252	ex_regular	debit	Repairs	root_expenses
6253	ex_regular	debit	HOA	root_expenses
6254	ex_regular	debit	Snow Removal	root_expenses
6255	ex_regular	debit	Lawn Care	root_expenses
6260	ex_regular	debit	Salaries	root_expenses
6270	ex_regular	debit	Supplies	root_expenses
6290	ex_regular	debit	Utilities	root_expenses
6292	ex_regular	debit	Sewer	root_expenses
6293	ex_regular	debit	Gas	root_expenses
6294	ex_regular	debit	Garbage	root_expenses
6295	ex_regular	debit	Electricity	root_expenses
6300	ex_regular	debit	Property Management	root_expenses
6400	ex_regular	debit	Vacancy	root_expenses
6210	ex_taxes	debit	Payroll Taxes	root_expenses
6280	ex_taxes	debit	Taxes	root_expenses
4040	in_gain_loss	credit	Capital Gain/Loss Income	root_income
4030	in_interest	credit	Interest Income	root_income
4010	in_operational	credit	Sales Income	root_income
4050	in_other	credit	Other Income	root_income
4020	in_passive	credit	Investing Income	root_income
2010	lia_cl_acc_payable	credit	Accounts Payable	root_liabilities
2060	lia_cl_def_rev	credit	Deferred Revenues	root_liabilities
2030	lia_cl_int_payable	credit	Interest Payable	root_liabilities
2050	lia_cl_ltd_mat	credit	Current Maturities LT Debt	root_liabilities
2070	lia_cl_other	credit	Other Payables	root_liabilities
2040	lia_cl_st_notes_payable	credit	Short-Term Notes Payable	root_liabilities
2020	lia_cl_wages_payable	credit	Wages Payable	root_liabilities
2120	lia_ltl_bonds	credit	Bonds Payable	root_liabilities
2130	lia_ltl_mortgage	credit	Mortgage Payable	root_liabilities
2110	lia_ltl_notes	credit	Long Term Notes Payable	root_liabilities

django_ledger.models.coa_default.get_default_coa_rst(default_coa: Dict | None = None) → str

Converts the provided Chart of Account into restructuredText format. :param default_coa: A dictionary of chart of accounts. Must follow the same keys as CHART_OF_ACCOUNTS.

Returns:: The table in RestructuredText format.
Return type:: str

django_ledger.models.coa_default.verify_unique_code(): A function that verifies that there are no duplicate code in the Default CoA during the development and launch.

Item Model

The Items refer to the additional detail provided to Bills, Invoices, Purchase Orders and Estimates for the purposes of documenting a breakdown of materials, labor, equipment, and other resources used for the purposes of the business operations.

The items associated with any of the aforementioned models are responsible for calculating the different amounts that ultimately drive the behavior of Journal Entries onto the company books.

Each item must be assigned a UnitOfMeasureModel which is the way or method used to quantify such resource. Examples are Pounds, Gallons, Man Hours, etc used to measure how resources are quantified when associated with a specific ItemTransactionModel. If many unit of measures are used for the same item, it would constitute a different item hence a new record must be created.

ItemsTransactionModels constitute the way multiple items and used resources are associated with Bills, Invoices, Purchase Orders and Estimates. Each transaction will record the unit of measure and quantity of each resource. Totals will be calculated and associated with the containing model at the time of update.

class django_ledger.models.items.ItemModel(*args, **kwargs)

Base ItemModel from Abstract.

exception DoesNotExist

exception MultipleObjectsReturned

class django_ledger.models.items.ItemModelAbstract(*args, **kwargs)

Base implementation of the ItemModel.

uuid

This is a unique primary key generated for the table. The default value of this field is uuid4().

Type:: UUID

name

Human readable name of the ItemModel instance. Maximum of 100 characters.

Type:: str

item_role

A choice of ITEM_ROLE_CHOICES that determines whether the ItemModel should be treated as an expense, inventory, service or product.

Type:: str

item_type

A choice of ITEM_TYPE_CHOICES that determines whether the ItemModel should be treated as labor, material, equipment, lump sum or other.

Type:: str

uom

The assigned UnitOfMeasureModel of the ItemModel instance. Mandatory.

Type:: UnitOfMeasureModel

sku

The SKU number associated with the ItemModel instance. Maximum 50 characters.

Type:: str

upc

The UPC number associated with the ItemModel instance. Maximum 50 characters.

Type:: str

item_id

EntityModel specific id associated with the ItemModel instance. Maximum 50 characters.

Type:: str

item_number

Auto generated human-readable item number.

Type:: str

is_active

Determines if the ItemModel instance is considered active. Defaults to True.

Type:: bool

default_amount

The default, prepopulated monetary amount of the ItemModel instance .

Type:: Decimal

for_inventory

Legacy field used to determine if the ItemModel instance is considered an inventory item. Mandatory. Superseded by item_role field. Will be deprecated.

Type:: bool

is_product_or_service

Legacy field used to determine if the ItemModel instance is considered a product or service item. Mandatory. Superseded by item_role field. Will be deprecated.

Type:: bool

sold_as_unit

Determines if only whole numbers can be used when specifying the quantity on ItemTransactionModels.

Type:: bool

inventory_account

Inventory account associated with the ItemModel instance. Enforced if ItemModel instance is_inventory() is True.

Type:: AccountModel

inventory_received

Holds the total quantity of the inventory received for the whole EntityModel instance.

Type:: Decimal

inventory_received_value

Holds the total monetary value of the inventory received for the whole EntityModel instance.

Type:: Decimal

cogs_account

COGS account associated with the ItemModel instance. Enforced if ItemModel instance is_inventory() is True.

Type:: AccountModel

earnings_account

Earnings account associated with the ItemModel instance. Enforced if ItemModel instance is_product() or: is_service() is True.

Type:: AccountModel

expense_account

Expense account associated with the ItemModel instance. Enforced if ItemModel instance is_expense() is True.

Type:: AccountModel

additional_info

Additional user defined information stored as JSON document in the Database.

Type:: dict

entity

The EntityModel associated with the ItemModel instance.

Type:: EntityModel

clean(): Hook for doing any extra model-wide validation after clean() has been called on every field by self.clean_fields. Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

generate_item_number(commit: bool = False) → str: Atomic Transaction. Generates the next Vendor Number available. @param commit: Commit transaction into VendorModel. @return: A String, representing the current InvoiceModel instance Document Number.

save(**kwargs)

Save the current instance. Override this in a subclass if you want to control the saving process.

The ‘force_insert’ and ‘force_update’ parameters can be used to insist that the “save” must be an SQL insert or update (or equivalent for non-SQL backends), respectively. Normally, they should not be set.

class django_ledger.models.items.ItemModelManager(*args, **kwargs)

A custom defined ItemModelManager that implement custom QuerySet methods related to the ItemModel

for_bill(entity_slug, user_model)

Returns a QuerySet of ItemModels that can only be used for BillModels for a specific EntityModel & UserModel. These types of items qualify as expenses or inventory purchases. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered ItemModelQuerySet.

Return type:

for_entity(entity_slug, user_model)

Returns a QuerySet of ItemModel associated with a specific EntityModel & UserModel. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered ItemModelQuerySet.

Return type:

for_entity_active(entity_slug, user_model)

Returns a QuerySet of Active ItemModel associated with a specific EntityModel & UserModel. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered ItemModelQuerySet.

Return type:

for_estimate(entity_slug: str, user_model)

Returns a QuerySet of ItemModels that can only be used for EstimateModels for a specific EntityModel & UserModel. These types of items qualify as products. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered ItemModelQuerySet.

Return type:

for_invoice(entity_slug, user_model)

Returns a QuerySet of ItemModels that can only be used for InvoiceModels for a specific EntityModel & UserModel. These types of items qualify as products or services sold. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered ItemModelQuerySet.

Return type:

for_po(entity_slug, user_model)

Returns a QuerySet of ItemModels that can only be used for PurchaseOrders for a specific EntityModel & UserModel. These types of items qualify as inventory purchases. May pass an instance of EntityModel or a String representing the EntityModel slug.

Parameters:

entity_slug (str or EntityModel) – The entity slug or EntityModel used for filtering the QuerySet.
user_model – The request UserModel to check for privileges.

Returns:

A Filtered ItemModelQuerySet.

Return type: