-
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, for example,
- 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, for example, 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
- 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
- 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 pcreate -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
pserve development.ini to start any
- pcreate-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:
-
-
- [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
pshell development.ini to visit an interactive shell using a
- pcreate-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 = {{ htmlEscape "{{package}}:main" }}
-"""
-
-
-
- - This makes it possible for users to use the following pattern (particularly
-
{{ htmlEscape "use = egg:{{project}}" }}):
-
-
- {{ htmlEscape "[app:{{project}}]" }}
-{{ htmlEscape "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:
-
-
- [pipeline:main]
-pipeline =
- egg:WebError#evalerror
- tm
- {{ htmlEscape "{{project}}" }}
-
-
-
-
-
-
- 
-