unclogger 0.2.1__tar.gz

unclogger-0.2.1/.gitignore

@@ -0,0 +1,202 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+BUILD_NUMBER/
+develop-eggs/
+build/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*-coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+test-reports/
+
+# Various testing files
+.mutmut-cache
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+.ipynb
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# lock files
+#   According to pypa/pipenv#598, it is recommended to include the lock file in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+poetry.lock
+requirements.txt
+requirements.in
+pdm.lock
+uv.lock
+
+# other tools
+.pdm-python
+.pdm-build
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# PyCharm stuff
+.idea
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Editor workspace files
+.vscode
+
+.testmondata
+
+# macOS
+.DS_Store
+
+# Docker stuff for local dev
+docker-compose.override.yml
+
+.skip-hooks
+
+tmp/
+.ruff_cache
+
+# run configurations
+.run/
+/.run/
+
+# kube manifest
+helm/baked_manifest.yaml
+
+# local storage
+_storage
+database.json
+
+# localstack cache
+volume/cache

unclogger-0.2.1/.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+   install:
+   - method: pip
+     path: .
+     extra_requirements:
+       - docs

unclogger-0.2.1/CONTRIBUTE.md

@@ -0,0 +1,54 @@
+Contributing Guidelines
+=========
+
+## Development Environment
+
+To manage packaging and dependencies, please [install `uv` first](https://docs.astral.sh/uv/getting-started/installation/).
+
+Tu run development scripts, please [install `just`](https://just.systems/man/en/). To display the list of all `just` commands (a.k.a. recipes), run `just`:
+
+```shell
+$ just
+Available recipes:
+    help       # List available recipes.
+    test       # Run unit tests.
+    test-cov   # Run unit tests with coverage report.
+    lint       # Run linting and formating checks.
+    type       # Run static typing analysis.
+    analyze    # Run security checks.
+    check      # Run all checks.
+    commits    # Extract the latest commits
+    reformat   # Reformat the code using isort and ruff.
+    docs       # Serve documentation website for development purposes.
+    docs-build # Build the documentation website.
+    reqs       # Extract current production requirements. Save to a file by appending `> requirements.txt`.
+```
+
+
+### Development Checks
+
+During development, the command `just check` will execute a number of checks and tests on the library codebase:
+
+* correct dependency declarations using `deptry`
+* code linting check using `ruff`
+* code format check using `ruff format`
+* documentation styling check using `pydocstyle`
+
+The full unit test suite can be executed with `just test`.
+
+
+## API Documentation
+
+The project documentation can then be served locally by running:
+
+```shell
+$ just docs
+```
+
+To build the static documentation site, run:
+
+```shell
+$ just docs-build
+```
+
+This will create the HTML documentation in the `site` directory.

unclogger-0.2.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: unclogger
+Version: 0.2.1
+Summary: Custom wrapper for enhanced structured logging.
+Project-URL: Homepage, https://unclogger.readthedocs.io
+Project-URL: Documentation, https://unclogger.readthedocs.io
+Project-URL: Repository, https://github.com/berislavlopac/unclogger
+Author-email: Berislav Lopac <berislav@lopac.net>
+License: MIT
+Requires-Python: <4.0,>=3.10
+Requires-Dist: structlog>=24.1
+Provides-Extra: clean
+Requires-Dist: sanitary>=0.1.0; extra == 'clean'
+Provides-Extra: docs
+Requires-Dist: jinja2>=3.1.3; extra == 'docs'
+Requires-Dist: mkapi>=1.0.14; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5.4; extra == 'docs'
+Requires-Dist: mkdocs>=1.3.0; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
+Provides-Extra: sanitary
+Requires-Dist: sanitary>=0.1.0; extra == 'sanitary'
+Description-Content-Type: text/markdown
+
+Unclogger
+=========
+
+Simple Python library for customizable structured logging.
+
+[![Documentation Status](https://readthedocs.org/projects/unclogger/badge/?version=latest)](https://unclogger.readthedocs.io/en/latest/?badge=latest)
+
+## Quick Intro
+
+ ```python
+from unclogger import get_logger
+logger = get_logger("test logger")
+logger.info("test test", foo="abc", bar=123)
+```
+
+Output:
+```json
+{
+  "foo": "abc", 
+  "bar": 123, 
+  "event": "test test", 
+  "logger": "test logger", 
+  "level": "info", 
+  "timestamp": "2021-02-12T22:40:07.600385Z"
+}
+```

unclogger-0.2.1/README.md

@@ -0,0 +1,26 @@
+Unclogger
+=========
+
+Simple Python library for customizable structured logging.
+
+[![Documentation Status](https://readthedocs.org/projects/unclogger/badge/?version=latest)](https://unclogger.readthedocs.io/en/latest/?badge=latest)
+
+## Quick Intro
+
+ ```python
+from unclogger import get_logger
+logger = get_logger("test logger")
+logger.info("test test", foo="abc", bar=123)
+```
+
+Output:
+```json
+{
+  "foo": "abc", 
+  "bar": 123, 
+  "event": "test test", 
+  "logger": "test logger", 
+  "level": "info", 
+  "timestamp": "2021-02-12T22:40:07.600385Z"
+}
+```

unclogger-0.2.1/docs/index.md

@@ -0,0 +1,175 @@
+# Introduction
+
+**Unclogger** is a simple library for customisable structured logging. It mirrors the standard Python logging library API, with a few additional functionalities.
+
+!!! Info "Implementation detail"
+
+    Unclogger is using the [Structlog library](https://www.structlog.org) under the hood.
+
+??? Note
+
+    The JSON messages in examples below were formatted for convenience; in practice they are sent as a single line of text.
+
+## Structured Loggers
+
+Unclogger creates a logger object which adds one important functionality on top of the [standard logging library](https://docs.python.org/3/library/logging.html): in addition to a textual log message, any additional values passed to logging methods as keyword arguments will be included to the log context, along with a few standard fields:
+
+* `event`: The original textual log message.
+* `logger`: Name of the logger instance that created the message.
+* `level`: The [log level](https://docs.python.org/3/library/logging.html#logging-levels) of the message.
+* `timestamp`: Time date of the message in ISO 8601 format.
+
+The final logging context will be converted and emitted as a JSON-formatted message.
+
+
+!!! Example
+
+    ```python
+    >>> from unclogger import get_logger
+    >>> logger = get_logger("test logger")
+    >>> logger.info("test test", foo="abc", bar=123)
+    {
+        "foo": "abc", 
+        "bar": 123, 
+        "event": "test test", 
+        "logger": "test logger", 
+        "level": "info", 
+        "timestamp": "2021-02-12T22:40:07.600385Z"
+    }
+    >>>
+    ```
+
+### Configuration
+
+The logger can be configured using the special attribute `config`. This can be used for configuring additional functionality.
+
+!!! Example
+
+    ```python
+    >>> from unclogger import get_logger
+    >>> logger = get_logger("test logger")
+    >>> logger.config.foo = "foo"
+    >>> logger.config.bar = "bar"
+    >>> print(logger.config.foo)
+    foo
+    >>> print(logger.config.bar)
+    foo
+    >>> print(logger.config.baz)
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+    AttributeError: 'types.SimpleNamespace' object has no attribute 'baz'. Did you mean: 'bar'?
+    >>>
+    ```
+
+As can be seen in the error message above, `config` is an instance of [SimpleNamespace](https://docs.python.org/3/library/types.html#types.SimpleNamespace).
+
+
+### Local Context
+
+Each logger has a local context; values can be bound to it so they can appear in any message sent by that logger.
+
+!!! Example
+
+    ```python
+    >>> from unclogger import get_logger
+    >>> logger = get_logger("test logger").bind(abc="def")
+    >>> logger.info("test test", foo="abc", bar=123)
+    {
+        "abc": "def", 
+        "foo": "abc", 
+        "bar": 123, 
+        "event": "test test", 
+        "logger": "test logger", 
+        "level": "info", "timestamp": 
+        "2021-02-12T23:04:11.743922Z"
+    }
+    >>> # let's bind some more
+    >>> import uuid
+    >>> logger = logger.bind(some_uuid=uuid.uuid4())
+    {
+        "abc": "def", 
+        "some_uuid": "88227c28-f5a6-430a-bdee-9e967c6c8d13",
+        "foo": "abc", 
+        "bar": 123, 
+        "event": "test test", 
+        "logger": "test logger", 
+        "level": "info", 
+        "timestamp": "2021-02-12T23:06:15.917766Z"
+    }
+    >>> # let's change a bound value
+    >>> logger = logger.bind(abc="I have a new value now")
+    >>> logger.info("test test", foo="abc", bar=123)
+    {
+        "abc": "I have a new value now",
+        "some_uuid": "88227c28-f5a6-430a-bdee-9e967c6c8d13",
+        "foo": "abc",
+        "bar": 123,
+        "event": "test test",
+        "logger": "test logger",
+        "level": "info",
+        "timestamp": "2021-02-12T23:08:21.768578Z"
+    }
+    >>>
+    ```
+
+
+## Global Context
+
+The [`context_bind`](reference.md#unclogger.context_bind) function will set values in the global context, where they can be used by any logger.
+
+!!! Example
+
+    ```python
+    >>> from unclogger import get_logger, context_bind
+    >>> # binding data before even creating a logger
+    >>> context_bind(abc="def")
+    >>> logger1 = get_logger("test logger 1")
+    >>> logger1.info("test test", foo="abc", bar=123)
+    {
+        "abc": "def", 
+        "foo": "abc", 
+        "bar": 123, 
+        "event": "test test", 
+        "logger": "test logger 1", 
+        "level": "info", 
+        "timestamp": "2021-02-12T22:43:48.062282Z"
+    }
+    >>> logger2 = get_logger("test logger 2")
+    >>> # a different logger can access the same data
+    >>> logger2.info("another message")
+    {
+        "abc": "def", 
+        "event": "another message", 
+        "logger": "test logger 2", 
+        "level": "info", "timestamp": 
+        "2021-02-12T22:45:05.599852Z"
+    }
+    >>>
+    ```
+
+## Custom Processors
+
+It is possible to add other `structlog` processors into the logger configuration. For example, to hide sensitive information that might be present in the logged data (using the [Sanitary](https://sanitary.readthedocs.io) library as an example):
+
+!!! Example
+
+    ```python
+    >>> from sanitary import StructlogSanitizer
+    >>> from unclogger import add_processors, get_logger
+    >>>
+    >>> add_processors(StructlogSanitizer(keys={"password", "email"}))
+    >>>
+    >>> logger = get_logger("test logger")
+    >>> logger.info("test test", foo="abc", email="test@example.com", password="myPa55w0rd")
+    {
+        "foo": "abc", 
+        "email": "********",
+        "password": "********",
+        "event": "test test", 
+        "logger": "test logger", 
+        "level": "info", 
+        "timestamp": "2021-02-12T22:40:07.600385Z"
+    }
+    >>>
+    ```
+

unclogger-0.2.1/docs/reference.md

@@ -0,0 +1,41 @@
+# API Reference
+
+## Logger
+
+::: unclogger.get_logger
+
+::: unclogger.context_bind
+
+## Global Log Level Configuration
+
+??? Example
+
+    ```python
+    >>> from unclogger import get_logger, set_level
+    >>> logger = get_logger("test logger")
+    >>> logger.info("bar")
+    {
+        "event": "bar",
+        "logger": "test logger",
+        "level": "info",
+        "timestamp": "2021-02-18T21:59:40.102272Z"
+    }
+    >>> logger.debug("bar")
+    >>> set_level("debug")
+    >>> logger.debug("bar")
+    {
+        "event": "bar",
+        "logger": "test logger",
+        "level": "debug",
+        "timestamp": "2021-02-18T22:00:09.147106Z"
+    }
+    >>> set_level("warning")
+    >>> logger.info("bar")
+    >>>
+    ```
+
+::: unclogger.set_level
+
+## Custom Processors
+
+::: unclogger.processors.add_processors

unclogger-0.2.1/justfile

@@ -0,0 +1,52 @@
+# List available recipes.
+help:
+    @just --list --unsorted
+
+# Run unit tests.
+test:
+    uv run --all-extras pytest --spec
+
+# Run unit tests with coverage report.
+test-cov:
+    uv run --all-extras pytest --cov --spec
+
+# Run linting and formating checks.
+lint:
+    uv run deptry .
+    uv run ruff format --check .
+    uv run ruff check .
+    uv run pydocstyle unclogger/
+
+# Run static typing analysis.
+type:
+    uv run mypy --install-types --non-interactive unclogger/
+
+# Run security checks.
+analyze:
+    uvx vulture --min-confidence 100 unclogger/
+    uvx radon mi --show --multi --min B unclogger/
+
+# Run all checks.
+check: lint type analyze
+
+# Extract the latest commits
+commits:
+    git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-decorate
+
+# Reformat the code using isort and ruff.
+[confirm]
+reformat:
+    uv run ruff format .
+    uv run ruff check --select I --fix .
+
+# Serve documentation website for development purposes.
+docs:
+    uv run --extra docs mkdocs serve
+
+# Build the documentation website.
+docs-build:
+    uv run --extra docs mkdocs build
+
+# Extract current production requirements. Save to a file by appending `> requirements.txt`.
+reqs:
+    uv export --no-default-groups

unclogger-0.2.1/mkdocs.yml

@@ -0,0 +1,50 @@
+site_name: Unclogger
+repo_url: https://github.com/berislavlopac/unclogger
+site_description: Simple library for customisable structured logging.
+site_author: Berislav Lopac <berislav@lopac.net>
+use_directory_urls: false
+theme:
+  name: material
+  logo: assets/plunger-logo.png
+  favicon: assets/plunger-favicon.png
+  features:
+    - search.suggest
+  palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
+plugins:
+  - search
+  - mkapi
+markdown_extensions:
+  - abbr
+  - attr_list
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      permalink: yes
+  - codehilite:
+      guess_lang: no
+nav:
+  - index.md
+  - reference.md