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

Thread safe 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

__dict__ = mappingproxy({'__module__': 'logging_strict.logging_api', '__firstlineno__': 992, '__doc__': 'Thread safe Singleton to hold the current logging state. To know whether or\nnot, 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\n**Class variables**\n\n:cvar _instance: Default None. Holds Singleton instance\n:type _instance: logging_strict.logging_api.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', '_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>, '__annotations__': {}})
__firstlineno__ = 992
__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__ = 50
__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__ = 98
__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__ = 62
__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__ = 74
__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__ = 86
__init__(msg)

Exception class constructor

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

ABC for LoggingYaml implementations

__abstractmethods__ = frozenset({'category', 'dest_folder', 'extract', 'file_name', 'file_stem', 'flavor', 'genre', 'package', 'version'})
__annotations__ = {'suffixes': typing.ClassVar[str]}
__dict__ = mappingproxy({'__module__': 'logging_strict.logging_yaml_abc', '__firstlineno__': 228, '__annotations__': {'suffixes': typing.ClassVar[str]}, '__doc__': 'ABC for LoggingYaml implementations', 'category': <property object>, 'genre': <property object>, 'flavor': <property object>, 'version': <property object>, '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({'file_stem', 'genre', 'extract', 'dest_folder', 'flavor', 'category', 'file_name', 'package', 'version'}), '_abc_impl': <_abc._abc_data object>})
__firstlineno__ = 228
__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 category: str | None

Template method pattern. These dependencies provided by subclasses

Return type:

str | None

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

abstract property flavor: str | None

Template method pattern. These dependencies provided by subclasses

Return type:

str | None

abstract property genre: str | None

Template method pattern. These dependencies provided by subclasses

Return type:

str | None

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

suffixes: ClassVar[str]
abstract property version: str | None

Template method pattern. These dependencies provided by subclasses

Return type:

str | None

logging_strict.setup_logging_yaml(path_yaml, package_name=None)

Loads logging.config configuration.

Can pass in a path or a 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: