5. Package an addon (installation)¶

So far we have added applications by adding a module into the project directoryor installing via pip.

In each case, the applications had to be configured. However, thisconfiguration can be automated, making it possible to create self-configuringapplications, that take care of applying the necessary settings when they areadded to a project - so you can install them without having to touch yoursettings.py at all.

This is done by providing an application with an aldryn_config.py file, in which the application will check the project andensure that INSTALLED_APPS, urls.py and other key configurationsettings are correct.

The Divio Cloud also allows applications to be installed into projects from theControl Panel, selecting the version to be installed and configuring theapplication - i.e. applying some settings - using a web form. This is alsohandled by the same aldryn_config.py file.

In this section of the tutorial, we’ll start packaging Django Debug Toolbar asa Divio Cloud addon, so that it can install itself into a project.

Important

In the examples below, pay particular attention to the use of dashes -and underscores _ in the names of files and directories.

In Python naming conventions, a package name will use dashes, as intutorial-django-debug-toolbar. The application name within the package will useunderscores: tutorial_django_debug_toolbar.

This is significant, because although underscores are theoretically allowed in package names,various tools, including pip, will silently convert them to dashes, with predictablyconfusing results.

5.1. Register the addon¶

Before your addon can be uploaded, the Divio Cloud must be ready to receive it(just as GitHub requires you to create the repository on the platform beforeyou can push a local repository)

Go to your addons in the Divio Control Panel and Add custom addon.

The Package Name field is the most important, and must be unique on thesystem. Call it <your name>-django-debug-toolbar.

Important

From this point onwards for convenience we will refer to this astutorial-django-debug-toolbar in examples - but you need to substitute<your name>-django-debug-toolbar, that you registered the addon with.

Every time you see “tutorial”, remember to use your own name instead.

The other fields:

Name
<your name> Django Debug Toolbar
License
Select a license for your addon
Organisation
You can leave this blank
'Add custom addon'
When you hit Create addon, the addon tutorial-django-debug-toolbar willbe registered on the system. On the next page, supply a Description for theaddon:

  1. Tutorial Django Debug Toolbar

A Divio Cloud addon to install and configure Django Debug Toolbar into
Divio Cloud projects. Created as part of the Divio Cloud developer
tutorial.

and hit Save once more.

5.2. Add the packaging files¶

We need to work in the project’s addons-dev directory. Create a newtutorial-django-debug-toolbar directory in there.

Select Package Information from your addon’s menu. From here, you’ll be ableto download system-created versions of the required packaging files. Of courseyou can also create them yourself, but this will save you the trouble.

5.2.1. Add setup.py¶

In the current set-up, we install the Django Debug Toolbar package manually. Westill want it to be installed, but we need the addon to take care of theinstallation for us instead.

Remove django-debug-toolbar==1.8 from requirements.in.

If you now rebuild the project and try to run it, you’ll get an error:

  1. ➜ docker-compose build web
  2. Building web
  3. [...]
  4. Successfully built 9317b86c7745
  5. ➜ docker-compose up
  6. [...]
  7. web_1  | ImportError: No module named debug_toolbar

Instead, move the setup.py file you downloaded totutorial-django-debug-toolbar to handle installation. You’ll need to make one change in it:

  1. # -*- coding: utf-8 -*-
  2. from setuptools import setup, find_packages
  3. from tutorial_django_debug_toolbar import __version__
  4.  
  5.  
  6. setup(
  7.     name='tutorial-django-debug-toolbar',
  8.     version=__version__,
  9.     description=open('README.rst').read(),
  10.     author='Django Developer',
  11.     author_email='[[email protected]](http://docs.divio.com/cdn-cgi/l/email-protection)',
  12.     packages=find_packages(),
  13.     platforms=['OS Independent'],
  14.     install_requires=["django-debug-toolbar==1.8"],
  15.     include_package_data=True,
  16.     zip_safe=False,
  17. )

5.2.2. Add init.py¶

You’ll see from the setup.py that it expects to find a version number at tutorialdjangodebug_toolbar.__version:

  1. from tutorial_django_debug_toolbar import __version__
  2.  
  3.  
  4. setup(
  5.     [...]
  6.     version=__version__,
  7.     [...]
  8. )

Create a new directory inside the addon, namedtutorialdjangodebug_toolbar. Download and move the the __init.pyfile provided by the Control Panel to the new directory.

By default it declares the version number as 0.0.1, but we recommendtracking the version number of the application that it installs (in this case,1.8) so change it to:

  1. __version__ = "1.8.0.1"

(If you create another version of the addon to installdjango-debug-toolbar==1.8, that would be version 1.8.0.2. For version1.9, you’d start at 1.9.0.1 and so on.)

5.2.3. Add README.rst¶

The setup() of setup.py expects to find a README file:

  1. setup(
  2.     [...]
  3.     description=open('README.rst').read(),
  4.     [...]
  5. )

Download and add the README.rst file. If you haven’t already provided aDescription via the Control Panel, it will be empty, otherwise, it willcontain the description.

5.3. Build the project with the new addon¶

We’re now ready to build the project. Check that the addon file structure lookslike this:

  1. addons-dev/
  2.     tutorial-django-debug-toolbar/
  3.         tutorial_django_debug_toolbar/
  4.             __init__.py
  5.         README.rst
  6.         setup.py

and run:

  1. divio project develop tutorial-django-debug-toolbar
  1. ➜  divio project develop tutorial-django-debug-toolbar
  2. Building web
  3. [...]
  4. The package tutorial-django-debug-toolbar has been added to your local development project!

See the divio project develop reference for more.

You can test that it works by starting the project again (docker-compose
up).

Once divio project develop <addon> has been run, it doesn’t need to beexecuted again. From this point henceforth any changes you make to the addon,other than in its setup.py, can be picked up automatically, even while theproject is still running.

Note that:

  • Adding new files may require you to restart the server.
  • Changes to setup.py will require running docker-compose build web.
    We now have mechanism for a self-installing addon package. The next stepis configuration.

原文: http://docs.divio.com/en/latest/introduction/05-package-addon.html