Base API Reference

Interfaces

Interfaces for the publisher.

exception zope.publisher.interfaces.Retry(orig_exc=None)

Bases: zope.publisher.interfaces.PublishingException

Raise this to retry a request.

orig_exc must be a 3-tuple as returned from sys.exc_info() or None

interface zope.publisher.interfaces.IExceptionSideEffects

An exception caught by the publisher is adapted to this so that it can have persistent side-effects.

__call__(obj, request, exc_info)

Effect persistent side-effects.

Arguments are:

obj context-wrapped object that was published request the request exc_info the exception info being handled

interface zope.publisher.interfaces.IResponse

Interface used by the publsher

setResult(result)

Sets the response result value.

handleException(exc_info)

Handles an exception.

This method is intended only as a convenience for the publication object. The publication object can choose to handle exceptions by calling this method. The publication object can also choose not to call this method at all.

Implementations set the reponse body.

internalError()

Called when the exception handler bombs.

Should report back to the client that an internal error occurred.

reset()

Reset the output result.

Reset the response by nullifying already set variables.

retry()

Returns a retry response

Returns a response suitable for repeating the publication attempt.

interface zope.publisher.interfaces.IPublication

Object publication framework.

The responsibility of publication objects is to provide application hooks for the publishing process. This allows application-specific tasks, such as connecting to databases, managing transactions, and setting security contexts to be invoked during the publishing process.

beforeTraversal(request)

Pre-traversal hook.

This is called once before any traversal has been done.

getApplication(request)

Returns the object where traversal should commence.

callTraversalHooks(request, ob)

Invokes any traversal hooks associated with the object.

This is called before traversing each object. The ob argument is the object that is about to be traversed.

traverseName(request, ob, name)

Traverses to the next object.

Name must be an ASCII string or Unicode object.

afterTraversal(request, ob)

Post-traversal hook.

This is called after all traversal.

callObject(request, ob)

Call the object, returning the result.

For GET/POST this means calling it, but for other methods (including those of WebDAV and FTP) this might mean invoking a method of an adapter.

afterCall(request, ob)

Post-callObject hook (if it was successful).

handleException(object, request, exc_info, retry_allowed=1)

Handle an exception

Either: - sets the body of the response, request.response, or - raises a Retry exception, or - throws another exception, which is a Bad Thing.

endRequest(request, ob)

Do any end-of-request cleanup

interface zope.publisher.interfaces.IPublicationRequest

Extends: zope.security.interfaces.IParticipation

Interface provided by requests to IPublication objects

response

The request’s response object

Return an IPublisherResponse for the request.

close()

Release resources held by the request.

hold(held)

Hold a reference to an object until the request is closed.

The object should be an IHeld. If it is an IHeld, its release method will be called when it is released.

getTraversalStack()

Return the request traversal stack

This is a sequence of steps to traverse in reverse order. They will be traversed from last to first.

setTraversalStack(stack)

Change the traversal stack.

See getTraversalStack.

getPositionalArguments()

Return the positional arguments given to the request.

setPrincipal(principal)

Set the principal attribute.

It should be IPrincipal wrapped in its AuthenticationService’s context.

interface zope.publisher.interfaces.IHeld

Object to be held and explicitly released by a request

release()

Release the held object

This is called by a request that holds the IHeld when the request is closed

interface zope.publisher.interfaces.IPublisherRequest

Extends: zope.publisher.interfaces.IPublicationRequest

Request interface use by the publisher

The responsibility of requests is to encapsulate protocol specific details, especially wrt request inputs.

Request objects also serve as “context” objects, providing construction of and access to responses and storage of publication objects.

supportsRetry()

Check whether the request supports retry

Return a boolean value indicating whether the request can be retried.

retry()

Return a retry request

Return a request suitable for repeating the publication attempt.

publication

The request’s publication object

The publication object, an IRequestPublication provides application-specific functionality hooks.

setPublication(publication)

Set the request’s publication object

traverse(obj)

Traverse from the given object to the published object

The published object is returned.

The following hook methods on the publication will be called:

• callTraversalHooks is called before each step and after the last step.
• traverseName to actually do a single traversal

processInputs()

Do any input processing that needs to be done before traversing

This is done after construction to allow the publisher to handle errors that arise.

interface zope.publisher.interfaces.IDebugFlags

Features that support debugging.

sourceAnnotations

Enable ZPT source annotations

showTAL

Leave TAL markup in rendered page templates

interface zope.publisher.interfaces.IApplicationRequest

Extends: zope.interface.common.mapping.IEnumerableMapping

Features that support application logic

principal

Principal object associated with the request This is a read-only attribute.

bodyStream

The stream that provides the data of the request.

The data returned by the stream will not include any possible header information, which should have been stripped by the server (or previous layer) before.

Also, the body stream might already be read and not return any data. This is commonly done when retrieving the data for the body attribute.

If you access this stream directly to retrieve data, it will not be possible by other parts of the framework to access the data of the request via the body attribute.

debug

Debug flags (see IDebugFlags).

