API Reference

class pushcollector.Collector

A collector for log files and push item data.

This class defines the interface for all pushcollector backends. Instances of this class shouldn’t be constructed directly; rather, the get() method should be used to obtain a collector of the desired backend.

Custom backends may choose to implement the context manager protocol (i.e. __enter__, and __exit__). If a backend does support the context manager protocol, the __enter__ and __exit__ methods may be called more than once. Whether a backend is single-use, reentrant, or reusable is an implementation detail left to the programmer, and no attempt is made to handle any exceptions that may result from calling a backend’s __enter__ method more than once.

New in version 1.3.0: Backends can choose to support the context manager protocol.

See also

Python docs on the different types of context managers.

update_push_items(items)

Record a state change on one or more push items.

Parameters:

items (List[dict], List[PushItem]) –

A list of push item dicts or list of PushItem objects.

Each dict must have, at minimum, “filename” and “state” keys. For complete information on the format of push item dicts, see the Push Item Schema documentation.

An exception will be raised if any push item does not match the documented schema.

Returns:

Future

A Future resolved with None when the push item update succeeds, or resolved with an error if the update failed.

attach_file(filename, content)

Collect some content into a file of the specified name.

Parameters:

• filename (str) – The name of a file to be created (or overwritten).

• content (bytes, str) –

  Content to be written into the file.

  Both binary and text files are supported.

  If a str is provided, it will always be encoded as UTF-8.

Returns:

Future

A Future resolved with None when the file has been written, or resolved with an error if the operation failed.

append_file(filename, content)

Like attach_file(), except that if the named file already exists, content is appended to it rather than overwriting the file.

classmethod get(backend=None)

Obtain a collector using the specified backend.

New in version 1.3.0: The object returned by a call to get can always be used as a context manager, regardless of which backend is requested.

Parameters:

backend (str) –

If provided, must be the name of an existing pushcollector backend. An instance of this backend will be used.

If omitted/None, the library’s default backend will be used. The default backend is initially set to “local”.

Returns:

Collector

An object implementing the Collector interface, which may be used to record log files and push item data.

Raises:

ValueError – If the requested backend is not valid.

classmethod register_backend(name, factory)

Register a new pushcollector backend, or update/remove an existing backend.

Parameters:

• name (str) – The name of a backend. This should be a brief unique identifying string for programmatic use.

• factory (callable) –

  A callable used to create new instances of the backend. When invoked, this callable must return an object which implements the Collector interface.

  Alternatively, if None is provided, the backend of the given name is unregistered and may no longer be used.

Raises:

TypeError – If factory is not callable and not None.

classmethod set_default_backend(name)

Set the default pushcollector backend.

Parameters:

name (str) – The name of a backend registered with the library, or None to reset the default backend to the library’s initial default.

Raises:

ValueError – If there is no registered backend of the requested name.