policyglass (0.1.0)
Installation
pip install --index-url About this package
Declarative filesystem policy checks for repositories, release bundles, and CI gates.
Policyglass
Policyglass is a production-oriented Python CLI and library for validating a directory tree against a declarative YAML policy.
It is built for teams that want a lightweight guardrail in local workflows, CI, or release packaging without writing custom shell scripts for every repository.
What it checks
Policyglass currently supports four classes of checks:
- required paths — fail when expected files or directories are missing
- forbidden globs — fail when a path matches a banned pattern
- size limits — fail when matched files exceed a configured byte threshold
- forbidden content patterns — fail when text content matches a dangerous or disallowed regex
Why use it
- small and explicit configuration
- typed Python API and a usable CLI
- JSON output for automation and text output for humans
- designed to fit pre-commit, CI, packaging, and release validation flows
- straightforward extension surface for adding new rule types later
Install
Policyglass currently targets Python 3.13+.
pip install policyglass
For local development in this repository:
uv venv .venv
uv pip install --python .venv/bin/python -e '.[dev]'
Quick start
Create a starter policy:
policyglass init policyglass.yml
Note: if the policy file lives under the scan target, it counts as part of the scanned tree like any other file.
Example policy:
version: 1
required_paths:
- README.md
- src/
forbidden_globs:
- '*.pem'
- '.env'
ignore_globs:
- '.git/'
- '.venv/'
size_limits:
- glob: 'dist/*.whl'
max_bytes: 10000000
forbidden_content_patterns:
- pattern: 'AKIA[0-9A-Z]{16}'
message: 'Possible AWS key'
Run a check:
policyglass check . --policy policyglass.yml
Machine-readable output:
policyglass check . --policy policyglass.yml --format json
CLI overview
policyglass check
Validate a directory tree against a policy file.
policyglass check PATH --policy policyglass.yml [--format text|json]
Exit codes:
0— no violations1— one or more violations
policyglass init
Write a starter policy file.
policyglass init policyglass.yml
Use --force to overwrite an existing file.
Python API
from pathlib import Path
from policyglass import load_policy, scan_path
policy = load_policy(Path("policyglass.yml"))
report = scan_path(Path("."), policy)
if not report.passed:
for finding in report.findings:
print(finding.code, finding.path, finding.message)
Documentation
The docs site lives under docs/, is built with MkDocs Material, and is published at https://clawlter.mehalter.page/policyglass/.
Useful entry points:
docs/index.mddocs/getting-started.mddocs/reference/policy-file.mddocs/reference/cli.mddocs/guides/ci.mddocs/architecture.md
Build locally:
mkdocs build --strict
Serve locally:
mkdocs serve
Development
Run the main quality gates:
ruff check .
ruff format --check .
mypy src
pytest
mkdocs build --strict
python -m build
Release automation
- Forgejo CI runs from
.forgejo/workflows/ci.yml - docs validation runs from
.forgejo/workflows/docs-site.yml - docs publishing runs from
.forgejo/workflows/docs-deploy.yml - tag-based release publishing runs from
.forgejo/workflows/release.yml
Release publishing targets the Forgejo PyPI-compatible package registry at https://code.mehalter.com/api/packages/clawlter/pypi.
To enable automated publishing from Forgejo Actions, configure the repository secret FORGEJO_PACKAGE_TOKEN with a package-write token for clawlter. Tagged pushes matching v* will then build, validate, and upload the distribution.
Install from the Forgejo package registry with:
pip install \
--index-url https://<username>:<token>@code.mehalter.com/api/packages/clawlter/pypi/simple \
--no-deps \
policyglass==0.1.0
Project status
Policyglass is intentionally small but production-minded:
- typed modules
- unit tests with coverage enforcement
- CI workflow included
- contributor and security documentation included
- documentation website included
License
MIT. See LICENSE.