Django Ledger v0.8.0 Release: Enhanced Entity Management, Dependency Updates, and Improved Usability

As the maintainer of Django Ledger, an open-source Django application designed to simplify financial accounting workflows, I am pleased to announce the release of version 0.8.0. This update introduces significant refactoring for entity handling, modern dependency alignments, and refinements to user experience, positioning the project for greater scalability and maintainability.

This release includes breaking changes, reflected in the version increment to 0.8.0. To support a smooth transition, deprecation warnings and a configurable backward-compatibility option have been implemented.

Refactored Entity Handling: Spotlight on for_entity Methods and Queryset Improvements

At the heart of v0.8.0 is a comprehensive refactor of entity referencing, with a particular emphasis on the for_entity methods in querysets and models. Previously, these methods relied on fragmented parameters like entity_slug and user_model, which could lead to inconsistent filtering and unnecessary complexity in financial queries. To address this, we've unified the approach around the more robust entity_model parameter, which now seamlessly accepts:

• An EntityModel instance for direct object handling.
• A string slug for lightweight string-based lookups.
• A UUID for high-performance identifier-based resolution.

This refactor has been applied across multiple models, querysets, and views, fundamentally improving how entity-specific data is filtered and retrieved. For instance, querysets now leverage entity_model for optimized filtering, enabling more efficient operations in entity-scoped workflows—such as generating reports for a specific business unit or client in a Wagtail-powered financial dashboard.

Key enhancements include:

• Streamlined Queryset Filtering: The for_entity method has been overhauled to support the new entity_model format natively, reducing boilerplate code and enhancing query performance. This includes simplified chaining with new helper methods like .active() and .hidden() for targeted visibility controls.
• Deprecation of Legacy Parameters: The user_model parameter, often a source of confusion in multi-user setups, has been fully deprecated in favor of this streamlined model. Similarly, entity_slug has been phased out across views, models, and forms.
• Robust Deprecation Handling: To minimize disruption, we've introduced console warnings for any legacy usage of user_model or entity_slug. A new deprecated_for_entity_behavior decorator wraps affected methods, allowing optional backward compatibility. Additionally, the deprecated_entity_slug_behavior mechanism ensures graceful fallbacks in querysets and related logic.

For existing projects, the DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR setting in settings.py provides a migration lifeline:

DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR = True

When enabled, it reactivates deprecated behaviors temporarily, giving developers time to update their querysets and views. A dedicated utility module further aids in managing these transitions, ensuring that even complex Wagtail integrations—where entity querysets power dynamic financial pages—can upgrade without halting production.

This refactor not only clarifies the API but also paves the way for future extensions, such as advanced entity hierarchies in accounting models. If you're scripting entity-based queries in Wagtail, expect noticeable gains in readability and speed.

Model Enhancements: Referential Integrity and Field Flexibility

Refinements to core models include:

• ForeignKey fields in BillModel and InvoiceModel (cash_account, prepaid_account, unearned_account) now employ RESTRICT on delete, with support for blank and null values, and unique related_name attributes.
• Address fields (address_1 in CustomerModel, EntityModel, and VendorModel) are nullable, with validation ensuring address_1 is provided when address_2 is used.

Migration 0025 has been restored to apply these changes without data disruption. Templates have been adjusted to conditionally render address fields, and status icons (active/hidden) now feature standardized styling.

Chart of Accounts: Automated Configuration and Validation

The ChartOfAccounts model has been fortified with:

• Advanced annotations (accountmodel_rootgroup__count, accountmodel_rootgroup_roles__distinct_count) for root-group integrity checks.
• A dynamic configured boolean field for configuration status assessment.
• A refactored configure() method supporting hierarchical boilerplate generation.
• An is_configured() method for validation, integrated with post_save signals for automated setup.

These features support lazy hierarchy creation for root and child accounts, reducing setup overhead in scripted environments like Wagtail.

Theme Configuration: Customizable Visual Styling

Template rendering now supports theme selection via the DJANGO_LEDGER_THEME setting (default: lux), with validation for lux and minty options. A new django_ledger_context processor injects variables such as DEBUG, VERSION, and theme data into templates, requiring addition to the TEMPLATES configuration in settings.py.

Settings imports have been standardized to django.conf.global_settings, with cleanup of obsolete configurations.

Financial Statement Templates: Refined Presentation

Usability improvements to financial reports include:

• Table enhancements with classes is-hoverable, is-bordered, and financial-statement, featuring hover effects and currency right-alignment.
• Styled tags and icons for balance types (credit/debit).
• Adjusted heading sizes (e.g., is-size-4) for improved readability.
• Localized date formats, such as "For the month ended December 31, 2024" or "As of September 13, 2025".
• Translation placeholders and enhanced entity card spacing.

Data import forms have also received usability updates for efficient bulk operations.

Removals and Documentation Updates

• Experimental GraphQL support (django_ledger_graphene) has been deprecated and removed to concentrate on core Django Ledger functionality.
• The README has been reformatted for clarity, including a dedicated section on DJANGO_LEDGER_USE_DEPRECATED_BEHAVIOR.

Thank you for your continued support of Django Ledger.