diff options
| -rw-r--r-- | docs/api/config.rst | 19 | ||||
| -rw-r--r-- | pyramid/config/__init__.py | 77 | ||||
| -rw-r--r-- | pyramid/config/factories.py | 7 | ||||
| -rw-r--r-- | pyramid/config/security.py | 21 | ||||
| -rw-r--r-- | pyramid/config/settings.py | 13 | ||||
| -rw-r--r-- | pyramid/config/tweens.py | 3 | ||||
| -rw-r--r-- | pyramid/config/views.py | 15 |
7 files changed, 80 insertions, 75 deletions
diff --git a/docs/api/config.rst b/docs/api/config.rst index d744418b3..a8c193b60 100644 --- a/docs/api/config.rst +++ b/docs/api/config.rst @@ -5,7 +5,7 @@ .. automodule:: pyramid.config - .. autoclass:: Configurator(registry=None, package=None, settings=None, root_factory=None, authentication_policy=None, authorization_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None, default_permission=None, session_factory=None, autocommit=False) + .. autoclass:: Configurator .. attribute:: registry @@ -36,9 +36,9 @@ .. automethod:: absolute_asset_spec - .. automethod:: setup_registry(settings=None, root_factory=None, authentication_policy=None, renderers=DEFAULT_RENDERERS, debug_logger=None, locale_negotiator=None, request_factory=None, renderer_globals_factory=None) + .. automethod:: setup_registry - .. automethod:: add_renderer(name, factory) + .. automethod:: add_renderer .. automethod:: add_response_adapter @@ -64,10 +64,6 @@ .. automethod:: scan - .. automethod:: set_forbidden_view - - .. automethod:: set_notfound_view - .. automethod:: set_locale_negotiator .. automethod:: set_default_permission @@ -78,8 +74,6 @@ .. automethod:: set_root_factory - .. automethod:: set_renderer_globals_factory(factory) - .. automethod:: set_view_mapper .. automethod:: set_authentication_policy @@ -94,6 +88,13 @@ .. automethod:: testing_add_renderer + .. automethod:: set_forbidden_view + + .. automethod:: set_notfound_view + + .. automethod:: set_renderer_globals_factory(factory) + + .. attribute:: global_registries The set of registries that have been created for :app:`Pyramid` diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py index 91c351fa5..c7ee8c47f 100644 --- a/pyramid/config/__init__.py +++ b/pyramid/config/__init__.py @@ -71,48 +71,46 @@ class Configurator( ``authorization_policy``, ``renderers``, ``debug_logger``, ``locale_negotiator``, ``request_factory``, ``renderer_globals_factory``, ``default_permission``, ``session_factory``, ``default_view_mapper``, - ``autocommit``, and ``exceptionresponse_view``. - - If the ``registry`` argument is passed as a non-``None`` value, it - must be an instance of the :class:`pyramid.registry.Registry` - class representing the registry to configure. If ``registry`` is - ``None``, the configurator will create a - :class:`pyramid.registry.Registry` instance itself; it will - also perform some default configuration that would not otherwise - be done. After construction, the configurator may be used to add - configuration to the registry. The overall state of a registry is - called the 'configuration state'. + ``autocommit``, ``exceptionresponse_view`` and ``route_prefix``. + + If the ``registry`` argument is passed as a non-``None`` value, it must + be an instance of the :class:`pyramid.registry.Registry` class + representing the registry to configure. If ``registry`` is ``None``, the + configurator will create a :class:`pyramid.registry.Registry` instance + itself; it will also perform some default configuration that would not + otherwise be done. After its construction, the configurator may be used + to add further configuration to the registry. .. warning:: If a ``registry`` is passed to the Configurator constructor, all other constructor arguments except ``package`` are ignored. - If the ``package`` argument is passed, it must be a reference to a - Python :term:`package` (e.g. ``sys.modules['thepackage']``) or a - :term:`dotted Python name` to same. This value is used as a basis - to convert relative paths passed to various configuration methods, - such as methods which accept a ``renderer`` argument, into - absolute paths. If ``None`` is passed (the default), the package - is assumed to be the Python package in which the *caller* of the - ``Configurator`` constructor lives. + If the ``package`` argument is passed, it must be a reference to a Python + :term:`package` (e.g. ``sys.modules['thepackage']``) or a :term:`dotted + Python name` to the same. This value is used as a basis to convert + relative paths passed to various configuration methods, such as methods + which accept a ``renderer`` argument, into absolute paths. If ``None`` + is passed (the default), the package is assumed to be the Python package + in which the *caller* of the ``Configurator`` constructor lives. If the ``settings`` argument is passed, it should be a Python dictionary - representing the deployment settings for this application. These are - later retrievable using the :attr:`pyramid.registry.Registry.settings` - attribute (aka ``request.registry.settings``). + representing the :term:`deployment settings` for this application. These + are later retrievable using the + :attr:`pyramid.registry.Registry.settings` attribute (aka + ``request.registry.settings``). If the ``root_factory`` argument is passed, it should be an object - representing the default :term:`root factory` for your application - or a :term:`dotted Python name` to same. If it is ``None``, a - default root factory will be used. + representing the default :term:`root factory` for your application or a + :term:`dotted Python name` to the same. If it is ``None``, a default + root factory will be used. If ``authentication_policy`` is passed, it should be an instance of an :term:`authentication policy` or a :term:`dotted Python - name` to same. + name` to the same. If ``authorization_policy`` is passed, it should be an instance of an :term:`authorization policy` or a :term:`dotted Python name` to - same. + the same. .. note:: A ``ConfigurationError`` will be raised when an authorization policy is supplied without also supplying an @@ -137,14 +135,14 @@ class Configurator( same. See :ref:`custom_locale_negotiator`. If ``request_factory`` is passed, it should be a :term:`request - factory` implementation or a :term:`dotted Python name` to same. + factory` implementation or a :term:`dotted Python name` to the same. See :ref:`changing_the_request_factory`. By default it is ``None``, which means use the default request factory. If ``renderer_globals_factory`` is passed, it should be a :term:`renderer - globals` factory implementation or a :term:`dotted Python name` to same. - See :ref:`adding_renderer_globals`. By default, it is ``None``, which - means use no renderer globals factory. + globals` factory implementation or a :term:`dotted Python name` to the + same. See :ref:`adding_renderer_globals`. By default, it is ``None``, + which means use no renderer globals factory. .. warning:: as of Pyramid 1.1, ``renderer_globals_factory`` is deprecated. Instead, use a BeforeRender event subscriber as per @@ -266,16 +264,15 @@ class Configurator( session_factory=None, default_view_mapper=None, exceptionresponse_view=default_exceptionresponse_view): """ When you pass a non-``None`` ``registry`` argument to the - :term:`Configurator` constructor, no initial 'setup' is performed + :term:`Configurator` constructor, no initial setup is performed against the registry. This is because the registry you pass in may have already been initialized for use under :app:`Pyramid` via a different configurator. However, in some circumstances (such as when - you want to use the Zope 'global` registry instead of a registry - created as a result of the Configurator constructor), or when you - want to reset the initial setup of a registry, you *do* want to - explicitly initialize the registry associated with a Configurator for - use under :app:`Pyramid`. Use ``setup_registry`` to do this - initialization. + you want to use a global registry instead of a registry created as a + result of the Configurator constructor), or when you want to reset + the initial setup of a registry, you *do* want to explicitly + initialize the registry associated with a Configurator for use under + :app:`Pyramid`. Use ``setup_registry`` to do this initialization. ``setup_registry`` configures settings, a root factory, security policies, renderers, a debug logger, a locale negotiator, and various @@ -421,7 +418,7 @@ class Configurator( def action(self, discriminator, callable=None, args=(), kw=None, order=0): """ Register an action which will be executed when - :meth:`pyramid.config.Configuration.commit` is called (or executed + :meth:`pyramid.config.Configurator.commit` is called (or executed immediately if ``autocommit`` is ``True``). .. warning:: This method is typically only used by :app:`Pyramid` @@ -471,7 +468,7 @@ class Configurator( def commit(self): """ Commit any pending configuration actions. If a configuration - conflict is detected in the pending configuration actins, this method + conflict is detected in the pending configuration actions, this method will raise a :exc:`ConfigurationConflictError`; within the traceback of this error will be information about the source of the conflict, usually including file names and line numbers of the cause of the diff --git a/pyramid/config/factories.py b/pyramid/config/factories.py index cc73d596c..1421082cd 100644 --- a/pyramid/config/factories.py +++ b/pyramid/config/factories.py @@ -12,7 +12,12 @@ class FactoriesConfiguratorMixin(object): def set_root_factory(self, factory): """ Add a :term:`root factory` to the current configuration state. If the ``factory`` argument is ``None`` a default root - factory will be registered.""" + 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. + """ factory = self.maybe_dotted(factory) if factory is None: factory = DefaultRootFactory diff --git a/pyramid/config/security.py b/pyramid/config/security.py index 4a4b7a1ad..897d4bbec 100644 --- a/pyramid/config/security.py +++ b/pyramid/config/security.py @@ -2,7 +2,6 @@ from pyramid.interfaces import IAuthorizationPolicy from pyramid.interfaces import IAuthenticationPolicy from pyramid.interfaces import IDefaultPermission -from pyramid.authorization import ACLAuthorizationPolicy from pyramid.exceptions import ConfigurationError from pyramid.config.util import action_method @@ -13,6 +12,11 @@ class SecurityConfiguratorMixin(object): current configuration. The ``policy`` argument must be an instance 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. + """ self._set_authentication_policy(policy) def ensure(): @@ -36,6 +40,10 @@ class SecurityConfiguratorMixin(object): current configuration. The ``policy`` argument must be an instance 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. """ self._set_authorization_policy(policy) def ensure(): @@ -76,12 +84,11 @@ class SecurityConfiguratorMixin(object): If a default permission is in effect, view configurations meant to create a truly anonymously accessible view (even :term:`exception - view` views) *must* use the explicit permission string - :data:`pyramid.security.NO_PERMISSION_REQUIRED` as the permission. - When this string is used as the ``permission`` for a view - configuration, the default permission is ignored, and the view is - registered, making it available to all callers regardless of their - credentials. + view` views) *must* use the value of the permission importable as + :data:`pyramid.security.NO_PERMISSION_REQUIRED`. When this string + is used as the ``permission`` for a view configuration, the default + permission is ignored, and the view is registered, making it + available to all callers regardless of their credentials. See also :ref:`setting_a_default_permission`. diff --git a/pyramid/config/settings.py b/pyramid/config/settings.py index 513a57871..fad442853 100644 --- a/pyramid/config/settings.py +++ b/pyramid/config/settings.py @@ -9,11 +9,8 @@ class SettingsConfiguratorMixin(object): return settings def add_settings(self, settings=None, **kw): - """Augment the ``settings`` argument passed in to the Configurator - constructor with one or more 'setting' key/value pairs. A setting is - a single key/value pair in the dictionary-ish object returned from - the API :attr:`pyramid.registry.Registry.settings` and - :meth:`pyramid.config.Configurator.get_settings`. + """Augment the :term:`deployment settings` with one or more + key/value pairs. You may pass a dictionary:: @@ -42,11 +39,7 @@ class SettingsConfiguratorMixin(object): application. A deployment settings object is a dictionary-like object that contains key/value pairs based on the dictionary passed as the ``settings`` argument to the - :class:`pyramid.config.Configurator` constructor or the - :func:`pyramid.router.make_app` API. - - .. note:: For backwards compatibility, dictionary keys can also be - looked up as attributes of the settings object. + :class:`pyramid.config.Configurator` constructor. .. note:: the :attr:`pyramid.registry.Registry.settings` API performs the same duty. diff --git a/pyramid/config/tweens.py b/pyramid/config/tweens.py index 4551c7fac..83067f0fe 100644 --- a/pyramid/config/tweens.py +++ b/pyramid/config/tweens.py @@ -11,6 +11,8 @@ class TweensConfiguratorMixin(object): @action_method def add_tween(self, tween_factory, alias=None, under=None, over=None): """ + .. note:: This feature is new as of Pyramid 1.2. + Add a 'tween factory'. A :term:`tween` (a contraction of 'between') is a bit of code that sits between the Pyramid router's main request handling function and the upstream WSGI component that uses @@ -98,7 +100,6 @@ class TweensConfiguratorMixin(object): For more information, see :ref:`registering_tweens`. - .. note:: This feature is new as of Pyramid 1.2. """ return self._add_tween(tween_factory, alias=alias, under=under, over=over, explicit=False) diff --git a/pyramid/config/views.py b/pyramid/config/views.py index 5ec2f68a1..c4c9f1fbc 100644 --- a/pyramid/config/views.py +++ b/pyramid/config/views.py @@ -1249,14 +1249,15 @@ class ViewsConfiguratorMixin(object): The ``mapper`` should argument be an object implementing :class:`pyramid.interfaces.IViewMapperFactory` or a :term:`dotted - Python name` to such an object. + Python name` to such an object. The provided ``mapper`` will become + the default view mapper to be used by all subsequent :term:`view + configuration` registrations. - The provided ``mapper`` will become the default view mapper to be - used by all subsequent :term:`view configuration` registrations, as - if you had passed a ``default_view_mapper`` argument to the - :class:`pyramid.config.Configurator` constructor. - See also :ref:`using_a_view_mapper`. + + .. note:: Using the ``default_view_mapper`` argument to the + :class:`pyramid.config.Configurator` constructor + can be used to achieve the same purpose. """ mapper = self.maybe_dotted(mapper) self.registry.registerUtility(mapper, IViewMapperFactory) @@ -1293,7 +1294,7 @@ class ViewsConfiguratorMixin(object): be performed against the default root factory ACL. Any other keyword arguments sent to ``add_static_view`` are passed on - to :meth:`pyramid.config.Configuration.add_route` (e.g. ``factory``, + to :meth:`pyramid.config.Configurator.add_route` (e.g. ``factory``, perhaps to define a custom factory with a custom ACL for this static view). |