noterator package

Subpackages

• noterator.plugins package
  • Submodules
  • noterator.plugins.email module
  • noterator.plugins.hipchat module
  • noterator.plugins.twilio module
  • Module contents

Submodules

noterator.config module

exception noterator.config.ConfigurationError

Bases: exceptions.Exception

noterator.config.load_config(fname=None)

Load and return configuration from a file.

Args:

fname (str): Path to the ini file we should use. If not provided, we

default to $HOME/.config/noterator/config.ini

Returns:

The parsed configuration

Raises:

ConfigurationError: if the file can’t be found.

noterator.utils module

noterator.utils.catch_all(func)

Simple decorator that wraps a function in a silent try/except.

Useful for wrapping functions that might fail but shouldn’t propagate that failure to the caller. For example, notifications might break, but we don’t want that to interrupt the iteration.

noterator.utils.now()

Module contents

class noterator.Noterator(iterable=None, method=0, desc=None, head=None, body=None, start=False, finish=True, every_n=None, config_file=None)

Bases: object

Base class for setting up & configuring your noteration.

You only really need to interact with this class directly (rather than just using noterator.noterate) is if you want to build a re-usable Noterator or you want to build one without using a configuration file.

For example, you could define a Noterator for use on two iterables, and use a different description for each one:

>>> from noterator import Noterator, EMAIL
>>> noterator = Noterator(method=EMAIL, every_n=100, start=True)
>>> for obj in noterator(my_objects, desc="loop 1")
...     do_something_slow(obj)
...
>>> for obj in noterator(my_other_objects, desc="loop 2")
...     do_something_else_slow(obj)
...
>>> 

And if you want to build a Noterator without using a configuration file (or if you just want to override some configured options):

>>> from noterator import Noterator, EMAIL
>>> noterator = Noterator(my_objects, method=EMAIL, every_n=100)
>>> noterator.configure_plugin('email', recipient='you@example.org')
>>> for obj in noterator
...     do_something_slow(obj)
... 
>>> 

If iterable isn’t set on class initialisation, it must be set before looping, or as a parameter to the noterate method.

When iteration begins, the configuration will be validated.

Args:

Technically none, but iterable, method, and desc are often passed as positional arguments, and such usage is encouraged for brevity.

Kwargs:

iterable (iterable): The iterable we’re going to wrap desc (str): Description to include in the notification. start (bool): Send a notification when iteration starts finish (bool): Send a notification when iteration completes every_n (int): Send a notification every every_n iterations method (int): Method(s) to use (e.g. EMAIL|HIPCHAT) head (string): Header for notification message body (string): Body for notification message. We call .format on this

string with the iteration count at the point of notification.

config_file (string): Path to alternative configuration file.

configure_plugin(name, **kwargs)

Optionally set up plugins without using a configuration file.

You can also use this to override defaults set in a configuration file.

Args:

name (str): the name of the plugin (e.g. ‘email’)

Kwargs: any keyword arguments accepted by the named plugin.

index = 0

methods = ((8, u'desktop', <module 'noterator.plugins.desktop' from '/home/docs/checkouts/readthedocs.org/user_builds/noterator/checkouts/latest/noterator/plugins/desktop.py'>), (1, u'email', <module 'noterator.plugins.email' from '/home/docs/checkouts/readthedocs.org/user_builds/noterator/checkouts/latest/noterator/plugins/email.py'>), (2, u'twilio', <module 'noterator.plugins.twilio' from '/home/docs/checkouts/readthedocs.org/user_builds/noterator/checkouts/latest/noterator/plugins/twilio.py'>), (4, u'hipchat', <module 'noterator.plugins.hipchat' from '/home/docs/checkouts/readthedocs.org/user_builds/noterator/checkouts/latest/noterator/plugins/hipchat.py'>))

next()

noterator.noterate(iterable, *args, **kwargs)

Wrap any iterable with noterate and you’ll be notified when the iteration completes, for example:

>>> from noterator import noterate, EMAIL
>>> for obj in noterate(my_objects, EMAIL, "My super-slow iteration"):
...     do_something_slow(obj)
... 
>>> 

By default you only find out when the iteration completes, but sometimes it’s useful to know when these things start too:

>>> from noterator import noterate, EMAIL, HIPCHAT
>>> for obj in noterate(my_objects, EMAIL|HIPCHAT, start=True):
...     do_something_slow(obj)
... 
>>> 

This function is a convenience wrapper around the Noterator class. The code above is equivalent to:

>>> from noterator import Noterator, EMAIL, HIPCHAT
>>> noterator = Noterator(my_objects, EMAIL|HIPCHAT, start=True)
>>> for obj in noterator:
...     do_something_slow(obj)
... 
>>> 

Positional and Keyword arguments are the same as for Noterator.__init__ except that iterable is required.