hanaro 0.0.1__tar.gz

hanaro-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) Shaun Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hanaro-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: hanaro
+Version: 0.0.1
+Summary: A non-invasive `logging` configurator and facilitator.
+Author-email: Shaun Wilson <mrshaunwilson@msn.com>
+Project-URL: Documentation, https://hanaro.readthedocs.io/
+Project-URL: Homepage, https://github.com/wilson0x4d/hanaro
+Project-URL: Repository, https://github.com/wilson0x4d/hanaro.git
+Keywords: logging,configuration,appsettings2,async
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+`hanaro` (하나로) is a non-invasive `logging` configurator and facilitator for Python.
+
+This README is only a high-level introduction to **hanaro**. For more detailed documentation, please view the official docs at [https://hanaro.readthedocs.io](https://hanaro.readthedocs.io).
+
+## Installation
+
+**hanaro** can be installed from pypi through the usual means:
+
+```bash
+pip install hanaro
+```
+
+## Usage
+
+Let's try a "learn by example" approach. The following two snippets are the contents of a configuration file that contains a "logging" configuration section, and a Python code file that initializes Python's standard `logging` system using that configuration. This is by no means an exhaustive example, it only intends to touch on the major offerings of **hanaro**.
+
+> NOTE: Configuration handling is performed using `appsettings2` which supports json, toml, yaml, xml, command-line args, and environment variables to provide a unified configuration solution. This example, however, uses json because of json's wider familiarity. For the sake of demonstration assume this content is in a file named `appsettings.json`.
+
+```json
+{
+    "logging": {
+        "level": "INFO",
+        "format": "[%(asctime)s] %(message)s level=%(levelname)s source=%(name)s %(meta)s",
+        "datefmt": "%Y-%m-%dT%H:%M:%S",
+        "handlers": [
+            {
+                "type": "console",
+                "level": "DEBUG"
+            },
+            {
+                "type": "file",
+                "level": "DEBUG",
+                "path": "logs/",
+                "name": "debug.log",
+                "max_size": "4KiB",
+                "max_count": 10,
+                "format": "[%(asctime)s] level=%(levelname)s %(message)s source=\"%(name)s\" func=\"%(funcName)s\" %(meta)s"
+            },
+            {
+                "type": "custom",
+                "canonical": "myapp.mymodule.myhandler",
+                "level": "WARNING",
+                "format": "msg=\"%(message)s\" level=\"%(levelname)s\" source=\"%(name)s\" func=\"%(funcName)s\" %(meta)s"
+            }
+        ],
+        "filters": {
+            "asyncio": {
+                "level": "WARNING"
+            },
+            "mysql.connector": {
+                "level": "WARNING"
+            },
+            "urllib3.connectionpool": {
+                "level": "WARNING"
+            },
+            "websockets.client": {
+                "level": "WARNING"
+            }
+        }
+    },
+}
+```
+
+This code sample is a minimum-viable solution. The `custom` handler above is omitted, but for the sake of demonstration know that `canonical` is the fully-qualified type name of a `logging.Handler` subclass and **hanaro** will create an instance of that class and configure as it does all other handlers.
+
+```python
+from appsettings2 import getConfiguration
+from hanaro import configureLogging
+import logging
+
+configureLogging(getConfiguration())
+
+logger = logging.getLogger(__name__)
+
+logger.info('Hello, World!')
+```
+
+When executed the program outputs the following:
+
+```plaintext
+[2025-12-31T12:34:56] Hello, World! level=INFO source=__main__ 
+```
+
+## Notables..
+
+Things not obvious given the example above:
+
+* All configuration options are optional, you can reduce the config to specifying only those things you wish to customize.
+* It is not necessary to load a configuration at all, a call to `configureLogging()` will still apply reasonable defaults such as adding a console handler, applying a line format, applying a default date format (ISO 9601), etc.
+* If no handlers are configured, a default handler for "console" is configured.
+
+**hanaro** only has a single direct dependency: [``appsettings2``](https://pypi.org/project/appsettings2/).
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/hanaro/issues/new/choose).

hanaro-0.0.1/README.md

@@ -0,0 +1,96 @@
+`hanaro` (하나로) is a non-invasive `logging` configurator and facilitator for Python.
+
+This README is only a high-level introduction to **hanaro**. For more detailed documentation, please view the official docs at [https://hanaro.readthedocs.io](https://hanaro.readthedocs.io).
+
+## Installation
+
+**hanaro** can be installed from pypi through the usual means:
+
+```bash
+pip install hanaro
+```
+
+## Usage
+
+Let's try a "learn by example" approach. The following two snippets are the contents of a configuration file that contains a "logging" configuration section, and a Python code file that initializes Python's standard `logging` system using that configuration. This is by no means an exhaustive example, it only intends to touch on the major offerings of **hanaro**.
+
+> NOTE: Configuration handling is performed using `appsettings2` which supports json, toml, yaml, xml, command-line args, and environment variables to provide a unified configuration solution. This example, however, uses json because of json's wider familiarity. For the sake of demonstration assume this content is in a file named `appsettings.json`.
+
+```json
+{
+    "logging": {
+        "level": "INFO",
+        "format": "[%(asctime)s] %(message)s level=%(levelname)s source=%(name)s %(meta)s",
+        "datefmt": "%Y-%m-%dT%H:%M:%S",
+        "handlers": [
+            {
+                "type": "console",
+                "level": "DEBUG"
+            },
+            {
+                "type": "file",
+                "level": "DEBUG",
+                "path": "logs/",
+                "name": "debug.log",
+                "max_size": "4KiB",
+                "max_count": 10,
+                "format": "[%(asctime)s] level=%(levelname)s %(message)s source=\"%(name)s\" func=\"%(funcName)s\" %(meta)s"
+            },
+            {
+                "type": "custom",
+                "canonical": "myapp.mymodule.myhandler",
+                "level": "WARNING",
+                "format": "msg=\"%(message)s\" level=\"%(levelname)s\" source=\"%(name)s\" func=\"%(funcName)s\" %(meta)s"
+            }
+        ],
+        "filters": {
+            "asyncio": {
+                "level": "WARNING"
+            },
+            "mysql.connector": {
+                "level": "WARNING"
+            },
+            "urllib3.connectionpool": {
+                "level": "WARNING"
+            },
+            "websockets.client": {
+                "level": "WARNING"
+            }
+        }
+    },
+}
+```
+
+This code sample is a minimum-viable solution. The `custom` handler above is omitted, but for the sake of demonstration know that `canonical` is the fully-qualified type name of a `logging.Handler` subclass and **hanaro** will create an instance of that class and configure as it does all other handlers.
+
+```python
+from appsettings2 import getConfiguration
+from hanaro import configureLogging
+import logging
+
+configureLogging(getConfiguration())
+
+logger = logging.getLogger(__name__)
+
+logger.info('Hello, World!')
+```
+
+When executed the program outputs the following:
+
+```plaintext
+[2025-12-31T12:34:56] Hello, World! level=INFO source=__main__ 
+```
+
+## Notables..
+
+Things not obvious given the example above:
+
+* All configuration options are optional, you can reduce the config to specifying only those things you wish to customize.
+* It is not necessary to load a configuration at all, a call to `configureLogging()` will still apply reasonable defaults such as adding a console handler, applying a line format, applying a default date format (ISO 9601), etc.
+* If no handlers are configured, a default handler for "console" is configured.
+
+**hanaro** only has a single direct dependency: [``appsettings2``](https://pypi.org/project/appsettings2/).
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/hanaro/issues/new/choose).

hanaro-0.0.1/hanaro/ConfigFilter.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: Copyright (C) Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import logging
+
+
+class _ConfigFilterSettings:
+
+    def __init__(self, source:str, settings:dict[str,str]):
+        self.source = source
+        self.level = getattr(logging, settings.get("level", "DEBUG").upper())
+
+
+class ConfigFilter(logging.Filter):
+
+    def __init__(self, config:dict[str,dict[str,str]]):
+        self.__settings = [_ConfigFilterSettings(k, v) for k,v in config.items()]
+        super().__init__()
+
+    def filter(self, record:logging.LogRecord) -> bool:
+        for e in self.__settings:
+            if record.name == e.source:
+                if record.levelno < e.level:
+                    return False
+        return True

hanaro-0.0.1/hanaro/ContextInjectionFilter.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (C) Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import logging
+import re
+
+
+class ContextInjectionFilter(logging.Filter):
+
+    def __init__(self, context:dict[str,str] = None, isMetadata:bool = False, metadataName:str = 'metadata'):
+        self.__context = context if context is not None else {}
+        self.__isMetadata = isMetadata
+        self.__metadataName = metadataName if metadataName is not None and len(metadataName) > 0 else 'metadata'
+        super().__init__()
+
+    def __getitem__(self, key:str) -> str|None:
+        self.__context.get(key, None)
+
+    def __setitem__(self, key:str, value:str|None) -> None:        
+        self.__context[key] = value
+
+    def __delitem__(self, key:str) -> None:
+        self.__context.pop(key, None)
+
+    def filter(self, record:logging.LogRecord) -> bool:
+        if self.__isMetadata:
+            metadata = f' {getattr(record, self.__metadataName, '')}'
+            for k,v in self.__context.items():
+                if not hasattr(record, k):
+                    metadata = f'{metadata} {k}="{v}"'
+                else:
+                    metadata = re.sub(f' {k}="[^"]*"', f' {k}="{v}"', metadata)
+                setattr(record, k, v)
+            setattr(record, self.__metadataName, metadata.lstrip())
+        else:            
+            for k,v in self.__context.items():
+                setattr(record, k, v)
+        return True

hanaro-0.0.1/hanaro/QueuedHandler.py

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: Copyright (C) Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import logging
+import queue
+
+
+class QueuedHandler(logging.Handler):
+
+    __s_queue:queue.Queue[logging.LogRecord] = queue.Queue()
+
+    def __init__(self):
+        super().__init__()
+
+    def emit(self, record:logging.LogRecord) -> None:
+        QueuedHandler.__s_queue.put(record)
+
+    @staticmethod
+    def getLogRecord() -> logging.LogRecord|None:
+        record:logging.LogRecord = None
+        try:
+             record = QueuedHandler.__s_queue.get_nowait()
+        except:
+            pass
+        return record

hanaro-0.0.1/hanaro/__init__.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: Copyright (C) Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from .utils import configureLogging, getQueuedLogger
+from .ConfigFilter import ConfigFilter
+from .ContextInjectionFilter import ContextInjectionFilter
+from .QueuedHandler import QueuedHandler
+from . import utils
+
+__version__ = '0.0.1'
+__commit__ = '3ee5ba9'
+
+__all__ = [
+    '__version__', '__commit__',
+    'ConfigFilter',
+    'ContextInjectionFilter',
+    'configureLogging',
+    'getQueuedLogger',
+    'QueuedHandler',
+    'utils'
+]

hanaro-0.0.1/hanaro/utils.py

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: Copyright (C) Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+import importlib
+import os
+import appsettings2
+import logging
+import logging.handlers
+import sys
+
+from .ConfigFilter import ConfigFilter
+from .ContextInjectionFilter import ContextInjectionFilter
+from .QueuedHandler import QueuedHandler
+
+
+def configureLogging(config:appsettings2.Configuration = None) -> list[logging.Handler]:
+    config = config if config is not None else appsettings2.Configuration()
+    handlers = []
+    defaultLevel = getattr(logging, config.get('logging__level', 'DEBUG').upper())
+    defaultFormat = config.get('logging__format', logging.BASIC_FORMAT)
+    filters:appsettings2.Configuration = config.get('logging__filters', None)
+    configFilter = ConfigFilter(filters.toDictionary() if filters is not None else {})
+    contextInjectorFilter = ContextInjectionFilter({}, True)
+    datefmt = config.get('logging__datefmt', '%Y-%m-%dT%H:%M:%S')
+    # create configured handlers
+    handler_configs = config.get('logging__handlers')
+    if handler_configs != None:
+        for handler_config in handler_configs:
+            handler = None
+            match str(handler_config.get('type')).lower():
+                case 'custom':
+                    module_name, class_name = handler_config.get('class').rsplit('.', 1)
+                    module = importlib.import_module(module_name)
+                    handler_class = getattr(module, class_name)
+                    args = handler_config.get('args')
+                    handler = handler_class(**(args.toDictionary() if args is not None else {}))
+                case 'console':
+                    handler = logging.StreamHandler(sys.stdout)                    
+                case 'file':
+                    log_path = handler_config.get('path')
+                    if log_path == None:
+                        log_path = '.'
+                    log_path = os.path.abspath(log_path)
+                    os.makedirs(log_path, exist_ok=True)
+                    log_name = handler_config.get('name')
+                    if log_name == None:
+                        log_name = 'adamantium.log'
+                    log_name = os.path.join(log_path, log_name)
+                    max_size = handler_config.get('max_size')                    
+                    if max_size == None:
+                        max_size = 4 * 1024 * 1024
+                    elif not type(max_size) is int:
+                        size_unit = max_size[len(max_size)-3:].upper()
+                        match size_unit:
+                            case 'KIB':
+                                max_size = int(max_size[:-3]) * 1024
+                            case 'MIB':
+                                max_size = int(max_size[:-3]) * 1024 * 1024
+                            case 'GIB':
+                                max_size = int(max_size[:-3]) * 1024 * 1024 * 1024
+                            case _:
+                                max_size = int(max_size)
+                    max_count = handler_config.get('max_count')
+                    if max_count == None:
+                        max_count = 10
+                    else:
+                        max_count = int(max_count)
+                    handler = logging.handlers.RotatingFileHandler(
+                        filename = log_name,
+                        encoding = 'utf-8',
+                        maxBytes = max_size,
+                        backupCount = max_count)
+            if handler != None:
+                handler.setLevel(getattr(logging, handler_config.get('level', defaultLevel).upper()))
+                handler.formatter = logging.Formatter(handler_config.get('format', defaultFormat), datefmt)
+                handler.addFilter(configFilter)
+                handler.addFilter(contextInjectorFilter)
+                handlers.append(handler)
+    # log to stdout if no handlers configured
+    if len(handlers) == 0:
+        handlers.append(logging.StreamHandler(sys.stdout))
+    # init
+    logging.basicConfig(
+        format = defaultFormat,
+        datefmt = datefmt,
+        handlers = handlers,
+        level = defaultLevel,
+        force = True
+    )
+    # return handlers so they can be registered with other loggers if necessary
+    logger = logging.getLogger(__name__)
+    return handlers
+
+def getQueuedLogger(name:str) -> logging.Logger:
+    logger = logging.Logger(name)
+    logger.addHandler(QueuedHandler())
+    return logger
+
+__all__ = [
+    'configureLogging',
+    'getQueuedLogger'
+]

hanaro-0.0.1/hanaro.egg-info/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: hanaro
+Version: 0.0.1
+Summary: A non-invasive `logging` configurator and facilitator.
+Author-email: Shaun Wilson <mrshaunwilson@msn.com>
+Project-URL: Documentation, https://hanaro.readthedocs.io/
+Project-URL: Homepage, https://github.com/wilson0x4d/hanaro
+Project-URL: Repository, https://github.com/wilson0x4d/hanaro.git
+Keywords: logging,configuration,appsettings2,async
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+`hanaro` (하나로) is a non-invasive `logging` configurator and facilitator for Python.
+
+This README is only a high-level introduction to **hanaro**. For more detailed documentation, please view the official docs at [https://hanaro.readthedocs.io](https://hanaro.readthedocs.io).
+
+## Installation
+
+**hanaro** can be installed from pypi through the usual means:
+
+```bash
+pip install hanaro
+```
+
+## Usage
+
+Let's try a "learn by example" approach. The following two snippets are the contents of a configuration file that contains a "logging" configuration section, and a Python code file that initializes Python's standard `logging` system using that configuration. This is by no means an exhaustive example, it only intends to touch on the major offerings of **hanaro**.
+
+> NOTE: Configuration handling is performed using `appsettings2` which supports json, toml, yaml, xml, command-line args, and environment variables to provide a unified configuration solution. This example, however, uses json because of json's wider familiarity. For the sake of demonstration assume this content is in a file named `appsettings.json`.
+
+```json
+{
+    "logging": {
+        "level": "INFO",
+        "format": "[%(asctime)s] %(message)s level=%(levelname)s source=%(name)s %(meta)s",
+        "datefmt": "%Y-%m-%dT%H:%M:%S",
+        "handlers": [
+            {
+                "type": "console",
+                "level": "DEBUG"
+            },
+            {
+                "type": "file",
+                "level": "DEBUG",
+                "path": "logs/",
+                "name": "debug.log",
+                "max_size": "4KiB",
+                "max_count": 10,
+                "format": "[%(asctime)s] level=%(levelname)s %(message)s source=\"%(name)s\" func=\"%(funcName)s\" %(meta)s"
+            },
+            {
+                "type": "custom",
+                "canonical": "myapp.mymodule.myhandler",
+                "level": "WARNING",
+                "format": "msg=\"%(message)s\" level=\"%(levelname)s\" source=\"%(name)s\" func=\"%(funcName)s\" %(meta)s"
+            }
+        ],
+        "filters": {
+            "asyncio": {
+                "level": "WARNING"
+            },
+            "mysql.connector": {
+                "level": "WARNING"
+            },
+            "urllib3.connectionpool": {
+                "level": "WARNING"
+            },
+            "websockets.client": {
+                "level": "WARNING"
+            }
+        }
+    },
+}
+```
+
+This code sample is a minimum-viable solution. The `custom` handler above is omitted, but for the sake of demonstration know that `canonical` is the fully-qualified type name of a `logging.Handler` subclass and **hanaro** will create an instance of that class and configure as it does all other handlers.
+
+```python
+from appsettings2 import getConfiguration
+from hanaro import configureLogging
+import logging
+
+configureLogging(getConfiguration())
+
+logger = logging.getLogger(__name__)
+
+logger.info('Hello, World!')
+```
+
+When executed the program outputs the following:
+
+```plaintext
+[2025-12-31T12:34:56] Hello, World! level=INFO source=__main__ 
+```
+
+## Notables..
+
+Things not obvious given the example above:
+
+* All configuration options are optional, you can reduce the config to specifying only those things you wish to customize.
+* It is not necessary to load a configuration at all, a call to `configureLogging()` will still apply reasonable defaults such as adding a console handler, applying a line format, applying a default date format (ISO 9601), etc.
+* If no handlers are configured, a default handler for "console" is configured.
+
+**hanaro** only has a single direct dependency: [``appsettings2``](https://pypi.org/project/appsettings2/).
+
+## Contact
+
+You can reach me on [Discord](https://discordapp.com/users/307684202080501761) or [open an Issue on Github](https://github.com/wilson0x4d/hanaro/issues/new/choose).

hanaro-0.0.1/hanaro.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+hanaro/ConfigFilter.py
+hanaro/ContextInjectionFilter.py
+hanaro/QueuedHandler.py
+hanaro/__init__.py
+hanaro/utils.py
+hanaro.egg-info/PKG-INFO
+hanaro.egg-info/SOURCES.txt
+hanaro.egg-info/dependency_links.txt
+hanaro.egg-info/top_level.txt

hanaro-0.0.1/hanaro.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hanaro-0.0.1/hanaro.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+dist
+docs
+hanaro

hanaro-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "hanaro"
+version = "0.0.1"
+description = "A non-invasive `logging` configurator and facilitator."
+keywords = ["logging", "configuration", "appsettings2", "async"]
+authors = [
+    { name="Shaun Wilson", email="mrshaunwilson@msn.com" }
+]
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Intended Audience :: Developers"
+]
+
+[project.urls]
+Documentation = "https://hanaro.readthedocs.io/"
+Homepage = "https://github.com/wilson0x4d/hanaro"
+Repository = "https://github.com/wilson0x4d/hanaro.git"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+exclude = [
+    "docs",
+    "tests",
+    "tests.*",
+    ".scripts",
+    ".gitea",
+    ".venv-*"
+]

hanaro-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+