Skip to content
Newer
Older
100644 196 lines (130 sloc) 8.93 KB
4444dd3 @gjhiggins Assorted doc edits and additions.
gjhiggins authored Aug 15, 2008
1 .. _creating_paste_templates:
2
3 ========================
4 Creating Paste templates
5 ========================
6
7 Introduction
8 ============
9
efc694c @bbangert More tweaks to reduce latex warnings
bbangert authored Sep 3, 2008
10 `Python Paste <http://pythonpaste.org/>`_ is an extremely powerful package that isn't just about WSGI middleware. The related document :ref:`entry_points_and_plugins` demonstrates how to use entry_points to create simple plugins. This document describes how to write just such a plugin for use Paste's project template creation facility and how to add a command to Paste's ``paster`` script.
4444dd3 @gjhiggins Assorted doc edits and additions.
gjhiggins authored Aug 15, 2008
11
12 The example task is to create a template for an imaginary content management system. The template is going to produce a project directory structure for a Python package, so we need to be able to specify a package name.
13
14 Creating The Directory Structure and Templates
15 ==============================================
16
17 The directory structure for the new project needs to look like this:
18
19 .. code-block:: text
20
21 - default_project
22 - +package+
23 - __init__.py
24 - static
25 - layout
26 - region
27 - renderer
28 - service
29 - layout
30 - __init__.py
31 - region
32 - __init__.py
33 - renderer
34 - __init__.py
35 - setup.py_tmpl
36 - setup.cfg_tmpl
37 - development.ini_tmpl
38 - README.txt_tmpl
39 - ez_setup.py
40
41 Of course, the actual project's directory structure might look very different. In fact the ``paster create`` command can even be used to generate directory structures which *aren't* project templates --- although this wasn't what it was designed for.
42
43 When the ``paster create`` command is run, any directories with ``+package+`` in their name will have that portion of the name replaced by a simplified package name and likewise any directories with ``+egg+`` in their name will have that portion replaced by the name of the egg directory, although we don't make use of that feature in this example.
44
45 All of the files with ``_tmpl`` at the end of their filenames are treated as templates and will have the variables they contain replaced automatically. All other files will remain unchanged.
46
47 .. note:: The small templating language used with ``paster create`` in files ending in ``_tmpl`` is described in detail in the `Paste util module documentation <http://pythonpaste.org/module-paste.util.template.html>`_
48
49 When specifying a package name it can include capitalisation and ``_`` characters but it should be borne in mind that the actual name of the package will be the *lowercase* package name with the ``_`` characters removed. If the package name contains an ``_``, the egg name will contain a ``_`` character so occasionally the ``+egg+`` name is different to the ``+package+`` name.
50
51 To avoid difficulty always recommend to users that they stick with package names that contain no ``_`` characters so that the names remain unique when made lowercase.
52
53 Implementing the Code
54 =====================
55
56 Now that the directory structure has been defined, the next step is to implement the commands that will convert this to a ready-to-run project. The template creation commands are implemented by a class derived from ``paste.script.templates.Template``. This is how our example appears:
57
58 .. code-block:: python
59
60 from paste.script.templates import Template, var
61
62 vars = [
63 var('version', 'Version (like 0.1)'),
64 var('description', 'One-line description of the package'),
65 var('long_description', 'Multi-line description (in reST)'),
66 var('keywords', 'Space-separated keywords/tags'),
67 var('author', 'Author name'),
68 var('author_email', 'Author email'),
69 var('url', 'URL of homepage'),
70 var('license_name', 'License name'),
71 var('zip_safe', 'True/False: if the package can be distributed as a .zip file',
72 default=False),
73 ]
74
75 class ArtProjectTemplate(Template):
76 _template_dir = 'templates/default_project'
77 summary = 'Art project template'
78 vars = vars
79
80 The ``vars`` arguments can all be set at run time and will be available to be used as (in this instance) Cheetah template variables in the files which end ``_tmpl``. For example the ``setup.py_tmpl`` file for the ``default_project`` might look like this:
81
82 .. code-block:: html+mako
83
84 from setuptools import setup, find_packages
85
86 version = ${repr(version)|"0.0"}
87
88 setup(name=${repr(project)},
89 version=version,
90 description="${description|nothing}",
91 long_description="""\
92 ${long_description|nothing}""",
93 classifiers=[],
94 keywords=${repr(keywords)|empty},
95 author=${repr(author)|empty},
96 author_email=${repr(author_email)|empty},
97 url=${repr(url)|empty},
98 license=${repr(license_name)|empty},
99 packages=find_packages(exclude=['ez_setup']),
100 include_package_data=True,
101 zip_safe=${repr(bool(zip_safe))|False},
102 install_requires=[
103 # Extra requirements go here #
104 ],
105 entry_points="""
106 [paste.app_factory]
107 main=${package}:make_app
108 """,
109 )
110
111
112 .. note: The list of available classifier strings can be obtained from: ``http://www.python.org/pypi?%3Aaction=list_classifiers``
113
114 Note how the variables specified in ``vars`` earlier are used to generate the actual ``setup.py`` file.
115
116 In order to use the new templates they must be hooked up to the ``paster create`` command by means of an entry point. In the ``setup.py`` file of the project (in which created the project template is going to be stored) we need to add the following:
117
118 .. code-block:: python
119
120 entry_points="""
121 [paste.paster_create_template]
122 art_project=art.entry.template:ArtProjectTemplate
123 """,
124
125 We also need to add ``PasteScript>=1.3`` to the ``install_requires`` line.
126
127 .. code-block:: python
128
129 install_requires=["PasteScript>=1.3"],
130
131 We just need to install the entry points now by running:
132
133 .. code-block:: bash
134
135 python setup.py develop
136
137 We should now be able to see a list of available templates with this command:
138
139 .. code-block:: bash
140
141 $ paster create --list-templates
142
143
144 .. note:: Windows users will need to add their Python scripts directory to their path or enter the full version of the command, similar to this:
145
146 .. code-block:: bash
147
148 C:\Python24\Scripts\paster.exe create --list-templates
149
150 You should see the following:
151
152 .. code-block:: text
153
154 Available templates:
155 art_project: Art project template
156 basic_package: A basic setuptools-enabled package
157
158
159 There may be other projects too.
160
161
162 Troubleshooting
163 ===============
164
165 If the Art entries don't show up, check whether it is possible to import the ``template.py`` file because any errors are simply ignored by the paster create command rather than output as a warning.
166
167 If the code is correct, the issue might be that the entry points data hasn't been updated. Examine the Python ``site-packages`` directory and delete the ``Art.egg-link`` files, any ``Art*.egg`` files or directories and remove any entries for art from ``easy_install.pth`` (replacing ``Art`` with the name chosen for the project of course). Then re-run ``python setup.py develop`` to install the correct information.
168
169 If problems are still evident, then running the following code will print out a list of all entry points. It might help track the problem down:
170
171 .. code-block:: python
172
173 import pkg_resources
174 for x in pkg_resources.iter_group_name(None, None):
175 print x
176
177 Using the Template
178 ===================
179
180 Now that the entry point is working, a new project can be created:
181
182 .. code-block:: bash
183
184 $ paster create --template=art TestProject
185
186 Paster will ask lots of questions based on the variables set up in ``vars`` earlier. Pressing ``return`` will cause the default to be used. The final result is a nice project template ready for people to start coding with.
187
188 Implementing Pylons Templates
189 =============================
190
191 If the development context is subject to a frequent need to create lots of Pylons projects, each with a slightly different setup from the standard Pylons defaults then it is probably desirable to create a customised Pylons template to use when generating projects. This can be done in exactly the way described in this document.
192
193 First, set up a new Python package, perhaps called something like ``CustomPylons`` (obviously, don't use the Pylons name because Pylons itself is already using it). Then check out the Pylons source code and copy the `pylons/templates/default_project <http://pylonshq.com/project/pylonshq/browser/Pylons/trunk/pylons/templates/default_project>`_ directory into the new project as a starting point. The next stage is to add the custom ``vars`` and ``Template`` class and set up the entry points in the ``CustomPylons`` ``setup.py`` file.
194
195 After those tasks have been completed, it is then possible to create customised templates (ultimately based on the Pylons one) by using the ``CustomPylons`` package.
Something went wrong with that request. Please try again.