add pyramid.decorator.reify as an API. Closes #682

Chris McDonough

2012-09-16 07cb8f0e112642a6a40127232ddc06125a73750e

add pyramid.decorator.reify as an API.  Closes #682

 CHANGES.txt

@@ -160,6 +160,9 @@
- ``request.context`` of environment request during ``bootstrap`` is now the
  root object if a context isn't already set on a provided request.

- The ``pyramid.decorator.reify`` function is now an API, and was added to
  the API documentation.

Deprecations
------------

@@ -250,7 +253,9 @@
-------------

- Added an "Upgrading Pyramid" chapter to the narrative documentation.  It
  describes how to cope with deprecations and removals of Pyramid APIs.
  describes how to cope with deprecations and removals of Pyramid APIs and
  how to show Pyramid-generated deprecation warnings while running tests and
  while running a server.

Dependencies
------------

 TODO.txt

@@ -143,7 +143,8 @@
  original dict (after ``__getattr__`` deprecation period, it was deprecated
  in 1.2).

- 1.5: Remove ``pyramid.requests.DeprecatedRequestMethodsMixin``.
- 1.5: Remove ``pyramid.requests.DeprecatedRequestMethodsMixin`` and code in
  renderers module that looks for _response_content_type, et. al.

- 1.5: Maybe? deprecate set_request_property in favor of pointing people at
  add_request_method, schedule removal for 1.8?

 docs/api.rst

@@ -12,6 +12,7 @@
   api/authentication
   api/compat
   api/config
   api/decorator
   api/events
   api/exceptions
   api/httpexceptions

 docs/api/decorator.rst

New file
@@ -0,0 +1,9 @@
.. _decorator_module:

:mod:`pyramid.decorator`
--------------------------

.. automodule:: pyramid.decorator

.. autofunction:: reify


 pyramid/decorator.py

@@ -1,9 +1,31 @@
class reify(object):
    """ Use as a class method decorator.  It operates almost exactly like the
    Python ``@property`` decorator, but it puts the result of the method it
    decorates into the instance dict after the first call, effectively
    replacing the function it decorates with an instance variable.  It is, in
    Python parlance, a non-data descriptor.  An example:

    """ Put the result of a method which uses this (non-data)
    descriptor decorator in the instance dict after the first call,
    effectively replacing the decorator with an instance variable."""
    .. code-block:: python

       class Foo(object):
           @reify
           def jammy(self):
               print 'jammy called'
               return 1

    And usage of Foo:

    .. code-block:: text

       >>> f = Foo()
       >>> v = f.jammy
       'jammy called'
       >>> print v
       1
       >>> f.jammy
       1
       >>> # jammy func not called the second time; it replaced itself with 1
    """
    def __init__(self, wrapped):
        self.wrapped = wrapped
        try:

 pyramid/testing.py

@@ -293,7 +293,7 @@
    request.  For example, by default, the DummyRequest ``GET`` and ``POST``
    attributes are of type ``dict``, unlike a normal Request's GET and POST,
    which are of type ``MultiDict``. If your code uses the features of
    MultiDict, you should either use a"real" :class:`pyramid.request.Request`
    MultiDict, you should either use a real :class:`pyramid.request.Request`
    or adapt your DummyRequest by replacing the attributes with ``MultiDict``
    instances.