pybill.lib.entities package

pybill.lib.entities package defines the PyBill entities used all over PyBill.

These entities represent the bills, the claim forms, the debits, the downpayments, the pro-formas and all their inner objects.

addresses module

pybill.lib.entities.addresses module contains the definition of the entities related to the address description.

These entities contain data information related to person or company addresses, and are used by other classes.

class pybill.lib.entities.addresses.Address

Abstract class containing common parts for PersonAddress and OrganisationAddress classes.

streets

Attribute containing the several street lines of the address (because the street definition can be complex and need several lines). Can be empty.

type: list of unicode

post_box

Attribute defining the post box described in the address. Can be empty.

type: unicode

post_code

Attribute defining the post code of the address. Can be empty but is often filled.

type: unicode

city

Attribute defining the city described in the address. Can be empty but is often filled.

type: unicode

state

Attribute containing the state described in the address. In some countries, the addresses don’t contain a specification of state. Can be empty.

type: unicode

country

Attribute defining the country of the address. Is often not filled when the sender and the receiver are in the same country. Can be empty.

type: unicode

phone

Attribute containing the phone number. Only one phone number is allowed. Can be empty.

type: unicode

fax

Attribute containing the fax number. Only one fax number is allowed. Can be empty.

type: unicode

web

Attribute containing the web site address. Only one web site address is allowed. Can be empty.

type: unicode

email

Attribute containing the email address. Only one email address is allowed. Can be empty.

type: unicode

__init__()

Initializes an object.

This object is empty and will be filled later by the XML readers.

get_postal_address_lines()

Gives the list of the various lines of the postal address.

Some pieces of information are displayed on the same line (e.g. post code and city). Some pieces of information (e.g. phone, email, etc.) are not in the list because they don’t concern the postal address. Doesn’t return empty lines.

Returns:The list of the various lines of the postal address. Each line is an Unicode string.
Return type:list of unicode
class pybill.lib.entities.addresses.PersonAddress

Bases: pybill.lib.entities.addresses.Address

Entity class describing the address of a person (used for sender and receiver of the accounting documents).

This class specializes the base class Address and contains only the attributes and methods to deal with the person name (other fields of the address are managed by the base class).

honorific

Attribute containing the honorific used to designate the person (e.g. u”Mr”, u”Ms”, u”Dr”). Can be empty.

type: unicode

firstname

Attribute containing the first name of the person. Can be empty.

type: unicode

other_name

Attribute defining the other name. Other name contains other pieces of data concerning the name that are not a honorific, a first name, a surname or a lineage. These pieces of data are often written between the first name and the name. Can be empty. Sometimes other_name contains all the name and the other fields are empty (data is not splitted accross all the fields).

type: unicode

surname

Attribute defining the surname of the person. Can be empty.

type: unicode

lineage

Attribute defining the lineage of the person (postfixes the name). E.g. u”Sr”, u”Jr”, u”3rd”. Can be empty.

type: unicode

organisation

Attribute containing the organisation (company, society, etc.) where the person works. This organisation is described with an OrganisationAddress object.

type: OrganisationAddress

__init__()

Initializes an empty object.

This method calls the __init__ method of the base class (Address).

get_person_name()

Returns the person name in one string (single line).

This string is composed with the various fields concerning the name: honorific, firstname, other_name, surname, lineage.

Returns:Single line containing the name of the person.
Return type:unicode
class pybill.lib.entities.addresses.OrganisationAddress

Bases: pybill.lib.entities.addresses.Address

Entity class describing the address of an organisation (used in PersonAdress to contain data about the company of the sender/receiver).

This class specializes the base class Address and contains only the attributes and methods to deal with the organisation name and the person role in this organisation (other fields of the address are managed by the base class).

name

Attribute defining the name of the organisation. Can be empty.

type: unicode

divisions

Attribute containing the list of the various divisions that the person working for this organisation is affiliated to. This attribute is used when the organisation address is embedded in a person address. Can be empty.

type: list of unicode

job_titles

Attribute containing a list of the various job titles that the person working for this organisation has got. This attribute is used when the organisation address is embedded in a person address. Can be empty.

type: list of unicode

__init__()

Initializes an empty object.

This method calls the __init__ method of the base class (Address).

accounting_docs sub-package

pybill.lib.entities.accounting_docs is a sub-package that defines the entities modelizing the accounting documents.

