.travis.yml
@@ -8,8 +8,6 @@ env: TOXENV=py26 - python: 2.7 env: TOXENV=py27 - python: 3.2 env: TOXENV=py32 - python: 3.3 env: TOXENV=py33 - python: 3.4 CHANGES.txt
@@ -1,3 +1,15 @@ unreleased ========== - Dropped Python 3.2 support. See https://github.com/Pylons/pyramid/pull/2256 - Fix ``pserve --browser`` to use the ``--server-name`` instead of the app name when selecting a section to use. This was only working for people who had server and app sections with the same name, for example ``[app:main]`` and ``[server:main]``. See https://github.com/Pylons/pyramid/pull/2292 1.6 (2015-04-14) ================
@@ -258,3 +258,5 @@ - Rami Chousein, 2015/10/28 - Sri Sanketh Uppalapati, 2015/12/12 - Marcin Raczyński, 2016/01/26 RELEASING.txt
@@ -28,11 +28,16 @@ include a link under "Bug Fix Releases" to the minor feature changes in CHANGES.txt . - update README.rst to use correct versions of badges and URLs according to - Update README.rst to use correct versions of badges and URLs according to each branch and context, i.e., RTD "latest" == GitHub/Travis "1.x-branch". - Update whatsnew-X.X.rst in docs to point at change log entries for individual releases if applicable. - For major version releases, in docs/conf.py, update values under html_theme_options for in_progress and outdated across master, releasing branch, and previously released branch. Also in the previously released branch only, uncomment the sections to enable pylons_sphinx_latesturl. - Change setup.py version to the new version number. @@ -51,11 +56,14 @@ $ python setup.py sdist bdist_wheel $ twine upload dist/pyramid-X.X-* - Edit Pylons/pylonshq/templates/home/home.mako for minor and major updates. - Edit Pylons/pylonshq/templates/home/home.mako. - Edit Pylons/pylonshq/templates/home/inside.rst for major updates only. - Edit Pylons/pylonshq/templates/home/inside.rst for major releases only. - Edit Pylons/pylonsrtd/pylonsrtd/docs/pyramid.rst for all updates. - Edit Pylons/trypyramid.com/src/templates/resources.html for major releases only. - Edit Pylons/pylonsrtd/pylonsrtd/docs/pyramid.rst for major releases only. - Edit `http://wiki.python.org/moin/WebFrameworks <http://wiki.python.org/moin/WebFrameworks>`_. docs/conf.py
@@ -55,6 +55,8 @@ 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'sphinxcontrib.programoutput', # enable pylons_sphinx_latesturl when this branch is no longer "latest" # 'pylons_sphinx_latesturl', ] # Looks for objects in external projects @@ -67,7 +69,7 @@ 'python': ('http://docs.python.org', None), 'python3': ('http://docs.python.org/3', None), 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), 'tm': ('http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/', None), 'tm': ('http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/', None), 'toolbar': ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None), 'tstring': ('http://docs.pylonsproject.org/projects/translationstring/en/latest', None), 'tutorials': ('http://docs.pylonsproject.org/projects/pyramid-tutorials/en/latest/', None), @@ -124,12 +126,30 @@ # Options for HTML output # ----------------------- # enable pylons_sphinx_latesturl when this branch is no longer "latest" # pylons_sphinx_latesturl_base = ( # 'http://docs.pylonsproject.org/projects/pyramid/en/latest/') # pylons_sphinx_latesturl_pagename_overrides = { # # map old pagename -> new pagename # 'whatsnew-1.0': 'index', # 'whatsnew-1.1': 'index', # 'whatsnew-1.2': 'index', # 'whatsnew-1.3': 'index', # 'whatsnew-1.4': 'index', # 'whatsnew-1.5': 'index', # 'tutorials/gae/index': 'index', # 'api/chameleon_text': 'api', # 'api/chameleon_zpt': 'api', # } html_theme = 'pyramid' html_theme_path = pylons_sphinx_themes.get_html_themes_path() html_theme_options = dict( github_url='https://github.com/Pylons/pyramid', # on master branch true, else false in_progress='true', # on previous branches/major releases true, else false outdated='false', ) # The name for this set of Sphinx documents. If None, it defaults to docs/designdefense.rst
@@ -175,11 +175,11 @@ +++++++++++++ First, the primary amelioration: :app:`Pyramid` *does not expect application developers to understand ZCA concepts or any of its APIs*. If an *application* developer needs to understand a ZCA concept or API during the creation of a :app:`Pyramid` application, we've failed on some axis. developers to understand ZCA concepts or any of its APIs*. If an *application* developer needs to understand a ZCA concept or API during the creation of a :app:`Pyramid` application, we've failed on some axis. Instead, the framework hides the presence of the ZCA registry behind Instead the framework hides the presence of the ZCA registry behind special-purpose API functions that *do* use ZCA APIs. Take for example the ``pyramid.security.authenticated_userid`` function, which returns the userid present in the current request or ``None`` if no userid is present in the @@ -191,10 +191,9 @@ from pyramid.security import authenticated_userid userid = authenticated_userid(request) He now has the current user id. They now have the current user id. Under its hood however, the implementation of ``authenticated_userid`` is this: Under its hood however, the implementation of ``authenticated_userid`` is this: .. code-block:: python :linenos: @@ -211,58 +210,56 @@ return policy.authenticated_userid(request) Using such wrappers, we strive to always hide the ZCA API from application developers. Application developers should just never know about the ZCA API: they should call a Python function with some object germane to the domain as an argument, and it should return a result. A corollary that follows is that any reader of an application that has been written using :app:`Pyramid` needn't understand the ZCA API either. developers. Application developers should just never know about the ZCA API; they should call a Python function with some object germane to the domain as an argument, and it should return a result. A corollary that follows is that any reader of an application that has been written using :app:`Pyramid` needn't understand the ZCA API either. Hiding the ZCA API from application developers and code readers is a form of enhancing domain specificity. No application developer wants to need to understand the small, detailed mechanics of how a web framework does its thing. People want to deal in concepts that are closer to the domain they're working in: for example, web developers want to know about *users*, not *utilities*. :app:`Pyramid` uses the ZCA as an implementation detail, not as a feature which is exposed to end users. understand the small, detailed mechanics of how a web framework does its thing. People want to deal in concepts that are closer to the domain they're working in. For example, web developers want to know about *users*, not *utilities*. :app:`Pyramid` uses the ZCA as an implementation detail, not as a feature which is exposed to end users. However, unlike application developers, *framework developers*, including people who want to override :app:`Pyramid` functionality via preordained framework plugpoints like traversal or view lookup *must* understand the ZCA framework plugpoints like traversal or view lookup, *must* understand the ZCA registry API. :app:`Pyramid` framework developers were so concerned about conceptual load issues of the ZCA registry API for framework developers that a `replacement registry implementation <https://github.com/repoze/repoze.component>`_ named :mod:`repoze.component` was actually developed. Though this package has a registry implementation which is fully functional and well-tested, and its API is much nicer than the ZCA registry API, work on it was largely abandoned and it is not used in :app:`Pyramid`. We continued to use a ZCA registry within :app:`Pyramid` because it ultimately proved a better fit. issues of the ZCA registry API that a `replacement registry implementation <https://github.com/repoze/repoze.component>`_ named :mod:`repoze.component` was actually developed. Though this package has a registry implementation which is fully functional and well-tested, and its API is much nicer than the ZCA registry API, work on it was largely abandoned, and it is not used in :app:`Pyramid`. We continued to use a ZCA registry within :app:`Pyramid` because it ultimately proved a better fit. .. note:: We continued using ZCA registry rather than disusing it in favor of using the registry implementation in :mod:`repoze.component` largely because the ZCA concept of interfaces provides for use of an interface hierarchy, which is useful in a lot of scenarios (such as context type inheritance). Coming up with a marker type that was something like an interface that allowed for this functionality seemed like it was just reinventing the wheel. We continued using ZCA registry rather than disusing it in favor of using the registry implementation in :mod:`repoze.component` largely because the ZCA concept of interfaces provides for use of an interface hierarchy, which is useful in a lot of scenarios (such as context type inheritance). Coming up with a marker type that was something like an interface that allowed for this functionality seemed like it was just reinventing the wheel. Making framework developers and extenders understand the ZCA registry API is a trade-off. We (the :app:`Pyramid` developers) like the features that the ZCA registry gives us, and we have long-ago borne the weight of understanding what it does and how it works. The authors of :app:`Pyramid` understand the ZCA deeply and can read code that uses it as easily as any other code. Making framework developers and extenders understand the ZCA registry API is a trade-off. We (the :app:`Pyramid` developers) like the features that the ZCA registry gives us, and we have long-ago borne the weight of understanding what it does and how it works. The authors of :app:`Pyramid` understand the ZCA deeply and can read code that uses it as easily as any other code. But we recognize that developers who might want to extend the framework are not as comfortable with the ZCA registry API as the original developers are with it. So, for the purposes of being kind to third-party :app:`Pyramid` framework developers in, we've drawn some lines in the sand. as comfortable with the ZCA registry API as the original developers. So for the purpose of being kind to third-party :app:`Pyramid` framework developers, we've drawn some lines in the sand. In all core code, We've made use of ZCA global API functions such as ``zope.component.getUtility`` and ``zope.component.getAdapter`` the exception In all core code, we've made use of ZCA global API functions, such as ``zope.component.getUtility`` and ``zope.component.getAdapter``, the exception instead of the rule. So instead of: .. code-block:: python @@ -282,9 +279,9 @@ registry = get_current_registry() policy = registry.getUtility(IAuthenticationPolicy) While the latter is more verbose, it also arguably makes it more obvious what's going on. All of the :app:`Pyramid` core code uses this pattern rather than the ZCA global API. While the latter is more verbose, it also arguably makes it more obvious what's going on. All of the :app:`Pyramid` core code uses this pattern rather than the ZCA global API. Rationale +++++++++ @@ -309,13 +306,12 @@ view that is only found when the context is some class of object, or when the context implements some :term:`interface`. - Singularity. There's only one place where "application configuration" lives in a :app:`Pyramid` application: in a component registry. The component registry answers questions made to it by the framework at runtime based on the configuration of *an application*. Note: "an application" is not the same as "a process", multiple independently configured copies of the same :app:`Pyramid` application are capable of running in the same process space. - Singularity. There's only one place where "application configuration" lives in a :app:`Pyramid` application: in a component registry. The component registry answers questions made to it by the framework at runtime based on the configuration of *an application*. Note: "an application" is not the same as "a process"; multiple independently configured copies of the same :app:`Pyramid` application are capable of running in the same process space. - Composability. A ZCA component registry can be populated imperatively, or there's an existing mechanism to populate a registry via the use of a @@ -333,10 +329,9 @@ (non-Zope) frameworks. - Testability. Judicious use of the ZCA registry in framework code makes testing that code slightly easier. Instead of using monkeypatching or other facilities to register mock objects for testing, we inject dependencies via ZCA registrations and then use lookups in the code find our mock objects. testing that code slightly easier. Instead of using monkeypatching or other facilities to register mock objects for testing, we inject dependencies via ZCA registrations, then use lookups in the code to find our mock objects. - Speed. The ZCA registry is very fast for a specific set of complex lookup scenarios that :app:`Pyramid` uses, having been optimized through the years @@ -350,17 +345,17 @@ ++++++++++ If you only *develop applications* using :app:`Pyramid`, there's not much to complain about here. You just should never need to understand the ZCA registry API: use documented :app:`Pyramid` APIs instead. However, you may be an application developer who doesn't read API documentation because it's unmanly. Instead you read the raw source code, and because you haven't read the documentation, you don't know what functions, classes, and methods even *form* the :app:`Pyramid` API. As a result, you've now written code that uses internals and you've painted yourself into a conceptual corner as a result of needing to wrestle with some ZCA-using implementation detail. If this is you, it's extremely hard to have a lot of sympathy for you. You'll either need to get familiar with how we're using the ZCA registry or you'll need to use only the documented APIs; that's why we document them as APIs. complain about here. You just should never need to understand the ZCA registry API; use documented :app:`Pyramid` APIs instead. However, you may be an application developer who doesn't read API documentation. Instead you read the raw source code, and because you haven't read the API documentation, you don't know what functions, classes, and methods even *form* the :app:`Pyramid` API. As a result, you've now written code that uses internals, and you've painted yourself into a conceptual corner, needing to wrestle with some ZCA-using implementation detail. If this is you, it's extremely hard to have a lot of sympathy for you. You'll either need to get familiar with how we're using the ZCA registry or you'll need to use only the documented APIs; that's why we document them as APIs. If you *extend* or *develop* :app:`Pyramid` (create new directives, use some of the more obscure hooks as described in :ref:`hooks_chapter`, or work on @@ -368,6 +363,7 @@ at least some ZCA concepts. In some places it's used unabashedly, and will be forever. We know it's quirky, but it's also useful and fundamentally understandable if you take the time to do some reading about it. .. _zcml_encouragement: @@ -384,15 +380,16 @@ any other sort of frameworky declarative frontend to application configuration. Pyramid Does Traversal, And I Don't Like Traversal Pyramid Does Traversal, and I Don't Like Traversal -------------------------------------------------- In :app:`Pyramid`, :term:`traversal` is the act of resolving a URL path to a :term:`resource` object in a resource tree. Some people are uncomfortable with this notion, and believe it is wrong. Thankfully, if you use :app:`Pyramid`, and you don't want to model your application in terms of a resource tree, you needn't use it at all. Instead, use :term:`URL dispatch` to map URL paths to views. :term:`resource` object in a resource tree. Some people are uncomfortable with this notion, and believe it is wrong. Thankfully if you use :app:`Pyramid` and you don't want to model your application in terms of a resource tree, you needn't use it at all. Instead use :term:`URL dispatch` to map URL paths to views. The idea that some folks believe traversal is unilaterally wrong is understandable. The people who believe it is wrong almost invariably have @@ -427,7 +424,8 @@ But the point is ultimately moot. If you don't want to use traversal, you needn't. Use URL dispatch instead. Pyramid Does URL Dispatch, And I Don't Like URL Dispatch Pyramid Does URL Dispatch, and I Don't Like URL Dispatch -------------------------------------------------------- In :app:`Pyramid`, :term:`url dispatch` is the act of resolving a URL path to @@ -449,41 +447,40 @@ traversal as well. You can actually *combine* URL dispatch and traversal in :app:`Pyramid` (see :ref:`hybrid_chapter`). One example of such a usage: if you want to emulate something like Zope 2's "Zope Management Interface" UI on top of your object graph (or any administrative interface), you can register a route like ``config.add_route('manage', '/manage/*traverse')`` and then associate "management" views in your code by using the ``route_name`` argument to a ``view`` configuration, e.g. ``config.add_view('.some.callable', context=".some.Resource", route_name='manage')``. If you wire things up this way someone then walks up to for example, ``/manage/ob1/ob2``, they might be presented with a management interface, but walking up to ``/ob1/ob2`` would present them with the default object view. There are other tricks you can pull in these hybrid configurations if you're clever (and maybe masochistic) too. top of your object graph (or any administrative interface), you can register a route like ``config.add_route('manage', '/manage/*traverse')`` and then associate "management" views in your code by using the ``route_name`` argument to a ``view`` configuration, e.g., ``config.add_view('.some.callable', context=".some.Resource", route_name='manage')``. If you wire things up this way, someone then walks up to, for example, ``/manage/ob1/ob2``, they might be presented with a management interface, but walking up to ``/ob1/ob2`` would present them with the default object view. There are other tricks you can pull in these hybrid configurations if you're clever (and maybe masochistic) too. Also, if you are a URL dispatch hater, if you should ever be asked to write an application that must use some legacy relational database structure, you might find that using URL dispatch comes in handy for one-off associations between views and URL paths. Sometimes it's just pointless to add a node to the object graph that effectively represents the entry point for some bit of code. You can just use a route and be done with it. If a route matches, a view associated with the route will be called; if no route matches, :app:`Pyramid` falls back to using traversal. Also, if you are a URL dispatch hater, if you should ever be asked to write an application that must use some legacy relational database structure, you might find that using URL dispatch comes in handy for one-off associations between views and URL paths. Sometimes it's just pointless to add a node to the object graph that effectively represents the entry point for some bit of code. You can just use a route and be done with it. If a route matches, a view associated with the route will be called. If no route matches, :app:`Pyramid` falls back to using traversal. But the point is ultimately moot. If you use :app:`Pyramid`, and you really don't want to use URL dispatch, you needn't use it at all. Instead, use :term:`traversal` exclusively to map URL paths to views, just like you do in :term:`Zope`. Pyramid Views Do Not Accept Arbitrary Keyword Arguments ------------------------------------------------------- Many web frameworks (Zope, TurboGears, Pylons 1.X, Django) allow for their variant of a :term:`view callable` to accept arbitrary keyword or positional arguments, which are filled in using values present in the ``request.POST`` or ``request.GET`` dictionaries or by values present in the route match dictionary. For example, a Django view will accept positional arguments which match information in an associated "urlconf" such as ``r'^polls/(?P<poll_id>\d+)/$``: arguments, which are filled in using values present in the ``request.POST``, ``request.GET``, or route match dictionaries. For example, a Django view will accept positional arguments which match information in an associated "urlconf" such as ``r'^polls/(?P<poll_id>\d+)/$``: .. code-block:: python :linenos: @@ -491,8 +488,8 @@ def aview(request, poll_id): return HttpResponse(poll_id) Zope, likewise allows you to add arbitrary keyword and positional arguments to any method of a resource object found via traversal: Zope likewise allows you to add arbitrary keyword and positional arguments to any method of a resource object found via traversal: .. code-block:: python :linenos: @@ -509,13 +506,13 @@ the method is called (if possible) with its argument list filled with values mentioned therein. TurboGears and Pylons 1.X operate similarly. Out of the box, :app:`Pyramid` is configured to have none of these features. By default, :app:`Pyramid` view callables always accept only ``request`` and no other arguments. The rationale: this argument specification matching done aggressively can be costly, and :app:`Pyramid` has performance as one of its main goals, so we've decided to make people, by default, obtain information by interrogating the request object within the view callable body instead of providing magic to do unpacking into the view argument list. Out of the box, :app:`Pyramid` is configured to have none of these features. By default :app:`Pyramid` view callables always accept only ``request`` and no other arguments. The rationale is, this argument specification matching when done aggressively can be costly, and :app:`Pyramid` has performance as one of its main goals. Therefore we've decided to make people, by default, obtain information by interrogating the request object within the view callable body instead of providing magic to do unpacking into the view argument list. However, as of :app:`Pyramid` 1.0a9, user code can influence the way view callables are expected to be called, making it possible to compose a system @@ -553,7 +550,7 @@ sources using :meth:`pyramid.config.Configurator.include`. - View and subscriber registrations made using :term:`interface` objects instead of class objects (e.g. :ref:`using_resource_interfaces`). instead of class objects (e.g., :ref:`using_resource_interfaces`). - A declarative :term:`authorization` system. @@ -579,42 +576,41 @@ In a bespoke web application, usually there's a single canonical deployment, and therefore no possibility of multiple code forks. Extensibility is not required; the code is just changed in-place. Security requirements are often less granular. Using the features listed above will often be overkill for such an application. required; the code is just changed in place. Security requirements are often less granular. Using the features listed above will often be overkill for such an application. If you don't like these features, it doesn't mean you can't or shouldn't use :app:`Pyramid`. They are all optional, and a lot of time has been spent making sure you don't need to know about them up-front. You can build "Pylons-1.X-style" applications using :app:`Pyramid` that are purely bespoke by ignoring the features above. You may find these features handy later after building a bespoke web application that suddenly becomes popular and requires extensibility because it must be deployed in multiple locations. :app:`Pyramid`. They are all optional, and a lot of time has been spent making sure you don't need to know about them up front. You can build "Pylons 1.X style" applications using :app:`Pyramid` that are purely bespoke by ignoring the features above. You may find these features handy later after building a bespoke web application that suddenly becomes popular and requires extensibility because it must be deployed in multiple locations. Pyramid Is Too Big ------------------ "The :app:`Pyramid` compressed tarball is larger than 2MB. It must be enormous!" "The :app:`Pyramid` compressed tarball is larger than 2MB. It must beenormous!" No. We just ship it with docs, test code, and scaffolding. Here's a breakdown of what's included in subdirectories of the package tree: No. We just ship it with docs, test code, and scaffolding. Here's a breakdown of what's included in subdirectories of the package tree: docs/ 4.9MB 3.6MB pyramid/tests/ 2.0MB 1.3MB pyramid/scaffolds/ 460KB 133KB pyramid/ (except for ``pyramd/tests`` and ``pyramid/scaffolds``) 844KB 812KB Of the approximately 34K lines of Python code in the package, the code that actually has a chance of executing during normal operation, excluding @@ -634,7 +630,8 @@ Chameleon and Mako templating system dependencies in the Pyramid core in 1.5 let us shed most of the remainder of them. Pyramid "Cheats" To Obtain Speed Pyramid "Cheats" to Obtain Speed -------------------------------- Complaints have been lodged by other web framework authors at various times @@ -643,10 +640,11 @@ :mod:`zope.interface` to do fast lookups. Another claimed cheating mechanism is the religious avoidance of extraneous function calls. If there's such a thing as cheating to get better performance, we want to cheat as much as possible. We optimize :app:`Pyramid` aggressively. This comes at a cost: the core code has sections that could be expressed more readably. As an amelioration, we've commented these sections liberally. If there's such a thing as cheating to get better performance, we want to cheat as much as possible. We optimize :app:`Pyramid` aggressively. This comes at a cost. The core code has sections that could be expressed with more readability. As an amelioration, we've commented these sections liberally. Pyramid Gets Its Terminology Wrong ("MVC") ------------------------------------------ @@ -659,8 +657,8 @@ expect that models are ORM models, controllers are classes that have methods that map to URLs, and views are templates. :app:`Pyramid` indeed has each of these concepts, and each probably *works* almost exactly like your existing "MVC" web framework. We just don't use the MVC terminology, as we can't square its usage in the web framework space with historical reality. "MVC" web framework. We just don't use the MVC terminology, as we can't square its usage in the web framework space with historical reality. People very much want to give web applications the same properties as common desktop GUI platforms by using similar terminology, and to provide some frame @@ -669,194 +667,189 @@ very well in general. Quoting from the `Model-View-Controller Wikipedia entry <http://en.wikipedia.org/wiki/Model–view–controller>`_: .. code-block:: text Though MVC comes in different flavors, control flow is generally as follows: Though MVC comes in different flavors, control flow is generally as follows: The user interacts with the user interface in some way (for example, presses a mouse button). The user interacts with the user interface in some way (for example, presses a mouse button). The controller handles the input event from the user interface, often via a registered handler or callback and converts the event into appropriate user action, understandable for the model. The controller handles the input event from the user interface, often via a registered handler or callback and converts the event into appropriate user action, understandable for the model. The controller notifies the model of the user action, possibly resulting in a change in the model's state. (For example, the controller updates the user's shopping cart.)[5] The controller notifies the model of the user action, possibly resulting in a change in the model's state. (For example, the controller updates the user's shopping cart.)[5] A view queries the model in order to generate an appropriate user interface (for example, the view lists the shopping cart's contents). Note that the view gets its own data from the model. A view queries the model in order to generate an appropriate user interface (for example, the view lists the shopping cart's contents). Note that the view gets its own data from the model. The controller may (in some implementations) issue a general instruction to the view to render itself. In others, the view is automatically notified by the model of changes in state (Observer) which require a screen update. The controller may (in some implementations) issue a general instruction to the view to render itself. In others, the view is automatically notified by the model of changes in state (Observer) which require a screen update. The user interface waits for further user interactions, which restarts the cycle. The user interface waits for further user interactions, which restarts the cycle. To the author, it seems as if someone edited this Wikipedia definition, tortuously couching concepts in the most generic terms possible in order to account for the use of the term "MVC" by current web frameworks. I doubt such a broad definition would ever be agreed to by the original authors of the MVC pattern. But *even so*, it seems most MVC web frameworks fail to meet even this falsely generic definition. account for the use of the term "MVC" by current web frameworks. I doubt such a broad definition would ever be agreed to by the original authors of the MVC pattern. But *even so*, it seems most MVC web frameworks fail to meet even this falsely generic definition. For example, do your templates (views) always query models directly as is claimed in "note that the view gets its own data from the model"? Probably not. My "controllers" tend to do this, massaging the data for easier use by the "view" (template). What do you do when your "controller" returns JSON? Do your controllers use a template to generate JSON? If not, what's the "view" then? Most MVC-style GUI web frameworks have some sort of event system hooked up that lets the view detect when the model changes. The web just has no such facility in its current form: it's effectively pull-only. claimed in "note that the view gets its own data from the model"? Probably not. My "controllers" tend to do this, massaging the data for easier use by the "view" (template). What do you do when your "controller" returns JSON? Do your controllers use a template to generate JSON? If not, what's the "view" then? Most MVC-style GUI web frameworks have some sort of event system hooked up that lets the view detect when the model changes. The web just has no such facility in its current form; it's effectively pull-only. So, in the interest of not mistaking desire with reality, and instead of trying to jam the square peg that is the web into the round hole of "MVC", we just punt and say there are two things: resources and views. The resource tree represents a site structure, the view presents a resource. The templates are really just an implementation detail of any given view: a view doesn't need a template to return a response. There's no "controller": it just doesn't exist. The "model" is either represented by the resource tree or by a "domain model" (like a SQLAlchemy model) that is separate from the framework entirely. This seems to us like more reasonable terminology, given the current constraints of the web. So, in the interest of not mistaking desire with reality, and instead of trying to jam the square peg that is the web into the round hole of "MVC", we just punt and say there are two things: resources and views. The resource tree represents a site structure, the view presents a resource. The templates are really just an implementation detail of any given view. A view doesn't need a template to return a response. There's no "controller"; it just doesn't exist. The "model" is either represented by the resource tree or by a "domain model" (like an SQLAlchemy model) that is separate from the framework entirely. This seems to us like more reasonable terminology, given the current constraints of the web. .. _apps_are_extensible: Pyramid Applications are Extensible; I Don't Believe In Application Extensibility Pyramid Applications Are Extensible; I Don't Believe in Application Extensibility --------------------------------------------------------------------------------- Any :app:`Pyramid` application written obeying certain constraints is *extensible*. This feature is discussed in the :app:`Pyramid` documentation chapters named :ref:`extending_chapter` and :ref:`advconfig_narr`. It is made possible by the use of the :term:`Zope Component Architecture` and within :app:`Pyramid`. chapters named :ref:`extending_chapter` and :ref:`advconfig_narr`. It is made possible by the use of the :term:`Zope Component Architecture` within :app:`Pyramid`. "Extensible", in this context, means: "Extensible" in this context means: - The behavior of an application can be overridden or extended in a particular *deployment* of the application without requiring that the deployer modify the source of the original application. - The behavior of an application can be overridden or extended in a particular *deployment* of the application without requiring that the deployer modify the source of the original application. - The original developer is not required to anticipate any extensibility plugpoints at application creation time to allow fundamental application behavior to be overriden or extended. - The original developer is not required to anticipate any extensibility plug points at application creation time to allow fundamental application behavior to be overridden or extended. - The original developer may optionally choose to anticipate an application-specific set of plugpoints, which may be hooked by a deployer. If he chooses to use the facilities provided by the ZCA, the original developer does not need to think terribly hard about the mechanics of introducing such a plugpoint. application-specific set of plug points, which may be hooked by a deployer. If they choose to use the facilities provided by the ZCA, the original developer does not need to think terribly hard about the mechanics of introducing such a plug point. Many developers seem to believe that creating extensible applications is not worth it. They instead suggest that modifying the source of a given application for each deployment to override behavior is more reasonable. Much discussion about version control branching and merging typically ensues. worth it. They instead suggest that modifying the source of a given application for each deployment to override behavior is more reasonable. Much discussion about version control branching and merging typically ensues. It's clear that making every application extensible isn't required. The majority of web applications only have a single deployment, and thus needn't be extensible at all. However, some web applications have multiple deployments, and some have *many* deployments. For example, a generic content management system (CMS) may have basic functionality that needs to be extended for a particular deployment. That CMS system may be deployed for many organizations at many places. Some number of deployments of this CMS may be deployed centrally by a third party and managed as a group. It's easier to be able to extend such a system for each deployment via preordained plugpoints than it is to continually keep each software branch of the system in sync with some upstream source: the upstream developers may change code in such a way that your changes to the same codebase conflict with theirs in fiddly, trivial ways. Merging such changes repeatedly over the lifetime of a deployment can be difficult and time consuming, and it's often useful to be able to modify an application for a particular deployment in a less invasive way. It's clear that making every application extensible isn't required. The majority of web applications only have a single deployment, and thus needn't be extensible at all. However some web applications have multiple deployments, and others have *many* deployments. For example, a generic content management system (CMS) may have basic functionality that needs to be extended for a particular deployment. That CMS may be deployed for many organizations at many places. Some number of deployments of this CMS may be deployed centrally by a third party and managed as a group. It's easier to be able to extend such a system for each deployment via preordained plug points than it is to continually keep each software branch of the system in sync with some upstream source. The upstream developers may change code in such a way that your changes to the same codebase conflict with theirs in fiddly, trivial ways. Merging such changes repeatedly over the lifetime of a deployment can be difficult and time consuming, and it's often useful to be able to modify an application for a particular deployment in a less invasive way. If you don't want to think about :app:`Pyramid` application extensibility at all, you needn't. You can ignore extensibility entirely. However, if you follow the set of rules defined in :ref:`extending_chapter`, you don't need to *make* your application extensible: any application you write in the framework just *is* automatically extensible at a basic level. The mechanisms that deployers use to extend it will be necessarily coarse: typically, views, routes, and resources will be capable of being overridden. But for most minor (and even some major) customizations, these are often the only override plugpoints necessary: if the application doesn't do exactly what the deployment requires, it's often possible for a deployer to override a view, route, or resource and quickly make it do what he or she wants it to do in ways *not necessarily anticipated by the original developer*. Here are some example scenarios demonstrating the benefits of such a feature. all, you needn't. You can ignore extensibility entirely. However if you follow the set of rules defined in :ref:`extending_chapter`, you don't need to *make* your application extensible. Any application you write in the framework just *is* automatically extensible at a basic level. The mechanisms that deployers use to extend it will be necessarily coarse. Typically views, routes, and resources will be capable of being overridden. But for most minor (and even some major) customizations, these are often the only override plug points necessary. If the application doesn't do exactly what the deployment requires, it's often possible for a deployer to override a view, route, or resource, and quickly make it do what they want it to do in ways *not necessarily anticipated by the original developer*. Here are some example scenarios demonstrating the benefits of such a feature. - If a deployment needs a different styling, the deployer may override the main template and the CSS in a separate Python package which defines overrides. - If a deployment needs a different styling, the deployer may override the main template and the CSS in a separate Python package which defines overrides. - If a deployment needs an application page to do something differently, or to expose more or different information, the deployer may override the view that renders the page within a separate Python package. - If a deployment needs an application page to do something differently, or to expose more or different information, the deployer may override the view that renders the page within a separate Python package. - If a deployment needs an additional feature, the deployer may add a view to the override package. As long as the fundamental design of the upstream package doesn't change, these types of modifications often survive across many releases of the upstream package without needing to be revisited. As long as the fundamental design of the upstream package doesn't change, these types of modifications often survive across many releases of the upstream package without needing to be revisited. Extending an application externally is not a panacea, and carries a set of risks similar to branching and merging: sometimes major changes upstream will cause you to need to revisit and update some of your modifications. But you won't regularly need to deal wth meaningless textual merge conflicts that trivial changes to upstream packages often entail when it comes time to update the upstream package, because if you extend an application externally, there just is no textual merge done. Your modifications will also, for whatever it's worth, be contained in one, canonical, well-defined place. risks similar to branching and merging. Sometimes major changes upstream will cause you to revisit and update some of your modifications. But you won't regularly need to deal with meaningless textual merge conflicts that trivial changes to upstream packages often entail when it comes time to update the upstream package, because if you extend an application externally, there just is no textual merge done. Your modifications will also, for whatever it's worth, be contained in one, canonical, well-defined place. Branching an application and continually merging in order to get new features and bugfixes is clearly useful. You can do that with a :app:`Pyramid` application just as usefully as you can do it with any application. But and bug fixes is clearly useful. You can do that with a :app:`Pyramid` application just as usefully as you can do it with any application. But deployment of an application written in :app:`Pyramid` makes it possible to avoid the need for this even if the application doesn't define any plugpoints ahead of time. It's possible that promoters of competing web frameworks dismiss this feature in favor of branching and merging because applications written in their framework of choice aren't extensible out of the box in a comparably fundamental way. avoid the need for this even if the application doesn't define any plug points ahead of time. It's possible that promoters of competing web frameworks dismiss this feature in favor of branching and merging because applications written in their framework of choice aren't extensible out of the box in a comparably fundamental way. While :app:`Pyramid` applications are fundamentally extensible even if you don't write them with specific extensibility in mind, if you're moderately adventurous, you can also take it a step further. If you learn more about the :term:`Zope Component Architecture`, you can optionally use it to expose other more domain-specific configuration plugpoints while developing an application. The plugpoints you expose needn't be as coarse as the ones provided automatically by :app:`Pyramid` itself. For example, you might compose your own directive that configures a set of views for a prebaked purpose (e.g. ``restview`` or somesuch) , allowing other people to refer to that directive when they make declarations in the ``includeme`` of their customization package. There is a cost for this: the developer of an application that defines custom plugpoints for its deployers will need to understand the ZCA or he will need to develop his own similar extensibility system. adventurous, you can also take it a step further. If you learn more about the :term:`Zope Component Architecture`, you can optionally use it to expose other more domain-specific configuration plug points while developing an application. The plug points you expose needn't be as coarse as the ones provided automatically by :app:`Pyramid` itself. For example, you might compose your own directive that configures a set of views for a pre-baked purpose (e.g., ``restview`` or somesuch), allowing other people to refer to that directive when they make declarations in the ``includeme`` of their customization package. There is a cost for this: the developer of an application that defines custom plug points for its deployers will need to understand the ZCA or they will need to develop their own similar extensibility system. Ultimately, any argument about whether the extensibility features lent to applications by :app:`Pyramid` are good or bad is mostly pointless. You needn't take advantage of the extensibility features provided by a particular Ultimately any argument about whether the extensibility features lent to applications by :app:`Pyramid` are good or bad is mostly pointless. You needn't take advantage of the extensibility features provided by a particular :app:`Pyramid` application in order to affect a modification for a particular set of its deployments. You can ignore the application's extensibility plugpoints entirely, and use version control branching and merging to manage application deployment modifications instead, as if you were deploying an application written using any other web framework. set of its deployments. You can ignore the application's extensibility plug points entirely, and use version control branching and merging to manage application deployment modifications instead, as if you were deploying an application written using any other web framework. Zope 3 Enforces "TTW" Authorization Checks By Default; Pyramid Does Not Zope 3 Enforces "TTW" Authorization Checks by Default; Pyramid Does Not ----------------------------------------------------------------------- Challenge +++++++++ :app:`Pyramid` performs automatic authorization checks only at :term:`view` execution time. Zope 3 wraps context objects with a `security proxy <http://wiki.zope.org/zope3/WhatAreSecurityProxies>`_, which causes Zope 3 to do also security checks during attribute access. I like this, because it means: execution time. Zope 3 wraps context objects with a `security proxy <http://wiki.zope.org/zope3/WhatAreSecurityProxies>`_, which causes Zope 3 also to do security checks during attribute access. I like this, because it means: #) When I use the security proxy machinery, I can have a view that conditionally displays certain HTML elements (like form fields) or @@ -888,7 +881,7 @@ And since we tend to use the same toolkit for all web applications, it's just never been a concern to be able to use the same set of restricted-execution code under two web different frameworks. code under two different web frameworks. Justifications for disabling security proxies by default notwithstanding, given that Zope 3 security proxies are viral by nature, the only requirement @@ -900,6 +893,7 @@ Zope3-security-proxy-wrapped objects for each traversed object (including the :term:`context` and the :term:`root`). This would have the effect of creating a more Zope3-like environment without much effort. .. _http_exception_hierarchy: @@ -913,28 +907,29 @@ :class:`~pyramid.httpexceptions.HTTPNotFound` or :class:`~pyramid.httpexceptions.HTTPForbidden`). They have the same names and largely the same behavior, and all have a very similar implementation, but not the same identity. Here's why they have a separate identity: the same identity. Here's why they have a separate identity. - Making them separate allows the HTTP exception classes to subclass :class:`pyramid.response.Response`. This speeds up response generation slightly due to the way the Pyramid router works. The same speedup could be slightly due to the way the Pyramid router works. The same speed up could be gained by monkeypatching :class:`webob.response.Response`, but it's usually the case that monkeypatching turns out to be evil and wrong. - Making them separate allows them to provide alternate ``__call__`` logic - Making them separate allows them to provide alternate ``__call__`` logic, which also speeds up response generation. - Making them separate allows the exception classes to provide for the proper value of ``RequestClass`` (:class:`pyramid.request.Request`). - Making them separate allows us freedom from having to think about backwards compatibility code present in :mod:`webob.exc` having to do with Python 2.4, which we no longer support in Pyramid 1.1+. - Making them separate gives us freedom from thinking about backwards compatibility code present in :mod:`webob.exc` related to Python 2.4, which we no longer support in Pyramid 1.1+. - We change the behavior of two classes (:class:`~pyramid.httpexceptions.HTTPNotFound` and :class:`~pyramid.httpexceptions.HTTPForbidden`) in the module so that they can be used by Pyramid internally for notfound and forbidden exceptions. can be used by Pyramid internally for ``notfound`` and ``forbidden`` exceptions. - Making them separate allows us to influence the docstrings of the exception classes to provide Pyramid-specific documentation. @@ -943,9 +938,10 @@ Python 2.6 when the response objects are used as exceptions (related to ``self.message``). .. _simpler_traversal_model: Pyramid has Simpler Traversal Machinery than Does Zope Pyramid has simpler traversal machinery than does Zope ------------------------------------------------------ Zope's default traverser: @@ -955,26 +951,26 @@ - Attempts to use an adaptation to obtain the next element in the path from the currently traversed object, falling back to ``__bobo_traverse__``, ``__getitem__`` and eventually ``__getattr__``. ``__getitem__``, and eventually ``__getattr__``. Zope's default traverser allows developers to mutate the traversal name stack during traversal by mutating ``REQUEST['TraversalNameStack']``. Pyramid's default traverser (``pyramid.traversal.ResourceTreeTraverser``) does not offer a way to do this; it does not maintain a stack as a request attribute and, even if it did, it does not pass the request to resource objects while it's traversing. While it was handy at times, this feature was abused in frameworks built atop Zope (like CMF and Plone), often making it difficult to tell exactly what was happening when a traversal didn't match a view. I felt it was better to make folks that wanted the feature replace the traverser rather than build that particular honey pot in to the default traverser. during traversal by mutating ``REQUEST['TraversalNameStack']``. Pyramid's default traverser (``pyramid.traversal.ResourceTreeTraverser``) does not offer a way to do this. It does not maintain a stack as a request attribute and, even if it did, it does not pass the request to resource objects while it's traversing. While it was handy at times, this feature was abused in frameworks built atop Zope (like CMF and Plone), often making it difficult to tell exactly what was happening when a traversal didn't match a view. I felt it was better for folks that wanted the feature to make them replace the traverser rather than build that particular honey pot in to the default traverser. Zope uses multiple mechanisms to attempt to obtain the next element in the resource tree based on a name. It first tries an adaptation of the current resource to ``ITraversable``, and if that fails, it falls back to attempting resource to ``ITraversable``, and if that fails, it falls back to attempting a number of magic methods on the resource (``__bobo_traverse__``, ``__getitem__``, and ``__getattr__``). My experience while both using Zope and attempting to reimplement its publisher in ``repoze.zope2`` led me to believe the following: ``__getitem__``, and ``__getattr__``). My experience while both using Zope and attempting to reimplement its publisher in ``repoze.zope2`` led me to believe the following: - The *default* traverser should be as simple as possible. Zope's publisher is somewhat difficult to follow and replicate due to the fallbacks it tried @@ -995,7 +991,7 @@ default implementation of the larger component, no one understands when (or whether) they should ever override the larger component entrirely. This results, over time, in a rusting together of the larger "replaceable" component and the framework itself, because people come to depend on the component and the framework itself because people come to depend on the availability of the default component in order just to turn its knobs. The default component effectively becomes part of the framework, which entirely subverts the goal of making it replaceable. In Pyramid, typically if a @@ -1004,40 +1000,42 @@ you will replace the component instead of turning knobs attached to the component. .. _microframeworks_smaller_hello_world: Microframeworks Have Smaller Hello World Programs Microframeworks have smaller Hello World programs ------------------------------------------------- Self-described "microframeworks" exist: `Bottle <http://bottle.paws.de>`_ and `Flask <http://flask.pocoo.org/>`_ are two that are becoming popular. `Bobo <http://bobo.digicool.com/>`_ doesn't describe itself as a microframework, but its intended userbase is much the same. Many others exist. We've actually even (only as a teaching tool, not as any sort of official project) `created one using Pyramid <http://bfg.repoze.org/videos#groundhog1>`_ (the videos use BFG, a precursor to Pyramid, but the resulting code is `available for Pyramid too <https://github.com/Pylons/groundhog>`_). Microframeworks are small frameworks with one common feature: each allows its users to create a fully functional application that lives in a single Python file. Self-described "microframeworks" exist. `Bottle <http://bottle.paws.de>`_ and `Flask <http://flask.pocoo.org/>`_ are two that are becoming popular. `Bobo <http://bobo.digicool.com/>`_ doesn't describe itself as a microframework, but its intended user base is much the same. Many others exist. We've even (only as a teaching tool, not as any sort of official project) `created one using Pyramid <http://bfg.repoze.org/videos#groundhog1>`_. The videos use BFG, a precursor to Pyramid, but the resulting code is `available for Pyramid too <https://github.com/Pylons/groundhog>`_). Microframeworks are small frameworks with one common feature: each allows its users to create a fully functional application that lives in a single Python file. Some developers and microframework authors point out that Pyramid's "hello world" single-file program is longer (by about five lines) than the equivalent program in their favorite microframework. Guilty as charged. world" single-file program is longer (by about five lines) than the equivalent program in their favorite microframework. Guilty as charged. This loss isn't for lack of trying. Pyramid is useful in the same circumstance in which microframeworks claim dominance: single-file applications. But Pyramid doesn't sacrifice its ability to credibly support larger applications in order to achieve hello-world LoC parity with the current crop of microframeworks. Pyramid's design instead tries to avoid some common pitfalls associated with naive declarative configuration schemes. The subsections which follow explain the rationale. This loss isn't for lack of trying. Pyramid is useful in the same circumstance in which microframeworks claim dominance: single-file applications. But Pyramid doesn't sacrifice its ability to credibly support larger applications in order to achieve "hello world" lines of code parity with the current crop of microframeworks. Pyramid's design instead tries to avoid some common pitfalls associated with naive declarative configuration schemes. The subsections which follow explain the rationale. .. _you_dont_own_modulescope: Application Programmers Don't Control The Module-Scope Codepath (Import-Time Side-Effects Are Evil) Application programmers don't control the module-scope codepath (import-time side-effects are evil) +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Please imagine a directory structure with a set of Python files in it: Imagine a directory structure with a set of Python files in it: .. code-block:: text @@ -1085,13 +1083,13 @@ L.append(func) return func If we cd to the directory that holds these files and we run ``python app.py`` given the directory structure and code above, what happens? Presumably, our ``decorator`` decorator will be used twice, once by the decorated function ``foo`` in ``app.py`` and once by the decorated function ``bar`` in ``app2.py``. Since each time the decorator is used, the list ``L`` in ``config.py`` is appended to, we'd expect a list with two elements to be printed, right? Sadly, no: If we ``cd`` to the directory that holds these files, and we run ``python app.py``, given the directory structure and code above, what happens? Presumably, our ``decorator`` decorator will be used twice, once by the decorated function ``foo`` in ``app.py``, and once by the decorated function ``bar`` in ``app2.py``. Since each time the decorator is used, the list ``L`` in ``config.py`` is appended to, we'd expect a list with two elements to be printed, right? Sadly, no: .. code-block:: text @@ -1101,21 +1099,21 @@ <function bar at 0x7f4ea41ab2a8>] By visual inspection, that outcome (three different functions in the list) seems impossible. We only defined two functions and we decorated each of those functions only once, so we believe that the ``decorator`` decorator will only run twice. However, what we believe is wrong because the code at module scope in our ``app.py`` module was *executed twice*. The code is seems impossible. We defined only two functions, and we decorated each of those functions only once, so we believe that the ``decorator`` decorator will run only twice. However, what we believe is in fact wrong, because the code at module scope in our ``app.py`` module was *executed twice*. The code is executed once when the script is run as ``__main__`` (via ``python app.py``), and then it is executed again when ``app2.py`` imports the same file as ``app``. What does this have to do with our comparison to microframeworks? Many microframeworks in the current crop (e.g. Bottle, Flask) encourage you to attach configuration decorators to objects defined at module scope. These decorators execute arbitrarily complex registration code which populates a singleton registry that is a global defined in external Python module. This is analogous to the above example: the "global registry" in the above example is the list ``L``. What does this have to do with our comparison to microframeworks? Many microframeworks in the current crop (e.g., Bottle and Flask) encourage you to attach configuration decorators to objects defined at module scope. These decorators execute arbitrarily complex registration code, which populates a singleton registry that is a global which is in turn defined in external Python module. This is analogous to the above example: the "global registry" in the above example is the list ``L``. Let's see what happens when we use the same pattern with the `Groundhog <https://github.com/Pylons/groundhog>`_ microframework. Replace the contents @@ -1168,41 +1166,39 @@ The encouragement to use decorators which perform population of an external registry has an unintended consequence: the application developer now must assert ownership of every codepath that executes Python module scope code. Module-scope code is presumed by the current crop of decorator-based microframeworks to execute once and only once; if it executes more than once, weird things will start to happen. It is up to the application developer to maintain this invariant. Unfortunately, however, in reality, this is an impossible task, because, Python programmers *do not own the module scope codepath, and never will*. Anyone who tries to sell you on the idea that they do is simply mistaken. Test runners that you may want to use to run your code's tests often perform imports of arbitrary code in strange orders that manifest bugs like the one demonstrated above. API documentation generation tools do the same. Some people even think it's safe to use the Python ``reload`` command or delete objects from ``sys.modules``, each of which has hilarious effects when used against code that has import-time side effects. assert ownership of every code path that executes Python module scope code. Module-scope code is presumed by the current crop of decorator-based microframeworks to execute once and only once. If it executes more than once, weird things will start to happen. It is up to the application developer to maintain this invariant. Unfortunately, in reality this is an impossible task, because Python programmers *do not own the module scope code path, and never will*. Anyone who tries to sell you on the idea that they do so is simply mistaken. Test runners that you may want to use to run your code's tests often perform imports of arbitrary code in strange orders that manifest bugs like the one demonstrated above. API documentation generation tools do the same. Some people even think it's safe to use the Python ``reload`` command, or delete objects from ``sys.modules``, each of which has hilarious effects when used against code that has import-time side effects. Global-registry-mutating microframework programmers therefore will at some point need to start reading the tea leaves about what *might* happen if module scope code gets executed more than once like we do in the previous paragraph. When Python programmers assume they can use the module-scope codepath to run arbitrary code (especially code which populates an external registry), and this assumption is challenged by reality, the application developer is often required to undergo a painful, meticulous debugging process to find the root cause of an inevitably obscure symptom. The solution is often to rearrange application import ordering or move an import statement from module-scope into a function body. The rationale for doing so can never be expressed adequately in the checkin message which accompanies the fix and can't be documented succinctly enough for the benefit of the rest of the development team so that the problem never happens again. It will happen again, especially if you are working on a project with other people who haven't yet internalized the lessons you learned while you stepped through module-scope code using ``pdb``. This is a really pretty poor situation to find yourself in as an application developer: you probably didn't even know your or your team signed up for the job, because the documentation offered by decorator-based microframeworks don't warn you about it. Global registry-mutating microframework programmers therefore will at some point need to start reading the tea leaves about what *might* happen if module scope code gets executed more than once, like we do in the previous paragraph. When Python programmers assume they can use the module-scope code path to run arbitrary code (especially code which populates an external registry), and this assumption is challenged by reality, the application developer is often required to undergo a painful, meticulous debugging process to find the root cause of an inevitably obscure symptom. The solution is often to rearrange application import ordering, or move an import statement from module-scope into a function body. The rationale for doing so can never be expressed adequately in the commit message which accompanies the fix, and can't be documented succinctly enough for the benefit of the rest of the development team so that the problem never happens again. It will happen again, especially if you are working on a project with other people who haven't yet internalized the lessons you learned while you stepped through module-scope code using ``pdb``. This is a very poor situation in which to find yourself as an application developer: you probably didn't even know you or your team signed up for the job, because the documentation offered by decorator-based microframeworks don't warn you about it. Folks who have a large investment in eager decorator-based configuration that populates an external data structure (such as microframework authors) may @@ -1218,7 +1214,7 @@ If microframework authors do admit that the circumstance isn't contrived, they might then argue that real damage will never happen as the result of the double-execution (or triple-execution, etc) of module scope code. You would double-execution (or triple-execution, etc.) of module scope code. You would be wise to disbelieve this assertion. The potential outcomes of multiple execution are too numerous to predict because they involve delicate relationships between application and framework code as well as chronology of @@ -1226,14 +1222,14 @@ what will happen in all circumstances. But even if given the gift of omniscience for some limited set of circumstances, the framework author almost certainly does not have the double-execution anomaly in mind when coding new features. He's thinking of adding a feature, not protecting coding new features. They're thinking of adding a feature, not protecting against problems that might be caused by the 1% multiple execution case. However, any 1% case may cause 50% of your pain on a project, so it'd be nice if it never occured. if it never occurred. Responsible microframeworks actually offer a back-door way around the problem. They allow you to disuse decorator based configuration entirely. Instead of requiring you to do the following: Responsible microframeworks actually offer a back-door way around the problem. They allow you to disuse decorator-based configuration entirely. Instead of requiring you to do the following: .. code-block:: python :linenos: @@ -1247,7 +1243,7 @@ if __name__ == '__main__': gh.run() They allow you to disuse the decorator syntax and go almost-all-imperative: They allow you to disuse the decorator syntax and go almost all-imperative: .. code-block:: python :linenos: @@ -1271,23 +1267,23 @@ .. note:: Astute readers may notice that Pyramid has configuration decorators too. Aha! Don't these decorators have the same problems? No. These decorators do not populate an external Python module when they are executed. They only mutate the functions (and classes and methods) they're attached to. These mutations must later be found during a scan process that has a predictable and structured import phase. Module-localized mutation is actually the best-case circumstance for double-imports; if a module only mutates itself and its contents at import time, if it is imported twice, that's OK, because each decorator invocation will always be mutating an independent copy of the object it's attached to, not a shared resource like a registry in another module. This has the effect that double-registrations will never be performed. Astute readers may notice that Pyramid has configuration decorators too. Aha! Don't these decorators have the same problems? No. These decorators do not populate an external Python module when they are executed. They only mutate the functions (and classes and methods) to which they're attached. These mutations must later be found during a scan process that has a predictable and structured import phase. Module-localized mutation is actually the best-case circumstance for double-imports. If a module only mutates itself and its contents at import time, if it is imported twice, that's OK, because each decorator invocation will always be mutating an independent copy of the object to which it's attached, not a shared resource like a registry in another module. This has the effect that double-registrations will never be performed. .. _routes_need_ordering: Routes Need Relative Ordering Routes need relative ordering +++++++++++++++++++++++++++++ Consider the following simple `Groundhog @@ -1315,8 +1311,8 @@ app.run() If you run this application and visit the URL ``/admin``, you will see the "admin" page. This is the intended result. However, what if you rearrange the order of the function definitions in the file? "admin" page. This is the intended result. However, what if you rearrange the order of the function definitions in the file? .. code-block:: python :linenos: @@ -1339,11 +1335,11 @@ if __name__ == '__main__': app.run() If you run this application and visit the URL ``/admin``, you will now be returned a 404 error. This is probably not what you intended. The reason you see a 404 error when you rearrange function definition ordering is that routing declarations expressed via our microframework's routing decorators have an *ordering*, and that ordering matters. If you run this application and visit the URL ``/admin``, your app will now return a 404 error. This is probably not what you intended. The reason you see a 404 error when you rearrange function definition ordering is that routing declarations expressed via our microframework's routing decorators have an *ordering*, and that ordering matters. In the first case, where we achieved the expected result, we first added a route with the pattern ``/admin``, then we added a route with the pattern @@ -1351,65 +1347,67 @@ scope. When a request with a ``PATH_INFO`` of ``/admin`` enters our application, the web framework loops over each of our application's route patterns in the order in which they were defined in our module. As a result, the view associated with the ``/admin`` routing pattern will be invoked: it matches first. All is right with the world. the view associated with the ``/admin`` routing pattern will be invoked because it matches first. All is right with the world. In the second case, where we did not achieve the expected result, we first added a route with the pattern ``/:action``, then we added a route with the pattern ``/admin``. When a request with a ``PATH_INFO`` of ``/admin`` enters our application, the web framework loops over each of our application's route patterns in the order in which they were defined in our module. As a result, the view associated with the ``/:action`` routing pattern will be invoked: it matches first. A 404 error is raised. This is not what we wanted; it just happened due to the order in which we defined our view functions. the view associated with the ``/:action`` routing pattern will be invoked because it matches first. A 404 error is raised. This is not what we wanted; it just happened due to the order in which we defined our view functions. This is because Groundhog routes are added to the routing map in import order, and matched in the same order when a request comes in. Bottle, like Groundhog, as of this writing, matches routes in the order in which they're defined at Python execution time. Flask, on the other hand, does not order route matching based on import order; it reorders the routes you add to your application based on their "complexity". Other microframeworks have varying This is because Groundhog routes are added to the routing map in import order, and matched in the same order when a request comes in. Bottle, like Groundhog, as of this writing, matches routes in the order in which they're defined at Python execution time. Flask, on the other hand, does not order route matching based on import order. Instead it reorders the routes you add to your application based on their "complexity". Other microframeworks have varying strategies to do route ordering. Your application may be small enough where route ordering will never cause an issue. If your application becomes large enough, however, being able to specify or predict that ordering as your application grows larger will be difficult. At some point, you will likely need to more explicitly start controlling route ordering, especially in applications that require extensibility. issue. If your application becomes large enough, however, being able to specify or predict that ordering as your application grows larger will be difficult. At some point, you will likely need to start controlling route ordering more explicitly, especially in applications that require extensibility. If your microframework orders route matching based on complexity, you'll need to understand what is meant by "complexity", and you'll need to attempt to inject a "less complex" route to have it get matched before any "more complex" one to ensure that it's tried first. inject a "less complex" route to have it get matched before any "more complex" one to ensure that it's tried first. If your microframework orders its route matching based on relative import/execution of function decorator definitions, you will need to ensure you execute all of these statements in the "right" order, and you'll need to be cognizant of this import/execution ordering as you grow your application or try to extend it. This is a difficult invariant to maintain for all but the smallest applications. that you execute all of these statements in the "right" order, and you'll need to be cognizant of this import/execution ordering as you grow your application or try to extend it. This is a difficult invariant to maintain for all but the smallest applications. In either case, your application must import the non-``__main__`` modules which contain configuration decorations somehow for their configuration to be executed. Does that make you a little uncomfortable? It should, because In either case, your application must import the non-``__main__`` modules which contain configuration decorations somehow for their configuration to be executed. Does that make you a little uncomfortable? It should, because :ref:`you_dont_own_modulescope`. Pyramid uses neither decorator import time ordering nor does it attempt to divine the relative complexity of one route to another in order to define a route match ordering. In Pyramid, you have to maintain relative route ordering imperatively via the chronology of multiple executions of the :meth:`pyramid.config.Configurator.add_route` method. The order in which you divine the relative complexity of one route to another as a means to define a route match ordering. In Pyramid, you have to maintain relative route ordering imperatively via the chronology of multiple executions of the :meth:`pyramid.config.Configurator.add_route` method. The order in which you repeatedly call ``add_route`` becomes the order of route matching. If needing to maintain this imperative ordering truly bugs you, you can use :term:`traversal` instead of route matching, which is a completely declarative (and completely predictable) mechanism to map code to URLs. While URL dispatch is easier to understand for small non-extensible applications, traversal is a great fit for very large applications and applications that need to be arbitrarily extensible. :term:`traversal` instead of route matching, which is a completely declarative (and completely predictable) mechanism to map code to URLs. While URL dispatch is easier to understand for small non-extensible applications, traversal is a great fit for very large applications and applications that need to be arbitrarily extensible. "Stacked Object Proxies" Are Too Clever / Thread Locals Are A Nuisance .. _thread_local_nuisance: "Stacked object proxies" are too clever / thread locals are a nuisance ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Some microframeworks use the ``import`` statement to get a handle to an @@ -1452,32 +1450,35 @@ for i in range(10): print(i) By its nature, the *request* object created as the result of a WSGI server's call into a long-lived web framework cannot be global, because the lifetime of a single request will be much shorter than the lifetime of the process running the framework. A request object created by a web framework actually has more similarity to the ``i`` loop counter in our example above than it has to any comparable importable object defined in the Python standard By its nature, the *request* object that is created as the result of a WSGI server's call into a long-lived web framework cannot be global, because the lifetime of a single request will be much shorter than the lifetime of the process running the framework. A request object created by a web framework actually has more similarity to the ``i`` loop counter in our example above than it has to any comparable importable object defined in the Python standard library or in normal library code. However, systems which use stacked object proxies promote locally scoped objects such as ``request`` out to module scope, for the purpose of being objects, such as ``request``, out to module scope, for the purpose of being able to offer users a nice spelling involving ``import``. They, for what I consider dubious reasons, would rather present to their users the canonical way of getting at a ``request`` as ``from framework import request`` instead of a saner ``from myframework.threadlocals import get_request; request = get_request()`` even though the latter is more explicit. consider dubious reasons, would rather present to their users the canonical way of getting at a ``request`` as ``from framework import request`` instead of a saner ``from myframework.threadlocals import get_request; request = get_request()``, even though the latter is more explicit. It would be *most* explicit if the microframeworks did not use thread local variables at all. Pyramid view functions are passed a request object; many of Pyramid's APIs require that an explicit request object be passed to them. It is *possible* to retrieve the current Pyramid request as a threadlocal variable but it is a "in case of emergency, break glass" type of activity. This explicitness makes Pyramid view functions more easily unit testable, as you don't need to rely on the framework to manufacture suitable "dummy" request (and other similarly-scoped) objects during test setup. It also makes them more likely to work on arbitrary systems, such as async servers that do no monkeypatching. variables at all. Pyramid view functions are passed a request object. Many of Pyramid's APIs require that an explicit request object be passed to them. It is *possible* to retrieve the current Pyramid request as a threadlocal variable, but it is an "in case of emergency, break glass" type of activity. This explicitness makes Pyramid view functions more easily unit testable, as you don't need to rely on the framework to manufacture suitable "dummy" request (and other similarly-scoped) objects during test setup. It also makes them more likely to work on arbitrary systems, such as async servers, that do no monkeypatching. .. _explicitly_wsgi: Explicitly WSGI +++++++++++++++ @@ -1491,35 +1492,35 @@ the documentation of that WSGI server. The extra lines saved by abstracting away the serving step behind ``run()`` seem to have driven dubious second-order decisions related to API in some microframeworks. For example, Bottle contains a ``ServerAdapter`` subclass for each type of WSGI server it supports via its ``app.run()`` mechanism. This means that there exists code in ``bottle.py`` that depends on the following modules: ``wsgiref``, ``flup``, ``paste``, ``cherrypy``, ``fapws``, seems to have driven dubious second-order decisions related to its API in some microframeworks. For example, Bottle contains a ``ServerAdapter`` subclass for each type of WSGI server it supports via its ``app.run()`` mechanism. This means that there exists code in ``bottle.py`` that depends on the following modules: ``wsgiref``, ``flup``, ``paste``, ``cherrypy``, ``fapws``, ``tornado``, ``google.appengine``, ``twisted.web``, ``diesel``, ``gevent``, ``gunicorn``, ``eventlet``, and ``rocket``. You choose the kind of server you want to run by passing its name into the ``run`` method. In theory, this sounds great: I can try Bottle out on ``gunicorn`` just by passing in a name! However, to fully test Bottle, all of these third-party systems must be installed and functional; the Bottle developers must monitor changes to each of these packages and make sure their code still interfaces properly with them. This expands the packages required for testing greatly; this is a *lot* of requirements. It is likely difficult to fully automate these tests due to requirements conflicts and build issues. ``gunicorn``, ``eventlet``, and ``rocket``. You choose the kind of server you want to run by passing its name into the ``run`` method. In theory, this sounds great: I can try out Bottle on ``gunicorn`` just by passing in a name! However, to fully test Bottle, all of these third-party systems must be installed and functional. The Bottle developers must monitor changes to each of these packages and make sure their code still interfaces properly with them. This increases the number of packages required for testing greatly; this is a *lot* of requirements. It is likely difficult to fully automate these tests due to requirements conflicts and build issues. As a result, for single-file apps, we currently don't bother to offer a ``run()`` shortcut; we tell folks to import their WSGI server of choice and run it by hand. For the people who want a server abstraction layer, we suggest that they use PasteDeploy. In PasteDeploy-based systems, the onus for making sure that the server can interface with a WSGI application is placed on the server developer, not the web framework developer, making it more likely to be timely and correct. ``run()`` shortcut. We tell folks to import their WSGI server of choice and run it by hand. For the people who want a server abstraction layer, we suggest that they use PasteDeploy. In PasteDeploy-based systems, the onus for making sure that the server can interface with a WSGI application is placed on the server developer, not the web framework developer, making it more likely to be timely and correct. Wrapping Up Wrapping up +++++++++++ Here's a diagrammed version of the simplest pyramid application, where comments take into account what we've discussed in the Here's a diagrammed version of the simplest pyramid application, where the inlined comments take into account what we've discussed in the :ref:`microframeworks_smaller_hello_world` section. .. code-block:: python @@ -1530,16 +1531,17 @@ def hello_world(request): # accepts a request; no request thread local reqd # explicit response object means no response threadlocal return Response('Hello world!') return Response('Hello world!') if __name__ == '__main__': from pyramid.config import Configurator config = Configurator() # no global application object. config = Configurator() # no global application object config.add_view(hello_world) # explicit non-decorator registration app = config.make_wsgi_app() # explicitly WSGI server = make_server('0.0.0.0', 8080, app) server.serve_forever() # explicitly WSGI Pyramid Doesn't Offer Pluggable Apps ------------------------------------
@@ -234,7 +234,7 @@ object *location-aware*. permission A string or unicode object that represents an action being taken against A string or Unicode object that represents an action being taken against a :term:`context` resource. A permission is associated with a view name and a resource type by the developer. Resources are decorated with security declarations (e.g. an :term:`ACL`), which reference these @@ -291,22 +291,22 @@ :term:`authorization policy`. principal A *principal* is a string or unicode object representing an entity, typically a user or group. Principals are provided by an :term:`authentication policy`. For example, if a user had the :term:`userid` `"bob"`, and was part of two groups named `"group foo"` and "group bar", the request might have information attached to it that would indicate that Bob was represented by three principals: `"bob"`, `"group foo"` and `"group bar"`. A *principal* is a string or Unicode object representing an entity, typically a user or group. Principals are provided by an :term:`authentication policy`. For example, if a user has the :term:`userid` `bob`, and is a member of two groups named `group foo` and `group bar`, then the request might have information attached to it indicating that Bob was represented by three principals: `bob`, `group foo` and `group bar`. userid A *userid* is a string or unicode object used to identify and authenticate a real-world user (or client). A userid is supplied to an :term:`authentication policy` in order to discover the user's :term:`principals <principal>`. The default behavior of the authentication policies :app:`Pyramid` provides is to return the user's userid as a principal, but this is not strictly necessary in custom policies that define their principals differently. A *userid* is a string or Unicode object used to identify and authenticate a real-world user or client. A userid is supplied to an :term:`authentication policy` in order to discover the user's :term:`principals <principal>`. In the authentication policies which :app:`Pyramid` provides, the default behavior returns the user's userid as a principal, but this is not strictly necessary in custom policies that define their principals differently. authorization policy An authorization policy in :app:`Pyramid` terms is a bit of @@ -367,13 +367,13 @@ file. It was developed by Ian Bicking. Chameleon `chameleon <http://chameleon.repoze.org>`_ is an attribute language template compiler which supports the :term:`ZPT` templating specification. It is written and maintained by Malthe Borch. It has several extensions, such as the ability to use bracketed (Mako-style) ``${name}`` syntax. It is also much faster than the reference implementation of ZPT. :app:`Pyramid` offers Chameleon templating out of the box in ZPT and text flavors. `chameleon <https://chameleon.readthedocs.org/en/latest/>`_ is an attribute language template compiler which supports the :term:`ZPT` templating specification. It is written and maintained by Malthe Borch. It has several extensions, such as the ability to use bracketed (Mako-style) ``${name}`` syntax. It is also much faster than the reference implementation of ZPT. :app:`Pyramid` offers Chameleon templating out of the box in ZPT and text flavors. ZPT The `Zope Page Template <http://wiki.zope.org/ZPT/FrontPage>`_ @@ -815,11 +815,10 @@ library, used by the :app:`Pyramid` translation machinery. Babel A `collection of tools <http://babel.edgewall.org/>`_ for internationalizing Python applications. :app:`Pyramid` does not depend on Babel to operate, but if Babel is installed, additional locale functionality becomes available to your application. A `collection of tools <http://babel.pocoo.org/en/latest/>`_ for internationalizing Python applications. :app:`Pyramid` does not depend on Babel to operate, but if Babel is installed, additional locale functionality becomes available to your application. Lingua A package by Wichert Akkerman which provides the ``pot-create`` @@ -960,10 +959,10 @@ users transition from Pylons and those preferring a more Pylons-like API. The scaffold has been retired but the demo plays a similar role. Pyramid Cookbook Additional documentation for Pyramid which presents topical, practical uses of Pyramid: http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest. Pyramid Community Cookbook Additional, community-based documentation for Pyramid which presents topical, practical uses of Pyramid: :ref:`Pyramid Community Cookbook <cookbook:pyramid-cookbook>` distutils The standard system for packaging and distributing Python packages. See docs/index.rst
@@ -39,9 +39,9 @@ format, with somewhat deeper treatment of each topic and with working code. * Like learning by example? Visit the official :ref:`html_tutorials` as well as the community-contributed :ref:`Pyramid tutorials <tutorials:pyramid-tutorials>`, which include a :ref:`Todo List Application in One File <tutorials:single-file-tutorial>`. the community-contributed :ref:`Pyramid Tutorials <tutorials:pyramid-tutorials>` and :ref:`Pyramid Community Cookbook <cookbook:pyramid-cookbook>`. * For help getting Pyramid set up, try :ref:`installing_chapter`.
@@ -417,7 +417,6 @@ More Information ---------------- For more information, see the article `"A Whirlwind Tour of Advanced Configuration Tactics" <http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/configuration/whirlwind_tour.html>`_ in the Pyramid Cookbook. For more information, see the article :ref:`A Whirlwind Tour of Advanced Configuration Tactics <cookbook:whirlwind-adv-conf>` in the Pyramid Community Cookbook. docs/narr/hooks.rst
@@ -262,7 +262,7 @@ Adding Methods or Properties to a Request Object ------------------------------------------------ .. versionadded:: 1.4. .. versionadded:: 1.4 Since each Pyramid application can only have one :term:`request` factory, :ref:`changing the request factory <changing_the_request_factory>` is not that docs/narr/i18n.rst
@@ -585,10 +585,10 @@ :app:`Pyramid` does not itself perform date and currency formatting for different locales. However, :term:`Babel` can help you do this via the :class:`babel.core.Locale` class. The `Babel documentation for this class <http://babel.edgewall.org/wiki/ApiDocs/babel.core#babel.core:Locale>`_ provides minimal information about how to perform date and currency related locale operations. See :ref:`installing_babel` for information about how to install Babel. <http://babel.pocoo.org/en/latest/api/core.html#basic-interface>`_ provides minimal information about how to perform date and currency related locale operations. See :ref:`installing_babel` for information about how to install Babel. The :class:`babel.core.Locale` class requires a :term:`locale name` as an argument to its constructor. You can use :app:`Pyramid` APIs to obtain the @@ -666,9 +666,9 @@ Mako Pyramid i18n Support ------------------------- There exists a recipe within the :term:`Pyramid Cookbook` named ":ref:`Mako Internationalization <cookbook:mako_i18n>`" which explains how to add idiomatic i18n support to :term:`Mako` templates. There exists a recipe within the :term:`Pyramid Community Cookbook` named :ref:`Mako Internationalization <cookbook:mako_i18n>` which explains how to add idiomatic i18n support to :term:`Mako` templates. .. index:: single: localization deployment settings docs/narr/install.rst
@@ -15,7 +15,7 @@ .. sidebar:: Python Versions As of this writing, :app:`Pyramid` has been tested under Python 2.6, Python 2.7, Python 3.2, Python 3.3, Python 3.4, PyPy, and PyPy3. :app:`Pyramid` 2.7, Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3. :app:`Pyramid` does not run under any version of Python before 2.6. :app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, @@ -46,7 +46,7 @@ # for python 2.7 $ brew install python # for python 3.4 # for python 3.5 $ brew install python3 If you use an installer for your Python, then you can skip to the section @@ -292,7 +292,7 @@ itself using the following commands: .. parsed-literal:: $ $VENV/bin/easy_install "pyramid==\ |release|\ " The ``easy_install`` command will take longer than the previous ones to @@ -371,7 +371,7 @@ installed: .. parsed-literal:: c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " What Gets Installed docs/narr/introduction.rst
@@ -860,8 +860,8 @@ tests, as measured by the ``coverage`` tool available on PyPI. It also has greater than 95% decision/condition coverage as measured by the ``instrumental`` tool available on PyPI. It is automatically tested by the Jenkins tool on Python 2.6, Python 2.7, Python 3.2, Python 3.3, Python 3.4, PyPy, and PyPy3 after each commit to its GitHub repository. Official Pyramid Jenkins tool on Python 2.6, Python 2.7, Python 3.3, Python 3.4, Python 3.5, PyPy, and PyPy3 after each commit to its GitHub repository. Official Pyramid add-ons are held to a similar testing standard. We still find bugs in Pyramid and its official add-ons, but we've noticed we find a lot more of them while working on other projects that don't have a good testing regime. @@ -892,8 +892,7 @@ common integration scenarios too specific to add to the official narrative docs. In any case, the Pyramid documentation is comprehensive. Example: The Pyramid Cookbook at http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/. Example: The :ref:`Pyramid Community Cookbook <cookbook:pyramid-cookbook>`. .. index:: single: Pylons Project docs/narr/project.rst
@@ -447,7 +447,7 @@ :linenos: [app:main] ... # ... elided configuration pyramid.includes = pyramid_debugtoolbar @@ -457,7 +457,7 @@ :linenos: [app:main] ... # ... elided configuration pyramid.includes = # pyramid_debugtoolbar
@@ -17,7 +17,7 @@ Here's an example application which uses a subrequest: .. code-block:: python :linenos: :linenos: from wsgiref.simple_server import make_server from pyramid.config import Configurator @@ -61,8 +61,8 @@ object: .. code-block:: python :linenos: :emphasize-lines: 11 :linenos: :emphasize-lines: 11 from wsgiref.simple_server import make_server from pyramid.config import Configurator @@ -106,8 +106,8 @@ :term:`exception view` configured: .. code-block:: python :linenos: :emphasize-lines: 11-16 :linenos: :emphasize-lines: 11-16 from wsgiref.simple_server import make_server from pyramid.config import Configurator @@ -175,8 +175,8 @@ :meth:`~pyramid.request.Request.invoke_subrequest`, like this: .. code-block:: python :linenos: :emphasize-lines: 7 :linenos: :emphasize-lines: 7 from wsgiref.simple_server import make_server from pyramid.config import Configurator docs/narr/upgrading.rst
@@ -75,6 +75,27 @@ should change older spellings to newer ones to ensure that people reading your code can find the APIs you're using in the Pyramid docs. Python support policy ~~~~~~~~~~~~~~~~~~~~~ At the time of a Pyramid version release, each supports all versions of Python through the end of their lifespans. The end-of-life for a given version of Python is when security updates are no longer released. - `Python 3.2 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_ ends February 2016. - `Python 3.3 Lifespan <https://www.python.org/dev/peps/pep-0392/#lifespan>`_ ends September 2017. - `Python 3.4 Lifespan <https://www.python.org/dev/peps/pep-0429/>`_ TBD. - `Python 3.5 Lifespan <https://www.python.org/dev/peps/pep-0478/>`_ TBD. - `Python 3.6 Lifespan <https://www.python.org/dev/peps/pep-0494/#id4>`_ December 2021. To determine the Python support for a specific release of Pyramid, view its ``tox.ini`` file at the root of the repository's version. Consulting the change history -----------------------------
@@ -269,7 +269,7 @@ When such a request reaches a view in your application, the ``request.json_body`` attribute will be available in the view callable body. .. code-block:: javascript .. code-block:: python @view_config(renderer='string') def aview(request): docs/quick_tour.rst
@@ -5,19 +5,20 @@ ===================== Pyramid lets you start small and finish big. This *Quick Tour* of Pyramid is for those who want to evaluate Pyramid, whether you are new to Python web frameworks, or a pro in a hurry. For more detailed treatment of each topic, give the :ref:`quick_tutorial` a try. for those who want to evaluate Pyramid, whether you are new to Python web frameworks, or a pro in a hurry. For more detailed treatment of each topic, give the :ref:`quick_tutorial` a try. Installation ============ Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this Quick Tour, it means: `Python <https://www.python.org/downloads/>`_, a `virtual environment <http://docs.python.org/dev/library/venv.html>`_ (or `virtualenv for Python 2.7 <https://pypi.python.org/pypi/virtualenv>`_), and `setuptools <https://pypi.python.org/pypi/setuptools/>`_. Once you have a standard Python environment setup, getting started with Pyramid is a breeze. Unfortunately "standard" is not so simple in Python. For this Quick Tour, it means `Python <https://www.python.org/downloads/>`_, a `virtual environment <http://docs.python.org/dev/library/venv.html>`_ (or `virtualenv for Python 2.7 <https://pypi.python.org/pypi/virtualenv>`_), and `setuptools <https://pypi.python.org/pypi/setuptools/>`_. As an example, for Python 3.3+ on Linux: @@ -37,32 +38,32 @@ c:\\> env33\\Scripts\\python ez_setup.py c:\\> env33\\Scripts\\easy_install "pyramid==\ |release|\ " Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production support for Python 3 in October 2011). Of course Pyramid runs fine on Python 2.6+, as do the examples in this *Quick Tour*. We're just showing Python 3 a little love (Pyramid had production support for Python 3 in October 2011). .. note:: Why ``easy_install`` and not ``pip``? Some distributions on which Pyramid depends upon have optional C extensions for performance. ``pip`` cannot Why ``easy_install`` and not ``pip``? Some distributions upon which Pyramid depends have optional C extensions for performance. ``pip`` cannot install some binary Python distributions. With ``easy_install``, Windows users are able to obtain binary Python distributions, so they get the benefit of the C extensions without needing a C compiler. Also, there can benefit of the C extensions without needing a C compiler. Also there can be issues when ``pip`` and ``easy_install`` are used side-by-side in the same environment, so we chose to recommend ``easy_install`` for the sake of reducing the complexity of these instructions. .. seealso:: See also: :ref:`Quick Tutorial section on Requirements <qtut_requirements>`, :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`, and :ref:`Installing Pyramid on a Windows System <installing_windows>` :ref:`installing_unix`, :ref:`Before You Install <installing_chapter>`, and :ref:`Installing Pyramid on a Windows System <installing_windows>`. Hello World =========== Microframeworks have shown that learning starts best from a very small first step. Here's a tiny application in Pyramid: Microframeworks have shown that learning starts best from a very small first step. Here's a tiny application in Pyramid: .. literalinclude:: quick_tour/hello_world/app.py :linenos: @@ -79,65 +80,63 @@ New to Python web programming? If so, some lines in the module merit explanation: #. *Line 10*. The ``if __name__ == '__main__':`` is Python's way of saying "Start here when running from the command line". #. *Line 10*. ``if __name__ == '__main__':`` is Python's way of saying "Start here when running from the command line". #. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect :term:`view` code to a particular URL :term:`route`. #. *Lines 11-13*. Use Pyramid's :term:`configurator` to connect :term:`view` code to a particular URL :term:`route`. #. *Lines 6-7*. Implement the view code that generates the :term:`response`. #. *Lines 6-7*. Implement the view code that generates the :term:`response`. #. *Lines 14-16*. Publish a :term:`WSGI` app using an HTTP server. As shown in this example, the :term:`configurator` plays a central role in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. As shown in this example, the :term:`configurator` plays a central role in Pyramid development. Building an application from loosely-coupled parts via :doc:`../narr/configuration` is a central idea in Pyramid, one that we will revisit regurlarly in this *Quick Tour*. .. seealso:: See also: :ref:`Quick Tutorial Hello World <qtut_hello_world>`, :ref:`firstapp_chapter`, and :ref:`Single File Tasks tutorial <tutorials:single-file-tutorial>` :ref:`firstapp_chapter`, and :ref:`Todo List Application in One File <cookbook:single-file-tutorial>`. Handling web requests and responses =================================== Developing for the web means processing web requests. As this is a critical part of a web application, web developers need a robust, mature set of software for web requests. Developing for the web means processing web requests. As this is a critical part of a web application, web developers need a robust, mature set of software for web requests. Pyramid has always fit nicely into the existing world of Python web development (virtual environments, packaging, scaffolding, one of the first to embrace Python 3, etc.). Pyramid turned to the well-regarded :term:`WebOb` Python library for request and response handling. In our example above, Pyramid hands ``hello_world`` a ``request`` that is :ref:`based on WebOb <webob_chapter>`. Pyramid has always fit nicely into the existing world of Python web development (virtual environments, packaging, scaffolding, one of the first to embrace Python 3, etc.). Pyramid turned to the well-regarded :term:`WebOb` Python library for request and response handling. In our example above, Pyramid hands ``hello_world`` a ``request`` that is :ref:`based on WebOb <webob_chapter>`. Let's see some features of requests and responses in action: .. literalinclude:: quick_tour/requests/app.py :pyobject: hello_world In this Pyramid view, we get the URL being visited from ``request.url``. Also, In this Pyramid view, we get the URL being visited from ``request.url``. Also if you visited http://localhost:6543/?name=alice in a browser, the name is included in the body of the response:: URL http://localhost:6543/?name=alice with name: alice Finally, we set the response's content type and return the Response. Finally we set the response's content type, and return the Response. .. seealso:: See also: :ref:`Quick Tutorial Request and Response <qtut_request_response>` and :ref:`webob_chapter` :ref:`Quick Tutorial Request and Response <qtut_request_response>` and :ref:`webob_chapter`. Views ===== For the examples above, the ``hello_world`` function is a "view". In Pyramid, views are the primary way to accept web requests and return responses. For the examples above, the ``hello_world`` function is a "view". In Pyramid views are the primary way to accept web requests and return responses. So far our examples place everything in one file: @@ -149,169 +148,169 @@ - the WSGI application launcher Let's move the views out to their own ``views.py`` module and change the ``app.py`` to scan that module, looking for decorators that set up the views. Let's move the views out to their own ``views.py`` module and change the ``app.py`` to scan that module, looking for decorators that set up the views. First, our revised ``app.py``: First our revised ``app.py``: .. literalinclude:: quick_tour/views/app.py :linenos: We added some more routes, but we also removed the view code. Our views and their registrations (via decorators) are now in a module ``views.py``, which is scanned via ``config.scan('views')``. We added some more routes, but we also removed the view code. Our views and their registrations (via decorators) are now in a module ``views.py``, which is scanned via ``config.scan('views')``. We now have a ``views.py`` module that is focused on handling requests and responses: We now have a ``views.py`` module that is focused on handling requests and responses: .. literalinclude:: quick_tour/views/views.py :linenos: We have four views, each leading to the other. If you start at http://localhost:6543/, you get a response with a link to the next view. The ``hello_view`` (available at the URL ``/howdy``) has a link to the ``redirect_view``, which issues a redirect to the final view. http://localhost:6543/, you get a response with a link to the next view. The ``hello_view`` (available at the URL ``/howdy``) has a link to the ``redirect_view``, which issues a redirect to the final view. Earlier we saw ``config.add_view`` as one way to configure a view. This section introduces ``@view_config``. Pyramid's configuration supports :term:`imperative configuration`, such as the ``config.add_view`` in the previous example. You can also use :term:`declarative configuration`, in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually it is simply a matter of taste. Earlier we saw ``config.add_view`` as one way to configure a view. This section introduces ``@view_config``. Pyramid's configuration supports :term:`imperative configuration`, such as the ``config.add_view`` in the previous example. You can also use :term:`declarative configuration` in which a Python :term:`decorator` is placed on the line above the view. Both approaches result in the same final configuration, thus usually it is simply a matter of taste. .. seealso:: See also: :ref:`Quick Tutorial Views <qtut_views>`, :doc:`../narr/views`, :doc:`../narr/viewconfig`, and :ref:`debugging_view_configuration` :ref:`Quick Tutorial Views <qtut_views>`, :doc:`../narr/views`, :doc:`../narr/viewconfig`, and :ref:`debugging_view_configuration`. Routing ======= Writing web applications usually means sophisticated URL design. We just saw some Pyramid machinery for requests and views. Let's look at features that help in routing. Writing web applications usually means sophisticated URL design. We just saw some Pyramid machinery for requests and views. Let's look at features that help with routing. Above we saw the basics of routing URLs to views in Pyramid: - Your project's "setup" code registers a route name to be used when matching part of the URL - Your project's "setup" code registers a route name to be used when matching part of the URL. - Elsewhere a view is configured to be called for that route name - Elsewhere a view is configured to be called for that route name. .. note:: Why do this twice? Other Python web frameworks let you create a route and associate it with a view in one step. As illustrated in :ref:`routes_need_ordering`, multiple routes might match the same URL pattern. Rather than provide ways to help guess, Pyramid lets you be explicit in ordering. Pyramid also gives facilities to avoid the problem. Why do this twice? Other Python web frameworks let you create a route and associate it with a view in one step. As illustrated in :ref:`routes_need_ordering`, multiple routes might match the same URL pattern. Rather than provide ways to help guess, Pyramid lets you be explicit in ordering. Pyramid also gives facilities to avoid the problem. What if we want part of the URL to be available as data in my view? This route declaration: What if we want part of the URL to be available as data in my view? We can use this route declaration, for example: .. literalinclude:: quick_tour/routing/app.py :start-after: Start Route 1 :end-before: End Route 1 :linenos: :lines: 6 :lineno-start: 6 With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to ``first`` and ``smith`` to ``last``. We can then use this data in our view: With this, URLs such as ``/howdy/amy/smith`` will assign ``amy`` to ``first`` and ``smith`` to ``last``. We can then use this data in our view: .. literalinclude:: quick_tour/routing/views.py :start-after: Start Route 1 :end-before: End Route 1 :linenos: :lines: 5-8 :lineno-start: 5 :emphasize-lines: 3 ``request.matchdict`` contains values from the URL that match the "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. ``request.matchdict`` contains values from the URL that match the "replacement patterns" (the curly braces) in the route declaration. This information can then be used in your view. .. seealso:: See also: :ref:`Quick Tutorial Routing <qtut_routing>`, :doc:`../narr/urldispatch`, :ref:`debug_routematch_section`, and :doc:`../narr/router` :ref:`Quick Tutorial Routing <qtut_routing>`, :doc:`../narr/urldispatch`, :ref:`debug_routematch_section`, and :doc:`../narr/router`. Templating ========== Ouch. We have been making our own ``Response`` and filling the response body with HTML. You usually won't embed an HTML string directly in Python, but instead, will use a templating language. Ouch. We have been making our own ``Response`` and filling the response body with HTML. You usually won't embed an HTML string directly in Python, but instead you will use a templating language. Pyramid doesn't mandate a particular database system, form library, etc. It encourages replaceability. This applies equally to templating, which is fortunate: developers have strong views about template languages. That said, the Pylons Project officially supports bindings for Chameleon, Jinja2, and Mako, so in this step, let's use Chameleon. Pyramid doesn't mandate a particular database system, form library, and so on. It encourages replaceability. This applies equally to templating, which is fortunate: developers have strong views about template languages. That said, the Pylons Project officially supports bindings for Chameleon, Jinja2, and Mako. In this step let's use Chameleon. Let's add ``pyramid_chameleon``, a Pyramid :term:`add-on` which enables Chameleon as a :term:`renderer` in our Pyramid applications: Chameleon as a :term:`renderer` in our Pyramid application: .. code-block:: bash $ easy_install pyramid_chameleon With the package installed, we can include the template bindings into our configuration: With the package installed, we can include the template bindings into our configuration in ``app.py``: .. code-block:: python .. literalinclude:: quick_tour/templating/app.py :linenos: :lines: 6-8 :lineno-start: 6 :emphasize-lines: 2 config.include('pyramid_chameleon') Now lets change our views.py file: Now lets change our ``views.py`` file: .. literalinclude:: quick_tour/templating/views.py :start-after: Start View 1 :end-before: End View 1 :linenos: :emphasize-lines: 4,6 Ahh, that looks better. We have a view that is focused on Python code. Our ``@view_config`` decorator specifies a :term:`renderer` that points to our template file. Our view then simply returns data which is then supplied to our template: Ahh, that looks better. We have a view that is focused on Python code. Our ``@view_config`` decorator specifies a :term:`renderer` that points to our template file. Our view then simply returns data which is then supplied to our template ``hello_world.pt``: .. literalinclude:: quick_tour/templating/hello_world.pt :language: html Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. Since our view returned ``dict(name=request.matchdict['name'])``, we can use ``name`` as a variable in our template via ``${name}``. .. seealso:: See also: :ref:`Quick Tutorial Templating <qtut_templating>`, :doc:`../narr/templates`, :ref:`debugging_templates`, and :ref:`available_template_system_bindings` :doc:`../narr/templates`, :ref:`debugging_templates`, and :ref:`available_template_system_bindings`. Templating with ``jinja2`` ========================== We just said Pyramid doesn't prefer one templating language over another. Time to prove it. Jinja2 is a popular templating system, modeled after Django's templates. Let's add ``pyramid_jinja2``, a Pyramid :term:`add-on` which enables Jinja2 as a :term:`renderer` in our Pyramid applications: Templating with Jinja2 ====================== We just said Pyramid doesn't prefer one templating language over another. Time to prove it. Jinja2 is a popular templating system, modeled after Django's templates. Let's add ``pyramid_jinja2``, a Pyramid :term:`add-on` which enables Jinja2 as a :term:`renderer` in our Pyramid applications: .. code-block:: bash $ easy_install pyramid_jinja2 With the package installed, we can include the template bindings into our configuration: With the package installed, we can include the template bindings into our configuration: .. code-block:: python config.include('pyramid_jinja2') .. literalinclude:: quick_tour/jinja2/app.py :linenos: :lines: 6-8 :lineno-start: 6 :emphasize-lines: 2 The only change in our view is to point the renderer at the ``.jinja2`` file: .. literalinclude:: quick_tour/jinja2/views.py :start-after: Start View 1 :end-before: End View 1 :linenos: :lines: 4-6 :lineno-start: 4 :emphasize-lines: 1 Our Jinja2 template is very similar to our previous template: @@ -319,54 +318,60 @@ :language: html Pyramid's templating add-ons register a new kind of renderer into your application. The renderer registration maps to different kinds of filename extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` renderer. application. The renderer registration maps to different kinds of filename extensions. In this case, changing the extension from ``.pt`` to ``.jinja2`` passed the view response through the ``pyramid_jinja2`` renderer. .. seealso:: See also: :ref:`Quick Tutorial Jinja2 <qtut_jinja2>`, `Jinja2 homepage <http://jinja.pocoo.org/>`_, and :ref:`pyramid_jinja2 Overview <jinja2:overview>` :ref:`Quick Tutorial Jinja2 <qtut_jinja2>`, `Jinja2 homepage <http://jinja.pocoo.org/>`_, and :ref:`pyramid_jinja2 Overview <jinja2:overview>`. Static assets ============= Of course the Web is more than just markup. You need static assets: CSS, JS, and images. Let's point our web app at a directory where Pyramid will serve some static assets. First another call to the Of course the Web is more than just markup. You need static assets: CSS, JS, and images. Let's point our web app at a directory from which Pyramid will serve some static assets. First let's make another call to the :term:`configurator`: .. literalinclude:: quick_tour/static_assets/app.py :start-after: Start Static 1 :end-before: End Static 1 :linenos: :lines: 6-8 :lineno-start: 6 :emphasize-lines: 2 This tells our WSGI application to map requests under http://localhost:6543/static/ to files and directories inside a ``static`` directory alongside our Python module. http://localhost:6543/static/ to files and directories inside a ``static`` directory alongside our Python module. Next make a directory named ``static``, and place ``app.css`` inside: .. literalinclude:: quick_tour/static_assets/static/app.css :language: css All we need to do now is point to it in the ``<head>`` of our Jinja2 template: All we need to do now is point to it in the ``<head>`` of our Jinja2 template, ``hello_world.jinja2``: .. literalinclude:: quick_tour/static_assets/hello_world.pt :language: html :start-after: Start Link 1 :end-before: End Link 1 .. literalinclude:: quick_tour/static_assets/hello_world.jinja2 :language: jinja :linenos: :lines: 4-6 :lineno-start: 4 :emphasize-lines: 2 This link presumes that our CSS is at a URL starting with ``/static/``. What if the site is later moved under ``/somesite/static/``? Or perhaps a web developer changes the arrangement on disk? Pyramid provides a helper to allow flexibility on URL generation: This link presumes that our CSS is at a URL starting with ``/static/``. What if the site is later moved under ``/somesite/static/``? Or perhaps a web developer changes the arrangement on disk? Pyramid provides a helper to allow flexibility on URL generation: .. literalinclude:: quick_tour/static_assets/hello_world.pt :language: html :start-after: Start Link 2 :end-before: End Link 2 .. literalinclude:: quick_tour/static_assets/hello_world_static.jinja2 :language: jinja :linenos: :lines: 4-6 :lineno-start: 4 :emphasize-lines: 2 By using ``request.static_url`` to generate the full URL to the static assets, you both ensure you stay in sync with the configuration and @@ -374,38 +379,48 @@ .. seealso:: See also: :ref:`Quick Tutorial Static Assets <qtut_static_assets>`, :doc:`../narr/assets`, :ref:`preventing_http_caching`, and :ref:`influencing_http_caching` :doc:`../narr/assets`, :ref:`preventing_http_caching`, and :ref:`influencing_http_caching`. Returning JSON ============== Modern web apps are more than rendered HTML. Dynamic pages now use JavaScript to update the UI in the browser by requesting server data as JSON. Pyramid supports this with a JSON renderer: Modern web apps are more than rendered HTML. Dynamic pages now use JavaScript to update the UI in the browser by requesting server data as JSON. Pyramid supports this with a JSON renderer: .. literalinclude:: quick_tour/json/views.py :start-after: Start View 1 :end-before: End View 2 :linenos: :lines: 9- :lineno-start: 9 This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON and set the appropriate HTTP headers. This wires up a view that returns some data through the JSON :term:`renderer`, which calls Python's JSON support to serialize the data into JSON, and sets the appropriate HTTP headers. We also need to add a route to ``app.py`` so that our app will know how to respond to a request for ``hello.json``. .. literalinclude:: quick_tour/json/app.py :linenos: :lines: 6-8 :lineno-start: 6 :emphasize-lines: 2 .. seealso:: See also: :ref:`Quick Tutorial JSON <qtut_json>`, :ref:`views_which_use_a_renderer`, :ref:`json_renderer`, and :ref:`adding_and_overriding_renderers` :ref:`Quick Tutorial JSON <qtut_json>`, :ref:`views_which_use_a_renderer`, :ref:`json_renderer`, and :ref:`adding_and_overriding_renderers`. View classes ============ So far our views have been simple, free-standing functions. Many times your views are related: different ways to look at or work on the same data, or a REST API that handles multiple operations. Grouping these together as a :ref:`view class <class_as_view>` makes sense. So far our views have been simple, free-standing functions. Many times your views are related. They may have different ways to look at or work on the same data, or they may be a REST API that handles multiple operations. Grouping these together as a :ref:`view class <class_as_view>` makes sense and achieves the following goals. - Group views @@ -413,86 +428,85 @@ - Share some state and helpers The following shows a "Hello World" example with three operations: view a form, save a change, or press the delete button: The following shows a "Hello World" example with three operations: view a form, save a change, or press the delete button in our ``views.py``: .. literalinclude:: quick_tour/view_classes/views.py :start-after: Start View 1 :end-before: End View 1 :linenos: :lines: 7- :lineno-start: 7 As you can see, the three views are logically grouped together. Specifically: As you can see, the three views are logically grouped together. Specifically: - The first view is returned when you go to ``/howdy/amy``. This URL is mapped to the ``hello`` route that we centrally set using the optional - The first view is returned when you go to ``/howdy/amy``. This URL is mapped to the ``hello`` route that we centrally set using the optional ``@view_defaults``. - The second view is returned when the form data contains a field with ``form.edit``, such as clicking on ``<input type="submit" name="form.edit" value="Save">``. This rule is specified in the ``@view_config`` for that view. ``form.edit``, such as clicking on ``<input type="submit" name="form.edit" value="Save">``. This rule is specified in the ``@view_config`` for that view. - The third view is returned when clicking on a button such as ``<input type="submit" name="form.delete" value="Delete">``. - The third view is returned when clicking on a button such as ``<input type="submit" name="form.delete" value="Delete">``. Only one route is needed, stated in one place atop the view class. Also, the assignment of ``name`` is done in the ``__init__`` function. Our templates can then use ``{{ view.name }}``. Only one route is needed, stated in one place atop the view class. Also, the assignment of ``name`` is done in the ``__init__`` function. Our templates can then use ``{{ view.name }}``. Pyramid view classes, combined with built-in and custom predicates, have much more to offer: Pyramid view classes, combined with built-in and custom predicates, have much more to offer: - All the same view configuration parameters as function views - One route leading to multiple views, based on information in the request or data such as ``request_param``, ``request_method``, ``accept``, ``header``, ``xhr``, ``containment``, and ``custom_predicates`` - One route leading to multiple views, based on information in the request or data such as ``request_param``, ``request_method``, ``accept``, ``header``, ``xhr``, ``containment``, and ``custom_predicates`` .. seealso:: See also: :ref:`Quick Tutorial View Classes <qtut_view_classes>`, :ref:`Quick Tutorial More View Classes <qtut_more_view_classes>`, and :ref:`class_as_view` :ref:`Quick Tutorial View Classes <qtut_view_classes>`, :ref:`Quick Tutorial More View Classes <qtut_more_view_classes>`, and :ref:`class_as_view`. Quick project startup with scaffolds ==================================== So far we have done all of our *Quick Tour* as a single Python file. No Python packages, no structure. Most Pyramid projects, though, aren't developed this way. So far we have done all of our *Quick Tour* as a single Python file. No Python packages, no structure. Most Pyramid projects, though, aren't developed this way. To ease the process of getting started, Pyramid provides *scaffolds* that generate sample projects from templates in Pyramid and Pyramid add-ons. Pyramid's ``pcreate`` command can list the available scaffolds: To ease the process of getting started, Pyramid provides *scaffolds* that generate sample projects from templates in Pyramid and Pyramid add-ons. Pyramid's ``pcreate`` command can list the available scaffolds: .. code-block:: bash $ pcreate --list Available scaffolds: alchemy: Pyramid SQLAlchemy project using url dispatch pyramid_jinja2_starter: pyramid jinja2 starter project pyramid_jinja2_starter: Pyramid Jinja2 starter project starter: Pyramid starter project zodb: Pyramid ZODB project using traversal The ``pyramid_jinja2`` add-on gave us a scaffold that we can use. From the parent directory of where we want our Python package to be generated, let's use that scaffold to make our project: The ``pyramid_jinja2`` add-on gave us a scaffold that we can use. From the parent directory of where we want our Python package to be generated, let's use that scaffold to make our project: .. code-block:: bash $ pcreate --scaffold pyramid_jinja2_starter hello_world We next use the normal Python command to set up our package for development: We next use the normal Python command to set up our package for development: .. code-block:: bash $ cd hello_world $ python ./setup.py develop We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This includes a new way of running your application: We are moving in the direction of a full-featured Pyramid project, with a proper setup for Python standards (packaging) and Pyramid configuration. This includes a new way of running your application: .. code-block:: bash @@ -508,28 +522,27 @@ Application running with ``pserve`` =================================== Prior to scaffolds, our project mixed a number of operational details into our code. Why should my main code care which HTTP server I want and what port number to run on? Prior to scaffolds, our project mixed a number of operational details into our code. Why should my main code care which HTTP server I want and what port number to run on? ``pserve`` is Pyramid's application runner, separating operational details from your code. When you install Pyramid, a small command program called ``pserve`` is written to your ``bin`` directory. This program is an executable Python module. It's very small, getting most of its brains via import. ``pserve`` is Pyramid's application runner, separating operational details from your code. When you install Pyramid, a small command program called ``pserve`` is written to your ``bin`` directory. This program is an executable Python module. It's very small, getting most of its brains via import. You can run ``pserve`` with ``--help`` to see some of its options. Doing so reveals that you can ask ``pserve`` to watch your development files and reload the server when they change: You can run ``pserve`` with ``--help`` to see some of its options. Doing so reveals that you can ask ``pserve`` to watch your development files and reload the server when they change: .. code-block:: bash $ pserve development.ini --reload The ``pserve`` command has a number of other options and operations. Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to ``pserve``. Let's take a look at this configuration file. The ``pserve`` command has a number of other options and operations. Most of the work, though, comes from your project's wiring, as expressed in the configuration file you supply to ``pserve``. Let's take a look at this configuration file. .. seealso:: See also: :ref:`what_is_this_pserve_thing` @@ -537,21 +550,18 @@ Configuration with ``.ini`` files ================================= Earlier in *Quick Tour* we first met Pyramid's configuration system. At that point we did all configuration in Python code. For example, the port number chosen for our HTTP server was right there in Python code. Our scaffold has moved this decision and more into the ``development.ini`` file: Earlier in *Quick Tour* we first met Pyramid's configuration system. At that point we did all configuration in Python code. For example, the port number chosen for our HTTP server was right there in Python code. Our scaffold has moved this decision and more into the ``development.ini`` file: .. literalinclude:: quick_tour/package/development.ini :language: ini Let's take a quick high-level look. First the ``.ini`` file is divided into sections: Let's take a quick high-level look. First the ``.ini`` file is divided into sections: - ``[app:hello_world]`` configures our WSGI app - ``[pipeline:main]`` sets up our WSGI "pipeline" - ``[app:main]`` configures our WSGI app - ``[server:main]`` holds our WSGI server settings @@ -559,23 +569,23 @@ We have a few decisions made for us in this configuration: #. *Choice of web server:* ``use = egg:pyramid#wsgiref`` tells ``pserve`` to use the ``wsgiref`` server that is wrapped in the Pyramid package. #. *Choice of web server:* ``use = egg:hello_world`` tells ``pserve`` to use the ``waitress`` server. #. *Port number:* ``port = 6543`` tells ``wsgiref`` to listen on port 6543. #. *Port number:* ``port = 6543`` tells ``waitress`` to listen on port 6543. #. *WSGI app:* What package has our WSGI application in it? ``use = egg:hello_world`` in the app section tells the configuration what application to load. ``use = egg:hello_world`` in the app section tells the configuration what application to load. #. *Easier development by automatic template reloading:* In development mode, you shouldn't have to restart the server when editing a Jinja2 template. ``reload_templates = true`` sets this policy, which might be different in production. ``pyramid.reload_templates = true`` sets this policy, which might be different in production. Additionally the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well as traceback information. Additionally the ``development.ini`` generated by this scaffold wired up Python's standard logging. We'll now see in the console, for example, a log on every request that comes in, as well as traceback information. .. seealso:: See also: :ref:`Quick Tutorial Application Configuration <qtut_ini>`, @@ -587,76 +597,77 @@ ======================================== As we introduce the basics, we also want to show how to be productive in development and debugging. For example, we just discussed template reloading and earlier we showed ``--reload`` for application reloading. development and debugging. For example, we just discussed template reloading and earlier we showed ``--reload`` for application reloading. ``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes several tools available in your browser. Adding it to your project illustrates several points about configuration. ``pyramid_debugtoolbar`` is a popular Pyramid add-on which makes several tools available in your browser. Adding it to your project illustrates several points about configuration. First change your ``setup.py`` to say: The scaffold ``pyramid_jinja2_starter`` is already configured to include the add-on ``pyramid_debugtoolbar`` in its ``setup.py``: .. literalinclude:: quick_tour/package/setup.py :start-after: Start Requires :end-before: End Requires :language: python :linenos: :lineno-start: 11 :lines: 11-16 ...and rerun your setup: It was installed when you previously ran: .. code-block:: bash $ python ./setup.py develop The Python package ``pyramid_debugtoolbar`` is now installed into our environment. The package is a Pyramid add-on, which means we need to include its configuration into our web application. We could do this with imperative configuration, as we did above for the ``pyramid_jinja2`` add-on: The ``pyramid_debugtoolbar`` package is a Pyramid add-on, which means we need to include its configuration into our web application. The ``pyramid_jinja2`` add-on already took care of this for us in its ``__init__.py``: .. literalinclude:: quick_tour/package/hello_world/__init__.py :start-after: Start Include :end-before: End Include :language: python :linenos: :lineno-start: 16 :lines: 19 Now that we have a configuration file, we can use the ``pyramid.includes`` facility and place this in our ``development.ini`` instead: And it uses the ``pyramid.includes`` facility in our ``development.ini``: .. literalinclude:: quick_tour/package/development.ini :language: ini :start-after: Start Includes :end-before: End Includes :linenos: :lineno-start: 15 :lines: 15-16 You'll now see an attractive (and collapsible) menu in the right of your browser, providing introspective access to debugging information. Even better, if your web application generates an error, you will see a nice traceback on the screen. When you want to disable this toolbar, there's no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. You'll now see a Pyramid logo on the right side of your browser window, which when clicked opens a new window that provides introspective access to debugging information. Even better, if your web application generates an error, you will see a nice traceback on the screen. When you want to disable this toolbar, there's no need to change code: you can remove it from ``pyramid.includes`` in the relevant ``.ini`` configuration file. .. seealso:: See also: :ref:`Quick Tutorial pyramid_debugtoolbar <qtut_debugtoolbar>` and :ref:`Quick Tutorial pyramid_debugtoolbar <qtut_debugtoolbar>` and :ref:`pyramid_debugtoolbar <toolbar:overview>` Unit tests and ``nose`` ======================= Yikes! We got this far and we haven't yet discussed tests. This is particularly egregious, as Pyramid has had a deep commitment to full test coverage since before its release. Yikes! We got this far and we haven't yet discussed tests. This is particularly egregious, as Pyramid has had a deep commitment to full test coverage since before its release. Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module with one unit test in it. To run it, let's install the handy ``nose`` test runner by editing ``setup.py``. While we're at it, we'll throw in the ``coverage`` tool which yells at us for code that isn't tested: Our ``pyramid_jinja2_starter`` scaffold generated a ``tests.py`` module with one unit test in it. To run it, let's install the handy ``nose`` test runner by editing ``setup.py``. While we're at it, we'll throw in the ``coverage`` tool which yells at us for code that isn't tested. Edit line 36 so it becomes the following: .. code-block:: python :linenos: :lineno-start: 36 setup(name='hello_world', # Some lines removed... extras_require={ tests_require={ 'testing': ['nose', 'coverage'], } ) }, We changed ``setup.py`` which means we need to rerun ``python ./setup.py develop``. We can now run all our tests: @@ -667,136 +678,150 @@ . Name Stmts Miss Cover Missing --------------------------------------------------- hello_world 12 8 33% 11-23 hello_world.models 5 1 80% 8 hello_world.tests 14 0 100% hello_world.views 4 0 100% hello_world 11 8 27% 11-23 hello_world.models 5 1 80% 8 hello_world.tests 14 0 100% hello_world.views 4 0 100% --------------------------------------------------- TOTAL 35 9 74% TOTAL 34 9 74% ---------------------------------------------------------------------- Ran 1 test in 0.931s Ran 1 test in 0.009s OK Our unit test passed. What did our test look like? .. literalinclude:: quick_tour/package/hello_world/tests.py :linenos: Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. Pyramid supplies helpers for test writing, which we use in the test setup and teardown. Our one test imports the view, makes a dummy request, and sees if the view returns what we expected. .. seealso:: See also: :ref:`Quick Tutorial Unit Testing <qtut_unit_testing>`, :ref:`Quick Tutorial Functional Testing <qtut_functional_testing>`, and :ref:`Quick Tutorial Unit Testing <qtut_unit_testing>`, :ref:`Quick Tutorial Functional Testing <qtut_functional_testing>`, and :ref:`testing_chapter` Logging ======= It's important to know what is going on inside our web application. In development we might need to collect some output. In production we might need to detect situations when other people use the site. We need *logging*. It's important to know what is going on inside our web application. In development we might need to collect some output. In production we might need to detect situations when other people use the site. We need *logging*. Fortunately Pyramid uses the normal Python approach to logging. The scaffold generated in your ``development.ini`` has a number of lines that configure the logging for you to some reasonable defaults. You then see messages sent by Pyramid (for example, when a new request comes in). Fortunately Pyramid uses the normal Python approach to logging. The scaffold generated in your ``development.ini`` has a number of lines that configure the logging for you to some reasonable defaults. You then see messages sent by Pyramid (for example, when a new request comes in). Maybe you would like to log messages in your code? In your Python module, import and set up the logging: Maybe you would like to log messages in your code? In your Python module, import and set up the logging: .. literalinclude:: quick_tour/package/hello_world/views.py :start-after: Start Logging 1 :end-before: End Logging 1 :language: python :linenos: :lineno-start: 3 :lines: 3-4 You can now, in your code, log messages: .. literalinclude:: quick_tour/package/hello_world/views.py :start-after: Start Logging 2 :end-before: End Logging 2 :language: python :linenos: :lineno-start: 9 :lines: 9-10 :emphasize-lines: 2 This will log ``Some Message`` at a ``debug`` log level to the application-configured logger in your ``development.ini``. What controls that? These sections in the configuration file: This will log ``Some Message`` at a ``debug`` log level to the application-configured logger in your ``development.ini``. What controls that? These emphasized sections in the configuration file: .. literalinclude:: quick_tour/package/development.ini :language: ini :start-after: Start Sphinx Include :end-before: End Sphinx Include :linenos: :lineno-start: 36 :lines: 36-52 :emphasize-lines: 1-2,14-17 Our application, a package named ``hello_world``, is set up as a logger and configured to log messages at a ``DEBUG`` or higher level. When you visit http://localhost:6543, your console will now show:: Our application, a package named ``hello_world``, is set up as a logger and configured to log messages at a ``DEBUG`` or higher level. When you visit http://localhost:6543, your console will now show:: 2013-08-09 10:42:42,968 DEBUG [hello_world.views][MainThread] Some Message 2016-01-18 13:55:55,040 DEBUG [hello_world.views:10][waitress] Some Message .. seealso:: See also: :ref:`Quick Tutorial Logging <qtut_logging>` and :ref:`logging_chapter` :ref:`Quick Tutorial Logging <qtut_logging>` and :ref:`logging_chapter`. Sessions ======== When people use your web application, they frequently perform a task that requires semi-permanent data to be saved. For example, a shopping cart. This is called a :term:`session`. When people use your web application, they frequently perform a task that requires semi-permanent data to be saved. For example, a shopping cart. This is called a :term:`session`. Pyramid has basic built-in support for sessions. Third party packages such as ``pyramid_redis_sessions`` provide richer session support. Or you can create your own custom sessioning engine. Let's take a look at the :doc:`built-in sessioning support <../narr/sessions>`. In our ``__init__.py`` we first import the kind of sessioning we want: Pyramid has basic built-in support for sessions. Third party packages such as ``pyramid_redis_sessions`` provide richer session support. Or you can create your own custom sessioning engine. Let's take a look at the :doc:`built-in sessioning support <../narr/sessions>`. In our ``__init__.py`` we first import the kind of sessioning we want: .. literalinclude:: quick_tour/package/hello_world/__init__.py :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 :language: python :linenos: :lineno-start: 2 :lines: 2-3 :emphasize-lines: 2 .. warning:: As noted in the session docs, this example implementation is not intended for use in settings with security implications. As noted in the session docs, this example implementation is not intended for use in settings with security implications. Now make a "factory" and pass it to the :term:`configurator`'s ``session_factory`` argument: .. literalinclude:: quick_tour/package/hello_world/__init__.py :start-after: Start Sphinx Include 2 :end-before: End Sphinx Include 2 :language: python :linenos: :lineno-start: 13 :lines: 13-17 :emphasize-lines: 3-5 Pyramid's :term:`request` object now has a ``session`` attribute that we can use in our view code: Pyramid's :term:`request` object now has a ``session`` attribute that we can use in our view code in ``views.py``: .. literalinclude:: quick_tour/package/hello_world/views.py :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 :language: python :linenos: :lineno-start: 9 :lines: 9-15 :emphasize-lines: 3-7 With this, each reload will increase the counter displayed in our Jinja2 template: We need to update our Jinja2 template to show counter increment in the session: .. literalinclude:: quick_tour/package/hello_world/templates/mytemplate.jinja2 :language: jinja :start-after: Start Sphinx Include 1 :end-before: End Sphinx Include 1 :linenos: :lineno-start: 40 :lines: 40-42 :emphasize-lines: 3 .. seealso:: See also: :ref:`Quick Tutorial Sessions <qtut_sessions>`, :ref:`sessions_chapter`, :ref:`flash_messages`, :ref:`session_module`, and :term:`pyramid_redis_sessions`. :ref:`Quick Tutorial Sessions <qtut_sessions>`, :ref:`sessions_chapter`, :ref:`flash_messages`, :ref:`session_module`, and :term:`pyramid_redis_sessions`. Databases ========= Web applications mean data. Data means databases. Frequently SQL databases. SQL databases frequently mean an "ORM" (object-relational mapper.) In Python, ORM usually leads to the mega-quality *SQLAlchemy*, a Python package that greatly eases working with databases. Web applications mean data. Data means databases. Frequently SQL databases. SQL databases frequently mean an "ORM" (object-relational mapper.) In Python, ORM usually leads to the mega-quality *SQLAlchemy*, a Python package that greatly eases working with databases. Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! Pyramid and SQLAlchemy are great friends. That friendship includes a scaffold! .. code-block:: bash @@ -804,50 +829,53 @@ $ cd sqla_demo $ python setup.py develop We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite database with tables. Let's run it and then start the application: We now have a working sample SQLAlchemy application with all dependencies installed. The sample project provides a console script to initialize a SQLite database with tables. Let's run it, then start the application: .. code-block:: bash $ initialize_sqla_demo_db development.ini $ pserve development.ini The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The scaffold generated a sample model: The ORM eases the mapping of database structures into a programming language. SQLAlchemy uses "models" for this mapping. The scaffold generated a sample model: .. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py :start-after: Start Sphinx Include :end-before: End Sphinx Include :language: python :linenos: :lineno-start: 21 :lines: 21- View code, which mediates the logic between web requests and the rest of the system, can then easily get at the data thanks to SQLAlchemy: View code, which mediates the logic between web requests and the rest of the system, can then easily get at the data thanks to SQLAlchemy: .. literalinclude:: quick_tour/sqla_demo/sqla_demo/views.py :start-after: Start Sphinx Include :end-before: End Sphinx Include :language: python :linenos: :lineno-start: 12 :lines: 12-18 :emphasize-lines: 4 .. seealso:: See also: :ref:`Quick Tutorial Databases <qtut_databases>`, `SQLAlchemy <http://www.sqlalchemy.org/>`_, :ref:`making_a_console_script`, :ref:`bfg_sql_wiki_tutorial`, and :ref:`Application Transactions With pyramid_tm <tm:overview>` :ref:`Quick Tutorial Databases <qtut_databases>`, `SQLAlchemy <http://www.sqlalchemy.org/>`_, :ref:`making_a_console_script`, :ref:`bfg_sql_wiki_tutorial`, and :ref:`Application Transactions with pyramid_tm <tm:overview>`. Forms ===== Developers have lots of opinions about web forms, and thus there are many form libraries for Python. Pyramid doesn't directly bundle a form library, but *Deform* is a popular choice for forms, along with its related *Colander* schema system. Developers have lots of opinions about web forms, thus there are many form libraries for Python. Pyramid doesn't directly bundle a form library, but *Deform* is a popular choice for forms, along with its related *Colander* schema system. As an example, imagine we want a form that edits a wiki page. The form should have two fields on it, one of them a required title and the other a rich text editor for the body. With Deform we can express this as a Colander schema: As an example, imagine we want a form that edits a wiki page. The form should have two fields on it, one of them a required title and the other a rich text editor for the body. With Deform we can express this as a Colander schema: .. code-block:: python @@ -858,8 +886,8 @@ widget=deform.widget.RichTextWidget() ) With this in place, we can render the HTML for a form, perhaps with form data from an existing page: With this in place, we can render the HTML for a form, perhaps with form data from an existing page: .. code-block:: python @@ -883,20 +911,18 @@ page['title'] = appstruct['title'] page['body'] = appstruct['body'] Deform and Colander provide a very flexible combination for forms, widgets, schemas, and validation. Recent versions of Deform also include a :ref:`retail mode <deform:retail>` for gaining Deform features on custom forms. Deform and Colander provide a very flexible combination for forms, widgets, schemas, and validation. Recent versions of Deform also include a :ref:`retail mode <deform:retail>` for gaining Deform features on custom forms. Also the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Twitter Bootstrap and more powerful widgets from Chosen. Also the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform widgets using attractive CSS from Twitter Bootstrap and more powerful widgets from Chosen. .. seealso:: See also: :ref:`Quick Tutorial Forms <qtut_forms>`, :ref:`Deform <deform:overview>`, :ref:`Colander <colander:overview>`, and `deform_bootstrap <https://pypi.python.org/pypi/deform_bootstrap>`_ :ref:`Quick Tutorial Forms <qtut_forms>`, :ref:`Deform <deform:overview>`, :ref:`Colander <colander:overview>`, and `deform_bootstrap <https://pypi.python.org/pypi/deform_bootstrap>`_. Conclusion ========== docs/quick_tour/awesome/CHANGES.txt
File was deleted docs/quick_tour/awesome/MANIFEST.in
File was deleted docs/quick_tour/awesome/README.txt
File was deleted docs/quick_tour/awesome/awesome/__init__.py
File was deleted docs/quick_tour/awesome/awesome/locale/awesome.pot
File was deleted docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.moBinary files differ
docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.po
File was deleted docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.moBinary files differ
docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.po
File was deleted docs/quick_tour/awesome/awesome/models.py
File was deleted docs/quick_tour/awesome/awesome/static/favicon.icoBinary files differ
docs/quick_tour/awesome/awesome/static/logo.pngBinary files differ
docs/quick_tour/awesome/awesome/static/pylons.css
File was deleted docs/quick_tour/awesome/awesome/templates/mytemplate.jinja2
File was deleted docs/quick_tour/awesome/awesome/tests.py
File was deleted docs/quick_tour/awesome/awesome/views.py
File was deleted docs/quick_tour/awesome/development.ini
File was deleted docs/quick_tour/awesome/message-extraction.ini
File was deleted docs/quick_tour/awesome/setup.py
File was deleted docs/quick_tour/hello_world/app.py
@@ -13,4 +13,4 @@ config.add_view(hello_world, route_name='hello') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/jinja2/app.py
@@ -8,4 +8,4 @@ config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/jinja2/views.py
@@ -1,8 +1,6 @@ from pyramid.view import view_config # Start View 1 @view_config(route_name='hello', renderer='hello_world.jinja2') # End View 1 def hello_world(request): return dict(name=request.matchdict['name']) docs/quick_tour/json/app.py
@@ -1,7 +1,5 @@ from wsgiref.simple_server import make_server from pyramid.config import Configurator if __name__ == '__main__': config = Configurator() @@ -12,4 +10,4 @@ config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/json/hello_world.jinja2
@@ -1,8 +1,8 @@ <!DOCTYPE html> <html lang="en"> <head> <title>Quick Glance</title> <link rel="stylesheet" href="/static/app.css"/> <title>Hello World</title> <link rel="stylesheet" href="{{ request.static_url('static/app.css') }}"/> </head> <body> <h1>Hello {{ name }}!</h1> docs/quick_tour/json/hello_world.pt
File was deleted docs/quick_tour/json/views.py
@@ -1,13 +1,11 @@ from pyramid.view import view_config @view_config(route_name='hello', renderer='hello_world.pt') @view_config(route_name='hello', renderer='hello_world.jinja2') def hello_world(request): return dict(name=request.matchdict['name']) # Start View 1 @view_config(route_name='hello_json', renderer='json') def hello_json(request): return [1, 2, 3] # End View 1 docs/quick_tour/package/MANIFEST.in
@@ -1,2 +1,2 @@ include *.txt *.ini *.cfg *.rst recursive-include hello_world *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml recursive-include hello_world *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.jinja2 *.js *.html *.xml docs/quick_tour/package/development.ini
@@ -1,36 +1,40 @@ # Start Includes [app:hello_world] pyramid.includes = pyramid_debugtoolbar # End Includes use = egg:hello_world reload_templates = true debug_authorization = false debug_notfound = false debug_routematch = false debug_templates = true default_locale_name = en jinja2.directories = hello_world:templates ### # app configuration # http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/narr/environment.html ### [pipeline:main] pipeline = hello_world [app:main] use = egg:hello_world pyramid.reload_templates = true pyramid.debug_authorization = false pyramid.debug_notfound = false pyramid.debug_routematch = false pyramid.debug_templates = true pyramid.default_locale_name = en pyramid.includes = pyramid_debugtoolbar # By default, the toolbar only appears for clients from IP addresses # '127.0.0.1' and '::1'. # debugtoolbar.hosts = 127.0.0.1 ::1 ### # wsgi server configuration ### [server:main] use = egg:pyramid#wsgiref host = 0.0.0.0 use = egg:waitress#main host = 127.0.0.1 port = 6543 # Begin logging configuration ### # logging configuration # http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/narr/logging.html ### # Start Sphinx Include [loggers] keys = root, hello_world [logger_hello_world] level = DEBUG handlers = qualname = hello_world # End Sphinx Include [handlers] keys = console @@ -42,6 +46,11 @@ level = INFO handlers = console [logger_hello_world] level = DEBUG handlers = qualname = hello_world [handler_console] class = StreamHandler args = (sys.stderr,) @@ -49,6 +58,4 @@ formatter = generic [formatter_generic] format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s # End logging configuration format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s docs/quick_tour/package/hello_world/__init__.py
@@ -1,10 +1,7 @@ from pyramid.config import Configurator from pyramid_jinja2 import renderer_factory # Start Sphinx Include 1 from hello_world.resources import get_root from pyramid.session import SignedCookieSessionFactory # End Sphinx Include 1 from hello_world.models import get_root def main(global_config, **settings): """ This function returns a WSGI application. @@ -15,20 +12,15 @@ settings = dict(settings) settings.setdefault('jinja2.i18n.domain', 'hello_world') # Start Sphinx Include 2 my_session_factory = SignedCookieSessionFactory('itsaseekreet') config = Configurator(root_factory=get_root, settings=settings, session_factory=my_session_factory) # End Sphinx Include 2 config.add_translation_dirs('locale/') # Start Include config.include('pyramid_jinja2') # End Include config.add_static_view('static', 'static') config.add_view('hello_world.views.my_view', context='hello_world.models.MyModel', renderer="mytemplate.jinja2") context='hello_world.resources.MyResource', renderer="templates/mytemplate.jinja2") return config.make_wsgi_app() docs/quick_tour/package/hello_world/init.py
File was deleted docs/quick_tour/package/hello_world/models.py
File was deleted docs/quick_tour/package/hello_world/resources.py
New file @@ -0,0 +1,8 @@ class MyResource(object): pass root = MyResource() def get_root(request): return root docs/quick_tour/package/hello_world/static/logo.pngBinary files differ
docs/quick_tour/package/hello_world/static/pylons.css
File was deleted docs/quick_tour/package/hello_world/static/pyramid-16x16.png
New file @@ -0,0 +1,153 @@ @import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700); body { font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-weight: 300; color: #ffffff; background: #bc2131; } h1, h2, h3, h4, h5, h6 { font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-weight: 300; } p { font-weight: 300; } .font-normal { font-weight: 400; } .font-semi-bold { font-weight: 600; } .font-bold { font-weight: 700; } .starter-template { margin-top: 250px; } .starter-template .content { margin-left: 10px; } .starter-template .content h1 { margin-top: 10px; font-size: 60px; } .starter-template .content h1 .smaller { font-size: 40px; color: #f2b7bd; } .starter-template .content .lead { font-size: 25px; color: #f2b7bd; } .starter-template .content .lead .font-normal { color: #ffffff; } .starter-template .links { float: right; right: 0; margin-top: 125px; } .starter-template .links ul { display: block; padding: 0; margin: 0; } .starter-template .links ul li { list-style: none; display: inline; margin: 0 10px; } .starter-template .links ul li:first-child { margin-left: 0; } .starter-template .links ul li:last-child { margin-right: 0; } .starter-template .links ul li.current-version { color: #f2b7bd; font-weight: 400; } .starter-template .links ul li a { color: #ffffff; } .starter-template .links ul li a:hover { text-decoration: underline; } .starter-template .links ul li .icon-muted { color: #eb8b95; margin-right: 5px; } .starter-template .links ul li:hover .icon-muted { color: #ffffff; } .starter-template .copyright { margin-top: 10px; font-size: 0.9em; color: #f2b7bd; text-transform: lowercase; float: right; right: 0; } @media (max-width: 1199px) { .starter-template .content h1 { font-size: 45px; } .starter-template .content h1 .smaller { font-size: 30px; } .starter-template .content .lead { font-size: 20px; } } @media (max-width: 991px) { .starter-template { margin-top: 0; } .starter-template .logo { margin: 40px auto; } .starter-template .content { margin-left: 0; text-align: center; } .starter-template .content h1 { margin-bottom: 20px; } .starter-template .links { float: none; text-align: center; margin-top: 60px; } .starter-template .copyright { float: none; text-align: center; } } @media (max-width: 767px) { .starter-template .content h1 .smaller { font-size: 25px; display: block; } .starter-template .content .lead { font-size: 16px; } .starter-template .links { margin-top: 40px; } .starter-template .links ul li { display: block; margin: 0; } .starter-template .links ul li .icon-muted { display: none; } .starter-template .copyright { margin-top: 20px; } }
@@ -1,90 +1,72 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>The Pyramid Web Framework</title> <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> <meta name="keywords" content="python web application" /> <meta name="description" content="pyramid web application" /> <link rel="shortcut icon" href="{{request.application_url}}/static/favicon.ico" /> <link rel="stylesheet" href="{{request.application_url}}/static/pylons.css" type="text/css" media="screen" charset="utf-8" /> <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&subset=latin" type="text/css" media="screen" charset="utf-8" /> <!--[if !IE 7]> <style type="text/css"> #wrap {display:table;height:100%} </style> <![endif]--> <style type="text/css"> .locale { text-align: center; } .locale-name { font-weight: bold; } </style> </head> <body> <div id="wrap"> <div id="header"> <div class="header">The Pyramid Web Framework</div> </div> <div id="top"> <div class="top align-center"> <img src="{{request.application_url}}/static/logo.png" width="300" height="80" alt="Logo"/> <p class="app-welcome"> Welcome to <span class="app-name">{{project}}</span>, an application generated by<br/> the Pyramid Web Framework. </p> </div> </div> <div id="bottom"> <div class="locale"> <h2>{% trans %}Hello!{% endtrans %}</h2> <!-- Start Sphinx Include 1 --> <p>Counter: {{ request.session.counter }}</p> <!-- End Sphinx Include 1 --> <p>Request performed with <span class="locale-name">{{ request.locale_name }}</span> locale.</p> <!DOCTYPE html> <html lang="{{request.locale_name}}"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="description" content="pyramid web application"> <meta name="author" content="Pylons Project"> <link rel="shortcut icon" href="{{request.static_url('hello_world:static/pyramid-16x16.png')}}"> <title>Starter Scaffold for Pyramid Jinja2</title> <!-- Bootstrap core CSS --> <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet"> <!-- Custom styles for this scaffold --> <link href="{{request.static_url('hello_world:static/theme.css')}}" rel="stylesheet"> <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> <!--[if lt IE 9]> <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script> <![endif]--> </head> <body> <div class="starter-template"> <div class="container"> <div class="row"> <div class="col-md-2"> <img class="logo img-responsive" src="{{request.static_url('hello_world:static/pyramid.png')}}" alt="pyramid web framework"> </div> <div class="bottom"> <div id="left" class="align-right"> <h3>Search Pyramid documentation</h3> <form method="get" action="http://docs.pylonshq.com/pyramid/dev/search.html"> <input type="text" id="q" name="q" value="" /> <input type="submit" id="x" value="Search" /> </form> </div> <div id="right" class="align-left"> <h3>Pyramid links</h3> <ul class="links"> <li> <a href="http://pylonshq.com">Pylons Website</a> </li> <li> <a href="http://docs.pylonshq.com/">The Pylons Project Documentation</a> </li> <li> <a href="http://docs.pylonshq.com/pyramid/dev/#narrative-documentation">Narrative Documentation</a> </li> <li> <a href="http://docs.pylonshq.com/pyramid/dev/#api-documentation">API Documentation</a> </li> <li> <a href="http://docs.pylonshq.com/pyramid/dev/#tutorials">Tutorials</a> </li> <li> <a href="http://docs.pylonshq.com/pyramid/dev/#change-history">Change History</a> </li> <li> <a href="http://docs.pylonshq.com/pyramid/dev/#sample-applications">Sample Applications</a> </li> <li> <a href="http://docs.pylonshq.com/pyramid/dev/#support-and-development">Support and Development</a> </li> <li> <a href="irc://irc.freenode.net#pyramid">IRC Channel</a> </li> </ul> </div> </div> </div> </div> <div id="footer"> <div class="footer">© Copyright 2008-2010, Agendaless Consulting.</div> </div> </body> <div class="col-md-10"> <div class="content"> <h1> <span class="font-semi-bold">Pyramid</span> <span class="smaller">Jinja2 scaffold</span> </h1> <p class="lead"> {% trans %}Hello{% endtrans %} to <span class="font-normal">{{project}}</span>, an application generated by<br>the <span class="font-normal">Pyramid Web Framework 1.6</span>.</p> <p>Counter: {{ request.session.counter }}</p> </div> </div> </div> <div class="row"> <div class="links"> <ul> <li class="current-version">Generated by v1.6</li> <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/">Docs</a></li> <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li> <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li> <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li> </ul> </div> </div> <div class="row"> <div class="copyright"> Copyright © Pylons Project </div> </div> </div> </div> <!-- Bootstrap core JavaScript ================================================== --> <!-- Placed at the end of the document so the pages load faster --> <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script> <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script> </body> </html> docs/quick_tour/package/hello_world/views.py
@@ -1,22 +1,16 @@ # Start Logging 1 from pyramid.i18n import TranslationStringFactory import logging log = logging.getLogger(__name__) # End Logging 1 from pyramid.i18n import TranslationStringFactory _ = TranslationStringFactory('hello_world') def my_view(request): # Start Logging 2 log.debug('Some Message') # End Logging 2 # Start Sphinx Include 1 session = request.session if 'counter' in session: session['counter'] += 1 else: session['counter'] = 0 # End Sphinx Include 1 return {'project': 'hello_world'} docs/quick_tour/package/setup.cfg
New file @@ -0,0 +1,28 @@ [nosetests] match = ^test nocapture = 1 cover-package = hello_world with-coverage = 1 cover-erase = 1 [compile_catalog] directory = hello_world/locale domain = hello_world statistics = true [extract_messages] add_comments = TRANSLATORS: output_file = hello_world/locale/hello_world.pot width = 80 mapping_file = message-extraction.ini [init_catalog] domain = hello_world input_file = hello_world/locale/hello_world.pot output_dir = hello_world/locale [update_catalog] domain = hello_world input_file = hello_world/locale/hello_world.pot output_dir = hello_world/locale previous = true docs/quick_tour/package/setup.py
@@ -3,12 +3,17 @@ from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) README = open(os.path.join(here, 'README.txt')).read() CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() with open(os.path.join(here, 'README.txt')) as f: README = f.read() with open(os.path.join(here, 'CHANGES.txt')) as f: CHANGES = f.read() # Start Requires requires = ['pyramid>=1.0.2', 'pyramid_jinja2', 'pyramid_debugtoolbar'] # End Requires requires = [ 'pyramid', 'pyramid_jinja2', 'pyramid_debugtoolbar', 'waitress', ] setup(name='hello_world', version='0.0', @@ -16,7 +21,7 @@ long_description=README + '\n\n' + CHANGES, classifiers=[ "Programming Language :: Python", "Framework :: Pylons", "Framework :: Pyramid", "Topic :: Internet :: WWW/HTTP", "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", ], @@ -28,14 +33,12 @@ include_package_data=True, zip_safe=False, install_requires=requires, tests_require=requires, tests_require={ 'testing': ['nose', 'coverage'], }, test_suite="hello_world", entry_points="""\ [paste.app_factory] main = hello_world:main """, paster_plugins=['pyramid'], extras_require={ 'testing': ['nose', ], } ) ) docs/quick_tour/requests/app.py
@@ -21,4 +21,4 @@ config.add_view(hello_world, route_name='hello') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/routing/app.py
@@ -3,9 +3,7 @@ if __name__ == '__main__': config = Configurator() # Start Route 1 config.add_route('hello', '/howdy/{first}/{last}') # End Route 1 config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) docs/quick_tour/routing/views.py
@@ -2,9 +2,7 @@ from pyramid.view import view_config # Start Route 1 @view_config(route_name='hello') def hello_world(request): body = '<h1>Hi %(first)s %(last)s!</h1>' % request.matchdict return Response(body) # End Route 1 docs/quick_tour/sqla_demo/README.txt
@@ -6,9 +6,9 @@ - cd <directory containing this file> - $venv/bin/python setup.py develop - $VENV/bin/python setup.py develop - $venv/bin/initialize_sqla_demo_db development.ini - $VENV/bin/initialize_sqla_demo_db development.ini - $venv/bin/pserve development.ini - $VENV/bin/pserve development.ini
@@ -68,4 +68,4 @@ formatter = generic [formatter_generic] format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s docs/quick_tour/sqla_demo/production.ini
@@ -59,4 +59,4 @@ formatter = generic [formatter_generic] format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s format = %(asctime)s %(levelname)-5.5s [%(name)s:%(lineno)s][%(threadName)s] %(message)s docs/quick_tour/sqla_demo/setup.cfg
New file @@ -0,0 +1,27 @@ [nosetests] match=^test nocapture=1 cover-package=sqla_demo with-coverage=1 cover-erase=1 [compile_catalog] directory = sqla_demo/locale domain = sqla_demo statistics = true [extract_messages] add_comments = TRANSLATORS: output_file = sqla_demo/locale/sqla_demo.pot width = 80 [init_catalog] domain = sqla_demo input_file = sqla_demo/locale/sqla_demo.pot output_dir = sqla_demo/locale [update_catalog] domain = sqla_demo input_file = sqla_demo/locale/sqla_demo.pot output_dir = sqla_demo/locale previous = true docs/quick_tour/sqla_demo/setup.py
@@ -3,15 +3,18 @@ from setuptools import setup, find_packages here = os.path.abspath(os.path.dirname(__file__)) README = open(os.path.join(here, 'README.txt')).read() CHANGES = open(os.path.join(here, 'CHANGES.txt')).read() with open(os.path.join(here, 'README.txt')) as f: README = f.read() with open(os.path.join(here, 'CHANGES.txt')) as f: CHANGES = f.read() requires = [ 'pyramid', 'pyramid_chameleon', 'pyramid_debugtoolbar', 'pyramid_tm', 'SQLAlchemy', 'transaction', 'pyramid_tm', 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', ] docs/quick_tour/sqla_demo/sqla_demo.sqliteBinary files differ
docs/quick_tour/sqla_demo/sqla_demo/__init__.py
@@ -14,6 +14,7 @@ DBSession.configure(bind=engine) Base.metadata.bind = engine config = Configurator(settings=settings) config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.add_route('home', '/') config.scan() docs/quick_tour/sqla_demo/sqla_demo/models.py
@@ -1,5 +1,6 @@ from sqlalchemy import ( Column, Index, Integer, Text, ) @@ -16,14 +17,11 @@ DBSession = scoped_session(sessionmaker(extension=ZopeTransactionExtension())) Base = declarative_base() # Start Sphinx Include class MyModel(Base): __tablename__ = 'models' id = Column(Integer, primary_key=True) name = Column(Text, unique=True) name = Column(Text) value = Column(Integer) def __init__(self, name, value): self.name = name self.value = value # End Sphinx Include Index('my_index', MyModel.name, unique=True, mysql_length=255) docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py
@@ -9,6 +9,8 @@ setup_logging, ) from pyramid.scripts.common import parse_vars from ..models import ( DBSession, MyModel, @@ -18,17 +20,18 @@ def usage(argv): cmd = os.path.basename(argv[0]) print('usage: %s <config_uri>\n' print('usage: %s <config_uri> [var=value]\n' '(example: "%s development.ini")' % (cmd, cmd)) sys.exit(1) def main(argv=sys.argv): if len(argv) != 2: if len(argv) < 2: usage(argv) config_uri = argv[1] options = parse_vars(argv[2:]) setup_logging(config_uri) settings = get_appsettings(config_uri) settings = get_appsettings(config_uri, options=options) engine = engine_from_config(settings, 'sqlalchemy.') DBSession.configure(bind=engine) Base.metadata.create_all(engine) docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-16x16.png
New file @@ -0,0 +1,154 @@ @import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700); body { font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-weight: 300; color: #ffffff; background: #bc2131; } h1, h2, h3, h4, h5, h6 { font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-weight: 300; } p { font-weight: 300; } .font-normal { font-weight: 400; } .font-semi-bold { font-weight: 600; } .font-bold { font-weight: 700; } .starter-template { margin-top: 250px; } .starter-template .content { margin-left: 10px; } .starter-template .content h1 { margin-top: 10px; font-size: 60px; } .starter-template .content h1 .smaller { font-size: 40px; color: #f2b7bd; } .starter-template .content .lead { font-size: 25px; color: #f2b7bd; } .starter-template .content .lead .font-normal { color: #ffffff; } .starter-template .links { float: right; right: 0; margin-top: 125px; } .starter-template .links ul { display: block; padding: 0; margin: 0; } .starter-template .links ul li { list-style: none; display: inline; margin: 0 10px; } .starter-template .links ul li:first-child { margin-left: 0; } .starter-template .links ul li:last-child { margin-right: 0; } .starter-template .links ul li.current-version { color: #f2b7bd; font-weight: 400; } .starter-template .links ul li a, a { color: #f2b7bd; text-decoration: underline; } .starter-template .links ul li a:hover, a:hover { color: #ffffff; text-decoration: underline; } .starter-template .links ul li .icon-muted { color: #eb8b95; margin-right: 5px; } .starter-template .links ul li:hover .icon-muted { color: #ffffff; } .starter-template .copyright { margin-top: 10px; font-size: 0.9em; color: #f2b7bd; text-transform: lowercase; float: right; right: 0; } @media (max-width: 1199px) { .starter-template .content h1 { font-size: 45px; } .starter-template .content h1 .smaller { font-size: 30px; } .starter-template .content .lead { font-size: 20px; } } @media (max-width: 991px) { .starter-template { margin-top: 0; } .starter-template .logo { margin: 40px auto; } .starter-template .content { margin-left: 0; text-align: center; } .starter-template .content h1 { margin-bottom: 20px; } .starter-template .links { float: none; text-align: center; margin-top: 60px; } .starter-template .copyright { float: none; text-align: center; } } @media (max-width: 767px) { .starter-template .content h1 .smaller { font-size: 25px; display: block; } .starter-template .content .lead { font-size: 16px; } .starter-template .links { margin-top: 40px; } .starter-template .links ul li { display: block; margin: 0; } .starter-template .links ul li .icon-muted { display: none; } .starter-template .copyright { margin-top: 20px; } } docs/quick_tour/sqla_demo/sqla_demo/static/theme.min.css
New file @@ -0,0 +1 @@ @import url(//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700);body{font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300;color:#fff;background:#bc2131}h1,h2,h3,h4,h5,h6{font-family:"Open Sans","Helvetica Neue",Helvetica,Arial,sans-serif;font-weight:300}p{font-weight:300}.font-normal{font-weight:400}.font-semi-bold{font-weight:600}.font-bold{font-weight:700}.starter-template{margin-top:250px}.starter-template .content{margin-left:10px}.starter-template .content h1{margin-top:10px;font-size:60px}.starter-template .content h1 .smaller{font-size:40px;color:#f2b7bd}.starter-template .content .lead{font-size:25px;color:#f2b7bd}.starter-template .content .lead .font-normal{color:#fff}.starter-template .links{float:right;right:0;margin-top:125px}.starter-template .links ul{display:block;padding:0;margin:0}.starter-template .links ul li{list-style:none;display:inline;margin:0 10px}.starter-template .links ul li:first-child{margin-left:0}.starter-template .links ul li:last-child{margin-right:0}.starter-template .links ul li.current-version{color:#f2b7bd;font-weight:400}.starter-template .links ul li a,a{color:#f2b7bd;text-decoration:underline}.starter-template .links ul li a:hover,a:hover{color:#fff;text-decoration:underline}.starter-template .links ul li .icon-muted{color:#eb8b95;margin-right:5px}.starter-template .links ul li:hover .icon-muted{color:#fff}.starter-template .copyright{margin-top:10px;font-size:.9em;color:#f2b7bd;text-transform:lowercase;float:right;right:0}@media (max-width:1199px){.starter-template .content h1{font-size:45px}.starter-template .content h1 .smaller{font-size:30px}.starter-template .content .lead{font-size:20px}}@media (max-width:991px){.starter-template{margin-top:0}.starter-template .logo{margin:40px auto}.starter-template .content{margin-left:0;text-align:center}.starter-template .content h1{margin-bottom:20px}.starter-template .links{float:none;text-align:center;margin-top:60px}.starter-template .copyright{float:none;text-align:center}}@media (max-width:767px){.starter-template .content h1 .smaller{font-size:25px;display:block}.starter-template .content .lead{font-size:16px}.starter-template .links{margin-top:40px}.starter-template .links ul li{display:block;margin:0}.starter-template .links ul li .icon-muted{display:none}.starter-template .copyright{margin-top:20px}} docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt
@@ -1,76 +1,67 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" xmlns:tal="http://xml.zope.org/namespaces/tal"> <head> <title>The Pyramid Web Framework</title> <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> <meta name="keywords" content="python web application" /> <meta name="description" content="pyramid web application" /> <link rel="shortcut icon" href="${request.static_url('sqla_demo:static/favicon.ico')}" /> <link rel="stylesheet" href="${request.static_url('sqla_demo:static/pylons.css')}" type="text/css" media="screen" charset="utf-8" /> <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/nobile/stylesheet.css" media="screen" /> <link rel="stylesheet" href="http://static.pylonsproject.org/fonts/neuton/stylesheet.css" media="screen" /> <!--[if lte IE 6]> <link rel="stylesheet" href="${request.static_url('sqla_demo:static/ie6.css')}" type="text/css" media="screen" charset="utf-8" /> <![endif]--> </head> <body> <div id="wrap"> <div id="top"> <div class="top align-center"> <div><img src="${request.static_url('sqla_demo:static/pyramid.png')}" width="750" height="169" alt="pyramid"/></div> </div> </div> <div id="middle"> <div class="middle align-center"> <p class="app-welcome"> Welcome to <span class="app-name">${project}</span>, an application generated by<br/> the Pyramid web framework. </p> </div> </div> <div id="bottom"> <div class="bottom"> <div id="left" class="align-right"> <h2>Search documentation</h2> <form method="get" action="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/search.html"> <input type="text" id="q" name="q" value="" /> <input type="submit" id="x" value="Go" /> </form> <!DOCTYPE html> <html lang="${request.locale_name}"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="description" content="pyramid web application"> <meta name="author" content="Pylons Project"> <link rel="shortcut icon" href="${request.static_url('sqla_demo:static/pyramid-16x16.png')}"> <title>Alchemy Scaffold for The Pyramid Web Framework</title> <!-- Bootstrap core CSS --> <link href="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/css/bootstrap.min.css" rel="stylesheet"> <!-- Custom styles for this scaffold --> <link href="${request.static_url('sqla_demo:static/theme.css')}" rel="stylesheet"> <!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries --> <!--[if lt IE 9]> <script src="//oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script> <script src="//oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script> <![endif]--> </head> <body> <div class="starter-template"> <div class="container"> <div class="row"> <div class="col-md-2"> <img class="logo img-responsive" src="${request.static_url('sqla_demo:static/pyramid.png')}" alt="pyramid web framework"> </div> <div class="col-md-10"> <div class="content"> <h1><span class="font-semi-bold">Pyramid</span> <span class="smaller">Alchemy scaffold</span></h1> <p class="lead">Welcome to <span class="font-normal">${project}</span>, an application generated by<br>the <span class="font-normal">Pyramid Web Framework 1.6</span>.</p> </div> </div> </div> <div id="right" class="align-left"> <h2>Pyramid links</h2> <ul class="links"> <li> <a href="http://pylonsproject.org">Pylons Website</a> </li> <li> <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#narrative-documentation">Narrative Documentation</a> </li> <li> <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#reference-material">API Documentation</a> </li> <li> <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#tutorials">Tutorials</a> </li> <li> <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#detailed-change-history">Change History</a> </li> <li> <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#sample-applications">Sample Applications</a> </li> <li> <a href="http://docs.pylonsproject.org/projects/pyramid/en/1.4-branch/#support-and-development">Support and Development</a> </li> <li> <a href="irc://irc.freenode.net#pyramid">IRC Channel</a> </li> <div class="row"> <div class="links"> <ul> <li class="current-version">Generated by v1.6</li> <li><i class="glyphicon glyphicon-bookmark icon-muted"></i><a href="http://docs.pylonsproject.org/projects/pyramid/en/1.6-branch/">Docs</a></li> <li><i class="glyphicon glyphicon-cog icon-muted"></i><a href="https://github.com/Pylons/pyramid">Github Project</a></li> <li><i class="glyphicon glyphicon-globe icon-muted"></i><a href="irc://irc.freenode.net#pyramid">IRC Channel</a></li> <li><i class="glyphicon glyphicon-home icon-muted"></i><a href="http://pylonsproject.org">Pylons Project</a></li> </ul> </div> </div> <div class="row"> <div class="copyright"> Copyright © Pylons Project </div> </div> </div> </div> </div> <div id="footer"> <div class="footer">© Copyright 2008-2012, Agendaless Consulting.</div> </div> </body> <!-- Bootstrap core JavaScript ================================================== --> <!-- Placed at the end of the document so the pages load faster --> <script src="//oss.maxcdn.com/libs/jquery/1.10.2/jquery.min.js"></script> <script src="//oss.maxcdn.com/libs/twitter-bootstrap/3.0.3/js/bootstrap.min.js"></script> </body> </html> docs/quick_tour/sqla_demo/sqla_demo/tests.py
@@ -6,7 +6,7 @@ from .models import DBSession class TestMyView(unittest.TestCase): class TestMyViewSuccessCondition(unittest.TestCase): def setUp(self): self.config = testing.setUp() from sqlalchemy import create_engine @@ -25,9 +25,31 @@ DBSession.remove() testing.tearDown() def test_it(self): def test_passing_view(self): from .views import my_view request = testing.DummyRequest() info = my_view(request) self.assertEqual(info['one'].name, 'one') self.assertEqual(info['project'], 'sqla_demo') class TestMyViewFailureCondition(unittest.TestCase): def setUp(self): self.config = testing.setUp() from sqlalchemy import create_engine engine = create_engine('sqlite://') from .models import ( Base, MyModel, ) DBSession.configure(bind=engine) def tearDown(self): DBSession.remove() testing.tearDown() def test_failing_view(self): from .views import my_view request = testing.DummyRequest() info = my_view(request) self.assertEqual(info.status_int, 500) docs/quick_tour/sqla_demo/sqla_demo/views.py
@@ -12,19 +12,18 @@ @view_config(route_name='home', renderer='templates/mytemplate.pt') def my_view(request): try: # Start Sphinx Include one = DBSession.query(MyModel).filter(MyModel.name == 'one').first() # End Sphinx Include except DBAPIError: return Response(conn_err_msg, content_type='text/plain', status_int=500) return {'one': one, 'project': 'sqla_demo'} conn_err_msg = """\ Pyramid is having a problem using your SQL database. The problem might be caused by one of the following things: 1. You may need to run the "initialize_sqla_demo_db" script to initialize your database tables. Check your virtual to initialize your database tables. Check your virtual environment's "bin" directory for this script and try to run it. 2. Your database server may not be running. Check that the docs/quick_tour/static_assets/app.py
@@ -4,11 +4,9 @@ if __name__ == '__main__': config = Configurator() config.add_route('hello', '/howdy/{name}') # Start Static 1 config.add_static_view(name='static', path='static') # End Static 1 config.include('pyramid_jinja2') config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/static_assets/hello_world.jinja2
@@ -1,7 +1,7 @@ <!DOCTYPE html> <html lang="en"> <head> <title>Quick Glance</title> <title>Hello World</title> <link rel="stylesheet" href="/static/app.css"/> </head> <body> docs/quick_tour/static_assets/hello_world.pt
File was deleted docs/quick_tour/static_assets/hello_world_static.jinja2
New file @@ -0,0 +1,10 @@ <!DOCTYPE html> <html lang="en"> <head> <title>Hello World</title> <link rel="stylesheet" href="{{ request.static_url('static/app.css') }}"/> </head> <body> <h1>Hello {{ name }}!</h1> </body> </html> docs/quick_tour/static_assets/views.py
@@ -1,6 +1,6 @@ from pyramid.view import view_config @view_config(route_name='hello', renderer='hello_world.pt') @view_config(route_name='hello', renderer='hello_world.jinja2') def hello_world(request): return dict(name=request.matchdict['name']) docs/quick_tour/templating/app.py
@@ -4,7 +4,8 @@ if __name__ == '__main__': config = Configurator() config.add_route('hello', '/howdy/{name}') config.include('pyramid_chameleon') config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/templating/views.py
@@ -1,8 +1,6 @@ from pyramid.view import view_config # Start View 1 @view_config(route_name='hello', renderer='hello_world.pt') def hello_world(request): return dict(name=request.matchdict['name']) # End View 1 docs/quick_tour/view_classes/app.py
@@ -3,11 +3,11 @@ if __name__ == '__main__': config = Configurator() # Start Routes 1 config.add_route('hello', '/howdy/{name}') # End Routes 1 config.add_route('hello_json', 'hello.json') config.add_static_view(name='static', path='static') config.include('pyramid_jinja2') config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tour/view_classes/hello.jinja2
@@ -5,13 +5,11 @@ </head> <body> <h1>Hello {{ view.name }}!</h1> <!-- Start Form 1 --> <form method="POST" action="{{ request.current_route_url() }}"> <input name="new_name"/> <input type="submit" name="form.edit" value="Save"/> <input type="submit" name="form.delete" value="Delete"/> <input name="new_name"> <input type="submit" name="form.edit" value="Save"> <input type="submit" name="form.delete" value="Delete"> </form> <!-- End Form 1 --> </body> </html> docs/quick_tour/view_classes/views.py
@@ -4,7 +4,6 @@ ) # Start View 1 # One route, at /howdy/amy, so don't repeat on each @view_config @view_defaults(route_name='hello') class HelloWorldViews: @@ -29,4 +28,3 @@ def delete_view(self): print('Deleted') return dict() # End View 1 docs/quick_tour/views/app.py
@@ -10,4 +10,4 @@ config.scan('views') app = config.make_wsgi_app() server = make_server('0.0.0.0', 6543, app) server.serve_forever() server.serve_forever() docs/quick_tutorial/requirements.rst
@@ -19,7 +19,7 @@ This *Quick Tutorial* is based on: * **Python 3.3**. Pyramid fully supports Python 3.2+ and Python 2.6+. * **Python 3.3**. Pyramid fully supports Python 3.3+ and Python 2.6+. This tutorial uses **Python 3.3** but runs fine under Python 2.7. * **pyvenv**. We believe in virtual environments. For this tutorial, @@ -109,7 +109,7 @@ For Windows: .. code-block:: posh .. code-block:: ps1con # Windows c:\> cd \ docs/tutorials/wiki/design.rst
@@ -1,6 +1,6 @@ ========== ====== Design ========== ====== Following is a quick overview of the design of our wiki application, to help us understand the changes that we will be making as we work through the docs/tutorials/wiki/installation.rst
@@ -65,11 +65,11 @@ c:\> c:\Python27\Scripts\virtualenv %VENV% Python 3.2: Python 3.3: .. code-block:: text c:\> c:\Python32\Scripts\virtualenv %VENV% c:\> c:\Python33\Scripts\virtualenv %VENV% Install Pyramid and tutorial dependencies into the virtual Python environment ----------------------------------------------------------------------------- docs/tutorials/wiki2/design.rst
@@ -1,6 +1,6 @@ ========== ====== Design ========== ====== Following is a quick overview of the design of our wiki application, to help us understand the changes that we will be making as we work through the docs/tutorials/wiki2/installation.rst
@@ -65,11 +65,11 @@ c:\> c:\Python27\Scripts\virtualenv %VENV% Python 3.2: Python 3.3: .. code-block:: text c:\> c:\Python32\Scripts\virtualenv %VENV% c:\> c:\Python33\Scripts\virtualenv %VENV% Install Pyramid into the virtual Python environment --------------------------------------------------- @@ -392,7 +392,7 @@ application while you develop. Decisions the ``alchemy`` scaffold has made for you ================================================================= =================================================== Creating a project using the ``alchemy`` scaffold makes the following assumptions: docs/whatsnew-1.3.rst
@@ -18,7 +18,7 @@ .. image:: python-3.png Pyramid continues to run on Python 2, but Pyramid is now also Python 3 compatible. To use Pyramid under Python 3, Python 3.2 or better is required. compatible. To use Pyramid under Python 3, Python 3.3 or better is required. Many Pyramid add-ons are already Python 3 compatible. For example, ``pyramid_debugtoolbar``, ``pyramid_jinja2``, ``pyramid_exclog``, @@ -523,10 +523,11 @@ :ref:`making_a_console_script`. - Removed the "Running Pyramid on Google App Engine" tutorial from the main docs. It survives on in the Cookbook (http://docs.pylonsproject.org/projects/pyramid_cookbook/en/latest/deployment/gae.html). Rationale: it provides the correct info for the Python 2.5 version of GAE only, and this version of Pyramid does not support Python 2.5. docs. It survives on in the Pyramid Community Cookbook as :ref:`Pyramid on Google's App Engine (using appengine-monkey) <cookbook:appengine_tutorial>`. Rationale: it provides the correct info for the Python 2.5 version of GAE only, and this version of Pyramid does not support Python 2.5. - Updated the :ref:`changing_the_forbidden_view` section, replacing explanations of registering a view using ``add_view`` or ``view_config`` docs/whatsnew-1.6.rst
@@ -41,6 +41,18 @@ This does not change the API of a renderer. See https://github.com/Pylons/pyramid/pull/1563 - In an effort to combat a common issue it is now a :class:`~pyramid.exceptions.ConfigurationError` to register a view callable that is actually an unbound method when using the default view mapper. As unbound methods do not exist in PY3+ possible errors are detected by checking if the first parameter is named ``self``. For example, `config.add_view(ViewClass.some_method, ...)` should actually be `config.add_view(ViewClass, attr='some_method)'`. This was always an issue in Pyramid on PY2 but the backward incompatibility is on PY3+ where you may not use a function with the first parameter named ``self``. In this case it looks too much like a common error and the exception will be raised. See https://github.com/Pylons/pyramid/pull/1498 Feature Additions ----------------- pyramid/compat.py
@@ -20,23 +20,24 @@ except ImportError: # pragma: no cover import pickle # True if we are running on Python 3. # PY3 is left as bw-compat but PY2 should be used for most checks. PY2 = sys.version_info[0] == 2 PY3 = sys.version_info[0] == 3 if PY3: string_types = str, integer_types = int, class_types = type, text_type = str binary_type = bytes long = int else: if PY2: string_types = basestring, integer_types = (int, long) class_types = (type, types.ClassType) text_type = unicode binary_type = str long = long else: string_types = str, integer_types = int, class_types = type, text_type = str binary_type = bytes long = int def text_(s, encoding='latin-1', errors='strict'): """ If ``s`` is an instance of ``binary_type``, return @@ -52,16 +53,16 @@ return s.encode(encoding, errors) return s if PY3: def ascii_native_(s): if isinstance(s, text_type): s = s.encode('ascii') return str(s, 'ascii', 'strict') else: if PY2: def ascii_native_(s): if isinstance(s, text_type): s = s.encode('ascii') return str(s) else: def ascii_native_(s): if isinstance(s, text_type): s = s.encode('ascii') return str(s, 'ascii', 'strict') ascii_native_.__doc__ = """ Python 3: If ``s`` is an instance of ``text_type``, return @@ -72,20 +73,20 @@ """ if PY3: def native_(s, encoding='latin-1', errors='strict'): """ If ``s`` is an instance of ``text_type``, return ``s``, otherwise return ``str(s, encoding, errors)``""" if isinstance(s, text_type): return s return str(s, encoding, errors) else: if PY2: def native_(s, encoding='latin-1', errors='strict'): """ If ``s`` is an instance of ``text_type``, return ``s.encode(encoding, errors)``, otherwise return ``str(s)``""" if isinstance(s, text_type): return s.encode(encoding, errors) return str(s) else: def native_(s, encoding='latin-1', errors='strict'): """ If ``s`` is an instance of ``text_type``, return ``s``, otherwise return ``str(s, encoding, errors)``""" if isinstance(s, text_type): return s return str(s, encoding, errors) native_.__doc__ = """ Python 3: If ``s`` is an instance of ``text_type``, return ``s``, otherwise @@ -95,17 +96,7 @@ ``s.encode(encoding, errors)``, otherwise return ``str(s)`` """ if PY3: from urllib import parse urlparse = parse from urllib.parse import quote as url_quote from urllib.parse import quote_plus as url_quote_plus from urllib.parse import unquote as url_unquote from urllib.parse import urlencode as url_encode from urllib.request import urlopen as url_open url_unquote_text = url_unquote url_unquote_native = url_unquote else: if PY2: import urlparse from urllib import quote as url_quote from urllib import quote_plus as url_quote_plus @@ -119,22 +110,19 @@ def url_unquote_native(v, encoding='utf-8', errors='replace'): # pragma: no cover return native_(url_unquote_text(v, encoding, errors)) else: from urllib import parse urlparse = parse from urllib.parse import quote as url_quote from urllib.parse import quote_plus as url_quote_plus from urllib.parse import unquote as url_unquote from urllib.parse import urlencode as url_encode from urllib.request import urlopen as url_open url_unquote_text = url_unquote url_unquote_native = url_unquote if PY3: # pragma: no cover import builtins exec_ = getattr(builtins, "exec") def reraise(tp, value, tb=None): if value is None: value = tp if value.__traceback__ is not tb: raise value.with_traceback(tb) raise value del builtins else: # pragma: no cover if PY2: # pragma: no cover def exec_(code, globs=None, locs=None): """Execute code in a namespace.""" if globs is None: @@ -151,17 +139,21 @@ raise tp, value, tb """) if PY3: # pragma: no cover def iteritems_(d): return d.items() def itervalues_(d): return d.values() def iterkeys_(d): return d.keys() else: # pragma: no cover import builtins exec_ = getattr(builtins, "exec") def reraise(tp, value, tb=None): if value is None: value = tp if value.__traceback__ is not tb: raise value.with_traceback(tb) raise value del builtins if PY2: # pragma: no cover def iteritems_(d): return d.iteritems() @@ -170,29 +162,38 @@ def iterkeys_(d): return d.iterkeys() else: # pragma: no cover def iteritems_(d): return d.items() def itervalues_(d): return d.values() def iterkeys_(d): return d.keys() if PY3: if PY2: map_ = map else: def map_(*arg): return list(map(*arg)) else: map_ = map if PY3: if PY2: def is_nonstr_iter(v): return hasattr(v, '__iter__') else: def is_nonstr_iter(v): if isinstance(v, str): return False return hasattr(v, '__iter__') else: def is_nonstr_iter(v): return hasattr(v, '__iter__') if PY3: im_func = '__func__' im_self = '__self__' else: if PY2: im_func = 'im_func' im_self = 'im_self' else: im_func = '__func__' im_self = '__self__' try: import configparser @@ -204,65 +205,65 @@ except ImportError: from Cookie import SimpleCookie if PY3: from html import escape else: if PY2: from cgi import escape if PY3: input_ = input else: from html import escape if PY2: input_ = raw_input if PY3: from inspect import getfullargspec as getargspec else: input_ = input if PY2: from inspect import getargspec if PY3: from io import StringIO as NativeIO else: from inspect import getfullargspec as getargspec if PY2: from io import BytesIO as NativeIO else: from io import StringIO as NativeIO # "json" is not an API; it's here to support older pyramid_debugtoolbar # versions which attempt to import it import json if PY3: if PY2: def decode_path_info(path): return path.decode('utf-8') else: # see PEP 3333 for why we encode WSGI PATH_INFO to latin-1 before # decoding it to utf-8 def decode_path_info(path): return path.encode('latin-1').decode('utf-8') else: def decode_path_info(path): return path.decode('utf-8') if PY3: if PY2: from urlparse import unquote as unquote_to_bytes def unquote_bytes_to_wsgi(bytestring): return unquote_to_bytes(bytestring) else: # see PEP 3333 for why we decode the path to latin-1 from urllib.parse import unquote_to_bytes def unquote_bytes_to_wsgi(bytestring): return unquote_to_bytes(bytestring).decode('latin-1') else: from urlparse import unquote as unquote_to_bytes def unquote_bytes_to_wsgi(bytestring): return unquote_to_bytes(bytestring) def is_bound_method(ob): return inspect.ismethod(ob) and getattr(ob, im_self, None) is not None # support annotations and keyword-only arguments in PY3 if PY3: # pragma: no cover from inspect import getfullargspec as getargspec else: if PY2: from inspect import getargspec if PY3: # pragma: no cover from itertools import zip_longest else: from inspect import getfullargspec as getargspec if PY2: from itertools import izip_longest as zip_longest else: from itertools import zip_longest def is_unbound_method(fn): """ @@ -275,9 +276,9 @@ spec = getargspec(fn) has_self = len(spec.args) > 0 and spec.args[0] == 'self' if PY3 and inspect.isfunction(fn) and has_self: # pragma: no cover if PY2 and inspect.ismethod(fn): return True elif inspect.ismethod(fn): elif inspect.isfunction(fn) and has_self: return True return False pyramid/i18n.py
@@ -8,7 +8,7 @@ TranslationStringFactory, # API ) from pyramid.compat import PY3 from pyramid.compat import PY2 from pyramid.decorator import reify from pyramid.interfaces import ( @@ -332,10 +332,10 @@ """Like ``ugettext()``, but look the message up in the specified domain. """ if PY3: return self._domains.get(domain, self).gettext(message) else: if PY2: return self._domains.get(domain, self).ugettext(message) else: return self._domains.get(domain, self).gettext(message) def dngettext(self, domain, singular, plural, num): """Like ``ngettext()``, but look the message up in the specified @@ -353,11 +353,11 @@ """Like ``ungettext()`` but look the message up in the specified domain. """ if PY3: return self._domains.get(domain, self).ngettext( if PY2: return self._domains.get(domain, self).ungettext( singular, plural, num) else: return self._domains.get(domain, self).ungettext( return self._domains.get(domain, self).ngettext( singular, plural, num) class LocalizerRequestMixin(object): pyramid/interfaces.py
@@ -5,7 +5,7 @@ Interface, ) from pyramid.compat import PY3 from pyramid.compat import PY2 # public API interfaces @@ -311,7 +311,7 @@ def values(): """ Return a list of values from the dictionary """ if not PY3: if PY2: def iterkeys(): """ Return an iterator of keys from the dictionary """ pyramid/scripts/pserve.py
@@ -29,7 +29,7 @@ from paste.deploy import loadapp from paste.deploy.loadwsgi import loadcontext, SERVER from pyramid.compat import PY3 from pyramid.compat import PY2 from pyramid.compat import WIN from pyramid.paster import setup_logging @@ -114,7 +114,7 @@ '--log-file', dest='log_file', metavar='LOG_FILE', help="Save output to the given log file (redirects stdout)") help="Save output to the given log file (redirects stdout) [DEPRECATED]") parser.add_option( '--reload', dest='reload', @@ -287,7 +287,7 @@ base = os.getcwd() # warn before setting a default if self.options.pid_file: if self.options.pid_file or self.options.log_file: self._warn_daemon_deprecated() if getattr(self.options, 'daemon', False): @@ -391,7 +391,7 @@ if self.options.browser: def open_browser(): context = loadcontext(SERVER, app_spec, name=app_name, relative_to=base, context = loadcontext(SERVER, app_spec, name=server_name, relative_to=base, global_conf=vars) url = 'http://127.0.0.1:{port}/'.format(**context.config()) time.sleep(1) @@ -675,7 +675,7 @@ a real process manager for your processes like Systemd, Circus, or Supervisor. The following commands are deprecated: [start,stop,restart,status] --daemon, --stop-server, --status, --pid-file [start,stop,restart,status] --daemon, --stop-server, --status, --pid-file, --log-file ''') class LazyWriter(object): @@ -1111,7 +1111,7 @@ server = wsgiserver.CherryPyWSGIServer(bind_addr, app, server_name=server_name, **kwargs) if ssl_pem is not None: if not PY3: if PY2: server.ssl_certificate = server.ssl_private_key = ssl_pem else: # creates wsgiserver.ssl_builtin as side-effect pyramid/session.py
@@ -12,7 +12,7 @@ from pyramid.compat import ( pickle, PY3, PY2, text_, bytes_, native_, @@ -126,7 +126,8 @@ .. versionadded:: 1.4a2 """ supplied_token = request.params.get(token, request.headers.get(header, "")) if strings_differ(request.session.get_csrf_token(), supplied_token): expected_token = request.session.get_csrf_token() if strings_differ(bytes_(expected_token), bytes_(supplied_token)): if raises: raise BadCSRFToken('check_csrf_token(): Invalid token') return False @@ -325,7 +326,7 @@ __len__ = manage_accessed(dict.__len__) __iter__ = manage_accessed(dict.__iter__) if not PY3: if PY2: iteritems = manage_accessed(dict.iteritems) itervalues = manage_accessed(dict.itervalues) iterkeys = manage_accessed(dict.iterkeys) pyramid/testing.py
@@ -16,6 +16,7 @@ PY3, PYPY, class_types, text_, ) from pyramid.config import Configurator @@ -274,7 +275,7 @@ return storage def new_csrf_token(self): token = '0123456789012345678901234567890123456789' token = text_('0123456789012345678901234567890123456789') self['_csrft_'] = token return token
@@ -1,6 +1,6 @@ import unittest from pyramid.compat import PY3 from pyramid.compat import PY2 from pyramid.tests.test_config import IDummy class AdaptersConfiguratorMixinTests(unittest.TestCase): @@ -219,10 +219,10 @@ def test_add_response_adapter_dottednames(self): from pyramid.interfaces import IResponse config = self._makeOne(autocommit=True) if PY3: str_name = 'builtins.str' else: if PY2: str_name = '__builtin__.str' else: str_name = 'builtins.str' config.add_response_adapter('pyramid.response.Response', str_name) result = config.registry.queryAdapter('foo', IResponse) self.assertTrue(result.body, b'foo') pyramid/tests/test_config/test_factories.py
@@ -128,17 +128,17 @@ def test_add_request_method_with_text_type_name(self): from pyramid.interfaces import IRequestExtensions from pyramid.compat import text_, PY3 from pyramid.compat import text_, PY2 from pyramid.exceptions import ConfigurationError config = self._makeOne(autocommit=True) def boomshaka(r): pass def get_bad_name(): if PY3: # pragma: nocover name = b'La Pe\xc3\xb1a' else: # pragma: nocover if PY2: name = text_(b'La Pe\xc3\xb1a', 'utf-8') else: name = b'La Pe\xc3\xb1a' config.add_request_method(boomshaka, name=name)
@@ -1,6 +1,6 @@ import unittest import os from pyramid.compat import PY3 from pyramid.compat import PY2 here = os.path.abspath(os.path.dirname(__file__)) @@ -376,10 +376,10 @@ def test_zope_dottedname_style_resolve_builtin(self): typ = self._makeOne() if PY3: result = typ._zope_dottedname_style('builtins.str', None) else: if PY2: result = typ._zope_dottedname_style('__builtin__.str', None) else: result = typ._zope_dottedname_style('builtins.str', None) self.assertEqual(result, str) def test_zope_dottedname_style_resolve_absolute(self): pyramid/tests/test_request.py
@@ -3,7 +3,7 @@ from pyramid import testing from pyramid.compat import ( PY3, PY2, text_, bytes_, native_, @@ -310,10 +310,10 @@ b'/\xe6\xb5\x81\xe8\xa1\x8c\xe8\xb6\x8b\xe5\x8a\xbf', 'utf-8' ) if PY3: body = bytes(json.dumps({'a':inp}), 'utf-16') else: if PY2: body = json.dumps({'a':inp}).decode('utf-8').encode('utf-16') else: body = bytes(json.dumps({'a':inp}), 'utf-16') request.body = body request.content_type = 'application/json; charset=utf-16' self.assertEqual(request.json_body, {'a':inp}) pyramid/tests/test_scripts/test_pserve.py
@@ -3,11 +3,11 @@ import tempfile import unittest from pyramid.compat import PY3 if PY3: import builtins as __builtin__ else: from pyramid.compat import PY2 if PY2: import __builtin__ else: import builtins as __builtin__ class TestPServeCommand(unittest.TestCase): def setUp(self): pyramid/tests/test_session.py
@@ -695,6 +695,13 @@ result = self._callFUT(request, 'csrf_token', raises=False) self.assertEqual(result, False) def test_token_differing_types(self): from pyramid.compat import text_ request = testing.DummyRequest() request.session['_csrft_'] = text_('foo') request.params['csrf_token'] = b'foo' self.assertEqual(self._callFUT(request, token='csrf_token'), True) class DummySerializer(object): def dumps(self, value): return base64.b64encode(json.dumps(value).encode('utf-8')) pyramid/tests/test_traversal.py
@@ -8,7 +8,7 @@ native_, text_type, url_quote, PY3, PY2, ) with warnings.catch_warnings(record=True) as w: @@ -335,10 +335,10 @@ foo = DummyContext(bar, path) root = DummyContext(foo, 'root') policy = self._makeOne(root) if PY3: vhm_root = b'/Qu\xc3\xa9bec'.decode('latin-1') else: if PY2: vhm_root = b'/Qu\xc3\xa9bec' else: vhm_root = b'/Qu\xc3\xa9bec'.decode('latin-1') environ = self._getEnviron(HTTP_X_VHM_ROOT=vhm_root) request = DummyRequest(environ, path_info=text_('/bar')) result = policy(request) pyramid/tests/test_urldispatch.py
@@ -2,7 +2,7 @@ from pyramid import testing from pyramid.compat import ( text_, PY3, PY2, ) class TestRoute(unittest.TestCase): @@ -120,10 +120,10 @@ def test___call__pathinfo_cant_be_decoded(self): from pyramid.exceptions import URLDecodeError mapper = self._makeOne() if PY3: path_info = b'\xff\xfe\xe6\x00'.decode('latin-1') else: if PY2: path_info = b'\xff\xfe\xe6\x00' else: path_info = b'\xff\xfe\xe6\x00'.decode('latin-1') request = self._getRequest(PATH_INFO=path_info) self.assertRaises(URLDecodeError, mapper, request)
@@ -1,5 +1,5 @@ import unittest from pyramid.compat import PY3 from pyramid.compat import PY2 class Test_InstancePropertyHelper(unittest.TestCase): @@ -149,10 +149,10 @@ from pyramid.exceptions import ConfigurationError cls = self._getTargetClass() if PY3: # pragma: nocover name = b'La Pe\xc3\xb1a' else: # pragma: nocover if PY2: name = text_(b'La Pe\xc3\xb1a', 'utf-8') else: name = b'La Pe\xc3\xb1a' def make_bad_name(): cls.make_property(lambda x: 1, name=name, reify=True) @@ -431,10 +431,10 @@ self.assertEqual(self._callFUT(('a', 'b')), "('a', 'b')") def test_set(self): if PY3: self.assertEqual(self._callFUT(set(['a'])), "{'a'}") else: if PY2: self.assertEqual(self._callFUT(set(['a'])), "set(['a'])") else: self.assertEqual(self._callFUT(set(['a'])), "{'a'}") def test_list(self): self.assertEqual(self._callFUT(['a']), "['a']") @@ -769,25 +769,25 @@ class TestCallableName(unittest.TestCase): def test_valid_ascii(self): from pyramid.util import get_callable_name from pyramid.compat import text_, PY3 from pyramid.compat import text_ if PY3: # pragma: nocover name = b'hello world' else: # pragma: nocover if PY2: name = text_(b'hello world', 'utf-8') else: name = b'hello world' self.assertEqual(get_callable_name(name), 'hello world') def test_invalid_ascii(self): from pyramid.util import get_callable_name from pyramid.compat import text_, PY3 from pyramid.compat import text_ from pyramid.exceptions import ConfigurationError def get_bad_name(): if PY3: # pragma: nocover name = b'La Pe\xc3\xb1a' else: # pragma: nocover if PY2: name = text_(b'La Pe\xc3\xb1a', 'utf-8') else: name = b'La Pe\xc3\xb1a' get_callable_name(name)
@@ -15,7 +15,7 @@ ) from pyramid.compat import ( PY3, PY2, native_, text_, ascii_native_, @@ -575,26 +575,8 @@ """ if PY3: if PY2: # special-case on Python 2 for speed? unchecked def quote_path_segment(segment, safe=''): """ %s """ % quote_path_segment_doc # The bit of this code that deals with ``_segment_cache`` is an # optimization: we cache all the computation of URL path segments # in this module-scope dictionary with the original string (or # unicode value) as the key, so we can look it up later without # needing to reencode or re-url-quote it try: return _segment_cache[(segment, safe)] except KeyError: if segment.__class__ not in (text_type, binary_type): segment = str(segment) result = url_quote(native_(segment, 'utf-8'), safe) # we don't need a lock to mutate _segment_cache, as the below # will generate exactly one Python bytecode (STORE_SUBSCR) _segment_cache[(segment, safe)] = result return result else: def quote_path_segment(segment, safe=''): """ %s """ % quote_path_segment_doc # The bit of this code that deals with ``_segment_cache`` is an @@ -613,7 +595,25 @@ # will generate exactly one Python bytecode (STORE_SUBSCR) _segment_cache[(segment, safe)] = result return result else: def quote_path_segment(segment, safe=''): """ %s """ % quote_path_segment_doc # The bit of this code that deals with ``_segment_cache`` is an # optimization: we cache all the computation of URL path segments # in this module-scope dictionary with the original string (or # unicode value) as the key, so we can look it up later without # needing to reencode or re-url-quote it try: return _segment_cache[(segment, safe)] except KeyError: if segment.__class__ not in (text_type, binary_type): segment = str(segment) result = url_quote(native_(segment, 'utf-8'), safe) # we don't need a lock to mutate _segment_cache, as the below # will generate exactly one Python bytecode (STORE_SUBSCR) _segment_cache[(segment, safe)] = result return result slash = text_('/') @implementer(ITraverser) pyramid/urldispatch.py
@@ -7,7 +7,7 @@ ) from pyramid.compat import ( PY3, PY2, native_, text_, text_type, @@ -210,14 +210,14 @@ def generator(dict): newdict = {} for k, v in dict.items(): if PY3: if v.__class__ is binary_type: # url_quote below needs a native string, not bytes on Py3 v = v.decode('utf-8') else: if PY2: if v.__class__ is text_type: # url_quote below needs bytes, not unicode on Py2 v = v.encode('utf-8') else: if v.__class__ is binary_type: # url_quote below needs a native string, not bytes on Py3 v = v.decode('utf-8') if k == remainder: # a stararg argument pyramid/util.py
@@ -20,7 +20,7 @@ integer_types, string_types, text_, PY3, PY2, native_ ) @@ -310,10 +310,10 @@ if isinstance(object, (bool, float, type(None))): return text_(str(object)) if isinstance(object, set): if PY3: return shortrepr(object, '}') else: if PY2: return shortrepr(object, ')') else: return shortrepr(object, '}') if isinstance(object, tuple): return shortrepr(object, ')') if isinstance(object, list): pyramid/view.py
@@ -165,7 +165,7 @@ ``request_type``, ``route_name``, ``request_method``, ``request_param``, ``containment``, ``xhr``, ``accept``, ``header``, ``path_info``, ``custom_predicates``, ``decorator``, ``mapper``, ``http_cache``, ``match_param``, ``csrf_token``, ``physical_path``, and ``predicates``. ``match_param``, ``check_csrf``, ``physical_path``, and ``predicates``. The meanings of these arguments are the same as the arguments passed to :meth:`pyramid.config.Configurator.add_view`. If any argument is left setup.py
@@ -18,12 +18,13 @@ from setuptools import setup, find_packages py_version = sys.version_info[:2] is_pypy = '__pypy__' in sys.builtin_module_names PY3 = py_version[0] == 3 if PY3: if py_version < (3, 2): raise RuntimeError('On Python 3, Pyramid requires Python 3.2 or better') if py_version < (3, 3) and not is_pypy: # PyPy3 masquerades as Python 3.2... raise RuntimeError('On Python 3, Pyramid requires Python 3.3 or better') else: if py_version < (2, 6): raise RuntimeError('On Python 2, Pyramid requires Python 2.6 or better') @@ -56,7 +57,7 @@ tests_require.append('zope.component>=3.11.0') docs_extras = [ 'Sphinx >= 1.3.1', 'Sphinx >= 1.3.5', 'docutils', 'repoze.sphinx.autointerface', 'pylons_sphinx_latesturl', @@ -81,7 +82,6 @@ "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.2", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", tox.ini
@@ -1,6 +1,6 @@ [tox] envlist = py26,py27,py32,py33,py34,py35,pypy,pypy3, py26,py27,py33,py34,py35,pypy,pypy3, docs,pep8, {py2,py3}-cover,coverage, @@ -10,7 +10,6 @@ basepython = py26: python2.6 py27: python2.7 py32: python3.2 py33: python3.3 py34: python3.4 py35: python3.5
