Source

The Source class is the base from which all pushsource backends derive.

class pushsource.Source

A source of push items.

This base class defines the interface for all pushsource backends. Instances of a specific backend can be obtained using the get() method.

Though not mandatory, instances of Source are preferably used via with statements to ensure that all resources are cleaned up when no longer needed, as in example:

with Source.get('some-url') as source:
    for item in source:
        do_something(item)

Note that the items produced by a source are not bound to the lifecycle of a source instance, so it’s safe to store them and continue using them beyond the end of the with statement.

__iter__()

Iterate over the push items contained within this source.

Yields a series of PushItem instances.

classmethod get(source_url, **kwargs)

Obtain a push source from the given URL.

Parameters:

• source_url (str) – Specifies a push source backend and associated arguments. For information about push source URLs, see Obtaining a source by URL.

• kwargs (dict) – Any additional keyword arguments to be passed into the backend.

Raises:

SourceUrlError – If source_url is not a valid push source URL.

Returns:

Source

A new Source instance initialized with the given arguments.

classmethod get_partial(source_url, **kwargs)

Obtain a push source constructor from the given URL and arguments.

This method returns a constructor for a push source (rather than a push source instance directly) so that additional arguments may be provided later.

One of the primary uses of this method is to provide your own preconfigured aliases for existing backends, as described in Binding partially-configured backends.

Parameters:

• source_url (str) – Specifies a push source backend and associated arguments. For information about push source URLs, see Obtaining a source by URL.

• kwargs (dict) – Any additional keyword arguments to be passed into the backend.

Raises:

SourceUrlError – If source_url is not a valid push source URL.

Returns:

callable

A callable which accepts any number of keyword arguments and returns a Source.

classmethod register_backend(name, factory)

Register a new pushsource backend.

This method allows registering additional backends beyond those shipped with the pushsource library. See Implementing a backend for more information.

Parameters:

• name (str) –

  The name of a backend. This should be a brief unique identifying string.

  If a backend of the given name is already registered, it will be overwritten.

• factory (callable) – A callable used to create new instances of the backend. When invoked, this callable must return an object which implements the Source interface.

Raises:

TypeError – If factory is not callable.

classmethod reset()

Reset the library to the default configuration.

This method will undo the effect of any prior calls to register_backend(), restoring only the default backends provided by the pushsource library.

This may be used from within tests to ensure a known state.

New in version 2.6.0.

class pushsource.SourceUrlError

Errors of this type are raised when an invalid URL is provided to get() and related methods.