ll.misc – Utility functions and classes

ll.misc contains various utility functions and classes used by the other LivingLogic modules and packages.

ll.misc.item(iterable, index, /, default=None)

Returns the index’th item from the iterable. index may be negative to count from the end. E.g. 0 returns the first item produced by the iterator, 1 the second, -1 the last one etc. If index is negative the iterator will be completely exhausted, if it’s positive it will be exhausted up to the index’th item. If the iterator doesn’t produce that many items default will be returned.

index may also be an iterable of indexes, in which case item() will be applied recursively, i.e. item(["foo", "bar"], (1, -1)) returns 'r'.

ll.misc.first(iterable, /, default=None)

Return the first item from the iterable. If the iterator doesn’t produce any items default will be returned.

ll.misc.last(iterable, /, default=None)

Return the last item from the iterable. If the iterator doesn’t produce any items default will be returned.

ll.misc.count(iterable, /)

Count the number of items produced by the iterable. Calling this function will exhaust the iterator.

ll.misc.isfirst(iterable, /)

Iterate through items of the iterable and give information about whether the item is the first in the iterable:

>>> list(misc.isfirst("foo"))
[(True, 'f'), (False, 'o'), (False, 'o')]

ll.misc.islast(iterable, /)

Iterate through items of the iterable and give information about whether the item is the last in the iterable:

>>> list(misc.islast("foo"))
[(False, 'f'), (False, 'o'), (True, 'o')]

ll.misc.isfirstlast(iterable, /)

Iterate through items of the iterable and give information about whether the item is the first and/or last in the iterable:

>>> list(misc.isfirstlast("foo"))
[(True, False, 'f'), (False, False, 'o'), (False, True, 'o')]

ll.misc.notimplemented(function)

A decorator that raises NotImplementedError when the method is called.

This saves you the trouble of formatting the error message yourself for each implementation.

ll.misc.withdoc(doc)

A decorator that adds a docstring to the function it decorates.

This can be useful if the docstring is not static, and adding it afterwards is not possible.

class ll.misc.Enum

Bases: enum.Enum

Subclass of enum.Enum where class and instance repr() output include the module and fully qualified class name.

class ll.misc.IntEnum

Bases: enum.IntEnum

Subclass of enum.IntEnum where class and instance repr() output includes the module and fully qualified class name.

class ll.misc.propclass

Bases: property

propclass provides an alternate way to define properties.

Subclassing propclass and defining methods __get__(), __set__() and __delete__() will automatically generate the appropriate property:

class name(misc.propclass):
   """
   The name property
   """
   def __get__(self):
      return self._name
   def __set__(self, name):
      self._name = name.lower()
   def __delete__(self):
      self._name = None

ll.misc.format_class(obj)

Format the name of the class of obj.

Example:

>>> misc.format_class(42)
'int'
>>> misc.format_class(open('README.rst', 'rb'))
'_io.BufferedReader'

ll.misc.format_exception(exc)

Format an exception object.

Example:

>>> misc.format_exception(ValueError("bad value"))
'ValueError: bad value'

ll.misc.exception_chain(exc)

Traverses the chain of exceptions. This is a generator.

class ll.misc.Pool

Bases: object

A Pool object can be used as an inheritable alternative to modules. The attributes of a module can be put into a pool and each pool can have base pools where lookup continues if an attribute can’t be found.

register(object)

Register object in the pool. object can be a module, a dictionary or a Pool objects (with registers the pool as a base pool). If object is a module and has an attribute __bases__ (being a sequence of other modules) this attribute will be used to initialize selfs base pool.

clear()

Make self empty.

clone()

Return a copy of self.

ll.misc.iterone(item)

Return an iterator that will produce one item: item.

class ll.misc.Iterator

Bases: object

Iterator adds __getitem__() support to an iterator. This is done by calling item() internally.

get(index, default=None)

Return the index’th item from the iterator (or default if there’s no such item).

class ll.misc.Queue

Bases: object

Queue provides FIFO queues: The method write() writes to the queue and the method read() read from the other end of the queue and remove the characters read.

write(chars)

Write the string chars to the buffer.

read(size=- 1)

Read up to size character from the buffer (or all if size is negative). Those characters will be removed from the buffer.

class ll.misc.Const

Bases: object

This class can be used for singleton constants.

class ll.misc.FlagAction

Bases: argparse.Action

FlagAction can be use with argparse for options that represent flags. An options can have a value like yes or no for the correspending boolean value, or if the value is omitted it is the inverted default value (i.e. specifying the option toggles it).

ll.misc.tokenizepi(string)

Tokenize the string object string according to the processing instructions in the string. tokenize() will generate tuples with the first item being the processing instruction target and the second being the PI data. “Text” content (i.e. anything other than PIs) will be returned as (None, data).

ll.misc.itersplitat(string, positions)

Split string at the positions specified in positions.

For example:

>>> from ll import misc
>>> import datetime
>>> datetime.datetime(*map(int, misc.itersplitat("20090609172345", (4, 6, 8, 10, 12))))
datetime.datetime(2009, 6, 9, 17, 23, 45)

This is a generator.

ll.misc.module(source, filename='unnamed.py', name=None)

Create a module from the Python source code source. filename will be used as the filename for the module and name as the module name (defaulting to the filename part of filename).

ll.misc.javaexpr(obj)

Return a Java expression for the object obj.

Example:

>>> print(misc.javaexpr([1, 2, 3]))
java.util.Arrays.asList(1, 2, 3)

class ll.misc.SysInfo

Bases: object

A SysInfo object contains information about the host, user, python version and script. Available attributes are host_name, host_fqdn, host_ip, host_sysname, host_nodename, host_release, host_version, host_machine, user_name, user_uid, user_gid, user_gecos, user_dir, user_shell, python_executable, python_version, pid, script_name, short_script_name and script_url.

SysInfo object also support a mimimal dictionary interface (i.e. __getitem__() and __iter__()).

One module global instance named sysinfo is created at module import time.

class ll.misc.monthdelta

Bases: object

monthdelta objects can be used to add months/years to a datetime.datetime or datetime.date object. If the resulting day falls out of the range of valid days for the target month, the last day for the target month will be used instead:

>>> import datetime
>>> from ll import misc
>>> datetime.date(2000, 1, 31) + misc.monthdelta(1)
datetime.date(2000, 2, 29)

exception ll.misc.Timeout

Bases: Exception

Exception that is raised when a timeout in timeout() occurs.

ll.misc.timeout(seconds)

A context manager that limits the runtime of the wrapped code.

As this uses signal, this won’t with threads and only on UNIX.

ll.misc.notifystart()

Notify OS X of the start of a process by removing the previous notification.

ll.misc.notifyfinish(title, subtitle, message)

Notify OS X of the end of a process.

ll.misc.prettycsv(rows, padding='   ')

Format table rows.

rows must be a list of lists of strings (e.g. as produced by the csv module). padding is the padding between columns.

prettycsv() is a generator.

ll.misc.jsmin(input)

Minimizes the Javascript source input.