policyglass (0.1.1)
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 \
--index-url https://code.mehalter.com/api/packages/clawlter/pypi/simple \
--extra-index-url https://pypi.org/simple \
'policyglass==0.1.1'
Do not use a bare pip install policyglass. An unrelated package with the same name exists on public PyPI, so the Forgejo registry must be explicit here.
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.
Automated publishing uses the shared user-level Forgejo Actions secret PACKAGE_TOKEN. Tagged pushes matching v* validate the tag/version match, run the full quality gates, smoke-test the built wheel, and upload the distribution.
Install from the Forgejo package registry with:
pip install \
--index-url https://code.mehalter.com/api/packages/clawlter/pypi/simple \
--extra-index-url https://pypi.org/simple \
'policyglass==0.1.1'
policyglass is published from the Forgejo registry, while its runtime dependencies are resolved from the public Python package index through the explicit fallback above.
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.