logging-strict 1.5.0__py3-none-any.whl

logging_strict/__init__.py

@@ -0,0 +1,147 @@
+"""
+UI
+---
+
+:ref:`getting_started/usage:app`
+
+Within UI process, call both:
+
+- LoggingState
+
+- ui_yaml_curated or setup_ui_other
+
+worker process
+---------------
+
+:ref:`getting_started/usage: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
+----------
+
+- LoggingConfigCategory
+  :ref:`[constant docs] <code/constants/constants_general:top>`
+
+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
+------
+
+- LoggingYamlType
+  :ref:`[type docs] <code/yaml/logging_yaml_abc:top>`
+
+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
+-----------
+
+:ref:`[exc docs] <code/constants/exceptions:exceptions>`
+
+- LoggingStrictError
+
+logging_strict catch all Exception. Base type of other exceptions.
+Implements ValueError
+
+Provided just for completeness. Not intended for use
+
+- LoggingStrictPackageNameRequired
+
+:abbr:`ep (entrypoint)` requires package name
+
+Corresponding exit code -- 6
+
+- LoggingStrictPackageStartFolderNameRequired
+
+:abbr:`ep (entrypoint)` 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, :abbr:`mp (multiprocessing)` or :abbr:`mq (rabbitmq)`
+
+"""
+
+from .constants import LoggingConfigCategory
+from .exceptions import (
+    LoggingStrictError,
+    LoggingStrictGenreRequired,
+    LoggingStrictPackageNameRequired,
+    LoggingStrictPackageStartFolderNameRequired,
+    LoggingStrictProcessCategoryRequired,
+)
+from .logging_api import (
+    LoggingState,
+    setup_ui_other,
+    setup_worker_other,
+    ui_yaml_curated,
+    worker_yaml_curated,
+)
+from .logging_yaml_abc import (
+    LoggingYamlType,
+    setup_logging_yaml,
+)
+
+__all__ = (
+    "LoggingConfigCategory",
+    "LoggingState",
+    "LoggingYamlType",
+    "setup_ui_other",
+    "ui_yaml_curated",
+    "setup_worker_other",
+    "worker_yaml_curated",
+    "setup_logging_yaml",
+    "LoggingStrictError",
+    "LoggingStrictPackageNameRequired",
+    "LoggingStrictPackageStartFolderNameRequired",
+    "LoggingStrictProcessCategoryRequired",
+    "LoggingStrictGenreRequired",
+)

logging_strict/__init__.pyi

@@ -0,0 +1,35 @@
+from .constants import LoggingConfigCategory
+from .exceptions import (
+    LoggingStrictError,
+    LoggingStrictGenreRequired,
+    LoggingStrictPackageNameRequired,
+    LoggingStrictPackageStartFolderNameRequired,
+    LoggingStrictProcessCategoryRequired,
+)
+from .logging_api import (
+    LoggingState,
+    setup_ui_other,
+    setup_worker_other,
+    ui_yaml_curated,
+    worker_yaml_curated,
+)
+from .logging_yaml_abc import (
+    LoggingYamlType,
+    setup_logging_yaml,
+)
+
+__all__ = (
+    "LoggingConfigCategory",
+    "LoggingState",
+    "LoggingYamlType",
+    "setup_ui_other",
+    "ui_yaml_curated",
+    "setup_worker_other",
+    "worker_yaml_curated",
+    "setup_logging_yaml",
+    "LoggingStrictError",
+    "LoggingStrictPackageNameRequired",
+    "LoggingStrictPackageStartFolderNameRequired",
+    "LoggingStrictProcessCategoryRequired",
+    "LoggingStrictGenreRequired",
+)

logging_strict/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '1.5.0'
+__version_tuple__ = version_tuple = (1, 5, 0)

logging_strict/_version.pyi

@@ -0,0 +1,6 @@
+from typing import Final
+
+version: Final[str]
+__version__: Final[str]
+__version_tuple__: Final[tuple[int | str, ...]]
+version_tuple: Final[tuple[int | str, ...]]

logging_strict/bad_idea/folder0/mp_1_shared.worker.logging.config.yaml

@@ -0,0 +1 @@
+version: 1

logging_strict/bad_idea/folder1/mp_1_shared.worker.logging.config.yaml