These entities represent bills, claim forms, debits, downpayments, pro-formas, and some inner business objects.

The sub-package is divided in several modules, each defining some of the entity classes.

utils module

pybill.lib.entities.accounting_docs.utils module defines some elementary entities used by the entity classes.

class pybill.lib.entities.accounting_docs.utils.AccItem

Entity class representing an item that appears on the accounting document.

quantity

Attribute defining the quantity of the item. Is not necessarily an integer, can be a real.

type: float

quantity_digits

Attribute defining the number of digits to be written, for the quantity, on the documents where the item is displayed. This number of digits is also used to round the quantity before doing any of the item computations (VAT, price, etc.) By default, the number of digits is 0.

type: int

title:

Attribute containing the description of the item

type: unicode

details

Attribute defining a list of additional descriptions of the item.

type: list of unicode

unit_price

Attribute defining the unit price of the item. Actually, this is a tax free price.

type: float

vat_rate

Attribute defining the VAT rate that is applied to this item. This rate is None when no VAT is applicable to the item. Default value is None. The rate is expressed in percents (e.g. 19.6 for 19.6%).

type: float

holdback_rate

Attribute defining the holdback rate applied to this item. Hence, sometimes, an holdback is retained from the price of the item (and will be billed a few months later after the item has been fully tested). Can be None if no holdback is applied to this item. Default value is None. The rate is expressed in percents (e.g. 5.0 for 5.0%).

type: float

holdback_on_vat

Attribute defining a flag set to True if the holdback is also applied on VAT (thus the holback will be computed and substracted from the tax free price and from the VAT amount). When set to False, the holdback is only applied on the tax free price (therefore, we substract the holdback from the tax free price but we keep the integrality of the VAT amount).

For example: if the tax free price is 100.0, the VAT rate is 20.0 and the holdback rate is 5.0. If the holdback is on VAT, we will pay: 100.0*(1.0-0.05) + 20.0*(1.0-0.05) = 114.0. If the holdback is not on VAT, we will pay: 100.0*(1.0-0.05) +20.0 = 115.0.

By default, the holdback is not applied on VAT (flag set to False).

type: bool

__init__()

Initializes an empty object.

get_holdback_amount()

Computes the holdback amount for this item (price * holdback_rate).

When no holdback rate is defined for the item, returns 0.0.

Returns:The holdback amount of the item. 0.0 if no holdback rate is defined for the item.
Return type:float
get_holdback_vat_amount()

Computes the holdback amount on the VAT amount for this item (vat_amount * holdback_rate).

When no holdback rate is defined for the item, returns 0.0. When no VAT rate is defined for the item, returns 0.0.

Returns:The holdback amount on the VAT amount of the item. 0.0 if no holdback rate or no VAT rate is defined for the item.
Return type:float
get_including_taxes_price()

Computes the including taxes price for this item (price + vat_amount).

When no VAT is defined for the item, returns the tax free price ( price).

Returns:The including taxes price of the item or the price of the item if no VAT rate is defined for the item.
Return type:float
get_price()

Computes the price of this item (quantity * unit_price).

This price is actually a tax free price.

Returns:The price of the item.
Return type:float
get_vat_amount()

Computes the Value Added Tax (VAT) amount for this item (price * vat_rate).

When no VAT is defined for the item, returns 0.0.

Returns:The VAT amount of the item. 0.0 if no VAT rate is defined for the item.
Return type:float
class pybill.lib.entities.accounting_docs.utils.PreviousAccountingDoc

Entity class representing an accounting document that was previously sent and that is used in the current bill.

This accounting document can be a downpayment that has previously been charged (Downpayment previously sent) or a debit that has previously been issued (Debit previously sent). The amount of this previous accounting document will modify the total to be paid of the current bill.

The real type represented by a previous accounting document depends on the attribute where the object will be added in the current bill (charged_downpayment or issued_debit).

total

Attribute containing the total of the previous accounting document.

type: float

vat_amount

Attribute containing the VAT amount of the previous accounting document. This VAT amount is a part of the total previously defined.

type: float

accdoc_id

Attribute defining the identifier of the previous accounting document. This identifier is not the document reference but the legal identifier of the document (cf. id)

type: unicode

accdoc_date

Attribute defining the date when the previous accounting document was published.

type: unicode

__init__()

Initializes an empty object.

abstract module

