Public API

UI

app

Within UI process, call both:

  • LoggingState

  • ui_yaml_curated or setup_ui_other

worker process

worker

Step 1

Within worker entrypoint call either:

  • worker_yaml_curated or setup_worker_other

Then pass str_yaml to the worker process

Step 2

Within worker process call

  • setup_logging_yaml

Constants

tl;dr; ^^ won’t need this ^^

Process categories Enum. Iterate over the Enum values, using class method, categories.

strict_logging public methods are convenience functions for class, strict_logging.logging_api.LoggingConfigYaml. If LoggingConfigYaml used directly, choose one of the LoggingConfigCategory values to pass as param, category.

Values: LoggingConfigCategory.UI or LoggingConfigCategory.WORKER

Corresponds to ‘app’ and ‘worker’

Types

tl;dr; ^^ won’t need this ^^

Useful only during strict type checking. class LoggingConfigYaml implements LoggingYamlType interface and is a direct subclass

e.g. type[LoggingYamlType]

Exceptions

[exc docs]

  • LoggingStrictError

logging_strict catch all Exception. Base type of other exceptions. Implements ValueError

Provided just for completeness. Not intended for use

  • LoggingStrictPackageNameRequired

ep requires package name

Corresponding exit code – 6

  • LoggingStrictPackageStartFolderNameRequired

ep requires package start folder name

In logging-strict this is configs. Normally its data. But it can be anything

Corresponding exit code – 7

  • LoggingStrictProcessCategoryRequired

Applicable only during extract or setup, not during validation

Category required. Either:

LoggingConfigCategory.UI.value or LoggingConfigCategory.WORKER.value

Which corresponds to “app” or “worker”

  • LoggingStrictGenreRequired

Applicable only during extract or setup, not during validation

UI framework terse name or worker implementation characteristic

e.g. textual, rich, mp or mq

