django-ledgers^v0.1.0

Django app which implements ledgers to store cumulative data.

Description

A Ledger is an abstraction over Django ORM which consists of 2 tables:

movements — stores periodic data about ledger's state change.
totals — stores pre-calculated cumulative result for some period.

Ledger's state is changed via Documents — an "atomic" abstraction over set of simultaneous changes.

Examples

Warehouse remains

Items:

from django.db import models


class Item(models.Model):
    name = models.CharField(max_length=200, unique=True)

can be stored at Warehouse:

class Warehouse(models.Model):
    name = models.CharField()

via Warehouse Balance Ledger:

from ledgers.enum import CumulativeLedgerRecordActionEnum
from ledgers.ledger import CumulativeLedger
from ledgers.ledger.fields import dimensions, resources


class BalanceAtWarehousesLedger(CumulativeLedger):
    warehouse = dimensions.ForeignKey(
        to=Warehouse,
        null=False,
    )
    item = dimensions.ForeignKey(
        to=Item,
        null=False,
    )
    amount = resources.Integer()
    comment = models.CharField(max_length=200, null=False, default='')
    
    @classmethod
    def movements_for_itemmovement(cls, doc):
        # noinspection PyCallingNonCallable
        return (
            cls.mvm_model(
                period=doc.execution_date,
                registrator=doc,
                line_index=0,
                action=CumulativeLedgerRecordActionEnum.OUTCOME,
                warehouse_id=doc.from_warehouse_id,
                item_id=doc.item_id,
                amount=doc.amount,
            ),
            cls.mvm_model(
                period=doc.execution_date,
                registrator=doc,
                line_index=1,
                action=CumulativeLedgerRecordActionEnum.INCOME,
                warehouse_id=doc.to_warehouse_id,
                item_id=doc.item_id,
                amount=doc.amount,
            ),
        )

and changed via Item Movement:

class ItemMovement(Document):
    class DocumentMeta(Document.DocumentMeta):
        related_ledgers = [BalanceAtWarehousesLedger]
        default_prefix = 'MVM'

    from_warehouse = models.ForeignKey(
        Warehouse,
        on_delete=models.CASCADE,
        null=False,
        blank=False,
        related_name='+',
    )
    to_warehouse = models.ForeignKey(
        Warehouse,
        on_delete=models.CASCADE,
        null=False,
        blank=False,
        related_name='+',
    )
    item = models.ForeignKey(
        Item,
        on_delete=models.CASCADE,
        null=False,
        blank=False,
    )
    amount = models.IntegerField(
        null=False,
        blank=False,
    )

Then, on creating an ItemMovement:

from ledgers.enum import DocumentStateEnum

# prepare instances
t_shirt = Item.objects.get_or_create(name='T-shirt')
london_warehouse = Warehouse.objects.get_or_create(name='London')
tokyo_warehouse = Warehouse.objects.get_or_create(name='Tokyo')

# prepare and save document
doc = ItemMovement(
    state=DocumentStateEnum.ACTIVE,
    item=t_shirt,
    from_warehouse=london_warehouse,
    to_warehouse=tokyo_warehouse,
    amount=100,
)
doc.save()

Movements and totals tables will be updated, and actual remains for any period can be fetched:

from example.exampleapp.models import Item, Warehouse, BalanceAtWarehousesLedger
from datetime import timedelta


# prepare instances
t_shirt = Item.objects.get_or_create(name='T-shirt')
london_warehouse = Warehouse.objects.get_or_create(name='London')
tokyo_warehouse = Warehouse.objects.get_or_create(name='Tokyo')

remains_before_document_date = BalanceAtWarehousesLedger.remains_qs(
    period=doc.execution_date - timedelta(days=1),
)
remains_after_document_date = BalanceAtWarehousesLedger.remains_qs()

print(list(remains_before_document_date))
# [
#   {
#       'warehouse_id': 1,
#       'item_id': 1,
#       'amount_remains': 0
#   },
#   {
#       'warehouse_id': 2,
#       'item_id': 1,
#       'amount_remains': 0
#   }
# ]

print(list(remains_after_document_date))
# [
#   {
#       'warehouse_id': 1,
#       'item_id': 1,
#       'amount_remains': -10
#   },
#   {
#       'warehouse_id': 2,
#       'item_id': 1,
#       'amount_remains': 10
#   }
# ]

Features

django-ledgers @ v0.1.0 can:

store push tokens from FCM or HMS
link push tokens with their users and applications
store push notifications
store push notifications extra kwargs (e.g. deeplinks)
compose recipients via UI based on user-specified conditions
watch notifications schedule on calendar
send scheduled push notifications
store applications as swappable model

Usage example

TODO

exampleproj

Example project is a showcase django project. You can reference to it for usage cases, examples, testing. You must never deploy exampleproj in production due to exposed SECRET_KEY.

Getting Started

Dependencies

Python packages

django
django-cte

Installing

Using Python Package Index

make sure to use latest pip:
```
python3 -m pip install --upgrade pip
```
install django-ledgers:
```
python3 -m pip install django-ledgers
```

OR download package from releases

download release asset (.tar.gz or .whl)
make sure to use latest pip:
```
python3 -m pip install --upgrade pip
```

install djangoFCM from file:

python3 -m pip install /path/to/downloaded/asset.tar.gz # or .whl

OR clone from repository

clone project:

git clone \
        --depth=1 \
        --branch=master \
        git@github.com:omelched/django-ledgers.git \
        </path/to/downloads>

move /django-ledgers/ledgers solely to folder containing django apps

mv      </path/to/downloads>/django-ledgers/ledgers \
        </path/to/django/project/apps>

remove leftovers

rm -rf  </path/to/downloads>/django-ledgers

Configuring

Installing application

Add django-ledgers to INSTALLED_APPS in your Django project settings.py.

If you installed package the third way, </path/to/django/project/apps> must be added to PYTHONPATH. If you not sure add code below in your Django project manage.py before calling main():

sys.path.append('</path/to/django/project/apps>')

Subclass ledgers.ledger.cumulative.CumulativeLedger and ledgers.models.documents.document.Document.

Migrations

Execute database migrations:

python example/manage.py migrate

Collect static:

python example/manage.py collectstatic

Authors

@omelched (Denis Omelchenko)

Contributors

Changelist

django-ledgers version history and changelist available at releases page.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

This project is inspired by 1C ORM. More on topic:

https://its.1c.ru/db/pubapplied/content/123/hdoc (writing)
https://its.1c.ru/db/pubapplied/content/130/hdoc (querying)

omelched/django-ledgers

django-ledgersv0.1.0