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)

Example:

serve-markdown README.md
serve-markdown pydoc:python_helpers.console