@@ -0,0 +1 @@
+version: 1

logging_strict/configs/mp_1_asz.worker.logging.config.yaml

@@ -0,0 +1,27 @@
+version: 1
+disable_existing_loggers: false
+raise_exceptions: true
+formatters:
+  detailed:
+    class: logging.Formatter
+    format: '%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
+  simple:
+    class: logging.Formatter
+    format: '%(name)-15s %(levelname)-8s %(processName)-10s %(message)s'
+handlers:
+  console_worker:
+    class: logging.StreamHandler
+    formatter: simple
+    level: WARNING
+loggers:
+  package_name:
+    handlers: [console_worker]
+    propagate: true
+    level: INFO
+  asyncio:
+    handlers: [console_worker]
+    propagate: true
+    level: ERROR
+root:
+  handlers: [console_worker]
+  level: ERROR

logging_strict/configs/textual_1_asz.app.logging.config.yaml

@@ -0,0 +1,24 @@
+version: 1
+disable_existing_loggers: false
+raise_exceptions: true
+formatters:
+  simple:
+    class: logging.Formatter
+    format: '%(levelname)s %(module)s %(funcName)s: %(lineno)d: %(message)s'
+handlers:
+  console_ui:
+    '()': ext://textual.logging.TextualHandler
+    formatter: simple
+    level: WARNING
+loggers:
+  package_name:
+    handlers: [console_ui]
+    propagate: true
+    level: INFO
+  asyncio:
+    handlers: [console_ui]
+    propagate: true
+    level: ERROR
+root:
+  handlers: [console_ui]
+  level: ERROR

logging_strict/constants.py

