def register_split_transaction(source, splits, description, issuer, date=None, kind=None):
"""
A factory function for registering general (split) transactions between accounts.
When invoked, this function takes care of the following tasks:
* create a new ``Transaction`` model instance from the given input arguments
* for each account involved in the transaction, add an entry
to the corresponding ledger (as a ``LedgerEntry`` instance).
Arguments
=========
``source``
A ``CashFlow`` model instance specifying the source account for the transaction
and the amount of money flowing from/to it
``splits``
An iterable of ``Split`` model instances, representing the flow components
(a.k.a. *splits*) from which the transaction is made. They must satisfy all the compatibility
constraints descending from the reference accounting model (for details,
see ``Transaction`` model's docstring)
``description``
A string describing what the transaction stands for
``issuer``
The economic subject (a ``Subject`` model instance) who issued the transaction
``date``
A reference date for the transaction (as a ``DateTime`` object);
default to the current date & time
``kind``
A type specification for the transaction. It's an (optional) domain-specific string;
if specified, it must be one of the values listed in ``settings.TRANSACTION_TYPES``
Return value
============
If input is valid, return the newly created ``Transaction`` model instance;
otherwise, report to the client code whatever error(s) occurred during the processing,
by raising a ``MalformedTransaction`` exception.
"""
try:
transaction = Transaction()
transaction.source = source
transaction.description = description
transaction.issuer = issuer
transaction.date = date
transaction.kind = kind
transaction.save()
# set transaction splits
transaction.split_set = splits
except ValidationError, e:
err_msg = _(u"Transaction specs are invalid: %(specs)s. The following error(s) occured: %(errors)s")\
% {'specs':transaction_details(transaction), 'errors':str(e.message_dict)}
raise MalformedTransaction(err_msg)
def register_split_transaction(source, splits, description, issuer, date=None, kind=None):
"""
A factory function for registering general (split) transactions between accounts.
When invoked, this function takes care of the following tasks:
* create a new ``Transaction`` model instance from the given input arguments
* for each account involved in the transaction, add an entry
to the corresponding ledger (as a ``LedgerEntry`` instance).
Arguments
=========
``source``
A ``CashFlow`` model instance specifying the source account for the transaction
and the amount of money flowing from/to it
``splits``
An iterable of ``Split`` model instances, representing the flow components
(a.k.a. *splits*) from which the transaction is made. They must satisfy all the compatibility
constraints descending from the reference accounting model (for details,
see ``Transaction`` model's docstring)
``description``
A string describing what the transaction stands for
``issuer``
The economic subject (a ``Subject`` model instance) who issued the transaction
``date``
A reference date for the transaction (as a ``DateTime`` object);
default to the current date & time
``kind``
A type specification for the transaction. It's an (optional) domain-specific string;
if specified, it must be one of the values listed in ``settings.TRANSACTION_TYPES``
Return value
============
If input is valid, return the newly created ``Transaction`` model instance;
otherwise, report to the client code whatever error(s) occurred during the processing,
by raising a ``MalformedTransaction`` exception.
"""
try:
transaction = Transaction()
transaction.source = source
transaction.description = description
transaction.issuer = issuer
transaction.date = date
transaction.kind = kind
transaction.save()
# set transaction splits
transaction.split_set = splits
except ValidationError, e:
err_msg = _(u"Transaction specs are invalid: %(specs)s. The following error(s) occured: %(errors)s")\
% {'specs':transaction_details(transaction), 'errors':str(e.message_dict)}
raise MalformedTransaction(err_msg)
def register_simple_transaction(source_account, target_account, amount, description, issuer, date=None, kind=None):
"""
A factory function for registering simple transactions.
This is just a convenience version of ``register_transaction``,
to be used when dealing with simple transactions.
When invoked, this function takes care of the following tasks:
* create a new ``Transaction`` model instance from the given input arguments
* for each account involved in the transaction (i.e., ``source`` and ``target``),
add an entry to the corresponding ledger (as a ``LedgerEntry`` instance).
For details about simple transactions, see ``Transaction`` model's docstring.
Arguments
=========
``source_account``
the source account for the transaction (a stock-like ``Account`` model instance)
``target_account``
the target account for the transaction (a stock-like ``Account`` model instance)
``amount``
the amount of money flowing between source and target accounts (as a signed decimal);
its sign determines the flows's direction with respect to the source account
(i.e., positive -> outgoing, negative -> incoming)
``description``
A string describing what the transaction stands for
``issuer``
The economic subject (a ``Subject`` model instance) who issued the transaction
``date``
A reference date for the transaction (as a ``DateTime`` object);
default to the current date & time
``kind``
A type specification for the transaction. It's an (optional) domain-specific string;
if specified, it must be one of the values listed in ``settings.TRANSACTION_TYPES``
Return value
============
If input is valid, return the newly created ``Transaction`` model instance;
otherwise, report to the client code whatever error(s) occurred during the processing,
by raising a ``MalformedTransaction`` exception.
"""
try:
transaction = Transaction()
# source flow
source = CashFlow.objects.create(account=source_account, amount=amount)
transaction.source = source
transaction.description = description
transaction.issuer = issuer
transaction.date = date
transaction.kind = kind
transaction.save()
# construct the (single) transaction split from input arguments
# entry- & exit- points are missing, because this is an internal transaction
# target flow
target = CashFlow.objects.create(account=target_account, amount=-amount)
split = Split.objects.create(target=target)
# add this single split to the transaction
transaction.split_set = [split]
except ValidationError, e:
err_msg = _(u"Transaction specs are invalid: %(specs)s. The following error(s) occured: %(errors)s")\
% {'specs':transaction_details(transaction), 'errors':str(e.message_dict)}
raise MalformedTransaction(err_msg)
def register_internal_transaction(source, targets, description, issuer, date=None, kind=None):
"""
A factory function for registering internal transactions.
This is just a convenience version of ``register_split_transaction``,
to be used when dealing with internal transactions.
When invoked, this function takes care of the following tasks:
* create a new ``Transaction`` model instance from the given input arguments
* for each account involved in the transaction (i.e., ``source`` and ``targets``),
add an entry to the corresponding ledger (as a ``LedgerEntry`` instance).
For details about internal transactions, see ``Transaction`` model's docstring.
Arguments
=========
``source``
A ``CashFlow`` model instance specifying the source account for the transaction
and the amount of money flowing from/to it
``targets``
An iterable of ``CashFlow`` model instances, representing the flow components
(a.k.a. splits) from which the transaction is made.
Since we are dealing with an internal transaction, a split is fully defined
by the target account and the amount of money flowing to/from it
(so, a ``CashFlow`` rather than a ``Split`` instance).
``description``
A string describing what the transaction stands for
``issuer``
The economic subject (a ``Subject`` model instance) who issued the transaction
``date``
A reference date for the transaction (as a ``DateTime`` object);
default to the current date & time
``kind``
A type specification for the transaction. It's an (optional) domain-specific string;
if specified, it must be one of the values listed in ``settings.TRANSACTION_TYPES``
Return value
============
If input is valid, return the newly created ``Transaction`` model instance;
otherwise, report to the client code whatever error(s) occurred during the processing,
by raising a ``MalformedTransaction`` exception.
"""
try:
transaction = Transaction()
transaction.source = source
transaction.description = description
transaction.issuer = issuer
transaction.date = date
transaction.kind = kind
transaction.save()
# construct transaction splits from input arguments
splits = []
for target in targets:
# entry- & exit- points are missing, because this is an internal transaction
split = Split.objects.create(target=target)
splits.append(split)
# set transaction splits
transaction.split_set = splits
except ValidationError, e:
err_msg = _(u"Transaction specs are invalid: %(specs)s. The following error(s) occured: %(errors)s")\
% {'specs':transaction_details(transaction), 'errors':str(e.message_dict)}
raise MalformedTransaction(err_msg)
def register_simple_transaction(source_account, target_account, amount, description, issuer, date=None, kind=None):
"""
A factory function for registering simple transactions.
This is just a convenience version of ``register_transaction``,
to be used when dealing with simple transactions.
When invoked, this function takes care of the following tasks:
* create a new ``Transaction`` model instance from the given input arguments
* for each account involved in the transaction (i.e., ``source`` and ``target``),
add an entry to the corresponding ledger (as a ``LedgerEntry`` instance).
For details about simple transactions, see ``Transaction`` model's docstring.
Arguments
=========
``source_account``
the source account for the transaction (a stock-like ``Account`` model instance)
``target_account``
the target account for the transaction (a stock-like ``Account`` model instance)
``amount``
the amount of money flowing between source and target accounts (as a signed decimal);
its sign determines the flows's direction with respect to the source account
(i.e., positive -> outgoing, negative -> incoming)
``description``
A string describing what the transaction stands for
``issuer``
The economic subject (a ``Subject`` model instance) who issued the transaction
``date``
A reference date for the transaction (as a ``DateTime`` object);
default to the current date & time
``kind``
A type specification for the transaction. It's an (optional) domain-specific string;
if specified, it must be one of the values listed in ``settings.TRANSACTION_TYPES``
Return value
============
If input is valid, return the newly created ``Transaction`` model instance;
otherwise, report to the client code whatever error(s) occurred during the processing,
by raising a ``MalformedTransaction`` exception.
"""
try:
transaction = Transaction()
# source flow
source = CashFlow.objects.create(account=source_account, amount=amount)
transaction.source = source
transaction.description = description
transaction.issuer = issuer
transaction.date = date
transaction.kind = kind
transaction.save()
# construct the (single) transaction split from input arguments
# entry- & exit- points are missing, because this is an internal transaction
# target flow
target = CashFlow.objects.create(account=target_account, amount=-amount)
split = Split.objects.create(target=target)
# add this single split to the transaction
transaction.split_set = [split]
except ValidationError, e:
err_msg = _(u"Transaction specs are invalid: %(specs)s. The following error(s) occured: %(errors)s")\
% {'specs':transaction_details(transaction), 'errors':str(e.message_dict)}
raise MalformedTransaction(err_msg)
def register_internal_transaction(source, targets, description, issuer, date=None, kind=None):
"""
A factory function for registering internal transactions.
This is just a convenience version of ``register_split_transaction``,
to be used when dealing with internal transactions.
When invoked, this function takes care of the following tasks:
* create a new ``Transaction`` model instance from the given input arguments
* for each account involved in the transaction (i.e., ``source`` and ``targets``),
add an entry to the corresponding ledger (as a ``LedgerEntry`` instance).
For details about internal transactions, see ``Transaction`` model's docstring.
Arguments
=========
``source``
A ``CashFlow`` model instance specifying the source account for the transaction
and the amount of money flowing from/to it
``targets``
An iterable of ``CashFlow`` model instances, representing the flow components
(a.k.a. splits) from which the transaction is made.
Since we are dealing with an internal transaction, a split is fully defined
by the target account and the amount of money flowing to/from it
(so, a ``CashFlow`` rather than a ``Split`` instance).
``description``
A string describing what the transaction stands for
``issuer``
The economic subject (a ``Subject`` model instance) who issued the transaction
``date``
A reference date for the transaction (as a ``DateTime`` object);
default to the current date & time
``kind``
A type specification for the transaction. It's an (optional) domain-specific string;
if specified, it must be one of the values listed in ``settings.TRANSACTION_TYPES``
Return value
============
If input is valid, return the newly created ``Transaction`` model instance;
otherwise, report to the client code whatever error(s) occurred during the processing,
by raising a ``MalformedTransaction`` exception.
"""
try:
transaction = Transaction()
transaction.source = source
transaction.description = description
transaction.issuer = issuer
transaction.date = date
transaction.kind = kind
transaction.save()
# construct transaction splits from input arguments
splits = []
for target in targets:
# entry- & exit- points are missing, because this is an internal transaction
split = Split.objects.create(target=target)
splits.append(split)
# set transaction splits
transaction.split_set = splits
except ValidationError, e:
err_msg = _(u"Transaction specs are invalid: %(specs)s. The following error(s) occured: %(errors)s")\
% {'specs':transaction_details(transaction), 'errors':str(e.message_dict)}
raise MalformedTransaction(err_msg)
