mh_structlog 0.0.40__tar.gz

mh_structlog-0.0.40/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: mh_structlog
+Version: 0.0.40
+Summary: Some Structlog configuration and wrappers to easily use structlog.
+Author: Mathieu Hinderyckx
+Author-email: Mathieu Hinderyckx <mathieu.hinderyckx@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: orjson>=3.11.5
+Requires-Dist: rich>=14.0.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: structlog-sentry>=2.2.1
+Requires-Dist: django>=5.0 ; extra == 'django'
+Requires-Python: >=3.11
+Provides-Extra: django
+Description-Content-Type: text/markdown
+
+# MH-Structlog
+
+This package is used to setup the python logging system in combination with structlog. It configures both structlog and the standard library logging module, so your code can either use a structlog logger (which is recommended) or keep working with the standard logging library. This way all third-party packages that are producing logs (which use the stdlib logging module) will follow your logging setup and you will always output structured logging.
+
+It is a fairly opinionated setup but has some configuration options to influence the behaviour. The two output log formats are either pretty-printing (for interactive views) or json. It includes optional reporting to Sentry, and can also log to a file.
+
+## Usage
+
+This library should behave mostly as a drop-in import instead of the logging library import.
+
+So instead of
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.info('hey')
+```
+
+you can do
+
+```python
+import mh_structlog as logging
+logging.setup()  # necessary once at program startup, see readme further below
+
+logger = logging.getLogger(__name__)
+
+logger.info('hey')
+```
+
+One big advantage of using the structlog logger over de stdlib logging one, is that you can pass arbitrary keyword arguments to our loggers when producing logs. E.g.
+
+```python
+import mh_structlog as logging
+
+logger = logging.getLogger(__name__)
+
+logger.info('some message', hey='ho', a_list=[1,2,3])
+```
+
+These extra key-value pairs will be included in the produced logs; either pretty-printed to the console or as data in the json entries.
+
+## Configuration via `setup()`
+
+To configure your logging, call the `setup` function, which should be called once as early as possible in your program execution. This function configures all loggers.
+
+```python
+import mh_structlog as logging
+
+logging.setup()
+```
+
+This will work out of the box with sane defaults: it logs to stdout in a pretty colored output when running in an interactive terminal, else it defaults to producing json output. See the next section for information on the arguments to this method.
+
+### Configuration options
+
+For a setup which logs everything to the console in a pretty (colored) output, simply do:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+)
+
+getLogger().info('hey')
+```
+
+To log as json:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='json',
+)
+
+getLogger().info('hey')
+```
+
+To filter everything out up to a certain level:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+    global_filter_level=WARNING,
+)
+
+getLogger().info('hey')  # this does not get printed
+getLogger().error('hey')  # this does get printed
+```
+
+To write logs to a file additionally (next to stdout):
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+    log_file='myfile.log',
+)
+
+getLogger().info('hey')
+```
+
+To silence specific named loggers specifically (instead of setting the log level globally, it can be done per named logger):
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+    logging_configs=[
+        filter_named_logger('some_named_logger', WARNING),
+    ],
+)
+
+getLogger('some_named_logger').info('hey')  # does not get logged
+getLogger('some_named_logger').warning('hey')  # does get logged
+
+getLogger('some_other_named_logger').info('hey')  # does get logged
+getLogger('some_other_named_logger').warning('hey')  # does get logged
+```
+
+To include the source information about where a log was produced:
+
+```python
+from mh_structlog import *
+
+setup(
+    include_source_location=True
+)
+
+getLogger().info('hey')
+```
+
+To choose how many frames you want to include in stacktraces on logging exceptions:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='json',
+    max_frames=3,
+)
+
+try:
+    5 / 0
+except Exception as e:
+    getLogger().exception(e)
+```
+
+To enable Sentry integration, pass a dict with a config according to the arguments which [structlog-sentry](https://github.com/kiwicom/structlog-sentry?tab=readme-ov-file#usage) allows to the setup function:
+
+```python
+from mh_structlog import *
+import sentry_sdk
+
+config = {'dsn': '1234'}
+sentry_sdk.init(dsn=config['dsn'])
+
+setup(
+    sentry_config={'event_level': WARNING}  # pass everything starting from WARNING level to Sentry
+)
+
+```

mh_structlog-0.0.40/README.md

@@ -0,0 +1,169 @@
+# MH-Structlog
+
+This package is used to setup the python logging system in combination with structlog. It configures both structlog and the standard library logging module, so your code can either use a structlog logger (which is recommended) or keep working with the standard logging library. This way all third-party packages that are producing logs (which use the stdlib logging module) will follow your logging setup and you will always output structured logging.
+
+It is a fairly opinionated setup but has some configuration options to influence the behaviour. The two output log formats are either pretty-printing (for interactive views) or json. It includes optional reporting to Sentry, and can also log to a file.
+
+## Usage
+
+This library should behave mostly as a drop-in import instead of the logging library import.
+
+So instead of
+
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+logger.info('hey')
+```
+
+you can do
+
+```python
+import mh_structlog as logging
+logging.setup()  # necessary once at program startup, see readme further below
+
+logger = logging.getLogger(__name__)
+
+logger.info('hey')
+```
+
+One big advantage of using the structlog logger over de stdlib logging one, is that you can pass arbitrary keyword arguments to our loggers when producing logs. E.g.
+
+```python
+import mh_structlog as logging
+
+logger = logging.getLogger(__name__)
+
+logger.info('some message', hey='ho', a_list=[1,2,3])
+```
+
+These extra key-value pairs will be included in the produced logs; either pretty-printed to the console or as data in the json entries.
+
+## Configuration via `setup()`
+
+To configure your logging, call the `setup` function, which should be called once as early as possible in your program execution. This function configures all loggers.
+
+```python
+import mh_structlog as logging
+
+logging.setup()
+```
+
+This will work out of the box with sane defaults: it logs to stdout in a pretty colored output when running in an interactive terminal, else it defaults to producing json output. See the next section for information on the arguments to this method.
+
+### Configuration options
+
+For a setup which logs everything to the console in a pretty (colored) output, simply do:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+)
+
+getLogger().info('hey')
+```
+
+To log as json:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='json',
+)
+
+getLogger().info('hey')
+```
+
+To filter everything out up to a certain level:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+    global_filter_level=WARNING,
+)
+
+getLogger().info('hey')  # this does not get printed
+getLogger().error('hey')  # this does get printed
+```
+
+To write logs to a file additionally (next to stdout):
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+    log_file='myfile.log',
+)
+
+getLogger().info('hey')
+```
+
+To silence specific named loggers specifically (instead of setting the log level globally, it can be done per named logger):
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='console',
+    logging_configs=[
+        filter_named_logger('some_named_logger', WARNING),
+    ],
+)
+
+getLogger('some_named_logger').info('hey')  # does not get logged
+getLogger('some_named_logger').warning('hey')  # does get logged
+
+getLogger('some_other_named_logger').info('hey')  # does get logged
+getLogger('some_other_named_logger').warning('hey')  # does get logged
+```
+
+To include the source information about where a log was produced:
+
+```python
+from mh_structlog import *
+
+setup(
+    include_source_location=True
+)
+
+getLogger().info('hey')
+```
+
+To choose how many frames you want to include in stacktraces on logging exceptions:
+
+```python
+from mh_structlog import *
+
+setup(
+    log_format='json',
+    max_frames=3,
+)
+
+try:
+    5 / 0
+except Exception as e:
+    getLogger().exception(e)
+```
+
+To enable Sentry integration, pass a dict with a config according to the arguments which [structlog-sentry](https://github.com/kiwicom/structlog-sentry?tab=readme-ov-file#usage) allows to the setup function:
+
+```python
+from mh_structlog import *
+import sentry_sdk
+
+config = {'dsn': '1234'}
+sentry_sdk.init(dsn=config['dsn'])
+
+setup(
+    sentry_config={'event_level': WARNING}  # pass everything starting from WARNING level to Sentry
+)
+
+```

mh_structlog-0.0.40/pyproject.toml

@@ -0,0 +1,316 @@
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "mh_structlog"
+authors = [
+    { name = "Mathieu Hinderyckx", email = "mathieu.hinderyckx@gmail.com" },
+]
+description = "Some Structlog configuration and wrappers to easily use structlog."
+version = "0.0.40"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "orjson>=3.11.5",
+    "rich>=14.0.0",
+    "structlog>=25.5.0",
+    "structlog-sentry>=2.2.1",
+]
+[project.optional-dependencies]
+django = [
+    "django>=5.0",
+]
+
+[tool.setuptools_scm]
+version_file = "src/mh_structlog/_version.py"
+
+[dependency-groups]
+dev = ["ipdb>=0.13.13", "ipython>=8.18.1", "pre-commit>=4.0.1", "ruff>=0.12.1"]
+tests = [
+    "coverage>=7.5.3",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pytest-django>=4.11.1",
+    "pytest-env>=1.2.0",
+    "pytest-randomly>=3.15.0",
+    "pytest-sugar>=1.1.1",
+    "django>=5.2",
+    "freezegun>=1.5.5",
+]
+pages = [
+    "black>=24.10.0",
+    "mkdocs-literate-nav>=0.6.1",
+    "mkdocs-gen-files>=0.5.0",
+    "mkdocstrings[python]>=0.26.2",
+    "pymdown-extensions>=10.12",
+    "mkdocs-include-dir-to-nav>=1.2.0",
+    "mkdocs-git-authors-plugin>=0.9.2",
+    "mkdocs-glightbox>=0.4.0",
+    "mkdocs-git-revision-date-localized-plugin>=1.3.0",
+    "mkdocs-roamlinks-plugin>=0.3.2",
+    "mkdocs>=1.6.1",
+    "mkdocs-material>=9.5.44",
+]
+
+[tool.uv]
+required-version = ">=0.9.11"
+package = true
+cache-keys = [{ file = "pyproject.toml" }]
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'",
+]
+
+# ==== ruff ====
+[tool.ruff]
+line-length = 120
+indent-width = 4
+preview = false
+required-version = ">=0.4.5"
+target-version = "py39"
+unsafe-fixes = true
+
+# Overwritten in CI/CD
+output-format = "full"
+fix = true
+
+[tool.ruff.lint]
+preview = true
+select = [
+    # https://docs.astral.sh/ruff/rules/#rules
+    "A",
+    "AIR",
+    "ANN",
+    "ARG",
+    "ASYNC",
+    "B",
+    "BLE",
+    "C4",
+    "C90",
+    "COM",
+    # "D",
+    "DJ",
+    "DOC",
+    "DTZ",
+    "E",
+    "EM",
+    "EXE",
+    "F",
+    "FA",
+    "FBT",
+    "FLY",
+    "FURB",
+    "G",
+    "I",
+    "ICN",
+    "INP",
+    "INT",
+    "ISC",
+    "LOG",
+    "N",
+    "NPY",
+    "PD",
+    "PERF",
+    "PGH",
+    "PIE",
+    "PL",
+    "PT",
+    "PTH",
+    "PYI",
+    "Q",
+    "R",
+    "RET",
+    "RSE",
+    "RUF",
+    "S",
+    "SIM",
+    "SLF",
+    "SLOT",
+    "T10",
+    "T20",
+    "TC",
+    "TID",
+    "TRY",
+    "UP",
+    "YTT",
+    # "ERA",   # commented out code; not always best to have it removed forcefully, sometimes want to keep
+]
+
+ignore = [
+    "ANN002",  # Missing type annotations for *args
+    "ANN003",  # Missing type annotations for **kwargs
+    "ANN204",  # Missing return type annotation for special method `__init__`
+    "ANN401",  # Disallow Any type hints
+    "COM812",  # Trailing comma missing. The ruff format always removes this on e.g. a list of function arguments.
+    "D100",    # Missing docstring in public module
+    "D105",    # Missing docstring in magic method
+    "D106",    # Missing docstring in public nested class
+    "D202",    # No blank line after function docstring
+    "E501",    # Line too long
+    "EM101",   # Exception must not use a string literal, assign to variable first
+    "EM102",   # Exception must not use an f-string literal, assign to variable first
+    "ISC001",  # Conflicting with formatter
+    "PD011",   # pandas-use-of-dot-values. Ignored because it gives a lot of false positives every time .values is used on something.
+    "Q000",    # Single quotes found but double quotes preferred
+    "RUF012",  # mutable-class-default. Class attributes would required type annotations everywhere if enabled.
+    "TRY002",  # Create your own exception
+    "TRY003",  # Avoid specifying long messages outside the exception class
+    "PGH003",  # Require specific codes when silencing linting.
+    "FBT001",  # Boolean arguments in function calls
+    "FBT002",  # Boolean arguments in function calls
+    "RUF100",  # Report unused noqa directives. This clashes with the leniency from the ignore above this one.
+    "DOC501",  # Raised exception {id} missing from docstring
+    "PLR6301", # Not using self in a method
+    "DOC201",  # Not mentioning 'return' explicitly in a docstring
+    "A005",    # Module name is shadowing a python builtin module
+]
+
+# Allow fix for all enabled rules (when `--fix`) is provided.
+fixable = ["ALL"]
+unfixable = ["T201"]
+
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+preview = false
+line-ending = "auto"
+indent-style = "space"
+quote-style = "preserve"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+exclude = ["*.pyi", "__pypackages__/", ".venv/", "env/", "venv/", ".git/", ".hg/", ".mypy_cache/", ".tox/", ".nox/", ".pytest_cache/", ".ruff_cache/"]
+
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = true
+
+# 4. Ignore `E402` (import violations) in all `__init__.py` files, and in select subdirectories.
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["E402", "D104", "F403"]
+"**/{tests,docs,tools}/*" = [
+    "ANN201",
+    "ARG001",
+    "ARG002",
+    "D101",
+    "D102",
+    "D103",
+    "DOC402",
+    "DJ008",
+    "E402",
+    "PLC2701",
+    "PLR0914",
+    "PLR0915",
+    "PLR2004",
+    "S101",
+    "S105",
+    "S311",
+    "SLF001",
+]
+"test*.py" = [
+    "ANN201",
+    "ARG001",
+    "ARG002",
+    "D101",
+    "D102",
+    "D103",
+    "DOC402",
+    "DJ008",
+    "E402",
+    "PLC2701",
+    "PLR0914",
+    "PLR0915",
+    "PLR2004",
+    "S101",
+    "S105",
+    "S311",
+    "SLF001",
+]
+
+[tool.ruff.lint.pylint]
+max-args = 20
+max-positional-args = 20
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "double"
+avoid-escape = true
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+ignore-fully-untyped = true     # allows for gradual typing
+suppress-none-returning = false
+
+[tool.ruff.lint.flake8-unused-arguments]
+ignore-variadic-names = true
+
+[tool.ruff.lint.isort]
+force-single-line = false
+combine-as-imports = true
+force-wrap-aliases = false
+detect-same-package = true
+split-on-trailing-comma = false
+known-local-folder = ["src"]
+lines-after-imports = 2
+
+# ==== pytest ====
+[tool.pytest_env]
+ENVIRONMENT = "test"
+COLOR = 1
+
+[tool.pytest]
+addopts = ["-s", "--durations=5", "-v", "--import-mode=importlib", "--cov", "--cov-report=term", "--cov-report=html", "--cov-report=xml", "--junit-xml=junit.xml"]
+
+junit_family = 'xunit2'
+junit_suite_name = "test_suite"
+junit_logging = 'all'
+junit_log_passing_tests = true
+junit_duration_report = "call"
+
+python_files = ["*/tests.py", "*/test_*.py", "*/tests_*.py", "*/*.py"]
+testpaths = ["tests", "src"]
+
+filterwarnings = [
+    "ignore::DeprecationWarning",
+    "ignore::PendingDeprecationWarning",
+]
+
+# ==== Coverage ====
+[tool.coverage.run]
+omit = [
+    "*/migrations/*",
+    "*/media/*",
+    ".venv/*",
+    "terraform/*",
+    "htmlcov/*",
+    "staticfiles/*",
+    "requirements/*",
+    "manage.py",
+    "asgi.py",
+    "wsgi.py",
+    "*/.vscode/*",
+]
+plugins = []
+branch = true
+
+[tool.coverage.report]
+format = "text"
+skip_empty = false
+precision = 2
+
+[tool.coverage.term]
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[tool.coverage.xml]
+output = "coverage.xml"

mh_structlog-0.0.40/src/mh_structlog/__init__.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from logging import CRITICAL, DEBUG, ERROR, FATAL, INFO, WARN, WARNING
+
+import structlog
+
+from .config import filter_named_logger, setup
+from .utils import determine_name_for_logger
+
+
+def getLogger(name: str | None = None):  # noqa: ANN201, N802
+    """Return a named logger."""
+    if name is None:
+        name = determine_name_for_logger()
+    return structlog.get_logger(name)
+
+
+def get_logger(name: str | None = None):  # noqa: ANN201
+    """Return a named logger."""
+    return getLogger(name)
+
+
+__all__ = [
+    "CRITICAL",
+    "DEBUG",
+    "ERROR",
+    "FATAL",
+    "INFO",
+    "WARN",
+    "WARNING",
+    "filter_named_logger",
+    "getLogger",
+    "getLogger",
+    "get_logger",
+    "get_logger",
+    "setup",
+]

mh_structlog-0.0.40/src/mh_structlog/config.py

@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+import logging  # noqa: I001
+import logging.config
+import sys
+from pathlib import Path
+from typing import Literal
+
+import structlog
+from structlog.dev import RichTracebackFormatter
+from structlog.processors import CallsiteParameter
+
+from . import processors
+
+
+SELECTED_LOG_FORMAT = 'console'
+
+
+class StructlogLoggingConfigExceptionError(Exception):
+    """Exception to raise if the config is not correct."""
+
+
+def setup(  # noqa: PLR0912, PLR0915, C901
+    log_format: Literal["console", "json", "gcp_json"] | None = None,
+    logging_configs: list[dict] | None = None,
+    include_source_location: bool = False,  # noqa: FBT001, FBT002
+    global_filter_level: int | None = None,
+    log_file: str | Path | None = None,
+    log_file_format: Literal["console", "json"] | None = None,
+    testing_mode: bool = False,  # noqa: FBT001, FBT002
+    max_frames: int = 100,
+    sentry_config: dict | None = None,
+) -> None:
+    """This method configures structlog and the standard library logging module."""
+    global SELECTED_LOG_FORMAT  # noqa: PLW0603
+
+    # Unless we are in testing mode, don't configure logging if it was already configured.
+    # During testing, we need te flexibility to configure logging multiple times.
+    if structlog.is_configured() and not testing_mode:
+        from logging import getLogger  # noqa: PLC0415
+
+        getLogger('mh_structlog').warning('logging was already configured, so I return and do nothing.')
+        return
+
+    shared_processors = [
+        structlog.stdlib.add_logger_name,  # add the logger name
+        structlog.stdlib.add_log_level,  # add the log level as textual representation
+        structlog.processors.TimeStamper(fmt="iso", utc=True),  # add a timestamp
+        structlog.contextvars.merge_contextvars,  # add variables and bound data from global context
+    ]
+
+    if max_frames <= 0:
+        raise StructlogLoggingConfigExceptionError("max_frames should be a positive integer.")
+
+    # Configure stdout formatter
+    if log_format is None:
+        log_format = "console" if sys.stdout.isatty() else "json"
+    if log_format not in {"console", "json", "gcp_json"}:
+        raise StructlogLoggingConfigExceptionError("Unknown logging format requested.")
+
+    SELECTED_LOG_FORMAT = log_format
+
+    if sentry_config and sentry_config.get('active', True):
+        # By default, ignore our own request access logger (which is only used when you use the Django access logger from this package in your project).
+        # When a request errors, there are normally other exceptions that show up in Sentry for it; adding the
+        # access log at the end only results in a duplicate event.
+        #
+        # When you specify ignore_loggers manually, it is not ignored anymore, so you should add it yourself (when wanted).
+        sentry_config.setdefault('ignore_loggers', ['mh_structlog.django.access'])
+        shared_processors.append(processors.SentryProcessor(**sentry_config))
+    else:
+        # In case logging statements add sentry_skip, but Sentry isn't configured at all, we do not want to output that key.
+        shared_processors.append(processors.FieldDropper(['sentry_skip']))
+
+    if log_format == "console":
+        selected_formatter = "mh_structlog_colored"
+    elif log_format in {"json", "gcp_json"}:
+        shared_processors.extend(
+            [structlog.processors.dict_tracebacks, processors.CapExceptionFrames(max_frames=2 * max_frames)]
+        )
+        selected_formatter = "mh_structlog_json"
+
+    if include_source_location:
+        shared_processors.append(
+            structlog.processors.CallsiteParameterAdder(
+                parameters={CallsiteParameter.PATHNAME, CallsiteParameter.LINENO, CallsiteParameter.FUNC_NAME}
+            )
+        )
+
+    wrapper_class = structlog.stdlib.BoundLogger
+    if global_filter_level is not None:
+        wrapper_class = structlog.make_filtering_bound_logger(global_filter_level)
+
+    # Structlog configuration
+    structlog.configure(
+        processors=[
+            *shared_processors,
+            structlog.stdlib.filter_by_level,  # filter based on the stdlib logging config
+            structlog.stdlib.PositionalArgumentsFormatter(),  # Allow string formatting with positional arguments in log calls
+            structlog.processors.StackInfoRenderer(
+                additional_ignores=['mh_structlog']
+            ),  # when you create a log and specify stack_info=True, add a stacktrace to the log
+            structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+        ],
+        logger_factory=structlog.stdlib.LoggerFactory(),
+        wrapper_class=wrapper_class,
+        cache_logger_on_first_use=not testing_mode,  # https://www.structlog.org/en/stable/testing.html#testing
+    )
+
+    # Std lib logging configuration.
+    stdlib_logging_config = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "mh_structlog_plain": {
+                "()": structlog.stdlib.ProcessorFormatter,
+                "processors": [
+                    processors.add_flattened_extra,  # extract the content of 'extra' and add it as entries in the event dict
+                    structlog.stdlib.ProcessorFormatter.remove_processors_meta,  # remove some fields used by structlogs internal logic
+                    structlog.processors.EventRenamer("message"),
+                    structlog.dev.ConsoleRenderer(
+                        colors=False,
+                        force_colors=False,
+                        pad_event_to=80,
+                        sort_keys=True,
+                        event_key="message",
+                        exception_formatter=RichTracebackFormatter(
+                            width=None, max_frames=max_frames, show_locals=True, locals_hide_dunder=True
+                        ),
+                    ),
+                ],
+                "foreign_pre_chain": shared_processors,
+            },
+            "mh_structlog_colored": {
+                "()": structlog.stdlib.ProcessorFormatter,
+                "processors": [
+                    processors.add_flattened_extra,  # extract the content of 'extra' and add it as entries in the event dict
+                    structlog.stdlib.ProcessorFormatter.remove_processors_meta,  # remove some fields used by structlogs internal logic
+                    structlog.processors.EventRenamer("message"),
+                    structlog.dev.ConsoleRenderer(
+                        colors=True,
+                        pad_event_to=80,
+                        sort_keys=True,
+                        event_key="message",
+                        exception_formatter=RichTracebackFormatter(
+                            width=None, max_frames=max_frames, show_locals=True, locals_hide_dunder=True
+                        ),
+                    ),
+                ],
+                "foreign_pre_chain": shared_processors,
+            },
+            "mh_structlog_json": {
+                "()": structlog.stdlib.ProcessorFormatter,
+                "processors": [
+                    processors.add_flattened_extra,  # extract the content of 'extra' and add it as entries in the event dict
+                    structlog.stdlib.ProcessorFormatter.remove_processors_meta,  # remove some fields used by structlogs internal logic
+                    structlog.processors.EventRenamer("message"),
+                    processors.FieldRenamer(
+                        log_format == 'gcp_json', 'level', 'severity'
+                    ),  # rename the level field for GCP
+                    processors.render_orjson,
+                ],
+                "foreign_pre_chain": shared_processors,
+            },
+        },
+        "filters": {},
+        "handlers": {
+            "mh_structlog_stdout": {
+                "level": "DEBUG" if global_filter_level is None else logging.getLevelName(global_filter_level),
+                "class": "logging.StreamHandler",
+                "stream": "ext://sys.stdout",
+                "formatter": selected_formatter,
+            }
+        },
+        "loggers": {
+            "": {
+                "handlers": ["mh_structlog_stdout"],
+                "level": "DEBUG" if global_filter_level is None else logging.getLevelName(global_filter_level),
+                "propagate": True,
+            },
+            "stdout": {
+                "handlers": ["mh_structlog_stdout"],
+                "level": "DEBUG" if global_filter_level is None else logging.getLevelName(global_filter_level),
+                "propagate": False,
+            },
+        },
+    }
+
+    # Add a handler to output to a file
+    if log_file:
+        # Select formatter
+        if log_file_format is None:
+            log_file_format = "console" if sys.stdout.isatty() else "json"
+        if log_file_format not in {"console", "json"}:
+            raise StructlogLoggingConfigExceptionError("Unknown logging format requested.")
+
+        if log_file_format == "console":
+            selected_file_formatter = "mh_structlog_plain"
+        elif log_file_format == "json":
+            selected_file_formatter = "mh_structlog_json"
+
+        log_file = Path(log_file)
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Add a handler with file output to the root logger
+        stdlib_logging_config['handlers']['mh_structlog_file'] = {
+            "level": "DEBUG" if global_filter_level is None else logging.getLevelName(global_filter_level),
+            "class": "logging.FileHandler",
+            "formatter": selected_file_formatter,
+            'filename': str(log_file.resolve()),
+        }
+        stdlib_logging_config['loggers']['']['handlers'].append('mh_structlog_file')
+        # Add a named logger to log to the file only (the root logger logs to both stdout and file)
+        stdlib_logging_config['loggers']['file'] = {
+            "handlers": ["mh_structlog_file"],
+            "level": "DEBUG" if global_filter_level is None else logging.getLevelName(global_filter_level),
+            "propagate": False,
+        }
+
+    # Merge in additional logging configs that were passed in by the caller.
+    if logging_configs:
+        for lc in logging_configs:
+            for k, v in lc.get("loggers", {}).items():
+                if k in {"", "root"}:
+                    raise StructlogLoggingConfigExceptionError(
+                        "It is not allowed to specify a custom root logger, since structlog configures that one."
+                    )
+                # Add our handler if none was specified explicitly
+                if "handlers" not in v:
+                    v["handlers"] = ["mh_structlog_stdout"]
+                    if log_file:
+                        v['handlers'].append('mh_structlog_file')
+                if "level" not in v:
+                    v["level"] = "DEBUG" if global_filter_level is None else logging.getLevelName(global_filter_level)
+                    v["propagate"] = False
+                stdlib_logging_config["loggers"][k] = v
+            for k, v in lc.get("handlers", {}).items():
+                # Set the formatter to ours if none was specified explicitly
+                if "formatter" not in v:
+                    # If we are logging to a file and we do not do json format, use the non-colored formatter
+                    if "file" in v["class"].lower() and selected_formatter == "mh_structlog_colored":
+                        v["formatter"] = "mh_structlog_plain"
+                    else:
+                        v["formatter"] = selected_formatter
+                stdlib_logging_config["handlers"][k] = v
+            for k, v in lc.get("formatters", {}).items():
+                if k in {"mh_structlog_plain", "mh_structlog_colored", "mh_structlog_json"}:
+                    raise StructlogLoggingConfigExceptionError(
+                        f"It is not allowed to specify a formatter with the name {k}, since structlog configures that one."
+                    )
+                stdlib_logging_config["formatters"][k] = v
+            for k, v in lc.get("filters", {}).items():
+                stdlib_logging_config["filters"][k] = v
+
+    logging.config.dictConfig(stdlib_logging_config)
+
+
+def filter_named_logger(logger_name: str, level: int) -> dict:
+    """Return a dict containing a configuration for a named logger with a certain level filter.
+
+    Use this to silence a named logger by passing this config to the setup() method.
+    """
+    # fmt: off
+    return {
+        "loggers": {
+            logger_name: {
+                "level": level,
+                "propagate": False,
+            },
+        }
+    }
+    # fmt: on

mh_structlog-0.0.40/src/mh_structlog/django.py

@@ -0,0 +1,80 @@
+import time
+
+import structlog
+from asgiref.sync import iscoroutinefunction
+from django.http import HttpRequest, HttpResponse
+from django.utils.decorators import sync_and_async_middleware
+
+from mh_structlog.config import SELECTED_LOG_FORMAT  # noqa: PLC0415
+
+
+logger = structlog.getLogger("mh_structlog.django.access")
+
+
+def get_fields_to_log(request: HttpRequest, response: HttpResponse, latency_ms: int) -> dict:
+    """Extracts fields to log from the request object."""
+
+    fields_to_log = {'latency_ms': latency_ms, 'method': request.method, 'status': response.status_code}
+
+    if SELECTED_LOG_FORMAT == 'gcp_json':
+        fields_to_log['httpRequest'] = {
+            'requestMethod': request.method,
+            'requestUrl': request.build_absolute_uri(),
+            'status': response.status_code,
+            'latency': f"{latency_ms / 1000}s",
+            "userAgent": request.headers.get('User-Agent', ''),
+            "responseSize": str(response.headers.get('Content-Length', 0)),
+        }
+
+    return fields_to_log
+
+
+@sync_and_async_middleware
+def StructLogAccessLoggingMiddleware(get_response):  # noqa: N802
+    """Middleware that logs access requests with some extra fields as structured logs."""
+
+    if iscoroutinefunction(get_response):
+
+        async def middleware(request):
+            start = time.time()
+            response = await get_response(request)
+            end = time.time()
+
+            latency_ms = int(1000 * (end - start))
+            fields_to_log = get_fields_to_log(request, response, latency_ms)
+
+            # in case Sentry is enabled, prevent logging to it.
+            # The actual exception will be logged if necessary somewhere else, but the response access log to the client should not be on there.
+
+            if response.status_code >= 500:  # noqa: PLR2004
+                await logger.aerror(request.get_full_path(), sentry_skip=True, **fields_to_log)
+            elif response.status_code >= 400:  # noqa: PLR2004
+                await logger.awarning(request.get_full_path(), sentry_skip=True, **fields_to_log)
+            else:
+                await logger.ainfo(request.get_full_path(), **fields_to_log)
+
+            return response
+
+    else:
+
+        def middleware(request):
+            start = time.time()
+            response = get_response(request)
+            end = time.time()
+
+            latency_ms = int(1000 * (end - start))
+            fields_to_log = get_fields_to_log(request, response, latency_ms)
+
+            # in case Sentry is enabled, prevent logging to it.
+            # The actual exception will be logged if necessary somewhere else, but the response access log to the client should not be on there.
+
+            if response.status_code >= 500:  # noqa: PLR2004
+                logger.error(request.get_full_path(), sentry_skip=True, **fields_to_log)
+            elif response.status_code >= 400:  # noqa: PLR2004
+                logger.warning(request.get_full_path(), sentry_skip=True, **fields_to_log)
+            else:
+                logger.info(request.get_full_path(), **fields_to_log)
+
+            return response
+
+    return middleware

mh_structlog-0.0.40/src/mh_structlog/processors.py

@@ -0,0 +1,106 @@
+import logging
+
+import orjson
+import structlog
+from structlog.processors import CallsiteParameter
+from structlog.typing import EventDict
+from structlog_sentry import SentryProcessor as _SentryProcessor
+
+
+# Inspect a default logging library record so we can find out which keys on a LogRecord are 'extra' and not default ones.
+_LOG_RECORD_KEYS = set(logging.LogRecord("name", 0, "pathname", 0, "msg", (), None).__dict__.keys())
+
+
+def add_flattened_extra(_, __, event_dict: dict) -> dict:  # noqa: ANN001
+    """Include the content of 'extra' in the output log, flattened the attributes."""
+    if event_dict.get("_from_structlog"):
+        # Coming from structlog logging call
+        extra = event_dict.pop("extra", {})
+        event_dict.update(extra)
+    else:
+        # Coming from standard logging call
+        record = event_dict.get("_record")
+        if record is not None:
+            event_dict.update({k: v for k, v in record.__dict__.items() if k not in _LOG_RECORD_KEYS})
+
+    return event_dict
+
+
+def _merge_pathname_lineno_function_to_location(logger: structlog.BoundLogger, name: str, event_dict: dict) -> dict:  # noqa: ARG001
+    """Add the source of the log as a single attribute."""
+    pathname = event_dict.pop(CallsiteParameter.PATHNAME.value, None)
+    lineno = event_dict.pop(CallsiteParameter.LINENO.value, None)
+    func_name = event_dict.pop(CallsiteParameter.FUNC_NAME.value, None)
+    event_dict["location"] = f"{pathname}:{lineno}({func_name})"
+    return event_dict
+
+
+def render_orjson(logger: structlog.BoundLogger, name: str, event_dict: dict) -> str:  # noqa: ARG001
+    """Render the event_dict as a json string using orjson."""
+    return orjson.dumps(event_dict, default=repr).decode()
+
+
+class FieldDropper:
+    """Drop fields from the event dict if present."""
+
+    def __init__(self, fields: list):  # noqa: D107
+        self.fields = fields
+
+    def __call__(self, logger: logging.Logger, name: str, event_dict: EventDict) -> EventDict:  # noqa: D102,ARG001,ARG002
+        for field in self.fields:
+            event_dict.pop(field, None)
+        return event_dict
+
+
+class FieldRenamer:
+    """Rename fields in the event dict."""
+
+    def __init__(self, enable: bool, name_from: str, name_to: str):  # noqa: D107
+        self.enable = enable
+        self.name_from = name_from
+        self.name_to = name_to
+
+    def __call__(self, logger: logging.Logger, name: str, event_dict: EventDict) -> EventDict:  # noqa: D102,ARG001,ARG002
+        if self.enable and self.name_from in event_dict:
+            event_dict[self.name_to] = event_dict.pop(self.name_from)
+
+        return event_dict
+
+
+class CapExceptionFrames:
+    """Limit the number of frames in the exception traceback.
+
+    With the builtin ConsoleRenderer, this can be given as argument (max_frames), but not when dict_tracebacks is used.
+    """
+
+    def __init__(self, max_frames: int):
+        """Set the max number of frames to keep in exception tracebacks."""
+        self.max_frames = max_frames
+
+    def __call__(self, logger: structlog.BoundLogger, name: str, event_dict: EventDict) -> EventDict:  # noqa: ARG002, D102
+        if self.max_frames is not None and 'exception' in event_dict and 'frames' in event_dict["exception"]:
+            event_dict['exception']['frames'] = event_dict['exception']['frames'][-self.max_frames :]
+        return event_dict
+
+
+class SentryProcessor(_SentryProcessor):
+    """The SentryProcessor but with some of our own defaults and slight customization applied."""
+
+    def __init__(self, **kwargs):  # noqa: D107
+        # Unless otherwise specified, add all extra attributes from the log to Sentry as tags.
+        # Explicitly pass tag_keys=None to avoid this behaviour.
+        if 'tag_keys' not in kwargs:
+            kwargs['tag_keys'] = '__all__'
+        super().__init__(**kwargs)
+
+    def _get_event_and_hint(self, event_dict: EventDict) -> tuple[dict, dict]:
+        """Filter out tag_keys which are not primitive types, because Sentry gives an error otherwise."""
+
+        event, hint = super()._get_event_and_hint(event_dict)
+
+        if 'tags' in event:
+            for k in list(event['tags'].keys()):
+                if not isinstance(event['tags'][k], (bool, str, int, float, type(None))):  # noqa: UP038
+                    del event['tags'][k]
+
+        return event, hint

mh_structlog-0.0.40/src/mh_structlog/utils.py

@@ -0,0 +1,22 @@
+import inspect
+
+
+def determine_name_for_logger():
+    """Return a name for a logger depending on the stackframe."""
+    frames = inspect.stack()
+
+    for f in frames:
+        frame = f
+        if 'mh_structlog' not in f[1]:
+            break
+
+    # Make a name ourselves
+    name: str = frame[1].lstrip('/').rstrip('.py').replace('/', '.')
+
+    # Strip away some common 'prefixes' paths
+    for location in ['src', 'code', 'app']:
+        if f'{location}.' in name:
+            _, _, name = name.partition(f'{location}.')
+            break
+
+    return name