MHelper
=======

A collection of utility packages.

.. contents::

.. **** autogenerated content follows ****


ansi
----
This package contains constants for ANSI-terminal escape sequences for colour
and font formatting.
There are also functions for generating 24-bit colour codes.

Please note that this package only defines the codes, it does not guarantee
support for their correct interpretation in the terminal.


ansi_format_helper
------------------
Contains functions for printing error tracebacks to an ANSI terminal using
colour highlighting, as well as a function to replace the default Python handler
with a colour version.


ansi_helper
-----------
Using a string containing ANSI colour codes is problematic in that __len__, etc.
return the length of the full text, including the codes.

This class provides functions for dealing with such strings, as well as a class
`AnsiStr`, that behaves like `str`, but accounts for colour codes.


array_helper
------------
This package includes a variety of utility functions for dealing with arrays
(lists, tuples, iterables, etc.)


batch_lists
-----------
Contains a class and function for dealing with workloads split into batches.


colours
-------
Contains constants and a class for dealing with 24 bit colours.


component_helper
----------------
Allows one to find connected components given a graph-like data-set without
having to actually construct a graph.


data_store
----------
Contains a class for generating proxies for settings objects, committing changes
to disk when their attributes are modified.


debug_helper
------------
Contains a terminal based object inspector `view`, which is similar to Python's
inbuilt `help`, but prettier.

When passed a raw function, this display hook includes the documentation,
arguments, and PEP-484 annotations.

When passed a type, the documentation and available methods are included.

When passed a list, tuple, or dict, the contents are of the iterable are
included, one per line.

When passed any object, the fields of the object are listed, if available,
alongside the object repr.


dispatch_helper
---------------
Contains a multithreaded dispatch queue class, for dispatching function calls
into worker threads.

This can be easily converted into a multiprocessed queue, by having the threads
make a system call.


disposal_helper
---------------
Contains the `ManagedWith` class, which allows a function to generate an object
compatible with `with ...`.

This may be more convenient than generating a separate class implementing
`__enter__` and `__exit__` for simple functions.


documentation_helper
--------------------
Manages and creates a documentation `dict` from docstrings.

This handles extracting `:param:` tags, etc.


emoji_helper
------------
Helper class that contains definitions for all emoji.

Names should be identical to those defined in Unicode, with the exceptions:
    * All names are in upper case
    * Names beginning 1st, 2nd, 3rd are replaced with FIRST, SECOND, THIRD
    * Special symbols &, # and * are replaced with AND, HASH and ASTERISK


event_helper
------------
Contains the multiple dispatch `Event` class, which is designed to behave
the same as the one in C#.


exception_helper
----------------
Contains various assertion functions, generic exception classes and functions
to generate error messages which actually try to be helpful.

Notable examples include `SwitchError`, `NotSupportedError` and `safe_cast`.

This package also includes functions for more easily parsing exception
tracebacks.


file_helper
-----------
Various functions for parsing and generating filenames and enumerating
directories.


io_helper
---------
Convenience functions for reading and writing files of different types: text,
pickle, json, etc.


ipc_helper
----------
Provides an interprocess mutex.

Uses the `posix_ipc.Semaphore`.


lambda_helper
-------------
Provides classes with lambda based dunders.


log_helper
----------
Logging helpers.

Includes:

* A logging handler that formats for the terminal, including thread and process information.
* A logger which highlights variadic values, contains helpers for dealing with progress bars, iteration, enumeration and timing.
* A function to iterate information on existing loggers.


maths_helper
------------
Contains a few simple math functions.


password_helper
---------------
Fixes issues with the `keyring` library on Ubuntu - see the `get_keyring`
function.

Contains a `ManagedPassword` class, which wraps the `keyring` module.


progress_helper
---------------
Contains functions for generating the information required for progress-bar
type reports, notably the estimated time to completion.


property_helper
---------------
Various property related helpers:

* Indexable properties
* Frozen classes
* Class properties


proxy_helper
------------
Contains the class `SimpleProxy` and its dependencies.


qt_resource_objects
-------------------
Wraps Qt resource paths into an object which extracts that resource, caching
it if necessary.


reflection_helper
-----------------
Various helpers for reflection.


serialisable
------------
Dynamically generates both `__getstate__` and `__setstate__` based on a single
definition of the serialisable (or non-serialisable) attributes.


special_types
-------------
Defines a Sentinel class, as well as a typical `NOT_PROVIDED` sentinel value.


string_helper
-------------
Functions for parsing strings into objects and generating strings from objects.

Also contains `TStr` functions that replicate several of Python's `str` methods.
Unlike `str`, `TStr` permits an duck-typed object behaving *like* a `str`,
rather than enforcing a `str` specificly.


subprocess_helper
-----------------
Wraps a subprocess, creating threads to monitor its output, allowing a
process's output to be recorded and displayed in real-time.


svg_helper
----------
Functions for writing SVG images to disk.


utf_helper
----------
Functions for generating UTF-formatted text (e.g. bold, italic, small-caps,
etc.)


utf_table
---------
This is a package for drawing ASCII boxes and tables.

A variety of box drawing character sets are specified, and table drawing
supports wrapping and text spanning multiple columns.

Unlike most other available tools, the direction of lines is honoured and
UTF characters can be used.

To draw a table, please see the `TextTable` class documentation.
