Files

T

slawek 9f56b3ee19 Add initial implementation of Python helpers and CLI tools

- Create .gitignore to exclude build artifacts
- Add README.md with project description and installation instructions
- Implement pyproject.toml for package metadata and script entry points
- Add console output helpers for command-line scripts
- Implement environment file loading functionality
- Add JSON file I/O helpers
- Create token decoder CLI for decoding JWT claims
- Implement serve-markdown CLI for serving Markdown files as HTML

2026-09-06 19:15:54 +02:00

2.6 KiB

Raw Blame History

Python Helpers

Generic Python helpers and command-line tools with no cloud-specific logic. It has no external dependencies.

serve-markdown: serve Markdown files as live-reloading GitHub-styled HTML pages
token-decoder: decode a JWT's claims without verifying its signature

Installation

Each command below is available on PATH directly (no .py extension, no python3 prefix) once the package is installed into the active virtual environment, by any of the methods below.

Local install

From a checkout of this repository:

pip install -e .   # editable, for development: picks up source changes without reinstalling
pip install .      # normal install: copies the package in

Install from git

pip install git+<repository-url>@main

Running without installing

From a repo checkout, run any command as a module with -m instead of installing the package:

python3 -m python_helpers.cli.token_decoder --help

From elsewhere, set PYTHONPATH to the repo root instead:

PYTHONPATH=/path/to/python-helpers python3 -m python_helpers.cli.token_decoder --help

The module path replaces the installed command's short hyphenated name; the underlying main() and behavior are identical.

Library

console: colored console output and the fail() helper used to report errors and exit
env: loading docker-style NAME=VALUE environment files into the process environment
files: JSON file load/save helpers

Commands

`token-decoder`

Decode a JWT's claims, without verifying its signature. Reads from a file argument, or stdin.

Example:

token-decoder token.txt
echo "$TOKEN" | token-decoder

`serve-markdown`

Render Markdown files under a directory as GitHub-styled pages and serve them locally, live-reloading on change.

Parameters:

path (optional, positional): Markdown file or directory to serve; defaults to the current directory. A directory is served at its own URL path, resolving to index.md or README.md within it. Prefix with pydoc: and a dotted module name (e.g. pydoc:python_helpers.console) to render that module's docs with pydoc-markdown instead; requires the pydoc-markdown package to be installed
--listen-address (optional): Address for the local web server to listen on (default: 127.0.0.1)
--port (optional): Port for the local web server (default: 8000)
--watch-interval (optional): Seconds between checks for changes to the file, polled by the browser page (default: 1.0)