pybill.lib.entities.accounting_docs.abstract module is a private module containing the abstract class that all the high-level entity classes inherit from.

class pybill.lib.entities.accounting_docs.abstract.GenericAccountingDoc

Abstract class containing common parts for Bill, Downpayment, ClaimForm, ProForma and Debit.

id

Attribute defiing the iIdentifier of the accounting document. This attribute is legally mandatory on some documents (e.g. bills that must have a unique identifier). On some other documents (e.g. pro-forma, it doesn’t make sense). Thus, can be empty for some documents.

type: unicode

origin_format

Attribute containing the name of the format from which this entity was created. This attribute is set by the XML reader when the entity is created from a file. Can be u"PBD-1.0" or u"PBD-0.X". By default, it is set to the latest format (i.e. "PBD-1.0").

type: unicode

doc_ref

Attribute defining the reference of the document. It is different from the identifier because the document reference is actually used for classifying documents in the organisation whereas the identifier is for legal reference. Can be empty.

type: unicode

date

Attribute defining the date when the document was published; this is a string representation of the date. The date_num attribute contains a date object. There is no correlation between these two attributes but they often refer to the same date. Can be empty.

type: unicode

date_num

Attribute defining the date when the document was published; This is a date object. The date attribute contains a string representation of the date. There is no correlation between these two attributes but they often refer to the same date. Can be None.

type: datetime.date

place

Attribute defining the place where the document was written. Can be empty.

type: unicode

other_infos

Attribute defining a dictionary whose keys are the keywords of additional pieces of metadata and whose values are the values associated to these keywords for the document. For example: u”Supplier” and the supplier reference.

type: dictionary of unicode indexed by unicode keys

sender

Attribute containing the identification and various information about the sender of the document. These pieces of information complement the address of the organisation that emits the document (that is read from the configuration file). They actually consist in the sender name, its job titles, its phone and email.

type: PersonAddress

receiver

Attribute containing the name and address of the receiver of the document. The name of the person is used to display the person who should process the document. The organisation associated to this person is used to know which organisation will receive (and pay) the accounting document (e.g. bill).

type: PersonAddress

acc_items

Attribute containing the list of the items that appear on the accounting document (e.g. items sold that appear on a bill).

type: list of AccItem

remarks

Attribute containing the optional remarks. Each remark is a text paragraph that is displayed at the beginning of the accounting document.

type: list of unicode

cfg_data

Attribute containing the configuration data that must be used to render the accounting document. This configuration object is attached to the acccounting document by the XML reader.

type: ConfigData

account_numbers

Attribute containing the numbers of the accounting accounts that should be impacted by this accounting document. The numbers are stored in a dictionary whose keys are the CLIENT, HOLDBACK_CLIENT, PRODUCT and VAT constants.

type: dictionary of unicode indexed by unicode keys

__init__()

Initializes common parts of the object.

This method raises a NotImplementedError exception if you try to instantiate an object of this class (that is abstract)

get_all_vat_rates()

Returns a set of the different VAT rates applied to the accounting items.

Of course, each VAT rate appears only one time in the set. The set can be empty if no VAT is applied to the items.

Returns:Set containing the different VAT rates that are applied to the accounting items of the document
Return type:set of float
get_holdback_amount()

Computes the sum of the holdbacks of all the accounting items.

Returns 0.0 if no item has a holdback. Please note that these holdbacks are on tax free prices, see method get_holdback_vat_amount method for holdbacks on VAT amount.

Returns:Sum of the holdbacks for all the items in the accounting document.
Return type:float
get_holdback_vat_amount()

Computes the sum of the holdbacks on VAT for all the accounting items.

Returns 0.0 if no item has a holdback or no item has a VAT rate. Please note that these holdbacks are on VAT amounts, see method get_holdback_amount method for holdbacks on tax free prices.

Returns:Sum of the holdbacks on VAT amounts for all the items in the accounting document.
Return type:float
get_including_taxes_total()

Computes the sum of the including taxes prices for all the items in the accounting document.

If the document contains only items with no VAT rate defined, this total is identical to the total returned by get_price_total method.

Returns:Sum of the including taxes prices of all the items.
Return type:float
get_price_total()

Computes the sum of the prices (actually tax free price) for all the items in the accounting document.

Returns:Sum of the price of all the items.
Return type:float
get_to_be_paid()

Computes the total that must be paid.

This method can be redefined in the child classes.

