Installation

Getting the package

Note

Regardless of the installation method that you choose, it is recommended that you use a virtual environment to keep your Python environment clean. If you are using Python 3.6 or greater, the tools you will to create virtual environments ship with the interpreter as the venv module. For older versions of Python, or for further customization, see the virtualenv and virtualenvwrapper packages.

The recommended way to install Django HTCPCP-TEA is via pip:

$ pip install django-htcpcp-tea

Alternatively, you can install Django HTCPCP-TEA from its source:

$ git clone git://github.com/blueschu/django-htcpcp-tea.git
$ cd django-htcpcp-tea
$ python3 setup.py install

Installing the Django App

To load Django HTCPCP-TEA into an existing Django project, add 'django_htcpcp_tea' to the INSTALLED_APPS list in your setting file:

INSTALLED_APPS = [
    # ...
    'django_htcpcp_tea',
    # ...
]

If you intend to use interactive pot sessions, make sure that the Django sessions framework is also installed and properly configured (it’s installed by default).

Next, enable the Django HTCPCP-TEA middleware in your settings:

MIDDLEWARE = [
    # ...
    'django_htcpcp_tea.middleware.HTCPCPTeaMiddleware',
    # ...
]

Configuring the URL patterns

It is recommend to install the URL configuration for Django HTCPCP-TEA in one of two fashions: the “Standard” Installation, where this app behaves like a standard Django app and is isolated to the URL namespace you include it under, or the “Schema Compliant” Installation, which makes this app work extra hard to follow the HTCPCP URI schema.

Standard Installation

You can include the Django HTCPCP-TEA urls in your URL configuration in the same way as any Django app:

from django.urls import include, path

urlspatterns = [
    # ...
    path('htcpcp/', include('django_htcpcp_tea.urls')),
    # ...
]

With this installation method, all HTCPCP URIs must be prefixed with the string /htcpcp. For example, the request line a of BREW request to Pot #1 would look like

BREW /htcpcp/pot-1/ HTTP/1.1

Schema Compliant Installation

For an installation that closely follows that HTCPCP standard, append the Django HTCPCP-TEA URLs directly to your URL patterns:

from django.urls import include, path
from django_htcpcp_tea import urls as htcpcp_urls

urlspatterns = [
    # ...
]

urlpatterns += htcpcp_urls.urlpatterns

Then, add the following options to your project’s Django settings file:

HTCPCP_OVERRIDE_ROOT_URI = True

This will allow Django HTCPCP-TEA to override default URL dispatcher when it receives a request that is unambiguously an HTCPCP request. Making requests to the root url (/) or top-level HTCPCP URIs (e.g. /pot-1/earl-grey/) will behave as defined in RFCs 2324 and 7168 with no /htcpcp prefix required.

(Optional) Loading the demo data fixture

Django HTCPCP-TEA ships will a few data fixtures to help you explore the app after installation:

  • rfc_2324_additions: All of the beverage additions types listed as examples in RFC 2324.
  • rfc_7168_additions: The Sugar addition types added to the HTCPCP standard in RFC 7168.
  • rfc_7168_teas: The tea types listed as examples in RFC 7168.
  • demo_pots: A hand-craft selection of coffee- and teapots to demonstrate the HTCPCP protocol (depends on rfc_2324_additions and rfc_7168_teas).
  • demo_forbidden_combinations: Common sense rules that forbid combinations of additions contrary to the sensibilities of a consensus of drinkers (depends on rfc_2324_additions and rfc_7168_teas).

Each of these data fixtures can be loaded using the following manage.py command:

$ ./manage.py loaddata FIXTURE