@@ -0,0 +1,190 @@
+"""
+.. moduleauthor:: Dave Faulkmore <https://mastodon.social/@msftcangoblowme>
+
+Seperate constants out so independent of any dependencies
+
+**Module private variables**
+
+.. py:data:: _map_release
+   :type: types.MappingProxyType
+   :value: types.MappingProxyType({"alpha": "a", "beta": "b", "candidate": "rc"})
+
+   Mapping of release levels. So can gracefully go back and forth
+
+.. py:data:: __all__
+   :type: tuple[str, str, str, str, str, str, str, str]
+   :value: ("g_app_name", "__version_app", "LoggingConfigCategory", \
+   "PREFIX_DEFAULT", "LOG_FORMAT", "FALLBACK_LEVEL", "sanitize_tag", \
+   "get_version")
+
+   Module exports
+
+**Module objects**
+
+.. py:data:: g_app_name
+   :type: str
+   :value: "logging_strict"
+
+   App name. No hyphens. Lowercase. Not project name which can contain
+   hyphen
+
+.. py:data:: PREFIX_DEFAULT
+   :type: str
+   :value: "test_"
+
+   unittest module default file name prefix
+
+.. py:data:: LOG_FORMAT
+   :type: str
+   :value: "%(levelname)s %(module)s %(funcName)s: %(lineno)d: %(message)s"
+
+   :py:mod:`logging` handlers contain formatters, which require a format
+   str. Especially pertinent to unittests
+
+.. py:data:: FALLBACK_LEVEL
+   :type: str
+   :value: "DEBUG"
+
+   Fallback logging level, if provided level is an unsupported type, None, or empty str.
+   So by default, this logging level, captures all.
+
+.. py:data:: LOG_FMT_DETAILED
+   :type: str
+   :value: "%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s"
+
+   Detailed log message format. Notably includes: time, logger
+   (worker) name, and process name
+
+.. py:data:: LOG_FMT_SIMPLE
+   :type: str
+   :value: "%(name)-15s %(levelname)-8s %(processName)-10s %(message)s"
+
+   Terse log message format. Notably includes: logger (worker) name and process name
+
+.. py:data:: LOG_LEVEL_WORKER
+   :type: str
+   :value: "INFO"
+
+   Show messages from :py:data:`logging.INFO` and higher
+
+   .. seealso::
+
+      - :py:meth:`coverage.control.Coverage.start`
+
+      - :py:mod:`coverage.multiproc`
+
+
+.. py:data:: version_info
+   :type: tuple[int, int, int, str, int]
+
+   Same semantics as :py:data:`sys.version_info`
+
+.. py:data:: _dev
+   :type: int
+
+   .devN suffix, if any
+
+.. py:data:: __version__
+   :type: str
+
+   Semantic versioning.
+
+   :py:mod:`setuptools_scm` semantic versioning in: logging_strict._version.__version__
+
+   .. code-block:: shell
+
+      python igor.py bump_version
+
+   ``igor.py`` updates this file, writing both version_info and _dev
+
+   Dynamically generated by :py:mod:`setuptools_scm`
+   if no patch or no tags at all SemVer will break.
+
+   e.g. 2.1.devX instead of 2.0.1.devX
+
+   Always include patch and ensure at least one tagged version
+
+   .. seealso::
+
+      :py:mod:`setuptools_scm`
+
+
+"""
+
+from __future__ import annotations
+
+import logging  # noqa: F401 used by sphinx
+from enum import Enum
+from typing import Any  # noqa: F401 used by sphinx
+
+from ._version import __version__
+from .version_semantic import (
+    readthedocs_url,
+    sanitize_tag,
+)
+
+__all__ = (
+    "g_app_name",
+    "__version_app",
+    "__url__",
+    "PREFIX_DEFAULT",
+    "LoggingConfigCategory",
+    "LOG_FORMAT",
+    "FALLBACK_LEVEL",
+)
+
+g_app_name = "logging_strict"
+
+PREFIX_DEFAULT = "test_"
+
+
+def enum_map_func_get_value(enum_item):
+    """func for use with Python built-in :py:func:`map`, to get the
+    value of an Enum item
+
+    :param enum_item: Enum subclass item. Get the Enum item value
+    :type enum_item: type[enum.Enum]
+    :returns: Enum item value. Can be anything but usually a str or int
+    :rtype: typing.Any
+    """
+    return enum_item.value
+
+
+class LoggingConfigCategory(Enum):
+    """logging.config yaml process categories
+
+    Public API
+
+    .. code-block:: text
+
+       from logging_strict import LoggingConfigCategory
+
+    """
+
+    WORKER = "worker"
+    UI = "app"
+
+    @classmethod
+    def categories(cls):
+        """Get Enum items' value
+
+        :returns: In this case, Enum values holds str
+        :rtype: collections.abc.Iterator[str]
+        """
+        values = cls._member_map_.values()
+        yield from map(enum_map_func_get_value, values)
+
+
+LOG_FORMAT = "%(levelname)s %(module)s %(funcName)s: %(lineno)d: %(message)s"
+FALLBACK_LEVEL = logging.getLevelName(logging.DEBUG)
+
+# Thread pool worker
+LOG_FMT_DETAILED = (
+    "%(asctime)s %(name)-15s %(levelname)-8s %(processName)-10s %(message)s"
+)
+LOG_FMT_SIMPLE = "%(name)-15s %(levelname)-8s %(processName)-10s %(message)s"
+LOG_LEVEL_WORKER = "INFO"
+
+# Removes epoch and local. Fixes version
+__version_app = sanitize_tag(__version__)
+__url__ = readthedocs_url(g_app_name, ver_=__version__)

logging_strict/constants.pyi

@@ -0,0 +1,38 @@
+from collections.abc import Iterator
+from enum import Enum
+from typing import (
+    Any,
+    Final,
+)
+
+__all__ = (
+    "g_app_name",
+    "__version_app",
+    "__url__",
+    "PREFIX_DEFAULT",
+    "LoggingConfigCategory",
+    "LOG_FORMAT",
+    "FALLBACK_LEVEL",
+)
+
+g_app_name: Final[str]
+PREFIX_DEFAULT: Final[str]
+
+def enum_map_func_get_value(enum_item: type[Enum]) -> Any: ...
+
+class LoggingConfigCategory(Enum):
+    WORKER = "worker"
+    UI = "app"
+
+    @classmethod
+    def categories(cls) -> Iterator[str]: ...
+
+LOG_FORMAT: Final[str]
+FALLBACK_LEVEL: Final[str]
+
+LOG_FMT_DETAILED: Final[str]
+LOG_FMT_SIMPLE: Final[str]
+LOG_LEVEL_WORKER: Final[str]
+
+__version_app: Final[str]
+__url__: Final[str]