__getitem__(key)

Return request data

The only request data are environment variables.

environment

Request environment data

This is a read-only mapping from variable name to value.

annotations

Stores arbitrary application data under package-unique keys.

By “package-unique keys”, we mean keys that are are unique by virtue of including the dotted name of a package as a prefex. A package name is used to limit the authority for picking names for a package to the people using that package.

For example, when implementing annotations for hypothetical request-persistent adapters in a hypothetical zope.persistentadapter package, the key would be (or at least begin with) the following:

"zope.persistentadapter"

interface zope.publisher.interfaces.IRequest

Extends: zope.publisher.interfaces.IPublisherRequest, zope.publisher.interfaces.IPublicationRequest, zope.publisher.interfaces.IApplicationRequest

The basic request contract

interface zope.publisher.interfaces.IRequestEvent

An event which is about or for a request.

request

The request this event is about.

interface zope.publisher.interfaces.IEndRequestEvent

Extends: zope.publisher.interfaces.IRequestEvent

An event which gets sent when the publication is ended.

interface zope.publisher.interfaces.IStartRequestEvent

Extends: zope.publisher.interfaces.IRequestEvent

An event which gets sent before publication of a request.

class zope.publisher.interfaces.RequestEvent(request)

Bases: object

Events for requests.

Parameters:request – The request the event is for.

class zope.publisher.interfaces.EndRequestEvent(ob, request)

Bases: zope.publisher.interfaces.RequestEvent

An event which gets sent when the publication is ended

class zope.publisher.interfaces.StartRequestEvent(request)

Bases: zope.publisher.interfaces.RequestEvent

An event send when before publication of a request.

interface zope.publisher.interfaces.ISkinType

Extends: zope.interface.interfaces.IInterface

Base interface for skin types.

interface zope.publisher.interfaces.ISkinnable

A skinnable (request) can provide a skin.

The implementation in BrowserRequest will apply a default skin/layer called IDefaultBrowserLayer if not default skin get registered.

interface zope.publisher.interfaces.IDefaultSkin

Any component providing this interface must be a skin.

This is a marker interface, so that we can register the default skin as an adapter from the presentation type to IDefaultSkin.

interface zope.publisher.interfaces.ISkinChangedEvent

Extends: zope.publisher.interfaces.IRequestEvent

Event that gets triggered when the skin of a request is changed.

interface zope.publisher.interfaces.IDefaultViewName

A string that contains the default view name

A default view name is used to select a view when a user hasn’t specified one.

interface zope.publisher.interfaces.IReRaiseException

An exception that should be reraised, when handled in publisher.

Under some circumstances (for instance if acting in a WSGI pipeline with debugger middleware) certain exceptions occuring while publishing should be handled by the Zope machinery and never reach the ‘outside world’.

Adapters providing this interface for a certain exception type which also return False when being called, indicate by this that the exception should not be reraised during publishing.

This makes it possible, for instance, to authenticate with basic-auth when a debugger middleware is used and IUnauthorized is raised.

__call__()

Return True if an exception should be re-raised

Implementation

Base implementations of the Publisher objects

Specifically, ‘BaseRequest’, ‘BaseResponse’, and ‘DefaultPublication’ are specified here.

class zope.publisher.base.BaseResponse

Bases: object

Base Response Class

setResult(result)

See IPublisherResponse

handleException(exc_info)

See IPublisherResponse

internalError()

See IPublisherResponse

reset()

See IPublisherResponse

retry()

See IPublisherResponse

class zope.publisher.base.DebugFlags

Bases: object

Debugging flags.

class zope.publisher.base.BaseRequest(body_instream, environ, response=None, positional=None)

Bases: object

Represents a publishing request.

This object provides access to request data. Request data may vary depending on the protocol used.

Request objects are created by the object publisher and will be passed to published objects through the argument name, REQUEST.

The request object is a mapping object that represents a collection of variable to value mappings.

publication

See IPublisherRequest

processInputs()

See IPublisherRequest

retry()

See IPublisherRequest

setPublication(pub)

See IPublisherRequest

supportsRetry()

See IPublisherRequest

traverse(obj)

See IPublisherRequest

close()

See IPublicationRequest

getPositionalArguments()

See IPublicationRequest

getTraversalStack()

See IPublicationRequest

hold(object)

See IPublicationRequest

setTraversalStack(stack)

See IPublicationRequest

bodyStream

See zope.publisher.interfaces.IApplicationRequest

items()

See Interface.Common.Mapping.IEnumerableMapping

keys()

See Interface.Common.Mapping.IEnumerableMapping

values()

See Interface.Common.Mapping.IEnumerableMapping

get(key, default=None)

See Interface.Common.Mapping.IReadMapping

has_key(key)

See Interface.Common.Mapping.IReadMapping

class zope.publisher.base.DefaultPublication(app)

Bases: object

A stub publication.

This works just like Zope2’s ZPublisher. It rejects any name starting with an underscore and any objects (specifically: method) that doesn’t have a docstring.