Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 172 lines (133 sloc) 7.269 kB
bfd4b39 @mcdonc - Changed scaffolding machinery around a bit to make it easier for pe…
mcdonc authored
1 .. _scaffolding_chapter:
2
3 Creating Pyramid Scaffolds
4 ==========================
5
6 You can extend Pyramid by creating a :term:`scaffold` template. A scaffold
7 template is useful if you'd like to distribute a customizable configuration
8 of Pyramid to other users. Once you've created a scaffold, and someone has
9 installed the distribution that houses the scaffold, they can use the
10 ``pcreate`` script to create a custom version of your scaffold's template.
11 Pyramid itself uses scaffolds to allow people to bootstrap new projects. For
12 example, ``pcreate -s alchemy MyStuff`` causes Pyramid to render the
13 ``alchemy`` scaffold template to the ``MyStuff`` directory.
14
15 Basics
16 ------
17
18 A scaffold template is just a bunch of source files and directories on disk.
19 A small definition class points at this directory; it is in turn pointed at
20 by a :term:`setuptools` "entry point" which registers the scaffold so it can
21 be found by the ``pcreate`` command.
22
23 To create a scaffold template, create a Python :term:`distribution` to house
24 the scaffold which includes a ``setup.py`` that relies on the ``setuptools``
25 package. See `Creating a Package
26 <http://guide.python-distribute.org/creation.html>`_ for more information
27 about how to do this. For the sake of example, we'll pretend the
28 distribution you create is named ``CoolExtension``, and it has a package
29 directory within it named ``coolextension``
30
31 Once you've created the distribution put a "scaffolds" directory within your
32 distribution's package directory, and create a file within that directory
33 named ``__init__.py`` with something like the following:
34
35 .. code-block:: python
36 :linenos:
37
38 # CoolExtension/coolextension/scaffolds/__init__.py
39
40 from pyramid.scaffolds import PyramidTemplate
41
42 class CoolExtensionTemplate(PyramidTemplate):
43 _template_dir = 'coolextension_scaffold'
44 summary = 'My cool extension'
45
46 Once this is done, within the ``scaffolds`` directory, create a template
47 directory. Our example used a template directory named
48 ``coolextension_scaffold``.
49
50 As you create files and directories within the template directory, note that:
51
52 - Files which have a name which are suffixed with the value ``_tmpl`` will be
53 rendered, and replacing any instance of the literal string ``{{var}}`` with
54 the string value of the variable named ``var`` provided to the scaffold.
55
56 - Files and directories with filenames that contain the string ``+var+`` will
57 have that string replaced with the value of the ``var`` variable provided
58 to the scaffold.
59
60 Otherwise, files and directories which live in the template directory will be
61 copied directly without modification to the ``pcreate`` output location.
62
63 The variables provided by the default ``PyramidTemplate`` include ``project``
64 (the project name provided by the user as an argument to ``pcreate``),
65 ``package`` (a lowercasing and normalizing of the project name provided by
66 the user), ``random_string`` (a long random string), and ``package_logger``
67 (the name of the package's logger).
68
69 See Pyramid's "scaffolds" package
70 (https://github.com/Pylons/pyramid/tree/master/pyramid/scaffolds) for
71 concrete examples of scaffold directories (``zodb``, ``alchemy``, and
72 ``starter``, for example).
73
74 After you've created the template directory, add the following to the
75 ``entry_points`` value of your distribution's ``setup.py``:
76
77 [pyramid.scaffold]
78 coolextension=coolextension.scaffolds:CoolExtensionTemplate
79
80 For example::
81
82 def setup(
83 ...,
84 entry_points = """\
85 [pyramid.scaffold]
86 coolextension=coolextension.scaffolds:CoolExtensionTemplate
87 """
88 )
89
90 Run your distribution's ``setup.py develop`` or ``setup.py install``
91 command. After that, you should be able to see your scaffolding template
92 listed when you run ``pcreate -l``. It will be named ``coolextension``
93 because that's the name we gave it in the entry point setup. Running
94 ``pcreate -s coolextension MyStuff`` will then render your scaffold to an
95 output directory named ``MyStuff``.
96
97 See the module documentation for :mod:`pyramid.scaffolds` for information
98 about the API of the :class:`pyramid.scaffolds.PyramidScaffold` class and
99 related classes. You can override methods of this class to get special
100 behavior.
101
102 Supporting Older Pyramid Versions
103 ---------------------------------
104
105 Because different versions of Pyramid handled scaffolding differently, if you
106 want to have extension scaffolds that can work across Pyramid 1.0.X, 1.1.X,
107 1.2.X and 1.3.X, you'll need to use something like this bit of horror while
108 defining your scaffold template:
109
110 .. code-block:: python
111 :linenos:
112
113 try: # pyramid 1.0.X
604b812 @mcdonc avoid warning under 1.2
mcdonc authored
114 # "pyramid.paster.paste_script..." doesn't exist past 1.0.X
351777c @mcdonc fix for 1.0
mcdonc authored
115 from pyramid.paster import paste_script_template_renderer
604b812 @mcdonc avoid warning under 1.2
mcdonc authored
116 from pyramid.paster import PyramidTemplate
bfd4b39 @mcdonc - Changed scaffolding machinery around a bit to make it easier for pe…
mcdonc authored
117 except ImportError:
118 try: # pyramid 1.1.X, 1.2.X
119 # trying to import "paste_script_template_renderer" fails on 1.3.X
120 from pyramid.scaffolds import paste_script_template_renderer
121 from pyramid.scaffolds import PyramidTemplate
122 except ImportError: # pyramid >=1.3a2
123 paste_script_template_renderer = None
124 from pyramid.scaffolds import PyramidTemplate
125
9103fbc @mcdonc wrong class name, fixes #451
mcdonc authored
126 class CoolExtensionTemplate(PyramidTemplate):
bfd4b39 @mcdonc - Changed scaffolding machinery around a bit to make it easier for pe…
mcdonc authored
127 _template_dir = 'coolextension_scaffold'
128 summary = 'My cool extension'
129 template_renderer = staticmethod(paste_script_template_renderer)
130
131 And then in the setup.py of the package that contains your scaffold, define
132 the template as a target of both ``paste.paster_create_template`` (for
133 ``paster create``) and ``pyramid.scaffold`` (for ``pcreate``)::
134
135 [paste.paster_create_template]
136 coolextension=coolextension.scaffolds:CoolExtensionTemplate
137 [pyramid.scaffold]
138 coolextension=coolextension.scaffolds:CoolExtensionTemplate
139
140 Doing this hideousness will allow your scaffold to work as a ``paster
141 create`` target (under 1.0, 1.1, or 1.2) or as a ``pcreate`` target (under
142 1.3). If an invoker tries to run ``paster create`` against a scaffold
143 defined this way under 1.3, an error is raised instructing them to use
144 ``pcreate`` instead.
145
146 If you want only to support Pyramid 1.3 only, it's much cleaner, and the API
147 is stable:
148
149 .. code-block:: python
150 :linenos:
151
152 from pyramid.scaffolds import PyramidTemplate
153
154 class CoolExtensionTemplate(PyramidTemplate):
155 _template_dir = 'coolextension_scaffold'
156 summary = 'My cool_extension'
157
158 You only need to specify a ``paste.paster_create_template`` entry point
159 target in your ``setup.py`` if you want your scaffold to be consumable by
160 users of Pyramid 1.0, 1.1, or 1.2. To support only 1.3, specifying only the
161 ``pyramid.scaffold`` entry point is good enough. If you want to support both
162 ``paster create`` and ``pcreate`` (meaning you want to support Pyramid 1.2
163 and some older version), you'll need to define both.
164
165 Examples
166 --------
167
168 Existing third-party distributions which house scaffolding are available via
169 :term:`PyPI`. The ``pyramid_jqm``, ``pyramid_zcml`` and ``pyramid_jinja2``
170 packages house scaffolds. You can install and examine these packages to see
171 how they work in the quest to develop your own scaffolding.
Something went wrong with that request. Please try again.