l.s.utils : module documentation

Part of lp.services

Generic Python utilities.

Functions, lists and so forth. Nothing here that does system calls or network stuff.

Function AutoDecorate Factory to generate metaclasses that automatically apply decorators.
Function base Convert 'number' to an arbitrary base numbering scheme, 'radix'.
Function compress_hash Compress a hash_obj using base.
Function iter_split Iterate over ways to split 'string' in two with 'splitter'.
Function iter_chunks Iterate over iterable in chunks of size size.
Function value_string Return a unicode string representing value.
Function text_delta Return a textual delta for a Delta object.
Class CachingIterator Remember the items extracted from the iterator for the next iteration.
Function decorate_with Create a decorator that runs decorated functions with 'context'.
Function docstring_dedent Remove leading indentation from a doc string.
Function file_exists Does filename exist?
Class CapturedOutput A fixture that captures output to stdout and stderr.
Function run_capturing_output Run function capturing output to stdout and stderr.
Function traceback_info Set __traceback_info__ in the caller's locals.
Function utc_now Return a timezone-aware timestamp for the current time.
Function seconds_since_epoch Express a datetime as the number of seconds since the Unix epoch.
Function obfuscate_email Obfuscate an email address.
Function save_bz2_pickle Save a bz2 compressed pickle of obj to filename.
Function load_bz2_pickle Load and return a bz2 compressed pickle from filename.
Function obfuscate_structure Obfuscate the strings of a json-serializable structure.
Function sanitise_urls Sanitise a string that may contain URLs for logging.
def AutoDecorate(*decorators):
Factory to generate metaclasses that automatically apply decorators.

AutoDecorate is a metaclass factory that can be used to make a class implicitly wrap all of its methods with one or more decorators.

def base(number, radix):
Convert 'number' to an arbitrary base numbering scheme, 'radix'.

This function is based on work from the Python Cookbook and is under the Python licence.

Inverse function to int(str, radix) and long(str, radix)

def compress_hash(hash_obj):
Compress a hash_obj using base.

Given an md5 or sha1 hash object, compress it down to either 22 or 27 characters in a way that's safe to be used in URLs. Takes the hex of the hash and converts it to base 62.

def iter_split(string, splitter, splits=None):
Iterate over ways to split 'string' in two with 'splitter'.

If 'string' is empty, then yield nothing. Otherwise, yield tuples like ('a/b/c', ''), ('a/b', '/c'), ('a', '/b/c') for a string 'a/b/c' and a splitter '/'.

The tuples are yielded such that the first result has everything in the first tuple. With each iteration, the first element gets smaller and the second gets larger. It stops iterating just before it would have to yield ('', 'a/b/c').

Splits, if specified, is an iterable of splitters to split the string at.

def iter_chunks(iterable, size):
Iterate over iterable in chunks of size size.

I'm amazed this isn't in itertools (mwhudson).

def value_string(item):
Return a unicode string representing value.

This text is special cased for enumerated types.

def text_delta(instance_delta, delta_names, state_names, interface):
Return a textual delta for a Delta object.

A list of strings is returned.

Only modified members of the delta will be shown.

Parametersinstance_deltaThe delta to generate a textual representation of.
delta_namesThe names of all members to show changes to.
state_namesThe names of all members to show only the new state of.
interfaceThe Zope interface that the input delta compared.
def decorate_with(context_factory, *args, **kwargs):
Create a decorator that runs decorated functions with 'context'.
def docstring_dedent(s):
Remove leading indentation from a doc string.

Since the first line doesn't have indentation, split it off, dedent, and then reassemble.

def file_exists(filename):
Does filename exist?
def run_capturing_output(function, *args, **kwargs):
Run function capturing output to stdout and stderr.
ParametersfunctionA function to run.
argsArguments passed to the function.
kwargsKeyword arguments passed to the function.
ReturnsA tuple of (ret, stdout, stderr), where ret is the value returned by function, stdout is the captured standard output and stderr is the captured stderr.
def traceback_info(info):
Set __traceback_info__ in the caller's locals.

This is more aesthetically pleasing that assigning to __traceback_info__, but it more importantly avoids spurious lint warnings about unused local variables, and helps to avoid typos.

def utc_now():
Return a timezone-aware timestamp for the current time.
def seconds_since_epoch(dt):
Express a datetime as the number of seconds since the Unix epoch.
def obfuscate_email(text_to_obfuscate, replacement=None):
Obfuscate an email address.

The email address is obfuscated as <email address hidden> by default, or with the given replacement.

The pattern used to identify an email address is not 2822. It strives to match any possible email address embedded in the text. For example, mailto:person@domain.dom and http://person:password@domain.dom both match, though the http match is in fact not an email address.

def save_bz2_pickle(obj, filename):
Save a bz2 compressed pickle of obj to filename.
def load_bz2_pickle(filename):
Load and return a bz2 compressed pickle from filename.
def obfuscate_structure(o):
Obfuscate the strings of a json-serializable structure.

Note: tuples are converted to lists because json encoders do not distinguish between lists and tuples.

ParametersoAny json-serializable object.
Returnsa possibly-new structure in which all strings, list and tuple elements, and dict keys and values have undergone obfuscate_email recursively.
def sanitise_urls(s):
Sanitise a string that may contain URLs for logging.

Some jobs are started with arguments that probably shouldn't be logged in their entirety (usernames and passwords for P3As, for example). This function removes them.

API Documentation for Launchpad, generated by pydoctor at 2022-06-16 00:00:12.