birling 0.1.0__tar.gz

birling-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["[0-9]+.[0-9]+.[0-9]+*"]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: checks + docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+      - uses: extractions/setup-just@v4
+      - run: just check
+      - run: just docs-build
+
+  test:
+    name: test (${{ matrix.toxenv }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        toxenv: [py311, py312, py313, py314, py315]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.3.0
+        with:
+          enable-cache: true
+      - run: uv run tox run -e ${{ matrix.toxenv }}
+
+  publish:
+    name: publish
+    needs: [checks, test]
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write  # create the GitHub release
+      id-token: write  # publish to PyPI as a trusted publisher
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # the version comes from the tag
+      - uses: astral-sh/setup-uv@v10.3.0
+      # Outside the checkout, so the source package does not pick it up.
+      - run: uv run python scripts/extract_changelog.py "$GITHUB_REF_NAME" > "$RUNNER_TEMP/notes.md"
+      - run: uv build
+      # Skips files already on PyPI, so a rerun of a failed job can finish the release.
+      - run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/birling/
+      - name: Create or update the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          PRERELEASE=""
+          if [[ "$GITHUB_REF_NAME" =~ (a|b|rc)[0-9]+$ ]]; then PRERELEASE="--prerelease"; fi
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release edit "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" $PRERELEASE
+          else
+            gh release create "$GITHUB_REF_NAME" --notes-file "$RUNNER_TEMP/notes.md" $PRERELEASE
+          fi

birling-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python bytecode
+__pycache__/
+*.py[cod]
+
+# Packaging and build output
+build/
+dist/
+wheels/
+*.egg-info/
+requirements.txt
+
+# Environments
+.venv/
+.env
+
+# Tests and coverage
+.pytest_cache/
+.tox/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+test-reports/
+
+# Documentation build output
+site/
+
+# Tool caches
+.ruff_cache/
+.pyrefly_cache/
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+
+# Agent instructions and settings, kept per checkout
+CLAUDE.md
+AGENTS.md
+.claude/

birling-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

birling-0.1.0/.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "latest"
+  jobs:
+    pre_create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --no-default-groups --group docs
+
+mkdocs:
+  configuration: mkdocs.yml

birling-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Unreleased changes are kept as news fragments in `release-notes/`, and collated into a dated section by towncrier at release time.
+
+<!-- towncrier release notes start -->
+
+## [0.1.0] - 2026-10-13
+
+### Added
+
+- The `birling` command, which finds the branches in a project's code that should log, checks whether each holds a log call, and reports a score for each module and in total:
+
+  - A minimum score, `fail-under` in the configuration or `--fail-under`, below which the command exits with status 1, so that a CI run can hold to it.
+  - Configuration in the `[tool.birling]` table of `pyproject.toml`: which kinds of branch should log, which exceptions never need a log, and how log calls are recognised, covering `logging`, structlog, loguru and a project's own helpers.
+  - A `# birling: ignore` comment on the line that opens a branch, which accepts that branch without a log.
+  - `--show-unlogged`, which lists each unlogged branch as `path:line`, with its unit and how the branch is selected.
+  - `--coverage-file`, which marks the unlogged branches that ran in the tests, read from coverage.py's data; it needs the `coverage` extra.
+  - A Python interface, `measure_source()` and `measure_paths()`, which the command is built on.

birling-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Berislav Lopac <berislav@lopac.net>
+
+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.

birling-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.5
+Name: birling
+Version: 0.1.0
+Summary: Measure how well Python code is covered by log calls.
+Project-URL: documentation, https://birling.readthedocs.io
+Project-URL: repository, https://github.com/berislavlopac/birling
+Project-URL: issues, https://github.com/berislavlopac/birling/issues
+Project-URL: changelog, https://birling.readthedocs.io/en/stable/changelog.html
+Author-email: Berislav Lopac <berislav@lopac.net>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.11
+Provides-Extra: coverage
+Requires-Dist: coverage>=7.16.2; extra == 'coverage'
+Description-Content-Type: text/markdown
+
+# birling
+
+birling measures log coverage in Python projects: how well the code is covered by log calls, whether through the standard [`logging`](https://docs.python.org/3/library/logging.html) module, [structlog](https://www.structlog.org/), [loguru](https://github.com/Delgan/loguru) or a project's own helpers, the way [coverage.py](https://coverage.readthedocs.io/) measures how well it is covered by tests.
+
+A handled exception that leaves no log is a failure nobody hears about. birling finds the places in the code where something should be logged, checks whether a log call is there, and gives the project a score that a CI run can hold to a minimum. By default, those places are `except` handlers that do not raise again.
+
+```shell
+$ birling shop
+Name              Branches  Logged  Score  Unlogged
+---------------------------------------------------
+shop/orders.py           2       1    50%  12
+shop/payments.py         2       1    50%  12
+---------------------------------------------------
+TOTAL                    4       2    50%
+```
+
+## Installation
+
+birling needs Python 3.11 or later and has no dependencies of its own. Install it from PyPI:
+
+```shell
+pip install birling
+```
+
+The `coverage` extra, `birling[coverage]`, adds coverage.py, which the command needs to mark the unlogged branches that ran in the tests.
+
+## Usage
+
+```shell
+birling PATH... [--config FILE] [--fail-under SCORE] [--coverage-file FILE] [--show-unlogged]
+```
+
+The command reads its configuration from the `[tool.birling]` table of `pyproject.toml`, and exits with status 1 when the score is below the minimum:
+
+```toml
+[tool.birling]
+fail-under = 80
+```
+
+The standard `logging` module needs no configuration; other logging libraries and a project's own logging helpers are described in the table.
+
+## Documentation
+
+The documentation covers the command, the configuration, how branches and log calls are found, and the Python interface. It is in `docs/`; `just docs` serves it locally.
+
+## The name
+
+> Log rolling, sometimes called birling, is a sparring sport involving two competitors, each standing on one end of a free-floating log in a body of water. The two battle to dislodge each other from the log while keeping their own footing on it by spinning and kicking it and various other means.
+>
+> — Wikipedia, [Logrolling (sport)](https://en.wikipedia.org/wiki/Logrolling_%28sport%29)
+
+The lumberjacks' sport lends its name to a tool for keeping on top of a project's logs.
+
+## Status
+
+birling is experimental: its interface may change before the first release.

birling-0.1.0/README.md

@@ -0,0 +1,56 @@
+# birling
+
+birling measures log coverage in Python projects: how well the code is covered by log calls, whether through the standard [`logging`](https://docs.python.org/3/library/logging.html) module, [structlog](https://www.structlog.org/), [loguru](https://github.com/Delgan/loguru) or a project's own helpers, the way [coverage.py](https://coverage.readthedocs.io/) measures how well it is covered by tests.
+
+A handled exception that leaves no log is a failure nobody hears about. birling finds the places in the code where something should be logged, checks whether a log call is there, and gives the project a score that a CI run can hold to a minimum. By default, those places are `except` handlers that do not raise again.
+
+```shell
+$ birling shop
+Name              Branches  Logged  Score  Unlogged
+---------------------------------------------------
+shop/orders.py           2       1    50%  12
+shop/payments.py         2       1    50%  12
+---------------------------------------------------
+TOTAL                    4       2    50%
+```
+
+## Installation
+
+birling needs Python 3.11 or later and has no dependencies of its own. Install it from PyPI:
+
+```shell
+pip install birling
+```
+
+The `coverage` extra, `birling[coverage]`, adds coverage.py, which the command needs to mark the unlogged branches that ran in the tests.
+
+## Usage
+
+```shell
+birling PATH... [--config FILE] [--fail-under SCORE] [--coverage-file FILE] [--show-unlogged]
+```
+
+The command reads its configuration from the `[tool.birling]` table of `pyproject.toml`, and exits with status 1 when the score is below the minimum:
+
+```toml
+[tool.birling]
+fail-under = 80
+```
+
+The standard `logging` module needs no configuration; other logging libraries and a project's own logging helpers are described in the table.
+
+## Documentation
+
+The documentation covers the command, the configuration, how branches and log calls are found, and the Python interface. It is in `docs/`; `just docs` serves it locally.
+
+## The name
+
+> Log rolling, sometimes called birling, is a sparring sport involving two competitors, each standing on one end of a free-floating log in a body of water. The two battle to dislodge each other from the log while keeping their own footing on it by spinning and kicking it and various other means.
+>
+> — Wikipedia, [Logrolling (sport)](https://en.wikipedia.org/wiki/Logrolling_%28sport%29)
+
+The lumberjacks' sport lends its name to a tool for keeping on top of a project's logs.
+
+## Status
+
+birling is experimental: its interface may change before the first release.

birling-0.1.0/birling/__init__.py

@@ -0,0 +1,6 @@
+"""Measure how well Python code is covered by log calls."""
+
+from importlib.metadata import version
+
+__version__ = version("birling")
+"""The installed distribution's version, derived from the git tag it was built from."""

birling-0.1.0/birling/__main__.py

@@ -0,0 +1,7 @@
+"""Run the `birling` command as `python -m birling`."""
+
+import sys
+
+from birling.cli import main
+
+sys.exit(main())