diff options
37 files changed, 935 insertions, 742 deletions
diff --git a/CHANGES.txt b/CHANGES.txt index 1997c69de..047db6472 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,478 +1,29 @@ Next release ============ -Dependencies ------------- - -- Pyramid no longer depends on the zope.component package, except as a - testing dependency. - -- Pyramid now depends on a ``zope.interface`` version greater than or equal - to 3.8.0. - -1.2 (2011-09-12) -================ - -Features --------- - -- Route pattern replacement marker names can now begin with an underscore. - See https://github.com/Pylons/pyramid/issues/276. - -1.2b3 (2011-09-11) -================== - -Bug Fixes ---------- - -- The route prefix was not taken into account when a static view was added in - an "include". See https://github.com/Pylons/pyramid/issues/266 . - -1.2b2 (2011-09-08) -================== - -Bug Fixes ---------- - -- The 1.2b1 tarball was a brownbag (particularly for Windows users) because - it contained filenames with stray quotation marks in inappropriate places. - We depend on ``setuptools-git`` to produce release tarballs, and when it - was run to produce the 1.2b1 tarball, it didn't yet cope well with files - present in git repositories with high-order characters in their filenames. - -Documentation -------------- - -- Minor tweaks to the "Introduction" narrative chapter example app and - wording. - -1.2b1 (2011-09-08) -================== - -Bug Fixes ---------- - -- Sometimes falling back from territory translations (``de_DE``) to language - translations (``de``) would not work properly when using a localizer. See - https://github.com/Pylons/pyramid/issues/263 - -- The static file serving machinery could not serve files that started with a - ``.`` (dot) character. - -- Static files with high-order (super-ASCII) characters in their names could - not be served by a static view. The static file serving machinery - inappropriately URL-quoted path segments in filenames when asking for files - from the filesystem. - -- Within ``pyramid.traversal.traversal_path`` , canonicalize URL segments - from UTF-8 to Unicode before checking whether a segment matches literally - one of ``.``, the empty string, or ``..`` in case there's some sneaky way - someone might tunnel those strings via UTF-8 that don't match the literals - before decoded. - -Documentation -------------- - -- Added a "What Makes Pyramid Unique" section to the Introduction narrative - chapter. - -1.2a6 (2011-09-06) -================== - -Bug Fixes ---------- - -- AuthTktAuthenticationPolicy with a ``reissue_time`` interfered with logout. - See https://github.com/Pylons/pyramid/issues/262. - -Internal --------- - -- Internalize code previously depended upon as imports from the - ``paste.auth`` module (futureproof). - -- Replaced use of ``paste.urlparser.StaticURLParser`` with a derivative of - Chris Rossi's "happy" static file serving code (futureproof). - -- Fixed test suite; on some systems tests would fail due to indeterminate - test run ordering and a double-push-single-pop of a shared test variable. - -Behavior Differences --------------------- - -- An ETag header is no longer set when serving a static file. A - Last-Modified header is set instead. - -- Static file serving no longer supports the ``wsgi.file_wrapper`` extension. - -- Instead of returning a ``403 Forbidden`` error when a static file is served - that cannot be accessed by the Pyramid process' user due to file - permissions, an IOError (or similar) will be raised. - -Scaffolds ---------- - -- All scaffolds now send the ``cache_max_age`` parameter to the - ``add_static_view`` method. - -1.2a5 (2011-09-04) -================== - -Bug Fixes ---------- - -- The ``route_prefix`` of a configurator was not properly taken into account - when registering routes in certain circumstances. See - https://github.com/Pylons/pyramid/issues/260 - -Dependencies ------------- - -- The ``zope.configuration`` package is no longer a dependency. - -1.2a4 (2011-09-02) -================== - -Features --------- - -- Support an ``onerror`` keyword argument to - ``pyramid.config.Configurator.scan()``. This onerror keyword argument is - passed to ``venusian.Scanner.scan()`` to influence error behavior when - an exception is raised during scanning. - -- The ``request_method`` predicate argument to - ``pyramid.config.Configurator.add_view`` and - ``pyramid.config.Configurator.add_route`` is now permitted to be a tuple of - HTTP method names. Previously it was restricted to being a string - representing a single HTTP method name. - -- Undeprecated ``pyramid.traversal.find_model``, - ``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, - and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. - There's just not much cost to keeping them around forever as aliases to - their renamed ``resource_*`` prefixed functions. - -- Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid - 1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll - just keep around forever. - -Dependencies ------------- - -- Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` - keyword argument to ``pyramid.config.Configurator.scan``. - -1.2a3 (2011-08-29) -================== - -Bug Fixes ---------- - -- Pyramid did not properly generate static URLs using - ``pyramid.url.static_url`` when passed a caller-package relative path due - to a refactoring done in 1.2a1. - -- The ``settings`` object emitted a deprecation warning any time - ``__getattr__`` was called upon it. However, there are legitimate - situations in which ``__getattr__`` is called on arbitrary objects - (e.g. ``hasattr``). Now, the ``settings`` object only emits the warning - upon successful lookup. - -Internal --------- - -- Use ``config.with_package`` in view_config decorator rather than - manufacturing a new renderer helper (cleanup). - -1.2a2 (2011-08-27) -================== - -Bug Fixes ---------- - -- When a ``renderers=`` argument is not specified to the Configurator - constructor, eagerly register and commit the default renderer set. This - permits the overriding of the default renderers, which was broken in 1.2a1 - without a commit directly after Configurator construction. - -- Mako rendering exceptions had the wrong value for an error message. - -- An include could not set a root factory successfully because the - Configurator constructor unconditionally registered one that would be - treated as if it were "the word of the user". - Features -------- -- A session factory can now be passed in using the dotted name syntax. - -1.2a1 (2011-08-24) -================== - -Features --------- - -- The ``[pshell]`` section in an ini configuration file now treats a - ``setup`` key as a dotted name that points to a callable that is passed the - bootstrap environment. It can mutate the environment as necessary for - great justice. - -- A new configuration setting named ``pyramid.includes`` is now available. - It is described in the "Environment Variables and ``.ini`` Files Settings" - narrative documentation chapter. - -- Added a ``route_prefix`` argument to the - ``pyramid.config.Configurator.include`` method. This argument allows you - to compose URL dispatch applications together. See the section entitled - "Using a Route Prefix to Compose Applications" in the "URL Dispatch" - narrative documentation chapter. - -- Added a ``pyramid.security.NO_PERMISSION_REQUIRED`` constant for use in - ``permission=`` statements to view configuration. This constant has a - value of the string ``__no_permission_required__``. This string value was - previously referred to in documentation; now the documentation uses the - constant. - -- Added a decorator-based way to configure a response adapter: - ``pyramid.response.response_adapter``. This decorator has the same use as - ``pyramid.config.Configurator.add_response_adapter`` but it's declarative. - -- The ``pyramid.events.BeforeRender`` event now has an attribute named - ``rendering_val``. This can be used to introspect the value returned by a - view in a BeforeRender subscriber. - -- New configurator directive: ``pyramid.config.Configurator.add_tween``. - This directive adds a "tween". A "tween" is used to wrap the Pyramid - router's primary request handling function. This is a feature may be used - by Pyramid framework extensions, to provide, for example, view timing - support and as a convenient place to hang bookkeeping code. - - Tweens are further described in the narrative docs section in the Hooks - chapter, named "Registering Tweens". - -- New paster command ``paster ptweens``, which prints the current "tween" - configuration for an application. See the section entitled "Displaying - Tweens" in the Command-Line Pyramid chapter of the narrative documentation - for more info. - -- The Pyramid debug logger now uses the standard logging configuration - (usually set up by Paste as part of startup). This means that output from - e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the - normal logging channels. The logger name of the debug logger will be the - package name of the *caller* of the Configurator's constructor. - -- A new attribute is available on request objects: ``exc_info``. Its value - will be ``None`` until an exception is caught by the Pyramid router, after - which it will be the result of ``sys.exc_info()``. - -- ``pyramid.testing.DummyRequest`` now implements the - ``add_finished_callback`` and ``add_response_callback`` methods. - -- New methods of the ``pyramid.config.Configurator`` class: - ``set_authentication_policy`` and ``set_authorization_policy``. These are - meant to be consumed mostly by add-on authors. - -- New Configurator method: ``set_root_factory``. - -- Pyramid no longer eagerly commits some default configuration statements at - Configurator construction time, which permits values passed in as - constructor arguments (e.g. ``authentication_policy`` and - ``authorization_policy``) to override the same settings obtained via an - "include". - -- Better Mako rendering exceptions via - ``pyramid.mako_templating.MakoRenderingException`` - -- New request methods: ``current_route_url``, ``current_route_path``, and - ``static_path``. - -- New functions in ``pyramid.url``: ``current_route_path`` and - ``static_path``. - -- The ``pyramid.request.Request.static_url`` API (and its brethren - ``pyramid.request.Request.static_path``, ``pyramid.url.static_url``, and - ``pyramid.url.static_path``) now accept an asbolute filename as a "path" - argument. This will generate a URL to an asset as long as the filename is - in a directory which was previously registered as a static view. - Previously, trying to generate a URL to an asset using an absolute file - path would raise a ValueError. - -- The ``RemoteUserAuthenticationPolicy ``, ``AuthTktAuthenticationPolicy``, - and ``SessionAuthenticationPolicy`` constructors now accept an additional - keyword argument named ``debug``. By default, this keyword argument is - ``False``. When it is ``True``, debug information will be sent to the - Pyramid debug logger (usually on stderr) when the ``authenticated_userid`` - or ``effective_principals`` method is called on any of these policies. The - output produced can be useful when trying to diagnose - authentication-related problems. - -- New view predicate: ``match_param``. Example: a view added via - ``config.add_view(aview, match_param='action=edit')`` will be called only - when the ``request.matchdict`` has a value inside it named ``action`` with - a value of ``edit``. - -Internal --------- - -- The Pyramid "exception view" machinery is now implemented as a "tween" - (``pyramid.tweens.excview_tween_factory``). - -- WSGIHTTPException (HTTPFound, HTTPNotFound, etc) now has a new API named - "prepare" which renders the body and content type when it is provided with - a WSGI environ. Required for debug toolbar. - -- Once ``__call__`` or ``prepare`` is called on a WSGIHTTPException, the body - will be set, and subsequent calls to ``__call__`` will always return the - same body. Delete the body attribute to rerender the exception body. - -- Previously the ``pyramid.events.BeforeRender`` event *wrapped* a dictionary - (it addressed it as its ``_system`` attribute). Now it *is* a dictionary - (it inherits from ``dict``), and it's the value that is passed to templates - as a top-level dictionary. - -- The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and - ``current_route_url`` functions in the ``pyramid.url`` package now delegate - to a method on the request they've been passed, instead of the other way - around. The pyramid.request.Request object now inherits from a mixin named - pyramid.url.URLMethodsMixin to make this possible, and all url/path - generation logic is embedded in this mixin. - -- Refactor ``pyramid.config`` into a package. - -- Removed the ``_set_security_policies`` method of the Configurator. +- Python 3.2 compatibility (except for Paste scaffolding and paster commands, + which do not work, because Paste has not been ported to Python 3 yet). -- Moved the ``StaticURLInfo`` class from ``pyramid.static`` to - ``pyramid.config.views``. - -- Move the ``Settings`` class from ``pyramid.settings`` to - ``pyramid.config.settings``. - -- Move the ``OverrideProvider``, ``PackageOverrides``, ``DirectoryOverride``, - and ``FileOverride`` classes from ``pyramid.asset`` to - ``pyramid.config.assets``. - -Deprecations ------------- - -- All Pyramid-related deployment settings (e.g. ``debug_all``, - ``debug_notfound``) are now meant to be prefixed with the prefix - ``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The - old non-prefixed settings will continue to work indefinitely but supplying - them may eventually print a deprecation warning. All scaffolds and - tutorials have been changed to use prefixed settings. - -- The ``settings`` dictionary now raises a deprecation warning when you - attempt to access its values via ``__getattr__`` instead of - via ``__getitem__``. +- Lone instance methods can now be treated as view callables (see + https://github.com/Pylons/pyramid/pull/283). Backwards Incompatibilities --------------------------- -- If a string is passed as the ``debug_logger`` parameter to a Configurator, - that string is considered to be the name of a global Python logger rather - than a dotted name to an instance of a logger. - -- The ``pyramid.config.Configurator.include`` method now accepts only a - single ``callable`` argument (a sequence of callables used to be - permitted). If you are passing more than one ``callable`` to - ``pyramid.config.Configurator.include``, it will break. You now must now - instead make a separate call to the method for each callable. This change - was introduced to support the ``route_prefix`` feature of include. - -- It may be necessary to more strictly order configuration route and view - statements when using an "autocommitting" Configurator. In the past, it - was possible to add a view which named a route name before adding a route - with that name when you used an autocommitting configurator. For example:: - - config = Configurator(autocommit=True) - config.add_view('my.pkg.someview', route_name='foo') - config.add_route('foo', '/foo') - - The above will raise an exception when the view attempts to add itself. - Now you must add the route before adding the view:: - - config = Configurator(autocommit=True) - config.add_route('foo', '/foo') - config.add_view('my.pkg.someview', route_name='foo') - - This won't effect "normal" users, only people who have legacy BFG codebases - that used an autommitting configurator and possibly tests that use the - configurator API (the configurator returned by ``pyramid.testing.setUp`` is - an autocommitting configurator). The right way to get around this is to - use a non-autocommitting configurator (the default), which does not have - these directive ordering requirements. - -- The ``pyramid.config.Configurator.add_route`` directive no longer returns a - route object. This change was required to make route vs. view - configuration processing work properly. - -Documentation -------------- - -- Narrative and API documentation which used the ``route_url``, - ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` - functions in the ``pyramid.url`` package have now been changed to use - eponymous methods of the request instead. - -- Added a section entitled "Using a Route Prefix to Compose Applications" to - the "URL Dispatch" narrative documentation chapter. - -- Added a new module to the API docs: ``pyramid.tweens``. - -- Added a "Registering Tweens" section to the "Hooks" narrative chapter. +- Pyramid no longer runs on Python 2.5 (which includes the most recent + release of Jython, and the current version of GAE). -- Added a "Displaying Tweens" section to the "Command-Line Pyramid" narrative - chapter. - -- Added documentation for the ``pyramid.tweens`` and ``pyramid.includes`` - configuration settings to the "Environment Variables and ``.ini`` Files - Settings" chapter. - -- Added a Logging chapter to the narrative docs (based on the Pylons logging - docs, thanks Phil). - -- Added a Paste chapter to the narrative docs (moved content from the Project - chapter). - -- Added the ``pyramid.interfaces.IDict`` interface representing the methods - of a dictionary, for documentation purposes only (IMultiDict and - IBeforeRender inherit from it). - -- All tutorials now use - The ``route_url``, ``route_path``, - ``resource_url``, ``static_url``, and ``current_route_url`` methods of the - request rather than the function variants imported from ``pyramid.url``. - -- The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather - than the ``repoze.zodbconn`` package to provide ZODB integration. - -Dependency Changes ------------------- - -- Pyramid now relies on PasteScript >= 1.7.4. This version contains a - feature important for allowing flexible logging configuration. - -Scaffolds ----------- - -- All scaffolds now use the ``pyramid_tm`` package rather than the - ``repoze.tm2`` middleware to manage transaction management. - -- The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the - ``repoze.zodbconn`` package to provide ZODB integration. - -- All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the - ``WebError`` package to provide interactive debugging features. - -- Projects created via a scaffold no longer depend on the ``WebError`` - package at all; configuration in the ``production.ini`` file which used to - require its ``error_catcher`` middleware has been removed. Configuring - error catching / email sending is now the domain of the ``pyramid_exclog`` - package (see https://docs.pylonsproject.org/projects/pyramid_exclog/dev/). +Dependencies +------------ -Bug Fixes ---------- +- Pyramid no longer depends on the zope.component package, except as a + testing dependency. -- Fixed an issue with the default renderer not working at certain times. See - https://github.com/Pylons/pyramid/issues/249 +- Pyramid now depends on a zope.interface>=3.8.0, WebOb>=1.2dev, + repoze.lru>=0.4, zope.deprecation>=3.5.0, translationstring>=0.4 (for + Python 3 compatibility purposes). It also, as a testing dependency, + depends on WebTest>=1.3.1 for the same reason. diff --git a/HISTORY.txt b/HISTORY.txt index 5cabb0111..956f07362 100644 --- a/HISTORY.txt +++ b/HISTORY.txt @@ -1,3 +1,470 @@ +1.2 (2011-09-12) +================ + +Features +-------- + +- Route pattern replacement marker names can now begin with an underscore. + See https://github.com/Pylons/pyramid/issues/276. + +1.2b3 (2011-09-11) +================== + +Bug Fixes +--------- + +- The route prefix was not taken into account when a static view was added in + an "include". See https://github.com/Pylons/pyramid/issues/266 . + +1.2b2 (2011-09-08) +================== + +Bug Fixes +--------- + +- The 1.2b1 tarball was a brownbag (particularly for Windows users) because + it contained filenames with stray quotation marks in inappropriate places. + We depend on ``setuptools-git`` to produce release tarballs, and when it + was run to produce the 1.2b1 tarball, it didn't yet cope well with files + present in git repositories with high-order characters in their filenames. + +Documentation +------------- + +- Minor tweaks to the "Introduction" narrative chapter example app and + wording. + +1.2b1 (2011-09-08) +================== + +Bug Fixes +--------- + +- Sometimes falling back from territory translations (``de_DE``) to language + translations (``de``) would not work properly when using a localizer. See + https://github.com/Pylons/pyramid/issues/263 + +- The static file serving machinery could not serve files that started with a + ``.`` (dot) character. + +- Static files with high-order (super-ASCII) characters in their names could + not be served by a static view. The static file serving machinery + inappropriately URL-quoted path segments in filenames when asking for files + from the filesystem. + +- Within ``pyramid.traversal.traversal_path`` , canonicalize URL segments + from UTF-8 to Unicode before checking whether a segment matches literally + one of ``.``, the empty string, or ``..`` in case there's some sneaky way + someone might tunnel those strings via UTF-8 that don't match the literals + before decoded. + +Documentation +------------- + +- Added a "What Makes Pyramid Unique" section to the Introduction narrative + chapter. + +1.2a6 (2011-09-06) +================== + +Bug Fixes +--------- + +- AuthTktAuthenticationPolicy with a ``reissue_time`` interfered with logout. + See https://github.com/Pylons/pyramid/issues/262. + +Internal +-------- + +- Internalize code previously depended upon as imports from the + ``paste.auth`` module (futureproof). + +- Replaced use of ``paste.urlparser.StaticURLParser`` with a derivative of + Chris Rossi's "happy" static file serving code (futureproof). + +- Fixed test suite; on some systems tests would fail due to indeterminate + test run ordering and a double-push-single-pop of a shared test variable. + +Behavior Differences +-------------------- + +- An ETag header is no longer set when serving a static file. A + Last-Modified header is set instead. + +- Static file serving no longer supports the ``wsgi.file_wrapper`` extension. + +- Instead of returning a ``403 Forbidden`` error when a static file is served + that cannot be accessed by the Pyramid process' user due to file + permissions, an IOError (or similar) will be raised. + +Scaffolds +--------- + +- All scaffolds now send the ``cache_max_age`` parameter to the + ``add_static_view`` method. + +1.2a5 (2011-09-04) +================== + +Bug Fixes +--------- + +- The ``route_prefix`` of a configurator was not properly taken into account + when registering routes in certain circumstances. See + https://github.com/Pylons/pyramid/issues/260 + +Dependencies +------------ + +- The ``zope.configuration`` package is no longer a dependency. + +1.2a4 (2011-09-02) +================== + +Features +-------- + +- Support an ``onerror`` keyword argument to + ``pyramid.config.Configurator.scan()``. This onerror keyword argument is + passed to ``venusian.Scanner.scan()`` to influence error behavior when + an exception is raised during scanning. + +- The ``request_method`` predicate argument to + ``pyramid.config.Configurator.add_view`` and + ``pyramid.config.Configurator.add_route`` is now permitted to be a tuple of + HTTP method names. Previously it was restricted to being a string + representing a single HTTP method name. + +- Undeprecated ``pyramid.traversal.find_model``, + ``pyramid.traversal.model_path``, ``pyramid.traversal.model_path_tuple``, + and ``pyramid.url.model_url``, which were all deprecated in Pyramid 1.0. + There's just not much cost to keeping them around forever as aliases to + their renamed ``resource_*`` prefixed functions. + +- Undeprecated ``pyramid.view.bfg_view``, which was deprecated in Pyramid + 1.0. This is a low-cost alias to ``pyramid.view.view_config`` which we'll + just keep around forever. + +Dependencies +------------ + +- Pyramid now requires Venusian 1.0a1 or better to support the ``onerror`` + keyword argument to ``pyramid.config.Configurator.scan``. + +1.2a3 (2011-08-29) +================== + +Bug Fixes +--------- + +- Pyramid did not properly generate static URLs using + ``pyramid.url.static_url`` when passed a caller-package relative path due + to a refactoring done in 1.2a1. + +- The ``settings`` object emitted a deprecation warning any time + ``__getattr__`` was called upon it. However, there are legitimate + situations in which ``__getattr__`` is called on arbitrary objects + (e.g. ``hasattr``). Now, the ``settings`` object only emits the warning + upon successful lookup. + +Internal +-------- + +- Use ``config.with_package`` in view_config decorator rather than + manufacturing a new renderer helper (cleanup). + +1.2a2 (2011-08-27) +================== + +Bug Fixes +--------- + +- When a ``renderers=`` argument is not specified to the Configurator + constructor, eagerly register and commit the default renderer set. This + permits the overriding of the default renderers, which was broken in 1.2a1 + without a commit directly after Configurator construction. + +- Mako rendering exceptions had the wrong value for an error message. + +- An include could not set a root factory successfully because the + Configurator constructor unconditionally registered one that would be + treated as if it were "the word of the user". + +Features +-------- + +- A session factory can now be passed in using the dotted name syntax. + +1.2a1 (2011-08-24) +================== + +Features +-------- + +- The ``[pshell]`` section in an ini configuration file now treats a + ``setup`` key as a dotted name that points to a callable that is passed the + bootstrap environment. It can mutate the environment as necessary for + great justice. + +- A new configuration setting named ``pyramid.includes`` is now available. + It is described in the "Environment Variables and ``.ini`` Files Settings" + narrative documentation chapter. + +- Added a ``route_prefix`` argument to the + ``pyramid.config.Configurator.include`` method. This argument allows you + to compose URL dispatch applications together. See the section entitled + "Using a Route Prefix to Compose Applications" in the "URL Dispatch" + narrative documentation chapter. + +- Added a ``pyramid.security.NO_PERMISSION_REQUIRED`` constant for use in + ``permission=`` statements to view configuration. This constant has a + value of the string ``__no_permission_required__``. This string value was + previously referred to in documentation; now the documentation uses the + constant. + +- Added a decorator-based way to configure a response adapter: + ``pyramid.response.response_adapter``. This decorator has the same use as + ``pyramid.config.Configurator.add_response_adapter`` but it's declarative. + +- The ``pyramid.events.BeforeRender`` event now has an attribute named + ``rendering_val``. This can be used to introspect the value returned by a + view in a BeforeRender subscriber. + +- New configurator directive: ``pyramid.config.Configurator.add_tween``. + This directive adds a "tween". A "tween" is used to wrap the Pyramid + router's primary request handling function. This is a feature may be used + by Pyramid framework extensions, to provide, for example, view timing + support and as a convenient place to hang bookkeeping code. + + Tweens are further described in the narrative docs section in the Hooks + chapter, named "Registering Tweens". + +- New paster command ``paster ptweens``, which prints the current "tween" + configuration for an application. See the section entitled "Displaying + Tweens" in the Command-Line Pyramid chapter of the narrative documentation + for more info. + +- The Pyramid debug logger now uses the standard logging configuration + (usually set up by Paste as part of startup). This means that output from + e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the + normal logging channels. The logger name of the debug logger will be the + package name of the *caller* of the Configurator's constructor. + +- A new attribute is available on request objects: ``exc_info``. Its value + will be ``None`` until an exception is caught by the Pyramid router, after + which it will be the result of ``sys.exc_info()``. + +- ``pyramid.testing.DummyRequest`` now implements the + ``add_finished_callback`` and ``add_response_callback`` methods. + +- New methods of the ``pyramid.config.Configurator`` class: + ``set_authentication_policy`` and ``set_authorization_policy``. These are + meant to be consumed mostly by add-on authors. + +- New Configurator method: ``set_root_factory``. + +- Pyramid no longer eagerly commits some default configuration statements at + Configurator construction time, which permits values passed in as + constructor arguments (e.g. ``authentication_policy`` and + ``authorization_policy``) to override the same settings obtained via an + "include". + +- Better Mako rendering exceptions via + ``pyramid.mako_templating.MakoRenderingException`` + +- New request methods: ``current_route_url``, ``current_route_path``, and + ``static_path``. + +- New functions in ``pyramid.url``: ``current_route_path`` and + ``static_path``. + +- The ``pyramid.request.Request.static_url`` API (and its brethren + ``pyramid.request.Request.static_path``, ``pyramid.url.static_url``, and + ``pyramid.url.static_path``) now accept an asbolute filename as a "path" + argument. This will generate a URL to an asset as long as the filename is + in a directory which was previously registered as a static view. + Previously, trying to generate a URL to an asset using an absolute file + path would raise a ValueError. + +- The ``RemoteUserAuthenticationPolicy ``, ``AuthTktAuthenticationPolicy``, + and ``SessionAuthenticationPolicy`` constructors now accept an additional + keyword argument named ``debug``. By default, this keyword argument is + ``False``. When it is ``True``, debug information will be sent to the + Pyramid debug logger (usually on stderr) when the ``authenticated_userid`` + or ``effective_principals`` method is called on any of these policies. The + output produced can be useful when trying to diagnose + authentication-related problems. + +- New view predicate: ``match_param``. Example: a view added via + ``config.add_view(aview, match_param='action=edit')`` will be called only + when the ``request.matchdict`` has a value inside it named ``action`` with + a value of ``edit``. + +Internal +-------- + +- The Pyramid "exception view" machinery is now implemented as a "tween" + (``pyramid.tweens.excview_tween_factory``). + +- WSGIHTTPException (HTTPFound, HTTPNotFound, etc) now has a new API named + "prepare" which renders the body and content type when it is provided with + a WSGI environ. Required for debug toolbar. + +- Once ``__call__`` or ``prepare`` is called on a WSGIHTTPException, the body + will be set, and subsequent calls to ``__call__`` will always return the + same body. Delete the body attribute to rerender the exception body. + +- Previously the ``pyramid.events.BeforeRender`` event *wrapped* a dictionary + (it addressed it as its ``_system`` attribute). Now it *is* a dictionary + (it inherits from ``dict``), and it's the value that is passed to templates + as a top-level dictionary. + +- The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and + ``current_route_url`` functions in the ``pyramid.url`` package now delegate + to a method on the request they've been passed, instead of the other way + around. The pyramid.request.Request object now inherits from a mixin named + pyramid.url.URLMethodsMixin to make this possible, and all url/path + generation logic is embedded in this mixin. + +- Refactor ``pyramid.config`` into a package. + +- Removed the ``_set_security_policies`` method of the Configurator. + +- Moved the ``StaticURLInfo`` class from ``pyramid.static`` to + ``pyramid.config.views``. + +- Move the ``Settings`` class from ``pyramid.settings`` to + ``pyramid.config.settings``. + +- Move the ``OverrideProvider``, ``PackageOverrides``, ``DirectoryOverride``, + and ``FileOverride`` classes from ``pyramid.asset`` to + ``pyramid.config.assets``. + +Deprecations +------------ + +- All Pyramid-related deployment settings (e.g. ``debug_all``, + ``debug_notfound``) are now meant to be prefixed with the prefix + ``pyramid.``. For example: ``debug_all`` -> ``pyramid.debug_all``. The + old non-prefixed settings will continue to work indefinitely but supplying + them may eventually print a deprecation warning. All scaffolds and + tutorials have been changed to use prefixed settings. + +- The ``settings`` dictionary now raises a deprecation warning when you + attempt to access its values via ``__getattr__`` instead of + via ``__getitem__``. + +Backwards Incompatibilities +--------------------------- + +- If a string is passed as the ``debug_logger`` parameter to a Configurator, + that string is considered to be the name of a global Python logger rather + than a dotted name to an instance of a logger. + +- The ``pyramid.config.Configurator.include`` method now accepts only a + single ``callable`` argument (a sequence of callables used to be + permitted). If you are passing more than one ``callable`` to + ``pyramid.config.Configurator.include``, it will break. You now must now + instead make a separate call to the method for each callable. This change + was introduced to support the ``route_prefix`` feature of include. + +- It may be necessary to more strictly order configuration route and view + statements when using an "autocommitting" Configurator. In the past, it + was possible to add a view which named a route name before adding a route + with that name when you used an autocommitting configurator. For example:: + + config = Configurator(autocommit=True) + config.add_view('my.pkg.someview', route_name='foo') + config.add_route('foo', '/foo') + + The above will raise an exception when the view attempts to add itself. + Now you must add the route before adding the view:: + + config = Configurator(autocommit=True) + config.add_route('foo', '/foo') + config.add_view('my.pkg.someview', route_name='foo') + + This won't effect "normal" users, only people who have legacy BFG codebases + that used an autommitting configurator and possibly tests that use the + configurator API (the configurator returned by ``pyramid.testing.setUp`` is + an autocommitting configurator). The right way to get around this is to + use a non-autocommitting configurator (the default), which does not have + these directive ordering requirements. + +- The ``pyramid.config.Configurator.add_route`` directive no longer returns a + route object. This change was required to make route vs. view + configuration processing work properly. + +Documentation +------------- + +- Narrative and API documentation which used the ``route_url``, + ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` + functions in the ``pyramid.url`` package have now been changed to use + eponymous methods of the request instead. + +- Added a section entitled "Using a Route Prefix to Compose Applications" to + the "URL Dispatch" narrative documentation chapter. + +- Added a new module to the API docs: ``pyramid.tweens``. + +- Added a "Registering Tweens" section to the "Hooks" narrative chapter. + +- Added a "Displaying Tweens" section to the "Command-Line Pyramid" narrative + chapter. + +- Added documentation for the ``pyramid.tweens`` and ``pyramid.includes`` + configuration settings to the "Environment Variables and ``.ini`` Files + Settings" chapter. + +- Added a Logging chapter to the narrative docs (based on the Pylons logging + docs, thanks Phil). + +- Added a Paste chapter to the narrative docs (moved content from the Project + chapter). + +- Added the ``pyramid.interfaces.IDict`` interface representing the methods + of a dictionary, for documentation purposes only (IMultiDict and + IBeforeRender inherit from it). + +- All tutorials now use - The ``route_url``, ``route_path``, + ``resource_url``, ``static_url``, and ``current_route_url`` methods of the + request rather than the function variants imported from ``pyramid.url``. + +- The ZODB wiki tutorial now uses the ``pyramid_zodbconn`` package rather + than the ``repoze.zodbconn`` package to provide ZODB integration. + +Dependency Changes +------------------ + +- Pyramid now relies on PasteScript >= 1.7.4. This version contains a + feature important for allowing flexible logging configuration. + +Scaffolds +---------- + +- All scaffolds now use the ``pyramid_tm`` package rather than the + ``repoze.tm2`` middleware to manage transaction management. + +- The ZODB scaffold now uses the ``pyramid_zodbconn`` package rather than the + ``repoze.zodbconn`` package to provide ZODB integration. + +- All scaffolds now use the ``pyramid_debugtoolbar`` package rather than the + ``WebError`` package to provide interactive debugging features. + +- Projects created via a scaffold no longer depend on the ``WebError`` + package at all; configuration in the ``production.ini`` file which used to + require its ``error_catcher`` middleware has been removed. Configuring + error catching / email sending is now the domain of the ``pyramid_exclog`` + package (see https://docs.pylonsproject.org/projects/pyramid_exclog/dev/). + +Bug Fixes +--------- + +- Fixed an issue with the default renderer not working at certain times. See + https://github.com/Pylons/pyramid/issues/249 + + 1.1 (2011-07-22) ================ diff --git a/docs/conf.py b/docs/conf.py index 71c4f58d4..a5eaeb0fb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -106,6 +106,10 @@ today_fmt = '%B %d, %Y' # List of documents that shouldn't be included in the build. #unused_docs = [] +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_themes/README.rst',] + # List of directories, relative to source directories, that shouldn't be searched # for source files. #exclude_dirs = [] diff --git a/docs/designdefense.rst b/docs/designdefense.rst index d1b969ff4..d71f9af7f 100644 --- a/docs/designdefense.rst +++ b/docs/designdefense.rst @@ -245,7 +245,9 @@ its API is much nicer than the ZCA registry API, work on it was largely abandoned and it is not used in :app:`Pyramid`. We continued to use a ZCA registry within :app:`Pyramid` because it ultimately proved a better fit. -.. note:: We continued using ZCA registry rather than disusing it in +.. note:: + + We continued using ZCA registry rather than disusing it in favor of using the registry implementation in :mod:`repoze.component` largely because the ZCA concept of interfaces provides for use of an interface hierarchy, which is diff --git a/docs/index.rst b/docs/index.rst index d7f2f4fb6..25aaab7af 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -227,3 +227,12 @@ Index and Glossary * :ref:`glossary` * :ref:`genindex` * :ref:`search` + + +.. add glossary in hidden toc tree so it does not complain its not included + +.. toctree:: + :hidden: + + glossary + diff --git a/docs/narr/assets.rst b/docs/narr/assets.rst index 93b03fbc9..cd76f7b60 100644 --- a/docs/narr/assets.rst +++ b/docs/narr/assets.rst @@ -102,7 +102,9 @@ directory on a filesystem to an application user's browser. Use the mechanism makes a directory of static files available at a name relative to the application root URL, e.g. ``/static`` or as an external URL. -.. note:: :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a +.. note:: + + :meth:`~pyramid.config.Configurator.add_static_view` cannot serve a single file, nor can it serve a directory of static files directly relative to the root URL of a :app:`Pyramid` application. For these features, see :ref:`advanced_static`. @@ -312,7 +314,9 @@ instance of this class is actually used by the :meth:`~pyramid.config.Configurator.add_static_view` configuration method, so its behavior is almost exactly the same once it's configured. -.. warning:: The following example *will not work* for applications that use +.. warning:: + + The following example *will not work* for applications that use :term:`traversal`, it will only work if you use :term:`URL dispatch` exclusively. The root-relative route we'll be registering will always be matched before traversal takes place, subverting any views registered via diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 4afc0506b..3ab82ecf7 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -55,7 +55,9 @@ Here's some sample code that implements a minimal NotFound view callable: def notfound_view(request): return HTTPNotFound() -.. note:: When a NotFound view callable is invoked, it is passed a +.. note:: + + When a NotFound view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception that caused the not found view to be called. The value of @@ -64,7 +66,9 @@ Here's some sample code that implements a minimal NotFound view callable: ``pyramid.debug_notfound`` environment setting is true than it is when it is false. -.. warning:: When a NotFound view callable accepts an argument list as +.. warning:: + + When a NotFound view callable accepts an argument list as described in :ref:`request_and_context_view_definitions`, the ``context`` passed as the first argument to the view callable will be the :exc:`~pyramid.httpexceptions.HTTPNotFound` exception instance. If @@ -121,7 +125,9 @@ Here's some sample code that implements a minimal forbidden view: def forbidden_view(request): return Response('forbidden') -.. note:: When a forbidden view callable is invoked, it is passed a +.. note:: + + When a forbidden view callable is invoked, it is passed a :term:`request`. The ``exception`` attribute of the request will be an instance of the :exc:`~pyramid.httpexceptions.HTTPForbidden` exception that caused the forbidden view to be called. The value of @@ -1100,7 +1106,9 @@ in the ``pyramid.tweens`` list will be used as the producer of the effective declared directly "below" it, ad infinitum. The "main" Pyramid request handler is implicit, and always "at the bottom". -.. note:: Pyramid's own :term:`exception view` handling logic is implemented +.. note:: + + Pyramid's own :term:`exception view` handling logic is implemented as a tween factory function: :func:`pyramid.tweens.excview_tween_factory`. If Pyramid exception view handling is desired, and tween factories are specified via the ``pyramid.tweens`` configuration setting, the diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index aef9b59ab..bac86e982 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -518,7 +518,9 @@ negotiator is registered. def aview(request): locale = get_localizer(request) -.. note:: If you need to create a localizer for a locale use the +.. note:: + + If you need to create a localizer for a locale use the :func:`pyramid.i18n.make_localizer` function. .. index:: @@ -555,7 +557,9 @@ represented by the request. The translation returned from its ``domain`` attribute of the provided translation string as well as the locale of the localizer. -.. note:: If you're using :term:`Chameleon` templates, you don't need +.. note:: + + If you're using :term:`Chameleon` templates, you don't need to pre-translate translation strings this way. See :ref:`chameleon_translation_strings`. diff --git a/docs/narr/install.rst b/docs/narr/install.rst index a1e7ce382..e1b5eb208 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -229,7 +229,9 @@ following: New python executable in env/bin/python Installing setuptools.............done. -.. warning:: Using ``--no-site-packages`` when generating your +.. 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``, diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 8abcba3c7..3e39151a3 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -7,7 +7,9 @@ Logging :mod:`logging` module. This chapter describes how to configure logging and how to send log messages to loggers that you've configured. -.. warning:: This chapter assumes you've used a :term:`scaffold` to create a +.. warning:: + + This chapter assumes you've used a :term:`scaffold` to create a project which contains ``development.ini`` and ``production.ini`` files which help configure logging. All of the scaffolds which ship along with :app:`Pyramid` do this. If you're not using a scaffold, or if you've used diff --git a/docs/narr/muchadoabouttraversal.rst b/docs/narr/muchadoabouttraversal.rst index 6ad33c1ce..a948e57cc 100644 --- a/docs/narr/muchadoabouttraversal.rst +++ b/docs/narr/muchadoabouttraversal.rst @@ -313,6 +313,8 @@ don't require it, great: stick with :term:`URL dispatch`. But if you're using :app:`Pyramid` and you ever find that you *do* need to support one of these use cases, you'll be glad you have traversal in your toolkit. -.. note:: It is even possible to mix and match :term:`traversal` with +.. note:: + + It is even possible to mix and match :term:`traversal` with :term:`URL dispatch` in the same :app:`Pyramid` application. See the :ref:`hybrid_chapter` chapter for details. diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 10b7a5d04..345672204 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -64,7 +64,9 @@ The included scaffolds are these: URL mapping via :term:`traversal` and persistence via :term:`SQLAlchemy` -.. note:: At this time, each of these scaffolds uses the :term:`Chameleon` +.. note:: + + At this time, each of these scaffolds uses the :term:`Chameleon` templating system, which is incompatible with Jython. To use scaffolds to build applications which will run on Jython, you can try the ``pyramid_jinja2_starter`` scaffold which ships as part of the diff --git a/docs/narr/resources.rst b/docs/narr/resources.rst index 9335906a0..256f69fc3 100644 --- a/docs/narr/resources.rst +++ b/docs/narr/resources.rst @@ -160,7 +160,9 @@ resource in the resource tree, you will eventually come to the root resource, just like if you keep executing the ``cd ..`` filesystem command, eventually you will reach the filesystem root directory. -.. warning:: If your root resource has a ``__name__`` argument that is not +.. warning:: + + If your root resource has a ``__name__`` argument that is not ``None`` or the empty string, URLs returned by the :func:`~pyramid.request.Request.resource_url` function and paths generated by the :func:`~pyramid.traversal.resource_path` and @@ -229,7 +231,7 @@ this: .. code-block:: python :linenos: - url = request.resource_url(resource, request) + url = request.resource_url(resource) The ``request`` in the above example is an instance of a :app:`Pyramid` :term:`request` object. diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 6412c070d..052843a23 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -46,7 +46,9 @@ within the body of a view callable like so: {'foo':1, 'bar':2}, request=request) -.. warning:: Earlier iterations of this documentation +.. warning:: + + Earlier iterations of this documentation (pre-version-1.3) encouraged the application developer to use ZPT-specific APIs such as :func:`pyramid.chameleon_zpt.render_template_to_response` and diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index a6e46515f..2fcbce507 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -190,7 +190,7 @@ at the end of the segment represented by ``{name}.html`` (it only contains To capture both segments, two replacement markers can be used: .. code-block:: text - + foo/{name}.{ext} The literal path ``/foo/biz.html`` will match the above route pattern, and @@ -256,10 +256,10 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text - foo/1/2/ -> + foo/1/2/ -> {'baz':u'1', 'bar':u'2', 'fizzle':()} - foo/abc/def/a/b/c -> + foo/abc/def/a/b/c -> {'baz':u'abc', 'bar':u'def', 'fizzle':(u'a', u'b', u'c')} Note that when a ``*stararg`` remainder match is matched, the value put into @@ -288,7 +288,7 @@ split by segment. Changing the regular expression used to match a marker can also capture the remainder of the URL, for example: .. code-block:: text - + foo/{baz}/{bar}{fizzle:.*} The above pattern will match these URLs, generating the following matchdicts: @@ -353,7 +353,9 @@ 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 +.. 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. @@ -646,7 +648,9 @@ 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``. -.. note:: the ``static`` argument to +.. note:: + + the ``static`` argument to :meth:`~pyramid.config.Configurator.add_route` is new as of :app:`Pyramid` 1.1. @@ -695,10 +699,10 @@ route with an appended slash. .. warning:: - You **should not** rely on this mechanism to redirect ``POST`` requests. - The redirect of the slash-appending not found view will turn a ``POST`` - request into a ``GET``, losing any ``POST`` data in the original - request. + You **should not** rely on this mechanism to redirect ``POST`` requests. + The redirect of the slash-appending not found view will turn a ``POST`` + request into a ``GET``, losing any ``POST`` data in the original + request. To configure the slash-appending not found view in your application, change the application's startup configuration, adding the following stanza: @@ -706,7 +710,7 @@ the application's startup configuration, adding the following stanza: .. code-block:: python :linenos: - config.add_view('pyramid.view.append_slash_notfound_view', + config.add_view('pyramid.view.append_slash_notfound_view', context='pyramid.httpexceptions.HTTPNotFound') See :ref:`view_module` and :ref:`changing_the_notfound_view` for more @@ -768,7 +772,7 @@ which you started the application from. For example: :linenos: [chrism@thinko pylonsbasic]$ PYRAMID_DEBUG_ROUTEMATCH=true \ - bin/paster serve development.ini + bin/paster serve development.ini Starting server in PID 13586. serving on 0.0.0.0:6543 view at http://127.0.0.1:6543 2010-12-16 14:45:19,956 no route matched for url \ @@ -809,7 +813,7 @@ will have their pattern prefixed with the value of ``route_prefix``. This can be used to help mount a set of routes at a different location than the included callable's author intended while still maintaining the same route names. For example: - + .. code-block:: python :linenos: @@ -817,7 +821,7 @@ names. For example: def users_include(config): config.add_route('show_users', '/show') - + def main(global_config, **settings): config = Configurator() config.include(users_include, route_prefix='/users') @@ -840,7 +844,7 @@ will be prepended with the first: def timing_include(config): config.add_route('show_times', /times') - + def users_include(config): config.add_route('show_users', '/show') config.include(timing_include, route_prefix='/timing') @@ -867,7 +871,7 @@ that may be added in the future. For example: def timing_include(config): config.add_route('timing.show_times', /times') - + def users_include(config): config.add_route('users.show_users', '/show') config.include(timing_include, route_prefix='/timing') @@ -909,7 +913,7 @@ For example: num_one_two_or_three = any_of('num', 'one', 'two', 'three') - config.add_route('route_to_num', '/{num}', + config.add_route('route_to_num', '/{num}', custom_predicates=(num_one_two_or_three,)) The above ``any_of`` function generates a predicate which ensures that the @@ -940,7 +944,7 @@ instance, a predicate might do some type conversion of values: ymd_to_int = integers('year', 'month', 'day') - config.add_route('ymd', '/{year}/{month}/{day}', + config.add_route('ymd', '/{year}/{month}/{day}', custom_predicates=(ymd_to_int,)) Note that a conversion predicate is still a predicate so it must return @@ -963,7 +967,7 @@ expressions specifying requirements for that marker. For instance: ymd_to_int = integers('year', 'month', 'day') - config.add_route('ymd', '/{year:\d+}/{month:\d+}/{day:\d+}', + config.add_route('ymd', '/{year:\d+}/{month:\d+}/{day:\d+}', custom_predicates=(ymd_to_int,)) Now the try/except is no longer needed because the route will not match at @@ -1001,13 +1005,54 @@ the route in a set of route predicates: config.add_route('y', '/{year}', custom_predicates=(twenty_ten,)) config.add_route('ym', '/{year}/{month}', custom_predicates=(twenty_ten,)) - config.add_route('ymd', '/{year}/{month}/{day}', + config.add_route('ymd', '/{year}/{month}/{day}', custom_predicates=(twenty_ten,)) The above predicate, when added to a number of route configurations ensures that the year match argument is '2010' if and only if the route name is 'ymd', 'ym', or 'y'. +You can also caption the predicates by setting the ``__text__`` attribute. This +will help you with the ``paster pviews`` command (see +:ref:`displaying_application_routes`) and the ``pyramid_debugtoolbar``. + +If a predicate is a class just add __text__ property in a standard manner. + +.. code-block:: python + :linenos: + + class DummyCustomPredicate1(object): + def __init__(self): + self.__text__ = 'my custom class predicate' + + class DummyCustomPredicate2(object): + __text__ = 'my custom class predicate' + +If a predicate is a method you'll need to assign it after method declaration +(see `PEP 232 <http://www.python.org/dev/peps/pep-0232/>`_) + +.. code-block:: python + :linenos: + + def custom_predicate(): + pass + custom_predicate.__text__ = 'my custom method predicate' + +If a predicate is a classmethod using @classmethod will not work, but you can +still easily do it by wrapping it in classmethod call. + +.. code-block:: python + :linenos: + + def classmethod_predicate(): + pass + classmethod_predicate.__text__ = 'my classmethod predicate' + classmethod_predicate = classmethod(classmethod_predicate) + +Same will work with staticmethod, just use ``staticmethod`` instead of +``classmethod``. + + See also :class:`pyramid.interfaces.IRoute` for more API documentation about route objects. @@ -1030,7 +1075,7 @@ callable ultimately found via :term:`view lookup`. .. code-block:: python :linenos: - config.add_route('abc', '/abc', + config.add_route('abc', '/abc', factory='myproject.resources.root_factory') config.add_view('myproject.views.theview', route_name='abc') @@ -1098,7 +1143,9 @@ permission. Obviously you can do more generic things than inspect the routes match dict to see if the ``article`` argument matches a particular string; our sample ``Article`` factory class is not very ambitious. -.. note:: See :ref:`security_chapter` for more information about +.. note:: + + See :ref:`security_chapter` for more information about :app:`Pyramid` security and ACLs. .. index:: diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index 9d783f8cb..ed3a84118 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -7,7 +7,9 @@ application is typically a simple Python function that accepts two parameters: :term:`context` and :term:`request`. A view callable is assumed to return a :term:`response` object. -.. note:: A :app:`Pyramid` view can also be defined as callable +.. note:: + + A :app:`Pyramid` view can also be defined as callable which accepts *only* a :term:`request` argument. You'll see this one-argument pattern used in other :app:`Pyramid` tutorials and applications. Either calling convention will work in any @@ -253,7 +255,9 @@ the below: .. literalinclude:: src/views/tutorial/templates/view.pt :language: xml -.. note:: The names available for our use in a template are always those that +.. note:: + + The names available for our use in a template are always those that are present in the dictionary returned by the view callable. But our templates make use of a ``request`` object that none of our tutorial views return in their dictionary. This value appears as if "by magic". diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 8f6dd6455..234f91246 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -7,7 +7,9 @@ application is typically a simple Python function that accepts a single parameter named :term:`request`. A view callable is assumed to return a :term:`response` object. -.. note:: A :app:`Pyramid` view can also be defined as callable +.. note:: + + A :app:`Pyramid` view can also be defined as callable which accepts *two* arguments: a :term:`context` and a :term:`request`. You'll see this two-argument pattern used in other :app:`Pyramid` tutorials and applications. Either calling diff --git a/pyramid/chameleon_text.py b/pyramid/chameleon_text.py index 0539e0f29..872d3b920 100644 --- a/pyramid/chameleon_text.py +++ b/pyramid/chameleon_text.py @@ -59,7 +59,9 @@ def get_renderer(path): package-relative path, an absolute path, or a :term:`asset specification`. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use :func:`pyramid.renderers.get_renderer` instead. """ package = caller_package() @@ -77,7 +79,9 @@ def get_template(path): The ``path`` argument may be a package-relative path, an absolute path, or a :term:`asset specification`. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use the ``implementation()`` method of a template renderer retrieved via :func:`pyramid.renderers.get_renderer` instead. """ @@ -99,7 +103,9 @@ def render_template(path, **kw): names to the template, and so may be used within the template itself. Returns a string. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use :func:`pyramid.renderers.render` instead. """ package = caller_package() @@ -121,7 +127,9 @@ def render_template_to_response(path, **kw): itself. Returns a :term:`Response` object with the body as the template result. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use :func:`pyramid.renderers.render_to_response` instead. """ package = caller_package() diff --git a/pyramid/chameleon_zpt.py b/pyramid/chameleon_zpt.py index dd1c47dcb..aa6f89e07 100644 --- a/pyramid/chameleon_zpt.py +++ b/pyramid/chameleon_zpt.py @@ -58,7 +58,9 @@ def get_renderer(path): package-relative path, an absolute path, or a :term:`asset specification`. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use :func:`pyramid.renderers.get_renderer` instead. """ package = caller_package() @@ -76,7 +78,9 @@ def get_template(path): The ``path`` argument may be a package-relative path, an absolute path, or a :term:`asset specification`. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use the ``implementation()`` method of a template renderer retrieved via :func:`pyramid.renderers.get_renderer` instead. """ @@ -98,7 +102,9 @@ def render_template(path, **kw): names to the template, and so may be used within the template itself. Returns a string. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use :func:`pyramid.renderers.render` instead. """ package = caller_package() @@ -120,7 +126,9 @@ def render_template_to_response(path, **kw): itself. Returns a :term:`Response` object with the body as the template result. - .. warning:: This API is deprecated in :app:`Pyramid` 1.0. Use + .. warning:: + + This API is deprecated in :app:`Pyramid` 1.0. Use :func:`pyramid.renderers.render_to_response` instead. """ package = caller_package() diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py index 3b5d88d5f..8085bbc79 100644 --- a/pyramid/config/__init__.py +++ b/pyramid/config/__init__.py @@ -146,9 +146,10 @@ class Configurator( same. See :ref:`adding_renderer_globals`. By default, it is ``None``, which means use no renderer globals factory. - .. warning:: as of Pyramid 1.1, ``renderer_globals_factory`` is - deprecated. Instead, use a BeforeRender event subscriber as per - :ref:`beforerender_event`. + .. warning:: + + as of Pyramid 1.1, ``renderer_globals_factory`` is deprecated. Instead, + use a BeforeRender event subscriber as per :ref:`beforerender_event`. If ``default_permission`` is passed, it should be a :term:`permission` string to be used as the default permission for @@ -294,7 +295,7 @@ class Configurator( if debug_logger is None: debug_logger = logging.getLogger(self.package_name) - + registry.registerUtility(debug_logger, IDebugLogger) for name, renderer in DEFAULT_RENDERERS: @@ -367,7 +368,7 @@ class Configurator( tweens = aslist(registry.settings.get('pyramid.tweens', [])) for factory in tweens: self._add_tween(factory, explicit=True) - + includes = aslist(registry.settings.get('pyramid.includes', [])) for inc in includes: self.include(inc) @@ -563,7 +564,7 @@ class Configurator( ``route_prefix``. This can be used to help mount a set of routes at a different location than the included callable's author intended while still maintaining the same route names. For example: - + .. code-block:: python :linenos: @@ -571,7 +572,7 @@ class Configurator( def included(config): config.add_route('show_users', '/show') - + def main(global_config, **settings): config = Configurator() config.include(included, route_prefix='/users') @@ -619,7 +620,7 @@ class Configurator( configurator.basepath = os.path.dirname(sourcefile) configurator.includepath = self.includepath + (spec,) c(configurator) - + def add_directive(self, name, directive, action_wrap=True): """ Add a directive method to the configurator. @@ -642,7 +643,7 @@ class Configurator( discriminators. ``action_wrap`` will cause the directive to be wrapped in a decorator which provides more accurate conflict cause information. - + ``add_directive`` does not participate in conflict detection, and later calls to ``add_directive`` will override earlier calls. """ diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py index 4b3fa5a9d..0e59f9286 100644 --- a/pyramid/config/factories.py +++ b/pyramid/config/factories.py @@ -14,9 +14,11 @@ class FactoriesConfiguratorMixin(object): state. If the ``factory`` argument is ``None`` a default root factory will be registered. - .. note:: Using the ``root_factory`` argument to the - :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. + .. note:: + + Using the ``root_factory`` argument to the + :class:`pyramid.config.Configurator` constructor can be used to + achieve the same purpose. """ factory = self.maybe_dotted(factory) if factory is None: @@ -35,9 +37,11 @@ class FactoriesConfiguratorMixin(object): method is called, the ``session_factory`` argument must be a session factory callable or a :term:`dotted Python name` to that factory. - .. note:: Using the ``session_factory`` argument to the - :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. + .. note:: + + Using the ``session_factory`` argument to the + :class:`pyramid.config.Configurator` constructor can be used to + achieve the same purpose. """ session_factory = self.maybe_dotted(session_factory) def register(): @@ -54,7 +58,9 @@ class FactoriesConfiguratorMixin(object): :class:`pyramid.request.Request` class (particularly ``__call__``, and ``blank``). - .. note:: Using the ``request_factory`` argument to the + .. note:: + + Using the ``request_factory`` argument to the :class:`pyramid.config.Configurator` constructor can be used to achieve the same purpose. """ diff --git a/pyramid/config/i18n.py b/pyramid/config/i18n.py index 0c07ad4f8..6eed99191 100644 --- a/pyramid/config/i18n.py +++ b/pyramid/config/i18n.py @@ -30,9 +30,11 @@ class I18NConfiguratorMixin(object): application. See :ref:`activating_translation` for more information. - .. note:: Using the ``locale_negotiator`` argument to the - :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. + .. note:: + + Using the ``locale_negotiator`` argument to the + :class:`pyramid.config.Configurator` constructor can be used to + achieve the same purpose. """ def register(): self._set_locale_negotiator(negotiator) diff --git a/pyramid/config/rendering.py b/pyramid/config/rendering.py index c652a980c..f70dea118 100644 --- a/pyramid/config/rendering.py +++ b/pyramid/config/rendering.py @@ -39,7 +39,7 @@ class RenderingConfiguratorMixin(object): # if name is None or the empty string, we're trying to register # a default renderer, but registerUtility is too dumb to accept None # as a name - if not name: + if not name: name = '' def register(): self.registry.registerUtility(factory, IRendererFactory, name=name) @@ -61,9 +61,13 @@ class RenderingConfiguratorMixin(object): dictionary, and therefore will be made available to the code which uses the renderer. - .. warning:: This method is deprecated as of Pyramid 1.1. + .. warning:: - .. note:: Using the ``renderer_globals_factory`` argument + This method is deprecated as of Pyramid 1.1. + + .. note:: + + Using the ``renderer_globals_factory`` argument to the :class:`pyramid.config.Configurator` constructor can be used to achieve the same purpose. """ diff --git a/pyramid/config/routes.py b/pyramid/config/routes.py index f89dcdc8d..4008a2e08 100644 --- a/pyramid/config/routes.py +++ b/pyramid/config/routes.py @@ -147,12 +147,14 @@ class RoutesConfiguratorMixin(object): pattern doesn't match the current URL, route matching continues. - .. note:: For backwards compatibility purposes (as of - :app:`Pyramid` 1.0), a ``path`` keyword argument passed - to this function will be used to represent the pattern - value if the ``pattern`` argument is ``None``. If both - ``path`` and ``pattern`` are passed, ``pattern`` wins. - + .. note:: + + For backwards compatibility purposes (as of :app:`Pyramid` 1.0), a + ``path`` keyword argument passed to this function will be used to + represent the pattern value if the ``pattern`` argument is + ``None``. If both ``path`` and ``pattern`` are passed, ``pattern`` + wins. + xhr This value should be either ``True`` or ``False``. If this @@ -249,7 +251,9 @@ class RoutesConfiguratorMixin(object): View-Related Arguments - .. warning:: The arguments described below have been deprecated as of + .. 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 @@ -267,7 +271,7 @@ class RoutesConfiguratorMixin(object): view_context .. warning:: Deprecated as of :app:`Pyramid` 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 diff --git a/pyramid/config/security.py b/pyramid/config/security.py index 31bf74e7c..935e2fd95 100644 --- a/pyramid/config/security.py +++ b/pyramid/config/security.py @@ -15,10 +15,12 @@ class SecurityConfiguratorMixin(object): of an authentication policy or a :term:`dotted Python name` that points at an instance of an authentication policy. - .. note:: Using the ``authentication_policy`` argument to the - :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. - + .. note:: + + Using the ``authentication_policy`` argument to the + :class:`pyramid.config.Configurator` constructor can be used to + achieve the same purpose. + """ def register(): self._set_authentication_policy(policy) @@ -41,9 +43,11 @@ class SecurityConfiguratorMixin(object): of an authorization policy or a :term:`dotted Python name` that points at an instance of an authorization policy. - .. note:: Using the ``authorization_policy`` argument to the - :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. + .. note:: + + Using the ``authorization_policy`` argument to the + :class:`pyramid.config.Configurator` constructor can be used to + achieve the same purpose. """ def register(): self._set_authorization_policy(policy) @@ -55,7 +59,7 @@ class SecurityConfiguratorMixin(object): 'Cannot configure an authorization policy without ' 'also configuring an authentication policy ' '(use the set_authorization_policy method)') - + # authorization policy used by view config (phase 3) and # authentication policy (phase 2) self.action(IAuthorizationPolicy, register, order=PHASE1_CONFIG) @@ -98,9 +102,11 @@ class SecurityConfiguratorMixin(object): See also :ref:`setting_a_default_permission`. - .. note:: Using the ``default_permission`` argument to the - :class:`pyramid.config.Configurator` constructor - can be used to achieve the same purpose. + .. note:: + + Using the ``default_permission`` argument to the + :class:`pyramid.config.Configurator` constructor can be used to + achieve the same purpose. """ # default permission used during view registration (phase 3) def register(): diff --git a/pyramid/config/util.py b/pyramid/config/util.py index 919862a9d..0336b103d 100644 --- a/pyramid/config/util.py +++ b/pyramid/config/util.py @@ -262,4 +262,4 @@ def as_sorted_tuple(val): val = (val,) val = tuple(sorted(val)) return val - + diff --git a/pyramid/config/views.py b/pyramid/config/views.py index 726223fd9..179d4065c 100644 --- a/pyramid/config/views.py +++ b/pyramid/config/views.py @@ -143,7 +143,7 @@ class ViewDeriver(object): def http_cached_view(self, view): if self.registry.settings.get('prevent_http_cache', False): return view - + seconds = self.kw.get('http_cache') if seconds is None: @@ -369,7 +369,7 @@ class DefaultViewMapper(object): elif self.attr: mapped_view = self.map_nonclass_attr(view) return mapped_view - + def map_class_requestonly(self, view): # its a class that has an __init__ which only accepts request attr = self.attr @@ -421,7 +421,7 @@ def requestonly(view, attr=None): ismethod = False if attr is None: attr = '__call__' - if inspect.isfunction(view): + if inspect.isroutine(view): fn = view elif inspect.isclass(view): try: @@ -719,7 +719,7 @@ class ViewsConfiguratorMixin(object): accept ``(context, request)``. The decorator must return a replacement view callable which also accepts ``(context, request)``. - + mapper A Python object or :term:`dotted Python name` which refers to a @@ -728,7 +728,7 @@ class ViewsConfiguratorMixin(object): plug-point is useful for Pyramid extension developers, but it's not very useful for 'civilians' who are just developing stock Pyramid applications. Pay no attention to the man behind the curtain. - + Predicate Arguments name @@ -1067,16 +1067,17 @@ class ViewsConfiguratorMixin(object): discriminator.extend(sorted([hash(x) for x in custom_predicates])) discriminator = tuple(discriminator) self.action(discriminator, register) - + def derive_view(self, view, attr=None, renderer=None): """ Create a :term:`view callable` using the function, instance, or class (or :term:`dotted Python name` referring to the same) provided as ``view`` object. - .. warning:: This method is typically only used by :app:`Pyramid` - framework extension authors, not by :app:`Pyramid` application - developers. + .. warning:: + + This method is typically only used by :app:`Pyramid` framework + extension authors, not by :app:`Pyramid` application developers. This is API is useful to framework extenders who create pluggable systems which need to register 'proxy' view @@ -1179,7 +1180,7 @@ class ViewsConfiguratorMixin(object): mapper=mapper, decorator=decorator, http_cache=http_cache) - + return deriver(view) @action_method @@ -1188,11 +1189,12 @@ class ViewsConfiguratorMixin(object): """ Add a default forbidden view to the current configuration state. - .. warning:: This method has been deprecated in :app:`Pyramid` - 1.0. *Do not use it for new development; it should only be - used to support older code bases which depend upon it.* See - :ref:`changing_the_forbidden_view` to see how a forbidden - view should be registered in new projects. + .. warning:: + + This method has been deprecated in :app:`Pyramid` 1.0. *Do not use + it for new development; it should only be used to support older code + bases which depend upon it.* See :ref:`changing_the_forbidden_view` + to see how a forbidden view should be registered in new projects. The ``view`` argument should be a :term:`view callable` or a :term:`dotted Python name` which refers to a view callable. @@ -1228,12 +1230,12 @@ class ViewsConfiguratorMixin(object): """ Add a default not found view to the current configuration state. - .. warning:: This method has been deprecated in - :app:`Pyramid` 1.0. *Do not use it for new development; - it should only be used to support older code bases which - depend upon it.* See :ref:`changing_the_notfound_view` to - see how a not found view should be registered in new - projects. + .. warning:: + + This method has been deprecated in :app:`Pyramid` 1.0. *Do not use + it for new development; it should only be used to support older code + bases which depend upon it.* See :ref:`changing_the_notfound_view` to + see how a not found view should be registered in new projects. The ``view`` argument should be a :term:`view callable` or a :term:`dotted Python name` which refers to a view callable. @@ -1280,7 +1282,9 @@ class ViewsConfiguratorMixin(object): See also :ref:`using_a_view_mapper`. - .. note:: Using the ``default_view_mapper`` argument to the + .. note:: + + Using the ``default_view_mapper`` argument to the :class:`pyramid.config.Configurator` constructor can be used to achieve the same purpose. """ @@ -1489,7 +1493,7 @@ class StaticURLInfo(object): attr = extra.pop('view_attr', None) - # register a route using the computed view, permission, and + # register a route using the computed view, permission, and # pattern, plus any extras passed to us via add_static_view pattern = "%s*subpath" % name # name already ends with slash if config.route_prefix: diff --git a/pyramid/events.py b/pyramid/events.py index 45edb8d02..a495d9c29 100644 --- a/pyramid/events.py +++ b/pyramid/events.py @@ -16,7 +16,7 @@ class subscriber(object): For example: .. code-block:: python - + from pyramid.events import NewRequest from pyramid.events import subscriber @@ -26,9 +26,9 @@ class subscriber(object): More than one event type can be passed as a construtor argument. The decorated subscriber will be called for each event type. - + .. code-block:: python - + from pyramid.events import NewRequest, NewResponse from pyramid.events import subscriber @@ -40,7 +40,7 @@ class subscriber(object): the function it decorates is called for every event sent: .. code-block:: python - + from pyramid.events import subscriber @subscriber() @@ -51,7 +51,7 @@ class subscriber(object): against the package or module which contains it, ala: .. code-block:: python - + from pyramid.config import Configurator config = Configurator() config.scan('somepackage_containing_subscribers') @@ -133,15 +133,16 @@ class ContextFound(object): This class implements the :class:`pyramid.interfaces.IContextFound` interface. - .. note:: As of :app:`Pyramid` 1.0, for backwards compatibility - purposes, this event may also be imported as - :class:`pyramid.events.AfterTraversal`. + .. note:: + + As of :app:`Pyramid` 1.0, for backwards compatibility purposes, this + event may also be imported as :class:`pyramid.events.AfterTraversal`. """ def __init__(self, request): self.request = request AfterTraversal = ContextFound # b/c as of 1.0 - + @implementer(IApplicationCreated) class ApplicationCreated(object): """ An instance of this class is emitted as an :term:`event` when @@ -151,11 +152,11 @@ class ApplicationCreated(object): This class implements the :class:`pyramid.interfaces.IApplicationCreated` interface. - .. note:: For backwards compatibility purposes, this class can - also be imported as - :class:`pyramid.events.WSGIApplicationCreatedEvent`. This - was the name of the event class before :app:`Pyramid` 1.0. + .. note:: + For backwards compatibility purposes, this class can also be imported as + :class:`pyramid.events.WSGIApplicationCreatedEvent`. This was the name + of the event class before :app:`Pyramid` 1.0. """ def __init__(self, app): self.app = app diff --git a/pyramid/interfaces.py b/pyramid/interfaces.py index 5f7108e89..f08bd5fbb 100644 --- a/pyramid/interfaces.py +++ b/pyramid/interfaces.py @@ -11,7 +11,9 @@ class IContextFound(Interface): documentation attached to :class:`pyramid.events.ContextFound` for more information. - .. note:: For backwards compatibility with versions of + .. note:: + + For backwards compatibility with versions of :app:`Pyramid` before 1.0, this event interface can also be imported as :class:`pyramid.interfaces.IAfterTraversal`. """ @@ -24,7 +26,7 @@ class INewRequest(Interface): begins to process a new request. See the documentation attached to :class:`pyramid.events.NewRequest` for more information.""" request = Attribute('The request object') - + class INewResponse(Interface): """ An event type that is emitted whenever any :app:`Pyramid` view returns a response. See the @@ -40,7 +42,9 @@ class IApplicationCreated(Interface): :class:`pyramid.events.ApplicationCreated` for more information. - .. note:: For backwards compatibility with :app:`Pyramid` + .. note:: + + For backwards compatibility with :app:`Pyramid` versions before 1.0, this interface can also be imported as :class:`pyramid.interfaces.IWSGIApplicationCreatedEvent`. """ @@ -153,7 +157,7 @@ class IResponse(Interface): otherwise they will be preserved.""") content_type_params = Attribute( - """A dictionary of all the parameters in the content type. This is + """A dictionary of all the parameters in the content type. This is not a view, set to change, modifications of the dict would not be applied otherwise.""") @@ -278,18 +282,18 @@ class IDict(Interface): def __setitem__(k, value): """ Set a key/value pair into the dictionary""" - + def __delitem__(k): """ Delete an item from the dictionary which is passed to the renderer as the renderer globals dictionary.""" - + def __getitem__(k): """ Return the value for key ``k`` from the dictionary or raise a KeyError if the key doesn't exist""" def __iter__(): """ Return an iterator over the keys of this dictionary """ - + def get(k, default=None): """ Return the value for key ``k`` from the renderer dictionary, or the default if no such value exists.""" @@ -331,7 +335,7 @@ class IDict(Interface): value into the dictionary under the k name passed. If a value already existed in the dictionary, return it. If a value did not exist in the dictionary, return the default""" - + def update(d): """ Update the renderer dictionary with another dictionary ``d``.""" @@ -345,7 +349,7 @@ class IBeforeRender(IDict): The event object itself provides a dictionary-like interface for adding and removing :term:`renderer globals`. The keys and values of the dictionary are those globals. For example:: - + from repoze.events import subscriber from pyramid.interfaces import IBeforeRender @@ -428,7 +432,7 @@ class IAuthenticationPolicy(Interface): principal named ``principal`` when set in a response. An individual authentication policy and its consumers can decide on the composition and meaning of ``**kw.`` """ - + def forget(request): """ Return a set of headers suitable for 'forgetting' the current user on subsequent requests. """ @@ -439,7 +443,7 @@ class IAuthorizationPolicy(Interface): """ Return ``True`` if any of the ``principals`` is allowed the ``permission`` in the current ``context``, else return ``False`` """ - + def principals_allowed_by_permission(context, permission): """ Return a set of principal identifiers allowed by the ``permission`` in ``context``. This behavior is optional; if you @@ -503,7 +507,7 @@ class IRequestHandler(Interface): The ``request`` argument will be an instance of an object that provides IRequest.""" -IRequest.combined = IRequest # for exception view lookups +IRequest.combined = IRequest # for exception view lookups class IRouteRequest(Interface): """ *internal only* interface used as in a utility lookup to find @@ -618,12 +622,12 @@ class IRouter(Interface): a view registry.""" registry = Attribute( """Component architecture registry local to this application.""") - + class ISettings(Interface): """ Runtime settings utility for pyramid; represents the deployment settings for the application. Implements a mapping interface.""" - + # this interface, even if it becomes unused within Pyramid, is # imported by other packages (such as traversalwrapper) class ILocation(Interface): @@ -753,7 +757,7 @@ class IChameleonTranslate(Interface): class ILocalizer(Interface): """ Localizer for a specific language """ - + class ILocaleNegotiator(Interface): def __call__(request): """ Return a locale name """ diff --git a/pyramid/paster.py b/pyramid/paster.py index ab764ba59..c9c356a92 100644 --- a/pyramid/paster.py +++ b/pyramid/paster.py @@ -65,19 +65,21 @@ def bootstrap(config_uri, request=None): that may be called when your script is complete (it pops a threadlocal stack). - .. note:: Most operations within :app:`Pyramid` expect to be invoked - within the context of a WSGI request, thus it's important when - loading your application to anchor it when executing scripts - and other code that is not normally invoked during active WSGI - requests. - - .. note:: For a complex config file containing multiple :app:`Pyramid` - applications, this function will setup the environment under - the context of the last-loaded :app:`Pyramid` application. You - may load a specific application yourself by using the - lower-level functions :meth:`pyramid.paster.get_app` and - :meth:`pyramid.scripting.prepare` in conjunction with - :attr:`pyramid.config.global_registries`. + .. note:: + + Most operations within :app:`Pyramid` expect to be invoked within the + context of a WSGI request, thus it's important when loading your + application to anchor it when executing scripts and other code that is + not normally invoked during active WSGI requests. + + .. note:: + + For a complex config file containing multiple :app:`Pyramid` + applications, this function will setup the environment under the context + of the last-loaded :app:`Pyramid` application. You may load a specific + application yourself by using the lower-level functions + :meth:`pyramid.paster.get_app` and :meth:`pyramid.scripting.prepare` in + conjunction with :attr:`pyramid.config.global_registries`. ``config_uri`` -- specifies the PasteDeploy config file to use for the interactive shell. The format is ``inifile#name``. If the name is left @@ -399,7 +401,7 @@ class PViewsCommand(PCommand): from pyramid.request import Request from pyramid.traversal import DefaultRootFactory from pyramid.traversal import ResourceTreeTraverser - + q = registry.queryUtility root_factory = q(IRootFactory, default=DefaultRootFactory) routes_mapper = q(IRoutesMapper) @@ -588,7 +590,7 @@ class PTweensCommand(PCommand): using an explicit tweens ordering (will be true when the ``pyramid.tweens`` setting is used) or an implicit tweens ordering (will be true when the ``pyramid.tweens`` setting is *not* used). - + This command accepts one positional argument: ``config_uri`` -- specifies the PasteDeploy config file to use for the diff --git a/pyramid/request.py b/pyramid/request.py index afeee4bb2..eae83da6f 100644 --- a/pyramid/request.py +++ b/pyramid/request.py @@ -414,7 +414,7 @@ def call_app_with_subpath_as_path_info(request, app): if new_path_info != '/': # don't want a sole double-slash if path_info != '/': # if orig path_info is '/', we're already done if path_info.endswith('/'): - # readd trailing slash stripped by subpath (traversal) + # readd trailing slash stripped by subpath (traversal) # conversion new_path_info += '/' @@ -433,7 +433,7 @@ def call_app_with_subpath_as_path_info(request, app): # to end of script_name while workback and (workback[-1] == ''): workback = workback[:-1] - + new_script_name = '/'.join(workback) new_request = request.copy() diff --git a/pyramid/security.py b/pyramid/security.py index 4355737b7..a552b613a 100644 --- a/pyramid/security.py +++ b/pyramid/security.py @@ -110,7 +110,9 @@ def principals_allowed_by_permission(context, permission): :mod:`pyramid.security.Everyone` (the special principal identifier representing all principals). - .. note:: even if an :term:`authorization policy` is in effect, + .. note:: + + even if an :term:`authorization policy` is in effect, some (exotic) authorization policies may not implement the required machinery for this function; those will cause a :exc:`NotImplementedError` exception to be raised when this @@ -193,14 +195,14 @@ def forget(request): return [] else: return policy.forget(request) - + class PermitsResult(int): def __new__(cls, s, *args): inst = int.__new__(cls, cls.boolval) inst.s = s inst.args = args return inst - + @property def msg(self): return self.s % self.args diff --git a/pyramid/static.py b/pyramid/static.py index 79384da09..50a8b918b 100644 --- a/pyramid/static.py +++ b/pyramid/static.py @@ -50,7 +50,7 @@ class _FileResponse(Response): content_length = getsize(path) self.app_iter = _FileIter(open(path, 'rb'), content_length) # assignment of content_length must come after assignment of app_iter - self.content_length = content_length + self.content_length = content_length if cache_max_age is not None: self.cache_expires = cache_max_age @@ -115,13 +115,15 @@ class static_view(object): the static application will consider request.environ[``PATH_INFO``] as ``PATH_INFO`` input. By default, this is ``False``. - .. note:: If the ``root_dir`` is relative to a :term:`package`, or - is a :term:`asset specification` the :app:`Pyramid` - :class:`pyramid.config.Configurator` method can be - used to override assets within the named ``root_dir`` - package-relative directory. However, if the ``root_dir`` is - absolute, configuration will not be able to - override the assets it contains. """ + .. note:: + + If the ``root_dir`` is relative to a :term:`package`, or is a + :term:`asset specification` the :app:`Pyramid` + :class:`pyramid.config.Configurator` method can be used to override + assets within the named ``root_dir`` package-relative directory. + However, if the ``root_dir`` is absolute, configuration will not be able + to override the assets it contains. + """ def __init__(self, root_dir, cache_max_age=3600, package_name=None, use_subpath=False, index='index.html'): diff --git a/pyramid/tests/test_config/test_views.py b/pyramid/tests/test_config/test_views.py index ce8d01f38..1f7ea05c2 100644 --- a/pyramid/tests/test_config/test_views.py +++ b/pyramid/tests/test_config/test_views.py @@ -1764,6 +1764,13 @@ class Test_requestonly(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): + """ """ + foo = Foo() + self.assertTrue(self._callFUT(foo.method)) class Test_isexception(unittest.TestCase): def _callFUT(self, ob): diff --git a/pyramid/traversal.py b/pyramid/traversal.py index 49f9be55f..ee6b5fb7a 100644 --- a/pyramid/traversal.py +++ b/pyramid/traversal.py @@ -141,26 +141,29 @@ def resource_path(resource, *elements): The ``resource`` passed in *must* be :term:`location`-aware. - .. note:: Each segment in the path string returned will use the - ``__name__`` attribute of the resource it represents within - the resource tree. Each of these segments *should* be a unicode - or string object (as per the contract of - :term:`location`-awareness). However, no conversion or - safety checking of resource names is performed. For - instance, if one of the resources in your tree has a - ``__name__`` which (by error) is a dictionary, the - :func:`pyramid.traversal.resource_path` function will - attempt to append it to a string and it will cause a - :exc:`pyramid.exceptions.URLDecodeError`. - - .. note:: The :term:`root` resource *must* have a ``__name__`` - attribute with a value of either ``None`` or the empty - string for paths to be generated properly. If the root - resource has a non-null ``__name__`` attribute, its name - will be prepended to the generated path rather than a - single leading '/' character. + .. note:: - .. note:: For backwards compatibility purposes, this function can also + Each segment in the path string returned will use the ``__name__`` + attribute of the resource it represents within the resource tree. Each + of these segments *should* be a unicode or string object (as per the + contract of :term:`location`-awareness). However, no conversion or + safety checking of resource names is performed. For instance, if one of + the resources in your tree has a ``__name__`` which (by error) is a + dictionary, the :func:`pyramid.traversal.resource_path` function will + attempt to append it to a string and it will cause a + :exc:`pyramid.exceptions.URLDecodeError`. + + .. note:: + + The :term:`root` resource *must* have a ``__name__`` attribute with a + value of either ``None`` or the empty string for paths to be generated + properly. If the root resource has a non-null ``__name__`` attribute, + its name will be prepended to the generated path rather than a single + leading '/' character. + + .. note:: + + For backwards compatibility purposes, this function can also be imported as ``model_path``, although doing so will cause a deprecation warning to be emitted. """ @@ -313,7 +316,7 @@ def traverse(resource, path): resource = find_root(resource) reg = get_current_registry() - + request_factory = reg.queryUtility(IRequestFactory) if request_factory is None: from pyramid.request import Request # avoid circdep @@ -346,28 +349,30 @@ def resource_path_tuple(resource, *elements): The ``resource`` passed in *must* be :term:`location`-aware. - .. note:: Each segment in the path tuple returned will equal the - ``__name__`` attribute of the resource it represents within - the resource tree. Each of these segments *should* be a unicode - or string object (as per the contract of - :term:`location`-awareness). However, no conversion or - safety checking of resource names is performed. For - instance, if one of the resources in your tree has a - ``__name__`` which (by error) is a dictionary, that - dictionary will be placed in the path tuple; no warning - or error will be given. - - .. note:: The :term:`root` resource *must* have a ``__name__`` - attribute with a value of either ``None`` or the empty - string for path tuples to be generated properly. If - the root resource has a non-null ``__name__`` attribute, - its name will be the first element in the generated - path tuple rather than the empty string. - - .. note:: For backwards compatibility purposes, this function can also be - imported as ``model_path_tuple``, although doing so will cause a - deprecation warning to be emitted. + .. note:: + + Each segment in the path tuple returned will equal the ``__name__`` + attribute of the resource it represents within the resource tree. Each + of these segments *should* be a unicode or string object (as per the + contract of :term:`location`-awareness). However, no conversion or + safety checking of resource names is performed. For instance, if one of + the resources in your tree has a ``__name__`` which (by error) is a + dictionary, that dictionary will be placed in the path tuple; no warning + or error will be given. + + .. note:: + + The :term:`root` resource *must* have a ``__name__`` attribute with a + value of either ``None`` or the empty string for path tuples to be + generated properly. If the root resource has a non-null ``__name__`` + attribute, its name will be the first element in the generated path tuple + rather than the empty string. + + .. note:: + For backwards compatibility purposes, this function can also be imported + as ``model_path_tuple``, although doing so will cause a deprecation + warning to be emitted. """ return tuple(_resource_path_list(resource, *elements)) @@ -481,18 +486,17 @@ def traversal_path_info(path): (u'archives', u'<unprintable unicode>') - .. note:: This function does not generate the same type of tuples - that :func:`pyramid.traversal.resource_path_tuple` does. - In particular, the leading empty string is not present - in the tuple it returns, unlike tuples returned by - :func:`pyramid.traversal.resource_path_tuple`. As a - result, tuples generated by ``traversal_path`` are not - resolveable by the - :func:`pyramid.traversal.find_resource` API. - ``traversal_path`` is a function mostly used by the - internals of :app:`Pyramid` and by people writing - their own traversal machinery, as opposed to users - writing applications in :app:`Pyramid`. + .. note:: + + This function does not generate the same type of tuples that + :func:`pyramid.traversal.resource_path_tuple` does. In particular, the + leading empty string is not present in the tuple it returns, unlike tuples + returned by :func:`pyramid.traversal.resource_path_tuple`. As a result, + tuples generated by ``traversal_path`` are not resolveable by the + :func:`pyramid.traversal.find_resource` API. ``traversal_path`` is a + function mostly used by the internals of :app:`Pyramid` and by people + writing their own traversal machinery, as opposed to users writing + applications in :app:`Pyramid`. """ try: path = bytes_(path, 'latin-1').decode('utf-8') diff --git a/pyramid/url.py b/pyramid/url.py index 0ccf02ab9..7a7dd3b4c 100644 --- a/pyramid/url.py +++ b/pyramid/url.py @@ -72,13 +72,14 @@ class URLMethodsMixin(object): data is turned into a query string, a leading ``?`` is prepended, and the resulting string is appended to the generated URL. - .. note:: Python data structures that are passed as ``_query`` - which are sequences or dictionaries are turned into a - string under the same rules as when run through - :func:`urllib.urlencode` with the ``doseq`` argument - equal to ``True``. This means that sequences can be - passed as values, and a k=v pair will be placed into the - query string for each value. + .. note:: + + Python data structures that are passed as ``_query`` which are + sequences or dictionaries are turned into a string under the same + rules as when run through :func:`urllib.urlencode` with the ``doseq`` + argument equal to ``True``. This means that sequences can be passed + as values, and a k=v pair will be placed into the query string for + each value. If a keyword argument ``_anchor`` is present, its string representation will be used as a named anchor in the generated URL @@ -86,11 +87,12 @@ class URLMethodsMixin(object): ``http://example.com/route/url``, the resulting generated URL will be ``http://example.com/route/url#foo``). - .. note:: If ``_anchor`` is passed as a string, it should be UTF-8 - encoded. If ``_anchor`` is passed as a Unicode object, it - will be converted to UTF-8 before being appended to the - URL. The anchor value is not quoted in any way before - being appended to the generated URL. + .. note:: + + If ``_anchor`` is passed as a string, it should be UTF-8 encoded. If + ``_anchor`` is passed as a Unicode object, it will be converted to + UTF-8 before being appended to the URL. The anchor value is not + quoted in any way before being appended to the generated URL. If both ``_anchor`` and ``_query`` are specified, the anchor element will always follow the query element, @@ -178,13 +180,14 @@ class URLMethodsMixin(object): Will return the string ``/1/2``. - .. note:: Calling ``request.route_path('route')`` is the same as - calling ``request.route_url('route', - _app_url=request.script_name)``. - :meth:`pyramid.request.Request.route_path` is, in fact, - implemented in terms of `:meth:`pyramid.request.Request.route_url` - in just this way. As a result, any ``_app_url`` passed within the - ``**kw`` values to ``route_path`` will be ignored. + .. note:: + + Calling ``request.route_path('route')`` is the same as calling + ``request.route_url('route', _app_url=request.script_name)``. + :meth:`pyramid.request.Request.route_path` is, in fact, implemented + in terms of `:meth:`pyramid.request.Request.route_url` in just this + way. As a result, any ``_app_url`` passed within the ``**kw`` values + to ``route_path`` will be ignored. """ kw['_app_url'] = self.script_name return self.route_url(route_name, *elements, **kw) @@ -239,13 +242,14 @@ class URLMethodsMixin(object): into a query string, a leading ``?`` is prepended, and the resulting string is appended to the generated URL. - .. note:: Python data structures that are passed as ``query`` which - are sequences or dictionaries are turned into a string - under the same rules as when run through - :func:`urllib.urlencode` with the ``doseq`` argument equal - to ``True``. This means that sequences can be passed as - values, and a k=v pair will be placed into the query string - for each value. + .. note:: + + Python data structures that are passed as ``query`` which are + sequences or dictionaries are turned into a string under the same + rules as when run through :func:`urllib.urlencode` with the ``doseq`` + argument equal to ``True``. This means that sequences can be passed + as values, and a k=v pair will be placed into the query string for + each value. If a keyword argument ``anchor`` is present, its string representation will be used as a named anchor in the generated URL @@ -253,11 +257,12 @@ class URLMethodsMixin(object): ``http://example.com/resource/url``, the resulting generated URL will be ``http://example.com/resource/url#foo``). - .. note:: If ``anchor`` is passed as a string, it should be UTF-8 - encoded. If ``anchor`` is passed as a Unicode object, it - will be converted to UTF-8 before being appended to the - URL. The anchor value is not quoted in any way before - being appended to the generated URL. + .. note:: + + If ``anchor`` is passed as a string, it should be UTF-8 encoded. If + ``anchor`` is passed as a Unicode object, it will be converted to + UTF-8 before being appended to the URL. The anchor value is not + quoted in any way before being appended to the generated URL. If both ``anchor`` and ``query`` are specified, the anchor element will always follow the query element, @@ -268,19 +273,24 @@ class URLMethodsMixin(object): the base resource which is operated upon by this function. See also :ref:`overriding_resource_url_generation`. - .. note:: If the :term:`resource` used is the result of a - :term:`traversal`, it must be :term:`location`-aware. The - resource can also be the context of a :term:`URL dispatch`; - contexts found this way do not need to be location-aware. + .. note:: + + If the :term:`resource` used is the result of a :term:`traversal`, it + must be :term:`location`-aware. The resource can also be the context + of a :term:`URL dispatch`; contexts found this way do not need to be + location-aware. + + .. note:: + + If a 'virtual root path' is present in the request environment (the + value of the WSGI environ key ``HTTP_X_VHM_ROOT``), and the resource + was obtained via :term:`traversal`, the URL path will not include the + virtual root prefix (it will be stripped off the left hand side of + the generated URL). - .. note:: If a 'virtual root path' is present in the request - environment (the value of the WSGI environ key - ``HTTP_X_VHM_ROOT``), and the resource was obtained via - :term:`traversal`, the URL path will not include the - virtual root prefix (it will be stripped off the left hand - side of the generated URL). + .. note:: - .. note:: For backwards compatibility purposes, this method is also + For backwards compatibility purposes, this method is also aliased as the ``model_url`` method of request. """ try: @@ -311,7 +321,7 @@ class URLMethodsMixin(object): suffix = '' return resource_url + suffix + qs + anchor - + model_url = resource_url # b/w compat forever def static_url(self, path, **kw): @@ -381,14 +391,14 @@ class URLMethodsMixin(object): /static/foo.css - .. note:: Calling ``request.static_path(apath)`` is the same - as calling ``request.static_url(apath, - _app_url=request.script_name)``. - :meth:`pyramid.request.Request.static_path` is, in fact, - implemented in terms of - `:meth:`pyramid.request.Request.static_url` in just this - way. As a result, any ``_app_url`` passed within the ``**kw`` - values to ``static_path`` will be ignored. + .. note:: + + Calling ``request.static_path(apath)`` is the same as calling + ``request.static_url(apath, _app_url=request.script_name)``. + :meth:`pyramid.request.Request.static_path` is, in fact, implemented + in terms of `:meth:`pyramid.request.Request.static_url` in just this + way. As a result, any ``_app_url`` passed within the ``**kw`` values + to ``static_path`` will be ignored. """ if not os.path.isabs(path): if not ':' in path: @@ -479,7 +489,9 @@ class URLMethodsMixin(object): Will return the string ``/1/2``. - .. note:: Calling ``request.current_route_path('route')`` is the same + .. note:: + + Calling ``request.current_route_path('route')`` is the same as calling ``request.current_route_url('route', _app_url=request.script_name)``. :meth:`pyramid.request.Request.current_route_path` is, in fact, @@ -490,8 +502,8 @@ class URLMethodsMixin(object): """ kw['_app_url'] = self.script_name return self.current_route_url(*elements, **kw) - - + + def route_url(route_name, request, *elements, **kw): """ This is a backwards compatibility function. Its result is the same as diff --git a/pyramid/view.py b/pyramid/view.py index f4d92b6ed..581e42185 100644 --- a/pyramid/view.py +++ b/pyramid/view.py @@ -16,7 +16,7 @@ from pyramid.threadlocal import get_current_registry _marker = object() -class static(static_view): +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. This class is deprecated as of @@ -302,7 +302,9 @@ def is_response(ob): """ Return ``True`` if ``ob`` implements the interface implied by :ref:`the_response`. ``False`` if not. - .. warning:: This function is deprecated as of :app:`Pyramid` 1.1. New + .. warning:: + + This function is deprecated as of :app:`Pyramid` 1.1. New code should not use it. Instead, new code should use the :func:`pyramid.request.Request.is_response` method.""" if ( hasattr(ob, 'app_iter') and hasattr(ob, 'headerlist') and |