class logging_strict.LoggingConfigCategory(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

logging.config yaml process categories

Public API

from logging_strict import LoggingConfigCategory
UI = 'app'
WORKER = 'worker'
__module__ = 'logging_strict.constants'
classmethod categories()

Get Enum items’ value

Returns:

In this case, Enum values holds str

Return type:

collections.abc.Iterator[str]

class logging_strict.LoggingState

Singleton to hold the current logging state. To know whether or not, run by app or from cli

logging is redirected to

Knowing the logging mode (or state), first step towards restoring logging mode

Class variables

Variables:

  • _instance – Default None. Holds Singleton instance

  • _lock – Thread lock for Singleton

See also

See textual.logging

Thread safe Singleton [blog post]

__annotations__ = {'_instance': "'LoggingState' | None"}
__dict__ = mappingproxy({'__module__': 'logging_strict.logging_api', '__firstlineno__': 996, '__annotations__': {'_instance': "'LoggingState' | None"}, '__doc__': 'Singleton to hold the current logging state.\nTo know whether or not, run by app or from cli\n\nlogging is redirected to\n\n- If run from app --> :py:exc:`textual.logging.TextualHandler`\n\n- If run from cli --> :py:class:`logging.StreamHandler`\n\nKnowing the logging mode (or state), first step towards restoring logging mode\n\nClass variables\n\n:cvar _instance: Default ``None``. Holds Singleton instance\n:type _instance: ``"LoggingState"`` | None\n:cvar _lock: Thread lock for Singleton\n:type _lock: threading.RLock\n\n.. seealso::\n\n   See :py:mod:`textual.logging`\n\n   Thread safe Singleton\n   `[blog post] <https://medium.com/analytics-vidhya/how-to-create-a-thread-safe-singleton-class-in-python-822e1170a7f6>`_\n\n', '_instance': None, '_lock': <unlocked _thread.RLock object owner=0 count=0>, '__new__': <staticmethod(<function LoggingState.__new__>)>, 'reset': <classmethod(<function LoggingState.reset>)>, 'is_state_app': <property object>, '__static_attributes__': ('_state',), '__dict__': <attribute '__dict__' of 'LoggingState' objects>, '__weakref__': <attribute '__weakref__' of 'LoggingState' objects>})
__firstlineno__ = 996
__module__ = 'logging_strict.logging_api'
static __new__(cls)
Returns:

Singleton instance

Return type:

"LoggingState"

__static_attributes__ = ('_state',)
__weakref__

list of weak references to the object

property is_state_app

Get logging state

Returns:

True if app logging state otherwise False

Return type:

bool | None

classmethod reset()

A cheat to reset the Singleton state. Use only during testing

exception logging_strict.LoggingStrictError(msg)

Catchall back exception

Variables:

msg (str) – The error message

__annotations__ = {}
__firstlineno__ = 41
__init__(msg)

Exception class constructor

__module__ = 'logging_strict.exceptions'
__static_attributes__ = ()
__weakref__

list of weak references to the object

exception logging_strict.LoggingStrictGenreRequired(msg)

Genre is required

Variables:

msg (str) – The error message

__annotations__ = {}
__firstlineno__ = 89
__init__(msg)

Exception class constructor

__module__ = 'logging_strict.exceptions'
__static_attributes__ = ()
exception logging_strict.LoggingStrictPackageNameRequired(msg)

In entrypoint, package name is required

Variables:

msg (str) – The error message

__annotations__ = {}
__firstlineno__ = 53
__init__(msg)

Exception class constructor

__module__ = 'logging_strict.exceptions'
__static_attributes__ = ()
exception logging_strict.LoggingStrictPackageStartFolderNameRequired(msg)

In entrypoint, package start data folder name is required

Variables:

msg (str) – The error message

__annotations__ = {}
__firstlineno__ = 65
__init__(msg)

Exception class constructor

__module__ = 'logging_strict.exceptions'
__static_attributes__ = ()
exception logging_strict.LoggingStrictProcessCategoryRequired(msg)

Category is required

Variables:

msg (str) – The error message

__annotations__ = {}
__firstlineno__ = 77
__init__(msg)

Exception class constructor

__module__ = 'logging_strict.exceptions'
__static_attributes__ = ()
class logging_strict.LoggingYamlType

ABC for LoggingYaml implementations

__abstractmethods__ = frozenset({'dest_folder', 'extract', 'file_name', 'file_stem', 'package'})
__dict__ = mappingproxy({'__module__': 'logging_strict.logging_yaml_abc', '__firstlineno__': 263, '__doc__': 'ABC for LoggingYaml implementations', 'get_version': <staticmethod(<function LoggingYamlType.get_version>)>, 'pattern': <classmethod(<function LoggingYamlType.pattern>)>, 'iter_yamls': <function LoggingYamlType.iter_yamls>, '__subclasshook__': <classmethod(<function LoggingYamlType.__subclasshook__>)>, 'file_stem': <property object>, 'file_name': <property object>, 'package': <property object>, 'dest_folder': <property object>, 'extract': <function LoggingYamlType.extract>, 'as_str': <function LoggingYamlType.as_str>, 'setup': <function LoggingYamlType.setup>, '__static_attributes__': (), '__dict__': <attribute '__dict__' of 'LoggingYamlType' objects>, '__weakref__': <attribute '__weakref__' of 'LoggingYamlType' objects>, '__abstractmethods__': frozenset({'package', 'extract', 'file_stem', 'file_name', 'dest_folder'}), '_abc_impl': <_abc._abc_data object>, '__annotations__': {}})
__firstlineno__ = 263
__module__ = 'logging_strict.logging_yaml_abc'
__static_attributes__ = ()
classmethod __subclasshook__(C)

A class wanting to be LoggingYamlType, minimally requires:

Properties:

  • file_stem

  • file_name

  • package

  • dest_folder

Methods:

  • extract

  • as_str – get for free

  • setup – get for free

Then register itself LoggingYamlType.register(AnotherDatumClass) or subclass LoggingYamlType

Parameters:

C (Any) – Class to test whether implements this interface or is a subclass

Returns:

True implements LoggingYamlType interface or is a subclass. False not a LoggingYamlType

Return type:

bool

__weakref__

list of weak references to the object

as_str()

Read the YAML config file, raise an error if not there or invalid

The yaml files must have already been extracted from a package

Returns:

YAML str. Pass this to each worker

Return type:

str

Raises:
abstract property dest_folder

logging.config yaml file export destination folder

Returns:

Destination folder. XDG user data dir, on linux, $HOME/.local/share/[app name]

Return type:

pathlib.Path

abstract extract(path_relative_package_dir='')

Extract logging.config yaml files to xdg user data dir

Parameters:

path_relative_package_dir (pathlib.Path | str | None) – Default empty string. Relative to the package base data folder, provide a relative path or str to narrow search results

Returns:

Destination path of extracted/exported logging.config yaml file(s)

Return type:

str

abstract property file_name

Get full file name. Includes stem and suffixes

Returns:

file name

Return type:

str

abstract property file_stem

Get file stem

Returns:

file stem

Return type:

str

static get_version(val)

Get a particular version of a logging.config yaml file

Parameters:

val (Any) – To not filter, getting all versions, None. To get the fallback version, pass in an unsupported type, e.g. 0.12345

Returns:

version as a str (unsigned integer)

Return type:

str

iter_yamls(path_dir)

Conducts a recursive search thru the folder tree starting from package base data folder, further narrow search by relative (to package base data folder) path, logging_strict.logging_yaml_abc.LoggingYamlType.iter_yamls.params.path_dir

Iterator of absolute path of search results

Parameters:

path_dir (pathlib.Path | None) – Absolute path to a folder

Returns:

Within folder tree, iterator of yaml

True if at least one yaml file exists in folder otherwise False

Return type:

collections.abc.Iterator[pathlib.Path]

abstract property package

Get package name

Returns:

package name

Return type:

str

classmethod pattern(category=None, genre=None, flavor=None, version=None)

Search pattern. Can’t distinguish latest version.

Each paramater narrows down search results.

version applies to:

  • genre

or

  • genre and flavor

Parameters:
Returns:

Pattern used with glob.glob() to find files

Return type:

str

setup(str_yaml, package_name=None)

Only called by app, not worker. For worker, is a 2 step process, not 1.

A multiprocessing.pool.Pool worker, needs to be feed the contents of the logging.config YAML file

xdg user data folder: $HOME/.local/share/[app name]

Parameters:

  • str_yaml (str) – logging.config yaml str

  • package_name – In logger dict, instead of the default package name, set a package name. Always desirable.

Type:

str | None

logging_strict.setup_logging_yaml(path_yaml, package_name=None)

Loads logging.config configuration.

Can pass in a path or a the YAML str

Parameters:

  • path_yaml (Any) – logging.config YAML file path

  • package_name (str | None) – Set logger to the intended package name. Default None which leaves as-is

Raises:
logging_strict.setup_ui_other(package_name, package_data_folder_start, genre, flavor, version_no='1', package_start_relative_folder='', logger_package_name=None)

Before creating an App instance, seemlessly extracts logging.config yaml file for app, but not worker(s)

Parameters:

  • package_name (str) – Package name containing logging.config yaml file

  • package_data_folder_start (str) – Package base data folder name. Not a relative path. This is the fallback search folder. Use package_start_relative_folder to further narrow the search

  • genre (str) – UI framework or worker implementation characteristic. E.g. textual, rich, mp, or mq

  • flavor (str) – Brand or how variation differs. e.g. asz

  • version_no (Any | None) – Default “1”. Applies to genre or genre & flavor

  • package_start_relative_folder (str | None) –

    Default empty string.

    Relative to package_data_folder_start.
    Relative path to further narrow down which folder contains the
    logging.config yaml file.

    Needed when multiple folders contain logging.config yaml file
    with same file name

  • logger_package_name (str | None) – Default None. Update the dict to set a more appropriate logger package name. Will always want to do this

Returns:

relative path to validated logging config YAML file and the yaml str

Return type:

tuple[str, str]

Raises:
logging_strict.setup_worker_other(package_name, package_data_folder_start, genre, flavor, version_no='1', package_start_relative_folder='', logger_package_name=None)

worker_yaml_curated grabs the logging.config yaml from logging-strict. Use this if located in another package

Process 2nd step is calling: setup_logging_yaml()

Parameters:

  • package_name (str) – If logging_strict, use method worker_yaml_curated instead. Otherwise package name which contains the logging.config yaml files

  • package_data_folder_start (str) – Within package_name, base data folder name. Not a relative path. Does not assume data

  • genre (str) – Default “mp”. If UI: “textual” or “rich”. If worker: “mp”. Then can have a library of yaml files that can be used with a particular UI framework or worker type

  • flavor (str) –

    Default “asz”. Unique identifier name given to a particular logging.config yaml. Should be one word w/o special characters

    Flavor is a very terse description, for a genre, how this yaml differs from others. If completely generic, call it generic. If different handlers or formatters or filters are used, what is the yaml’s purpose?

  • version_no (Any | None) – Default 1. Version of this particular genre. Not the version of the yaml spec. Don’t confuse the two.

  • package_start_relative_folder (pathlib.Path | str | None) – Default empty string which means search the entire package. Further narrows down search, so as to differentiate between folders which contain file with the same file name

  • logger_package_name (str | None) – Set logger to the intended package name. Default None which leaves as-is

Returns:

relative destination path to validated logging config YAML file and the yaml str

Return type:

tuple[str, str]

Raises:
logging_strict.ui_yaml_curated(genre, flavor, version_no='1', package_start_relative_folder='', logger_package_name=None)

Curated within logging-strict So do not have to provide package and package base data folder name

Parameters:

  • genre (str) – UI framework or worker implementation characteristic. E.g. textual, rich, mp, or mq

  • flavor (str) – Brand or how variation differs. e.g. asz

  • version_no (Any | None) – Default “1”. Applies to genre or genre & flavor

  • package_start_relative_folder (str) –

    Default empty string. Relative to package_data_folder_start. Relative path to further narrow down which folder contains the logging.config yaml file.

    Needed when multiple folders contain logging.config yaml file with same file name

  • logger_package_name (str | None) – In logger dict, instead of the default package name, set a package name. Always desirable.

Returns:

relative destination path to validated logging config YAML file and the yaml str

Return type:

tuple[str, str]

logging_strict.worker_yaml_curated(genre='mp', flavor='asz', version_no='1', package_start_relative_folder='', logger_package_name=None)

For multiprocessing workers, retrieve the yaml in this order:

  • xdg user data dir folder

  • logging_strict package

If QA tester, modifies the exported logging.config yaml, those changes are not overwritten

Process 2nd step is calling: setup_logging_yaml()

Parameters:

  • genre (str | None) – Default “mp”. If UI: “textual” or “rich”. If worker: “mp”. Then can have a library of yaml files that can be used with a particular UI framework or worker type

  • flavor (str | None) –

    Default “asz”. Unique identifier name given to a particular logging.config yaml. Should be one word w/o special characters

    Flavor is a very terse description, for a genre, how this yaml differs from others. If completely generic, call it generic. If different handlers or formatters or filters are used, what is the yaml’s purpose?

  • version_no (Any | None) – Default 1. Version of this particular genre. Not the version of the yaml spec. Don’t confuse the two.

  • package_start_relative_folder (pathlib.Path | str | None) – Default empty string which means search the entire package. Further narrows down search, so as to differentiate between folders which contain file with the same file name

  • logger_package_name (str | None) – Set logger to the intended package name. Default None which leaves as-is

Returns:

relative destination path to validated logging config YAML file and the yaml str

Return type:

tuple[str, str]

Raises: