wuttjamaican.util

WuttJamaican - utilities

wuttjamaican.util.get_class_hierarchy(klass, topfirst=True)

Returns a list of all classes in the inheritance chain for the given class.

For instance:

class A:
   pass

class B(A):
   pass

class C(B):
   pass

get_class_hierarchy(C)
# -> [A, B, C]

Parameters:

• klass – The reference class. The list of classes returned will include this class and all its parents.

• topfirst – Whether the returned list should be sorted in a “top first” way, e.g. A) grandparent, B) parent, C) child. This is the default but pass False to get the reverse.

wuttjamaican.util.load_entry_points(group, ignore_errors=False)

Load a set of setuptools-style entry points.

This is used to locate “plugins” and similar things, e.g. the set of subcommands which belong to a main command.

Parameters:

• group – The group (string name) of entry points to be loaded, e.g. 'wutta.commands'.

• ignore_errors – If false (the default), any errors will be raised normally. If true, errors will be logged but not raised.

Returns:

A dictionary whose keys are the entry point names, and values are the loaded entry points.

wuttjamaican.util.load_object(spec)

Load an arbitrary object from a module, according to the spec.

The spec string should contain a dotted path to an importable module, followed by a colon (':'), followed by the name of the object to be loaded. For example:

wuttjamaican.util:parse_bool

You’ll notice from this example that “object” in this context refers to any valid Python object, i.e. not necessarily a class instance. The name may refer to a class, function, variable etc. Once the module is imported, the getattr() function is used to obtain a reference to the named object; therefore anything supported by that approach should work.

Parameters:

spec – Spec string.

Returns:

The specified object.

wuttjamaican.util.make_title(text)

Return a human-friendly “title” for the given text.

This is mostly useful for converting a Python variable name (or similar) to a human-friendly string, e.g.:

make_title('foo_bar')     # => 'Foo Bar'

wuttjamaican.util.make_true_uuid()

Generate a new v7 UUID value.

Returns:

uuid.UUID instance

Warning

For now, callers should use this function when they want a proper UUID instance, whereas make_uuid() will always return a string.

However once all dependent logic has been refactored to support proper UUID data type, then make_uuid() will return those and this function will eventually be removed.

wuttjamaican.util.make_uuid()

Generate a new v7 UUID value.

Returns:

A 32-character hex string.

Warning

For now, this function always returns a string.

However once all dependent logic has been refactored to support proper UUID data type, then this function will return those and the make_true_uuid() function will eventually be removed.

wuttjamaican.util.parse_bool(value)

Derive a boolean from the given string value.

wuttjamaican.util.parse_list(value)

Parse a configuration value, splitting by whitespace and/or commas and taking quoting into account etc., yielding a list of strings.

wuttjamaican.util.progress_loop(func, items, factory, message=None)

Convenience function to iterate over a set of items, invoking logic for each, and updating a progress indicator along the way.

This function may also be called via the app handler; see progress_loop().

The factory will be called to create the progress indicator, which should be an instance of ProgressBase.

The factory may also be None in which case there is no progress, and this is really just a simple “for loop”.

Parameters:

• func – Callable to be invoked for each item in the sequence. See below for more details.

• items – Sequence of items over which to iterate.

• factory – Callable which creates/returns a progress indicator, or can be None for no progress.

• message – Message to display along with the progress indicator. If no message is specified, whether a default is shown will be up to the progress indicator.

The func param should be a callable which accepts 2 positional args (obj, i) - meaning for which is as follows:

Parameters:

• obj – This will be an item within the sequence.

• i – This will be the one-based sequence number for the item.

See also ConsoleProgress for a usage example.

wuttjamaican.util.resource_path(path)

Returns the absolute file path for the given resource path.

A “resource path” is one which designates a python package name, plus some path under that. For instance:

wuttjamaican.email:templates

Assuming such a path should exist, the question is “where?”

So this function uses importlib.resources to locate the path, possibly extracting the file(s) from a zipped package, and returning the final path on disk.

It only does this if it detects it is needed, based on the given path argument. If that is already an absolute path then it will be returned as-is.

Parameters:

path – Either a package resource specifier as shown above, or regular file path.

Returns:

Absolute file path to the resource.