Extending Pyramid

Pyramid may be extended through add-ons and development environments. The Python Package Index trove classifier "Framework :: Pyramid" is used by over 470 packages. Support may be "official" by the Pylons Project or "unofficial" by the community.

All projects under the Pylons Project have 100% test coverage and 100% documentation.

An "add-on" is a package which relies on Pyramid itself and extends the functionality of Pyramid, such as adding an ORM, sending email, or using a template-based language. If your add-on does not rely on Pyramid, it's not an add-on, but just a library, and it will not be listed on the Extending Pyramid page. Official Pylons Project libraries may be listed.

"Development environments" are a special category of packages which use Pyramid as a core, but offer alternative services and scaffolding to ease web application development. Some could be labeled "content management system" or "admin interface". Development environments often have dependencies beyond those of the Pyramid core.

Contributing add-ons

Add-ons may be created and shared wherever you like. Pylons Project supported add-ons must be under its GitHub organization account, and comply with guidelines for How to Contribute Source Code and Documentation, Coding Style and Standards, and Unit Testing Guidelines. All Pylons Project participants should strive to follow our Code of Conduct.

To add your project to the listing, see Adding an add-on to "Extending Pyramid" page in CONTRIBUTING.md.

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 = {{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:

                [pipeline:main]
  pipeline =
      egg:WebError#evalerror
      tm
      {{project}}