11.5.3 BaseHandler Objects

##
11.5.3 BaseHandler Objects

`BaseHandler` objects provide a couple of methods that are directly useful, and others that are meant to be used by derived classes. These are intended for direct use:

`add_parent`( | director)

  Add a director as parent.

`close`( | )

  Remove any parents.

The following members and methods should only be used by classes derived from `BaseHandler`. Note: The convention has been adopted that subclasses defining `protocol_request()` or `protocol_response()` methods are named `*Processor`; all others are named `*Handler`.

`parent`
  A valid `OpenerDirector`, which can be used to open using a different protocol, or handle errors.

`default_open`( | req)

  This method is not defined in `BaseHandler`, but subclasses should define it if they want to catch all URLs.

  This method, if implemented, will be called by the parent `OpenerDirector`. It should return a file-like object as described in the return value of the `open()` of `OpenerDirector`, or `None`. It should raise `URLError`, unless a truly exceptional thing happens (for example, `MemoryError` should not be mapped to `URLError`).

  This method will be called before any protocol-specific open method.

protocol_open( | req)

  This method is not defined in `BaseHandler`, but subclasses should define it if they want to handle URLs with the given protocol.

  This method, if defined, will be called by the parent `OpenerDirector`. Return values should be the same as for `default_open()`.

`unknown_open`( | req)

  This method is not defined in `BaseHandler`, but subclasses should define it if they want to catch all URLs with no specific registered handler to open it.

  This method, if implemented, will be called by the `parent` `OpenerDirector`. Return values should be the same as for `default_open()`.

`http_error_default`( | req, fp, code, msg, hdrs)

  This method is not defined in `BaseHandler`, but subclasses should override it if they intend to provide a catch-all for otherwise unhandled HTTP errors. It will be called automatically by the `OpenerDirector` getting the error, and should not normally be called in other circumstances.

  req will be a `Request` object, fp will be a file-like object with the HTTP error body, code will be the three-digit code of the error, msg will be the user-visible explanation of the code and hdrs will be a mapping object with the headers of the error.

  Return values and exceptions raised should be the same as those of `urlopen()`.

`http_error_nnn`( | req, fp, code, msg, hdrs)

  nnn should be a three-digit HTTP error code. This method is also not defined in `BaseHandler`, but will be called, if it exists, on an instance of a subclass, when an HTTP error with code nnn occurs.

  Subclasses should override this method to handle specific HTTP errors.

  Arguments, return values and exceptions raised should be the same as for `http_error_default()`.

protocol_request( | req)

  This method is not defined in `BaseHandler`, but subclasses should define it if they want to pre-process requests of the given protocol.

  This method, if defined, will be called by the parent `OpenerDirector`. req will be a `Request` object. The return value should be a `Request` object.

protocol_response( | req, response)

  This method is not defined in `BaseHandler`, but subclasses should define it if they want to post-process responses of the given protocol.

  This method, if defined, will be called by the parent `OpenerDirector`. req will be a `Request` object. response will be an object implementing the same interface as the return value of `urlopen()`. The return value should implement the same interface as the return value of `urlopen()`.