From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/advconfig.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 3bd9c2a4e..8040a465f 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -14,7 +14,7 @@ you to ignore relative configuration statement ordering in some circumstances. .. index:: - single: imperative configuration + pair: configuration; conflict detection .. _conflict_detection: @@ -299,6 +299,9 @@ These are the methods of the configurator which provide conflict detection: provides conflict detection, because it's implemented in terms of the conflict-aware ``add_route`` and ``add_view`` methods. +.. index:: + pair: configuration; including from external sources + .. _including_configuration: Including Configuration from External Sources @@ -397,6 +400,10 @@ constraints: the routes they imply require relative ordering. Such ordering constraints are not absolved by two-phase configuration. Routes are still added in configuration execution order. +.. index:: + single: add_directive + pair: configurator; adding directives + .. _add_directive: Adding Methods to the Configurator via ``add_directive`` -- cgit v1.2.3 From 25be339daa0448bf64b4dba03c08205b571a1cb0 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 4 Sep 2011 00:04:12 -0400 Subject: remove documentation and todo mentions of zope.configuration --- docs/narr/advconfig.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 8040a465f..7b62b1a73 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -82,11 +82,8 @@ that ends something like this: self.commit() File "pyramid/pyramid/config.py", line 473, in commit self._ctx.execute_actions() - File "zope/configuration/config.py", line 600, in execute_actions - for action in resolveConflicts(self.actions): - File "zope/configuration/config.py", line 1507, in resolveConflicts - raise ConfigurationConflictError(conflicts) - zope.configuration.config.ConfigurationConflictError: + ... more code ... + pyramid.exceptions.ConfigurationConflictError: Conflicting configuration actions For: ('view', None, '', None, , None, None, None, None, None, False, None, None, None) -- cgit v1.2.3 From 35ad08ba9c66b900fe0c537516b390a92cb2a8cd Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 29 Nov 2011 08:31:33 -0500 Subject: move register method from IIntrospector back to IIntrospectable; provide better conflict reporting and a more useful ActionInfo object --- docs/narr/advconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 7b62b1a73..a6db5f58e 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -87,8 +87,8 @@ that ends something like this: Conflicting configuration actions For: ('view', None, '', None, , None, None, None, None, None, False, None, None, None) - ('app.py', 14, '', 'config.add_view(hello_world)') - ('app.py', 17, '', 'config.add_view(hello_world)') + Line 14 of file app.py in : 'config.add_view(hello_world)' + Line 17 of file app.py in : 'config.add_view(hello_world)' This traceback is trying to tell us: -- cgit v1.2.3 From 56bfd68215d656cb5039bc842b030b5ab447a7f7 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 29 Nov 2011 08:33:24 -0500 Subject: get repr right --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index a6db5f58e..4d4f82197 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -88,7 +88,7 @@ that ends something like this: For: ('view', None, '', None, , None, None, None, None, None, False, None, None, None) Line 14 of file app.py in : 'config.add_view(hello_world)' - Line 17 of file app.py in : 'config.add_view(hello_world)' + Line 17 of file app.py in : 'config.add_view(goodbye_world)' This traceback is trying to tell us: -- cgit v1.2.3 From 9f341ea78cfae3a33ef250acee49fa9709a7d7fe Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 29 Nov 2011 08:37:49 -0500 Subject: add note about allowing extension via custom directives --- docs/narr/advconfig.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 4d4f82197..3b6f7669a 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -13,6 +13,8 @@ also, by default, performs configuration in two separate phases. This allows you to ignore relative configuration statement ordering in some circumstances. +Pyramid also allows you to extend its Configurator with custom directives. + .. index:: pair: configuration; conflict detection -- cgit v1.2.3 From c4503bf117e43f780c269e64edbde71fc3d6d72b Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 3 Dec 2011 01:56:17 -0500 Subject: break out 'extending config' into exconfig and add stuff about the action method; move startup and router chapters to earlier in toc --- docs/narr/advconfig.rst | 77 ++----------------------------------------------- 1 file changed, 2 insertions(+), 75 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 3b6f7669a..3a7bf2805 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -13,8 +13,6 @@ also, by default, performs configuration in two separate phases. This allows you to ignore relative configuration statement ordering in some circumstances. -Pyramid also allows you to extend its Configurator with custom directives. - .. index:: pair: configuration; conflict detection @@ -117,6 +115,8 @@ Conflict detection happens for any kind of configuration: imperative configuration or configuration that results from the execution of a :term:`scan`. +.. _manually_resolving_conflicts: + Manually Resolving Conflicts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -399,76 +399,3 @@ constraints: the routes they imply require relative ordering. Such ordering constraints are not absolved by two-phase configuration. Routes are still added in configuration execution order. -.. index:: - single: add_directive - pair: configurator; adding directives - -.. _add_directive: - -Adding Methods to the Configurator via ``add_directive`` --------------------------------------------------------- - -Framework extension writers can add arbitrary methods to a -:term:`Configurator` by using the -:meth:`pyramid.config.Configurator.add_directive` method of the configurator. -This makes it possible to extend a Pyramid configurator in arbitrary ways, -and allows it to perform application-specific tasks more succinctly. - -The :meth:`~pyramid.config.Configurator.add_directive` method accepts two -positional arguments: a method name and a callable object. The callable -object is usually a function that takes the configurator instance as its -first argument and accepts other arbitrary positional and keyword arguments. -For example: - -.. code-block:: python - :linenos: - - from pyramid.events import NewRequest - from pyramid.config import Configurator - - def add_newrequest_subscriber(config, subscriber): - config.add_subscriber(subscriber, NewRequest). - - if __name__ == '__main__': - config = Configurator() - config.add_directive('add_newrequest_subscriber', - add_newrequest_subscriber) - -Once :meth:`~pyramid.config.Configurator.add_directive` is called, a user can -then call the method by its given name as if it were a built-in method of the -Configurator: - -.. code-block:: python - :linenos: - - def mysubscriber(event): - print event.request - - config.add_newrequest_subscriber(mysubscriber) - -A call to :meth:`~pyramid.config.Configurator.add_directive` is often -"hidden" within an ``includeme`` function within a "frameworky" package meant -to be included as per :ref:`including_configuration` via -:meth:`~pyramid.config.Configurator.include`. For example, if you put this -code in a package named ``pyramid_subscriberhelpers``: - -.. code-block:: python - :linenos: - - def includeme(config) - config.add_directive('add_newrequest_subscriber', - add_newrequest_subscriber) - -The user of the add-on package ``pyramid_subscriberhelpers`` would then be -able to install it and subsequently do: - -.. code-block:: python - :linenos: - - def mysubscriber(event): - print event.request - - from pyramid.config import Configurator - config = Configurator() - config.include('pyramid_subscriberhelpers') - config.add_newrequest_subscriber(mysubscriber) -- cgit v1.2.3 From 10f1b5c35072c5499f3504dc261fb3c67a90c70d Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 16 Dec 2011 04:54:09 -0500 Subject: stamp out paste.httpserver usage --- docs/narr/advconfig.rst | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 3a7bf2805..5f2175d2a 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -27,7 +27,7 @@ configured imperatively: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -38,7 +38,8 @@ configured imperatively: config = Configurator() config.add_view(hello_world) app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() When you start this application, all will be OK. However, what happens if we try to add another view to the configuration with the same set of @@ -47,7 +48,7 @@ try to add another view to the configuration with the same set of .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -66,7 +67,8 @@ try to add another view to the configuration with the same set of config.add_view(goodbye_world, name='hello') app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() The application now has two conflicting view configuration statements. When we try to start it again, it won't start. Instead, we'll receive a traceback @@ -170,7 +172,7 @@ application that generates conflicts: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -189,7 +191,8 @@ application that generates conflicts: config.add_view(goodbye_world, name='hello') app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() We can prevent the two ``add_view`` calls from conflicting by issuing a call to :meth:`~pyramid.config.Configurator.commit` between them: @@ -197,7 +200,7 @@ to :meth:`~pyramid.config.Configurator.commit` between them: .. code-block:: python :linenos: - from paste.httpserver import serve + from wsgiref.simple_server import make_server from pyramid.config import Configurator from pyramid.response import Response @@ -218,7 +221,8 @@ to :meth:`~pyramid.config.Configurator.commit` between them: config.add_view(goodbye_world, name='hello') app = config.make_wsgi_app() - serve(app, host='0.0.0.0') + server = make_server('0.0.0.0', 8080, app) + server.serve_forever() In the above example we've issued a call to :meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` -- cgit v1.2.3 From 20ecd354ab99eb0dec5617115f4288ec9262270c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 18 Feb 2012 08:26:26 -0500 Subject: expand --- docs/narr/advconfig.rst | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 5f2175d2a..0060ef65c 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -122,9 +122,10 @@ configuration or configuration that results from the execution of a Manually Resolving Conflicts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There are a number of ways to manually resolve conflicts: the "right" way, by -strategically using :meth:`pyramid.config.Configurator.commit`, or by using -an "autocommitting" configurator. +There are a number of ways to manually resolve conflicts: by changing +registrations to not conflict, by strategically using +:meth:`pyramid.config.Configurator.commit`, or by using an "autocommitting" +configurator. The Right Thing +++++++++++++++ @@ -294,9 +295,18 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.add_route`, :meth:`~pyramid.config.Configurator.add_renderer`, :meth:`~pyramid.config.Configurator.set_request_factory`, +:meth:`~pyramid.config.Configurator.set_session_factory`, +:meth:`~pyramid.config.Configurator.set_request_property`, +:meth:`~pyramid.config.Configurator.set_root_factory`, +:meth:`~pyramid.config.Configurator.set_view_mapper`, +:meth:`~pyramid.config.Configurator.set_authentication_policy`, +:meth:`~pyramid.config.Configurator.set_authorization_policy`, :meth:`~pyramid.config.Configurator.set_renderer_globals_factory`, -:meth:`~pyramid.config.Configurator.set_locale_negotiator` and -:meth:`~pyramid.config.Configurator.set_default_permission`. +:meth:`~pyramid.config.Configurator.set_locale_negotiator`, +:meth:`~pyramid.config.Configurator.set_default_permission`, +:meth:`~pyramid.config.Configurator.add_traverser`, +:meth:`~pyramid.config.Configurator.add_resource_url_adapter`, +and :meth:`~pyramid.config.Configurator.add_response_adapter`. :meth:`~pyramid.config.Configurator.add_static_view` also indirectly provides conflict detection, because it's implemented in terms of the -- cgit v1.2.3 From c946fc7b717359cf26dab45a9b84f06f6c1bc466 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Tue, 13 Mar 2012 17:19:18 -0700 Subject: Typos --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 0060ef65c..9cb4db325 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -227,7 +227,7 @@ to :meth:`~pyramid.config.Configurator.commit` between them: In the above example we've issued a call to :meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` -calls. :meth:`~pyramid.config.Configurator.commit` will cause any pending +calls. :meth:`~pyramid.config.Configurator.commit` will execute any pending configuration statements. Calling :meth:`~pyramid.config.Configurator.commit` is safe at any time. It -- cgit v1.2.3 From 1d03bbca7fe9f005d4a08c7dfe7eb139ab4b0df1 Mon Sep 17 00:00:00 2001 From: Patricio Paez Date: Mon, 7 May 2012 21:45:40 -0500 Subject: Two grammatical fixes --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 9cb4db325..2949dc808 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -282,7 +282,7 @@ Pyramid application, and they want to customize the configuration of this application without hacking its code "from outside", they can "include" a configuration function from the package and override only some of its configuration statements within the code that does the include. No conflicts -will be generated by configuration statements within the code which does the +will be generated by configuration statements within the code that does the including, even if configuration statements in the included code would conflict if it was moved "up" to the calling code. -- cgit v1.2.3 From 2c25342383eed7b10e349b2396eed08d332cfb80 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Thu, 16 Aug 2012 02:28:43 -0500 Subject: docs-deprecated set_request_property --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 2949dc808..0ad2fdc95 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -296,7 +296,7 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.add_renderer`, :meth:`~pyramid.config.Configurator.set_request_factory`, :meth:`~pyramid.config.Configurator.set_session_factory`, -:meth:`~pyramid.config.Configurator.set_request_property`, +:meth:`~pyramid.config.Configurator.set_request_method`, :meth:`~pyramid.config.Configurator.set_root_factory`, :meth:`~pyramid.config.Configurator.set_view_mapper`, :meth:`~pyramid.config.Configurator.set_authentication_policy`, -- cgit v1.2.3 From 9cdb28614e558a886cb75d1d9ce9689621199722 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 16 Aug 2012 11:25:23 -0400 Subject: readd set_request_property to docs (just so when people run across it in in-the-wild code they're not totally confused); we'll remove it later --- docs/narr/advconfig.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 0ad2fdc95..b1ea652d6 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -297,6 +297,7 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.set_request_factory`, :meth:`~pyramid.config.Configurator.set_session_factory`, :meth:`~pyramid.config.Configurator.set_request_method`, +:meth:`~pyramid.config.Configurator.set_request_property`, :meth:`~pyramid.config.Configurator.set_root_factory`, :meth:`~pyramid.config.Configurator.set_view_mapper`, :meth:`~pyramid.config.Configurator.set_authentication_policy`, -- cgit v1.2.3 From 023c88b67b907dd3682ef71216245609c9bbdbe1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 9 Sep 2012 23:01:06 -0400 Subject: rename set_request_method to add_request_method. closes #683 --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index b1ea652d6..165cf7474 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -294,9 +294,9 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.add_view`, :meth:`~pyramid.config.Configurator.add_route`, :meth:`~pyramid.config.Configurator.add_renderer`, +:meth:`~pyramid.config.Configurator.add_request_method`, :meth:`~pyramid.config.Configurator.set_request_factory`, :meth:`~pyramid.config.Configurator.set_session_factory`, -:meth:`~pyramid.config.Configurator.set_request_method`, :meth:`~pyramid.config.Configurator.set_request_property`, :meth:`~pyramid.config.Configurator.set_root_factory`, :meth:`~pyramid.config.Configurator.set_view_mapper`, -- cgit v1.2.3 From d501b7cb23a26b85882d01deb1c8381acd75447e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 15 Sep 2012 04:17:12 -0400 Subject: point at cookbook --- docs/narr/advconfig.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 165cf7474..ad22a82c9 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -414,3 +414,10 @@ constraints: the routes they imply require relative ordering. Such ordering constraints are not absolved by two-phase configuration. Routes are still added in configuration execution order. +More Information +---------------- + +For more information, see the article entitled `"A Whirlwind Rour of Advanced +Configuration Tactics" +`_ +in the Pyramid Cookbook. -- cgit v1.2.3 From 8109ae8ef7e04135a4724963951983ee260293a7 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Sun, 13 Jan 2013 22:45:36 +0200 Subject: typo; should be 'titled', but would be redundant --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index ad22a82c9..7caea28b8 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article entitled `"A Whirlwind Rour of Advanced +For more information, see the article `"A Whirlwind Tour of Advanced Configuration Tactics" `_ in the Pyramid Cookbook. -- cgit v1.2.3 From b00f1e46f100d8a23041a1bb7a7b37b026170fe3 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Mon, 14 Jan 2013 08:50:51 -0500 Subject: Punctuate. --- docs/narr/advconfig.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 7caea28b8..ba43f3ea6 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article `"A Whirlwind Tour of Advanced +For more information, see the article,`"A Whirlwind Tour of Advanced Configuration Tactics" -`_ +`_, in the Pyramid Cookbook. -- cgit v1.2.3 From 18d0a34fbd804be11046efe7f10b7212f018091b Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Tue, 12 Mar 2013 19:55:09 +0200 Subject: fix markup --- docs/narr/advconfig.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index ba43f3ea6..434e2bd6c 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article,`"A Whirlwind Tour of Advanced +For more information, see the article, `"A Whirlwind Tour of Advanced Configuration Tactics" `_, in the Pyramid Cookbook. -- cgit v1.2.3 From f5eb753eebbda6fa55ccc5108fcc325931a17f85 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Fri, 5 Apr 2013 22:56:48 +0200 Subject: fix some cross-references --- docs/narr/advconfig.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 434e2bd6c..1b8e33de3 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -148,14 +148,14 @@ one: config.add_route(...) Don't call this function directly with ``config`` as an argument. Instead, -use :meth:`pyramid.config.Configuration.include`: +use :meth:`pyramid.config.Configurator.include`: .. code-block:: python :linenos: config.include(add_routes) -Using :meth:`~pyramid.config.Configuration.include` instead of calling the +Using :meth:`~pyramid.config.Configurator.include` instead of calling the function directly provides a modicum of automated conflict resolution, with the configuration statements you define in the calling code overriding those of the included function. See also :ref:`automatic_conflict_resolution` and @@ -333,7 +333,7 @@ his application: config.add_route(...) Rather than calling this function directly with ``config`` as an argument. -Instead, use :meth:`pyramid.config.Configuration.include`: +Instead, use :meth:`pyramid.config.Configurator.include`: .. code-block:: python :linenos: @@ -343,7 +343,7 @@ Instead, use :meth:`pyramid.config.Configuration.include`: Using ``include`` rather than calling the function directly will allow :ref:`automatic_conflict_resolution` to work. -:meth:`~pyramid.config.Configuration.include` can also accept a :term:`module` +:meth:`~pyramid.config.Configurator.include` can also accept a :term:`module` as an argument: .. code-block:: python @@ -357,7 +357,7 @@ For this to work properly, the ``myapp`` module must contain a callable with the special name ``includeme``, which should perform configuration (like the ``add_routes`` callable we showed above as an example). -:meth:`~pyramid.config.Configuration.include` can also accept a :term:`dotted +:meth:`~pyramid.config.Configurator.include` can also accept a :term:`dotted Python name` to a function or a module. .. note: See :ref:`the_include_tag` for a declarative alternative to -- cgit v1.2.3 From c6601f77f91dc933ca429d1448f4c6b27857b608 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 8 Sep 2013 22:52:54 -0400 Subject: - The ``renderer_globals_factory`` argument to the ``pyramid.config.Configurator` constructor and its ``setup_registry`` method has been removed. The ``set_renderer_globals_factory`` method of ``pyramid.config.Configurator`` has also been removed. The (internal) ``pyramid.interfaces.IRendererGlobals`` interface was also removed. These arguments, methods and interfaces had been deprecated since 1.1. Use a ``BeforeRender`` event subscriber as documented in the "Hooks" chapter of the Pyramid narrative documentation instead of providing renderer globals values to the configurator. --- docs/narr/advconfig.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 1b8e33de3..d3431e39e 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -302,7 +302,6 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.set_view_mapper`, :meth:`~pyramid.config.Configurator.set_authentication_policy`, :meth:`~pyramid.config.Configurator.set_authorization_policy`, -:meth:`~pyramid.config.Configurator.set_renderer_globals_factory`, :meth:`~pyramid.config.Configurator.set_locale_negotiator`, :meth:`~pyramid.config.Configurator.set_default_permission`, :meth:`~pyramid.config.Configurator.add_traverser`, -- cgit v1.2.3 From 2033eeb3602f330930585678aac926749b9c22f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 10 Feb 2014 03:22:33 -0600 Subject: - Garden PR #1121 --- docs/narr/advconfig.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index d3431e39e..9ceaaa495 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -158,8 +158,12 @@ use :meth:`pyramid.config.Configurator.include`: Using :meth:`~pyramid.config.Configurator.include` instead of calling the function directly provides a modicum of automated conflict resolution, with the configuration statements you define in the calling code overriding those -of the included function. See also :ref:`automatic_conflict_resolution` and -:ref:`including_configuration`. +of the included function. + +.. seealso:: + + See also :ref:`automatic_conflict_resolution` and + :ref:`including_configuration`. Using ``config.commit()`` +++++++++++++++++++++++++ -- cgit v1.2.3 From 1205ecbbb4e131b8eed0616a25e44cd3398b7a0f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 6 Nov 2015 00:05:11 -0800 Subject: minor grammar, fix .rst markup, add emphasize lines for diff, rewrap to 79 columns --- docs/narr/advconfig.rst | 133 +++++++++++++++++++++++------------------------- 1 file changed, 65 insertions(+), 68 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index 9ceaaa495..ba9bd1352 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -6,12 +6,11 @@ Advanced Configuration ====================== -To support application extensibility, the :app:`Pyramid` -:term:`Configurator`, by default, detects configuration conflicts and allows -you to include configuration imperatively from other packages or modules. It -also, by default, performs configuration in two separate phases. This allows -you to ignore relative configuration statement ordering in some -circumstances. +To support application extensibility, the :app:`Pyramid` :term:`Configurator` +by default detects configuration conflicts and allows you to include +configuration imperatively from other packages or modules. It also by default +performs configuration in two separate phases. This allows you to ignore +relative configuration statement ordering in some circumstances. .. index:: pair: configuration; conflict detection @@ -70,11 +69,11 @@ try to add another view to the configuration with the same set of server = make_server('0.0.0.0', 8080, app) server.serve_forever() -The application now has two conflicting view configuration statements. When -we try to start it again, it won't start. Instead, we'll receive a traceback -that ends something like this: +The application now has two conflicting view configuration statements. When we +try to start it again, it won't start. Instead we'll receive a traceback that +ends something like this: -.. code-block:: guess +.. code-block:: text :linenos: Traceback (most recent call last): @@ -94,19 +93,19 @@ that ends something like this: This traceback is trying to tell us: -- We've got conflicting information for a set of view configuration - statements (The ``For:`` line). +- We've got conflicting information for a set of view configuration statements + (The ``For:`` line). - There are two statements which conflict, shown beneath the ``For:`` line: ``config.add_view(hello_world. 'hello')`` on line 14 of ``app.py``, and ``config.add_view(goodbye_world, 'hello')`` on line 17 of ``app.py``. -These two configuration statements are in conflict because we've tried to -tell the system that the set of :term:`predicate` values for both view +These two configuration statements are in conflict because we've tried to tell +the system that the set of :term:`predicate` values for both view configurations are exactly the same. Both the ``hello_world`` and ``goodbye_world`` views are configured to respond under the same set of -circumstances. This circumstance: the :term:`view name` (represented by the -``name=`` predicate) is ``hello``. +circumstances. This circumstance, the :term:`view name` represented by the +``name=`` predicate, is ``hello``. This presents an ambiguity that :app:`Pyramid` cannot resolve. Rather than allowing the circumstance to go unreported, by default Pyramid raises a @@ -138,8 +137,7 @@ made by your application. Use the detail provided in the modify your configuration code accordingly. If you're getting a conflict while trying to extend an existing application, -and that application has a function which performs configuration like this -one: +and that application has a function which performs configuration like this one: .. code-block:: python :linenos: @@ -147,8 +145,8 @@ one: def add_routes(config): config.add_route(...) -Don't call this function directly with ``config`` as an argument. Instead, -use :meth:`pyramid.config.Configurator.include`: +Don't call this function directly with ``config`` as an argument. Instead, use +:meth:`pyramid.config.Configurator.include`: .. code-block:: python :linenos: @@ -156,9 +154,9 @@ use :meth:`pyramid.config.Configurator.include`: config.include(add_routes) Using :meth:`~pyramid.config.Configurator.include` instead of calling the -function directly provides a modicum of automated conflict resolution, with -the configuration statements you define in the calling code overriding those -of the included function. +function directly provides a modicum of automated conflict resolution, with the +configuration statements you define in the calling code overriding those of the +included function. .. seealso:: @@ -169,10 +167,10 @@ Using ``config.commit()`` +++++++++++++++++++++++++ You can manually commit a configuration by using the -:meth:`~pyramid.config.Configurator.commit` method between configuration -calls. For example, we prevent conflicts from occurring in the application -we examined previously as the result of adding a ``commit``. Here's the -application that generates conflicts: +:meth:`~pyramid.config.Configurator.commit` method between configuration calls. +For example, we prevent conflicts from occurring in the application we examined +previously as the result of adding a ``commit``. Here's the application that +generates conflicts: .. code-block:: python :linenos: @@ -199,11 +197,12 @@ application that generates conflicts: server = make_server('0.0.0.0', 8080, app) server.serve_forever() -We can prevent the two ``add_view`` calls from conflicting by issuing a call -to :meth:`~pyramid.config.Configurator.commit` between them: +We can prevent the two ``add_view`` calls from conflicting by issuing a call to +:meth:`~pyramid.config.Configurator.commit` between them: .. code-block:: python :linenos: + :emphasize-lines: 16 from wsgiref.simple_server import make_server from pyramid.config import Configurator @@ -230,21 +229,20 @@ to :meth:`~pyramid.config.Configurator.commit` between them: server.serve_forever() In the above example we've issued a call to -:meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` -calls. :meth:`~pyramid.config.Configurator.commit` will execute any pending +:meth:`~pyramid.config.Configurator.commit` between the two ``add_view`` calls. +:meth:`~pyramid.config.Configurator.commit` will execute any pending configuration statements. Calling :meth:`~pyramid.config.Configurator.commit` is safe at any time. It -executes all pending configuration actions and leaves the configuration -action list "clean". +executes all pending configuration actions and leaves the configuration action +list "clean". -Note that :meth:`~pyramid.config.Configurator.commit` has no effect when -you're using an *autocommitting* configurator (see -:ref:`autocommitting_configurator`). +Note that :meth:`~pyramid.config.Configurator.commit` has no effect when you're +using an *autocommitting* configurator (see :ref:`autocommitting_configurator`). .. _autocommitting_configurator: -Using An Autocommitting Configurator +Using an Autocommitting Configurator ++++++++++++++++++++++++++++++++++++ You can also use a heavy hammer to circumvent conflict detection by using a @@ -278,17 +276,17 @@ Automatic Conflict Resolution If your code uses the :meth:`~pyramid.config.Configurator.include` method to include external configuration, some conflicts are automatically resolved. Configuration statements that are made as the result of an "include" will be -overridden by configuration statements that happen within the caller of -the "include" method. +overridden by configuration statements that happen within the caller of the +"include" method. -Automatic conflict resolution supports this goal: if a user wants to reuse a +Automatic conflict resolution supports this goal. If a user wants to reuse a Pyramid application, and they want to customize the configuration of this application without hacking its code "from outside", they can "include" a configuration function from the package and override only some of its configuration statements within the code that does the include. No conflicts will be generated by configuration statements within the code that does the -including, even if configuration statements in the included code would -conflict if it was moved "up" to the calling code. +including, even if configuration statements in the included code would conflict +if it was moved "up" to the calling code. Methods Which Provide Conflict Detection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -312,9 +310,9 @@ These are the methods of the configurator which provide conflict detection: :meth:`~pyramid.config.Configurator.add_resource_url_adapter`, and :meth:`~pyramid.config.Configurator.add_response_adapter`. -:meth:`~pyramid.config.Configurator.add_static_view` also indirectly -provides conflict detection, because it's implemented in terms of the -conflict-aware ``add_route`` and ``add_view`` methods. +:meth:`~pyramid.config.Configurator.add_static_view` also indirectly provides +conflict detection, because it's implemented in terms of the conflict-aware +``add_route`` and ``add_view`` methods. .. index:: pair: configuration; including from external sources @@ -324,10 +322,10 @@ conflict-aware ``add_route`` and ``add_view`` methods. Including Configuration from External Sources --------------------------------------------- -Some application programmers will factor their configuration code in such a -way that it is easy to reuse and override configuration statements. For -example, such a developer might factor out a function used to add routes to -his application: +Some application programmers will factor their configuration code in such a way +that it is easy to reuse and override configuration statements. For example, +such a developer might factor out a function used to add routes to their +application: .. code-block:: python :linenos: @@ -335,8 +333,8 @@ his application: def add_routes(config): config.add_route(...) -Rather than calling this function directly with ``config`` as an argument. -Instead, use :meth:`pyramid.config.Configurator.include`: +Rather than calling this function directly with ``config`` as an argument, +instead use :meth:`pyramid.config.Configurator.include`: .. code-block:: python :linenos: @@ -363,21 +361,21 @@ the special name ``includeme``, which should perform configuration (like the :meth:`~pyramid.config.Configurator.include` can also accept a :term:`dotted Python name` to a function or a module. -.. note: See :ref:`the_include_tag` for a declarative alternative to - the :meth:`~pyramid.config.Configurator.include` method. +.. note:: See :ref:`the_include_tag` for a declarative alternative to the + :meth:`~pyramid.config.Configurator.include` method. .. _twophase_config: Two-Phase Configuration ----------------------- -When a non-autocommitting :term:`Configurator` is used to do configuration -(the default), configuration execution happens in two phases. In the first -phase, "eager" configuration actions (actions that must happen before all -others, such as registering a renderer) are executed, and *discriminators* -are computed for each of the actions that depend on the result of the eager -actions. In the second phase, the discriminators of all actions are compared -to do conflict detection. +When a non-autocommitting :term:`Configurator` is used to do configuration (the +default), configuration execution happens in two phases. In the first phase, +"eager" configuration actions (actions that must happen before all others, such +as registering a renderer) are executed, and *discriminators* are computed for +each of the actions that depend on the result of the eager actions. In the +second phase, the discriminators of all actions are compared to do conflict +detection. Due to this, for configuration methods that have no internal ordering constraints, execution order of configuration method calls is not important. @@ -401,15 +399,14 @@ Has the same result as: config.add_view('some.view', renderer='path_to_custom/renderer.rn') Even though the view statement depends on the registration of a custom -renderer, due to two-phase configuration, the order in which the -configuration statements are issued is not important. ``add_view`` will be -able to find the ``.rn`` renderer even if ``add_renderer`` is called after -``add_view``. +renderer, due to two-phase configuration, the order in which the configuration +statements are issued is not important. ``add_view`` will be able to find the +``.rn`` renderer even if ``add_renderer`` is called after ``add_view``. The same is untrue when you use an *autocommitting* configurator (see :ref:`autocommitting_configurator`). When an autocommitting configurator is -used, two-phase configuration is disabled, and configuration statements must -be ordered in dependency order. +used, two-phase configuration is disabled, and configuration statements must be +ordered in dependency order. Some configuration methods, such as :meth:`~pyramid.config.Configurator.add_route` have internal ordering @@ -420,7 +417,7 @@ added in configuration execution order. More Information ---------------- -For more information, see the article, `"A Whirlwind Tour of Advanced +For more information, see the article `"A Whirlwind Tour of Advanced Configuration Tactics" -`_, +`_ in the Pyramid Cookbook. -- cgit v1.2.3 From 34515f33b3e391dd1c0c727bf5ef4af586b57889 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Jan 2016 02:55:04 -0800 Subject: Rename Cookbook to Pyramid Community Cookbook - use .rst intersphinx labels for pages instead of broken URLs --- docs/narr/advconfig.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/narr/advconfig.rst') diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst index ba9bd1352..bdcdf45a4 100644 --- a/docs/narr/advconfig.rst +++ b/docs/narr/advconfig.rst @@ -417,7 +417,6 @@ added in configuration execution order. More Information ---------------- -For more information, see the article `"A Whirlwind Tour of Advanced -Configuration Tactics" -`_ -in the Pyramid Cookbook. +For more information, see the article :ref:`A Whirlwind Tour of Advanced +Configuration Tactics ` in the Pyramid Community +Cookbook. -- cgit v1.2.3