From a6d8b494c3de85eceb33ab57a046fb6955f909fc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 16 Nov 2018 05:34:00 -0800 Subject: Remove most Python 2 mentions from docs. Exclusions: - `docs/tutorials/wiki/*` was written for Python 2 and supposedly won't run on Python 3. - `docs/api/compat.rst` because it drops some stuff and moves other bits into `pyramid.util` and should be part of another PR. - Ignored a couple of times where `env27` and `Python 2.` appear in command output, but they are inconsequential. --- docs/narr/install.rst | 3 +-- docs/narr/upgrading.rst | 1 - docs/narr/webob.rst | 3 +-- 3 files changed, 2 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/install.rst b/docs/narr/install.rst index 248b432d3..268ae5f8d 100644 --- a/docs/narr/install.rst +++ b/docs/narr/install.rst @@ -21,8 +21,7 @@ the following sections. .. sidebar:: Python Versions - As of this writing, :app:`Pyramid` is tested against Python 2.7, - Python 3.4, Python 3.5, Python 3.6, Python 3.7, and PyPy. + As of this writing, :app:`Pyramid` is tested against Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 (with allowed failures), and PyPy3. :app:`Pyramid` is known to run on all popular Unix-like systems such as Linux, macOS, and FreeBSD, as well as on Windows platforms. It is also known to diff --git a/docs/narr/upgrading.rst b/docs/narr/upgrading.rst index 12e146cf1..87e4647c3 100644 --- a/docs/narr/upgrading.rst +++ b/docs/narr/upgrading.rst @@ -86,7 +86,6 @@ At the time of a Pyramid version release, each supports all versions of Python through the end of their lifespans. The end-of-life for a given version of Python is when security updates are no longer released. -- `Python 2.7 Lifespan `_ 2020-01-01. - `Python 3.4 Lifespan `_ 2019-03-16 . - `Python 3.5 Lifespan `_ 2020-09-13 . - `Python 3.6 Lifespan `_ 2021-12-23. diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 89dc6e0f1..c9a5a68e1 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -188,8 +188,7 @@ of them. Here are a couple that might be useful: Text (Unicode) ++++++++++++++ -Many of the properties of the request object will be text values (``unicode`` -under Python 2 or ``str`` under Python 3) if the request encoding/charset is +Many of the properties of the request object will be text values (``str`` type) if the request encoding/charset is provided. If it is provided, the values in ``req.POST``, ``req.GET``, ``req.params``, and ``req.cookies`` will contain text. The client *can* indicate the charset with something like ``Content-Type: -- cgit v1.2.3 From 699bd8720dc16ef5dd3321ebbeaa6fa94505b33f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 16 Nov 2018 05:38:29 -0800 Subject: Remove virtualenv and explicit py3 mentions --- docs/narr/commandline.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index b571a7d7b..962193ec3 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -1006,8 +1006,8 @@ top-level directory, your ``setup.py`` file will look something like this: requires = ['pyramid', 'pyramid_debugtoolbar'] tests_require = [ - 'WebTest >= 1.3.1', # py3 compat - 'pytest', # includes virtualenv + 'WebTest >= 1.3.1', + 'pytest', 'pytest-cov', ] @@ -1073,8 +1073,8 @@ The result will be something like: requires = ['pyramid', 'pyramid_debugtoolbar'] tests_require = [ - 'WebTest >= 1.3.1', # py3 compat - 'pytest', # includes virtualenv + 'WebTest >= 1.3.1', + 'pytest', 'pytest-cov', ] -- cgit v1.2.3 From f77957109be35d7b93014d5623fae7e670797213 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 19 Nov 2018 02:35:36 -0800 Subject: unpin webtest (missed in first pass) --- docs/narr/commandline.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/commandline.rst b/docs/narr/commandline.rst index 962193ec3..21b2a0839 100644 --- a/docs/narr/commandline.rst +++ b/docs/narr/commandline.rst @@ -1006,7 +1006,7 @@ top-level directory, your ``setup.py`` file will look something like this: requires = ['pyramid', 'pyramid_debugtoolbar'] tests_require = [ - 'WebTest >= 1.3.1', + 'WebTest', 'pytest', 'pytest-cov', ] @@ -1073,7 +1073,7 @@ The result will be something like: requires = ['pyramid', 'pyramid_debugtoolbar'] tests_require = [ - 'WebTest >= 1.3.1', + 'WebTest', 'pytest', 'pytest-cov', ] -- cgit v1.2.3 From 8c943501e87bed7836bb9ec1b216a561cc3f6be6 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 19 Nov 2018 21:35:37 -0600 Subject: rip out moar unicode prefixes --- docs/narr/hooks.rst | 8 ++++---- docs/narr/i18n.rst | 11 +++++------ docs/narr/myproject/setup.py | 4 ++-- docs/narr/renderers.rst | 5 ++--- docs/narr/traversal.rst | 6 +++--- docs/narr/urldispatch.rst | 30 +++++++++++++++--------------- docs/narr/views.rst | 39 +++++++++------------------------------ docs/narr/webob.rst | 20 ++++++++------------ 8 files changed, 48 insertions(+), 75 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 9f405c336..5e67a81c7 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -659,15 +659,15 @@ that implements the following interface: ``virtual_root``, and ``virtual_root_path``. These values are typically the result of a resource tree traversal. ``root`` is the physical root object, ``context`` will be a resource - object, ``view_name`` will be the view name used (a Unicode - name), ``subpath`` will be a sequence of Unicode names that + object, ``view_name`` will be the view name used (a string), + ``subpath`` will be a sequence of strings that followed the view name but were not traversed, ``traversed`` - will be a sequence of Unicode names that were traversed + will be a sequence of strings that were traversed (including the virtual root path, if any) ``virtual_root`` will be a resource object representing the virtual root (or the physical root if traversal was not performed), and ``virtual_root_path`` will be a sequence representing the - virtual root path (a sequence of Unicode names) or None if + virtual root path (a sequence of strings) or None if traversal was not performed. Extra keys for special purpose functionality can be added as diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 9b838c7f4..3a4f5af5b 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -33,7 +33,7 @@ While you write your software, you can insert specialized markup into your Python code that makes it possible for the system to translate text values into the languages used by your application's users. This markup creates a :term:`translation string`. A translation string is an object that behaves -mostly like a normal Unicode object, except that it also carries around extra +mostly like a normal Unicode string, except that it also carries around extra information related to its job as part of the :app:`Pyramid` translation machinery. @@ -49,7 +49,7 @@ The most primitive way to create a translation string is to use the from pyramid.i18n import TranslationString ts = TranslationString('Add') -This creates a Unicode-like object that is a TranslationString. +This creates a ``str``-like object that is a TranslationString. .. note:: @@ -61,9 +61,8 @@ This creates a Unicode-like object that is a TranslationString. The first argument to :class:`~pyramid.i18n.TranslationString` is the ``msgid``; it is required. It represents the key into the translation mappings -provided by a particular localization. The ``msgid`` argument must be a Unicode -object or an ASCII string. The msgid may optionally contain *replacement -markers*. For instance: +provided by a particular localization. The ``msgid`` argument must be a string. +The msgid may optionally contain *replacement markers*. For instance: .. code-block:: python :linenos: @@ -429,7 +428,7 @@ Performing a Translation A :term:`localizer` has a ``translate`` method which accepts either a :term:`translation string` or a Unicode string and which returns a Unicode -object representing the translation. Generating a translation in a view +string representing the translation. Generating a translation in a view component of an application might look like so: .. code-block:: python diff --git a/docs/narr/myproject/setup.py b/docs/narr/myproject/setup.py index cf626880f..1ee272270 100644 --- a/docs/narr/myproject/setup.py +++ b/docs/narr/myproject/setup.py @@ -17,8 +17,8 @@ requires = [ ] tests_require = [ - 'WebTest >= 1.3.1', # py3 compat - 'pytest>=3.7.4', + 'WebTest', + 'pytest', 'pytest-cov', ] diff --git a/docs/narr/renderers.rst b/docs/narr/renderers.rst index 493f808d5..6b4982e4b 100644 --- a/docs/narr/renderers.rst +++ b/docs/narr/renderers.rst @@ -145,8 +145,7 @@ used in the ``renderer`` attribute of view configurations. The ``string`` renderer renders a view callable result to a string. If a view callable returns a non-Response object, and the ``string`` renderer is associated in that view's configuration, the result will be to run the object -through the Python ``str`` function to generate a string. Note that if a -Unicode object is returned by the view callable, it is not ``str()``-ified. +through the Python ``str`` function to generate a string. Here's an example of a view that returns a dictionary. If the ``string`` renderer is specified in the configuration for this view, the view will render @@ -496,7 +495,7 @@ interface. A typical class that follows this setup is as follows: def __call__(self, value, system): """ Call the renderer implementation with the value and the system value passed in as arguments and return - the result (a string or unicode object). The value is + the result (a bytes or string object). The value is the return value of a view. The system value is a dictionary containing available system values (e.g., view, context, and request). """ diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 9b91e21ba..769d0984c 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -237,7 +237,7 @@ uses this algorithm to find a :term:`context` resource and a :term:`view name`. The traversal algorithm by default attempts to first URL-unquote and then Unicode-decode each path segment derived from ``PATH_INFO`` from its - natural byte string (``str`` type) representation. URL unquoting is + natural string representation. URL unquoting is performed using the Python standard library ``urllib.unquote`` function. Conversion from a URL-decoded string into Unicode is attempted using the UTF-8 encoding. If any URL-unquoted path segment in ``PATH_INFO`` is not @@ -246,10 +246,10 @@ uses this algorithm to find a :term:`context` resource and a :term:`view name`. to the ``__getitem__`` of any resource during traversal. Thus a request with a ``PATH_INFO`` variable of ``/a/b/c`` maps to the - traversal sequence ``[u'a', u'b', u'c']``. + traversal sequence ``['a', 'b', 'c']``. #. :term:`Traversal` begins at the root resource returned by the root factory. - For the traversal sequence ``[u'a', u'b', u'c']``, the root resource's + For the traversal sequence ``['a', 'b', 'c']``, the root resource's ``__getitem__`` is called with the name ``'a'``. Traversal continues through the sequence. In our example, if the root resource's ``__getitem__`` called with the name ``a`` returns a resource (a.k.a. diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 3b737b46d..b9b42a9bd 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -165,8 +165,8 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text - foo/1/2 -> {'baz':u'1', 'bar':u'2'} - foo/abc/def -> {'baz':u'abc', 'bar':u'def'} + foo/1/2 -> {'baz':'1', 'bar':'2'} + foo/abc/def -> {'baz':'abc', 'bar':'def'} It will not match the following patterns however: @@ -184,7 +184,7 @@ instance, if this route pattern was used: foo/{name}.html The literal path ``/foo/biz.html`` will match the above route pattern, and the -match result will be ``{'name':u'biz'}``. However, the literal path +match result will be ``{'name':'biz'}``. However, the literal path ``/foo/biz`` will not match, because it does not contain a literal ``.html`` at the end of the segment represented by ``{name}.html`` (it only contains ``biz``, not ``biz.html``). @@ -242,7 +242,7 @@ The matchdict will look like so (the value is URL-decoded / UTF-8 decoded): .. code-block:: text - {'bar':u'La Pe\xf1a'} + {'bar': 'La Pe\xf1a'} Literal strings in the path segment should represent the *decoded* value of the ``PATH_INFO`` provided to Pyramid. You don't want to use a URL-encoded value @@ -303,10 +303,10 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text foo/1/2/ -> - {'baz':u'1', 'bar':u'2', 'fizzle':()} + {'baz':'1', 'bar':'2', 'fizzle':()} foo/abc/def/a/b/c -> - {'baz':u'abc', 'bar':u'def', 'fizzle':(u'a', u'b', u'c')} + {'baz':'abc', 'bar':'def', 'fizzle':('a', 'b', 'c')} Note that when a ``*stararg`` remainder match is matched, the value put into the matchdict is turned into a tuple of path segments representing the @@ -327,7 +327,7 @@ Will generate the following matchdict: .. code-block:: text - {'fizzle':(u'La Pe\xf1a', u'a', u'b', u'c')} + {'fizzle':('La Pe\xf1a', 'a', 'b', 'c')} By default, the ``*stararg`` will parse the remainder sections into a tuple split by segment. Changing the regular expression used to match a marker can @@ -341,8 +341,8 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text - foo/1/2/ -> {'baz':u'1', 'bar':u'2', 'fizzle':u''} - foo/abc/def/a/b/c -> {'baz':u'abc', 'bar':u'def', 'fizzle': u'a/b/c'} + foo/1/2/ -> {'baz':'1', 'bar':'2', 'fizzle':''} + foo/abc/def/a/b/c -> {'baz':'abc', 'bar':'def', 'fizzle': 'a/b/c'} This occurs because the default regular expression for a marker is ``[^/]+`` which will match everything up to the first ``/``, while ``{fizzle:.*}`` will @@ -562,12 +562,12 @@ Here is an example of a corresponding ``mypackage.views`` module: @view_config(route_name='user') def user_view(request): user = request.matchdict['user'] - return Response(u'The user is {}.'.format(user)) + return Response('The user is {}.'.format(user)) @view_config(route_name='tag') def tag_view(request): tag = request.matchdict['tag'] - return Response(u'The tag is {}.'.format(tag)) + return Response('The tag is {}.'.format(tag)) The above configuration will allow :app:`Pyramid` to service URLs in these forms: @@ -714,13 +714,13 @@ Therefore, if you've added a route like so: .. code-block:: python - config.add_route('la', u'/La Peña/{city}') + config.add_route('la', '/La Peña/{city}') And you later generate a URL using ``route_path`` or ``route_url`` like so: .. code-block:: python - url = request.route_path('la', city=u'Québec') + url = request.route_path('la', city='Québec') You will wind up with the path encoded to UTF-8 and URL-quoted like so: @@ -739,7 +739,7 @@ And you later generate a URL using ``route_path`` or ``route_url`` using a .. code-block:: python - url = request.route_path('abc', foo=u'Québec/biz') + url = request.route_path('abc', foo='Québec/biz') The value you pass will be URL-quoted except for embedded slashes in the result: @@ -752,7 +752,7 @@ You can get a similar result by passing a tuple composed of path elements: .. code-block:: python - url = request.route_path('abc', foo=(u'Québec', u'biz')) + url = request.route_path('abc', foo=('Québec', 'biz')) Each value in the tuple will be URL-quoted and joined by slashes in this case: diff --git a/docs/narr/views.rst b/docs/narr/views.rst index a53063f78..40717c37a 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -442,10 +442,7 @@ browser client, and its ``action`` points at some :app:`Pyramid` view code: :linenos: - - - -
+
@@ -457,8 +454,8 @@ browser client, and its ``action`` points at some :app:`Pyramid` view code: The ``myview`` view code in the :app:`Pyramid` application *must* expect that -the values returned by ``request.params`` will be of type ``unicode``, as -opposed to type ``str``. The following will work to accept a form post from the +the values returned by ``request.params`` will be of type ``str``, as opposed +to type ``bytes``. The following will work to accept a form post from the above form: .. code-block:: python @@ -468,24 +465,12 @@ above form: firstname = request.params['firstname'] lastname = request.params['lastname'] -But the following ``myview`` view code *may not* work, as it tries to decode -already-decoded (``unicode``) values obtained from ``request.params``: - -.. code-block:: python - :linenos: - - def myview(request): - # the .decode('utf-8') will break below if there are any high-order - # characters in the firstname or lastname - firstname = request.params['firstname'].decode('utf-8') - lastname = request.params['lastname'].decode('utf-8') - For implicit decoding to work reliably, you should ensure that every form you render that posts to a :app:`Pyramid` view explicitly defines a charset encoding of UTF-8. This can be done via a response that has a ``;charset=UTF-8`` in its ``Content-Type`` header; or, as in the form above, -with a ``meta http-equiv`` tag that implies that the charset is UTF-8 within -the HTML ``head`` of the page containing the form. This must be done +with a ``accept-charset`` tag that implies that informs the browser that the +server expects the form content to be encoded using UTF-8. This must be done explicitly because all known browser clients assume that they should encode form data in the same character set implied by the ``Content-Type`` value of the response containing the form when subsequently submitting that form. There @@ -499,21 +484,15 @@ when it can't decode some high-order character encoded in another character set within form data, e.g., when ``request.params['somename']`` is accessed. If you are using the :class:`~pyramid.response.Response` class to generate a -response, or if you use the ``render_template_*`` templating APIs, the UTF-8 -``charset`` is set automatically as the default via the ``Content-Type`` -header. If you return a ``Content-Type`` header without an explicit -``charset``, a request will add a ``;charset=utf-8`` trailer to the +response, or if you use the ``pyramid.renderers.render_*`` templating APIs, +the UTF-8 ``charset`` is set automatically as the default via the +``Content-Type`` header. If you return a ``Content-Type`` header without an +explicit ``charset``, a request will add a ``;charset=utf-8`` trailer to the ``Content-Type`` header value for you for response content types that are textual (e.g., ``text/html`` or ``application/xml``) as it is rendered. If you are using your own response object, you will need to ensure you do this yourself. -.. note:: Only the *values* of request params obtained via ``request.params``, - ``request.GET`` or ``request.POST`` are decoded to Unicode objects - implicitly in the :app:`Pyramid` default configuration. The keys are still - (byte) strings. - - .. index:: single: view calling convention diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index c9a5a68e1..72f2db42e 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -188,14 +188,10 @@ of them. Here are a couple that might be useful: Text (Unicode) ++++++++++++++ -Many of the properties of the request object will be text values (``str`` type) if the request encoding/charset is -provided. If it is provided, the values in ``req.POST``, ``req.GET``, -``req.params``, and ``req.cookies`` will contain text. The client *can* -indicate the charset with something like ``Content-Type: -application/x-www-form-urlencoded; charset=utf8``, but browsers seldom set -this. You can reset the charset of an existing request with ``newreq = -req.decode('utf-8')``, or during instantiation with ``Request(environ, -charset='utf8')``. +Most of the properties of the request object will be text values. +The values in ``req.POST``, ``req.GET``, ``req.params``, and ``req.cookies`` will contain text and are generated assuming a UTF-8 charset. +The client *can* indicate the charset with something like ``Content-Type: application/x-www-form-urlencoded; charset=utf8``, but browsers seldom set this. +You can reset the charset of an existing request with ``newreq = req.decode('utf-8')``, or during instantiation with ``Request(environ, charset='utf8')``. .. index:: single: multidict (WebOb) @@ -263,7 +259,7 @@ to a :app:`Pyramid` application: jQuery.ajax({type:'POST', url: 'http://localhost:6543/', // the pyramid server data: JSON.stringify({'a':1}), - contentType: 'application/json; charset=utf-8'}); + contentType: 'application/json'}); When such a request reaches a view in your application, the ``request.json_body`` attribute will be available in the view callable body. @@ -279,7 +275,7 @@ For the above view, printed to the console will be: .. code-block:: python - {u'a': 1} + {'a': 1} For bonus points, here's a bit of client-side code that will produce a request that has a body suitable for reading via ``request.json_body`` using Python's @@ -385,8 +381,8 @@ A response object has three fundamental parts: ``response.app_iter`` An iterable (such as a list or generator) that will produce the content of - the response. This is also accessible as ``response.body`` (a string), - ``response.text`` (a unicode object, informed by ``response.charset``), and + the response. This is also accessible as ``response.body`` (bytes), + ``response.text`` (a string, informed by ``response.charset``), and ``response.body_file`` (a file-like object; writing to it appends to ``app_iter``). -- cgit v1.2.3 From a08763a9b5213ed352a26c603a6d3722aebe9dd0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Nov 2018 00:42:39 -0800 Subject: proper hyphenation of UTF-8-decoded --- docs/narr/traversal.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst index 769d0984c..0282c6096 100644 --- a/docs/narr/traversal.rst +++ b/docs/narr/traversal.rst @@ -242,7 +242,7 @@ uses this algorithm to find a :term:`context` resource and a :term:`view name`. Conversion from a URL-decoded string into Unicode is attempted using the UTF-8 encoding. If any URL-unquoted path segment in ``PATH_INFO`` is not decodeable using the UTF-8 decoding, a :exc:`TypeError` is raised. A - segment will be fully URL-unquoted and UTF8-decoded before it is passed in + segment will be fully URL-unquoted and UTF-8-decoded before it is passed in to the ``__getitem__`` of any resource during traversal. Thus a request with a ``PATH_INFO`` variable of ``/a/b/c`` maps to the -- cgit v1.2.3 From 1007fa3773a311a72dd7b2e5e8c52584c5d6e416 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Nov 2018 00:55:17 -0800 Subject: proper spacing of interpreter output between a dict's colon and value --- docs/narr/urldispatch.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index b9b42a9bd..129dce8f3 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -165,8 +165,8 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text - foo/1/2 -> {'baz':'1', 'bar':'2'} - foo/abc/def -> {'baz':'abc', 'bar':'def'} + foo/1/2 -> {'baz': '1', 'bar': '2'} + foo/abc/def -> {'baz': 'abc', 'bar': 'def'} It will not match the following patterns however: @@ -303,10 +303,10 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text foo/1/2/ -> - {'baz':'1', 'bar':'2', 'fizzle':()} + {'baz': '1', 'bar': '2', 'fizzle': ()} foo/abc/def/a/b/c -> - {'baz':'abc', 'bar':'def', 'fizzle':('a', 'b', 'c')} + {'baz': 'abc', 'bar': 'def', 'fizzle': ('a', 'b', 'c')} Note that when a ``*stararg`` remainder match is matched, the value put into the matchdict is turned into a tuple of path segments representing the @@ -327,7 +327,7 @@ Will generate the following matchdict: .. code-block:: text - {'fizzle':('La Pe\xf1a', 'a', 'b', 'c')} + {'fizzle': ('La Pe\xf1a', 'a', 'b', 'c')} By default, the ``*stararg`` will parse the remainder sections into a tuple split by segment. Changing the regular expression used to match a marker can @@ -341,8 +341,8 @@ The above pattern will match these URLs, generating the following matchdicts: .. code-block:: text - foo/1/2/ -> {'baz':'1', 'bar':'2', 'fizzle':''} - foo/abc/def/a/b/c -> {'baz':'abc', 'bar':'def', 'fizzle': 'a/b/c'} + foo/1/2/ -> {'baz': '1', 'bar': '2', 'fizzle': ''} + foo/abc/def/a/b/c -> {'baz': 'abc', 'bar': 'def', 'fizzle': 'a/b/c'} This occurs because the default regular expression for a marker is ``[^/]+`` which will match everything up to the first ``/``, while ``{fizzle:.*}`` will -- cgit v1.2.3 From 9eec98980d17fee7c27aa1b36a0b8ae74b081e26 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Nov 2018 00:59:57 -0800 Subject: grammar fixes --- docs/narr/views.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 40717c37a..1b4118b85 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -469,7 +469,7 @@ For implicit decoding to work reliably, you should ensure that every form you render that posts to a :app:`Pyramid` view explicitly defines a charset encoding of UTF-8. This can be done via a response that has a ``;charset=UTF-8`` in its ``Content-Type`` header; or, as in the form above, -with a ``accept-charset`` tag that implies that informs the browser that the +with an ``accept-charset`` attribute, informing the browser that the server expects the form content to be encoded using UTF-8. This must be done explicitly because all known browser clients assume that they should encode form data in the same character set implied by the ``Content-Type`` value of -- cgit v1.2.3 From c9d5832707877faac5b94943e00951b69192185d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Nov 2018 01:07:29 -0800 Subject: moar proper spacing of interpreter output between a dict's colon and value --- docs/narr/urldispatch.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 129dce8f3..9372163e8 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -184,7 +184,7 @@ instance, if this route pattern was used: foo/{name}.html The literal path ``/foo/biz.html`` will match the above route pattern, and the -match result will be ``{'name':'biz'}``. However, the literal path +match result will be ``{'name': 'biz'}``. However, the literal path ``/foo/biz`` will not match, because it does not contain a literal ``.html`` at the end of the segment represented by ``{name}.html`` (it only contains ``biz``, not ``biz.html``). @@ -513,7 +513,7 @@ When the ``/site/{id}`` route pattern matches during a request, the When this route matches, a ``matchdict`` will be generated and attached to the request as ``request.matchdict``. If the specific URL matched is ``/site/1``, the ``matchdict`` will be a dictionary with a single key, ``id``; the value -will be the string ``'1'``, ex.: ``{'id':'1'}``. +will be the string ``'1'``, ex.: ``{'id': '1'}``. The ``mypackage.views`` module referred to above might look like so: @@ -581,17 +581,17 @@ forms: - When a URL matches the pattern ``/ideas/{idea}``, the view callable available at the dotted Python pathname ``mypackage.views.idea_view`` will be called. For the specific URL ``/ideas/1``, the ``matchdict`` generated - and attached to the :term:`request` will consist of ``{'idea':'1'}``. + and attached to the :term:`request` will consist of ``{'idea': '1'}``. - When a URL matches the pattern ``/users/{user}``, the view callable available at the dotted Python pathname ``mypackage.views.user_view`` will be called. For the specific URL ``/users/1``, the ``matchdict`` generated and - attached to the :term:`request` will consist of ``{'user':'1'}``. + attached to the :term:`request` will consist of ``{'user': '1'}``. - When a URL matches the pattern ``/tags/{tag}``, the view callable available at the dotted Python pathname ``mypackage.views.tag_view`` will be called. For the specific URL ``/tags/1``, the ``matchdict`` generated and attached to - the :term:`request` will consist of ``{'tag':'1'}``. + the :term:`request` will consist of ``{'tag': '1'}``. In this example we've again associated each of our routes with a :term:`view callable` directly. In all cases, the request, which will have a ``matchdict`` -- cgit v1.2.3 From b1c500c3d4cb269aed254742501040c1c64367c2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Nov 2018 01:11:09 -0800 Subject: s/msgid/``msgid`` as needed --- docs/narr/i18n.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst index 3a4f5af5b..b8cd396c0 100644 --- a/docs/narr/i18n.rst +++ b/docs/narr/i18n.rst @@ -62,7 +62,7 @@ This creates a ``str``-like object that is a TranslationString. The first argument to :class:`~pyramid.i18n.TranslationString` is the ``msgid``; it is required. It represents the key into the translation mappings provided by a particular localization. The ``msgid`` argument must be a string. -The msgid may optionally contain *replacement markers*. For instance: +The ``msgid`` may optionally contain *replacement markers*. For instance: .. code-block:: python :linenos: @@ -80,14 +80,14 @@ may be supplied at the same time as the replacement marker itself: from pyramid.i18n import TranslationString ts = TranslationString('Add ${number}', mapping={'number':1}) -Any number of replacement markers can be present in the msgid value, any number +Any number of replacement markers can be present in the ``msgid`` value, any number of times. Only markers which can be replaced by the values in the *mapping* will be replaced at translation time. The others will not be interpolated and will be output literally. A translation string should also usually carry a *domain*. The domain represents a translation category to disambiguate it from other translations of -the same msgid, in case they conflict. +the same ``msgid``, in case they conflict. .. code-block:: python :linenos: @@ -99,7 +99,7 @@ the same msgid, in case they conflict. The above translation string named a domain of ``form``. A :term:`translator` function will often use the domain to locate the right translator file on the filesystem which contains translations for a given domain. In this case, if it -were trying to translate our msgid to German, it might try to find a +were trying to translate our ``msgid`` to German, it might try to find a translation from a :term:`gettext` file within a :term:`translation directory` like this one: -- cgit v1.2.3 From b404d4b29e5eaa08fb38e9bd4818e1a2d390c10b Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 23 Nov 2018 15:54:53 -0600 Subject: fix a couple more doc strings --- docs/narr/hooks.rst | 2 +- docs/narr/webob.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 5e67a81c7..0dac8d426 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -667,7 +667,7 @@ that implements the following interface: will be a resource object representing the virtual root (or the physical root if traversal was not performed), and ``virtual_root_path`` will be a sequence representing the - virtual root path (a sequence of strings) or None if + virtual root path (a sequence of strings) or ``None`` if traversal was not performed. Extra keys for special purpose functionality can be added as diff --git a/docs/narr/webob.rst b/docs/narr/webob.rst index 72f2db42e..665bbddc9 100644 --- a/docs/narr/webob.rst +++ b/docs/narr/webob.rst @@ -382,7 +382,7 @@ A response object has three fundamental parts: ``response.app_iter`` An iterable (such as a list or generator) that will produce the content of the response. This is also accessible as ``response.body`` (bytes), - ``response.text`` (a string, informed by ``response.charset``), and + ``response.text`` (a Unicode string, informed by ``response.charset``), and ``response.body_file`` (a file-like object; writing to it appends to ``app_iter``). -- cgit v1.2.3 From 641a788dc61acf2efb91f4d2a196cb585d89a47b Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:14:31 -0600 Subject: Rework sentence to simplify --- docs/narr/startup.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 17926c716..7ce36f05e 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -48,9 +48,9 @@ Here's a high-level time-ordered overview of what happens when you press the format. #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, - ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This - section represents the configuration of a :term:`WSGI` application that will - be served. If you're using a simple application (e.g., ``[app:main]``), the + ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. + This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + If you're using a simple application (e.g., ``[app:main]``), the application's ``paste.app_factory`` :term:`entry point` will be named on the ``use=`` line within the section's configuration. If instead of a simple application, you're using a WSGI :term:`pipeline` (e.g., a -- cgit v1.2.3 From d728e112303a1eabd774fb2b8fde7d117422222d Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:15:16 -0600 Subject: Split paragraph in two --- docs/narr/startup.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 7ce36f05e..a72b89d4c 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -50,6 +50,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + If you're using a simple application (e.g., ``[app:main]``), the application's ``paste.app_factory`` :term:`entry point` will be named on the ``use=`` line within the section's configuration. If instead of a simple -- cgit v1.2.3 From 197a77b5783151c742e335235323627c0538b2a6 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:16:08 -0600 Subject: Split long sentence into two and clarify each --- docs/narr/startup.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index a72b89d4c..f740baadf 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,11 +68,9 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for this application. See :ref:`logging_config` for more information. -#. The application's *constructor* named by the entry point referenced on the - ``use=`` line of the section representing your :app:`Pyramid` application is - passed the key/value parameters mentioned within the section in which it's - defined. The constructor is meant to return a :term:`router` instance, - which is a :term:`WSGI` application. +#. The application's *constructor* is named by the entry point referenced on the ``use=`` line of the ``ini`` section which configures your :app:`Pyramid` application. + It is passed the key/value parameters mentioned within the this section. + The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. For :app:`Pyramid` applications, the constructor will be a function named ``main`` in the ``__init__.py`` file within the :term:`package` in which -- cgit v1.2.3 From d9137a9b888271cdd9e52d5e885fd04589b67578 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:53:40 -0600 Subject: Simply sentences by adding hyperlinks --- docs/narr/startup.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index f740baadf..6c5fe8f60 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -47,10 +47,14 @@ Here's a high-level time-ordered overview of what happens when you press the :term:`PasteDeploy` library and returns a parser that can understand the format. +.. _ini_section_discovery: + #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + .. _entry_point_discovery: + If you're using a simple application (e.g., ``[app:main]``), the application's ``paste.app_factory`` :term:`entry point` will be named on the ``use=`` line within the section's configuration. If instead of a simple @@ -68,8 +72,8 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for this application. See :ref:`logging_config` for more information. -#. The application's *constructor* is named by the entry point referenced on the ``use=`` line of the ``ini`` section which configures your :app:`Pyramid` application. - It is passed the key/value parameters mentioned within the this section. +#. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. + It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. For :app:`Pyramid` applications, the constructor will be a function named -- cgit v1.2.3 From fbf42997374321d395be9ff11a264954e0fcb70e Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:54:06 -0600 Subject: Use present tense instead of future tense --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 6c5fe8f60..baa31000d 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -76,7 +76,7 @@ Here's a high-level time-ordered overview of what happens when you press It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. - For :app:`Pyramid` applications, the constructor will be a function named + For :app:`Pyramid` applications, the constructor is a function named ``main`` in the ``__init__.py`` file within the :term:`package` in which your application lives. If this function succeeds, it will return a :app:`Pyramid` :term:`router` instance. Here's the contents of an example -- cgit v1.2.3 From 799810caee1b9acb74950dbc5b0f003a386f8a38 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:55:16 -0600 Subject: Better english --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index baa31000d..eb255d527 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -74,7 +74,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. It is passed the key/value parameters in :ref:`the application's .ini section `. - The constructor is meant to return a :term:`router` instance, which is a :term:`WSGI` application. + The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. For :app:`Pyramid` applications, the constructor is a function named ``main`` in the ``__init__.py`` file within the :term:`package` in which -- cgit v1.2.3 From 2ce055b7f3e81b363d25925276fe7bbcad705be7 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Fri, 23 Nov 2018 23:59:14 -0600 Subject: Remove extra word --- docs/narr/logging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 2acdb33f4..c0008282a 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -39,7 +39,7 @@ format `. This is the same format used as the Python :ref:`logging module's Configuration file format `. The application-related and logging-related sections in the configuration file can coexist peacefully, and the logging-related sections in the file are used -from when you run ``pserve``. +when you run ``pserve``. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, a thin wrapper around the :func:`logging.config.fileConfig` using the specified -- cgit v1.2.3 From 8a919fa0efb4448954c70cd1cba9e72f57008cf9 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:03:17 -0600 Subject: Split long sentence --- docs/narr/logging.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index c0008282a..ad63b218f 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -37,9 +37,8 @@ These ``.ini`` file sections are passed to the `logging module's config file con PasteDeploy ``.ini`` files use the Python standard library :mod:`ConfigParser format `. This is the same format used as the Python :ref:`logging module's Configuration file format `. -The application-related and logging-related sections in the configuration file -can coexist peacefully, and the logging-related sections in the file are used -when you run ``pserve``. +The application-related and logging-related sections in the configuration file can coexist peacefully. +The logging-related sections in the file configure logging when you run ``pserve``. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, a thin wrapper around the :func:`logging.config.fileConfig` using the specified -- cgit v1.2.3 From 28d5c1c17f683a69345ddfe2a27b5c5aa2668d5a Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:15:12 -0600 Subject: Improve sentence --- docs/narr/logging.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index ad63b218f..408c8fc7c 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -43,8 +43,8 @@ The logging-related sections in the file configure logging when you run ``pserve The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, a thin wrapper around the :func:`logging.config.fileConfig` using the specified ``.ini`` file, if it contains a ``[loggers]`` section (all of the -cookiecutter-generated ``.ini`` files do). ``setup_logging`` reads the logging -configuration from the ini file upon which ``pserve`` was invoked. +cookiecutter-generated ``.ini`` files do). +``setup_logging`` reads the logging configuration from the ``ini`` file given on the ``pserve`` command line. Default logging configuration is provided in both the default ``development.ini`` and the ``production.ini`` files. If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration -- cgit v1.2.3 From 2b306dcb80b9ec510c74f3baa1de2ca23339cfc3 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:34:44 -0600 Subject: Read better --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index eb255d527..29e5436fe 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -70,7 +70,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The framework finds all :mod:`logging` related configuration in the ``.ini`` file and uses it to configure the Python standard library logging system for - this application. See :ref:`logging_config` for more information. + the application. See :ref:`logging_config` for more information. #. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. It is passed the key/value parameters in :ref:`the application's .ini section `. -- cgit v1.2.3 From bc17531c1eb67f2a5eb31b966f2ede63d767b803 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 00:59:35 -0600 Subject: Split long complicated sentence into 3 --- docs/narr/logging.rst | 9 ++++----- docs/narr/startup.rst | 2 ++ 2 files changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 408c8fc7c..b12434317 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -40,11 +40,10 @@ format `. This is the same format used as the Python The application-related and logging-related sections in the configuration file can coexist peacefully. The logging-related sections in the file configure logging when you run ``pserve``. -The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, -a thin wrapper around the :func:`logging.config.fileConfig` using the specified -``.ini`` file, if it contains a ``[loggers]`` section (all of the -cookiecutter-generated ``.ini`` files do). -``setup_logging`` reads the logging configuration from the ``ini`` file given on the ``pserve`` command line. +On :ref:`startup ` the ``pserve`` command :ref:`configures logging ` using the ``.ini`` file given to it. +If the ``.ini`` file contains a ``[loggers]`` section (all of the cookiecutter-generated ``.ini`` files do) ``pserve`` calls the :func:`pyramid.paster.setup_logging` function. +The :func:`setup_logging` function is a thin wrapper around the :func:`logging.config.fileConfig`. +When ``setup_logging`` is passed the ``ini`` file given on the ``pserve`` command line it reads the file and configures logging. Default logging configuration is provided in both the default ``development.ini`` and the ``production.ini`` files. If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 29e5436fe..ff94f441e 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,6 +68,8 @@ Here's a high-level time-ordered overview of what happens when you press will have a single ``[app:main]`` section in it, and this will be the application served. +.. _startup_logging_initialization: + #. The framework finds all :mod:`logging` related configuration in the ``.ini`` file and uses it to configure the Python standard library logging system for the application. See :ref:`logging_config` for more information. -- cgit v1.2.3 From 27c82826d669e4b381328643f84ccfff5bcba16e Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 01:13:47 -0600 Subject: Add index entries for logging initialization --- docs/narr/logging.rst | 3 +++ docs/narr/startup.rst | 3 +++ 2 files changed, 6 insertions(+) (limited to 'docs/narr') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index b12434317..8ae8469de 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -40,6 +40,9 @@ format `. This is the same format used as the Python The application-related and logging-related sections in the configuration file can coexist peacefully. The logging-related sections in the file configure logging when you run ``pserve``. +.. index:: + pair: logging; startup + On :ref:`startup ` the ``pserve`` command :ref:`configures logging ` using the ``.ini`` file given to it. If the ``.ini`` file contains a ``[loggers]`` section (all of the cookiecutter-generated ``.ini`` files do) ``pserve`` calls the :func:`pyramid.paster.setup_logging` function. The :func:`setup_logging` function is a thin wrapper around the :func:`logging.config.fileConfig`. diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index ff94f441e..e2a18cd60 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -68,6 +68,9 @@ Here's a high-level time-ordered overview of what happens when you press will have a single ``[app:main]`` section in it, and this will be the application served. +.. index:: + pair: logging; startup + .. _startup_logging_initialization: #. The framework finds all :mod:`logging` related configuration in the ``.ini`` -- cgit v1.2.3 From 6ca75ed314188de40a8676bf1258762bc9522b91 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 08:10:47 -0600 Subject: Use numbered list instead of a paragraph per Steve Piercy --- docs/narr/logging.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/logging.rst b/docs/narr/logging.rst index 8ae8469de..58bd2d4ec 100644 --- a/docs/narr/logging.rst +++ b/docs/narr/logging.rst @@ -43,10 +43,14 @@ The logging-related sections in the file configure logging when you run ``pserve .. index:: pair: logging; startup -On :ref:`startup ` the ``pserve`` command :ref:`configures logging ` using the ``.ini`` file given to it. -If the ``.ini`` file contains a ``[loggers]`` section (all of the cookiecutter-generated ``.ini`` files do) ``pserve`` calls the :func:`pyramid.paster.setup_logging` function. -The :func:`setup_logging` function is a thin wrapper around the :func:`logging.config.fileConfig`. -When ``setup_logging`` is passed the ``ini`` file given on the ``pserve`` command line it reads the file and configures logging. +If the configuration ``.ini`` file, specified when invoking ``pserve``, contains a ``[loggers]`` section then on :ref:`startup ` the following process takes place: + +#. The ``pserve`` command calls the :func:`pyramid.paster.setup_logging` function, passing the ``.ini`` file. + +#. ``setup_logging`` is a thin wrapper which calls the Python standard library's :func:`logging.config.fileConfig`. + +#. :func:`logging.config.fileConfig` reads the logging configuration from the ``.ini`` file and configures logging. + Default logging configuration is provided in both the default ``development.ini`` and the ``production.ini`` files. If you use our cookiecutter to generate a Pyramid project with the name of the package as ``hello_world``, then the logging configuration -- cgit v1.2.3 From a0d75f29020b8763982a9e77fcdca354cf663913 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 08:51:09 -0600 Subject: Say 2 things in separate sentences --- docs/narr/startup.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index e2a18cd60..555663804 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -51,7 +51,8 @@ Here's a high-level time-ordered overview of what happens when you press #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. - This section becomes the ``ini`` section for the :term:`WSGI` webserver portion of your application -- the part ``Pyramid`` was built to help with. + This section configures the :term:`WSGI` webserver which serves your application. + As such it is the ``ini`` section for your application and can supply many of your application's :term:`settings`. .. _entry_point_discovery: -- cgit v1.2.3 From ee8033a6b1292bc9a65151e34cdc34dcffd33efb Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 08:52:34 -0600 Subject: Shorten and fix sentence per Steve Piercy --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 555663804..af9415cc9 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -78,7 +78,7 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for the application. See :ref:`logging_config` for more information. -#. The application's entry point :ref:`found above `, usually the entry point referenced on the above mentioned ``use=`` line, is the application's *constructor*. +#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned ` ``use=`` line, is the application's *constructor*. It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. -- cgit v1.2.3 From 21bff45c53e06d283518265b5381450b2f188944 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 09:18:53 -0600 Subject: Add "constructor" glossary entry --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index af9415cc9..0b3680bca 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -78,7 +78,7 @@ Here's a high-level time-ordered overview of what happens when you press file and uses it to configure the Python standard library logging system for the application. See :ref:`logging_config` for more information. -#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned ` ``use=`` line, is the application's *constructor*. +#. The application's entry point, usually the entry point referenced on the :ref:`above mentioned ` ``use=`` line, is the application's :term:`constructor`. It is passed the key/value parameters in :ref:`the application's .ini section `. The constructor should return a :term:`router` instance, which is a :term:`WSGI` application. -- cgit v1.2.3 From a86f9f56067c80eedbdabc4c983628e2aa31479d Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 09:41:51 -0600 Subject: Better wording --- docs/narr/startup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 0b3680bca..65669e0b9 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -52,7 +52,7 @@ Here's a high-level time-ordered overview of what happens when you press #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. This section configures the :term:`WSGI` webserver which serves your application. - As such it is the ``ini`` section for your application and can supply many of your application's :term:`settings`. + As such it is the ``ini`` section for your application and can be the source for many of your application's :term:`settings`. .. _entry_point_discovery: -- cgit v1.2.3 From 19a7ed53e981afdc0fee3f2a307f8917ce6c8a95 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Sat, 24 Nov 2018 15:22:22 -0600 Subject: Fix REST indentation so numbered list does not restart counting --- docs/narr/startup.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/startup.rst b/docs/narr/startup.rst index 65669e0b9..37825d2da 100644 --- a/docs/narr/startup.rst +++ b/docs/narr/startup.rst @@ -47,7 +47,7 @@ Here's a high-level time-ordered overview of what happens when you press the :term:`PasteDeploy` library and returns a parser that can understand the format. -.. _ini_section_discovery: + .. _ini_section_discovery: #. The :term:`PasteDeploy` finds a section named either ``[app:main]``, ``[pipeline:main]``, or ``[composite:main]`` in the ``.ini`` file. @@ -69,10 +69,10 @@ Here's a high-level time-ordered overview of what happens when you press will have a single ``[app:main]`` section in it, and this will be the application served. -.. index:: - pair: logging; startup + .. index:: + pair: logging; startup -.. _startup_logging_initialization: + .. _startup_logging_initialization: #. The framework finds all :mod:`logging` related configuration in the ``.ini`` file and uses it to configure the Python standard library logging system for -- cgit v1.2.3