Metadata-Version: 1.0
Name: plone.subrequest
Version: 1.6.1
Summary: Subrequests for Zope2
Home-page: http://pypi.python.org/pypi/plone.subrequest/
Author: Plone Foundation
Author-email: plone-developers@lists.sourceforge.net
License: GPL version 2
Description: Overview
        ========
        
        plone.subrequest provides a mechanism for issuing subrequests under Zope2.
        
        Installation
        ============
        
        Plone 4
        -------
        
        An entry point is provided so no special installation is required past adding
        `plone.subrequest` to your instance's `eggs`.
        
        Zope 2.12 without Plone
        -----------------------
        
        Load this package's ZCML in the usual manner.
        
        Zope 2.10
        ---------
        
        You must install ZPublisherEventsBackport_ to use this package with Zope 2.10
        and load both package's ZCML. The tests require Zope 2.12 / Python 2.6 so will
        not run.
        
        .. _ZPublisherEventsBackport: http://pypi.python.org/pypi/ZPublisherEventsBackport
        
        
        Usage
        =====
        
        Basic usage
        -----------
        
        .. test-case: absolute
        
        Call ``subrequest(url)``, it returns a response object.
        
            >>> from plone.subrequest import subrequest
            >>> response = subrequest('/folder1/@@url')
            >>> response.getBody()
            'http://nohost/folder1'
        
        .. test-case: response-write
        
        ``response.getBody()`` also works for code that calls ``response.write(data)``.
        
            >>> response = subrequest('/@@response-write')
            >>> response.getBody()
            'Some data.\nSome more data.\n'
        
        But in this case ``response.getBody()`` may only be called once.
        
            >>> response.getBody()
            Traceback (most recent call last):
                ...
            ValueError: I/O operation on closed file
        
        Accessing the response body as a file
        -------------------------------------
        
        .. test-case: stdout
        
        Some code may call ``response.write(data)``.
        
            >>> response = subrequest('/@@response-write')
        
        In which case you may access response.stdout as file.
        
            >>> response.stdout.seek(0, 0)
            >>> list(response.stdout)
            ['Some data.\n', 'Some more data.\n']
        
        You can test whether a file was returned using ``response._wrote``.
        
            >>> response._wrote
            1
        
        When you're done, close the file:
        
            >>> response.stdout.close()
        
        .. test-case: response-outputBody
        
        Use ``response.outputBody()`` to ensure the body may be accessed as a file.
        
            >>> from plone.subrequest import subrequest
            >>> response = subrequest('/folder1/@@url')
            >>> response._wrote
            >>> response.outputBody()
            >>> response._wrote
            1
            >>> response.stdout.seek(0, 0)
            >>> list(response.stdout)
            ['http://nohost/folder1']
        
        Relative paths
        --------------
        
        .. test-case: relative
        
        Relative paths are resolved relative to the parent request's location:
        
            >>> request = traverse('/folder1/@@test')
            >>> response = subrequest('folder1A/@@url')
            >>> response.getBody()
            'http://nohost/folder1/folder1A'
        
        .. test-case: relative-default-view
        
        This takes account of default view's url.
        
            >>> request = traverse('/folder1')
            >>> request['URL']
            'http://nohost/folder1/@@test'
            >>> response = subrequest('folder1A/@@url')
            >>> response.getBody()
            'http://nohost/folder1/folder1A'
        
        Virtual hosting
        ---------------
        
        .. test-case: virtual-hosting
        
        When virtual hosting is used, absolute paths are traversed from the virtual host root.
        
            >>> request = traverse('/VirtualHostBase/http/example.org:80/folder1/VirtualHostRoot/')
            >>> response = subrequest('/folder1A/@@url')
            >>> response.getBody()
            'http://example.org/folder1A'
        
        Specifying the root
        -------------------
        
        .. test-case: specify-root
        
        You may also set the root object explicitly
        
            >>> app = layer['app']
            >>> response = subrequest('/folder1A/@@url', root=app.folder1)
            >>> response.getBody()
            'http://nohost/folder1/folder1A'
        
        Error responses
        ---------------
        
        .. test-case: not-found
        
        Subrequests may not be found.
        
            >>> response = subrequest('/not-found')
            >>> response.status
            404
        
        .. test-case: error-response
        
        Or might raise an error.
        
            >>> response = subrequest('/@@error')
            >>> response.status
            500
        
        .. test-case: status-ok
        
        So check for the expected status.
        
            >>> response = subrequest('/')
            >>> response.status == 200
            True
        
        Handling subrequests
        --------------------
        
        The parent request is set as PARENT_REQUEST onto subrequests.
        
        Subrequests also provide the ``plone.subrequest.interfaces.ISubRequest``
        marker interface.
        
        
        Changelog
        =========
        
        1.6.1 - 2011-07-04
        ------------------
        
        - Move tests to package directory to making testing possible when installed
          normally.
        
        1.6 - 2011-06-06
        ----------------
        
        - Ensure url is a string and not unicode.
          [elro]
        
        1.6b2 - 2011-05-20
        ------------------
        
        - Set PARENT_REQUEST and add ISubRequest interface to subrequests.
          [elro]
        
        1.6b1 - 2011-02-11
        ------------------
        
        - Handle IStreamIterator.
          [elro]
        
        - Simplify API so ``response.getBody()`` always works.
          [elro]
        
        1.5 - 2010-11-26
        ----------------
        
        - Merge cookies from subrequest response into parent response.
          [awello]
        
        1.4 - 2010-11-10
        ----------------
        
        - First processInput, then traverse (fixes #11254)
          [awello]
        
        1.3 - 2010-08-24
        ----------------
        
        - Fixed bug with virtual hosting and quoted paths.
          [elro]
        
        1.2 - 2010-08-16
        ----------------
        
        - Restore zope.component site after subrequest.
          [elro]
        
        1.1 - 2010-08-14
        ----------------
        
        - Virtual hosting, relative url and error response support.
          [elro]
        
        1.0 - 2010-07-28
        ----------------
        
        - Initial release.
          [elro]
        
Keywords: plone
Platform: Any
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Zope2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