Actually it is:

total without holdbacks to be paid + total of holdbacks to be paid
Returns:The total that must be paid. The computation of this total depends on the accounting document type.
Return type:float
get_to_be_paid_holdback()

Computes the total of holdbacks that must be paid.

This abstract method will be defined in the child classes.

Returns:The total of holdbacks that must be paid. The computation of this total depends on the accounting document type.
Return type:float
get_to_be_paid_holdback_free()

Computes the total without holdbacks that must be paid.

This abstract method will be defined in the child classes.

Returns:The total without holdbacks that must be paid. The computation of this total depends on the accounting document type.
Return type:float
get_to_be_paid_vat()

Computes the total of VAT amounts that must be paid.

This abstract method will be defined in the child classes.

Returns:The total of VAT amounts that must be paid. The computation of this total depends on the accounting document type.
Return type:float
get_vat_amount_for_rate(vat_rate)

Computes the sum of the VAT amounts of all the accounting items that use the given VAT rate.

Returns 0.0 if no item matches the given VAT rate.

Parameters:vat_rate (float) – VAT rate. Only the items that use this VAT rate will be used to compute the VAT amount.
Returns:VAT amount of all the items that use the specified VAT rate.
Return type:float
has_holdbacks()

This methods tests if the accounting document contains items with a holdback rate.

Returns:True if the accounting document contains at least one item with a holdback rate.
Return type:bool
has_vat_holdbacks()

This methods tests if the accounting document contains items with a holdback rate applied on VAT.

Returns:True if the accounting document contains at least one item with a holdback rate that is applied on VAT amount and this item has a VAT rate.
Return type:bool
has_vat_rates()

This methods tests if the accounting document contains items with a VAT rate.

Returns:True if the accounting document contains at least one item with a VAT rate.
Return type:bool

bill module

pybill.lib.entities.accounting_docs.bill module contains the definition of the entity representing a bill.

class pybill.lib.entities.accounting_docs.bill.Bill(bill_id)

Bases: pybill.lib.entities.accounting_docs.abstract.GenericAccountingDoc

Entity class representing a bill.

charged_downpayments

Attribute containing the list of the downpayments already charged in previous bills. The totals of these downpayments will be discarded from the total to be paid.

type: list of PreviousAccountingDoc

issued_debits

Attribute containing the list of the debits previously issued. The totals of these debits will be discarded from the total to be paid.

type: list of PreviousAccountingDoc

payment_terms

Attribute defining the description of the payment terms. This description will be displayed after the bank data that is read from the configuration file.

type: unicode

. automethod:: __init__

get_downpayments_and_debits()

Computes the total of the already charged downpayments and the already issued debits.

This total will be substracted at the end of the bill in order to compute the total to be paid.

Returns:The total of downpayments and debits.
Return type:float
get_to_be_paid_holdback()

Computes the total of holdbacks that must be paid.

This total depends, of course, on the including taxes total but also on the holdbacks, the downpayments and the debits.

Returns:The total of holdbacks of the bill that must be paid.
Return type:float
get_to_be_paid_holdback_free()

Computes the total without holdback that must be paid.

This total depends, of course, on the including taxes total but also on the holdbacks, the downpayments and the debits.

Returns:The total without holdback of the bill that must be paid.
Return type:float
get_to_be_paid_vat()

Computes the total of VAT amounts that must be paid.

This amount depends on the VAT amounts but also on the charged downpayments and the issued debits.

Returns:The total of VAT amounts that must be paid.
Return type:float

claimform module

pybill.lib.entities.accounting_docs.claimform module defines the entity representing a claim-form.

class pybill.lib.entities.accounting_docs.claimform.ClaimForm(claim_id)

Bases: pybill.lib.entities.accounting_docs.abstract.GenericAccountingDoc

Entity class representing a claim form.

payment_terms

Attrribute defining the description of the payment terms. This description will be displayed after the bank data that is read from the configuration file.

type: unicode

__init__(claim_id)

Initializes an empty object.

Parameters:claim_id (unicode) – Identifier of this accounting document.
get_to_be_paid_holdback()

Computes the total of holdbacks that must be paid.

This total depends, of course, on the including taxes total but also on the holdbacks.

Returns:The total of holdbacks of the claim form that must be paid.
Return type:float
get_to_be_paid_holdback_free()

Computes the total without holdback that must be paid.

