:mod:`rattail.ext.orders` Module
================================

This extension adds a more or less generic customer (special) order system to Rattail.

The API itself is meant to allow for many different workflows, so how you use it really
should be up to you.  Please see http://rattail.edbob.org/moin/Workflows/Orders for
some notes on workflow.

Classes
-------

.. autoclass:: rattail.Order

   .. attribute:: id

      An integer field which may contain a human-friendly ID for the order.

      This is auto-incremented by default.

   .. attribute:: customer

      A reference to a :class:`rattail.Customer` to which the order belongs.

   .. attribute:: products

      A list of :class:`rattail.OrderProduct` instances which belong to the order.

   .. attribute:: created

      Date and time the order was created.

   .. attribute:: creator

      A reference to the :class:`rattail.User` who created the order.

   .. attribute:: status

      An integer field to contain a custom-defined enumeration value.

   .. attribute:: events

      A list of :class:`rattail.OrderEvent` instances for the order.

.. autoclass:: rattail.OrderEvent

   .. attribute:: order

      A reference to the :class:`rattail.Order` to which the event applies.

   .. attribute:: type

      An integer field to contain a custom-defined enumeration value.

   .. attribute:: timestamp

      Date and time when the event occurred.

   .. attribute:: user

      A reference to the :class:`rattail.User` who performed the event.

   .. attribute:: note

      Optional note text for the event.

.. autoclass:: rattail.OrderProduct

   .. attribute:: id

      An integer field which may contain a human-friendly ID for the item.

      This is auto-incremented by default.

   .. attribute:: order

      A reference to the :class:`rattail.Order` to which the item belongs.

   .. attribute:: ordinal

      An integer containing the "line number" within the Order.

   .. attribute:: product

      Reference to the :class:`rattail.Product` being ordered.

   .. attribute:: product_description

      A cached copy of the :attr:`OrderProduct.product`'s description.

   .. attribute:: initial_description

      A large text field to contain a free-form description of the product and
      its attributes, for use when the product cannot be solidly identified
      when the order is created.

   .. attribute:: quantity

      Decimal quantity for the product being ordered.

   .. attribute:: price

      A reference to the :class:`rattail.Price` to be charged for the product.

   .. attribute:: discount_percent

      Percentage discount to be applied to the product at the point of sale.

   .. attribute:: discount_amount

      Dollar amount of discount to be applied to the product at the point of sale.

   .. attribute:: deposit_due

      Dollar amount of the total deposit which is required for the product.

   .. attribute:: deposit_paid

      Dollar amount of any deposit(s) which has been paid.

   .. attribute:: total_due

      Total payment amount which is required for the product.

   .. attribute:: total_paid

      Dollar amount of any payment(s) which has been submitted.

   .. attribute:: status

      An integer field to contain a custom-defined enumeration value.

   .. attribute:: events

      A list of :class:`rattail.OrderProductEvent` instances for the item.

.. autoclass:: rattail.OrderProductEvent

   .. attribute:: order_product

      A reference to the :class:`rattail.OrderProduct` to which the event applies.

   .. attribute:: type

      An integer field to contain a custom-defined enumeration value.

   .. attribute:: timestamp

      Date and time when the event occurred.

   .. attribute:: user

      A reference to the :class:`rattail.User` who performed the event.

   .. attribute:: note

      Optional note text for the event.

Enumeration: Order Status
-------------------------

This enumeration is meant to hold possible values for :attr:`Order.status`.

.. attribute:: ORDER_STATUS
   
   Dictionary containing text mappings for the enumeration.

.. attribute:: OS_INITIATED

   The first status an ``Order`` may have.

Enumeration: Order Product Status
---------------------------------

This enumeration is meant to hold possible values for :attr:`OrderProduct.status`.

.. attribute:: ORDER_PRODUCT_STATUS

   Dictionary containing text mappings for the enumeration.

.. attribute:: OPS_INITIATED

   The first status an ``OrderProduct`` may have.