.. _addons_and_dev_envs:
Add-on and Development Environment Guidelines
=============================================
Along with the "100% test coverage, 100% documentation" requirements of all
packages that wish to be part of the Pylons Project, there are some more
specific guidelines for creating add-ons and "development environments" for
Pyramid. If you would like your add-on to be considered for inclusion into
the :ref:`pyramid-add-ons` or :ref:`sample_pyramid_dev_env` sections of
the Pylons Project web site, you should attempt to adhere to these guidelines.
An "add-on" is a package which relies on Pyramid itself. If your add-on does
not rely on Pyramid, it's not an add-on (just a library), and it will not be
listed on the add-ons page.
"Development environments" are packages which use Pyramid as a core, but offer
alternate services and scaffolding. Each development environment presents a
set of opinions and a "personality" to its users. Although users of a
development environment can still use all of the services offered by the
Pyramid core, they are usually guided to a more focused set of opinions
offered by the development environment itself. Development environments
often have dependencies beyond those of the Pyramid core.
Below, we talk about what makes a good add-on and what makes a good
development environment.
Contributing Add-ons
--------------------
Pyramid provides a repository that allows everyone to share add-ons.
Please refer to the `community docs `_.
Making Good Add-Ons
-------------------
Add-on packages should be named ``pyramid_foo`` where ``foo`` describes the
functionality of the package. For example, ``pyramid_mailer`` is a great
name for something that provides outbound mail service. If the name you want
has already been taken, try to think of another, e.g. ``pyramid_mailout``.
If the functionality of the package cannot easily be described with one word,
or the name you want has already been taken and you can't think of another
name related to functionality, use a codename, e.g. ``pyramid_postoffice``.
If your package provides "configuration" functionality, you will be tempted
to create your own framework to do the configuration, like the following::
class MyConfigurationExtender(object):
def __init__(self, config):
self.config = config
def doit(self, a, b):
self.config.somedirective(a, b)
extender = MyConfigurationExtender(config)
extender.doit(1, 2)
Instead of doing so, use the ``add_directive`` method of a configurator as
documented at :ref:`Adding Methods to the Configurator via add_directive `::
def doit(config, a, b):
config.somedirective(a, b)
config.add_directive('doit', doit)
If your add-on wants to provide some default behavior, provide an
``includeme`` method in your add-on's ``__init__.py``, so
``config.include('pyramid_foo')`` will pick it up. See :ref:`Including
Configuration From External Sources `.
Making Good Development Environments
------------------------------------
If you are creating a higher-level framework atop the Pyramid codebase that
contains "template" code (skeleton code rendered by a user via ``paster
create -t foo``), for the purposes of uniformity with other "development
environment" packages, we offer some guidelines below.
* It should not be named with a ``pyramid_`` prefix. For example, instead
of ``pyramid_foo`` it should just be named ``foo``. The ``pyramid_``
prefix is best used for add-ons that plug some discrete functionality in
to Pyramid, not for code that simply uses Pyramid as a base for a
separate framework with its own "opinions".
* It should be possible to subsequently run ``paster serve
development.ini`` to start any ``paster create`` -rendered application.
* ``development.ini`` should ensure that the ``pyramid_debugtoolbar``
package is active.
* There should be a ``production.ini`` file that mirrors
``development.ini`` but disincludes ``pyramid_debugtoolbar``.
* The ``[server:main]`` section of both ``production.ini`` and
``development.ini`` should start ``paste.httpserver`` on port 6543, ala::
[server:main]
use = egg:Paste#http
host = 0.0.0.0
port = 6543
* ``development.ini`` and ``production.ini`` should configure logging (see
any existing template).
* It should be possible to use ``paster pshell development.ini`` to visit
an interactive shell using a ``paster create``-rendered application.
* Startup/configuration code should live in a function named ``main``
within the ``__init__.py`` of the main package of the rendered template.
This function should be linked within a ``paster.app_factory`` section in
the template's ``setup.py`` like so::
entry_points = """\
[paste.app_factory]
main = {{package}}:main
"""
This makes it possible for users to use the following pattern
(particularly ``use = egg:{{project}}``)::
[app:{{project}}]
use = egg:{{project}}
reload_templates = true
.. other config ..
* WSGI middleware configuration should not be inlined into imperative code
within the ``main`` function. Instead, middleware should be configured
within a ``[pipeline:main]`` section in the configuration file, e.g.::
[pipeline:main]
pipeline =
egg:WebError#evalerror
tm
{{project}}