diff options
486 files changed, 14746 insertions, 6218 deletions
diff --git a/.gitignore b/.gitignore index 5fa2a2ee4..8dca2069c 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,7 @@ .coverage .tox/ nosetests.xml -pyramid/coverage.xml +coverage.xml tutorial.db build/ dist/ diff --git a/.travis.yml b/.travis.yml index ab9c3ff30..9d4324ff8 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,3 +1,4 @@ +# Wire up travis language: python python: @@ -6,7 +7,7 @@ python: - pypy - 3.2 -script: python setup.py test +script: python setup.py test -q notifications: email: diff --git a/CHANGES.txt b/CHANGES.txt index 08e498b7a..051328a02 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,9 +1,312 @@ -next release -============ +Unreleased +========== + +Bug Fixes +--------- + +- Fix the ``pcreate`` script so that when the target directory name ends with a + slash it does not produce a non-working project directory structure. + Previously saying ``pcreate -s starter /foo/bar/`` produced different output + than saying ``pcreate -s starter /foo/bar``. The former did not work + properly. + +- Fix the ``principals_allowed_by_permission`` method of + ``ACLAuthorizationPolicy`` so it anticipates a callable ``__acl__`` + on resources. Previously it did not try to call the ``__acl__`` + if it was callable. + +- The ``pviews`` script did not work when a url required custom request + methods in order to perform traversal. Custom methods and descriptors added + via ``pyramid.config.Configurator.add_request_method`` will now be present, + allowing traversal to continue. + See https://github.com/Pylons/pyramid/issues/1104 + +Documentation +------------- + +- Added a "Quick Tutorial" to go with the Quick Tour + +- Removed mention of ``pyramid_beaker`` from docs. Beaker is no longer + maintained. Point people at ``pyramid_redis_sessions`` instead. + +Backwards Incompatibilities +--------------------------- + +- The key/values in the ``_query`` parameter of ``request.route_url`` and the + ``query`` parameter of ``request.resource_url`` (and their variants), used + to encode a value of ``None`` as the string ``'None'``, leaving the resulting + query string to be ``a=b&key=None``. The value is now dropped in this + situation, leaving a query string of ``a=b&key=``. + See https://github.com/Pylons/pyramid/issues/1119 + +1.5a2 (2013-09-22) +================== + +Features +-------- + +- Users can now provide dotted Python names to as the ``factory`` argument + the Configurator methods named ``add_{view,route,subscriber}_predicate`` + (instead of passing the predicate factory directly, you can pass a + dotted name which refers to the factory). + +Bug Fixes +--------- + +- Fix an exception in ``pyramid.path.package_name`` when resolving the package + name for namespace packages that had no ``__file__`` attribute. + +Backwards Incompatibilities +--------------------------- + +- Pyramid no longer depends on or configures the Mako and Chameleon templating + system renderers by default. Disincluding these templating systems by + default means that the Pyramid core has fewer dependencies and can run on + future platforms without immediate concern for the compatibility of its + templating add-ons. It also makes maintenance slightly more effective, as + different people can maintain the templating system add-ons that they + understand and care about without needing commit access to the Pyramid core, + and it allows users who just don't want to see any packages they don't use + come along for the ride when they install Pyramid. + + This means that upon upgrading to Pyramid 1.5a2+, projects that use either + of these templating systems will see a traceback that ends something like + this when their application attempts to render a Chameleon or Mako template:: + + ValueError: No such renderer factory .pt + + Or:: + + ValueError: No such renderer factory .mako + + Or:: + + ValueError: No such renderer factory .mak + + Support for Mako templating has been moved into an add-on package named + ``pyramid_mako``, and support for Chameleon templating has been moved into + an add-on package named ``pyramid_chameleon``. These packages are drop-in + replacements for the old built-in support for these templating langauges. + All you have to do is install them and make them active in your configuration + to register renderer factories for ``.pt`` and/or ``.mako`` (or ``.mak``) to + make your application work again. + + To re-add support for Chameleon and/or Mako template renderers into your + existing projects, follow the below steps. + + If you depend on Mako templates: + + * Make sure the ``pyramid_mako`` package is installed. One way to do this + is by adding ``pyramid_mako`` to the ``install_requires`` section of your + package's ``setup.py`` file and afterwards rerunning ``setup.py develop``:: + + setup( + #... + install_requires=[ + 'pyramid_mako', # new dependency + 'pyramid', + #... + ], + ) + + * Within the portion of your application which instantiates a Pyramid + ``pyramid.config.Configurator`` (often the ``main()`` function in + your project's ``__init__.py`` file), tell Pyramid to include the + ``pyramid_mako`` includeme:: + + config = Configurator(.....) + config.include('pyramid_mako') + + If you depend on Chameleon templates: + + * Make sure the ``pyramid_chameleon`` package is installed. One way to do + this is by adding ``pyramid_chameleon`` to the ``install_requires`` section + of your package's ``setup.py`` file and afterwards rerunning + ``setup.py develop``:: + + setup( + #... + install_requires=[ + 'pyramid_chameleon', # new dependency + 'pyramid', + #... + ], + ) + + * Within the portion of your application which instantiates a Pyramid + ``~pyramid.config.Configurator`` (often the ``main()`` function in + your project's ``__init__.py`` file), tell Pyramid to include the + ``pyramid_chameleon`` includeme:: + + config = Configurator(.....) + config.include('pyramid_chameleon') + + Note that it's also fine to install these packages into *older* Pyramids for + forward compatibility purposes. Even if you don't upgrade to Pyramid 1.5 + immediately, performing the above steps in a Pyramid 1.4 installation is + perfectly fine, won't cause any difference, and will give you forward + compatibility when you eventually do upgrade to Pyramid 1.5. + + With the removal of Mako and Chameleon support from the core, some + unit tests that use the ``pyramid.renderers.render*`` methods may begin to + fail. If any of your unit tests are invoking either + ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response()`` + with either Mako or Chameleon templates then the + ``pyramid.config.Configurator`` instance in effect during + the unit test should be also be updated to include the addons, as shown + above. For example:: + + class ATest(unittest.TestCase): + def setUp(self): + self.config = pyramid.testing.setUp() + self.config.include('pyramid_mako') + + def test_it(self): + result = pyramid.renderers.render('mypkg:templates/home.mako', {}) + + Or:: + + class ATest(unittest.TestCase): + def setUp(self): + self.config = pyramid.testing.setUp() + self.config.include('pyramid_chameleon') + + def test_it(self): + result = pyramid.renderers.render('mypkg:templates/home.pt', {}) + +- If you're using the Pyramid debug toolbar, when you upgrade Pyramid to + 1.5a2+, you'll also need to upgrade the ``pyramid_debugtoolbar`` package to + at least version 1.0.8, as older toolbar versions are not compatible with + Pyramid 1.5a2+ due to the removal of Mako support from the core. It's + fine to use this newer version of the toolbar code with older Pyramids too. + +- Removed the ``request.response_*`` varying attributes. These attributes + have been deprecated since Pyramid 1.1, and as per the deprecation policy, + have now been removed. + +- ``request.response`` will no longer be mutated when using the + ``pyramid.renderers.render()`` API. Almost all renderers mutate the + ``request.response`` response object (for example, the JSON renderer sets + ``request.response.content_type`` to ``application/json``), but this is + only necessary when the renderer is generating a response; it was a bug + when it was done as a side effect of calling ``pyramid.renderers.render()``. + +- Removed the ``bfg2pyramid`` fixer script. + +- The ``pyramid.events.NewResponse`` event is now sent **after** response + callbacks are executed. It previously executed before response callbacks + were executed. Rationale: it's more useful to be able to inspect the response + after response callbacks have done their jobs instead of before. + +- Removed the class named ``pyramid.view.static`` that had been deprecated + since Pyramid 1.1. Instead use ``pyramid.static.static_view`` with + ``use_subpath=True`` argument. + +- Removed the ``pyramid.view.is_response`` function that had been deprecated + since Pyramid 1.1. Use the ``pyramid.request.Request.is_response`` method + instead. + +- Removed the ability to pass the following arguments to + ``pyramid.config.Configurator.add_route``: ``view``, ``view_context``. + ``view_for``, ``view_permission``, ``view_renderer``, and ``view_attr``. + Using these arguments had been deprecated since Pyramid 1.1. Instead of + passing view-related arguments to ``add_route``, use a separate call to + ``pyramid.config.Configurator.add_view`` to associate a view with a route + using its ``route_name`` argument. Note that this impacts the + ``pyramid.config.Configurator.add_static_view`` function too, because it + delegates to ``add_route``. + +- Removed the ability to influence and query a ``pyramid.request.Request`` + object as if it were a dictionary. Previously it was possible to use methods + like ``__getitem__``, ``get``, ``items``, and other dictlike methods to + access values in the WSGI environment. This behavior had been deprecated + since Pyramid 1.1. Use methods of ``request.environ`` (a real dictionary) + instead. + +- Removed ancient backwards compatibily hack in + ``pyramid.traversal.DefaultRootFactory`` which populated the ``__dict__`` of + the factory with the matchdict values for compatibility with BFG 0.9. + +- The ``renderer_globals_factory`` argument to the + ``pyramid.config.Configurator` constructor and its ``setup_registry`` method + has been removed. The ``set_renderer_globals_factory`` method of + ``pyramid.config.Configurator`` has also been removed. The (internal) + ``pyramid.interfaces.IRendererGlobals`` interface was also removed. These + arguments, methods and interfaces had been deprecated since 1.1. Use a + ``BeforeRender`` event subscriber as documented in the "Hooks" chapter of the + Pyramid narrative documentation instead of providing renderer globals values + to the configurator. + +Deprecations +------------ + +- The ``pyramid.config.Configurator.set_request_property`` method now issues + a deprecation warning when used. It had been docs-deprecated in 1.4 + but did not issue a deprecation warning when used. + +1.5a1 (2013-08-30) +================== Features -------- +- A new http exception subclass named ``pyramid.httpexceptions.HTTPSuccessful`` + was added. You can use this class as the ``context`` of an exception + view to catch all 200-series "exceptions" (e.g. "raise HTTPOk"). This + also allows you to catch *only* the ``HTTPOk`` exception itself; previously + this was impossible because a number of other exceptions + (such as ``HTTPNoContent``) inherited from ``HTTPOk``, but now they do not. + +- You can now generate "hybrid" urldispatch/traversal URLs more easily + by using the new ``route_name``, ``route_kw`` and ``route_remainder_name`` + arguments to ``request.resource_url`` and ``request.resource_path``. See + the new section of the "Combining Traversal and URL Dispatch" documentation + chapter entitled "Hybrid URL Generation". + +- It is now possible to escape double braces in Pyramid scaffolds (unescaped, + these represent replacement values). You can use ``\{\{a\}\}`` to + represent a "bare" ``{{a}}``. See + https://github.com/Pylons/pyramid/pull/862 + +- Add ``localizer`` and ``locale_name`` properties (reified) to the request. + See https://github.com/Pylons/pyramid/issues/508. Note that the + ``pyramid.i18n.get_localizer`` and ``pyramid.i18n.get_locale_name`` functions + now simply look up these properties on the request. + +- Add ``pdistreport`` script, which prints the Python version in use, the + Pyramid version in use, and the version number and location of all Python + distributions currently installed. + +- Add the ability to invert the result of any view, route, or subscriber + predicate using the ``not_`` class. For example:: + + from pyramid.config import not_ + + @view_config(route_name='myroute', request_method=not_('POST')) + def myview(request): ... + + The above example will ensure that the view is called if the request method + is not POST (at least if no other view is more specific). + + The ``pyramid.config.not_`` class can be used against any value that is + a predicate value passed in any of these contexts: + + - ``pyramid.config.Configurator.add_view`` + + - ``pyramid.config.Configurator.add_route`` + + - ``pyramid.config.Configurator.add_subscriber`` + + - ``pyramid.view.view_config`` + + - ``pyramid.events.subscriber`` + +- ``scripts/prequest.py``: add support for submitting ``PUT`` and ``PATCH`` + requests. See https://github.com/Pylons/pyramid/pull/1033. add support for + submitting ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify + basic authentication credentials in the request via a ``--login`` argument to + the script. See https://github.com/Pylons/pyramid/pull/1039. + - ``ACLAuthorizationPolicy`` supports ``__acl__`` as a callable. This removes the ambiguity between the potential ``AttributeError`` that would be raised on the ``context`` when the property was not defined and the @@ -15,6 +318,19 @@ Features ``pyramid.config.Configurator.add_static_view``. This allows externally-hosted static URLs to be generated based on the current protocol. +- The ``AuthTktAuthenticationPolicy`` has two new options to configure its + domain usage: + + * ``parent_domain``: if set the authentication cookie is set on + the parent domain. This is useful if you have multiple sites sharing the + same domain. + * ``domain``: if provided the cookie is always set for this domain, bypassing + all usual logic. + + See https://github.com/Pylons/pyramid/pull/1028, + https://github.com/Pylons/pyramid/pull/1072 and + https://github.com/Pylons/pyramid/pull/1078. + - The ``AuthTktAuthenticationPolicy`` now supports IPv6 addresses when using the ``include_ip=True`` option. This is possibly incompatible with alternative ``auth_tkt`` implementations, as the specification does not @@ -29,8 +345,10 @@ Features ``initialize_myapp_db etc/development.ini a=1 b=2``. See https://github.com/Pylons/pyramid/pull/911 -Bug Fixes ---------- +- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view + predicate now take into account the value of the HTTP header named + ``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they + always did). The header is tried when the form parameter does not exist. - View lookup will now search for valid views based on the inheritance hierarchy of the context. It tries to find views based on the most @@ -41,8 +359,6 @@ Bug Fixes raised. Now predicate mismatches don't hide valid views registered on super-types. Here's an example that now works:: - .. code-block:: python - class IResource(Interface): ... @@ -62,7 +378,7 @@ Bug Fixes ... - @implementor(IResource) + @implementer(IResource) class MyResource: ... @@ -77,700 +393,115 @@ Bug Fixes predicate mismatch error when trying to use GET or DELETE methods. Now the views are found and no predicate mismatch is raised. + See https://github.com/Pylons/pyramid/pull/786 and + https://github.com/Pylons/pyramid/pull/1004 and + https://github.com/Pylons/pyramid/pull/1046 -- Spaces and dots may now be in mako renderer template paths. This was - broken when support for the new makodef syntax was added in 1.4a1. - See https://github.com/Pylons/pyramid/issues/950 - -- ``pyramid.debug_authorization=true`` will now correctly print out - ``Allowed`` for views registered with ``NO_PERMISSION_REQUIRED`` instead - of invoking the ``permits`` method of the authorization policy. - See https://github.com/Pylons/pyramid/issues/954 - -1.4 (2012-12-18) -================ - -Docs ----- - -- Fix functional tests in the ZODB tutorial - -1.4b3 (2012-12-10) -================== - -- Packaging release only, no code changes. 1.4b2 was a brownbag release due to - missing directories in the tarball. - -1.4b2 (2012-12-10) -================== - -Docs ----- - -- Scaffolding is now PEP-8 compliant (at least for a brief shining moment). - -- Tutorial improvements. - -Backwards Incompatibilities ---------------------------- - -- Modified the ``_depth`` argument to ``pyramid.view.view_config`` to accept - a value relative to the invocation of ``view_config`` itself. Thus, when it - was previously expecting a value of ``1`` or greater, to reflect that - the caller of ``view_config`` is 1 stack frame away from ``venusian.attach``, - this implementation detail is now hidden. - -- Modified the ``_backframes`` argument to ``pyramid.util.action_method`` in a - similar way to the changes described to ``_depth`` above. This argument - remains undocumented, but might be used in the wild by some insane person. - -1.4b1 (2012-11-21) -================== - -Features --------- - -- Small microspeed enhancement which anticipates that a - ``pyramid.response.Response`` object is likely to be returned from a view. - Some code is shortcut if the class of the object returned by a view is this - class. A similar microoptimization was done to - ``pyramid.request.Request.is_response``. - -- Make it possible to use variable arguments on ``p*`` commands (``pserve``, - ``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can fill in - values in parameterized ``.ini`` file, e.g. ``pshell etc/development.ini - http_port=8080``. See https://github.com/Pylons/pyramid/pull/714 - -- A somewhat advanced and obscure feature of Pyramid event handlers is their - ability to handle "multi-interface" notifications. These notifications have - traditionally presented multiple objects to the subscriber callable. For - instance, if an event was sent by code like this:: - - registry.notify(event, context) - - In the past, in order to catch such an event, you were obligated to write and - register an event subscriber that mentioned both the event and the context in - its argument list:: - - @subscriber([SomeEvent, SomeContextType]) - def asubscriber(event, context): - pass - - In many subscriber callables registered this way, it was common for the logic - in the subscriber callable to completely ignore the second and following - arguments (e.g. ``context`` in the above example might be ignored), because - they usually existed as attributes of the event anyway. You could usually - get the same value by doing ``event.context`` or similar. - - The fact that you needed to put an extra argument which you usually ignored - in the subscriber callable body was only a minor annoyance until we added - "subscriber predicates", used to narrow the set of circumstances under which - a subscriber will be executed, in a prior 1.4 alpha release. Once those were - added, the annoyance was escalated, because subscriber predicates needed to - accept the same argument list and arity as the subscriber callables that they - were configured against. So, for example, if you had these two subscriber - registrations in your code:: - - @subscriber([SomeEvent, SomeContextType]) - def asubscriber(event, context): - pass - - @subscriber(SomeOtherEvent) - def asubscriber(event): - pass - - And you wanted to use a subscriber predicate:: - - @subscriber([SomeEvent, SomeContextType], mypredicate=True) - def asubscriber1(event, context): - pass - - @subscriber(SomeOtherEvent, mypredicate=True) - def asubscriber2(event): - pass - - If an existing ``mypredicate`` subscriber predicate had been written in such - a way that it accepted only one argument in its ``__call__``, you could not - use it against a subscription which named more than one interface in its - subscriber interface list. Similarly, if you had written a subscriber - predicate that accepted two arguments, you couldn't use it against a - registration that named only a single interface type. - - For example, if you created this predicate:: - - class MyPredicate(object): - # portions elided... - def __call__(self, event): - return self.val == event.context.foo - - It would not work against a multi-interface-registered subscription, so in - the above example, when you attempted to use it against ``asubscriber1``, it - would fail at runtime with a TypeError, claiming something was attempting to - call it with too many arguments. - - To hack around this limitation, you were obligated to design the - ``mypredicate`` predicate to expect to receive in its ``__call__`` either a - single ``event`` argument (a SomeOtherEvent object) *or* a pair of arguments - (a SomeEvent object and a SomeContextType object), presumably by doing - something like this:: - - class MyPredicate(object): - # portions elided... - def __call__(self, event, context=None): - return self.val == event.context.foo - - This was confusing and bad. - - In order to allow people to ignore unused arguments to subscriber callables - and to normalize the relationship between event subscribers and subscriber - predicates, we now allow both subscribers and subscriber predicates to accept - only a single ``event`` argument even if they've been subscribed for - notifications that involve multiple interfaces. Subscribers and subscriber - predicates that accept only one argument will receive the first object passed - to ``notify``; this is typically (but not always) the event object. The - other objects involved in the subscription lookup will be discarded. You can - now write an event subscriber that accepts only ``event`` even if it - subscribes to multiple interfaces:: - - @subscriber([SomeEvent, SomeContextType]) - def asubscriber(event): - # this will work! - - This prevents you from needing to match the subscriber callable parameters to - the subscription type unnecessarily, especially when you don't make use of - any argument in your subscribers except for the event object itself. - - Note, however, that if the event object is not the first - object in the call to ``notify``, you'll run into trouble. For example, if - notify is called with the context argument first:: - - registry.notify(context, event) - - You won't be able to take advantage of the event-only feature. It will - "work", but the object received by your event handler won't be the event - object, it will be the context object, which won't be very useful:: - - @subscriber([SomeContextType, SomeEvent]) - def asubscriber(event): - # bzzt! you'll be getting the context here as ``event``, and it'll - # be useless - - Existing multiple-argument subscribers continue to work without issue, so you - should continue use those if your system notifies using multiple interfaces - and the first interface is not the event interface. For example:: - - @subscriber([SomeContextType, SomeEvent]) - def asubscriber(context, event): - # this will still work! - - The event-only feature makes it possible to use a subscriber predicate that - accepts only a request argument within both multiple-interface subscriber - registrations and single-interface subscriber registrations. You needn't - make slightly different variations of predicates depending on the - subscription type arguments. Instead, just write all your subscriber - predicates so they only accept ``event`` in their ``__call__`` and they'll be - useful across all registrations for subscriptions that use an event as their - first argument, even ones which accept more than just ``event``. - - However, the same caveat applies to predicates as to subscriber callables: if - you're subscribing to a multi-interface event, and the first interface is not - the event interface, the predicate won't work properly. In such a case, - you'll need to match the predicate ``__call__`` argument ordering and - composition to the ordering of the interfaces. For example, if the - registration for the subscription uses ``[SomeContext, SomeEvent]``, you'll - need to reflect that in the ordering of the parameters of the predicate's - ``__call__`` method:: - - def __call__(self, context, event): - return event.request.path.startswith(self.val) - - tl;dr: 1) When using multi-interface subscriptions, always use the event type - as the first subscription registration argument and 2) When 1 is true, use - only ``event`` in your subscriber and subscriber predicate parameter lists, - no matter how many interfaces the subscriber is notified with. This - combination will result in the maximum amount of reusability of subscriber - predicates and the least amount of thought on your part. Drink responsibly. - -Bug Fixes ---------- - -- A failure when trying to locate the attribute ``__text__`` on route and view - predicates existed when the ``debug_routematch`` setting was true or when the - ``pviews`` command was used. See https://github.com/Pylons/pyramid/pull/727 - -Documentation -------------- - -- Sync up tutorial source files with the files that are rendered by the - scaffold that each uses. +- The ``pserve`` command now takes a ``-v`` (or ``--verbose``) flag and a + ``-q`` (or ``--quiet``) flag. Output from running ``pserve`` can be + controlled using these flags. ``-v`` can be specified multiple times to + increase verbosity. ``-q`` sets verbosity to ``0`` unconditionally. The + default verbosity level is ``1``. -1.4a4 (2012-11-14) -================== - -Features --------- - -- ``pyramid.authentication.AuthTktAuthenticationPolicy`` has been updated to - support newer hashing algorithms such as ``sha512``. Existing applications - should consider updating if possible for improved security over the default - md5 hashing. - -- Added an ``effective_principals`` route and view predicate. - -- Do not allow the userid returned from the ``authenticated_userid`` or the - userid that is one of the list of principals returned by - ``effective_principals`` to be either of the strings ``system.Everyone`` or - ``system.Authenticated`` when any of the built-in authorization policies that - live in ``pyramid.authentication`` are in use. These two strings are - reserved for internal usage by Pyramid and they will not be accepted as valid - userids. - -- Slightly better debug logging from - ``pyramid.authentication.RepozeWho1AuthenticationPolicy``. - -- ``pyramid.security.view_execution_permitted`` used to return ``True`` if no - view could be found. It now raises a ``TypeError`` exception in that case, as - it doesn't make sense to assert that a nonexistent view is - execution-permitted. See https://github.com/Pylons/pyramid/issues/299. - -- Allow a ``_depth`` argument to ``pyramid.view.view_config``, which will - permit limited composition reuse of the decorator by other software that - wants to provide custom decorators that are much like view_config. - -- Allow an iterable of decorators to be passed to - ``pyramid.config.Configurator.add_view``. This allows views to be wrapped - by more than one decorator without requiring combining the decorators - yourself. - -Bug Fixes ---------- - -- In the past if a renderer returned ``None``, the body of the resulting - response would be set explicitly to the empty string. Instead, now, the body - is left unchanged, which allows the renderer to set a body itself by using - e.g. ``request.response.body = b'foo'``. The body set by the renderer will - be unmolested on the way out. See - https://github.com/Pylons/pyramid/issues/709 - -- In uncommon cases, the ``pyramid_excview_tween_factory`` might have - inadvertently raised a ``KeyError`` looking for ``request_iface`` as an - attribute of the request. It no longer fails in this case. See - https://github.com/Pylons/pyramid/issues/700 - -- Be more tolerant of potential error conditions in ``match_param`` and - ``physical_path`` predicate implementations; instead of raising an exception, - return False. - -- ``pyramid.view.render_view`` was not functioning properly under Python 3.x - due to a byte/unicode discrepancy. See - https://github.com/Pylons/pyramid/issues/721 - -Deprecations ------------- - -- ``pyramid.authentication.AuthTktAuthenticationPolicy`` will emit a warning if - an application is using the policy without explicitly passing a ``hashalg`` - argument. This is because the default is "md5" which is considered - theoretically subject to collision attacks. If you really want "md5" then you - must specify it explicitly to get rid of the warning. - -Documentation -------------- - -- All of the tutorials that use - ``pyramid.authentication.AuthTktAuthenticationPolicy`` now explicitly pass - ``sha512`` as a ``hashalg`` argument. - - -Internals ---------- - -- Move ``TopologicalSorter`` from ``pyramid.config.util`` to ``pyramid.util``, - move ``CyclicDependencyError`` from ``pyramid.config.util`` to - ``pyramid.exceptions``, rename ``Singleton`` to ``Sentinel`` and move from - ``pyramid.config.util`` to ``pyramid.util``; this is in an effort to - move that stuff that may be an API one day out of ``pyramid.config.util``, - because that package should never be imported from non-Pyramid code. - TopologicalSorter is still not an API, but may become one. - -- Get rid of shady monkeypatching of ``pyramid.request.Request`` and - ``pyramid.response.Response`` done within the ``__init__.py`` of Pyramid. - Webob no longer relies on this being done. Instead, the ResponseClass - attribute of the Pyramid Request class is assigned to the Pyramid response - class; that's enough to satisfy WebOb and behave as it did before with the - monkeypatching. - -1.4a3 (2012-10-26) -================== - -Bug Fixes ---------- - -- The match_param predicate's text method was fixed to sort its values. - Part of https://github.com/Pylons/pyramid/pull/705 - -- 1.4a ``pyramid.scripting.prepare`` behaved differently than 1.3 series - function of same name. In particular, if passed a request, it would not - set the ``registry`` attribute of the request like 1.3 did. A symptom - would be that passing a request to ``pyramid.paster.bootstrap`` (which uses - the function) that did not have a ``registry`` attribute could assume that - the registry would be attached to the request by Pyramid. This assumption - could be made in 1.3, but not in 1.4. The assumption can now be made in - 1.4 too (a registry is attached to a request passed to bootstrap or - prepare). - -- When registering a view configuration that named a Chameleon ZPT renderer - with a macro name in it (e.g. ``renderer='some/template#somemacro.pt``) as - well as a view configuration without a macro name in it that pointed to the - same template (e.g. ``renderer='some/template.pt'``), internal caching could - confuse the two, and your code might have rendered one instead of the - other. - -Features --------- +- The ``alchemy`` scaffold tests now provide better coverage. See + https://github.com/Pylons/pyramid/pull/1029 -- Allow multiple values to be specified to the ``request_param`` view/route - predicate as a sequence. Previously only a single string value was allowed. - See https://github.com/Pylons/pyramid/pull/705 - -- Comments with references to documentation sections placed in scaffold - ``.ini`` files. - -- Added an HTTP Basic authentication policy - at ``pyramid.authentication.BasicAuthAuthenticationPolicy``. - -- The Configurator ``testing_securitypolicy`` method now returns the policy - object it creates. - -- The Configurator ``testing_securitypolicy`` method accepts two new - arguments: ``remember_result`` and ``forget_result``. If supplied, these - values influence the result of the policy's ``remember`` and ``forget`` - methods, respectively. - -- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a - ``forgotten`` value on the policy (the value ``True``) when its ``forget`` - method is called. - -- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a - ``remembered`` value on the policy, which is the value of the ``principal`` - argument it's called with when its ``remember`` method is called. - -- New ``physical_path`` view predicate. If specified, this value should be a - string or a tuple representing the physical traversal path of the context - found via traversal for this predicate to match as true. For example: - ``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('', - 'a', 'b', 'c')``. This is not a path prefix match or a regex, it's a - whole-path match. It's useful when you want to always potentially show a - view when some object is traversed to, but you can't be sure about what kind - of object it will be, so you can't use the ``context`` predicate. The - individual path elements inbetween slash characters or in tuple elements - should be the Unicode representation of the name of the resource and should - not be encoded in any way. - -1.4a2 (2012-09-27) -================== +- The ``pyramid.config.Configurator.add_route`` method now supports being + called with an external URL as pattern. See + https://github.com/Pylons/pyramid/issues/611 and the documentation section + in the "URL Dispatch" chapter entitled "External Routes" for more information. Bug Fixes --------- -- When trying to determine Mako defnames and Chameleon macro names in asset - specifications, take into account that the filename may have a hyphen in - it. See https://github.com/Pylons/pyramid/pull/692 - -Features --------- - -- A new ``pyramid.session.check_csrf_token`` convenience function was added. - -- A ``check_csrf`` view predicate was added. For example, you can now do - ``config.add_view(someview, check_csrf=True)``. When the predicate is - checked, if the ``csrf_token`` value in ``request.params`` matches the CSRF - token in the request's session, the view will be permitted to execute. - Otherwise, it will not be permitted to execute. - -- Add ``Base.metadata.bind = engine`` to alchemy template, so that tables - defined imperatively will work. - -Documentation -------------- +- It was not possible to use ``pyramid.httpexceptions.HTTPException`` as + the ``context`` of an exception view as very general catchall for + http-related exceptions when you wanted that exception view to override the + default exception view. See https://github.com/Pylons/pyramid/issues/985 + +- When the ``pyramid.reload_templates`` setting was true, and a Chameleon + template was reloaded, and the renderer specification named a macro + (e.g. ``foo#macroname.pt``), renderings of the template after the template + was reloaded due to a file change would produce the entire template body + instead of just a rendering of the macro. See + https://github.com/Pylons/pyramid/issues/1013. + +- Fix an obscure problem when combining a virtual root with a route with a + ``*traverse`` in its pattern. Now the traversal path generated in + such a configuration will be correct, instead of an element missing + a leading slash. + +- Fixed a Mako renderer bug returning a tuple with a previous defname value + in some circumstances. See https://github.com/Pylons/pyramid/issues/1037 + for more information. + +- Make the ``pyramid.config.assets.PackageOverrides`` object implement the API + for ``__loader__`` objects specified in PEP 302. Proxies to the + ``__loader__`` set by the importer, if present; otherwise, raises + ``NotImplementedError``. This makes Pyramid static view overrides work + properly under Python 3.3 (previously they would not). See + https://github.com/Pylons/pyramid/pull/1015 for more information. + +- ``mako_templating``: added defensive workaround for non-importability of + ``mako`` due to upstream ``markupsafe`` dropping Python 3.2 support. Mako + templating will no longer work under the combination of MarkupSafe 0.17 and + Python 3.2 (although the combination of MarkupSafe 0.17 and Python 3.3 or any + supported Python 2 version will work OK). -- update wiki2 SQLA tutorial with the changes required after inserting - ``Base.metadata.bind = engine`` into the alchemy scaffold. - -1.4a1 (2012-09-16) -================== - -Bug Fixes ---------- - -- Forward port from 1.3 branch: When no authentication policy was configured, - a call to ``pyramid.security.effective_principals`` would unconditionally - return the empty list. This was incorrect, it should have unconditionally - returned ``[Everyone]``, and now does. - -- Explicit url dispatch regexes can now contain colons. - https://github.com/Pylons/pyramid/issues/629 - -- On at least one 64-bit Ubuntu system under Python 3.2, using the - ``view_config`` decorator caused a ``RuntimeError: dictionary changed size - during iteration`` exception. It no longer does. See - https://github.com/Pylons/pyramid/issues/635 for more information. - -- In Mako Templates lookup, check if the uri is already adjusted and bring - it back to an asset spec. Normally occurs with inherited templates or - included components. - https://github.com/Pylons/pyramid/issues/606 - https://github.com/Pylons/pyramid/issues/607 - -- In Mako Templates lookup, check for absolute uri (using mako directories) - when mixing up inheritance with asset specs. - https://github.com/Pylons/pyramid/issues/662 +- Spaces and dots may now be in mako renderer template paths. This was + broken when support for the new makodef syntax was added in 1.4a1. + See https://github.com/Pylons/pyramid/issues/950 -- HTTP Accept headers were not being normalized causing potentially - conflicting view registrations to go unnoticed. Two views that only - differ in the case ('text/html' vs. 'text/HTML') will now raise an error. - https://github.com/Pylons/pyramid/pull/620 +- ``pyramid.debug_authorization=true`` will now correctly print out + ``Allowed`` for views registered with ``NO_PERMISSION_REQUIRED`` instead + of invoking the ``permits`` method of the authorization policy. + See https://github.com/Pylons/pyramid/issues/954 -- Forward-port from 1.3 branch: when registering multiple views with an - ``accept`` predicate in a Pyramid application runing under Python 3, you - might have received a ``TypeError: unorderable types: function() < - function()`` exception. +- Pyramid failed to install on some systems due to being packaged with + some test files containing higher order characters in their names. These + files have now been removed. See + https://github.com/Pylons/pyramid/issues/981 -Features --------- +- ``pyramid.testing.DummyResource`` didn't define ``__bool__``, so code under + Python 3 would use ``__len__`` to find truthiness; this usually caused an + instance of DummyResource to be "falsy" instead of "truthy". See + https://github.com/Pylons/pyramid/pull/1032 -- Configurator.add_directive now accepts arbitrary callables like partials or - objects implementing ``__call__`` which dont have ``__name__`` and - ``__doc__`` attributes. See https://github.com/Pylons/pyramid/issues/621 - and https://github.com/Pylons/pyramid/pull/647. - -- Third-party custom view, route, and subscriber predicates can now be added - for use by view authors via - ``pyramid.config.Configurator.add_view_predicate``, - ``pyramid.config.Configurator.add_route_predicate`` and - ``pyramid.config.Configurator.add_subscriber_predicate``. So, for example, - doing this:: - - config.add_view_predicate('abc', my.package.ABCPredicate) - - Might allow a view author to do this in an application that configured that - predicate:: - - @view_config(abc=1) - - Similar features exist for ``add_route``, and ``add_subscriber``. See - "Adding A Third Party View, Route, or Subscriber Predicate" in the Hooks - chapter for more information. - - Note that changes made to support the above feature now means that only - actions registered using the same "order" can conflict with one another. - It used to be the case that actions registered at different orders could - potentially conflict, but to my knowledge nothing ever depended on this - behavior (it was a bit silly). - -- Custom objects can be made easily JSON-serializable in Pyramid by defining - a ``__json__`` method on the object's class. This method should return - values natively serializable by ``json.dumps`` (such as ints, lists, - dictionaries, strings, and so forth). - -- The JSON renderer now allows for the definition of custom type adapters to - convert unknown objects to JSON serializations. - -- As of this release, the ``request_method`` predicate, when used, will also - imply that ``HEAD`` is implied when you use ``GET``. For example, using - ``@view_config(request_method='GET')`` is equivalent to using - ``@view_config(request_method=('GET', 'HEAD'))``. Using - ``@view_config(request_method=('GET', 'POST')`` is equivalent to using - ``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because - HEAD is a variant of GET that omits the body, and WebOb has special support - to return an empty body when a HEAD is used. - -- ``config.add_request_method`` has been introduced to support extending - request objects with arbitrary callables. This method expands on the - previous ``config.set_request_property`` by supporting methods as well as - properties. This method now causes less code to be executed at - request construction time than ``config.set_request_property`` in - version 1.3. - -- Don't add a ``?`` to URLs generated by ``request.resource_url`` if the - ``query`` argument is provided but empty. - -- Don't add a ``?`` to URLs generated by ``request.route_url`` if the - ``_query`` argument is provided but empty. - -- The static view machinery now raises (rather than returns) ``HTTPNotFound`` - and ``HTTPMovedPermanently`` exceptions, so these can be caught by the - Not Found View (and other exception views). - -- The Mako renderer now supports a def name in an asset spec. When the def - name is present in the asset spec, the system will render the template def - within the template and will return the result. An example asset spec is - ``package:path/to/template#defname.mako``. This will render the def named - ``defname`` inside the ``template.mako`` template instead of rendering the - entire template. The old way of returning a tuple in the form - ``('defname', {})`` from the view is supported for backward compatibility, - -- The Chameleon ZPT renderer now accepts a macro name in an asset spec. When - the macro name is present in the asset spec, the system will render the - macro listed as a ``define-macro`` and return the result instead of - rendering the entire template. An example asset spec: - ``package:path/to/template#macroname.pt``. This will render the macro - defined as ``macroname`` within the ``template.pt`` template instead of the - entire templae. - -- When there is a predicate mismatch exception (seen when no view matches for - a given request due to predicates not working), the exception now contains - a textual description of the predicate which didn't match. - -- An ``add_permission`` directive method was added to the Configurator. This - directive registers a free-standing permission introspectable into the - Pyramid introspection system. Frameworks built atop Pyramid can thus use - the ``permissions`` introspectable category data to build a - comprehensive list of permissions supported by a running system. Before - this method was added, permissions were already registered in this - introspectable category as a side effect of naming them in an ``add_view`` - call, this method just makes it possible to arrange for a permission to be - put into the ``permissions`` introspectable category without naming it - along with an associated view. Here's an example of usage of - ``add_permission``:: - - config = Configurator() - config.add_permission('view') - -- The ``UnencryptedCookieSessionFactoryConfig`` now accepts - ``signed_serialize`` and ``signed_deserialize`` hooks which may be used - to influence how the sessions are marshalled (by default this is done - with HMAC+pickle). - -- ``pyramid.testing.DummyRequest`` now supports methods supplied by the - ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. - -- Request properties and methods added via ``config.set_request_property`` or - ``config.add_request_method`` are now available to tweens. - -- Request properties and methods added via ``config.set_request_property`` or - ``config.add_request_method`` are now available in the request object - returned from ``pyramid.paster.bootstrap``. - -- ``request.context`` of environment request during ``bootstrap`` is now the - root object if a context isn't already set on a provided request. - -- The ``pyramid.decorator.reify`` function is now an API, and was added to - the API documentation. - -- Added the ``pyramid.testing.testConfig`` context manager, which can be used - to generate a configurator in a test, e.g. ``with testing.testConfig(...):``. - -- Users can now invoke a subrequest from within view code using a new - ``request.invoke_subrequest`` API. +- The ``alchemy`` scaffold would break when the database was MySQL during + tables creation. See https://github.com/Pylons/pyramid/pull/1049 -Deprecations ------------- +- The ``current_route_url`` method now attaches the query string to the URL by + default. See + https://github.com/Pylons/pyramid/issues/1040 -- The ``pyramid.config.Configurator.set_request_property`` has been - documentation-deprecated. The method remains usable but the more - featureful ``pyramid.config.Configurator.add_request_method`` should be - used in its place (it has all of the same capabilities but can also extend - the request object with methods). +- Make ``pserve.cherrypy_server_runner`` Python 3 compatible. See + https://github.com/Pylons/pyramid/issues/718 Backwards Incompatibilities --------------------------- -- The Pyramid router no longer adds the values ``bfg.routes.route`` or - ``bfg.routes.matchdict`` to the request's WSGI environment dictionary. - These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven - minor releases ago). If your code depended on these values, use - request.matched_route and request.matchdict instead. - -- It is no longer possible to pass an environ dictionary directly to - ``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka - ``ModelGraphTraverser.__call__``). Instead, you must pass a request - object. Passing an environment instead of a request has generated a - deprecation warning since Pyramid 1.1. - -- Pyramid will no longer work properly if you use the - ``webob.request.LegacyRequest`` as a request factory. Instances of the - LegacyRequest class have a ``request.path_info`` which return a string. - This Pyramid release assumes that ``request.path_info`` will - unconditionally be Unicode. - -- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` - named ``get_renderer``, ``get_template``, ``render_template``, and - ``render_template_to_response`` have been removed. These have issued a - deprecation warning upon import since Pyramid 1.0. Use - ``pyramid.renderers.get_renderer()``, - ``pyramid.renderers.get_renderer().implementation()``, - ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response`` - respectively instead of these functions. - -- The ``pyramid.configuration`` module was removed. It had been deprecated - since Pyramid 1.0 and printed a deprecation warning upon its use. Use - ``pyramid.config`` instead. - -- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been - deprecated since Pyramid 1.1 and issued a warning on import. If your code - depended on this, adjust your code to import - ``pyramid.scaffolds.PyramidTemplate`` instead. - -- The ``pyramid.settings.get_settings()`` API was removed. It had been - printing a deprecation warning since Pyramid 1.0. If your code depended on - this API, use ``pyramid.threadlocal.get_current_registry().settings`` - instead or use the ``settings`` attribute of the registry available from - the request (``request.registry.settings``). - -- These APIs from the ``pyramid.testing`` module were removed. They have - been printing deprecation warnings since Pyramid 1.0: - - * ``registerDummySecurityPolicy``, use - ``pyramid.config.Configurator.testing_securitypolicy`` instead. - - * ``registerResources`` (aka ``registerModels``, use - ``pyramid.config.Configurator.testing_resources`` instead. - - * ``registerEventListener``, use - ``pyramid.config.Configurator.testing_add_subscriber`` instead. - - * ``registerTemplateRenderer`` (aka `registerDummyRenderer``), use - ``pyramid.config.Configurator.testing_add_template`` instead. - - * ``registerView``, use ``pyramid.config.Configurator.add_view`` instead. - - * ``registerUtility``, use - ``pyramid.config.Configurator.registry.registerUtility`` instead. - - * ``registerAdapter``, use - ``pyramid.config.Configurator.registry.registerAdapter`` instead. - - * ``registerSubscriber``, use - ``pyramid.config.Configurator.add_subscriber`` instead. - - * ``registerRoute``, use - ``pyramid.config.Configurator.add_route`` instead. - - * ``registerSettings``, use - ``pyramid.config.Configurator.add_settings`` instead. - -- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object - was invoked before any finished callbacks were executed. As of this - release, the ``__call__`` method of a Response object is invoked *after* - finished callbacks are executed. This is in support of the - ``request.invoke_subrequest`` feature. - -Documentation -------------- - -- Added an "Upgrading Pyramid" chapter to the narrative documentation. It - describes how to cope with deprecations and removals of Pyramid APIs and - how to show Pyramid-generated deprecation warnings while running tests and - while running a server. - -- Added a "Invoking a Subrequest" chapter to the documentation. It describes - how to use the new ``request.invoke_subrequest`` API. - -Dependencies ------------- - -- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on - 1.2dev+). This is to ensure that we obtain a version of WebOb that returns - ``request.path_info`` as text. +- Modified the ``current_route_url`` method in pyramid.Request. The method + previously returned the URL without the query string by default, it now does + attach the query string unless it is overriden. + +- The ``route_url`` and ``route_path`` APIs no longer quote ``/`` + to ``%2F`` when a replacement value contains a ``/``. This was pointless, + as WSGI servers always unquote the slash anyway, and Pyramid never sees the + quoted value. + +- It is no longer possible to set a ``locale_name`` attribute of the request, + nor is it possible to set a ``localizer`` attribute of the request. These + are now "reified" properties that look up a locale name and localizer + respectively using the machinery described in the "Internationalization" + chapter of the documentation. + +- If you send an ``X-Vhm-Root`` header with a value that ends with a slash (or + any number of slashes), the trailing slash(es) will be removed before a URL + is generated when you use use ``request.resource_url`` or + ``request.resource_path``. Previously the virtual root path would not have + trailing slashes stripped, which would influence URL generation. + +- The ``pyramid.interfaces.IResourceURL`` interface has now grown two new + attributes: ``virtual_path_tuple`` and ``physical_path_tuple``. These should + be the tuple form of the resource's path (physical and virtual). diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt index 97eb54f7b..bfe22e540 100644 --- a/CONTRIBUTORS.txt +++ b/CONTRIBUTORS.txt @@ -198,3 +198,29 @@ Contributors - Georges Dubus, 2013/03/21 - Jason McKellar, 2013/03/28 + +- Luke Cyca, 2013/05/30 + +- Laurence Rowe, 2013/04/24 + +- Julian P. Glass, 2013/08/10 + +- Junaid Ali, 2013/08/10 + +- Chris Davies, 2013/08/11 + +- Jonathan Villemaire-Krajden, 2013/08/13 + +- Charlie Clark, 2013/08/15 + +- Tom Lazar, 2013/08/15 + +- Andreas Zeidler, 2013/08/15 + +- Matthew Wilkes, 2013/08/23 + +- Takahiro Fujiwara, 2013/08/28 + +- Doug Hellmann, 2013/09/06 + +- Karl O. Pinc, 2013/09/27 diff --git a/HACKING.txt b/HACKING.txt index 26e85ee80..be67000ce 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -6,28 +6,43 @@ Here are some guidelines about hacking on Pyramid. Using a Development Checkout ---------------------------- -Below is a quick start on creating a development environment using a Pyramid -checkout. +You'll have to create a development environment to hack on Pyramid, using a +Pyramid checkout. You can either do this by hand or, if you have ``tox`` +installed (it's on PyPI), you can (ab)use tox to get a working development +environment. Each installation method is described below. -- Create a new directory somewhere and ``cd`` to it:: +By Hand ++++++++ - $ mkdir ~/hack-on-pyramid - $ cd ~/hack-on-pyramid +- Check out Pyramid from source:: -- Check out a read-only copy of the Pyramid source:: + $ cd ~ + $ git clone git://github.com/Pylons/pyramid.git hack-on-pyramid + $ cd hack-on-pyramid - $ git clone git://github.com/Pylons/pyramid.git +- Create a virtualenv in which to install Pyramid:: - (alternately, create a writeable fork on GitHub and check that out). + $ cd ~/hack-on-pyramid + $ virtualenv -ppython2.7 env -- Create a virtualenv in which to install Pyramid:: + Note that very old versions of virtualenv (virtualenv versions below, say, + 1.10 or thereabouts) require you to pass a ``--no-site-packages`` flag to + get a completely isolated environment. If you're on an old system, use + ``virtualenv --no-site-packages`` instead of ``virtualenv`` above. + + You can choose which Python version you want to use by passing a ``-p`` + flag to ``virtualenv``. For example, ``virtualenv -ppython2.7`` + chooses the Python 2.7 interpreter to be installed. - $ virtualenv2.6 --no-site-packages env + From here on in within these instructions, the ``~/hack-on-pyramid/env`` + virtual environment you created above will be referred to as ``$VENV``. + To use the instructions in the steps that follow literally, use the + ``export VENV=~/hack-on-pyramid/env`` command. - Install ``setuptools-git`` into the virtualenv (for good measure, as we're using git to do version control):: - $ $VENV/bin/easy_install setuptools-git + $ $VENV/bin/easy_install setuptools-git - Install Pyramid from the checkout into the virtualenv using ``setup.py dev``. ``setup.py dev`` is an alias for "setup.py develop" which also @@ -35,21 +50,54 @@ checkout. ``setup.py dev`` *must* be done while the current working directory is the ``pyramid`` checkout directory:: - $ cd pyramid - $ $VENV/bin/python setup.py dev + $ cd ~/hack-on-pyramid + $ $VENV/bin/python setup.py dev - At that point, you should be able to create new Pyramid projects by using ``pcreate``:: - $ cd ../env - $ $VENV/bin/pcreate -s starter starter + $ cd $VENV + $ bin/pcreate -s starter starter - And install those projects (also using ``setup.py develop``) into the virtualenv:: - $ cd starter + $ cd $VENV/starter $ $VENV/bin/python setup.py develop +Using Tox ++++++++++ + +Alternatively, if you already have ``tox`` installed, there is an easier +way to get going. + +- Create a new directory somewhere and ``cd`` to it:: + + $ mkdir ~/hack-on-pyramid + $ cd ~/hack-on-pyramid + +- Check out a read-only copy of the Pyramid source:: + + $ git clone git://github.com/Pylons/pyramid.git . + + (alternately, create a writeable fork on GitHub and check that out). + +Since pyramid is a framework and not an application, it can be +convenient to work against a sample application, preferably in its own +virtualenv. A quick way to achieve this is to (ab-)use ``tox`` +(http://tox.readthedocs.org/en/latest/) with a custom configuration +file that's part of the checkout:: + + tox -c hacking-tox.ini + +This will create a python-2.7 based virtualenv named ``env27`` (pyramid's +``.gitconfig` ignores all top-level folders that start with ``env`` specifically +for this use case) and inside that a simple pyramid application named +``hacking`` that you can then fire up like so:: + + cd env27/hacking + ../bin/pserve development.ini + Adding Features --------------- @@ -59,7 +107,7 @@ In order to add a feature to Pyramid: documentation (in ``docs/``). - The feature must work fully on the following CPython versions: 2.6, - 2.7, and 3.2 on both UNIX and Windows. + 2.7, 3.2, and 3.3 on both UNIX and Windows. - The feature must work on the latest version of PyPy. @@ -85,7 +133,9 @@ Coding Style - PEP8 compliance. Whitespace rules are relaxed: not necessary to put 2 newlines between classes. But 80-column lines, in particular, are - mandatory. + mandatory. See + http://docs.pylonsproject.org/en/latest/community/codestyle.html for more + information. - Please do not remove trailing whitespace. Configure your editor to reduce diff noise. See https://github.com/Pylons/pyramid/issues/788 for more. @@ -93,9 +143,15 @@ Coding Style Running Tests -------------- -- To run tests for Pyramid on a single Python version, run ``python setup.py - test`` against the Python interpreter from virtualenv into which - you've ``setup.py develop``-ed Pyramid. +- To run all tests for Pyramid on a single Python version, run ``nosetests`` + from your development virtualenv (See *Using a Development Checkout* above). + +- To run individual tests (i.e. during development) you can use a regular + expression with the ``-t`` parameter courtesy of the `nose-selecttests + <https://pypi.python.org/pypi/nose-selecttests/>`_ plugin that's been + installed (along with nose itself) via ``python setup.py dev``. The + easiest usage is to simply provide the verbatim name of the test you're + working on. - To run the full set of Pyramid tests on all platforms, install ``tox`` (http://codespeak.net/~hpk/tox/) into a system Python. The ``tox`` console @@ -106,10 +162,17 @@ Running Tests it creates a virtualenv for each version/platform combination. For example:: - $ /usr/bin/easy_install tox - $ cd ~/hack-on-pyramid/pyramid + $ sudo /usr/bin/easy_install tox + $ cd ~/hack-on-pyramid/ $ /usr/bin/tox +- The tests can also be run usign ``pytest`` (http://pytest.org/). This is + intended as a convenience for people who are more used or fond of ``pytest``. + Run the tests like so:: + + $ $VENV/bin/easy_install pytest + $ py.test --strict pyramid/ + Test Coverage ------------- @@ -126,21 +189,31 @@ documentation in this package which references that API or behavior must change to reflect the bug fix, ideally in the same commit that fixes the bug or adds the feature. -To build and review docs (where ``$yourvenv`` refers to the virtualenv you're +To build and review docs (where ``$VENV`` refers to the virtualenv you're using to develop Pyramid): -1. Run ``$VENV/bin/python setup.py dev docs``. This will cause Sphinx - and all development requirements to be installed in your virtualenv. +1. After follwing the steps above in "Using a Development Checkout", cause + Sphinx and all development requirements to be installed in your + virtualenv:: + + $ cd ~/hack-on-pyramid + $ $VENV/bin/python setup.py docs 2. Update all git submodules from the top-level of your Pyramid checkout, like - so: - git submodule update --init --recursive + so:: + + $ git submodule update --init --recursive + This will checkout theme subrepositories and prevent error conditions when HTML docs are generated. 3. cd to the ``docs`` directory within your Pyramid checkout and execute - ``make clean html SPHINXBUILD=$VENV/bin/sphinx-build``. The - ``SPHINXBUILD=...`` hair is there in order to tell it to use the + the ``make`` command with some flags:: + + $ cd ~/hack-on-pyramid/pyramid/docs + $ make clean html SPHINXBUILD=$VENV/bin/sphinx-build + + The ``SPHINXBUILD=...`` hair is there in order to tell it to use the virtualenv Python, which will have both Sphinx and Pyramid (for API documentation generation) installed. diff --git a/HISTORY.txt b/HISTORY.txt index 67de56998..6aad221a8 100644 --- a/HISTORY.txt +++ b/HISTORY.txt @@ -1,3 +1,698 @@ +1.4 (2012-12-18) +================ + +Docs +---- + +- Fix functional tests in the ZODB tutorial + +1.4b3 (2012-12-10) +================== + +- Packaging release only, no code changes. 1.4b2 was a brownbag release due to + missing directories in the tarball. + +1.4b2 (2012-12-10) +================== + +Docs +---- + +- Scaffolding is now PEP-8 compliant (at least for a brief shining moment). + +- Tutorial improvements. + +Backwards Incompatibilities +--------------------------- + +- Modified the ``_depth`` argument to ``pyramid.view.view_config`` to accept + a value relative to the invocation of ``view_config`` itself. Thus, when it + was previously expecting a value of ``1`` or greater, to reflect that + the caller of ``view_config`` is 1 stack frame away from ``venusian.attach``, + this implementation detail is now hidden. + +- Modified the ``_backframes`` argument to ``pyramid.util.action_method`` in a + similar way to the changes described to ``_depth`` above. This argument + remains undocumented, but might be used in the wild by some insane person. + +1.4b1 (2012-11-21) +================== + +Features +-------- + +- Small microspeed enhancement which anticipates that a + ``pyramid.response.Response`` object is likely to be returned from a view. + Some code is shortcut if the class of the object returned by a view is this + class. A similar microoptimization was done to + ``pyramid.request.Request.is_response``. + +- Make it possible to use variable arguments on ``p*`` commands (``pserve``, + ``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can fill in + values in parameterized ``.ini`` file, e.g. ``pshell etc/development.ini + http_port=8080``. See https://github.com/Pylons/pyramid/pull/714 + +- A somewhat advanced and obscure feature of Pyramid event handlers is their + ability to handle "multi-interface" notifications. These notifications have + traditionally presented multiple objects to the subscriber callable. For + instance, if an event was sent by code like this:: + + registry.notify(event, context) + + In the past, in order to catch such an event, you were obligated to write and + register an event subscriber that mentioned both the event and the context in + its argument list:: + + @subscriber([SomeEvent, SomeContextType]) + def asubscriber(event, context): + pass + + In many subscriber callables registered this way, it was common for the logic + in the subscriber callable to completely ignore the second and following + arguments (e.g. ``context`` in the above example might be ignored), because + they usually existed as attributes of the event anyway. You could usually + get the same value by doing ``event.context`` or similar. + + The fact that you needed to put an extra argument which you usually ignored + in the subscriber callable body was only a minor annoyance until we added + "subscriber predicates", used to narrow the set of circumstances under which + a subscriber will be executed, in a prior 1.4 alpha release. Once those were + added, the annoyance was escalated, because subscriber predicates needed to + accept the same argument list and arity as the subscriber callables that they + were configured against. So, for example, if you had these two subscriber + registrations in your code:: + + @subscriber([SomeEvent, SomeContextType]) + def asubscriber(event, context): + pass + + @subscriber(SomeOtherEvent) + def asubscriber(event): + pass + + And you wanted to use a subscriber predicate:: + + @subscriber([SomeEvent, SomeContextType], mypredicate=True) + def asubscriber1(event, context): + pass + + @subscriber(SomeOtherEvent, mypredicate=True) + def asubscriber2(event): + pass + + If an existing ``mypredicate`` subscriber predicate had been written in such + a way that it accepted only one argument in its ``__call__``, you could not + use it against a subscription which named more than one interface in its + subscriber interface list. Similarly, if you had written a subscriber + predicate that accepted two arguments, you couldn't use it against a + registration that named only a single interface type. + + For example, if you created this predicate:: + + class MyPredicate(object): + # portions elided... + def __call__(self, event): + return self.val == event.context.foo + + It would not work against a multi-interface-registered subscription, so in + the above example, when you attempted to use it against ``asubscriber1``, it + would fail at runtime with a TypeError, claiming something was attempting to + call it with too many arguments. + + To hack around this limitation, you were obligated to design the + ``mypredicate`` predicate to expect to receive in its ``__call__`` either a + single ``event`` argument (a SomeOtherEvent object) *or* a pair of arguments + (a SomeEvent object and a SomeContextType object), presumably by doing + something like this:: + + class MyPredicate(object): + # portions elided... + def __call__(self, event, context=None): + return self.val == event.context.foo + + This was confusing and bad. + + In order to allow people to ignore unused arguments to subscriber callables + and to normalize the relationship between event subscribers and subscriber + predicates, we now allow both subscribers and subscriber predicates to accept + only a single ``event`` argument even if they've been subscribed for + notifications that involve multiple interfaces. Subscribers and subscriber + predicates that accept only one argument will receive the first object passed + to ``notify``; this is typically (but not always) the event object. The + other objects involved in the subscription lookup will be discarded. You can + now write an event subscriber that accepts only ``event`` even if it + subscribes to multiple interfaces:: + + @subscriber([SomeEvent, SomeContextType]) + def asubscriber(event): + # this will work! + + This prevents you from needing to match the subscriber callable parameters to + the subscription type unnecessarily, especially when you don't make use of + any argument in your subscribers except for the event object itself. + + Note, however, that if the event object is not the first + object in the call to ``notify``, you'll run into trouble. For example, if + notify is called with the context argument first:: + + registry.notify(context, event) + + You won't be able to take advantage of the event-only feature. It will + "work", but the object received by your event handler won't be the event + object, it will be the context object, which won't be very useful:: + + @subscriber([SomeContextType, SomeEvent]) + def asubscriber(event): + # bzzt! you'll be getting the context here as ``event``, and it'll + # be useless + + Existing multiple-argument subscribers continue to work without issue, so you + should continue use those if your system notifies using multiple interfaces + and the first interface is not the event interface. For example:: + + @subscriber([SomeContextType, SomeEvent]) + def asubscriber(context, event): + # this will still work! + + The event-only feature makes it possible to use a subscriber predicate that + accepts only a request argument within both multiple-interface subscriber + registrations and single-interface subscriber registrations. You needn't + make slightly different variations of predicates depending on the + subscription type arguments. Instead, just write all your subscriber + predicates so they only accept ``event`` in their ``__call__`` and they'll be + useful across all registrations for subscriptions that use an event as their + first argument, even ones which accept more than just ``event``. + + However, the same caveat applies to predicates as to subscriber callables: if + you're subscribing to a multi-interface event, and the first interface is not + the event interface, the predicate won't work properly. In such a case, + you'll need to match the predicate ``__call__`` argument ordering and + composition to the ordering of the interfaces. For example, if the + registration for the subscription uses ``[SomeContext, SomeEvent]``, you'll + need to reflect that in the ordering of the parameters of the predicate's + ``__call__`` method:: + + def __call__(self, context, event): + return event.request.path.startswith(self.val) + + tl;dr: 1) When using multi-interface subscriptions, always use the event type + as the first subscription registration argument and 2) When 1 is true, use + only ``event`` in your subscriber and subscriber predicate parameter lists, + no matter how many interfaces the subscriber is notified with. This + combination will result in the maximum amount of reusability of subscriber + predicates and the least amount of thought on your part. Drink responsibly. + +Bug Fixes +--------- + +- A failure when trying to locate the attribute ``__text__`` on route and view + predicates existed when the ``debug_routematch`` setting was true or when the + ``pviews`` command was used. See https://github.com/Pylons/pyramid/pull/727 + +Documentation +------------- + +- Sync up tutorial source files with the files that are rendered by the + scaffold that each uses. + +1.4a4 (2012-11-14) +================== + +Features +-------- + +- ``pyramid.authentication.AuthTktAuthenticationPolicy`` has been updated to + support newer hashing algorithms such as ``sha512``. Existing applications + should consider updating if possible for improved security over the default + md5 hashing. + +- Added an ``effective_principals`` route and view predicate. + +- Do not allow the userid returned from the ``authenticated_userid`` or the + userid that is one of the list of principals returned by + ``effective_principals`` to be either of the strings ``system.Everyone`` or + ``system.Authenticated`` when any of the built-in authorization policies that + live in ``pyramid.authentication`` are in use. These two strings are + reserved for internal usage by Pyramid and they will not be accepted as valid + userids. + +- Slightly better debug logging from + ``pyramid.authentication.RepozeWho1AuthenticationPolicy``. + +- ``pyramid.security.view_execution_permitted`` used to return ``True`` if no + view could be found. It now raises a ``TypeError`` exception in that case, as + it doesn't make sense to assert that a nonexistent view is + execution-permitted. See https://github.com/Pylons/pyramid/issues/299. + +- Allow a ``_depth`` argument to ``pyramid.view.view_config``, which will + permit limited composition reuse of the decorator by other software that + wants to provide custom decorators that are much like view_config. + +- Allow an iterable of decorators to be passed to + ``pyramid.config.Configurator.add_view``. This allows views to be wrapped + by more than one decorator without requiring combining the decorators + yourself. + +Bug Fixes +--------- + +- In the past if a renderer returned ``None``, the body of the resulting + response would be set explicitly to the empty string. Instead, now, the body + is left unchanged, which allows the renderer to set a body itself by using + e.g. ``request.response.body = b'foo'``. The body set by the renderer will + be unmolested on the way out. See + https://github.com/Pylons/pyramid/issues/709 + +- In uncommon cases, the ``pyramid_excview_tween_factory`` might have + inadvertently raised a ``KeyError`` looking for ``request_iface`` as an + attribute of the request. It no longer fails in this case. See + https://github.com/Pylons/pyramid/issues/700 + +- Be more tolerant of potential error conditions in ``match_param`` and + ``physical_path`` predicate implementations; instead of raising an exception, + return False. + +- ``pyramid.view.render_view`` was not functioning properly under Python 3.x + due to a byte/unicode discrepancy. See + https://github.com/Pylons/pyramid/issues/721 + +Deprecations +------------ + +- ``pyramid.authentication.AuthTktAuthenticationPolicy`` will emit a warning if + an application is using the policy without explicitly passing a ``hashalg`` + argument. This is because the default is "md5" which is considered + theoretically subject to collision attacks. If you really want "md5" then you + must specify it explicitly to get rid of the warning. + +Documentation +------------- + +- All of the tutorials that use + ``pyramid.authentication.AuthTktAuthenticationPolicy`` now explicitly pass + ``sha512`` as a ``hashalg`` argument. + + +Internals +--------- + +- Move ``TopologicalSorter`` from ``pyramid.config.util`` to ``pyramid.util``, + move ``CyclicDependencyError`` from ``pyramid.config.util`` to + ``pyramid.exceptions``, rename ``Singleton`` to ``Sentinel`` and move from + ``pyramid.config.util`` to ``pyramid.util``; this is in an effort to + move that stuff that may be an API one day out of ``pyramid.config.util``, + because that package should never be imported from non-Pyramid code. + TopologicalSorter is still not an API, but may become one. + +- Get rid of shady monkeypatching of ``pyramid.request.Request`` and + ``pyramid.response.Response`` done within the ``__init__.py`` of Pyramid. + Webob no longer relies on this being done. Instead, the ResponseClass + attribute of the Pyramid Request class is assigned to the Pyramid response + class; that's enough to satisfy WebOb and behave as it did before with the + monkeypatching. + +1.4a3 (2012-10-26) +================== + +Bug Fixes +--------- + +- The match_param predicate's text method was fixed to sort its values. + Part of https://github.com/Pylons/pyramid/pull/705 + +- 1.4a ``pyramid.scripting.prepare`` behaved differently than 1.3 series + function of same name. In particular, if passed a request, it would not + set the ``registry`` attribute of the request like 1.3 did. A symptom + would be that passing a request to ``pyramid.paster.bootstrap`` (which uses + the function) that did not have a ``registry`` attribute could assume that + the registry would be attached to the request by Pyramid. This assumption + could be made in 1.3, but not in 1.4. The assumption can now be made in + 1.4 too (a registry is attached to a request passed to bootstrap or + prepare). + +- When registering a view configuration that named a Chameleon ZPT renderer + with a macro name in it (e.g. ``renderer='some/template#somemacro.pt``) as + well as a view configuration without a macro name in it that pointed to the + same template (e.g. ``renderer='some/template.pt'``), internal caching could + confuse the two, and your code might have rendered one instead of the + other. + +Features +-------- + +- Allow multiple values to be specified to the ``request_param`` view/route + predicate as a sequence. Previously only a single string value was allowed. + See https://github.com/Pylons/pyramid/pull/705 + +- Comments with references to documentation sections placed in scaffold + ``.ini`` files. + +- Added an HTTP Basic authentication policy + at ``pyramid.authentication.BasicAuthAuthenticationPolicy``. + +- The Configurator ``testing_securitypolicy`` method now returns the policy + object it creates. + +- The Configurator ``testing_securitypolicy`` method accepts two new + arguments: ``remember_result`` and ``forget_result``. If supplied, these + values influence the result of the policy's ``remember`` and ``forget`` + methods, respectively. + +- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a + ``forgotten`` value on the policy (the value ``True``) when its ``forget`` + method is called. + +- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a + ``remembered`` value on the policy, which is the value of the ``principal`` + argument it's called with when its ``remember`` method is called. + +- New ``physical_path`` view predicate. If specified, this value should be a + string or a tuple representing the physical traversal path of the context + found via traversal for this predicate to match as true. For example: + ``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('', + 'a', 'b', 'c')``. This is not a path prefix match or a regex, it's a + whole-path match. It's useful when you want to always potentially show a + view when some object is traversed to, but you can't be sure about what kind + of object it will be, so you can't use the ``context`` predicate. The + individual path elements inbetween slash characters or in tuple elements + should be the Unicode representation of the name of the resource and should + not be encoded in any way. + +1.4a2 (2012-09-27) +================== + +Bug Fixes +--------- + +- When trying to determine Mako defnames and Chameleon macro names in asset + specifications, take into account that the filename may have a hyphen in + it. See https://github.com/Pylons/pyramid/pull/692 + +Features +-------- + +- A new ``pyramid.session.check_csrf_token`` convenience function was added. + +- A ``check_csrf`` view predicate was added. For example, you can now do + ``config.add_view(someview, check_csrf=True)``. When the predicate is + checked, if the ``csrf_token`` value in ``request.params`` matches the CSRF + token in the request's session, the view will be permitted to execute. + Otherwise, it will not be permitted to execute. + +- Add ``Base.metadata.bind = engine`` to alchemy template, so that tables + defined imperatively will work. + +Documentation +------------- + +- update wiki2 SQLA tutorial with the changes required after inserting + ``Base.metadata.bind = engine`` into the alchemy scaffold. + +1.4a1 (2012-09-16) +================== + +Bug Fixes +--------- + +- Forward port from 1.3 branch: When no authentication policy was configured, + a call to ``pyramid.security.effective_principals`` would unconditionally + return the empty list. This was incorrect, it should have unconditionally + returned ``[Everyone]``, and now does. + +- Explicit url dispatch regexes can now contain colons. + https://github.com/Pylons/pyramid/issues/629 + +- On at least one 64-bit Ubuntu system under Python 3.2, using the + ``view_config`` decorator caused a ``RuntimeError: dictionary changed size + during iteration`` exception. It no longer does. See + https://github.com/Pylons/pyramid/issues/635 for more information. + +- In Mako Templates lookup, check if the uri is already adjusted and bring + it back to an asset spec. Normally occurs with inherited templates or + included components. + https://github.com/Pylons/pyramid/issues/606 + https://github.com/Pylons/pyramid/issues/607 + +- In Mako Templates lookup, check for absolute uri (using mako directories) + when mixing up inheritance with asset specs. + https://github.com/Pylons/pyramid/issues/662 + +- HTTP Accept headers were not being normalized causing potentially + conflicting view registrations to go unnoticed. Two views that only + differ in the case ('text/html' vs. 'text/HTML') will now raise an error. + https://github.com/Pylons/pyramid/pull/620 + +- Forward-port from 1.3 branch: when registering multiple views with an + ``accept`` predicate in a Pyramid application runing under Python 3, you + might have received a ``TypeError: unorderable types: function() < + function()`` exception. + +Features +-------- + +- Configurator.add_directive now accepts arbitrary callables like partials or + objects implementing ``__call__`` which dont have ``__name__`` and + ``__doc__`` attributes. See https://github.com/Pylons/pyramid/issues/621 + and https://github.com/Pylons/pyramid/pull/647. + +- Third-party custom view, route, and subscriber predicates can now be added + for use by view authors via + ``pyramid.config.Configurator.add_view_predicate``, + ``pyramid.config.Configurator.add_route_predicate`` and + ``pyramid.config.Configurator.add_subscriber_predicate``. So, for example, + doing this:: + + config.add_view_predicate('abc', my.package.ABCPredicate) + + Might allow a view author to do this in an application that configured that + predicate:: + + @view_config(abc=1) + + Similar features exist for ``add_route``, and ``add_subscriber``. See + "Adding A Third Party View, Route, or Subscriber Predicate" in the Hooks + chapter for more information. + + Note that changes made to support the above feature now means that only + actions registered using the same "order" can conflict with one another. + It used to be the case that actions registered at different orders could + potentially conflict, but to my knowledge nothing ever depended on this + behavior (it was a bit silly). + +- Custom objects can be made easily JSON-serializable in Pyramid by defining + a ``__json__`` method on the object's class. This method should return + values natively serializable by ``json.dumps`` (such as ints, lists, + dictionaries, strings, and so forth). + +- The JSON renderer now allows for the definition of custom type adapters to + convert unknown objects to JSON serializations. + +- As of this release, the ``request_method`` predicate, when used, will also + imply that ``HEAD`` is implied when you use ``GET``. For example, using + ``@view_config(request_method='GET')`` is equivalent to using + ``@view_config(request_method=('GET', 'HEAD'))``. Using + ``@view_config(request_method=('GET', 'POST')`` is equivalent to using + ``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because + HEAD is a variant of GET that omits the body, and WebOb has special support + to return an empty body when a HEAD is used. + +- ``config.add_request_method`` has been introduced to support extending + request objects with arbitrary callables. This method expands on the + previous ``config.set_request_property`` by supporting methods as well as + properties. This method now causes less code to be executed at + request construction time than ``config.set_request_property`` in + version 1.3. + +- Don't add a ``?`` to URLs generated by ``request.resource_url`` if the + ``query`` argument is provided but empty. + +- Don't add a ``?`` to URLs generated by ``request.route_url`` if the + ``_query`` argument is provided but empty. + +- The static view machinery now raises (rather than returns) ``HTTPNotFound`` + and ``HTTPMovedPermanently`` exceptions, so these can be caught by the + Not Found View (and other exception views). + +- The Mako renderer now supports a def name in an asset spec. When the def + name is present in the asset spec, the system will render the template def + within the template and will return the result. An example asset spec is + ``package:path/to/template#defname.mako``. This will render the def named + ``defname`` inside the ``template.mako`` template instead of rendering the + entire template. The old way of returning a tuple in the form + ``('defname', {})`` from the view is supported for backward compatibility, + +- The Chameleon ZPT renderer now accepts a macro name in an asset spec. When + the macro name is present in the asset spec, the system will render the + macro listed as a ``define-macro`` and return the result instead of + rendering the entire template. An example asset spec: + ``package:path/to/template#macroname.pt``. This will render the macro + defined as ``macroname`` within the ``template.pt`` template instead of the + entire templae. + +- When there is a predicate mismatch exception (seen when no view matches for + a given request due to predicates not working), the exception now contains + a textual description of the predicate which didn't match. + +- An ``add_permission`` directive method was added to the Configurator. This + directive registers a free-standing permission introspectable into the + Pyramid introspection system. Frameworks built atop Pyramid can thus use + the ``permissions`` introspectable category data to build a + comprehensive list of permissions supported by a running system. Before + this method was added, permissions were already registered in this + introspectable category as a side effect of naming them in an ``add_view`` + call, this method just makes it possible to arrange for a permission to be + put into the ``permissions`` introspectable category without naming it + along with an associated view. Here's an example of usage of + ``add_permission``:: + + config = Configurator() + config.add_permission('view') + +- The ``UnencryptedCookieSessionFactoryConfig`` now accepts + ``signed_serialize`` and ``signed_deserialize`` hooks which may be used + to influence how the sessions are marshalled (by default this is done + with HMAC+pickle). + +- ``pyramid.testing.DummyRequest`` now supports methods supplied by the + ``pyramid.util.InstancePropertyMixin`` class such as ``set_property``. + +- Request properties and methods added via ``config.set_request_property`` or + ``config.add_request_method`` are now available to tweens. + +- Request properties and methods added via ``config.set_request_property`` or + ``config.add_request_method`` are now available in the request object + returned from ``pyramid.paster.bootstrap``. + +- ``request.context`` of environment request during ``bootstrap`` is now the + root object if a context isn't already set on a provided request. + +- The ``pyramid.decorator.reify`` function is now an API, and was added to + the API documentation. + +- Added the ``pyramid.testing.testConfig`` context manager, which can be used + to generate a configurator in a test, e.g. ``with testing.testConfig(...):``. + +- Users can now invoke a subrequest from within view code using a new + ``request.invoke_subrequest`` API. + +Deprecations +------------ + +- The ``pyramid.config.Configurator.set_request_property`` has been + documentation-deprecated. The method remains usable but the more + featureful ``pyramid.config.Configurator.add_request_method`` should be + used in its place (it has all of the same capabilities but can also extend + the request object with methods). + +Backwards Incompatibilities +--------------------------- + +- The Pyramid router no longer adds the values ``bfg.routes.route`` or + ``bfg.routes.matchdict`` to the request's WSGI environment dictionary. + These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven + minor releases ago). If your code depended on these values, use + request.matched_route and request.matchdict instead. + +- It is no longer possible to pass an environ dictionary directly to + ``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka + ``ModelGraphTraverser.__call__``). Instead, you must pass a request + object. Passing an environment instead of a request has generated a + deprecation warning since Pyramid 1.1. + +- Pyramid will no longer work properly if you use the + ``webob.request.LegacyRequest`` as a request factory. Instances of the + LegacyRequest class have a ``request.path_info`` which return a string. + This Pyramid release assumes that ``request.path_info`` will + unconditionally be Unicode. + +- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text`` + named ``get_renderer``, ``get_template``, ``render_template``, and + ``render_template_to_response`` have been removed. These have issued a + deprecation warning upon import since Pyramid 1.0. Use + ``pyramid.renderers.get_renderer()``, + ``pyramid.renderers.get_renderer().implementation()``, + ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response`` + respectively instead of these functions. + +- The ``pyramid.configuration`` module was removed. It had been deprecated + since Pyramid 1.0 and printed a deprecation warning upon its use. Use + ``pyramid.config`` instead. + +- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been + deprecated since Pyramid 1.1 and issued a warning on import. If your code + depended on this, adjust your code to import + ``pyramid.scaffolds.PyramidTemplate`` instead. + +- The ``pyramid.settings.get_settings()`` API was removed. It had been + printing a deprecation warning since Pyramid 1.0. If your code depended on + this API, use ``pyramid.threadlocal.get_current_registry().settings`` + instead or use the ``settings`` attribute of the registry available from + the request (``request.registry.settings``). + +- These APIs from the ``pyramid.testing`` module were removed. They have + been printing deprecation warnings since Pyramid 1.0: + + * ``registerDummySecurityPolicy``, use + ``pyramid.config.Configurator.testing_securitypolicy`` instead. + + * ``registerResources`` (aka ``registerModels``, use + ``pyramid.config.Configurator.testing_resources`` instead. + + * ``registerEventListener``, use + ``pyramid.config.Configurator.testing_add_subscriber`` instead. + + * ``registerTemplateRenderer`` (aka `registerDummyRenderer``), use + ``pyramid.config.Configurator.testing_add_template`` instead. + + * ``registerView``, use ``pyramid.config.Configurator.add_view`` instead. + + * ``registerUtility``, use + ``pyramid.config.Configurator.registry.registerUtility`` instead. + + * ``registerAdapter``, use + ``pyramid.config.Configurator.registry.registerAdapter`` instead. + + * ``registerSubscriber``, use + ``pyramid.config.Configurator.add_subscriber`` instead. + + * ``registerRoute``, use + ``pyramid.config.Configurator.add_route`` instead. + + * ``registerSettings``, use + ``pyramid.config.Configurator.add_settings`` instead. + +- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object + was invoked before any finished callbacks were executed. As of this + release, the ``__call__`` method of a Response object is invoked *after* + finished callbacks are executed. This is in support of the + ``request.invoke_subrequest`` feature. + +- The 200-series exception responses named ``HTTPCreated``, ``HTTPAccepted``, + ``HTTPNonAuthoritativeInformation``, ``HTTPNoContent``, ``HTTPResetContent``, + and ``HTTPPartialContent`` in ``pyramid.httpexceptions`` no longer inherit + from ``HTTPOk``. Instead they inherit from a new base class named + ``HTTPSuccessful``. This will have no effect on you unless you've registered + an exception view for ``HTTPOk`` and expect that exception view to + catch all the aforementioned exceptions. + +Documentation +------------- + +- Added an "Upgrading Pyramid" chapter to the narrative documentation. It + describes how to cope with deprecations and removals of Pyramid APIs and + how to show Pyramid-generated deprecation warnings while running tests and + while running a server. + +- Added a "Invoking a Subrequest" chapter to the documentation. It describes + how to use the new ``request.invoke_subrequest`` API. + +Dependencies +------------ + +- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on + 1.2dev+). This is to ensure that we obtain a version of WebOb that returns + ``request.path_info`` as text. + 1.3 (2012-03-21) ================ @@ -2150,7 +2845,7 @@ Features - Add ``wild_domain`` argument to AuthTktAuthenticationPolicy, which defaults to ``True``. If it is set to ``False``, the feature of the policy which - sets a cookie with a wilcard domain will be turned off. + sets a cookie with a wildcard domain will be turned off. - Add a ``MANIFEST.in`` file to each paster template. See https://github.com/Pylons/pyramid/issues#issue/95 diff --git a/README.rst b/README.rst index 4d427a13d..a3458028b 100644 --- a/README.rst +++ b/README.rst @@ -1,8 +1,8 @@ Pyramid ======= -Pyramid is a small, fast, down-to-earth, open source Python web application -development framework. It makes real-world web application development and +Pyramid is a small, fast, down-to-earth, open source Python web framework. +It makes real-world web application development and deployment more fun, more predictable, and more productive. Pyramid is produced by the `Pylons Project <http://pylonsproject.org/>`_. diff --git a/RELEASING.txt b/RELEASING.txt index 379965c53..553d2dcf2 100644 --- a/RELEASING.txt +++ b/RELEASING.txt @@ -35,8 +35,6 @@ Releasing Pyramid - Change setup.py version to the new version number. -- Change docs/conf.py version to the new version number. - - Change CHANGES.txt heading to reflect the new version number. - Make sure PyPI long description renders (requires ``collective.dist`` @@ -12,9 +12,6 @@ Nice-to-Have - Have action methods return their discriminators. -- Fix renderers chapter to better document system values passed to template - renderers. - - Modify view mapper narrative docs to not use pyramid_handlers. - Modify the urldispatch chapter examples to assume a scan rather than @@ -41,8 +38,6 @@ Nice-to-Have - Add narrative docs for wsgiapp and wsgiapp2. -- Flesh out "Paste" narrative docs chapter. - - Basic WSGI documentation (pipeline / app / server). - Change docs about creating a venusian decorator to not use ZCA (use @@ -56,9 +51,6 @@ Nice-to-Have app1" and "domain app1.localhost = app1"), ProxyPreserveHost and the nginx equivalent, preserving HTTPS URLs. -- Make "localizer" a property of request (instead of requiring - "get_localizer(request)"? - - Alias the stupid long default session factory name. - Debug option to print view matching decision (e.g. debug_viewlookup or so). @@ -124,27 +116,17 @@ Nice-to-Have Future ------ -- 1.5: remove ``pyramid.view.static`` and ``pyramid.view.is_response``. - -- 1.5: turn ``pyramid.settings.Settings`` into a function that returns the +- 1.6: turn ``pyramid.settings.Settings`` into a function that returns the original dict (after ``__getattr__`` deprecation period, it was deprecated in 1.2). -- 1.5: Remove ``pyramid.requests.DeprecatedRequestMethodsMixin`` and code in - renderers module that looks for _response_content_type, et. al. - -- 1.5: Maybe? deprecate set_request_property in favor of pointing people at - add_request_method, schedule removal for 1.8? - -- 1.5: Remove pyramid.config.rendering set_renderer_globals_factory maybe. - -- 1.5: remove pyramid.config.route _add_view_from_route function. - - 1.6: Remove IContextURL and TraversalContextURL. - 1.7: Change ``pyramid.authentication.AuthTktAuthenticationPolicy`` default ``hashalg`` to ``sha512``. +- 1.8 Remove set_request_property. + Probably Bad Ideas ------------------ diff --git a/docs/Makefile b/docs/Makefile index c98fdc65e..12dc88bf8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -63,8 +63,13 @@ latex: cp _static/latex-note.png _build/latex @echo @echo "Build finished; the LaTeX files are in _build/latex." - @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ - "run these through (pdf)latex." + @echo "Run \`make latexpdf' to build a PDF file from them." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C _build/latex all-pdf + @echo "pdflatex finished; the PDF file is in _build/latex." changes: mkdir -p _build/changes _build/doctrees diff --git a/docs/_static/directory_structure_generic.png b/docs/_static/directory_structure_generic.png Binary files differnew file mode 100644 index 000000000..c6d1a5b03 --- /dev/null +++ b/docs/_static/directory_structure_generic.png diff --git a/docs/_static/directory_structure_initial.png b/docs/_static/directory_structure_initial.png Binary files differnew file mode 100644 index 000000000..000f1bb27 --- /dev/null +++ b/docs/_static/directory_structure_initial.png diff --git a/docs/_static/directory_structure_pyramid.png b/docs/_static/directory_structure_pyramid.png Binary files differnew file mode 100644 index 000000000..74edd6533 --- /dev/null +++ b/docs/_static/directory_structure_pyramid.png diff --git a/docs/_themes b/docs/_themes -Subproject f59f7bfce5259f50fbb67b9040c03ecb080130b +Subproject 26732645619b372764097e5e8086f89871d90c0 diff --git a/docs/api/config.rst b/docs/api/config.rst index 39d504348..48dd2f0b9 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -52,10 +52,6 @@ .. automethod:: override_asset(to_override, override_with) - :methodcategory:`Setting Renderer Globals` - - .. automethod:: set_renderer_globals_factory(factory) - :methodcategory:`Getting and Adding Settings` .. automethod:: add_settings @@ -135,3 +131,4 @@ will only exist for the lifetime of the actual applications for which they are being used. +.. autoclass:: not_ diff --git a/docs/api/registry.rst b/docs/api/registry.rst index db348495c..7736cf075 100644 --- a/docs/api/registry.rst +++ b/docs/api/registry.rst @@ -29,6 +29,15 @@ This attribute is often accessed as ``request.registry.introspector`` in a typical Pyramid application. + .. method:: notify(*events) + + Fire one or more events. All event subscribers to the event(s) + will be notified. The subscribers will be called synchronously. + This method is often accessed as ``request.registry.notify`` + in Pyramid applications to fire custom events. See + :ref:`custom_events` for more information. + + .. class:: Introspectable .. versionadded:: 1.3 diff --git a/docs/api/request.rst b/docs/api/request.rst index 7b843f86e..72abddb68 100644 --- a/docs/api/request.rst +++ b/docs/api/request.rst @@ -156,7 +156,7 @@ .. attribute:: matched_route If a :term:`route` has matched during this request, this attribute will - be an obect representing the route matched by the URL pattern + be an object representing the route matched by the URL pattern associated with the route. If a route has not matched during this request, the value of this attribute will be ``None``. See :ref:`matched_route`. @@ -190,22 +190,22 @@ :meth:`~pyramid.config.Configurator.set_request_property`) on the request it's passed. - - causes a :class:`~pyramid.event.NewRequest` event to be sent at the + - causes a :class:`~pyramid.events.NewRequest` event to be sent at the beginning of request processing. - - causes a :class:`~pyramid.event.ContextFound` event to be sent + - causes a :class:`~pyramid.events.ContextFound` event to be sent when a context resource is found. - + - Ensures that the user implied by the request passed has the necessary authorization to invoke view callable before calling it. - - causes a :class:`~pyramid.event.NewResponse` event to be sent when - the Pyramid application returns a response. - - Calls any :term:`response callback` functions defined within the request's lifetime if a response is obtained from the Pyramid application. + - causes a :class:`~pyramid.events.NewResponse` event to be sent if a + response is obtained. + - Calls any :term:`finished callback` functions defined within the request's lifetime. @@ -235,24 +235,6 @@ .. automethod:: resource_path - .. attribute:: response_* - - In Pyramid 1.0, you could set attributes on a - :class:`pyramid.request.Request` which influenced the behavor of - *rendered* responses (views which use a :term:`renderer` and which - don't directly return a response). These attributes began with - ``response_``, such as ``response_headerlist``. If you needed to - influence response values from a view that uses a renderer (such as the - status code, a header, the content type, etc) you would set these - attributes. See :ref:`response_prefixed_attrs` for further discussion. - As of Pyramid 1.1, assignment to ``response_*`` attrs is deprecated. - Assigning to one is still supported but will cause a deprecation - warning to be emitted, and eventually the feature will be removed. For - new code, instead of assigning ``response_*`` attributes to the - request, use API of the :attr:`pyramid.request.Request.response` - object (exposed to view code as ``request.response``) to influence - rendered response behavior. - .. attribute:: json_body This property will return the JSON-decoded variant of the request @@ -311,6 +293,20 @@ .. versionadded:: 1.3 + .. attribute:: localizer + + A :term:`localizer` which will use the current locale name to + translate values. + + .. versionadded:: 1.5 + + .. attribute:: locale_name + + The locale name of the current request as computed by the + :term:`locale negotiator`. + + .. versionadded:: 1.5 + .. note:: For information about the API of a :term:`multidict` structure (such as diff --git a/docs/api/view.rst b/docs/api/view.rst index 21d2bb90d..d8e429552 100644 --- a/docs/api/view.rst +++ b/docs/api/view.rst @@ -11,8 +11,6 @@ .. autofunction:: render_view - .. autofunction:: is_response - .. autoclass:: view_config :members: @@ -25,8 +23,4 @@ .. autoclass:: forbidden_view_config :members: - .. autoclass:: static - :members: - :inherited-members: - diff --git a/docs/authorintro.rst b/docs/authorintro.rst index f1a9d1484..ebc6bcff8 100644 --- a/docs/authorintro.rst +++ b/docs/authorintro.rst @@ -2,7 +2,7 @@ Author Introduction ===================== -Welcome to "The :app:`Pyramid` Web Application Framework". In this +Welcome to "The :app:`Pyramid` Web Framework". In this introduction, I'll describe the audience for this book, I'll describe the book content, I'll provide some context regarding the genesis of :app:`Pyramid`, and I'll thank some important people. @@ -73,7 +73,7 @@ This book is divided into three major parts: concepts in terms of the sample. You should read the tutorials if you want a guided tour of :app:`Pyramid`. -:ref:`api_reference` +:ref:`api_documentation` Comprehensive reference material for every public API exposed by :app:`Pyramid`. The API documentation is organized diff --git a/docs/conf.py b/docs/conf.py index 33bedc9dd..f18cf3ec3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,6 +19,8 @@ import warnings warnings.simplefilter('ignore', DeprecationWarning) +import pkg_resources + # skip raw nodes from sphinx.writers.text import TextTranslator from sphinx.writers.latex import LaTeXTranslator @@ -55,9 +57,21 @@ extensions = [ # Looks for objects in external projects intersphinx_mapping = { + 'tutorials': ('http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/', None), + 'jinja2': ('http://docs.pylonsproject.org/projects/pyramid_jinja2/en/latest/', None), + 'tm': ( + 'http://docs.pylonsproject.org/projects/pyramid_tm/en/latest/', + None, + ), 'zcomponent': ('http://docs.zope.org/zope.component', None), 'webtest': ('http://webtest.pythonpaste.org/en/latest', None), 'webob': ('http://docs.webob.org/en/latest', None), + 'colander': ( + 'http://docs.pylonsproject.org/projects/colander/en/latest', + None), + 'deform': ( + 'http://docs.pylonsproject.org/projects/deform/en/latest', + None), 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), 'who': ('http://docs.repoze.org/who/latest', None), 'python': ('http://docs.python.org', None), @@ -70,8 +84,12 @@ intersphinx_mapping = { 'toolbar': ('http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest', None), + 'zcml': + ('http://docs.pylonsproject.org/projects/pyramid_zcml/en/latest', + None), } + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -82,7 +100,7 @@ source_suffix = '.rst' master_doc = 'index' # General substitutions. -project = 'The Pyramid Web Application Development Framework' +project = 'The Pyramid Web Framework' thisyear = datetime.datetime.now().year copyright = '2008-%s, Agendaless Consulting' % thisyear @@ -90,7 +108,7 @@ copyright = '2008-%s, Agendaless Consulting' % thisyear # other places throughout the built documents. # # The short X.Y version. -version = '1.4' +version = pkg_resources.get_distribution('pyramid').version # The full version, including alpha/beta/rc tags. release = version @@ -147,17 +165,21 @@ html_theme_path = ['_themes'] html_theme = 'pyramid' html_theme_options = dict( github_url='https://github.com/Pylons/pyramid', -# in_progress='true', + in_progress='true', ) # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". -html_title = 'The Pyramid Web Application Development Framework v%s' % release +html_title = 'The Pyramid Web Framework v%s' % release # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +html_use_smartypants = False # people use cutnpaste in some places + # Output file base name for HTML help builder. htmlhelp_basename = 'pyramid' @@ -176,7 +198,7 @@ latex_additional_files = ['_static/latex-note.png', '_static/latex-warning.png'] # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ ('latexindex', 'pyramid.tex', - 'The Pyramid Web Application Development Framework', + 'The Pyramid Web Framework', 'Chris McDonough', 'manual'), ] @@ -301,7 +323,7 @@ latex_elements = { 'wrapperclass': 'book', 'date': '', 'releasename': 'Version', - 'title': r'The Pyramid Web Application \newline Development Framework', + 'title': r'The Pyramid Web Framework', # 'pointsize':'12pt', # uncomment for 12pt version } @@ -406,7 +428,7 @@ def resig(app, what, name, obj, options, signature, return_annotation): # -- Options for Epub output --------------------------------------------------- # Bibliographic Dublin Core info. -epub_title = 'The Pyramid Web Application Development Framework, Version %s' \ +epub_title = 'The Pyramid Web Framework, Version %s' \ % release epub_author = 'Chris McDonough' epub_publisher = 'Agendaless Consulting' @@ -424,7 +446,7 @@ epub_scheme = 'ISBN' epub_identifier = '0615445675' # A unique identification for the text. -epub_uid = 'The Pyramid Web Application Development Framework, Version %s' \ +epub_uid = 'The Pyramid Web Framework, Version %s' \ % release # A list of files that should not be packed into the epub file. diff --git a/docs/copyright.rst b/docs/copyright.rst index 8f3a5f5e7..980335827 100644 --- a/docs/copyright.rst +++ b/docs/copyright.rst @@ -1,7 +1,7 @@ Copyright, Trademarks, and Attributions ======================================= -*The Pyramid Web Application Development Framework, Version 1.1* +*The Pyramid Web Framework, Version 1.1* by Chris McDonough diff --git a/docs/designdefense.rst b/docs/designdefense.rst index 7bc37ac06..bbce3e29c 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -38,13 +38,13 @@ forking is also a Zope derivative. Implementations of these features were *required* to allow the :app:`Pyramid` authors to build the bread-and-butter CMS-type systems for customers in the -way they were accustomed to building them. No other system, save for Zope itself, -had such features. And Zope itself was beginning to show signs of its age. +way in which they were accustomed. No other system, save for Zope itself, +had such features, and Zope itself was beginning to show signs of its age. We were becoming hampered by consequences of its early design mistakes. Zope's lack of documentation was also difficult to work around: it was hard to hire smart people to work on Zope applications, because there was no comprehensive documentation set to point them at which explained "it all" in -one consumble place, and it was too large and self-inconsistent to document +one consumable place, and it was too large and self-inconsistent to document properly. Before :mod:`repoze.bfg` went under development, its authors obviously looked around for other frameworks that fit the bill. But no non-Zope framework did. So we embarked on building :mod:`repoze.bfg`. @@ -514,7 +514,7 @@ 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, :mod:`pyramid` view callables always accept only ``request`` and +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 @@ -594,55 +594,45 @@ requires extensibility because it must be deployed in multiple locations. Pyramid Is Too Big ------------------ -"The :app:`Pyramid` compressed tarball is almost 2MB. It must be +"The :app:`Pyramid` compressed tarball is larger than 2MB. It must be enormous!" -No. We just ship it with test code and helper templates. Here's a +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/ - 3.0MB + 4.9MB pyramid/tests/ - 1.1MB + 2.0MB -pyramid/paster_templates/ +pyramid/scaffolds/ - 804KB + 460KB -pyramid/ (except for ``pyramd/tests and pyramid/paster_templates``) +pyramid/ (except for ``pyramd/tests`` and ``pyramid/scaffolds``) - 539K + 844KB -The actual :app:`Pyramid` runtime code is about 10% of the total size of the -tarball omitting docs, helper templates used for package generation, and test -code. Of the approximately 19K lines of Python code in the package, the code +Of the approximately 34K lines of Python code in the package, the code that actually has a chance of executing during normal operation, excluding -tests and paster template Python files, accounts for approximately 5K lines -of Python code. This is comparable to Pylons 1.X, which ships with a little -over 2K lines of Python code, excluding tests. +tests and scaffolding Python files, accounts for approximately 10K lines. + Pyramid Has Too Many Dependencies --------------------------------- -This is true. At the time of this writing (Pyramid 1.3), the total number of -Python package distributions that :app:`Pyramid` depends upon transitively is -if you use Python 3.2 or Python 2.7 is 10. If you use Python 2.6, Pyramid -will pull in 12 package distributions. This is a lot more than zero package -distribution dependencies: a metric which various Python microframeworks and -Django boast. - -However, Pyramid 1.2 relied on 15 packages under Python 2.7 and 17 packages -under Python 2.6, so we've made progress here. A port to Python 3 completed -in Pyramid 1.3 helped us shed a good number of dependencies by forcing us to -make better packaging decisions. +Over time, we've made lots of progress on reducing the number of packaging +dependencies Pyramid has had. Pyramid 1.2 had 15 of them. Pyramid 1.3 and 1.4 +had 12 of them. The current release as of this writing, Pyramid 1.5, has +only 7. This number is unlikely to become any smaller. -In the future, we may also move templating system dependencies out of the -core and place them in add-on packages, to be included by developers instead -of by the framework. This would reduce the number of core dependencies by -about five, leaving us with only five remaining core dependencies. +A port to Python 3 completed in Pyramid 1.3 helped us shed a good number of +dependencies by forcing us to make better packaging decisions. Removing +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 -------------------------------- @@ -774,7 +764,7 @@ 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 -useful to be able to extend such a system for each deployment via preordained +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 @@ -802,8 +792,8 @@ such a feature. main template and the CSS in a separate Python package which defines overrides. -- If a deployment needs an application page to do something differently needs - it to expose more or different information, the deployer may override the +- 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 @@ -820,7 +810,7 @@ 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 its worth, be contained in one, canonical, well-defined place. +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` @@ -832,7 +822,7 @@ 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` application are fundamentally extensible even if you +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 @@ -852,7 +842,7 @@ 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 instead use version control branching and merging to +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. @@ -1295,6 +1285,9 @@ predictability. a registry in another module. This has the effect that double-registrations will never be performed. + +.. _routes_need_ordering: + Routes Need Relative Ordering +++++++++++++++++++++++++++++ @@ -1458,7 +1451,7 @@ code below: def afunc(): for i in range(10): - print i + 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 @@ -1656,7 +1649,7 @@ If you can understand this hello world program, you can use Pyramid: server = make_server('0.0.0.0', 8080, app) server.serve_forever() -Pyramid has ~ 650 pages of documentation (printed), covering topics from the +Pyramid has ~ 700 pages of documentation (printed), covering topics from the very basic to the most advanced. *Nothing* is left undocumented, quite literally. It also has an *awesome*, very helpful community. Visit the #pyramid IRC channel on freenode.net (irc://freenode.net#pyramid) and see. @@ -1678,7 +1671,7 @@ was written to address these issues. If it's Zope3-the-web-framework, Pyramid is *definitely* not that. Making use of lots of Zope 3 technologies is territory already staked out by the :term:`Grok` project. Save for the obvious fact that they're both web -frameworks, :mod:`Pyramid` is very, very different than Grok. Grok exposes +frameworks, :app:`Pyramid` is very, very different than Grok. Grok exposes lots of Zope technologies to end users. On the other hand, if you need to understand a Zope-only concept while using Pyramid, then we've failed on some very basic axis. @@ -1691,7 +1684,7 @@ some sort of monolithic thing, and a lot of its software is usable externally. And while it's not really the job of this document to defend it, Zope has been around for over 10 years and has an incredibly large, active community. If you don't believe this, -http://taichino.appspot.com/pypi_ranking/authors is an eye-opening reality +http://pypi-ranking.info/author is an eye-opening reality check. Love Simplicity diff --git a/docs/foreword.rst b/docs/foreword.rst index aa8d7c77b..cc8271bdf 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -1,3 +1,5 @@ +:orphan: + Foreword ======== diff --git a/docs/glossary.rst b/docs/glossary.rst index 241f951d6..406b81778 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -156,9 +156,9 @@ Glossary resource An object representing a node in the :term:`resource tree` of an - application. If :mod:`traversal` is used, a resource is an element in + application. If :term:`traversal` is used, a resource is an element in the resource tree traversed by the system. When traversal is used, a - resource becomes the :term:`context` of a :term:`view`. If :mod:`url + resource becomes the :term:`context` of a :term:`view`. If :term:`url dispatch` is used, a single resource is generated for each request and is used as the context resource of a view. @@ -505,15 +505,20 @@ Glossary available as its ``__parent__`` attribute. root factory - The "root factory" of a :app:`Pyramid` application is called - on every request sent to the application. The root factory - returns the traversal root of an application. It is - conventionally named ``get_root``. An application may supply a - root factory to :app:`Pyramid` during the construction of a - :term:`Configurator`. If a root factory is not supplied, the - application uses a default root object. Use of the default root - object is useful in application which use :term:`URL dispatch` for - all URL-to-view code mappings. + The "root factory" of a :app:`Pyramid` application is called on every + request sent to the application. The root factory returns the traversal + root of an application. It is conventionally named ``get_root``. An + application may supply a root factory to :app:`Pyramid` during the + construction of a :term:`Configurator`. If a root factory is not + supplied, the application creates a default root object using the + :term:`default root factory`. + + default root factory + If an application does not register a :term:`root factory` at Pyramid + configuration time, a *default* root factory is used to created the + default root object. Use of the default root object is useful in + application which use :term:`URL dispatch` for all URL-to-view code + mappings, and does not (knowingly) use traversal otherwise. SQLAlchemy `SQLAlchemy <http://www.sqlalchemy.org/>`_ is an object @@ -698,7 +703,7 @@ Glossary :app:`Pyramid` runs on GAE. Venusian - `Venusian <http://docs.repoze.org/venusian>`_ is a library which + :ref:`Venusian` is a library which allows framework authors to defer decorator actions. Instead of taking actions when a function (or class) decorator is executed at import time, the action usually taken by the decorator is @@ -798,9 +803,8 @@ Glossary :term:`Internationalization`. renderer globals - Values injected as names into a renderer based on application - policy. See :ref:`adding_renderer_globals` for more - information. + Values injected as names into a renderer by a + :class:`pyramid.event.BeforeRender` event. response callback A user-defined callback executed by the :term:`router` at a @@ -1010,7 +1014,8 @@ Glossary Green Unicorn Aka ``gunicorn``, a fast :term:`WSGI` server that runs on UNIX under - Python 2.6+ or Python 3.1+. See http://gunicorn.org/ for detailed information. + Python 2.6+ or Python 3.1+. See http://gunicorn.org/ for detailed + information. predicate factory A callable which is used by a third party during the registration of a @@ -1018,3 +1023,13 @@ Glossary system. See :ref:`registering_thirdparty_predicates` for more information. + add-on + A Python :term:`distribution` that uses Pyramid's extensibility + to plug into a Pyramid application and provide extra, + configurable services. + + pyramid_redis_sessions + A package by Eric Rasmussen which allows you to store Pyramid session + data in a Redis database. See + https://pypi.python.org/pypi/pyramid_redis_sessions for more information. + diff --git a/docs/index.rst b/docs/index.rst index bc711f8ff..78a00966d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,11 +1,11 @@ .. _index: -================================================= -The Pyramid Web Application Development Framework -================================================= +========================= +The Pyramid Web Framework +========================= -:app:`Pyramid` is a small, fast, down-to-earth Python web application -development framework. It is developed as part of the `Pylons Project +:app:`Pyramid` is a small, fast, down-to-earth Python web framework. It +is developed as part of the `Pylons Project <http://docs.pylonsproject.org/>`_. It is licensed under a `BSD-like license <http://repoze.org/license.html>`_. @@ -20,7 +20,8 @@ After you install :app:`Pyramid` and run this application, when you visit See :ref:`firstapp_chapter` for a full explanation of how this application works. Read the :ref:`html_narrative_documentation` to understand how :app:`Pyramid` is designed to scale from simple applications like this to -very large web applications. +very large web applications. To just dive in headfirst, read the +:doc:`quick_tour`. Front Matter ============ @@ -31,21 +32,45 @@ Front Matter copyright.rst conventions.rst -What's New -========== +.. _html_getting_started: + +Getting Started +=============== + +If you are new to Pyramid, we have a few resources that can help you get +up to speed right away. .. toctree:: - :maxdepth: 1 + :hidden: + + quick_tour + quick_tutorial/index + +* :doc:`quick_tour` goes through the major features in Pyramid, covering + a little about a lot. + +* :doc:`quick_tutorial/index` does the same, but in a tutorial format: + deeper treatment of each topic and with working code. + +* To see a minimal Pyramid web application, check out + :ref:`firstapp_chapter`. + +* For help getting Pyramid set up, try + :ref:`installing_chapter`. + +* Like learning by example? Visit the official + :doc:`wiki tutorial <../tutorials/wiki2/index>` as well as the + community-contributed + :ref:`Pyramid tutorials <tutorials:pyramid-tutorials>`, which include + a :ref:`single file tasks tutorial <tutorials:single-file-tutorial>`. + +* Need help? See :ref:`Support and + Development <support-and-development>`. - whatsnew-1.4 - whatsnew-1.3 - whatsnew-1.2 - whatsnew-1.1 - whatsnew-1.0 .. _html_narrative_documentation: -Narrative documentation +Narrative Documentation ======================= Narrative documentation in chapter form explaining how to use @@ -106,11 +131,12 @@ platforms. tutorials/wiki2/index.rst tutorials/wiki/index.rst - tutorials/bfg/index.rst tutorials/modwsgi/index.rst +.. _html_api_documentation: + API Documentation -================== +================= Comprehensive reference material for every public API exposed by :app:`Pyramid`: @@ -126,6 +152,12 @@ Change History .. toctree:: :maxdepth: 1 + whatsnew-1.5 + whatsnew-1.4 + whatsnew-1.3 + whatsnew-1.2 + whatsnew-1.1 + whatsnew-1.0 changes Design Documents @@ -136,51 +168,7 @@ Design Documents designdefense -Sample Applications -=================== - -.. note:: - - These applications run only on Python 2.x, and so do some of their - dependencies. - -`cluegun <https://github.com/Pylons/cluegun>`_ is a simple pastebin -application based on Rocky Burt's `ClueBin -<http://pypi.python.org/pypi/ClueBin/0.2.3>`_. It demonstrates form -processing, security, and the use of :term:`ZODB` within a :app:`Pyramid` -application. Check this application out via: - -.. code-block:: text - - git clone git://github.com/Pylons/cluegun.git - -`virginia <https://github.com/Pylons/virginia>`_ is a very simple dynamic -file rendering application. It is willing to render structured text -documents, HTML documents, and images from a filesystem directory. -It's also a good example of :term:`traversal`. An -earlier version of this application runs the `repoze.org -<http://repoze.org>`_ website. Check this application out via: - -.. code-block:: text - - git clone git://github.com/Pylons/virginia.git - -`shootout <https://github.com/Pylons/shootout>`_ is an example "idea -competition" application by Carlos de la Guardia and Lukasz Fidosz. It -demonstrates :term:`URL dispatch`, simple authentication, integration -with `SQLAlchemy <http://www.sqlalchemy.org/>`_ and ``pyramid_simpleform``. -Check this application out of version control via: - -.. code-block:: text - - git clone git://github.com/Pylons/shootout.git - -`KARL <http://karlproject.org>`_ is a moderately-sized application (roughly -80K lines of Python code) built on top of :app:`Pyramid`. It is an open -source web system for collaboration, organizational intranets, and knowledge -management. It provides facilities for wikis, calendars, manuals, searching, -tagging, commenting, and file uploads. See the `KARL site -<http://karlproject.org>`_ for download and installation details. +.. _support-and-development: Support and Development ======================= @@ -216,12 +204,8 @@ Index and Glossary * :ref:`search` -.. add glossary, foreword, and latexindex in a hidden toc to avoid warnings - .. toctree:: :hidden: glossary - foreword.rst - latexindex.rst diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 6bb875f73..c4afff212 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -1,8 +1,10 @@ +:orphan: + .. _latexindex: -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -The :app:`Pyramid` Web Application Framework -@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ +========================= +The Pyramid Web Framework +========================= .. frontmatter:: @@ -28,8 +30,8 @@ Narrative Documentation narr/introduction narr/install - narr/configuration narr/firstapp + narr/configuration narr/project narr/startup narr/router @@ -50,6 +52,7 @@ Narrative Documentation narr/vhosting narr/testing narr/resources + narr/hellotraversal narr/muchadoabouttraversal narr/traversal narr/security @@ -60,6 +63,8 @@ Narrative Documentation narr/extending narr/advconfig narr/extconfig + narr/scaffolding + narr/upgrading narr/threadlocals narr/zca @@ -71,42 +76,20 @@ Tutorials .. toctree:: :maxdepth: 1 - tutorials/wiki/index.rst tutorials/wiki2/index.rst - tutorials/bfg/index.rst + tutorials/wiki/index.rst tutorials/modwsgi/index.rst -.. _api_reference: +.. _api_documentation: -API Reference -@@@@@@@@@@@@@ +API Documentation +@@@@@@@@@@@@@@@@@ .. toctree:: :maxdepth: 1 + :glob: - api/authorization - api/authentication - api/config - api/events - api/exceptions - api/httpexceptions - api/i18n - api/interfaces - api/location - api/paster - api/registry - api/renderers - api/request - api/response - api/scripting - api/security - api/settings - api/testing - api/threadlocal - api/traversal - api/url - api/view - api/wsgi + api/* .. backmatter:: diff --git a/docs/narr/MyProject/myproject/__init__.py b/docs/narr/MyProject/myproject/__init__.py index 6c512f52f..ad5ecbc6f 100644 --- a/docs/narr/MyProject/myproject/__init__.py +++ b/docs/narr/MyProject/myproject/__init__.py @@ -5,6 +5,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(settings=settings) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.add_route('home', '/') config.scan() diff --git a/docs/narr/MyProject/myproject/templates/mytemplate.pt b/docs/narr/MyProject/myproject/templates/mytemplate.pt index 0bfac946e..0fccba624 100644 --- a/docs/narr/MyProject/myproject/templates/mytemplate.pt +++ b/docs/narr/MyProject/myproject/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/narr/MyProject/setup.py b/docs/narr/MyProject/setup.py index 6969c73e7..a23f46c91 100644 --- a/docs/narr/MyProject/setup.py +++ b/docs/narr/MyProject/setup.py @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_debugtoolbar', 'waitress', ] diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 1b8e33de3..d3431e39e 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -302,7 +302,6 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.set_view_mapper`, :meth:`~pyramid.config.Configurator.set_authentication_policy`, :meth:`~pyramid.config.Configurator.set_authorization_policy`, -:meth:`~pyramid.config.Configurator.set_renderer_globals_factory`, :meth:`~pyramid.config.Configurator.set_locale_negotiator`, :meth:`~pyramid.config.Configurator.set_default_permission`, :meth:`~pyramid.config.Configurator.add_traverser`, diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 26b3e3a92..b0a8d18b0 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -227,14 +227,14 @@ API to generate them for you. For example: .. code-block:: python :linenos: - from pyramid.chameleon_zpt import render_template_to_response + from pyramid.renderers import render_to_response def my_view(request): css_url = request.static_url('mypackage:assets/1/foo.css') js_url = request.static_url('mypackage:assets/2/foo.js') - return render_template_to_response('templates/my_template.pt', - css_url = css_url, - js_url = js_url) + return render_to_response('templates/my_template.pt', + dict(css_url=css_url, js_url=js_url), + request=request) If the request "application URL" of the running system is ``http://example.com``, the ``css_url`` generated above would be: @@ -336,7 +336,9 @@ your application root as below. from pyramid.static import static_view static_view = static_view('/path/to/static/dir', use_subpath=True) -.. note:: For better cross-system flexibility, use an :term:`asset +.. note:: + + For better cross-system flexibility, use an :term:`asset specification` as the argument to :class:`~pyramid.static.static_view` instead of a physical absolute filesystem path, e.g. ``mypackage:static`` instead of ``/path/to/mypackage/static``. @@ -432,9 +434,9 @@ feature, a :term:`Configurator` API exists named :meth:`pyramid.config.Configurator.override_asset`. This API allows you to *override* the following kinds of assets defined in any Python package: -- Individual :term:`Chameleon` templates. +- Individual template files. -- A directory containing multiple Chameleon templates. +- A directory containing multiple template files. - Individual static files served up by an instance of the ``pyramid.static.static_view`` helper class. @@ -460,8 +462,8 @@ can override a single asset. For example: :linenos: config.override_asset( - to_override='some.package:templates/mytemplate.pt', - override_with='another.package:othertemplates/anothertemplate.pt') + to_override='some.package:templates/mytemplate.pt', + override_with='another.package:othertemplates/anothertemplate.pt') The string value passed to both ``to_override`` and ``override_with`` sent to the ``override_asset`` API is called an :term:`asset specification`. The diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index e1347f3ca..58b9bdd21 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -474,6 +474,30 @@ input of the ``prequest`` process is used as the ``POST`` body:: $ $VENV/bin/prequest -mPOST development.ini / < somefile +Showing All Installed Distributions and their Versions +------------------------------------------------------ + +.. versionadded:: 1.5 + +You can use the ``pdistreport`` command to show the Pyramid version in use, the +Python version in use, and all installed versions of Python distributions in +your Python environment:: + + $ $VENV/bin/pdistreport + Pyramid version: 1.5dev + Platform Linux-3.2.0-51-generic-x86_64-with-debian-wheezy-sid + Packages: + authapp 0.0 + /home/chrism/projects/foo/src/authapp + beautifulsoup4 4.1.3 + /home/chrism/projects/foo/lib/python2.7/site-packages/beautifulsoup4-4.1.3-py2.7.egg + ... more output ... + +``pdistreport`` takes no options. Its output is useful to paste into a +pastebin when you are having problems and need someone with more familiarity +with Python packaging and distribution than you have to look at your +environment. + .. _writing_a_script: Writing a Script @@ -514,7 +538,7 @@ representing Pyramid your application configuration as a single argument: from pyramid.paster import bootstrap env = bootstrap('/path/to/my/development.ini') - print env['request'].route_url('home') + print(env['request'].route_url('home')) :func:`pyramid.paster.bootstrap` returns a dictionary containing framework-related information. This dictionary will always contain a @@ -582,7 +606,7 @@ to load instead of ``main``: from pyramid.paster import bootstrap env = bootstrap('/path/to/my/development.ini#another') - print env['request'].route_url('home') + print(env['request'].route_url('home')) The above example specifies the ``another`` ``app``, ``pipeline``, or ``composite`` section of your PasteDeploy configuration file. The ``app`` @@ -619,7 +643,7 @@ the desired request and passing it into :func:`~pyramid.paster.bootstrap`: request = Request.blank('/', base_url='https://example.com/prefix') env = bootstrap('/path/to/my/development.ini#another', request=request) - print env['request'].application_url + print(env['request'].application_url) # will print 'https://example.com/prefix' Now you can readily use Pyramid's APIs for generating URLs: diff --git a/docs/narr/environment.rst b/docs/narr/environment.rst index e059acc4e..f0c0c18fe 100644 --- a/docs/narr/environment.rst +++ b/docs/narr/environment.rst @@ -302,7 +302,7 @@ Ideally, you won't need to use the ``pyramid.tweens`` setting at all. Tweens are generally ordered and included "implicitly" when an add-on package which registers a tween is "included". Packages are included when you name a ``pyramid.includes`` setting in your configuration or when you call -:meth:`pyramid.config.Configuration.include`. +:meth:`pyramid.config.Configurator.include`. Authors of included add-ons provide "implicit" tween configuration ordering hints to Pyramid when their packages are included. However, the implicit diff --git a/docs/narr/events.rst b/docs/narr/events.rst index 929208083..2accb3dbe 100644 --- a/docs/narr/events.rst +++ b/docs/narr/events.rst @@ -26,7 +26,7 @@ subscriber is a function that accepts a single argument named `event`: :linenos: def mysubscriber(event): - print event + print(event) The above is a subscriber that simply prints the event to the console when it's called. @@ -53,7 +53,7 @@ method (see also :term:`Configurator`): from subscribers import mysubscriber - # "config" below is assumed to be an instance of a + # "config" below is assumed to be an instance of a # pyramid.config.Configurator object config.add_subscriber(mysubscriber, NewRequest) @@ -77,7 +77,7 @@ type via the :func:`pyramid.events.subscriber` function. @subscriber(NewRequest) def mysubscriber(event): - event.request.foo = 1 + event.request.foo = 1 When the :func:`~pyramid.events.subscriber` decorator is used a :term:`scan` must be performed against the package containing the @@ -113,10 +113,10 @@ your application like so: :linenos: def handle_new_request(event): - print 'request', event.request + print('request', event.request) def handle_new_response(event): - print 'response', event.response + print('response', event.response) You may configure these functions to be called at the appropriate times by adding the following code to your application's @@ -150,3 +150,86 @@ application, because the interface defined at :class:`pyramid.interfaces.INewResponse` says it must (:class:`pyramid.events.NewResponse` objects also have a ``request``). +.. _custom_events: + +Creating Your Own Events +------------------------ + +In addition to using the events that the Pyramid framework creates, +you can create your own events for use in your application. This can +be useful to decouple parts of your application. + +For example, suppose your application has to do many things when a new +document is created. Rather than putting all this logic in the view +that creates the document, you can create the document in your view +and then fire a custom event. Subscribers to the custom event can take +other actions, such as indexing the document, sending email, or +sending a message to a remote system. + +An event is simply an object. There are no required attributes or +method for your custom events. In general, your events should keep +track of the information that subscribers will need. Here are some +example custom event classes: + +.. code-block:: python + :linenos: + + class DocCreated(object): + def __init__(self, doc, request): + self.doc = doc + self.request = request + + class UserEvent(object): + def __init__(self, user): + self.user = user + + class UserLoggedIn(UserEvent): + pass + +Some Pyramid applications choose to define custom events classes in an +``events`` module. + +You can subscribe to custom events in the same way that you subscribe +to Pyramid events -- either imperatively or with a decorator. You can +also use custom events with :ref:`subscriber predicates +<subscriber_predicates>`. Here's an example of subscribing to a custom +event with a decorator: + +.. code-block:: python + :linenos: + + from pyramid.events import subscriber + from .events import DocCreated + from .index import index_doc + + @subscriber(DocCreated) + def index_doc(event): + # index the document using our application's index_doc function + index_doc(event.doc, event.request) + +The above example assumes that the application defines a +``DocCreated`` event class and an ``index_doc`` function. + +To fire your custom events use the +:meth:`pyramid.registry.Registry.notify` method, which is most often +accessed as ``request.registry.notify``. For example: + +.. code-block:: python + :linenos: + + from .events import DocCreated + + def new_doc_view(request): + doc = MyDoc() + event = DocCreated(doc, request) + request.registry.notify(event) + return {'document': doc} + +This example view will notify all subscribers to the custom +``DocCreated`` event. + +Note that when you fire an event, all subscribers are run +synchronously so it's generally not a good idea +to create event handlers that may take a long time to run. Although +event handlers could be used as a central place to spawn tasks on your +own message queues. diff --git a/docs/narr/extconfig.rst b/docs/narr/extconfig.rst index 659056952..6587aef92 100644 --- a/docs/narr/extconfig.rst +++ b/docs/narr/extconfig.rst @@ -55,7 +55,7 @@ method of the Configurator: :linenos: def mysubscriber(event): - print event.request + print(event.request) config.add_newrequest_subscriber(mysubscriber) @@ -79,7 +79,7 @@ able to install it and subsequently do: :linenos: def mysubscriber(event): - print event.request + print(event.request) from pyramid.config import Configurator config = Configurator() diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 77c66b0d2..0c450fad7 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -14,8 +14,8 @@ in various ways. Changing the Not Found View --------------------------- -When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`not -found view`, which is a :term:`view callable`. The default Not Found View +When :app:`Pyramid` can't map a URL to view code, it invokes a :term:`Not +Found View`, which is a :term:`view callable`. The default Not Found View can be overridden through application configuration. If your application uses :term:`imperative configuration`, you can replace @@ -25,15 +25,17 @@ the Not Found View by using the .. code-block:: python :linenos: - from helloworld.views import notfound - config.add_notfound_view(notfound) + def notfound(request): + return Response('Not Found, dude', status='404 Not Found') + + def main(globals, **settings): + config = Configurator() + config.add_notfound_view(notfound) -Replace ``helloworld.views.notfound`` with a reference to the :term:`view -callable` you want to use to represent the Not Found View. The :term:`not -found view` callable is a view callable like any other. +The :term:`Not Found View` callable is a view callable like any other. If your application instead uses :class:`pyramid.view.view_config` decorators -and a :term:`scan`, you can replace the Not Found view by using the +and a :term:`scan`, you can replace the Not Found View by using the :class:`pyramid.view.notfound_view_config` decorator: .. code-block:: python @@ -46,8 +48,8 @@ and a :term:`scan`, you can replace the Not Found view by using the return Response('Not Found, dude', status='404 Not Found') def main(globals, **settings): - config = Configurator() - config.scan() + config = Configurator() + config.scan() This does exactly what the imperative example above showed. @@ -154,12 +156,12 @@ forbidden view: .. code-block:: python :linenos: - from helloworld.views import forbidden_view - from pyramid.httpexceptions import HTTPForbidden - config.add_forbidden_view(forbidden_view) + def forbidden(request): + return Response('forbidden') -Replace ``helloworld.views.forbidden_view`` with a reference to the Python -:term:`view callable` you want to use to represent the Forbidden view. + def main(globals, **settings): + config = Configurator() + config.add_forbidden_view(forbidden_view) If instead you prefer to use decorators and a :term:`scan`, you can use the :class:`pyramid.view.forbidden_view_config` decorator to mark a view callable @@ -289,7 +291,7 @@ actually execute the function until accessed. return sum(args) def prop(request): - print "getting the property" + print("getting the property") return "the property" config = Configurator() @@ -330,7 +332,7 @@ Here is an example of passing a class to ``Configurator.add_request_method``: # use @property if you don't want to cache the result @reify def prop(self): - print "getting the property" + print("getting the property") return "the property" config = Configurator() @@ -370,10 +372,8 @@ that can be used for this purpose. For example: def add_global(event): event['mykey'] = 'foo' -An object of this type is sent as an event just before a :term:`renderer` is -invoked (but *after* the application-level renderer globals factory added via -:class:`~pyramid.config.Configurator.set_renderer_globals_factory`, if any, -has injected its own keys into the renderer globals dictionary). +An object of this type is sent as an event just before a :term:`renderer` +is invoked. If a subscriber attempts to add a key that already exist in the renderer globals dictionary, a :exc:`KeyError` is raised. This limitation is enforced @@ -415,66 +415,6 @@ your view callable, like so: See the API documentation for the :class:`~pyramid.events.BeforeRender` event interface at :class:`pyramid.interfaces.IBeforeRender`. -Another (deprecated) mechanism which allows event subscribers more control -when adding renderer global values exists in :ref:`adding_renderer_globals`. - -.. index:: - single: adding renderer globals - -.. _adding_renderer_globals: - -Adding Renderer Globals (Deprecated) ------------------------------------- - -.. deprecated:: 1.1 - An alternative mechanism which allows event subscribers to add renderer - global values is documented in :ref:`beforerender_event`. - -Whenever :app:`Pyramid` handles a request to perform a rendering (after a -view with a ``renderer=`` configuration attribute is invoked, or when any of -the methods beginning with ``render`` within the :mod:`pyramid.renderers` -module are called), *renderer globals* can be injected into the *system* -values sent to the renderer. By default, no renderer globals are injected, -and the "bare" system values (such as ``request``, ``context``, ``view``, and -``renderer_name``) are the only values present in the system dictionary -passed to every renderer. - -A callback that :app:`Pyramid` will call every time a renderer is invoked can -be added by passing a ``renderer_globals_factory`` argument to the -constructor of the :term:`configurator`. This callback can either be a -callable object or a :term:`dotted Python name` representing such a callable. - -.. code-block:: python - :linenos: - - def renderer_globals_factory(system): - return {'a': 1} - - config = Configurator( - renderer_globals_factory=renderer_globals_factory) - -Such a callback must accept a single positional argument (notionally named -``system``) which will contain the original system values. It must return a -dictionary of values that will be merged into the system dictionary. See -:ref:`renderer_system_values` for description of the values present in the -system dictionary. - -If you're doing imperative configuration, and you'd rather do it after you've -already constructed a :term:`configurator` it can also be registered via the -:meth:`pyramid.config.Configurator.set_renderer_globals_factory` method: - -.. code-block:: python - :linenos: - - from pyramid.config import Configurator - - def renderer_globals_factory(system): - return {'a': 1} - - config = Configurator() - config.set_renderer_globals_factory(renderer_globals_factory) - - .. index:: single: response callback @@ -512,7 +452,7 @@ callback will be an exception object instead of its default value of ``None``. Response callbacks are called in the order they're added -(first-to-most-recently-added). All response callbacks are called *after* +(first-to-most-recently-added). All response callbacks are called *before* the :class:`~pyramid.events.NewResponse` event is sent. Errors raised by response callbacks are not handled specially. They will be propagated to the caller of the :app:`Pyramid` router application. @@ -673,7 +613,7 @@ traverser. If you've added a traverser, you can change how :meth:`~pyramid.request.Request.resource_url` generates a URL for a specific type of resource by adding a call to -:meth:`pyramid.config.add_resource_url_adapter`. +:meth:`pyramid.config.Configurator.add_resource_url_adapter`. For example: @@ -1382,9 +1322,11 @@ The first argument to :meth:`pyramid.config.Configurator.add_view_predicate`, the name, is a string representing the name that is expected to be passed to ``view_config`` (or its imperative analogue ``add_view``). -The second argument is a view or route predicate factory. A view or route -predicate factory is most often a class with a constructor (``__init__``), a -``text`` method, a ``phash`` method and a ``__call__`` method. For example: +The second argument is a view or route predicate factory, or a :term:`dotted +Python name` which refers to a view or route predicate factory. A view or +route predicate factory is most often a class with a constructor +(``__init__``), a ``text`` method, a ``phash`` method and a ``__call__`` +method. For example: .. code-block:: python :linenos: diff --git a/docs/narr/hybrid.rst b/docs/narr/hybrid.rst index 1773a6b8c..a29ccb2ac 100644 --- a/docs/narr/hybrid.rst +++ b/docs/narr/hybrid.rst @@ -549,3 +549,105 @@ be invoked when the request URI is ``/abc/bazbuz``, assuming there is no object contained by the root object with the key ``bazbuz``. A different request URI, such as ``/abc/foo/bar``, would invoke the default ``myproject.views.abc`` view. + +.. index:: + pair: hybrid urls; generating + +.. _generating_hybrid_urls: + +Generating Hybrid URLs +---------------------- + +.. versionadded:: 1.5 + +The :meth:`pyramid.request.Request.resource_url` method and the +:meth:`pyramid.request.Request.resource_path` method both accept optional +keyword arguments that make it easier to generate route-prefixed URLs that +contain paths to traversal resources:``route_name``, ``route_kw``, and +``route_remainder_name``. + +Any route that has a pattern that contains a ``*remainder`` pattern (any +stararg remainder pattern, such as ``*traverse`` or ``*subpath`` or ``*fred``) +can be used as the target name for ``request.resource_url(..., route_name=)`` +and ``request.resource_path(..., route_name=)``. + +For example, let's imagine you have a route defined in your Pyramid application +like so: + +.. code-block:: python + + config.add_route('mysection', '/mysection*traverse') + +If you'd like to generate the URL ``http://example.com/mysection/a/``, you can +use the following incantation, assuming that the variable ``a`` below points to +a resource that is a child of the root with a ``__name__`` of ``a``: + +.. code-block:: python + + request.resource_url(a, route_name='mysection') + +You can generate only the path portion ``/mysection/a/`` assuming the same: + +.. code-block:: python + + request.resource_path(a, route_name='mysection') + +The path is virtual host aware, so if the ``X-Vhm-Root`` environ variable is +present in the request, and it's set to ``/a``, the above call to +``request.resource_url`` would generate ``http://example.com/mysection/`` +and the above call to ``request.resource_path`` would generate ``/mysection/``. +See :ref:`virtual_root_support` for more information. + +If the route you're trying to use needs simple dynamic part values to be filled +in to succesfully generate the URL, you can pass these as the ``route_kw`` +argument to ``resource_url`` and ``resource_path``. For example, assuming that +the route definition is like so: + +.. code-block:: python + + config.add_route('mysection', '/{id}/mysection*traverse') + +You can pass ``route_kw`` in to fill in ``{id}`` above: + +.. code-block:: python + + request.resource_url(a, route_name='mysection', route_kw={'id':'1'}) + +If you pass ``route_kw`` but do not pass ``route_name``, ``route_kw`` will +be ignored. + +By default this feature works by calling ``route_url`` under the hood, +and passing the value of the resource path to that function as ``traverse``. +If your route has a different ``*stararg`` remainder name (such as +``*subpath``), you can tell ``resource_url`` or ``resource_path`` to use that +instead of ``traverse`` by passing ``route_remainder_name``. For example, +if you have the following route: + +.. code-block:: python + + config.add_route('mysection', '/mysection*subpath') + +You can fill in the ``*subpath`` value using ``resource_url`` by doing: + +.. code-block:: python + + request.resource_path(a, route_name='mysection', + route_remainder_name='subpath') + +If you pass ``route_remainder_name`` but do not pass ``route_name``, +``route_remainder_name`` will be ignored. + +If you try to use ``resource_path`` or ``resource_url`` when the ``route_name`` +argument points at a route that does not have a remainder stararg, an error +will not be raised, but the generated URL will not contain any remainder +information either. + +All other values that are normally passable to ``resource_path`` and +``resource_url`` (such as ``query``, ``anchor``, ``host``, ``port``, and +positional elements) work as you might expect in this configuration. + +Note that this feature is incompatible with the ``__resource_url__`` feature +(see :ref:`overriding_resource_url_generation`) implemented on resource +objects. Any ``__resource_url__`` supplied by your resource will be ignored +when you pass ``route_name``. + diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 74765f8e2..b62c16ff0 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -495,7 +495,6 @@ translations will be available to :app:`Pyramid`. .. index:: single: localizer - single: get_localizer single: translation single: pluralization @@ -503,19 +502,17 @@ Using a Localizer ----------------- A :term:`localizer` is an object that allows you to perform translation or -pluralization "by hand" in an application. You may use the -:func:`pyramid.i18n.get_localizer` function to obtain a :term:`localizer`. -This function will return either the localizer object implied by the active -:term:`locale negotiator` or a default localizer object if no explicit locale -negotiator is registered. +pluralization "by hand" in an application. You may use the +:attr:`pyramid.request.Request.localizer` attribute to obtain a +:term:`localizer`. The localizer object will be configured to produce +translations implied by the active :term:`locale negotiator` or a default +localizer object if no explicit locale negotiator is registered. .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - locale = get_localizer(request) + localizer = request.localizer .. note:: @@ -538,22 +535,20 @@ translation in a view component of an application might look like so: .. code-block:: python :linenos: - from pyramid.i18n import get_localizer from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}, domain='pyramid') def aview(request): - localizer = get_localizer(request) + localizer = request.localizer translated = localizer.translate(ts) # translation string # ... use translated ... -The :func:`~pyramid.i18n.get_localizer` function will return a -:class:`pyramid.i18n.Localizer` object bound to the locale name -represented by the request. The translation returned from its -:meth:`pyramid.i18n.Localizer.translate` method will depend on the -``domain`` attribute of the provided translation string as well as the +The ``request.localizer`` attribute will be a :class:`pyramid.i18n.Localizer` +object bound to the locale name represented by the request. The translation +returned from its :meth:`pyramid.i18n.Localizer.translate` method will depend +on the ``domain`` attribute of the provided translation string as well as the locale of the localizer. .. note:: @@ -579,32 +574,63 @@ signature: def pluralize(singular, plural, n, domain=None, mapping=None): ... -The ``singular`` and ``plural`` arguments should each be a Unicode -value representing a :term:`message identifier`. ``n`` should be an -integer. ``domain`` should be a :term:`translation domain`, and -``mapping`` should be a dictionary that is used for *replacement -value* interpolation of the translated string. If ``n`` is plural -for the current locale, ``pluralize`` will return a Unicode -translation for the message id ``plural``, otherwise it will return a -Unicode translation for the message id ``singular``. - -The arguments provided as ``singular`` and/or ``plural`` may also be -:term:`translation string` objects, but the domain and mapping -information attached to those objects is ignored. +The simplest case is the ``singular`` and ``plural`` arguments being passed as +unicode literals. This returns the appropriate literal according to the locale +pluralization rules for the number ``n``, and interpolates ``mapping``. .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - localizer = get_localizer(request) + localizer = request.localizer translated = localizer.pluralize('Item', 'Items', 1, 'mydomain') # ... use translated ... +However, for support of other languages, the ``singular`` argument should +be a Unicode value representing a :term:`message identifier`. In this +case the ``plural`` value is ignored. +``domain`` should be a :term:`translation domain`, and +``mapping`` should be a dictionary that is used for *replacement +value* interpolation of the translated string. + +The value of ``n`` will be used to find the appropriate plural form for the +current language and ``pluralize`` will return a Unicode translation for the +message id ``singular``. The message file must have defined ``singular`` as a +translation with plural forms. + +The argument provided as ``singular`` may be a :term:`translation string` +object, but the domain and mapping information attached is ignored. + +.. code-block:: python + :linenos: + + def aview(request): + localizer = request.localizer + num = 1 + translated = localizer.pluralize( + _('item_plural', default="${number} items"), + None, num, 'mydomain', mapping={'number':num} + ) + +The corresponding message catalog must have language plural definitions and +plural alternatives set. + +.. code-block:: text + :linenos: + + "Plural-Forms: nplurals=3; plural=n==0 ? 0 : n==1 ? 1 : 2;" + + msgid "item_plural" + msgid_plural "" + msgstr[0] "No items" + msgstr[1] "${number} item" + msgstr[2] "${number} items" + +More information on complex plurals can be found in the `gettext documentation +<https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/Plural-forms.html>`_. + .. index:: single: locale name - single: get_locale_name single: negotiate_locale_name .. _obtaining_the_locale_name: @@ -613,25 +639,23 @@ Obtaining the Locale Name for a Request --------------------------------------- You can obtain the locale name related to a request by using the -:func:`pyramid.i18n.get_locale_name` function. +:func:`pyramid.request.Request.locale_name` attribute of the request. .. code-block:: python :linenos: - from pyramid.i18n import get_locale_name - def aview(request): - locale_name = get_locale_name(request) + locale_name = request.locale_name -This returns the locale name negotiated by the currently active -:term:`locale negotiator` or the :term:`default locale name` if the -locale negotiator returns ``None``. You can change the default locale -name by changing the ``pyramid.default_locale_name`` setting; see -:ref:`default_locale_name_setting`. +The locale name of a request is dynamically computed; it will be the locale +name negotiated by the currently active :term:`locale negotiator` or +the :term:`default locale name` if the locale negotiator returns ``None``. +You can change the default locale name by changing the +``pyramid.default_locale_name`` setting; see :ref:`default_locale_name_setting`. -Once :func:`~pyramid.i18n.get_locale_name` is first run, the locale +Once :func:`~pyramid.request.Request.locale_name` is first run, the locale name is stored on the request object. Subsequent calls to -:func:`~pyramid.i18n.get_locale_name` will return the stored locale +:func:`~pyramid.request.Request.locale_name` will return the stored locale name without invoking the :term:`locale negotiator`. To avoid this caching, you can use the :func:`pyramid.i18n.negotiate_locale_name` function: @@ -650,15 +674,13 @@ You can also obtain the locale name related to a request using the .. code-block:: python :linenos: - from pyramid.i18n import get_localizer - def aview(request): - localizer = get_localizer(request) + localizer = request.localizer locale_name = localizer.locale_name Obtaining the locale name as an attribute of a localizer is equivalent -to obtaining a locale name by calling the -:func:`~pyramid.i18n.get_locale_name` function. +to obtaining a locale name by asking for the +:func:`~pyramid.request.Request.locale_name` attribute. .. index:: single: date and currency formatting (i18n) @@ -686,10 +708,9 @@ obtain the locale name for a request to pass to the :linenos: from babel.core import Locale - from pyramid.i18n import get_locale_name def aview(request): - locale_name = get_locale_name(request) + locale_name = request.locale_name locale = Locale(locale_name) .. index:: @@ -808,7 +829,7 @@ If this setting is supplied within the :app:`Pyramid` application default_locale_name = settings['pyramid.default_locale_name'] .. index:: - single: detecting langauges + single: detecting languages "Detecting" Available Languages ------------------------------- @@ -971,8 +992,8 @@ a particular request. A locale negotiator is a bit of code which accepts a request and which returns a :term:`locale name`. It is consulted when :meth:`pyramid.i18n.Localizer.translate` or :meth:`pyramid.i18n.Localizer.pluralize` is invoked. It is also -consulted when :func:`~pyramid.i18n.get_locale_name` or -:func:`~pyramid.i18n.negotiate_locale_name` is invoked. +consulted when :func:`~pyramid.request.Request.locale_name` is accessed or +when :func:`~pyramid.i18n.negotiate_locale_name` is invoked. .. _default_locale_negotiator: @@ -984,7 +1005,7 @@ requires no additional coding or configuration. The default locale negotiator implementation named :class:`~pyramid.i18n.default_locale_negotiator` uses the following -set of steps to dermine the locale name. +set of steps to determine the locale name. - First, the negotiator looks for the ``_LOCALE_`` attribute of the request object (possibly set directly by view code or by a listener diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 8fc63f3a4..e419a8b20 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -9,49 +9,54 @@ Installing :app:`Pyramid` Before You Install ------------------ -You will need `Python <http://python.org>`_ version 2.6 or better to -run :app:`Pyramid`. +You will need `Python <http://python.org>`_ version 2.6 or better to run +:app:`Pyramid`. .. sidebar:: Python Versions - As of this writing, :app:`Pyramid` has been tested under Python 2.6, - Python 2.7, Python 3.2, and Python 3.3. :app:`Pyramid` does not - run under any version of Python before 2.6. + As of this writing, :app:`Pyramid` has been tested under Python 2.6, Python + 2.7, Python 3.2, and Python 3.3. :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, Mac OS X, and FreeBSD as well as on Windows platforms. It is -also known to run on :term:`PyPy` (1.9+). +:app:`Pyramid` is known to run on all popular UNIX-like systems such as Linux, +Mac OS X, and FreeBSD as well as on Windows platforms. It is also known to run +on :term:`PyPy` (1.9+). -:app:`Pyramid` installation does not require the compilation of any -C code, so you need only a Python interpreter that meets the -requirements mentioned. +:app:`Pyramid` installation does not require the compilation of any C code, so +you need only a Python interpreter that meets the requirements mentioned. + +Some :app:`Pyramid` dependencies may attempt to build C extensions for +performance speedups. If a compiler or Python headers are unavailable the +dependency will fall back to using pure Python instead. For Mac OS X Users ~~~~~~~~~~~~~~~~~~ From `Python.org <http://python.org/download/mac/>`_: - Python comes pre-installed on Mac OS X, but due to Apple's release - cycle, it's often one or even two years old. The overwhelming - recommendation of the "MacPython" community is to upgrade your - Python by downloading and installing a newer version from - `the Python standard release page <http://python.org/download/releases/>`_. + Python comes pre-installed on Mac OS X, but due to Apple's release cycle, + it's often one or even two years old. The overwhelming recommendation of + the "MacPython" community is to upgrade your Python by downloading and + installing a newer version from `the Python standard release page + <http://python.org/download/releases/>`_. -It is recommended to download one of the *installer* versions, unless you prefer to install your Python through a packgage manager (e.g., macports or homebrew) or to build your Python from source. +It is recommended to download one of the *installer* versions, unless you +prefer to install your Python through a packgage manager (e.g., macports or +homebrew) or to build your Python from source. -Unless you have a need for a specific earlier version, it is recommended -to install the latest 2.x or 3.x version of Python. +Unless you have a need for a specific earlier version, it is recommended to +install the latest 2.x or 3.x version of Python. -If you use an installer for your Python, then you can skip to the -section :ref:`installing_unix`. +If you use an installer for your Python, then you can skip to the section +:ref:`installing_unix`. If You Don't Yet Have A Python Interpreter (UNIX) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your system doesn't have a Python interpreter, and you're on UNIX, -you can either install Python using your operating system's package -manager *or* you can install Python from source fairly easily on any -UNIX system that has development tools. +If your system doesn't have a Python interpreter, and you're on UNIX, you can +either install Python using your operating system's package manager *or* you +can install Python from source fairly easily on any UNIX system that has +development tools. .. index:: pair: install; Python (from package, UNIX) @@ -59,9 +64,8 @@ UNIX system that has development tools. Package Manager Method ++++++++++++++++++++++ -You can use your system's "package manager" to install Python. -Each package manager is slightly different, but the "flavor" of -them is usually the same. +You can use your system's "package manager" to install Python. Each package +manager is slightly different, but the "flavor" of them is usually the same. For example, on a Debian or Ubuntu system, use the following command: @@ -82,28 +86,27 @@ invokable via ``python2.7`` from a shell prompt. Source Compile Method +++++++++++++++++++++ -It's useful to use a Python interpreter that *isn't* the "system" -Python interpreter to develop your software. The authors of -:app:`Pyramid` tend not to use the system Python for development -purposes; always a self-compiled one. Compiling Python is usually -easy, and often the "system" Python is compiled with options that -aren't optimal for web development. For an explanation, see +It's useful to use a Python interpreter that *isn't* the "system" Python +interpreter to develop your software. The authors of :app:`Pyramid` tend not +to use the system Python for development purposes; always a self-compiled one. +Compiling Python is usually easy, and often the "system" Python is compiled +with options that aren't optimal for web development. For an explanation, see https://github.com/Pylons/pyramid/issues/747. -To compile software on your UNIX system, typically you need -development tools. Often these can be installed via the package -manager. For example, this works to do so on an Ubuntu Linux system: +To compile software on your UNIX system, typically you need development tools. +Often these can be installed via the package manager. For example, this works +to do so on an Ubuntu Linux system: .. code-block:: text $ sudo apt-get install build-essential -On Mac OS X, installing `XCode -<http://developer.apple.com/tools/xcode/>`_ has much the same effect. +On Mac OS X, installing `XCode <http://developer.apple.com/tools/xcode/>`_ has +much the same effect. -Once you've got development tools installed on your system, you can -install a Python 2.7 interpreter from *source*, on the same system, -using the following commands: +Once you've got development tools installed on your system, you can install a +Python 2.7 interpreter from *source*, on the same system, using the following +commands: .. code-block:: text @@ -117,9 +120,8 @@ using the following commands: $ ./configure --prefix=$HOME/opt/Python-2.7.3 $ make && make install -Once these steps are performed, the Python interpreter will be -invokable via ``$HOME/opt/Python-2.7.3/bin/python`` from a shell -prompt. +Once these steps are performed, the Python interpreter will be invokable via +``$HOME/opt/Python-2.7.3/bin/python`` from a shell prompt. .. index:: pair: install; Python (from package, Windows) @@ -127,24 +129,21 @@ prompt. If You Don't Yet Have A Python Interpreter (Windows) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If your Windows system doesn't have a Python interpreter, you'll need -to install it by downloading a Python 2.7-series interpreter -executable from `python.org's download section -<http://python.org/download/>`_ (the files labeled "Windows -Installer"). Once you've downloaded it, double click on the -executable and accept the defaults during the installation process. -You may also need to download and install the `Python for Windows -extensions <http://sourceforge.net/projects/pywin32/files/>`_. +If your Windows system doesn't have a Python interpreter, you'll need to +install it by downloading a Python 2.7-series interpreter executable from +`python.org's download section <http://python.org/download/>`_ (the files +labeled "Windows Installer"). Once you've downloaded it, double click on the +executable and accept the defaults during the installation process. You may +also need to download and install the Python for Windows extensions. .. warning:: - After you install Python on Windows, you may need to add the - ``C:\Python27`` directory to your environment's ``Path`` in order - to make it possible to invoke Python from a command prompt by - typing ``python``. To do so, right click ``My Computer``, select - ``Properties`` --> ``Advanced Tab`` --> ``Environment Variables`` - and add that directory to the end of the ``Path`` environment - variable. + After you install Python on Windows, you may need to add the ``C:\Python27`` + directory to your environment's ``Path`` in order to make it possible to + invoke Python from a command prompt by typing ``python``. To do so, right + click ``My Computer``, select ``Properties`` --> ``Advanced Tab`` --> + ``Environment Variables`` and add that directory to the end of the ``Path`` + environment variable. .. index:: single: installing on UNIX @@ -154,27 +153,26 @@ extensions <http://sourceforge.net/projects/pywin32/files/>`_. Installing :app:`Pyramid` on a UNIX System --------------------------------------------- -It is best practice to install :app:`Pyramid` into a "virtual" -Python environment in order to obtain isolation from any "system" -packages you've got installed in your Python version. This can be -done by using the :term:`virtualenv` package. Using a virtualenv will -also prevent :app:`Pyramid` from globally installing versions of -packages that are not compatible with your system Python. +It is best practice to install :app:`Pyramid` into a "virtual" Python +environment in order to obtain isolation from any "system" packages you've got +installed in your Python version. This can be done by using the +:term:`virtualenv` package. Using a virtualenv will also prevent +:app:`Pyramid` from globally installing versions of packages that are not +compatible with your system Python. To set up a virtualenv in which to install :app:`Pyramid`, first ensure that -:term:`setuptools` or :term:`distribute` is installed. To do so, invoke -``import setuptools`` within the Python interpreter you'd like to run -:app:`Pyramid` under. +:term:`setuptools` is installed. To do so, invoke ``import setuptools`` within +the Python interpreter you'd like to run :app:`Pyramid` under. -The following command will not display anything if setuptools or distribute is -already installed: +The following command will not display anything if setuptools is already +installed: .. code-block:: text $ python2.7 -c 'import setuptools' -Running the same command will yield the following output if setuptools or -distribute is not yet installed: +Running the same command will yield the following output if setuptools is not +yet installed: .. code-block:: text @@ -183,62 +181,35 @@ distribute is not yet installed: ImportError: No module named setuptools If ``import setuptools`` raises an :exc:`ImportError` as it does above, you -will need to install setuptools or distribute manually. +will need to install setuptools manually. If you are using a "system" Python (one installed by your OS distributor or a -3rd-party packager such as Fink or MacPorts), you can usually install the -setuptools or distribute package by using your system's package manager. If -you cannot do this, or if you're using a self-installed version of Python, -you will need to install setuptools or distribute "by hand". Installing -setuptools or distribute "by hand" is always a reasonable thing to do, even -if your package manager already has a pre-chewed version of setuptools for -installation. - -If you're using Python 2, you'll want to install ``setuptools``. If you're -using Python 3, you'll want to install ``distribute``. Below we tell you how -to do both. +third-party packager such as Fink or MacPorts), you can usually install the +setuptools package by using your system's package manager. If you cannot do +this, or if you're using a self-installed version of Python, you will need to +install setuptools "by hand". Installing setuptools "by hand" is always a +reasonable thing to do, even if your package manager already has a pre-chewed +version of setuptools for installation. -Installing Setuptools On Python 2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Installing Setuptools +~~~~~~~~~~~~~~~~~~~~~ To install setuptools by hand under Python 2, first download `ez_setup.py -<http://peak.telecommunity.com/dist/ez_setup.py>`_ then invoke it using the -Python interpreter into which you want to install setuptools. +<https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ then invoke +it using the Python interpreter into which you want to install setuptools. .. code-block:: text $ python ez_setup.py -Once this command is invoked, setuptools should be installed on your -system. If the command fails due to permission errors, you may need -to be the administrative user on your system to successfully invoke -the script. To remediate this, you may need to do: - -.. code-block:: text - - $ sudo python ez_setup.py - -Installing Distribute On Python 3 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``setuptools`` doesn't work under Python 3. Instead, you can use -``distribute``, which is a fork of setuptools. To -install it, first download `distribute_setup.py -<http://python-distribute.org/distribute_setup.py>`_ then invoke it using the -Python interpreter into which you want to install setuptools. - -.. code-block:: text - - $ python3 distribute_setup.py - -Once this command is invoked, distribute should be installed on your system. +Once this command is invoked, setuptools should be installed on your system. If the command fails due to permission errors, you may need to be the administrative user on your system to successfully invoke the script. To remediate this, you may need to do: .. code-block:: text - $ sudo python3 distribute_setup.py + $ sudo python ez_setup.py .. index:: pair: install; virtualenv @@ -246,9 +217,9 @@ remediate this, you may need to do: Installing the ``virtualenv`` Package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Once you've got setuptools or distribute installed, you should install the -:term:`virtualenv` package. To install the :term:`virtualenv` package into -your setuptools-enabled Python interpreter, use the ``easy_install`` command. +Once you've got setuptools installed, you should install the :term:`virtualenv` +package. To install the :term:`virtualenv` package into your +setuptools-enabled Python interpreter, use the ``easy_install`` command. .. warning:: @@ -261,16 +232,16 @@ your setuptools-enabled Python interpreter, use the ``easy_install`` command. Turing-complete. If you insist on using ``pyvenv``, you'll need to understand how to install - software such as ``distribute`` into the virtual environment manually, - which this guide does not cover. + software such as ``setuptools`` into the virtual environment manually, which + this guide does not cover. .. code-block:: text $ easy_install virtualenv This command should succeed, and tell you that the virtualenv package is now -installed. If it fails due to permission errors, you may need to install it -as your system's administrative user. For example: +installed. If it fails due to permission errors, you may need to install it as +your system's administrative user. For example: .. code-block:: text @@ -289,44 +260,49 @@ you can then create a virtual environment. To do so, invoke the following: .. code-block:: text $ export VENV=~/env - $ virtualenv --no-site-packages $VENV + $ virtualenv $VENV New python executable in /home/foo/env/bin/python Installing setuptools.............done. -You can either follow the use of the environment variable, ``$VENV``, -or replace it with the root directory of the :term:`virtualenv`. -In that case, the `export` command can be skipped. -If you choose the former approach, ensure that it's an absolute path. +You can either follow the use of the environment variable, ``$VENV``, or +replace it with the root directory of the :term:`virtualenv`. In that case, the +`export` command can be skipped. If you choose the former approach, ensure that +it's an absolute path. .. warning:: - Using ``--no-site-packages`` when generating your - virtualenv is *very important*. This flag provides the necessary - isolation for running the set of packages required by - :app:`Pyramid`. If you do not specify ``--no-site-packages``, - it's possible that :app:`Pyramid` will not install properly into - the virtualenv, or, even if it does, may not run properly, - depending on the packages you've already got installed into your - Python's "main" site-packages dir. + Avoid using the ``--system-site-packages`` option when creating the + virtualenv unless you know what you are doing. For versions of virtualenv + prior to 1.7, make sure to use the ``--no-site-packages`` option, because + this option was formerly not the default and may produce undesirable + results. -.. warning:: *do not* use ``sudo`` to run the - ``virtualenv`` script. It's perfectly acceptable (and desirable) - to create a virtualenv as a normal user. +.. warning:: + + *do not* use ``sudo`` to run the ``virtualenv`` script. It's perfectly + acceptable (and desirable) to create a virtualenv as a normal user. Installing :app:`Pyramid` Into the Virtual Python Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -After you've got your virtualenv installed, you may install -:app:`Pyramid` itself using the following commands: - -.. code-block:: text +After you've got your virtualenv installed, you may install :app:`Pyramid` +itself using the following commands: - $ $VENV/bin/easy_install pyramid +.. parsed-literal:: + + $ $VENV/bin/easy_install "pyramid==\ |release|\ " The ``easy_install`` command will take longer than the previous ones to complete, as it downloads and installs a number of dependencies. +.. note:: + + If you see any warnings and/or errors related to failing to compile the C + extensions, in most cases you may safely ignore those errors. If you wish + to use the C extensions, please verify that you have a functioning compiler + and the Python header files installed. + .. index:: single: installing on Windows @@ -335,91 +311,39 @@ complete, as it downloads and installs a number of dependencies. Installing :app:`Pyramid` on a Windows System ------------------------------------------------- -You can use Pyramid on Windows under Python 2 or under Python 3. Directions -for both versions are included below. - -Windows Using Python 2 -~~~~~~~~~~~~~~~~~~~~~~ +You can use Pyramid on Windows under Python 2 or 3. -#. Install the most recent `Python 2.7.x version +#. Download and install the most recent `Python 2.7.x or 3.3.x version <http://www.python.org/download/>`_ for your system. -#. Install the `Python for Windows extensions - <http://sourceforge.net/projects/pywin32/files/>`_. Make sure to - pick the right download for Python 2.7 and install it using the - same Python installation from the previous step. +#. Download and install the `Python for Windows extensions + <http://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read + the README.txt file at the end of the list of builds, and follow its + directions. Make sure you get the proper 32- or 64-bit build and Python + version. -#. Install latest :term:`setuptools` distribution into the Python you - obtained/installed/found in the step above: download `ez_setup.py - <http://peak.telecommunity.com/dist/ez_setup.py>`_ and run it using - the ``python`` interpreter of your Python 2.7 installation using a - command prompt: +#. Install latest :term:`setuptools` distribution into the Python from step 1 + above: download `ez_setup.py + <https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py>`_ and run + it using the ``python`` interpreter of your Python 2.7 or 3.3 installation + using a command prompt: .. code-block:: text + # modify the command according to the python version, e.g.: + # for Python 2.7: c:\> c:\Python27\python ez_setup.py + # for Python 3.3: + c:\> c:\Python33\python ez_setup.py #. Install `virtualenv`: .. code-block:: text - c:\> c:\Python27\Scripts\easy_install virtualenv - -#. Make a :term:`virtualenv` workspace: - - .. code-block:: text - - c:\> set VENV=c:\env - c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV% - - You can either follow the use of the environment variable, ``%VENV%``, - or replace it with the root directory of the :term:`virtualenv`. - In that case, the `set` command can be skipped. - If you choose the former approach, ensure that it's an absolute path. - -#. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell - environment wired to use the virtualenv. - -#. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies - installed: - - .. code-block:: text - - c:\env> %VENV%\Scripts\easy_install pyramid - -Windows Using Python 3 -~~~~~~~~~~~~~~~~~~~~~~ - -#. Install, or find the latest version of `Python 3.x - <http://www.python.org/download/>`_ for your system and which is - supported by Pyramid. - -#. Install the `Python for Windows extensions - <http://sourceforge.net/projects/pywin32/files/>`_. Make sure to - pick the right download for Python 3.x and install it using the - same Python installation from the previous step. - -#. Install latest :term:`distribute` distribution into the Python you - obtained/installed/found in the step above: download `distribute_setup.py - <http://python-distribute.org/distribute_setup.py>`_ and run it using the - ``python`` interpreter of your Python 3.x installation using a command - prompt: - - .. code-block:: text - # modify the command according to the python version, e.g.: - # for Python 3.2.x: - c:\> c:\Python32\python distribute_setup.py - # for Python 3.3.x: - c:\> c:\Python33\python distribute_setup.py - -#. Install :term:`virtualenv`: - - .. code-block:: text - - # for Python 3.2.x: - c:\> c:\Python32\Scripts\easy_install virtualenv - # for Python 3.3.x: + # for Python 2.7: + c:\> c:\Python27\Scripts\easy_install virtualenv + # for Python 3.3: c:\> c:\Python33\Scripts\easy_install virtualenv #. Make a :term:`virtualenv` workspace: @@ -427,15 +351,16 @@ Windows Using Python 3 .. code-block:: text c:\> set VENV=c:\env - # for Python 3.2.x: - c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% - # for Python 3.3.x: - c:\> c:\Python33\Scripts\virtualenv --no-site-packages %VENV% + # modify the command according to the python version, e.g.: + # for Python 2.7: + c:\> c:\Python27\Scripts\virtualenv %VENV% + # for Python 3.3: + c:\> c:\Python33\Scripts\virtualenv %VENV% - You can either follow the use of the environment variable, ``%VENV%``, - or replace it with the root directory of the :term:`virtualenv`. - In that case, the `set` command can be skipped. - If you choose the former approach, ensure that it's an absolute path. + You can either follow the use of the environment variable, ``%VENV%``, or + replace it with the root directory of the :term:`virtualenv`. In that case, + the `set` command can be skipped. If you choose the former approach, ensure + that it's an absolute path. #. (Optional) Consider using ``%VENV%\Scripts\activate.bat`` to make your shell environment wired to use the virtualenv. @@ -443,9 +368,9 @@ Windows Using Python 3 #. Use ``easy_install`` to get :app:`Pyramid` and its direct dependencies installed: - .. code-block:: text - - c:\env> %VENV%\Scripts\easy_install pyramid + .. parsed-literal:: + + c:\\env> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " What Gets Installed ------------------- diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst index 48164d323..ece720a97 100644 --- a/docs/narr/introduction.rst +++ b/docs/narr/introduction.rst @@ -176,8 +176,14 @@ static file server in production without changing any code. Example: :ref:`static_assets_section`. -Debug Toolbar -~~~~~~~~~~~~~ +Fully Interactive Development +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When developing a Pyramid application, several interactive features are +available. Pyramid can automatically utilize changed templates when rendering +pages and automatically restart the application to incorporate changed python +code. Plain old ``printf()`` calls used for debugging can display to a +console. Pyramid's debug toolbar comes activated when you use a Pyramid scaffold to render a project. This toolbar overlays your application in the browser, and @@ -217,6 +223,8 @@ that the Pyramid core doesn't. Add-on packages already exist which let you easily send email, let you use the Jinja2 templating system, let you use XML-RPC or JSON-RPC, let you integrate with jQuery Mobile, etc. +Examples: http://docs.pylonsproject.org/en/latest/docs/pyramid.html#pyramid-add-on-documentation + Class-based and function-based views ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -319,7 +327,14 @@ assertion instead that the view returns "the right stuff" in the dictionary it returns. You can write "real" unit tests instead of functionally testing all of your views. -For example, instead of: +.. index:: + pair: renderer; explicitly calling + pair: view renderer; explictly calling + +.. _example_render_to_response_call: + +For example, instead of returning a ``Response`` object from a +``render_to_response`` call: .. code-block:: python :linenos: @@ -330,7 +345,7 @@ For example, instead of: return render_to_response('myapp:templates/mytemplate.pt', {'a':1}, request=request) -You can do this: +You can return a Python dictionary: .. code-block:: python :linenos: @@ -775,7 +790,7 @@ automate some of the tedium away: for method in ('GET', 'POST', 'HEAD'): view = getattr(module, 'xhr_%s_view' % method, None) if view is not None: - config.add_view(view, route_name='xhr_route', xhr=True, + config.add_view(view, route_name='xhr_route', xhr=True, permission='view', request_method=method) config = Configurator() @@ -857,7 +872,7 @@ It's our goal that no Pyramid question go unanswered. Whether you ask a question on IRC, on the Pylons-discuss maillist, or on StackOverflow, you're likely to get a reasonably prompt response. We don't tolerate "support trolls" or other people who seem to get their rocks off by berating fellow -users in our various offical support channels. We try to keep it well-lit +users in our various official support channels. We try to keep it well-lit and new-user-friendly. Example: Visit irc\://freenode.net#pyramid (the ``#pyramid`` channel on diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst index dec22c5b1..3c0a6744f 100644 --- a/docs/narr/introspector.rst +++ b/docs/narr/introspector.rst @@ -232,18 +232,6 @@ introspectables in categories not described here. The factory object (the resolved ``factory`` argument to ``add_renderer``). -``renderer globals factory`` - - There will be one and only one introspectable in the ``renderer globals - factory`` category. It represents a call to - :meth:`pyramid.config.Configurator.set_renderer_globals_factory`; it will - have the following data. - - ``factory`` - - The factory object (the resolved ``factory`` argument to - ``set_renderer_globals_factory``). - ``routes`` Each introspectable in the ``routes`` category represents a call to diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 9d69a65a5..8b7c24725 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -49,9 +49,7 @@ The included scaffolds are these: URL mapping via :term:`URL dispatch` and no persistence mechanism. ``zodb`` - URL mapping via :term:`traversal` and persistence via :term:`ZODB`. *Note - that, as of this writing, this scaffold will not run under Python 3, only - under Python 2.* + URL mapping via :term:`traversal` and persistence via :term:`ZODB`. ``alchemy`` URL mapping via :term:`URL dispatch` and persistence via @@ -146,9 +144,9 @@ contains no space characters, so it's wise to *avoid* a path that contains i.e. ``My Documents``. As a result, the author, when he uses Windows, just puts his projects in ``C:\projects``. -.. warning:: +.. warning:: - You’ll need to avoid using ``pcreate`` to create a project with the same + You'll need to avoid using ``pcreate`` to create a project with the same name as a Python standard library component. In particular, this means you should avoid using the names ``site`` or ``test``, both of which conflict with Python standard library packages. You should also avoid @@ -195,10 +193,10 @@ Elided output from a run of this command on UNIX is shown below: ... Finished processing dependencies for MyProject==0.0 -This will install a :term:`distribution` representing your project into the -interpreter's library set so it can be found by ``import`` statements and by -other console scripts such as ``pserve``, ``pshell``, ``proutes`` and -``pviews``. +This will install a :term:`distribution` representing your project +into the virtual environment interpreter's library set so it can be +found by ``import`` statements and by other console scripts such as +``pserve``, ``pshell``, ``proutes`` and ``pviews``. .. index:: single: running tests @@ -245,16 +243,16 @@ Here's sample output from a test run on UNIX: OK -.. note:: - - The ``-q`` option is passed to the ``setup.py test`` command to limit the - output to a stream of dots. If you don't pass ``-q``, you'll see more - verbose test result output (which normally isn't very useful). - The tests themselves are found in the ``tests.py`` module in your ``pcreate`` generated project. Within a project generated by the ``starter`` scaffold, a single sample test exists. +.. note:: + + The ``-q`` option is passed to the ``setup.py test`` command to limit the + output to a stream of dots. If you don't pass ``-q``, you'll see more + verbose test result output (which normally isn't very useful). + .. index:: single: running an application single: pserve @@ -572,8 +570,8 @@ adding more settings to this section. The ``pyramid.reload_templates`` setting in the ``[app:main]`` section is a :app:`Pyramid` -specific setting which is passed into the framework. If it -exists, and its value is ``true``, :term:`Chameleon` and :term:`Mako` -template changes will not require an application restart to be detected. See +exists, and its value is ``true``, supported template changes will not +require an application restart to be detected. See :ref:`reload_templates_section` for more information. .. warning:: The ``pyramid.reload_templates`` option should be turned off for @@ -698,11 +696,11 @@ testing, packaging, and distributing your application. .. note:: - ``setup.py`` is the de facto standard which Python developers use to - distribute their reusable code. You can read more about ``setup.py`` files - and their usage in the `Setuptools documentation - <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The - Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_. + ``setup.py`` is the de facto standard which Python developers use to + distribute their reusable code. You can read more about ``setup.py`` files + and their usage in the `Setuptools documentation + <http://peak.telecommunity.com/DevCenter/setuptools>`_ and `The + Hitchhiker's Guide to Packaging <http://guide.python-distribute.org/>`_. Our generated ``setup.py`` looks like this: @@ -820,7 +818,7 @@ also informs Python that the directory which contains it is a *package*. #. Line 1 imports the :term:`Configurator` class from :mod:`pyramid.config` that we use later. -#. Lines 4-11 define a function named ``main`` that returns a :app:`Pyramid` +#. Lines 4-12 define a function named ``main`` that returns a :app:`Pyramid` WSGI application. This function is meant to be called by the :term:`PasteDeploy` framework as a result of running ``pserve``. @@ -828,17 +826,20 @@ also informs Python that the directory which contains it is a *package*. Line 7 creates an instance of a :term:`Configurator`. - Line 8 registers a static view, which will serve up the files from the + Line 8 adds support for Chameleon templating bindings, allowing us to + specify renderers with the ``.pt`` extension. + + Line 9 registers a static view, which will serve up the files from the ``myproject:static`` :term:`asset specification` (the ``static`` directory of the ``myproject`` package). - Line 9 adds a :term:`route` to the configuration. This route is later + Line 10 adds a :term:`route` to the configuration. This route is later used by a view in the ``views`` module. - Line 10 calls ``config.scan()``, which picks up view registrations declared + Line 11 calls ``config.scan()``, which picks up view registrations declared elsewhere in the package (in this case, in the ``views.py`` module). - Line 11 returns a :term:`WSGI` application to the caller of the function + Line 12 returns a :term:`WSGI` application to the caller of the function (Pyramid's pserve). .. index:: @@ -870,31 +871,40 @@ specification` that specifies the ``mytemplate.pt`` file within the ``templates`` directory of the ``myproject`` package. The asset specification could have also been specified as ``myproject:templates/mytemplate.pt``; the leading package name and colon is -optional. The template file it actually points to is a :term:`Chameleon` ZPT -template file. +optional. The template file pointed to is a :term:`Chameleon` ZPT +template file (``templates/my_template.pt``). This view callable function is handed a single piece of information: the :term:`request`. The *request* is an instance of the :term:`WebOb` ``Request`` class representing the browser's request to our server. -This view returns a dictionary. When this view is invoked, a -:term:`renderer` converts the dictionary returned by the view into HTML, and -returns the result as the :term:`response`. This view is configured to -invoke a renderer which uses a :term:`Chameleon` ZPT template -(``templates/my_template.pt``). - -See :ref:`views_which_use_a_renderer` for more information about how views, -renderers, and templates relate and cooperate. - -.. note:: Because our ``development.ini`` has a ``pyramid.reload_templates = - true`` directive indicating that templates should be reloaded when - they change, you won't need to restart the application server to - see changes you make to templates. During development, this is - handy. If this directive had been ``false`` (or if the directive - did not exist), you would need to restart the application server - for each template change. For production applications, you should - set your project's ``pyramid.reload_templates`` to ``false`` to increase - the speed at which templates may be rendered. +This view is configured to invoke a :term:`renderer` on a template. The +dictionary the view returns (on line 6) provides the value the renderer +substitutes into the template when generating HTML. The renderer then +returns the HTML in a :term:`response`. + +.. note:: Dictionaries provide values to :term:`template`\s. + +.. note:: ``development.ini`` has a setting that controls how templates are + reloaded, ``pyramid.reload_templates``. + + - When set to ``True`` (as in the scaffold ``development.ini``) changed + templates automatically reload without a server restart. This is + convenient while developing, but slows template rendering speed. + + - When set to ``False`` (the default value), changing templates requires + a server restart to reload them. Production applications should use + ``pyramid.reload_templates = False``. + +.. seealso:: See also :ref:`views_which_use_a_renderer` for more information + about how views, renderers, and templates relate and cooperate. + +.. seealso:: Pyramid can also dynamically reload changed Python files. For + more on this see :ref:`reloading_code`. + +.. seealso:: The :ref:`debug_toolbar` provides interactive access to your + application's internals and, should an exception occur, allows interactive + access to traceback execution stack frames from the Python interpreter. .. index:: single: static directory @@ -970,12 +980,15 @@ named ``views`` instead of within a single ``views.py`` file, you might: - Create a ``views`` directory inside your ``myproject`` package directory (the same directory which holds ``views.py``). -- *Move* the existing ``views.py`` file to a file inside the new ``views`` - directory named, say, ``blog.py``. +- Create a file within the new ``views`` directory named ``__init__.py``. (It + can be empty. This just tells Python that the ``views`` directory is a + *package*.) -- Create a file within the new ``views`` directory named ``__init__.py`` (it - can be empty, this just tells Python that the ``views`` directory is a - *package*. +- *Move* the content from the existing ``views.py`` file to a file inside the + new ``views`` directory named, say, ``blog.py``. Because the ``templates`` + directory remains in the ``myproject`` package, the template :term:`asset + specification` values in ``blog.py`` must now be fully qualified with the + project's package name (``myproject:templates/blog.pt``). You can then continue to add view callable functions to the ``blog.py`` module, but you can also add other ``.py`` files which contain view callable @@ -992,6 +1005,8 @@ prompt with a similar configuration as would be loaded if you were running your Pyramid application via ``pserve``. This can be a useful debugging tool. See :ref:`interactive_shell` for more details. +.. _what_is_this_pserve_thing: + What Is This ``pserve`` Thing ----------------------------- @@ -1005,12 +1020,12 @@ Pyramid application based on the data in the file. application. As we saw in :ref:`firstapp_chapter`, ``pserve`` needn't be invoked at all to run a :app:`Pyramid` application. The use of ``pserve`` to run a :app:`Pyramid` application is purely conventional based on the output -of its scaffolding. But we strongly recommend using while developing your -application, because many other convenience introspection commands (such as -``pviews``, ``prequest``, ``proutes`` and others) are also implemented in -terms of configuration availability of this ``.ini`` file format. It also -configures Pyramid logging and provides the ``--reload`` switch for -convenient restarting of the server when code changes. +of its scaffolding. But we strongly recommend using ``pserve`` while +developing your application, because many other convenience introspection +commands (such as ``pviews``, ``prequest``, ``proutes`` and others) are also +implemented in terms of configuration availability of this ``.ini`` file +format. It also configures Pyramid logging and provides the ``--reload`` +switch for convenient restarting of the server when code changes. .. _alternate_wsgi_server: @@ -1022,7 +1037,7 @@ server. Waitress is a server that is suited for development and light production usage. It's not the fastest nor the most featureful WSGI server. Instead, its main feature is that it works on all platforms that Pyramid needs to run on, making it a good choice as a default server from the -perspective of Pyramid's developers. +perspective of Pyramid's developers. Any WSGI server is capable of running a :app:`Pyramid` application. But we suggest you stick with the default server for development, and that you wait diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index b4eb95186..740c81555 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -33,14 +33,11 @@ by the view must be compatible with the particular kind of renderer used, or an error may occur during view invocation. One exception exists: it is *always* OK to return a Response object, even -when a ``renderer`` is configured. If a view callable returns a response -object from a view that is configured with a renderer, the renderer is +when a ``renderer`` is configured. In such cases, the renderer is bypassed entirely. Various types of renderers exist, including serialization renderers -and renderers which use templating systems. See also -:ref:`views_which_use_a_renderer`. - +and renderers which use templating systems. .. index:: single: renderer @@ -51,16 +48,20 @@ and renderers which use templating systems. See also Writing View Callables Which Use a Renderer ------------------------------------------- -As we've seen, view callables needn't always return a Response object. -Instead, they may return an arbitrary Python object, with the expectation -that a :term:`renderer` will convert that object into a response instance on -your behalf. Some renderers use a templating system; other renderers use -object serialization techniques. - -View configuration can vary the renderer associated with a view callable via -the ``renderer`` attribute. For example, this call to -:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` renderer -with a view callable: +As we've seen, a view callable needn't always return a Response object. +Instead, it may return an arbitrary Python object, with the expectation that +a :term:`renderer` will convert that object into a response instance on your +behalf. Some renderers use a templating system; other renderers use object +serialization techniques. In practice, renderers obtain application data +values from Python dictionaries so, in practice, view callables which use +renderers return Python dictionaries. + +View callables can :ref:`explicitly call <example_render_to_response_call>` +renderers, but typically don't. Instead view configuration declares the +renderer used to render a view callable's results. This is done with the +``renderer`` attribute. For example, this call to +:meth:`~pyramid.config.Configurator.add_view` associates the ``json`` +renderer with a view callable: .. code-block:: python @@ -70,9 +71,8 @@ When this configuration is added to an application, the ``myproject.views.my_view`` view callable will now use a ``json`` renderer, which renders view return values to a :term:`JSON` response serialization. -Other built-in renderers include renderers which use the :term:`Chameleon` -templating language to render a dictionary to a response. Additional -renderers can be added by developers to the system as necessary. +Pyramid defines several :ref:`built_in_renderers`, and additional renderers +can be added by developers to the system as necessary. See :ref:`adding_and_overriding_renderers`. Views which use a renderer and return a non-Response value can vary non-body @@ -80,12 +80,10 @@ response attributes (such as headers and the HTTP status code) by attaching a property to the ``request.response`` attribute. See :ref:`request_response_attr`. -If the :term:`view callable` associated with a :term:`view configuration` -returns a Response object directly, any renderer associated with the view -configuration is ignored, and the response is passed back to :app:`Pyramid` -unchanged. For example, if your view callable returns an instance of the -:class:`pyramid.response.Response` class as a response, no renderer -will be employed. +As already mentioned, if the :term:`view callable` associated with a +:term:`view configuration` returns a Response object (or its instance), +any renderer associated with the view configuration is ignored, +and the response is passed back to :app:`Pyramid` unchanged. For example: .. code-block:: python :linenos: @@ -134,13 +132,18 @@ Built-In Renderers Several built-in renderers exist in :app:`Pyramid`. These renderers can be used in the ``renderer`` attribute of view configurations. +.. note:: + + Bindings for officially supported templating languages can be found + at :ref:`available_template_system_bindings`. + .. index:: pair: renderer; string ``string``: String Renderer ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``string`` renderer is a renderer which renders a view callable result to +The ``string`` renderer renders a view callable result to a string. If a view callable returns a non-Response object, and the ``string`` renderer is associated in that view's configuration, the result will be to run the object through the Python ``str`` function to generate a @@ -203,18 +206,12 @@ representing the JSON serialization of the return value: .. code-block:: python - '{"content": "Hello!"}' + {"content": "Hello!"} The return value needn't be a dictionary, but the return value must contain values serializable by the configured serializer (by default ``json.dumps``). -.. note:: - - Extra arguments can be passed to the serializer by overriding the default - ``json`` renderer. See :class:`pyramid.renderers.JSON` and - :ref:`adding_and_overriding_renderers` for more information. - -You can configure a view to use the JSON renderer by naming ``json`` as the +You can configure a view to use the JSON renderer by naming``json`` as the ``renderer`` argument of a view configuration, e.g. by using :meth:`~pyramid.config.Configurator.add_view`: @@ -235,6 +232,18 @@ using the api of the ``request.response`` attribute. See Serializing Custom Objects ++++++++++++++++++++++++++ +Some objects are not, by default, JSON-serializable (such as datetimes and +other arbitrary Python objects). You can, however, register code that makes +non-serializable objects serializable in two ways: + +- By defining a ``__json__`` method on objects in your application. + +- For objects you don't "own", you can register JSON renderer that knows about + an *adapter* for that kind of object. + +Using a Custom ``__json__`` Method +********************************** + Custom objects can be made easily JSON-serializable in Pyramid by defining a ``__json__`` method on the object's class. This method should return values natively JSON-serializable (such as ints, lists, dictionaries, strings, and @@ -260,6 +269,9 @@ will be the active request object at render time. # the JSON value returned by ``objects`` will be: # [{"x": 1}, {"x": 2}] +Using the ``add_adapter`` Method of a Custom JSON Renderer +********************************************************** + If you aren't the author of the objects being serialized, it won't be possible (or at least not reasonable) to add a custom ``__json__`` method to their classes in order to influence serialization. If the object passed @@ -274,19 +286,21 @@ objects using the registered adapters. A short example follows: from pyramid.renderers import JSON - json_renderer = JSON() - def datetime_adapter(obj, request): - return obj.isoformat() - json_renderer.add_adapter(datetime.datetime, datetime_adapter) + if __name__ == '__main__': + config = Configurator() + json_renderer = JSON() + def datetime_adapter(obj, request): + return obj.isoformat() + json_renderer.add_adapter(datetime.datetime, datetime_adapter) + config.add_renderer('json', json_renderer) - # then during configuration .... - config = Configurator() - config.add_renderer('json', json_renderer) +The ``add_adapter`` method should accept two arguments: the *class* of the object that you want this adapter to run for (in the example above, +``datetime.datetime``), and the adapter itself. -The adapter should accept two arguments: the object needing to be serialized -and ``request``, which will be the current request object at render time. -The adapter should raise a :exc:`TypeError` if it can't determine what to do -with the object. +The adapter should be a callable. It should accept two arguments: the object +needing to be serialized and ``request``, which will be the current request +object at render time. The adapter should raise a :exc:`TypeError` +if it can't determine what to do with the object. See :class:`pyramid.renderers.JSON` and :ref:`adding_and_overriding_renderers` for more information. @@ -371,136 +385,6 @@ renderer in :ref:`json_serializing_custom_objects` can be used when passing values to a JSONP renderer too. .. index:: - pair: renderer; chameleon - -.. _chameleon_template_renderers: - -``*.pt`` or ``*.txt``: Chameleon Template Renderers -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Two built-in renderers exist for :term:`Chameleon` templates. - -If the ``renderer`` attribute of a view configuration is an absolute path, a -relative path or :term:`asset specification` which has a final path element -with a filename extension of ``.pt``, the Chameleon ZPT renderer is used. -See :ref:`chameleon_zpt_templates` for more information about ZPT templates. - -If the ``renderer`` attribute of a view configuration is an absolute path or -a :term:`asset specification` which has a final path element with a filename -extension of ``.txt``, the :term:`Chameleon` text renderer is used. See -:ref:`chameleon_text_templates` for more information about Chameleon text -templates. - -The behavior of these renderers is the same, except for the engine -used to render the template. - -When a ``renderer`` attribute that names a template path or :term:`asset -specification` (e.g. ``myproject:templates/foo.pt`` or -``myproject:templates/foo.txt``) is used, the view must return a -:term:`Response` object or a Python *dictionary*. If the view callable with -an associated template returns a Python dictionary, the named template will -be passed the dictionary as its keyword arguments, and the template renderer -implementation will return the resulting rendered template in a response to -the user. If the view callable returns anything but a Response object or a -dictionary, an error will be raised. - -Before passing keywords to the template, the keyword arguments derived from -the dictionary returned by the view are augmented. The callable object -- -whatever object was used to define the view -- will be automatically inserted -into the set of keyword arguments passed to the template as the ``view`` -keyword. If the view callable was a class, the ``view`` keyword will be an -instance of that class. Also inserted into the keywords passed to the -template are ``renderer_name`` (the string used in the ``renderer`` attribute -of the directive), ``renderer_info`` (an object containing renderer-related -information), ``context`` (the context resource of the view used to render -the template), and ``request`` (the request passed to the view used to render -the template). ``request`` is also available as ``req`` in Pyramid 1.3+. - -Here's an example view configuration which uses a Chameleon ZPT renderer: - -.. code-block:: python - :linenos: - - # config is an instance of pyramid.config.Configurator - - config.add_view('myproject.views.hello_world', - name='hello', - context='myproject.resources.Hello', - renderer='myproject:templates/foo.pt') - -Here's an example view configuration which uses a Chameleon text renderer: - -.. code-block:: python - :linenos: - - config.add_view('myproject.views.hello_world', - name='hello', - context='myproject.resources.Hello', - renderer='myproject:templates/foo.txt') - -Views which use a Chameleon renderer can vary response attributes by using -the API of the ``request.response`` attribute. See -:ref:`request_response_attr`. - -.. index:: - pair: renderer; mako - -.. _mako_template_renderers: - -``*.mak`` or ``*.mako``: Mako Template Renderer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``Mako`` template renderer renders views using a Mako template. When -used, the view must return a Response object or a Python *dictionary*. The -dictionary items will then be used in the global template space. If the view -callable returns anything but a Response object or a dictionary, an error -will be raised. - -When using a ``renderer`` argument to a :term:`view configuration` to specify -a Mako template, the value of the ``renderer`` may be a path relative to the -``mako.directories`` setting (e.g. ``some/template.mak``) or, alternately, -it may be a :term:`asset specification` -(e.g. ``apackage:templates/sometemplate.mak``). Mako templates may -internally inherit other Mako templates using a relative filename or a -:term:`asset specification` as desired. - -Here's an example view configuration which uses a relative path: - -.. code-block:: python - :linenos: - - # config is an instance of pyramid.config.Configurator - - config.add_view('myproject.views.hello_world', - name='hello', - context='myproject.resources.Hello', - renderer='foo.mak') - -It's important to note that in Mako's case, the 'relative' path name -``foo.mak`` above is not relative to the package, but is relative to the -directory (or directories) configured for Mako via the ``mako.directories`` -configuration file setting. - -The renderer can also be provided in :term:`asset specification` -format. Here's an example view configuration which uses one: - -.. code-block:: python - :linenos: - - config.add_view('myproject.views.hello_world', - name='hello', - context='myproject.resources.Hello', - renderer='mypackage:templates/foo.mak') - -The above configuration will use the file named ``foo.mak`` in the -``templates`` directory of the ``mypackage`` package. - -The ``Mako`` template renderer can take additional arguments beyond the -standard ``pyramid.reload_templates`` setting, see the -:ref:`environment_chapter` for additional -:ref:`mako_template_renderer_settings`. - -.. index:: single: response headers (from a renderer) single: renderer response headers @@ -561,40 +445,6 @@ For more information on attributes of the request, see the API documentation in :ref:`request_module`. For more information on the API of ``request.response``, see :attr:`pyramid.request.Request.response`. -.. _response_prefixed_attrs: - -Deprecated Mechanism to Vary Attributes of Rendered Responses -------------------------------------------------------------- - -In previous releases of Pyramid (1.0 and before), the ``request.response`` -attribute did not exist. Instead, Pyramid required users to set special -``response_`` -prefixed attributes of the request to influence response -behavior. As of Pyramid 1.1, those request attributes are deprecated and -their use will cause a deprecation warning to be issued when used. Until -their existence is removed completely, we document them below, for benefit of -people with older code bases. - -``response_content_type`` - Defines the content-type of the resulting response, - e.g. ``text/xml``. - -``response_headerlist`` - A sequence of tuples describing header values that should be set in the - response, e.g. ``[('Set-Cookie', 'abc=123'), ('X-My-Header', 'foo')]``. - -``response_status`` - A WSGI-style status code (e.g. ``200 OK``) describing the status of the - response. - -``response_charset`` - The character set (e.g. ``UTF-8``) of the response. - -``response_cache_for`` - A value in seconds which will influence ``Cache-Control`` and ``Expires`` - headers in the returned response. The same can also be achieved by - returning various values in the ``response_headerlist``, this is purely a - convenience. - .. _adding_and_overriding_renderers: Adding and Changing Renderers @@ -744,44 +594,37 @@ ending with ``.jinja2`` in its ``renderer`` value. The ``name`` passed to the ``MyJinja2Renderer`` constructor will be the full value that was set as ``renderer=`` in the view configuration. -.. index:: - pair: renderer; changing +Adding a Default Renderer +~~~~~~~~~~~~~~~~~~~~~~~~~ -Changing an Existing Renderer -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can associate more than one filename extension with the same existing -renderer implementation as necessary if you need to use a different file -extension for the same kinds of templates. For example, to associate the -``.zpt`` extension with the Chameleon ZPT renderer factory, use the -:meth:`pyramid.config.Configurator.add_renderer` method: +To associate a *default* renderer with *all* view configurations (even +ones which do not possess a ``renderer`` attribute), pass ``None`` as +the ``name`` attribute to the renderer tag: .. code-block:: python - config.add_renderer('.zpt', 'pyramid.chameleon_zpt.renderer_factory') - -After you do this, :app:`Pyramid` will treat templates ending in both the -``.pt`` and ``.zpt`` filename extensions as Chameleon ZPT templates. - -To change the default mapping in which files with a ``.pt`` extension are -rendered via a Chameleon ZPT page template renderer, use a variation on the -following in your application's startup code: - -.. code-block:: python + config.add_renderer(None, 'mypackage.json_renderer_factory') - config.add_renderer('.pt', 'mypackage.pt_renderer') +.. index:: + pair: renderer; changing -After you do this, the :term:`renderer factory` in -``mypackage.pt_renderer`` will be used to render templates which end -in ``.pt``, replacing the default Chameleon ZPT renderer. +Changing an Existing Renderer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To associate a *default* renderer with *all* view configurations (even -ones which do not possess a ``renderer`` attribute), pass ``None`` as -the ``name`` attribute to the renderer tag: +Pyramid supports overriding almost every aspect of its setup through its +:ref:`Conflict Resolution <automatic_conflict_resolution>` mechanism. This +means that in most cases overriding a renderer is as simple as using the +:meth:`pyramid.config.Configurator.add_renderer` method to re-define the +template extension. For example, if you would like to override the ``.txt`` +extension to specify a new renderer you could do the following: .. code-block:: python - config.add_renderer(None, 'mypackage.json_renderer_factory') + json_renderer = pyramid.renderers.JSON() + config.add_renderer('json', json_renderer) + +After doing this, any views registered with the ``json`` renderer will use +the new renderer. .. index:: pair: renderer; overriding at runtime diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 699a3d4ac..b1bb611e5 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -300,7 +300,7 @@ the resource by :meth:`~pyramid.request.Request.resource_url`. The ``__resource_url__`` hook is passed two arguments: ``request`` and ``info``. ``request`` is the :term:`request` object passed to :meth:`~pyramid.request.Request.resource_url`. ``info`` is a dictionary with -two keys: +the following keys: ``physical_path`` A string representing the "physical path" computed for the resource, as diff --git a/docs/narr/sessions.rst b/docs/narr/sessions.rst index c4f4b5f07..649d22bd2 100644 --- a/docs/narr/sessions.rst +++ b/docs/narr/sessions.rst @@ -99,6 +99,11 @@ example: else: return Response('Fred was not in the session') +The first time this view is invoked produces ``Fred was not in the +session``. Subsequent invocations produce ``Fred was in the +session``, assuming of course that the client side maintains the +session's identity across multiple requests. + You can use a session much like a Python dictionary. It supports all dictionary methods, along with some extra attributes, and methods. @@ -146,8 +151,7 @@ Some gotchas: you've changed sessioning data. .. index:: - single: pyramid_beaker - single: Beaker + single: pyramid_redis_sessions single: session factory (alternates) .. _using_alternate_session_factories: @@ -155,13 +159,10 @@ Some gotchas: Using Alternate Session Factories --------------------------------- -At the time of this writing, exactly one alternate session factory -implementation exists, named ``pyramid_beaker``. This is a session factory -that uses the `Beaker <http://beaker.groovie.org/>`_ library as a backend. -Beaker has support for file-based sessions, database based sessions, and -encrypted cookie-based sessions. See `the pyramid_beaker documentation -<http://docs.pylonsproject.org/projects/pyramid_beaker/en/latest/>`_ for more -information about ``pyramid_beaker``. +At the time of this writing, exactly one project-endorsed alternate session +factory exists named :term:`pyramid_redis_sessions`. It can be downloaded from +PyPI. It uses the Redis database as a backend. It is the recommended +persistent session solution at the time of this writing. .. index:: single: session factory (custom) @@ -181,6 +182,8 @@ implementation in the :mod:`pyramid.session` module as inspiration. .. index:: single: flash messages +.. _flash_messages: + Flash Messages -------------- @@ -298,14 +301,15 @@ Preventing Cross-Site Request Forgery Attacks `Cross-site request forgery <http://en.wikipedia.org/wiki/Cross-site_request_forgery>`_ attacks are a -phenomenon whereby a user with an identity on your website might click on a -URL or button on another website which secretly redirects the user to your -application to perform some command that requires elevated privileges. - -You can avoid most of these attacks by making sure that the correct *CSRF -token* has been set in an :app:`Pyramid` session object before performing any -actions in code which requires elevated privileges that is invoked via a form -post. To use CSRF token support, you must enable a :term:`session factory` +phenomenon whereby a user who is logged in to your website might inadvertantly +load a URL because it is linked from, or embedded in, an attacker's website. +If the URL is one that may modify or delete data, the consequences can be dire. + +You can avoid most of these attacks by issuing a unique token to the browser +and then requiring that it be present in all potentially unsafe requests. +:app:`Pyramid` sessions provide facilities to create and check CSRF tokens. + +To use CSRF tokens, you must first enable a :term:`session factory` as described in :ref:`using_the_default_session_factory` or :ref:`using_alternate_session_factories`. @@ -324,33 +328,82 @@ To get the current CSRF token from the session, use the The ``session.get_csrf_token()`` method accepts no arguments. It returns a CSRF *token* string. If ``session.get_csrf_token()`` or -``session.new_csrf_token()`` was invoked previously for this session, the +``session.new_csrf_token()`` was invoked previously for this session, then the existing token will be returned. If no CSRF token previously existed for -this session, a new token will be will be set into the session and returned. +this session, then a new token will be will be set into the session and returned. The newly created token will be opaque and randomized. You can use the returned token as the value of a hidden field in a form that -posts to a method that requires elevated privileges. The handler for the -form post should use ``session.get_csrf_token()`` *again* to obtain the -current CSRF token related to the user from the session, and compare it to -the value of the hidden form field. For example, if your form rendering -included the CSRF token obtained via ``session.get_csrf_token()`` as a hidden -input field named ``csrf_token``: +posts to a method that requires elevated privileges, or supply it as a request +header in AJAX requests. + +For example, include the CSRF token as a hidden field: + +.. code-block:: html + + <form method="post" action="/myview"> + <input type="hidden" name="csrf_token" value="${request.session.get_csrf_token()}"> + <input type="submit" value="Delete Everything"> + </form> + +Or, include it as a header in a jQuery AJAX request: + +.. code-block:: javascript + + var csrfToken = ${request.session.get_csrf_token()}; + $.ajax({ + type: "POST", + url: "/myview", + headers: { 'X-CSRF-Token': csrfToken } + }).done(function() { + alert("Deleted"); + }); + + +The handler for the URL that receives the request +should then require that the correct CSRF token is supplied. + +Using the ``session.check_csrf_token`` Method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In request handling code, you can check the presence and validity of a CSRF +token with ``session.check_csrf_token(request)``. If the token is valid, +it will return True, otherwise it will raise ``HTTPBadRequest``. + +By default, it checks for a GET or POST parameter named ``csrf_token`` or a +header named ``X-CSRF-Token``. .. code-block:: python - :linenos: - token = request.session.get_csrf_token() - if token != request.POST['csrf_token']: - raise ValueError('CSRF token did not match') + def myview(request): + session = request.session + + # Require CSRF Token + session.check_csrf_token(request): + + ... .. index:: single: session.new_csrf_token +Checking CSRF Tokens With A View Predicate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A convenient way to require a valid CSRF Token for a particular view is to +include ``check_csrf=True`` as a view predicate. +See :meth:`pyramid.config.Configurator.add_route`. + +.. code-block:: python + + @view_config(request_method='POST', check_csrf=True, ...) + def myview(request): + ... + + Using the ``session.new_csrf_token`` Method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To explicitly add a new CSRF token to the session, use the +To explicitly create a new CSRF token, use the ``session.new_csrf_token()`` method. This differs only from ``session.get_csrf_token()`` inasmuch as it clears any existing CSRF token, creates a new CSRF token, sets the token into the session, and returns the diff --git a/docs/narr/subrequest.rst b/docs/narr/subrequest.rst index 6437bd0fa..4b4e99d41 100644 --- a/docs/narr/subrequest.rst +++ b/docs/narr/subrequest.rst @@ -232,12 +232,12 @@ unconditionally: - Ensures that the user implied by the request passed has the necessary authorization to invoke view callable before calling it. -- causes a :class:`~pyramid.events.NewResponse` event to be sent when the - Pyramid application returns a response. - - Calls any :term:`response callback` functions defined within the subrequest's lifetime if a response is obtained from the Pyramid application. +- causes a :class:`~pyramid.events.NewResponse` event to be sent if a response + is obtained. + - Calls any :term:`finished callback` functions defined within the subrequest's lifetime. diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index d4cf20b93..3e19f7198 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -8,10 +8,6 @@ dynamic data provided by a :term:`view`. :app:`Pyramid` offers a number of ways to perform templating tasks out of the box, and provides add-on templating support through a set of bindings packages. -Out of the box, :app:`Pyramid` provides templating via the :term:`Chameleon` -and :term:`Mako` templating libraries. :term:`Chameleon` provides support for -two different types of templates: :term:`ZPT` templates, and text templates. - Before discussing how built-in templates are used in detail, we'll discuss two ways to render templates within :app:`Pyramid` in general: directly, and via renderer @@ -32,7 +28,7 @@ given templating engine to do so. :app:`Pyramid` provides various APIs that allow you to render templates directly from within a view callable. For example, if there is a -:term:`Chameleon` ZPT template named ``foo.pt`` in a directory named +:term:`Chameleon` ZPT template named ``foo.pt`` in a directory named ``templates`` in your application, you can render the template from within the body of a view callable like so: @@ -60,19 +56,8 @@ In this case, this is the directory containing the file that defines the ``sample_view`` function. Although a renderer path is usually just a simple relative pathname, a path named as a renderer can be absolute, starting with a slash on UNIX or a drive letter -prefix on Windows. - -.. warning:: - - Only :term:`Chameleon` templates support defining a renderer for a - template relative to the location of the module where the view callable is - defined. Mako templates, and other templating system bindings work - differently. In particular, Mako templates use a "lookup path" as defined - by the ``mako.directories`` configuration file instead of treating - relative paths as relative to the current view module. See - :ref:`mako_templates`. - -The path can alternately be a :term:`asset specification` in the form +prefix on Windows. The path can alternately be a +:term:`asset specification` in the form ``some.dotted.package_name:relative/path``. This makes it possible to address template assets which live in another package. For example: @@ -90,16 +75,9 @@ An asset specification points at a file within a Python *package*. In this case, it points at a file named ``foo.pt`` within the ``templates`` directory of the ``mypackage`` package. Using a asset specification instead of a relative template name is usually -a good idea, because calls to ``render_to_response`` using asset -specifications will continue to work properly if you move the code -containing them around. - -.. note:: - - Mako templating system bindings also respect absolute asset - specifications as an argument to any of the ``render*`` commands. If a - template name defines a ``:`` (colon) character and is not an absolute - path, it is treated as an absolute asset specification. +a good idea, because calls to :func:`~pyramid.renderers.render_to_response` +using asset specifications will continue to work properly if you move the +code containing them around. In the examples above we pass in a keyword argument named ``request`` representing the current :app:`Pyramid` request. Passing a request @@ -147,8 +125,8 @@ import its API functions into your views module, use those APIs to generate a string, then return that string as the body of a :app:`Pyramid` :term:`Response` object. -For example, here's an example of using "raw" `Mako -<http://www.makotemplates.org/>`_ from within a :app:`Pyramid` :term:`view`: +For example, here's an example of using "raw" Mako_ from within a +:app:`Pyramid` :term:`view`: .. code-block:: python :linenos: @@ -163,10 +141,10 @@ For example, here's an example of using "raw" `Mako return response You probably wouldn't use this particular snippet in a project, because it's -easier to use the Mako renderer bindings which already exist in -:app:`Pyramid`. But if your favorite templating system is not supported as a -renderer extension for :app:`Pyramid`, you can create your own simple -combination as shown above. +easier to use the supported +:ref:`Mako bindings <available_template_system_bindings>`. But if your +favorite templating system is not supported as a renderer extension for +:app:`Pyramid`, you can create your own simple combination as shown above. .. note:: @@ -281,8 +259,8 @@ You can define more values which will be passed to every template executed as a result of rendering by defining :term:`renderer globals`. What any particular renderer does with these system values is up to the -renderer itself, but most template renderers, including Chameleon and Mako -renderers, make these names available as top-level template variables. +renderer itself, but most template renderers make these names available as +top-level template variables. .. index:: pair: renderer; templates @@ -322,7 +300,9 @@ template renderer: def my_view(request): return {'foo':1, 'bar':2} -.. note:: You do not need to supply the ``request`` value as a key +.. note:: + + You do not need to supply the ``request`` value as a key in the dictionary result returned from a renderer-configured view callable. :app:`Pyramid` automatically supplies this value for you so that the "most correct" system values are provided to @@ -350,11 +330,7 @@ it possible to address template assets which live in another package. Not just any template from any arbitrary templating system may be used as a renderer. Bindings must exist specifically for :app:`Pyramid` to use a -templating language template as a renderer. Currently, :app:`Pyramid` has -built-in support for two Chameleon templating languages: ZPT and text, and -the Mako templating system. See :ref:`built_in_renderers` for a discussion -of their details. :app:`Pyramid` also supports the use of :term:`Jinja2` -templates as renderers. See :ref:`available_template_system_bindings`. +templating language template as a renderer. .. sidebar:: Why Use A Renderer via View Configuration @@ -383,239 +359,11 @@ The same set of system values are provided to templates rendered via a renderer view configuration as those provided to templates rendered imperatively. See :ref:`renderer_system_values`. - -.. index:: - single: Chameleon ZPT templates - single: ZPT templates (Chameleon) - -.. _chameleon_zpt_templates: - -:term:`Chameleon` ZPT Templates -------------------------------- - -Like :term:`Zope`, :app:`Pyramid` uses :term:`ZPT` (Zope Page -Templates) as its default templating language. However, -:app:`Pyramid` uses a different implementation of the :term:`ZPT` -specification than Zope does: the :term:`Chameleon` templating -engine. The Chameleon engine complies largely with the `Zope Page -Template <http://wiki.zope.org/ZPT/FrontPage>`_ template -specification. However, it is significantly faster. - -The language definition documentation for Chameleon ZPT-style -templates is available from `the Chameleon website -<http://chameleon.repoze.org/>`_. - -Given a :term:`Chameleon` ZPT template named ``foo.pt`` in a directory -in your application named ``templates``, you can render the template as -a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='templates/foo.pt') - def my_view(request): - return {'foo':1, 'bar':2} - -See also :ref:`built_in_renderers` for more general information about -renderers, including Chameleon ZPT renderers. - -.. index:: - single: ZPT template (sample) - -A Sample ZPT Template -~~~~~~~~~~~~~~~~~~~~~ - -Here's what a simple :term:`Chameleon` ZPT template used under -:app:`Pyramid` might look like: - -.. code-block:: xml - :linenos: - - <!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" - xmlns:tal="http://xml.zope.org/namespaces/tal"> - <head> - <meta http-equiv="content-type" content="text/html; charset=utf-8" /> - <title>${project} Application</title> - </head> - <body> - <h1 class="title">Welcome to <code>${project}</code>, an - application generated by the <a - href="http://docs.pylonsproject.org/projects/pyramid/current/" - >pyramid</a> web - application framework.</h1> - </body> - </html> - -Note the use of :term:`Genshi` -style ``${replacements}`` above. This -is one of the ways that :term:`Chameleon` ZPT differs from standard -ZPT. The above template expects to find a ``project`` key in the set -of keywords passed in to it via :func:`~pyramid.renderers.render` or -:func:`~pyramid.renderers.render_to_response`. Typical ZPT -attribute-based syntax (e.g. ``tal:content`` and ``tal:replace``) also -works in these templates. - -.. index:: - single: ZPT macros - single: Chameleon ZPT macros - -Using ZPT Macros in :app:`Pyramid` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When a :term:`renderer` is used to render a template, :app:`Pyramid` makes at -least two top-level names available to the template by default: ``context`` -and ``request``. One of the common needs in ZPT-based templates is to use -one template's "macros" from within a different template. In Zope, this is -typically handled by retrieving the template from the ``context``. But the -context in :app:`Pyramid` is a :term:`resource` object, and templates cannot -usually be retrieved from resources. To use macros in :app:`Pyramid`, you -need to make the macro template itself available to the rendered template by -passing the macro template, or even the macro itself, *into* the rendered -template. To do this you can use the :func:`pyramid.renderers.get_renderer` -API to retrieve the macro template, and pass it into the template being -rendered via the dictionary returned by the view. For example, using a -:term:`view configuration` via a :class:`~pyramid.view.view_config` decorator -that uses a :term:`renderer`: - -.. code-block:: python - :linenos: - - from pyramid.renderers import get_renderer - from pyramid.view import view_config - - @view_config(renderer='templates/mytemplate.pt') - def my_view(request): - main = get_renderer('templates/master.pt').implementation() - return {'main':main} - -Where ``templates/master.pt`` might look like so: - -.. code-block:: xml - :linenos: - - <html xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal" - xmlns:metal="http://xml.zope.org/namespaces/metal"> - <span metal:define-macro="hello"> - <h1> - Hello <span metal:define-slot="name">Fred</span>! - </h1> - </span> - </html> - -And ``templates/mytemplate.pt`` might look like so: - -.. code-block:: xml - :linenos: - - <html xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal" - xmlns:metal="http://xml.zope.org/namespaces/metal"> - <span metal:use-macro="main.macros['hello']"> - <span metal:fill-slot="name">Chris</span> - </span> - </html> - - -Using A Chameleon Macro Name Within a Renderer Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -At times, you may want to render a macro inside of a Chameleon ZPT template -instead of the full Chameleon ZPT template. To render the content of a -``define-macro`` field inside a Chameleon ZPT template, given a Chameleon -template file named ``foo.pt`` and a macro named ``bar`` defined within it -(e.g. ``<div metal:define-macro="bar">...</div>``), you can configure the -template as a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='foo#bar.pt') - def my_view(request): - return {'project':'my project'} - -The above will render only the ``bar`` macro defined within the ``foo.pt`` -template instead of the entire template. - -.. versionadded:: 1.4 - -.. index:: - single: Chameleon text templates - -.. _chameleon_text_templates: - -Templating with :term:`Chameleon` Text Templates ------------------------------------------------- - -:app:`Pyramid` also allows for the use of templates which are -composed entirely of non-XML text via :term:`Chameleon`. To do so, -you can create templates that are entirely composed of text except for -``${name}`` -style substitution points. - -Here's an example usage of a Chameleon text template. Create a file -on disk named ``mytemplate.txt`` in your project's ``templates`` -directory with the following contents: - -.. code-block:: text - - Hello, ${name}! - -Then in your project's ``views.py`` module, you can create a view -which renders this template: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='templates/mytemplate.txt') - def my_view(request): - return {'name':'world'} - -When the template is rendered, it will show: - -.. code-block:: text - - Hello, world! - -See also :ref:`built_in_renderers` for more general information about -renderers, including Chameleon text renderers. - -.. index:: - single: template renderer side effects - -Side Effects of Rendering a Chameleon Template ----------------------------------------------- - -When a Chameleon template is rendered from a file, the templating -engine writes a file in the same directory as the template file itself -as a kind of cache, in order to do less work the next time the -template needs to be read from disk. If you see "strange" ``.py`` -files showing up in your ``templates`` directory (or otherwise -directly "next" to your templates), it is due to this feature. - -If you're using a version control system such as Subversion, you -should configure it to ignore these files. Here's the contents of the -author's ``svn propedit svn:ignore .`` in each of my ``templates`` -directories. - -.. code-block:: text - - *.pt.py - *.txt.py - -Note that I always name my Chameleon ZPT template files with a ``.pt`` -extension and my Chameleon text template files with a ``.txt`` -extension so that these ``svn:ignore`` patterns work. - .. index:: pair: debugging; templates +.. _debugging_templates: + Debugging Templates ------------------- @@ -642,107 +390,6 @@ The output tells you which template the error occurred in, as well as displaying the arguments passed to the template itself. .. index:: - single: template internationalization - single: internationalization (of templates) - -:term:`Chameleon` Template Internationalization ------------------------------------------------ - -See :ref:`chameleon_translation_strings` for information about -supporting internationalized units of text within :term:`Chameleon` -templates. - -.. index:: - single: Mako - -.. _mako_templates: - -Templating With Mako Templates ------------------------------- - -:term:`Mako` is a templating system written by Mike Bayer. :app:`Pyramid` -has built-in bindings for the Mako templating system. The language -definition documentation for Mako templates is available from `the Mako -website <http://www.makotemplates.org/>`_. - -To use a Mako template, given a :term:`Mako` template file named ``foo.mak`` -in the ``templates`` subdirectory in your application package named -``mypackage``, you can configure the template as a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='foo.mak') - def my_view(request): - return {'project':'my project'} - -For the above view callable to work, the following setting needs to be -present in the application stanza of your configuration's ``ini`` file: - -.. code-block:: ini - - mako.directories = mypackage:templates - -This lets the Mako templating system know that it should look for templates -in the ``templates`` subdirectory of the ``mypackage`` Python package. See -:ref:`mako_template_renderer_settings` for more information about the -``mako.directories`` setting and other Mako-related settings that can be -placed into the application's ``ini`` file. - -.. index:: - single: Mako template (sample) - -A Sample Mako Template -~~~~~~~~~~~~~~~~~~~~~~ - -Here's what a simple :term:`Mako` template used under :app:`Pyramid` might -look like: - -.. code-block:: xml - :linenos: - - <html> - <head> - <title>${project} Application</title> - </head> - <body> - <h1 class="title">Welcome to <code>${project}</code>, an - application generated by the <a - href="http://docs.pylonsproject.org/projects/pyramid/current/" - >pyramid</a> web application framework.</h1> - </body> - </html> - -This template doesn't use any advanced features of Mako, only the -``${}`` replacement syntax for names that are passed in as -:term:`renderer globals`. See the `the Mako documentation -<http://www.makotemplates.org/>`_ to use more advanced features. - -Using A Mako def name Within a Renderer Name -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sommetime you'd like to render a ``def`` inside of a Mako template instead of -the full Mako template. To render a def inside a Mako template, given a -:term:`Mako` template file named ``foo.mak`` and a def named ``bar``, you can -configure the template as a :term:`renderer` like so: - -.. code-block:: python - :linenos: - - from pyramid.view import view_config - - @view_config(renderer='foo#bar.mak') - def my_view(request): - return {'project':'my project'} - -The above will render the ``bar`` def from within the ``foo.mak`` template -instead of the entire template. - -.. versionadded:: 1.4 - -.. index:: single: automatic reloading of templates single: template automatic reload @@ -757,9 +404,11 @@ appear immediately without needing to restart the application process. environment so that a change to a template will be automatically detected, and the template will be reloaded on the next rendering. -.. warning:: Auto-template-reload behavior is not recommended for - production sites as it slows rendering slightly; it's - usually only desirable during development. +.. warning:: + + Auto-template-reload behavior is not recommended for + production sites as it slows rendering slightly; it's + usually only desirable during development. In order to turn on automatic reloading of templates, you can use an environment variable, or a configuration file setting. @@ -770,31 +419,48 @@ variable set to ``1``, For example: .. code-block:: text - $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini + $ PYRAMID_RELOAD_TEMPLATES=1 $VENV/bin/pserve myproject.ini To use a setting in the application ``.ini`` file for the same purpose, set the ``pyramid.reload_templates`` key to ``true`` within the application's configuration section, e.g.: .. code-block:: ini - :linenos: + :linenos: - [app:main] - use = egg:MyProject - pyramid.reload_templates = true + [app:main] + use = egg:MyProject + pyramid.reload_templates = true .. index:: single: template system bindings + single: Chameleon single: Jinja2 + single: Mako .. _available_template_system_bindings: Available Add-On Template System Bindings ----------------------------------------- -Jinja2 template bindings are available for :app:`Pyramid` in the -``pyramid_jinja2`` package. You can get the latest release of -this package from the -`Python package index <http://pypi.python.org/pypi/pyramid_jinja2>`_ -(pypi). +The Pylons Project maintains several packages providing bindings to different +templating languages including the following: + ++------------------------------+------------------------------+ +| Template Language | Pyramid Bindings | ++==============================+==============================+ +| Chameleon_ | pyramid_chameleon_ | ++------------------------------+------------------------------+ +| Jinja2_ | pyramid_jinja2_ | ++------------------------------+------------------------------+ +| Mako_ | pyramid_mako_ | ++------------------------------+------------------------------+ + +.. _Chameleon: http://chameleon.readthedocs.org/en/latest/ +.. _pyramid_chameleon: https://pypi.python.org/pypi/pyramid_chameleon + +.. _Jinja2: http://jinja.pocoo.org/docs/ +.. _pyramid_jinja2: https://pypi.python.org/pypi/pyramid_jinja2 +.. _Mako: http://www.makotemplates.org/ +.. _pyramid_mako: https://pypi.python.org/pypi/pyramid_mako diff --git a/docs/narr/testing.rst b/docs/narr/testing.rst index bfb1287d9..88d6904c7 100644 --- a/docs/narr/testing.rst +++ b/docs/narr/testing.rst @@ -125,7 +125,7 @@ method attached to ``MyTest`` will use an isolated registry. The :func:`~pyramid.testing.setUp` and :func:`~pyramid.testing.tearDown` functions accepts various arguments that influence the environment of the -test. See the :ref:`testing_module` chapter for information about the extra +test. See the :ref:`testing_module` API for information about the extra arguments supported by these functions. If you also want to make :func:`~pyramid.threadlocal.get_current_request` return something @@ -202,7 +202,7 @@ any ``get_current*`` function. Using the ``Configurator`` and ``pyramid.testing`` APIs in Unit Tests --------------------------------------------------------------------- -The ``Configurator`` API and the ``pyramid.testing`` module provide a number +The ``Configurator`` API and the :mod:`pyramid.testing` module provide a number of functions which can be used during unit testing. These functions make :term:`configuration declaration` calls to the current :term:`application registry`, but typically register a "stub" or "dummy" feature in place of the @@ -222,6 +222,12 @@ function. raise HTTPForbidden return {'greeting':'hello'} +.. note:: + + This code implies that you have defined a renderer imperatively in a + relevant :class:`pyramid.config.Configurator` instance, + otherwise it would fail when run normally. + Without doing anything special during a unit test, the call to :func:`~pyramid.security.has_permission` in this view function will always return a ``True`` value. When a :app:`Pyramid` application starts normally, @@ -291,7 +297,7 @@ function is called, :func:`pyramid.security.has_permission` will call the access. We check that the view function raises a :exc:`~pyramid.httpexceptions.HTTPForbidden` error. -The second test method, named ``test_view_fn_allowed`` tests the alternate +The second test method, named ``test_view_fn_allowed``, tests the alternate case, where the authentication policy allows access. Notice that we pass different values to :meth:`~pyramid.config.Configurator.testing_securitypolicy` to obtain this @@ -373,7 +379,7 @@ after accessing some values that require a fully set up environment. result = my_view(request) self.assertEqual(result.status, '200 OK') body = result.app_iter[0] - self.failUnless('Welcome to' in body) + self.assertTrue('Welcome to' in body) self.assertEqual(len(result.headerlist), 2) self.assertEqual(result.headerlist[0], ('Content-Type', 'text/html; charset=UTF-8')) @@ -416,7 +422,7 @@ functional testing package written by Ian Bicking. def test_root(self): res = self.testapp.get('/', status=200) - self.failUnless('Pyramid' in res.body) + self.assertTrue('Pyramid' in res.body) When this test is run, each test creates a "real" WSGI application using the ``main`` function in your ``myapp.__init__`` module and uses :term:`WebTest` diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 2eb6ece13..454bb5620 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -146,35 +146,15 @@ refer to a root factory defined in a different module. If no :term:`root factory` is passed to the :app:`Pyramid` :term:`Configurator` constructor, or if the ``root_factory`` value -specified is ``None``, a *default* root factory is used. The default +specified is ``None``, a :term:`default root factory` is used. The default root factory always returns a resource that has no child resources; it is effectively empty. Usually a root factory for a traversal-based application will be more -complicated than the above ``Root`` class; in particular it may be -associated with a database connection or another persistence mechanism. - -.. sidebar:: Emulating the Default Root Factory - - For purposes of understanding the default root factory better, we'll note - that you can emulate the default root factory by using this code as an - explicit root factory in your application setup: - - .. code-block:: python - :linenos: - - class Root(object): - def __init__(self, request): - pass - - config = Configurator(root_factory=Root) - - The default root factory is just a really stupid object that has no - behavior or state. Using :term:`traversal` against an application that - uses the resource tree supplied by the default root resource is not very - interesting, because the default root resource has no children. Its - availability is more useful when you're developing an application using - :term:`URL dispatch`. +complicated than the above ``Root`` class; in particular it may be associated +with a database connection or another persistence mechanism. The above +``Root`` class is analogous to the default root factory present in Pyramid. The +default root factory is very simple and not very useful. .. note:: @@ -289,7 +269,7 @@ system uses this algorithm to find a :term:`context` resource and a return resource "C". #. Traversal ends when a) the entire path is exhausted or b) when any - resouce raises a :exc:`KeyError` from its ``__getitem__`` or c) when any + resource raises a :exc:`KeyError` from its ``__getitem__`` or c) when any non-final path element traversal does not have a ``__getitem__`` method (resulting in a :exc:`AttributeError`) or d) when any path element is prefixed with the set of characters ``@@`` (indicating that the characters diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index ca6dc565b..64343ca3e 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -150,7 +150,7 @@ do things the newer way: .. code-block:: python :linenos: - from pyramid.view. import view_config + from pyramid.view import view_config from pyramid.static import static_view myview = static_view('static', 'static', use_subpath=True) diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 18cb3e4db..61849c3c0 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -105,6 +105,7 @@ to using the previous combination of ``add_route`` and ``add_view``. .. _route_pattern_syntax: + Route Pattern Syntax ~~~~~~~~~~~~~~~~~~~~ @@ -127,6 +128,10 @@ and: /{foo}/bar/baz +If a pattern is a valid URL it won't be ever matched against an incoming +request. Instead it can be useful for generating external URLs. See +:ref:`External routes <external_route_narr>` for details. + A pattern segment (an individual item between ``/`` characters in the pattern) may either be a literal string (e.g. ``foo``) *or* it may be a replacement marker (e.g. ``{foo}``) or a certain combination of both. A @@ -394,13 +399,6 @@ process. Examples of route predicate arguments are ``pattern``, ``xhr``, and Other arguments are ``name`` and ``factory``. These arguments represent neither predicates nor view configuration information. -.. warning:: - - Some arguments are view-configuration related arguments, such as - ``view_renderer``. These only have an effect when the route configuration - names a ``view`` and these arguments have been deprecated as of - :app:`Pyramid` 1.1. - .. index:: single: route matching @@ -754,9 +752,39 @@ other non-``name`` and non-``pattern`` arguments to exception to this rule is use of the ``pregenerator`` argument, which is not ignored when ``static`` is ``True``. +:ref:`External routes <external_route_narr>` are implicitly static. + .. versionadded:: 1.1 the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` +.. _external_route_narr: + + +External Routes +--------------- + +.. versionadded:: 1.5 + +Route patterns that are valid URLs, are treated as external routes. Like +:ref:`static routes <static_route_narr>` they are useful for URL generation +purposes only and are never considered for matching at request time. + +.. code-block:: python + :linenos: + + >>> config = Configurator() + >>> config.add_route('youtube', 'https://youtube.com/watch/{video_id}') + ... + >>> request.route_url('youtube', video_id='oHg5SJYRHA0') + >>> "https://youtube.com/watch/oHg5SJYRHA0" + +Most pattern replacements and calls to +:meth:`pyramid.request.Request.route_url` will work as expected. However, calls +to :meth:`pyramid.request.Request.route_path` against external patterns will +raise an exception, and passing ``_app_url`` to +:meth:`~pyramid.request.Request.route_url` to generate a URL against a route +that has an external pattern will also raise an exception. + .. index:: single: redirecting to slash-appended routes @@ -865,7 +893,7 @@ Debugging Route Matching ------------------------ It's useful to be able to take a peek under the hood when requests that enter -your application arent matching your routes as you expect them to. To debug +your application aren't matching your routes as you expect them to. To debug route matching, use the ``PYRAMID_DEBUG_ROUTEMATCH`` environment variable or the ``pyramid.debug_routematch`` configuration file setting (set either to ``true``). Details of the route matching decision for a particular request to the diff --git a/docs/narr/viewconfig.rst b/docs/narr/viewconfig.rst index 241ce62b5..7c76116f7 100644 --- a/docs/narr/viewconfig.rst +++ b/docs/narr/viewconfig.rst @@ -290,9 +290,9 @@ configured view. of the ``REQUEST_METHOD`` of the :term:`WSGI` environment. ``request_param`` - This value can be any string or a sequence of strings. A view declaration - with this argument ensures that the view will only be called when the - :term:`request` has a key in the ``request.params`` dictionary (an HTTP + This value can be any string or a sequence of strings. A view declaration + with this argument ensures that the view will only be called when the + :term:`request` has a key in the ``request.params`` dictionary (an HTTP ``GET`` or ``POST`` variable) that has a name which matches the supplied value. @@ -306,8 +306,6 @@ configured view. consideration of keys and values in the ``request.params`` dictionary. ``match_param`` - .. versionadded:: 1.2 - This param may be either a single string of the format "key=value" or a dict of key/value pairs. @@ -324,6 +322,8 @@ configured view. If ``match_param`` is not supplied, the view will be invoked without consideration of the keys and values in ``request.matchdict``. + .. versionadded:: 1.2 + ``containment`` This value should be a reference to a Python class or :term:`interface` that a parent object in the context resource's :term:`lineage` must provide @@ -465,6 +465,36 @@ configured view. .. versionadded:: 1.4a1 +Inverting Predicate Values +++++++++++++++++++++++++++ + +You can invert the meaning of any predicate value by wrapping it in a call to +:class:`pyramid.config.not_`. + +.. code-block:: python + :linenos: + + from pyramid.config import not_ + + config.add_view( + 'mypackage.views.my_view', + route_name='ok', + request_method=not_('POST') + ) + +The above example will ensure that the view is called if the request method +is *not* ``POST``, at least if no other view is more specific. + +This technique of wrapping a predicate value in ``not_`` can be used anywhere +predicate values are accepted: + +- :meth:`pyramid.config.Configurator.add_view` + +- :meth:`pyramid.view.view_config` + +.. versionadded:: 1.5 + + .. index:: single: view_config decorator @@ -505,7 +535,7 @@ configuration stanza: .. code-block:: python :linenos: - config.add_view('mypackage.views.my_view', route_name='ok', + config.add_view('mypackage.views.my_view', route_name='ok', request_method='POST', permission='read') All arguments to ``view_config`` may be omitted. For example: @@ -792,7 +822,7 @@ of this: def delete(self): return Response('delete') - if __name__ == '__main__': + def main(global_config, **settings): config = Configurator() config.add_route('rest', '/rest') config.add_view( @@ -801,9 +831,10 @@ of this: RESTView, route_name='rest', attr='post', request_method='POST') config.add_view( RESTView, route_name='rest', attr='delete', request_method='DELETE') + return config.make_wsgi_app() -To reduce the amount of repetion in the ``config.add_view`` statements, we -can move the ``route_name='rest'`` argument to a ``@view_default`` class +To reduce the amount of repetition in the ``config.add_view`` statements, we +can move the ``route_name='rest'`` argument to a ``@view_defaults`` class decorator on the RESTView class: .. code-block:: python @@ -827,12 +858,13 @@ decorator on the RESTView class: def delete(self): return Response('delete') - if __name__ == '__main__': + def main(global_config, **settings): config = Configurator() config.add_route('rest', '/rest') config.add_view(RESTView, attr='get', request_method='GET') config.add_view(RESTView, attr='post', request_method='POST') config.add_view(RESTView, attr='delete', request_method='DELETE') + return config.make_wsgi_app() :class:`pyramid.view.view_defaults` accepts the same set of arguments that :class:`pyramid.view.view_config` does, and they have the same meaning. Each @@ -976,6 +1008,8 @@ invoked as the result of the ``http_cache`` argument to view configuration. .. index:: pair: view configuration; debugging +.. _debugging_view_configuration: + Debugging View Configuration ---------------------------- diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index c0ca450b1..f0a4b5a0b 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -287,7 +287,7 @@ When such a request reaches a view in your application, the @view_config(renderer='string') def aview(request): - print request.json_body + print(request.json_body) return 'OK' For the above view, printed to the console will be: diff --git a/docs/quick_tour.rst b/docs/quick_tour.rst new file mode 100644 index 000000000..2db18c8a7 --- /dev/null +++ b/docs/quick_tour.rst @@ -0,0 +1,890 @@ +.. _quick_tour: + +===================== +Quick Tour of Pyramid +===================== + +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. + +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 <http://www.python.org/download/releases/>`_, 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: + +.. parsed-literal:: + + $ pyvenv env33 + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | env33/bin/python + $ env33/bin/easy_install "pyramid==\ |release|\ " + +For Windows: + +.. parsed-literal:: + + # Use your browser to download: + # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py + c:\\> c:\\Python33\\python -m venv env33 + 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 in October 2011.) + +.. note:: + + Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace + packages which, until recently, ``pip`` didn't permit. Also, Pyramid has + some optional C extensions for performance. With ``easy_install``, Windows + users can get these extensions without needing a C compiler. + +.. 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>` + +Hello World +=========== + +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: + +This simple example is easy to run. Save this as ``app.py`` and run it: + +.. code-block:: bash + + $ python ./app.py + +Next, open `http://localhost:6543/ <http://localhost:6543/>`_ in a +browser and you will see the ``Hello World!`` message. + +New to Python web programming? If so, some lines in module merit +explanation: + +#. *Line 10*. The ``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 particular URL :term:`route`. + +#. *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*. + +.. seealso:: See Also: + :ref:`Quick Tutorial Hello World <qtut_hello_world>`, + :ref:`firstapp_chapter`, and + :ref:`Single File Tasks tutorial <tutorials: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. + +Pyramid has always fit nicely into the existing world of Python web +development (virtual environments, packaging, scaffolding, +first to embrace Python 3, etc.) For request handling, 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, if you visited ``http://localhost:6543/?name=alice``, +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. + +.. seealso:: See Also: + :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. + +So far our examples place everything in one file: + +- the view function + +- its registration with the configurator + +- the route to map it to a URL + +- 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 setup +the views. 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 now have a ``views.py`` module that is focused on handling requests +and responses: + +.. literalinclude:: quick_tour/views/views.py + :linenos: + +We have 4 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 shows issuing 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. + +.. seealso:: See Also: + :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. + +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 + +- 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. + +What if we want part of the URL to be available as data in my view? This +route declaration: + +.. literalinclude:: quick_tour/routing/app.py + :start-after: Start Route 1 + :end-before: End Route 1 + +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 + +``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` + +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. + +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 as an +example: + +.. literalinclude:: quick_tour/templating/views.py + :start-after: Start View 1 + :end-before: End View 1 + +Ahh, that looks better. We have a view that is focused on Python code. +Our ``@view_config`` decorator specifies a :term:`renderer` that points +our template file. Our view then simply returns data which is then +supplied to our template: + +.. 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}``. + +.. seealso:: See Also: + :ref:`Quick Tutorial Templating <qtut_templating>`, + :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, +modelled 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: + +.. code-block:: python + + config.include('pyramid_jinja2') + +The only change in our view...point the renderer at the ``.jinja2`` file: + +.. literalinclude:: quick_tour/jinja2/views.py + :start-after: Start View 1 + :end-before: End View 1 + +Our Jinja2 template is very similar to our previous template: + +.. literalinclude:: quick_tour/jinja2/hello_world.jinja2 + :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. + +.. seealso:: See Also: + :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 +:term:`configurator`: + +.. literalinclude:: quick_tour/static_assets/app.py + :start-after: Start Static 1 + :end-before: End Static 1 + +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. + +Next, make a directory ``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: + +.. literalinclude:: quick_tour/static_assets/hello_world.pt + :language: html + :start-after: Start Link 1 + :end-before: End Link 1 + +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 +web developer changes the arrangement on disk? Pyramid gives a helper +that provides flexibility on URL generation: + +.. literalinclude:: quick_tour/static_assets/hello_world.pt + :language: html + :start-after: Start Link 2 + :end-before: End Link 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 +gain refactoring flexibility later. + +.. seealso:: See Also: + :ref:`Quick Tutorial Static Assets <qtut_static_assets>`, + :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: + +.. literalinclude:: quick_tour/json/views.py + :start-after: Start View 1 + :end-before: End View 2 + +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. + +.. seealso:: See Also: + :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: + +- Group views + +- Centralize some repetitive defaults + +- 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: + +.. literalinclude:: quick_tour/view_classes/views.py + :start-after: Start View 1 + :end-before: End View 1 + +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 + ``@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. + +- The third view is returned when clicking on a button such + as ``<input type="submit" name="form.delete" value="Delete"/>``. + +Only one route needed, stated in one place atop the view class. Also, +the assignment of the ``name`` is done in the ``__init__``. Our +templates can then use ``{{ view.name }}``. + +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`` + +.. 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` + +Quick Project Startup with Scaffolds +==================================== + +So far we have done all of our *Quick Glance* 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: + +.. code-block:: bash + + $ pcreate --list + Available scaffolds: + alchemy: Pyramid SQLAlchemy project using url dispatch + 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: + +.. code-block:: bash + + $ pcreate --scaffold pyramid_jinja2_starter hello_world + +We next use the normal Python development to setup 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: + +.. code-block:: bash + + $ pserve development.ini + +Let's look at ``pserve`` and configuration in more depth. + +.. seealso:: See Also: + :ref:`Quick Tutorial Scaffolds <qtut_scaffolds>`, + :ref:`project_narr`, and + :doc:`../narr/scaffolding` + +Application Running with ``pserve`` +=================================== + +Prior to scaffolds, our project mixed a number of operations 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. + +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. + +.. seealso:: See Also: + :ref:`what_is_this_pserve_thing` + +Configuration with ``.ini`` Files +================================= + +Earlier in *Quick Glance* 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: + +- ``[app:hello_world]`` configures our WSGI app + +- ``[pipeline:main]`` sets up our WSGI "pipeline" + +- ``[server:main]`` holds our WSGI server settings + +- Various sections afterwards configure our Python logging system + +We have a few decisions made for us in this configuration: + +#. *Choice of web server*. The ``use = egg:pyramid#wsgiref`` tell + ``pserve`` to the ``wsgiref`` server that is wrapped in the Pyramid + package. + +#. *Port number*. ``port = 6543`` tells ``wsgiref`` 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. + +#. *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. + +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 traceback information. + +.. seealso:: See Also: + :ref:`Quick Tutorial Application Configuration <qtut_ini>`, + :ref:`environment_chapter` and + :doc:`../narr/paste` + + +Easier Development with ``debugtoolbar`` +======================================== + +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. + +``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: + +.. literalinclude:: quick_tour/package/setup.py + :start-after: Start Requires + :end-before: End Requires + +...and re-run your setup: + +.. code-block:: bash + + $ python ./setup.py develop + +The Python package was 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: + +.. literalinclude:: quick_tour/package/hello_world/__init__.py + :start-after: Start Include + :end-before: End Include + +Now that we have a configuration file, we can use the +``pyramid.includes`` facility and place this in our +``development.ini`` instead: + +.. literalinclude:: quick_tour/package/development.ini + :language: ini + :start-after: Start Includes + :end-before: End Includes + +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, 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:`pyramid_debugtoolbar <toolbar:overview>` + +Unit Tests and ``nose`` +======================= + +Yikes! We got this far and we haven't yet discussed tests. Particularly +egregious, as Pyramid has had a deep commitment to full test coverage +since before it was released. + +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: + +.. code-block:: python + + setup(name='hello_world', + # Some lines removed... + extras_require={ + 'testing': ['nose', 'coverage'], + } + ) + +We changed ``setup.py`` which means we need to re-run +``python ./setup.py develop``. We can now run all our tests: + +.. code-block:: bash + + $ nosetests hello_world/tests.py + . + 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% + --------------------------------------------------- + TOTAL 35 9 74% + ---------------------------------------------------------------------- + Ran 1 test in 0.931s + + OK + +Our unit test passed. What did our test look like? + +.. literalinclude:: quick_tour/package/hello_world/tests.py + +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:`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*. + +Fortunately Pyramid uses the normal Python approach to logging. The +scaffold generated, in your ``development.ini``, 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 setup the logging: + +.. literalinclude:: quick_tour/package/hello_world/views.py + :start-after: Start Logging 1 + :end-before: End Logging 1 + +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 + +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: + +.. literalinclude:: quick_tour/package/development.ini + :language: ini + :start-after: Start Sphinx Include + :end-before: End Sphinx Include + +Our application, a package named ``hello_world``, is setup 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 + +.. seealso:: See Also: + :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`. + +Pyramid has basic built-in support for sessions, with add-ons such as +``pyramid_redis_sessions`` (or your own custom sessioning engine) that provide +richer session support. 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 + +.. warning:: + + 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 + +Pyramid's :term:`request` object now has a ``session`` attribute +that we can use in our view code: + +.. literalinclude:: quick_tour/package/hello_world/views.py + :start-after: Start Sphinx Include 1 + :end-before: End Sphinx Include 1 + +With this, each reload will increase the counter displayed in our +Jinja2 template: + +.. literalinclude:: quick_tour/package/hello_world/templates/mytemplate.jinja2 + :language: jinja + :start-after: Start Sphinx Include 1 + :end-before: End Sphinx Include 1 + +.. seealso:: See Also: + :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. + +Pyramid and SQLAlchemy are great friends. That friendship includes a +scaffold! + +.. code-block:: bash + + $ pcreate --scaffold alchemy sqla_demo + $ 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: + +.. 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: + +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models.py + :start-after: Start Sphinx Include + :end-before: End Sphinx Include + +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 + +.. 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>` + +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. + +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 + + class WikiPage(colander.MappingSchema): + title = colander.SchemaNode(colander.String()) + body = colander.SchemaNode( + colander.String(), + widget=deform.widget.RichTextWidget() + ) + +With this in place, we can render the HTML for a form, +perhaps with form data from an existing page: + +.. code-block:: python + + form = self.wiki_form.render() + +We'd like to handle form submission, validation, and saving: + +.. code-block:: python + + # Get the form data that was posted + controls = self.request.POST.items() + try: + # Validate and either raise a validation error + # or return deserialized data from widgets + appstruct = wiki_form.validate(controls) + except deform.ValidationFailure as e: + # Bail out and render form with errors + return dict(title=title, page=page, form=e.render()) + + # Change the content and redirect to the view + 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. + +Also, the ``deform_bootstrap`` Pyramid add-on restyles the stock Deform +widgets using attractive CSS from 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>`_ + +Conclusion +========== + +This *Quick Tour* covered a little about a lot. We introduced a long list +of concepts in Pyramid, many of which are expanded on more fully in the +Pyramid developer docs. diff --git a/docs/quick_tour/awesome/CHANGES.txt b/docs/quick_tour/awesome/CHANGES.txt new file mode 100644 index 000000000..ffa255da8 --- /dev/null +++ b/docs/quick_tour/awesome/CHANGES.txt @@ -0,0 +1,4 @@ +0.0 +--- + +- Initial version diff --git a/docs/quick_tour/awesome/MANIFEST.in b/docs/quick_tour/awesome/MANIFEST.in new file mode 100644 index 000000000..e78395da8 --- /dev/null +++ b/docs/quick_tour/awesome/MANIFEST.in @@ -0,0 +1,2 @@ +include *.txt *.ini *.cfg *.rst +recursive-include awesome *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml diff --git a/docs/quick_tour/awesome/README.txt b/docs/quick_tour/awesome/README.txt new file mode 100644 index 000000000..f695286d9 --- /dev/null +++ b/docs/quick_tour/awesome/README.txt @@ -0,0 +1,4 @@ +awesome README + + + diff --git a/docs/quick_tour/awesome/awesome/__init__.py b/docs/quick_tour/awesome/awesome/__init__.py new file mode 100644 index 000000000..408033997 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/__init__.py @@ -0,0 +1,23 @@ +from pyramid.config import Configurator +from pyramid_jinja2 import renderer_factory +from awesome.models import get_root + +def main(global_config, **settings): + """ This function returns a WSGI application. + + It is usually called by the PasteDeploy framework during + ``paster serve``. + """ + settings = dict(settings) + settings.setdefault('jinja2.i18n.domain', 'awesome') + + config = Configurator(root_factory=get_root, settings=settings) + config.add_translation_dirs('locale/') + config.include('pyramid_jinja2') + + config.add_static_view('static', 'static') + config.add_view('awesome.views.my_view', + context='awesome.models.MyModel', + renderer="mytemplate.jinja2") + + return config.make_wsgi_app() diff --git a/docs/quick_tour/awesome/awesome/locale/awesome.pot b/docs/quick_tour/awesome/awesome/locale/awesome.pot new file mode 100644 index 000000000..9c9460cb2 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/locale/awesome.pot @@ -0,0 +1,21 @@ +# Translations template for PROJECT. +# Copyright (C) 2011 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2011. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2011-05-12 09:14-0330\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.6\n" + +msgid "Hello!" +msgstr "" diff --git a/docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.mo b/docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.mo Binary files differnew file mode 100644 index 000000000..40bf0c271 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.mo diff --git a/docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.po b/docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.po new file mode 100644 index 000000000..0df243dba --- /dev/null +++ b/docs/quick_tour/awesome/awesome/locale/de/LC_MESSAGES/awesome.po @@ -0,0 +1,21 @@ +# Translations template for PROJECT. +# Copyright (C) 2011 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2011. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2011-05-12 09:14-0330\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.6\n" + +msgid "Hello!" +msgstr "Hallo!" diff --git a/docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.mo b/docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.mo Binary files differnew file mode 100644 index 000000000..4fc438bfe --- /dev/null +++ b/docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.mo diff --git a/docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.po b/docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.po new file mode 100644 index 000000000..dc0aae5d7 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/locale/fr/LC_MESSAGES/awesome.po @@ -0,0 +1,21 @@ +# Translations template for PROJECT. +# Copyright (C) 2011 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2011. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2011-05-12 09:14-0330\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.6\n" + +msgid "Hello!" +msgstr "Bonjour!" diff --git a/docs/quick_tour/awesome/awesome/models.py b/docs/quick_tour/awesome/awesome/models.py new file mode 100644 index 000000000..edd361c9c --- /dev/null +++ b/docs/quick_tour/awesome/awesome/models.py @@ -0,0 +1,8 @@ +class MyModel(object): + pass + +root = MyModel() + + +def get_root(request): + return root diff --git a/docs/quick_tour/awesome/awesome/static/favicon.ico b/docs/quick_tour/awesome/awesome/static/favicon.ico Binary files differnew file mode 100644 index 000000000..71f837c9e --- /dev/null +++ b/docs/quick_tour/awesome/awesome/static/favicon.ico diff --git a/docs/quick_tour/awesome/awesome/static/logo.png b/docs/quick_tour/awesome/awesome/static/logo.png Binary files differnew file mode 100644 index 000000000..88f5d9865 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/static/logo.png diff --git a/docs/quick_tour/awesome/awesome/static/pylons.css b/docs/quick_tour/awesome/awesome/static/pylons.css new file mode 100644 index 000000000..42e2e320e --- /dev/null +++ b/docs/quick_tour/awesome/awesome/static/pylons.css @@ -0,0 +1,73 @@ +html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */ +vertical-align:baseline;background:transparent;} +body{line-height:1;} +ol,ul{list-style:none;} +blockquote,q{quotes:none;} +blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;} +/* remember to define focus styles! */ +:focus{outline:0;} +/* remember to highlight inserts somehow! */ +ins{text-decoration:none;} +del{text-decoration:line-through;} +/* tables still need 'cellspacing="0"' in the markup */ +table{border-collapse:collapse;border-spacing:0;} +/* restyling */ +sub{vertical-align:sub;font-size:smaller;line-height:normal;} +sup{vertical-align:super;font-size:smaller;line-height:normal;} +/* lists */ +ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;} +ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;} +li{display:list-item;} +/* nested lists have no top/bottom margins */ +ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;} +/* 2 deep unordered lists use a circle */ +ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;} +/* 3 deep (or more) unordered lists use a square */ +ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;} +.hidden{display:none;} +p{line-height:1.5em;} +h1{font-size:1.75em;/* 28px */ +line-height:1.7em;font-family:helvetica,verdana;} +h2{font-size:1.5em;/* 24px */ +line-height:1.7em;font-family:helvetica,verdana;} +h3{font-size:1.25em;/* 20px */ +line-height:1.7em;font-family:helvetica,verdana;} +h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;} +html,body{width:100%;height:100%;} +body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;} +a{color:#1b61d6;text-decoration:none;} +a:hover{color:#e88f00;text-decoration:underline;} +body h1, +body h2, +body h3, +body h4, +body h5, +body h6{font-family:"Nobile","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#144fb2;font-style:normal;} +#wrap {min-height: 100%;} +#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;} +#header{background-color:#e88f00;top:0;font-size:14px;} +#footer{background-color:#000000;bottom:0;position: relative;margin-top:-40px;clear:both;} +.header,.footer{width:700px;margin-right:auto;margin-left:auto;} +.wrapper{width:100%} +#top,#bottom{width:100%;} +#top{color:#888;background-color:#eee;height:300px;border-bottom:2px solid #ddd;} +#bottom{color:#222;background-color:#ffffff;overflow:auto;padding-bottom:80px;} +.top,.bottom{width:700px;margin-right:auto;margin-left:auto;} +.top{padding-top:100px;} +.app-welcome{margin-top:25px;} +.app-name{color:#000000;font-weight:bold;} +.bottom{padding-top:50px;} +#left{width:325px;float:left;padding-right:25px;} +#right{width:325px;float:right;padding-left:25px;} +.align-left{text-align:left;} +.align-right{text-align:right;} +.align-center{text-align:center;} +ul.links{margin:0;padding:0;} +ul.links li{list-style-type:none;font-size:14px;} +form{border-style:none;} +fieldset{border-style:none;} +input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;} +input[type=text]{} +input[type=submit]{background-color:#ddd;font-weight:bold;} +/*Opera Fix*/ +body:before {content:"";height:100%;float:left;width:0;margin-top:-32767px;} diff --git a/docs/quick_tour/awesome/awesome/templates/mytemplate.jinja2 b/docs/quick_tour/awesome/awesome/templates/mytemplate.jinja2 new file mode 100644 index 000000000..8bf676041 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/templates/mytemplate.jinja2 @@ -0,0 +1,87 @@ +<!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> + <p>Request performed with <span class="locale-name">{{ request.locale_name }}</span> locale.</p> + </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> +</html> diff --git a/docs/quick_tour/awesome/awesome/tests.py b/docs/quick_tour/awesome/awesome/tests.py new file mode 100644 index 000000000..ac222e25b --- /dev/null +++ b/docs/quick_tour/awesome/awesome/tests.py @@ -0,0 +1,21 @@ +import unittest +from pyramid import testing +from pyramid.i18n import TranslationStringFactory + +_ = TranslationStringFactory('awesome') + + +class ViewTests(unittest.TestCase): + + def setUp(self): + testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_my_view(self): + from awesome.views import my_view + request = testing.DummyRequest() + response = my_view(request) + self.assertEqual(response['project'], 'awesome') + diff --git a/docs/quick_tour/awesome/awesome/views.py b/docs/quick_tour/awesome/awesome/views.py new file mode 100644 index 000000000..67b282f87 --- /dev/null +++ b/docs/quick_tour/awesome/awesome/views.py @@ -0,0 +1,6 @@ +from pyramid.i18n import TranslationStringFactory + +_ = TranslationStringFactory('awesome') + +def my_view(request): + return {'project':'awesome'} diff --git a/docs/quick_tour/awesome/development.ini b/docs/quick_tour/awesome/development.ini new file mode 100644 index 000000000..a473d32f1 --- /dev/null +++ b/docs/quick_tour/awesome/development.ini @@ -0,0 +1,49 @@ +[app:awesome] +use = egg:awesome +reload_templates = true +debug_authorization = false +debug_notfound = false +debug_routematch = false +debug_templates = true +default_locale_name = en +jinja2.directories = awesome:templates + +[pipeline:main] +pipeline = + awesome + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, awesome + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[logger_awesome] +level = DEBUG +handlers = +qualname = awesome + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tour/awesome/message-extraction.ini b/docs/quick_tour/awesome/message-extraction.ini new file mode 100644 index 000000000..0c3d54bc1 --- /dev/null +++ b/docs/quick_tour/awesome/message-extraction.ini @@ -0,0 +1,3 @@ +[python: **.py] +[jinja2: **.jinja2] +encoding = utf-8 diff --git a/docs/quick_tour/awesome/setup.cfg b/docs/quick_tour/awesome/setup.cfg new file mode 100644 index 000000000..b1cd90d2c --- /dev/null +++ b/docs/quick_tour/awesome/setup.cfg @@ -0,0 +1,28 @@ +[nosetests] +match = ^test +nocapture = 1 +cover-package = awesome +with-coverage = 1 +cover-erase = 1 + +[compile_catalog] +directory = awesome/locale +domain = awesome +statistics = true + +[extract_messages] +add_comments = TRANSLATORS: +output_file = awesome/locale/awesome.pot +width = 80 +mapping_file = message-extraction.ini + +[init_catalog] +domain = awesome +input_file = awesome/locale/awesome.pot +output_dir = awesome/locale + +[update_catalog] +domain = awesome +input_file = awesome/locale/awesome.pot +output_dir = awesome/locale +previous = true diff --git a/docs/quick_tour/awesome/setup.py b/docs/quick_tour/awesome/setup.py new file mode 100644 index 000000000..32d666317 --- /dev/null +++ b/docs/quick_tour/awesome/setup.py @@ -0,0 +1,36 @@ +import os + +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() + +requires=['pyramid>=1.0.2', 'pyramid_jinja2'] + +setup(name='awesome', + version='0.0', + description='awesome', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Programming Language :: Python", + "Framework :: Pylons", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web pyramid pylons', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + install_requires=requires, + tests_require=requires, + test_suite="awesome", + entry_points = """\ + [paste.app_factory] + main = awesome:main + """, + paster_plugins=['pyramid'], + ) diff --git a/docs/quick_tour/hello_world/app.py b/docs/quick_tour/hello_world/app.py new file mode 100644 index 000000000..df5a6cf18 --- /dev/null +++ b/docs/quick_tour/hello_world/app.py @@ -0,0 +1,16 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + return Response('<h1>Hello World!</h1>') + + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/') + 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()
\ No newline at end of file diff --git a/docs/quick_tour/jinja2/app.py b/docs/quick_tour/jinja2/app.py new file mode 100644 index 000000000..83af219db --- /dev/null +++ b/docs/quick_tour/jinja2/app.py @@ -0,0 +1,11 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/howdy/{name}') + config.include('pyramid_jinja2') + config.scan('views') + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 6543, app) + server.serve_forever()
\ No newline at end of file diff --git a/docs/quick_tour/jinja2/hello_world.jinja2 b/docs/quick_tour/jinja2/hello_world.jinja2 new file mode 100644 index 000000000..7a902dd3a --- /dev/null +++ b/docs/quick_tour/jinja2/hello_world.jinja2 @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Hello World</title> +</head> +<body> +<h1>Hello {{ name }}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/jinja2/views.py b/docs/quick_tour/jinja2/views.py new file mode 100644 index 000000000..916cdc720 --- /dev/null +++ b/docs/quick_tour/jinja2/views.py @@ -0,0 +1,8 @@ +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']) diff --git a/docs/quick_tour/json/app.py b/docs/quick_tour/json/app.py new file mode 100644 index 000000000..950cb478f --- /dev/null +++ b/docs/quick_tour/json/app.py @@ -0,0 +1,15 @@ +from wsgiref.simple_server import make_server + +from pyramid.config import Configurator + + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/howdy/{name}') + 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()
\ No newline at end of file diff --git a/docs/quick_tour/json/hello_world.jinja2 b/docs/quick_tour/json/hello_world.jinja2 new file mode 100644 index 000000000..f6862e618 --- /dev/null +++ b/docs/quick_tour/json/hello_world.jinja2 @@ -0,0 +1,10 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Glance</title> + <link rel="stylesheet" href="/static/app.css"/> +</head> +<body> +<h1>Hello {{ name }}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/json/hello_world.pt b/docs/quick_tour/json/hello_world.pt new file mode 100644 index 000000000..711054aa9 --- /dev/null +++ b/docs/quick_tour/json/hello_world.pt @@ -0,0 +1,17 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Glance</title> + <!-- Start Link 1 --> + <link rel="stylesheet" href="/static/app.css" /> + <!-- End Link 1 --> + <!-- Start Link 2 --> + <link rel="stylesheet" + href="${request.static_url('static/app.css')}" + /> + <!-- End Link 2 --> +</head> +<body> +<h1>Hello ${name}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/json/views.py b/docs/quick_tour/json/views.py new file mode 100644 index 000000000..583e220c7 --- /dev/null +++ b/docs/quick_tour/json/views.py @@ -0,0 +1,13 @@ +from pyramid.view import view_config + + +@view_config(route_name='hello', renderer='hello_world.pt') +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
\ No newline at end of file diff --git a/docs/quick_tour/package/CHANGES.txt b/docs/quick_tour/package/CHANGES.txt new file mode 100644 index 000000000..ffa255da8 --- /dev/null +++ b/docs/quick_tour/package/CHANGES.txt @@ -0,0 +1,4 @@ +0.0 +--- + +- Initial version diff --git a/docs/quick_tour/package/MANIFEST.in b/docs/quick_tour/package/MANIFEST.in new file mode 100644 index 000000000..18fbd855c --- /dev/null +++ b/docs/quick_tour/package/MANIFEST.in @@ -0,0 +1,2 @@ +include *.txt *.ini *.cfg *.rst +recursive-include hello_world *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml diff --git a/docs/quick_tour/package/README.txt b/docs/quick_tour/package/README.txt new file mode 100644 index 000000000..63aaf6fbd --- /dev/null +++ b/docs/quick_tour/package/README.txt @@ -0,0 +1,4 @@ +hello_world README + + + diff --git a/docs/quick_tour/package/development.ini b/docs/quick_tour/package/development.ini new file mode 100644 index 000000000..a3a73e885 --- /dev/null +++ b/docs/quick_tour/package/development.ini @@ -0,0 +1,54 @@ +# 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 + +[pipeline:main] +pipeline = + hello_world + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +# Start Sphinx Include +[loggers] +keys = root, hello_world + +[logger_hello_world] +level = DEBUG +handlers = +qualname = hello_world +# End Sphinx Include + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tour/package/hello_world/__init__.py b/docs/quick_tour/package/hello_world/__init__.py new file mode 100644 index 000000000..6e66bf40a --- /dev/null +++ b/docs/quick_tour/package/hello_world/__init__.py @@ -0,0 +1,34 @@ +from pyramid.config import Configurator +from pyramid_jinja2 import renderer_factory +# Start Sphinx Include 1 +from pyramid.session import UnencryptedCookieSessionFactoryConfig +# End Sphinx Include 1 + +from hello_world.models import get_root + +def main(global_config, **settings): + """ This function returns a WSGI application. + + It is usually called by the PasteDeploy framework during + ``paster serve``. + """ + settings = dict(settings) + settings.setdefault('jinja2.i18n.domain', 'hello_world') + + # Start Sphinx Include 2 + my_session_factory = UnencryptedCookieSessionFactoryConfig('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") + + return config.make_wsgi_app() diff --git a/docs/quick_tour/package/hello_world/init.py b/docs/quick_tour/package/hello_world/init.py new file mode 100644 index 000000000..9d7ec43d8 --- /dev/null +++ b/docs/quick_tour/package/hello_world/init.py @@ -0,0 +1,34 @@ +from pyramid.config import Configurator +from pyramid_jinja2 import renderer_factory +# Start Sphinx 1 +from pyramid.session import UnencryptedCookieSessionFactoryConfig +# End Sphinx 1 + +from hello_world.models import get_root + +def main(global_config, **settings): + """ This function returns a WSGI application. + + It is usually called by the PasteDeploy framework during + ``paster serve``. + """ + settings = dict(settings) + settings.setdefault('jinja2.i18n.domain', 'hello_world') + + config = Configurator(root_factory=get_root, settings=settings) + config.add_translation_dirs('locale/') + # Start Include + config.include('pyramid_jinja2') + # End Include + + # Start Sphinx Include 2 + my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet') + config = Configurator(session_factory=my_session_factory) + # End Sphinx Include 2 + + config.add_static_view('static', 'static') + config.add_view('hello_world.views.my_view', + context='hello_world.models.MyModel', + renderer="mytemplate.jinja2") + + return config.make_wsgi_app() diff --git a/docs/quick_tour/package/hello_world/locale/de/LC_MESSAGES/hello_world.mo b/docs/quick_tour/package/hello_world/locale/de/LC_MESSAGES/hello_world.mo Binary files differnew file mode 100644 index 000000000..40bf0c271 --- /dev/null +++ b/docs/quick_tour/package/hello_world/locale/de/LC_MESSAGES/hello_world.mo diff --git a/docs/quick_tour/package/hello_world/locale/de/LC_MESSAGES/hello_world.po b/docs/quick_tour/package/hello_world/locale/de/LC_MESSAGES/hello_world.po new file mode 100644 index 000000000..0df243dba --- /dev/null +++ b/docs/quick_tour/package/hello_world/locale/de/LC_MESSAGES/hello_world.po @@ -0,0 +1,21 @@ +# Translations template for PROJECT. +# Copyright (C) 2011 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2011. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2011-05-12 09:14-0330\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.6\n" + +msgid "Hello!" +msgstr "Hallo!" diff --git a/docs/quick_tour/package/hello_world/locale/fr/LC_MESSAGES/hello_world.mo b/docs/quick_tour/package/hello_world/locale/fr/LC_MESSAGES/hello_world.mo Binary files differnew file mode 100644 index 000000000..4fc438bfe --- /dev/null +++ b/docs/quick_tour/package/hello_world/locale/fr/LC_MESSAGES/hello_world.mo diff --git a/docs/quick_tour/package/hello_world/locale/fr/LC_MESSAGES/hello_world.po b/docs/quick_tour/package/hello_world/locale/fr/LC_MESSAGES/hello_world.po new file mode 100644 index 000000000..dc0aae5d7 --- /dev/null +++ b/docs/quick_tour/package/hello_world/locale/fr/LC_MESSAGES/hello_world.po @@ -0,0 +1,21 @@ +# Translations template for PROJECT. +# Copyright (C) 2011 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2011. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2011-05-12 09:14-0330\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.6\n" + +msgid "Hello!" +msgstr "Bonjour!" diff --git a/docs/quick_tour/package/hello_world/locale/hello_world.pot b/docs/quick_tour/package/hello_world/locale/hello_world.pot new file mode 100644 index 000000000..9c9460cb2 --- /dev/null +++ b/docs/quick_tour/package/hello_world/locale/hello_world.pot @@ -0,0 +1,21 @@ +# Translations template for PROJECT. +# Copyright (C) 2011 ORGANIZATION +# This file is distributed under the same license as the PROJECT project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2011. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: PROJECT VERSION\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2011-05-12 09:14-0330\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: LANGUAGE <LL@li.org>\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.6\n" + +msgid "Hello!" +msgstr "" diff --git a/docs/quick_tour/package/hello_world/models.py b/docs/quick_tour/package/hello_world/models.py new file mode 100644 index 000000000..edd361c9c --- /dev/null +++ b/docs/quick_tour/package/hello_world/models.py @@ -0,0 +1,8 @@ +class MyModel(object): + pass + +root = MyModel() + + +def get_root(request): + return root diff --git a/docs/quick_tour/package/hello_world/static/favicon.ico b/docs/quick_tour/package/hello_world/static/favicon.ico Binary files differnew file mode 100644 index 000000000..71f837c9e --- /dev/null +++ b/docs/quick_tour/package/hello_world/static/favicon.ico diff --git a/docs/quick_tour/package/hello_world/static/logo.png b/docs/quick_tour/package/hello_world/static/logo.png Binary files differnew file mode 100644 index 000000000..88f5d9865 --- /dev/null +++ b/docs/quick_tour/package/hello_world/static/logo.png diff --git a/docs/quick_tour/package/hello_world/static/pylons.css b/docs/quick_tour/package/hello_world/static/pylons.css new file mode 100644 index 000000000..42e2e320e --- /dev/null +++ b/docs/quick_tour/package/hello_world/static/pylons.css @@ -0,0 +1,73 @@ +html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,sub,sup,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;/* 16px */ +vertical-align:baseline;background:transparent;} +body{line-height:1;} +ol,ul{list-style:none;} +blockquote,q{quotes:none;} +blockquote:before,blockquote:after,q:before,q:after{content:'';content:none;} +/* remember to define focus styles! */ +:focus{outline:0;} +/* remember to highlight inserts somehow! */ +ins{text-decoration:none;} +del{text-decoration:line-through;} +/* tables still need 'cellspacing="0"' in the markup */ +table{border-collapse:collapse;border-spacing:0;} +/* restyling */ +sub{vertical-align:sub;font-size:smaller;line-height:normal;} +sup{vertical-align:super;font-size:smaller;line-height:normal;} +/* lists */ +ul,menu,dir{display:block;list-style-type:disc;margin:1em 0;padding-left:40px;} +ol{display:block;list-style-type:decimal-leading-zero;margin:1em 0;padding-left:40px;} +li{display:list-item;} +/* nested lists have no top/bottom margins */ +ul ul,ul ol,ul dir,ul menu,ul dl,ol ul,ol ol,ol dir,ol menu,ol dl,dir ul,dir ol,dir dir,dir menu,dir dl,menu ul,menu ol,menu dir,menu menu,menu dl,dl ul,dl ol,dl dir,dl menu,dl dl{margin-top:0;margin-bottom:0;} +/* 2 deep unordered lists use a circle */ +ol ul,ul ul,menu ul,dir ul,ol menu,ul menu,menu menu,dir menu,ol dir,ul dir,menu dir,dir dir{list-style-type:circle;} +/* 3 deep (or more) unordered lists use a square */ +ol ol ul,ol ul ul,ol menu ul,ol dir ul,ol ol menu,ol ul menu,ol menu menu,ol dir menu,ol ol dir,ol ul dir,ol menu dir,ol dir dir,ul ol ul,ul ul ul,ul menu ul,ul dir ul,ul ol menu,ul ul menu,ul menu menu,ul dir menu,ul ol dir,ul ul dir,ul menu dir,ul dir dir,menu ol ul,menu ul ul,menu menu ul,menu dir ul,menu ol menu,menu ul menu,menu menu menu,menu dir menu,menu ol dir,menu ul dir,menu menu dir,menu dir dir,dir ol ul,dir ul ul,dir menu ul,dir dir ul,dir ol menu,dir ul menu,dir menu menu,dir dir menu,dir ol dir,dir ul dir,dir menu dir,dir dir dir{list-style-type:square;} +.hidden{display:none;} +p{line-height:1.5em;} +h1{font-size:1.75em;/* 28px */ +line-height:1.7em;font-family:helvetica,verdana;} +h2{font-size:1.5em;/* 24px */ +line-height:1.7em;font-family:helvetica,verdana;} +h3{font-size:1.25em;/* 20px */ +line-height:1.7em;font-family:helvetica,verdana;} +h4{font-size:1em;line-height:1.7em;font-family:helvetica,verdana;} +html,body{width:100%;height:100%;} +body{margin:0;padding:0;background-color:#ffffff;position:relative;font:16px/24px "Nobile","Lucida Grande",Lucida,Verdana,sans-serif;} +a{color:#1b61d6;text-decoration:none;} +a:hover{color:#e88f00;text-decoration:underline;} +body h1, +body h2, +body h3, +body h4, +body h5, +body h6{font-family:"Nobile","Lucida Grande",Lucida,Verdana,sans-serif;font-weight:normal;color:#144fb2;font-style:normal;} +#wrap {min-height: 100%;} +#header,#footer{width:100%;color:#ffffff;height:40px;position:absolute;text-align:center;line-height:40px;overflow:hidden;font-size:12px;} +#header{background-color:#e88f00;top:0;font-size:14px;} +#footer{background-color:#000000;bottom:0;position: relative;margin-top:-40px;clear:both;} +.header,.footer{width:700px;margin-right:auto;margin-left:auto;} +.wrapper{width:100%} +#top,#bottom{width:100%;} +#top{color:#888;background-color:#eee;height:300px;border-bottom:2px solid #ddd;} +#bottom{color:#222;background-color:#ffffff;overflow:auto;padding-bottom:80px;} +.top,.bottom{width:700px;margin-right:auto;margin-left:auto;} +.top{padding-top:100px;} +.app-welcome{margin-top:25px;} +.app-name{color:#000000;font-weight:bold;} +.bottom{padding-top:50px;} +#left{width:325px;float:left;padding-right:25px;} +#right{width:325px;float:right;padding-left:25px;} +.align-left{text-align:left;} +.align-right{text-align:right;} +.align-center{text-align:center;} +ul.links{margin:0;padding:0;} +ul.links li{list-style-type:none;font-size:14px;} +form{border-style:none;} +fieldset{border-style:none;} +input{color:#222;border:1px solid #ccc;font-family:sans-serif;font-size:12px;line-height:16px;} +input[type=text]{} +input[type=submit]{background-color:#ddd;font-weight:bold;} +/*Opera Fix*/ +body:before {content:"";height:100%;float:left;width:0;margin-top:-32767px;} diff --git a/docs/quick_tour/package/hello_world/templates/mytemplate.jinja2 b/docs/quick_tour/package/hello_world/templates/mytemplate.jinja2 new file mode 100644 index 000000000..25a28ed7a --- /dev/null +++ b/docs/quick_tour/package/hello_world/templates/mytemplate.jinja2 @@ -0,0 +1,90 @@ +<!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> + </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> +</html> diff --git a/docs/quick_tour/package/hello_world/tests.py b/docs/quick_tour/package/hello_world/tests.py new file mode 100644 index 000000000..ccec14f70 --- /dev/null +++ b/docs/quick_tour/package/hello_world/tests.py @@ -0,0 +1,20 @@ +import unittest +from pyramid import testing +from pyramid.i18n import TranslationStringFactory + +_ = TranslationStringFactory('hello_world') + + +class ViewTests(unittest.TestCase): + + def setUp(self): + testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_my_view(self): + from hello_world.views import my_view + request = testing.DummyRequest() + response = my_view(request) + self.assertEqual(response['project'], 'hello_world') diff --git a/docs/quick_tour/package/hello_world/views.py b/docs/quick_tour/package/hello_world/views.py new file mode 100644 index 000000000..109c260ad --- /dev/null +++ b/docs/quick_tour/package/hello_world/views.py @@ -0,0 +1,22 @@ +# Start Logging 1 +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'} diff --git a/docs/quick_tour/package/message-extraction.ini b/docs/quick_tour/package/message-extraction.ini new file mode 100644 index 000000000..0c3d54bc1 --- /dev/null +++ b/docs/quick_tour/package/message-extraction.ini @@ -0,0 +1,3 @@ +[python: **.py] +[jinja2: **.jinja2] +encoding = utf-8 diff --git a/docs/quick_tour/package/setup.cfg b/docs/quick_tour/package/setup.cfg new file mode 100644 index 000000000..186e796fc --- /dev/null +++ b/docs/quick_tour/package/setup.cfg @@ -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 diff --git a/docs/quick_tour/package/setup.py b/docs/quick_tour/package/setup.py new file mode 100644 index 000000000..f118ed5fb --- /dev/null +++ b/docs/quick_tour/package/setup.py @@ -0,0 +1,41 @@ +import os + +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() + +# Start Requires +requires = ['pyramid>=1.0.2', 'pyramid_jinja2', 'pyramid_debugtoolbar'] +# End Requires + +setup(name='hello_world', + version='0.0', + description='hello_world', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Programming Language :: Python", + "Framework :: Pylons", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web pyramid pylons', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + install_requires=requires, + tests_require=requires, + test_suite="hello_world", + entry_points="""\ + [paste.app_factory] + main = hello_world:main + """, + paster_plugins=['pyramid'], + extras_require={ + 'testing': ['nose', ], + } +)
\ No newline at end of file diff --git a/docs/quick_tour/requests/app.py b/docs/quick_tour/requests/app.py new file mode 100644 index 000000000..7ac81eb50 --- /dev/null +++ b/docs/quick_tour/requests/app.py @@ -0,0 +1,24 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + # Some parameters from a request such as /?name=lisa + url = request.url + name = request.params.get('name', 'No Name Provided') + + body = 'URL %s with name: %s' % (url, name) + return Response( + content_type="text/plain", + body=body + ) + + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/') + 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()
\ No newline at end of file diff --git a/docs/quick_tour/routing/app.py b/docs/quick_tour/routing/app.py new file mode 100644 index 000000000..04a8a6344 --- /dev/null +++ b/docs/quick_tour/routing/app.py @@ -0,0 +1,12 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator + +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) + server.serve_forever()
\ No newline at end of file diff --git a/docs/quick_tour/routing/views.py b/docs/quick_tour/routing/views.py new file mode 100644 index 000000000..8cb8d3780 --- /dev/null +++ b/docs/quick_tour/routing/views.py @@ -0,0 +1,10 @@ +from pyramid.response import Response +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
\ No newline at end of file diff --git a/docs/quick_tour/sqla_demo/CHANGES.txt b/docs/quick_tour/sqla_demo/CHANGES.txt new file mode 100644 index 000000000..35a34f332 --- /dev/null +++ b/docs/quick_tour/sqla_demo/CHANGES.txt @@ -0,0 +1,4 @@ +0.0 +--- + +- Initial version diff --git a/docs/quick_tour/sqla_demo/MANIFEST.in b/docs/quick_tour/sqla_demo/MANIFEST.in new file mode 100644 index 000000000..a432577e9 --- /dev/null +++ b/docs/quick_tour/sqla_demo/MANIFEST.in @@ -0,0 +1,2 @@ +include *.txt *.ini *.cfg *.rst +recursive-include sqla_demo *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml diff --git a/docs/quick_tour/sqla_demo/README.txt b/docs/quick_tour/sqla_demo/README.txt new file mode 100644 index 000000000..f35d3aec5 --- /dev/null +++ b/docs/quick_tour/sqla_demo/README.txt @@ -0,0 +1,14 @@ +sqla_demo README +================== + +Getting Started +--------------- + +- cd <directory containing this file> + +- $venv/bin/python setup.py develop + +- $venv/bin/initialize_sqla_demo_db development.ini + +- $venv/bin/pserve development.ini + diff --git a/docs/quick_tour/sqla_demo/development.ini b/docs/quick_tour/sqla_demo/development.ini new file mode 100644 index 000000000..174468abf --- /dev/null +++ b/docs/quick_tour/sqla_demo/development.ini @@ -0,0 +1,71 @@ +### +# app configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html +### + +[app:main] +use = egg:sqla_demo + +pyramid.reload_templates = true +pyramid.debug_authorization = false +pyramid.debug_notfound = false +pyramid.debug_routematch = false +pyramid.default_locale_name = en +pyramid.includes = + pyramid_debugtoolbar + pyramid_tm + +sqlalchemy.url = sqlite:///%(here)s/sqla_demo.sqlite + +# 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:waitress#main +host = 0.0.0.0 +port = 6543 + +### +# logging configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html +### + +[loggers] +keys = root, sqla_demo, sqlalchemy + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[logger_sqla_demo] +level = DEBUG +handlers = +qualname = sqla_demo + +[logger_sqlalchemy] +level = INFO +handlers = +qualname = sqlalchemy.engine +# "level = INFO" logs SQL queries. +# "level = DEBUG" logs SQL queries and results. +# "level = WARN" logs neither. (Recommended for production systems.) + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s diff --git a/docs/quick_tour/sqla_demo/production.ini b/docs/quick_tour/sqla_demo/production.ini new file mode 100644 index 000000000..dc0ba304f --- /dev/null +++ b/docs/quick_tour/sqla_demo/production.ini @@ -0,0 +1,62 @@ +### +# app configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html +### + +[app:main] +use = egg:sqla_demo + +pyramid.reload_templates = false +pyramid.debug_authorization = false +pyramid.debug_notfound = false +pyramid.debug_routematch = false +pyramid.default_locale_name = en +pyramid.includes = + pyramid_tm + +sqlalchemy.url = sqlite:///%(here)s/sqla_demo.sqlite + +[server:main] +use = egg:waitress#main +host = 0.0.0.0 +port = 6543 + +### +# logging configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html +### + +[loggers] +keys = root, sqla_demo, sqlalchemy + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARN +handlers = console + +[logger_sqla_demo] +level = WARN +handlers = +qualname = sqla_demo + +[logger_sqlalchemy] +level = WARN +handlers = +qualname = sqlalchemy.engine +# "level = INFO" logs SQL queries. +# "level = DEBUG" logs SQL queries and results. +# "level = WARN" logs neither. (Recommended for production systems.) + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s diff --git a/docs/quick_tour/sqla_demo/setup.cfg b/docs/quick_tour/sqla_demo/setup.cfg new file mode 100644 index 000000000..9f91cd122 --- /dev/null +++ b/docs/quick_tour/sqla_demo/setup.cfg @@ -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 diff --git a/docs/quick_tour/sqla_demo/setup.py b/docs/quick_tour/sqla_demo/setup.py new file mode 100644 index 000000000..ac2eed035 --- /dev/null +++ b/docs/quick_tour/sqla_demo/setup.py @@ -0,0 +1,44 @@ +import os + +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() + +requires = [ + 'pyramid', + 'SQLAlchemy', + 'transaction', + 'pyramid_tm', + 'pyramid_debugtoolbar', + 'zope.sqlalchemy', + 'waitress', + ] + +setup(name='sqla_demo', + version='0.0', + description='sqla_demo', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Programming Language :: Python", + "Framework :: Pyramid", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web wsgi bfg pylons pyramid', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + test_suite='sqla_demo', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = sqla_demo:main + [console_scripts] + initialize_sqla_demo_db = sqla_demo.scripts.initializedb:main + """, + ) diff --git a/docs/quick_tour/sqla_demo/sqla_demo.sqlite b/docs/quick_tour/sqla_demo/sqla_demo.sqlite Binary files differnew file mode 100644 index 000000000..fa6adb104 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo.sqlite diff --git a/docs/quick_tour/sqla_demo/sqla_demo/__init__.py b/docs/quick_tour/sqla_demo/sqla_demo/__init__.py new file mode 100644 index 000000000..aac7c5e69 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/__init__.py @@ -0,0 +1,20 @@ +from pyramid.config import Configurator +from sqlalchemy import engine_from_config + +from .models import ( + DBSession, + Base, + ) + + +def main(global_config, **settings): + """ This function returns a Pyramid WSGI application. + """ + engine = engine_from_config(settings, 'sqlalchemy.') + DBSession.configure(bind=engine) + Base.metadata.bind = engine + config = Configurator(settings=settings) + config.add_static_view('static', 'static', cache_max_age=3600) + config.add_route('home', '/') + config.scan() + return config.make_wsgi_app() diff --git a/docs/quick_tour/sqla_demo/sqla_demo/models.py b/docs/quick_tour/sqla_demo/sqla_demo/models.py new file mode 100644 index 000000000..3dfb40e58 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/models.py @@ -0,0 +1,29 @@ +from sqlalchemy import ( + Column, + Integer, + Text, + ) + +from sqlalchemy.ext.declarative import declarative_base + +from sqlalchemy.orm import ( + scoped_session, + sessionmaker, + ) + +from zope.sqlalchemy import ZopeTransactionExtension + +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) + value = Column(Integer) + + def __init__(self, name, value): + self.name = name + self.value = value + # End Sphinx Include diff --git a/pyramid/fixers/__init__.py b/docs/quick_tour/sqla_demo/sqla_demo/scripts/__init__.py index 5bb534f79..5bb534f79 100644 --- a/pyramid/fixers/__init__.py +++ b/docs/quick_tour/sqla_demo/sqla_demo/scripts/__init__.py diff --git a/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py b/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py new file mode 100644 index 000000000..66feb3008 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/scripts/initializedb.py @@ -0,0 +1,37 @@ +import os +import sys +import transaction + +from sqlalchemy import engine_from_config + +from pyramid.paster import ( + get_appsettings, + setup_logging, + ) + +from ..models import ( + DBSession, + MyModel, + Base, + ) + + +def usage(argv): + cmd = os.path.basename(argv[0]) + print('usage: %s <config_uri>\n' + '(example: "%s development.ini")' % (cmd, cmd)) + sys.exit(1) + + +def main(argv=sys.argv): + if len(argv) != 2: + usage(argv) + config_uri = argv[1] + setup_logging(config_uri) + settings = get_appsettings(config_uri) + engine = engine_from_config(settings, 'sqlalchemy.') + DBSession.configure(bind=engine) + Base.metadata.create_all(engine) + with transaction.manager: + model = MyModel(name='one', value=1) + DBSession.add(model) diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/favicon.ico b/docs/quick_tour/sqla_demo/sqla_demo/static/favicon.ico Binary files differnew file mode 100644 index 000000000..71f837c9e --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/favicon.ico diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/footerbg.png b/docs/quick_tour/sqla_demo/sqla_demo/static/footerbg.png Binary files differnew file mode 100644 index 000000000..1fbc873da --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/footerbg.png diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/headerbg.png b/docs/quick_tour/sqla_demo/sqla_demo/static/headerbg.png Binary files differnew file mode 100644 index 000000000..0596f2020 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/headerbg.png diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/ie6.css b/docs/quick_tour/sqla_demo/sqla_demo/static/ie6.css new file mode 100644 index 000000000..b7c8493d8 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/ie6.css @@ -0,0 +1,8 @@ +* html img, +* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none", +this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')", +this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''), +this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')", +this.runtimeStyle.backgroundImage = "none")),this.pngSet=true) +);} +#wrap{display:table;height:100%} diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/middlebg.png b/docs/quick_tour/sqla_demo/sqla_demo/static/middlebg.png Binary files differnew file mode 100644 index 000000000..2369cfb7d --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/middlebg.png diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/pylons.css b/docs/quick_tour/sqla_demo/sqla_demo/static/pylons.css new file mode 100644 index 000000000..4b1c017cd --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/pylons.css @@ -0,0 +1,372 @@ +html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, font, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td +{ + margin: 0; + padding: 0; + border: 0; + outline: 0; + font-size: 100%; /* 16px */ + vertical-align: baseline; + background: transparent; +} + +body +{ + line-height: 1; +} + +ol, ul +{ + list-style: none; +} + +blockquote, q +{ + quotes: none; +} + +blockquote:before, blockquote:after, q:before, q:after +{ + content: ''; + content: none; +} + +:focus +{ + outline: 0; +} + +ins +{ + text-decoration: none; +} + +del +{ + text-decoration: line-through; +} + +table +{ + border-collapse: collapse; + border-spacing: 0; +} + +sub +{ + vertical-align: sub; + font-size: smaller; + line-height: normal; +} + +sup +{ + vertical-align: super; + font-size: smaller; + line-height: normal; +} + +ul, menu, dir +{ + display: block; + list-style-type: disc; + margin: 1em 0; + padding-left: 40px; +} + +ol +{ + display: block; + list-style-type: decimal-leading-zero; + margin: 1em 0; + padding-left: 40px; +} + +li +{ + display: list-item; +} + +ul ul, ul ol, ul dir, ul menu, ul dl, ol ul, ol ol, ol dir, ol menu, ol dl, dir ul, dir ol, dir dir, dir menu, dir dl, menu ul, menu ol, menu dir, menu menu, menu dl, dl ul, dl ol, dl dir, dl menu, dl dl +{ + margin-top: 0; + margin-bottom: 0; +} + +ol ul, ul ul, menu ul, dir ul, ol menu, ul menu, menu menu, dir menu, ol dir, ul dir, menu dir, dir dir +{ + list-style-type: circle; +} + +ol ol ul, ol ul ul, ol menu ul, ol dir ul, ol ol menu, ol ul menu, ol menu menu, ol dir menu, ol ol dir, ol ul dir, ol menu dir, ol dir dir, ul ol ul, ul ul ul, ul menu ul, ul dir ul, ul ol menu, ul ul menu, ul menu menu, ul dir menu, ul ol dir, ul ul dir, ul menu dir, ul dir dir, menu ol ul, menu ul ul, menu menu ul, menu dir ul, menu ol menu, menu ul menu, menu menu menu, menu dir menu, menu ol dir, menu ul dir, menu menu dir, menu dir dir, dir ol ul, dir ul ul, dir menu ul, dir dir ul, dir ol menu, dir ul menu, dir menu menu, dir dir menu, dir ol dir, dir ul dir, dir menu dir, dir dir dir +{ + list-style-type: square; +} + +.hidden +{ + display: none; +} + +p +{ + line-height: 1.5em; +} + +h1 +{ + font-size: 1.75em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +h2 +{ + font-size: 1.5em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +h3 +{ + font-size: 1.25em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +h4 +{ + font-size: 1em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +html, body +{ + width: 100%; + height: 100%; +} + +body +{ + margin: 0; + padding: 0; + background-color: #fff; + position: relative; + font: 16px/24px NobileRegular, "Lucida Grande", Lucida, Verdana, sans-serif; +} + +a +{ + color: #1b61d6; + text-decoration: none; +} + +a:hover +{ + color: #e88f00; + text-decoration: underline; +} + +body h1, body h2, body h3, body h4, body h5, body h6 +{ + font-family: NeutonRegular, "Lucida Grande", Lucida, Verdana, sans-serif; + font-weight: 400; + color: #373839; + font-style: normal; +} + +#wrap +{ + min-height: 100%; +} + +#header, #footer +{ + width: 100%; + color: #fff; + height: 40px; + position: absolute; + text-align: center; + line-height: 40px; + overflow: hidden; + font-size: 12px; + vertical-align: middle; +} + +#header +{ + background: #000; + top: 0; + font-size: 14px; +} + +#footer +{ + bottom: 0; + background: #000 url(footerbg.png) repeat-x 0 top; + position: relative; + margin-top: -40px; + clear: both; +} + +.header, .footer +{ + width: 750px; + margin-right: auto; + margin-left: auto; +} + +.wrapper +{ + width: 100%; +} + +#top, #top-small, #bottom +{ + width: 100%; +} + +#top +{ + color: #000; + height: 230px; + background: #fff url(headerbg.png) repeat-x 0 top; + position: relative; +} + +#top-small +{ + color: #000; + height: 60px; + background: #fff url(headerbg.png) repeat-x 0 top; + position: relative; +} + +#bottom +{ + color: #222; + background-color: #fff; +} + +.top, .top-small, .middle, .bottom +{ + width: 750px; + margin-right: auto; + margin-left: auto; +} + +.top +{ + padding-top: 40px; +} + +.top-small +{ + padding-top: 10px; +} + +#middle +{ + width: 100%; + height: 100px; + background: url(middlebg.png) repeat-x; + border-top: 2px solid #fff; + border-bottom: 2px solid #b2b2b2; +} + +.app-welcome +{ + margin-top: 25px; +} + +.app-name +{ + color: #000; + font-weight: 700; +} + +.bottom +{ + padding-top: 50px; +} + +#left +{ + width: 350px; + float: left; + padding-right: 25px; +} + +#right +{ + width: 350px; + float: right; + padding-left: 25px; +} + +.align-left +{ + text-align: left; +} + +.align-right +{ + text-align: right; +} + +.align-center +{ + text-align: center; +} + +ul.links +{ + margin: 0; + padding: 0; +} + +ul.links li +{ + list-style-type: none; + font-size: 14px; +} + +form +{ + border-style: none; +} + +fieldset +{ + border-style: none; +} + +input +{ + color: #222; + border: 1px solid #ccc; + font-family: sans-serif; + font-size: 12px; + line-height: 16px; +} + +input[type=text], input[type=password] +{ + width: 205px; +} + +input[type=submit] +{ + background-color: #ddd; + font-weight: 700; +} + +/*Opera Fix*/ +body:before +{ + content: ""; + height: 100%; + float: left; + width: 0; + margin-top: -32767px; +} diff --git a/pyramid/scaffolds/alchemy/+package+/static/pyramid-small.png b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-small.png Binary files differindex a5bc0ade7..a5bc0ade7 100644 --- a/pyramid/scaffolds/alchemy/+package+/static/pyramid-small.png +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid-small.png diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png Binary files differnew file mode 100644 index 000000000..347e05549 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/pyramid.png diff --git a/docs/quick_tour/sqla_demo/sqla_demo/static/transparent.gif b/docs/quick_tour/sqla_demo/sqla_demo/static/transparent.gif Binary files differnew file mode 100644 index 000000000..0341802e5 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/static/transparent.gif diff --git a/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt b/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt new file mode 100644 index 000000000..321c0f5fb --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/templates/mytemplate.pt @@ -0,0 +1,76 @@ +<!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> + </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> + </ul> + </div> + </div> + </div> + </div> + <div id="footer"> + <div class="footer">© Copyright 2008-2012, Agendaless Consulting.</div> + </div> +</body> +</html> diff --git a/docs/quick_tour/sqla_demo/sqla_demo/tests.py b/docs/quick_tour/sqla_demo/sqla_demo/tests.py new file mode 100644 index 000000000..6fef6d695 --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/tests.py @@ -0,0 +1,33 @@ +import unittest +import transaction + +from pyramid import testing + +from .models import DBSession + + +class TestMyView(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) + Base.metadata.create_all(engine) + with transaction.manager: + model = MyModel(name='one', value=55) + DBSession.add(model) + + def tearDown(self): + DBSession.remove() + testing.tearDown() + + def test_it(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') diff --git a/docs/quick_tour/sqla_demo/sqla_demo/views.py b/docs/quick_tour/sqla_demo/sqla_demo/views.py new file mode 100644 index 000000000..768a7e42e --- /dev/null +++ b/docs/quick_tour/sqla_demo/sqla_demo/views.py @@ -0,0 +1,37 @@ +from pyramid.response import Response +from pyramid.view import view_config + +from sqlalchemy.exc import DBAPIError + +from .models import ( + DBSession, + MyModel, + ) + + +@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 + environment's "bin" directory for this script and try to run it. + +2. Your database server may not be running. Check that the + database server referred to by the "sqlalchemy.url" setting in + your "development.ini" file is running. + +After you fix the problem, please restart the Pyramid application to +try it again. +""" + diff --git a/docs/quick_tour/static_assets/app.py b/docs/quick_tour/static_assets/app.py new file mode 100644 index 000000000..9c808972f --- /dev/null +++ b/docs/quick_tour/static_assets/app.py @@ -0,0 +1,14 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator + +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()
\ No newline at end of file diff --git a/docs/quick_tour/static_assets/hello_world.jinja2 b/docs/quick_tour/static_assets/hello_world.jinja2 new file mode 100644 index 000000000..f6862e618 --- /dev/null +++ b/docs/quick_tour/static_assets/hello_world.jinja2 @@ -0,0 +1,10 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Glance</title> + <link rel="stylesheet" href="/static/app.css"/> +</head> +<body> +<h1>Hello {{ name }}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/static_assets/hello_world.pt b/docs/quick_tour/static_assets/hello_world.pt new file mode 100644 index 000000000..1797146eb --- /dev/null +++ b/docs/quick_tour/static_assets/hello_world.pt @@ -0,0 +1,16 @@ +<!DOCTYPE html> +<html lang="en"><head> + <title>Quick Glance</title> + <!-- Start Link 1 --> + <link rel="stylesheet" href="/static/app.css" /> + <!-- End Link 1 --> + <!-- Start Link 2 --> + <link rel="stylesheet" + href="${request.static_url('static/app.css')}" + /> + <!-- End Link 2 --> +</head> +<body> +<h1>Hello ${name}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/static_assets/static/app.css b/docs/quick_tour/static_assets/static/app.css new file mode 100644 index 000000000..f8acf3164 --- /dev/null +++ b/docs/quick_tour/static_assets/static/app.css @@ -0,0 +1,4 @@ +body { + margin: 2em; + font-family: sans-serif; +}
\ No newline at end of file diff --git a/docs/quick_tour/static_assets/views.py b/docs/quick_tour/static_assets/views.py new file mode 100644 index 000000000..90730ae32 --- /dev/null +++ b/docs/quick_tour/static_assets/views.py @@ -0,0 +1,6 @@ +from pyramid.view import view_config + + +@view_config(route_name='hello', renderer='hello_world.pt') +def hello_world(request): + return dict(name=request.matchdict['name']) diff --git a/docs/quick_tour/templating/app.py b/docs/quick_tour/templating/app.py new file mode 100644 index 000000000..6d1a29f4e --- /dev/null +++ b/docs/quick_tour/templating/app.py @@ -0,0 +1,10 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/howdy/{name}') + config.scan('views') + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 6543, app) + server.serve_forever()
\ No newline at end of file diff --git a/docs/quick_tour/templating/hello_world.pt b/docs/quick_tour/templating/hello_world.pt new file mode 100644 index 000000000..ae14f447d --- /dev/null +++ b/docs/quick_tour/templating/hello_world.pt @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Glance</title> +</head> +<body> +<h1>Hello ${name}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/templating/views.py b/docs/quick_tour/templating/views.py new file mode 100644 index 000000000..6c7846efa --- /dev/null +++ b/docs/quick_tour/templating/views.py @@ -0,0 +1,8 @@ +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
\ No newline at end of file diff --git a/docs/quick_tour/view_classes/app.py b/docs/quick_tour/view_classes/app.py new file mode 100644 index 000000000..468c8c29e --- /dev/null +++ b/docs/quick_tour/view_classes/app.py @@ -0,0 +1,13 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator + +if __name__ == '__main__': + config = Configurator() + # Start Routes 1 + config.add_route('hello', '/howdy/{name}') + # End Routes 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()
\ No newline at end of file diff --git a/docs/quick_tour/view_classes/delete.jinja2 b/docs/quick_tour/view_classes/delete.jinja2 new file mode 100644 index 000000000..ba45b7d16 --- /dev/null +++ b/docs/quick_tour/view_classes/delete.jinja2 @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Delete World</title> +</head> +<body> +<h1>Delete {{ view.name }}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/view_classes/edit.jinja2 b/docs/quick_tour/view_classes/edit.jinja2 new file mode 100644 index 000000000..ce0eb5bd1 --- /dev/null +++ b/docs/quick_tour/view_classes/edit.jinja2 @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Edit World</title> +</head> +<body> +<h1>Edit {{ view.name }}!</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/view_classes/hello.jinja2 b/docs/quick_tour/view_classes/hello.jinja2 new file mode 100644 index 000000000..3446b96ce --- /dev/null +++ b/docs/quick_tour/view_classes/hello.jinja2 @@ -0,0 +1,17 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Hello World</title> +</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"/> +</form> +<!-- End Form 1 --> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tour/view_classes/views.py b/docs/quick_tour/view_classes/views.py new file mode 100644 index 000000000..62556142e --- /dev/null +++ b/docs/quick_tour/view_classes/views.py @@ -0,0 +1,32 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +# Start View 1 +# One route, at /howdy/amy, so don't repeat on each @view_config +@view_defaults(route_name='hello') +class HelloWorldViews: + def __init__(self, request): + self.request = request + # Our templates can now say {{ view.name }} + self.name = request.matchdict['name'] + + # Retrieving /howdy/amy the first time + @view_config(renderer='hello.jinja2') + def hello_view(self): + return dict() + + # Posting to /howdy/amy via the "Edit" submit button + @view_config(request_param='form.edit', renderer='edit.jinja2') + def edit_view(self): + print('Edited') + return dict() + + # Posting to /howdy/amy via the "Delete" submit button + @view_config(request_param='form.delete', renderer='delete.jinja2') + def delete_view(self): + print('Deleted') + return dict() + # End View 1
\ No newline at end of file diff --git a/docs/quick_tour/views/app.py b/docs/quick_tour/views/app.py new file mode 100644 index 000000000..54dc9ed4b --- /dev/null +++ b/docs/quick_tour/views/app.py @@ -0,0 +1,13 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator + +if __name__ == '__main__': + config = Configurator() + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.add_route('redirect', '/goto') + config.add_route('exception', '/problem') + config.scan('views') + app = config.make_wsgi_app() + server = make_server('0.0.0.0', 6543, app) + server.serve_forever()
\ No newline at end of file diff --git a/docs/quick_tour/views/views.py b/docs/quick_tour/views/views.py new file mode 100644 index 000000000..9dc795f14 --- /dev/null +++ b/docs/quick_tour/views/views.py @@ -0,0 +1,29 @@ +from pyramid.httpexceptions import HTTPFound +from pyramid.response import Response +from pyramid.view import view_config + + +# First view, available at http://localhost:6543/ +@view_config(route_name='home') +def home_view(request): + return Response('<p>Visit <a href="/howdy?name=lisa">hello</a></p>') + + +# /howdy?name=alice which links to the next view +@view_config(route_name='hello') +def hello_view(request): + name = request.params.get('name', 'No Name') + body = '<p>Hi %s, this <a href="/goto">redirects</a></p>' + return Response(body % name) + + +# /goto which issues HTTP redirect to the last view +@view_config(route_name='redirect') +def redirect_view(request): + return HTTPFound(location="/problem") + + +# /problem which causes an site error +@view_config(route_name='exception') +def exception_view(request): + raise Exception() diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst new file mode 100644 index 000000000..8380a75ed --- /dev/null +++ b/docs/quick_tutorial/authentication.rst @@ -0,0 +1,134 @@ +============================== +20: Logins With Authentication +============================== + +Login views that authenticate a username/password against a list of +users. + +Background +========== + +Most web applications have URLs that allow people to add/edit/delete +content via a web browser. Time to add +:ref:`security <security_chapter>` +to the application. In this first step we introduce authentication. +That is, logging in and logging out using Pyramid's rich facilities for +pluggable user storages. + +In the next step we will introduce protection resources with +authorization security statements. + +Objectives +========== + +- Introduce the Pyramid concepts of authentication + +- Create login/logout views + +Steps +===== + +#. We are going to use the view classes step as our starting point: + + .. code-block:: bash + + $ cd ..; cp -r view_classes authentication; cd authentication + $ $VENV/bin/python setup.py develop + +#. Put the security hash in the ``authentication/development.ini`` + configuration file as ``tutorial.secret`` instead of putting it in + the code: + + .. literalinclude:: authentication/development.ini + :language: ini + :linenos: + +#. Get authentication (and for now, authorization policies) and login + route into the :term:`configurator` in + ``authentication/tutorial/__init__.py``: + + .. literalinclude:: authentication/tutorial/__init__.py + :linenos: + +#. Create a ``authentication/tutorial/security.py`` module that can find + our user information by providing an *authentication policy callback*: + + .. literalinclude:: authentication/tutorial/security.py + :linenos: + +#. Update the views in ``authentication/tutorial/views.py``: + + .. literalinclude:: authentication/tutorial/views.py + :linenos: + +#. Add a login template at ``authentication/tutorial/login.pt``: + + .. literalinclude:: authentication/tutorial/login.pt + :language: html + :linenos: + +#. Provide a login/logout box in ``authentication/tutorial/home.pt`` + + .. literalinclude:: authentication/tutorial/home.pt + :language: html + :linenos: + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in a browser. + +#. Click the "Log In" link. + +#. Submit the login form with the username ``editor`` and the password + ``editor``. + +#. Note that the "Log In" link has changed to "Logout". + +#. Click the "Logout" link. + +Analysis +======== + +Unlike many web frameworks, Pyramid includes a built-in (but optional) +security model for authentication and authorization. This security +system is intended to be flexible and support many needs. In this +security model, authentication (who are you) and authorization (what +are you allowed to do) are not just pluggable, but de-coupled. To learn +one step at a time, we provide a system that identifies users and lets +them log out. + +In this example we chose to use the bundled +:ref:`AuthTktAuthenticationPolicy <authentication_module>` +policy. We enabled it in our configuration and provided a +ticket-signing secret in our INI file. + +Our view class grew a login view. When you reached it via a GET, +it returned a login form. When reached via POST, it processed the +username and password against the "groupfinder" callable that we +registered in the configuration. + +In our template, we fetched the ``logged_in`` value from the view +class. We use this to calculate the logged-in user, +if any. In the template we can then choose to show a login link to +anonymous visitors or a logout link to logged-in users. + +Extra Credit +============ + +#. What is the difference between a user and a principal? + +#. Can I use a database behind my ``groupfinder`` to look up principals? + +#. Do I have to put a ``renderer`` in my ``@forbidden_view_config`` + decorator? + +#. Once I am logged in, does any user-centric information get jammed + onto each request? Use ``import pdb; pdb.set_trace()`` to answer + this. + +.. seealso:: :ref:`security_chapter`, + :ref:`AuthTktAuthenticationPolicy <authentication_module>` diff --git a/docs/quick_tutorial/authentication/development.ini b/docs/quick_tutorial/authentication/development.ini new file mode 100644 index 000000000..5d4580ff5 --- /dev/null +++ b/docs/quick_tutorial/authentication/development.ini @@ -0,0 +1,42 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar +tutorial.secret = 98zd + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/authentication/setup.py b/docs/quick_tutorial/authentication/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/authentication/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/authentication/tutorial/__init__.py b/docs/quick_tutorial/authentication/tutorial/__init__.py new file mode 100644 index 000000000..efc09e760 --- /dev/null +++ b/docs/quick_tutorial/authentication/tutorial/__init__.py @@ -0,0 +1,25 @@ +from pyramid.authentication import AuthTktAuthenticationPolicy +from pyramid.authorization import ACLAuthorizationPolicy +from pyramid.config import Configurator + +from .security import groupfinder + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + + # Security policies + authn_policy = AuthTktAuthenticationPolicy( + settings['tutorial.secret'], callback=groupfinder, + hashalg='sha512') + authz_policy = ACLAuthorizationPolicy() + config.set_authentication_policy(authn_policy) + config.set_authorization_policy(authz_policy) + + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.add_route('login', '/login') + config.add_route('logout', '/logout') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/authentication/tutorial/home.pt b/docs/quick_tutorial/authentication/tutorial/home.pt new file mode 100644 index 000000000..6ecd0081b --- /dev/null +++ b/docs/quick_tutorial/authentication/tutorial/home.pt @@ -0,0 +1,18 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> + +<div> + <a tal:condition="view.logged_in is None" + href="${request.application_url}/login">Log In</a> + <a tal:condition="view.logged_in is not None" + href="${request.application_url}/logout">Logout</a> +</div> + +<h1>Hi ${name}</h1> +<p>Visit <a href="${request.route_url('hello')}">hello</a></p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/authentication/tutorial/login.pt b/docs/quick_tutorial/authentication/tutorial/login.pt new file mode 100644 index 000000000..4451fc4f8 --- /dev/null +++ b/docs/quick_tutorial/authentication/tutorial/login.pt @@ -0,0 +1,25 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Login</h1> +<span tal:replace="message"/> + +<form action="${url}" method="post"> + <input type="hidden" name="came_from" + value="${came_from}"/> + <label for="login">Username</label> + <input type="text" id="login" + name="login" + value="${login}"/><br/> + <label for="password">Password</label> + <input type="password" id="password" + name="password" + value="${password}"/><br/> + <input type="submit" name="form.submitted" + value="Log In"/> +</form> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/authentication/tutorial/security.py b/docs/quick_tutorial/authentication/tutorial/security.py new file mode 100644 index 000000000..ab90bab2c --- /dev/null +++ b/docs/quick_tutorial/authentication/tutorial/security.py @@ -0,0 +1,8 @@ +USERS = {'editor': 'editor', + 'viewer': 'viewer'} +GROUPS = {'editor': ['group:editors']} + + +def groupfinder(userid, request): + if userid in USERS: + return GROUPS.get(userid, [])
\ No newline at end of file diff --git a/docs/quick_tutorial/authentication/tutorial/views.py b/docs/quick_tutorial/authentication/tutorial/views.py new file mode 100644 index 000000000..3038b6d9b --- /dev/null +++ b/docs/quick_tutorial/authentication/tutorial/views.py @@ -0,0 +1,64 @@ +from pyramid.httpexceptions import HTTPFound +from pyramid.security import ( + remember, + forget, + authenticated_userid + ) +from pyramid.view import ( + view_config, + view_defaults + ) + +from .security import USERS + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + self.logged_in = authenticated_userid(request) + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello') + def hello(self): + return {'name': 'Hello View'} + + @view_config(route_name='login', renderer='login.pt') + def login(self): + request = self.request + login_url = request.route_url('login') + referrer = request.url + if referrer == login_url: + referrer = '/' # never use login form itself as came_from + came_from = request.params.get('came_from', referrer) + message = '' + login = '' + password = '' + if 'form.submitted' in request.params: + login = request.params['login'] + password = request.params['password'] + if USERS.get(login) == password: + headers = remember(request, login) + return HTTPFound(location=came_from, + headers=headers) + message = 'Failed login' + + return dict( + name='Login', + message=message, + url=request.application_url + '/login', + came_from=came_from, + login=login, + password=password, + ) + + @view_config(route_name='logout') + def logout(self): + request = self.request + headers = forget(request) + url = request.route_url('home') + return HTTPFound(location=url, + headers=headers) diff --git a/docs/quick_tutorial/authorization.rst b/docs/quick_tutorial/authorization.rst new file mode 100644 index 000000000..6b10d3409 --- /dev/null +++ b/docs/quick_tutorial/authorization.rst @@ -0,0 +1,112 @@ +=========================================== +21: Protecting Resources With Authorization +=========================================== + +Assign security statements to resources describing the permissions +required to perform an operation. + +Background +========== + +Our application has URLs that allow people to add/edit/delete content +via a web browser. Time to add security to the application. Let's +protect our add/edit views to require a login (username of +``editor`` and password of ``editor``.) We will allow the other views +to continue working without a password. + +Objectives +========== + +- Introduce the Pyramid concepts of authentication, authorization, + permissions, and access control lists (ACLs) + +- Make a :term:`root factory` that returns an instance of our + class for the top of the application + +- Assign security statements to our root resource + +- Add a permissions predicate on a view + +- Provide a :term:`Forbidden view` to handle visiting a URL without + adequate permissions + +Steps +===== + +#. We are going to use the authentication step as our starting point: + + .. code-block:: bash + + $ cd ..; cp -r authentication authorization; cd authorization + $ $VENV/bin/python setup.py develop + +#. Start by changing ``authorization/tutorial/__init__.py`` to + specify a root factory to the :term:`configurator`: + + .. literalinclude:: authorization/tutorial/__init__.py + :linenos: + +#. That means we need to implement + ``authorization/tutorial/resources.py`` + + .. literalinclude:: authorization/tutorial/resources.py + :linenos: + +#. Change ``authorization/tutorial/views.py`` to require the ``edit`` + permission on the ``hello`` view and implement the forbidden view: + + .. literalinclude:: authorization/tutorial/views.py + :linenos: + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in a browser. + +#. If you are still logged in, click the "Log Out" link. + +#. Visit http://localhost:6543/howdy in a browser. You should be + asked to login. + +Analysis +======== + +This simple tutorial step can be boiled down to the following: + +- A view can require a *permission* (``edit``) + +- The context for our view (the ``Root``) has an access control list + (ACL) + +- This ACL says that the ``edit`` permission is available on ``Root`` + to the ``group:editors`` *principal* + +- The registered ``groupfinder`` answers whether a particular user + (``editor``) has a particular group (``group:editors``) + +In summary: ``hello`` wants ``edit`` permission, ``Root`` says +``group:editors`` has ``edit`` permission. + +Of course, this only applies on ``Root``. Some other part of the site +(a.k.a. *context*) might have a different ACL. + +If you are not logged in and visit ``/hello``, you need to get +shown the login screen. How does Pyramid know what is the login page to +use? We explicitly told Pyramid that the ``login`` view should be used +by decorating the view with ``@forbidden_view_config``. + +Extra Credit +============ + +#. Perhaps you would like experience of not having enough permissions + (forbidden) to be richer. How could you change this? + +#. Perhaps we want to store security statements in a database and + allow editing via a browser. How might this be done? + +#. What if we want different security statements on different kinds of + objects? Or on the same kinds of objects, but in different parts of a + URL hierarchy? diff --git a/docs/quick_tutorial/authorization/development.ini b/docs/quick_tutorial/authorization/development.ini new file mode 100644 index 000000000..5d4580ff5 --- /dev/null +++ b/docs/quick_tutorial/authorization/development.ini @@ -0,0 +1,42 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar +tutorial.secret = 98zd + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/authorization/setup.py b/docs/quick_tutorial/authorization/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/authorization/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/authorization/tutorial/__init__.py b/docs/quick_tutorial/authorization/tutorial/__init__.py new file mode 100644 index 000000000..8f7ab8277 --- /dev/null +++ b/docs/quick_tutorial/authorization/tutorial/__init__.py @@ -0,0 +1,26 @@ +from pyramid.authentication import AuthTktAuthenticationPolicy +from pyramid.authorization import ACLAuthorizationPolicy +from pyramid.config import Configurator + +from .security import groupfinder + + +def main(global_config, **settings): + config = Configurator(settings=settings, + root_factory='.resources.Root') + config.include('pyramid_chameleon') + + # Security policies + authn_policy = AuthTktAuthenticationPolicy( + settings['tutorial.secret'], callback=groupfinder, + hashalg='sha512') + authz_policy = ACLAuthorizationPolicy() + config.set_authentication_policy(authn_policy) + config.set_authorization_policy(authz_policy) + + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.add_route('login', '/login') + config.add_route('logout', '/logout') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/authorization/tutorial/home.pt b/docs/quick_tutorial/authorization/tutorial/home.pt new file mode 100644 index 000000000..6ecd0081b --- /dev/null +++ b/docs/quick_tutorial/authorization/tutorial/home.pt @@ -0,0 +1,18 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> + +<div> + <a tal:condition="view.logged_in is None" + href="${request.application_url}/login">Log In</a> + <a tal:condition="view.logged_in is not None" + href="${request.application_url}/logout">Logout</a> +</div> + +<h1>Hi ${name}</h1> +<p>Visit <a href="${request.route_url('hello')}">hello</a></p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/authorization/tutorial/login.pt b/docs/quick_tutorial/authorization/tutorial/login.pt new file mode 100644 index 000000000..4451fc4f8 --- /dev/null +++ b/docs/quick_tutorial/authorization/tutorial/login.pt @@ -0,0 +1,25 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Login</h1> +<span tal:replace="message"/> + +<form action="${url}" method="post"> + <input type="hidden" name="came_from" + value="${came_from}"/> + <label for="login">Username</label> + <input type="text" id="login" + name="login" + value="${login}"/><br/> + <label for="password">Password</label> + <input type="password" id="password" + name="password" + value="${password}"/><br/> + <input type="submit" name="form.submitted" + value="Log In"/> +</form> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/authorization/tutorial/resources.py b/docs/quick_tutorial/authorization/tutorial/resources.py new file mode 100644 index 000000000..0cb656f12 --- /dev/null +++ b/docs/quick_tutorial/authorization/tutorial/resources.py @@ -0,0 +1,9 @@ +from pyramid.security import Allow, Everyone + + +class Root(object): + __acl__ = [(Allow, Everyone, 'view'), + (Allow, 'group:editors', 'edit')] + + def __init__(self, request): + pass
\ No newline at end of file diff --git a/docs/quick_tutorial/authorization/tutorial/security.py b/docs/quick_tutorial/authorization/tutorial/security.py new file mode 100644 index 000000000..ab90bab2c --- /dev/null +++ b/docs/quick_tutorial/authorization/tutorial/security.py @@ -0,0 +1,8 @@ +USERS = {'editor': 'editor', + 'viewer': 'viewer'} +GROUPS = {'editor': ['group:editors']} + + +def groupfinder(userid, request): + if userid in USERS: + return GROUPS.get(userid, [])
\ No newline at end of file diff --git a/docs/quick_tutorial/authorization/tutorial/views.py b/docs/quick_tutorial/authorization/tutorial/views.py new file mode 100644 index 000000000..92c1946ba --- /dev/null +++ b/docs/quick_tutorial/authorization/tutorial/views.py @@ -0,0 +1,66 @@ +from pyramid.httpexceptions import HTTPFound +from pyramid.security import ( + remember, + forget, + authenticated_userid + ) +from pyramid.view import ( + view_config, + view_defaults, + forbidden_view_config + ) + +from .security import USERS + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + self.logged_in = authenticated_userid(request) + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello', permission='edit') + def hello(self): + return {'name': 'Hello View'} + + @view_config(route_name='login', renderer='login.pt') + @forbidden_view_config(renderer='login.pt') + def login(self): + request = self.request + login_url = request.route_url('login') + referrer = request.url + if referrer == login_url: + referrer = '/' # never use login form itself as came_from + came_from = request.params.get('came_from', referrer) + message = '' + login = '' + password = '' + if 'form.submitted' in request.params: + login = request.params['login'] + password = request.params['password'] + if USERS.get(login) == password: + headers = remember(request, login) + return HTTPFound(location=came_from, + headers=headers) + message = 'Failed login' + + return dict( + name='Login', + message=message, + url=request.application_url + '/login', + came_from=came_from, + login=login, + password=password, + ) + + @view_config(route_name='logout') + def logout(self): + request = self.request + headers = forget(request) + url = request.route_url('home') + return HTTPFound(location=url, + headers=headers) diff --git a/docs/quick_tutorial/conf.py b/docs/quick_tutorial/conf.py new file mode 100644 index 000000000..47b8fae41 --- /dev/null +++ b/docs/quick_tutorial/conf.py @@ -0,0 +1,281 @@ +# -*- coding: utf-8 -*- +# +# Getting Started with Pyramid and REST documentation build configuration file, created by +# sphinx-quickstart on Mon Aug 26 14:44:57 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.intersphinx'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Getting Started with Pyramid and REST' +copyright = u'2013, Agendaless Consulting' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'GettingStartedwithPyramidandRESTdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + #'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'GettingStartedwithPyramidandREST.tex', + u'Getting Started with Pyramid and REST Documentation', + u'Agendaless Consulting', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'gettingstartedwithpyramidandrest', + u'Getting Started with Pyramid and REST Documentation', + [u'Agendaless Consulting'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'GettingStartedwithPyramidandREST', + u'Getting Started with Pyramid and REST Documentation', + u'Agendaless Consulting', 'GettingStartedwithPyramidandREST', + 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'python': ( + 'http://docs.python.org/2', + None), + 'sqla': ( + 'http://docs.sqlalchemy.org/en/latest', + None), + 'pyramid': ( + 'http://docs.pylonsproject.org/projects/pyramid/en/latest/', + None), + 'jinja2': ( + 'http://docs.pylonsproject.org/projects/pyramid_jinja2/en/latest/', + None), + 'toolbar': ( + 'http://docs.pylonsproject.org/projects/pyramid_debugtoolbar/en/latest', + None), + 'deform': ( + 'http://docs.pylonsproject.org/projects/deform/en/latest', + None), + 'colander': ( + 'http://docs.pylonsproject.org/projects/colander/en/latest', + None), + 'tutorials': ( + 'http://docs.pylonsproject.org/projects/pyramid_tutorials/en/latest/', + None), +} diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst new file mode 100644 index 000000000..93a02ffc7 --- /dev/null +++ b/docs/quick_tutorial/databases.rst @@ -0,0 +1,195 @@ +.. _qtut_databases: + +============================== +19: Databases Using SQLAlchemy +============================== + +Store/retrieve data using the SQLAlchemy ORM atop the SQLite database. + +Background +========== + +Our Pyramid-based wiki application now needs database-backed storage of +pages. This frequently means a SQL database. The Pyramid community +strongly supports the +:ref:`SQLAlchemy <sqla:index_toplevel>` project and its +:ref:`object-relational mapper (ORM) <sqla:ormtutorial_toplevel>` +as a convenient, Pythonic way to interface to databases. + +In this step we hook up SQLAlchemy to a SQLite database table, +providing storage and retrieval for the wikipages in the previous step. + +.. note:: + + The ``alchemy`` scaffold is really helpful for getting a + SQLAlchemy project going, including generation of the console + script. Since we want to see all the decisions, we will forgo + convenience in this tutorial and wire it up ourselves. + +Objectives +========== + +- Store pages in SQLite by using SQLAlchemy models + +- Use SQLAlchemy queries to list/add/view/edit pages + +- Provide a database-initialize command by writing a Pyramid *console + script* which can be run from the command line + +Steps +===== + +.. warning:: + + Your Python might not have SQLite bundled. If not, install it into + your virtual environment with: + + .. code-block:: bash + + $ $VENV/bin/easy_install sphinx pysqlite + +#. We are going to use the forms step as our starting point: + + .. code-block:: bash + + $ cd ..; cp -r forms databases; cd databases + +#. We need to add some dependencies in ``databases/setup.py`` as well + as an "entry point" for the command-line script: + + .. literalinclude:: databases/setup.py + :linenos: + + .. note:: + + We aren't yet doing ``python3.3 setup.py develop`` as we + are changing it later. + +#. Our configuration file at ``databases/development.ini`` wires + together some new pieces: + + .. literalinclude:: databases/development.ini + :language: ini + +#. This engine configuration now needs to be read into the application + through changes in ``databases/tutorial/__init__.py``: + + .. literalinclude:: databases/tutorial/__init__.py + :linenos: + +#. Make a command-line script at ``databases/tutorial/initialize_db.py`` + to initialize the database: + + .. literalinclude:: databases/tutorial/initialize_db.py + +#. Since ``setup.py`` changed, we now run it: + + .. code-block:: bash + + $ $VENV/bin/python setup.py develop + +#. The script references some models in ``databases/tutorial/models.py``: + + .. literalinclude:: databases/tutorial/models.py + :linenos: + +#. Let's run this console script, thus producing our database and table: + + .. code-block:: bash + + $ initialize_tutorial_db development.ini + 2013-09-06 15:54:08,050 INFO [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages") + 2013-09-06 15:54:08,050 INFO [sqlalchemy.engine.base.Engine][MainThread] () + 2013-09-06 15:54:08,051 INFO [sqlalchemy.engine.base.Engine][MainThread] + CREATE TABLE wikipages ( + uid INTEGER NOT NULL, + title TEXT, + body TEXT, + PRIMARY KEY (uid), + UNIQUE (title) + ) + +#. With our data now driven by SQLAlchemy queries, we need to update + our ``databases/tutorial/views.py``: + + .. literalinclude:: databases/tutorial/views.py + +#. Our tests in ``databases/tutorial/tests.py`` changed to include + SQLAlchemy bootstrapping: + + .. literalinclude:: databases/tutorial/tests.py + :linenos: + +#. Run the tests in your package using ``nose``: + + .. code-block:: bash + + $ $VENV/bin/nosetests . + .. + ----------------------------------------------------------------- + Ran 2 tests in 1.141s + + OK + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in a browser. + +Analysis +======== + +Let's start with the dependencies. We made the decision to use +``SQLAlchemy`` to talk to our database. We also, though, installed +``pyramid_tm`` and ``zope.sqlalchemy``. Why? + +Pyramid has a strong orientation towards support for ``transactions``. +Specifically, you can install a transaction manager into your app +application, either as middleware or a Pyramid "tween". Then, +just before you return the response, all transaction-aware parts of +your application are executed. + +This means Pyramid view code usually doesn't manage transactions. If +your view code or a template generates an error, the transaction manager +aborts the transaction. This is a very liberating way to write code. + +The ``pyramid_tm`` package provides a "tween" that is configured in the +``development.ini`` configuration file. That installs it. We then need +a package that makes SQLAlchemy and thus the RDBMS transaction manager +integrate with the Pyramid transaction manager. That's what +``zope.sqlalchemy`` does. + +Where do we point at the location on disk for the SQLite file? In the +configuration file. This lets consumers of our package change the +location in a safe (non-code) way. That is, in configuration. This +configuration-oriented approach isn't required in Pyramid; you can +still make such statements in your ``__init__.py`` or some companion +module. + +The ``initialize_tutorial_db`` is a nice example of framework support. +You point your setup at the location of some ``[console_scripts]`` and +these get generated into your virtualenv's ``bin`` directory. Our +console script follows the pattern of being fed a configuration file +with all the bootstrapping. It then opens SQLAlchemy and creates the +root of the wiki, which also makes the SQLite file. Note the +``with transaction.manager`` part that puts the work in the scope of a +transaction (as we aren't inside a web request where this is done +automatically.) + +The ``models.py`` does a little bit extra work to hook up SQLAlchemy +into the Pyramid transaction manager. It then declares the model for a +``Page``. + +Our views have changes primarily around replacing our dummy +dictionary-of-dictionaries data with proper database support: list the +rows, add a row, edit a row, and delete a row. + +Extra Credit +============ + +#. Why all this code? Why can't I just type 2 lines and have magic ensue? + +#. Give a try at a button that deletes a wiki page. diff --git a/docs/quick_tutorial/databases/development.ini b/docs/quick_tutorial/databases/development.ini new file mode 100644 index 000000000..270da960f --- /dev/null +++ b/docs/quick_tutorial/databases/development.ini @@ -0,0 +1,49 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + pyramid_tm + +sqlalchemy.url = sqlite:///%(here)s/sqltutorial.sqlite + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial, sqlalchemy + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[logger_sqlalchemy] +level = INFO +handlers = +qualname = sqlalchemy.engine + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/databases/setup.py b/docs/quick_tutorial/databases/setup.py new file mode 100644 index 000000000..238358fe4 --- /dev/null +++ b/docs/quick_tutorial/databases/setup.py @@ -0,0 +1,20 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon', + 'deform', + 'sqlalchemy', + 'pyramid_tm', + 'zope.sqlalchemy' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + [console_scripts] + initialize_tutorial_db = tutorial.initialize_db:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/databases/sqltutorial.sqlite b/docs/quick_tutorial/databases/sqltutorial.sqlite Binary files differnew file mode 100644 index 000000000..b8bd856fd --- /dev/null +++ b/docs/quick_tutorial/databases/sqltutorial.sqlite diff --git a/docs/quick_tutorial/databases/tutorial/__init__.py b/docs/quick_tutorial/databases/tutorial/__init__.py new file mode 100644 index 000000000..74aa25740 --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/__init__.py @@ -0,0 +1,21 @@ +from pyramid.config import Configurator + +from sqlalchemy import engine_from_config + +from .models import DBSession, Base + +def main(global_config, **settings): + engine = engine_from_config(settings, 'sqlalchemy.') + DBSession.configure(bind=engine) + Base.metadata.bind = engine + + config = Configurator(settings=settings, + root_factory='tutorial.models.Root') + config.include('pyramid_chameleon') + config.add_route('wiki_view', '/') + config.add_route('wikipage_add', '/add') + config.add_route('wikipage_view', '/{uid}') + config.add_route('wikipage_edit', '/{uid}/edit') + config.add_static_view('deform_static', 'deform:static/') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/databases/tutorial/initialize_db.py b/docs/quick_tutorial/databases/tutorial/initialize_db.py new file mode 100644 index 000000000..98be524a1 --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/initialize_db.py @@ -0,0 +1,37 @@ +import os +import sys +import transaction + +from sqlalchemy import engine_from_config + +from pyramid.paster import ( + get_appsettings, + setup_logging, + ) + +from .models import ( + DBSession, + Page, + Base, + ) + + +def usage(argv): + cmd = os.path.basename(argv[0]) + print('usage: %s <config_uri>\n' + '(example: "%s development.ini")' % (cmd, cmd)) + sys.exit(1) + + +def main(argv=sys.argv): + if len(argv) != 2: + usage(argv) + config_uri = argv[1] + setup_logging(config_uri) + settings = get_appsettings(config_uri) + engine = engine_from_config(settings, 'sqlalchemy.') + DBSession.configure(bind=engine) + Base.metadata.create_all(engine) + with transaction.manager: + model = Page(title='Root', body='<p>Root</p>') + DBSession.add(model) diff --git a/docs/quick_tutorial/databases/tutorial/models.py b/docs/quick_tutorial/databases/tutorial/models.py new file mode 100644 index 000000000..b27c38417 --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/models.py @@ -0,0 +1,35 @@ +from pyramid.security import Allow, Everyone + +from sqlalchemy import ( + Column, + Integer, + Text, + ) + +from sqlalchemy.ext.declarative import declarative_base + +from sqlalchemy.orm import ( + scoped_session, + sessionmaker, + ) + +from zope.sqlalchemy import ZopeTransactionExtension + +DBSession = scoped_session( + sessionmaker(extension=ZopeTransactionExtension())) +Base = declarative_base() + + +class Page(Base): + __tablename__ = 'wikipages' + uid = Column(Integer, primary_key=True) + title = Column(Text, unique=True) + body = Column(Text) + + +class Root(object): + __acl__ = [(Allow, Everyone, 'view'), + (Allow, 'group:editors', 'edit')] + + def __init__(self, request): + pass
\ No newline at end of file diff --git a/docs/quick_tutorial/databases/tutorial/tests.py b/docs/quick_tutorial/databases/tutorial/tests.py new file mode 100644 index 000000000..e18e70c8c --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/tests.py @@ -0,0 +1,58 @@ +import unittest +import transaction + +from pyramid import testing + + +def _initTestingDB(): + from sqlalchemy import create_engine + from .models import ( + DBSession, + Page, + Base + ) + engine = create_engine('sqlite://') + Base.metadata.create_all(engine) + DBSession.configure(bind=engine) + with transaction.manager: + model = Page(title='FrontPage', body='This is the front page') + DBSession.add(model) + return DBSession + + +class WikiViewTests(unittest.TestCase): + def setUp(self): + self.session = _initTestingDB() + self.config = testing.setUp() + + def tearDown(self): + self.session.remove() + testing.tearDown() + + def test_wiki_view(self): + from tutorial.views import WikiViews + + request = testing.DummyRequest() + inst = WikiViews(request) + response = inst.wiki_view() + self.assertEqual(response['title'], 'Wiki View') + + +class WikiFunctionalTests(unittest.TestCase): + def setUp(self): + self.session = _initTestingDB() + self.config = testing.setUp() + from pyramid.paster import get_app + app = get_app('development.ini') + from webtest import TestApp + self.testapp = TestApp(app) + + def tearDown(self): + self.session.remove() + testing.tearDown() + + def test_it(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'Wiki: View', res.body) + res = self.testapp.get('/add', status=200) + self.assertIn(b'Add/Edit', res.body) diff --git a/docs/quick_tutorial/databases/tutorial/views.py b/docs/quick_tutorial/databases/tutorial/views.py new file mode 100644 index 000000000..4608c6d43 --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/views.py @@ -0,0 +1,96 @@ +import colander +import deform.widget + +from pyramid.httpexceptions import HTTPFound +from pyramid.view import view_config + +from .models import DBSession, Page + + +class WikiPage(colander.MappingSchema): + title = colander.SchemaNode(colander.String()) + body = colander.SchemaNode( + colander.String(), + widget=deform.widget.RichTextWidget() + ) + + +class WikiViews(object): + def __init__(self, request): + self.request = request + + @property + def wiki_form(self): + schema = WikiPage() + return deform.Form(schema, buttons=('submit',)) + + @property + def reqts(self): + return self.wiki_form.get_widget_resources() + + @view_config(route_name='wiki_view', renderer='wiki_view.pt') + def wiki_view(self): + pages = DBSession.query(Page).order_by(Page.title) + return dict(title='Wiki View', pages=pages) + + @view_config(route_name='wikipage_add', + renderer='wikipage_addedit.pt') + def wikipage_add(self): + form = self.wiki_form.render() + + if 'submit' in self.request.params: + controls = self.request.POST.items() + try: + appstruct = self.wiki_form.validate(controls) + except deform.ValidationFailure as e: + # Form is NOT valid + return dict(form=e.render()) + + # Add a new page to the database + new_title = appstruct['title'] + new_body = appstruct['body'] + DBSession.add(Page(title=new_title, body=new_body)) + + # Get the new ID and redirect + page = DBSession.query(Page).filter_by(title=new_title).one() + new_uid = page.uid + + url = self.request.route_url('wikipage_view', uid=new_uid) + return HTTPFound(url) + + return dict(form=form) + + + @view_config(route_name='wikipage_view', renderer='wikipage_view.pt') + def wikipage_view(self): + uid = int(self.request.matchdict['uid']) + page = DBSession.query(Page).filter_by(uid=uid).one() + return dict(page=page) + + + @view_config(route_name='wikipage_edit', + renderer='wikipage_addedit.pt') + def wikipage_edit(self): + uid = int(self.request.matchdict['uid']) + page = DBSession.query(Page).filter_by(uid=uid).one() + + wiki_form = self.wiki_form + + if 'submit' in self.request.params: + controls = self.request.POST.items() + try: + appstruct = wiki_form.validate(controls) + except deform.ValidationFailure as e: + return dict(page=page, form=e.render()) + + # Change the content and redirect to the view + page.title = appstruct['title'] + page.body = appstruct['body'] + url = self.request.route_url('wikipage_view', uid=uid) + return HTTPFound(url) + + form = self.wiki_form.render(dict( + uid=page.uid, title=page.title, body=page.body) + ) + + return dict(page=page, form=form) diff --git a/docs/quick_tutorial/databases/tutorial/wiki_view.pt b/docs/quick_tutorial/databases/tutorial/wiki_view.pt new file mode 100644 index 000000000..9e3afe495 --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/wiki_view.pt @@ -0,0 +1,19 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Wiki: View</title> +</head> +<body> +<h1>Wiki</h1> + +<a href="${request.route_url('wikipage_add')}">Add + WikiPage</a> +<ul> + <li tal:repeat="page pages"> + <a href="${request.route_url('wikipage_view', uid=page.uid)}"> + ${page.title} + </a> + </li> +</ul> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/databases/tutorial/wikipage_addedit.pt b/docs/quick_tutorial/databases/tutorial/wikipage_addedit.pt new file mode 100644 index 000000000..d1fea0d7f --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/wikipage_addedit.pt @@ -0,0 +1,22 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>WikiPage: Add/Edit</title> + <tal:block tal:repeat="reqt view.reqts['css']"> + <link rel="stylesheet" type="text/css" + href="${request.static_url('deform:static/' + reqt)}"/> + </tal:block> + <tal:block tal:repeat="reqt view.reqts['js']"> + <script src="${request.static_url('deform:static/' + reqt)}" + type="text/javascript"></script> + </tal:block> +</head> +<body> +<h1>Wiki</h1> + +<p>${structure: form}</p> +<script type="text/javascript"> + deform.load() +</script> +</body> +</html> diff --git a/docs/quick_tutorial/databases/tutorial/wikipage_view.pt b/docs/quick_tutorial/databases/tutorial/wikipage_view.pt new file mode 100644 index 000000000..cb9ff526e --- /dev/null +++ b/docs/quick_tutorial/databases/tutorial/wikipage_view.pt @@ -0,0 +1,17 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>WikiPage: View</title> +</head> +<body> +<a href="${request.route_url('wiki_view')}"> + Up +</a> | +<a href="${request.route_url('wikipage_edit', uid=page.uid)}"> + Edit +</a> + +<h1>${page.title}</h1> +<p>${structure: page.body}</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst new file mode 100644 index 000000000..d25588c49 --- /dev/null +++ b/docs/quick_tutorial/debugtoolbar.rst @@ -0,0 +1,89 @@ +.. _qtut_debugtoolbar: + +============================================ +04: Easier Development with ``debugtoolbar`` +============================================ + +Error-handling and introspection using the ``pyramid_debugtoolbar`` +add-on. + +Background +========== + +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. + +``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. + +Objectives +========== + +- Install and enable the toolbar to help during development + +- Explain Pyramid add-ons + +- Show how an add-on gets configured into your application + +Steps +===== + +#. First we copy the results of the previous step, as well as install + the ``pyramid_debugtoolbar`` package: + + .. code-block:: bash + + $ cd ..; cp -r ini debugtoolbar; cd debugtoolbar + $ $VENV/bin/python setup.py develop + $ $VENV/bin/easy_install pyramid_debugtoolbar + + +#. Our ``debugtoolbar/development.ini`` gets a configuration entry for + ``pyramid.includes``: + + .. literalinclude:: debugtoolbar/development.ini + :language: ini + :linenos: + +#. Run the WSGI application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser. See the handy + toolbar on the right. + +Analysis +======== + +``pyramid_debugtoolbar`` is a full-fledged Python package, +available on PyPI just like thousands of other Python packages. Thus we +start by installing the ``pyramid_debugtoolbar`` package into our +virtual environment using normal Python package installation commands. + +The ``pyramid_debugtoolbar`` Python package is also a Pyramid add-on, +which means we need to include its add-on configuration into our web +application. We could do this with imperative configuration in +``tutorial/__init__.py`` by using ``config.include``. Pyramid also +supports wiring in add-on configuration via our ``development.ini`` +using ``pyramid.includes``. We use this to load the configuration for +the debugtoolbar. + +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, no need to change code: you can remove it from +``pyramid.includes`` in the relevant ``.ini`` configuration file (thus +showing why configuration files are handy.) + +Note that the toolbar mutates the HTML generated by our app and uses jQuery to +overlay itself. If you are using the toolbar while you're developing and you +start to experience otherwise inexplicable client-side weirdness, you can shut +it off by commenting out the ``pyramid_debugtoolbar`` line in +``pyramid.includes`` temporarily. + +.. seealso:: See Also: :ref:`pyramid_debugtoolbar <toolbar:overview>` diff --git a/docs/quick_tutorial/debugtoolbar/development.ini b/docs/quick_tutorial/debugtoolbar/development.ini new file mode 100644 index 000000000..470d92c57 --- /dev/null +++ b/docs/quick_tutorial/debugtoolbar/development.ini @@ -0,0 +1,40 @@ +[app:main] +use = egg:tutorial +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/debugtoolbar/setup.py b/docs/quick_tutorial/debugtoolbar/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/debugtoolbar/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py b/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py new file mode 100644 index 000000000..2b4e84f30 --- /dev/null +++ b/docs/quick_tutorial/debugtoolbar/tutorial/__init__.py @@ -0,0 +1,13 @@ +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + return Response('<body><h1>Hello World!</h1></body>') + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('hello', '/') + config.add_view(hello_world, route_name='hello') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst new file mode 100644 index 000000000..e8bc0c8b4 --- /dev/null +++ b/docs/quick_tutorial/forms.rst @@ -0,0 +1,148 @@ +.. _qtut_forms: + +==================================== +18: Forms and Validation With Deform +==================================== + +Schema-driven, autogenerated forms with validation. + +Background +========== + +Modern web applications deal extensively with forms. Developers, +though, have a wide range of philosophies about how frameworks should +help them with their forms. As such, Pyramid doesn't directly bundle +one particular form library. Instead, there are a variety of form +libraries that are easy to use in Pyramid. + +:ref:`Deform <deform:overview>` +is one such library. In this step, we introduce Deform for our +forms and validation. This also gives us the +:ref:`Colander <colander:overview>` for schemas and validation. + +Deform is getting a facelift, with styling from Twitter Bootstrap and +advanced widgets from popular JavaScript projects. The work began in +``deform_bootstrap`` and is being merged into an update to Deform. + +Objectives +========== + +- Make a schema using Colander, the companion to Deform + +- Create a form with Deform and change our views to handle validation + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes forms; cd forms + +#. Let's edit ``forms/setup.py`` to declare a dependency on Deform + (which then pulls in Colander as a dependency: + + .. literalinclude:: forms/setup.py + :linenos: + +#. We can now install our project in development mode: + + .. code-block:: bash + + $ $VENV/bin/python setup.py develop + +#. Register a static view in ``forms/tutorial/__init__.py`` for + Deform's CSS/JS etc. as well as our demo wikipage scenario's + views: + + .. literalinclude:: forms/tutorial/__init__.py + :linenos: + +#. Implement the new views, as well as the form schemas and some + dummy data, in ``forms/tutorial/views.py``: + + .. literalinclude:: forms/tutorial/views.py + :linenos: + +#. A template for the top of the "wiki" in + ``forms/tutorial/wiki_view.pt``: + + .. literalinclude:: forms/tutorial/wiki_view.pt + :language: html + :linenos: + +#. Another template for adding/editing in + ``forms/tutorial/wikipage_addedit.pt``: + + .. literalinclude:: forms/tutorial/wikipage_addedit.pt + :language: html + :linenos: + +#. Finally, a template at ``forms/tutorial/wikipage_view.pt`` + for viewing a wiki page: + + .. literalinclude:: forms/tutorial/wikipage_view.pt + :language: html + :linenos: + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in a browser. + + +Analysis +======== + +This step helps illustrate the utility of asset specifications for +static assets. We have an outside package called Deform with static +assets which need to be published. We don't have to know where on disk +it is located. We point at the package, then the path inside the package. + +We just need to include a call to ``add_static_view`` to make that +directory available at a URL. For Pyramid-specific pages, +Pyramid provides a facility (``config.include()``) which even makes +that unnecessary for consumers of a package. (Deform is not specific to +Pyramid.) + +Our forms have rich widgets which need the static CSS and JS just +mentioned. Deform has a :term:`resource registry` which allows widgets +to specify which JS and CSS are needed. Our ``wikipage_addedit.pt`` +template shows how we iterated over that data to generate markup that +includes the needed resources. + +Our add and edit views use a pattern called *self-posting forms*. +Meaning, the same URL is used to ``GET`` the form as is used to +``POST`` the form. The route, the view, and the template are the same +whether you are walking up to it the first time or you clicked a button. + +Inside the view we do ``if 'submit' in self.request.params:`` to see if +this form was a ``POST`` where the user clicked on a particular button +``<input name="submit">``. + +The form controller then follows a typical pattern: + +- If you are doing a GET, skip over and just return the form + +- If you are doing a POST, validate the form contents + +- If the form is invalid, bail out by re-rendering the form with the + supplied ``POST`` data + +- If the validation succeeded, perform some action and issue a + redirect via ``HTTPFound``. + +We are, in essence, writing our own form controller. Other +Pyramid-based systems, including ``pyramid_deform``, provide a +form-centric view class which automates much of this branching and +routing. + +Extra Credit +============ + +#. Give a try at a button that goes to a delete view for a + particular wiki page. diff --git a/docs/quick_tutorial/forms/development.ini b/docs/quick_tutorial/forms/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/forms/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/forms/setup.py b/docs/quick_tutorial/forms/setup.py new file mode 100644 index 000000000..361ade013 --- /dev/null +++ b/docs/quick_tutorial/forms/setup.py @@ -0,0 +1,15 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon', + 'deform' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/forms/tutorial/__init__.py b/docs/quick_tutorial/forms/tutorial/__init__.py new file mode 100644 index 000000000..dff7457cf --- /dev/null +++ b/docs/quick_tutorial/forms/tutorial/__init__.py @@ -0,0 +1,13 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('wiki_view', '/') + config.add_route('wikipage_add', '/add') + config.add_route('wikipage_view', '/{uid}') + config.add_route('wikipage_edit', '/{uid}/edit') + config.add_static_view('deform_static', 'deform:static/') + config.scan('.views') + return config.make_wsgi_app() diff --git a/docs/quick_tutorial/forms/tutorial/tests.py b/docs/quick_tutorial/forms/tutorial/tests.py new file mode 100644 index 000000000..5a2c40904 --- /dev/null +++ b/docs/quick_tutorial/forms/tutorial/tests.py @@ -0,0 +1,36 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import WikiViews + + request = testing.DummyRequest() + inst = WikiViews(request) + response = inst.wiki_view() + self.assertEqual(len(response['pages']), 3) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def tearDown(self): + testing.tearDown() + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<title>Wiki: View</title>', res.body) diff --git a/docs/quick_tutorial/forms/tutorial/views.py b/docs/quick_tutorial/forms/tutorial/views.py new file mode 100644 index 000000000..004d2aba9 --- /dev/null +++ b/docs/quick_tutorial/forms/tutorial/views.py @@ -0,0 +1,96 @@ +import colander +import deform.widget + +from pyramid.httpexceptions import HTTPFound +from pyramid.view import view_config + +pages = { + '100': dict(uid='100', title='Page 100', body='<em>100</em>'), + '101': dict(uid='101', title='Page 101', body='<em>101</em>'), + '102': dict(uid='102', title='Page 102', body='<em>102</em>') +} + +class WikiPage(colander.MappingSchema): + title = colander.SchemaNode(colander.String()) + body = colander.SchemaNode( + colander.String(), + widget=deform.widget.RichTextWidget() + ) + + +class WikiViews(object): + def __init__(self, request): + self.request = request + + @property + def wiki_form(self): + schema = WikiPage() + return deform.Form(schema, buttons=('submit',)) + + @property + def reqts(self): + return self.wiki_form.get_widget_resources() + + @view_config(route_name='wiki_view', renderer='wiki_view.pt') + def wiki_view(self): + return dict(pages=pages.values()) + + @view_config(route_name='wikipage_add', + renderer='wikipage_addedit.pt') + def wikipage_add(self): + form = self.wiki_form.render() + + if 'submit' in self.request.params: + controls = self.request.POST.items() + try: + appstruct = self.wiki_form.validate(controls) + except deform.ValidationFailure as e: + # Form is NOT valid + return dict(form=e.render()) + + # Form is valid, make a new identifier and add to list + last_uid = int(sorted(pages.keys())[-1]) + new_uid = str(last_uid + 1) + pages[new_uid] = dict( + uid=new_uid, title=appstruct['title'], + body=appstruct['body'] + ) + + # Now visit new page + url = self.request.route_url('wikipage_view', uid=new_uid) + return HTTPFound(url) + + return dict(form=form) + + @view_config(route_name='wikipage_view', renderer='wikipage_view.pt') + def wikipage_view(self): + uid = self.request.matchdict['uid'] + page = pages[uid] + return dict(page=page) + + @view_config(route_name='wikipage_edit', + renderer='wikipage_addedit.pt') + def wikipage_edit(self): + uid = self.request.matchdict['uid'] + page = pages[uid] + + wiki_form = self.wiki_form + + if 'submit' in self.request.params: + controls = self.request.POST.items() + try: + appstruct = wiki_form.validate(controls) + except deform.ValidationFailure as e: + return dict(page=page, form=e.render()) + + # Change the content and redirect to the view + page['title'] = appstruct['title'] + page['body'] = appstruct['body'] + + url = self.request.route_url('wikipage_view', + uid=page['uid']) + return HTTPFound(url) + + form = wiki_form.render(page) + + return dict(page=page, form=form)
\ No newline at end of file diff --git a/docs/quick_tutorial/forms/tutorial/wiki_view.pt b/docs/quick_tutorial/forms/tutorial/wiki_view.pt new file mode 100644 index 000000000..9e3afe495 --- /dev/null +++ b/docs/quick_tutorial/forms/tutorial/wiki_view.pt @@ -0,0 +1,19 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Wiki: View</title> +</head> +<body> +<h1>Wiki</h1> + +<a href="${request.route_url('wikipage_add')}">Add + WikiPage</a> +<ul> + <li tal:repeat="page pages"> + <a href="${request.route_url('wikipage_view', uid=page.uid)}"> + ${page.title} + </a> + </li> +</ul> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt b/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt new file mode 100644 index 000000000..d1fea0d7f --- /dev/null +++ b/docs/quick_tutorial/forms/tutorial/wikipage_addedit.pt @@ -0,0 +1,22 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>WikiPage: Add/Edit</title> + <tal:block tal:repeat="reqt view.reqts['css']"> + <link rel="stylesheet" type="text/css" + href="${request.static_url('deform:static/' + reqt)}"/> + </tal:block> + <tal:block tal:repeat="reqt view.reqts['js']"> + <script src="${request.static_url('deform:static/' + reqt)}" + type="text/javascript"></script> + </tal:block> +</head> +<body> +<h1>Wiki</h1> + +<p>${structure: form}</p> +<script type="text/javascript"> + deform.load() +</script> +</body> +</html> diff --git a/docs/quick_tutorial/forms/tutorial/wikipage_view.pt b/docs/quick_tutorial/forms/tutorial/wikipage_view.pt new file mode 100644 index 000000000..cb9ff526e --- /dev/null +++ b/docs/quick_tutorial/forms/tutorial/wikipage_view.pt @@ -0,0 +1,17 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>WikiPage: View</title> +</head> +<body> +<a href="${request.route_url('wiki_view')}"> + Up +</a> | +<a href="${request.route_url('wikipage_edit', uid=page.uid)}"> + Edit +</a> + +<h1>${page.title}</h1> +<p>${structure: page.body}</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst new file mode 100644 index 000000000..205ddf5cb --- /dev/null +++ b/docs/quick_tutorial/functional_testing.rst @@ -0,0 +1,70 @@ +.. _qtut_functional_testing: + +=================================== +06: Functional Testing with WebTest +=================================== + +Write end-to-end full-stack testing using ``webtest``. + +Background +========== + +Unit tests are a common and popular approach to test-driven development +(TDD.) In web applications, though, the templating and entire apparatus +of a web site are important parts of the delivered quality. We'd like a +way to test these. + +WebTest is a Python package that does functional testing. With WebTest +you can write tests which simulate a full HTTP request against a WSGI +application, then test the information in the response. For speed +purposes, WebTest skips the setup/teardown of an actual HTTP server, +providing tests that run fast enough to be part of TDD. + +Objectives +========== + +- Write a test which checks the contents of the returned HTML + +Steps +===== + +#. First we copy the results of the previous step, as well as install + the ``webtest`` package: + + .. code-block:: bash + + $ cd ..; cp -r unit_testing functional_testing; cd functional_testing + $ $VENV/bin/python setup.py develop + $ $VENV/bin/easy_install webtest + +#. Let's extend ``unit_testing/tutorial/tests.py`` to include a + functional test: + + .. literalinclude:: functional_testing/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + $ $VENV/bin/nosetests tutorial + . + ---------------------------------------------------------------------- + Ran 2 tests in 0.141s + + OK + +Analysis +======== + +We now have the end-to-end testing we were looking for. WebTest lets us +simply extend our existing ``nose``-based test approach with functional +tests that are reported in the same output. These new tests not only +cover our templating, but they didn't dramatically increase the +execution time of our tests. + +Extra Credit +============ + +#. Why do our functional tests use ``b''``?
\ No newline at end of file diff --git a/docs/quick_tutorial/functional_testing/development.ini b/docs/quick_tutorial/functional_testing/development.ini new file mode 100644 index 000000000..470d92c57 --- /dev/null +++ b/docs/quick_tutorial/functional_testing/development.ini @@ -0,0 +1,40 @@ +[app:main] +use = egg:tutorial +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/functional_testing/setup.py b/docs/quick_tutorial/functional_testing/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/functional_testing/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/functional_testing/tutorial/__init__.py b/docs/quick_tutorial/functional_testing/tutorial/__init__.py new file mode 100644 index 000000000..2b4e84f30 --- /dev/null +++ b/docs/quick_tutorial/functional_testing/tutorial/__init__.py @@ -0,0 +1,13 @@ +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + return Response('<body><h1>Hello World!</h1></body>') + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('hello', '/') + config.add_view(hello_world, route_name='hello') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/functional_testing/tutorial/tests.py b/docs/quick_tutorial/functional_testing/tutorial/tests.py new file mode 100644 index 000000000..4248acbe7 --- /dev/null +++ b/docs/quick_tutorial/functional_testing/tutorial/tests.py @@ -0,0 +1,31 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_hello_world(self): + from tutorial import hello_world + + request = testing.DummyRequest() + response = hello_world(request) + self.assertEqual(response.status_code, 200) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_hello_world(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hello World!</h1>', res.body) diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst new file mode 100644 index 000000000..c7a8eaf5e --- /dev/null +++ b/docs/quick_tutorial/hello_world.rst @@ -0,0 +1,114 @@ +.. _qtut_hello_world: + +================================ +01: Single-File Web Applications +================================ + +What's the simplest way to get started in Pyramid? A single-file module. +No Python packages, no ``setup.py``, no other machinery. + +Background +========== + +Microframeworks are all the rage these days. "Microframework" is a +marketing term, not a technical one. They have a low mental overhead: +they do so little, the only things you have to worry about are *your +things*. + +Pyramid is special because it can act as a single-file module +microframework. You can have a single Python file that can be executed +directly by Python. But Pyramid also provides facilities to scale to +the largest of applications. + +Python has a standard called :term:`WSGI` that defines how +Python web applications plug into standard servers, getting passed +incoming requests and returning responses. Most modern Python web +frameworks obey an "MVC" (model-view-controller) application pattern, +where the data in the model has a view that mediates interaction with +outside systems. + +In this step we'll see a brief glimpse of WSGI servers, WSGI +applications, requests, responses, and views. + +Objectives +========== + +- Get a running Pyramid web application, as simply as possible + +- Use that as a well-understood base for adding each unit of complexity + +- Initial exposure to WSGI apps, requests, views, and responses + +Steps +===== + +#. Make sure you have followed the steps in :doc:`requirements`. + +#. Starting from your workspace directory + (``~/projects/quick_tutorial``), create a directory for this step: + + .. code-block:: bash + + $ mkdir hello_world; cd hello_world + +#. Copy the following into ``hello_world/app.py``: + + .. literalinclude:: hello_world/app.py + :linenos: + +#. Run the application: + + .. code-block:: bash + + $ $VENV/bin/python app.py + +#. Open http://localhost:6543/ in your browser. + +Analysis +======== + +New to Python web programming? If so, some lines in module merit +explanation: + +#. *Line 11*. The ``if __name__ == '__main__':`` is Python's way of + saying "Start here when running from the command line". + +#. *Lines 12-14*. 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 15-17*. 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 :ref:`configuration_narr` is a +central idea in Pyramid, one that we will revisit regularly in this +*Quick Tour*. + +Extra Credit +============ + +#. Why do we do this: + + .. code-block:: python + + print ('Starting up server on http://localhost:6547') + + ...instead of: + + .. code-block:: python + + print 'Starting up server on http://localhost:6547' + +#. What happens if you return a string of HTML? A sequence of integers? + +#. Put something invalid, such as ``print xyz``, in the view function. + Kill your ``python app.py`` with ``cntrl-c`` and restart, + then reload your browser. See the exception in the console? + +#. The ``GI`` in ``WSGI`` stands for "Gateway Interface". What web + standard is this modelled after?
\ No newline at end of file diff --git a/docs/quick_tutorial/hello_world/app.py b/docs/quick_tutorial/hello_world/app.py new file mode 100644 index 000000000..210075023 --- /dev/null +++ b/docs/quick_tutorial/hello_world/app.py @@ -0,0 +1,17 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + print ('Incoming request') + return Response('<body><h1>Hello World!</h1></body>') + + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/') + 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()
\ No newline at end of file diff --git a/docs/quick_tutorial/index.rst b/docs/quick_tutorial/index.rst new file mode 100644 index 000000000..9373fe38a --- /dev/null +++ b/docs/quick_tutorial/index.rst @@ -0,0 +1,50 @@ +.. _quick_tutorial: + +========================== +Quick Tutorial for Pyramid +========================== + +Pyramid is a web framework for Python 2 and 3. This tutorial gives a +Python 3/2-compatible, high-level tour of the major features. + +This hands-on tutorial covers "a little about a lot": practical +introductions to the most common facilities. Fun, fast-paced, and most +certainly not aimed at experts of the Pyramid web framework. + +Contents +======== + +.. toctree:: + :maxdepth: 1 + + requirements + tutorial_approach + scaffolds + hello_world + package + ini + debugtoolbar + unit_testing + functional_testing + views + templating + view_classes + request_response + routing + jinja2 + static_assets + json + more_view_classes + logging + sessions + forms + databases + authentication + authorization + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst new file mode 100644 index 000000000..630b1faa5 --- /dev/null +++ b/docs/quick_tutorial/ini.rst @@ -0,0 +1,146 @@ +.. _qtut_ini: + +================================================= +03: Application Configuration with ``.ini`` Files +================================================= + +Use Pyramid's ``pserve`` command with a ``.ini`` configuration file for +simpler, better application running. + +Background +========== + +Pyramid has a first-class concept of +:ref:`configuration <configuration_narr>` distinct from code. +This approach is optional, but its presence makes it distinct from +other Python web frameworks. It taps into Python's ``setuptools`` +library, which establishes conventions for how Python projects can be +installed and provide "entry points". Pyramid uses an entry point to +let a Pyramid application it where to find the WSGI app. + +Objectives +========== + +- Modify our ``setup.py`` to have an entry point telling Pyramid the + location of the WSGI app + +- Create an application driven by a ``.ini`` file + +- Startup the application with Pyramid's ``pserve`` command + +- Move code into the package's ``__init__.py`` + +Steps +===== + +#. First we copy the results of the previous step: + + .. code-block:: bash + + $ cd ..; cp -r package ini; cd ini + +#. Our ``ini/setup.py`` needs a setuptools "entry point" in the + ``setup()`` function: + + .. literalinclude:: ini/setup.py + :linenos: + +#. We can now install our project, thus generating (or re-generating) an + "egg" at ``ini/tutorial.egg-info``: + + .. code-block:: bash + + $ $VENV/bin/python setup.py develop + +#. Let's make a file ``ini/development.ini`` for our configuration: + + .. literalinclude:: ini/development.ini + :language: ini + :linenos: + +#. We can refactor our startup code from the previous step's ``app.py`` + into ``ini/tutorial/__init__.py``: + + .. literalinclude:: ini/tutorial/__init__.py + :linenos: + +#. Now that ``ini/tutorial/app.py`` isn't used, let's remove it: + + .. code-block:: bash + + $ rm tutorial/app.py + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/. + +Analysis +======== + +Our ``development.ini`` file is read by ``pserve`` and serves to +bootstrap our application. Processing then proceeds as described in +the Pyramid chapter on +:ref:`application startup <startup_chapter>`: + +- ``pserve`` looks for ``[app:main]`` and finds ``use = egg:tutorial`` + +- The projects's ``setup.py`` has defined an "entry point" (lines 9-10) + for the project "main" entry point of ``tutorial:main`` + +- The ``tutorial`` package's ``__init__`` has a ``main`` function + +- This function is invoked, with the values from certain ``.ini`` + sections passed in + +The ``.ini`` file is also used for two other functions: + +- *Choice of WSGI server*. ``[server:main]`` wires up the choice of WSGI + *server* for your WSGI *application*. In this case, we are using + ``wsgiref`` bundled in the Python library. + +- *Python logging*. Pyramid uses Python standard logging, which needs a + number of configuration values. The ``.ini`` serves this function. + This provides the console log output that you see on startup and each + request. + +- *Port number*. ``port = 6543`` tells ``wsgiref`` to listen on port + 6543. + +We moved our startup code from ``app.py`` to the package's +``tutorial/__init__.py``. This isn't necessary, +but it is a common style in Pyramid to take the WSGI app bootstrapping +out of your module's code and put it in the package's ``__init__.py``. + +The ``pserve`` application runner has a number of command-line arguments +and options. We are using ``--reload`` which tells ``pserve`` to watch +the filesystem for changes to relevant code (Python files, the INI file, +etc.) and, when something changes, restart the application. Very handy +during development. + +Extra Credit +============ + +#. If you don't like configuration and/or ``.ini`` files, + could you do this yourself in Python code? + +#. Can we have multiple ``.ini`` configuration files for a project? Why + might you want to do that? + +#. The entry point in ``setup.py`` didn't mention ``__init__.py`` when + it the ``main`` function. Why not? + +.. seealso:: + :ref:`project_narr`, + :ref:`scaffolding_chapter`, + :ref:`what_is_this_pserve_thing`, + :ref:`environment_chapter`, + :ref:`paste_chapter` + +Extra Credit +============ + +#. What is the purpose of ``**settings``? What does the ``**`` signify? diff --git a/docs/quick_tutorial/ini/development.ini b/docs/quick_tutorial/ini/development.ini new file mode 100644 index 000000000..ca7d9bf81 --- /dev/null +++ b/docs/quick_tutorial/ini/development.ini @@ -0,0 +1,38 @@ +[app:main] +use = egg:tutorial + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/ini/setup.py b/docs/quick_tutorial/ini/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/ini/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/ini/tutorial/__init__.py b/docs/quick_tutorial/ini/tutorial/__init__.py new file mode 100644 index 000000000..2b4e84f30 --- /dev/null +++ b/docs/quick_tutorial/ini/tutorial/__init__.py @@ -0,0 +1,13 @@ +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + return Response('<body><h1>Hello World!</h1></body>') + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('hello', '/') + config.add_view(hello_world, route_name='hello') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst new file mode 100644 index 000000000..40d941098 --- /dev/null +++ b/docs/quick_tutorial/jinja2.rst @@ -0,0 +1,98 @@ +.. _qtut_jinja2: + +============================== +12: 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, +used in Flask and modelled 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. + +Objectives +========== + +- Show Pyramid's support for different templating systems + +- Learn about installing Pyramid add-ons + +Steps +===== + +#. In this step let's start by installing the ``pyramid_jinja2`` + add-on, the copying the ``view_class`` step's directory: + + .. code-block:: bash + + $ cd ..; cp -r view_classes jinja2; cd jinja2 + $ $VENV/bin/python setup.py develop + $ $VENV/bin/easy_install pyramid_jinja2 + +#. We need to add an item to ``pyramid.includes`` in + ``jinja2/development.ini``: + + .. literalinclude:: jinja2/development.ini + :language: ini + :linenos: + +#. Our ``jinja2/tutorial/views.py`` simply changes its ``renderer``: + + .. literalinclude:: jinja2/tutorial/views.py + :linenos: + +#. Add ``jinja2/tutorial/home.jinja2`` as a template: + + .. literalinclude:: jinja2/tutorial/home.jinja2 + :language: html + +#. Get the ``pyramid.includes`` into the functional test setup in + ``jinja2/tutorial/tests.py``: + + .. literalinclude:: jinja2/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser. + +Analysis +======== + +Getting a Pyramid add-on into Pyramid is simple. First you use normal +Python package installation tools to install the add-on package into +your Python. You then tell Pyramid's configurator to run the setup code +in the add-on. In this case the setup code told Pyramid to make a new +"renderer" available that looked for ``.jinja2`` file extensions. + +Our view code stayed largely the same. We simply changed the file +extension on the renderer. For the template, the syntax for Chameleon +and Jinja2's basic variable insertion is very similar. + +Our functional tests don't have ``development.ini`` so they needed the +``pyramid.includes`` to be setup in the test setup. + +Extra Credit +============ + +#. Our project now depends on ``pyramid_jinja2``. We installed that + dependency manually. What is another way we could have made the + association? + +#. We used ``development.ini`` to get the :term:`configurator` to + load ``pyramid_jinja2``'s configuration. What is another way could + include it into the config? + +.. seealso:: `Jinja2 homepage <http://jinja.pocoo.org/>`_, + and + :ref:`pyramid_jinja2 Overview <jinja2:overview>` diff --git a/docs/quick_tutorial/jinja2/development.ini b/docs/quick_tutorial/jinja2/development.ini new file mode 100644 index 000000000..c096fa936 --- /dev/null +++ b/docs/quick_tutorial/jinja2/development.ini @@ -0,0 +1,42 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + pyramid_jinja2 + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/jinja2/setup.py b/docs/quick_tutorial/jinja2/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/jinja2/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/jinja2/tutorial/__init__.py b/docs/quick_tutorial/jinja2/tutorial/__init__.py new file mode 100644 index 000000000..013d4538f --- /dev/null +++ b/docs/quick_tutorial/jinja2/tutorial/__init__.py @@ -0,0 +1,9 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/jinja2/tutorial/home.jinja2 b/docs/quick_tutorial/jinja2/tutorial/home.jinja2 new file mode 100644 index 000000000..975323169 --- /dev/null +++ b/docs/quick_tutorial/jinja2/tutorial/home.jinja2 @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: {{ name }}</title> +</head> +<body> +<h1>Hi {{ name }}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/jinja2/tutorial/tests.py b/docs/quick_tutorial/jinja2/tutorial/tests.py new file mode 100644 index 000000000..0b22946f3 --- /dev/null +++ b/docs/quick_tutorial/jinja2/tutorial/tests.py @@ -0,0 +1,50 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.hello() + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + + settings = { + 'pyramid.includes': [ + 'pyramid_jinja2' + ] + } + app = main({}, **settings) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) diff --git a/docs/quick_tutorial/jinja2/tutorial/views.py b/docs/quick_tutorial/jinja2/tutorial/views.py new file mode 100644 index 000000000..fa9ec5121 --- /dev/null +++ b/docs/quick_tutorial/jinja2/tutorial/views.py @@ -0,0 +1,18 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(renderer='home.jinja2') +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello') + def hello(self): + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst new file mode 100644 index 000000000..ece8a61c0 --- /dev/null +++ b/docs/quick_tutorial/json.rst @@ -0,0 +1,103 @@ +.. _qtut_json: + +======================================== +14: Ajax Development With JSON Renderers +======================================== + +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*. + +Background +========== + +As we saw in :doc:`templating`, view declarations can specify a +renderer. Output from the view is then run through the renderer, +which generates and returns the ``Response``. We first used a Chameleon +renderer, then a Jinja2 renderer. + +Renderers aren't limited, however, to templates that generate HTML. +Pyramid supplies a JSON renderer which takes Python data, +serializes it to JSON, and performs some other functions such as +setting the content type. In fact, you can write your own renderer (or +extend a built-in renderer) containing custom logic for your unique +application. + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes json; cd json + $ $VENV/bin/python setup.py develop + +#. We add a new route for ``hello_json`` in + ``json/tutorial/__init__.py``: + + .. literalinclude:: json/tutorial/__init__.py + :linenos: + +#. Rather than implement a new view, we will "stack" another decorator + on the ``hello`` view: + + .. literalinclude:: json/tutorial/views.py + :linenos: + +#. We need a new functional test at the end of + ``json/tutorial/tests.py``: + + .. literalinclude:: json/tutorial/tests.py + :linenos: + +#. Run the tests: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/howdy.json in your browser and you + will see the resulting JSON response. + +Analysis +======== + +Earlier we changed our view functions and methods to return Python +data. This change to a data-oriented view layer made test writing +easier, decoupling the templating from the view logic. + +Since Pyramid has a JSON renderer as well as the templating renderers, +it is an easy step to return JSON. In this case we kept the exact same +view and arranged to return a JSON encoding of the view data. We did +this by: + +- Adding a route to map ``/howdy.json`` to a route name + +- Providing a ``@view_config`` that associated that route name with an + existing view + +- *overriding* the view defaults in the view config that mentions the + ``hello_json`` route, so that when the route is matched, we use the JSON + renderer rather than the ``home.pt`` template renderer that would otherwise + be used. + +In fact, for pure Ajax-style web applications, we could re-use the existing +route by using Pyramid's view predicates to match on the +``Accepts:`` header sent by modern Ajax implementation. + +Pyramid's JSON renderer uses the base Python JSON encoder, +thus inheriting its strengths and weaknesses. For example, +Python can't natively JSON encode DateTime objects. There are a number +of solutions for this in Pyramid, including extending the JSON renderer +with a custom renderer. + +.. seealso:: :ref:`views_which_use_a_renderer`, + :ref:`json_renderer`, and + :ref:`adding_and_overriding_renderers` diff --git a/docs/quick_tutorial/json/development.ini b/docs/quick_tutorial/json/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/json/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/json/setup.py b/docs/quick_tutorial/json/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/json/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/json/tutorial/__init__.py b/docs/quick_tutorial/json/tutorial/__init__.py new file mode 100644 index 000000000..6652544c3 --- /dev/null +++ b/docs/quick_tutorial/json/tutorial/__init__.py @@ -0,0 +1,11 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.add_route('hello_json', 'howdy.json') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/json/tutorial/home.pt b/docs/quick_tutorial/json/tutorial/home.pt new file mode 100644 index 000000000..a0cc08e7a --- /dev/null +++ b/docs/quick_tutorial/json/tutorial/home.pt @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Hi ${name}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/json/tutorial/tests.py b/docs/quick_tutorial/json/tutorial/tests.py new file mode 100644 index 000000000..c3cdacbdb --- /dev/null +++ b/docs/quick_tutorial/json/tutorial/tests.py @@ -0,0 +1,50 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.hello() + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) + + def test_hello_json(self): + res = self.testapp.get('/howdy.json', status=200) + self.assertIn(b'{"name": "Hello View"}', res.body) + self.assertEqual(res.content_type, 'application/json') + diff --git a/docs/quick_tutorial/json/tutorial/views.py b/docs/quick_tutorial/json/tutorial/views.py new file mode 100644 index 000000000..f15e55d1b --- /dev/null +++ b/docs/quick_tutorial/json/tutorial/views.py @@ -0,0 +1,19 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello') + @view_config(route_name='hello_json', renderer='json') + def hello(self): + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst new file mode 100644 index 000000000..0167e5249 --- /dev/null +++ b/docs/quick_tutorial/logging.rst @@ -0,0 +1,79 @@ +.. _qtut_logging: + +============================================ +16: Collecting Application Info With Logging +============================================ + +Capture debugging and error output from your web applications using +standard Python logging. + +Background +========== + +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 problems 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``, 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.) + +Objectives +========== + +- Inspect the configuration setup used for logging + +- Add logging statements to your view code + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes logging; cd logging + $ $VENV/bin/python setup.py develop + +#. Extend ``logging/tutorial/views.py`` to log a message: + + .. literalinclude:: logging/tutorial/views.py + :linenos: + +#. Make sure the tests still pass: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ and http://localhost:6543/howdy + in your browser. Note, both in the console and in the debug + toolbar, the message that you logged. + +Analysis +======== + +Our ``development.ini`` configuration file wires up Python standard +logging for our Pyramid application: + +.. literalinclude:: logging/development.ini + :language: ini + +In this, our ``tutorial`` Python package is setup 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 [tutorial.views][MainThread] In home view + +Also, if you have configured your Pyramid application to use the +``pyramid_debugtoolbar``, logging statements appear in one of its menus. + +.. seealso:: See Also: :ref:`logging_chapter` diff --git a/docs/quick_tutorial/logging/development.ini b/docs/quick_tutorial/logging/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/logging/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/logging/setup.py b/docs/quick_tutorial/logging/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/logging/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/logging/tutorial/__init__.py b/docs/quick_tutorial/logging/tutorial/__init__.py new file mode 100644 index 000000000..c3e1c9eef --- /dev/null +++ b/docs/quick_tutorial/logging/tutorial/__init__.py @@ -0,0 +1,10 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/logging/tutorial/home.pt b/docs/quick_tutorial/logging/tutorial/home.pt new file mode 100644 index 000000000..a0cc08e7a --- /dev/null +++ b/docs/quick_tutorial/logging/tutorial/home.pt @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Hi ${name}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/logging/tutorial/tests.py b/docs/quick_tutorial/logging/tutorial/tests.py new file mode 100644 index 000000000..4381235ec --- /dev/null +++ b/docs/quick_tutorial/logging/tutorial/tests.py @@ -0,0 +1,44 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.hello() + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) diff --git a/docs/quick_tutorial/logging/tutorial/views.py b/docs/quick_tutorial/logging/tutorial/views.py new file mode 100644 index 000000000..63d95f405 --- /dev/null +++ b/docs/quick_tutorial/logging/tutorial/views.py @@ -0,0 +1,23 @@ +import logging +log = logging.getLogger(__name__) + +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + log.debug('In home view') + return {'name': 'Home View'} + + @view_config(route_name='hello') + def hello(self): + log.debug('In hello view') + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst new file mode 100644 index 000000000..2792869ac --- /dev/null +++ b/docs/quick_tutorial/more_view_classes.rst @@ -0,0 +1,182 @@ +.. _qtut_more_view_classes: + +========================== +15: More With View Classes +========================== + +Group views into a class, sharing configuration, state, and logic. + +Background +========== + +As part of its mission to help build more ambitious web applications, +Pyramid provides many more features for views and view classes. + +The Pyramid documentation discusses views as a Python "callable". This +callable can be a function, an object with an ``__call__``, +or a Python class. In this last case, methods on the class can be +decorated with ``@view_config`` to register the class methods with the +:term:`configurator` as a view. + +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: + +- Group views + +- Centralize some repetitive defaults + +- Share some state and helpers + +Pyramid views have +:ref:`view predicates <view_configuration_parameters>` that +help determine which view is matched to a request. These predicates +provide many axes of flexibility. + +The following shows a simple example with four operations operations: +view a home page which leads to a form, save a change, +and press the delete button. + +Objectives +========== + +- Group related views into a view class + +- Centralize configuration with class-level ``@view_defaults`` + +- Dispatch one route/URL to multiple views based on request data + +- Share stated and logic between views and templates via the view class + +Steps +===== + +#. First we copy the results of the previous step: + + .. code-block:: bash + + $ cd ..; cp -r templating more_view_classes; cd more_view_classes + $ $VENV/bin/python setup.py develop + +#. Our route in ``more_view_classes/tutorial/__init__.py`` needs some + replacement patterns: + + .. literalinclude:: more_view_classes/tutorial/__init__.py + :linenos: + +#. Our ``more_view_classes/tutorial/views.py`` now has a view class with + several views: + + .. literalinclude:: more_view_classes/tutorial/views.py + :linenos: + +#. Our primary view needs a template at + ``more_view_classes/tutorial/home.pt``: + + .. literalinclude:: more_view_classes/tutorial/home.pt + :language: html + +#. Ditto for our other view from the previous section at + ``more_view_classes/tutorial/hello.pt``: + + .. literalinclude:: more_view_classes/tutorial/hello.pt + :language: html + +#. We have an edit view that also needs a template at + ``more_view_classes/tutorial/edit.pt``: + + .. literalinclude:: more_view_classes/tutorial/edit.pt + :language: html + +#. And finally the delete view's template at + ``more_view_classes/tutorial/delete.pt``: + + .. literalinclude:: more_view_classes/tutorial/delete.pt + :language: html + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/howdy/jane/doe in your browser. Click + the ``Save`` and ``Delete`` buttons and watch the output in the + console window. + +Analysis +======== + +As you can see, the four views are logically grouped together. +Specifically: + +- We have a ``home`` view available at http://localhost:6543/ with + a clickable link to the ``hello`` view. + +- The second view is returned when you go to ``/howdy/jane/doe``. This + URL is + mapped to the ``hello`` route that we centrally set using the optional + ``@view_defaults``. + +- The third view is returned when the form is submitted with a ``POST`` + method. This rule is specified in the ``@view_config`` for that view. + +- The fourth view is returned when clicking on a button such + as ``<input type="submit" name="form.delete" value="Delete"/>``. + +In this step we show using the following information as criteria to +decide which view to use: + +- Method of the HTTP request (``GET``, ``POST``, etc.) + +- Parameter information in the request (submitted form field names) + +We also centralize part of the view configuration to the class level +with ``@view_defaults``, then in one view, override that default just +for that one view. Finally, we put this commonality between views to +work in the view class by sharing: + +- State assigned in ``TutorialViews.__init__`` + +- A computed value + +These are then available both in the view methods but also in the +templates (e.g. ``${view.view_name}`` and ``${view.full_name}``. + +As a note, we made a switch in our templates on how we generate URLs. +We previously hardcode the URLs, such as:: + + <a href="/howdy/jane/doe">Howdy</a> + +In ``home.pt`` we switched to:: + + <a href="${request.route_url('hello', first='jane', + last='doe')}">form</a> + +Pyramid has rich facilities to help generate URLs in a flexible, +non-error-prone fashion. + +Extra Credit +============ + +#. Why could our template do ``${view.full_name}`` and not have to do + ``${view.full_name()}``? + +#. The ``edit`` and ``delete`` views are both submitted to with + ``POST``. Why does the ``edit`` view configuration not catch the + the ``POST`` used by ``delete``? + +#. We used Python ``@property`` on ``full_name``. If we reference this + many times in a template or view code, it would re-compute this + every time. Does Pyramid provide something that will cache the initial + computation on a property? + +#. Can you associate more than one route with the same view? + +#. There is also a ``request.route_path`` API. How does this differ from + ``request.route_url``? + +.. seealso:: :ref:`class_as_view`, `Weird Stuff You Can Do With + URL Dispatch <http://www.plope.com/weird_pyramid_urldispatch>`_ diff --git a/docs/quick_tutorial/more_view_classes/development.ini b/docs/quick_tutorial/more_view_classes/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/more_view_classes/setup.py b/docs/quick_tutorial/more_view_classes/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/more_view_classes/tutorial/__init__.py b/docs/quick_tutorial/more_view_classes/tutorial/__init__.py new file mode 100644 index 000000000..9c1bcec06 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/__init__.py @@ -0,0 +1,10 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy/{first}/{last}') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/more_view_classes/tutorial/delete.pt b/docs/quick_tutorial/more_view_classes/tutorial/delete.pt new file mode 100644 index 000000000..67cc8bf09 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/delete.pt @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${page_title}</title> +</head> +<body> +<h1>${view.view_name} - ${page_title}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/more_view_classes/tutorial/edit.pt b/docs/quick_tutorial/more_view_classes/tutorial/edit.pt new file mode 100644 index 000000000..1bd204065 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/edit.pt @@ -0,0 +1,10 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${view.view_name} - ${page_title}</title> +</head> +<body> +<h1>${view.view_name} - ${page_title}</h1> +<p>You submitted <code>${new_name}</code></p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/more_view_classes/tutorial/hello.pt b/docs/quick_tutorial/more_view_classes/tutorial/hello.pt new file mode 100644 index 000000000..8a39aed09 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/hello.pt @@ -0,0 +1,16 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${view.view_name} - ${page_title}</title> +</head> +<body> +<h1>${view.view_name} - ${page_title}</h1> +<p>Welcome, ${view.full_name}</p> +<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"/> +</form> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/more_view_classes/tutorial/home.pt b/docs/quick_tutorial/more_view_classes/tutorial/home.pt new file mode 100644 index 000000000..fa9016705 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/home.pt @@ -0,0 +1,12 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${view.view_name} - ${page_title}</title> +</head> +<body> +<h1>${view.view_name} - ${page_title}</h1> + +<p>Go to the <a href="${request.route_url('hello', first='jane', + last='doe')}">form</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/more_view_classes/tutorial/tests.py b/docs/quick_tutorial/more_view_classes/tutorial/tests.py new file mode 100644 index 000000000..dca8d7f7b --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/tests.py @@ -0,0 +1,31 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['page_title']) + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'TutorialViews - Home View', res.body) diff --git a/docs/quick_tutorial/more_view_classes/tutorial/views.py b/docs/quick_tutorial/more_view_classes/tutorial/views.py new file mode 100644 index 000000000..fdba04ba8 --- /dev/null +++ b/docs/quick_tutorial/more_view_classes/tutorial/views.py @@ -0,0 +1,39 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(route_name='hello') +class TutorialViews: + def __init__(self, request): + self.request = request + self.view_name = 'TutorialViews' + + @property + def full_name(self): + first = self.request.matchdict['first'] + last = self.request.matchdict['last'] + return first + ' ' + last + + @view_config(route_name='home', renderer='home.pt') + def home(self): + return {'page_title': 'Home View'} + + + # Retrieving /howdy/first/last the first time + @view_config(renderer='hello.pt') + def hello(self): + return {'page_title': 'Hello View'} + + # Posting to /home via the "Edit" submit button + @view_config(request_method='POST', renderer='edit.pt') + def edit(self): + new_name = self.request.params['new_name'] + return {'page_title': 'Edit View', 'new_name': new_name} + + # Posting to /home via the "Delete" submit button + @view_config(request_param='form.delete', renderer='delete.pt') + def delete(self): + print ('Deleted') + return {'page_title': 'Delete View'} diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst new file mode 100644 index 000000000..90d022b29 --- /dev/null +++ b/docs/quick_tutorial/package.rst @@ -0,0 +1,112 @@ +============================================ +02: Python Packages for Pyramid Applications +============================================ + +Most modern Python development is done using Python packages, an approach +Pyramid puts to good use. In this step we re-do "Hello World" as a +minimum Python package inside a minimum Python project. + +Background +========== + +Python developers can organize a collection of modules and files into a +namespaced unit called a :ref:`package <python:tut-packages>`. If a +directory is on ``sys.path`` and has a special file named +``__init__.py``, it is treated as a Python package. + +Packages can be bundled up, made available for installation, +and installed through a (muddled, but improving) toolchain oriented +around a ``setup.py`` file for a +`setuptools project <http://pythonhosted.org/setuptools/setuptools.html>`_. +Explaining it all in this +tutorial will induce madness. For this tutorial, this is all you need to +know: + +- We will have a directory for each tutorial step as a + setuptools *project* + +- This project will contain a ``setup.py`` which injects the features + of the setuptool's project machinery into the directory + +- In this project we will make a ``tutorial`` subdirectory into a Python + *package* using an ``__init__.py`` Python module file + +- We will run ``python setup.py develop`` to install our project in + development mode + +In summary: + +- You'll do your development in a Python *package* + +- That package will be part of a setuptools *project* + +Objectives +========== + +- Make a Python "package" directory with an ``__init__.py`` + +- Get a minimum Python "project" in place by making a ``setup.py`` + +- Install our ``tutorial`` project in development mode + +Steps +===== + +#. Make an area for this tutorial step: + + .. code-block:: bash + + $ cd ..; mkdir package; cd package + +#. In ``package/setup.py``, enter the following: + + .. literalinclude:: package/setup.py + +#. Make the new project installed for development then make a directory + for the actual code: + + .. code-block:: bash + + $ $VENV/bin/python setup.py develop + $ mkdir tutorial + +#. Enter the following into ``package/tutorial/__init__.py``: + + .. literalinclude:: package/tutorial/__init__.py + +#. Enter the following into ``package/tutorial/app.py``: + + .. literalinclude:: package/tutorial/app.py + +#. Run the WSGI application with: + + .. code-block:: bash + + $ $VENV/bin/python tutorial/app.py + +#. Open http://localhost:6543/ in your browser. + +Analysis +======== + +Python packages give us an organized unit of project development. +Python projects, via ``setup.py``, gives us special features when +our package is installed (in this case, in local development mode.) + +In this step we have a Python package called ``tutorial``. We use the +same name in each step of the tutorial, to avoid unnecessary re-typing. + +Above this ``tutorial`` directory we have the files that handle the +packaging of this, well, package. At the moment, all we need is a +bare-bones ``ini/setup.py``. + +Everything else is the same about our application. We simply made a +Python package with a ``setup.py`` and installed it in development mode. + +Note that the way we're running the app (``python tutorial/app.py``) is a bit +of an odd duck. We would never do this unless we were writing a tutorial that +tries to capture how this stuff works a step at a time. It's generally a bad +idea to run a Python module inside a package directly as a script. + +.. seealso:: :ref:`Python Packages <python:tut-packages>`, + `setuptools Entry Points <http://pythonhosted.org/setuptools/pkg_resources.html#entry-points>`_ diff --git a/docs/quick_tutorial/package/setup.py b/docs/quick_tutorial/package/setup.py new file mode 100644 index 000000000..bcfcfa684 --- /dev/null +++ b/docs/quick_tutorial/package/setup.py @@ -0,0 +1,9 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/package/tutorial/__init__.py b/docs/quick_tutorial/package/tutorial/__init__.py new file mode 100644 index 000000000..d310fdde9 --- /dev/null +++ b/docs/quick_tutorial/package/tutorial/__init__.py @@ -0,0 +1 @@ +# package
\ No newline at end of file diff --git a/docs/quick_tutorial/package/tutorial/app.py b/docs/quick_tutorial/package/tutorial/app.py new file mode 100644 index 000000000..210075023 --- /dev/null +++ b/docs/quick_tutorial/package/tutorial/app.py @@ -0,0 +1,17 @@ +from wsgiref.simple_server import make_server +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + print ('Incoming request') + return Response('<body><h1>Hello World!</h1></body>') + + +if __name__ == '__main__': + config = Configurator() + config.add_route('hello', '/') + 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()
\ No newline at end of file diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst new file mode 100644 index 000000000..504803804 --- /dev/null +++ b/docs/quick_tutorial/request_response.rst @@ -0,0 +1,103 @@ +.. _qtut_request_response: + +======================================= +10: Handling Web Requests and Responses +======================================= + +Web applications handle incoming requests and return outgoing responses. +Pyramid makes working with requests and responses convenient and +reliable. + +Objectives +========== + +- Learn the background on Pyramid's choices for requests and responses + +- Grab data out of the request + +- Change information in the response headers + +Background +========== + +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 and returning web +responses. + +Pyramid has always fit nicely into the existing world of Python web +development (virtual environments, packaging, scaffolding, +first to embrace Python 3, etc.) For request handling, 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>`. + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes request_response; cd request_response + $ $VENV/bin/python setup.py develop + +#. Simplify the routes in ``request_response/tutorial/__init__.py``: + + .. literalinclude:: request_response/tutorial/__init__.py + +#. We only need one view in ``request_response/tutorial/views.py``: + + .. literalinclude:: request_response/tutorial/views.py + +#. Update the tests in ``request_response/tutorial/tests.py``: + + .. literalinclude:: request_response/tutorial/tests.py + +#. Now run the tests: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser. You will be + redirected to http://localhost:6543/plain + +#. Open http://localhost:6543/plain?name=alice in your browser. + +Analysis +======== + +In this view class we have two routes and two views, with the first +leading to the second by an HTTP redirect. Pyramid can +:ref:`generate redirects <http_redirect>` by returning a +special object from a view or raising a special exception. + +In this Pyramid view, we get the URL being visited from ``request.url``. +Also, if you visited http://localhost:6543/plain?name=alice, +the name is included in the body of the response:: + + URL http://localhost:6543/plain?name=alice with name: alice + +Finally, we set the response's content type and body, then return the +Response. + +We updated the unit and functional tests to prove that our code +does the redirection, but also handles sending and not sending +``/plain?name``. + +Extra Credit +============ + +#. Could we also ``raise HTTPFound(location='/plain')`` instead of + returning it? If so, what's the difference? + +.. seealso:: :ref:`webob_chapter`, + :ref:`generate redirects <http_redirect>` diff --git a/docs/quick_tutorial/request_response/development.ini b/docs/quick_tutorial/request_response/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/request_response/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/request_response/setup.py b/docs/quick_tutorial/request_response/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/request_response/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/request_response/tutorial/__init__.py b/docs/quick_tutorial/request_response/tutorial/__init__.py new file mode 100644 index 000000000..77a172888 --- /dev/null +++ b/docs/quick_tutorial/request_response/tutorial/__init__.py @@ -0,0 +1,9 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('home', '/') + config.add_route('plain', '/plain') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/request_response/tutorial/tests.py b/docs/quick_tutorial/request_response/tutorial/tests.py new file mode 100644 index 000000000..7486c2b2d --- /dev/null +++ b/docs/quick_tutorial/request_response/tutorial/tests.py @@ -0,0 +1,54 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual(response.status, '302 Found') + + def test_plain_without_name(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.plain() + self.assertIn(b'No Name Provided', response.body) + + def test_plain_with_name(self): + from .views import TutorialViews + + request = testing.DummyRequest() + request.GET['name'] = 'Jane Doe' + inst = TutorialViews(request) + response = inst.plain() + self.assertIn(b'Jane Doe', response.body) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_plain_without_name(self): + res = self.testapp.get('/plain', status=200) + self.assertIn(b'No Name Provided', res.body) + + def test_plain_with_name(self): + res = self.testapp.get('/plain?name=Jane%20Doe', status=200) + self.assertIn(b'Jane Doe', res.body) diff --git a/docs/quick_tutorial/request_response/tutorial/views.py b/docs/quick_tutorial/request_response/tutorial/views.py new file mode 100644 index 000000000..8c7ff5f37 --- /dev/null +++ b/docs/quick_tutorial/request_response/tutorial/views.py @@ -0,0 +1,22 @@ +from pyramid.httpexceptions import HTTPFound +from pyramid.response import Response +from pyramid.view import view_config + + +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + return HTTPFound(location='/plain') + + @view_config(route_name='plain') + def plain(self): + name = self.request.params.get('name', 'No Name Provided') + + body = 'URL %s with name: %s' % (self.request.url, name) + return Response( + content_type='text/plain', + body=body + ) diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst new file mode 100644 index 000000000..40e818807 --- /dev/null +++ b/docs/quick_tutorial/requirements.rst @@ -0,0 +1,250 @@ +.. _qtut_requirements: + +============ +Requirements +============ + +Let's get our tutorial environment setup. Most of the setup work is in +standard Python development practices (install Python, +make an isolated environment, and setup packaging tools.) + +.. note:: + + Pyramid encourages standard Python development practices with + packaging tools, virtual environments, logging, and so on. There + are many variations, implementations, and opinions across the Python + community. For consistency, ease of documentation maintenance, + and to minimize confusion, the Pyramid *documentation* has adopted + specific conventions. + +This *Quick Tutorial* is based on: + +* **Python 3.3**. Pyramid fully supports Python 3.2+ 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, + we use Python 3.3's built-in solution, the ``pyvenv`` command. + For Python 2.7, you can install ``virtualenv``. + +* **setuptools and easy_install**. We use + `setuptools <https://pypi.python.org/pypi/setuptools/>`_ + and its ``easy_install`` for package management. + +* **Workspaces, projects, and packages.** Our home directory + will contain a *tutorial workspace* with our Python virtual + environment(s) and *Python projects* (a directory with packaging + information and *Python packages* of working code.) + +* **Unix commands**. Commands in this tutorial use UNIX syntax and + paths. Windows users should adjust commands accordingly. + +.. note:: + + Pyramid was one of the first web frameworks to fully support Python 3 in + October 2011. + +Steps +===== + +#. :ref:`install-python-3.3-or-greater` +#. :ref:`create-a-project-directory-structure` +#. :ref:`set-an-environment-variable` +#. :ref:`create-a-virtual-environment` +#. :ref:`install-setuptools-(python-packaging-tools)` +#. :ref:`install-pyramid` + +.. _install-python-3.3-or-greater: + +Install Python 3.3 or greater +----------------------------- + +Download the latest standard Python 3.3+ release (not development +release) from +`python.org <http://www.python.org/download/releases/>`_. On that page, you +must click the latest version, then scroll down to the "Downloads" section +for your operating system. + +Windows and Mac OS X users can download and run an installer. + +Windows users should also install the `Python for Windows extensions +<http://sourceforge.net/projects/pywin32/files/pywin32/>`_. Carefully read the +``README.txt`` file at the end of the list of builds, and follow its +directions. Make sure you get the proper 32- or 64-bit build and Python +version. + +Linux users can either use their package manager to install Python 3.3 +or may +`build Python 3.3 from source +<http://pyramid.readthedocs.org/en/master/narr/install.html#package-manager- +method>`_. + + +.. _create-a-project-directory-structure: + +Create a project directory structure +------------------------------------ + +We will arrive at a directory structure of +``workspace->project->package``, with our workspace named +``quick_tutorial``. The following diagram shows how this is structured +and where our virtual environment will reside: + +.. figure:: ../_static/directory_structure_pyramid.png + :alt: Final directory structure + + Final directory structure. + +For Linux, the commands to do so are as follows: + +.. code-block:: bash + + # Mac and Linux + $ cd ~ + $ mkdir -p projects/quick_tutorial + $ cd projects/quick_tutorial + +For Windows: + +.. code-block:: posh + + # Windows + c:\> cd \ + c:\> mkdir projects\quick_tutorial + c:\> cd projects\quick_tutorial + +In the above figure, your user home directory is represented by ``~``. In +your home directory, all of your projects are in the ``projects`` directory. +This is a general convention not specific to Pyramid that many developers use. +Windows users will do well to use ``c:\`` as the location for ``projects`` in +order to avoid spaces in any of the path names. + +Next within ``projects`` is your workspace directory, here named +``quick_tutorial``. A workspace is a common term used by integrated +development environments (IDE) like PyCharm and PyDev that stores +isolated Python environments (virtualenvs) and specific project files +and repositories. + + +.. _set-an-environment-variable: + +Set an Environment Variable +--------------------------- + +This tutorial will refer frequently to the location of the virtual +environment. We set an environment variable to save typing later. + +.. code-block:: bash + + # Mac and Linux + $ export VENV=~/projects/quick_tutorial/env33/ + + # Windows + # TODO: This command does not work + c:\> set VENV=c:\projects\quick_tutorial\env33 + + +.. _create-a-virtual-environment: + +Create a Virtual Environment +---------------------------- + +.. warning:: The current state of isolated Python environments using + ``pyvenv`` on Windows is suboptimal in comparison to Mac and Linux. See + http://stackoverflow.com/q/15981111/95735 for a discussion of the issue + and `PEP 453 <http://www.python.org/dev/peps/pep-0453/>`_ for a proposed + resolution. + +``pyvenv`` is a tool to create isolated Python 3.3 environments, each +with its own Python binary and independent set of installed Python +packages in its site directories. Let's create one, using the location +we just specified in the environment variable. + +.. code-block:: bash + + # Mac and Linux + $ pyvenv $VENV + + # Windows + c:\> c:\Python33\python -m venv %VENV% + +.. seealso:: See also Python 3's :mod:`venv module <python3:venv>`, + Python 2's `virtualenv <http://www.virtualenv.org/en/latest/>`_ + package, + :ref:`Installing Pyramid on a Windows System <installing_windows>` + + +.. _install-setuptools-(python-packaging-tools): + +Install ``setuptools`` (Python packaging tools) +----------------------------------------------- + +The following command will download a script to install ``setuptools``, then +pipe it to your environment's version of Python. + +.. code-block:: bash + + # Mac and Linux + $ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python + + # Windows + # Use your browser to download: + # https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.p + # ...into c:\projects\quick_tutorial\ez_setup.py + c:\> %VENV%\Scripts\python ez_setup.py + +If ``wget`` complains with a certificate error, then run this command instead: + +.. code-block:: bash + + # Mac and Linux + $ wget --no-check-certificate https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | $VENV/bin/python + + +.. _install-pyramid: + +Install Pyramid +--------------- + +We have our Python standard prerequisites out of the way. The Pyramid +part is pretty easy: + +.. parsed-literal:: + + # Mac and Linux + $ $VENV/bin/easy_install "pyramid==\ |release|\ " + + # Windows + c:\\> %VENV%\\Scripts\\easy_install "pyramid==\ |release|\ " + +Our Python virtual environment now has the Pyramid software available. + +You can optionally install some of the extra Python packages used +during this tutorial: + +.. code-block:: bash + + # Mac and Linux + $ $VENV/bin/easy_install nose webtest deform sqlalchemy \ + pyramid_chameleon pyramid_debugtoolbar waitress \ + pyramid_jinja2 pyramid_tm zope.sqlalchemy pysqlite + + # Windows + c:\> %VENV%\Scripts\easy_install nose webtest deform sqlalchemy pyramid_chameleon + + + +.. note:: + + Why ``easy_install`` and not ``pip``? Pyramid encourages use of namespace + packages which, until recently, ``pip`` didn't permit. Also, Pyramid has + some optional C extensions for performance. With ``easy_install``, Windows + users can get these extensions without needing a C compiler. + +.. seealso:: See Also: :ref:`installing_unix`. For instructions to set up your + Python environment for development using Windows or Python 2, see Pyramid's + :ref:`Before You Install <installing_chapter>`. + + See also Python 3's :mod:`venv module <python3:venv>`, the `setuptools` `installation instructions + <https://pypi.python.org/pypi/setuptools/0.9.8#installation-instructions>`_, + and `easy_install help <https://pypi.python.org/pypi/setuptools/0.9.8#using-setuptools-and-easyinstall>`_. + diff --git a/docs/quick_tutorial/routing.rst b/docs/quick_tutorial/routing.rst new file mode 100644 index 000000000..54dff5c39 --- /dev/null +++ b/docs/quick_tutorial/routing.rst @@ -0,0 +1,121 @@ +.. _qtut_routing: + +========================================== +11: Dispatching URLs To Views With Routing +========================================== + +Routing matches incoming URL patterns to view code. Pyramid's routing +has a number of useful features. + +Background +========== + +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. + +Previously we saw the basics of routing URLs to views in + +- 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 + +.. 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. It's relatively easy to build a system that uses implicit route + ordering with Pyramid too. See `The Groundhog series of screencasts + <http://bfg.repoze.org/videos#groundhog1>`_ if you're interested in + doing so. + +Objectives +========== + +- Define a route that extracts part of the URL into a Python dictionary + +- Use that dictionary data in a view + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes routing; cd routing + $ $VENV/bin/python setup.py develop + +#. Our ``routing/tutorial/__init__.py`` needs a route with a replacement + pattern: + + .. literalinclude:: routing/tutorial/__init__.py + :linenos: + +#. We just need one view in ``routing/tutorial/views.py``: + + .. literalinclude:: routing/tutorial/views.py + :linenos: + +#. We just need one view in ``routing/tutorial/home.pt``: + + .. literalinclude:: routing/tutorial/home.pt + :language: html + :linenos: + +#. Update ``routing/tutorial/tests.py``: + + .. literalinclude:: routing/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/howdy/amy/smith in your browser. + +Analysis +======== + +In ``__init__.py`` we see an important change in our route declaration: + +.. code-block:: python + + config.add_route('hello', '/howdy/{first}/{last}') + +With this we tell the :term:`configurator` that our URL has +a "replacement pattern". 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: + +.. code-block:: python + + self.request.matchdict['first'] + self.request.matchdict['last'] + +``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 anywhere in Pyramid that has access +to the request. + +Extra Credit +============ + +#. What happens if you to go the URL + http://localhost:6543/howdy? Is this the result that you + expected? + +.. seealso:: `Weird Stuff You Can Do With URL + Dispatch <http://www.plope.com/weird_pyramid_urldispatch>`_ diff --git a/docs/quick_tutorial/routing/development.ini b/docs/quick_tutorial/routing/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/routing/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/routing/setup.py b/docs/quick_tutorial/routing/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/routing/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/routing/tutorial/__init__.py b/docs/quick_tutorial/routing/tutorial/__init__.py new file mode 100644 index 000000000..4b2dac36d --- /dev/null +++ b/docs/quick_tutorial/routing/tutorial/__init__.py @@ -0,0 +1,9 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/howdy/{first}/{last}') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/routing/tutorial/home.pt b/docs/quick_tutorial/routing/tutorial/home.pt new file mode 100644 index 000000000..f2b991059 --- /dev/null +++ b/docs/quick_tutorial/routing/tutorial/home.pt @@ -0,0 +1,10 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>${name}</h1> +<p>First: ${first}, Last: ${last}</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/routing/tutorial/tests.py b/docs/quick_tutorial/routing/tutorial/tests.py new file mode 100644 index 000000000..572f389fb --- /dev/null +++ b/docs/quick_tutorial/routing/tutorial/tests.py @@ -0,0 +1,36 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + request.matchdict['first'] = 'First' + request.matchdict['last'] = 'Last' + inst = TutorialViews(request) + response = inst.home() + self.assertEqual(response['first'], 'First') + self.assertEqual(response['last'], 'Last') + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/howdy/Jane/Doe', status=200) + self.assertIn(b'Jane', res.body) + self.assertIn(b'Doe', res.body) diff --git a/docs/quick_tutorial/routing/tutorial/views.py b/docs/quick_tutorial/routing/tutorial/views.py new file mode 100644 index 000000000..8a9211e92 --- /dev/null +++ b/docs/quick_tutorial/routing/tutorial/views.py @@ -0,0 +1,20 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + first = self.request.matchdict['first'] + last = self.request.matchdict['last'] + return { + 'name': 'Home View', + 'first': first, + 'last': last + } diff --git a/docs/quick_tutorial/scaffolds.rst b/docs/quick_tutorial/scaffolds.rst new file mode 100644 index 000000000..8ca2d27df --- /dev/null +++ b/docs/quick_tutorial/scaffolds.rst @@ -0,0 +1,86 @@ +.. _qtut_scaffolds: + +============================================= +Prelude: Quick Project Startup with Scaffolds +============================================= + +To ease the process of getting started, Pyramid provides *scaffolds* +that generate sample projects from templates in Pyramid and Pyramid +add-ons. + +Background +========== + +We're going to cover a lot in this tutorial, focusing on one topic at a +time and writing everything from scratch. As a warmup, though, +it sure would be nice to see some pixels on a screen. + +Like other web development frameworks, Pyramid provides a number of +"scaffolds" that generate working Python, template, and CSS code for +sample applications. In this step we'll use a built-in scaffold to let +us preview a Pyramid application, before starting from scratch on Step 1. + +Objectives +========== + +- Use Pyramid's ``pcreate`` command to list scaffolds and make a new + project + +- Start up a Pyramid application and visit it in a web browser + +Steps +===== + +#. Pyramid's ``pcreate`` command can list the available scaffolds: + + .. code-block:: bash + + $ $VENV/bin/pcreate --list + Available scaffolds: + alchemy: Pyramid SQLAlchemy project using url dispatch + starter: Pyramid starter project + zodb: Pyramid ZODB project using traversal + +#. Tell ``pcreate`` to use the ``starter`` scaffold to make our project: + + .. code-block:: bash + + $ $VENV/bin/pcreate --scaffold starter scaffolds + +#. Use normal Python development to setup our project for development: + + .. code-block:: bash + + $ cd scaffolds + $ $VENV/bin/python setup.py develop + +#. Startup the application by pointing Pyramid's ``pserve`` command at + the project's (generated) configuration file: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + + On startup, ``pserve`` logs some output: + + .. code-block:: bash + + Starting subprocess with file monitor + Starting server in PID 72213. + Starting HTTP server on http://0.0.0.0:6543 + +#. Open http://localhost:6543/ in your browser. + +Analysis +======== + +Rather than starting from scratch, ``pcreate`` can make getting a +Python project containing a Pyramid application a quick matter. +Pyramid ships with a few scaffolds. But installing a Pyramid add-on can +give you new scaffolds from that add-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 is passed a configuration +file (in this case, ``development.ini``.) diff --git a/docs/quick_tutorial/scaffolds/CHANGES.txt b/docs/quick_tutorial/scaffolds/CHANGES.txt new file mode 100644 index 000000000..35a34f332 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/CHANGES.txt @@ -0,0 +1,4 @@ +0.0 +--- + +- Initial version diff --git a/docs/quick_tutorial/scaffolds/MANIFEST.in b/docs/quick_tutorial/scaffolds/MANIFEST.in new file mode 100644 index 000000000..91d3f763b --- /dev/null +++ b/docs/quick_tutorial/scaffolds/MANIFEST.in @@ -0,0 +1,2 @@ +include *.txt *.ini *.cfg *.rst +recursive-include scaffolds *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml diff --git a/docs/quick_tutorial/scaffolds/README.txt b/docs/quick_tutorial/scaffolds/README.txt new file mode 100644 index 000000000..7776dd2d5 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/README.txt @@ -0,0 +1 @@ +scaffolds README diff --git a/docs/quick_tutorial/scaffolds/development.ini b/docs/quick_tutorial/scaffolds/development.ini new file mode 100644 index 000000000..b31d06194 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/development.ini @@ -0,0 +1,60 @@ +### +# app configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html +### + +[app:main] +use = egg:scaffolds + +pyramid.reload_templates = true +pyramid.debug_authorization = false +pyramid.debug_notfound = false +pyramid.debug_routematch = false +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:waitress#main +host = 0.0.0.0 +port = 6543 + +### +# logging configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html +### + +[loggers] +keys = root, scaffolds + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[logger_scaffolds] +level = DEBUG +handlers = +qualname = scaffolds + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s diff --git a/docs/quick_tutorial/scaffolds/production.ini b/docs/quick_tutorial/scaffolds/production.ini new file mode 100644 index 000000000..1418e6bf6 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/production.ini @@ -0,0 +1,54 @@ +### +# app configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/environment.html +### + +[app:main] +use = egg:scaffolds + +pyramid.reload_templates = false +pyramid.debug_authorization = false +pyramid.debug_notfound = false +pyramid.debug_routematch = false +pyramid.default_locale_name = en + +### +# wsgi server configuration +### + +[server:main] +use = egg:waitress#main +host = 0.0.0.0 +port = 6543 + +### +# logging configuration +# http://docs.pylonsproject.org/projects/pyramid/en/latest/narr/logging.html +### + +[loggers] +keys = root, scaffolds + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARN +handlers = console + +[logger_scaffolds] +level = WARN +handlers = +qualname = scaffolds + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s diff --git a/docs/quick_tutorial/scaffolds/scaffolds/__init__.py b/docs/quick_tutorial/scaffolds/scaffolds/__init__.py new file mode 100644 index 000000000..ad5ecbc6f --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/__init__.py @@ -0,0 +1,12 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + """ This function returns a Pyramid WSGI application. + """ + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_static_view('static', 'static', cache_max_age=3600) + config.add_route('home', '/') + config.scan() + return config.make_wsgi_app() diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/favicon.ico b/docs/quick_tutorial/scaffolds/scaffolds/static/favicon.ico Binary files differnew file mode 100644 index 000000000..71f837c9e --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/favicon.ico diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/footerbg.png b/docs/quick_tutorial/scaffolds/scaffolds/static/footerbg.png Binary files differnew file mode 100644 index 000000000..1fbc873da --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/footerbg.png diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/headerbg.png b/docs/quick_tutorial/scaffolds/scaffolds/static/headerbg.png Binary files differnew file mode 100644 index 000000000..0596f2020 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/headerbg.png diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/ie6.css b/docs/quick_tutorial/scaffolds/scaffolds/static/ie6.css new file mode 100644 index 000000000..b7c8493d8 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/ie6.css @@ -0,0 +1,8 @@ +* html img, +* html .png{position:relative;behavior:expression((this.runtimeStyle.behavior="none")&&(this.pngSet?this.pngSet=true:(this.nodeName == "IMG" && this.src.toLowerCase().indexOf('.png')>-1?(this.runtimeStyle.backgroundImage = "none", +this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.src + "',sizingMethod='image')", +this.src = "static/transparent.gif"):(this.origBg = this.origBg? this.origBg :this.currentStyle.backgroundImage.toString().replace('url("','').replace('")',''), +this.runtimeStyle.filter = "progid:DXImageTransform.Microsoft.AlphaImageLoader(src='" + this.origBg + "',sizingMethod='crop')", +this.runtimeStyle.backgroundImage = "none")),this.pngSet=true) +);} +#wrap{display:table;height:100%} diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/middlebg.png b/docs/quick_tutorial/scaffolds/scaffolds/static/middlebg.png Binary files differnew file mode 100644 index 000000000..2369cfb7d --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/middlebg.png diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/pylons.css b/docs/quick_tutorial/scaffolds/scaffolds/static/pylons.css new file mode 100644 index 000000000..4b1c017cd --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/pylons.css @@ -0,0 +1,372 @@ +html, body, div, span, applet, object, iframe, h1, h2, h3, h4, h5, h6, p, blockquote, pre, a, abbr, acronym, address, big, cite, code, del, dfn, em, font, img, ins, kbd, q, s, samp, small, strike, strong, sub, sup, tt, var, b, u, i, center, dl, dt, dd, ol, ul, li, fieldset, form, label, legend, table, caption, tbody, tfoot, thead, tr, th, td +{ + margin: 0; + padding: 0; + border: 0; + outline: 0; + font-size: 100%; /* 16px */ + vertical-align: baseline; + background: transparent; +} + +body +{ + line-height: 1; +} + +ol, ul +{ + list-style: none; +} + +blockquote, q +{ + quotes: none; +} + +blockquote:before, blockquote:after, q:before, q:after +{ + content: ''; + content: none; +} + +:focus +{ + outline: 0; +} + +ins +{ + text-decoration: none; +} + +del +{ + text-decoration: line-through; +} + +table +{ + border-collapse: collapse; + border-spacing: 0; +} + +sub +{ + vertical-align: sub; + font-size: smaller; + line-height: normal; +} + +sup +{ + vertical-align: super; + font-size: smaller; + line-height: normal; +} + +ul, menu, dir +{ + display: block; + list-style-type: disc; + margin: 1em 0; + padding-left: 40px; +} + +ol +{ + display: block; + list-style-type: decimal-leading-zero; + margin: 1em 0; + padding-left: 40px; +} + +li +{ + display: list-item; +} + +ul ul, ul ol, ul dir, ul menu, ul dl, ol ul, ol ol, ol dir, ol menu, ol dl, dir ul, dir ol, dir dir, dir menu, dir dl, menu ul, menu ol, menu dir, menu menu, menu dl, dl ul, dl ol, dl dir, dl menu, dl dl +{ + margin-top: 0; + margin-bottom: 0; +} + +ol ul, ul ul, menu ul, dir ul, ol menu, ul menu, menu menu, dir menu, ol dir, ul dir, menu dir, dir dir +{ + list-style-type: circle; +} + +ol ol ul, ol ul ul, ol menu ul, ol dir ul, ol ol menu, ol ul menu, ol menu menu, ol dir menu, ol ol dir, ol ul dir, ol menu dir, ol dir dir, ul ol ul, ul ul ul, ul menu ul, ul dir ul, ul ol menu, ul ul menu, ul menu menu, ul dir menu, ul ol dir, ul ul dir, ul menu dir, ul dir dir, menu ol ul, menu ul ul, menu menu ul, menu dir ul, menu ol menu, menu ul menu, menu menu menu, menu dir menu, menu ol dir, menu ul dir, menu menu dir, menu dir dir, dir ol ul, dir ul ul, dir menu ul, dir dir ul, dir ol menu, dir ul menu, dir menu menu, dir dir menu, dir ol dir, dir ul dir, dir menu dir, dir dir dir +{ + list-style-type: square; +} + +.hidden +{ + display: none; +} + +p +{ + line-height: 1.5em; +} + +h1 +{ + font-size: 1.75em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +h2 +{ + font-size: 1.5em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +h3 +{ + font-size: 1.25em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +h4 +{ + font-size: 1em; + line-height: 1.7em; + font-family: helvetica, verdana; +} + +html, body +{ + width: 100%; + height: 100%; +} + +body +{ + margin: 0; + padding: 0; + background-color: #fff; + position: relative; + font: 16px/24px NobileRegular, "Lucida Grande", Lucida, Verdana, sans-serif; +} + +a +{ + color: #1b61d6; + text-decoration: none; +} + +a:hover +{ + color: #e88f00; + text-decoration: underline; +} + +body h1, body h2, body h3, body h4, body h5, body h6 +{ + font-family: NeutonRegular, "Lucida Grande", Lucida, Verdana, sans-serif; + font-weight: 400; + color: #373839; + font-style: normal; +} + +#wrap +{ + min-height: 100%; +} + +#header, #footer +{ + width: 100%; + color: #fff; + height: 40px; + position: absolute; + text-align: center; + line-height: 40px; + overflow: hidden; + font-size: 12px; + vertical-align: middle; +} + +#header +{ + background: #000; + top: 0; + font-size: 14px; +} + +#footer +{ + bottom: 0; + background: #000 url(footerbg.png) repeat-x 0 top; + position: relative; + margin-top: -40px; + clear: both; +} + +.header, .footer +{ + width: 750px; + margin-right: auto; + margin-left: auto; +} + +.wrapper +{ + width: 100%; +} + +#top, #top-small, #bottom +{ + width: 100%; +} + +#top +{ + color: #000; + height: 230px; + background: #fff url(headerbg.png) repeat-x 0 top; + position: relative; +} + +#top-small +{ + color: #000; + height: 60px; + background: #fff url(headerbg.png) repeat-x 0 top; + position: relative; +} + +#bottom +{ + color: #222; + background-color: #fff; +} + +.top, .top-small, .middle, .bottom +{ + width: 750px; + margin-right: auto; + margin-left: auto; +} + +.top +{ + padding-top: 40px; +} + +.top-small +{ + padding-top: 10px; +} + +#middle +{ + width: 100%; + height: 100px; + background: url(middlebg.png) repeat-x; + border-top: 2px solid #fff; + border-bottom: 2px solid #b2b2b2; +} + +.app-welcome +{ + margin-top: 25px; +} + +.app-name +{ + color: #000; + font-weight: 700; +} + +.bottom +{ + padding-top: 50px; +} + +#left +{ + width: 350px; + float: left; + padding-right: 25px; +} + +#right +{ + width: 350px; + float: right; + padding-left: 25px; +} + +.align-left +{ + text-align: left; +} + +.align-right +{ + text-align: right; +} + +.align-center +{ + text-align: center; +} + +ul.links +{ + margin: 0; + padding: 0; +} + +ul.links li +{ + list-style-type: none; + font-size: 14px; +} + +form +{ + border-style: none; +} + +fieldset +{ + border-style: none; +} + +input +{ + color: #222; + border: 1px solid #ccc; + font-family: sans-serif; + font-size: 12px; + line-height: 16px; +} + +input[type=text], input[type=password] +{ + width: 205px; +} + +input[type=submit] +{ + background-color: #ddd; + font-weight: 700; +} + +/*Opera Fix*/ +body:before +{ + content: ""; + height: 100%; + float: left; + width: 0; + margin-top: -32767px; +} diff --git a/pyramid/scaffolds/starter/+package+/static/pyramid-small.png b/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid-small.png Binary files differindex a5bc0ade7..a5bc0ade7 100644 --- a/pyramid/scaffolds/starter/+package+/static/pyramid-small.png +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid-small.png diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid.png b/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid.png Binary files differnew file mode 100644 index 000000000..347e05549 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/pyramid.png diff --git a/docs/quick_tutorial/scaffolds/scaffolds/static/transparent.gif b/docs/quick_tutorial/scaffolds/scaffolds/static/transparent.gif Binary files differnew file mode 100644 index 000000000..0341802e5 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/static/transparent.gif diff --git a/docs/quick_tutorial/scaffolds/scaffolds/templates/mytemplate.pt b/docs/quick_tutorial/scaffolds/scaffolds/templates/mytemplate.pt new file mode 100644 index 000000000..b43a174e3 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/templates/mytemplate.pt @@ -0,0 +1,73 @@ +<!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('scaffolds:static/favicon.ico')}" /> + <link rel="stylesheet" href="${request.static_url('scaffolds: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('scaffolds: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('scaffolds: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> + </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> + </ul> + </div> + </div> + </div> + </div> +</body> +</html> diff --git a/docs/quick_tutorial/scaffolds/scaffolds/tests.py b/docs/quick_tutorial/scaffolds/scaffolds/tests.py new file mode 100644 index 000000000..4f906ffa9 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/tests.py @@ -0,0 +1,17 @@ +import unittest + +from pyramid import testing + + +class ViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_my_view(self): + from .views import my_view + request = testing.DummyRequest() + info = my_view(request) + self.assertEqual(info['project'], 'scaffolds') diff --git a/docs/quick_tutorial/scaffolds/scaffolds/views.py b/docs/quick_tutorial/scaffolds/scaffolds/views.py new file mode 100644 index 000000000..db90d8364 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/scaffolds/views.py @@ -0,0 +1,6 @@ +from pyramid.view import view_config + + +@view_config(route_name='home', renderer='templates/mytemplate.pt') +def my_view(request): + return {'project': 'scaffolds'} diff --git a/docs/quick_tutorial/scaffolds/setup.cfg b/docs/quick_tutorial/scaffolds/setup.cfg new file mode 100644 index 000000000..c980261e3 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/setup.cfg @@ -0,0 +1,27 @@ +[nosetests] +match = ^test +nocapture = 1 +cover-package = scaffolds +with-coverage = 1 +cover-erase = 1 + +[compile_catalog] +directory = scaffolds/locale +domain = scaffolds +statistics = true + +[extract_messages] +add_comments = TRANSLATORS: +output_file = scaffolds/locale/scaffolds.pot +width = 80 + +[init_catalog] +domain = scaffolds +input_file = scaffolds/locale/scaffolds.pot +output_dir = scaffolds/locale + +[update_catalog] +domain = scaffolds +input_file = scaffolds/locale/scaffolds.pot +output_dir = scaffolds/locale +previous = true diff --git a/docs/quick_tutorial/scaffolds/setup.py b/docs/quick_tutorial/scaffolds/setup.py new file mode 100644 index 000000000..ec95946a5 --- /dev/null +++ b/docs/quick_tutorial/scaffolds/setup.py @@ -0,0 +1,42 @@ +import os + +from setuptools import setup, find_packages + +here = os.path.abspath(os.path.dirname(__file__)) +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', + 'waitress', + ] + +setup(name='scaffolds', + version='0.0', + description='scaffolds', + long_description=README + '\n\n' + CHANGES, + classifiers=[ + "Programming Language :: Python", + "Framework :: Pyramid", + "Topic :: Internet :: WWW/HTTP", + "Topic :: Internet :: WWW/HTTP :: WSGI :: Application", + ], + author='', + author_email='', + url='', + keywords='web pyramid pylons', + packages=find_packages(), + include_package_data=True, + zip_safe=False, + install_requires=requires, + tests_require=requires, + test_suite="scaffolds", + entry_points="""\ + [paste.app_factory] + main = scaffolds:main + """, + ) diff --git a/docs/quick_tutorial/sessions.rst b/docs/quick_tutorial/sessions.rst new file mode 100644 index 000000000..ba26d0133 --- /dev/null +++ b/docs/quick_tutorial/sessions.rst @@ -0,0 +1,100 @@ +.. _qtut_sessions: + +================================= +17: Transient Data Using Sessions +================================= + +Store and retrieve non-permanent data in Pyramid sessions. + +Background +========== + +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, with add-ons such as +*dogpile.cache* (or your own custom sessioning engine) that provide +richer session support. Let's take a look at the +:ref:`built-in sessioning support <sessions_chapter>`. + +Objectives +========== + +- Make a session factory using a built-in, simple Pyramid sessioning + system + +- Change our code to use a session + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes sessions; cd sessions + $ $VENV/bin/python setup.py develop + +#. Our ``sessions/tutorial/__init__.py`` needs a choice of session + factory to get registered with the :term:`configurator`: + + .. literalinclude:: sessions/tutorial/__init__.py + :linenos: + +#. Our views in ``sessions/tutorial/views.py`` can now use + ``request.session``: + + .. literalinclude:: sessions/tutorial/views.py + :linenos: + +#. The template at ``sessions/tutorial/home.pt`` can display the value: + + .. literalinclude:: sessions/tutorial/home.pt + :language: html + :linenos: + +#. Make sure the tests still pass: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ and http://localhost:6543/howdy + in your browser. As you reload and switch between those URLs, note + that the counter increases and is *not* specific to the URL. + +#. Restart the application and revisit the page. Note that counter + still increases from where it left off. + +Analysis +======== + +Pyramid's :term:`request` object now has a ``session`` attribute +that we can use in our view code. It acts like a dictionary. + +Since all the views are using the same counter, we made the counter a +Python property at the view class level. With this, each reload will +increase the counter displayed in our template. + +In web development, "flash messages" are notes for the user that need +to appear on a screen after a future web request. For example, +when you add an item using a form ``POST``, the site usually issues a +second HTTP Redirect web request to view the new item. You might want a +message to appear after that second web request saying "Your item was +added." You can't just return it in the web response for the POST, +as it will be tossed out during the second web requests. + +Flash messages are a technique where messages can be stored between +requests, using sessions, then removed when they finally get displayed. + +.. seealso:: + :ref:`sessions_chapter`, + :ref:`flash_messages`, and + :ref:`session_module`. diff --git a/docs/quick_tutorial/sessions/development.ini b/docs/quick_tutorial/sessions/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/sessions/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/sessions/setup.py b/docs/quick_tutorial/sessions/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/sessions/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/sessions/tutorial/__init__.py b/docs/quick_tutorial/sessions/tutorial/__init__.py new file mode 100644 index 000000000..ecf57bb32 --- /dev/null +++ b/docs/quick_tutorial/sessions/tutorial/__init__.py @@ -0,0 +1,14 @@ +from pyramid.config import Configurator +from pyramid.session import UnencryptedCookieSessionFactoryConfig + + +def main(global_config, **settings): + my_session_factory = UnencryptedCookieSessionFactoryConfig( + 'itsaseekreet') + config = Configurator(settings=settings, + session_factory=my_session_factory) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/sessions/tutorial/home.pt b/docs/quick_tutorial/sessions/tutorial/home.pt new file mode 100644 index 000000000..0b27ba1d8 --- /dev/null +++ b/docs/quick_tutorial/sessions/tutorial/home.pt @@ -0,0 +1,10 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Hi ${name}</h1> +<p>Count: ${view.counter}</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/sessions/tutorial/tests.py b/docs/quick_tutorial/sessions/tutorial/tests.py new file mode 100644 index 000000000..4381235ec --- /dev/null +++ b/docs/quick_tutorial/sessions/tutorial/tests.py @@ -0,0 +1,44 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.hello() + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) diff --git a/docs/quick_tutorial/sessions/tutorial/views.py b/docs/quick_tutorial/sessions/tutorial/views.py new file mode 100644 index 000000000..a4659d265 --- /dev/null +++ b/docs/quick_tutorial/sessions/tutorial/views.py @@ -0,0 +1,29 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + + @property + def counter(self): + session = self.request.session + if 'counter' in session: + session['counter'] += 1 + else: + session['counter'] = 1 + + return session['counter'] + + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello') + def hello(self): + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/static_assets.rst b/docs/quick_tutorial/static_assets.rst new file mode 100644 index 000000000..19d33f00f --- /dev/null +++ b/docs/quick_tutorial/static_assets.rst @@ -0,0 +1,91 @@ +.. _qtut_static_assets: + +========================================== +13: CSS/JS/Images Files With 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. + +Objectives +========== + +- Publish a directory of static assets at a URL + +- Use Pyramid to help generate URLs to files in that directory + +Steps +===== + +#. First we copy the results of the ``view_classes`` step: + + .. code-block:: bash + + $ cd ..; cp -r view_classes static_assets; cd static_assets + $ $VENV/bin/python setup.py develop + +#. We add a call ``config.add_static_view in + ``static_assets/tutorial/__init__.py``: + + .. literalinclude:: static_assets/tutorial/__init__.py + :linenos: + +#. We can add a CSS link in the ``<head>`` of our template at + ``static_assets/tutorial/home.pt``: + + .. literalinclude:: static_assets/tutorial/home.pt + :language: html + +#. Add a CSS file at + ``static_assets/tutorial/static/app.css``: + + .. literalinclude:: static_assets/tutorial/static/app.css + :language: css + +#. Make sure we haven't broken any existing code by running the tests: + + .. code-block:: bash + + $ $VENV/bin/nosetests tutorial + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ in your browser and note the new font. + +Analysis +======== + +We changed our WSGI application to map requests under +http://localhost:6543/static/ to files and directories inside a +``static`` directory inside our ``tutorial`` package. This directory +contained ``app.css``. + +We linked to the CSS in our template. We could have hard-coded this +link to ``/static/app.css``. But what if the site is later moved under +``/somesite/static/``? Or perhaps the web developer changes the +arrangement on disk? Pyramid gives a helper that provides flexibility +on URL generation: + +.. code-block:: html + + ${request.static_url('tutorial:static/app.css')} + +This matches the ``path='tutorial:static'`` in our +``config.add_static_view`` registration. 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 gain refactoring flexibility later. + +Extra Credit +============ + +#. There is also a ``request.static_path`` API. How does this differ from + ``request.static_url``? + +.. seealso:: :ref:`assets_chapter`, + :ref:`preventing_http_caching`, and + :ref:`influencing_http_caching` diff --git a/docs/quick_tutorial/static_assets/development.ini b/docs/quick_tutorial/static_assets/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/static_assets/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/static_assets/setup.py b/docs/quick_tutorial/static_assets/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/static_assets/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/static_assets/tutorial/__init__.py b/docs/quick_tutorial/static_assets/tutorial/__init__.py new file mode 100644 index 000000000..e244c2997 --- /dev/null +++ b/docs/quick_tutorial/static_assets/tutorial/__init__.py @@ -0,0 +1,11 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.add_static_view(name='static', path='tutorial:static') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/static_assets/tutorial/home.pt b/docs/quick_tutorial/static_assets/tutorial/home.pt new file mode 100644 index 000000000..5d347f057 --- /dev/null +++ b/docs/quick_tutorial/static_assets/tutorial/home.pt @@ -0,0 +1,11 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> + <link rel="stylesheet" + href="${request.static_url('tutorial:static/app.css') }"/> +</head> +<body> +<h1>Hi ${name}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/static_assets/tutorial/static/app.css b/docs/quick_tutorial/static_assets/tutorial/static/app.css new file mode 100644 index 000000000..f8acf3164 --- /dev/null +++ b/docs/quick_tutorial/static_assets/tutorial/static/app.css @@ -0,0 +1,4 @@ +body { + margin: 2em; + font-family: sans-serif; +}
\ No newline at end of file diff --git a/docs/quick_tutorial/static_assets/tutorial/tests.py b/docs/quick_tutorial/static_assets/tutorial/tests.py new file mode 100644 index 000000000..4381235ec --- /dev/null +++ b/docs/quick_tutorial/static_assets/tutorial/tests.py @@ -0,0 +1,44 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.hello() + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) diff --git a/docs/quick_tutorial/static_assets/tutorial/views.py b/docs/quick_tutorial/static_assets/tutorial/views.py new file mode 100644 index 000000000..a56c0adbf --- /dev/null +++ b/docs/quick_tutorial/static_assets/tutorial/views.py @@ -0,0 +1,18 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello') + def hello(self): + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst new file mode 100644 index 000000000..d73067f48 --- /dev/null +++ b/docs/quick_tutorial/templating.rst @@ -0,0 +1,123 @@ +.. _qtut_templating: + +=================================== +08: HTML Generation With Templating +=================================== + +Most web frameworks don't embed HTML in programming code. Instead, +they pass data into a templating system. In this step we look at the +basics of using HTML templates in Pyramid. + +Background +========== + +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. + +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. As of Pyramid 1.5a2, Pyramid doesn't even bundle a template +language! + +It does, however, have strong ties to Jinja2, Mako, and Chameleon. In +this step we see how to add ``pyramid_chameleon`` to your project, +then change your views to use templating. + +Objectives +========== + +- Enable the ``pyramid_chameleon`` Pyramid add-on + +- Generate HTML from template files + +- Connect the templates as "renderers" for view code + +- Change the view code to simply return data + +Steps +===== + +#. Let's begin by using the previous package as a starting point for a + new project: + + .. code-block:: bash + + $ cd ..; cp -r views templating; cd templating + +#. This step depends on ``pyramid_chameleon``, so add it as a dependency + in ``templating/setup.py``: + + .. literalinclude:: templating/setup.py + :linenos: + +#. Now we can activate the development-mode distribution: + + .. code-block:: bash + + $ $VENV/bin/python setup.py develop + +#. We need to connect ``pyramid_chameleon`` as a renderer by making a + call in the setup of ``templating/tutorial/__init__.py``: + + .. literalinclude:: templating/tutorial/__init__.py + :linenos: + +#. Our ``templating/tutorial/views.py`` no longer has HTML in it: + + .. literalinclude:: templating/tutorial/views.py + :linenos: + +#. Instead we have ``templating/tutorial/home.pt`` as a template: + + .. literalinclude:: templating/tutorial/home.pt + :language: html + +#. For convenience, change ``templating/development.ini`` to reload + templates automatically with ``pyramid.reload_templates``: + + .. literalinclude:: templating/development.ini + :language: ini + +#. Our unit tests in ``templating/tutorial/tests.py`` can focus on + data: + + .. literalinclude:: templating/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + $ $VENV/bin/nosetests tutorial + . + ---------------------------------------------------------------------- + Ran 4 tests in 0.141s + + OK + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ and http://localhost:6543/howdy + in your browser. + +Analysis +======== + +Ahh, that looks better. We have a view that is focused on Python code. +Our ``@view_config`` decorator specifies a :term:`renderer` that points +our template file. Our view then simply returns data which is then +supplied to our template. Note that we used the same template for both +views. + +Note the effect on testing. We can focus on having a data-oriented +contract with our view code. + +.. seealso:: :ref:`templates_chapter`, :ref:`debugging_templates`, and + :ref:`available_template_system_bindings`. diff --git a/docs/quick_tutorial/templating/development.ini b/docs/quick_tutorial/templating/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/templating/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/templating/setup.py b/docs/quick_tutorial/templating/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/templating/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/templating/tutorial/__init__.py b/docs/quick_tutorial/templating/tutorial/__init__.py new file mode 100644 index 000000000..c3e1c9eef --- /dev/null +++ b/docs/quick_tutorial/templating/tutorial/__init__.py @@ -0,0 +1,10 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/templating/tutorial/home.pt b/docs/quick_tutorial/templating/tutorial/home.pt new file mode 100644 index 000000000..a0cc08e7a --- /dev/null +++ b/docs/quick_tutorial/templating/tutorial/home.pt @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Hi ${name}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/templating/tutorial/tests.py b/docs/quick_tutorial/templating/tutorial/tests.py new file mode 100644 index 000000000..d06a62982 --- /dev/null +++ b/docs/quick_tutorial/templating/tutorial/tests.py @@ -0,0 +1,44 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import home + + request = testing.DummyRequest() + response = home(request) + # Our view now returns data + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import hello + + request = testing.DummyRequest() + response = hello(request) + # Our view now returns data + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) diff --git a/docs/quick_tutorial/templating/tutorial/views.py b/docs/quick_tutorial/templating/tutorial/views.py new file mode 100644 index 000000000..979d69c43 --- /dev/null +++ b/docs/quick_tutorial/templating/tutorial/views.py @@ -0,0 +1,13 @@ +from pyramid.view import view_config + + +# First view, available at http://localhost:6543/ +@view_config(route_name='home', renderer='home.pt') +def home(request): + return {'name': 'Home View'} + + +# /howdy +@view_config(route_name='hello', renderer='home.pt') +def hello(request): + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst new file mode 100644 index 000000000..52d768306 --- /dev/null +++ b/docs/quick_tutorial/tutorial_approach.rst @@ -0,0 +1,45 @@ +================= +Tutorial Approach +================= + +This tutorial uses conventions to keep the introduction focused and +concise. Details, references, and deeper discussions are mentioned in +"See Also" notes. + +.. seealso:: This is an example "See Also" note. + +This "Getting Started" tutorial is broken into independent steps, +starting with the smallest possible "single file WSGI app" example. +Each of these steps introduce a topic and a very small set of concepts +via working code. The steps each correspond to a directory in this +repo, where each step/topic/directory is a Python package. + +To successfully run each step:: + + $ cd request_response + $ $VENV/bin/python setup.py develop + +...and repeat for each step you would like to work on. In most cases we +will start with the results of an earlier step. + +Directory Tree +============== + +As we develop our tutorial our directory tree will resemble the +structure below:: + + quicktutorial/ + request_response/ + development.ini + setup.py + tutorial/ + __init__.py + home.pt + tests.py + views.py + +Each of the first-level directories (e.g. ``request_response``) is a +*Python project* (except, as noted, the ``hello_world`` step.) The +``tutorial`` directory is a *Python package*. At the end of each step, +we copy a previous directory into a new directory to use as a starting +point.
\ No newline at end of file diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst new file mode 100644 index 000000000..73b33c588 --- /dev/null +++ b/docs/quick_tutorial/unit_testing.rst @@ -0,0 +1,119 @@ +.. _qtut_unit_testing: + +=========================== +05: Unit Tests and ``nose`` +=========================== + +Provide unit testing for our project's Python code. + +Background +========== + +As the mantra says, "Untested code is broken code." The Python +community has had a long culture of writing test scripts which ensure +that your code works correctly as you write it and maintain it in the +future. Pyramid has always had a deep commitment to testing, +with 100% test coverage from the earliest pre-releases. + +Python includes a +:ref:`unit testing framework <python:unittest-minimal-example>` in its +standard library. Over the years a number of Python projects, such as +`nose <https://pypi.python.org/pypi/nose/>`_, have extended this +framework with alternative test runners that provide more convenience +and functionality. The Pyramid developers use ``nose``, which we'll thus +use in this tutorial. + +Don't worry, this tutorial won't be pedantic about "test-driven +development" (TDD.) We'll do just enough to ensure that, in each step, +we haven't majorly broken the code. As you're writing your code you +might find this more convenient than changing to your browser +constantly and clicking reload. + +We'll also leave discussion of +`coverage <https://pypi.python.org/pypi/coverage>`_ for another section. + +Objectives +========== + +- Write unit tests that ensure the quality of our code + +- Install a Python package (``nose``) which helps in our testing + +Steps +===== + +#. First we copy the results of the previous step, as well as install + the ``nose`` package: + + .. code-block:: bash + + $ cd ..; cp -r debugtoolbar unit_testing; cd unit_testing + $ $VENV/bin/python setup.py develop + $ $VENV/bin/easy_install nose + +#. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``: + + .. literalinclude:: unit_testing/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + $ $VENV/bin/nosetests tutorial + . + ---------------------------------------------------------------------- + Ran 1 test in 0.141s + + OK + +Analysis +======== + +Our ``tests.py`` imports the Python standard unit testing framework. To +make writing Pyramid-oriented tests more convenient, Pyramid supplies +some ``pyramid.testing`` helpers 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. + +The ``tests.HelloWorldViewTests.test_hello_world`` test is a small +example of a unit test. First, we import the view inside each test. Why +not import at the top, like in normal Python code? Because imports can +cause effects that break a test. We'd like our tests to be in *units*, +hence the name *unit* testing. Each test should isolate itself to the +correct degree. + +Our test then makes a fake incoming web request, then calls our Pyramid +view. We test the HTTP status code on the response to make sure it +matches our expectations. + +Note that our use of ``pyramid.testing.setUp()`` and +``pyramid.testing.tearDown()`` aren't actually necessary here; they are only +necessary when your test needs to make use of the ``config`` object (it's a +Configurator) to add stuff to the configuration state before calling the view. + +Extra Credit +============ + +#. Change the test to assert that the response status code should be + ``404`` (meaning, not found.) Run ``nosetests`` again. Read the + error report and see if you can decipher what it is telling you. + +#. As a more realistic example, put the ``tests.py`` back as you found + it and put an error in your view, such as a reference to a + non-existing variable. Run the tests and see how this is more + convenient than reloading your browser and going back to your code. + +#. Finally, for the most realistic test, read about Pyramid ``Response`` + objects and see how to change the response code. Run the tests and + see how testing confirms the "contract" that your code claims to + support. + +#. How could we add a unit test assertion to test the HTML value of the + response body? + +#. Why do we import the ``hello_world`` view function *inside* the + ``test_hello_world`` method instead of at the top of the module? + +.. seealso:: See Also: :ref:`testing_chapter` diff --git a/docs/quick_tutorial/unit_testing/development.ini b/docs/quick_tutorial/unit_testing/development.ini new file mode 100644 index 000000000..470d92c57 --- /dev/null +++ b/docs/quick_tutorial/unit_testing/development.ini @@ -0,0 +1,40 @@ +[app:main] +use = egg:tutorial +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/unit_testing/setup.py b/docs/quick_tutorial/unit_testing/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/unit_testing/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/unit_testing/tutorial/__init__.py b/docs/quick_tutorial/unit_testing/tutorial/__init__.py new file mode 100644 index 000000000..2b4e84f30 --- /dev/null +++ b/docs/quick_tutorial/unit_testing/tutorial/__init__.py @@ -0,0 +1,13 @@ +from pyramid.config import Configurator +from pyramid.response import Response + + +def hello_world(request): + return Response('<body><h1>Hello World!</h1></body>') + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('hello', '/') + config.add_view(hello_world, route_name='hello') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/unit_testing/tutorial/tests.py b/docs/quick_tutorial/unit_testing/tutorial/tests.py new file mode 100644 index 000000000..66029b421 --- /dev/null +++ b/docs/quick_tutorial/unit_testing/tutorial/tests.py @@ -0,0 +1,18 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_hello_world(self): + from tutorial import hello_world + + request = testing.DummyRequest() + response = hello_world(request) + self.assertEqual(response.status_code, 200) diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst new file mode 100644 index 000000000..58ab43e40 --- /dev/null +++ b/docs/quick_tutorial/view_classes.rst @@ -0,0 +1,98 @@ +.. _qtut_view_classes: + +====================================== +09: Organizing Views With View Classes +====================================== + +Change our view functions to be methods on a view class, +then move some declarations to the class level. + +Background +========== + +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: + +- Group views + +- Centralize some repetitive defaults + +- Share some state and helpers + +In this step we just do the absolute minimum to convert the existing +views to a view class. In a later tutorial step we'll examine view +classes in depth. + +Objectives +========== + +- Group related views into a view class + +- Centralize configuration with class-level ``@view_defaults`` + +Steps +===== + + +#. First we copy the results of the previous step: + + .. code-block:: bash + + $ cd ..; cp -r templating view_classes; cd view_classes + $ $VENV/bin/python setup.py develop + +#. Our ``view_classes/tutorial/views.py`` now has a view class with + our two views: + + .. literalinclude:: view_classes/tutorial/views.py + :linenos: + +#. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, + so let's modify the to import the view class and make an instance + before getting a response: + + .. literalinclude:: view_classes/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + $ $VENV/bin/nosetests tutorial + . + ---------------------------------------------------------------------- + Ran 4 tests in 0.141s + + OK + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ and http://localhost:6543/howdy + in your browser. + +Analysis +======== + +To ease the transition to view classes, we didn't introduce any new +functionality. We simply changed the view functions to methods on a +view class, then updated the tests. + +In our ``TutorialViews`` view class you can see that our two view +classes are logically grouped together as methods on a common class. +Since the two views shared the same template, we could move that to a +``@view_defaults`` decorator on at the class level. + +The tests needed to change. Obviously we needed to import the view +class. But you can also see the pattern in the tests of instantiating +the view class with the dummy request first, then calling the view +method being tested. + +.. seealso:: :ref:`class_as_view` diff --git a/docs/quick_tutorial/view_classes/development.ini b/docs/quick_tutorial/view_classes/development.ini new file mode 100644 index 000000000..62e0c5123 --- /dev/null +++ b/docs/quick_tutorial/view_classes/development.ini @@ -0,0 +1,41 @@ +[app:main] +use = egg:tutorial +pyramid.reload_templates = true +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/view_classes/setup.py b/docs/quick_tutorial/view_classes/setup.py new file mode 100644 index 000000000..2221b72e9 --- /dev/null +++ b/docs/quick_tutorial/view_classes/setup.py @@ -0,0 +1,14 @@ +from setuptools import setup + +requires = [ + 'pyramid', + 'pyramid_chameleon' +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/view_classes/tutorial/__init__.py b/docs/quick_tutorial/view_classes/tutorial/__init__.py new file mode 100644 index 000000000..c3e1c9eef --- /dev/null +++ b/docs/quick_tutorial/view_classes/tutorial/__init__.py @@ -0,0 +1,10 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.include('pyramid_chameleon') + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/view_classes/tutorial/home.pt b/docs/quick_tutorial/view_classes/tutorial/home.pt new file mode 100644 index 000000000..a0cc08e7a --- /dev/null +++ b/docs/quick_tutorial/view_classes/tutorial/home.pt @@ -0,0 +1,9 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <title>Quick Tour: ${name}</title> +</head> +<body> +<h1>Hi ${name}</h1> +</body> +</html>
\ No newline at end of file diff --git a/docs/quick_tutorial/view_classes/tutorial/tests.py b/docs/quick_tutorial/view_classes/tutorial/tests.py new file mode 100644 index 000000000..4381235ec --- /dev/null +++ b/docs/quick_tutorial/view_classes/tutorial/tests.py @@ -0,0 +1,44 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.home() + self.assertEqual('Home View', response['name']) + + def test_hello(self): + from .views import TutorialViews + + request = testing.DummyRequest() + inst = TutorialViews(request) + response = inst.hello() + self.assertEqual('Hello View', response['name']) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<h1>Hi Home View', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<h1>Hi Hello View', res.body) diff --git a/docs/quick_tutorial/view_classes/tutorial/views.py b/docs/quick_tutorial/view_classes/tutorial/views.py new file mode 100644 index 000000000..58db53c4a --- /dev/null +++ b/docs/quick_tutorial/view_classes/tutorial/views.py @@ -0,0 +1,17 @@ +from pyramid.view import ( + view_config, + view_defaults + ) + +@view_defaults(renderer='home.pt') +class TutorialViews: + def __init__(self, request): + self.request = request + + @view_config(route_name='home') + def home(self): + return {'name': 'Home View'} + + @view_config(route_name='hello') + def hello(self): + return {'name': 'Hello View'} diff --git a/docs/quick_tutorial/views.rst b/docs/quick_tutorial/views.rst new file mode 100644 index 000000000..15785e902 --- /dev/null +++ b/docs/quick_tutorial/views.rst @@ -0,0 +1,122 @@ +.. _qtut_views: + +================================= +07: Basic Web Handling With Views +================================= + +Organize a views module with decorators and multiple views. + +Background +========== + +For the examples so far, 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: + +- The view function + +- Its registration with the configurator + +- The route to map it to a URL + +- The WSGI application launcher + +Let's move the views out to their own ``views.py`` module and change +our startup code to scan that module, looking for decorators that setup +the views. Let's also add a second view and update our tests. + +Objectives +========== + +- Views in a module that is scanned by the configurator + +- Decorators that do declarative configuration + +Steps +===== + +#. Let's begin by using the previous package as a starting point for a + new distribution, then making it active: + + .. code-block:: bash + + $ cd ..; cp -r function_testing views; cd views + $ $VENV/bin/python setup.py develop + +#. Our ``views/tutorial/__init__.py`` gets a lot shorter: + + .. literalinclude:: views/tutorial/__init__.py + :linenos: + +#. Let's add a module ``views/tutorial/views.py`` that is focused on + handling requests and responses: + + .. literalinclude:: views/tutorial/views.py + :linenos: + +#. Update the tests to cover the two new views: + + .. literalinclude:: views/tutorial/tests.py + :linenos: + +#. Now run the tests: + + .. code-block:: bash + + + $ $VENV/bin/nosetests tutorial + . + ---------------------------------------------------------------------- + Ran 4 tests in 0.141s + + OK + +#. Run your Pyramid application with: + + .. code-block:: bash + + $ $VENV/bin/pserve development.ini --reload + +#. Open http://localhost:6543/ and http://localhost:6543/howdy + in your browser. + +Analysis +======== + +We added some more URLs, but we also removed the view code from the +application startup code in ``tutorial/__init__.py``. +Our views, and their view registrations (via decorators) are now in a +module ``views.py`` which is scanned via ``config.scan('.views')``. + +We have 2 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 +back to the first view. + +This step also shows that the name appearing in the URL, +the name of the "route" that maps a URL to a view, +and the name of the view, can all be different. More on routes later. + +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:`python: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. + +Extra Credit +============ + +#. What does the dot in ``.views`` signify? + +#. Why might ``assertIn`` be a better choice in testing the text in + responses than ``assertEqual``? + +.. seealso:: :ref:`views_chapter`, + :ref:`view_config_chapter`, and + :ref:`debugging_view_configuration` + diff --git a/docs/quick_tutorial/views/development.ini b/docs/quick_tutorial/views/development.ini new file mode 100644 index 000000000..470d92c57 --- /dev/null +++ b/docs/quick_tutorial/views/development.ini @@ -0,0 +1,40 @@ +[app:main] +use = egg:tutorial +pyramid.includes = + pyramid_debugtoolbar + +[server:main] +use = egg:pyramid#wsgiref +host = 0.0.0.0 +port = 6543 + +# Begin logging configuration + +[loggers] +keys = root, tutorial + +[logger_tutorial] +level = DEBUG +handlers = +qualname = tutorial + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = INFO +handlers = console + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(asctime)s %(levelname)-5.5s [%(name)s][%(threadName)s] %(message)s + +# End logging configuration diff --git a/docs/quick_tutorial/views/setup.py b/docs/quick_tutorial/views/setup.py new file mode 100644 index 000000000..9997984d3 --- /dev/null +++ b/docs/quick_tutorial/views/setup.py @@ -0,0 +1,13 @@ +from setuptools import setup + +requires = [ + 'pyramid', +] + +setup(name='tutorial', + install_requires=requires, + entry_points="""\ + [paste.app_factory] + main = tutorial:main + """, +)
\ No newline at end of file diff --git a/docs/quick_tutorial/views/tutorial/__init__.py b/docs/quick_tutorial/views/tutorial/__init__.py new file mode 100644 index 000000000..013d4538f --- /dev/null +++ b/docs/quick_tutorial/views/tutorial/__init__.py @@ -0,0 +1,9 @@ +from pyramid.config import Configurator + + +def main(global_config, **settings): + config = Configurator(settings=settings) + config.add_route('home', '/') + config.add_route('hello', '/howdy') + config.scan('.views') + return config.make_wsgi_app()
\ No newline at end of file diff --git a/docs/quick_tutorial/views/tutorial/tests.py b/docs/quick_tutorial/views/tutorial/tests.py new file mode 100644 index 000000000..f1757757c --- /dev/null +++ b/docs/quick_tutorial/views/tutorial/tests.py @@ -0,0 +1,44 @@ +import unittest + +from pyramid import testing + + +class TutorialViewTests(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def test_home(self): + from .views import home + + request = testing.DummyRequest() + response = home(request) + self.assertEqual(response.status_code, 200) + self.assertIn(b'Visit', response.body) + + def test_hello(self): + from .views import hello + + request = testing.DummyRequest() + response = hello(request) + self.assertEqual(response.status_code, 200) + self.assertIn(b'Go back', response.body) + + +class TutorialFunctionalTests(unittest.TestCase): + def setUp(self): + from tutorial import main + app = main({}) + from webtest import TestApp + + self.testapp = TestApp(app) + + def test_home(self): + res = self.testapp.get('/', status=200) + self.assertIn(b'<body>Visit', res.body) + + def test_hello(self): + res = self.testapp.get('/howdy', status=200) + self.assertIn(b'<body>Go back', res.body) diff --git a/docs/quick_tutorial/views/tutorial/views.py b/docs/quick_tutorial/views/tutorial/views.py new file mode 100644 index 000000000..6ff149d7b --- /dev/null +++ b/docs/quick_tutorial/views/tutorial/views.py @@ -0,0 +1,14 @@ +from pyramid.response import Response +from pyramid.view import view_config + + +# First view, available at http://localhost:6543/ +@view_config(route_name='home') +def home(request): + return Response('<body>Visit <a href="/howdy">hello</a></body>') + + +# /howdy +@view_config(route_name='hello') +def hello(request): + return Response('<body>Go back <a href="/">home</a></body>') diff --git a/docs/tutorials/bfg/index.rst b/docs/tutorials/bfg/index.rst deleted file mode 100644 index a50637279..000000000 --- a/docs/tutorials/bfg/index.rst +++ /dev/null @@ -1,204 +0,0 @@ -.. index:: - single: converting a BFG app - single: bfg2pyramid - -.. _converting_a_bfg_app: - -Converting a :mod:`repoze.bfg` Application to :app:`Pyramid` -============================================================ - -Prior iterations of :app:`Pyramid` were released as a package named -:mod:`repoze.bfg`. :mod:`repoze.bfg` users are encouraged to upgrade -their deployments to :app:`Pyramid`, as, after the first final release -of :app:`Pyramid`, further feature development on :mod:`repoze.bfg` -will cease. - -Most existing :mod:`repoze.bfg` applications can be converted to a -:app:`Pyramid` application in a completely automated fashion. -However, if your application depends on packages which are not "core" -parts of :mod:`repoze.bfg` but which nonetheless have ``repoze.bfg`` -in their names (e.g. ``repoze.bfg.skins``, -``repoze.bfg.traversalwrapper``, ``repoze.bfg.jinja2``), you will need -to find an analogue for each. For example, by the time you read this, -there will be a ``pyramid_jinja2`` package, which can be used instead -of ``repoze.bfg.jinja2``. If an analogue does not seem to exist for a -``repoze.bfg`` add-on package that your application uses, please email -the `Pylons-devel <http://groups.google.com/group/pylons-devel>`_ -maillist; we'll convert the package to a :app:`Pyramid` analogue for -you. - -Here's how to convert a :mod:`repoze.bfg` application to a -:app:`Pyramid` application: - -#. Ensure that your application works under :mod:`repoze.bfg` *version - 1.3 or better*. See - `http://docs.repoze.org/bfg/1.3/narr/install.html - <http://docs.repoze.org/bfg/1.3/narr/install.html>`_ for - :mod:`repoze.bfg` 1.3 installation instructions. If your - application has an automated test suite, run it while your - application is using :mod:`repoze.bfg` 1.3+. Otherwise, test it - manually. It is only safe to proceed to the next step once your - application works under :mod:`repoze.bfg` 1.3+. - - If your application has a proper set of dependencies, and a - standard automated test suite, you might test your - :mod:`repoze.bfg` application against :mod:`repoze.bfg` 1.3 like - so: - - .. code-block:: bash - - $ $VENV/bin/python setup.py test - - ``bfgenv`` above will be the virtualenv into which you've installed - :mod:`repoze.bfg` 1.3. - -#. Install :app:`Pyramid` into a *separate* virtualenv as per the - instructions in :ref:`installing_chapter`. The :app:`Pyramid` - virtualenv should be separate from the one you've used to install - :mod:`repoze.bfg`. A quick way to do this: - - .. code-block:: bash - - $ cd ~ - $ virtualenv --no-site-packages pyramidenv - $ cd pyramidenv - $ $VENV/bin/easy_install pyramid - -#. Put a *copy* of your :mod:`repoze.bfg` application into a temporary - location (perhaps by checking a fresh copy of the application out - of a version control repository). For example: - - .. code-block:: bash - - $ cd /tmp - $ svn co http://my.server/my/bfg/application/trunk bfgapp - -#. Use the ``bfg2pyramid`` script present in the ``bin`` directory of - the :app:`Pyramid` virtualenv to convert all :mod:`repoze.bfg` - Python import statements into compatible :app:`Pyramid` import - statements. ``bfg2pyramid`` will also fix ZCML directive usages of - common :mod:`repoze.bfg` directives. You invoke ``bfg2pyramid`` by - passing it the *path* of the copy of your application. The path - passed should contain a "setup.py" file, representing your - :mod:`repoze.bfg` application's setup script. ``bfg2pyramid`` will - change the copy of the application *in place*. - - .. code-block:: bash - - $ ~/pyramidenv/bfg2pyramid /tmp/bfgapp - - ``bfg2pyramid`` will convert the following :mod:`repoze.bfg` - application aspects to :app:`Pyramid` compatible analogues: - - - Python ``import`` statements naming :mod:`repoze.bfg` APIs will - be converted to :app:`Pyramid` compatible ``import`` statements. - Every Python file beneath the top-level path will be visited and - converted recursively, except Python files which live in - directories which start with a ``.`` (dot). - - - Each ZCML file found (recursively) within the path will have the - default ``xmlns`` attribute attached to the ``configure`` tag - changed from ``http://namespaces.repoze.org/bfg`` to - ``http://pylonshq.com/pyramid``. Every ZCML file beneath the - top-level path (files ending with ``.zcml``) will be visited and - converted recursively, except ZCML files which live in - directories which start with a ``.`` (dot). - - - ZCML files which contain directives that have attributes which - name a ``repoze.bfg`` API module or attribute of an API module - (e.g. ``context="repoze.bfg.exceptions.NotFound"``) will be - converted to :app:`Pyramid` compatible ZCML attributes - (e.g. ``context="pyramid.exceptions.NotFound``). Every ZCML file - beneath the top-level path (files ending with ``.zcml``) will be - visited and converted recursively, except ZCML files which live - in directories which start with a ``.`` (dot). - -#. Edit the ``setup.py`` file of the application you've just converted - (if you've been using the example paths, this will be - ``/tmp/bfgapp/setup.py``) to depend on the ``pyramid`` distribution - instead the of ``repoze.bfg`` distribution in its - ``install_requires`` list. If you used a scaffold to - create the :mod:`repoze.bfg` application, you can do so by changing - the ``requires`` line near the top of the ``setup.py`` file. The - original may look like this: - - .. code-block:: text - - requires = ['repoze.bfg', ... other dependencies ...] - - Edit the ``setup.py`` so it has: - - .. code-block:: text - - requires = ['pyramid', ... other dependencies ...] - - All other install-requires and tests-requires dependencies save for - the one on ``repoze.bfg`` can remain the same. - -#. Convert any ``install_requires`` dependencies your application has - on other add-on packages which have ``repoze.bfg`` in their names - to :app:`Pyramid` compatible analogues (e.g. ``repoze.bfg.jinja2`` - should be replaced with ``pyramid_jinja2``). You may need to - adjust configuration options and/or imports in your - :mod:`repoze.bfg` application after replacing these add-ons. Read - the documentation of the :app:`Pyramid` add-on package for - information. - -#. *Only if you use ZCML and add-ons which use ZCML*: The default - ``xmlns`` of the ``configure`` tag in ZCML has changed. The - ``bfg2pyramid`` script effects the default namespace change (it - changes the ``configure`` tag default ``xmlns`` from - ``http://namespaces.repoze.org/bfg`` to - ``http://pylonshq.com/pyramid``). - - This means that uses of add-ons which define ZCML directives in the - ``http://namespaces.repoze.org/bfg`` namespace will begin to "fail" - (they're actually not really failing, but your ZCML assumes that - they will always be used within a ``configure`` tag which names the - ``http://namespaces.repoze.org/bfg`` namespace as its default - ``xmlns``). Symptom: when you attempt to start the application, an - error such as ``ConfigurationError: ('Unknown directive', - u'http://namespaces.repoze.org/bfg', u'workflow')`` is printed to - the console and the application fails to start. In such a case, - either add an ``xmlns="http://namespaces.repoze.org/bfg"`` - attribute to each tag which causes a failure, or define a namespace - alias in the configure tag and prefix each failing tag. For - example, change this "failing" tag instance:: - - <configure xmlns="http://pylonshq.com/pyramid"> - <failingtag attr="foo"/> - </configure> - - To this, which will begin to succeed:: - - <configure xmlns="http://pylonshq.com/pyramid" - xmlns:bfg="http://namespaces.repoze.org/bfg"> - <bfg:failingtag attr="foo"/> - </configure> - - You will also need to add the ``pyramid_zcml`` package to your - ``setup.py`` ``install_requires`` list. In Pyramid, ZCML configuration - became an optional add-on supported by the ``pyramid_zcml`` package. - -#. Retest your application using :app:`Pyramid`. This might be as - easy as: - - .. code-block:: bash - - $ cd /tmp/bfgapp - $ $VENV/bin/python setup.py test - -#. Fix any test failures. - -#. Fix any code which generates deprecation warnings. - -#. Start using the converted version of your application. Celebrate. - -Two terminological changes have been made to Pyramid which make its -documentation and newer APIs different than those of ``repoze.bfg``. The -concept that BFG called ``model`` is called ``resource`` in Pyramid and the -concept that BFG called ``resource`` is called ``asset`` in Pyramid. Various -APIs have changed as a result (although all have backwards compatible shims). -Additionally, the environment variables that influenced server behavior which -used to be prefixed with ``BFG_`` (such as ``BFG_DEBUG_NOTFOUND``) must now -be prefixed with ``PYRAMID_``. diff --git a/docs/tutorials/modwsgi/index.rst b/docs/tutorials/modwsgi/index.rst index e0021f8db..ddd968927 100644 --- a/docs/tutorials/modwsgi/index.rst +++ b/docs/tutorials/modwsgi/index.rst @@ -46,7 +46,7 @@ specific path information for commands and files. $ cd ~ $ mkdir modwsgi $ cd modwsgi - $ /usr/local/bin/virtualenv --no-site-packages env + $ /usr/local/bin/virtualenv env #. Install :app:`Pyramid` into the newly created virtualenv: diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst index 25ac9aabd..cdf52b73e 100644 --- a/docs/tutorials/wiki/basiclayout.rst +++ b/docs/tutorials/wiki/basiclayout.rst @@ -34,7 +34,10 @@ point happens to be the ``main`` function within the file named factory` and the settings keywords parsed by :term:`PasteDeploy`. The root factory is named ``root_factory``. -#. *Line 15*. Register a "static view" which answers requests whose URL path +#. *Line 15*. Include support for the :term:`Chameleon` template rendering + bindings, allowing us to use the ``.pt`` templates. + +#. *Line 16*. Register a "static view" which answers requests whose URL path start with ``/static`` using the :meth:`pyramid.config.Configurator.add_static_view` method. This statement registers a view that will serve up static assets, such as CSS @@ -47,7 +50,7 @@ point happens to be the ``main`` function within the file named package. Alternatively the scaffold could have used an *absolute* asset specification as the path (``tutorial:static``). -#. *Line 16*. Perform a :term:`scan`. A scan will find :term:`configuration +#. *Line 17*. Perform a :term:`scan`. A scan will find :term:`configuration decoration`, such as view configuration decorators (e.g., ``@view_config``) in the source code of the ``tutorial`` package and will take actions based on these decorators. We don't pass any arguments to @@ -56,7 +59,7 @@ point happens to be the ``main`` function within the file named The scaffold could have equivalently said ``config.scan('tutorial')``, but it chose to omit the package name argument. -#. *Line 17*. Use the +#. *Line 18*. Use the :meth:`pyramid.config.Configurator.make_wsgi_app` method to return a :term:`WSGI` application. diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 23ee142af..e06468267 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -306,9 +306,9 @@ by the view (row 45). The view will use the ``body`` and none of our tutorial views return in their dictionary. ``request`` is one of several names that are available "by default" in a template when a template - renderer is used. See :ref:`chameleon_template_renderers` for + renderer is used. See :ref:`renderer_system_values` for information about other names that are available by default - when a Chameleon template is used as a renderer. + when a template is used as a renderer. Static Assets ------------- diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py index 5d87fedbf..5ab4f73cd 100644 --- a/docs/tutorials/wiki/src/authorization/setup.py +++ b/docs/tutorials/wiki/src/authorization/setup.py @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_zodbconn', 'transaction', 'pyramid_tm', diff --git a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py index 8ea8f8fa3..39b94abd1 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/__init__.py +++ b/docs/tutorials/wiki/src/authorization/tutorial/__init__.py @@ -21,6 +21,7 @@ def main(global_config, **settings): config = Configurator(root_factory=root_factory, settings=settings) config.set_authentication_policy(authn_policy) config.set_authorization_policy(authz_policy) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.scan() return config.make_wsgi_app() diff --git a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/authorization/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki/src/basiclayout/setup.py b/docs/tutorials/wiki/src/basiclayout/setup.py index 75ba02611..da79881ab 100644 --- a/docs/tutorials/wiki/src/basiclayout/setup.py +++ b/docs/tutorials/wiki/src/basiclayout/setup.py @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_zodbconn', 'transaction', 'pyramid_tm', diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py index c3bb87a62..f2a86df47 100644 --- a/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py +++ b/docs/tutorials/wiki/src/basiclayout/tutorial/__init__.py @@ -12,6 +12,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(root_factory=root_factory, settings=settings) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.scan() return config.make_wsgi_app() diff --git a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/basiclayout/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki/src/models/setup.py b/docs/tutorials/wiki/src/models/setup.py index 75ba02611..da79881ab 100644 --- a/docs/tutorials/wiki/src/models/setup.py +++ b/docs/tutorials/wiki/src/models/setup.py @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_zodbconn', 'transaction', 'pyramid_tm', diff --git a/docs/tutorials/wiki/src/models/tutorial/__init__.py b/docs/tutorials/wiki/src/models/tutorial/__init__.py index c3bb87a62..f2a86df47 100644 --- a/docs/tutorials/wiki/src/models/tutorial/__init__.py +++ b/docs/tutorials/wiki/src/models/tutorial/__init__.py @@ -12,6 +12,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(root_factory=root_factory, settings=settings) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.scan() return config.make_wsgi_app() diff --git a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/models/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki/src/models/tutorial/tests.py b/docs/tutorials/wiki/src/models/tutorial/tests.py index 9fd13a18d..0c5f99575 100644 --- a/docs/tutorials/wiki/src/models/tutorial/tests.py +++ b/docs/tutorials/wiki/src/models/tutorial/tests.py @@ -45,7 +45,7 @@ class AppmakerTests(unittest.TestCase): app_root = object() root = {'app_root': app_root} self._callFUT(root) - self.failUnless(root['app_root'] is app_root) + self.assertTrue(root['app_root'] is app_root) class ViewTests(unittest.TestCase): def setUp(self): diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py index 5ff7b545c..2e7ed2398 100644 --- a/docs/tutorials/wiki/src/tests/setup.py +++ b/docs/tutorials/wiki/src/tests/setup.py @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_zodbconn', 'transaction', 'pyramid_tm', diff --git a/docs/tutorials/wiki/src/tests/tutorial/__init__.py b/docs/tutorials/wiki/src/tests/tutorial/__init__.py index 8ea8f8fa3..bd3c5619f 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/__init__.py +++ b/docs/tutorials/wiki/src/tests/tutorial/__init__.py @@ -19,6 +19,7 @@ def main(global_config, **settings): 'sosecret', callback=groupfinder, hashalg='sha512') authz_policy = ACLAuthorizationPolicy() config = Configurator(root_factory=root_factory, settings=settings) + config.include('pyramid_chameleon') config.set_authentication_policy(authn_policy) config.set_authorization_policy(authz_policy) config.add_static_view('static', 'static', cache_max_age=3600) diff --git a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt index e8672104d..13b41f823 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/tests/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki/src/views/setup.py b/docs/tutorials/wiki/src/views/setup.py index 5d87fedbf..5ab4f73cd 100644 --- a/docs/tutorials/wiki/src/views/setup.py +++ b/docs/tutorials/wiki/src/views/setup.py @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_zodbconn', 'transaction', 'pyramid_tm', diff --git a/docs/tutorials/wiki/src/views/tutorial/__init__.py b/docs/tutorials/wiki/src/views/tutorial/__init__.py index c3bb87a62..f2a86df47 100644 --- a/docs/tutorials/wiki/src/views/tutorial/__init__.py +++ b/docs/tutorials/wiki/src/views/tutorial/__init__.py @@ -12,6 +12,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(root_factory=root_factory, settings=settings) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.scan() return config.make_wsgi_app() diff --git a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt index 84824f605..50102aa20 100644 --- a/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki/src/views/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki/tests.rst b/docs/tutorials/wiki/tests.rst index e40dc286b..e724f3e18 100644 --- a/docs/tutorials/wiki/tests.rst +++ b/docs/tutorials/wiki/tests.rst @@ -59,8 +59,8 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``. .. literalinclude:: src/tests/setup.py :linenos: :language: python - :lines: 11-21 - :emphasize-lines: 10 + :lines: 11-22 + :emphasize-lines: 11 After we've added a dependency on WebTest in ``setup.py``, we need to rerun ``setup.py develop`` to get WebTest installed into our virtualenv. Assuming diff --git a/docs/tutorials/wiki2/authorization.rst b/docs/tutorials/wiki2/authorization.rst index 01c301e74..cf20db6d7 100644 --- a/docs/tutorials/wiki2/authorization.rst +++ b/docs/tutorials/wiki2/authorization.rst @@ -83,7 +83,7 @@ statement at the head: Add the following class definition: .. literalinclude:: src/authorization/tutorial/models.py - :lines: 36-40 + :lines: 33-37 :linenos: :language: python @@ -203,7 +203,7 @@ Go back to ``tutorial/tutorial/__init__.py`` and add these two routes: .. literalinclude:: src/authorization/tutorial/__init__.py - :lines: 30-31 + :lines: 31-32 :linenos: :language: python @@ -329,7 +329,7 @@ when we're done: .. literalinclude:: src/authorization/tutorial/__init__.py :linenos: - :emphasize-lines: 2-3,7,21-23,25-27,30-31 + :emphasize-lines: 2-3,7,21-23,25-27,31-32 :language: python (Only the highlighted lines need to be added.) @@ -339,7 +339,7 @@ when we're done: .. literalinclude:: src/authorization/tutorial/models.py :linenos: - :emphasize-lines: 1-4,36-40 + :emphasize-lines: 1-4,33-37 :language: python (Only the highlighted lines need to be added.) diff --git a/docs/tutorials/wiki2/basiclayout.rst b/docs/tutorials/wiki2/basiclayout.rst index 0193afab4..05781c044 100644 --- a/docs/tutorials/wiki2/basiclayout.rst +++ b/docs/tutorials/wiki2/basiclayout.rst @@ -82,11 +82,18 @@ dictionary of settings parsed from the ``.ini`` file, which contains deployment-related values such as ``pyramid.reload_templates``, ``db_string``, etc. +Next, include :term:`Chameleon` templating bindings so that we can use +renderers with the ``.pt`` extension within our project. + + .. literalinclude:: src/basiclayout/tutorial/__init__.py + :lines: 17 + :language: py + ``main`` now calls :meth:`pyramid.config.Configurator.add_static_view` with two arguments: ``static`` (the name), and ``static`` (the path): .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 17 + :lines: 18 :language: py This registers a static resource view which will match any URL that starts @@ -104,7 +111,7 @@ via the :meth:`pyramid.config.Configurator.add_route` method that will be used when the URL is ``/``: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 18 + :lines: 19 :language: py Since this route has a ``pattern`` equalling ``/`` it is the route that will @@ -118,7 +125,7 @@ view configuration will be registered, which will allow one of our application URLs to be mapped to some code. .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 19 + :lines: 20 :language: py Finally, ``main`` is finished configuring things, so it uses the @@ -126,7 +133,7 @@ Finally, ``main`` is finished configuring things, so it uses the :term:`WSGI` application: .. literalinclude:: src/basiclayout/tutorial/__init__.py - :lines: 20 + :lines: 21 :language: py View Declarations via ``views.py`` @@ -225,10 +232,17 @@ To give a simple example of a model class, we define one named ``MyModel``: :linenos: :language: py -Our example model has an ``__init__`` method that takes two arguments -(``name``, and ``value``). It stores these values as ``self.name`` and -``self.value`` on the instance created by the ``__init__`` function itself. -The ``MyModel`` class also has a ``__tablename__`` attribute. This informs +Our example model does not require an ``__init__`` method because SQLAlchemy +supplies for us a default constructor if one is not already present, +which accepts keyword arguments of the same name as that of the mapped attributes. + +.. note:: Example usage of MyModel: + + .. code-block:: python + + johnny = MyModel(name="John Doe", value=10) + +The ``MyModel`` class has a ``__tablename__`` attribute. This informs SQLAlchemy which table to use to store the data representing instances of this class. diff --git a/docs/tutorials/wiki2/definingmodels.rst b/docs/tutorials/wiki2/definingmodels.rst index 60427a911..e30af12b2 100644 --- a/docs/tutorials/wiki2/definingmodels.rst +++ b/docs/tutorials/wiki2/definingmodels.rst @@ -24,7 +24,7 @@ following: .. literalinclude:: src/models/tutorial/models.py :linenos: :language: py - :emphasize-lines: 20-22,25,27,29 + :emphasize-lines: 20-22,25 (The highlighted lines are the ones that need to be changed.) diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index a1e2313f3..49dbed50f 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -30,7 +30,7 @@ Open ``tutorial/setup.py`` and edit it to look like the following: .. literalinclude:: src/views/setup.py :linenos: :language: python - :emphasize-lines: 19 + :emphasize-lines: 20 (Only the highlighted line needs to be added.) @@ -272,9 +272,9 @@ by the view (row 45). The view will use the ``body`` and none of our tutorial views return in their dictionary. ``request`` is one of several names that are available "by default" in a template when a template - renderer is used. See :ref:`chameleon_template_renderers` for + renderer is used. See :ref:`renderer_system_values` for information about other names that are available by default - when a Chameleon template is used as a renderer. + when a template is used as a renderer. Static Assets ------------- @@ -335,7 +335,7 @@ something like: .. literalinclude:: src/views/tutorial/__init__.py :linenos: :language: python - :emphasize-lines: 18-21 + :emphasize-lines: 19-22 (The highlighted lines are the ones that need to be added or edited.) diff --git a/docs/tutorials/wiki2/installation.rst b/docs/tutorials/wiki2/installation.rst index 17788cdde..e21bf7108 100644 --- a/docs/tutorials/wiki2/installation.rst +++ b/docs/tutorials/wiki2/installation.rst @@ -26,7 +26,7 @@ On UNIX .. code-block:: text $ export VENV=~/pyramidtut - $ virtualenv --no-site-packages $VENV + $ virtualenv $VENV New python executable in /home/foo/env/bin/python Installing setuptools.............done. @@ -46,13 +46,13 @@ Python 2.7: .. code-block:: text - c:\> c:\Python27\Scripts\virtualenv --no-site-packages %VENV% + c:\> c:\Python27\Scripts\virtualenv %VENV% Python 3.2: .. code-block:: text - c:\> c:\Python32\Scripts\virtualenv --no-site-packages %VENV% + c:\> c:\Python32\Scripts\virtualenv %VENV% Install Pyramid Into the Virtual Python Environment --------------------------------------------------- diff --git a/docs/tutorials/wiki2/src/authorization/setup.py b/docs/tutorials/wiki2/src/authorization/setup.py index e8fa8f396..09bd63d33 100644 --- a/docs/tutorials/wiki2/src/authorization/setup.py +++ b/docs/tutorials/wiki2/src/authorization/setup.py @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'SQLAlchemy', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', 'docutils', diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py index d08e55bf9..2ada42171 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/__init__.py @@ -25,6 +25,7 @@ def main(global_config, **settings): root_factory='tutorial.models.RootFactory') config.set_authentication_policy(authn_policy) config.set_authorization_policy(authz_policy) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.add_route('view_wiki', '/') config.add_route('login', '/login') diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/models.py b/docs/tutorials/wiki2/src/authorization/tutorial/models.py index 91e5a0019..4f7e1e024 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/models.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/models.py @@ -29,9 +29,6 @@ class Page(Base): name = Column(Text, unique=True) data = Column(Text) - def __init__(self, name, data): - self.name = name - self.data = data class RootFactory(object): __acl__ = [ (Allow, Everyone, 'view'), diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/authorization/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt index 14b88d16a..cf3da2073 100644 --- a/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/authorization/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki2/src/basiclayout/setup.py b/docs/tutorials/wiki2/src/basiclayout/setup.py index e7d318128..15e7e5923 100644 --- a/docs/tutorials/wiki2/src/basiclayout/setup.py +++ b/docs/tutorials/wiki2/src/basiclayout/setup.py @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'SQLAlchemy', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', ] diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py index aac7c5e69..867049e4f 100644 --- a/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py +++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/__init__.py @@ -14,6 +14,7 @@ def main(global_config, **settings): 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() diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py index aeeb9df64..0cdd4bbc3 100644 --- a/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py +++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/models.py @@ -22,7 +22,3 @@ class MyModel(Base): id = Column(Integer, primary_key=True) name = Column(Text, unique=True) value = Column(Integer) - - def __init__(self, name, value): - self.name = name - self.value = value diff --git a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt index ee9fdb7fa..ca4e0af26 100644 --- a/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/basiclayout/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki2/src/models/setup.py b/docs/tutorials/wiki2/src/models/setup.py index e7d318128..15e7e5923 100644 --- a/docs/tutorials/wiki2/src/models/setup.py +++ b/docs/tutorials/wiki2/src/models/setup.py @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'SQLAlchemy', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', ] diff --git a/docs/tutorials/wiki2/src/models/tutorial/__init__.py b/docs/tutorials/wiki2/src/models/tutorial/__init__.py index aac7c5e69..867049e4f 100644 --- a/docs/tutorials/wiki2/src/models/tutorial/__init__.py +++ b/docs/tutorials/wiki2/src/models/tutorial/__init__.py @@ -14,6 +14,7 @@ def main(global_config, **settings): 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() diff --git a/docs/tutorials/wiki2/src/models/tutorial/models.py b/docs/tutorials/wiki2/src/models/tutorial/models.py index 9a078d757..f028c917a 100644 --- a/docs/tutorials/wiki2/src/models/tutorial/models.py +++ b/docs/tutorials/wiki2/src/models/tutorial/models.py @@ -23,7 +23,3 @@ class Page(Base): id = Column(Integer, primary_key=True) name = Column(Text, unique=True) data = Column(Text) - - def __init__(self, name, data): - self.name = name - self.data = data diff --git a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/models/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt index ee9fdb7fa..ca4e0af26 100644 --- a/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/models/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki2/src/tests/setup.py b/docs/tutorials/wiki2/src/tests/setup.py index c3da36b39..d8486e462 100644 --- a/docs/tutorials/wiki2/src/tests/setup.py +++ b/docs/tutorials/wiki2/src/tests/setup.py @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'SQLAlchemy', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', 'docutils', diff --git a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py index d08e55bf9..cee89184b 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/__init__.py +++ b/docs/tutorials/wiki2/src/tests/tutorial/__init__.py @@ -23,6 +23,7 @@ def main(global_config, **settings): authz_policy = ACLAuthorizationPolicy() config = Configurator(settings=settings, root_factory='tutorial.models.RootFactory') + config.include('pyramid_chameleon') config.set_authentication_policy(authn_policy) config.set_authorization_policy(authz_policy) config.add_static_view('static', 'static', cache_max_age=3600) diff --git a/docs/tutorials/wiki2/src/tests/tutorial/models.py b/docs/tutorials/wiki2/src/tests/tutorial/models.py index 91e5a0019..4f7e1e024 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/models.py +++ b/docs/tutorials/wiki2/src/tests/tutorial/models.py @@ -29,9 +29,6 @@ class Page(Base): name = Column(Text, unique=True) data = Column(Text) - def __init__(self, name, data): - self.name = name - self.data = data class RootFactory(object): __acl__ = [ (Allow, Everyone, 'view'), diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt index 9c077568d..6c1ca924a 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/tests/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki2/src/views/setup.py b/docs/tutorials/wiki2/src/views/setup.py index e8fa8f396..09bd63d33 100644 --- a/docs/tutorials/wiki2/src/views/setup.py +++ b/docs/tutorials/wiki2/src/views/setup.py @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'SQLAlchemy', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', 'docutils', diff --git a/docs/tutorials/wiki2/src/views/tutorial/__init__.py b/docs/tutorials/wiki2/src/views/tutorial/__init__.py index c95bfdbf8..37cae1997 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/__init__.py +++ b/docs/tutorials/wiki2/src/views/tutorial/__init__.py @@ -14,6 +14,7 @@ def main(global_config, **settings): 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('view_wiki', '/') config.add_route('view_page', '/{pagename}') diff --git a/docs/tutorials/wiki2/src/views/tutorial/models.py b/docs/tutorials/wiki2/src/views/tutorial/models.py index 9a078d757..f028c917a 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/models.py +++ b/docs/tutorials/wiki2/src/views/tutorial/models.py @@ -23,7 +23,3 @@ class Page(Base): id = Column(Integer, primary_key=True) name = Column(Text, unique=True) data = Column(Text) - - def __init__(self, name, data): - self.name = name - self.data = data diff --git a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py index 092e359ce..23a5f13f4 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/views/tutorial/scripts/initializedb.py @@ -33,5 +33,5 @@ def main(argv=sys.argv): DBSession.configure(bind=engine) Base.metadata.create_all(engine) with transaction.manager: - model = Page('FrontPage', 'This is the front page') + model = Page(name='FrontPage', data='This is the front page') DBSession.add(model) diff --git a/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt b/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt index ee9fdb7fa..ca4e0af26 100644 --- a/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt +++ b/docs/tutorials/wiki2/src/views/tutorial/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/docs/tutorials/wiki2/tests.rst b/docs/tutorials/wiki2/tests.rst index 33b5d35c1..9aca0c5b7 100644 --- a/docs/tutorials/wiki2/tests.rst +++ b/docs/tutorials/wiki2/tests.rst @@ -54,8 +54,8 @@ Change the ``requires`` list in ``setup.py`` to include ``WebTest``. .. literalinclude:: src/tests/setup.py :linenos: :language: python - :lines: 11-21 - :emphasize-lines: 10 + :lines: 11-22 + :emphasize-lines: 11 After we've added a dependency on WebTest in ``setup.py``, we need to rerun ``setup.py develop`` to get WebTest installed into our virtualenv. Assuming diff --git a/docs/whatsnew-1.0.rst b/docs/whatsnew-1.0.rst index d1f3046ca..8750863e7 100644 --- a/docs/whatsnew-1.0.rst +++ b/docs/whatsnew-1.0.rst @@ -92,7 +92,7 @@ BFG Conversion Script The ``bfg2pyramid`` conversion script performs a mostly automated conversion of an existing :mod:`repoze.bfg` application to Pyramid. The process is -described in :ref:`converting_a_bfg_app`. +described in "Converting a BFG Application to Pyramid". Scaffold Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -203,8 +203,8 @@ Mako ~~~~ In addition to Chameleon templating, Pyramid now also provides built-in -support for :term:`Mako` templating. See :ref:`mako_templates` for more -information. +support for :term:`Mako` templating. See +:ref:`available_template_system_bindings` for more information. URL Dispatch ~~~~~~~~~~~~ diff --git a/docs/whatsnew-1.1.rst b/docs/whatsnew-1.1.rst index 5cba8dd3e..086c12ca2 100644 --- a/docs/whatsnew-1.1.rst +++ b/docs/whatsnew-1.1.rst @@ -13,7 +13,7 @@ Terminology Changes The term "template" used by the Pyramid documentation used to refer to both "paster templates" and "rendered templates" (templates created by a rendering engine. i.e. Mako, Chameleon, Jinja, etc.). "Paster templates" will now be -refered to as "scaffolds", whereas the name for "rendered templates" will +referred to as "scaffolds", whereas the name for "rendered templates" will remain as "templates." Major Feature Additions @@ -397,7 +397,7 @@ Deprecations and Behavior Differences shell you use to invoke ``paster serve`` to see these warnings, e.g. on UNIX, ``PYTHONWARNINGS=all $VENV/bin/paster serve development.ini``. Python 2.5 and 2.6 show deprecation warnings by default, - so this is unecessary there. + so this is unnecessary there. All deprecation warnings are emitted to the console. - The :class:`pyramid.view.static` class has been deprecated in favor of the @@ -540,11 +540,10 @@ Deprecations and Behavior Differences within a static view returns the index.html properly. See also https://github.com/Pylons/pyramid/issues/67. -- Deprecated the - :meth:`pyramid.config.Configurator.set_renderer_globals_factory` method and - the ``renderer_globals`` Configurator constructor parameter. Users should - convert code using this feature to use a BeforeRender event. See the section - :ref:`beforerender_event` in the Hooks chapter. +- Deprecated the ``pyramid.config.Configurator.set_renderer_globals_factory`` + method and the ``renderer_globals`` Configurator constructor parameter. + Users should convert code using this feature to use a BeforeRender event. See + the section :ref:`beforerender_event` in the Hooks chapter. - In Pyramid 1.0, the :class:`pyramid.events.subscriber` directive behaved contrary to the documentation when passed more than one interface object to diff --git a/docs/whatsnew-1.5.rst b/docs/whatsnew-1.5.rst new file mode 100644 index 000000000..57f93cbff --- /dev/null +++ b/docs/whatsnew-1.5.rst @@ -0,0 +1,433 @@ +What's New In Pyramid 1.5 +========================= + +This article explains the new features in :app:`Pyramid` version 1.5 as +compared to its predecessor, :app:`Pyramid` 1.4. It also documents backwards +incompatibilities between the two versions and deprecations added to +:app:`Pyramid` 1.5, as well as software dependency changes and notable +documentation additions. + +Major Backwards Incompatibilities +--------------------------------- + +- Pyramid no longer depends on or configures the Mako and Chameleon templating + system renderers by default. Disincluding these templating systems by + default means that the Pyramid core has fewer dependencies and can run on + future platforms without immediate concern for the compatibility of its + templating add-ons. It also makes maintenance slightly more effective, as + different people can maintain the templating system add-ons that they + understand and care about without needing commit access to the Pyramid core, + and it allows users who just don't want to see any packages they don't use + come along for the ride when they install Pyramid. + + This means that upon upgrading to Pyramid 1.5a2+, projects that use either + of these templating systems will see a traceback that ends something like + this when their application attempts to render a Chameleon or Mako template:: + + ValueError: No such renderer factory .pt + + Or:: + + ValueError: No such renderer factory .mako + + Or:: + + ValueError: No such renderer factory .mak + + Support for Mako templating has been moved into an add-on package named + ``pyramid_mako``, and support for Chameleon templating has been moved into + an add-on package named ``pyramid_chameleon``. These packages are drop-in + replacements for the old built-in support for these templating langauges. + All you have to do is install them and make them active in your configuration + to register renderer factories for ``.pt`` and/or ``.mako`` (or ``.mak``) to + make your application work again. + + To re-add support for Chameleon and/or Mako template renderers into your + existing projects, follow the below steps. + + If you depend on Mako templates: + + * Make sure the ``pyramid_mako`` package is installed. One way to do this + is by adding ``pyramid_mako`` to the ``install_requires`` section of your + package's ``setup.py`` file and afterwards rerunning ``setup.py develop``:: + + setup( + #... + install_requires=[ + 'pyramid_mako', # new dependency + 'pyramid', + #... + ], + ) + + * Within the portion of your application which instantiates a Pyramid + :class:`~pyramid.config.Configurator` (often the ``main()`` function in + your project's ``__init__.py`` file), tell Pyramid to include the + ``pyramid_mako`` includeme:: + + config = Configurator(.....) + config.include('pyramid_mako') + + If you depend on Chameleon templates: + + * Make sure the ``pyramid_chameleon`` package is installed. One way to do + this is by adding ``pyramid_chameleon`` to the ``install_requires`` section + of your package's ``setup.py`` file and afterwards rerunning + ``setup.py develop``:: + + setup( + #... + install_requires=[ + 'pyramid_chameleon', # new dependency + 'pyramid', + #... + ], + ) + + * Within the portion of your application which instantiates a Pyramid + :class:`~pyramid.config.Configurator` (often the ``main()`` function in + your project's ``__init__.py`` file), tell Pyramid to include the + ``pyramid_chameleon`` includeme:: + + config = Configurator(.....) + config.include('pyramid_chameleon') + + Note that it's also fine to install these packages into *older* Pyramids for + forward compatibility purposes. Even if you don't upgrade to Pyramid 1.5 + immediately, performing the above steps in a Pyramid 1.4 installation is + perfectly fine, won't cause any difference, and will give you forward + compatibility when you eventually do upgrade to Pyramid 1.5. + + With the removal of Mako and Chameleon support from the core, some + unit tests that use the ``pyramid.renderers.render*`` methods may begin to + fail. If any of your unit tests are invoking either + ``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response()`` + with either Mako or Chameleon templates then the + ``pyramid.config.Configurator`` instance in effect during + the unit test should be also be updated to include the addons, as shown + above. For example:: + + class ATest(unittest.TestCase): + def setUp(self): + self.config = pyramid.testing.setUp() + self.config.include('pyramid_mako') + + def test_it(self): + result = pyramid.renderers.render('mypkg:templates/home.mako', {}) + + Or:: + + class ATest(unittest.TestCase): + def setUp(self): + self.config = pyramid.testing.setUp() + self.config.include('pyramid_chameleon') + + def test_it(self): + result = pyramid.renderers.render('mypkg:templates/home.pt', {}) + +- If you're using the Pyramid debug toolbar, when you upgrade Pyramid to + 1.5a2+, you'll also need to upgrade the ``pyramid_debugtoolbar`` package to + at least version 1.0.8, as older toolbar versions are not compatible with + Pyramid 1.5a2+ due to the removal of Mako support from the core. It's + fine to use this newer version of the toolbar code with older Pyramids too. + +Feature Additions +----------------- + +The feature additions in Pyramid 1.5 follow. + +- Add ``pdistreport`` script, which prints the Python version in use, the + Pyramid version in use, and the version number and location of all Python + distributions currently installed. + +- Add the ability to invert the result of any view, route, or subscriber + predicate value using the ``not_`` class. For example: + + .. code-block:: python + + from pyramid.config import not_ + + @view_config(route_name='myroute', request_method=not_('POST')) + def myview(request): ... + + The above example will ensure that the view is called if the request method + is not POST, at least if no other view is more specific. + + The :class:`pyramid.config.not_` class can be used against any value that is + a predicate value passed in any of these contexts: + + - :meth:`pyramid.config.Configurator.add_view` + + - :meth:`pyramid.config.Configurator.add_route` + + - :meth:`pyramid.config.Configurator.add_subscriber` + + - :meth:`pyramid.view.view_config` + + - :meth:`pyramid.events.subscriber` + +- View lookup will now search for valid views based on the inheritance + hierarchy of the context. It tries to find views based on the most specific + context first, and upon predicate failure, will move up the inheritance chain + to test views found by the super-type of the context. In the past, only the + most specific type containing views would be checked and if no matching view + could be found then a PredicateMismatch would be raised. Now predicate + mismatches don't hide valid views registered on super-types. Here's an + example that now works: + + .. code-block:: python + + class IResource(Interface): + + ... + + @view_config(context=IResource) + def get(context, request): + + ... + + @view_config(context=IResource, request_method='POST') + def post(context, request): + + ... + + @view_config(context=IResource, request_method='DELETE') + def delete(context, request): + + ... + + @implementer(IResource) + class MyResource: + + ... + + @view_config(context=MyResource, request_method='POST') + def override_post(context, request): + + ... + + Previously the override_post view registration would hide the get + and delete views in the context of MyResource -- leading to a + predicate mismatch error when trying to use GET or DELETE + methods. Now the views are found and no predicate mismatch is + raised. + See https://github.com/Pylons/pyramid/pull/786 and + https://github.com/Pylons/pyramid/pull/1004 and + https://github.com/Pylons/pyramid/pull/1046 + +- ``scripts/prequest.py`` (aka the ``prequest`` console script): added support + for submitting ``PUT`` and ``PATCH`` requests. See + https://github.com/Pylons/pyramid/pull/1033. add support for submitting + ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify basic + authentication credentials in the request via a ``--login`` argument to the + script. See https://github.com/Pylons/pyramid/pull/1039. + +- The :meth:`pyramid.config.Configurator.add_route` method now supports being + called with an external URL as pattern. See + https://github.com/Pylons/pyramid/issues/611 and the documentation section + :ref:`external_route_narr`. + +- :class:`pyramid.authorization.ACLAuthorizationPolicy` supports ``__acl__`` as + a callable. This removes the ambiguity between the potential + ``AttributeError`` that would be raised on the ``context`` when the property + was not defined and the ``AttributeError`` that could be raised from any + user-defined code within a dynamic property. It is recommended to define a + dynamic ACL as a callable to avoid this ambiguity. See + https://github.com/Pylons/pyramid/issues/735. + +- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to + :meth:`pyramid.config.Configurator.add_static_view`. This allows + externally-hosted static URLs to be generated based on the current protocol. + +- The :class:`pyramid.authentication.AuthTktAuthenticationPolicy` class has two + new options to configure its domain usage: + + * ``parent_domain``: if set the authentication cookie is set on + the parent domain. This is useful if you have multiple sites sharing the + same domain. + + * ``domain``: if provided the cookie is always set for this domain, bypassing + all usual logic. + + See https://github.com/Pylons/pyramid/pull/1028, + https://github.com/Pylons/pyramid/pull/1072 and + https://github.com/Pylons/pyramid/pull/1078. + +- The :class:`pyramid.authentication.AuthTktPolicy` now supports IPv6 + addresses when using the ``include_ip=True`` option. This is possibly + incompatible with alternative ``auth_tkt`` implementations, as the + specification does not define how to properly handle IPv6. See + https://github.com/Pylons/pyramid/issues/831. + +- Make it possible to use variable arguments via + :func:`pyramid.paster.get_appsettings`. This also allowed the generated + ``initialize_db`` script from the ``alchemy`` scaffold to grow support for + options in the form ``a=1 b=2`` so you can fill in values in a parameterized + ``.ini`` file, e.g. ``initialize_myapp_db etc/development.ini a=1 b=2``. + See https://github.com/Pylons/pyramid/pull/911 + +- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view + predicate now take into account the value of the HTTP header named + ``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they + always did). The header is tried when the form parameter does not exist. + +- You can now generate "hybrid" urldispatch/traversal URLs more easily by using + the new ``route_name``, ``route_kw`` and ``route_remainder_name`` arguments + to :meth:`~pyramid.request.Request.resource_url` and + :meth:`~pyuramid.request.Request.resource_path`. See + :ref:`generating_hybrid_urls`. + +- A new http exception superclass named + :class:`~pyramid.httpexceptions.HTTPSuccessful` was added. You can use this + class as the ``context`` of an exception view to catch all 200-series + "exceptions" (e.g. "raise HTTPOk"). This also allows you to catch *only* the + :class:`~pyramid.httpexceptions.HTTPOk` exception itself; previously this was + impossible because a number of other exceptions (such as ``HTTPNoContent``) + inherited from ``HTTPOk``, but now they do not. + +- It is now possible to escape double braces in Pyramid scaffolds (unescaped, + these represent replacement values). You can use ``\{\{a\}\}`` to + represent a "bare" ``{{a}}``. See + https://github.com/Pylons/pyramid/pull/862 + +- Add ``localizer`` and ``locale_name`` properties (reified) to + :class:`pyramid.request.Request`. See + https://github.com/Pylons/pyramid/issues/508. Note that the + :func:`pyramid.i18n.get_localizer` and :func:`pyramid.i18n.get_locale_name` + functions now simply look up these properties on the request. + +- The ``pserve`` command now takes a ``-v`` (or ``--verbose``) flag and a + ``-q`` (or ``--quiet``) flag. Output from running ``pserve`` can be + controlled using these flags. ``-v`` can be specified multiple times to + increase verbosity. ``-q`` sets verbosity to ``0`` unconditionally. The + default verbosity level is ``1``. + +- The ``alchemy`` scaffold tests now provide better coverage. See + https://github.com/Pylons/pyramid/pull/1029 + +- Users can now provide dotted Python names to as the ``factory`` argument + the Configurator methods named + :meth:`~pyramid.config.Configurator.add_view_predicate`, + :meth:`~pyramid.config.Configurator.add_route_predicate` and + :meth:`~pyramid.config.Configurator.add_subscriber_predicate`. Instead of + passing the predicate factory directly, you can pass a dotted name which + refers to the factory. + +- :func:`pyramid.path.package_name` no longer thows an exception when resolving + the package name for namespace packages that have no ``__file__`` attribute. + +Other Backwards Incompatibilities +--------------------------------- + +- Modified the :meth:`~pyramid.request.Reuqest.current_route_url` method. The + method previously returned the URL without the query string by default, it + now does attach the query string unless it is overriden. + +- The :meth:`~pyramid.request.Request.route_url` and + :meth:`~pyramid.request.Request.route_path` APIs no longer quote ``/`` to + ``%2F`` when a replacement value contains a ``/``. This was pointless, as + WSGI servers always unquote the slash anyway, and Pyramid never sees the + quoted value. + +- It is no longer possible to set a ``locale_name`` attribute of the request, + nor is it possible to set a ``localizer`` attribute of the request. These + are now "reified" properties that look up a locale name and localizer + respectively using the machinery described in :ref:`i18n_chapter`. + +- If you send an ``X-Vhm-Root`` header with a value that ends with a slash (or + any number of slashes), the trailing slash(es) will be removed before a URL + is generated when you use use :meth:`~pyramid.request.Request.resource_url` + or :meth:`~pyramid.request.Request.resource_path`. Previously the virtual + root path would not have trailing slashes stripped, which would influence URL + generation. + +- The :class:`pyramid.interfaces.IResourceURL` interface has now grown two new + attributes: ``virtual_path_tuple`` and ``physical_path_tuple``. These should + be the tuple form of the resource's path (physical and virtual). + +- Removed the ``request.response_*`` varying attributes (such + as``request.response_headers``) . These attributes had been deprecated + since Pyramid 1.1, and as per the deprecation policy, have now been removed. + +- ``request.response`` will no longer be mutated when using the + :func:`pyramid.renderers.render` API. Almost all renderers mutate the + ``request.response`` response object (for example, the JSON renderer sets + ``request.response.content_type`` to ``application/json``), but this is + only necessary when the renderer is generating a response; it was a bug + when it was done as a side effect of calling + :func:`pyramid.renderers.render`. + +- Removed the ``bfg2pyramid`` fixer script. + +- The :class:`pyramid.events.NewResponse` event is now sent **after** response + callbacks are executed. It previously executed before response callbacks + were executed. Rationale: it's more useful to be able to inspect the response + after response callbacks have done their jobs instead of before. + +- Removed the class named ``pyramid.view.static`` that had been deprecated + since Pyramid 1.1. Instead use :class:`pyramid.static.static_view` with the + ``use_subpath=True`` argument. + +- Removed the ``pyramid.view.is_response`` function that had been deprecated + since Pyramid 1.1. Use the :meth:`pyramid.request.Request.is_response` + method instead. + +- Removed the ability to pass the following arguments to + :meth:`pyramid.config.Configurator.add_route`: ``view``, ``view_context``. + ``view_for``, ``view_permission``, ``view_renderer``, and ``view_attr``. + Using these arguments had been deprecated since Pyramid 1.1. Instead of + passing view-related arguments to ``add_route``, use a separate call to + :meth:`pyramid.config.Configurator.add_view` to associate a view with a route + using its ``route_name`` argument. Note that this impacts the + :meth:`pyramid.config.Configurator.add_static_view` function too, because + it delegates to``add_route``. + +- Removed the ability to influence and query a :class:`pyramid.request.Request` + object as if it were a dictionary. Previously it was possible to use methods + like ``__getitem__``, ``get``, ``items``, and other dictlike methods to + access values in the WSGI environment. This behavior had been deprecated + since Pyramid 1.1. Use methods of ``request.environ`` (a real dictionary) + instead. + +- Removed ancient backwards compatibily hack in + ``pyramid.traversal.DefaultRootFactory`` which populated the ``__dict__`` of + the factory with the matchdict values for compatibility with BFG 0.9. + +- The ``renderer_globals_factory`` argument to the + :class:`pyramid.config.Configurator` constructor and the + coresponding argument to :meth:`~pyramid.config.Configurator.setup_registry` + has been removed. The ``set_renderer_globals_factory`` method of + :class:`~pyramid.config.Configurator` has also been removed. The (internal) + ``pyramid.interfaces.IRendererGlobals`` interface was also removed. These + arguments, methods and interfaces had been deprecated since 1.1. Use a + ``BeforeRender`` event subscriber as documented in the "Hooks" chapter of the + Pyramid narrative documentation instead of providing renderer globals values + to the configurator. + + +Deprecations +------------ + +- Returning a ``("defname", dict)`` tuple from a view which has a Mako renderer + is now deprecated. Instead you should use the renderer spelling + ``foo#defname.mak`` in the view configuration definition and return a dict + only. + +- The :meth:`pyramid.config.Configurator.set_request_property` method now issues + a deprecation warning when used. It had been docs-deprecated in 1.4 + but did not issue a deprecation warning when used. + +Documentation Enhancements +-------------------------- + +- A new documentation chapter named :ref:`quick_tour` was added. It describes + starting out with Pyramid from a high level. + +- Many other enhancements. + + +Dependency Changes +------------------ + +- Pyramid no longer depends upon ``Mako`` or ``Chameleon``. + diff --git a/hacking-tox.ini b/hacking-tox.ini new file mode 100644 index 000000000..9520b7aef --- /dev/null +++ b/hacking-tox.ini @@ -0,0 +1,25 @@ +[tox] +envlist = + env27,ttw27-create,ttw27-install + +[testenv:env27] +envdir = env27 +basepython = python2.7 +usedevelop = True +deps = setuptools-git +commands = + python setup.py dev + +[testenv:ttw27-create] +envdir = env27 +usedevelop = True +changedir = env27 +commands = + pcreate -s starter hacking + +[testenv:ttw27-install] +envdir = env27 +usedevelop = True +changedir = env27/hacking +commands = + python setup.py develop diff --git a/pyramid/authentication.py b/pyramid/authentication.py index bc0286ed3..454ebd4b2 100644 --- a/pyramid/authentication.py +++ b/pyramid/authentication.py @@ -511,9 +511,32 @@ class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy): ``wild_domain`` Default: ``True``. An auth_tkt cookie will be generated for the - wildcard domain. + wildcard domain. If your site is hosted as ``example.com`` this + will make the cookie available for sites underneath ``example.com`` + such as ``www.example.com``. Optional. + ``parent_domain`` + + Default: ``False``. An auth_tkt cookie will be generated for the + parent domain of the current site. For example if your site is + hosted under ``www.example.com`` a cookie will be generated for + ``.example.com``. This can be useful if you have multiple sites + sharing the same domain. This option supercedes the ``wild_domain`` + option. + Optional. + + This option is available as of :app:`Pyramid` 1.5. + + ``domain`` + + Default: ``None``. If provided the auth_tkt cookie will only be + set for this domain. This option is not compatible with ``wild_domain`` + and ``parent_domain``. + Optional. + + This option is available as of :app:`Pyramid` 1.5. + ``hashalg`` Default: ``md5`` (the literal string). @@ -565,7 +588,9 @@ class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy): http_only=False, wild_domain=True, debug=False, - hashalg=_marker + hashalg=_marker, + parent_domain=False, + domain=None, ): if hashalg is _marker: hashalg = 'md5' @@ -603,6 +628,8 @@ class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy): path=path, wild_domain=wild_domain, hashalg=hashalg, + parent_domain=parent_domain, + domain=domain, ) self.callback = callback self.debug = debug @@ -800,7 +827,7 @@ class AuthTktCookieHelper(object): def __init__(self, secret, cookie_name='auth_tkt', secure=False, include_ip=False, timeout=None, reissue_time=None, max_age=None, http_only=False, path="/", wild_domain=True, - hashalg='md5'): + hashalg='md5', parent_domain=False, domain=None): self.secret = secret self.cookie_name = cookie_name self.include_ip = include_ip @@ -811,6 +838,8 @@ class AuthTktCookieHelper(object): self.http_only = http_only self.path = path self.wild_domain = wild_domain + self.parent_domain = parent_domain + self.domain = domain self.hashalg = hashalg static_flags = [] @@ -848,19 +877,25 @@ class AuthTktCookieHelper(object): if ':' in cur_domain: cur_domain = cur_domain.split(':', 1)[0] - cookies = [ - ('Set-Cookie', '%s="%s"; Path=%s%s%s' % ( - self.cookie_name, value, self.path, max_age, self.static_flags)), - ('Set-Cookie', '%s="%s"; Path=%s; Domain=%s%s%s' % ( - self.cookie_name, value, self.path, cur_domain, max_age, - self.static_flags)), - ] - - if self.wild_domain: - wild_domain = '.' + cur_domain - cookies.append(('Set-Cookie', '%s="%s"; Path=%s; Domain=%s%s%s' % ( - self.cookie_name, value, self.path, wild_domain, max_age, - self.static_flags))) + + domains = [] + if self.domain: + domains.append(self.domain) + else: + if self.parent_domain and cur_domain.count('.') > 1: + domains.append('.' + cur_domain.split('.', 1)[1]) + else: + domains.append(None) + domains.append(cur_domain) + if self.wild_domain: + domains.append('.' + cur_domain) + + cookies = [] + base_cookie = '%s="%s"; Path=%s%s%s' % (self.cookie_name, value, + self.path, max_age, self.static_flags) + for domain in domains: + domain = '; Domain=%s' % domain if domain is not None else '' + cookies.append(('Set-Cookie', '%s%s' % (base_cookie, domain))) return cookies diff --git a/pyramid/authorization.py b/pyramid/authorization.py index 1fd05e244..5e7baa19d 100644 --- a/pyramid/authorization.py +++ b/pyramid/authorization.py @@ -122,6 +122,9 @@ class ACLAuthorizationPolicy(object): allowed_here = set() denied_here = set() + if acl and callable(acl): + acl = acl() + for ace_action, ace_principal, ace_permissions in acl: if not is_nonstr_iter(ace_permissions): ace_permissions = [ace_permissions] diff --git a/pyramid/chameleon_text.py b/pyramid/chameleon_text.py deleted file mode 100644 index 8cf04bf79..000000000 --- a/pyramid/chameleon_text.py +++ /dev/null @@ -1,38 +0,0 @@ -from zope.interface import implementer - -from chameleon.zpt.template import PageTextTemplateFile - -from pyramid.interfaces import ITemplateRenderer - -from pyramid.decorator import reify -from pyramid import renderers - -def renderer_factory(info): - return renderers.template_renderer_factory(info, TextTemplateRenderer) - -@implementer(ITemplateRenderer) -class TextTemplateRenderer(object): - def __init__(self, path, lookup, macro=None): - self.path = path - self.lookup = lookup - # text template renderers have no macros, so we ignore the - # macro arg - - @reify # avoid looking up reload_templates before manager pushed - def template(self): - return PageTextTemplateFile(self.path, - auto_reload=self.lookup.auto_reload, - debug=self.lookup.debug, - translate=self.lookup.translate) - - def implementation(self): - return self.template - - def __call__(self, value, system): - try: - system.update(value) - except (TypeError, ValueError): - raise ValueError('renderer was passed non-dictionary as value') - result = self.template(**system) - return result - diff --git a/pyramid/chameleon_zpt.py b/pyramid/chameleon_zpt.py deleted file mode 100644 index d8a8ee1be..000000000 --- a/pyramid/chameleon_zpt.py +++ /dev/null @@ -1,44 +0,0 @@ -from zope.interface import implementer - -from chameleon.zpt.template import PageTemplateFile - -from pyramid.interfaces import ITemplateRenderer -from pyramid.decorator import reify -from pyramid import renderers - -def renderer_factory(info): - return renderers.template_renderer_factory(info, ZPTTemplateRenderer) - -@implementer(ITemplateRenderer) -class ZPTTemplateRenderer(object): - def __init__(self, path, lookup, macro=None): - self.path = path - self.lookup = lookup - self.macro = macro - - @reify # avoid looking up reload_templates before manager pushed - def template(self): - tf = PageTemplateFile( - self.path, - auto_reload=self.lookup.auto_reload, - debug=self.lookup.debug, - translate=self.lookup.translate - ) - if self.macro: - # render only the portion of the template included in a - # define-macro named the value of self.macro - macro_renderer = tf.macros[self.macro].include - tf._render = macro_renderer - return tf - - def implementation(self): - return self.template - - def __call__(self, value, system): - try: - system.update(value) - except (TypeError, ValueError): - raise ValueError('renderer was passed non-dictionary as value') - result = self.template(**system) - return result - diff --git a/pyramid/compat.py b/pyramid/compat.py index 222810b3b..bfa345b88 100644 --- a/pyramid/compat.py +++ b/pyramid/compat.py @@ -160,7 +160,7 @@ if PY3: # pragma: no cover return d.values() def iterkeys_(d): return d.keys() -else: +else: # pragma: no cover def iteritems_(d): return d.iteritems() def itervalues_(d): diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py index 4f7899b54..19c47cbd9 100644 --- a/pyramid/config/__init__.py +++ b/pyramid/config/__init__.py @@ -4,7 +4,6 @@ import logging import operator import os import sys -import warnings import venusian from webob.exc import WSGIHTTPException as WebobWSGIHTTPException @@ -63,14 +62,13 @@ from pyramid.config.adapters import AdaptersConfiguratorMixin from pyramid.config.assets import AssetsConfiguratorMixin from pyramid.config.factories import FactoriesConfiguratorMixin from pyramid.config.i18n import I18NConfiguratorMixin -from pyramid.config.rendering import DEFAULT_RENDERERS from pyramid.config.rendering import RenderingConfiguratorMixin from pyramid.config.routes import RoutesConfiguratorMixin from pyramid.config.security import SecurityConfiguratorMixin from pyramid.config.settings import SettingsConfiguratorMixin from pyramid.config.testing import TestingConfiguratorMixin from pyramid.config.tweens import TweensConfiguratorMixin -from pyramid.config.util import PredicateList +from pyramid.config.util import PredicateList, not_ from pyramid.config.views import ViewsConfiguratorMixin from pyramid.config.zca import ZCAConfiguratorMixin @@ -86,6 +84,9 @@ _marker = object() ConfigurationError = ConfigurationError # pyflakes +not_ = not_ # pyflakes, this is an API + + class Configurator( TestingConfiguratorMixin, TweensConfiguratorMixin, @@ -170,15 +171,6 @@ class Configurator( See :ref:`changing_the_request_factory`. By default it is ``None``, which means use the default request factory. - If ``renderer_globals_factory`` is passed, it should be a :term:`renderer - globals` factory implementation or a :term:`dotted Python name` to the - same. See :ref:`adding_renderer_globals`. By default, it is ``None``, - which means use no renderer globals factory. - - .. deprecated:: 1.1 - Use a BeforeRender event subscriber as per :ref:`beforerender_event` - in place of ``renderer_globals_factory``. - If ``default_permission`` is passed, it should be a :term:`permission` string to be used as the default permission for all view configuration registrations performed against this @@ -270,7 +262,6 @@ class Configurator( debug_logger=None, locale_negotiator=None, request_factory=None, - renderer_globals_factory=None, default_permission=None, session_factory=None, default_view_mapper=None, @@ -301,7 +292,6 @@ class Configurator( debug_logger=debug_logger, locale_negotiator=locale_negotiator, request_factory=request_factory, - renderer_globals_factory=renderer_globals_factory, default_permission=default_permission, session_factory=session_factory, default_view_mapper=default_view_mapper, @@ -317,7 +307,6 @@ class Configurator( debug_logger=None, locale_negotiator=None, request_factory=None, - renderer_globals_factory=None, default_permission=None, session_factory=None, default_view_mapper=None, @@ -344,7 +333,6 @@ class Configurator( self._fix_registry() self._set_settings(settings) - self._register_response_adapters() if isinstance(debug_logger, string_types): debug_logger = logging.getLogger(debug_logger) @@ -354,9 +342,8 @@ class Configurator( registry.registerUtility(debug_logger, IDebugLogger) - for name, renderer in DEFAULT_RENDERERS: - self.add_renderer(name, renderer) - + self.add_default_response_adapters() + self.add_default_renderers() self.add_default_view_predicates() self.add_default_route_predicates() @@ -375,12 +362,12 @@ class Configurator( self.commit() - # self.commit() should not be called after this point because the - # following registrations should be treated as analogues of methods - # called by the user after configurator construction. Rationale: - # user-supplied implementations should be preferred rather than - # add-on author implementations with the help of automatic conflict - # resolution. + # self.commit() should not be called within this method after this + # point because the following registrations should be treated as + # analogues of methods called by the user after configurator + # construction. Rationale: user-supplied implementations should be + # preferred rather than add-on author implementations with the help of + # automatic conflict resolution. if authentication_policy and not authorization_policy: authorization_policy = ACLAuthorizationPolicy() # default @@ -407,17 +394,6 @@ class Configurator( if request_factory: self.set_request_factory(request_factory) - if renderer_globals_factory: - warnings.warn( - 'Passing ``renderer_globals_factory`` as a Configurator ' - 'constructor parameter is deprecated as of Pyramid 1.1. ' - 'Use a BeforeRender event subscriber as documented in the ' - '"Hooks" chapter of the Pyramid narrative documentation ' - 'instead', - DeprecationWarning, - 2) - self.set_renderer_globals_factory(renderer_globals_factory, - warn=False) if default_permission: self.set_default_permission(default_permission) @@ -509,7 +485,7 @@ class Configurator( '%s predicate named %s' % (type, name), '%s predicate' % type) intr['name'] = name - intr['factory'] = factory + intr['factory'] = self.maybe_dotted(factory) intr['weighs_more_than'] = weighs_more_than intr['weighs_less_than'] = weighs_less_than def register(): @@ -642,7 +618,7 @@ class Configurator( argument named ``config``, which will be an instance of a :term:`Configurator`. However, be warned that it will not be the same configurator instance on which you call this method. The - code which runs as the result of calling the callable should invoke + code which runs as a result of calling the callable should invoke methods on the configurator passed to it which add configuration state. The return value of a callable will be ignored. @@ -1052,7 +1028,7 @@ class ActionState(object): ... v = context.execute_actions() ... except ConfigurationExecutionError, v: ... pass - >>> print v + >>> print(v) exceptions.AttributeError: 'function' object has no attribute 'xxx' in: oops diff --git a/pyramid/config/adapters.py b/pyramid/config/adapters.py index 319beab67..f6a652e3d 100644 --- a/pyramid/config/adapters.py +++ b/pyramid/config/adapters.py @@ -1,3 +1,5 @@ +from webob import Response as WebobResponse + from functools import update_wrapper from zope.interface import Interface @@ -33,7 +35,7 @@ class AdaptersConfiguratorMixin(object): Any number of predicate keyword arguments may be passed in ``**predicates``. Each predicate named will narrow the set of - circumstances that the subscriber will be invoked. Each named + circumstances in which the subscriber will be invoked. Each named predicate must have been registered via :meth:`pyramid.config.Configurator.add_subscriber_predicate` before it can be used. See :ref:`subscriber_predicates` for more information. @@ -147,7 +149,8 @@ class AdaptersConfiguratorMixin(object): Python identifier (it will be used as a ``**predicates`` keyword argument to :meth:`~pyramid.config.Configurator.add_subscriber`). - ``factory`` should be a :term:`predicate factory`. + ``factory`` should be a :term:`predicate factory` or :term:`dotted + Python name` which refers to a predicate factory. See :ref:`subscriber_predicates` for more information. @@ -192,10 +195,9 @@ class AdaptersConfiguratorMixin(object): intr['type'] = type_or_iface self.action(discriminator, register, introspectables=(intr,)) - def _register_response_adapters(self): + def add_default_response_adapters(self): # cope with WebOb response objects that aren't decorated with IResponse - from webob import Response as WebobResponse - self.registry.registerSelfAdapter((WebobResponse,), IResponse) + self.add_response_adapter(None, WebobResponse) @action_method def add_traverser(self, adapter, iface=None): @@ -216,7 +218,7 @@ class AdaptersConfiguratorMixin(object): config.add_traverser(MyCustomTraverser) This would cause the Pyramid superdefault traverser to never be used; - intead all traversal would be done using your ``MyCustomTraverser`` + instead all traversal would be done using your ``MyCustomTraverser`` class, no matter which object was returned by the :term:`root factory` of this application. Note that we passed no arguments to the ``iface`` keyword parameter. The default value of ``iface``, @@ -228,7 +230,7 @@ class AdaptersConfiguratorMixin(object): time. The traverser used can depend on the result of the :term:`root factory`. For instance, if your root factory returns more than one type of object conditionally, you could claim that an alternate - traverser adapter should be used agsinst one particular class or + traverser adapter should be used against one particular class or interface returned by that root factory. When the root factory returned an object that implemented that class or interface, a custom traverser would be used. Otherwise, the default traverser would be diff --git a/pyramid/config/assets.py b/pyramid/config/assets.py index 5d4682349..0616e6cda 100644 --- a/pyramid/config/assets.py +++ b/pyramid/config/assets.py @@ -81,14 +81,12 @@ class OverrideProvider(pkg_resources.DefaultProvider): self, resource_name) @implementer(IPackageOverrides) -class PackageOverrides: +class PackageOverrides(object): # pkg_resources arg in kw args below for testing def __init__(self, package, pkg_resources=pkg_resources): - if hasattr(package, '__loader__') and not isinstance(package.__loader__, - self.__class__): - raise TypeError('Package %s already has a non-%s __loader__ ' - '(probably a module in a zipped egg)' % - (package, self.__class__)) + loader = self._real_loader = getattr(package, '__loader__', None) + if isinstance(loader, self.__class__): + self._real_loader = None # We register ourselves as a __loader__ *only* to support the # setuptools _find_adapter adapter lookup; this class doesn't # actually support the PEP 302 loader "API". This is @@ -150,7 +148,33 @@ class PackageOverrides: for package, rname in self.search_path(resource_name): if pkg_resources.resource_exists(package, rname): return pkg_resources.resource_listdir(package, rname) - + + @property + def real_loader(self): + if self._real_loader is None: + raise NotImplementedError() + return self._real_loader + + def get_data(self, path): + """ See IPEP302Loader. + """ + return self.real_loader.get_data(path) + + def is_package(self, fullname): + """ See IPEP302Loader. + """ + return self.real_loader.is_package(fullname) + + def get_code(self, fullname): + """ See IPEP302Loader. + """ + return self.real_loader.get_code(fullname) + + def get_source(self, fullname): + """ See IPEP302Loader. + """ + return self.real_loader.get_source(fullname) + class DirectoryOverride: def __init__(self, path, package, prefix): diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py index d30df3b74..774125821 100644 --- a/pyramid/config/factories.py +++ b/pyramid/config/factories.py @@ -1,3 +1,4 @@ +from zope.deprecation import deprecate from zope.interface import implementer from pyramid.interfaces import ( @@ -179,12 +180,15 @@ class FactoriesConfiguratorMixin(object): introspectables=(intr,)) @action_method + @deprecate('set_request_propery() is deprecated as of Pyramid 1.5; use ' + 'add_request_method() with the property=True argument instead') def set_request_property(self, callable, name=None, reify=False): """ Add a property to the request object. - .. deprecated:: 1.4 + .. deprecated:: 1.5 :meth:`pyramid.config.Configurator.add_request_method` should be - used instead. + used instead. (This method was docs-deprecated in 1.4 and + issues a real deprecation warning in 1.5). .. versionadded:: 1.3 """ diff --git a/pyramid/config/i18n.py b/pyramid/config/i18n.py index 9eb59e1c7..69af0f9bc 100644 --- a/pyramid/config/i18n.py +++ b/pyramid/config/i18n.py @@ -1,18 +1,13 @@ import os import sys -from translationstring import ChameleonTranslate - from pyramid.interfaces import ( - IChameleonTranslate, ILocaleNegotiator, ITranslationDirectories, ) from pyramid.exceptions import ConfigurationError -from pyramid.i18n import get_localizer from pyramid.path import package_path -from pyramid.threadlocal import get_current_request from pyramid.util import action_method class I18NConfiguratorMixin(object): @@ -108,18 +103,5 @@ class I18NConfiguratorMixin(object): tdirs.insert(0, directory) - if directories: - # We actually only need an IChameleonTranslate function - # utility to be registered zero or one times. We register the - # same function once for each added translation directory, - # which does too much work, but has the same effect. - ctranslate = ChameleonTranslate(translator) - self.registry.registerUtility(ctranslate, IChameleonTranslate) - self.action(None, register, introspectables=introspectables) -def translator(msg): - request = get_current_request() - localizer = get_localizer(request) - return localizer.translate(msg) - diff --git a/pyramid/config/predicates.py b/pyramid/config/predicates.py index ded8fbfbf..c8f66e83d 100644 --- a/pyramid/config/predicates.py +++ b/pyramid/config/predicates.py @@ -294,3 +294,4 @@ class EffectivePrincipalsPredicate(object): if self.val.issubset(rpset): return True return False + diff --git a/pyramid/config/rendering.py b/pyramid/config/rendering.py index 356bf033e..68671d08e 100644 --- a/pyramid/config/rendering.py +++ b/pyramid/config/rendering.py @@ -1,31 +1,21 @@ -import warnings - from pyramid.interfaces import ( IRendererFactory, - IRendererGlobalsFactory, PHASE1_CONFIG, ) from pyramid.util import action_method - -from pyramid import ( - renderers, - chameleon_text, - chameleon_zpt, - ) - -from pyramid.mako_templating import renderer_factory as mako_renderer_factory +from pyramid import renderers DEFAULT_RENDERERS = ( - ('.txt', chameleon_text.renderer_factory), - ('.pt', chameleon_zpt.renderer_factory), - ('.mak', mako_renderer_factory), - ('.mako', mako_renderer_factory), ('json', renderers.json_renderer_factory), ('string', renderers.string_renderer_factory), ) class RenderingConfiguratorMixin(object): + def add_default_renderers(self): + for name, renderer in DEFAULT_RENDERERS: + self.add_renderer(name, renderer) + @action_method def add_renderer(self, name, factory): """ @@ -59,44 +49,3 @@ class RenderingConfiguratorMixin(object): self.action((IRendererFactory, name), register, order=PHASE1_CONFIG, introspectables=(intr,)) - @action_method - def set_renderer_globals_factory(self, factory, warn=True): - """ The object passed as ``factory`` should be an callable (or - a :term:`dotted Python name` which refers to an callable) that - will be used by the :app:`Pyramid` rendering machinery as a - renderers global factory (see :ref:`adding_renderer_globals`). - - The ``factory`` callable must accept a single argument named - ``system`` (which will be a dictionary) and it must return a - dictionary. When an application uses a renderer, the - factory's return dictionary will be merged into the ``system`` - dictionary, and therefore will be made available to the code - which uses the renderer. - - .. deprecated:: 1.1 - Use a BeforeRender event subscriber as documented in the - :ref:`hooks_chapter` chapter instead. - - .. note:: - - Using the ``renderer_globals_factory`` argument - to the :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. - """ - if warn: - warnings.warn( - 'Calling the ``set_renderer_globals`` method of a Configurator ' - 'is deprecated as of Pyramid 1.1. Use a BeforeRender event ' - 'subscriber as documented in the "Hooks" chapter of the ' - 'Pyramid narrative documentation instead', - DeprecationWarning, - 3) - - factory = self.maybe_dotted(factory) - def register(): - self.registry.registerUtility(factory, IRendererGlobalsFactory) - intr = self.introspectable('renderer globals factory', None, - self.object_description(factory), - 'renderer globals factory') - intr['factory'] = factory - self.action(IRendererGlobalsFactory, register) diff --git a/pyramid/config/routes.py b/pyramid/config/routes.py index 7a7bbae1a..9dca9e51e 100644 --- a/pyramid/config/routes.py +++ b/pyramid/config/routes.py @@ -1,5 +1,6 @@ import warnings +from pyramid.compat import urlparse from pyramid.interfaces import ( IRequest, IRouteRequest, @@ -24,8 +25,6 @@ class RoutesConfiguratorMixin(object): def add_route(self, name, pattern=None, - view=None, - view_for=None, permission=None, factory=None, for_=None, @@ -37,11 +36,7 @@ class RoutesConfiguratorMixin(object): request_param=None, traverse=None, custom_predicates=(), - view_permission=None, renderer=None, - view_renderer=None, - view_context=None, - view_attr=None, use_global_views=False, path=None, pregenerator=None, @@ -90,10 +85,10 @@ class RoutesConfiguratorMixin(object): ``traverse`` argument provided to ``add_route`` is ``/{article}``, when a request comes in that causes the route to match in such a way that the ``article`` match value is - '1' (when the request URI is ``/articles/1/edit``), the + ``'1'`` (when the request URI is ``/articles/1/edit``), the traversal path will be generated as ``/1``. This means that the root object's ``__getitem__`` will be called with the - name ``1`` during the traversal phase. If the ``1`` object + name ``'1'`` during the traversal phase. If the ``'1'`` object exists, it will become the :term:`context` of the request. :ref:`traversal_chapter` has more information about traversal. @@ -235,7 +230,8 @@ class RoutesConfiguratorMixin(object): wildcard mimetype match token in the form ``text/*`` or a match-all wildcard mimetype match token in the form ``*/*``. If any of the forms matches the ``Accept`` header of the - request, this predicate will be true. If this predicate + request, or if the ``Accept`` header isn't set at all in the + request, this predicate will be true. If this predicate returns ``False``, route matching continues. effective_principals @@ -253,6 +249,8 @@ class RoutesConfiguratorMixin(object): custom_predicates + .. deprecated:: 1.5 + This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates does what you need. Custom predicates @@ -280,98 +278,19 @@ class RoutesConfiguratorMixin(object): .. versionadded:: 1.4 - View-Related Arguments - - .. warning:: - - The arguments described below have been deprecated as of - :app:`Pyramid` 1.1. *Do not use these for new development; they - should only be used to support older code bases which depend upon - them.* Use a separate call to - :meth:`pyramid.config.Configurator.add_view` to associate a view - with a route using the ``route_name`` argument. - - view - - .. deprecated:: 1.1 - - A Python object or :term:`dotted Python name` to the same - object that will be used as a view callable when this route - matches. e.g. ``mypackage.views.my_view``. - - view_context - - .. deprecated:: 1.1 - - A class or an :term:`interface` or :term:`dotted Python - name` to the same object which the :term:`context` of the - view should match for the view named by the route to be - used. This argument is only useful if the ``view`` - attribute is used. If this attribute is not specified, the - default (``None``) will be used. - - If the ``view`` argument is not provided, this argument has - no effect. - - This attribute can also be spelled as ``for_`` or ``view_for``. - - view_permission - - .. deprecated:: 1.1 - - The permission name required to invoke the view associated - with this route. e.g. ``edit``. (see - :ref:`using_security_with_urldispatch` for more information - about permissions). - - If the ``view`` attribute is not provided, this argument has - no effect. - - This argument can also be spelled as ``permission``. - - view_renderer - - .. deprecated:: 1.1 - - This is either a single string term (e.g. ``json``) or a - string implying a path or :term:`asset specification` - (e.g. ``templates/views.pt``). If the renderer value is a - single term (does not contain a dot ``.``), the specified - term will be used to look up a renderer implementation, and - that renderer implementation will be used to construct a - response from the view return value. If the renderer term - contains a dot (``.``), the specified term will be treated - as a path, and the filename extension of the last element in - the path will be used to look up the renderer - implementation, which will be passed the full path. The - renderer implementation will be used to construct a response - from the view return value. See - :ref:`views_which_use_a_renderer` for more information. - - If the ``view`` argument is not provided, this argument has - no effect. - - This argument can also be spelled as ``renderer``. - - view_attr - - .. deprecated:: 1.1 - - The view machinery defaults to using the ``__call__`` method - of the view callable (or the function itself, if the view - callable is a function) to obtain a response dictionary. - The ``attr`` value allows you to vary the method attribute - used to obtain the response. For example, if your view was - a class, and the class has a method named ``index`` and you - wanted to use this method instead of the class' ``__call__`` - method to return the response, you'd say ``attr="index"`` in - the view configuration for the view. This is - most useful when the view definition is a class. - - If the ``view`` argument is not provided, this argument has no - effect. - """ + if custom_predicates: + warnings.warn( + ('The "custom_predicates" argument to Configurator.add_route ' + 'is deprecated as of Pyramid 1.5. Use ' + '"config.add_route_predicate" and use the registered ' + 'route predicate as a predicate argument to add_route ' + 'instead. See "Adding A Third Party View, Route, or ' + 'Subscriber Predicate" in the "Hooks" chapter of the ' + 'documentation for more information.'), + DeprecationWarning, + stacklevel=3 + ) # these are route predicates; if they do not match, the next route # in the routelist will be tried if request_method is not None: @@ -383,7 +302,39 @@ class RoutesConfiguratorMixin(object): if pattern is None: raise ConfigurationError('"pattern" argument may not be None') - if self.route_prefix: + # check for an external route; an external route is one which is + # is a full url (e.g. 'http://example.com/{id}') + parsed = urlparse.urlparse(pattern) + if parsed.hostname: + pattern = parsed.path + + original_pregenerator = pregenerator + def external_url_pregenerator(request, elements, kw): + if '_app_url' in kw: + raise ValueError( + 'You cannot generate a path to an external route ' + 'pattern via request.route_path nor pass an _app_url ' + 'to request.route_url when generating a URL for an ' + 'external route pattern (pattern was "%s") ' % + (pattern,) + ) + if '_scheme' in kw: + scheme = kw['_scheme'] + elif parsed.scheme: + scheme = parsed.scheme + else: + scheme = request.scheme + kw['_app_url'] = '{0}://{1}'.format(scheme, parsed.netloc) + + if original_pregenerator: + elements, kw = original_pregenerator( + request, elements, kw) + return elements, kw + + pregenerator = external_url_pregenerator + static = True + + elif self.route_prefix: pattern = self.route_prefix.rstrip('/') + '/' + pattern.lstrip('/') mapper = self.get_routes_mapper() @@ -465,19 +416,6 @@ class RoutesConfiguratorMixin(object): self.action(('route', name), register_route_request_iface, order=PHASE2_CONFIG, introspectables=introspectables) - # deprecated adding views from add_route; must come after - # route registration for purposes of autocommit ordering - if any([view, view_context, view_permission, view_renderer, - view_for, for_, permission, renderer, view_attr]): - self._add_view_from_route( - route_name=name, - view=view, - permission=view_permission or permission, - context=view_context or view_for or for_, - renderer=view_renderer or renderer, - attr=view_attr, - ) - @action_method def add_route_predicate(self, name, factory, weighs_more_than=None, weighs_less_than=None): @@ -489,7 +427,8 @@ class RoutesConfiguratorMixin(object): Python identifier (it will be used as a keyword argument to ``add_view``). - ``factory`` should be a :term:`predicate factory`. + ``factory`` should be a :term:`predicate factory` or :term:`dotted + Python name` which refers to a predicate factory. See :ref:`view_and_route_predicates` for more information. @@ -517,7 +456,7 @@ class RoutesConfiguratorMixin(object): ('traverse', p.TraversePredicate), ): self.add_route_predicate(name, factory) - + def get_routes_mapper(self): """ Return the :term:`routes mapper` object associated with this configurator's :term:`registry`.""" @@ -527,49 +466,3 @@ class RoutesConfiguratorMixin(object): self.registry.registerUtility(mapper, IRoutesMapper) return mapper - def _add_view_from_route(self, - route_name, - view, - context, - permission, - renderer, - attr, - ): - if view: - self.add_view( - permission=permission, - context=context, - view=view, - name='', - route_name=route_name, - renderer=renderer, - attr=attr, - ) - else: - # prevent mistakes due to misunderstanding of how hybrid calls to - # add_route and add_view interact - if attr: - raise ConfigurationError( - 'view_attr argument not permitted without view ' - 'argument') - if context: - raise ConfigurationError( - 'view_context argument not permitted without view ' - 'argument') - if permission: - raise ConfigurationError( - 'view_permission argument not permitted without view ' - 'argument') - if renderer: - raise ConfigurationError( - 'view_renderer argument not permitted without ' - 'view argument') - - warnings.warn( - 'Passing view-related arguments to add_route() is deprecated as of ' - 'Pyramid 1.1. Use add_view() to associate a view with a route ' - 'instead. See "Deprecations" in "What\'s New in Pyramid 1.1" ' - 'within the general Pyramid documentation for further details.', - DeprecationWarning, - 4) - diff --git a/pyramid/config/util.py b/pyramid/config/util.py index af0dd1641..892592196 100644 --- a/pyramid/config/util.py +++ b/pyramid/config/util.py @@ -28,6 +28,69 @@ def as_sorted_tuple(val): val = tuple(sorted(val)) return val +class not_(object): + """ + + You can invert the meaning of any predicate value by wrapping it in a call + to :class:`pyramid.config.not_`. + + .. code-block:: python + :linenos: + + from pyramid.config import not_ + + config.add_view( + 'mypackage.views.my_view', + route_name='ok', + request_method=not_('POST') + ) + + The above example will ensure that the view is called if the request method + is *not* ``POST``, at least if no other view is more specific. + + This technique of wrapping a predicate value in ``not_`` can be used + anywhere predicate values are accepted: + + - :meth:`pyramid.config.Configurator.add_view` + + - :meth:`pyramid.config.Configurator.add_route` + + - :meth:`pyramid.config.Configurator.add_subscriber` + + - :meth:`pyramid.view.view_config` + + - :meth:`pyramid.events.subscriber` + + .. versionadded:: 1.5 + """ + def __init__(self, value): + self.value = value + +class Notted(object): + def __init__(self, predicate): + self.predicate = predicate + + def _notted_text(self, val): + # if the underlying predicate doesnt return a value, it's not really + # a predicate, it's just something pretending to be a predicate, + # so dont update the hash + if val: + val = '!' + val + return val + + def text(self): + return self._notted_text(self.predicate.text()) + + def phash(self): + return self._notted_text(self.predicate.phash()) + + def __call__(self, context, request): + result = self.predicate(context, request) + phash = self.phash() + if phash: + result = not result + return result + # under = after # over = before @@ -74,7 +137,14 @@ class PredicateList(object): if not isinstance(vals, predvalseq): vals = (vals,) for val in vals: - pred = predicate_factory(val, config) + realval = val + notted = False + if isinstance(val, not_): + realval = val.value + notted = True + pred = predicate_factory(realval, config) + if notted: + pred = Notted(pred) hashes = pred.phash() if not is_nonstr_iter(hashes): hashes = [hashes] diff --git a/pyramid/config/views.py b/pyramid/config/views.py index 707c84043..233bbac12 100644 --- a/pyramid/config/views.py +++ b/pyramid/config/views.py @@ -1,6 +1,7 @@ import inspect import operator import os +import warnings from zope.interface import ( Interface, @@ -1027,6 +1028,8 @@ class ViewsConfiguratorMixin(object): custom_predicates + .. deprecated:: 1.5 + This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates do what you need. Custom predicates can be combined with @@ -1050,6 +1053,19 @@ class ViewsConfiguratorMixin(object): .. versionadded: 1.4a1 """ + if custom_predicates: + warnings.warn( + ('The "custom_predicates" argument to Configurator.add_view ' + 'is deprecated as of Pyramid 1.5. Use ' + '"config.add_view_predicate" and use the registered ' + 'view predicate as a predicate argument to add_view instead. ' + 'See "Adding A Third Party View, Route, or Subscriber ' + 'Predicate" in the "Hooks" chapter of the documentation ' + 'for more information.'), + DeprecationWarning, + stacklevel=4 + ) + view = self.maybe_dotted(view) context = self.maybe_dotted(context) for_ = self.maybe_dotted(for_) @@ -1133,6 +1149,8 @@ class ViewsConfiguratorMixin(object): attr, self.object_description(view)) else: view_desc = self.object_description(view) + + tmpl_intr = None view_intr = self.introspectable('views', discriminator, @@ -1183,7 +1201,8 @@ class ViewsConfiguratorMixin(object): renderer = renderers.RendererHelper( name=None, package=self.package, - registry=self.registry) + registry=self.registry + ) if permission is None: # intent: will be None if no default permission is registered @@ -1314,6 +1333,22 @@ class ViewsConfiguratorMixin(object): multiview, (IExceptionViewClassifier, request_iface, context), IMultiView, name=name) + renderer_type = getattr(renderer, 'type', None) # gard against None + intrspc = self.introspector + if ( + renderer_type is not None and + tmpl_intr is not None and + intrspc is not None and + intrspc.get('renderer factories', renderer_type) is not None + ): + # allow failure of registered template factories to be deferred + # until view execution, like other bad renderer factories; if + # we tried to relate this to an existing renderer factory + # without checking if it the factory actually existed, we'd end + # up with a KeyError at startup time, which is inconsistent + # with how other bad renderer registrations behave (they throw + # a ValueError at view execution time) + tmpl_intr.relate('renderer factories', renderer.type) if mapper: mapper_intr = self.introspectable( @@ -1339,7 +1374,6 @@ class ViewsConfiguratorMixin(object): tmpl_intr['name'] = renderer.name tmpl_intr['type'] = renderer.type tmpl_intr['renderer'] = renderer - tmpl_intr.relate('renderer factories', renderer.type) introspectables.append(tmpl_intr) if permission is not None: # if a permission exists, register a permission introspectable @@ -1369,7 +1403,8 @@ class ViewsConfiguratorMixin(object): Python identifier (it will be used as a keyword argument to ``add_view`` by others). - ``factory`` should be a :term:`predicate factory`. + ``factory`` should be a :term:`predicate factory` or :term:`dotted + Python name` which refers to a predicate factory. See :ref:`view_and_route_predicates` for more information. """ @@ -1907,27 +1942,16 @@ class StaticURLInfo(object): # Mutate extra to allow factory, etc to be passed through here. # Treat permission specially because we'd like to default to - # permissiveness (see docs of config.add_static_view). We need - # to deal with both ``view_permission`` and ``permission`` - # because ``permission`` is used in the docs for add_static_view, - # but ``add_route`` prefers ``view_permission`` - permission = extra.pop('view_permission', None) - if permission is None: - permission = extra.pop('permission', None) + # permissiveness (see docs of config.add_static_view). + permission = extra.pop('permission', None) if permission is None: permission = NO_PERMISSION_REQUIRED - context = extra.pop('view_context', None) - if context is None: - context = extra.pop('view_for', None) + context = extra.pop('context', None) if context is None: context = extra.pop('for_', None) - renderer = extra.pop('view_renderer', None) - if renderer is None: - renderer = extra.pop('renderer', None) - - attr = extra.pop('view_attr', None) + renderer = extra.pop('renderer', None) # register a route using the computed view, permission, and # pattern, plus any extras passed to us via add_static_view @@ -1943,7 +1967,6 @@ class StaticURLInfo(object): permission=permission, context=context, renderer=renderer, - attr=attr ) def register(): diff --git a/pyramid/decorator.py b/pyramid/decorator.py index e5f2996dc..0d17bc398 100644 --- a/pyramid/decorator.py +++ b/pyramid/decorator.py @@ -10,7 +10,7 @@ class reify(object): class Foo(object): @reify def jammy(self): - print 'jammy called' + print('jammy called') return 1 And usage of Foo: @@ -18,7 +18,7 @@ class reify(object): >>> f = Foo() >>> v = f.jammy 'jammy called' - >>> print v + >>> print(v) 1 >>> f.jammy 1 diff --git a/pyramid/encode.py b/pyramid/encode.py index 65bc95032..9e190bc21 100644 --- a/pyramid/encode.py +++ b/pyramid/encode.py @@ -32,6 +32,10 @@ def urlencode(query, doseq=True): See the Python stdlib documentation for ``urllib.urlencode`` for more information. + + .. versionchanged:: 1.5 + In a key/value pair, if the value is ``None`` then it will be + dropped from the resulting output. """ try: # presumed to be a dictionary @@ -50,6 +54,8 @@ def urlencode(query, doseq=True): x = _enc(x) result += '%s%s=%s' % (prefix, k, x) prefix = '&' + elif v is None: + result += '%s%s=' % (prefix, k) else: v = _enc(v) result += '%s%s=%s' % (prefix, k, v) diff --git a/pyramid/events.py b/pyramid/events.py index 836466ba2..5179ab08a 100644 --- a/pyramid/events.py +++ b/pyramid/events.py @@ -40,7 +40,7 @@ class subscriber(object): @subscriber(NewRequest, NewResponse) def mysubscriber(event): - print event + print(event) When the ``subscriber`` decorator is used without passing an arguments, the function it decorates is called for every event sent: @@ -51,7 +51,7 @@ class subscriber(object): @subscriber() def mysubscriber(event): - print event + print(event) This method will have no effect until a :term:`scan` is performed against the package or module which contains it, ala: @@ -192,10 +192,7 @@ class BeforeRender(dict): event['mykey'] = 'foo' An object of this type is sent as an event just before a :term:`renderer` - is invoked (but *after* the -- deprecated -- application-level renderer - globals factory added via - :class:`pyramid.config.Configurator.set_renderer_globals_factory`, if - any, has injected its own keys into the renderer globals dictionary). + is invoked. If a subscriber adds a key via ``__setitem__`` that already exists in the renderer globals dictionary, it will overwrite the older value there. @@ -231,9 +228,9 @@ class BeforeRender(dict): # {'mykey': 'somevalue'} is returned from the view print(event.rendering_val['mykey']) - In other words, :attr:`rendering_val` is the (non-system) value returned by a - view or passed to ``render*`` as ``value``. This feature is new in Pyramid - 1.2. + In other words, :attr:`rendering_val` is the (non-system) value returned + by a view or passed to ``render*`` as ``value``. This feature is new in + Pyramid 1.2. For a description of the values present in the renderer globals dictionary, see :ref:`renderer_system_values`. diff --git a/pyramid/fixers/fix_bfg_imports.py b/pyramid/fixers/fix_bfg_imports.py deleted file mode 100644 index 0046aad30..000000000 --- a/pyramid/fixers/fix_bfg_imports.py +++ /dev/null @@ -1,220 +0,0 @@ -import os -import re -import sys - -from lib2to3.refactor import get_fixers_from_package -from lib2to3.refactor import RefactoringTool -from lib2to3.fixer_util import Name -from lib2to3.fixer_util import attr_chain -from lib2to3 import fixer_base - -MAPPING = {'repoze.bfg':'pyramid'} - -MODULE_NAMES = ( - 'compat', - 'configuration', - 'authentication', - 'authorization', - 'chameleon_text', - 'chameleon_zpt', - 'decorator', - 'encode', - 'events', - 'exceptions', - 'i18n', - 'includes', - 'interfaces', - 'location', - 'log', - 'paster', - 'path', - 'registry', - 'renderers', - 'request', - 'resource', - 'router', - 'scripting', - 'security', - 'settings', - 'static', - 'testing', - 'tests', - 'tests.test_configuration', - 'tests.ccbugapp', - 'tests.exceptionviewapp', - 'tests.exceptionviewapp.models', - 'tests.fixtureapp', - 'tests.fixtureapp.models', - 'tests.grokkedapp', - 'tests.hybridapp', - 'tests.localeapp', - 'tests.restbugapp', - 'tests.routesapp', - 'threadlocal', - 'traversal', - 'urldispatch', - 'url', - 'view', - 'wsgi', - 'zcml', - ) - -for name in MODULE_NAMES: - frm = 'repoze.bfg.' + name - to = 'pyramid.' + name - MAPPING[frm] = to - -def alternates(members): - return "(" + "|".join(map(str, members)) + ")" - -def build_pattern(mapping=MAPPING): - mod_list = [] - - for key in mapping: - splitted = key.split('.') - joined = " '.' ".join(["'%s'" %s for s in splitted]) - mod_list.append(joined) - - mod_list = ' | '.join( - ['module_name=dotted_name< %s >' %s for s in mod_list]) - - yield """name_import=import_name< 'import' ((%s) | - multiple_imports=dotted_as_names< any* (%s) any* >) > - """ % (mod_list, mod_list) - yield """import_from< 'from' (%s) 'import' ['('] - ( any | import_as_name< any 'as' any > | - import_as_names< any* >) [')'] > - """ % mod_list - yield """import_name< 'import' (dotted_as_name< (%s) 'as' any > | - multiple_imports=dotted_as_names< - any* dotted_as_name< (%s) 'as' any > any* >) > - """ % (mod_list, mod_list) - - # Find usages of module members in code e.g. ``repoze.bfg`` or - # ``repoze.bfg.configuration`` - # 'repoze' trailer< '.' 'bfg' > trailer< '.' 'configuration' > - bare_names = [] - for key in mapping: - splitted = key.split('.') - tmp = ["'%s'" % splitted[0]] - for thing in splitted[1:]: - tmp.append(" trailer< '.' '%s' > " % thing) - bare_name = ''.join(tmp) - bare_names.append(bare_name) - - names = alternates(bare_names) - yield "power< bare_with_attr=%s >" % names - -class FixBfgImports(fixer_base.BaseFix): - - mapping = MAPPING - run_order = 8 - - def build_pattern(self): - pattern = "|".join(build_pattern(self.mapping)) - return pattern - - def compile_pattern(self): - # We override this, so MAPPING can be pragmatically altered and the - # changes will be reflected in PATTERN. - self.PATTERN = self.build_pattern() - super(FixBfgImports, self).compile_pattern() - - # Don't match the node if it's within another match. - def match(self, node): - match = super(FixBfgImports, self).match - results = match(node) - if results: - # Module usage could be in the trailer of an attribute lookup, so we - # might have nested matches when "bare_with_attr" is present. - if "bare_with_attr" not in results and \ - any(match(obj) for obj in attr_chain(node, "parent")): - return False - return results - return False - - def start_tree(self, tree, filename): - super(FixBfgImports, self).start_tree(tree, filename) - self.replace = {} - - def transform(self, node, results): - # Mostly copied from fix_imports.py - import_mod = results.get("module_name") - if import_mod: - try: - mod_name = import_mod.value - except AttributeError: - # XXX: A hack to remove whitespace prefixes and suffixes - mod_name = str(import_mod).strip() - new_name = self.mapping[mod_name] - import_mod.replace(Name(new_name, prefix=import_mod.prefix)) - if "name_import" in results: - # If it's not a "from x import x, y" or "import x as y" import, - # marked its usage to be replaced. - self.replace[mod_name] = new_name - if "multiple_imports" in results: - # This is a nasty hack to fix multiple imports on a line (e.g., - # "import StringIO, urlparse"). The problem is that I can't - # figure out an easy way to make a pattern recognize the keys of - # MAPPING randomly sprinkled in an import statement. - results = self.match(node) - if results: - self.transform(node, results) - else: - # Replace usage of the module. - bare_name_text = ''.join(map(str,results['bare_with_attr'])).strip() - new_name = self.replace.get(bare_name_text) - bare_name = results["bare_with_attr"][0] - - if new_name: - node.replace(Name(new_name, prefix=bare_name.prefix)) - -MODULE_ALTERNATIVES = [] -for name in MODULE_NAMES: - MODULE_ALTERNATIVES.append(r'\.' + re.escape(name)+r'[\w\.]*?') - -MODULE_ALTERNATIVES = '|'.join(MODULE_ALTERNATIVES) - -BFG_NS_RE = r'xmlns\s*?=\s*?[\'\"]http://namespaces\.repoze\.org/bfg[\'\"]' -BFG_IN_ATTR = r'(repoze\.bfg)(%s)' % MODULE_ALTERNATIVES -BFG_INCLUDE_IN_ATTR = r'repoze\.bfg\.includes' -ATTR = re.compile(BFG_IN_ATTR, re.MULTILINE) -INCLUDE_ATTR = re.compile(BFG_INCLUDE_IN_ATTR, re.MULTILINE) -NS = re.compile(BFG_NS_RE, re.MULTILINE) - -def replace(match): - return 'pyramid%s' % match.group(2) - -def fix_zcml(path): - for root, dirs, files in os.walk(path): - for file in files: - if file.endswith('.zcml'): - absfile = os.path.join(root, file) - f = open(absfile, 'rb') - text = f.read() - f.close() - newt = NS.sub('xmlns="http://pylonshq.com/pyramid"', text) - newt = INCLUDE_ATTR.sub('pyramid_zcml', newt) - newt = ATTR.sub(replace, newt) - if text != newt: - newf = open(absfile, 'wb') - newf.write(newt) - newf.flush() - newf.close() - - for dir in dirs: - if dir.startswith('.'): - dirs.remove(dir) - -def main(argv=None): - if argv is None: - argv = sys.argv - path = argv[1] - fixer_names = get_fixers_from_package('pyramid.fixers') - tool = RefactoringTool(fixer_names) - tool.refactor([path], write=True) - fix_zcml(path) - -if __name__ == '__main__': - main() - diff --git a/pyramid/httpexceptions.py b/pyramid/httpexceptions.py index c21a717f8..fff17b2df 100644 --- a/pyramid/httpexceptions.py +++ b/pyramid/httpexceptions.py @@ -13,7 +13,7 @@ and 500s are server errors. Exception HTTPException - HTTPOk + HTTPSuccessful * 200 - HTTPOk * 201 - HTTPCreated * 202 - HTTPAccepted @@ -28,7 +28,6 @@ Exception * 303 - HTTPSeeOther * 304 - HTTPNotModified * 305 - HTTPUseProxy - * 306 - Unused (not implemented, obviously) * 307 - HTTPTemporaryRedirect HTTPError HTTPClientError @@ -150,11 +149,8 @@ def _no_escape(value): value = text_type(value) return value -class HTTPException(Exception): # bw compat - """ Base class for all :term:`exception response` objects.""" - @implementer(IExceptionResponse) -class WSGIHTTPException(Response, HTTPException): +class HTTPException(Response, Exception): ## You should set in subclasses: # code = 200 @@ -254,7 +250,7 @@ ${body}''') 'html_comment':html_comment, } body_tmpl = self.body_template_obj - if WSGIHTTPException.body_template_obj is not body_tmpl: + if HTTPException.body_template_obj is not body_tmpl: # Custom template; add headers to args for k, v in environ.items(): if (not k.startswith('wsgi.')) and ('.' in k): @@ -290,7 +286,9 @@ ${body}''') self.prepare(environ) return Response.__call__(self, environ, start_response) -class HTTPError(WSGIHTTPException): +WSGIHTTPException = HTTPException # b/c post 1.5 + +class HTTPError(HTTPException): """ base class for exceptions with status codes in the 400s and 500s @@ -298,7 +296,7 @@ class HTTPError(WSGIHTTPException): and that any work in progress should not be committed. """ -class HTTPRedirection(WSGIHTTPException): +class HTTPRedirection(HTTPException): """ base class for exceptions with status codes in the 300s (redirections) @@ -308,23 +306,30 @@ class HTTPRedirection(WSGIHTTPException): condition. """ -class HTTPOk(WSGIHTTPException): +class HTTPSuccessful(HTTPException): """ Base class for exceptions with status codes in the 200s (successful responses) - - code: 200, title: OK """ - code = 200 - title = 'OK' ############################################################ ## 2xx success ############################################################ -class HTTPCreated(HTTPOk): +class HTTPOk(HTTPSuccessful): + """ + subclass of :class:`~HTTPSuccessful` + + Indicates that the request has succeeded. + + code: 200, title: OK + """ + code = 200 + title = 'OK' + +class HTTPCreated(HTTPSuccessful): """ - subclass of :class:`~HTTPOk` + subclass of :class:`~HTTPSuccessful` This indicates that request has been fulfilled and resulted in a new resource being created. @@ -334,9 +339,9 @@ class HTTPCreated(HTTPOk): code = 201 title = 'Created' -class HTTPAccepted(HTTPOk): +class HTTPAccepted(HTTPSuccessful): """ - subclass of :class:`~HTTPOk` + subclass of :class:`~HTTPSuccessful` This indicates that the request has been accepted for processing, but the processing has not been completed. @@ -347,9 +352,9 @@ class HTTPAccepted(HTTPOk): title = 'Accepted' explanation = 'The request is accepted for processing.' -class HTTPNonAuthoritativeInformation(HTTPOk): +class HTTPNonAuthoritativeInformation(HTTPSuccessful): """ - subclass of :class:`~HTTPOk` + subclass of :class:`~HTTPSuccessful` This indicates that the returned metainformation in the entity-header is not the definitive set as available from the origin server, but is @@ -360,9 +365,9 @@ class HTTPNonAuthoritativeInformation(HTTPOk): code = 203 title = 'Non-Authoritative Information' -class HTTPNoContent(HTTPOk): +class HTTPNoContent(HTTPSuccessful): """ - subclass of :class:`~HTTPOk` + subclass of :class:`~HTTPSuccessful` This indicates that the server has fulfilled the request but does not need to return an entity-body, and might want to return updated @@ -374,9 +379,9 @@ class HTTPNoContent(HTTPOk): title = 'No Content' empty_body = True -class HTTPResetContent(HTTPOk): +class HTTPResetContent(HTTPSuccessful): """ - subclass of :class:`~HTTPOk` + subclass of :class:`~HTTPSuccessful` This indicates that the server has fulfilled the request and the user agent SHOULD reset the document view which caused the @@ -388,9 +393,9 @@ class HTTPResetContent(HTTPOk): title = 'Reset Content' empty_body = True -class HTTPPartialContent(HTTPOk): +class HTTPPartialContent(HTTPSuccessful): """ - subclass of :class:`~HTTPOk` + subclass of :class:`~HTTPSuccessful` This indicates that the server has fulfilled the partial GET request for the resource. diff --git a/pyramid/i18n.py b/pyramid/i18n.py index b4bc0eaa7..cdedbc877 100644 --- a/pyramid/i18n.py +++ b/pyramid/i18n.py @@ -12,6 +12,7 @@ TranslationString = TranslationString # PyFlakes TranslationStringFactory = TranslationStringFactory # PyFlakes from pyramid.compat import PY3 +from pyramid.decorator import reify from pyramid.interfaces import ( ILocalizer, @@ -127,7 +128,7 @@ def default_locale_negotiator(request): def negotiate_locale_name(request): """ Negotiate and return the :term:`locale name` associated with - the current request (never cached).""" + the current request.""" try: registry = request.registry except AttributeError: @@ -144,12 +145,9 @@ def negotiate_locale_name(request): def get_locale_name(request): """ Return the :term:`locale name` associated with the current - request (possibly cached).""" - locale_name = getattr(request, 'locale_name', None) - if locale_name is None: - locale_name = negotiate_locale_name(request) - request.locale_name = locale_name - return locale_name + request. Deprecated in favor of using request.locale_name directly as of + Pyramid 1.5.""" + return request.locale_name def make_localizer(current_locale_name, translation_directories): """ Create a :class:`pyramid.i18n.Localizer` object @@ -196,30 +194,10 @@ def make_localizer(current_locale_name, translation_directories): def get_localizer(request): """ Retrieve a :class:`pyramid.i18n.Localizer` object - corresponding to the current request's locale name. """ - localizer = getattr(request, 'localizer', None) - - if localizer is None: - # no locale object cached on request - try: - registry = request.registry - except AttributeError: - registry = get_current_registry() - - current_locale_name = get_locale_name(request) - localizer = registry.queryUtility(ILocalizer, name=current_locale_name) - - if localizer is None: - # no localizer utility registered yet - tdirs = registry.queryUtility(ITranslationDirectories, default=[]) - localizer = make_localizer(current_locale_name, tdirs) - - registry.registerUtility(localizer, ILocalizer, - name=current_locale_name) - request.localizer = localizer + corresponding to the current request's locale name. Deprecated in favor + of using the ``request.localizer`` attribute directly as of Pyramid 1.5""" + return request.localizer - return localizer - class Translations(gettext.GNUTranslations, object): """An extended translation catalog class (ripped off from Babel) """ @@ -362,3 +340,28 @@ class Translations(gettext.GNUTranslations, object): return self._domains.get(domain, self).ungettext( singular, plural, num) +class LocalizerRequestMixin(object): + @reify + def localizer(self): + """ Convenience property to return a localizer """ + registry = self.registry + + current_locale_name = self.locale_name + localizer = registry.queryUtility(ILocalizer, name=current_locale_name) + + if localizer is None: + # no localizer utility registered yet + tdirs = registry.queryUtility(ITranslationDirectories, default=[]) + localizer = make_localizer(current_locale_name, tdirs) + + registry.registerUtility(localizer, ILocalizer, + name=current_locale_name) + + return localizer + + @reify + def locale_name(self): + locale_name = negotiate_locale_name(self) + return locale_name + + diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index 4fb4d615c..85b2227b4 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -616,15 +616,6 @@ class IRendererFactory(Interface): """ Return an object that implements ``IRenderer``. ``info`` is an object that implement ``IRendererInfo``. """ -class IRendererGlobalsFactory(Interface): - def __call__(system_values): - """ Return a dictionary of global renderer values (aka - top-level template names). The ``system_values`` value passed - in will be a dictionary that includes at least a ``request`` - key, indicating the current request, and the value - ``renderer_name``, which will be the name of the renderer in - use.""" - class IViewPermission(Interface): def __call__(context, request): """ Return True if the permission allows, return False if it denies. """ @@ -692,6 +683,7 @@ class IRoute(Interface): pregenerator = Attribute('This attribute should either be ``None`` or ' 'a callable object implementing the ' '``IRoutePregenerator`` interface') + def match(path): """ If the ``path`` passed to this function can be matched by the @@ -738,8 +730,18 @@ class IRoutesMapper(Interface): matched. Static routes will not be considered for matching. """ class IResourceURL(Interface): - virtual_path = Attribute('The virtual url path of the resource.') - physical_path = Attribute('The physical url path of the resource.') + virtual_path = Attribute( + 'The virtual url path of the resource as a string.' + ) + physical_path = Attribute( + 'The physical url path of the resource as a string.' + ) + virtual_path_tuple = Attribute( + 'The virtual url path of the resource as a tuple. (New in 1.5)' + ) + physical_path_tuple = Attribute( + 'The physical url path of the resource as a tuple. (New in 1.5)' + ) class IContextURL(IResourceURL): """ An adapter which deals with URLs related to a context. @@ -760,15 +762,15 @@ class IContextURL(IResourceURL): # # class Fudge(object): # def __init__(self, one, two): - # print one, two + # print(one, two) # class Another(object): # def __init__(self, one, two): - # print one, two + # print(one, two) # ob = object() # r.registerAdapter(Fudge, (Interface, Interface), IContextURL) - # print r.queryMultiAdapter((ob, ob), IResourceURL) + # print(r.queryMultiAdapter((ob, ob), IResourceURL)) # r.registerAdapter(Another, (Interface, Interface), IResourceURL) - # print r.queryMultiAdapter((ob, ob), IResourceURL) + # print(r.queryMultiAdapter((ob, ob), IResourceURL)) # # prints # @@ -793,26 +795,55 @@ deprecated( 'See the "What\'s new In Pyramid 1.3" document for more details.' ) -class IPackageOverrides(Interface): +class IPEP302Loader(Interface): + """ See http://www.python.org/dev/peps/pep-0302/#id30. + """ + def get_data(path): + """ Retrieve data for and arbitrary "files" from storage backend. + + Raise IOError for not found. + + Data is returned as bytes. + """ + + def is_package(fullname): + """ Return True if the module specified by 'fullname' is a package. + """ + + def get_code(fullname): + """ Return the code object for the module identified by 'fullname'. + + Return 'None' if it's a built-in or extension module. + + If the loader doesn't have the code object but it does have the source + code, return the compiled source code. + + Raise ImportError if the module can't be found by the importer at all. + """ + + def get_source(fullname): + """ Return the source code for the module identified by 'fullname'. + + Return a string, using newline characters for line endings, or None + if the source is not available. + + Raise ImportError if the module can't be found by the importer at all. + """ + + def get_filename(fullname): + """ Return the value of '__file__' if the named module was loaded. + + If the module is not found, raise ImportError. + """ + + +class IPackageOverrides(IPEP302Loader): """ Utility for pkg_resources overrides """ # VH_ROOT_KEY is an interface; its imported from other packages (e.g. # traversalwrapper) VH_ROOT_KEY = 'HTTP_X_VHM_ROOT' -class IChameleonLookup(Interface): - translate = Attribute('IChameleonTranslate object') - debug = Attribute('The ``debug_templates`` setting for this application') - auto_reload = Attribute('The ``reload_templates`` setting for this app') - def __call__(self, info): - """ Return an ITemplateRenderer based on IRendererInfo ``info`` """ - -class IChameleonTranslate(Interface): - """ Internal interface representing a chameleon translate function """ - def __call__(msgid, domain=None, mapping=None, context=None, - target_language=None, default=None): - """ Translate a mess of arguments to a Unicode object """ - class ILocalizer(Interface): """ Localizer for a specific language """ @@ -873,7 +904,7 @@ class ISession(IDict): by ``queue``. An alternate flash message queue can used by passing an optional ``queue``, which must be a string. If ``allow_duplicate`` is false, if the ``msg`` already exists in the - queue, it will not be readded.""" + queue, it will not be re-added.""" def pop_flash(queue=''): """ Pop a queue from the flash storage. The queue is removed from diff --git a/pyramid/mako_templating.py b/pyramid/mako_templating.py deleted file mode 100644 index 061bcb717..000000000 --- a/pyramid/mako_templating.py +++ /dev/null @@ -1,219 +0,0 @@ -import os -import posixpath -import re -import sys -import threading - -from zope.interface import ( - implementer, - Interface, - ) - -from pyramid.asset import ( - resolve_asset_spec, - abspath_from_asset_spec, - ) - -from pyramid.compat import ( - is_nonstr_iter, - reraise, - ) - -from pyramid.interfaces import ITemplateRenderer -from pyramid.settings import asbool -from pyramid.util import DottedNameResolver - -from mako.lookup import TemplateLookup -from mako import exceptions - -class IMakoLookup(Interface): - pass - -class PkgResourceTemplateLookup(TemplateLookup): - """TemplateLookup subclass that handles asset specification URIs""" - def adjust_uri(self, uri, relativeto): - """Called from within a Mako template, avoids adjusting the - uri if it looks like an asset specification""" - # Don't adjust asset spec names - isabs = os.path.isabs(uri) - if (not isabs) and (':' in uri): - return uri - if not(isabs) and ('$' in uri): - return uri.replace('$', ':') - if relativeto is not None: - relativeto = relativeto.replace('$', ':') - if not(':' in uri) and (':' in relativeto): - if uri.startswith('/'): - return uri - pkg, relto = relativeto.split(':') - _uri = posixpath.join(posixpath.dirname(relto), uri) - return '{0}:{1}'.format(pkg, _uri) - if not(':' in uri) and not(':' in relativeto): - return posixpath.join(posixpath.dirname(relativeto), uri) - return TemplateLookup.adjust_uri(self, uri, relativeto) - - def get_template(self, uri): - """Fetch a template from the cache, or check the filesystem - for it - - In addition to the basic filesystem lookup, this subclass will - use pkg_resource to load a file using the asset - specification syntax. - - """ - isabs = os.path.isabs(uri) - if (not isabs) and (':' in uri): - # Windows can't cope with colons in filenames, so we replace the - # colon with a dollar sign in the filename mako uses to actually - # store the generated python code in the mako module_directory or - # in the temporary location of mako's modules - adjusted = uri.replace(':', '$') - try: - if self.filesystem_checks: - return self._check(adjusted, self._collection[adjusted]) - else: - return self._collection[adjusted] - except KeyError: - pname, path = resolve_asset_spec(uri) - srcfile = abspath_from_asset_spec(path, pname) - if os.path.isfile(srcfile): - return self._load(srcfile, adjusted) - raise exceptions.TopLevelLookupException( - "Can not locate template for uri %r" % uri) - return TemplateLookup.get_template(self, uri) - -registry_lock = threading.Lock() - -class MakoRendererFactoryHelper(object): - def __init__(self, settings_prefix=None): - self.settings_prefix = settings_prefix - - def __call__(self, info): - defname = None - asset, ext = info.name.rsplit('.', 1) - if '#' in asset: - asset, defname = asset.rsplit('#', 1) - - path = '%s.%s' % (asset, ext) - registry = info.registry - settings = info.settings - settings_prefix = self.settings_prefix - - if settings_prefix is None: - settings_prefix = info.type +'.' - - lookup = registry.queryUtility(IMakoLookup, name=settings_prefix) - - def sget(name, default=None): - return settings.get(settings_prefix + name, default) - - if lookup is None: - reload_templates = settings.get('pyramid.reload_templates', None) - if reload_templates is None: - reload_templates = settings.get('reload_templates', False) - reload_templates = asbool(reload_templates) - directories = sget('directories', []) - module_directory = sget('module_directory', None) - input_encoding = sget('input_encoding', 'utf-8') - error_handler = sget('error_handler', None) - default_filters = sget('default_filters', 'h') - imports = sget('imports', None) - strict_undefined = asbool(sget('strict_undefined', False)) - preprocessor = sget('preprocessor', None) - if not is_nonstr_iter(directories): - directories = list(filter(None, directories.splitlines())) - directories = [ abspath_from_asset_spec(d) for d in directories ] - if module_directory is not None: - module_directory = abspath_from_asset_spec(module_directory) - if error_handler is not None: - dotted = DottedNameResolver(info.package) - error_handler = dotted.maybe_resolve(error_handler) - if default_filters is not None: - if not is_nonstr_iter(default_filters): - default_filters = list(filter( - None, default_filters.splitlines())) - if imports is not None: - if not is_nonstr_iter(imports): - imports = list(filter(None, imports.splitlines())) - if preprocessor is not None: - dotted = DottedNameResolver(info.package) - preprocessor = dotted.maybe_resolve(preprocessor) - - - lookup = PkgResourceTemplateLookup( - directories=directories, - module_directory=module_directory, - input_encoding=input_encoding, - error_handler=error_handler, - default_filters=default_filters, - imports=imports, - filesystem_checks=reload_templates, - strict_undefined=strict_undefined, - preprocessor=preprocessor - ) - - with registry_lock: - registry.registerUtility(lookup, IMakoLookup, - name=settings_prefix) - - return MakoLookupTemplateRenderer(path, defname, lookup) - -renderer_factory = MakoRendererFactoryHelper('mako.') - -class MakoRenderingException(Exception): - def __init__(self, text): - self.text = text - - def __repr__(self): - return self.text - - __str__ = __repr__ - -@implementer(ITemplateRenderer) -class MakoLookupTemplateRenderer(object): - """ Render a :term:`Mako` template using the template - implied by the ``path`` argument.The ``path`` argument may be a - package-relative path, an absolute path, or a :term:`asset - specification`. If a defname is defined, in the form of - package:path/to/template#defname.mako, a function named ``defname`` - inside the template will then be rendered. - """ - def __init__(self, path, defname, lookup): - self.path = path - self.defname = defname - self.lookup = lookup - - def implementation(self): - return self.lookup.get_template(self.path) - - def __call__(self, value, system): - context = system.pop('context', None) - if context is not None: - system['_context'] = context - if self.defname is None: - if isinstance(value, tuple): - self.defname, value = value - else: - if isinstance(value, tuple): - _, value = value - try: - system.update(value) - except (TypeError, ValueError): - raise ValueError('renderer was passed non-dictionary as value') - template = self.implementation() - if self.defname is not None: - template = template.get_def(self.defname) - try: - result = template.render_unicode(**system) - except: - try: - exc_info = sys.exc_info() - errtext = exceptions.text_error_template().render( - error=exc_info[1], - traceback=exc_info[2] - ) - reraise(MakoRenderingException(errtext), None, exc_info[2]) - finally: - del exc_info - - return result diff --git a/pyramid/path.py b/pyramid/path.py index 57eccdb19..470e766f8 100644 --- a/pyramid/path.py +++ b/pyramid/path.py @@ -33,8 +33,12 @@ def package_name(pkg_or_module): name of the package itself.""" if pkg_or_module is None or pkg_or_module.__name__ == '__main__': return '__main__' - pkg_filename = pkg_or_module.__file__ pkg_name = pkg_or_module.__name__ + pkg_filename = getattr(pkg_or_module, '__file__', None) + if pkg_filename is None: + # Namespace packages do not have __init__.py* files, + # and so have no __file__ attribute + return pkg_name splitted = os.path.split(pkg_filename) if splitted[-1] in init_names: # it's a package @@ -181,7 +185,7 @@ class AssetResolver(Resolver): a = AssetResolver('myproject') resolver = a.resolve('templates/foo.pt') - print resolver.abspath() + print(resolver.abspath()) # -> /path/to/myproject/templates/foo.pt If the AssetResolver is constructed without a ``package`` argument of @@ -324,7 +328,7 @@ class DottedNameResolver(Resolver): def _pkg_resources_style(self, value, package): """ package.module:attr style """ - if value.startswith('.') or value.startswith(':'): + if value.startswith(('.', ':')): if not package: raise ValueError( 'relative name %r irresolveable without package' % (value,) diff --git a/pyramid/renderers.py b/pyramid/renderers.py index 64951a6ba..e90d07b38 100644 --- a/pyramid/renderers.py +++ b/pyramid/renderers.py @@ -1,8 +1,5 @@ import json import os -import re -import pkg_resources -import threading from zope.interface import ( implementer, @@ -11,18 +8,12 @@ from zope.interface import ( from zope.interface.registry import Components from pyramid.interfaces import ( - IChameleonLookup, - IChameleonTranslate, IJSONAdapter, - IRendererGlobalsFactory, IRendererFactory, IResponseFactory, - ITemplateRenderer, IRendererInfo, ) -from pyramid.asset import asset_spec_from_abspath - from pyramid.compat import ( string_types, text_type, @@ -32,10 +23,7 @@ from pyramid.decorator import reify from pyramid.events import BeforeRender -from pyramid.path import ( - caller_package, - package_path, - ) +from pyramid.path import caller_package from pyramid.response import Response from pyramid.threadlocal import get_current_registry @@ -85,7 +73,23 @@ def render(renderer_name, value, request=None, package=None): package = caller_package() helper = RendererHelper(name=renderer_name, package=package, registry=registry) - return helper.render(value, None, request=request) + + saved_response = None + # save the current response, preventing the renderer from affecting it + attrs = request.__dict__ if request is not None else {} + if 'response' in attrs: + saved_response = attrs['response'] + del attrs['response'] + + result = helper.render(value, None, request=request) + + # restore the original response, overwriting any changes + if saved_response is not None: + attrs['response'] = saved_response + elif 'response' in attrs: + del attrs['response'] + + return result def render_to_response(renderer_name, value, request=None, package=None): """ Using the renderer ``renderer_name`` (a template @@ -114,7 +118,7 @@ def render_to_response(renderer_name, value, request=None, package=None): top-level system names, such as ``request``, ``context``, ``renderer_name``, and ``view``. See :ref:`renderer_system_values` for the full list. If :term:`renderer globals` have been specified, these - will also be used to agument the value. + will also be used to argument the value. Supply a ``request`` parameter in order to provide the renderer with the most correct 'system' values (``request`` and ``context`` @@ -197,11 +201,17 @@ class JSON(object): adapters with the renderer. See :ref:`json_serializing_custom_objects` for more information. - The default serializer uses ``json.JSONEncoder``. A different - serializer can be specified via the ``serializer`` argument. - Custom serializers should accept the object, a callback - ``default``, and any extra ``kw`` keyword argments passed during - renderer construction. + .. note:: + + The default serializer uses ``json.JSONEncoder``. A different + serializer can be specified via the ``serializer`` argument. Custom + serializers should accept the object, a callback ``default``, and any + extra ``kw`` keyword arguments passed during renderer construction. + This feature isn't widely used but it can be used to replace the + stock JSON serializer with, say, simplejson. If all you want to + do, however, is serialize custom objects, you should use the method + explained in :ref:`json_serializing_custom_objects` instead + of replacing the serializer. .. versionadded:: 1.4 Prior to this version, there was no public API for supplying options @@ -360,128 +370,6 @@ class JSONP(JSON): return body return _render -# utility functions, not API - -@implementer(IChameleonLookup) -class ChameleonRendererLookup(object): - spec_re = re.compile( - r'(?P<asset>[\w_.:/-]+)' - r'(?:\#(?P<defname>[\w_]+))?' - r'(\.(?P<ext>.*))' - ) - - def __init__(self, impl, registry): - self.impl = impl - self.registry = registry - self.lock = threading.Lock() - - def get_spec(self, name, package): - if not package: - # if there's no package, we can't do any conversion - return name - - spec = name - isabspath = os.path.isabs(name) - colon_in_name = ':' in name - isabsspec = colon_in_name and (not isabspath) - isrelspec = (not isabsspec) and (not isabspath) - - # if it's already an absolute spec, we don't need to do anything, - # but if it's a relative spec or an absolute path, we need to try - # to convert it to an absolute spec - - if isrelspec: - # convert relative asset spec to absolute asset spec - pp = package_path(package) - spec = os.path.join(pp, spec) - spec = asset_spec_from_abspath(spec, package) - - elif isabspath: - # convert absolute path to absolute asset spec - spec = asset_spec_from_abspath(spec, package) - - return spec - - @property # wait until completely necessary to look up translator - def translate(self): - return self.registry.queryUtility(IChameleonTranslate) - - @property # wait until completely necessary to look up debug_templates - def debug(self): - settings = self.registry.settings - if settings is None: - return False - return settings.get('debug_templates', False) - - @property # wait until completely necessary to look up reload_templates - def auto_reload(self): - settings = self.registry.settings - if settings is None: - return False - return settings.get('reload_templates', False) - - def _crack_spec(self, spec): - asset, macro, ext = self.spec_re.match(spec).group( - 'asset', 'defname', 'ext' - ) - return asset, macro, ext - - def __call__(self, info): - spec = self.get_spec(info.name, info.package) - registry = info.registry - - if os.path.isabs(spec): - # 'spec' is an absolute filename - if not os.path.exists(spec): - raise ValueError('Missing template file: %s' % spec) - renderer = registry.queryUtility(ITemplateRenderer, name=spec) - if renderer is None: - renderer = self.impl(spec, self, macro=None) - # cache the template - with self.lock: - registry.registerUtility(renderer, - ITemplateRenderer, name=spec) - else: - # spec is a package:relpath asset spec - renderer = registry.queryUtility(ITemplateRenderer, name=spec) - if renderer is None: - asset, macro, ext = self._crack_spec(spec) - spec_without_macro = '%s.%s' % (asset, ext) - try: - package_name, filename = spec_without_macro.split(':', 1) - except ValueError: # pragma: no cover - # somehow we were passed a relative pathname; this - # should die - package_name = caller_package(4).__name__ - filename = spec_without_macro - abspath = pkg_resources.resource_filename(package_name, - filename) - if not pkg_resources.resource_exists(package_name, filename): - raise ValueError( - 'Missing template asset: %s (%s)' % ( - spec_without_macro, abspath) - ) - renderer = self.impl(abspath, self, macro=macro) - settings = info.settings - if not settings.get('reload_assets'): - # cache the template - with self.lock: - registry.registerUtility(renderer, ITemplateRenderer, - name=spec) - - return renderer - -registry_lock = threading.Lock() - -def template_renderer_factory(info, impl, lock=registry_lock): - registry = info.registry - lookup = registry.queryUtility(IChameleonLookup, name=info.type) - if lookup is None: - lookup = ChameleonRendererLookup(impl, registry) - with lock: - registry.registerUtility(lookup, IChameleonLookup, name=info.type) - return lookup(info) - @implementer(IRendererInfo) class RendererHelper(object): def __init__(self, name=None, package=None, registry=None): @@ -542,13 +430,6 @@ class RendererHelper(object): system_values = BeforeRender(system_values, value) registry = self.registry - globals_factory = registry.queryUtility(IRendererGlobalsFactory) - - if globals_factory is not None: - renderer_globals = globals_factory(system_values) - if renderer_globals: - system_values.update(renderer_globals) - registry.notify(system_values) result = renderer(value, system_values) @@ -576,26 +457,6 @@ class RendererHelper(object): else: response.body = result - if request is not None: - # deprecated mechanism to set up request.response_* attrs, see - # pyramid.request.Request - attrs = request.__dict__ - content_type = attrs.get('_response_content_type', None) - if content_type is not None: - response.content_type = content_type - headerlist = attrs.get('_response_headerlist', None) - if headerlist is not None: - for k, v in headerlist: - response.headers.add(k, v) - status = attrs.get('_response_status', None) - if status is not None: - response.status = status - charset = attrs.get('_response_charset', None) - if charset is not None: - response.charset = charset - cache_for = attrs.get('_response_cache_for', None) - if cache_for is not None: - response.cache_expires = cache_for return response def clone(self, name=None, package=None, registry=None): diff --git a/pyramid/request.py b/pyramid/request.py index f9aa253ac..2cf0613f7 100644 --- a/pyramid/request.py +++ b/pyramid/request.py @@ -1,7 +1,5 @@ import json -from zope.deprecation import deprecate -from zope.deprecation.deprecation import deprecated from zope.interface import implementer from zope.interface.interface import InterfaceClass @@ -15,15 +13,13 @@ from pyramid.interfaces import ( ) from pyramid.compat import ( - iterkeys_, - itervalues_, - iteritems_, text_, bytes_, native_, ) from pyramid.decorator import reify +from pyramid.i18n import LocalizerRequestMixin from pyramid.response import Response from pyramid.url import URLMethodsMixin from pyramid.util import InstancePropertyMixin @@ -31,167 +27,6 @@ from pyramid.util import InstancePropertyMixin class TemplateContext(object): pass -class DeprecatedRequestMethodsMixin(object): - - # b/c dict interface for "root factory" code that expects a bare - # environ. Explicitly omitted dict methods: clear (unnecessary), - # copy (implemented by WebOb), fromkeys (unnecessary); deprecated - # as of Pyramid 1.1. - - dictlike = ('Use of the request as a dict-like object is deprecated as ' - 'of Pyramid 1.1. Use dict-like methods of "request.environ" ' - 'instead.') - - @deprecate(dictlike) - def __contains__(self, k): - return self.environ.__contains__(k) - - @deprecate(dictlike) - def __delitem__(self, k): - return self.environ.__delitem__(k) - - @deprecate(dictlike) - def __getitem__(self, k): - return self.environ.__getitem__(k) - - @deprecate(dictlike) - def __iter__(self): - return iter(self.environ) - - @deprecate(dictlike) - def __setitem__(self, k, v): - self.environ[k] = v - - @deprecate(dictlike) - def get(self, k, default=None): - return self.environ.get(k, default) - - @deprecate(dictlike) - def has_key(self, k): - return k in self.environ - - @deprecate(dictlike) - def items(self): - return self.environ.items() - - @deprecate(dictlike) - def iteritems(self): - return iteritems_(self.environ) - - @deprecate(dictlike) - def iterkeys(self): - return iterkeys_(self.environ) - - @deprecate(dictlike) - def itervalues(self): - return itervalues_(self.environ) - - @deprecate(dictlike) - def keys(self): - return self.environ.keys() - - @deprecate(dictlike) - def pop(self, k): - return self.environ.pop(k) - - @deprecate(dictlike) - def popitem(self): - return self.environ.popitem() - - @deprecate(dictlike) - def setdefault(self, v, default): - return self.environ.setdefault(v, default) - - @deprecate(dictlike) - def update(self, v, **kw): - return self.environ.update(v, **kw) - - @deprecate(dictlike) - def values(self): - return self.environ.values() - - # 1.0 deprecated bw compat code for using response_* values - - rr_dep = ('Accessing and setting "request.response_%s" is ' - 'deprecated as of Pyramid 1.1; access or set ' - '"request.response.%s" instead.') - - # response_content_type - def _response_content_type_get(self): - return self._response_content_type - def _response_content_type_set(self, value): - self._response_content_type = value - def _response_content_type_del(self): - del self._response_content_type - response_content_type = property(_response_content_type_get, - _response_content_type_set, - _response_content_type_del) - response_content_type = deprecated( - response_content_type, - rr_dep % ('content_type', 'content_type')) - - # response_headerlist - def _response_headerlist_get(self): - return self._response_headerlist - def _response_headerlist_set(self, value): - self._response_headerlist = value - def _response_headerlist_del(self): - del self._response_headerlist - response_headerlist = property(_response_headerlist_get, - _response_headerlist_set, - _response_headerlist_del) - - hl_dep = ('Accessing and setting "request.response_headerlist" is ' - 'deprecated as of Pyramid 1.1; access the headerlist via ' - '"request.response.headerlist" and extend headers via ' - '"request.response.headerlist.extend(alist)" instead of ' - '"request.response_headerlist = alist"') - - response_headerlist = deprecated(response_headerlist, hl_dep) - - # response_status - def _response_status_get(self): - return self._response_status - def _response_status_set(self, value): - self._response_status = value - def _response_status_del(self): - del self._response_status - response_status = property(_response_status_get, - _response_status_set, - _response_status_del) - - response_status = deprecated( - response_status, - rr_dep % ('status', 'status')) - - # response_charset - def _response_charset_get(self): - return self._response_charset - def _response_charset_set(self, value): - self._response_charset = value - def _response_charset_del(self): - del self._response_charset - response_charset = property(_response_charset_get, - _response_charset_set, - _response_charset_del) - response_charset = deprecated( - response_charset, - rr_dep % ('charset', 'charset')) - - # response_cache_for - def _response_cache_for_get(self): - return self._response_cache_for - def _response_cache_for_set(self, value): - self._response_cache_for = value - def _response_cache_for_del(self): - del self._response_cache_for - response_cache_for = property(_response_cache_for_get, - _response_cache_for_set, - _response_cache_for_del) - response_cache_for = deprecated( - response_cache_for, - rr_dep % ('cache_for', 'cache_expires')) - class CallbackMethodsMixin(object): response_callbacks = () finished_callbacks = () @@ -301,8 +136,8 @@ class CallbackMethodsMixin(object): callback(self) @implementer(IRequest) -class Request(BaseRequest, DeprecatedRequestMethodsMixin, URLMethodsMixin, - CallbackMethodsMixin, InstancePropertyMixin): +class Request(BaseRequest, URLMethodsMixin, CallbackMethodsMixin, + InstancePropertyMixin, LocalizerRequestMixin): """ A subclass of the :term:`WebOb` Request class. An instance of this class is created by the :term:`router` and is provided to a @@ -354,8 +189,7 @@ class Request(BaseRequest, DeprecatedRequestMethodsMixin, URLMethodsMixin, """This attribute is actually a "reified" property which returns an instance of the :class:`pyramid.response.Response`. class. The response object returned does not exist until this attribute is - accessed. Once it is accessed, subsequent accesses will return the - same Response object. + accessed. Subsequent accesses will return the same Response object. The ``request.response`` API is used by renderers. A render obtains the response object it will return from a view that uses that renderer @@ -384,6 +218,7 @@ class Request(BaseRequest, DeprecatedRequestMethodsMixin, URLMethodsMixin, def json_body(self): return json.loads(text_(self.body, self.charset)) + def route_request_iface(name, bases=()): # zope.interface treats the __name__ as the __doc__ and changes __name__ # to None for interfaces that contain spaces if you do not pass a diff --git a/pyramid/router.py b/pyramid/router.py index 63c12a1af..6239f3980 100644 --- a/pyramid/router.py +++ b/pyramid/router.py @@ -1,5 +1,4 @@ from zope.interface import ( - Interface, implementer, providedBy, ) @@ -165,10 +164,14 @@ class Router(object): except PredicateMismatch: # look for other views that meet the predicate # criteria - for iface in context_iface.flattened(): + for iface in context_iface.__sro__[1:]: + previous_view_callable = view_callable view_callable = adapters.lookup( (IViewClassifier, request.request_iface, iface), IView, name=view_name, default=None) + # intermediate bases may lookup same view_callable + if view_callable is previous_view_callable: + continue if view_callable is not None: try: response = view_callable(context, request) @@ -209,13 +212,13 @@ class Router(object): - causes a :class:`~pyramid.event.ContextFound` event to be sent when a context resource is found. - - causes a :class:`~pyramid.event.NewResponse` event to be sent when - the Pyramid application returns a response. - - Calls any :term:`response callback` functions defined within the request's lifetime if a response is obtained from the Pyramid application. + - causes a :class:`~pyramid.event.NewResponse` event to be sent if a + response is obtained. + - Calls any :term:`finished callback` functions defined within the request's lifetime. @@ -242,11 +245,12 @@ class Router(object): if extensions is not None: request._set_extensions(extensions) response = handle_request(request) - has_listeners and notify(NewResponse(request, response)) if request.response_callbacks: request._process_response_callbacks(response) + has_listeners and notify(NewResponse(request, response)) + return response finally: diff --git a/pyramid/scaffolds/__init__.py b/pyramid/scaffolds/__init__.py index d8fb9a62f..c993ce5f9 100644 --- a/pyramid/scaffolds/__init__.py +++ b/pyramid/scaffolds/__init__.py @@ -1,5 +1,6 @@ import binascii import os +from textwrap import dedent from pyramid.compat import native_ @@ -11,7 +12,7 @@ class PyramidTemplate(Template): templates. """ def pre(self, command, output_dir, vars): - """ Overrides :meth:`pyramid.scaffold.template.Template.pre`, adding + """ Overrides :meth:`pyramid.scaffolds.template.Template.pre`, adding several variables to the default variables list (including ``random_string``, and ``package_logger``). It also prevents common misnamings (such as naming a package "site" or naming a package @@ -30,10 +31,25 @@ class PyramidTemplate(Template): return Template.pre(self, command, output_dir, vars) def post(self, command, output_dir, vars): # pragma: no cover - """ Overrides :meth:`pyramid.scaffold.template.Template.post`, to + """ Overrides :meth:`pyramid.scaffolds.template.Template.post`, to print "Welcome to Pyramid. Sorry for the convenience." after a successful scaffolding rendering.""" - self.out('Welcome to Pyramid. Sorry for the convenience.') + + separator = "=" * 79 + msg = dedent( + """ + %(separator)s + Tutorials: http://docs.pylonsproject.org/projects/pyramid_tutorials + Documentation: http://docs.pylonsproject.org/projects/pyramid + + Twitter (tips & updates): http://twitter.com/pylons + Mailing List: http://groups.google.com/group/pylons-discuss + + Welcome to Pyramid. Sorry for the convenience. + %(separator)s + """ % {'separator': separator}) + + self.out(msg) return Template.post(self, command, output_dir, vars) def out(self, msg): # pragma: no cover (replaceable testing hook) diff --git a/pyramid/scaffolds/alchemy/+package+/__init__.py b/pyramid/scaffolds/alchemy/+package+/__init__.py index aac7c5e69..867049e4f 100644 --- a/pyramid/scaffolds/alchemy/+package+/__init__.py +++ b/pyramid/scaffolds/alchemy/+package+/__init__.py @@ -14,6 +14,7 @@ def main(global_config, **settings): 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() diff --git a/pyramid/scaffolds/alchemy/+package+/models.py b/pyramid/scaffolds/alchemy/+package+/models.py index aeeb9df64..a0d3e7b71 100644 --- a/pyramid/scaffolds/alchemy/+package+/models.py +++ b/pyramid/scaffolds/alchemy/+package+/models.py @@ -1,5 +1,6 @@ from sqlalchemy import ( Column, + Index, Integer, Text, ) @@ -20,9 +21,7 @@ Base = declarative_base() 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 +Index('my_index', MyModel.name, unique=True, mysql_length=255) diff --git a/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.pt_tmpl b/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.pt_tmpl index 99b3fe31c..24651643c 100644 --- a/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.pt_tmpl +++ b/pyramid/scaffolds/alchemy/+package+/templates/mytemplate.pt_tmpl @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl b/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl index a26cd9eeb..e6425eb91 100644 --- a/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl +++ b/pyramid/scaffolds/alchemy/+package+/tests.py_tmpl @@ -6,7 +6,7 @@ from pyramid import testing 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 @@ class TestMyView(unittest.TestCase): 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'], '{{project}}') + + +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)
\ No newline at end of file diff --git a/pyramid/scaffolds/alchemy/setup.py_tmpl b/pyramid/scaffolds/alchemy/setup.py_tmpl index 69b5faea9..9496b9948 100644 --- a/pyramid/scaffolds/alchemy/setup.py_tmpl +++ b/pyramid/scaffolds/alchemy/setup.py_tmpl @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'SQLAlchemy', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'zope.sqlalchemy', 'waitress', ] diff --git a/pyramid/scaffolds/copydir.py b/pyramid/scaffolds/copydir.py index ba0988523..3b871dc19 100644 --- a/pyramid/scaffolds/copydir.py +++ b/pyramid/scaffolds/copydir.py @@ -90,16 +90,16 @@ def copy_dir(source, dest, vars, verbosity, simulate, indent=0, if verbosity: out('%sRecursing into %s' % (pad, os.path.basename(full))) copy_dir((source[0], full), dest_full, vars, verbosity, simulate, - indent=indent+1, - sub_vars=sub_vars, interactive=interactive, + indent=indent+1, sub_vars=sub_vars, + interactive=interactive, overwrite=overwrite, template_renderer=template_renderer, out_=out_) continue elif not use_pkg_resources and os.path.isdir(full): if verbosity: out('%sRecursing into %s' % (pad, os.path.basename(full))) copy_dir(full, dest_full, vars, verbosity, simulate, - indent=indent+1, - sub_vars=sub_vars, interactive=interactive, + indent=indent+1, sub_vars=sub_vars, + interactive=interactive, overwrite=overwrite, template_renderer=template_renderer, out_=out_) continue elif use_pkg_resources: @@ -156,9 +156,9 @@ def should_skip_file(name): """ if name.startswith('.'): return 'Skipping hidden file %(filename)s' - if name.endswith('~') or name.endswith('.bak'): + if name.endswith(('~', '.bak')): return 'Skipping backup file %(filename)s' - if name.endswith('.pyc') or name.endswith('.pyo'): + if name.endswith(('.pyc', '.pyo')): return 'Skipping %s file ' % os.path.splitext(name)[1] + '%(filename)s' if name.endswith('$py.class'): return 'Skipping $py.class file %(filename)s' diff --git a/pyramid/scaffolds/starter/+package+/__init__.py b/pyramid/scaffolds/starter/+package+/__init__.py index 6c512f52f..ad5ecbc6f 100644 --- a/pyramid/scaffolds/starter/+package+/__init__.py +++ b/pyramid/scaffolds/starter/+package+/__init__.py @@ -5,6 +5,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(settings=settings) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.add_route('home', '/') config.scan() diff --git a/pyramid/scaffolds/starter/+package+/templates/mytemplate.pt_tmpl b/pyramid/scaffolds/starter/+package+/templates/mytemplate.pt_tmpl index 34706ec2f..c9a211935 100644 --- a/pyramid/scaffolds/starter/+package+/templates/mytemplate.pt_tmpl +++ b/pyramid/scaffolds/starter/+package+/templates/mytemplate.pt_tmpl @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/pyramid/scaffolds/starter/setup.py_tmpl b/pyramid/scaffolds/starter/setup.py_tmpl index c0908d96f..3802c3e23 100644 --- a/pyramid/scaffolds/starter/setup.py_tmpl +++ b/pyramid/scaffolds/starter/setup.py_tmpl @@ -10,6 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', 'pyramid_debugtoolbar', 'waitress', ] diff --git a/pyramid/scaffolds/template.py b/pyramid/scaffolds/template.py index 39d0e4b3f..d88f5b2a6 100644 --- a/pyramid/scaffolds/template.py +++ b/pyramid/scaffolds/template.py @@ -35,7 +35,8 @@ class Template(object): content = native_(content, fsenc) try: return bytes_( - substitute_double_braces(content, TypeMapper(vars)), fsenc) + substitute_escaped_double_braces( + substitute_double_braces(content, TypeMapper(vars))), fsenc) except Exception as e: _add_except(e, ' in file %s' % filename) raise @@ -148,7 +149,15 @@ def substitute_double_braces(content, values): value = match.group('braced').strip() return values[value] return double_brace_pattern.sub(double_bracerepl, content) - + +escaped_double_brace_pattern = re.compile(r'\\{\\{(?P<escape_braced>[^\\]*?)\\}\\}') + +def substitute_escaped_double_braces(content): + def escaped_double_bracerepl(match): + value = match.group('escape_braced').strip() + return "{{%(value)s}}" % locals() + return escaped_double_brace_pattern.sub(escaped_double_bracerepl, content) + def _add_except(exc, info): # pragma: no cover if not hasattr(exc, 'args') or exc.args is None: return diff --git a/pyramid/scaffolds/tests.py b/pyramid/scaffolds/tests.py index b90e494e9..d913d022a 100644 --- a/pyramid/scaffolds/tests.py +++ b/pyramid/scaffolds/tests.py @@ -9,22 +9,18 @@ import time try: import httplib except ImportError: # pragma: no cover - import http.client as httplib - -from pyramid.compat import PY3 + import http.client as httplib #py3 class TemplateTest(object): def make_venv(self, directory): # pragma: no cover import virtualenv - import sys from virtualenv import Logger logger = Logger([(Logger.level_for_integer(2), sys.stdout)]) virtualenv.logger = logger virtualenv.create_environment(directory, site_packages=False, clear=False, - unzip_setuptools=True, - use_distribute=PY3) + unzip_setuptools=True) def install(self, tmpl_name): # pragma: no cover try: self.old_cwd = os.getcwd() @@ -70,10 +66,7 @@ class TemplateTest(object): os.chdir(self.old_cwd) if __name__ == '__main__': # pragma: no cover - templates = ['starter', 'alchemy',] - - if sys.version_info >= (2, 6) and sys.version_info < (3, 0): - templates.append('zodb') + templates = ['starter', 'alchemy', 'zodb'] for name in templates: test = TemplateTest() diff --git a/pyramid/scaffolds/zodb/+package+/__init__.py b/pyramid/scaffolds/zodb/+package+/__init__.py index c3bb87a62..f2a86df47 100644 --- a/pyramid/scaffolds/zodb/+package+/__init__.py +++ b/pyramid/scaffolds/zodb/+package+/__init__.py @@ -12,6 +12,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(root_factory=root_factory, settings=settings) + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.scan() return config.make_wsgi_app() diff --git a/pyramid/scaffolds/zodb/+package+/static/pyramid-small.png b/pyramid/scaffolds/zodb/+package+/static/pyramid-small.png Binary files differdeleted file mode 100644 index a5bc0ade7..000000000 --- a/pyramid/scaffolds/zodb/+package+/static/pyramid-small.png +++ /dev/null diff --git a/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt b/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt index 200dac6d0..5a2ce2bd7 100644 --- a/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt +++ b/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/pyramid/scaffolds/zodb/setup.py_tmpl b/pyramid/scaffolds/zodb/setup.py_tmpl index 02789657d..3a6032429 100644 --- a/pyramid/scaffolds/zodb/setup.py_tmpl +++ b/pyramid/scaffolds/zodb/setup.py_tmpl @@ -10,10 +10,11 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', + 'pyramid_chameleon', + 'pyramid_debugtoolbar', + 'pyramid_tm', 'pyramid_zodbconn', 'transaction', - 'pyramid_tm', - 'pyramid_debugtoolbar', 'ZODB3', 'waitress', ] diff --git a/pyramid/scripts/pcreate.py b/pyramid/scripts/pcreate.py index ba4eb0856..5e2240856 100644 --- a/pyramid/scripts/pcreate.py +++ b/pyramid/scripts/pcreate.py @@ -77,8 +77,8 @@ class PCreateCommand(object): def render_scaffolds(self): options = self.options args = self.args - project_name = os.path.basename(args[0]) output_dir = os.path.abspath(os.path.normpath(args[0])) + project_name = os.path.basename(os.path.split(output_dir)[1]) pkg_name = _bad_chars_re.sub('', project_name.lower()) safe_name = pkg_resources.safe_name(project_name) egg_name = pkg_resources.to_filename(safe_name) diff --git a/pyramid/scripts/pdistreport.py b/pyramid/scripts/pdistreport.py new file mode 100644 index 000000000..10edb5715 --- /dev/null +++ b/pyramid/scripts/pdistreport.py @@ -0,0 +1,37 @@ +import sys +import platform +import pkg_resources +import optparse +from operator import itemgetter + +def out(*args): # pragma: no cover + for arg in args: + sys.stdout.write(arg) + sys.stdout.write(' ') + sys.stdout.write('\n') + +def main(argv=sys.argv, pkg_resources=pkg_resources, platform=platform.platform, + out=out): + # all args except argv are for unit testing purposes only + description = "Show Python distribution versions and locations in use" + usage = "usage: %prog" + parser = optparse.OptionParser(usage, description=description) + parser.parse_args(argv[1:]) + packages = [] + for distribution in pkg_resources.working_set: + name = distribution.project_name + packages.append( + {'version': distribution.version, + 'lowername': name.lower(), + 'name': name, + 'location':distribution.location} + ) + packages = sorted(packages, key=itemgetter('lowername')) + pyramid_version = pkg_resources.get_distribution('pyramid').version + plat = platform() + out('Pyramid version:', pyramid_version) + out('Platform:', plat) + out('Packages:') + for package in packages: + out(' ', package['name'], package['version']) + out(' ', package['location']) diff --git a/pyramid/scripts/prequest.py b/pyramid/scripts/prequest.py index da6b8cc14..8628d5a5a 100644 --- a/pyramid/scripts/prequest.py +++ b/pyramid/scripts/prequest.py @@ -1,3 +1,4 @@ +import base64 import optparse import sys import textwrap @@ -18,9 +19,22 @@ class PRequestCommand(object): This command makes an artifical request to a web application that uses a PasteDeploy (.ini) configuration file for the server and application. - Use "prequest config.ini /path" to request "/path". Use "prequest - --method=POST config.ini /path < data" to do a POST with the given - request body. + Use "prequest config.ini /path" to request "/path". + + Use "prequest --method=POST config.ini /path < data" to do a POST with + the given request body. + + Use "prequest --method=PUT config.ini /path < data" to do a + PUT with the given request body. + + Use "prequest --method=PATCH config.ini /path < data" to do a + PATCH with the given request body. + + Use "prequest --method=OPTIONS config.ini /path" to do an + OPTIONS request. + + Use "prequest --method=PROPFIND config.ini /path" to do a + PROPFIND request. If the path is relative (doesn't begin with "/") it is interpreted as relative to "/". The path passed to this script should be URL-quoted. @@ -59,9 +73,17 @@ class PRequestCommand(object): parser.add_option( '-m', '--method', dest='method', - choices=['GET', 'HEAD', 'POST', 'DELETE'], + choices=['GET', 'HEAD', 'POST', 'PUT', 'PATCH','DELETE', + 'PROPFIND', 'OPTIONS'], type='choice', - help='Request method type (GET, POST, DELETE)', + help='Request method type (GET, POST, PUT, PATCH, DELETE, ' + 'PROPFIND, OPTIONS)', + ) + parser.add_option( + '-l', '--login', + dest='login', + type='string', + help='HTTP basic auth username:password pair', ) get_app = staticmethod(get_app) @@ -92,6 +114,10 @@ class PRequestCommand(object): path = url_unquote(path) headers = {} + if self.options.login: + enc = base64.b64encode(self.options.login.encode('ascii')) + headers['Authorization'] = 'Basic ' + enc.decode('ascii') + if self.options.headers: for item in self.options.headers: if ':' not in item: @@ -110,9 +136,9 @@ class PRequestCommand(object): environ = { 'REQUEST_METHOD': request_method, 'SCRIPT_NAME': '', # may be empty if app is at the root - 'PATH_INFO': path, + 'PATH_INFO': path, 'SERVER_NAME': 'localhost', # always mandatory - 'SERVER_PORT': '80', # always mandatory + 'SERVER_PORT': '80', # always mandatory 'SERVER_PROTOCOL': 'HTTP/1.0', 'CONTENT_TYPE': 'text/plain', 'REMOTE_ADDR':'127.0.0.1', @@ -127,7 +153,7 @@ class PRequestCommand(object): 'paste.command_request': True, } - if request_method == 'POST': + if request_method in ('POST', 'PUT', 'PATCH'): environ['wsgi.input'] = self.stdin environ['CONTENT_LENGTH'] = '-1' diff --git a/pyramid/scripts/pserve.py b/pyramid/scripts/pserve.py index b840fbdb9..8cceecbb3 100644 --- a/pyramid/scripts/pserve.py +++ b/pyramid/scripts/pserve.py @@ -25,6 +25,7 @@ import traceback from paste.deploy import loadserver from paste.deploy import loadapp +from pyramid.compat import PY3 from pyramid.compat import WIN from pyramid.paster import setup_logging @@ -65,7 +66,7 @@ class PServeCommand(object): You can also include variable assignments like 'http_port=8080' and then use %(http_port)s in your config files. """ - verbose = 1 + default_verbosity = 1 parser = optparse.OptionParser( usage, @@ -125,6 +126,18 @@ class PServeCommand(object): action='store_true', dest='show_status', help="Show the status of the (presumably daemonized) server") + parser.add_option( + '-v', '--verbose', + default=default_verbosity, + dest='verbose', + action='count', + help="Set verbose level (default "+str(default_verbosity)+")") + parser.add_option( + '-q', '--quiet', + action='store_const', + const=0, + dest='verbose', + help="Suppress verbose output") if hasattr(os, 'setuid'): # I don't think these are available on Windows @@ -148,19 +161,18 @@ class PServeCommand(object): _scheme_re = re.compile(r'^[a-z][a-z]+:', re.I) - default_verbosity = 1 - _reloader_environ_key = 'PYTHON_RELOADER_SHOULD_RUN' _monitor_environ_key = 'PASTE_MONITOR_SHOULD_RUN' possible_subcommands = ('start', 'stop', 'restart', 'status') def __init__(self, argv, quiet=False): - self.quiet = quiet self.options, self.args = self.parser.parse_args(argv[1:]) + if quiet: + self.options.verbose = 0 def out(self, msg): # pragma: no cover - if not self.quiet: + if self.options.verbose > 0: print(msg) def get_options(self): @@ -197,7 +209,7 @@ class PServeCommand(object): if self.options.reload: if os.environ.get(self._reloader_environ_key): - if self.verbose > 1: + if self.options.verbose > 1: self.out('Running reloading file monitor') install_reloader(int(self.options.reload_interval), [app_spec]) # if self.requires_config_file: @@ -271,7 +283,7 @@ class PServeCommand(object): try: self.daemonize() except DaemonizeException as ex: - if self.verbose > 0: + if self.options.verbose > 0: self.out(str(ex)) return 2 @@ -303,7 +315,7 @@ class PServeCommand(object): app = self.loadapp(app_spec, name=app_name, relative_to=base, global_conf=vars) - if self.verbose > 0: + if self.options.verbose > 0: if hasattr(os, 'getpid'): msg = 'Starting server in PID %i.' % os.getpid() else: @@ -314,7 +326,7 @@ class PServeCommand(object): try: server(app) except (SystemExit, KeyboardInterrupt) as e: - if self.verbose > 1: + if self.options.verbose > 1: raise if str(e): msg = ' ' + str(e) @@ -358,7 +370,7 @@ class PServeCommand(object): "Daemon is already running (PID: %s from PID file %s)" % (pid, self.options.pid_file)) - if self.verbose > 0: + if self.options.verbose > 0: self.out('Entering daemon mode') pid = os.fork() if pid: @@ -433,11 +445,11 @@ class PServeCommand(object): def record_pid(self, pid_file): pid = os.getpid() - if self.verbose > 1: + if self.options.verbose > 1: self.out('Writing PID %s to %s' % (pid, pid_file)) with open(pid_file, 'w') as f: f.write(str(pid)) - atexit.register(self._remove_pid_file, pid, pid_file, self.verbose) + atexit.register(self._remove_pid_file, pid, pid_file, self.options.verbose) def stop_daemon(self): # pragma: no cover pid_file = self.options.pid_file or 'pyramid.pid' @@ -490,7 +502,7 @@ class PServeCommand(object): self.restart_with_monitor(reloader=True) def restart_with_monitor(self, reloader=False): # pragma: no cover - if self.verbose > 0: + if self.options.verbose > 0: if reloader: self.out('Starting subprocess with file monitor') else: @@ -511,7 +523,7 @@ class PServeCommand(object): proc = None except KeyboardInterrupt: self.out('^C caught in monitor process') - if self.verbose > 1: + if self.options.verbose > 1: raise return 1 finally: @@ -527,7 +539,7 @@ class PServeCommand(object): # a monitor, any exit code will restart if exit_code != 3: return exit_code - if self.verbose > 0: + if self.options.verbose > 0: self.out('%s %s %s' % ('-' * 20, 'Restarting', '-' * 20)) def change_user_group(self, user, group): # pragma: no cover @@ -559,7 +571,7 @@ class PServeCommand(object): if not gid: gid = entry.pw_gid uid = entry.pw_uid - if self.verbose > 0: + if self.options.verbose > 0: self.out('Changing user to %s:%s (%s:%s)' % ( user, group or '(unknown)', uid, gid)) if gid: @@ -948,7 +960,15 @@ def cherrypy_server_runner( server = wsgiserver.CherryPyWSGIServer(bind_addr, app, server_name=server_name, **kwargs) - server.ssl_certificate = server.ssl_private_key = ssl_pem + if ssl_pem is not None: + if not PY3: + server.ssl_certificate = server.ssl_private_key = ssl_pem + else: + # creates wsgiserver.ssl_builtin as side-effect + wsgiserver.get_ssl_adapter_class() + server.ssl_adapter = wsgiserver.ssl_builtin.BuiltinSSLAdapter( + ssl_pem, ssl_pem) + if protocol_version: server.protocol = protocol_version diff --git a/pyramid/scripts/pviews.py b/pyramid/scripts/pviews.py index 081c13e9d..504f583b7 100644 --- a/pyramid/scripts/pviews.py +++ b/pyramid/scripts/pviews.py @@ -4,6 +4,7 @@ import textwrap from pyramid.interfaces import IMultiView from pyramid.paster import bootstrap +from pyramid.request import Request from pyramid.scripts.common import parse_vars def main(argv=sys.argv, quiet=False): @@ -52,7 +53,7 @@ class PViewsCommand(object): infos.append(info) return infos - def _find_view(self, url, registry): + def _find_view(self, request): """ Accept ``url`` and ``registry``; create a :term:`request` and find a :app:`Pyramid` view based on introspection of :term:`view @@ -63,22 +64,19 @@ class PViewsCommand(object): from pyramid.interfaces import IRequest from pyramid.interfaces import IRootFactory from pyramid.interfaces import IRouteRequest - from pyramid.interfaces import IRequestFactory from pyramid.interfaces import IRoutesMapper from pyramid.interfaces import IView from pyramid.interfaces import IViewClassifier from pyramid.interfaces import ITraverser - from pyramid.request import Request from pyramid.traversal import DefaultRootFactory from pyramid.traversal import ResourceTreeTraverser + registry = request.registry q = registry.queryUtility root_factory = q(IRootFactory, default=DefaultRootFactory) routes_mapper = q(IRoutesMapper) - request_factory = q(IRequestFactory, default=Request) adapters = registry.adapters - request = None @implementer(IMultiView) class RoutesMultiView(object): @@ -111,20 +109,9 @@ class PViewsCommand(object): view.__view_attr__ = '' self.views.append((None, view, None)) - - # create the request - environ = { - 'wsgi.url_scheme':'http', - 'SERVER_NAME':'localhost', - 'SERVER_PORT':'8080', - 'REQUEST_METHOD':'GET', - 'PATH_INFO':url, - } - request = request_factory(environ) context = None routes_multiview = None attrs = request.__dict__ - attrs['registry'] = registry request_iface = IRequest # find the root object @@ -236,9 +223,10 @@ class PViewsCommand(object): if not url.startswith('/'): url = '/%s' % url - env = self.bootstrap[0](config_uri, options=parse_vars(self.args[2:])) - registry = env['registry'] - view = self._find_view(url, registry) + request = Request.blank(url) + env = self.bootstrap[0](config_uri, options=parse_vars(self.args[2:]), + request=request) + view = self._find_view(request) self.out('') self.out("URL = %s" % url) self.out('') @@ -257,5 +245,6 @@ class PViewsCommand(object): else: self.out(" Not found.") self.out('') + env['closer']() return 0 diff --git a/pyramid/session.py b/pyramid/session.py index 7db8c8e0e..3708ef879 100644 --- a/pyramid/session.py +++ b/pyramid/session.py @@ -81,15 +81,22 @@ def signed_deserialize(serialized, secret, hmac=hmac): return pickle.loads(pickled) -def check_csrf_token(request, token='csrf_token', raises=True): +def check_csrf_token(request, + token='csrf_token', + header='X-CSRF-Token', + raises=True): """ Check the CSRF token in the request's session against the value in - ``request.params.get(token)``. If a ``token`` keyword is not supplied - to this function, the string ``csrf_token`` will be used to look up - the token within ``request.params``. If the value in - ``request.params.get(token)`` doesn't match the value supplied by - ``request.session.get_csrf_token()``, and ``raises`` is ``True``, this - function will raise an :exc:`pyramid.httpexceptions.HTTPBadRequest` - exception. If the check does succeed and ``raises`` is ``False``, this + ``request.params.get(token)`` or ``request.headers.get(header)``. + If a ``token`` keyword is not supplied to this function, the string + ``csrf_token`` will be used to look up the token in ``request.params``. + If a ``header`` keyword is not supplied to this function, the string + ``X-CSRF-Token`` will be used to look up the token in ``request.headers``. + + If the value supplied by param or by header doesn't match the value + supplied by ``request.session.get_csrf_token()``, and ``raises`` is + ``True``, this function will raise an + :exc:`pyramid.httpexceptions.HTTPBadRequest` exception. + If the check does succeed and ``raises`` is ``False``, this function will return ``False``. If the CSRF check is successful, this function will return ``True`` unconditionally. @@ -98,7 +105,8 @@ def check_csrf_token(request, token='csrf_token', raises=True): .. versionadded:: 1.4a2 """ - if request.params.get(token) != request.session.get_csrf_token(): + supplied_token = request.params.get(token, request.headers.get(header)) + if supplied_token != request.session.get_csrf_token(): if raises: raise HTTPBadRequest('incorrect CSRF token') return False diff --git a/pyramid/testing.py b/pyramid/testing.py index c4e83714d..4590c55f8 100644 --- a/pyramid/testing.py +++ b/pyramid/testing.py @@ -34,11 +34,8 @@ from pyramid.threadlocal import ( manager, ) -from pyramid.request import ( - DeprecatedRequestMethodsMixin, - CallbackMethodsMixin, - ) - +from pyramid.i18n import LocalizerRequestMixin +from pyramid.request import CallbackMethodsMixin from pyramid.url import URLMethodsMixin from pyramid.util import InstancePropertyMixin @@ -137,7 +134,7 @@ class DummyTemplateRenderer(object): def assert_(self, **kw): """ Accept an arbitrary set of assertion key/value pairs. For each assertion key/value pair assert that the renderer - (eg. :func:`pyramid.renderer.render_to_response`) + (eg. :func:`pyramid.renderers.render_to_response`) received the key with a value that equals the asserted value. If the renderer did not receive the key at all, or the value received by the renderer doesn't match the assertion @@ -222,6 +219,8 @@ class DummyResource: def __nonzero__(self): return True + __bool__ = __nonzero__ + def __len__(self): return len(self.subs) @@ -283,8 +282,8 @@ class DummySession(dict): @implementer(IRequest) -class DummyRequest(DeprecatedRequestMethodsMixin, URLMethodsMixin, - CallbackMethodsMixin, InstancePropertyMixin): +class DummyRequest(URLMethodsMixin, CallbackMethodsMixin, InstancePropertyMixin, + LocalizerRequestMixin): """ A DummyRequest object (incompletely) imitates a :term:`request` object. The ``params``, ``environ``, ``headers``, ``path``, and @@ -409,7 +408,7 @@ def setUp(registry=None, request=None, hook_zca=True, autocommit=True, suitable testing analogue. After ``setUp`` is finished, the registry returned by the - :func:`pyramid.threadlocal.get_current_request` function will + :func:`pyramid.threadlocal.get_current_registry` function will be the passed (or constructed) registry until :func:`pyramid.testing.tearDown` is called (or :func:`pyramid.testing.setUp` is called again) . @@ -451,18 +450,7 @@ def setUp(registry=None, request=None, hook_zca=True, autocommit=True, # someone may be passing us an esoteric "dummy" registry, and # the below won't succeed if it doesn't have a registerUtility # method. - from pyramid.config import DEFAULT_RENDERERS - for name, renderer in DEFAULT_RENDERERS: - # Cause the default renderers to be registered because - # in-the-wild test code relies on being able to call - # e.g. ``pyramid.chameleon_zpt.render_template`` - # without registering a .pt renderer, expecting the "real" - # template to be rendered. This is a holdover from when - # individual template system renderers weren't indirected - # by the ``pyramid.renderers`` machinery, and - # ``render_template`` and friends went behind the back of - # any existing renderer factory lookup system. - config.add_renderer(name, renderer) + config.add_default_renderers() config.add_default_view_predicates() config.add_default_route_predicates() config.commit() @@ -482,9 +470,9 @@ def tearDown(unhook_zca=True): If the ``unhook_zca`` argument is ``True`` (the default), call :func:`zope.component.getSiteManager.reset`. This undoes the - action of :func:`pyramid.testing.setUp` called with the + action of :func:`pyramid.testing.setUp` when called with the argument ``hook_zca=True``. If :mod:`zope.component` cannot be - imported, ignore the argument. + imported, ``unhook_zca`` is set to ``False``. """ global have_zca if unhook_zca and have_zca: @@ -508,8 +496,7 @@ def tearDown(unhook_zca=True): pass def cleanUp(*arg, **kw): - """ :func:`pyramid.testing.cleanUp` is an alias for - :func:`pyramid.testing.setUp`. """ + """ An alias for :func:`pyramid.testing.setUp`. """ return setUp(*arg, **kw) class DummyRendererFactory(object): @@ -591,10 +578,10 @@ def testConfig(registry=None, settings=None): """Returns a context manager for test set up. - This context manager calls :func:`pyramid.testing.testSetup` when + This context manager calls :func:`pyramid.testing.setUp` when entering and :func:`pyramid.testing.tearDown` when exiting. - All arguments are passed directly to :func:`pyramid.testing.testSetup`. + All arguments are passed directly to :func:`pyramid.testing.setUp`. If the ZCA is hooked, it will always be un-hooked in tearDown. This context manager allows you to write test code like this: diff --git a/pyramid/tests/fixtures/components.mak b/pyramid/tests/fixtures/components.mak deleted file mode 100644 index cc886805c..000000000 --- a/pyramid/tests/fixtures/components.mak +++ /dev/null @@ -1,3 +0,0 @@ -<%def name="comp()"> -World! -</%def>
\ No newline at end of file diff --git a/pyramid/tests/fixtures/hello .world.mako b/pyramid/tests/fixtures/hello .world.mako deleted file mode 100644 index 7a06eed97..000000000 --- a/pyramid/tests/fixtures/hello .world.mako +++ /dev/null @@ -1,3 +0,0 @@ -## -*- coding: utf-8 -*- -<%!from pyramid.compat import text_%><% a, b = 'foo', text_('föö', 'utf-8') %> -Hello ${text_('föö', 'utf-8')}
\ No newline at end of file diff --git a/pyramid/tests/fixtures/hello_inherit_pkg.mak b/pyramid/tests/fixtures/hello_inherit_pkg.mak deleted file mode 100644 index 87d18d0f7..000000000 --- a/pyramid/tests/fixtures/hello_inherit_pkg.mak +++ /dev/null @@ -1,2 +0,0 @@ -Hello World! -<%inherit file="pyramid.tests:fixtures/layout.mak"/>
\ No newline at end of file diff --git a/pyramid/tests/fixtures/hellocompo.mak b/pyramid/tests/fixtures/hellocompo.mak deleted file mode 100644 index 142676a11..000000000 --- a/pyramid/tests/fixtures/hellocompo.mak +++ /dev/null @@ -1,3 +0,0 @@ -<%namespace name="comp" file="pyramid.tests:fixtures/components.mak"/> -Namespace -Hello ${comp.comp()}
\ No newline at end of file diff --git a/pyramid/tests/fixtures/helloinherit.mak b/pyramid/tests/fixtures/helloinherit.mak deleted file mode 100644 index 53edd71ed..000000000 --- a/pyramid/tests/fixtures/helloinherit.mak +++ /dev/null @@ -1,2 +0,0 @@ -Hello World! -<%inherit file="layout.mak"/>
\ No newline at end of file diff --git a/pyramid/tests/fixtures/helloworld.mak b/pyramid/tests/fixtures/helloworld.mak deleted file mode 100644 index 25283a50d..000000000 --- a/pyramid/tests/fixtures/helloworld.mak +++ /dev/null @@ -1,3 +0,0 @@ -## -*- coding: utf-8 -*- -<%!from pyramid.compat import text_%><% a, b = 'foo', text_('föö', 'utf-8') %> -Hello ${text_('föö', 'utf-8')} diff --git a/pyramid/tests/fixtures/helloworld.mako b/pyramid/tests/fixtures/helloworld.mako deleted file mode 100644 index 25283a50d..000000000 --- a/pyramid/tests/fixtures/helloworld.mako +++ /dev/null @@ -1,3 +0,0 @@ -## -*- coding: utf-8 -*- -<%!from pyramid.compat import text_%><% a, b = 'foo', text_('föö', 'utf-8') %> -Hello ${text_('föö', 'utf-8')} diff --git a/pyramid/tests/fixtures/layout.mak b/pyramid/tests/fixtures/layout.mak deleted file mode 100644 index 3bef88bf8..000000000 --- a/pyramid/tests/fixtures/layout.mak +++ /dev/null @@ -1,2 +0,0 @@ -Layout -${next.body()}
\ No newline at end of file diff --git a/pyramid/tests/fixtures/minimal.pt b/pyramid/tests/fixtures/minimal.pt deleted file mode 100644 index 693d155ef..000000000 --- a/pyramid/tests/fixtures/minimal.pt +++ /dev/null @@ -1,3 +0,0 @@ -<div xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal"> -</div> diff --git a/pyramid/tests/fixtures/nonminimal.mak b/pyramid/tests/fixtures/nonminimal.mak deleted file mode 100644 index 9de95ec92..000000000 --- a/pyramid/tests/fixtures/nonminimal.mak +++ /dev/null @@ -1 +0,0 @@ -Hello, ${name}! diff --git a/pyramid/tests/fixtures/pp.pt b/pyramid/tests/fixtures/pp.pt deleted file mode 100644 index 9df7d22da..000000000 --- a/pyramid/tests/fixtures/pp.pt +++ /dev/null @@ -1,3 +0,0 @@ -<p xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal" - tal:content="wrapped">WRAPPED</p> diff --git a/pyramid/tests/fixtures/withmacro.pt b/pyramid/tests/fixtures/withmacro.pt deleted file mode 100644 index 6fa654645..000000000 --- a/pyramid/tests/fixtures/withmacro.pt +++ /dev/null @@ -1,7 +0,0 @@ -<html> -Outside macro -<metal:m define-macro="foo"> - Hello! -</metal:m> -</html> - diff --git a/pyramid/tests/pkgs/exceptionviewapp/__init__.py b/pyramid/tests/pkgs/exceptionviewapp/__init__.py index f169e0cd5..ffc1b47c6 100644 --- a/pyramid/tests/pkgs/exceptionviewapp/__init__.py +++ b/pyramid/tests/pkgs/exceptionviewapp/__init__.py @@ -1,5 +1,8 @@ +from pyramid.httpexceptions import HTTPException + def includeme(config): config.add_route('route_raise_exception', 'route_raise_exception') + config.add_route('route_raise_httpexception', 'route_raise_httpexception') config.add_route('route_raise_exception2', 'route_raise_exception2', factory='.models.route_factory') config.add_route('route_raise_exception3', 'route_raise_exception3', @@ -21,3 +24,8 @@ def includeme(config): route_name='route_raise_exception4') config.add_view('.views.whoa', context='.models.AnException', route_name='route_raise_exception4') + config.add_view('.views.raise_httpexception', + route_name='route_raise_httpexception') + config.add_view('.views.catch_httpexception', context=HTTPException) + + diff --git a/pyramid/tests/pkgs/exceptionviewapp/views.py b/pyramid/tests/pkgs/exceptionviewapp/views.py index 33b97671e..4953056bc 100644 --- a/pyramid/tests/pkgs/exceptionviewapp/views.py +++ b/pyramid/tests/pkgs/exceptionviewapp/views.py @@ -1,5 +1,6 @@ from webob import Response from .models import AnException +from pyramid.httpexceptions import HTTPBadRequest def no(request): return Response('no') @@ -15,3 +16,9 @@ def whoa(request): def raise_exception(request): raise AnException() + +def raise_httpexception(request): + raise HTTPBadRequest + +def catch_httpexception(request): + return Response('caught') diff --git a/pyramid/tests/pkgs/fixtureapp/subpackage/templates/bar.pt b/pyramid/tests/pkgs/fixtureapp/subpackage/templates/bar.pt deleted file mode 100644 index 90531a4b3..000000000 --- a/pyramid/tests/pkgs/fixtureapp/subpackage/templates/bar.pt +++ /dev/null @@ -1,2 +0,0 @@ -<html> -</html> diff --git a/pyramid/tests/pkgs/fixtureapp/templates/fixture.pt b/pyramid/tests/pkgs/fixtureapp/templates/fixture.pt deleted file mode 100644 index 06dd4e2b1..000000000 --- a/pyramid/tests/pkgs/fixtureapp/templates/fixture.pt +++ /dev/null @@ -1,6 +0,0 @@ -<html xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal"> -<head></head> -<body> -</body> -</html> diff --git a/pyramid/tests/pkgs/rendererscanapp/__init__.py b/pyramid/tests/pkgs/rendererscanapp/__init__.py index 1baec0940..f3276a063 100644 --- a/pyramid/tests/pkgs/rendererscanapp/__init__.py +++ b/pyramid/tests/pkgs/rendererscanapp/__init__.py @@ -1,6 +1,6 @@ from pyramid.view import view_config -@view_config(name='one', renderer='one.pt') +@view_config(name='one', renderer='json') def one(request): return {'name':'One!'} diff --git a/pyramid/tests/pkgs/rendererscanapp/one.pt b/pyramid/tests/pkgs/rendererscanapp/one.pt deleted file mode 100644 index 42114d94f..000000000 --- a/pyramid/tests/pkgs/rendererscanapp/one.pt +++ /dev/null @@ -1,4 +0,0 @@ -<div xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal"> - ${name} -</div> diff --git a/pyramid/tests/pkgs/rendererscanapp/two/__init__.py b/pyramid/tests/pkgs/rendererscanapp/two/__init__.py index be0077fcb..6f575dd83 100644 --- a/pyramid/tests/pkgs/rendererscanapp/two/__init__.py +++ b/pyramid/tests/pkgs/rendererscanapp/two/__init__.py @@ -1,6 +1,6 @@ from pyramid.view import view_config -@view_config(name='two', renderer='two.pt') +@view_config(name='two', renderer='json') def two(request): return {'nameagain':'Two!'} diff --git a/pyramid/tests/pkgs/rendererscanapp/two/two.pt b/pyramid/tests/pkgs/rendererscanapp/two/two.pt deleted file mode 100644 index 7eff97c22..000000000 --- a/pyramid/tests/pkgs/rendererscanapp/two/two.pt +++ /dev/null @@ -1,4 +0,0 @@ -<div xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal"> - ${nameagain} -</div> diff --git a/pyramid/tests/pkgs/viewdecoratorapp/views/templates/foo.mak b/pyramid/tests/pkgs/viewdecoratorapp/views/templates/foo.mak deleted file mode 100644 index 6a2f701b6..000000000 --- a/pyramid/tests/pkgs/viewdecoratorapp/views/templates/foo.mak +++ /dev/null @@ -1,3 +0,0 @@ -<html> -${result} -</html> diff --git a/pyramid/tests/pkgs/viewdecoratorapp/views/views.py b/pyramid/tests/pkgs/viewdecoratorapp/views/views.py index 6f7ff1e21..18ec78847 100644 --- a/pyramid/tests/pkgs/viewdecoratorapp/views/views.py +++ b/pyramid/tests/pkgs/viewdecoratorapp/views/views.py @@ -1,11 +1,11 @@ from pyramid.view import view_config -@view_config(renderer='templates/foo.mak', name='first') +@view_config(renderer='json', name='first') def first(request): return {'result':'OK1'} @view_config( - renderer='pyramid.tests.pkgs.viewdecoratorapp.views:templates/foo.mak', + renderer='json', name='second') def second(request): return {'result':'OK2'} diff --git a/pyramid/tests/test_authentication.py b/pyramid/tests/test_authentication.py index cfabf9a9d..6e9e3920d 100644 --- a/pyramid/tests/test_authentication.py +++ b/pyramid/tests/test_authentication.py @@ -908,11 +908,11 @@ class TestAuthTktCookieHelper(unittest.TestCase): self.assertTrue(result[0][1].startswith('auth_tkt=')) self.assertEqual(result[1][0], 'Set-Cookie') - self.assertTrue(result[1][1].endswith('; HttpOnly')) + self.assertTrue('; HttpOnly' in result[1][1]) self.assertTrue(result[1][1].startswith('auth_tkt=')) self.assertEqual(result[2][0], 'Set-Cookie') - self.assertTrue(result[2][1].endswith('; HttpOnly')) + self.assertTrue('; HttpOnly' in result[2][1]) self.assertTrue(result[2][1].startswith('auth_tkt=')) def test_remember_secure(self): @@ -947,6 +947,45 @@ class TestAuthTktCookieHelper(unittest.TestCase): self.assertTrue(result[1][1].endswith('; Path=/; Domain=localhost')) self.assertTrue(result[1][1].startswith('auth_tkt=')) + def test_remember_parent_domain(self): + helper = self._makeOne('secret', parent_domain=True) + request = self._makeRequest() + request.environ['HTTP_HOST'] = 'www.example.com' + result = helper.remember(request, 'other') + self.assertEqual(len(result), 1) + + self.assertEqual(result[0][0], 'Set-Cookie') + self.assertTrue(result[0][1].endswith('; Path=/; Domain=.example.com')) + self.assertTrue(result[0][1].startswith('auth_tkt=')) + + def test_remember_parent_domain_supercedes_wild_domain(self): + helper = self._makeOne('secret', parent_domain=True, wild_domain=True) + request = self._makeRequest() + request.environ['HTTP_HOST'] = 'www.example.com' + result = helper.remember(request, 'other') + self.assertEqual(len(result), 1) + self.assertTrue(result[0][1].endswith('; Domain=.example.com')) + + def test_remember_explicit_domain(self): + helper = self._makeOne('secret', domain='pyramid.bazinga') + request = self._makeRequest() + request.environ['HTTP_HOST'] = 'www.example.com' + result = helper.remember(request, 'other') + self.assertEqual(len(result), 1) + + self.assertEqual(result[0][0], 'Set-Cookie') + self.assertTrue(result[0][1].endswith('; Path=/; Domain=pyramid.bazinga')) + self.assertTrue(result[0][1].startswith('auth_tkt=')) + + def test_remember_domain_supercedes_parent_and_wild_domain(self): + helper = self._makeOne('secret', domain='pyramid.bazinga', + parent_domain=True, wild_domain=True) + request = self._makeRequest() + request.environ['HTTP_HOST'] = 'www.example.com' + result = helper.remember(request, 'other') + self.assertEqual(len(result), 1) + self.assertTrue(result[0][1].endswith('; Path=/; Domain=pyramid.bazinga')) + def test_remember_domain_has_port(self): helper = self._makeOne('secret', wild_domain=False) request = self._makeRequest() @@ -1078,13 +1117,13 @@ class TestAuthTktCookieHelper(unittest.TestCase): name, value = headers[1] self.assertEqual(name, 'Set-Cookie') self.assertEqual(value, - 'auth_tkt=""; Path=/; Domain=localhost; Max-Age=0; ' - 'Expires=Wed, 31-Dec-97 23:59:59 GMT') + 'auth_tkt=""; Path=/; Max-Age=0; ' + 'Expires=Wed, 31-Dec-97 23:59:59 GMT; Domain=localhost') name, value = headers[2] self.assertEqual(name, 'Set-Cookie') self.assertEqual(value, - 'auth_tkt=""; Path=/; Domain=.localhost; Max-Age=0; ' - 'Expires=Wed, 31-Dec-97 23:59:59 GMT') + 'auth_tkt=""; Path=/; Max-Age=0; ' + 'Expires=Wed, 31-Dec-97 23:59:59 GMT; Domain=.localhost') class TestAuthTicket(unittest.TestCase): def _makeOne(self, *arg, **kw): diff --git a/pyramid/tests/test_authorization.py b/pyramid/tests/test_authorization.py index 60b1b0c8d..05cd3b4f8 100644 --- a/pyramid/tests/test_authorization.py +++ b/pyramid/tests/test_authorization.py @@ -146,6 +146,19 @@ class TestACLAuthorizationPolicy(unittest.TestCase): policy.principals_allowed_by_permission(context, 'read')) self.assertEqual(result, ['chrism']) + def test_principals_allowed_by_permission_callable_acl(self): + from pyramid.security import Allow + from pyramid.security import DENY_ALL + context = DummyContext() + acl = lambda: [ (Allow, 'chrism', ('read', 'write')), + DENY_ALL, + (Allow, 'other', 'read') ] + context.__acl__ = acl + policy = self._makeOne() + result = sorted( + policy.principals_allowed_by_permission(context, 'read')) + self.assertEqual(result, ['chrism']) + def test_principals_allowed_by_permission_string_permission(self): from pyramid.security import Allow context = DummyContext() diff --git a/pyramid/tests/test_chameleon_text.py b/pyramid/tests/test_chameleon_text.py deleted file mode 100644 index d9f20f241..000000000 --- a/pyramid/tests/test_chameleon_text.py +++ /dev/null @@ -1,145 +0,0 @@ -import sys -import unittest - -from pyramid.compat import binary_type -from pyramid import testing - -class Base(object): - def setUp(self): - self.config = testing.setUp() - - def tearDown(self): - testing.tearDown() - - def _getTemplatePath(self, name): - import os - here = os.path.abspath(os.path.dirname(__file__)) - return os.path.join(here, 'fixtures', name) - -class Test_renderer_factory(Base, unittest.TestCase): - def _callFUT(self, info): - from pyramid.chameleon_text import renderer_factory - return renderer_factory(info) - - def test_it(self): - # this test is way too functional - from pyramid.chameleon_text import TextTemplateRenderer - info = DummyInfo() - result = self._callFUT(info) - self.assertEqual(result.__class__, TextTemplateRenderer) - -class TextTemplateRendererTests(Base, unittest.TestCase): - def _getTargetClass(self): - from pyramid.chameleon_text import TextTemplateRenderer - return TextTemplateRenderer - - def _makeOne(self, *arg, **kw): - klass = self._getTargetClass() - return klass(*arg, **kw) - - def test_instance_implements_ITemplate(self): - from zope.interface.verify import verifyObject - from pyramid.interfaces import ITemplateRenderer - path = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - verifyObject(ITemplateRenderer, self._makeOne(path, lookup)) - - def test_class_implements_ITemplate(self): - from zope.interface.verify import verifyClass - from pyramid.interfaces import ITemplateRenderer - verifyClass(ITemplateRenderer, self._getTargetClass()) - - def test_template_reified(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template, instance.__dict__['template']) - - def test_template_with_ichameleon_translate(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.translate, lookup.translate) - - def test_template_with_debug_templates(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - lookup.debug = True - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.debug, True) - - def test_template_with_reload_templates(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - lookup.auto_reload = True - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.auto_reload, True) - - def test_template_without_reload_templates(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - lookup.auto_reload = False - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.auto_reload, False) - - def test_call(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - result = instance({}, {}) - self.assertTrue(isinstance(result, binary_type)) - self.assertEqual(result, b'Hello.\n') - - def test_call_with_nondict_value(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - self.assertRaises(ValueError, instance, None, {}) - - def test_call_nonminimal(self): - nonminimal = self._getTemplatePath('nonminimal.txt') - lookup = DummyLookup() - instance = self._makeOne(nonminimal, lookup) - result = instance({'name':'Chris'}, {}) - self.assertTrue(isinstance(result, binary_type)) - self.assertEqual(result, b'Hello, Chris!\n') - - def test_implementation(self): - minimal = self._getTemplatePath('minimal.txt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - result = instance.implementation()() - self.assertTrue(isinstance(result, binary_type)) - self.assertEqual(result, b'Hello.\n') - -class DummyLookup(object): - auto_reload=True - debug = True - def translate(self, msg): pass - -class DummyRegistry(object): - def queryUtility(self, iface, name): - self.queried = iface, name - return None - - def registerUtility(self, impl, iface, name): - self.registered = impl, iface, name - -class DummyInfo(object): - def __init__(self): - self.registry = DummyRegistry() - self.type = '.pt' - self.name = 'fixtures/minimal.pt' - self.package = sys.modules[__name__] - self.settings = {} - diff --git a/pyramid/tests/test_chameleon_zpt.py b/pyramid/tests/test_chameleon_zpt.py deleted file mode 100644 index 5ac57f869..000000000 --- a/pyramid/tests/test_chameleon_zpt.py +++ /dev/null @@ -1,163 +0,0 @@ -import sys -import unittest - -from pyramid import testing -from pyramid.compat import text_type - -class Base(object): - def setUp(self): - self.config = testing.setUp() - - def tearDown(self): - testing.tearDown() - - def _getTemplatePath(self, name): - import os - here = os.path.abspath(os.path.dirname(__file__)) - return os.path.join(here, 'fixtures', name) - -class Test_renderer_factory(Base, unittest.TestCase): - def _callFUT(self, info): - from pyramid.chameleon_zpt import renderer_factory - return renderer_factory(info) - - def test_it(self): - # this test is way too functional - from pyramid.chameleon_zpt import ZPTTemplateRenderer - info = DummyInfo() - result = self._callFUT(info) - self.assertEqual(result.__class__, ZPTTemplateRenderer) - -class ZPTTemplateRendererTests(Base, unittest.TestCase): - def _getTargetClass(self): - from pyramid.chameleon_zpt import ZPTTemplateRenderer - return ZPTTemplateRenderer - - def _makeOne(self, *arg, **kw): - klass = self._getTargetClass() - return klass(*arg, **kw) - - def test_instance_implements_ITemplate(self): - from zope.interface.verify import verifyObject - from pyramid.interfaces import ITemplateRenderer - path = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - verifyObject(ITemplateRenderer, self._makeOne(path, lookup)) - - def test_class_implements_ITemplate(self): - from zope.interface.verify import verifyClass - from pyramid.interfaces import ITemplateRenderer - verifyClass(ITemplateRenderer, self._getTargetClass()) - - def test_call(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - result = instance({}, {}) - self.assertTrue(isinstance(result, text_type)) - self.assertEqual(result.rstrip('\n'), - '<div xmlns="http://www.w3.org/1999/xhtml">\n</div>') - - def test_template_reified(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template, instance.__dict__['template']) - - def test_template_with_ichameleon_translate(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.translate, lookup.translate) - - def test_template_with_debug_templates(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - lookup.debug = True - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.debug, True) - - def test_template_without_debug_templates(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - lookup.debug = False - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.debug, False) - - def test_template_with_reload_templates(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - lookup.auto_reload = True - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.auto_reload, True) - - def test_template_without_reload_templates(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - lookup.auto_reload = False - instance = self._makeOne(minimal, lookup) - self.assertFalse('template' in instance.__dict__) - template = instance.template - self.assertEqual(template.auto_reload, False) - - def test_call_with_nondict_value(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - self.assertRaises(ValueError, instance, None, {}) - - def test_implementation(self): - minimal = self._getTemplatePath('minimal.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - result = instance.implementation()() - self.assertTrue(isinstance(result, text_type)) - self.assertEqual(result.rstrip('\n'), - '<div xmlns="http://www.w3.org/1999/xhtml">\n</div>') - - def test_macro_supplied(self): - minimal = self._getTemplatePath('withmacro.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup, macro='foo') - result = instance.implementation()() - self.assertEqual(result, '\n Hello!\n') - - def test_macro_notsupplied(self): - minimal = self._getTemplatePath('withmacro.pt') - lookup = DummyLookup() - instance = self._makeOne(minimal, lookup) - result = instance.implementation()() - self.assertEqual(result, - '<html>\nOutside macro\n\n Hello!\n\n</html>\n\n') - -class DummyLookup(object): - auto_reload=True - debug = True - def translate(self, msg): pass - -class DummyRegistry(object): - def queryUtility(self, iface, name): - self.queried = iface, name - return None - - def registerUtility(self, impl, iface, name): - self.registered = impl, iface, name - -class DummyInfo(object): - def __init__(self): - self.registry = DummyRegistry() - self.type = '.pt' - self.name = 'fixtures/minimal.pt' - self.package = sys.modules[__name__] - self.settings = {} - diff --git a/pyramid/tests/test_config/files/minimal.pt b/pyramid/tests/test_config/files/minimal.pt deleted file mode 100644 index 693d155ef..000000000 --- a/pyramid/tests/test_config/files/minimal.pt +++ /dev/null @@ -1,3 +0,0 @@ -<div xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal"> -</div> diff --git a/pyramid/tests/test_config/files/minimal.txt b/pyramid/tests/test_config/files/minimal.txt new file mode 100644 index 000000000..19fe66dfa --- /dev/null +++ b/pyramid/tests/test_config/files/minimal.txt @@ -0,0 +1 @@ +<div clas="header"></div> diff --git a/pyramid/tests/test_config/pkgs/asset/subpackage/templates/bar.pt b/pyramid/tests/test_config/pkgs/asset/subpackage/templates/bar.pt deleted file mode 100644 index 90531a4b3..000000000 --- a/pyramid/tests/test_config/pkgs/asset/subpackage/templates/bar.pt +++ /dev/null @@ -1,2 +0,0 @@ -<html> -</html> diff --git a/pyramid/tests/test_config/pkgs/asset/templates/fixture.pt b/pyramid/tests/test_config/pkgs/asset/templates/fixture.pt deleted file mode 100644 index 06dd4e2b1..000000000 --- a/pyramid/tests/test_config/pkgs/asset/templates/fixture.pt +++ /dev/null @@ -1,6 +0,0 @@ -<html xmlns="http://www.w3.org/1999/xhtml" - xmlns:tal="http://xml.zope.org/namespaces/tal"> -<head></head> -<body> -</body> -</html> diff --git a/pyramid/tests/test_config/test_assets.py b/pyramid/tests/test_config/test_assets.py index 5fe02c358..345e7f8d6 100644 --- a/pyramid/tests/test_config/test_assets.py +++ b/pyramid/tests/test_config/test_assets.py @@ -314,16 +314,40 @@ class TestPackageOverrides(unittest.TestCase): from pyramid.config.assets import PackageOverrides return PackageOverrides - def _makeOne(self, package, pkg_resources=None): + def _makeOne(self, package=None, pkg_resources=None): + if package is None: + package = DummyPackage('package') klass = self._getTargetClass() if pkg_resources is None: pkg_resources = DummyPkgResources() return klass(package, pkg_resources=pkg_resources) + def test_class_conforms_to_IPackageOverrides(self): + from zope.interface.verify import verifyClass + from pyramid.interfaces import IPackageOverrides + verifyClass(IPackageOverrides, self._getTargetClass()) + + def test_instance_conforms_to_IPackageOverrides(self): + from zope.interface.verify import verifyObject + from pyramid.interfaces import IPackageOverrides + verifyObject(IPackageOverrides, self._makeOne()) + + def test_class_conforms_to_IPEP302Loader(self): + from zope.interface.verify import verifyClass + from pyramid.interfaces import IPEP302Loader + verifyClass(IPEP302Loader, self._getTargetClass()) + + def test_instance_conforms_to_IPEP302Loader(self): + from zope.interface.verify import verifyObject + from pyramid.interfaces import IPEP302Loader + verifyObject(IPEP302Loader, self._makeOne()) + def test_ctor_package_already_has_loader_of_different_type(self): package = DummyPackage('package') - package.__loader__ = True - self.assertRaises(TypeError, self._makeOne, package) + loader = package.__loader__ = DummyLoader() + po = self._makeOne(package) + self.assertTrue(package.__loader__ is po) + self.assertTrue(po.real_loader is loader) def test_ctor_package_already_has_loader_of_same_type(self): package = DummyPackage('package') @@ -502,6 +526,55 @@ class TestPackageOverrides(unittest.TestCase): po.overrides= overrides self.assertEqual(po.listdir('whatever'), None) + # PEP 302 __loader__ extensions: use the "real" __loader__, if present. + def test_get_data_pkg_has_no___loader__(self): + package = DummyPackage('package') + po = self._makeOne(package) + self.assertRaises(NotImplementedError, po.get_data, 'whatever') + + def test_get_data_pkg_has___loader__(self): + package = DummyPackage('package') + loader = package.__loader__ = DummyLoader() + po = self._makeOne(package) + self.assertEqual(po.get_data('whatever'), b'DEADBEEF') + self.assertEqual(loader._got_data, 'whatever') + + def test_is_package_pkg_has_no___loader__(self): + package = DummyPackage('package') + po = self._makeOne(package) + self.assertRaises(NotImplementedError, po.is_package, 'whatever') + + def test_is_package_pkg_has___loader__(self): + package = DummyPackage('package') + loader = package.__loader__ = DummyLoader() + po = self._makeOne(package) + self.assertTrue(po.is_package('whatever')) + self.assertEqual(loader._is_package, 'whatever') + + def test_get_code_pkg_has_no___loader__(self): + package = DummyPackage('package') + po = self._makeOne(package) + self.assertRaises(NotImplementedError, po.get_code, 'whatever') + + def test_get_code_pkg_has___loader__(self): + package = DummyPackage('package') + loader = package.__loader__ = DummyLoader() + po = self._makeOne(package) + self.assertEqual(po.get_code('whatever'), b'DEADBEEF') + self.assertEqual(loader._got_code, 'whatever') + + def test_get_source_pkg_has_no___loader__(self): + package = DummyPackage('package') + po = self._makeOne(package) + self.assertRaises(NotImplementedError, po.get_source, 'whatever') + + def test_get_source_pkg_has___loader__(self): + package = DummyPackage('package') + loader = package.__loader__ = DummyLoader() + po = self._makeOne(package) + self.assertEqual(po.get_source('whatever'), 'def foo():\n pass') + self.assertEqual(loader._got_source, 'whatever') + class TestDirectoryOverride(unittest.TestCase): def _getTargetClass(self): from pyramid.config.assets import DirectoryOverride @@ -570,10 +643,25 @@ class DummyPkgResources: def register_loader_type(self, typ, inst): self.registered.append((typ, inst)) - + class DummyPackage: def __init__(self, name): self.__name__ = name + +class DummyLoader: + _got_data = _is_package = None + def get_data(self, path): + self._got_data = path + return b'DEADBEEF' + def is_package(self, fullname): + self._is_package = fullname + return True + def get_code(self, fullname): + self._got_code = fullname + return b'DEADBEEF' + def get_source(self, fullname): + self._got_source = fullname + return 'def foo():\n pass' class DummyUnderOverride: def __call__(self, package, path, override_package, override_prefix, diff --git a/pyramid/tests/test_config/test_factories.py b/pyramid/tests/test_config/test_factories.py index e89fc077e..6e679397f 100644 --- a/pyramid/tests/test_config/test_factories.py +++ b/pyramid/tests/test_config/test_factories.py @@ -67,51 +67,6 @@ class TestFactoriesMixin(unittest.TestCase): self.assertEqual(config.registry.getUtility(ISessionFactory), dummyfactory) - def test_set_request_property_with_callable(self): - from pyramid.interfaces import IRequestExtensions - config = self._makeOne(autocommit=True) - callable = lambda x: None - config.set_request_property(callable, name='foo') - exts = config.registry.getUtility(IRequestExtensions) - self.assertTrue('foo' in exts.descriptors) - - def test_set_request_property_with_unnamed_callable(self): - from pyramid.interfaces import IRequestExtensions - config = self._makeOne(autocommit=True) - def foo(self): pass - config.set_request_property(foo, reify=True) - exts = config.registry.getUtility(IRequestExtensions) - self.assertTrue('foo' in exts.descriptors) - - def test_set_request_property_with_property(self): - from pyramid.interfaces import IRequestExtensions - config = self._makeOne(autocommit=True) - callable = property(lambda x: None) - config.set_request_property(callable, name='foo') - exts = config.registry.getUtility(IRequestExtensions) - self.assertTrue('foo' in exts.descriptors) - - def test_set_multiple_request_properties(self): - from pyramid.interfaces import IRequestExtensions - config = self._makeOne() - def foo(self): pass - bar = property(lambda x: None) - config.set_request_property(foo, reify=True) - config.set_request_property(bar, name='bar') - config.commit() - exts = config.registry.getUtility(IRequestExtensions) - self.assertTrue('foo' in exts.descriptors) - self.assertTrue('bar' in exts.descriptors) - - def test_set_multiple_request_properties_conflict(self): - from pyramid.exceptions import ConfigurationConflictError - config = self._makeOne() - def foo(self): pass - bar = property(lambda x: None) - config.set_request_property(foo, name='bar', reify=True) - config.set_request_property(bar, name='bar') - self.assertRaises(ConfigurationConflictError, config.commit) - def test_add_request_method_with_callable(self): from pyramid.interfaces import IRequestExtensions config = self._makeOne(autocommit=True) @@ -157,3 +112,63 @@ class TestFactoriesMixin(unittest.TestCase): self.assertRaises(AttributeError, config.add_request_method) +class TestDeprecatedFactoriesMixinMethods(unittest.TestCase): + def setUp(self): + from zope.deprecation import __show__ + __show__.off() + + def tearDown(self): + from zope.deprecation import __show__ + __show__.on() + + def _makeOne(self, *arg, **kw): + from pyramid.config import Configurator + config = Configurator(*arg, **kw) + return config + + def test_set_request_property_with_callable(self): + from pyramid.interfaces import IRequestExtensions + config = self._makeOne(autocommit=True) + callable = lambda x: None + config.set_request_property(callable, name='foo') + exts = config.registry.getUtility(IRequestExtensions) + self.assertTrue('foo' in exts.descriptors) + + def test_set_request_property_with_unnamed_callable(self): + from pyramid.interfaces import IRequestExtensions + config = self._makeOne(autocommit=True) + def foo(self): pass + config.set_request_property(foo, reify=True) + exts = config.registry.getUtility(IRequestExtensions) + self.assertTrue('foo' in exts.descriptors) + + def test_set_request_property_with_property(self): + from pyramid.interfaces import IRequestExtensions + config = self._makeOne(autocommit=True) + callable = property(lambda x: None) + config.set_request_property(callable, name='foo') + exts = config.registry.getUtility(IRequestExtensions) + self.assertTrue('foo' in exts.descriptors) + + def test_set_multiple_request_properties(self): + from pyramid.interfaces import IRequestExtensions + config = self._makeOne() + def foo(self): pass + bar = property(lambda x: None) + config.set_request_property(foo, reify=True) + config.set_request_property(bar, name='bar') + config.commit() + exts = config.registry.getUtility(IRequestExtensions) + self.assertTrue('foo' in exts.descriptors) + self.assertTrue('bar' in exts.descriptors) + + def test_set_multiple_request_properties_conflict(self): + from pyramid.exceptions import ConfigurationConflictError + config = self._makeOne() + def foo(self): pass + bar = property(lambda x: None) + config.set_request_property(foo, name='bar', reify=True) + config.set_request_property(bar, name='bar') + self.assertRaises(ConfigurationConflictError, config.commit) + + diff --git a/pyramid/tests/test_config/test_i18n.py b/pyramid/tests/test_config/test_i18n.py index 25cb88cc3..71c68af8a 100644 --- a/pyramid/tests/test_config/test_i18n.py +++ b/pyramid/tests/test_config/test_i18n.py @@ -42,13 +42,10 @@ class TestI18NConfiguratorMixin(unittest.TestCase): def test_add_translation_dirs_no_specs(self): from pyramid.interfaces import ITranslationDirectories - from pyramid.interfaces import IChameleonTranslate config = self._makeOne() config.add_translation_dirs() self.assertEqual(config.registry.queryUtility(ITranslationDirectories), None) - self.assertEqual(config.registry.queryUtility(IChameleonTranslate), - None) def test_add_translation_dirs_asset_spec(self): from pyramid.interfaces import ITranslationDirectories @@ -83,19 +80,6 @@ class TestI18NConfiguratorMixin(unittest.TestCase): self.assertEqual(config.registry.getUtility(ITranslationDirectories), [locale3, locale, locale2]) - def test_add_translation_dirs_registers_chameleon_translate(self): - from pyramid.interfaces import IChameleonTranslate - from pyramid.threadlocal import manager - request = DummyRequest() - config = self._makeOne(autocommit=True) - manager.push({'request':request, 'registry':config.registry}) - try: - config.add_translation_dirs('pyramid.tests.pkgs.localeapp:locale') - translate = config.registry.getUtility(IChameleonTranslate) - self.assertEqual(translate('Approve'), 'Approve') - finally: - manager.pop() - def test_add_translation_dirs_abspath(self): from pyramid.interfaces import ITranslationDirectories config = self._makeOne(autocommit=True) @@ -103,12 +87,3 @@ class TestI18NConfiguratorMixin(unittest.TestCase): self.assertEqual(config.registry.getUtility(ITranslationDirectories), [locale]) -class DummyRequest: - subpath = () - matchdict = None - def __init__(self, environ=None): - if environ is None: - environ = {} - self.environ = environ - self.params = {} - self.cookies = {} diff --git a/pyramid/tests/test_config/test_init.py b/pyramid/tests/test_config/test_init.py index 7c2880a18..d6dba17f6 100644 --- a/pyramid/tests/test_config/test_init.py +++ b/pyramid/tests/test_config/test_init.py @@ -3,7 +3,6 @@ import warnings import os -from pyramid.compat import PYPY from pyramid.compat import im_func from pyramid.testing import skip_on @@ -69,11 +68,6 @@ class ConfiguratorTests(unittest.TestCase): config.commit() self.assertTrue(config.registry.getUtility(IRendererFactory, 'json')) self.assertTrue(config.registry.getUtility(IRendererFactory, 'string')) - if not PYPY: - self.assertTrue(config.registry.getUtility(IRendererFactory, '.pt')) - self.assertTrue(config.registry.getUtility(IRendererFactory,'.txt')) - self.assertTrue(config.registry.getUtility(IRendererFactory, '.mak')) - self.assertTrue(config.registry.getUtility(IRendererFactory, '.mako')) def test_begin(self): from pyramid.config import Configurator @@ -233,6 +227,14 @@ class ConfiguratorTests(unittest.TestCase): config = self._makeOne(introspection=False) self.assertEqual(config.introspection, False) + def test_ctor_default_webob_response_adapter_registered(self): + from webob import Response as WebobResponse + response = WebobResponse() + from pyramid.interfaces import IResponse + config = self._makeOne(autocommit=True) + result = config.registry.queryAdapter(response, IResponse) + self.assertEqual(result, response) + def test_with_package_module(self): from pyramid.tests.test_config import test_init import pyramid.tests @@ -556,35 +558,6 @@ class ConfiguratorTests(unittest.TestCase): utility = reg.getUtility(IRequestFactory) self.assertEqual(utility, pyramid.tests.test_config) - def test_setup_registry_renderer_globals_factory(self): - from pyramid.registry import Registry - from pyramid.interfaces import IRendererGlobalsFactory - reg = Registry() - config = self._makeOne(reg) - factory = object() - with warnings.catch_warnings(): - warnings.filterwarnings('ignore') - config.setup_registry(renderer_globals_factory=factory) - self.assertEqual(reg.queryUtility(IRendererGlobalsFactory), None) - config.commit() - utility = reg.getUtility(IRendererGlobalsFactory) - self.assertEqual(utility, factory) - - def test_setup_registry_renderer_globals_factory_dottedname(self): - from pyramid.registry import Registry - from pyramid.interfaces import IRendererGlobalsFactory - reg = Registry() - config = self._makeOne(reg) - import pyramid.tests.test_config - with warnings.catch_warnings(): - warnings.filterwarnings('ignore') - config.setup_registry( - renderer_globals_factory='pyramid.tests.test_config') - self.assertEqual(reg.queryUtility(IRendererGlobalsFactory), None) - config.commit() - utility = reg.getUtility(IRendererGlobalsFactory) - self.assertEqual(utility, pyramid.tests.test_config) - def test_setup_registry_alternate_renderers(self): from pyramid.registry import Registry from pyramid.interfaces import IRendererFactory @@ -1188,221 +1161,6 @@ pyramid.tests.test_config.dummy_include2""", foo_meth = config.foo self.assertTrue(getattr(foo_meth, im_func) is foo) -class TestConfiguratorDeprecatedFeatures(unittest.TestCase): - - def setUp(self): - self.warnings = warnings.catch_warnings() - self.warnings.__enter__() - warnings.filterwarnings('ignore') - - def tearDown(self): - self.warnings.__exit__(None, None, None) - - def _makeOne(self, *arg, **kw): - from pyramid.config import Configurator - config = Configurator(*arg, **kw) - config.registry._dont_resolve_responses = True - return config - - def _getRouteRequestIface(self, config, name): - from pyramid.interfaces import IRouteRequest - iface = config.registry.getUtility(IRouteRequest, name) - return iface - - def _getViewCallable(self, config, ctx_iface=None, request_iface=None, - name='', exception_view=False): - from zope.interface import Interface - from pyramid.interfaces import IView - from pyramid.interfaces import IViewClassifier - from pyramid.interfaces import IExceptionViewClassifier - if exception_view: - classifier = IExceptionViewClassifier - else: - classifier = IViewClassifier - if ctx_iface is None: - ctx_iface = Interface - return config.registry.adapters.lookup( - (classifier, request_iface, ctx_iface), IView, name=name, - default=None) - - def _registerRenderer(self, config, name='.txt'): - from pyramid.interfaces import IRendererFactory - from pyramid.interfaces import ITemplateRenderer - from zope.interface import implementer - @implementer(ITemplateRenderer) - class Renderer: - def __init__(self, info): - self.__class__.info = info - def __call__(self, *arg): - return 'Hello!' - config.registry.registerUtility(Renderer, IRendererFactory, name=name) - return Renderer - - def _assertRoute(self, config, name, path, num_predicates=0): - from pyramid.interfaces import IRoutesMapper - mapper = config.registry.getUtility(IRoutesMapper) - routes = mapper.get_routes() - route = routes[0] - self.assertEqual(len(routes), 1) - self.assertEqual(route.name, name) - self.assertEqual(route.path, path) - self.assertEqual(len(routes[0].predicates), num_predicates) - return route - - def _makeRequest(self, config): - request = DummyRequest() - request.registry = config.registry - return request - - def test_add_route_with_view(self): - from pyramid.renderers import null_renderer - config = self._makeOne(autocommit=True) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, view_renderer=null_renderer) - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, None, request_type) - self.assertEqual(wrapper(None, None), 'OK') - self._assertRoute(config, 'name', 'path') - - def test_add_route_with_view_context(self): - from pyramid.renderers import null_renderer - config = self._makeOne(autocommit=True) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, view_context=IDummy, - view_renderer=null_renderer) - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, IDummy, request_type) - self.assertEqual(wrapper(None, None), 'OK') - self._assertRoute(config, 'name', 'path') - wrapper = self._getViewCallable(config, IOther, request_type) - self.assertEqual(wrapper, None) - - def test_add_route_with_view_exception(self): - from pyramid.renderers import null_renderer - from zope.interface import implementedBy - config = self._makeOne(autocommit=True) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, view_context=RuntimeError, - view_renderer=null_renderer) - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable( - config, ctx_iface=implementedBy(RuntimeError), - request_iface=request_type, exception_view=True) - self.assertEqual(wrapper(None, None), 'OK') - self._assertRoute(config, 'name', 'path') - wrapper = self._getViewCallable( - config, ctx_iface=IOther, - request_iface=request_type, exception_view=True) - self.assertEqual(wrapper, None) - - def test_add_route_with_view_for(self): - from pyramid.renderers import null_renderer - config = self._makeOne(autocommit=True) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, view_for=IDummy, - view_renderer=null_renderer) - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, IDummy, request_type) - self.assertEqual(wrapper(None, None), 'OK') - self._assertRoute(config, 'name', 'path') - wrapper = self._getViewCallable(config, IOther, request_type) - self.assertEqual(wrapper, None) - - def test_add_route_with_for_(self): - from pyramid.renderers import null_renderer - config = self._makeOne(autocommit=True) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, for_=IDummy, - view_renderer=null_renderer) - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, IDummy, request_type) - self.assertEqual(wrapper(None, None), 'OK') - self._assertRoute(config, 'name', 'path') - wrapper = self._getViewCallable(config, IOther, request_type) - self.assertEqual(wrapper, None) - - def test_add_route_with_view_renderer(self): - config = self._makeOne(autocommit=True) - self._registerRenderer(config) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, - view_renderer='files/minimal.txt') - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, None, request_type) - self._assertRoute(config, 'name', 'path') - self.assertEqual(wrapper(None, None).body, b'Hello!') - - def test_add_route_with_view_attr(self): - from pyramid.renderers import null_renderer - config = self._makeOne(autocommit=True) - self._registerRenderer(config) - class View(object): - def __init__(self, context, request): - pass - def alt(self): - return 'OK' - config.add_route('name', 'path', view=View, view_attr='alt', - view_renderer=null_renderer) - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, None, request_type) - self._assertRoute(config, 'name', 'path') - request = self._makeRequest(config) - self.assertEqual(wrapper(None, request), 'OK') - - def test_add_route_with_view_renderer_alias(self): - config = self._makeOne(autocommit=True) - self._registerRenderer(config) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, - renderer='files/minimal.txt') - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, None, request_type) - self._assertRoute(config, 'name', 'path') - self.assertEqual(wrapper(None, None).body, b'Hello!') - - def test_add_route_with_view_permission(self): - from pyramid.interfaces import IAuthenticationPolicy - from pyramid.interfaces import IAuthorizationPolicy - config = self._makeOne(autocommit=True) - policy = lambda *arg: None - config.registry.registerUtility(policy, IAuthenticationPolicy) - config.registry.registerUtility(policy, IAuthorizationPolicy) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, view_permission='edit') - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, None, request_type) - self._assertRoute(config, 'name', 'path') - self.assertTrue(hasattr(wrapper, '__call_permissive__')) - - def test_add_route_with_view_permission_alias(self): - from pyramid.interfaces import IAuthenticationPolicy - from pyramid.interfaces import IAuthorizationPolicy - config = self._makeOne(autocommit=True) - policy = lambda *arg: None - config.registry.registerUtility(policy, IAuthenticationPolicy) - config.registry.registerUtility(policy, IAuthorizationPolicy) - view = lambda *arg: 'OK' - config.add_route('name', 'path', view=view, permission='edit') - request_type = self._getRouteRequestIface(config, 'name') - wrapper = self._getViewCallable(config, None, request_type) - self._assertRoute(config, 'name', 'path') - self.assertTrue(hasattr(wrapper, '__call_permissive__')) - - def test_conflict_route_with_view(self): - config = self._makeOne() - def view1(request): pass - def view2(request): pass - config.add_route('a', '/a', view=view1) - config.add_route('a', '/a', view=view2) - try: - config.commit() - except ConfigurationConflictError as why: - c1, c2 = _conflictFunctions(why) - self.assertEqual(c1, 'test_conflict_route_with_view') - self.assertEqual(c2, 'test_conflict_route_with_view') - else: # pragma: no cover - raise AssertionError - class TestConfigurator_add_directive(unittest.TestCase): def setUp(self): @@ -1496,6 +1254,39 @@ class TestConfigurator_add_directive(unittest.TestCase): self.assertEqual(action['callable'], None) self.assertEqual(action['args'], config2.package) +class TestConfigurator__add_predicate(unittest.TestCase): + def _makeOne(self): + from pyramid.config import Configurator + return Configurator() + + def test_factory_as_object(self): + config = self._makeOne() + + def _fakeAction(discriminator, callable=None, args=(), kw=None, + order=0, introspectables=(), **extra): + self.assertEqual(len(introspectables), 1) + self.assertEqual(introspectables[0]['name'], 'testing') + self.assertEqual(introspectables[0]['factory'], DummyPredicate) + + config.action = _fakeAction + config._add_predicate('route', 'testing', DummyPredicate) + + def test_factory_as_dotted_name(self): + config = self._makeOne() + + def _fakeAction(discriminator, callable=None, args=(), + kw=None, order=0, introspectables=(), **extra): + self.assertEqual(len(introspectables), 1) + self.assertEqual(introspectables[0]['name'], 'testing') + self.assertEqual(introspectables[0]['factory'], DummyPredicate) + + config.action = _fakeAction + config._add_predicate( + 'route', + 'testing', + 'pyramid.tests.test_config.test_init.DummyPredicate' + ) + class TestActionState(unittest.TestCase): def _makeOne(self): from pyramid.config import ActionState @@ -1955,12 +1746,6 @@ class DummyRequest: self.params = {} self.cookies = {} -class DummyResponse: - status = '200 OK' - headerlist = () - app_iter = () - body = '' - class DummyThreadLocalManager(object): pushed = None popped = False @@ -1992,11 +1777,6 @@ class DummyRegistry(object): def queryUtility(self, *arg, **kw): return self.util -from pyramid.interfaces import IResponse -@implementer(IResponse) -class DummyResponse(object): - pass - from zope.interface import Interface class IOther(Interface): pass @@ -2021,3 +1801,5 @@ class DummyIntrospectable(object): def register(self, introspector, action_info): self.registered.append((introspector, action_info)) +class DummyPredicate(object): + pass diff --git a/pyramid/tests/test_config/test_rendering.py b/pyramid/tests/test_config/test_rendering.py index e6ee9ad70..cede64d3a 100644 --- a/pyramid/tests/test_config/test_rendering.py +++ b/pyramid/tests/test_config/test_rendering.py @@ -1,7 +1,4 @@ import unittest -import warnings - -from pyramid.tests.test_config import dummyfactory class TestRenderingConfiguratorMixin(unittest.TestCase): def _makeOne(self, *arg, **kw): @@ -9,27 +6,15 @@ class TestRenderingConfiguratorMixin(unittest.TestCase): config = Configurator(*arg, **kw) return config - def test_set_renderer_globals_factory(self): - from pyramid.interfaces import IRendererGlobalsFactory - config = self._makeOne(autocommit=True) - factory = object() - with warnings.catch_warnings(): - warnings.filterwarnings('ignore') - config.set_renderer_globals_factory(factory) - self.assertEqual( - config.registry.getUtility(IRendererGlobalsFactory), - factory) - - def test_set_renderer_globals_factory_dottedname(self): - from pyramid.interfaces import IRendererGlobalsFactory + def test_add_default_renderers(self): + from pyramid.config.rendering import DEFAULT_RENDERERS + from pyramid.interfaces import IRendererFactory config = self._makeOne(autocommit=True) - with warnings.catch_warnings(): - warnings.filterwarnings('ignore') - config.set_renderer_globals_factory( - 'pyramid.tests.test_config.dummyfactory') - self.assertEqual( - config.registry.getUtility(IRendererGlobalsFactory), - dummyfactory) + config.add_default_renderers() + for name, impl in DEFAULT_RENDERERS: + self.assertTrue( + config.registry.queryUtility(IRendererFactory, name) is not None + ) def test_add_renderer(self): from pyramid.interfaces import IRendererFactory diff --git a/pyramid/tests/test_config/test_routes.py b/pyramid/tests/test_config/test_routes.py index 6fb5189f6..1d2530c02 100644 --- a/pyramid/tests/test_config/test_routes.py +++ b/pyramid/tests/test_config/test_routes.py @@ -153,10 +153,14 @@ class RoutesConfiguratorMixinTests(unittest.TestCase): self.assertEqual(predicate(None, request), False) def test_add_route_with_custom_predicates(self): + import warnings config = self._makeOne(autocommit=True) def pred1(context, request): pass def pred2(context, request): pass - config.add_route('name', 'path', custom_predicates=(pred1, pred2)) + with warnings.catch_warnings(record=True) as w: + warnings.filterwarnings('always') + config.add_route('name', 'path', custom_predicates=(pred1, pred2)) + self.assertEqual(len(w), 1) route = self._assertRoute(config, 'name', 'path', 2) self.assertEqual(len(route.predicates), 2) diff --git a/pyramid/tests/test_config/test_util.py b/pyramid/tests/test_config/test_util.py index a984acfd0..bb61714ae 100644 --- a/pyramid/tests/test_config/test_util.py +++ b/pyramid/tests/test_config/test_util.py @@ -364,7 +364,24 @@ class TestPredicateList(unittest.TestCase): def test_unknown_predicate(self): from pyramid.exceptions import ConfigurationError self.assertRaises(ConfigurationError, self._callFUT, unknown=1) - + + def test_notted(self): + from pyramid.config import not_ + from pyramid.testing import DummyRequest + request = DummyRequest() + _, predicates, _ = self._callFUT( + xhr='xhr', + request_method=not_('POST'), + header=not_('header'), + ) + self.assertEqual(predicates[0].text(), 'xhr = True') + self.assertEqual(predicates[1].text(), + "!request_method = POST") + self.assertEqual(predicates[2].text(), '!header header') + self.assertEqual(predicates[1](None, request), True) + self.assertEqual(predicates[2](None, request), True) + + class Test_takes_one_arg(unittest.TestCase): def _callFUT(self, view, attr=None, argname=None): from pyramid.config.util import takes_one_arg @@ -543,7 +560,7 @@ class Test_takes_one_arg(unittest.TestCase): class Foo: pass foo = Foo() self.assertFalse(self._callFUT(foo)) - + def test_method_onearg_named_request(self): class Foo: def method(self, request): @@ -551,6 +568,36 @@ class Test_takes_one_arg(unittest.TestCase): foo = Foo() self.assertTrue(self._callFUT(foo.method)) +class TestNotted(unittest.TestCase): + def _makeOne(self, predicate): + from pyramid.config.util import Notted + return Notted(predicate) + + def test_it_with_phash_val(self): + pred = DummyPredicate('val') + inst = self._makeOne(pred) + self.assertEqual(inst.text(), '!val') + self.assertEqual(inst.phash(), '!val') + self.assertEqual(inst(None, None), False) + + def test_it_without_phash_val(self): + pred = DummyPredicate('') + inst = self._makeOne(pred) + self.assertEqual(inst.text(), '') + self.assertEqual(inst.phash(), '') + self.assertEqual(inst(None, None), True) + +class DummyPredicate(object): + def __init__(self, result): + self.result = result + + def text(self): + return self.result + + phash = text + + def __call__(self, context, request): + return True class DummyCustomPredicate(object): def __init__(self): @@ -579,4 +626,4 @@ class DummyRequest: class DummyConfigurator(object): def maybe_dotted(self, thing): return thing - + diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py index 94bc497ba..be2865d30 100644 --- a/pyramid/tests/test_config/test_views.py +++ b/pyramid/tests/test_config/test_views.py @@ -47,7 +47,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): def __init__(self, info): self.__class__.info = info def __call__(self, *arg): - return 'Hello!' + return b'Hello!' config.registry.registerUtility(Renderer, IRendererFactory, name=name) return Renderer @@ -109,6 +109,37 @@ class TestViewsConfigurationMixin(unittest.TestCase): view = self._getViewCallable(config) self.assertTrue(b'Hello!' in view(None, None).body) + def test_add_view_with_tmpl_renderer_factory_introspector_missing(self): + config = self._makeOne(autocommit=True) + config.introspection = False + config.introspector = None + config.add_view(renderer='dummy.pt') + view = self._getViewCallable(config) + self.assertRaises(ValueError, view, None, None) + + def test_add_view_with_tmpl_renderer_factory_no_renderer_factory(self): + config = self._makeOne(autocommit=True) + introspector = DummyIntrospector() + config.introspector = introspector + config.add_view(renderer='dummy.pt') + self.assertFalse(('renderer factories', '.pt') in + introspector.related[-1]) + view = self._getViewCallable(config) + self.assertRaises(ValueError, view, None, None) + + def test_add_view_with_tmpl_renderer_factory_with_renderer_factory(self): + config = self._makeOne(autocommit=True) + introspector = DummyIntrospector(True) + config.introspector = introspector + def dummy_factory(helper): + return lambda val, system_vals: 'Hello!' + config.add_renderer('.pt', dummy_factory) + config.add_view(renderer='dummy.pt') + self.assertTrue( + ('renderer factories', '.pt') in introspector.related[-1]) + view = self._getViewCallable(config) + self.assertTrue(b'Hello!' in view(None, None).body) + def test_add_view_wrapped_view_is_decorated(self): def view(request): # request-only wrapper """ """ @@ -264,7 +295,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): wrapper = self._getViewCallable(config) result = wrapper(None, None) self.assertEqual(result, 'OK') - + def test_add_view_as_instance_requestonly(self): from pyramid.renderers import null_renderer class AView: @@ -994,7 +1025,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): pass foo = Foo() bar = Bar() - + from pyramid.interfaces import IRequest from pyramid.interfaces import IView from pyramid.interfaces import IViewClassifier @@ -1029,6 +1060,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): config = self._makeOne(autocommit=True) renderer = self._registerRenderer(config) fixture = 'pyramid.tests.test_config:files/minimal.txt' + config.introspection = False config.add_view(view=view, renderer=fixture) wrapper = self._getViewCallable(config) request = self._makeRequest(config) @@ -1055,7 +1087,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): def __init__(self, *arg, **kw): pass def __call__(self, *arg, **kw): - return 'moo' + return b'moo' config.add_renderer(None, moo) config.add_view(view=view) wrapper = self._getViewCallable(config) @@ -1069,6 +1101,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): config = self._makeOne(autocommit=True) renderer = self._registerRenderer(config) fixture = 'pyramid.tests.test_config:files/minimal.txt' + config.introspection = False config.add_view(view=None, renderer=fixture) wrapper = self._getViewCallable(config) request = self._makeRequest(config) @@ -1198,7 +1231,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): request = self._makeRequest(config) request.method = 'HEAD' self.assertEqual(wrapper(None, request), 'OK') - + def test_add_view_with_request_param_noval_true(self): from pyramid.renderers import null_renderer view = lambda *arg: 'OK' @@ -1389,6 +1422,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): self._assertNotFound(wrapper, None, request) def test_add_view_with_custom_predicates_match(self): + import warnings from pyramid.renderers import null_renderer view = lambda *arg: 'OK' config = self._makeOne(autocommit=True) @@ -1397,13 +1431,17 @@ class TestViewsConfigurationMixin(unittest.TestCase): def pred2(context, request): return True predicates = (pred1, pred2) - config.add_view(view=view, custom_predicates=predicates, - renderer=null_renderer) + with warnings.catch_warnings(record=True) as w: + warnings.filterwarnings('always') + config.add_view(view=view, custom_predicates=predicates, + renderer=null_renderer) + self.assertEqual(len(w), 1) wrapper = self._getViewCallable(config) request = self._makeRequest(config) self.assertEqual(wrapper(None, request), 'OK') def test_add_view_with_custom_predicates_nomatch(self): + import warnings view = lambda *arg: 'OK' config = self._makeOne(autocommit=True) def pred1(context, request): @@ -1411,22 +1449,29 @@ class TestViewsConfigurationMixin(unittest.TestCase): def pred2(context, request): return False predicates = (pred1, pred2) - config.add_view(view=view, custom_predicates=predicates) + with warnings.catch_warnings(record=True) as w: + warnings.filterwarnings('always') + config.add_view(view=view, custom_predicates=predicates) + self.assertEqual(len(w), 1) wrapper = self._getViewCallable(config) request = self._makeRequest(config) self._assertNotFound(wrapper, None, request) def test_add_view_custom_predicate_bests_standard_predicate(self): + import warnings from pyramid.renderers import null_renderer view = lambda *arg: 'OK' view2 = lambda *arg: 'NOT OK' config = self._makeOne(autocommit=True) def pred1(context, request): return True - config.add_view(view=view, custom_predicates=(pred1,), - renderer=null_renderer) - config.add_view(view=view2, request_method='GET', + with warnings.catch_warnings(record=True) as w: + warnings.filterwarnings('always') + config.add_view(view=view, custom_predicates=(pred1,), renderer=null_renderer) + config.add_view(view=view2, request_method='GET', + renderer=null_renderer) + self.assertEqual(len(w), 1) wrapper = self._getViewCallable(config) request = self._makeRequest(config) request.method = 'GET' @@ -1585,7 +1630,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): context = DummyContext() request = self._makeRequest(config) self.assertRaises(PredicateMismatch, wrapper, context, request) - + def test_add_view_with_view_config_and_view_defaults_doesnt_conflict(self): from pyramid.renderers import null_renderer class view(object): @@ -1663,7 +1708,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): def __init__(self, view): pass def __call__(self, *arg, **kw): - return 'foo' + return b'foo' def view(request): return 'OK' config = self._makeOne() @@ -1687,8 +1732,8 @@ class TestViewsConfigurationMixin(unittest.TestCase): wrapped = config.registry.adapters.lookup( (IViewClassifier, request_type, Interface), IView, name='') from pyramid.request import Request - request = Request.blank('/static/minimal.pt') - request.subpath = ('minimal.pt', ) + request = Request.blank('/static/minimal.txt') + request.subpath = ('minimal.txt', ) result = wrapped(None, request) self.assertEqual(result.status, '200 OK') self.assertTrue(result.body.startswith(b'<div')) @@ -1725,7 +1770,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): config.add_static_view('static', static_path) self.assertEqual(info.added, [(config, 'static', static_path, {})]) - + def test_add_forbidden_view(self): from pyramid.renderers import null_renderer from zope.interface import implementedBy @@ -1819,7 +1864,7 @@ class TestViewsConfigurationMixin(unittest.TestCase): config = self._makeOne(autocommit=True) self.assertRaises(ConfigurationError, config.add_notfound_view, http_cache='foo') - + def test_add_notfound_view_append_slash(self): from pyramid.response import Response from pyramid.renderers import null_renderer @@ -1839,26 +1884,31 @@ class TestViewsConfigurationMixin(unittest.TestCase): request_iface=IRequest) result = view(None, request) self.assertEqual(result.location, '/scriptname/foo/?a=1&b=2') - + + # Since Python 3 has to be all cool and fancy and different... + def _assertBody(self, response, value): + from pyramid.compat import text_type + if isinstance(value, text_type): # pragma: nocover + self.assertEqual(response.text, value) + else: # pragma: nocover + self.assertEqual(response.body, value) + def test_add_notfound_view_with_renderer(self): from zope.interface import implementedBy from pyramid.interfaces import IRequest from pyramid.httpexceptions import HTTPNotFound config = self._makeOne(autocommit=True) view = lambda *arg: {} + config.introspection = False config.add_notfound_view( view, - renderer='pyramid.tests.test_config:files/minimal.pt') - config.begin() - try: # chameleon depends on being able to find a threadlocal registry - request = self._makeRequest(config) - view = self._getViewCallable(config, - ctx_iface=implementedBy(HTTPNotFound), - request_iface=IRequest) - result = view(None, request) - finally: - config.end() - self.assertTrue(b'div' in result.body) + renderer='json') + request = self._makeRequest(config) + view = self._getViewCallable(config, + ctx_iface=implementedBy(HTTPNotFound), + request_iface=IRequest) + result = view(None, request) + self._assertBody(result, '{}') def test_add_forbidden_view_with_renderer(self): from zope.interface import implementedBy @@ -1866,19 +1916,16 @@ class TestViewsConfigurationMixin(unittest.TestCase): from pyramid.httpexceptions import HTTPForbidden config = self._makeOne(autocommit=True) view = lambda *arg: {} + config.introspection = False config.add_forbidden_view( view, - renderer='pyramid.tests.test_config:files/minimal.pt') - config.begin() - try: # chameleon requires a threadlocal registry - request = self._makeRequest(config) - view = self._getViewCallable(config, - ctx_iface=implementedBy(HTTPForbidden), - request_iface=IRequest) - result = view(None, request) - finally: - config.end() - self.assertTrue(b'div' in result.body) + renderer='json') + request = self._makeRequest(config) + view = self._getViewCallable(config, + ctx_iface=implementedBy(HTTPForbidden), + request_iface=IRequest) + result = view(None, request) + self._assertBody(result, '{}') def test_set_view_mapper(self): from pyramid.interfaces import IViewMapperFactory @@ -2228,12 +2275,12 @@ class TestViewDeriver(unittest.TestCase): def tearDown(self): self.config = None - + def _makeOne(self, **kw): kw['registry'] = self.config.registry from pyramid.config.views import ViewDeriver return ViewDeriver(**kw) - + def _makeRequest(self): request = DummyRequest() request.registry = self.config.registry @@ -2262,7 +2309,7 @@ class TestViewDeriver(unittest.TestCase): result(None, None) except ValueError as e: self.assertEqual( - e.args[0], + e.args[0], 'Could not convert return value of the view callable function ' 'pyramid.tests.test_config.test_views.view into a response ' 'object. The value returned was None. You may have forgotten ' @@ -2281,7 +2328,7 @@ class TestViewDeriver(unittest.TestCase): result(None, None) except ValueError as e: self.assertEqual( - e.args[0], + e.args[0], "Could not convert return value of the view callable function " "pyramid.tests.test_config.test_views.view into a response " "object. The value returned was {'a': 1}. You may have " @@ -2289,7 +2336,7 @@ class TestViewDeriver(unittest.TestCase): ) else: # pragma: no cover raise AssertionError - + def test_instance_returns_non_adaptable(self): class AView(object): def __call__(self, request): @@ -2348,7 +2395,7 @@ class TestViewDeriver(unittest.TestCase): result(None, request) except ValueError as e: self.assertEqual( - e.args[0], + e.args[0], 'Could not convert return value of the view callable ' 'method __call__ of ' 'class pyramid.tests.test_config.test_views.AView into a ' @@ -2372,7 +2419,7 @@ class TestViewDeriver(unittest.TestCase): result(None, request) except ValueError as e: self.assertEqual( - e.args[0], + e.args[0], 'Could not convert return value of the view callable ' 'method theviewmethod of ' 'class pyramid.tests.test_config.test_views.AView into a ' @@ -2381,7 +2428,7 @@ class TestViewDeriver(unittest.TestCase): ) else: # pragma: no cover raise AssertionError - + def test_requestonly_function(self): response = DummyResponse() def view(request): @@ -2415,7 +2462,7 @@ class TestViewDeriver(unittest.TestCase): self.assertEqual(value, 'OK') self.assertEqual(system['request'], request) self.assertEqual(system['context'], context) - return 'moo' + return b'moo' return inner def view(request): return 'OK' @@ -2932,7 +2979,7 @@ class TestViewDeriver(unittest.TestCase): 'predicate mismatch for view myview (pred2)') else: # pragma: no cover raise AssertionError - + def test_with_predicates_all(self): response = DummyResponse() view = lambda *arg: response @@ -3243,7 +3290,7 @@ class TestViewDeriver(unittest.TestCase): expires = parse_httpdate(headers['Expires']) assert_similar_datetime(expires, when) self.assertEqual(headers['Cache-Control'], 'max-age=3600') - + def test_http_cached_view_timedelta(self): import datetime from pyramid.response import Response @@ -3339,7 +3386,7 @@ class TestViewDeriver(unittest.TestCase): class TestDefaultViewMapper(unittest.TestCase): def setUp(self): self.config = testing.setUp() - self.registry = self.config.registry + self.registry = self.config.registry def tearDown(self): del self.registry @@ -3601,7 +3648,7 @@ class TestStaticURLInfo(unittest.TestCase): def _getTargetClass(self): from pyramid.config.views import StaticURLInfo return StaticURLInfo - + def _makeOne(self): return self._getTargetClass()() @@ -3773,27 +3820,13 @@ class TestStaticURLInfo(unittest.TestCase): permission='abc') self.assertEqual(config.view_kw['permission'], 'abc') - def test_add_viewname_with_view_permission(self): - config = self._makeConfig() - inst = self._makeOne() - inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1, - view_permission='abc') - self.assertEqual(config.view_kw['permission'], 'abc') - - def test_add_viewname_with_view_context(self): - config = self._makeConfig() - inst = self._makeOne() - inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1, - view_context=DummyContext) - self.assertEqual(config.view_kw['context'], DummyContext) - - def test_add_viewname_with_view_for(self): + def test_add_viewname_with_context(self): config = self._makeConfig() inst = self._makeOne() inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1, - view_for=DummyContext) + context=DummyContext) self.assertEqual(config.view_kw['context'], DummyContext) - + def test_add_viewname_with_for_(self): config = self._makeConfig() inst = self._makeOne() @@ -3801,14 +3834,6 @@ class TestStaticURLInfo(unittest.TestCase): for_=DummyContext) self.assertEqual(config.view_kw['context'], DummyContext) - def test_add_viewname_with_view_renderer(self): - config = self._makeConfig() - inst = self._makeOne() - inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1, - view_renderer='mypackage:templates/index.pt') - self.assertEqual(config.view_kw['renderer'], - 'mypackage:templates/index.pt') - def test_add_viewname_with_renderer(self): config = self._makeConfig() inst = self._makeOne() @@ -3817,53 +3842,50 @@ class TestStaticURLInfo(unittest.TestCase): self.assertEqual(config.view_kw['renderer'], 'mypackage:templates/index.pt') - def test_add_viewname_with_view_attr(self): - config = self._makeConfig() - inst = self._makeOne() - inst.add(config, 'view', 'anotherpackage:path', cache_max_age=1, - view_attr='attr') - self.assertEqual(config.view_kw['attr'], 'attr') - class Test_view_description(unittest.TestCase): def _callFUT(self, view): from pyramid.config.views import view_description return view_description(view) - + def test_with_text(self): def view(): pass view.__text__ = 'some text' result = self._callFUT(view) self.assertEqual(result, 'some text') - + def test_without_text(self): def view(): pass result = self._callFUT(view) - self.assertEqual(result, + self.assertEqual(result, 'function pyramid.tests.test_config.test_views.view') - + class DummyRegistry: pass +from zope.interface import implementer +from pyramid.interfaces import IResponse +@implementer(IResponse) +class DummyResponse(object): + content_type = None + default_content_type = None + body = None + class DummyRequest: subpath = () matchdict = None + def __init__(self, environ=None): if environ is None: environ = {} self.environ = environ self.params = {} self.cookies = {} + self.response = DummyResponse() class DummyContext: pass -from zope.interface import implementer -from pyramid.interfaces import IResponse -@implementer(IResponse) -class DummyResponse(object): - pass - class DummyAccept(object): def __init__(self, *matches): self.matches = list(matches) @@ -3963,3 +3985,14 @@ class DummyPredicate(object): phash = text +class DummyIntrospector(object): + def __init__(self, getval=None): + self.related = [] + self.introspectables = [] + self.getval = getval + def add(self, introspectable): + self.introspectables.append(introspectable) + def get(self, name, discrim): + return self.getval + def relate(self, a, b): + self.related.append((a, b)) diff --git a/pyramid/tests/test_encode.py b/pyramid/tests/test_encode.py index 736ecb5b3..908249877 100644 --- a/pyramid/tests/test_encode.py +++ b/pyramid/tests/test_encode.py @@ -41,6 +41,18 @@ class UrlEncodeTests(unittest.TestCase): result = self._callFUT({'a':1}) self.assertEqual(result, 'a=1') + def test_None_value(self): + result = self._callFUT([('a', None)]) + self.assertEqual(result, 'a=') + + def test_None_value_with_prefix(self): + result = self._callFUT([('a', '1'), ('b', None)]) + self.assertEqual(result, 'a=1&b=') + + def test_None_value_with_prefix_values(self): + result = self._callFUT([('a', '1'), ('b', None), ('c', None)]) + self.assertEqual(result, 'a=1&b=&c=') + class URLQuoteTests(unittest.TestCase): def _callFUT(self, val, safe=''): from pyramid.encode import url_quote diff --git a/pyramid/tests/test_httpexceptions.py b/pyramid/tests/test_httpexceptions.py index 0061907ba..d0779e080 100644 --- a/pyramid/tests/test_httpexceptions.py +++ b/pyramid/tests/test_httpexceptions.py @@ -57,10 +57,10 @@ class Test__no_escape(unittest.TestCase): duo = DummyUnicodeObject() self.assertEqual(self._callFUT(duo), text_('42')) -class TestWSGIHTTPException(unittest.TestCase): +class TestHTTPException(unittest.TestCase): def _getTargetClass(self): - from pyramid.httpexceptions import WSGIHTTPException - return WSGIHTTPException + from pyramid.httpexceptions import HTTPException + return HTTPException def _getTargetSubclass(self, code='200', title='OK', explanation='explanation', empty_body=False): diff --git a/pyramid/tests/test_i18n.py b/pyramid/tests/test_i18n.py index bd4998b10..67b2ac356 100644 --- a/pyramid/tests/test_i18n.py +++ b/pyramid/tests/test_i18n.py @@ -6,7 +6,7 @@ here = os.path.dirname(__file__) localedir = os.path.join(here, 'pkgs', 'localeapp', 'locale') import unittest -from pyramid.testing import cleanUp +from pyramid import testing class TestTranslationString(unittest.TestCase): def _makeOne(self, *arg, **kw): @@ -84,10 +84,10 @@ class TestLocalizer(unittest.TestCase): class Test_negotiate_locale_name(unittest.TestCase): def setUp(self): - cleanUp() + testing.setUp() def tearDown(self): - cleanUp() + testing.tearDown() def _callFUT(self, request): from pyramid.i18n import negotiate_locale_name @@ -140,40 +140,27 @@ class Test_negotiate_locale_name(unittest.TestCase): class Test_get_locale_name(unittest.TestCase): def setUp(self): - cleanUp() + testing.setUp() def tearDown(self): - cleanUp() + testing.tearDown() def _callFUT(self, request): from pyramid.i18n import get_locale_name return get_locale_name(request) - def _registerImpl(self, impl): - from pyramid.threadlocal import get_current_registry - registry = get_current_registry() - from pyramid.interfaces import ILocaleNegotiator - registry.registerUtility(impl, ILocaleNegotiator) - def test_name_on_request(self): request = DummyRequest() request.locale_name = 'ie' result = self._callFUT(request) self.assertEqual(result, 'ie') - def test_name_not_on_request(self): - self._registerImpl(dummy_negotiator) - request = DummyRequest() - result = self._callFUT(request) - self.assertEqual(result, 'bogus') - self.assertEqual(request.locale_name, 'bogus') - class Test_make_localizer(unittest.TestCase): def setUp(self): - cleanUp() + testing.setUp() def tearDown(self): - cleanUp() + testing.tearDown() def _callFUT(self, locale, tdirs): from pyramid.i18n import make_localizer @@ -221,83 +208,26 @@ class Test_make_localizer(unittest.TestCase): class Test_get_localizer(unittest.TestCase): def setUp(self): - cleanUp() + testing.setUp() def tearDown(self): - cleanUp() + testing.tearDown() def _callFUT(self, request): from pyramid.i18n import get_localizer return get_localizer(request) - def test_no_registry_on_request(self): - request = DummyRequest() - request.localizer = '123' - result = self._callFUT(request) - self.assertEqual(result, '123') - - def test_with_registry_on_request(self): - from pyramid.threadlocal import get_current_registry - registry = get_current_registry() - request = DummyRequest() - request.localizer = '123' - request.registry = registry - result = self._callFUT(request) - self.assertEqual(result, '123') - - def test_locale_on_request(self): - request = DummyRequest() - request.localizer = 'abc' - result = self._callFUT(request) - self.assertEqual(result, 'abc') - - def test_locale_from_registry(self): - from pyramid.threadlocal import get_current_registry - from pyramid.interfaces import ILocalizer - registry = get_current_registry() - locale = 'abc' - registry.registerUtility(locale, ILocalizer, name='en') - request = DummyRequest() - request.locale_name = 'en' - result = self._callFUT(request) - self.assertEqual(result, 'abc') - - def test_locale_from_mo(self): - from pyramid.threadlocal import get_current_registry - from pyramid.interfaces import ITranslationDirectories - from pyramid.i18n import Localizer - registry = get_current_registry() - localedirs = [localedir] - registry.registerUtility(localedirs, ITranslationDirectories) - request = DummyRequest() - request.locale_name = 'de' - result = self._callFUT(request) - self.assertEqual(result.__class__, Localizer) - self.assertEqual(result.translate('Approve', 'deformsite'), - 'Genehmigen') - self.assertEqual(result.translate('Approve'), 'Approve') - self.assertTrue(hasattr(result, 'pluralize')) - - def test_locale_from_mo_bad_mo(self): - from pyramid.threadlocal import get_current_registry - from pyramid.interfaces import ITranslationDirectories - from pyramid.i18n import Localizer - registry = get_current_registry() - localedirs = [localedir] - registry.registerUtility(localedirs, ITranslationDirectories) + def test_it(self): request = DummyRequest() - request.locale_name = 'be' - result = self._callFUT(request) - self.assertEqual(result.__class__, Localizer) - self.assertEqual(result.translate('Approve', 'deformsite'), - 'Approve') + request.localizer = 'localizer' + self.assertEqual(self._callFUT(request), 'localizer') class Test_default_locale_negotiator(unittest.TestCase): def setUp(self): - cleanUp() + testing.setUp() def tearDown(self): - cleanUp() + testing.tearDown() def _callFUT(self, request): from pyramid.i18n import default_locale_negotiator @@ -463,6 +393,70 @@ class TestTranslations(unittest.TestCase): result = t.dungettext('messages', 'foo1', 'foos1', 2) self.assertEqual(result, 'foos1') +class TestLocalizerRequestMixin(unittest.TestCase): + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def _makeOne(self): + from pyramid.i18n import LocalizerRequestMixin + request = LocalizerRequestMixin() + request.registry = self.config.registry + request.cookies = {} + request.params = {} + return request + + def test_default_localizer(self): + # `localizer` returns a default localizer for `en` + from pyramid.i18n import Localizer + request = self._makeOne() + self.assertEqual(request.localizer.__class__, Localizer) + self.assertEqual(request.locale_name, 'en') + + def test_custom_localizer_for_default_locale(self): + from pyramid.interfaces import ILocalizer + dummy = object() + self.config.registry.registerUtility(dummy, ILocalizer, name='en') + request = self._makeOne() + self.assertEqual(request.localizer, dummy) + + def test_custom_localizer_for_custom_locale(self): + from pyramid.interfaces import ILocalizer + dummy = object() + self.config.registry.registerUtility(dummy, ILocalizer, name='ie') + request = self._makeOne() + request._LOCALE_ = 'ie' + self.assertEqual(request.localizer, dummy) + + def test_localizer_from_mo(self): + from pyramid.interfaces import ITranslationDirectories + from pyramid.i18n import Localizer + localedirs = [localedir] + self.config.registry.registerUtility( + localedirs, ITranslationDirectories) + request = self._makeOne() + request._LOCALE_ = 'de' + result = request.localizer + self.assertEqual(result.__class__, Localizer) + self.assertEqual(result.translate('Approve', 'deformsite'), + 'Genehmigen') + self.assertEqual(result.translate('Approve'), 'Approve') + self.assertTrue(hasattr(result, 'pluralize')) + + def test_localizer_from_mo_bad_mo(self): + from pyramid.interfaces import ITranslationDirectories + from pyramid.i18n import Localizer + localedirs = [localedir] + self.config.registry.registerUtility( + localedirs, ITranslationDirectories) + request = self._makeOne() + request._LOCALE_ = 'be' + result = request.localizer + self.assertEqual(result.__class__, Localizer) + self.assertEqual(result.translate('Approve', 'deformsite'), + 'Approve') class DummyRequest(object): def __init__(self): diff --git a/pyramid/tests/test_integration.py b/pyramid/tests/test_integration.py index c8418c61d..9d3a9e004 100644 --- a/pyramid/tests/test_integration.py +++ b/pyramid/tests/test_integration.py @@ -72,10 +72,10 @@ class IntegrationBase(object): here = os.path.dirname(__file__) -class TestStaticAppBase(IntegrationBase): +class StaticAppBase(IntegrationBase): def test_basic(self): - res = self.testapp.get('/minimal.pt', status=200) - _assertBody(res.body, os.path.join(here, 'fixtures/minimal.pt')) + res = self.testapp.get('/minimal.txt', status=200) + _assertBody(res.body, os.path.join(here, 'fixtures/minimal.txt')) def test_hidden(self): res = self.testapp.get('/static/.hiddenfile', status=200) @@ -119,7 +119,7 @@ class TestStaticAppBase(IntegrationBase): def test_not_modified(self): self.testapp.extra_environ = { 'HTTP_IF_MODIFIED_SINCE':httpdate(fiveyrsfuture)} - res = self.testapp.get('/minimal.pt', status=304) + res = self.testapp.get('/minimal.txt', status=304) self.assertEqual(res.body, b'') def test_file_in_subdir(self): @@ -198,10 +198,10 @@ class TestEventOnlySubscribers(IntegrationBase, unittest.TestCase): self.assertEqual(sorted(res.body.split()), [b'foobar', b'foobar2', b'foobaryup', b'foobaryup2']) -class TestStaticAppUsingAbsPath(TestStaticAppBase, unittest.TestCase): +class TestStaticAppUsingAbsPath(StaticAppBase, unittest.TestCase): package = 'pyramid.tests.pkgs.static_abspath' -class TestStaticAppUsingAssetSpec(TestStaticAppBase, unittest.TestCase): +class TestStaticAppUsingAssetSpec(StaticAppBase, unittest.TestCase): package = 'pyramid.tests.pkgs.static_assetspec' class TestStaticAppNoSubpath(unittest.TestCase): @@ -222,19 +222,19 @@ class TestStaticAppNoSubpath(unittest.TestCase): return request def test_basic(self): - request = self._makeRequest({'PATH_INFO':'/minimal.pt'}) + request = self._makeRequest({'PATH_INFO':'/minimal.txt'}) context = DummyContext() result = self.staticapp(context, request) self.assertEqual(result.status, '200 OK') - _assertBody(result.body, os.path.join(here, 'fixtures/minimal.pt')) + _assertBody(result.body, os.path.join(here, 'fixtures/minimal.txt')) class TestStaticAppWithRoutePrefix(IntegrationBase, unittest.TestCase): package = 'pyramid.tests.pkgs.static_routeprefix' def test_includelevel1(self): - res = self.testapp.get('/static/minimal.pt', status=200) + res = self.testapp.get('/static/minimal.txt', status=200) _assertBody(res.body, - os.path.join(here, 'fixtures/minimal.pt')) + os.path.join(here, 'fixtures/minimal.txt')) def test_includelevel2(self): res = self.testapp.get('/prefix/static/index.html', status=200) @@ -369,22 +369,12 @@ class TestForbiddenAppHasResult(IntegrationBase, unittest.TestCase): class TestViewDecoratorApp(IntegrationBase, unittest.TestCase): package = 'pyramid.tests.pkgs.viewdecoratorapp' - def _configure_mako(self): - tmpldir = os.path.join(os.path.dirname(__file__), - 'pkgs', - 'viewdecoratorapp', - 'views') - self.config.registry.settings['mako.directories'] = tmpldir def test_first(self): - # we use mako here instead of chameleon because it works on Jython - self._configure_mako() res = self.testapp.get('/first', status=200) self.assertTrue(b'OK' in res.body) def test_second(self): - # we use mako here instead of chameleon because it works on Jython - self._configure_mako() res = self.testapp.get('/second', status=200) self.assertTrue(b'OK2' in res.body) @@ -475,6 +465,10 @@ class TestExceptionViewsApp(IntegrationBase, unittest.TestCase): res = self.testapp.get('/route_raise_exception4', status=200) self.assertTrue(b'whoa' in res.body) + def test_raise_httpexception(self): + res = self.testapp.get('/route_raise_httpexception', status=200) + self.assertTrue(b'caught' in res.body) + class TestConflictApp(unittest.TestCase): package = 'pyramid.tests.pkgs.conflictapp' def _makeConfig(self): @@ -659,6 +653,10 @@ class AcceptContentTypeTest(unittest.TestCase): from webtest import TestApp self.testapp = TestApp(app) + def tearDown(self): + import pyramid.config + pyramid.config.global_registries.empty() + def test_ordering(self): res = self.testapp.get('/hello', headers={'Accept': 'application/json; q=1.0, text/plain; q=0.9'}, status=200) self.assertEqual(res.content_type, 'application/json') diff --git a/pyramid/tests/test_mako_templating.py b/pyramid/tests/test_mako_templating.py deleted file mode 100644 index 50ef360d9..000000000 --- a/pyramid/tests/test_mako_templating.py +++ /dev/null @@ -1,612 +0,0 @@ -## come on python gimme some of that sweet, sweet -*- coding: utf-8 -*- - -import shutil -import tempfile -import unittest - -from pyramid import testing - -from pyramid.compat import ( - text_, - text_type, - ) - -class Base(object): - def setUp(self): - self.config = testing.setUp() - self.config.begin() - import os - here = os.path.abspath(os.path.dirname(__file__)) - self.templates_dir = os.path.join(here, 'fixtures') - - def tearDown(self): - self.config.end() - -class Test_renderer_factory(Base, unittest.TestCase): - def _callFUT(self, info): - from pyramid.mako_templating import renderer_factory - return renderer_factory(info) - - def _getLookup(self, name='mako.'): - from pyramid.mako_templating import IMakoLookup - return self.config.registry.getUtility(IMakoLookup, name=name) - - def test_hyphen_filenames(self): - from pyramid.mako_templating import renderer_factory - - info = DummyRendererInfo({ - 'name':'app:moon-and-world.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type': '' - }) - - result = renderer_factory(info) - self.assertEqual(result.path, 'app:moon-and-world.mak') - - def test_no_directories(self): - info = DummyRendererInfo({ - 'name':'pyramid.tests:fixtures/helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - }) - renderer = self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.directories, []) - self.assertEqual(lookup.filesystem_checks, False) - self.assertEqual(renderer.path, - 'pyramid.tests:fixtures/helloworld.mak') - self.assertEqual(renderer.lookup, lookup) - - def test_no_lookup(self): - settings = {'mako.directories':self.templates_dir} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - renderer = self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.directories, [self.templates_dir]) - self.assertEqual(lookup.filesystem_checks, False) - self.assertEqual(renderer.path, 'helloworld.mak') - self.assertEqual(renderer.lookup, lookup) - - def test_composite_directories_path(self): - twice = '\n' + self.templates_dir + '\n' + self.templates_dir + '\n' - settings = {'mako.directories':twice} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.directories, [self.templates_dir]*2) - - def test_directories_list(self): - import sys - import os.path - settings = {'mako.directories':['a', 'b']} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - module_path = os.path.dirname( - sys.modules['__main__'].__file__).rstrip('.') # ./setup.py - self.assertEqual(lookup.directories, [ - os.path.join(module_path, 'a'), - os.path.join(module_path, 'b')]) - - def test_with_module_directory_asset_spec(self): - import os - module_directory = 'pyramid.tests:fixtures' - settings = {'mako.directories':self.templates_dir, - 'mako.module_directory':module_directory} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - fixtures = os.path.join(os.path.dirname(__file__), 'fixtures') - self.assertEqual(lookup.module_directory, fixtures) - - def test_with_module_directory_asset_abspath(self): - import os - fixtures = os.path.join(os.path.dirname(__file__), 'fixtures') - settings = {'mako.directories':self.templates_dir, - 'mako.module_directory':fixtures} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.module_directory, fixtures) - - def test_with_input_encoding(self): - settings = {'mako.directories':self.templates_dir, - 'mako.input_encoding':'utf-16'} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['input_encoding'], 'utf-16') - - def test_with_error_handler(self): - settings = {'mako.directories':self.templates_dir, - 'mako.error_handler':'pyramid.tests'} - import pyramid.tests - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['error_handler'], pyramid.tests) - - def test_with_preprocessor(self): - settings = {'mako.directories':self.templates_dir, - 'mako.preprocessor':'pyramid.tests'} - import pyramid.tests - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['preprocessor'], pyramid.tests) - - def test_with_default_filters(self): - settings = {'mako.directories':self.templates_dir, - 'mako.default_filters':'\nh\ng\n\n'} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['default_filters'], ['h', 'g']) - - def test_with_default_filters_list(self): - settings = {'mako.directories':self.templates_dir, - 'mako.default_filters':['h', 'g']} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['default_filters'], ['h', 'g']) - - def test_with_imports(self): - settings = {'mako.directories':self.templates_dir, - 'mako.imports':'\none\ntwo\n\n'} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['imports'], ['one', 'two']) - - def test_with_imports_list(self): - settings = {'mako.directories':self.templates_dir, - 'mako.imports':['one', 'two']} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['imports'], ['one', 'two']) - - def test_with_strict_undefined_true(self): - settings = {'mako.directories':self.templates_dir, - 'mako.strict_undefined':'true'} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['strict_undefined'], True) - - def test_with_strict_undefined_false(self): - settings = {'mako.directories':self.templates_dir, - 'mako.strict_undefined':'false'} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - }) - self._callFUT(info) - lookup = self._getLookup() - self.assertEqual(lookup.template_args['strict_undefined'], False) - - def test_with_lookup(self): - from pyramid.mako_templating import IMakoLookup - lookup = dict() - self.config.registry.registerUtility(lookup, IMakoLookup, name='mako.') - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - }) - renderer = self._callFUT(info) - self.assertEqual(renderer.lookup, lookup) - self.assertEqual(renderer.path, 'helloworld.mak') - - def test_space_dot_name(self): - from pyramid.mako_templating import renderer_factory - - info = DummyRendererInfo({ - 'name':'hello .world.mako', - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - }) - - result = renderer_factory(info) - self.assertEqual(result.path, 'hello .world.mako') - self.assertTrue(result.defname is None) - - def test_space_dot_name_def(self): - from pyramid.mako_templating import renderer_factory - - info = DummyRendererInfo({ - 'name':'hello .world#comp.mako', - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - }) - - result = renderer_factory(info) - self.assertEqual(result.path, 'hello .world.mako') - self.assertEqual(result.defname, 'comp') - -class MakoRendererFactoryHelperTests(Base, unittest.TestCase): - def _getTargetClass(self): - from pyramid.mako_templating import MakoRendererFactoryHelper - return MakoRendererFactoryHelper - - def _makeOne(self, *arg, **kw): - klass = self._getTargetClass() - return klass(*arg, **kw) - - def _getLookup(self, name='mako.'): - from pyramid.mako_templating import IMakoLookup - return self.config.registry.getUtility(IMakoLookup, name=name) - - def test_no_settings_prefix(self): - settings = {'foo.directories':self.templates_dir} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - 'type':'foo', - }) - helper = self._makeOne() - renderer = helper(info) - lookup = self._getLookup('foo.') - self.assertEqual(lookup.directories, [self.templates_dir]) - self.assertEqual(lookup.filesystem_checks, False) - self.assertEqual(renderer.path, 'helloworld.mak') - self.assertEqual(renderer.lookup, lookup) - - def test_custom_settings_prefix(self): - settings = {'bar.directories':self.templates_dir} - info = DummyRendererInfo({ - 'name':'helloworld.mak', - 'package':None, - 'registry':self.config.registry, - 'settings':settings, - 'type':'foo', - }) - helper = self._makeOne('bar.') - renderer = helper(info) - lookup = self._getLookup('bar.') - self.assertEqual(lookup.directories, [self.templates_dir]) - self.assertEqual(lookup.filesystem_checks, False) - self.assertEqual(renderer.path, 'helloworld.mak') - self.assertEqual(renderer.lookup, lookup) - -class MakoLookupTemplateRendererTests(Base, unittest.TestCase): - def _getTargetClass(self): - from pyramid.mako_templating import MakoLookupTemplateRenderer - return MakoLookupTemplateRenderer - - def _makeOne(self, *arg, **kw): - klass = self._getTargetClass() - return klass(*arg, **kw) - - def test_instance_implements_ITemplate(self): - from zope.interface.verify import verifyObject - from pyramid.interfaces import ITemplateRenderer - verifyObject(ITemplateRenderer, self._makeOne(None, None, None)) - - def test_class_implements_ITemplate(self): - from zope.interface.verify import verifyClass - from pyramid.interfaces import ITemplateRenderer - verifyClass(ITemplateRenderer, self._getTargetClass()) - - def test_call(self): - lookup = DummyLookup() - instance = self._makeOne('path', None, lookup) - result = instance({}, {'system':1}) - self.assertTrue(isinstance(result, text_type)) - self.assertEqual(result, text_('result')) - - def test_call_with_system_context(self): - # lame - lookup = DummyLookup() - instance = self._makeOne('path', None, lookup) - result = instance({}, {'context':1}) - self.assertTrue(isinstance(result, text_type)) - self.assertEqual(result, text_('result')) - self.assertEqual(lookup.values, {'_context':1}) - - def test_call_with_tuple_value(self): - lookup = DummyLookup() - instance = self._makeOne('path', None, lookup) - result = instance(('fub', {}), {'context':1}) - self.assertEqual(lookup.deffed, 'fub') - self.assertEqual(result, text_('result')) - self.assertEqual(lookup.values, {'_context':1}) - - def test_call_with_defname(self): - lookup = DummyLookup() - instance = self._makeOne('path', 'defname', lookup) - result = instance({}, {'system':1}) - self.assertTrue(isinstance(result, text_type)) - self.assertEqual(result, text_('result')) - - def test_call_with_defname_with_tuple_value(self): - lookup = DummyLookup() - instance = self._makeOne('path', 'defname', lookup) - result = instance(('defname', {}), {'context':1}) - self.assertEqual(lookup.deffed, 'defname') - self.assertEqual(result, text_('result')) - self.assertEqual(lookup.values, {'_context':1}) - - def test_call_with_nondict_value(self): - lookup = DummyLookup() - instance = self._makeOne('path', None, lookup) - self.assertRaises(ValueError, instance, None, {}) - - def test_call_render_raises(self): - from pyramid.mako_templating import MakoRenderingException - lookup = DummyLookup(exc=NotImplementedError) - instance = self._makeOne('path', None, lookup) - try: - instance({}, {}) - except MakoRenderingException as e: - self.assertTrue('NotImplementedError' in e.text) - else: # pragma: no cover - raise AssertionError - - def test_implementation(self): - lookup = DummyLookup() - instance = self._makeOne('path', None, lookup) - result = instance.implementation().render_unicode() - self.assertTrue(isinstance(result, text_type)) - self.assertEqual(result, text_('result')) - -class TestIntegration(unittest.TestCase): - def setUp(self): - import pyramid.mako_templating - self.config = testing.setUp() - self.config.add_settings({'mako.directories': - 'pyramid.tests:fixtures'}) - self.config.add_renderer('.mak', - pyramid.mako_templating.renderer_factory) - - def tearDown(self): - self.config.end() - - def test_render(self): - from pyramid.renderers import render - result = render('helloworld.mak', {'a':1}).replace('\r','') - self.assertEqual(result, text_('\nHello föö\n', 'utf-8')) - - def test_render_from_fs(self): - from pyramid.renderers import render - self.config.add_settings({'reload_templates': True}) - result = render('helloworld.mak', {'a':1}).replace('\r','') - self.assertEqual(result, text_('\nHello föö\n', 'utf-8')) - - def test_render_inheritance(self): - from pyramid.renderers import render - result = render('helloinherit.mak', {}).replace('\r','') - self.assertEqual(result, text_('Layout\nHello World!\n')) - - def test_render_inheritance_pkg_spec(self): - from pyramid.renderers import render - result = render('hello_inherit_pkg.mak', {}).replace('\r','') - self.assertEqual(result, text_('Layout\nHello World!\n')) - - def test_render_namespace(self): - from pyramid.renderers import render - result = render('hellocompo.mak', {}).replace('\r','') - self.assertEqual(result, text_('\nNamespace\nHello \nWorld!\n')) - - def test_render_to_response(self): - from pyramid.renderers import render_to_response - result = render_to_response('helloworld.mak', {'a':1}) - self.assertEqual(result.ubody.replace('\r',''), - text_('\nHello föö\n', 'utf-8')) - - def test_render_to_response_pkg_spec(self): - from pyramid.renderers import render_to_response - result = render_to_response('pyramid.tests:fixtures/helloworld.mak', - {'a':1}) - self.assertEqual(result.ubody.replace('\r', ''), - text_('\nHello föö\n', 'utf-8')) - - def test_render_with_abs_path(self): - from pyramid.renderers import render - result = render('/helloworld.mak', {'a':1}).replace('\r','') - self.assertEqual(result, text_('\nHello föö\n', 'utf-8')) - - def test_get_renderer(self): - from pyramid.renderers import get_renderer - result = get_renderer('helloworld.mak') - self.assertEqual( - result.implementation().render_unicode().replace('\r',''), - text_('\nHello föö\n', 'utf-8')) - - def test_template_not_found(self): - from pyramid.renderers import render - from mako.exceptions import TemplateLookupException - self.assertRaises(TemplateLookupException, render, - 'helloworld_not_here.mak', {}) - - def test_template_default_escaping(self): - from pyramid.renderers import render - result = render('nonminimal.mak', - {'name':'<b>fred</b>'}).replace('\r','') - self.assertEqual(result, text_('Hello, <b>fred</b>!\n')) - -class TestPkgResourceTemplateLookup(unittest.TestCase): - def _makeOne(self, **kw): - from pyramid.mako_templating import PkgResourceTemplateLookup - return PkgResourceTemplateLookup(**kw) - - def get_fixturedir(self): - import os - import pyramid.tests - return os.path.join(os.path.dirname(pyramid.tests.__file__), 'fixtures') - - def test_adjust_uri_not_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('a', None) - self.assertEqual(result, '/a') - - def test_adjust_uri_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('a:b', None) - self.assertEqual(result, 'a:b') - - def test_adjust_uri_asset_spec_with_modified_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('a$b', None) - self.assertEqual(result, 'a:b') - - def test_adjust_uri_not_asset_spec_with_relativeto_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('c', 'a:b') - self.assertEqual(result, 'a:c') - - def test_adjust_uri_not_asset_spec_with_relativeto_modified_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('c', 'a$b') - self.assertEqual(result, 'a:c') - - def test_adjust_uri_not_asset_spec_with_relativeto_not_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('b', '../a') - self.assertEqual(result, '../b') - - def test_adjust_uri_not_asset_spec_abs_with_relativeto_asset_spec(self): - inst = self._makeOne() - result = inst.adjust_uri('/c', 'a:b') - self.assertEqual(result, '/c') - - def test_adjust_uri_asset_spec_with_relativeto_not_asset_spec_abs(self): - inst = self._makeOne() - result = inst.adjust_uri('a:b', '/c') - self.assertEqual(result, 'a:b') - - def test_get_template_not_asset_spec(self): - fixturedir = self.get_fixturedir() - inst = self._makeOne(directories=[fixturedir]) - result = inst.get_template('helloworld.mak') - self.assertFalse(result is None) - - def test_get_template_asset_spec_with_filesystem_checks(self): - inst = self._makeOne(filesystem_checks=True) - result = inst.get_template('pyramid.tests:fixtures/helloworld.mak') - self.assertFalse(result is None) - - def test_get_template_asset_spec_with_module_dir(self): - tmpdir = tempfile.mkdtemp() - try: - inst = self._makeOne(module_directory=tmpdir) - result = inst.get_template('pyramid.tests:fixtures/helloworld.mak') - self.assertFalse(result is None) - finally: - shutil.rmtree(tmpdir, ignore_errors=True) - - def test_get_template_asset_spec_missing(self): - from mako.exceptions import TopLevelLookupException - fixturedir = self.get_fixturedir() - inst = self._makeOne(filesystem_checks=True, directories=[fixturedir]) - self.assertRaises(TopLevelLookupException, inst.get_template, - 'pyramid.tests:fixtures/notthere.mak') - -class TestMakoRenderingException(unittest.TestCase): - def _makeOne(self, text): - from pyramid.mako_templating import MakoRenderingException - return MakoRenderingException(text) - - def test_repr_and_str(self): - exc = self._makeOne('text') - self.assertEqual(str(exc), 'text') - self.assertEqual(repr(exc), 'text') - -class DummyLookup(object): - def __init__(self, exc=None): - self.exc = exc - - def get_template(self, path): - self.path = path - return self - - def get_def(self, path): - self.deffed = path - return self - - def render_unicode(self, **values): - if self.exc: - raise self.exc - self.values = values - return text_('result') - -class DummyRendererInfo(object): - def __init__(self, kw): - self.__dict__.update(kw) - diff --git a/pyramid/tests/test_path.py b/pyramid/tests/test_path.py index a07ebeffa..fd927996a 100644 --- a/pyramid/tests/test_path.py +++ b/pyramid/tests/test_path.py @@ -154,6 +154,12 @@ class TestPackageName(unittest.TestCase): package = DummyPackageOrModule(tests) result = self._callFUT(package) self.assertEqual(result, 'pyramid.tests') + + def test_it_namespace_package(self): + from pyramid import tests + package = DummyNamespacePackage(tests) + result = self._callFUT(package) + self.assertEqual(result, 'pyramid.tests') def test_it_module(self): from pyramid.tests import test_path @@ -558,3 +564,13 @@ class DummyPackageOrModule: if self.raise_exc is not None: raise self.raise_exc self.__dict__[key] = val + +class DummyNamespacePackage: + """Has no __file__ attribute. + """ + + def __init__(self, real_package_or_module): + self.__name__ = real_package_or_module.__name__ + import os + self.package_path = os.path.dirname( + os.path.abspath(real_package_or_module.__file__)) diff --git a/pyramid/tests/test_renderers.py b/pyramid/tests/test_renderers.py index befb714bd..f6b9d2b0d 100644 --- a/pyramid/tests/test_renderers.py +++ b/pyramid/tests/test_renderers.py @@ -4,372 +4,6 @@ from pyramid.testing import cleanUp from pyramid import testing from pyramid.compat import text_ -class TestTemplateRendererFactory(unittest.TestCase): - def setUp(self): - self.config = cleanUp() - - def tearDown(self): - cleanUp() - - def _callFUT(self, info, impl): - from pyramid.renderers import template_renderer_factory - return template_renderer_factory(info, impl) - - def test_lookup_found(self): - from pyramid.interfaces import IChameleonLookup - L = [] - def dummy(info): - L.append(info) - return True - self.config.registry.registerUtility(dummy, IChameleonLookup, - name='abc') - class DummyInfo(object): - pass - info = DummyInfo() - info.registry = self.config.registry - info.type = 'abc' - result = self._callFUT(info, None) - self.assertEqual(result, True) - self.assertEqual(L, [info]) - - def test_lookup_miss(self): - from pyramid.interfaces import ITemplateRenderer - import os - abspath = os.path.abspath(__file__) - renderer = {} - self.config.registry.registerUtility( - renderer, ITemplateRenderer, name=abspath) - info = DummyRendererInfo({ - 'name':abspath, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - result = self._callFUT(info, None) - self.assertTrue(result is renderer) - -class TestChameleonRendererLookup(unittest.TestCase): - def setUp(self): - self.config = testing.setUp() - - def tearDown(self): - testing.tearDown() - - def _makeOne(self, impl): - from pyramid.renderers import ChameleonRendererLookup - return ChameleonRendererLookup(impl, self.config.registry) - - def _registerTemplateRenderer(self, renderer, name): - from pyramid.interfaces import ITemplateRenderer - self.config.registry.registerUtility( - renderer, ITemplateRenderer, name=name) - - def test_get_spec_not_abspath_no_colon_no_package(self): - lookup = self._makeOne(None) - result = lookup.get_spec('foo', None) - self.assertEqual(result, 'foo') - - def test_get_spec_not_abspath_no_colon_with_package(self): - from pyramid import tests - lookup = self._makeOne(None) - result = lookup.get_spec('foo', tests) - self.assertEqual(result, 'pyramid.tests:foo') - - def test_get_spec_not_abspath_with_colon_no_package(self): - lookup = self._makeOne(None) - result = lookup.get_spec('fudge:foo', None) - self.assertEqual(result, 'fudge:foo') - - def test_get_spec_not_abspath_with_colon_with_package(self): - from pyramid import tests - lookup = self._makeOne(None) - result = lookup.get_spec('fudge:foo', tests) - self.assertEqual(result, 'fudge:foo') - - def test_get_spec_is_abspath_no_colon_no_package(self): - import os - lookup = self._makeOne(None) - spec = os.path.abspath(__file__) - result = lookup.get_spec(spec, None) - self.assertEqual(result, spec) - - def test_get_spec_is_abspath_no_colon_with_path_in_package(self): - from pyramid import tests - import os - lookup = self._makeOne(None) - f = __file__ - spec = os.path.abspath(f) - result = lookup.get_spec(spec, tests) - self.assertEqual(result, 'pyramid.tests:%s' % os.path.split(f)[-1]) - - def test_get_spec_is_abspath_no_colon_with_path_outside_package(self): - import venusian # used only because it's outside of pyramid.tests - import os - lookup = self._makeOne(None) - f = __file__ - spec = os.path.abspath(f) - result = lookup.get_spec(spec, venusian) - self.assertEqual(result, spec) - - def test_get_spec_is_abspath_with_colon_no_package(self): - import os - lookup = self._makeOne(None) - spec = os.path.join(os.path.abspath(__file__), ':foo') - result = lookup.get_spec(spec, None) - self.assertEqual(result, spec) - - def test_get_spec_is_abspath_with_colon_with_path_in_package(self): - from pyramid import tests - import os - lookup = self._makeOne(None) - f = os.path.abspath(__file__) - spec = os.path.join(f, ':foo') - result = lookup.get_spec(spec, tests) - tail = spec.split(os.sep)[-2:] - self.assertEqual(result, 'pyramid.tests:%s/%s' % tuple(tail)) - - def test_get_spec_is_abspath_with_colon_with_path_outside_package(self): - import venusian # used only because it's outside of pyramid.tests - import os - lookup = self._makeOne(None) - spec = os.path.join(os.path.abspath(__file__), ':foo') - result = lookup.get_spec(spec, venusian) - self.assertEqual(result, spec) - - def test_translate(self): - from pyramid.interfaces import IChameleonTranslate - def t(): pass - self.config.registry.registerUtility(t, IChameleonTranslate) - lookup = self._makeOne(None) - self.assertEqual(lookup.translate, t) - - def test_debug_settings_None(self): - self.config.registry.settings = None - lookup = self._makeOne(None) - self.assertEqual(lookup.debug, False) - - def test_debug_settings_not_None(self): - self.config.registry.settings = {'debug_templates':True} - lookup = self._makeOne(None) - self.assertEqual(lookup.debug, True) - - def test_auto_reload_settings_None(self): - self.config.registry.settings = None - lookup = self._makeOne(None) - self.assertEqual(lookup.auto_reload, False) - - def test_auto_reload_settings_not_None(self): - self.config.registry.settings = {'reload_templates':True} - lookup = self._makeOne(None) - self.assertEqual(lookup.auto_reload, True) - - def test___call__abspath_path_notexists(self): - abspath = '/wont/exist' - self._registerTemplateRenderer({}, abspath) - info = DummyRendererInfo({ - 'name':abspath, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(None) - self.assertRaises(ValueError, lookup.__call__, info) - - def test___call__abspath_alreadyregistered(self): - import os - abspath = os.path.abspath(__file__) - renderer = {} - self._registerTemplateRenderer(renderer, abspath) - info = DummyRendererInfo({ - 'name':abspath, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(None) - result = lookup(info) - self.assertTrue(result is renderer) - - def test___call__abspath_notyetregistered(self): - import os - abspath = os.path.abspath(__file__) - renderer = {} - factory = DummyFactory(renderer) - info = DummyRendererInfo({ - 'name':abspath, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(factory) - result = lookup(info) - self.assertEqual(result, renderer) - - def test___call__relpath_path_registered(self): - renderer = {} - spec = 'foo/bar' - self._registerTemplateRenderer(renderer, spec) - info = DummyRendererInfo({ - 'name':spec, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(None) - result = lookup(info) - self.assertTrue(renderer is result) - - def test___call__relpath_has_package_registered(self): - renderer = {} - import pyramid.tests - spec = 'bar/baz' - self._registerTemplateRenderer(renderer, 'pyramid.tests:bar/baz') - info = DummyRendererInfo({ - 'name':spec, - 'package':pyramid.tests, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(None) - result = lookup(info) - self.assertTrue(renderer is result) - - def test___call__spec_notfound(self): - spec = 'pyramid.tests:wont/exist' - info = DummyRendererInfo({ - 'name':spec, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(None) - self.assertRaises(ValueError, lookup.__call__, info) - - def test___call__spec_alreadyregistered(self): - from pyramid import tests - module_name = tests.__name__ - relpath = 'test_renderers.py' - spec = '%s:%s' % (module_name, relpath) - info = DummyRendererInfo({ - 'name':spec, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - renderer = {} - self._registerTemplateRenderer(renderer, spec) - lookup = self._makeOne(None) - result = lookup(info) - self.assertTrue(result is renderer) - - def test___call__spec_notyetregistered(self): - import os - from pyramid import tests - module_name = tests.__name__ - relpath = 'test_renderers.py' - renderer = {} - factory = DummyFactory(renderer) - spec = '%s:%s' % (module_name, relpath) - info = DummyRendererInfo({ - 'name':spec, - 'package':None, - 'registry':self.config.registry, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(factory) - result = lookup(info) - self.assertTrue(result is renderer) - path = os.path.abspath(__file__).split('$')[0] # jython - if path.endswith('.pyc'): # pragma: no cover - path = path[:-1] - self.assertTrue(factory.path.startswith(path)) - self.assertEqual(factory.kw, {'macro':None}) - - def test___call__spec_withmacro(self): - from pyramid.interfaces import ITemplateRenderer - import os - from pyramid import tests - module_name = tests.__name__ - relpath = 'fixtures/withmacro#foo.pt' - renderer = {} - factory = DummyFactory(renderer) - spec = '%s:%s' % (module_name, relpath) - reg = self.config.registry - info = DummyRendererInfo({ - 'name':spec, - 'package':None, - 'registry':reg, - 'settings':{}, - 'type':'type', - }) - lookup = self._makeOne(factory) - result = lookup(info) - self.assertTrue(result is renderer) - path = os.path.join( - os.path.dirname(os.path.abspath(__file__)), - 'fixtures', - 'withmacro.pt') - self.assertTrue(factory.path.startswith(path)) - self.assertEqual(factory.kw, {'macro':'foo'}) - self.assertTrue( - reg.getUtility(ITemplateRenderer, name=spec) is renderer - ) - - def test___call__reload_assets_true(self): - import pyramid.tests - from pyramid.interfaces import ISettings - from pyramid.interfaces import ITemplateRenderer - settings = {'reload_assets':True} - self.config.registry.registerUtility(settings, ISettings) - renderer = {} - factory = DummyFactory(renderer) - spec = 'test_renderers.py' - reg = self.config.registry - info = DummyRendererInfo({ - 'name':spec, - 'package':pyramid.tests, - 'registry':reg, - 'settings':settings, - 'type':'type', - }) - lookup = self._makeOne(factory) - result = lookup(info) - self.assertTrue(result is renderer) - spec = '%s:%s' % ('pyramid.tests', 'test_renderers.py') - self.assertEqual(reg.queryUtility(ITemplateRenderer, name=spec), - None) - - def test___call__reload_assets_false(self): - import pyramid.tests - from pyramid.interfaces import ITemplateRenderer - settings = {'reload_assets':False} - renderer = {} - factory = DummyFactory(renderer) - spec = 'test_renderers.py' - reg = self.config.registry - info = DummyRendererInfo({ - 'name':spec, - 'package':pyramid.tests, - 'registry':reg, - 'settings':settings, - 'type':'type', - }) - lookup = self._makeOne(factory) - result = lookup(info) - self.assertTrue(result is renderer) - spec = '%s:%s' % ('pyramid.tests', 'test_renderers.py') - self.assertNotEqual(reg.queryUtility(ITemplateRenderer, name=spec), - None) - class TestJSON(unittest.TestCase): def setUp(self): self.config = testing.setUp() @@ -470,7 +104,7 @@ class Test_string_renderer_factory(unittest.TestCase): value = text_('La Pe\xc3\xb1a', 'utf-8') result = renderer(value, {}) self.assertEqual(result, value) - + def test_it_str(self): renderer = self._callFUT(None) value = 'La Pe\xc3\xb1a' @@ -621,16 +255,6 @@ class TestRendererHelper(unittest.TestCase): self.assertEqual(result[0], 'values') self.assertEqual(result[1], system) - def test_render_renderer_globals_factory_active(self): - self._registerRendererFactory() - from pyramid.interfaces import IRendererGlobalsFactory - def rg(system): - return {'a':1} - self.config.registry.registerUtility(rg, IRendererGlobalsFactory) - helper = self._makeOne('loo.foo') - result = helper.render('values', None) - self.assertEqual(result[1]['a'], 1) - def test__make_response_request_is_None(self): request = None helper = self._makeOne('loo.foo') @@ -680,63 +304,6 @@ class TestRendererHelper(unittest.TestCase): helper = self._makeOne('loo.foo') response = helper._make_response(None, request) self.assertEqual(response.body, b'abc') - - def test__make_response_with_content_type(self): - from pyramid.response import Response - request = testing.DummyRequest() - request.response = Response() - attrs = {'_response_content_type':'text/nonsense'} - request.__dict__.update(attrs) - helper = self._makeOne('loo.foo') - response = helper._make_response('abc', request) - self.assertEqual(response.content_type, 'text/nonsense') - self.assertEqual(response.body, b'abc') - - def test__make_response_with_headerlist(self): - from pyramid.response import Response - request = testing.DummyRequest() - request.response = Response() - attrs = {'_response_headerlist':[('a', '1'), ('b', '2')]} - request.__dict__.update(attrs) - helper = self._makeOne('loo.foo') - response = helper._make_response('abc', request) - self.assertEqual(response.headerlist, - [('Content-Type', 'text/html; charset=UTF-8'), - ('Content-Length', '3'), - ('a', '1'), - ('b', '2')]) - self.assertEqual(response.body, b'abc') - - def test__make_response_with_status(self): - from pyramid.response import Response - request = testing.DummyRequest() - request.response = Response() - attrs = {'_response_status':'406 You Lose'} - request.__dict__.update(attrs) - helper = self._makeOne('loo.foo') - response = helper._make_response('abc', request) - self.assertEqual(response.status, '406 You Lose') - self.assertEqual(response.body, b'abc') - - def test__make_response_with_charset(self): - from pyramid.response import Response - request = testing.DummyRequest() - request.response = Response() - attrs = {'_response_charset':'UTF-16'} - request.__dict__.update(attrs) - helper = self._makeOne('loo.foo') - response = helper._make_response('abc', request) - self.assertEqual(response.charset, 'UTF-16') - - def test__make_response_with_cache_for(self): - from pyramid.response import Response - request = testing.DummyRequest() - request.response = Response() - attrs = {'_response_cache_for':100} - request.__dict__.update(attrs) - helper = self._makeOne('loo.foo') - response = helper._make_response('abc', request) - self.assertEqual(response.cache_control.max_age, 100) def test_with_alternate_response_factory(self): from pyramid.interfaces import IResponseFactory @@ -865,19 +432,21 @@ class Test_render(unittest.TestCase): from pyramid.renderers import render return render(renderer_name, value, request=request, package=package) - def test_it_no_request(self): + def _registerRenderer(self): renderer = self.config.testing_add_renderer( 'pyramid.tests:abc/def.pt') renderer.string_response = 'abc' + return renderer + + def test_it_no_request(self): + renderer = self._registerRenderer() result = self._callFUT('abc/def.pt', dict(a=1)) self.assertEqual(result, 'abc') renderer.assert_(a=1) renderer.assert_(request=None) - + def test_it_with_request(self): - renderer = self.config.testing_add_renderer( - 'pyramid.tests:abc/def.pt') - renderer.string_response = 'abc' + renderer = self._registerRenderer() request = testing.DummyRequest() result = self._callFUT('abc/def.pt', dict(a=1), request=request) @@ -887,9 +456,7 @@ class Test_render(unittest.TestCase): def test_it_with_package(self): import pyramid.tests - renderer = self.config.testing_add_renderer( - 'pyramid.tests:abc/def.pt') - renderer.string_response = 'abc' + renderer = self._registerRenderer() request = testing.DummyRequest() result = self._callFUT('abc/def.pt', dict(a=1), request=request, package=pyramid.tests) @@ -897,6 +464,30 @@ class Test_render(unittest.TestCase): renderer.assert_(a=1) renderer.assert_(request=request) + def test_response_preserved(self): + request = testing.DummyRequest() + response = object() # should error if mutated + request.response = response + # use a json renderer, which will mutate the response + result = self._callFUT('json', dict(a=1), request=request) + self.assertEqual(result, '{"a": 1}') + self.assertEqual(request.response, response) + + def test_no_response_to_preserve(self): + from pyramid.decorator import reify + class DummyRequestWithClassResponse(object): + _response = DummyResponse() + _response.content_type = None + _response.default_content_type = None + @reify + def response(self): + return self._response + request = DummyRequestWithClassResponse() + # use a json renderer, which will mutate the response + result = self._callFUT('json', dict(a=1), request=request) + self.assertEqual(result, '{"a": 1}') + self.assertFalse('response' in request.__dict__) + class Test_render_to_response(unittest.TestCase): def setUp(self): self.config = testing.setUp() @@ -917,7 +508,7 @@ class Test_render_to_response(unittest.TestCase): self.assertEqual(response.body, b'abc') renderer.assert_(a=1) renderer.assert_(request=None) - + def test_it_with_request(self): renderer = self.config.testing_add_renderer( 'pyramid.tests:abc/def.pt') @@ -999,17 +590,3 @@ class DummyResponse: app_iter = () body = '' -class DummyFactory: - def __init__(self, renderer): - self.renderer = renderer - - def __call__(self, path, lookup, **kw): - self.path = path - self.kw = kw - return self.renderer - - -class DummyRendererInfo(object): - def __init__(self, kw): - self.__dict__.update(kw) - diff --git a/pyramid/tests/test_request.py b/pyramid/tests/test_request.py index 565c6377e..6cd72fc59 100644 --- a/pyramid/tests/test_request.py +++ b/pyramid/tests/test_request.py @@ -308,163 +308,6 @@ class TestRequest(unittest.TestCase): self.assertEqual(1, request.db) self.assertEqual(1, request.db) -class TestRequestDeprecatedMethods(unittest.TestCase): - def setUp(self): - self.config = testing.setUp() - from zope.deprecation import __show__ - __show__.off() - - def tearDown(self): - testing.tearDown() - from zope.deprecation import __show__ - __show__.on() - - def _getTargetClass(self): - from pyramid.request import Request - return Request - - def _makeOne(self, environ=None): - if environ is None: - environ = {} - return self._getTargetClass()(environ) - - def test___contains__(self): - environ ={'zooma':1} - inst = self._makeOne(environ) - self.assertTrue('zooma' in inst) - - def test___delitem__(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - del inst['zooma'] - self.assertFalse('zooma' in environ) - - def test___getitem__(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(inst['zooma'], 1) - - def test___iter__(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - iterator = iter(inst) - self.assertEqual(list(iterator), list(iter(environ))) - - def test___setitem__(self): - environ = {} - inst = self._makeOne(environ) - inst['zooma'] = 1 - self.assertEqual(environ, {'zooma':1}) - - def test_get(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(inst.get('zooma'), 1) - - def test_has_key(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(inst.has_key('zooma'), True) - - def test_items(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(inst.items(), environ.items()) - - def test_iteritems(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(list(inst.iteritems()), list(iteritems_(environ))) - - def test_iterkeys(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(list(inst.iterkeys()), list(iterkeys_(environ))) - - def test_itervalues(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(list(inst.itervalues()), list(itervalues_(environ))) - - def test_keys(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - self.assertEqual(inst.keys(), environ.keys()) - - def test_pop(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - popped = inst.pop('zooma') - self.assertEqual(environ, {}) - self.assertEqual(popped, 1) - - def test_popitem(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - popped = inst.popitem() - self.assertEqual(environ, {}) - self.assertEqual(popped, ('zooma', 1)) - - def test_setdefault(self): - environ = {} - inst = self._makeOne(environ) - marker = [] - result = inst.setdefault('a', marker) - self.assertEqual(environ, {'a':marker}) - self.assertEqual(result, marker) - - def test_update(self): - environ = {} - inst = self._makeOne(environ) - inst.update({'a':1}, b=2) - self.assertEqual(environ, {'a':1, 'b':2}) - - def test_values(self): - environ = {'zooma':1} - inst = self._makeOne(environ) - result = list(inst.values()) - self.assertEqual(result, list(environ.values())) - - def test_response_content_type(self): - inst = self._makeOne() - self.assertFalse(hasattr(inst, 'response_content_type')) - inst.response_content_type = 'abc' - self.assertEqual(inst.response_content_type, 'abc') - del inst.response_content_type - self.assertFalse(hasattr(inst, 'response_content_type')) - - def test_response_headerlist(self): - inst = self._makeOne() - self.assertFalse(hasattr(inst, 'response_headerlist')) - inst.response_headerlist = 'abc' - self.assertEqual(inst.response_headerlist, 'abc') - del inst.response_headerlist - self.assertFalse(hasattr(inst, 'response_headerlist')) - - def test_response_status(self): - inst = self._makeOne() - self.assertFalse(hasattr(inst, 'response_status')) - inst.response_status = 'abc' - self.assertEqual(inst.response_status, 'abc') - del inst.response_status - self.assertFalse(hasattr(inst, 'response_status')) - - def test_response_charset(self): - inst = self._makeOne() - self.assertFalse(hasattr(inst, 'response_charset')) - inst.response_charset = 'abc' - self.assertEqual(inst.response_charset, 'abc') - del inst.response_charset - self.assertFalse(hasattr(inst, 'response_charset')) - - def test_response_cache_for(self): - inst = self._makeOne() - self.assertFalse(hasattr(inst, 'response_cache_for')) - inst.response_cache_for = 'abc' - self.assertEqual(inst.response_cache_for, 'abc') - del inst.response_cache_for - self.assertFalse(hasattr(inst, 'response_cache_for')) - class Test_route_request_iface(unittest.TestCase): def _callFUT(self, name): from pyramid.request import route_request_iface diff --git a/pyramid/tests/test_router.py b/pyramid/tests/test_router.py index 432959147..b836d7d72 100644 --- a/pyramid/tests/test_router.py +++ b/pyramid/tests/test_router.py @@ -1180,11 +1180,9 @@ class TestRouter(unittest.TestCase): from pyramid.interfaces import IViewClassifier from pyramid.interfaces import IRequest, IResponse from pyramid.response import Response - from zope.interface import Interface, implementer - class IContext(Interface): + class BaseContext: pass - @implementer(IContext) - class DummyContext: + class DummyContext(BaseContext): pass context = DummyContext() self._registerTraverserFactory(context) @@ -1193,7 +1191,7 @@ class TestRouter(unittest.TestCase): DummyContext) good_view = DummyView('abc') self._registerView(self.config.derive_view(good_view), - '', IViewClassifier, IRequest, IContext) + '', IViewClassifier, IRequest, BaseContext) router = self._makeOne() def make_response(s): return Response(s) diff --git a/pyramid/tests/test_scaffolds/fixture_scaffold/+package+/templates/mytemplate.pt_tmpl b/pyramid/tests/test_scaffolds/fixture_scaffold/+package+/templates/mytemplate.pt_tmpl index 3cd9c66a4..856bc22e7 100644 --- a/pyramid/tests/test_scaffolds/fixture_scaffold/+package+/templates/mytemplate.pt_tmpl +++ b/pyramid/tests/test_scaffolds/fixture_scaffold/+package+/templates/mytemplate.pt_tmpl @@ -1,7 +1,7 @@ <!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 Application Development Framework</title> + <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" /> @@ -24,7 +24,7 @@ <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 application development framework. + the Pyramid Web Framework. </p> </div> </div> diff --git a/pyramid/tests/test_scaffolds/test_copydir.py b/pyramid/tests/test_scaffolds/test_copydir.py index d757b837c..1e92b3c36 100644 --- a/pyramid/tests/test_scaffolds/test_copydir.py +++ b/pyramid/tests/test_scaffolds/test_copydir.py @@ -103,16 +103,57 @@ class Test_copy_dir(unittest.TestCase): 1, False, overwrite=False, template_renderer=dummy_template_renderer) - target = os.path.join(self.dirname, 'mypackage', '__init__.py') - with open(target, 'w') as f: - f.write('These are not the words you are looking for.') + # toplevel file + toplevel = os.path.join(self.dirname, 'mypackage', '__init__.py') + with open(toplevel, 'w') as f: + f.write('These are the words you are looking for.') + # sub directory file + sub = os.path.join(self.dirname, 'mypackage', 'templates', 'mytemplate.pt') + with open(sub, 'w') as f: + f.write('These are the words you are looking for.') self._callFUT(source, self.dirname, vars, 1, False, overwrite=False, template_renderer=dummy_template_renderer) + with open(toplevel, 'r') as f: + tcontent = f.read() + self.assertEqual('These are the words you are looking for.', tcontent) + with open(sub, 'r') as f: + tcontent = f.read() + self.assertEqual('These are the words you are looking for.', tcontent) + def test_overwrite_true(self): + vars = {'package':'mypackage'} + source = pkg_resources.resource_filename(*self.fixturetuple) + self._callFUT(source, + self.dirname, + vars, + 1, False, + overwrite=True, + template_renderer=dummy_template_renderer) + # toplevel file + toplevel = os.path.join(self.dirname, 'mypackage', '__init__.py') + with open(toplevel, 'w') as f: + f.write('These are not the words you are looking for.') + # sub directory file + sub = os.path.join(self.dirname, 'mypackage', 'templates', 'mytemplate.pt') + with open(sub, 'w') as f: + f.write('These are not the words you are looking for.') + self._callFUT(source, + self.dirname, + vars, + 1, False, + overwrite=True, + template_renderer=dummy_template_renderer) + with open(toplevel, 'r') as f: + tcontent = f.read() + self.assertNotEqual('These are not the words you are looking for.', tcontent) + with open(sub, 'r') as f: + tcontent = f.read() + self.assertNotEqual('These are not the words you are looking for.', tcontent) + def test_detect_SkipTemplate(self): vars = {'package':'mypackage'} source = pkg_resources.resource_filename(*self.fixturetuple) diff --git a/pyramid/tests/test_scaffolds/test_template.py b/pyramid/tests/test_scaffolds/test_template.py index d7cf638b6..2e961c516 100644 --- a/pyramid/tests/test_scaffolds/test_template.py +++ b/pyramid/tests/test_scaffolds/test_template.py @@ -11,7 +11,7 @@ class TestTemplate(unittest.TestCase): inst = self._makeOne() result = inst.render_template('{{a}} {{b}}', {'a':'1', 'b':'2'}) self.assertEqual(result, bytes_('1 2')) - + def test_render_template_expr_failure(self): inst = self._makeOne() self.assertRaises(AttributeError, inst.render_template, @@ -37,6 +37,21 @@ class TestTemplate(unittest.TestCase): result = inst.render_template('{{a}}', {'a':None}) self.assertEqual(result, b'') + def test_render_template_with_escaped_double_braces(self): + inst = self._makeOne() + result = inst.render_template('{{a}} {{b}} \{\{a\}\} \{\{c\}\}', {'a':'1', 'b':'2'}) + self.assertEqual(result, bytes_('1 2 {{a}} {{c}}')) + + def test_render_template_with_breaking_escaped_braces(self): + inst = self._makeOne() + result = inst.render_template('{{a}} {{b}} \{\{a\} \{b\}\}', {'a':'1', 'b':'2'}) + self.assertEqual(result, bytes_('1 2 \{\{a\} \{b\}\}')) + + def test_render_template_with_escaped_single_braces(self): + inst = self._makeOne() + result = inst.render_template('{{a}} {{b}} \{a\} \{b', {'a':'1', 'b':'2'}) + self.assertEqual(result, bytes_('1 2 \{a\} \{b')) + def test_module_dir(self): import sys import pkg_resources @@ -90,7 +105,7 @@ class TestTemplate(unittest.TestCase): 'overwrite':False, 'interactive':False, }) - + def test_write_files_path_missing(self): L = [] inst = self._makeOne() @@ -132,9 +147,9 @@ class DummyOptions(object): simulate = False overwrite = False interactive = False - + class DummyCommand(object): options = DummyOptions() verbosity = 1 - - + + diff --git a/pyramid/tests/test_scripts/dummy.py b/pyramid/tests/test_scripts/dummy.py index d580203af..366aa00b5 100644 --- a/pyramid/tests/test_scripts/dummy.py +++ b/pyramid/tests/test_scripts/dummy.py @@ -146,10 +146,13 @@ class DummyBootstrap(object): def __call__(self, *a, **kw): self.a = a self.kw = kw + registry = kw.get('registry', self.registry) + request = kw.get('request', self.request) + request.registry = registry return { 'app': self.app, - 'registry': self.registry, - 'request': self.request, + 'registry': registry, + 'request': request, 'root': self.root, 'root_factory': self.root_factory, 'closer': self.closer, diff --git a/pyramid/tests/test_scripts/test_pcreate.py b/pyramid/tests/test_scripts/test_pcreate.py index 1406d3911..6516ac229 100644 --- a/pyramid/tests/test_scripts/test_pcreate.py +++ b/pyramid/tests/test_scripts/test_pcreate.py @@ -110,6 +110,21 @@ class TestPCreateCommand(unittest.TestCase): scaffold2.vars, {'project': 'Distro', 'egg': 'Distro', 'package': 'distro'}) + def test_known_scaffold_with_path_as_project_target_rendered(self): + import os + cmd = self._makeOne('-s', 'dummy', '/tmp/foo/Distro/') + scaffold = DummyScaffold('dummy') + cmd.scaffolds = [scaffold] + result = cmd.run() + self.assertEqual(result, 0) + self.assertEqual( + scaffold.output_dir, + os.path.normpath(os.path.join(os.getcwd(), '/tmp/foo/Distro')) + ) + self.assertEqual( + scaffold.vars, + {'project': 'Distro', 'egg': 'Distro', 'package': 'distro'}) + class Test_main(unittest.TestCase): def _callFUT(self, argv): from pyramid.scripts.pcreate import main diff --git a/pyramid/tests/test_scripts/test_pdistreport.py b/pyramid/tests/test_scripts/test_pdistreport.py new file mode 100644 index 000000000..e229667c5 --- /dev/null +++ b/pyramid/tests/test_scripts/test_pdistreport.py @@ -0,0 +1,73 @@ +import unittest + +class TestPDistReportCommand(unittest.TestCase): + def _callFUT(self, **kw): + argv = [] + from pyramid.scripts.pdistreport import main + return main(argv, **kw) + + def test_no_dists(self): + def platform(): + return 'myplatform' + pkg_resources = DummyPkgResources() + L = [] + def out(*args): + L.extend(args) + result = self._callFUT(pkg_resources=pkg_resources, platform=platform, + out=out) + self.assertEqual(result, None) + self.assertEqual( + L, + ['Pyramid version:', '1', + 'Platform:', 'myplatform', + 'Packages:'] + ) + + def test_with_dists(self): + def platform(): + return 'myplatform' + working_set = (DummyDistribution('abc'), DummyDistribution('def')) + pkg_resources = DummyPkgResources(working_set) + L = [] + def out(*args): + L.extend(args) + result = self._callFUT(pkg_resources=pkg_resources, platform=platform, + out=out) + self.assertEqual(result, None) + self.assertEqual( + L, + ['Pyramid version:', + '1', + 'Platform:', + 'myplatform', + 'Packages:', + ' ', + 'abc', + '1', + ' ', + '/projects/abc', + ' ', + 'def', + '1', + ' ', + '/projects/def'] + ) + +class DummyPkgResources(object): + def __init__(self, working_set=()): + self.working_set = working_set + + def get_distribution(self, name): + return Version('1') + +class Version(object): + def __init__(self, version): + self.version = version + +class DummyDistribution(object): + def __init__(self, name): + self.project_name = name + self.version = '1' + self.location = '/projects/%s' % name + + diff --git a/pyramid/tests/test_scripts/test_prequest.py b/pyramid/tests/test_scripts/test_prequest.py index 91d2b322a..37f1d3c0f 100644 --- a/pyramid/tests/test_scripts/test_prequest.py +++ b/pyramid/tests/test_scripts/test_prequest.py @@ -68,6 +68,19 @@ class TestPRequestCommand(unittest.TestCase): self.assertEqual(self._app_name, None) self.assertEqual(self._out, ['abc']) + def test_command_w_basic_auth(self): + command = self._makeOne( + ['', '--login=user:password', + '--header=name:value','development.ini', '/']) + command.run() + self.assertEqual(self._environ['HTTP_NAME'], 'value') + self.assertEqual(self._environ['HTTP_AUTHORIZATION'], + 'Basic dXNlcjpwYXNzd29yZA==') + self.assertEqual(self._path_info, '/') + self.assertEqual(self._spec, 'development.ini') + self.assertEqual(self._app_name, None) + self.assertEqual(self._out, ['abc']) + def test_command_has_content_type_header_var(self): command = self._makeOne( ['', '--header=content-type:app/foo','development.ini', '/']) @@ -96,6 +109,7 @@ class TestPRequestCommand(unittest.TestCase): def test_command_method_get(self): command = self._makeOne(['', '--method=GET', 'development.ini', '/']) command.run() + self.assertEqual(self._environ['REQUEST_METHOD'], 'GET') self.assertEqual(self._path_info, '/') self.assertEqual(self._spec, 'development.ini') self.assertEqual(self._app_name, None) @@ -107,6 +121,35 @@ class TestPRequestCommand(unittest.TestCase): stdin = NativeIO() command.stdin = stdin command.run() + self.assertEqual(self._environ['REQUEST_METHOD'], 'POST') + self.assertEqual(self._environ['CONTENT_LENGTH'], '-1') + self.assertEqual(self._environ['wsgi.input'], stdin) + self.assertEqual(self._path_info, '/') + self.assertEqual(self._spec, 'development.ini') + self.assertEqual(self._app_name, None) + self.assertEqual(self._out, ['abc']) + + def test_command_method_put(self): + from pyramid.compat import NativeIO + command = self._makeOne(['', '--method=PUT', 'development.ini', '/']) + stdin = NativeIO() + command.stdin = stdin + command.run() + self.assertEqual(self._environ['REQUEST_METHOD'], 'PUT') + self.assertEqual(self._environ['CONTENT_LENGTH'], '-1') + self.assertEqual(self._environ['wsgi.input'], stdin) + self.assertEqual(self._path_info, '/') + self.assertEqual(self._spec, 'development.ini') + self.assertEqual(self._app_name, None) + self.assertEqual(self._out, ['abc']) + + def test_command_method_patch(self): + from pyramid.compat import NativeIO + command = self._makeOne(['', '--method=PATCH', 'development.ini', '/']) + stdin = NativeIO() + command.stdin = stdin + command.run() + self.assertEqual(self._environ['REQUEST_METHOD'], 'PATCH') self.assertEqual(self._environ['CONTENT_LENGTH'], '-1') self.assertEqual(self._environ['wsgi.input'], stdin) self.assertEqual(self._path_info, '/') @@ -114,6 +157,32 @@ class TestPRequestCommand(unittest.TestCase): self.assertEqual(self._app_name, None) self.assertEqual(self._out, ['abc']) + def test_command_method_propfind(self): + from pyramid.compat import NativeIO + command = self._makeOne(['', '--method=PROPFIND', 'development.ini', + '/']) + stdin = NativeIO() + command.stdin = stdin + command.run() + self.assertEqual(self._environ['REQUEST_METHOD'], 'PROPFIND') + self.assertEqual(self._path_info, '/') + self.assertEqual(self._spec, 'development.ini') + self.assertEqual(self._app_name, None) + self.assertEqual(self._out, ['abc']) + + def test_command_method_options(self): + from pyramid.compat import NativeIO + command = self._makeOne(['', '--method=OPTIONS', 'development.ini', + '/']) + stdin = NativeIO() + command.stdin = stdin + command.run() + self.assertEqual(self._environ['REQUEST_METHOD'], 'OPTIONS') + self.assertEqual(self._path_info, '/') + self.assertEqual(self._spec, 'development.ini') + self.assertEqual(self._app_name, None) + self.assertEqual(self._out, ['abc']) + def test_command_with_query_string(self): command = self._makeOne(['', 'development.ini', '/abc?a=1&b=2&c']) command.run() diff --git a/pyramid/tests/test_scripts/test_pserve.py b/pyramid/tests/test_scripts/test_pserve.py index 6e4b0f17d..107ff4c0a 100644 --- a/pyramid/tests/test_scripts/test_pserve.py +++ b/pyramid/tests/test_scripts/test_pserve.py @@ -156,7 +156,7 @@ class TestPServeCommand(unittest.TestCase): self.pid_file = tempfile.mktemp() pid = os.getpid() inst = self._makeOne() - inst.verbose = verbosity + inst.options.verbose = verbosity try: atexit.register = fake_atexit diff --git a/pyramid/tests/test_scripts/test_pviews.py b/pyramid/tests/test_scripts/test_pviews.py index 266d1ec90..b162144a7 100644 --- a/pyramid/tests/test_scripts/test_pviews.py +++ b/pyramid/tests/test_scripts/test_pviews.py @@ -12,6 +12,12 @@ class TestPViewsCommand(unittest.TestCase): cmd.args = ('/foo/bar/myapp.ini#myapp',) return cmd + def _makeRequest(self, url, registry): + from pyramid.request import Request + request = Request.blank('/a') + request.registry = registry + return request + def _register_mapper(self, registry, routes): from pyramid.interfaces import IRoutesMapper mapper = dummy.DummyMapper(*routes) @@ -22,7 +28,8 @@ class TestPViewsCommand(unittest.TestCase): registry = Registry() self._register_mapper(registry, []) command = self._makeOne(registry) - result = command._find_view('/a', registry) + request = self._makeRequest('/a', registry) + result = command._find_view(request) self.assertEqual(result, None) def test__find_view_no_match_multiview_registered(self): @@ -45,7 +52,8 @@ class TestPViewsCommand(unittest.TestCase): IMultiView) self._register_mapper(registry, []) command = self._makeOne(registry=registry) - result = command._find_view('/x', registry) + request = self._makeRequest('/x', registry) + result = command._find_view(request) self.assertEqual(result, None) def test__find_view_traversal(self): @@ -65,7 +73,8 @@ class TestPViewsCommand(unittest.TestCase): IView, name='a') self._register_mapper(registry, []) command = self._makeOne(registry=registry) - result = command._find_view('/a', registry) + request = self._makeRequest('/a', registry) + result = command._find_view(request) self.assertEqual(result, view1) def test__find_view_traversal_multiview(self): @@ -89,7 +98,8 @@ class TestPViewsCommand(unittest.TestCase): IMultiView, name='a') self._register_mapper(registry, []) command = self._makeOne(registry=registry) - result = command._find_view('/a', registry) + request = self._makeRequest('/a', registry) + result = command._find_view(request) self.assertEqual(result, view) def test__find_view_route_no_multiview(self): @@ -117,7 +127,8 @@ class TestPViewsCommand(unittest.TestCase): dummy.DummyRoute('b', '/b', factory=Factory)] self._register_mapper(registry, routes) command = self._makeOne(registry=registry) - result = command._find_view('/a', registry) + request = self._makeRequest('/a', registry) + result = command._find_view(request) self.assertEqual(result, view) def test__find_view_route_multiview_no_view_registered(self): @@ -147,7 +158,8 @@ class TestPViewsCommand(unittest.TestCase): dummy.DummyRoute('b', '/a', matchdict={})] self._register_mapper(registry, routes) command = self._makeOne(registry=registry) - result = command._find_view('/a', registry) + request = self._makeRequest('/a', registry) + result = command._find_view(request) self.assertTrue(IMultiView.providedBy(result)) def test__find_view_route_multiview(self): @@ -185,7 +197,8 @@ class TestPViewsCommand(unittest.TestCase): dummy.DummyRoute('b', '/a', matchdict={})] self._register_mapper(registry, routes) command = self._makeOne(registry=registry) - result = command._find_view('/a', registry) + request = self._makeRequest('/a', registry) + result = command._find_view(request) self.assertTrue(IMultiView.providedBy(result)) self.assertEqual(len(result.views), 2) self.assertTrue((None, view1, None) in result.views) @@ -228,7 +241,7 @@ class TestPViewsCommand(unittest.TestCase): command = self._makeOne(registry=registry) L = [] command.out = L.append - command._find_view = lambda arg1, arg2: None + command._find_view = lambda arg1: None command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -241,7 +254,7 @@ class TestPViewsCommand(unittest.TestCase): command = self._makeOne(registry=registry) L = [] command.out = L.append - command._find_view = lambda arg1, arg2: None + command._find_view = lambda arg1: None command.args = ('/foo/bar/myapp.ini#myapp', 'a') result = command.run() self.assertEqual(result, 0) @@ -255,7 +268,7 @@ class TestPViewsCommand(unittest.TestCase): L = [] command.out = L.append view = dummy.DummyView(context='context', view_name='a') - command._find_view = lambda arg1, arg2: view + command._find_view = lambda arg1: view command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -273,7 +286,7 @@ class TestPViewsCommand(unittest.TestCase): command.out = L.append def view(): pass view.__request_attrs__ = {'context': 'context', 'view_name': 'a'} - command._find_view = lambda arg1, arg2: view + command._find_view = lambda arg1: view command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -291,7 +304,7 @@ class TestPViewsCommand(unittest.TestCase): command.out = L.append view = dummy.DummyView(context='context', view_name='a') view.__permission__ = 'test' - command._find_view = lambda arg1, arg2: view + command._find_view = lambda arg1: view command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -312,7 +325,7 @@ class TestPViewsCommand(unittest.TestCase): predicate.text = lambda *arg: "predicate = x" view = dummy.DummyView(context='context', view_name='a') view.__predicates__ = [predicate] - command._find_view = lambda arg1, arg2: view + command._find_view = lambda arg1: view command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -332,7 +345,7 @@ class TestPViewsCommand(unittest.TestCase): route = dummy.DummyRoute('a', '/a', matchdict={}) view = dummy.DummyView(context='context', view_name='a', matched_route=route, subpath='') - command._find_view = lambda arg1, arg2: view + command._find_view = lambda arg1: view command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -360,7 +373,7 @@ class TestPViewsCommand(unittest.TestCase): view_name='a1') multiview2 = dummy.DummyMultiView(multiview1, context='context', view_name='a') - command._find_view = lambda arg1, arg2: multiview2 + command._find_view = lambda arg1: multiview2 command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -383,7 +396,7 @@ class TestPViewsCommand(unittest.TestCase): route = dummy.DummyRoute('a', '/a', matchdict={}, predicate=predicate) view = dummy.DummyView(context='context', view_name='a', matched_route=route, subpath='') - command._find_view = lambda arg1, arg2: view + command._find_view = lambda arg1: view command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -409,7 +422,7 @@ class TestPViewsCommand(unittest.TestCase): view.__name__ = 'view' view.__view_attr__ = 'call' multiview = dummy.DummyMultiView(view, context='context', view_name='a') - command._find_view = lambda arg1, arg2: multiview + command._find_view = lambda arg1: multiview command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -430,7 +443,7 @@ class TestPViewsCommand(unittest.TestCase): view.__view_attr__ = 'call' view.__permission__ = 'test' multiview = dummy.DummyMultiView(view, context='context', view_name='a') - command._find_view = lambda arg1, arg2: multiview + command._find_view = lambda arg1: multiview command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) @@ -454,7 +467,7 @@ class TestPViewsCommand(unittest.TestCase): view.__view_attr__ = 'call' view.__predicates__ = [predicate] multiview = dummy.DummyMultiView(view, context='context', view_name='a') - command._find_view = lambda arg1, arg2: multiview + command._find_view = lambda arg1: multiview command.args = ('/foo/bar/myapp.ini#myapp', '/a') result = command.run() self.assertEqual(result, 0) diff --git a/pyramid/tests/test_session.py b/pyramid/tests/test_session.py index b3e0e20c4..35e2b5c27 100644 --- a/pyramid/tests/test_session.py +++ b/pyramid/tests/test_session.py @@ -356,20 +356,29 @@ class Test_signed_deserialize(unittest.TestCase): self.assertRaises(ValueError, self._callFUT, serialized, 'secret') class Test_check_csrf_token(unittest.TestCase): - def _callFUT(self, request, token, raises=True): + def _callFUT(self, *args, **kwargs): from ..session import check_csrf_token - return check_csrf_token(request, token, raises=raises) + return check_csrf_token(*args, **kwargs) - def test_success(self): + def test_success_token(self): request = testing.DummyRequest() request.params['csrf_token'] = request.session.get_csrf_token() - self.assertEqual(self._callFUT(request, 'csrf_token'), True) + self.assertEqual(self._callFUT(request, token='csrf_token'), True) + + def test_success_header(self): + request = testing.DummyRequest() + request.headers['X-CSRF-Token'] = request.session.get_csrf_token() + self.assertEqual(self._callFUT(request, header='X-CSRF-Token'), True) def test_success_default_token(self): - from ..session import check_csrf_token request = testing.DummyRequest() request.params['csrf_token'] = request.session.get_csrf_token() - self.assertEqual(check_csrf_token(request), True) + self.assertEqual(self._callFUT(request), True) + + def test_success_default_header(self): + request = testing.DummyRequest() + request.headers['X-CSRF-Token'] = request.session.get_csrf_token() + self.assertEqual(self._callFUT(request), True) def test_failure_raises(self): from pyramid.httpexceptions import HTTPBadRequest diff --git a/pyramid/tests/test_testing.py b/pyramid/tests/test_testing.py index 7f14462a2..da57c6301 100644 --- a/pyramid/tests/test_testing.py +++ b/pyramid/tests/test_testing.py @@ -114,6 +114,10 @@ class TestDummyResource(unittest.TestCase): resource = self._makeOne() self.assertEqual(resource.__nonzero__(), True) + def test_bool(self): + resource = self._makeOne() + self.assertEqual(resource.__bool__(), True) + def test_ctor_with__provides__(self): resource = self._makeOne(__provides__=IDummy) self.assertTrue(IDummy.providedBy(resource)) diff --git a/pyramid/tests/test_traversal.py b/pyramid/tests/test_traversal.py index 2e45ae1a9..0dcc4a027 100644 --- a/pyramid/tests/test_traversal.py +++ b/pyramid/tests/test_traversal.py @@ -456,6 +456,23 @@ class ResourceTreeTraverserTests(unittest.TestCase): self.assertEqual(result['virtual_root'], resource) self.assertEqual(result['virtual_root_path'], ()) + def test_withroute_and_traverse_and_vroot(self): + abc = DummyContext() + resource = DummyContext(next=abc) + environ = self._getEnviron(HTTP_X_VHM_ROOT='/abc') + request = DummyRequest(environ) + traverser = self._makeOne(resource) + matchdict = {'traverse':text_('/foo/bar')} + request.matchdict = matchdict + result = traverser(request) + self.assertEqual(result['context'], abc) + self.assertEqual(result['view_name'], 'foo') + self.assertEqual(result['subpath'], ('bar',)) + self.assertEqual(result['traversed'], ('abc', 'foo')) + self.assertEqual(result['root'], resource) + self.assertEqual(result['virtual_root'], abc) + self.assertEqual(result['virtual_root_path'], ('abc',)) + class FindInterfaceTests(unittest.TestCase): def _callFUT(self, context, iface): from pyramid.traversal import find_interface @@ -1046,7 +1063,28 @@ class ResourceURLTests(unittest.TestCase): context_url = self._makeOne(two, request) self.assertEqual(context_url.physical_path, '/one/two/') self.assertEqual(context_url.virtual_path, '/two/') - + self.assertEqual(context_url.physical_path_tuple, ('', 'one', 'two','')) + self.assertEqual(context_url.virtual_path_tuple, ('', 'two', '')) + + def test_IResourceURL_attributes_vroot_ends_with_slash(self): + from pyramid.interfaces import VH_ROOT_KEY + root = DummyContext() + root.__parent__ = None + root.__name__ = None + one = DummyContext() + one.__parent__ = root + one.__name__ = 'one' + two = DummyContext() + two.__parent__ = one + two.__name__ = 'two' + environ = {VH_ROOT_KEY:'/one/'} + request = DummyRequest(environ) + context_url = self._makeOne(two, request) + self.assertEqual(context_url.physical_path, '/one/two/') + self.assertEqual(context_url.virtual_path, '/two/') + self.assertEqual(context_url.physical_path_tuple, ('', 'one', 'two','')) + self.assertEqual(context_url.virtual_path_tuple, ('', 'two', '')) + def test_IResourceURL_attributes_no_vroot(self): root = DummyContext() root.__parent__ = None @@ -1062,7 +1100,9 @@ class ResourceURLTests(unittest.TestCase): context_url = self._makeOne(two, request) self.assertEqual(context_url.physical_path, '/one/two/') self.assertEqual(context_url.virtual_path, '/one/two/') - + self.assertEqual(context_url.physical_path_tuple, ('', 'one', 'two','')) + self.assertEqual(context_url.virtual_path_tuple, ('', 'one', 'two', '')) + class TestVirtualRoot(unittest.TestCase): def setUp(self): cleanUp() @@ -1238,22 +1278,13 @@ class TestDefaultRootFactory(unittest.TestCase): def _makeOne(self, environ): return self._getTargetClass()(environ) - def test_no_matchdict(self): - class DummyRequest: - matchdict = None + def test_it(self): + class DummyRequest(object): + pass root = self._makeOne(DummyRequest()) self.assertEqual(root.__parent__, None) self.assertEqual(root.__name__, None) - def test_matchdict(self): - class DummyRequest: - pass - request = DummyRequest() - request.matchdict = {'a':1, 'b':2} - root = self._makeOne(request) - self.assertEqual(root.a, 1) - self.assertEqual(root.b, 2) - class Test__join_path_tuple(unittest.TestCase): def _callFUT(self, tup): from pyramid.traversal import _join_path_tuple diff --git a/pyramid/tests/test_url.py b/pyramid/tests/test_url.py index e33eeebfd..f6117777f 100644 --- a/pyramid/tests/test_url.py +++ b/pyramid/tests/test_url.py @@ -46,11 +46,12 @@ class TestURLMethodsMixin(unittest.TestCase): from pyramid.interfaces import IResourceURL from zope.interface import Interface class DummyResourceURL(object): - def __init__(self, context, request): - self.physical_path = '/context/' - self.virtual_path = '/context/' + physical_path = '/context/' + virtual_path = '/context/' + def __init__(self, context, request): pass reg.registerAdapter(DummyResourceURL, (Interface, Interface), IResourceURL) + return DummyResourceURL def test_resource_url_root_default(self): request = self._makeOne() @@ -255,6 +256,148 @@ class TestURLMethodsMixin(unittest.TestCase): root.__resource_url__ = resource_url result = request.resource_url(root) self.assertEqual(result, 'http://example.com/contextabc/') + + def test_resource_url_with_route_name_no_remainder_on_adapter(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # no virtual_path_tuple on adapter + adapter.virtual_path = '/a/b/c/' + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url(root, route_name='foo') + self.assertEqual(result, 'http://example.com:5432/1/2/3') + self.assertEqual(route.kw, {'traverse': ('', 'a', 'b', 'c', '')}) + + def test_resource_url_with_route_name_remainder_on_adapter(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # virtual_path_tuple on adapter + adapter.virtual_path_tuple = ('', 'a', 'b', 'c', '') + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url(root, route_name='foo') + self.assertEqual(result, 'http://example.com:5432/1/2/3') + self.assertEqual(route.kw, {'traverse': ('', 'a', 'b', 'c', '')}) + + def test_resource_url_with_route_name_and_app_url(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # virtual_path_tuple on adapter + adapter.virtual_path_tuple = ('', 'a', 'b', 'c', '') + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url(root, route_name='foo', app_url='app_url') + self.assertEqual(result, 'app_url/1/2/3') + self.assertEqual(route.kw, {'traverse': ('', 'a', 'b', 'c', '')}) + + def test_resource_url_with_route_name_and_scheme_host_port_etc(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # virtual_path_tuple on adapter + adapter.virtual_path_tuple = ('', 'a', 'b', 'c', '') + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url(root, route_name='foo', scheme='scheme', + host='host', port='port', query={'a':'1'}, + anchor='anchor') + self.assertEqual(result, 'scheme://host:port/1/2/3?a=1#anchor') + self.assertEqual(route.kw, {'traverse': ('', 'a', 'b', 'c', '')}) + + def test_resource_url_with_route_name_and_route_kwargs(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # virtual_path_tuple on adapter + adapter.virtual_path_tuple = ('', 'a', 'b', 'c', '') + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url( + root, route_name='foo', route_kw={'a':'1', 'b':'2'}) + self.assertEqual(result, 'http://example.com:5432/1/2/3') + self.assertEqual( + route.kw, + {'traverse': ('', 'a', 'b', 'c', ''), + 'a':'1', + 'b':'2'} + ) + + def test_resource_url_with_route_name_and_elements(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # virtual_path_tuple on adapter + adapter.virtual_path_tuple = ('', 'a', 'b', 'c', '') + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url(root, 'e1', 'e2', route_name='foo') + self.assertEqual(result, 'http://example.com:5432/1/2/3/e1/e2') + self.assertEqual(route.kw, {'traverse': ('', 'a', 'b', 'c', '')}) + + def test_resource_url_with_route_name_and_remainder_name(self): + from pyramid.interfaces import IRoutesMapper + environ = { + 'wsgi.url_scheme':'http', + 'SERVER_PORT':'8080', + 'SERVER_NAME':'example.com', + } + request = self._makeOne(environ) + adapter = self._registerResourceURL(request.registry) + # virtual_path_tuple on adapter + adapter.virtual_path_tuple = ('', 'a', 'b', 'c', '') + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route) + request.registry.registerUtility(mapper, IRoutesMapper) + root = DummyContext() + result = request.resource_url(root, route_name='foo', + route_remainder_name='fred') + self.assertEqual(result, 'http://example.com:5432/1/2/3') + self.assertEqual(route.kw, {'fred': ('', 'a', 'b', 'c', '')}) def test_resource_path(self): request = self._makeOne() @@ -485,6 +628,49 @@ class TestURLMethodsMixin(unittest.TestCase): self.assertEqual(result, 'http://example.com:5432/1/2/3/extra1/extra2?a=1#foo') + def test_current_route_url_with_request_query(self): + from pyramid.interfaces import IRoutesMapper + from webob.multidict import GetDict + request = self._makeOne() + request.GET = GetDict([('q', '123')], {}) + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route=route) + request.matched_route = route + request.matchdict = {} + request.registry.registerUtility(mapper, IRoutesMapper) + result = request.current_route_url() + self.assertEqual(result, + 'http://example.com:5432/1/2/3?q=123') + + def test_current_route_url_with_request_query_duplicate_entries(self): + from pyramid.interfaces import IRoutesMapper + from webob.multidict import GetDict + request = self._makeOne() + request.GET = GetDict( + [('q', '123'), ('b', '2'), ('b', '2'), ('q', '456')], {}) + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route=route) + request.matched_route = route + request.matchdict = {} + request.registry.registerUtility(mapper, IRoutesMapper) + result = request.current_route_url() + self.assertEqual(result, + 'http://example.com:5432/1/2/3?q=123&b=2&b=2&q=456') + + def test_current_route_url_with_query_override(self): + from pyramid.interfaces import IRoutesMapper + from webob.multidict import GetDict + request = self._makeOne() + request.GET = GetDict([('q', '123')], {}) + route = DummyRoute('/1/2/3') + mapper = DummyRoutesMapper(route=route) + request.matched_route = route + request.matchdict = {} + request.registry.registerUtility(mapper, IRoutesMapper) + result = request.current_route_url(_query={'a':1}) + self.assertEqual(result, + 'http://example.com:5432/1/2/3?a=1') + def test_current_route_path(self): from pyramid.interfaces import IRoutesMapper request = self._makeOne() @@ -497,7 +683,7 @@ class TestURLMethodsMixin(unittest.TestCase): result = request.current_route_path('extra1', 'extra2', _query={'a':1}, _anchor=text_(b"foo")) self.assertEqual(result, '/script_name/1/2/3/extra1/extra2?a=1#foo') - + def test_route_path_with_elements(self): from pyramid.interfaces import IRoutesMapper request = self._makeOne() @@ -569,7 +755,6 @@ class TestURLMethodsMixin(unittest.TestCase): ('pyramid.tests:static/foo.css', request, {}) ) def test_static_url_abspath_integration_with_staticurlinfo(self): - import os from pyramid.interfaces import IStaticURLInfo from pyramid.config.views import StaticURLInfo info = StaticURLInfo() @@ -584,7 +769,6 @@ class TestURLMethodsMixin(unittest.TestCase): 'http://example.com:5432/absstatic/test_url.py') def test_static_url_noscheme_uses_scheme_from_request(self): - import os from pyramid.interfaces import IStaticURLInfo from pyramid.config.views import StaticURLInfo info = StaticURLInfo() @@ -987,6 +1171,77 @@ class Test_current_route_path(unittest.TestCase): self.assertEqual(request.elements, ('abc',)) self.assertEqual(request.kw, {'_anchor':'abc'}) +class Test_external_static_url_integration(unittest.TestCase): + + def setUp(self): + self.config = testing.setUp() + + def tearDown(self): + testing.tearDown() + + def _makeRequest(self): + from pyramid.request import Request + return Request.blank('/') + + def test_generate_external_url(self): + self.config.add_route('acme', 'https://acme.org/path/{foo}') + request = self._makeRequest() + request.registry = self.config.registry + self.assertEqual( + request.route_url('acme', foo='bar'), + 'https://acme.org/path/bar') + + def test_generate_external_url_without_scheme(self): + self.config.add_route('acme', '//acme.org/path/{foo}') + request = self._makeRequest() + request.registry = self.config.registry + self.assertEqual( + request.route_url('acme', foo='bar'), + 'http://acme.org/path/bar') + + def test_generate_external_url_with_explicit_scheme(self): + self.config.add_route('acme', '//acme.org/path/{foo}') + request = self._makeRequest() + request.registry = self.config.registry + self.assertEqual( + request.route_url('acme', foo='bar', _scheme='https'), + 'https://acme.org/path/bar') + + def test_generate_external_url_with_explicit_app_url(self): + self.config.add_route('acme', 'http://acme.org/path/{foo}') + request = self._makeRequest() + request.registry = self.config.registry + self.assertRaises(ValueError, + request.route_url, 'acme', foo='bar', _app_url='http://fakeme.com') + + def test_generate_external_url_route_path(self): + self.config.add_route('acme', 'https://acme.org/path/{foo}') + request = self._makeRequest() + request.registry = self.config.registry + self.assertRaises(ValueError, request.route_path, 'acme', foo='bar') + + def test_generate_external_url_with_pregenerator(self): + def pregenerator(request, elements, kw): + kw['_query'] = {'q': 'foo'} + return elements, kw + self.config.add_route('acme', 'https://acme.org/path/{foo}', + pregenerator=pregenerator) + request = self._makeRequest() + request.registry = self.config.registry + self.assertEqual( + request.route_url('acme', foo='bar'), + 'https://acme.org/path/bar?q=foo') + + def test_external_url_with_route_prefix(self): + def includeme(config): + config.add_route('acme', '//acme.org/{foo}') + self.config.include(includeme, route_prefix='some_prefix') + request = self._makeRequest() + request.registry = self.config.registry + self.assertEqual( + request.route_url('acme', foo='bar'), + 'http://acme.org/bar') + class DummyContext(object): def __init__(self, next=None): self.next = next diff --git a/pyramid/tests/test_urldispatch.py b/pyramid/tests/test_urldispatch.py index b2164717e..1755d9f47 100644 --- a/pyramid/tests/test_urldispatch.py +++ b/pyramid/tests/test_urldispatch.py @@ -295,7 +295,7 @@ class TestCompileRoute(unittest.TestCase): 'remainder':'/everything/else/here'}) self.assertEqual(matcher('foo/baz/biz/buz/bar'), None) self.assertEqual(generator( - {'baz':1, 'buz':2, 'remainder':'/a/b'}), '/foo/1/biz/2/bar%2Fa%2Fb') + {'baz':1, 'buz':2, 'remainder':'/a/b'}), '/foo/1/biz/2/bar/a/b') def test_no_beginning_slash(self): matcher, generator = self._callFUT('foo/:baz/biz/:buz/bar') @@ -491,10 +491,10 @@ class TestCompileRouteFunctional(unittest.TestCase): self.generates('zzz/{x}*traverse', {'x':'abc', 'traverse':'/def/g'}, '/zzz/abc/def/g') self.generates('/{x}', {'x':text_(b'/La Pe\xc3\xb1a', 'utf-8')}, - '/%2FLa%20Pe%C3%B1a') + '//La%20Pe%C3%B1a') self.generates('/{x}*y', {'x':text_(b'/La Pe\xc3\xb1a', 'utf-8'), 'y':'/rest/of/path'}, - '/%2FLa%20Pe%C3%B1a/rest/of/path') + '//La%20Pe%C3%B1a/rest/of/path') self.generates('*traverse', {'traverse':('a', text_(b'La Pe\xf1a'))}, '/a/La%20Pe%C3%B1a') self.generates('/foo/{id}.html', {'id':'bar'}, '/foo/bar.html') @@ -511,10 +511,10 @@ class TestCompileRouteFunctional(unittest.TestCase): self.generates('zzz/:x*traverse', {'x':'abc', 'traverse':'/def/g'}, '/zzz/abc/def/g') self.generates('/:x', {'x':text_(b'/La Pe\xc3\xb1a', 'utf-8')}, - '/%2FLa%20Pe%C3%B1a') + '//La%20Pe%C3%B1a') self.generates('/:x*y', {'x':text_(b'/La Pe\xc3\xb1a', 'utf-8'), 'y':'/rest/of/path'}, - '/%2FLa%20Pe%C3%B1a/rest/of/path') + '//La%20Pe%C3%B1a/rest/of/path') self.generates('*traverse', {'traverse':('a', text_(b'La Pe\xf1a'))}, '/a/La%20Pe%C3%B1a') self.generates('/foo/:id.html', {'id':'bar'}, '/foo/bar.html') diff --git a/pyramid/tests/test_view.py b/pyramid/tests/test_view.py index a0d476662..309fd47e2 100644 --- a/pyramid/tests/test_view.py +++ b/pyramid/tests/test_view.py @@ -301,51 +301,6 @@ class RenderViewTests(BaseTest, unittest.TestCase): s = self._callFUT(context, request, name='registered', secure=False) self.assertEqual(s, b'anotherview') -class TestIsResponse(unittest.TestCase): - def setUp(self): - from zope.deprecation import __show__ - __show__.off() - - def tearDown(self): - from zope.deprecation import __show__ - __show__.on() - - def _callFUT(self, *arg, **kw): - from pyramid.view import is_response - return is_response(*arg, **kw) - - def test_is(self): - response = DummyResponse() - self.assertEqual(self._callFUT(response), True) - - def test_isnt(self): - response = None - self.assertEqual(self._callFUT(response), False) - - def test_isnt_no_headerlist(self): - class Response(object): - pass - resp = Response - resp.status = '200 OK' - resp.app_iter = [] - self.assertEqual(self._callFUT(resp), False) - - def test_isnt_no_status(self): - class Response(object): - pass - resp = Response - resp.app_iter = [] - resp.headerlist = () - self.assertEqual(self._callFUT(resp), False) - - def test_isnt_no_app_iter(self): - class Response(object): - pass - resp = Response - resp.status = '200 OK' - resp.headerlist = () - self.assertEqual(self._callFUT(resp), False) - class TestViewConfigDecorator(unittest.TestCase): def setUp(self): testing.setUp() @@ -673,24 +628,6 @@ class Test_default_exceptionresponse_view(unittest.TestCase): result = self._callFUT(context, request) self.assertEqual(result, 'abc') -class Test_static(unittest.TestCase): - def setUp(self): - from zope.deprecation import __show__ - __show__.off() - - def tearDown(self): - from zope.deprecation import __show__ - __show__.on() - - def _makeOne(self, path, package_name): - from pyramid.view import static - return static(path, package_name) - - def test_it(self): - path = 'fixtures' - view = self._makeOne(path, None) - self.assertEqual(view.docroot, 'fixtures') - class Test_view_defaults(unittest.TestCase): def test_it(self): from pyramid.view import view_defaults diff --git a/pyramid/traversal.py b/pyramid/traversal.py index ed49d8743..4c275c4c1 100644 --- a/pyramid/traversal.py +++ b/pyramid/traversal.py @@ -640,7 +640,7 @@ class ResourceTreeTraverser(object): # this is a *traverse stararg (not a {traverse}) # routing has already decoded these elements, so we just # need to join them - path = slash.join(path) or slash + path = '/' + slash.join(path) or slash subpath = matchdict.get('subpath', ()) if not is_nonstr_iter(subpath): @@ -733,11 +733,15 @@ class ResourceURL(object): vroot_varname = VH_ROOT_KEY def __init__(self, resource, request): - physical_path = resource_path(resource) - if physical_path != '/': + physical_path_tuple = resource_path_tuple(resource) + physical_path = _join_path_tuple(physical_path_tuple) + + if physical_path_tuple != ('',): + physical_path_tuple = physical_path_tuple + ('',) physical_path = physical_path + '/' virtual_path = physical_path + virtual_path_tuple = physical_path_tuple environ = request.environ vroot_path = environ.get(self.vroot_varname) @@ -745,11 +749,17 @@ class ResourceURL(object): # if the physical path starts with the virtual root path, trim it out # of the virtual path if vroot_path is not None: - if physical_path.startswith(vroot_path): + vroot_path = vroot_path.rstrip('/') + if vroot_path and physical_path.startswith(vroot_path): + vroot_path_tuple = tuple(vroot_path.split('/')) + numels = len(vroot_path_tuple) + virtual_path_tuple = ('',) + physical_path_tuple[numels:] virtual_path = physical_path[len(vroot_path):] self.virtual_path = virtual_path # IResourceURL attr self.physical_path = physical_path # IResourceURL attr + self.virtual_path_tuple = virtual_path_tuple # IResourceURL attr (1.5) + self.physical_path_tuple = physical_path_tuple # IResourceURL attr (1.5) # bw compat for IContextURL methods self.resource = resource @@ -812,9 +822,4 @@ class DefaultRootFactory: __parent__ = None __name__ = None def __init__(self, request): - matchdict = request.matchdict - # provide backwards compatibility for applications which - # used routes (at least apps without any custom "context - # factory") in BFG 0.9.X and before - if matchdict is not None: - self.__dict__.update(matchdict) + pass diff --git a/pyramid/url.py b/pyramid/url.py index 84b58ac45..fda2c72c7 100644 --- a/pyramid/url.py +++ b/pyramid/url.py @@ -124,15 +124,18 @@ class URLMethodsMixin(object): ``*remainder`` replacement value, it is tacked on to the URL after being URL-quoted-except-for-embedded-slashes. - If a keyword argument ``_query`` is present, it will be used to - compose a query string that will be tacked on to the end of the - URL. The value of ``_query`` must be a sequence of two-tuples - *or* a data structure with an ``.items()`` method that returns a + If no ``_query`` keyword argument is provided, the request + query string will be returned in the URL. If it is present, it + will be used to compose a query string that will be tacked on + to the end of the URL, replacing any request query string. + The value of ``_query`` must be a sequence of two-tuples *or* + a data structure with an ``.items()`` method that returns a sequence of two-tuples (presumably a dictionary). This data - structure will be turned into a query string per the documentation - of :func:`pyramid.encode.urlencode` function. After the query - data is turned into a query string, a leading ``?`` is prepended, - and the resulting string is appended to the generated URL. + structure will be turned into a query string per the + documentation of :func:`pyramid.encode.urlencode` function. + After the query data is turned into a query string, a leading + ``?`` is prepended, and the resulting string is appended to + the generated URL. .. note:: @@ -387,7 +390,7 @@ class URLMethodsMixin(object): resulting url of a resource that has a path of ``/baz/bar`` will be ``http://foo/baz/bar``. If you want to generate completely relative URLs with no leading scheme, host, port, or initial path, you can - pass ``app_url=''`. Passing ``app_url=''` when the resource path is + pass ``app_url=''``. Passing ``app_url=''`` when the resource path is ``/baz/bar`` will return ``/baz/bar``. .. versionadded:: 1.3 @@ -398,10 +401,66 @@ class URLMethodsMixin(object): passed for ``scheme``, ``host``, and/or ``port`` will be ignored. If the ``resource`` passed in has a ``__resource_url__`` method, it - will be used to generate the URL (scheme, host, port, path) that for - the base resource which is operated upon by this function. See also + will be used to generate the URL (scheme, host, port, path) for the + base resource which is operated upon by this function. See also :ref:`overriding_resource_url_generation`. + .. versionadded:: 1.5 + ``route_name``, ``route_kw``, and ``route_remainder_name`` + + If ``route_name`` is passed, this function will delegate its URL + production to the ``route_url`` function. Calling + ``resource_url(someresource, 'element1', 'element2', query={'a':1}, + route_name='blogentry')`` is roughly equivalent to doing:: + + remainder_path = request.resource_path(someobject) + url = request.route_url( + 'blogentry', + 'element1', + 'element2', + _query={'a':'1'}, + traverse=traversal_path, + ) + + It is only sensible to pass ``route_name`` if the route being named has + a ``*remainder`` stararg value such as ``*traverse``. The remainder + value will be ignored in the output otherwise. + + By default, the resource path value will be passed as the name + ``traverse`` when ``route_url`` is called. You can influence this by + passing a different ``route_remainder_name`` value if the route has a + different ``*stararg`` value at its end. For example if the route + pattern you want to replace has a ``*subpath`` stararg ala + ``/foo*subpath``:: + + request.resource_url( + resource, + route_name='myroute', + route_remainder_name='subpath' + ) + + If ``route_name`` is passed, it is also permissible to pass + ``route_kw``, which will passed as additional keyword arguments to + ``route_url``. Saying ``resource_url(someresource, 'element1', + 'element2', route_name='blogentry', route_kw={'id':'4'}, + _query={'a':'1'})`` is roughly equivalent to:: + + remainder_path = request.resource_path_tuple(someobject) + kw = {'id':'4', '_query':{'a':'1'}, 'traverse':traversal_path} + url = request.route_url( + 'blogentry', + 'element1', + 'element2', + **kw, + ) + + If ``route_kw`` or ``route_remainder_name`` is passed, but + ``route_name`` is not passed, both ``route_kw`` and + ``route_remainder_name`` will be ignored. If ``route_name`` + is passed, the ``__resource_url__`` method of the resource passed is + ignored unconditionally. This feature is incompatible with + resources which generate their own URLs. + .. note:: If the :term:`resource` used is the result of a :term:`traversal`, it @@ -449,12 +508,37 @@ class URLMethodsMixin(object): resource_url = url_adapter() else: - # newer-style IResourceURL adapter (Pyramid 1.3 and after) + # IResourceURL adapter (Pyramid 1.3 and after) app_url = None scheme = None host = None port = None + if 'route_name' in kw: + newkw = {} + route_name = kw['route_name'] + remainder = getattr(url_adapter, 'virtual_path_tuple', None) + if remainder is None: + # older user-supplied IResourceURL adapter without 1.5 + # virtual_path_tuple + remainder = tuple(url_adapter.virtual_path.split('/')) + remainder_name = kw.get('route_remainder_name', 'traverse') + newkw[remainder_name] = remainder + + for name in ( + 'app_url', 'scheme', 'host', 'port', 'query', 'anchor' + ): + val = kw.get(name, None) + if val is not None: + newkw['_' + name] = val + + if 'route_kw' in kw: + route_kw = kw.get('route_kw') + if route_kw is not None: + newkw.update(route_kw) + + return self.route_url(route_name, *elements, **newkw) + if 'app_url' in kw: app_url = kw['app_url'] @@ -679,6 +763,9 @@ class URLMethodsMixin(object): if route_name is None: raise ValueError('Current request matches no route') + if '_query' not in kw: + kw['_query'] = self.GET + newkw = {} newkw.update(self.matchdict) newkw.update(kw) diff --git a/pyramid/urldispatch.py b/pyramid/urldispatch.py index 4182ea665..fe4d433c3 100644 --- a/pyramid/urldispatch.py +++ b/pyramid/urldispatch.py @@ -91,7 +91,7 @@ class RoutesMapper(object): # stolen from bobo and modified old_route_re = re.compile(r'(\:[_a-zA-Z]\w*)') -star_at_end = re.compile(r'\*\w*$') +star_at_end = re.compile(r'\*(\w*)$') # The tortuous nature of the regex named ``route_re`` below is due to the # fact that we need to support at least one level of "inner" squigglies @@ -213,7 +213,9 @@ def _compile_route(route): if k == remainder: # a stararg argument if is_nonstr_iter(v): - v = '/'.join([quote_path_segment(x) for x in v]) # native + v = '/'.join( + [quote_path_segment(x, safe='/') for x in v] + ) # native else: if v.__class__ not in string_types: v = str(v) @@ -222,7 +224,7 @@ def _compile_route(route): if v.__class__ not in string_types: v = str(v) # v may be bytes (py2) or native string (py3) - v = quote_path_segment(v) + v = quote_path_segment(v, safe='/') # at this point, the value will be a native string newdict[k] = v diff --git a/pyramid/util.py b/pyramid/util.py index 02bd7ba2a..73f3ebdb0 100644 --- a/pyramid/util.py +++ b/pyramid/util.py @@ -69,22 +69,18 @@ class InstancePropertyMixin(object): can accept multiple ``(name, property)`` pairs generated via :meth:`pyramid.util.InstancePropertyMixin._make_property`. - ``attrs`` is a sequence of 2-tuples *or* a data structure with - an ``.items()`` method which returns a sequence of 2-tuples + ``properties`` is a sequence of two-tuples *or* a data structure + with an ``.items()`` method which returns a sequence of two-tuples (presumably a dictionary). It will be used to add several properties to the instance in a manner that is more efficient than simply calling ``set_property`` repeatedly. """ - - if hasattr(properties, 'items'): - attrs = properties.items() - else: - attrs = properties attrs = dict(properties) - parent = self.__class__ - cls = type(parent.__name__, (parent, object), attrs) - self.__class__ = cls + if attrs: + parent = self.__class__ + cls = type(parent.__name__, (parent, object), attrs) + self.__class__ = cls def _set_extensions(self, extensions): for name, fn in iteritems_(extensions.methods): diff --git a/pyramid/view.py b/pyramid/view.py index 76752ce8f..55ab38871 100644 --- a/pyramid/view.py +++ b/pyramid/view.py @@ -1,8 +1,6 @@ import venusian from zope.interface import providedBy -from zope.deprecation import deprecated - from pyramid.interfaces import ( IRoutesMapper, @@ -20,33 +18,10 @@ from pyramid.httpexceptions import ( default_exceptionresponse_view, ) -from pyramid.path import caller_package -from pyramid.static import static_view from pyramid.threadlocal import get_current_registry _marker = object() -class static(static_view): - """ Backwards compatibility alias for - :class:`pyramid.static.static_view`; it overrides that class' constructor - to pass ``use_subpath=True`` by default. - - .. deprecated:: 1.1 - use :class:`pyramid.static.static_view` instead - (probably with a ``use_subpath=True`` argument) - """ - def __init__(self, root_dir, cache_max_age=3600, package_name=None): - if package_name is None: - package_name = caller_package().__name__ - static_view.__init__(self, root_dir, cache_max_age=cache_max_age, - package_name=package_name, use_subpath=True) - -deprecated( - 'static', - 'The "pyramid.view.static" class is deprecated as of Pyramid 1.1; ' - 'use the "pyramid.static.static_view" class instead with the ' - '"use_subpath" argument set to True.') - def render_view_to_response(context, request, name='', secure=True): """ Call the :term:`view callable` configured with a :term:`view configuration` that matches the :term:`view name` ``name`` @@ -191,6 +166,9 @@ class view_config(object): See :ref:`mapping_views_using_a_decorator_section` for details about using :class:`pyramid.view.view_config`. + ATTENTION: ``view_config`` will work ONLY on module top level members + because of the limitation of ``venusian.Scanner.scan``. + """ venusian = venusian # for testing injection def __init__(self, **settings): @@ -226,11 +204,11 @@ class view_defaults(view_config): """ A class :term:`decorator` which, when applied to a class, will provide defaults for all view configurations that use the class. This decorator accepts all the arguments accepted by - :class:`pyramid.config.view_config`, and each has the same meaning. + :meth:`pyramid.view.view_config`, and each has the same meaning. See :ref:`view_defaults` for more information. """ - + def __call__(self, wrapped): wrapped.__view_defaults__ = self.__dict__.copy() return wrapped @@ -330,7 +308,7 @@ class notfound_view_config(object): from pyramid.view import notfound_view_config from pyramid.response import Response - + @notfound_view_config() def notfound(request): return Response('Not found, dude!', status='404 Not Found') @@ -393,7 +371,7 @@ class forbidden_view_config(object): from pyramid.view import forbidden_view_config from pyramid.response import Response - + @forbidden_view_config() def forbidden(request): return Response('You are not allowed', status='401 Unauthorized') @@ -429,19 +407,4 @@ class forbidden_view_config(object): settings['_info'] = info.codeinfo # fbo "action_method" return wrapped - -def is_response(ob): - """ Return ``True`` if ``ob`` implements the interface implied by - :ref:`the_response`. ``False`` if not. - - .. deprecated:: 1.1 - use :func:`pyramid.request.Request.is_response` instead""" - if ( hasattr(ob, 'app_iter') and hasattr(ob, 'headerlist') and - hasattr(ob, 'status') ): - return True - return False - -deprecated( - 'is_response', - 'pyramid.view.is_response is deprecated as of Pyramid 1.1. Use ' - 'pyramid.request.Request.is_response instead.') + diff --git a/pyramid/wsgi.py b/pyramid/wsgi.py index 5fa23d554..d176e4ce5 100644 --- a/pyramid/wsgi.py +++ b/pyramid/wsgi.py @@ -25,7 +25,7 @@ def wsgiapp(wrapped): The ``wsgiapp`` decorator will convert the result of the WSGI application to a :term:`Response` and return it to - :app:`Pyramid` as if the WSGI app were a :mod:`pyramid` + :app:`Pyramid` as if the WSGI app were a :app:`Pyramid` view. """ @@ -1,3 +1,4 @@ repoze.sphinx.autointerface repoze.lru +pylons_sphinx_latesturl @@ -39,8 +39,6 @@ except IOError: install_requires=[ 'setuptools', - 'Chameleon >= 1.2.3', - 'Mako >= 0.3.6', # strict_undefined 'WebOb >= 1.2b3', # request.path_info is unicode 'repoze.lru >= 0.4', # py3 compat 'zope.interface >= 3.8.0', # has zope.interface.registry @@ -65,14 +63,14 @@ docs_extras = [ testing_extras = tests_require + [ 'nose', + 'nose-selecttests', 'coverage', 'virtualenv', # for scaffolding tests ] setup(name='pyramid', - version='1.4', - description=('The Pyramid web application development framework, a ' - 'Pylons project'), + version='1.5a2', + description='The Pyramid Web Framework, a Pylons project', long_description=README + '\n\n' + CHANGES, classifiers=[ "Intended Audience :: Developers", @@ -110,7 +108,6 @@ setup(name='pyramid', zodb=pyramid.scaffolds:ZODBProjectTemplate alchemy=pyramid.scaffolds:AlchemyProjectTemplate [console_scripts] - bfg2pyramid = pyramid.fixers.fix_bfg_imports:main pcreate = pyramid.scripts.pcreate:main pserve = pyramid.scripts.pserve:main pshell = pyramid.scripts.pshell:main @@ -118,6 +115,7 @@ setup(name='pyramid', pviews = pyramid.scripts.pviews:main ptweens = pyramid.scripts.ptweens:main prequest = pyramid.scripts.prequest:main + pdistreport = pyramid.scripts.pdistreport:main [paste.server_runner] wsgiref = pyramid.scripts.pserve:wsgiref_server_runner cherrypy = pyramid.scripts.pserve:cherrypy_server_runner |