This total depends, of course, on the including taxes total but also on the holdbacks.

Returns:The total without holdback of the claim form that must be paid.
Return type:float
get_to_be_paid_vat()

Computes the total of VAT amounts that must be paid.

This amount depends on the VAT amounts.

Returns:The total of VAT amounts that must be paid.
Return type:float

debit module

pybill.lib.entities.accounting_docs.debit module defines the entity representing a debit.

class pybill.lib.entities.accounting_docs.debit.Debit(debit_id)

Bases: pybill.lib.entities.accounting_docs.abstract.GenericAccountingDoc

Entity class representing a debit.

Please note that, for this class, the to_be_paid_* methods give the amounts that must be paid back to the client.

__init__(debit_id)

Initializes an empty object.

Parameters:debit_id (unicode) – Identifier of this accounting document.
get_to_be_paid_holdback()

Computes the total of holdbacks that must be paid back to the client.

This total depends, of course, on the including taxes total but also on the holdbacks.

Returns:The total of holdbacks of the debit that must be paid back to the client.
Return type:float
get_to_be_paid_holdback_free()

Computes the total without holdback that must be paid back to the client.

This total depends, of course, on the including taxes total but also on the holdbacks.

Returns:The total without holdback of the debit that must be paid back to the client.
Return type:float
get_to_be_paid_vat()

Computes the total of VAT amounts that must be paid back to the client.

This amount depends on the VAT amounts.

Returns:The total of VAT amounts that must be paid back to the client.
Return type:float

downpayment module

pybill.lib.entities.accounting_docs.downpayment module defines the entity representing a downpayment.

class pybill.lib.entities.accounting_docs.downpayment.Downpayment(downpay_id)

Bases: pybill.lib.entities.accounting_docs.abstract.GenericAccountingDoc

Entity class representing a downpayment

percent

Attribute defining the percent of the total that must be paid as a downpayment. Hence, the downpayment represents a percent of the actual bill. By default, the percent is 30.0.

type: float

payment_terms

Attribute defiing the description of the payment terms. This description will be displayed after the bank data that is read from the configuration file.

type: unicode

__init__(downpay_id)

Initializes an empty object.

Parameters:downpay_id (unicode) – Identifier of this accounting document.
get_downpayment()

Computes the downpayment.

The downpayment is the including taxes total multiplied by the downpayment percent.

Returns:The amount of the downpayment.
Return type:float
get_to_be_paid_holdback()

Computes the total of holdbacks that must be paid.

This total depends, of course, on the downpayment but also on the holdbacks.

Returns:The total of holdbacks of the downpayment that must be paid.
Return type:float
get_to_be_paid_holdback_free()

Computes the total without holdback that must be paid.

This total depends, of course, on the downpayment but also on the holdbacks.

Returns:The total without holdback of the downpayment that must be paid.
Return type:float
get_to_be_paid_vat()

Computes the total of VAT amounts that must be paid. This amount depends on the VAT amounts but also, of course, on the downpayment percent.

Returns:The total of VAT amounts that must be paid.
Return type:float

proforma module

pybill.lib.entities.accounting_docs.proforma module defines the entity representing a pro-forma.

class pybill.lib.entities.accounting_docs.proforma.ProForma(prof_id=None)

Bases: pybill.lib.entities.accounting_docs.abstract.GenericAccountingDoc

Entity class representing a pro-forma bill used as a purchase order.

validity_date

Attribute defining the date that the purchase order is valid until; this is a string representation of the date.

type: unicode

__init__(prof_id=None)

Initializes an empty object.

Please note that the objects of this class don’t need an identifier. The identifier is kept in the arguments to have the same interface as the others accounting entities.

Parameters:prof_id (unicode) – Just kept to have the same interface as the other accounting entities. This identifier is not used as ProForma objects don’t have identifier.
get_to_be_paid_holdback()

In a pro-forma, nothing is to be paid (it’s not really a bill).

This method always returns 0.0.

Returns:0.0 as nothing is to be paid.
Return type:float
get_to_be_paid_holdback_free()

In a pro-forma, nothing is to be paid (it’s not really a bill).

This method always returns 0.0.

Returns:0.0 as nothing is to be paid.
Return type:float
get_to_be_paid_vat()

In a pro-forma, nothing is to be paid (it’s not really a bill).

This method always returns 0.0.

Returns:0.0 as nothing is to be paid.
Return type:float