diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/introduction.rst | 240 |
1 files changed, 132 insertions, 108 deletions
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index a620e9505..df1f3f954 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -260,26 +260,6 @@ You can do this: Example: :ref:`renderers_chapter`. -Event system -~~~~~~~~~~~~ - -Pyramid emits *events* during its request processing lifecycle. You can -subscribe any number of listeners to these events. For example, to be -notified of a new request, you can subscribe to the ``NewRequest`` event. To -be notified that a template is about to be rendered, you can subscribe to the -``BeforeRender`` event, and so forth. Using an event publishing system as a -framework notification feature instead of hardcoded hook points tends to make -systems based on that framework less brittle. - -You can also use Pyramid's event system to send your *own* events. For -example, if you'd like to create a system that is itself a framework, and may -want to notify subscribers that a document has just been indexed, you can -create your own event type (``DocumentIndexed`` perhaps) and send the event -via Pyramid. Users of this framework can then subscribe to your event like -they'd subscribe to the events that are normally sent by Pyramid itself. - -Example: :ref:`events_chapter` and :ref:`event_types`. - Extensible templating ~~~~~~~~~~~~~~~~~~~~~ @@ -292,98 +272,22 @@ favorite templating system. You'll then be able to use that templating system from within Pyramid just as you'd use one of the "built-in" templating systems. -Example: :ref:`templates_used_directly`. - -Speed -~~~~~ - -The Pyramid core is, as far as we can tell, at least marginally faster than -any other existing Python web framework. It has been engineered from the -ground up for speed. It only does as much work as absolutely necessary when -you ask it to get a job done. Extraneous function calls and suboptimal -algorithms in its core codepaths are avoided. It is feasible to get, for -example, between 3500 and 4000 requests per second from a simple Pyramid view -on commodity dual-core laptop hardware and an appropriate WSGI server -(mod_wsgi or gunicorn). In any case, performance statstics are largely -useless without requirements and goals, but if you need speed, Pyramid will -almost certainly never be your application's bottleneck; at least no more -than Python will be a bottleneck. - -Example: http://blog.curiasolutions.com/the-great-web-framework-shootout/ - -Sessions -~~~~~~~~ - -Pyramid has built-in HTTP sessioning. This allows you to associate data with -otherwise anonymous users between requests. Lots of systems do this. But -Pyramid also allows you to plug in your own sessioning system by creating -some code that adheres to a documented interface. Currently there is a -binding package for the third-part Beaker sessioning system that does exactly -this. But if you have a specialized need (perhaps you want to store your -session data in MongoDB), you can. You can even switch between -implementations without changing your application code. - -Example: :ref:`sessions_chapter`. - -No singletons -~~~~~~~~~~~~~ - -Pyramid is written in such a way that it has exactly zero "singleton" data -structures. Or, put another way, Pyramid constructs no "mutable globals". -Or put even a different way, an import of a Pyramid application needn't have -any "import time side effects". This is esoteric-sounding, but if you've -ever tried to cope with parameterizing a Django "settings.py" file for -multiple installations of the same application, or if you've ever needed to -monkey-patch some framework fixture so that it behaves properly for your use -case, or if you've ever wanted to deploy your system using an asynchronous -server, you'll end up appreciating this feature. It just won't be a problem. -You can even run multiple copies of a similar but not identically configured -Pyramid application within the same Python process. This is good for shared -hosting environments, where RAM is at a premium. - -View Predicates and Many Views Per Route -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Unlike many other systems, Pyramid allows you to associate more than one view -per route. For example, you can create a route with the pattern ``/items`` -and when the route is matched, you can shuffle off the request to one view if -the request method is GET, another view if the request method is POST, etc. -A system known as "view predicates" allows for this. Request method matching -is the very most basic thing you can do with a view predicate. You can also -associate views with other request parameters such as the elements in the -query string, the Accept header, whether the request is an XHR request or -not, and lots of other things. This feature allows you to keep your -individual views "clean"; they won't need much conditional logic, so they'll -be easier to test. - -Example: :ref:`view_configuration_parameters`. - -Exception views -~~~~~~~~~~~~~~~ +Pyramid does not make you use a single templating system exclusively. You +can use multiple templating systems, even in the same project. -Exceptions happen. Rather than deal with exceptions that might present -themselves to a user in production in an ad-hoc way, Pyramid allows you to -register an :term:`exception view`. Exception views are like regular Pyramid -views, but they're only invoked when an exception "bubbles up" to Pyramid -itself. For example, you might register an exception view for the -:exc:`Exception` exception, which will catch *all* exceptions, and present a -pretty "well, this is embarrassing" page. Or you might choose to register an -exception view for only specific kinds of application-specific exceptions, -such as an exception that happens when a file is not found, or an exception -that happens when action cannot be performed because the user doesn't have -permission to do something. In the former case, you can show a pretty "Not -Found" page; in the latter case you might show a login form. - -Example: :ref:`exception_views`. +Example: :ref:`templates_used_directly`. View Response Adapters ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ -A lot is made of the aesthetics of what *kind* of objects you're allowed to -return from view callables in various frameworks. Some frameworks allow -you return strings or tuples from view callables, and they make much of it. -When frameworks allow for this, code looks slightly prettier, because fewer -imports need to be done, and there is less code. For example, compare this: +A lot is made of the aesthetics of what *kinds* of objects you're allowed to +return from view callables in various frameworks. In a previous section in +this document we showed you that, if you use a :term:`renderer`, you can +usually return a dictionary from a view callable instead of a full-on +:term:`Response` object. But some frameworks allow you return strings or +tuples from view callables, and they make much of it. When frameworks allow +for this, code looks slightly prettier, because fewer imports need to be +done, and there is less code. For example, compare this: .. code-block:: python :linenos: @@ -482,6 +386,126 @@ aesthetic desires. See also :ref:`using_iresponse`. +"Global" Response Object +~~~~~~~~~~~~~~~~~~~~~~~~ + +"Constructing these response objects in my view callables is such a chore! +And I'm way too lazy to register a response adapter, as per the prior +section," you say. Fine. Be that way: + +.. code-block:: python + :linenos: + + def aview(request): + response = request.response + response.body = 'Hello world!' + response.content_type = 'text/plain' + return response + +See also :ref:`request_response_attr`. + +Event system +~~~~~~~~~~~~ + +Pyramid emits *events* during its request processing lifecycle. You can +subscribe any number of listeners to these events. For example, to be +notified of a new request, you can subscribe to the ``NewRequest`` event. To +be notified that a template is about to be rendered, you can subscribe to the +``BeforeRender`` event, and so forth. Using an event publishing system as a +framework notification feature instead of hardcoded hook points tends to make +systems based on that framework less brittle. + +You can also use Pyramid's event system to send your *own* events. For +example, if you'd like to create a system that is itself a framework, and may +want to notify subscribers that a document has just been indexed, you can +create your own event type (``DocumentIndexed`` perhaps) and send the event +via Pyramid. Users of this framework can then subscribe to your event like +they'd subscribe to the events that are normally sent by Pyramid itself. + +Example: :ref:`events_chapter` and :ref:`event_types`. + +Speed +~~~~~ + +The Pyramid core is, as far as we can tell, at least marginally faster than +any other existing Python web framework. It has been engineered from the +ground up for speed. It only does as much work as absolutely necessary when +you ask it to get a job done. Extraneous function calls and suboptimal +algorithms in its core codepaths are avoided. It is feasible to get, for +example, between 3500 and 4000 requests per second from a simple Pyramid view +on commodity dual-core laptop hardware and an appropriate WSGI server +(mod_wsgi or gunicorn). In any case, performance statstics are largely +useless without requirements and goals, but if you need speed, Pyramid will +almost certainly never be your application's bottleneck; at least no more +than Python will be a bottleneck. + +Example: http://blog.curiasolutions.com/the-great-web-framework-shootout/ + +Sessions +~~~~~~~~ + +Pyramid has built-in HTTP sessioning. This allows you to associate data with +otherwise anonymous users between requests. Lots of systems do this. But +Pyramid also allows you to plug in your own sessioning system by creating +some code that adheres to a documented interface. Currently there is a +binding package for the third-part Beaker sessioning system that does exactly +this. But if you have a specialized need (perhaps you want to store your +session data in MongoDB), you can. You can even switch between +implementations without changing your application code. + +Example: :ref:`sessions_chapter`. + +No singletons +~~~~~~~~~~~~~ + +Pyramid is written in such a way that it has exactly zero "singleton" data +structures. Or, put another way, Pyramid constructs no "mutable globals". +Or put even a different way, an import of a Pyramid application needn't have +any "import time side effects". This is esoteric-sounding, but if you've +ever tried to cope with parameterizing a Django "settings.py" file for +multiple installations of the same application, or if you've ever needed to +monkey-patch some framework fixture so that it behaves properly for your use +case, or if you've ever wanted to deploy your system using an asynchronous +server, you'll end up appreciating this feature. It just won't be a problem. +You can even run multiple copies of a similar but not identically configured +Pyramid application within the same Python process. This is good for shared +hosting environments, where RAM is at a premium. + +View Predicates and Many Views Per Route +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Unlike many other systems, Pyramid allows you to associate more than one view +per route. For example, you can create a route with the pattern ``/items`` +and when the route is matched, you can shuffle off the request to one view if +the request method is GET, another view if the request method is POST, etc. +A system known as "view predicates" allows for this. Request method matching +is the very most basic thing you can do with a view predicate. You can also +associate views with other request parameters such as the elements in the +query string, the Accept header, whether the request is an XHR request or +not, and lots of other things. This feature allows you to keep your +individual views "clean"; they won't need much conditional logic, so they'll +be easier to test. + +Example: :ref:`view_configuration_parameters`. + +Exception views +~~~~~~~~~~~~~~~ + +Exceptions happen. Rather than deal with exceptions that might present +themselves to a user in production in an ad-hoc way, Pyramid allows you to +register an :term:`exception view`. Exception views are like regular Pyramid +views, but they're only invoked when an exception "bubbles up" to Pyramid +itself. For example, you might register an exception view for the +:exc:`Exception` exception, which will catch *all* exceptions, and present a +pretty "well, this is embarrassing" page. Or you might choose to register an +exception view for only specific kinds of application-specific exceptions, +such as an exception that happens when a file is not found, or an exception +that happens when action cannot be performed because the user doesn't have +permission to do something. In the former case, you can show a pretty "Not +Found" page; in the latter case you might show a login form. + +Example: :ref:`exception_views`. + Asset specifications ~~~~~~~~~~~~~~~~~~~~ |