pkgreach 0.0.2__tar.gz

pkgreach-0.0.2/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

pkgreach-0.0.2/.gitignore

@@ -0,0 +1,120 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+node_modules/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# 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/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea

pkgreach-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+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.

pkgreach-0.0.2/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: pkgreach
+Version: 0.0.2
+Summary: Track how your packages are really used across PyPI, npm, crates.io and GitHub: downloads against a noise floor, dependents, stars; a weekly GitHub Action keeps the history and publishes a report.
+Project-URL: Homepage, https://github.com/thorwhalen/pkgreach
+Project-URL: Repository, https://github.com/thorwhalen/pkgreach
+Project-URL: Dashboard, https://thorwhalen.github.io/pkgreach/
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: crates,dashboard,dependents,downloads,github,github-actions,npm,pypi,statistics
+Requires-Python: >=3.11
+Requires-Dist: cw<0.2,>=0.1.14
+Requires-Dist: ghtraffic<0.1,>=0.0.4
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
+Requires-Dist: sphinx>=6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# pkgreach
+
+How are your packages really used? `pkgreach` tracks your packages on PyPI, npm, crates.io and GitHub every week, keeps the history the registries throw away, and publishes a report that separates robots from people.
+
+**Live example (the author's packages):** https://thorwhalen.github.io/pkgreach/
+
+## Why
+
+Registries keep a few months of daily download counts (crates.io 90 days, PyPI about 6 months, npm 18 months), and none of them separates people from robots: mirrors, CI pipelines and scanners download every release of every package. So `pkgreach` reports downloads against a **noise floor** (what your least-used packages get), next to the signals a robot does not create: **dependents** (packages and repositories that declare yours, from [ecosyste.ms](https://ecosyste.ms)), and **stars and forks** of your public repositories.
+
+## Quick start: a weekly GitHub Action
+
+In any repository you own (it can be public: everything collected is public already):
+
+```bash
+pip install pkgreach
+pkgreach init . --pypi YOUR_PYPI_USER --npm YOUR_NPM_USER --github YOUR_GITHUB_USER YOUR_ORG
+git add -A && git commit -m "pkgreach" && git push
+```
+
+`pkgreach init` writes `pkgreach.toml` (what to follow) and `.github/workflows/pkgreach.yml`. Then turn on Pages once (Settings → Pages → Source: **GitHub Actions**) and run the workflow (`gh workflow run pkgreach.yml`). Every Sunday after that it collects, commits the history to the `pkgreach-data` branch, and publishes the report on your GitHub Pages. No secret is needed.
+
+The workflow is three steps:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: thorwhalen/pkgreach@<version>   # pin the release you installed
+  id: reach
+- uses: actions/upload-pages-artifact@v3
+  with:
+    path: ${{ steps.reach.outputs.site-dir }}
+- uses: actions/deploy-pages@v4
+```
+
+## Configuration
+
+`pkgreach.toml` has one table per platform: `pypi`, `npm`, `crates`, `github`. Every key is optional; unknown keys are refused, so a typo never silently does nothing.
+
+```toml
+[pypi]
+users = ["alice"]                    # every package these accounts own or maintain
+packages = ["a-package-of-a-friend"] # plus these
+exclude = ["alice-test-*"]           # minus these (glob patterns)
+
+[npm]
+users = ["alice"]
+
+[crates]
+users = ["alice"]                    # crates.io login
+
+[github]
+users = ["alice", "alice-org"]       # public repos of these users and orgs
+where = { fork = false, archived = false }   # characteristics a package must have
+```
+
+`where` matches the metadata of listed packages field by field (GitHub repos have `fork`, `archived`, `language`; PyPI packages have `role`, `owner` or `maintainer`); packages named in `packages` are always kept. PyPI names are normalized (`Flask_Login` is `flask-login`). Top-level keys: `max_workers` (default 4) and `dependents` (default `true`: ask ecosyste.ms).
+
+The Action's inputs: `config`, `data-branch` (default `pkgreach-data`), `site-dir`, `title`, `token` (reads GitHub; defaults to the workflow's token), `commit`, `fail-on-errors` (default `false`: a failed package is listed in `last_run.json` and flagged on the page, and the run stays green).
+
+## Run it locally
+
+```bash
+pkgreach collect --config pkgreach.toml   # into ~/.local/share/pkgreach/data
+pkgreach report --out site                # site/index.html and site/summary.json
+pkgreach init . --pypi me --github me my-org   # a config and a weekly workflow
+```
+
+From Python, every part is a keyword argument with a working default:
+
+```python
+from pkgreach import collect, load_settings, build_site, Files, PLATFORMS
+
+collect(load_settings("pkgreach.toml"), store=Files("data"))
+build_site(Files("data"), Files("site"))
+```
+
+- `collect(platforms=...)` and `summarize(platforms=...)`: add a platform with `Platform(name, list_packages, fetch, kind=..., headline=...)`; see `pkgreach/platforms/__init__.py` for the contract. A `"snapshot"` platform (current values only, like Hugging Face likes) is shown by its `headline` metrics.
+- `collect(select=lambda platform, record: ...)`: any selection a TOML file cannot express.
+- `collect(dependents=...)`: another source of dependents.
+- `build_site(analyze=...)`: your own summary; `summary.json` is the default one, for any other tool.
+- `make_http(headers_by_host=...)`: credentials per host (the CLI gives GitHub `GITHUB_TOKEN` or `GH_TOKEN`).
+- `store=` / `out=`: any `MutableMapping[str, str]`, such as a [dol](https://github.com/i2mint/dol) store (S3, a database).
+
+## What is collected
+
+| platform | daily downloads | other numbers | source |
+|---|---|---|---|
+| PyPI | all, and without mirrors | versions, dependents | pypistats.org, PyPI JSON, ecosyste.ms |
+| npm | all | dependents | api.npmjs.org, ecosyste.ms |
+| crates.io | all | total downloads, versions, dependents | crates.io, ecosyste.ms |
+| GitHub | none | stars, forks, open issues and PRs | GitHub REST (public repos only) |
+
+The history is plain CSV, one table per kind, split by year (`downloads/YYYY.csv`, `metrics.csv`, `packages.csv`, `runs.csv`), merged idempotently so re-running a collection never changes the result. `manifest.json` lists every file and its columns. Design and alternatives: [docs/adr/0001-seams-and-scope.md](docs/adr/0001-seams-and-scope.md). What each platform offers, verified: [docs/research/platform-apis.md](docs/research/platform-apis.md).
+
+**GitHub traffic** (views, clones, referrers) is private and needs a token with push access. That is [ghtraffic](https://github.com/thorwhalen/ghtraffic)'s job, in a private repository; pkgreach reuses its storage layer.
+
+Dependents data is from [ecosyste.ms](https://ecosyste.ms), licensed [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/); the report credits it and the history carries a `DATA-LICENSE.md`. A repository that stops being listed (made private, deleted, or dropped from the selection) leaves the current tables at the next run; what was committed before stays in the branch's git history.
+
+## Limits
+
+- History starts at your first run, minus what the registry still keeps.
+- One run of about 400 packages takes about 7 minutes, mostly waiting on pypistats.org's limit of 60 requests a minute.
+- Listing a PyPI account uses PyPI's XML-RPC `user_packages`, deprecated but still answered.
+- Dependents come from ecosyste.ms, which indexes new packages with some delay: a fresh package shows none at first.

pkgreach-0.0.2/README.md

@@ -0,0 +1,104 @@
+# pkgreach
+
+How are your packages really used? `pkgreach` tracks your packages on PyPI, npm, crates.io and GitHub every week, keeps the history the registries throw away, and publishes a report that separates robots from people.
+
+**Live example (the author's packages):** https://thorwhalen.github.io/pkgreach/
+
+## Why
+
+Registries keep a few months of daily download counts (crates.io 90 days, PyPI about 6 months, npm 18 months), and none of them separates people from robots: mirrors, CI pipelines and scanners download every release of every package. So `pkgreach` reports downloads against a **noise floor** (what your least-used packages get), next to the signals a robot does not create: **dependents** (packages and repositories that declare yours, from [ecosyste.ms](https://ecosyste.ms)), and **stars and forks** of your public repositories.
+
+## Quick start: a weekly GitHub Action
+
+In any repository you own (it can be public: everything collected is public already):
+
+```bash
+pip install pkgreach
+pkgreach init . --pypi YOUR_PYPI_USER --npm YOUR_NPM_USER --github YOUR_GITHUB_USER YOUR_ORG
+git add -A && git commit -m "pkgreach" && git push
+```
+
+`pkgreach init` writes `pkgreach.toml` (what to follow) and `.github/workflows/pkgreach.yml`. Then turn on Pages once (Settings → Pages → Source: **GitHub Actions**) and run the workflow (`gh workflow run pkgreach.yml`). Every Sunday after that it collects, commits the history to the `pkgreach-data` branch, and publishes the report on your GitHub Pages. No secret is needed.
+
+The workflow is three steps:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: thorwhalen/pkgreach@<version>   # pin the release you installed
+  id: reach
+- uses: actions/upload-pages-artifact@v3
+  with:
+    path: ${{ steps.reach.outputs.site-dir }}
+- uses: actions/deploy-pages@v4
+```
+
+## Configuration
+
+`pkgreach.toml` has one table per platform: `pypi`, `npm`, `crates`, `github`. Every key is optional; unknown keys are refused, so a typo never silently does nothing.
+
+```toml
+[pypi]
+users = ["alice"]                    # every package these accounts own or maintain
+packages = ["a-package-of-a-friend"] # plus these
+exclude = ["alice-test-*"]           # minus these (glob patterns)
+
+[npm]
+users = ["alice"]
+
+[crates]
+users = ["alice"]                    # crates.io login
+
+[github]
+users = ["alice", "alice-org"]       # public repos of these users and orgs
+where = { fork = false, archived = false }   # characteristics a package must have
+```
+
+`where` matches the metadata of listed packages field by field (GitHub repos have `fork`, `archived`, `language`; PyPI packages have `role`, `owner` or `maintainer`); packages named in `packages` are always kept. PyPI names are normalized (`Flask_Login` is `flask-login`). Top-level keys: `max_workers` (default 4) and `dependents` (default `true`: ask ecosyste.ms).
+
+The Action's inputs: `config`, `data-branch` (default `pkgreach-data`), `site-dir`, `title`, `token` (reads GitHub; defaults to the workflow's token), `commit`, `fail-on-errors` (default `false`: a failed package is listed in `last_run.json` and flagged on the page, and the run stays green).
+
+## Run it locally
+
+```bash
+pkgreach collect --config pkgreach.toml   # into ~/.local/share/pkgreach/data
+pkgreach report --out site                # site/index.html and site/summary.json
+pkgreach init . --pypi me --github me my-org   # a config and a weekly workflow
+```
+
+From Python, every part is a keyword argument with a working default:
+
+```python
+from pkgreach import collect, load_settings, build_site, Files, PLATFORMS
+
+collect(load_settings("pkgreach.toml"), store=Files("data"))
+build_site(Files("data"), Files("site"))
+```
+
+- `collect(platforms=...)` and `summarize(platforms=...)`: add a platform with `Platform(name, list_packages, fetch, kind=..., headline=...)`; see `pkgreach/platforms/__init__.py` for the contract. A `"snapshot"` platform (current values only, like Hugging Face likes) is shown by its `headline` metrics.
+- `collect(select=lambda platform, record: ...)`: any selection a TOML file cannot express.
+- `collect(dependents=...)`: another source of dependents.
+- `build_site(analyze=...)`: your own summary; `summary.json` is the default one, for any other tool.
+- `make_http(headers_by_host=...)`: credentials per host (the CLI gives GitHub `GITHUB_TOKEN` or `GH_TOKEN`).
+- `store=` / `out=`: any `MutableMapping[str, str]`, such as a [dol](https://github.com/i2mint/dol) store (S3, a database).
+
+## What is collected
+
+| platform | daily downloads | other numbers | source |
+|---|---|---|---|
+| PyPI | all, and without mirrors | versions, dependents | pypistats.org, PyPI JSON, ecosyste.ms |
+| npm | all | dependents | api.npmjs.org, ecosyste.ms |
+| crates.io | all | total downloads, versions, dependents | crates.io, ecosyste.ms |
+| GitHub | none | stars, forks, open issues and PRs | GitHub REST (public repos only) |
+
+The history is plain CSV, one table per kind, split by year (`downloads/YYYY.csv`, `metrics.csv`, `packages.csv`, `runs.csv`), merged idempotently so re-running a collection never changes the result. `manifest.json` lists every file and its columns. Design and alternatives: [docs/adr/0001-seams-and-scope.md](docs/adr/0001-seams-and-scope.md). What each platform offers, verified: [docs/research/platform-apis.md](docs/research/platform-apis.md).
+
+**GitHub traffic** (views, clones, referrers) is private and needs a token with push access. That is [ghtraffic](https://github.com/thorwhalen/ghtraffic)'s job, in a private repository; pkgreach reuses its storage layer.
+
+Dependents data is from [ecosyste.ms](https://ecosyste.ms), licensed [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/); the report credits it and the history carries a `DATA-LICENSE.md`. A repository that stops being listed (made private, deleted, or dropped from the selection) leaves the current tables at the next run; what was committed before stays in the branch's git history.
+
+## Limits
+
+- History starts at your first run, minus what the registry still keeps.
+- One run of about 400 packages takes about 7 minutes, mostly waiting on pypistats.org's limit of 60 requests a minute.
+- Listing a PyPI account uses PyPI's XML-RPC `user_packages`, deprecated but still answered.
+- Dependents come from ecosyste.ms, which indexes new packages with some delay: a fresh package shows none at first.

pkgreach-0.0.2/action.yml

@@ -0,0 +1,88 @@
+name: pkgreach
+description: Track downloads, dependents and stars of your packages on PyPI, npm, crates.io and GitHub, keep the history, and build a report site.
+branding:
+  icon: trending-up
+  color: green
+inputs:
+  config:
+    description: Path to pkgreach.toml in the checked-out repository.
+    default: pkgreach.toml
+  data-branch:
+    description: Branch of this repository that keeps the history (created on first run).
+    default: pkgreach-data
+  site-dir:
+    description: Where to write the report site (upload it with actions/upload-pages-artifact).
+    default: _pkgreach_site
+  title:
+    description: Title of the report page.
+    default: Package reach
+  token:
+    description: Token for reading GitHub (public data only; it only raises the rate limit).
+    default: ${{ github.token }}
+  commit:
+    description: Commit and push the updated history (pushed with the checkout's credentials).
+    default: "true"
+  fail-on-errors:
+    description: Fail the job if any package failed (the report is still built and pushed).
+    default: "false"
+outputs:
+  site-dir:
+    description: The folder holding the report site.
+    value: ${{ inputs.site-dir }}
+runs:
+  using: composite
+  steps:
+    - name: Install pkgreach
+      shell: bash
+      run: |
+        set -euo pipefail
+        python3 -c 'import sys; sys.exit(sys.version_info < (3, 11))' || {
+          echo "::error::pkgreach needs Python 3.11+; add actions/setup-python before this step."; exit 1; }
+        python3 -m venv "$RUNNER_TEMP/pkgreach-venv"
+        "$RUNNER_TEMP/pkgreach-venv/bin/pip" install --quiet "$GITHUB_ACTION_PATH"
+
+    - name: Collect, commit, report
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        CONFIG: ${{ inputs.config }}
+        BRANCH: ${{ inputs.data-branch }}
+        SITE_DIR: ${{ inputs.site-dir }}
+        TITLE: ${{ inputs.title }}
+        COMMIT: ${{ inputs.commit }}
+        FAIL_ON_ERRORS: ${{ inputs.fail-on-errors }}
+      run: |
+        set -euo pipefail
+        PKGREACH="$RUNNER_TEMP/pkgreach-venv/bin/pkgreach"
+        DATA_DIR="$RUNNER_TEMP/pkgreach-data"
+        CONFIG="$(realpath "$CONFIG")"
+        # The history lives on its own branch, checked out as a worktree.
+        # A network or auth failure must not look like "no branch yet".
+        if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null; then
+          git fetch -q --depth=1 origin "$BRANCH"
+          git worktree add -q -B "$BRANCH" "$DATA_DIR" FETCH_HEAD
+        else
+          rc=$?
+          [ "$rc" = 2 ] || { echo "::error::cannot reach origin (git ls-remote exit $rc)"; exit 1; }
+          git worktree add -q --orphan -b "$BRANCH" "$DATA_DIR"
+        fi
+        flags=()
+        [ "$FAIL_ON_ERRORS" = "true" ] && flags+=(--fail-on-errors)
+        status=0
+        "$PKGREACH" collect --config "$CONFIG" --data-dir "$DATA_DIR" "${flags[@]}" || status=$?
+        if [ "$COMMIT" = "true" ]; then
+          cd "$DATA_DIR"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A
+          if ! git diff --cached --quiet; then
+            git commit -q -m "pkgreach: collect $(date -u +%F) [skip ci]"
+          fi
+          # nothing ever committed (a first run that collected nothing): no push
+          if git rev-parse -q --verify HEAD >/dev/null; then
+            git push -q origin "HEAD:refs/heads/$BRANCH"
+          fi
+          cd - >/dev/null
+        fi
+        "$PKGREACH" report --data-dir "$DATA_DIR" --out "$SITE_DIR" --title "$TITLE"
+        exit $status

pkgreach-0.0.2/pkgreach/__init__.py

@@ -0,0 +1,53 @@
+"""Track how your packages are really used, across PyPI, npm, crates.io and GitHub.
+
+Registries keep a few months of daily download counts at most, and none of
+them separates people from robots. ``pkgreach`` collects the counts every week
+into a git-friendly history, adds the signals a robot does not create
+(dependent packages and repositories, stars, forks), and builds a static
+report that puts each package against a noise floor.
+
+>>> from pkgreach import collect, load_settings, build_site, Files  # doctest: +SKIP
+>>> collect(load_settings("pkgreach.toml"), store=Files("data"))   # doctest: +SKIP
+>>> build_site(Files("data"), Files("site"))                       # doctest: +SKIP
+
+Seams (each one keyword argument, with a working default):
+
+- ``collect(platforms=)``: which publishing platforms (:data:`PLATFORMS`).
+- :class:`Selection` per platform, plus ``collect(select=)``: which packages.
+- ``collect(dependents=)``: where dependents come from (ecosyste.ms).
+- ``build_site(analyze=, render=)``: what is computed and how it is shown.
+- ``store`` / ``out``: where the history and the site live (any
+  ``MutableMapping[str, str]``: a folder by default).
+"""
+
+from ghtraffic.tables import Files
+
+from pkgreach.analyze import summarize
+from pkgreach.collect import RunReport, collect, select_packages, write_manifest
+from pkgreach.config import Selection, Settings, load_settings, settings_from_mapping
+from pkgreach.http import HttpError, make_http
+from pkgreach.platforms import PLATFORMS, Platform
+from pkgreach.report import build_site, render_html
+from pkgreach.scaffold import init_repo
+from pkgreach.tables import TABLES
+
+__all__ = [
+    "Files",
+    "HttpError",
+    "PLATFORMS",
+    "Platform",
+    "RunReport",
+    "Selection",
+    "Settings",
+    "TABLES",
+    "build_site",
+    "collect",
+    "init_repo",
+    "load_settings",
+    "make_http",
+    "render_html",
+    "select_packages",
+    "settings_from_mapping",
+    "summarize",
+    "write_manifest",
+]

pkgreach-0.0.2/pkgreach/__main__.py

@@ -0,0 +1,36 @@
+# PYTHON_ARGCOMPLETE_OK
+"""Command line: ``pkgreach collect | report | init``, one command per function
+of :data:`pkgreach.tools.COMMANDS` (dispatched by ``cw``).
+
+``pkgreach collect --config pkgreach.toml --data-dir data`` merges this week's
+numbers into the history; ``pkgreach report --data-dir data --out site``
+writes the static report; ``pkgreach init . --pypi you --github you`` sets up
+a repository. Without ``--data-dir``, data goes to ``~/.local/share/pkgreach/data``.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import cw
+
+from pkgreach.config import SettingsError
+from pkgreach.tools import COMMANDS, CollectionFailed
+
+#: Keep injection-only parameters off the command line.
+_CLI_CONFIG = {"collect": {"environ": cw.HIDE}}
+
+
+def main(argv=None) -> int:
+    """Entry point of the ``pkgreach`` command; returns the exit code."""
+    try:
+        return cw.dispatch(
+            COMMANDS, argv=argv, config=_CLI_CONFIG, convention=cw.MODERN
+        )
+    except (CollectionFailed, SettingsError) as e:
+        print(f"pkgreach: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())