Functions

callsign functions

A callsign is an object identification used in logging. Normally, an object’s class name is enough. This is the default case for the callsign methods.

However, sometimes there are multiple objects of the same class which need to be distinguised between each other. For example when there are multiple http servers on different ports.

To handle this case, the class should have a callsign() method which returns the identifying string, such as the port.

dls_utilpack.callsign.callsign(something, message=None)

Return the callsign of the object. If a message is given, then return a full message with the callsign prepended.

Parameters:

• something (object) – object for which the callsign is desired

• message (str | None) – message body if a full message is desired

Returns:

callsign or callsign with message appended

Return type:

str

If the something object has a callsign method, then this is used. Otherwise, use the object’s module and type name.

dls_utilpack.callsign.callsign_html(the_object, message=None)

Return the callsign of the object wrapped in an html div with css class T_callsign.

See the callsign method for argument details.

Any html thus composed will have the callsign identifiers embedded in it.

The idea is that the css class normally be display: none; unless debugging.

Parameters:

• the_object (object) – the object whose callsign is wanted.

• message (str | None) – Extra bit of message text if desired. Defaults to None.

Return type:

str

datatype functions

Validate strings according to expected data types. The allowed data types are denoted as string constants so these can be specified in string-based configuration such as yaml.

At time of writing, only integer datatypes are handled. It is intended to add more such as float, filename, dict, etc.

class dls_utilpack.datatypes.Datatypes

Class with symbolic constants denoting the allowed data types.

INTEGER = 'integer'

dls_utilpack.datatypes.verify(name, value, datatype)

Return the given value converted according to datatype.

Parameters:

• name (str) – name for use in the possible exception

• value (Any) – value expected to be convertable into datatype

• datatype (str) – symbolic constant of the datatype

Raises:

• ValueError – if the value cannot be converted

• RuntimeError – if the datatype is invalid

Returns:

value from the conversion

Return type:

Any

formatting functions

dls_utilpack.describe.describe(name, value, level=0)

Compose a description of a variable’s type and its value.

Parameters:

• name – Name of the variable.

• value (Any) – Value of the variable.

• level (int) – Indents output according to depth of recursion.

Return type:

str

version functions

The version of the package can be returned as a single string or a dict.

When a string, it comes from the package __version__. When a dict, it also has __version__, as well as versions of other depdency packages.

dls_utilpack.version.version()

Version of the dls_utilpack package as a string.

Return type:

str

dls_utilpack.version.meta(given_meta=None)

Returns version information from the dls_utilpack package and its dependencies as a dict. Adds version information to a given meta dict if it was provided.

Parameters:

given_meta (dict | None) –

Return type:

dict