# 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:

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

### Install from git

```bash
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:

```bash
python3 -m python_helpers.cli.token_decoder --help
```

From elsewhere, set `PYTHONPATH` to the repo root instead:

```bash
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:

```bash
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:

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