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' True >>> 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.