112 lines
3.2 KiB
Markdown
112 lines
3.2 KiB
Markdown
# 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.
|
|
|
|
### Install from the Gitea package registry
|
|
|
|
```bash
|
|
pip install --index-url https://<username>:<token>@<gitea-host>/api/packages/<owner>/pypi/simple python-helpers
|
|
```
|
|
|
|
## Publishing
|
|
|
|
Add the registry to `~/.pypirc`:
|
|
|
|
```
|
|
[distutils]
|
|
index-servers = gitea
|
|
|
|
[gitea]
|
|
repository = https://<gitea-host>/api/packages/<owner>/pypi
|
|
username = <username>
|
|
password = <token>
|
|
```
|
|
|
|
```bash
|
|
pip install build twine
|
|
python3 -m build
|
|
python3 -m twine upload --repository gitea dist/*
|
|
```
|
|
|
|
> **Note**: a name and version already in the registry cannot be republished. Raise `version`
|
|
> in `pyproject.toml` before each upload.
|
|
|
|
## 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
|
|
```
|