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.get_timezone_by_name(tzname)

Retrieve a timezone object by name.

This is mostly a compatibility wrapper, since older Python is missing the zoneinfo module.

For Python 3.9 and newer, this instantiates zoneinfo.ZoneInfo.

For Python 3.8, this calls dateutil.tz.gettz().

See also get_timezone() on the app handler.

Parameters:

tzname – String name for timezone.

Returns:

datetime.tzinfo instance

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.localtime(dt=None, from_utc=True, want_tzinfo=True, local_zone=None)

This produces a datetime in the “local” timezone. By default it will be zone-aware.

See also the shortcut localtime() method on the app handler. For usage examples see Convert to Local Time.

See also make_utc() which is sort of the inverse.

Parameters:

• dt – Optional datetime.datetime instance. If not specified, the current time will be used.

• from_utc – Boolean indicating whether a naive dt is already (effectively) in UTC timezone. Set this to false when providing a naive dt which is already in “local” timezone instead of UTC. This flag is ignored if dt is zone-aware.

• want_tzinfo – Boolean indicating whether the resulting datetime should have its tzinfo attribute set. Set this to false if you want a naive value; it’s true by default, for zone-aware.

• local_zone – Optional datetime.tzinfo instance to use as “local” timezone, instead of relying on Python to determine the system local timezone.

Returns:

datetime.datetime instance in local timezone.

wuttjamaican.util.make_full_name(*parts)

Make a “full name” from the given parts.

Parameters:

*parts – Distinct name values which should be joined together to make the full name.

Returns:

The full name.

For instance:

make_full_name('First', '', 'Last', 'Suffix')
# => "First Last Suffix"

wuttjamaican.util.make_str_uuid()

Generate a new v7 UUID value as string.

See also make_uuid().

Returns:

UUID as 32-character hex string

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.

See also make_uuid().

Returns:

uuid.UUID instance

wuttjamaican.util.make_utc(dt=None, tzinfo=False)

This returns a datetime local to the UTC timezone. By default it will be a naive datetime; the common use case is to convert as needed for sake of writing to the database.

See also the shortcut make_utc() method on the app handler. For usage examples see Convert to UTC.

See also localtime() which is sort of the inverse.

Parameters:

• dt – Optional datetime.datetime instance. If not specified, the current time will be used.

• tzinfo – Boolean indicating whether the return value should have its tzinfo attribute set. This is false by default in which case the return value will be naive.

Returns:

datetime.datetime instance local to UTC.

wuttjamaican.util.make_uuid()

Generate a new v7 UUID value.

See also the app handler shortcut, make_uuid().

Returns:

UUID as 32-character hex string

Warning

TEMPORARY BEHAVIOR

For the moment, use of this function is discouraged. Instead you should use make_true_uuid() or make_str_uuid() to be explicit about the return type you expect.

Eventually (once it’s clear most/all callers are using the explicit functions) this will be refactored to return a UUID instance. But for now this function returns a string.

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.

wuttjamaican.util.simple_error(error)

Return a “simple” string for the given error. Result will look like:

"ErrorClass: Description for the error"

However the logic checks to ensure the error has a descriptive message first; if it doesn’t the result will just be:

"ErrorClass"