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