Metadata-Version: 2.4
Name: ocyan.plugin.oscar_invoices
Version: 0.3.1rc1
Summary: MandelBlogStack compatibility distribution for Django Oscar invoices
Home-page: https://git.mandelblog.com/mandel-plugins/ocyan.plugin.oscar_invoices
Author: MandelBlogStack
Author-email: info@mandelblog.com
License: BSD
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: Django<5.3,>=5.2
Requires-Dist: django-oscar<4.2,>=4.1
Requires-Dist: django-phonenumber-field<9,>=8.5
Requires-Dist: phonenumbers
Requires-Dist: Pillow
Provides-Extra: test
Requires-Dist: coverage>=5.4; extra == "test"
Requires-Dist: django-webtest<1.10,>=1.9; extra == "test"
Requires-Dist: pytest-django<5.0; extra == "test"
Requires-Dist: pytest-xdist<4.0.0,>=3.6.1; extra == "test"
Requires-Dist: sorl-thumbnail<13.0.0,>=12.10.0; extra == "test"
Requires-Dist: psycopg2-binary>=2.9.9; extra == "test"
Requires-Dist: vdt.versionplugin.wheel; extra == "test"
Provides-Extra: dev
Requires-Dist: flake8>=4.0.1; extra == "dev"
Requires-Dist: isort>=5.10.1; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

=====================
ocyan.plugin.oscar_invoices
===========================

This is the first-party MandelBlogStack compatibility distribution for the
``oscar_invoices`` Django application. It preserves the upstream public package and
app identity while targeting the supported MandelBlogStack runtime: Python 3.12,
Django 5.2 and Django Oscar 4.1.

Do not install ``django-oscar-invoices`` alongside this distribution; both own the
same Python import package. See ``UPSTREAM.md`` for provenance and attribution.

Quickstart
==========

Installation
------------

.. code-block:: console

    $ pip install ocyan.plugin.oscar_invoices


Setup
-----

1. Add ``oscar_invoices`` to the ``INSTALLED_APPS`` variable of your
   project's ``settings.py``.

2. Sync the database using ``python manage.py migrate``.

3. Create instances of ``LegalEntity`` and ``LegalEntityAddress``.

4. Integrate ``InvoiceCreator`` in your checkout process.


By default, we generate only HTML invoice document and allow user to decide how to
generate PDF documents. You can integrate `python-pdfkit`_, `WeasyPrint`_, `xhtml2pdf`_,
`reportlab`_ or another library of your choice.

.. _`python-pdfkit`: https://github.com/JazzCore/python-pdfkit
.. _`WeasyPrint`: https://github.com/Kozea/WeasyPrint
.. _`xhtml2pdf`: https://github.com/xhtml2pdf/xhtml2pdf
.. _`reportlab`: https://www.reportlab.com/

Since documents contains sensitive data, we store them out of the media folder and
do not provide public access via URL. For this purpose, we use custom storage class
``oscar_invoices.storages.DocumentsStorage``, invoice documents placed into the
nested folder ``settings.OSCAR_INVOICES_UPLOAD_FOLDER`` and available for the admin users via
dashboard order list.


You can find more information in documentation_.

.. _documentation: https://django-oscar-invoices.readthedocs.io


Sandbox
-------

Sandbox environment set up to automatically create invoices on checkout.
But for this, instances of ``LegalEntity`` and ``LegalEntityAddress`` must be created
(from ``admin`` site) before order placement.
