Skip to content
Newer
Older
100644 972 lines (759 sloc) 41.3 KB
e0887ee De-stiltify.
Chris McDonough authored Dec 31, 2009
1 .. index::
2 single: Agendaless Consulting
3 single: Pylons
4 single: Django
5 single: Zope
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
6 single: frameworks vs. libraries
7 single: framework
e0887ee De-stiltify.
Chris McDonough authored Dec 31, 2009
8
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
9 :app:`Pyramid` Introduction
c4d7f0b @pauleveritt Start working on a glossary. Also, start changing repoze.bfg occurren…
pauleveritt authored Jul 24, 2008
10 ==============================
9e3bdbc Rearrange into narrative and API sections; include README in narrativ…
Chris McDonough authored Jul 16, 2008
11
b0d2078 @mcdonc apply recomenndations from graham
mcdonc authored Jan 24, 2011
12 :app:`Pyramid` is a general, open source, Python web application development
7a505db @mcdonc simplify
mcdonc authored Jul 11, 2011
13 *framework*. Its primary goal is to make it easier for a Python developer to
14 create web applications.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
15
16 .. sidebar:: Frameworks vs. Libraries
17
18 A *framework* differs from a *library* in one very important way:
19 library code is always *called* by code that you write, while a
20 framework always *calls* code that you write. Using a set of
21 libraries to create an application is usually easier than using a
22 framework initially, because you can choose to cede control to
23 library code you have not authored very selectively. But when you
24 use a framework, you are required to cede a greater portion of
25 control to code you have not authored: code that resides in the
26 framework itself. You needn't use a framework at all to create a
27 web application using Python. A rich set of libraries already
28 exists for the platform. In practice, however, using a framework
29 to create an application is often more practical than rolling your
30 own via a set of libraries if the framework provides a set of
31 facilities that fits your application requirements.
9e3bdbc Rearrange into narrative and API sections; include README in narrativ…
Chris McDonough authored Jul 16, 2008
32
b202997 @cguardia remove extra word
cguardia authored Jul 23, 2011
33 Pyramid attempts to follow these design and engineering principles:
878328b Latex rendering.
Chris McDonough authored Dec 27, 2009
34
35 Simplicity
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
36 :app:`Pyramid` takes a *"pay only for what you eat"* approach. You can get
37 results even if you have only a partial understanding of :app:`Pyramid`.
38 It doesn’t force you to use any particular technology to produce an
39 application, and we try to keep the core set of concepts that you need to
40 understand to a minimum.
878328b Latex rendering.
Chris McDonough authored Dec 27, 2009
41
42 Minimalism
fed66ef @stevepiercy Replaced "the the" with "the" under Minimalism
stevepiercy authored Sep 8, 2011
43 :app:`Pyramid` tries to solve only the fundamental problems of creating
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
44 a web application: the mapping of URLs to code, templating, security and
45 serving static assets. We consider these to be the core activities that are
46 common to nearly all web applications.
878328b Latex rendering.
Chris McDonough authored Dec 27, 2009
47
48 Documentation
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
49 Pyramid's minimalism means that it is easier for us to maintain complete
50 and up-to-date documentation. It is our goal that no aspect of Pyramid
51 is undocumented.
878328b Latex rendering.
Chris McDonough authored Dec 27, 2009
52
53 Speed
b0d2078 @mcdonc apply recomenndations from graham
mcdonc authored Jan 24, 2011
54 :app:`Pyramid` is designed to provide noticeably fast execution for common
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
55 tasks such as templating and simple response generation. Although "hardware
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
56 is cheap", the limits of this approach become painfully evident when one
b0d2078 @mcdonc apply recomenndations from graham
mcdonc authored Jan 24, 2011
57 finds him or herself responsible for managing a great many machines.
58
59 Reliability
60 :app:`Pyramid` is developed conservatively and tested exhaustively. Where
61 Pyramid source code is concerned, our motto is: "If it ain’t tested, it’s
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
62 broke".
878328b Latex rendering.
Chris McDonough authored Dec 27, 2009
63
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
64 Openness
b0d2078 @mcdonc apply recomenndations from graham
mcdonc authored Jan 24, 2011
65 As with Python, the Pyramid software is distributed under a `permissive
66 open source license <http://repoze.org/license.html>`_.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
67
d8fc16f @mcdonc garden
mcdonc authored Sep 7, 2011
68 .. _what_makes_pyramid_unique:
69
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
70 What Makes Pyramid Unique
71 -------------------------
72
73 Understandably, people don't usually want to hear about squishy engineering
74 principles, they want to hear about concrete stuff that solves their
75 problems. With that in mind, what would make someone want to use Pyramid
e088447 @mcdonc add renderer section; fix wording (thanks jpenny)
mcdonc authored Sep 7, 2011
76 instead of one of the many other web frameworks available today? What makes
77 Pyramid unique?
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
78
79 This is a hard question to answer, because there are lots of excellent
80 choices, and it's actually quite hard to make a wrong choice, particularly in
81 the Python web framework market. But one reasonable answer is this: you can
82 write very small applications in Pyramid without needing to know a lot.
83 "What?", you say, "that can't possibly be a unique feature, lots of other web
84 frameworks let you do that!" Well, you're right. But unlike many other
85 systems, you can also write very large applications in Pyramid if you learn a
86 little more about it. Pyramid will allow you to become productive quickly,
87 and will grow with you; it won't hold you back when your application is small
88 and it won't get in your way when your application becomes large. "Well
89 that's fine," you say, "lots of other frameworks let me write large apps
90 too." Absolutely. But other Python web frameworks don't seamlessly let you
91 do both. They seem to fall into two non-overlapping categories: frameworks
92 for "small apps" and frameworks for "big apps". The "small app" frameworks
93 typically sacrifice "big app" features, and vice versa.
94
95 We don't think it's a universally reasonable suggestion to write "small apps"
96 in a "small framework" and "big apps" in a "big framework". You can't really
5962195 @mcdonc wording
mcdonc authored Sep 7, 2011
97 know to what size every application will eventually grow. We don't really
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
98 want to have to rewrite a previously small application in another framework
99 when it gets "too big". We believe the current binary distinction between
5962195 @mcdonc wording
mcdonc authored Sep 7, 2011
100 frameworks for small and large applications is just false; a well-designed
101 framework should be able to be good at both. Pyramid strives to be that kind
102 of framework.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
103
104 To this end, Pyramid provides a set of features, that, combined, are unique
105 amongst Python web frameworks. Lots of other frameworks contain some
106 combination of these features; Pyramid of course actually stole many of them
107 from those other frameworks. But Pyramid is the only one that has all of
31dc8d5 @mcdonc misspelling
mcdonc authored Sep 7, 2011
108 them in one place, documented appropriately, and useful a la carte without
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
109 necessarily paying for the entire banquet. These are detailed below.
110
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
111 Single-file applications
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
112 ~~~~~~~~~~~~~~~~~~~~~~~~
113
114 You can write a Pyramid application that lives entirely in one Python file,
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
115 not unlike existing Python microframeworks. This is beneficial for one-off
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
116 prototyping, bug reproduction, and very small applications. These
117 applications are easy to understand because all the information about the
118 application lives in a single place, and you can deploy them without needing
119 to understand much about Python distributions and packaging. Pyramid isn't
2bf587e @mcdonc typo
mcdonc authored Sep 7, 2011
120 really marketed as a microframework, but it allows you to do almost
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
121 everything that frameworks that are marketed as micro offer in very similar
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
122 ways.
123
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
124 .. literalinclude:: helloworld.py
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
125
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
126 See also :ref:`firstapp_chapter`.
127
128 Decorator-based configuration
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
130
131 If you like the idea of framework configuration statements living next to the
132 code it configures, so you don't have to constantly switch between files to
133 refer to framework configuration when adding new code, you can use Pyramid
bdebfb8 @mcdonc wording
mcdonc authored Sep 7, 2011
134 decorators to localize the configuration. For example:
135
136 .. code-block:: python
137
138 from pyramid.view import view_config
139 from pyramid.response import Response
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
140
141 @view_config(route_name='fred')
142 def fred_view(request):
143 return Response('fred')
144
2bf587e @mcdonc typo
mcdonc authored Sep 7, 2011
145 However, unlike some other systems, using decorators for Pyramid
146 configuration does not make your application difficult to extend, test or
bdebfb8 @mcdonc wording
mcdonc authored Sep 7, 2011
147 reuse. The :class:`~pyramid.view.view_config` decorator, for example, does
148 not actually *change* the input or output of the function it decorates, so
149 testing it is a "WYSIWYG" operation; you don't need to understand the
150 framework to test your own code, you just behave as if the decorator is not
151 there. You can also instruct Pyramid to ignore some decorators, or use
152 completely imperative configuration instead of decorators to add views.
153 Pyramid decorators are inert instead of eager: you detect and activate them
154 with a :term:`scan`.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
155
156 Example: :ref:`mapping_views_using_a_decorator_section`.
157
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
158 URL generation
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
159 ~~~~~~~~~~~~~~
160
161 Pyramid is capable of generating URLs for resources, routes, and static
162 assets. Its URL generation APIs are easy to use and flexible. If you use
163 Pyramid's various APIs for generating URLs, you can change your configuration
164 around arbitrarily without fear of breaking a link on one of your web pages.
165
166 Example: :ref:`generating_route_urls`.
167
168 Static file serving
169 ~~~~~~~~~~~~~~~~~~~
170
171 Pyramid is perfectly willing to serve static files itself. It won't make you
172 use some external web server to do that. You can even serve more than one
173 set of static files in a single Pyramid web application (e.g. ``/static`` and
174 ``/static2``). You can also, optionally, place your files on an external web
175 server and ask Pyramid to help you generate URLs to those files, so you can
176 use Pyramid's internal fileserving while doing development, and a faster
177 static file server in production without changing any code.
178
179 Example: :ref:`static_assets_section`.
180
181 Debug Toolbar
182 ~~~~~~~~~~~~~
183
184 Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to
185 render a project. This toolbar overlays your application in the browser, and
186 allows you access to framework data such as the routes configured, the last
187 renderings performed, the current set of packages installed, SQLAlchemy
188 queries run, logging data, and various other facts. When an exception
189 occurs, you can use its interactive debugger to poke around right in your
190 browser to try to determine the cause of the exception. It's handy.
191
192 Example: :ref:`debug_toolbar`.
193
194 Debugging settings
195 ~~~~~~~~~~~~~~~~~~
196
197 Pyramid has debugging settings that allow you to print Pyramid runtime
198 information to the console when things aren't behaving as you're expecting.
199 For example, you can turn on "debug_notfound", which prints an informative
200 message to the console every time a URL does not match any view. You can
201 turn on "debug_authorization", which lets you know why a view execution was
202 allowed or denied by printing a message to the console. These features are
203 useful for those WTF moments.
204
cfb2b55 @mcdonc remove all reference to the paster command-line utility
mcdonc authored Oct 6, 2011
205 There are also a number of commands that you can invoke within a Pyramid
206 environment that allow you to introspect the configuration of your system:
207 ``proutes`` shows all configured routes for an application in the order
208 they'll be evaluated for matching; ``pviews`` shows all configured views for
209 any given URL. These are also WTF-crushers in some circumstances.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
210
ab7b244 @mcdonc wording/typo fixes
mcdonc authored Sep 8, 2011
211 Examples: :ref:`debug_authorization_section` and :ref:`command_line_chapter`.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
212
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
213 Add-ons
214 ~~~~~~~~
215
216 Pyramid has an extensive set of add-ons held to the same quality standards as
217 the Pyramid core itself. Add-ons are packages which provide functionality
218 that the Pyramid core doesn't. Add-on packages already exist which let you
219 easily send email, let you use the Jinja2 templating system, let you use
220 XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc.
221
0814c20 @mcdonc use right link for add-on documentation
mcdonc authored Aug 2, 2013
222 Examples: http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
223
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
224 Class-based and function-based views
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
225 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
226
5b0496e @mmerickel garden
mmerickel authored Sep 8, 2011
227 Pyramid has a structured, unified concept of a :term:`view callable`.
bdebfb8 @mcdonc wording
mcdonc authored Sep 7, 2011
228 View callables can be functions, methods of classes, or even instances. When
229 you add a new view callable, you can choose to make it a function or a method
230 of a class; in either case, Pyramid treats it largely the same way. You can
231 change your mind later, and move code between methods of classes and
232 functions. A collection of similar view callables can be attached to a
233 single class as methods, if that floats your boat, and they can share
234 initialization code as necessary. All kinds of views are easy to understand
235 and use and operate similarly. There is no phony distinction between them;
236 they can be used for the same purposes.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
237
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
238 Here's a view callable defined as a function:
239
240 .. code-block:: python
241 :linenos:
242
243 from pyramid.response import Response
244 from pyramid.view import view_config
245
246 @view_config(route_name='aview')
247 def aview(request):
248 return Response('one')
249
250 Here's a few views defined as methods of a class instead:
251
252 .. code-block:: python
253 :linenos:
254
255 from pyramid.response import Response
256 from pyramid.view import view_config
257
258 class AView(object):
259 def __init__(self, request):
260 self.request = request
261
262 @view_config(route_name='view_one')
e73a549 @mcdonc only self
mcdonc authored Mar 11, 2012
263 def view_one(self):
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
264 return Response('one')
265
266 @view_config(route_name='view_two')
e73a549 @mcdonc only self
mcdonc authored Mar 12, 2012
267 def view_two(self):
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
268 return Response('two')
269
270 See also :ref:`view_config_placement`.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
271
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
272 .. _intro_asset_specs:
273
274 Asset specifications
275 ~~~~~~~~~~~~~~~~~~~~
276
277 Asset specifications are strings that contain both a Python package name and
278 a file or directory name, e.g. ``MyPackage:static/index.html``. Use of these
279 specifications is omnipresent in Pyramid. An asset specification can refer
280 to a template, a translation directory, or any other package-bound static
281 resource. This makes a system built on Pyramid extensible, because you don't
282 have to rely on globals ("*the* static directory") or lookup schemes ("*the*
283 ordered set of template directories") to address your files. You can move
284 files around as necessary, and include other packages that may not share your
285 system's templates or static files without encountering conflicts.
286
287 Because asset specifications are used heavily in Pyramid, we've also provided
288 a way to allow users to override assets. Say you love a system that someone
289 else has created with Pyramid but you just need to change "that one template"
290 to make it all better. No need to fork the application. Just override the
291 asset specification for that template with your own inside a wrapper, and
292 you're good to go.
293
294 Examples: :ref:`asset_specifications` and :ref:`overriding_assets_section`.
295
296 Extensible templating
297 ~~~~~~~~~~~~~~~~~~~~~
298
299 Pyramid has a structured API that allows for pluggability of "renderers".
300 Templating systems such as Mako, Genshi, Chameleon, and Jinja2 can be treated
301 as renderers. Renderer bindings for all of these templating systems already
302 exist for use in Pyramid. But if you'd rather use another, it's not a big
303 deal. Just copy the code from an existing renderer package, and plug in your
304 favorite templating system. You'll then be able to use that templating
305 system from within Pyramid just as you'd use one of the "built-in" templating
306 systems.
307
308 Pyramid does not make you use a single templating system exclusively. You
309 can use multiple templating systems, even in the same project.
310
311 Example: :ref:`templates_used_directly`.
312
85ac6b0 @mcdonc add code examples
mcdonc authored Sep 7, 2011
313 Rendered views can return dictionaries
314 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
e088447 @mcdonc add renderer section; fix wording (thanks jpenny)
mcdonc authored Sep 7, 2011
315
316 If you use a :term:`renderer`, you don't have to return a special kind of
317 "webby" ``Response`` object from a view. Instead, you can return a
5f0e510 @cguardia Remove duplicate word
cguardia authored Sep 28, 2012
318 dictionary, and Pyramid will take care of converting that dictionary
bdebfb8 @mcdonc wording
mcdonc authored Sep 7, 2011
319 to a Response using a template on your behalf. This makes the view easier to
320 test, because you don't have to parse HTML in your tests; just make an
e088447 @mcdonc add renderer section; fix wording (thanks jpenny)
mcdonc authored Sep 7, 2011
321 assertion instead that the view returns "the right stuff" in the dictionary
bdebfb8 @mcdonc wording
mcdonc authored Sep 7, 2011
322 it returns. You can write "real" unit tests instead of functionally testing
323 all of your views.
e088447 @mcdonc add renderer section; fix wording (thanks jpenny)
mcdonc authored Sep 7, 2011
324
85ac6b0 @mcdonc add code examples
mcdonc authored Sep 7, 2011
325 For example, instead of:
326
327 .. code-block:: python
328 :linenos:
329
330 from pyramid.renderers import render_to_response
331
332 def myview(request):
333 return render_to_response('myapp:templates/mytemplate.pt', {'a':1},
334 request=request)
335
336 You can do this:
337
338 .. code-block:: python
339 :linenos:
340
341 from pyramid.view import view_config
342
343 @view_config(renderer='myapp:templates/mytemplate.pt')
344 def myview(request):
345 return {'a':1}
346
d10aeb2 @mcdonc feedback from david cramer
mcdonc authored Sep 9, 2011
347 When this view callable is called by Pyramid, the ``{'a':1}`` dictionary will
348 be rendered to a response on your behalf. The string passed as ``renderer=``
349 above is an :term:`asset specification`. It is in the form
c946fc7 @ppaez Typos
ppaez authored Mar 13, 2012
350 ``packagename:directoryname/filename.ext``. In this case, it refers to the
d10aeb2 @mcdonc feedback from david cramer
mcdonc authored Sep 9, 2011
351 ``mytemplate.pt`` file in the ``templates`` directory within the ``myapp``
352 Python package. Asset specifications are omnipresent in Pyramid: see
353 :ref:`intro_asset_specs` for more information.
354
e088447 @mcdonc add renderer section; fix wording (thanks jpenny)
mcdonc authored Sep 7, 2011
355 Example: :ref:`renderers_chapter`.
356
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
357 Event system
358 ~~~~~~~~~~~~
359
360 Pyramid emits *events* during its request processing lifecycle. You can
361 subscribe any number of listeners to these events. For example, to be
362 notified of a new request, you can subscribe to the ``NewRequest`` event. To
363 be notified that a template is about to be rendered, you can subscribe to the
364 ``BeforeRender`` event, and so forth. Using an event publishing system as a
365 framework notification feature instead of hardcoded hook points tends to make
366 systems based on that framework less brittle.
367
368 You can also use Pyramid's event system to send your *own* events. For
369 example, if you'd like to create a system that is itself a framework, and may
370 want to notify subscribers that a document has just been indexed, you can
371 create your own event type (``DocumentIndexed`` perhaps) and send the event
372 via Pyramid. Users of this framework can then subscribe to your event like
373 they'd subscribe to the events that are normally sent by Pyramid itself.
374
375 Example: :ref:`events_chapter` and :ref:`event_types`.
376
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
377 Built-in internationalization
378 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
379
0e5e1bc @stevepiercy "internalization-related" s/b "internationalization-related"
stevepiercy authored Sep 9, 2011
380 Pyramid ships with internationalization-related features in its core:
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
381 localization, pluralization, and creating message catalogs from source files
382 and templates. Pyramid allows for a plurality of message catalog via the use
383 of translation domains: you can create a system that has its own translations
384 without conflict with other translations in other domains.
385
386 Example: :ref:`i18n_chapter`.
387
388 HTTP caching
389 ~~~~~~~~~~~~
390
391 Pyramid provides an easy way to associate views with HTTP caching policies.
392 You can just tell Pyramid to configure your view with an ``http_cache``
393 statement, and it will take care of the rest::
394
395 @view_config(http_cache=3600) # 60 minutes
396 def myview(request): ....
397
398 Pyramid will add appropriate ``Cache-Control`` and ``Expires`` headers to
399 responses generated when this view is invoked.
400
401 See the :meth:`~pyramid.config.Configurator.add_view` method's
402 ``http_cache`` documentation for more information.
403
404 Sessions
405 ~~~~~~~~
406
407 Pyramid has built-in HTTP sessioning. This allows you to associate data with
408 otherwise anonymous users between requests. Lots of systems do this. But
409 Pyramid also allows you to plug in your own sessioning system by creating
410 some code that adheres to a documented interface. Currently there is a
411 binding package for the third-party Beaker sessioning system that does exactly
412 this. But if you have a specialized need (perhaps you want to store your
413 session data in MongoDB), you can. You can even switch between
414 implementations without changing your application code.
415
416 Example: :ref:`sessions_chapter`.
417
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
418 Speed
419 ~~~~~
420
421 The Pyramid core is, as far as we can tell, at least marginally faster than
422 any other existing Python web framework. It has been engineered from the
423 ground up for speed. It only does as much work as absolutely necessary when
424 you ask it to get a job done. Extraneous function calls and suboptimal
425 algorithms in its core codepaths are avoided. It is feasible to get, for
426 example, between 3500 and 4000 requests per second from a simple Pyramid view
427 on commodity dual-core laptop hardware and an appropriate WSGI server
41cb3af @mcdonc typo
mcdonc authored Sep 8, 2011
428 (mod_wsgi or gunicorn). In any case, performance statistics are largely
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
429 useless without requirements and goals, but if you need speed, Pyramid will
430 almost certainly never be your application's bottleneck; at least no more
431 than Python will be a bottleneck.
432
e95f5cf @stevepiercy fix framework shootout link
stevepiercy authored Jan 29, 2016
433 Example: http://blog.curiasolutions.com/pages/the-great-web-framework-shootout.html
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
434
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
435 Exception views
436 ~~~~~~~~~~~~~~~
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
437
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
438 Exceptions happen. Rather than deal with exceptions that might present
439 themselves to a user in production in an ad-hoc way, Pyramid allows you to
440 register an :term:`exception view`. Exception views are like regular Pyramid
441 views, but they're only invoked when an exception "bubbles up" to Pyramid
442 itself. For example, you might register an exception view for the
443 :exc:`Exception` exception, which will catch *all* exceptions, and present a
444 pretty "well, this is embarrassing" page. Or you might choose to register an
445 exception view for only specific kinds of application-specific exceptions,
446 such as an exception that happens when a file is not found, or an exception
447 that happens when an action cannot be performed because the user doesn't have
448 permission to do something. In the former case, you can show a pretty "Not
449 Found" page; in the latter case you might show a login form.
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
450
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
451 Example: :ref:`exception_views`.
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
452
453 No singletons
454 ~~~~~~~~~~~~~
455
2386bb2 @mcdonc require, not construct
mcdonc authored Sep 8, 2011
456 Pyramid is written in such a way that it requires your application to have
457 exactly zero "singleton" data structures. Or, put another way, Pyramid
5b0496e @mmerickel garden
mmerickel authored Sep 8, 2011
458 doesn't require you to construct any "mutable globals". Or put even a
3970b06 @stevepiercy Removed line break in hyphenation of "import-time" which rendered as …
stevepiercy authored Sep 9, 2011
459 different way, an import of a Pyramid application needn't have any
460 "import-time side effects". This is esoteric-sounding, but if you've ever
461 tried to cope with parameterizing a Django "settings.py" file for multiple
2386bb2 @mcdonc require, not construct
mcdonc authored Sep 8, 2011
462 installations of the same application, or if you've ever needed to
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
463 monkey-patch some framework fixture so that it behaves properly for your use
464 case, or if you've ever wanted to deploy your system using an asynchronous
465 server, you'll end up appreciating this feature. It just won't be a problem.
466 You can even run multiple copies of a similar but not identically configured
467 Pyramid application within the same Python process. This is good for shared
468 hosting environments, where RAM is at a premium.
469
d3aae87 @mcdonc garden
mcdonc authored Sep 9, 2011
470 View predicates and many views per route
970b888 @mcdonc add global response section
mcdonc authored Sep 7, 2011
471 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
472
473 Unlike many other systems, Pyramid allows you to associate more than one view
474 per route. For example, you can create a route with the pattern ``/items``
475 and when the route is matched, you can shuffle off the request to one view if
476 the request method is GET, another view if the request method is POST, etc.
477 A system known as "view predicates" allows for this. Request method matching
478 is the very most basic thing you can do with a view predicate. You can also
479 associate views with other request parameters such as the elements in the
480 query string, the Accept header, whether the request is an XHR request or
481 not, and lots of other things. This feature allows you to keep your
482 individual views "clean"; they won't need much conditional logic, so they'll
483 be easier to test.
484
485 Example: :ref:`view_configuration_parameters`.
486
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
487 Transaction management
488 ~~~~~~~~~~~~~~~~~~~~~~
489
490 Pyramid's :term:`scaffold` system renders projects that include a
1bca77c @mcdonc chronology
mcdonc authored Sep 7, 2011
491 *transaction management* system, stolen from Zope. When you use this
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
492 transaction management system, you cease being responsible for committing
493 your data anymore. Instead, Pyramid takes care of committing: it commits at
494 the end of a request or aborts if there's an exception. Why is that a good
77ef3b0 @mcdonc wording
mcdonc authored Sep 7, 2011
495 thing? Having a centralized place for transaction management is a great
00128a1 @mcdonc wording
mcdonc authored Sep 8, 2011
496 thing. If, instead of managing your transactions in a centralized place, you
5b0496e @mmerickel garden
mmerickel authored Sep 8, 2011
497 sprinkle ``session.commit`` calls in your application logic itself, you can
00128a1 @mcdonc wording
mcdonc authored Sep 8, 2011
498 wind up in a bad place. Wherever you manually commit data to your database,
499 it's likely that some of your other code is going to run *after* your commit.
5b0496e @mmerickel garden
mmerickel authored Sep 8, 2011
500 If that code goes on to do other important things after that commit, and an
00128a1 @mcdonc wording
mcdonc authored Sep 8, 2011
501 error happens in the later code, you can easily wind up with inconsistent
502 data if you're not extremely careful. Some data will have been written to
503 the database that probably should not have. Having a centralized commit
504 point saves you from needing to think about this; it's great for lazy people
505 who also care about data integrity. Either the request completes
157d325 @stevepiercy Correct spelling of "chages" to "changes".
stevepiercy authored Sep 9, 2011
506 successfully, and all changes are committed, or it does not, and all changes
00128a1 @mcdonc wording
mcdonc authored Sep 8, 2011
507 are aborted.
508
509 Also, Pyramid's transaction management system allows you to synchronize
510 commits between multiple databases, and allows you to do things like
511 conditionally send email if a transaction commits, but otherwise keep quiet.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
512
513 Example: :ref:`bfg_sql_wiki_tutorial` (note the lack of commit statements
514 anywhere in application code).
515
516 Configuration conflict detection
517 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
518
5b0496e @mmerickel garden
mmerickel authored Sep 8, 2011
519 When a system is small, it's reasonably easy to keep it all in your head.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
520 But when systems grow large, you may have hundreds or thousands of
521 configuration statements which add a view, add a route, and so forth.
522 Pyramid's configuration system keeps track of your configuration statements,
523 and if you accidentally add two that are identical, or Pyramid can't make
524 sense out of what it would mean to have both statements active at the same
525 time, it will complain loudly at startup time. It's not dumb though: it will
526 automatically resolve conflicting configuration statements on its own if you
77ef3b0 @mcdonc wording
mcdonc authored Sep 7, 2011
527 use the configuration :meth:`~pyramid.config.Configurator.include` system:
528 "more local" statements are preferred over "less local" ones. This allows
529 you to intelligently factor large systems into smaller ones.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
530
531 Example: :ref:`conflict_detection`.
532
533 Configuration extensibility
534 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
535
77ef3b0 @mcdonc wording
mcdonc authored Sep 7, 2011
536 Unlike other systems, Pyramid provides a structured "include" mechanism (see
1d03bbc @ppaez Two grammatical fixes
ppaez authored May 7, 2012
537 :meth:`~pyramid.config.Configurator.include`) that allows you to combine
77ef3b0 @mcdonc wording
mcdonc authored Sep 7, 2011
538 applications from multiple Python packages. All the configuration statements
539 that can be performed in your "main" Pyramid application can also be
00128a1 @mcdonc wording
mcdonc authored Sep 8, 2011
540 performed by included packages including the addition of views, routes,
541 subscribers, and even authentication and authorization policies. You can even
542 extend or override an existing application by including another application's
ab7b244 @mcdonc wording/typo fixes
mcdonc authored Sep 8, 2011
543 configuration in your own, overriding or adding new views and routes to
1d03bbc @ppaez Two grammatical fixes
ppaez authored May 8, 2012
544 it. This has the potential to allow you to create a big application out of
00128a1 @mcdonc wording
mcdonc authored Sep 8, 2011
545 many other smaller ones. For example, if you want to reuse an existing
546 application that already has a bunch of routes, you can just use the
547 ``include`` statement with a ``route_prefix``; the new application will live
548 within your application at a URL prefix. It's not a big deal, and requires
549 little up-front engineering effort.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
550
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
551 For example:
3686674 @mcdonc add add_directive example
mcdonc authored Sep 7, 2011
552
553 .. code-block:: python
554 :linenos:
555
556 from pyramid.config import Configurator
557
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
558 if __name__ == '__main__':
559 config = Configurator()
560 config.include('pyramid_jinja2')
561 config.include('pyramid_exclog')
562 config.include('some.other.guys.package', route_prefix='/someotherguy')
3686674 @mcdonc add add_directive example
mcdonc authored Sep 7, 2011
563
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
564 See also :ref:`including_configuration` and :ref:`building_an_extensible_app`
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
565
566 Flexible authentication and authorization
567 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
568
569 Pyramid includes a flexible, pluggable authentication and authorization
570 system. No matter where your user data is stored, or what scheme you'd like
571 to use to permit your users to access your data, you can use a predefined
572 Pyramid plugpoint to plug in your custom authentication and authorization
573 code. If you want to change these schemes later, you can just change it in
574 one place rather than everywhere in your code. It also ships with prebuilt
575 well-tested authentication and authorization schemes out of the box. But
576 what if you don't want to use Pyramid's built-in system? You don't have to.
577 You can just write your own bespoke security code as you would in any other
578 system.
579
580 Example: :ref:`enabling_authorization_policy`.
581
582 Traversal
583 ~~~~~~~~~
584
585 :term:`Traversal` is a concept stolen from :term:`Zope`. It allows you to
586 create a tree of resources, each of which can be addressed by one or more
587 URLs. Each of those resources can have one or more *views* associated with
77ef3b0 @mcdonc wording
mcdonc authored Sep 7, 2011
588 it. If your data isn't naturally treelike (or you're unwilling to create a
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
589 treelike representation of your data), you aren't going to find traversal
590 very useful. However, traversal is absolutely fantastic for sites that need
591 to be arbitrarily extensible: it's a lot easier to add a node to a tree than
592 it is to shoehorn a route into an ordered list of other routes, or to create
593 another entire instance of an application to service a department and glue
594 code to allow disparate apps to share data. It's a great fit for sites that
acf9ff6 @stevepiercy "CMS systems" is redundant, so spelled out acronym.
stevepiercy authored Sep 9, 2011
595 naturally lend themselves to changing departmental hierarchies, such as
d6a9543 @mcdonc garden
mcdonc authored May 4, 2012
596 content management systems and document management systems. Traversal also
597 lends itself well to systems that require very granular security ("Bob can
598 edit *this* document" as opposed to "Bob can edit documents").
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
599
d6a9543 @mcdonc garden
mcdonc authored May 4, 2012
600 Examples: :ref:`hello_traversal_chapter` and
601 :ref:`much_ado_about_traversal_chapter`.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
602
603 Tweens
604 ~~~~~~
605
606 Pyramid has a sort of internal WSGI-middleware-ish pipeline that can be
607 hooked by arbitrary add-ons named "tweens". The debug toolbar is a "tween",
608 and the ``pyramid_tm`` transaction manager is also. Tweens are more useful
609 than WSGI middleware in some circumstances because they run in the context of
610 Pyramid itself, meaning you have access to templates and other renderers, a
611 "real" request object, and other niceties.
612
613 Example: :ref:`registering_tweens`.
614
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
615 View response adapters
616 ~~~~~~~~~~~~~~~~~~~~~~
617
618 A lot is made of the aesthetics of what *kinds* of objects you're allowed to
619 return from view callables in various frameworks. In a previous section in
620 this document we showed you that, if you use a :term:`renderer`, you can
621 usually return a dictionary from a view callable instead of a full-on
814455d @stevepiercy Insert missing "to".
stevepiercy authored Sep 9, 2011
622 :term:`Response` object. But some frameworks allow you to return strings or
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
623 tuples from view callables. When frameworks allow for this, code looks
624 slightly prettier, because fewer imports need to be done, and there is less
625 code. For example, compare this:
626
627 .. code-block:: python
628 :linenos:
629
630 def aview(request):
631 return "Hello world!"
632
633 To this:
634
635 .. code-block:: python
636 :linenos:
637
638 from pyramid.response import Response
639
640 def aview(request):
641 return Response("Hello world!")
642
643 The former is "prettier", right?
644
645 Out of the box, if you define the former view callable (the one that simply
646 returns a string) in Pyramid, when it is executed, Pyramid will raise an
647 exception. This is because "explicit is better than implicit", in most
648 cases, and by default, Pyramid wants you to return a :term:`Response` object
649 from a view callable. This is because there's usually a heck of a lot more
650 to a response object than just its body. But if you're the kind of person
651 who values such aesthetics, we have an easy way to allow for this sort of
652 thing:
653
654 .. code-block:: python
655 :linenos:
656
657 from pyramid.config import Configurator
658 from pyramid.response import Response
659
660 def string_response_adapter(s):
661 response = Response(s)
662 response.content_type = 'text/html'
663 return response
664
665 if __name__ == '__main__':
666 config = Configurator()
667 config.add_response_adapter(string_response_adapter, basestring)
668
669 Do that once in your Pyramid application at startup. Now you can return
670 strings from any of your view callables, e.g.:
671
672 .. code-block:: python
673 :linenos:
674
675 def helloview(request):
676 return "Hello world!"
677
678 def goodbyeview(request):
679 return "Goodbye world!"
680
681 Oh noes! What if you want to indicate a custom content type? And a custom
682 status code? No fear:
683
684 .. code-block:: python
685 :linenos:
686
687 from pyramid.config import Configurator
688
689 def tuple_response_adapter(val):
690 status_int, content_type, body = val
691 response = Response(body)
692 response.content_type = content_type
693 response.status_int = status_int
694 return response
695
696 def string_response_adapter(body):
697 response = Response(body)
698 response.content_type = 'text/html'
699 response.status_int = 200
700 return response
701
702 if __name__ == '__main__':
703 config = Configurator()
704 config.add_response_adapter(string_response_adapter, basestring)
705 config.add_response_adapter(tuple_response_adapter, tuple)
706
707 Once this is done, both of these view callables will work:
708
709 .. code-block:: python
710 :linenos:
711
712 def aview(request):
713 return "Hello world!"
714
715 def anotherview(request):
716 return (403, 'text/plain', "Forbidden")
717
718 Pyramid defaults to explicit behavior, because it's the most generally
7047d24 @stevepiercy Corrected verb to agree with singular subject "Pyramid".
stevepiercy authored Sep 9, 2011
719 useful, but provides hooks that allow you to adapt the framework to localized
82dcba5 @mcdonc reorder
mcdonc authored Sep 9, 2011
720 aesthetic desires.
721
722 See also :ref:`using_iresponse`.
723
724 "Global" response object
725 ~~~~~~~~~~~~~~~~~~~~~~~~
726
727 "Constructing these response objects in my view callables is such a chore!
728 And I'm way too lazy to register a response adapter, as per the prior
729 section," you say. Fine. Be that way:
730
731 .. code-block:: python
732 :linenos:
733
734 def aview(request):
735 response = request.response
736 response.body = 'Hello world!'
737 response.content_type = 'text/plain'
738 return response
739
740 See also :ref:`request_response_attr`.
741
214125f @mcdonc garden
mcdonc authored Sep 9, 2011
742 Automating repetitive configuration
743 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
744
745 Does Pyramid's configurator allow you to do something, but you're a little
746 adventurous and just want it a little less verbose? Or you'd like to offer
747 up some handy configuration feature to other Pyramid users without requiring
748 that we change Pyramid? You can extend Pyramid's :term:`Configurator` with
749 your own directives. For example, let's say you find yourself calling
750 :meth:`pyramid.config.Configurator.add_view` repetitively. Usually you can
751 take the boring away by using existing shortcuts, but let's say that this is
752 a case such a way that no existing shortcut works to take the boring away:
753
754 .. code-block:: python
755 :linenos:
756
757 from pyramid.config import Configurator
758
759 config = Configurator()
760 config.add_route('xhr_route', '/xhr/{id}')
761 config.add_view('my.package.GET_view', route_name='xhr_route',
762 xhr=True, permission='view', request_method='GET')
763 config.add_view('my.package.POST_view', route_name='xhr_route',
764 xhr=True, permission='view', request_method='POST')
765 config.add_view('my.package.HEAD_view', route_name='xhr_route',
766 xhr=True, permission='view', request_method='HEAD')
767
768 Pretty tedious right? You can add a directive to the Pyramid configurator to
769 automate some of the tedium away:
770
771 .. code-block:: python
772 :linenos:
773
774 from pyramid.config import Configurator
775
776 def add_protected_xhr_views(config, module):
777 module = config.maybe_dotted(module)
778 for method in ('GET', 'POST', 'HEAD'):
779 view = getattr(module, 'xhr_%s_view' % method, None)
780 if view is not None:
781 config.add_view(view, route_name='xhr_route', xhr=True,
782 permission='view', request_method=method)
783
784 config = Configurator()
785 config.add_directive('add_protected_xhr_views', add_protected_xhr_views)
786
787 Once that's done, you can call the directive you've just added as a method of
788 the Configurator object:
789
790 .. code-block:: python
791 :linenos:
792
793 config.add_route('xhr_route', '/xhr/{id}')
794 config.add_protected_xhr_views('my.package')
795
796 Your previously repetitive configuration lines have now morphed into one line.
797
798 You can share your configuration code with others this way too by packaging
799 it up and calling :meth:`~pyramid.config.Configurator.add_directive` from
800 within a function called when another user uses the
801 :meth:`~pyramid.config.Configurator.include` method against your code.
802
803 See also :ref:`add_directive`.
804
5d0989e @mcdonc add introspection to whats unique
mcdonc authored May 4, 2012
805 Programmatic Introspection
3217857 @mcdonc get heading levels right
mcdonc authored Aug 11, 2012
806 ~~~~~~~~~~~~~~~~~~~~~~~~~~
5d0989e @mcdonc add introspection to whats unique
mcdonc authored May 4, 2012
807
808 If you're building a large system that other users may plug code into, it's
809 useful to be able to get an enumeration of what code they plugged in *at
810 application runtime*. For example, you might want to show them a set of tabs
811 at the top of the screen based on an enumeration of views they registered.
812
813 This is possible using Pyramid's :term:`introspector`.
814
815 Here's an example of using Pyramid's introspector from within a view
816 callable:
817
818 .. code-block:: python
819 :linenos:
820
821 from pyramid.view import view_config
822 from pyramid.response import Response
823
824 @view_config(route_name='bar')
825 def show_current_route_pattern(request):
826 introspector = request.registry.introspector
827 route_name = request.matched_route.name
828 route_intr = introspector.get('routes', route_name)
829 return Response(str(route_intr['pattern']))
830
831 See also :ref:`using_introspection`.
832
1252ab7 @mcdonc add python 3 as a uniqueness
mcdonc authored May 4, 2012
833 Python 3 Compatibility
3217857 @mcdonc get heading levels right
mcdonc authored Aug 11, 2012
834 ~~~~~~~~~~~~~~~~~~~~~~
1252ab7 @mcdonc add python 3 as a uniqueness
mcdonc authored May 5, 2012
835
836 Pyramid and most of its add-ons are Python 3 compatible. If you develop a
837 Pyramid application today, you won't need to worry that five years from now
838 you'll be backwatered because there are language features you'd like to use
839 but your framework doesn't support newer Python versions.
840
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
841 Testing
842 ~~~~~~~
843
844 Every release of Pyramid has 100% statement coverage via unit and integration
845 tests, as measured by the ``coverage`` tool available on PyPI. It also has
846 greater than 95% decision/condition coverage as measured by the
847 ``instrumental`` tool available on PyPI. It is automatically tested by the
56f1d2e @mcdonc de-jythonify
mcdonc authored Nov 21, 2011
848 Jenkins tool on Python 2.6, Python 2.7, Python 3.2 and PyPy after each commit
849 to its GitHub repository. Official Pyramid add-ons are held to a similar
850 testing standard. We still find bugs in Pyramid and its official add-ons,
851 but we've noticed we find a lot more of them while working on other projects
852 that don't have a good testing regime.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
853
854 Example: http://jenkins.pylonsproject.org/
855
856 Support
857 ~~~~~~~
858
859 It's our goal that no Pyramid question go unanswered. Whether you ask a
860 question on IRC, on the Pylons-discuss maillist, or on StackOverflow, you're
bdebfb8 @mcdonc wording
mcdonc authored Sep 7, 2011
861 likely to get a reasonably prompt response. We don't tolerate "support
862 trolls" or other people who seem to get their rocks off by berating fellow
863 users in our various offical support channels. We try to keep it well-lit
864 and new-user-friendly.
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
865
c8b363e avoid warning for latexindex, foreword by putting them in a hidden toc
michr authored Sep 29, 2011
866 Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
867 irc.freenode.net in an IRC client) or the pylons-discuss maillist at
868 http://groups.google.com/group/pylons-discuss/ .
869
870 Documentation
871 ~~~~~~~~~~~~~
872
873 It's a constant struggle, but we try to maintain a balance between
874 completeness and new-user-friendliness in the official narrative Pyramid
875 documentation (concrete suggestions for improvement are always appreciated,
876 by the way). We also maintain a "cookbook" of recipes, which are usually
877 demonstrations of common integration scenarios, too specific to add to the
878 official narrative docs. In any case, the Pyramid documentation is
879 comprehensive.
880
77ef3b0 @mcdonc wording
mcdonc authored Sep 7, 2011
881 Example: The rest of this documentation and the cookbook at
f75a3f0 @cd34 https://docs.pylonsproject.org to http://docs.pylonsproject.org as re…
cd34 authored Dec 1, 2011
882 http://docs.pylonsproject.org/projects/pyramid_cookbook/dev/ .
bb93cbd @mcdonc add squishy whats-unique section to introduction
mcdonc authored Sep 7, 2011
883
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored Dec 27, 2009
884 .. index::
6ce1e0c @mcdonc add more index markers
mcdonc authored Jul 20, 2011
885 single: Pylons Project
3ea7c72 Commit from paper.
Chris McDonough authored Jan 14, 2010
886
a3a27a3 @mcdonc fix pylons project urls, change some wording
mcdonc authored Nov 5, 2010
887 What Is The Pylons Project?
888 ---------------------------
3ea7c72 Commit from paper.
Chris McDonough authored Jan 14, 2010
889
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
890 :app:`Pyramid` is a member of the collection of software published under the
c06d4ac remove errant colon
Casey Duncan authored Nov 14, 2010
891 Pylons Project. Pylons software is written by a loose-knit community of
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
892 contributors. The `Pylons Project website <http://pylonsproject.org>`_
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
893 includes details about how :app:`Pyramid` relates to the Pylons Project.
0936284 @mcdonc comment out inappropriate sections, add contributors
mcdonc authored Nov 4, 2010
894
3ea7c72 Commit from paper.
Chris McDonough authored Jan 14, 2010
895 .. index::
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored Oct 25, 2010
896 single: pyramid and other frameworks
e0887ee De-stiltify.
Chris McDonough authored Dec 31, 2009
897 single: Zope
898 single: Pylons
899 single: Django
900 single: MVC
8c56ae4 - Added manual index entries to generated index.
Chris McDonough authored Dec 27, 2009
901
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
902 :app:`Pyramid` and Other Web Frameworks
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
903 ------------------------------------------
9e3bdbc Rearrange into narrative and API sections; include README in narrativ…
Chris McDonough authored Jul 16, 2008
904
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
905 The first release of Pyramid's predecessor (named :mod:`repoze.bfg`) was made
906 in July of 2008. At the end of 2010, we changed the name of
907 :mod:`repoze.bfg` to :app:`Pyramid`. It was merged into the Pylons project
908 as :app:`Pyramid` in November of that year.
fec0f06 @mcdonc convert narrative docs to Pyramid
mcdonc authored Oct 25, 2010
909
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
910 :app:`Pyramid` was inspired by :term:`Zope`, :term:`Pylons` (version
911 1.0) and :term:`Django`. As a result, :app:`Pyramid` borrows several
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
912 concepts and features from each, combining them into a unique web
913 framework.
914
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
915 Many features of :app:`Pyramid` trace their origins back to :term:`Zope`.
916 Like Zope applications, :app:`Pyramid` applications can be easily extended:
917 if you obey certain constraints, the application you produce can be reused,
918 modified, re-integrated, or extended by third-party developers without
919 forking the original application. The concepts of :term:`traversal` and
920 declarative security in :app:`Pyramid` were pioneered first in Zope.
6012899 Rendering tweaks.
Chris McDonough authored Nov 22, 2009
921
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
922 The :app:`Pyramid` concept of :term:`URL dispatch` is inspired by the
7c697c5 @mcdonc better descriptions
mcdonc authored Oct 25, 2010
923 :term:`Routes` system used by :term:`Pylons` version 1.0. Like Pylons
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
924 version 1.0, :app:`Pyramid` is mostly policy-free. It makes no
7c697c5 @mcdonc better descriptions
mcdonc authored Oct 26, 2010
925 assertions about which database you should use, and its built-in
926 templating facilities are included only for convenience. In essence,
927 it only supplies a mechanism to map URLs to :term:`view` code, along
928 with a set of conventions for calling those views. You are free to
929 use third-party components that fit your needs in your applications.
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
930
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored Dec 18, 2010
931 The concept of :term:`view` is used by :app:`Pyramid` mostly as it would be
932 by Django. :app:`Pyramid` has a documentation culture more like Django's
933 than like Zope's.
52ced09 Fix.
Chris McDonough authored Nov 29, 2009
934
7a505db @mcdonc simplify
mcdonc authored Jul 12, 2011
935 Like :term:`Pylons` version 1.0, but unlike :term:`Zope`, a :app:`Pyramid`
936 application developer may use completely imperative code to perform common
937 framework configuration tasks such as adding a view or a route. In Zope,
938 :term:`ZCML` is typically required for similar purposes. In :term:`Grok`, a
939 Zope-based web framework, :term:`decorator` objects and class-level
55ce9d6 @mcdonc clean up inappropriate discussions of ZCML
mcdonc authored Aug 28, 2011
940 declarations are used for this purpose. Out of the box, Pyramid supports
941 imperative and decorator-based configuration; :term:`ZCML` may be used via an
942 add-on package named ``pyramid_zcml``.
c0c1885 Bring up to date.
Chris McDonough authored Jan 17, 2009
943
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
944 Also unlike :term:`Zope` and unlike other "full-stack" frameworks such
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
945 as :term:`Django`, :app:`Pyramid` makes no assumptions about which
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
946 persistence mechanisms you should use to build an application. Zope
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
947 applications are typically reliant on :term:`ZODB`; :app:`Pyramid`
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
948 allows you to build :term:`ZODB` applications, but it has no reliance
223d4c0 More pass overhaul based on making contextfinding explicit within doc…
Chris McDonough authored Jan 17, 2010
949 on the ZODB software. Likewise, :term:`Django` tends to assume that
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
950 you want to store your application's data in a relational database.
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
951 :app:`Pyramid` makes no such assumption; it allows you to use a
9ec2d64 Merge of andrew-docs branch.
Chris McDonough authored Jan 11, 2010
952 relational database but doesn't encourage or discourage the decision.
49127a2 More.
Chris McDonough authored Jan 17, 2009
953
c5f24b2 Prep for b1
Chris McDonough authored Jan 18, 2010
954 Other Python web frameworks advertise themselves as members of a class
955 of web frameworks named `model-view-controller
956 <http://en.wikipedia.org/wiki/Model–view–controller>`_ frameworks.
957 Insofar as this term has been claimed to represent a class of web
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
958 frameworks, :app:`Pyramid` also generally fits into this class.
c5f24b2 Prep for b1
Chris McDonough authored Jan 18, 2010
959
fd5ae92 @mcdonc - All references to Pyramid-the-application were changed from :mod:`p…
mcdonc authored Nov 9, 2010
960 .. sidebar:: You Say :app:`Pyramid` is MVC, But Where's The Controller?
c5f24b2 Prep for b1
Chris McDonough authored Jan 18, 2010
961
fb6a5ce @mcdonc model -> resource; resource -> asset
mcdonc authored Dec 18, 2010
962 The :app:`Pyramid` authors believe that the MVC pattern just doesn't
963 really fit the web very well. In a :app:`Pyramid` application, there is a
a5ffd62 @mcdonc model->resource; make docs render without warnings
mcdonc authored Dec 18, 2010
964 resource tree, which represents the site structure, and views, which tend
965 to present the data stored in the resource tree and a user-defined "domain
966 model". However, no facility provided *by the framework* actually
967 necessarily maps to the concept of a "controller" or "model". So if you
968 had to give it some acronym, I guess you'd say :app:`Pyramid` is actually
969 an "RV" framework rather than an "MVC" framework. "MVC", however, is
970 close enough as a general classification moniker for purposes of
971 comparison with other web frameworks.
Something went wrong with that request. Please try again.