make local_name an attribute of Request, move logic from get_localizer into Request.localizer, fix docs; closes #1099

2 files changed, 46 insertions, 45 deletions

diff --git a/docs/api/request.rst b/docs/api/request.rst
index a90cb1ac0..02290eaf3 100644
--- a/docs/api/request.rst
+++ b/docs/api/request.rst
@@ -311,6 +311,20 @@
 
        .. versionadded:: 1.3
 
+   .. attribute::  localizer
+
+       A :term:`localizer` which will use the current locale name to
+       translate values.
+
+       .. versionadded:: 1.5
+
+   .. attribute::  locale_name
+
+       The locale name of the current request as computed by the 
+       :term:`locale negotiator`.
+
+       .. versionadded:: 1.5
+
 .. note::
 
    For information about the API of a :term:`multidict` structure (such as
diff --git a/docs/narr/i18n.rst b/docs/narr/i18n.rst
index 555b06e0f..b62c16ff0 100644
--- a/docs/narr/i18n.rst
+++ b/docs/narr/i18n.rst
@@ -495,7 +495,6 @@ translations will be available to :app:`Pyramid`.
 
 .. index::
    single: localizer
-   single: get_localizer
    single: translation
    single: pluralization
 
@@ -503,19 +502,17 @@ Using a Localizer
 -----------------
 
 A :term:`localizer` is an object that allows you to perform translation or
-pluralization "by hand" in an application.  You may use the
-:func:`pyramid.i18n.get_localizer` function to obtain a :term:`localizer`.
-This function will return either the localizer object implied by the active
-:term:`locale negotiator` or a default localizer object if no explicit locale
-negotiator is registered.
+pluralization "by hand" in an application.  You may use the 
+:attr:`pyramid.request.Request.localizer` attribute to obtain a 
+:term:`localizer`.  The localizer object will be configured to produce 
+translations implied by the active :term:`locale negotiator` or a default
+localizer object if no explicit locale negotiator is registered.
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.i18n import get_localizer
-
    def aview(request):
-       locale = get_localizer(request)
+       localizer = request.localizer
 
 .. note::
 
@@ -538,22 +535,20 @@ translation in a view component of an application might look like so:
 .. code-block:: python
    :linenos:
 
-   from pyramid.i18n import get_localizer
    from pyramid.i18n import TranslationString
 
    ts = TranslationString('Add ${number}', mapping={'number':1},
                           domain='pyramid')
 
    def aview(request):
-       localizer = get_localizer(request)
+       localizer = request.localizer
        translated = localizer.translate(ts) # translation string
        # ... use translated ...
 
-The :func:`~pyramid.i18n.get_localizer` function will return a
-:class:`pyramid.i18n.Localizer` object bound to the locale name
-represented by the request.  The translation returned from its
-:meth:`pyramid.i18n.Localizer.translate` method will depend on the
-``domain`` attribute of the provided translation string as well as the
+The ``request.localizer`` attribute will be a :class:`pyramid.i18n.Localizer`
+object bound to the locale name represented by the request.  The translation
+returned from its :meth:`pyramid.i18n.Localizer.translate` method will depend
+on the ``domain`` attribute of the provided translation string as well as the
 locale of the localizer.
 
 .. note::
@@ -586,10 +581,8 @@ pluralization rules for the number ``n``, and interpolates ``mapping``.
 .. code-block:: python
    :linenos:
 
-   from pyramid.i18n import get_localizer
-
    def aview(request):
-       localizer = get_localizer(request)
+       localizer = request.localizer
        translated = localizer.pluralize('Item', 'Items', 1, 'mydomain')
        # ... use translated ...
 
@@ -611,13 +604,13 @@ object, but the domain and mapping information attached is ignored.
 .. code-block:: python
    :linenos:
 
-   from pyramid.i18n import get_localizer
-
    def aview(request):
-       localizer = get_localizer(request)
+       localizer = request.localizer
        num = 1
-       translated = localizer.pluralize(_('item_plural', default="${number} items"), 
-           None, num, 'mydomain', mapping={'number':num})
+       translated = localizer.pluralize(
+                          _('item_plural', default="${number} items"), 
+                          None, num, 'mydomain', mapping={'number':num}
+                          )
 
 The corresponding message catalog must have language plural definitions and
 plural alternatives set.
@@ -638,7 +631,6 @@ More information on complex plurals can be found in the `gettext documentation
 
 .. index::
    single: locale name
-   single: get_locale_name
    single: negotiate_locale_name
 
 .. _obtaining_the_locale_name:
@@ -647,25 +639,23 @@ Obtaining the Locale Name for a Request
 ---------------------------------------
 
 You can obtain the locale name related to a request by using the
-:func:`pyramid.i18n.get_locale_name` function.
+:func:`pyramid.request.Request.locale_name` attribute of the request.
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.i18n import get_locale_name
-
    def aview(request):
-       locale_name = get_locale_name(request)
+       locale_name = request.locale_name
 
-This returns the locale name negotiated by the currently active
-:term:`locale negotiator` or the :term:`default locale name` if the
-locale negotiator returns ``None``.  You can change the default locale
-name by changing the ``pyramid.default_locale_name`` setting; see
-:ref:`default_locale_name_setting`.
+The locale name of a request is dynamically computed; it will be the locale 
+name negotiated by the currently active :term:`locale negotiator` or 
+the :term:`default locale name` if the locale negotiator returns ``None``. 
+You can change the default locale name by changing the 
+``pyramid.default_locale_name`` setting; see :ref:`default_locale_name_setting`.
 
-Once :func:`~pyramid.i18n.get_locale_name` is first run, the locale
+Once :func:`~pyramid.request.Request.locale_name` is first run, the locale
 name is stored on the request object.  Subsequent calls to
-:func:`~pyramid.i18n.get_locale_name` will return the stored locale
+:func:`~pyramid.request.Request.locale_name` will return the stored locale
 name without invoking the :term:`locale negotiator`.  To avoid this
 caching, you can use the :func:`pyramid.i18n.negotiate_locale_name`
 function:
@@ -684,15 +674,13 @@ You can also obtain the locale name related to a request using the
 .. code-block:: python
    :linenos:
 
-   from pyramid.i18n import get_localizer
-
    def aview(request):
-       localizer = get_localizer(request)
+       localizer = request.localizer
        locale_name = localizer.locale_name
 
 Obtaining the locale name as an attribute of a localizer is equivalent
-to obtaining a locale name by calling the
-:func:`~pyramid.i18n.get_locale_name` function.
+to obtaining a locale name by asking for the 
+:func:`~pyramid.request.Request.locale_name` attribute.
 
 .. index::
    single: date and currency formatting (i18n)
@@ -720,10 +708,9 @@ obtain the locale name for a request to pass to the
    :linenos:
 
    from babel.core import Locale
-   from pyramid.i18n import get_locale_name
 
    def aview(request):
-       locale_name = get_locale_name(request)
+       locale_name = request.locale_name
        locale = Locale(locale_name)
 
 .. index::
@@ -1005,8 +992,8 @@ a particular request.  A locale negotiator is a bit of code which
 accepts a request and which returns a :term:`locale name`.  It is
 consulted when :meth:`pyramid.i18n.Localizer.translate` or
 :meth:`pyramid.i18n.Localizer.pluralize` is invoked.  It is also
-consulted when :func:`~pyramid.i18n.get_locale_name` or
-:func:`~pyramid.i18n.negotiate_locale_name` is invoked.
+consulted when :func:`~pyramid.request.Request.locale_name` is accessed or
+when :func:`~pyramid.i18n.negotiate_locale_name` is invoked.
 
 .. _default_locale_negotiator: