edwh
Table of Contents
Installation
pipx install edwh
# or: uvenv install edwh
# or with all plugins:
pipx install[plugins]
# or with specific plugins:
pipx install[multipass,restic]
# managing plugins later:
edwh plugins
edwh plugin.add multipass
edwh plugin.remove multipass
Usage
# to see all available commands:
ew # or `edwh`
# to see help about a specific namespace:
ew help <namespace> # e.g. `ew help plugin`
# to see help about a specific command:
ew help <command> # e.g. `ew help plugin.list`
Sudo authentication
edwh sudo verifies your sudo password and safely stores it temporarily so commands that require sudo can run without
prompting again.
By default, EDWH uses the operating system keyring (for example, GNOME Secret Service on Linux). This is the preferred backend when the desktop session and its keyring are available.
When the system keyring is locked, edwh sudo offers an SSH-agent fallback. If you accept, EDWH lists the public keys
available through ssh-add -L; select the key whose agent should unlock the encrypted EDWH keyring. The selection is
recorded in ~/.config/ssh-agent-keyring/config.json, the SSH-agent backend's documented configuration file, and later
EDWH commands automatically use that backend.
The SSH-agent backend requires a reachable agent, SSH_AUTH_SOCK, and the selected key loaded in that agent. For a
remote development machine, connect with agent forwarding (ssh -A or ForwardAgent yes). The sudo password remains
encrypted on disk; access depends on the selected SSH agent rather than a second keyring password.
Linting
edwh lint runs Ruff and Ty by default. Disable either tool for a specific project in its pyproject.toml:
[tool.edwh.lint]
ruff = false
ty = false
edwh fmt sorts imports and reformats Python code with Ruff.
Releasing plugins
edwh plugin.release warns when a project still releases with
python-semantic-release, and when the --hatch build fallback is selected.
Silence either for a project:
[tool.edwh.release]
warn-psr = false
warn-hatch-build = false
Warnings about the build configuration itself (Hatchling, the uv_build pin, a
hatch build release command) come from
vommit, which runs the build. Its
readme documents them under "Build checks", including how to silence one. When
using python-semantic-release they are not reported at all; that prints its
deprecation notice instead.
Testing
edwh test.run runs pytest with coverage by default. It prefers ./venv/bin/pytest, falls back to
pytest from PATH, and requires pytest-cov in the selected environment.
edwh test.run
edwh test.run -k test_specific_behavior
edwh test.run --html
edwh test.run --no-coverage
To generate both the terminal summary and an HTML report on every run, add this
to pyproject.toml:
[tool.edwh.test]
html = true
If a project provides its own test.tasks.py, edwh warns about the override and that local test.run
replaces the built-in task.
Worktrees
edwh worktree <branch> builds a second, isolated environment for a branch: a git worktree plus the
gitignored config, its own ports and hostnames, and a seeded database. edwh worktree.rm <branch>
removes it again, containers and volumes included. If no local branch exists, it checks fetched
upstream branches first and creates a tracking branch when it finds one.
edwh worktree.setup # configure this project once (writes [worktree] to .toml)
edwh worktree feature/login # create + start
edwh worktree feature/login --no-up # create, do not start
edwh worktree.list # branches, slugs, paths, ports, running containers
cd $(edwh worktree.path feature/login)
edwh worktree.rm feature/login # containers, volumes, directory and branch
Worktrees live under ~/.cache/edwh/worktrees/<repo>-<slug>; override with $EDWH_WORKTREE_ROOT
or root in the config. The slugified directory name keeps $PROJECT, the compose project and the
volume/container prefixes identical.
How it works
worktree copies the .env, deletes the keys that must be unique, and reruns
edwh setup --non-interactive so your local.setup regenerates them via next_value /
next_available_port. Port allocation also scans git worktree list, so environments find each
other even though they are not adjacent directories.
Configuration
[worktree]
copy = [".env", ".toml", "shared_keys/"] # gitignored paths to carry over
reset = ["*_PORT", "SCHEMA_VERSION"] # fnmatch globs; deleted so local.setup recomputes them
seed = "clone" # fresh | clone | devdb
[worktree.env]
# rewritten instead of regenerated; {value} {repo} {branch} {slug} available. All fields have defaults.
PROJECT = "{repo}-{slug}"
worktree.setup proposes both lists: copy comes from .gitignore, and reset is detected from
keys on the host side of a ports: mapping, a Traefik Host() rule, a Caddy caddy site-address
label, or HOSTINGDOMAIN(S), plus keys with a unique value in every existing checkout on this
machine. Values shared by any checkout are otherwise left unticked, since they are likely shared or
machine-specific config.
COMPOSE_PROJECT_NAME is always reset, since a copied value would fuse the environments. Ticked
keys collapse back to a glob when the glob covers exactly your selection.
reset or template?
Resetting only produces a new value when local.setup's default is environment-aware
(next_value, ports, os.getcwd()). With a constant default like "localhost" it silently
rewrites the same value, and both environments share it. Those keys need a [worktree.env]
template instead; after setup, worktree warns about any reset that came back identical.
HOSTINGDOMAIN and HOSTINGDOMAINS are the exception: when either is in reset, worktree
asks for its replacement before it creates anything. It never copies the source value or accepts
an empty answer. Scripts can provide the answer with --env HOSTINGDOMAIN=branch.localhost
(repeat --env for each requested hostname key). Do not also put a prompted hostname in
[worktree.env]: that section is only for automatic templates.
Seeding:
fresh- leave it empty and letmigratefill it.clone- copy the source's named docker volumes via a throwaway container each. Project-agnostic and current data, but services mounted on a copied volume pause in the source, soworktreeasks first unless--yes. Note it copies everything: N worktrees means N copies of the full volume.devdb- rundevdb.recoverafterupusing the trimmededwh-devdb-pluginsnapshot (putmigrate/data/snapshot/incopy). Postgres only, much smaller than a clone.
After seeding, a worktree task in your project's tasks.py runs last, inside the new worktree
(e.g. c.run("./bin/load-fixtures")).
Hostnames
Traefik routes on Host(), so overlapping hostnames make it pick a router at random, breaking both
environments. Rewriting HOSTINGDOMAIN covers all rules, but needs wildcard DNS one label deeper
and therefore a wildcard certificate (or CERTRESOLVER=default locally).
worktree compares the traefik Host() labels of the new environment against every other
checkout and refuses to up on an overlap. --force starts it anyway.
Task Load Order
Commands are loaded in the following order:
-
EDWH Package:
- Loaded into the global namespace and its own namespaces (like
edwh plugins.).
- Loaded into the global namespace and its own namespaces (like
-
Plugins:
- Loaded into their own namespaces (like
edwh mp.).
- Loaded into their own namespaces (like
-
Current Directory:
- Loaded into the
local.namespace. If it doesn't exist, it traverses up the directory tree - (e.g.,
../tasks.py,../../tasks.py).
- Loaded into the
-
Other Local Tasks:
- Other local tasks with their own namespace are loaded (e.g.,
namespace.tasks.py) and can be invoked withedwh namespace.command.
- Other local tasks with their own namespace are loaded (e.g.,
-
Personal Global Tasks:
- Personal global tasks (e.g.,
~/.config/edwh/tasks.py) are also loaded into the global namespace, useful for shortcuts, custom aliases, etc. (+add_alias).
- Personal global tasks (e.g.,
-
Personal Namespaced Tasks:
- Personal tasks with their own namespace (e.g.,
~/.config/edwh/namespace.tasks.py). Similar to a plugin, but for personal use.
- Personal tasks with their own namespace (e.g.,
Plugins
Multipass
- pip name:
edwh-multipass-plugin - github:
educationwarehouse/edwh-multipass-plugin - plugin name:
edwh[multipass] - subcommand namespace:
mp
Restic
- pip name:
edwh-restic-plugin - github:
educationwarehouse/edwh-restic-plugin - plugin name:
edwh[restic] - subcommand namespace:
restic
Pip Compile
- pip name:
edwh-pipcompile-plugin - github:
educationwarehouse/edwh-pipcompile-plugin - plugin name:
edwh[pip] - subcommand namespace:
pip
Bundler
- pip name:
edwh-bundler-plugin - github:
educationwarehouse/edwh-bundler-plugin - plugin name:
edwh[bundler] - subcommand namespace:
bundle
Server Provisioning
- pip name:
edwh-server-provisioning-plugin - github:
educationwarehouse/server_provisioning - plugin name:
edwh[server-provisioning] - subcommand namespace:
remote
b2
- pip name:
edwh-b2-plugin - github:
educationwarehouse/edwh-b2-plugin - plugin name:
edwh[b2] - subcommand namespace:
b2
Locust
- pip name:
edwh-locust-plugin - github:
educationwarehouse/edwh-locust-plugin - plugin name:
edwh[locust] - subcommand namespace:
locust
sshkey
- pip name:
edwh-sshkey-plugin - github:
educationwarehouse/edwh-sshkey-plugin - plugin name
edwh[sshkey] - subcommand namespace
sshkey
sshfs
- pip name:
edwh-sshfs-plugin - github:
educationwarehouse/edwh-sshfs-plugin - plugin name
edwh[sshfs] - subcommand namespace
sshfs
files
- pip name:
edwh-files-plugin - github:
educationwarehouse/edwh-files-plugin - plugin name
edwh[files] - subcommand namespace
file
whitelabel
- pip name:
edwh-whitelabel-plugin - github:
educationwarehouse/edwh-whitelabel-plugin - plugin name
edwh[whitelabel] - subcommand namespace
wl
devdb
- pip name:
edwh-devdb-plugin - github:
educationwarehouse/edwh-devdb-plugin - plugin name
edwh[devdb] - subcommand namespace
devdb
Improvements to @task
The edwh.improved_task decorator enhances the functionality of the standard @task decorator from Invoke by
introducing additional features:
-
Flags: You can now specify custom flags for command line arguments. This allows you to define aliases, rename arguments (e.g., using
--jsonfor an argument namedas_json), and create custom short flags (e.g.,--excludecan also be represented as-x). -
Hookable: The improved task supports hooks that allow you to run additional tasks after the main task execution. If the
hookableoption is set toTrue, any tasks found across namespaces with the same name will be executed in sequence, passing along the context and any provided arguments.
The return value of a hookable task will be available in the context under the key result.
Using a dictionary as the return value is recommended, as it allows you to merge the results of multiple cascading
tasks.
Example Usage
from edwh import improved_task as task
@task(flags={"exclude": ["--exclude", "-x"], "as_json": ["--json"]}, hookable=True)
def process_data(ctx, exclude: str, as_json: bool = False):
# Task implementation here
return {
"data": [],
}
# other plugin (or local tasks.py) can now also specify 'process_data':
@task()
def process_data(ctx, exclude: str):
# the cascading function can choose whether to include the arguments `exclude` and `as_json` or not.
# this can be cherry-picked as long as the names match the arguments of the main function.
print(
ctx["result"] # will contain {"data": []}
)
License
edwh is distributed under the terms of the MIT license.
Changelog
1 maintainer
Metadata
1 maintainer
Release files for edwh 1.17.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| edwh-1.17.2.tar.gz | 91.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| edwh-1.17.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 188.8 kB
Release files / edwh-1.17.2.tar.gz
| Download URL | edwh-1.17.2.tar.gz |
|---|---|
| Size | 91.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9f15e09a231df0716bf8d9f10f7f906b8a7114aaf40d140062f3b8f7334b2d55
|
|
BLAKE2b-256 checksum How to use checksums |
88820e76b33549f6b349ec2cdd43d8516415721b36f4060068d6b7a826b529c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / edwh-1.17.2-py3-none-any.whl
| Download URL | edwh-1.17.2-py3-none-any.whl |
|---|---|
| Size | 97.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f66e326ecb0d86358fdbdd0389244b724c0fcc992e957c6c8e0dd864e5f82ed7
|
|
BLAKE2b-256 checksum How to use checksums |
a76bf8f980a0c9344256208e850a89e471094023cd2a1fad0faba7d9f2f2c43f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
