Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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