pay.utils
=========

.. py:module:: pay.utils


Classes
-------

.. autoapisummary::

   pay.utils._PriceBase
   pay.utils.Price
   pay.utils.InvoiceItemMeta
   pay.utils.InvoiceMeta
   pay.utils._InvoiceDiscountMetaBase
   pay.utils.InvoiceDiscountMeta


Functions
---------

.. autoapisummary::

   pay.utils.round_amount
   pay.utils.payments_association_table_for


Module Contents
---------------

.. py:function:: round_amount(amount: decimal.Decimal, base: decimal.Decimal) -> decimal.Decimal

   Rounds the given amount to the nearest multiple of base.


.. py:class:: _PriceBase

   Bases: :py:obj:`NamedTuple`


   .. py:attribute:: amount
      :type:  decimal.Decimal


   .. py:attribute:: currency
      :type:  str | None


   .. py:attribute:: fee
      :type:  decimal.Decimal


   .. py:attribute:: credit_card_payment
      :type:  bool


.. py:class:: Price

   Bases: :py:obj:`_PriceBase`


   A single price.

   The amount includes the fee. To get the net amount use the net_amount
   property.



   .. py:method:: __bool__() -> bool


   .. py:method:: __lt__(other: Price) -> bool

      Return self<value.



   .. py:method:: __add__(other: Price) -> Self

      Return self+value.



   .. py:method:: __sub__(other: Price) -> Self


   .. py:method:: __mul__(other: decimal.Decimal | float | SupportsIndex) -> Self

      Return self*value.



   .. py:attribute:: __rmul__

      Return value*self.



   .. py:method:: __str__() -> str

      Return str(self).



   .. py:method:: __repr__() -> str

      Return repr(self).



   .. py:method:: zero() -> Self
      :classmethod:



   .. py:method:: as_dict() -> onegov.pay.types.PriceDict


   .. py:property:: net_amount
      :type: decimal.Decimal



   .. py:method:: apply_discount(discount: decimal.Decimal) -> Self


.. py:class:: InvoiceItemMeta

   .. py:attribute:: text
      :type:  str


   .. py:attribute:: group
      :type:  str


   .. py:attribute:: unit
      :type:  decimal.Decimal


   .. py:attribute:: quantity
      :type:  decimal.Decimal


   .. py:attribute:: vat_rate
      :type:  decimal.Decimal | None
      :value: None



   .. py:attribute:: family
      :type:  str | None
      :value: None



   .. py:attribute:: cost_object
      :type:  str | None
      :value: None



   .. py:attribute:: extra
      :type:  dict[str, Any] | None
      :value: None



   .. py:property:: amount
      :type: decimal.Decimal



   .. py:property:: vat
      :type: decimal.Decimal



   .. py:property:: net_amount
      :type: decimal.Decimal



   .. py:method:: total(items: collections.abc.Iterable[InvoiceItemMeta]) -> decimal.Decimal
      :staticmethod:



   .. py:method:: total_vat(items: collections.abc.Iterable[InvoiceItemMeta]) -> decimal.Decimal
      :staticmethod:



   .. py:method:: add_to_invoice(invoice: onegov.pay.models.Invoice) -> onegov.pay.models.InvoiceItem


   .. py:method:: refresh_item(item: onegov.pay.models.InvoiceItem) -> None


.. py:class:: InvoiceMeta

   The metadata of a full invoice.

   Contains the freshly generated invoice items, an optional rounding
   base and an optional reference to an already existing invoice, which
   may contain manually added items that need to be considered for the
   rounding.

   Iterating over this yields the generated items plus, if necessary,
   an extra item that rounds the invoice total to a multiple of the
   rounding base.



   .. py:attribute:: items
      :type:  list[InvoiceItemMeta]


   .. py:attribute:: rounding_base
      :type:  decimal.Decimal | None
      :value: None



   .. py:attribute:: invoice
      :type:  onegov.pay.models.Invoice | None
      :value: None



   .. py:attribute:: rounding_text
      :type:  str
      :value: 'Rounding difference'



   .. py:property:: manual_total
      :type: decimal.Decimal



   .. py:property:: manual_vat
      :type: decimal.Decimal



   .. py:property:: rounding_item
      :type: InvoiceItemMeta | None



   .. py:method:: __iter__() -> collections.abc.Iterator[InvoiceItemMeta]


   .. py:method:: __bool__() -> bool


   .. py:property:: total
      :type: decimal.Decimal


      The total amount including the rounding item as well as any
      manual items on an existing invoice, mirroring
      :attr:`Invoice.total_amount`.



   .. py:property:: total_excluding_manual_entries
      :type: decimal.Decimal


      The total of the generated items and the rounding item,
      excluding manual items on an existing invoice, mirroring
      :attr:`Invoice.total_excluding_manual_entries`.



   .. py:property:: total_vat
      :type: decimal.Decimal


      The total VAT including any manual items on an existing
      invoice, mirroring :attr:`Invoice.total_vat`.



   .. py:method:: total_changed() -> bool

      Whether the total differs from the existing invoice's total,
      taking rounding into account. Manual items are included on both
      sides, since they are preserved on refresh.



.. py:class:: _InvoiceDiscountMetaBase

   Bases: :py:obj:`NamedTuple`


   .. py:attribute:: text
      :type:  str


   .. py:attribute:: group
      :type:  str


   .. py:attribute:: discount
      :type:  decimal.Decimal


   .. py:attribute:: vat_rate
      :type:  decimal.Decimal | None
      :value: None



   .. py:attribute:: family
      :type:  str | None
      :value: None



   .. py:attribute:: cost_object
      :type:  str | None
      :value: None



   .. py:attribute:: extra
      :type:  dict[str, Any] | None
      :value: None



.. py:class:: InvoiceDiscountMeta

   Bases: :py:obj:`_InvoiceDiscountMetaBase`


   Built-in immutable sequence.

   If no argument is given, the constructor returns an empty tuple.
   If iterable is specified the tuple is initialized from iterable's items.

   If the argument is a tuple, the return value is the same object.


   .. py:method:: apply_discount(total: decimal.Decimal, remainder: decimal.Decimal) -> InvoiceItemMeta


.. py:function:: payments_association_table_for(cls: type[onegov.core.orm.Base]) -> sqlalchemy.Table