YAML ABC

Abstract Base Class.

Public API

from logging_strict import LoggingYamlType

Non-abstract methods:

• as_str

• setup – applicable only for the UI

• iter_yamls – search a (non-package) folder

• get_version – staticmethod

• pattern – classmethod

Base class of logging_yaml implementations

logging.config yaml config files are exported to $HOME/.locals/share/[app name]

One for the app and another for worker(s).

QA Tester can edit the yaml config files, before using, ensure validation passes!

Module private variables

logging_strict.logging_yaml_abc.__all__: tuple[str, str, str, str] = ("LoggingYamlType", "YAML_LOGGING_CONFIG_SUFFIX",    "after_as_str_update_package_name", "setup_logging_yaml")

Module exports

logging_strict.logging_yaml_abc.YAML_LOGGING_CONFIG_SUFFIX: str = ".logging.config.yaml"

For logging.config YAML files, define file extension (Suffixes) Differentiates from other .yaml files

logging_strict.logging_yaml_abc.VERSION_FALLBACK: str = "1"

Initial version of logging.config YAML files

logging_strict.logging_yaml_abc.PACKAGE_NAME_SRC: str = "asz"

In a .logging.config.yaml, under loggers, default package name. Should be a generic replacable name, package_name

Module objects

class logging_strict.logging_yaml_abc.LoggingYamlType

ABC for LoggingYaml implementations

__abstractmethods__ = frozenset({'dest_folder', 'extract', 'file_name', 'file_stem', 'package'})

__annotations__ = {}

__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

_abc_impl = <_abc._abc_data 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:

• strictyaml.exceptions.YAMLValidationError – Invalid. Validation against logging.config schema failed

• FileNotFoundError – Could not find logging config YAML file

• LoggingStrictGenreRequired – Genre required to get file name

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:

• category (str | None)

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

• flavor (str | None) –

  Unique identifier name given to a particular logging.config yaml. This name is slugified. Meaning period and underscores converted to hyphens

  Flavor is a very terse description, for a logging_strict.logging_yaml_abc.LoggingYamlType.pattern.params.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 (Any | None) – Default “1”. Version of this particular logging_strict.logging_yaml_abc.LoggingYamlType.pattern.params.category. Not the version of the yaml spec. Don’t confuse the two.

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.logging_yaml_abc.after_as_str_update_package_name(str_yaml, logger_package_name=None, target_logger_name='package_name')

Validation already occurred. In yaml, replace logger package name

Parameters:

• str_yaml (str) – validated yaml that needs some adjustments

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

• target_logger_name (str | None) – in logger config dict, logger name to replace

Returns:

yaml str after adjustments

Return type:

str

logging_strict.logging_yaml_abc.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:

• strictyaml.YAMLValidationError – Invalid. Validation against logging.config schema failed