Metadata-Version: 2.0
Name: money-to-prisoners-common
Version: 7.6.1
Summary: Django app with common code and assets for Money to Prisoners serivces
Home-page: https://github.com/ministryofjustice/money-to-prisoners-common
Author: Ministry of Justice Digital Services
License: MIT
Platform: UNKNOWN
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Provides-Extra: testing
Provides-Extra: monitoring
Requires-Dist: Django (>=1.11,<2.1)
Requires-Dist: django-form-error-reporting (>=0.7)
Requires-Dist: django-widget-tweaks (<1.5,>=1.4)
Requires-Dist: django-zendesk-tickets (>=0.12)
Requires-Dist: pytz (>=2018.3)
Requires-Dist: requests (>=2.18)
Requires-Dist: requests-oauthlib (<9,>=0.8)
Requires-Dist: slumber (<0.8,>=0.7)
Requires-Dist: selenium (<4,>=3.11)
Requires-Dist: transifex-client (>=0.13,<0.14)
Requires-Dist: govuk-bank-holidays (>=0.3)
Requires-Dist: cryptography (>=2.1,<2.2)
Requires-Dist: PyJWT (>=1.5,<1.6)
Requires-Dist: boto3 (<2,>=1.5)
Provides-Extra: monitoring
Requires-Dist: raven (<7,>=6.6); extra == 'monitoring'
Provides-Extra: testing
Requires-Dist: flake8 (<4,>=3.5); extra == 'testing'
Requires-Dist: pep8-naming (>=0.5,<1); extra == 'testing'
Requires-Dist: responses (>=0.8,<1); extra == 'testing'

Money to Prisoners
==================

A Django app containing utilities and assets common to all Money to Prisoners services/applications.

Features
--------

* Reusable templates for form fields and errors
* Base sass and static assets
* Base templates
* Authentication utilities and views for connecting to the MTP api
* User account management forms and views
* REST utilities for retrieving information from `money-to-prisoners-api`_
* Integration and accessibility testing with selenium
* Python code style testing
* Log formatting for shipping to ELK

Usage
-----

Add ``money-to-prisoners-common==<version>`` to the Money to Prisoners application’s requirements.txt.
There are two variations as setuptools *extras*:

* Use ``money-to-prisoners-common[testing]==<version>`` for environments requiring testing
* Use ``money-to-prisoners-common[monitoring]==<version>`` for the deployed version

Add url patterns:

.. code-block:: python

    from django.conf.urls import url

    from mtp_common.auth import views

    urlpatterns = [
        url(r'^login/$', views.login, {
            'template_name': 'login.html',
            }, name='login'),
        url(
            r'^logout/$', views.logout, {
                'template_name': 'login.html',
                'next_page': reverse_lazy('login'),
            }, name='logout'
        ),
    ]

Configure Django settings:

.. code-block:: python

    MIDDLEWARE = (
        ...
        # instead of django.middleware.csrf.CsrfViewMiddleware
        'mtp_common.auth.csrf.CsrfViewMiddleware',
        ...
        # instead of django.contrib.auth.middleware.AuthenticationMiddleware
        'mtp_common.auth.middleware.AuthenticationMiddleware',
        ...
    )

    AUTHENTICATION_BACKENDS = (
        'mtp_common.auth.backends.MojBackend',
    )

    CSRF_FAILURE_VIEW = 'mtp_common.auth.csrf.csrf_failure'

If you wish for additional interface methods, you can extend ``mtp_common.auth.models.MojUser``,
and specify your subclass as ``MOJ_USER_MODEL``. An example would be adding a property to
access a key in the ``user_data`` dict.

.. code-block:: python

    MOJ_USER_MODEL = 'myapp.models.MyCustomUser'

Specify the parameters of the API authentication. ``API_CLIENT_ID`` and ``API_CLIENT_SECRET``
should be unique to your application.

.. code-block:: python

    API_CLIENT_ID = 'xxx'
    API_CLIENT_SECRET = os.environ.get('API_CLIENT_SECRET', 'xxx')
    API_URL = os.environ.get('API_URL', 'http://localhost:8000')

    OAUTHLIB_INSECURE_TRANSPORT = True

Developing
----------

.. image:: https://travis-ci.org/ministryofjustice/money-to-prisoners-common.svg?branch=master
    :target: https://travis-ci.org/ministryofjustice/money-to-prisoners-common

* Test using ``./run.py test`` or ``python setup.py test``
* Update the version with ``./run.py set_version --version [?.?.?]``
* Commit and push changes to github
* Submit to PyPi with ``./run.py upload``

Translating
-----------

Update translation files with ``./run.py make_messages`` – you need to do this every time any translatable text is updated.

Compile messages ``./run.py compile_messages`` – only needed during local testing or development, it happens automatically during build or upload.

Pull updates from Transifex with ``./run.py translations --pull``. You'll need to update translation files afterwards and manually check that the merges occurred correctly.

Push latest English to Transifex with ``./run.py translations --push``. NB: you should pull updates before pushing to merge correctly.

Common assets
-------------

All shared assets used for `money-to-prisoners-cashbook`_, `money-to-prisoners-bank-admin`_,
`money-to-prisoners-prisoner-location-admin`_ and `money-to-prisoners-send-money`_ are kept in this package.

Each application’s build scripts install this package automatically.

SCSS, JavaScript, images
------------------------

Assets that need compiling are in ``mtp_common/assets-src/(images|javascripts|scss)``.
The base sass file, ``_mtp.scss``, is used to include the sass includes from this packge into each frontend app.

Static assets are in ``mtp_common/static/(images|javascripts|css)``.

There is a `separate guide to the various visual elements`_
defined in this repository and used by the various MTP apps.

Django templates
----------------

Common templates used by the client applications are kept in ``mtp_common/templates``.

.. _separate guide to the various visual elements: mtp_common/docs/README.md
.. _money-to-prisoners-api: https://github.com/ministryofjustice/money-to-prisoners-api
.. _money-to-prisoners-cashbook: https://github.com/ministryofjustice/money-to-prisoners-cashbook
.. _money-to-prisoners-bank-admin: https://github.com/ministryofjustice/money-to-prisoners-bank-admin
.. _money-to-prisoners-prisoner-location-admin: https://github.com/ministryofjustice/money-to-prisoners-prisoner-location-admin
.. _money-to-prisoners-send-money: https://github.com/ministryofjustice/money-to-prisoners-send-money


