Skip to content
Newer
Older
100644 140 lines (105 sloc) 5.43 KB
3b6aa4b @mcdonc unscrew the guidelines for add ons and dev envs minimally
mcdonc authored
1 .. _addons_and_dev_envs:
2
3 Pyramid Add-On and Development Environment Guidelines
4 =====================================================
5
6 Along with the "100% test coverage, 100% documentation" requirements of all
7 packages that wish to be part of the Pylons Project, there are some more
8 specific guidelines for creating Pyramid add-ons and "development
9 environments". If you would like your add-on to be considered for inclusion
10 into the `Pyramid Add-Ons
11 <http://docs.pylonsproject.org/docs/pyramid.html#pyramid-add-ons>`_ or
12 `Development Environments
5599fea @mcdonc fix link
mcdonc authored
13 <http://docs.pylonsproject.org/docs/pyramid.html#pyramid-development-environment-documentation>`_
3b6aa4b @mcdonc unscrew the guidelines for add ons and dev envs minimally
mcdonc authored
14 sections of the Pylons Project web site, you should attempt to adhere to
15 these guidelines.
16
17 An "add-on" is a package which relies on Pyramid itself. If your add-on does
18 not rely on Pyramid, it's not an add-on (just a library), and it will not be
19 listed on the add-ons page.
20
21 A separate class of packages exist, which are not simply add-ons, but contain
22 opinions usually taking shape in the form of "Paster templates", which set up
23 a locally customized Pyramid application on behalf of users who like that set
24 of opinions. These are referred to as "development environments".
25
26 Below, we talk about what makes a good add-on and what makes a good
27 development environment.
28
db70ee2 @kiorky add collectie docs
kiorky authored
29 Contributing Addons
30 ----------------------
5609de4 @mcdonc Wording.
mcdonc authored
31 Pyramid provides a repository that allows everyone to share add-ons.
db70ee2 @kiorky add collectie docs
kiorky authored
32
33 Please refer to the `community docs <https://github.com/pyramid-collective/pyramid-collective.github.com>`_
34
3b6aa4b @mcdonc unscrew the guidelines for add ons and dev envs minimally
mcdonc authored
35 Making Good Add-Ons
36 -------------------
37
38 Add-on packages should be named ``pyramid_foo`` where ``foo`` describes the
39 functionality of the package. For example, ``pyramid_mailer`` is a great
40 name for something that provides outbound mail service. If the name you want
41 has already been taken, try to think of another, e.g. ``pyramid_mailout``.
42 If the functionality of the package cannot easily be described with one word,
43 or the name you want has already been taken and you can't think of another
44 name related to functionality, use a codename, e.g. ``pyramid_postoffice``.
45
46 If your package provides "configuration" functionality, you will be tempted
47 to create your own framework to do the configuration, ala::
48
49 class MyConfigurationExtender(object):
50 def __init__(self, config):
51 self.config = config
52
53 def doit(self, a, b):
54 self.config.somedirective(a, b)
55
56 extender = MyConfigurationExtender(config)
57 extender.doit(1, 2)
58
59 Instead of doing so, use the ``add_directive`` method of a configurator as
60 documented at
61 http://docs.pylonsproject.org/projects/pyramid/1.0/narr/advconfig.html#adding-methods-to-the-configurator-via-add-directive
62 ::
63
64 def doit(config, a, b):
65 config.somedirective(a, b)
66
67 config.add_directive('doit', doit)
68
69 If your add-on wants to provide some default behavior, provide an
70 ``includeme`` method in your add-on's ``__init__.py``, so
71 ``config.include('pyramid_foo')`` will pick it up. See `Including
72 Configuration From External Sources
73 <http://docs.pylonsproject.org/projects/pyramid/1.0/narr/advconfig.html#including-configuration-from-external-sources>`_.
74
75 Making Good Development Environments
76 ------------------------------------
77
78 If you are creating a higher-level framework atop the Pyramid codebase that
79 contains "template" code (skeleton code rendered by a user via ``paster
80 create -t foo``), for the purposes of uniformity with other "development
db70ee2 @kiorky add collectie docs
kiorky authored
81 environment" packages, we offer some guidelines below.
3b6aa4b @mcdonc unscrew the guidelines for add ons and dev envs minimally
mcdonc authored
82
83 * It should not be named with a ``pyramid_`` prefix. For example, instead
84 of ``pyramid_foo`` it should just be named ``foo``. The ``pryamid_``
85 prefix is best used for add-ons that plug some discrete functionality in
86 to Pyramid, not for code that simply uses Pyramid as a base for a
87 separate framework with its own "opinions".
88
89 * It should be possible to subsequently run ``paster serve
90 development.ini`` to start any ``paster create`` -rendered application.
91
92 * ``development.ini`` should ensure that the ``pyramid_debugtoolbar``
93 package is active.
94
95 * There should be a ``production.ini`` file that mirrors
96 ``development.ini`` but disincludes ``pyramid_debugtoolbar``.
97
98 * The ``[server:main]`` section of both ``production.ini`` and
99 ``development.ini`` should start ``paste.httpserver`` on port 6543, ala::
100
101 [server:main]
102 use = egg:Paste#http
103 host = 0.0.0.0
104 port = 6543
105
106 * ``development.ini`` and ``production.ini`` should configure logging (see
107 any existing template).
108
109 * It should be possible to use ``paster pshell development.ini`` to visit
110 an interactive shell using a ``paster create``-rendered application.
111
112 * Startup/configuration code should live in a function named ``main``
113 within the ``__init__.py`` of the main package of the rendered template.
114 This function should be linked within a ``paster.app_factory`` section in
115 the template's ``setup.py`` like so::
116
117 entry_points = """\
118 [paste.app_factory]
119 main = {{package}}:main
120 """
121
122 This makes it possible for users to use the following pattern
123 (particularly ``use = egg:{{project}}``)::
124
125 [app:{{project}}]
126 use = egg:{{project}}
127 reload_templates = true
128 .. other config ..
129
130 * WSGI middleware configuration should not be inlined into imperative code
131 within the ``main`` function. Instead, middleware should be configured
132 within a ``[pipeline:main]`` section in the configuration file, e.g.::
133
134 [pipeline:main]
135 pipeline =
136 egg:WebError#evalerror
137 tm
138 {{project}}
139
Something went wrong with that request. Please try again.