django-reports-admin 1.1.0
A Django Admin add-on which adds functionality to export data in customized forms of output.
License: MIT
Keywords: django reports admin

django-reports-admin
====================

A Django Admin add-on which adds functionality to export data in
customized forms of output.

Requirements
------------

Django Reports Admin requires ``Django 1.10`` or later, and is written
for ``Python 3.5`` or later.

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

**NOTE:** Although enabled by default, you’ll want to ensure that
``django.contrib.contenttypes`` is within ``INSTALLED_APPS``.

.. code:: sh

   pip install django-reports-admin

Then, amend your Django ``settings.INSTALLED_APPS``:

.. code:: python

   INSTALLED_APPS = (
       ...
       'reports',
       ...
   )

Usage
-----

Creating reports requires subclassing the ``ModelReport`` class and
identifying a report. This can be done with a few lines of code if you
simply want to extract the admin list view for verbatim. For example:

.. code:: python

   # This file can be named anything, but it lives well within the admin.py or
   # models.py as it'll ensure your register() command is run.
   # yourapp/reports.py -- This file can be named anything

   from reports.base import ModelReport

   class MyReport(ModelReport)
       name = "Report - My Report"

Then, register the ``ModelReport`` against a model:

.. code:: python

   # yourapp/admin.py

   from .reports import MyReport
   from .models import MyModel

   reports.register(MyModel, MyReport)

Upon registration, you’ll see a new action with the Django Admin for
that Model, with whatever name you’ve provided in the ``name``
attribute.

For advanced report modification, subclass the following functions
within your ``ModelReport`` class:

``get_field_lookups`` returns a list of column name-value/callback
tuples. This function is a great way to modify the columns of the
report, and the exact output of each field. It is useful if you wish to
create a calculated field, or format a date field.

``get_row_data`` returns a dictionary of the data to be entered for each
row. Generally you should not need to modify this as
``get_field_lookups`` will be sufficient.

``generate_output`` can be modified to adjust the type of output. By
default, a CSV file is generated.

Usage In Shell And Tests
------------------------

It may be useful for you to test a report via code, either as a test or
a quick shell script. This is done without much stress:

.. code:: python

   # Assuming a defined ModelReport
   from reports.base import ModelReport
   from .models import MyModel

   class MyReport(ModelReport):
       queryset = MyModel.objects.all()

   # Instantiate the report, and run it through various means

   report = MyReport()

   # Create a SavedReport instance
   report.run_report()

   # Raw output of the report (as CSV, by default)
   report.generate_output()

   # Output list of OrderedDicts
   report.collect_data()

Testing
-------

Tests are run using ``pytest``, and the test suite can be executed using
the MakeFile

.. code:: sh

   make test


Changelog
=========

1.1.0 (2021-02-06)
------------------

* 58bece6_ - Migration for change to ``SavedReport.run_by``
* fae699c_ - Full code base format + commit of change to ``SavedReport.run_by``.
  Modified to add the ``on_delete=models.SET_NULL``

.. _58bece6: https://github.com/gadventures/django-reports-admin/commit/58bece6
.. _fae699c: https://github.com/gadventures/django-reports-admin/commit/fae699c

1.0.4 (2017-02-28)
------------------

* a0dc5a0_ - Return ``None`` on error when calling ``ModelReport``

.. _a0dc5a0: https://github.com/gadventures/django-reports-admin/commit/a0dc5a0

1.0.3 (2017-02-27)
------------------

* 21ca6a5_ - Refactor calling to report runner
* fba6bf1_ - Allow queryset to be passed within __init__ method
* 5f0ef05_ - Add simple test case for ModelReport, refine misc.
* 3d7d587_ - Document shell usage in README, add more type hints
* 5268739_ - Adjust signature of run_report, easing usage in shell

.. _21ca6a5: https://github.com/gadventures/django-reports-admin/commit/21ca6a5
.. _fba6bf1: https://github.com/gadventures/django-reports-admin/commit/fba6bf1
.. _5f0ef05: https://github.com/gadventures/django-reports-admin/commit/5f0ef05
.. _3d7d587: https://github.com/gadventures/django-reports-admin/commit/3d7d587
.. _5268739: https://github.com/gadventures/django-reports-admin/commit/5268739

1.0.2 (2017-02-10)
------------------

* fa46174_ Adjust user messaging in admin.
* Update README

.. _fa46174: https://github.com/gadventures/django-reports-admin/commit/fa46174

1.0.1 (2017-02-10)
------------------

* First pypi release

1.0.0 (2017-02-09)
------------------

* Initial commit