zoetty 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- zoetty-0.1.0/.github/workflows/ci.yml +62 -0
- zoetty-0.1.0/.gitignore +17 -0
- zoetty-0.1.0/.python-version +1 -0
- zoetty-0.1.0/CHANGELOG.md +11 -0
- zoetty-0.1.0/CLAUDE.md +9 -0
- zoetty-0.1.0/CODE_OF_CONDUCT.md +32 -0
- zoetty-0.1.0/CONTRIBUTING.md +144 -0
- zoetty-0.1.0/CONTRIBUTORS.md +3 -0
- zoetty-0.1.0/LICENSE +21 -0
- zoetty-0.1.0/Makefile +46 -0
- zoetty-0.1.0/PKG-INFO +145 -0
- zoetty-0.1.0/PUBLISHING.md +147 -0
- zoetty-0.1.0/README.md +124 -0
- zoetty-0.1.0/SECURITY.md +11 -0
- zoetty-0.1.0/docs/CHANGELOG.md +11 -0
- zoetty-0.1.0/docs/agents.md +54 -0
- zoetty-0.1.0/docs/cli.md +63 -0
- zoetty-0.1.0/docs/clip-format.md +134 -0
- zoetty-0.1.0/docs/clips/captures/quickstart-build.ansi +1 -0
- zoetty-0.1.0/docs/clips/captures/quickstart-check.ansi +1 -0
- zoetty-0.1.0/docs/clips/captures/quickstart-init.ansi +2 -0
- zoetty-0.1.0/docs/clips/captures/repl.ansi +6 -0
- zoetty-0.1.0/docs/clips/captures/zen.ansi +21 -0
- zoetty-0.1.0/docs/clips/hello.html +32 -0
- zoetty-0.1.0/docs/clips/hello.svg +42 -0
- zoetty-0.1.0/docs/clips/hello.toml +13 -0
- zoetty-0.1.0/docs/clips/quickstart.html +37 -0
- zoetty-0.1.0/docs/clips/quickstart.svg +55 -0
- zoetty-0.1.0/docs/clips/quickstart.toml +24 -0
- zoetty-0.1.0/docs/clips/repl.html +33 -0
- zoetty-0.1.0/docs/clips/repl.svg +47 -0
- zoetty-0.1.0/docs/clips/repl.toml +20 -0
- zoetty-0.1.0/docs/clips/steps.html +61 -0
- zoetty-0.1.0/docs/clips/steps.svg +125 -0
- zoetty-0.1.0/docs/clips/steps.toml +94 -0
- zoetty-0.1.0/docs/clips/zen.html +48 -0
- zoetty-0.1.0/docs/clips/zen.svg +92 -0
- zoetty-0.1.0/docs/clips/zen.toml +23 -0
- zoetty-0.1.0/docs/embedding.md +82 -0
- zoetty-0.1.0/docs/examples.md +65 -0
- zoetty-0.1.0/docs/index.md +69 -0
- zoetty-0.1.0/docs/install.md +33 -0
- zoetty-0.1.0/mkdocs.yml +53 -0
- zoetty-0.1.0/pyproject.toml +145 -0
- zoetty-0.1.0/specs/SPEC.md +154 -0
- zoetty-0.1.0/tasks/plan.md +46 -0
- zoetty-0.1.0/tasks/todo.md +77 -0
- zoetty-0.1.0/tests/conftest.py +23 -0
- zoetty-0.1.0/tests/test_ansi.py +64 -0
- zoetty-0.1.0/tests/test_cli.py +148 -0
- zoetty-0.1.0/tests/test_clip.py +224 -0
- zoetty-0.1.0/tests/test_docs.py +68 -0
- zoetty-0.1.0/tests/test_markup.py +51 -0
- zoetty-0.1.0/tests/test_record.py +84 -0
- zoetty-0.1.0/tests/test_render.py +120 -0
- zoetty-0.1.0/tests/test_timeline.py +153 -0
- zoetty-0.1.0/uv.lock +1257 -0
- zoetty-0.1.0/zoetty/__init__.py +0 -0
- zoetty-0.1.0/zoetty/ansi.py +70 -0
- zoetty-0.1.0/zoetty/cli.py +173 -0
- zoetty-0.1.0/zoetty/clip.py +272 -0
- zoetty-0.1.0/zoetty/html.py +91 -0
- zoetty-0.1.0/zoetty/markup.py +91 -0
- zoetty-0.1.0/zoetty/record.py +130 -0
- zoetty-0.1.0/zoetty/settings.py +3 -0
- zoetty-0.1.0/zoetty/svg.py +141 -0
- zoetty-0.1.0/zoetty/timeline.py +128 -0
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
name: CI - Lint and Test
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
build:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.12", "3.13", "3.14", "3.15-dev"]
|
|
15
|
+
steps:
|
|
16
|
+
#----------------------------------------------
|
|
17
|
+
# check-out repo and set-up python
|
|
18
|
+
#----------------------------------------------
|
|
19
|
+
- name: Check out repository
|
|
20
|
+
uses: actions/checkout@v7
|
|
21
|
+
- name: Set up python
|
|
22
|
+
id: setup-python
|
|
23
|
+
uses: actions/setup-python@v7
|
|
24
|
+
with:
|
|
25
|
+
python-version: ${{matrix.python-version}}
|
|
26
|
+
#----------------------------------------------
|
|
27
|
+
# ----- install & configure uv -----
|
|
28
|
+
#----------------------------------------------
|
|
29
|
+
# Pointing uv at the interpreter setup-python installed overrides .python-version,
|
|
30
|
+
# which would otherwise make every matrix entry run on 3.14.
|
|
31
|
+
- name: Install UV
|
|
32
|
+
uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
|
|
33
|
+
with:
|
|
34
|
+
python-version: ${{ steps.setup-python.outputs.python-path }}
|
|
35
|
+
enable-cache: true
|
|
36
|
+
cache-dependency-glob: "uv.lock"
|
|
37
|
+
|
|
38
|
+
#----------------------------------------------
|
|
39
|
+
# install dependencies
|
|
40
|
+
#----------------------------------------------
|
|
41
|
+
- name: Install dependencies
|
|
42
|
+
run: uv sync --frozen
|
|
43
|
+
- name: Show Python version
|
|
44
|
+
run: uv run python --version
|
|
45
|
+
#----------------------------------------------
|
|
46
|
+
# Run linting and tests
|
|
47
|
+
#----------------------------------------------
|
|
48
|
+
- name: Ruff format check
|
|
49
|
+
run: |
|
|
50
|
+
uv run ruff format --check .
|
|
51
|
+
- name: Ruff linting
|
|
52
|
+
run: |
|
|
53
|
+
uv run ruff check .
|
|
54
|
+
- name: Type check with ty
|
|
55
|
+
run: |
|
|
56
|
+
uv run ty check
|
|
57
|
+
- name: Check import contracts
|
|
58
|
+
run: |
|
|
59
|
+
make lint-imports
|
|
60
|
+
- name: Test with pytest
|
|
61
|
+
run: |
|
|
62
|
+
uv run pytest -vv --cov=zoetty --cov-branch --cov-report=term-missing --cov-config=pyproject.toml
|
zoetty-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
.venv/
|
|
2
|
+
.ty_cache/
|
|
3
|
+
.ruff_cache/
|
|
4
|
+
.import_linter_cache/
|
|
5
|
+
.pytest_cache/
|
|
6
|
+
.idea/
|
|
7
|
+
__pycache__
|
|
8
|
+
.DS_Store
|
|
9
|
+
dist/
|
|
10
|
+
site/
|
|
11
|
+
htmlcov/
|
|
12
|
+
*.coverage*
|
|
13
|
+
coverage.xml
|
|
14
|
+
.cache/
|
|
15
|
+
|
|
16
|
+
# Transcripts written by releasing zoetty with PUBLISHING.md
|
|
17
|
+
/logs/
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
3.14
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Change log
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
The first release.
|
|
6
|
+
|
|
7
|
+
- `zoetty init`, `record`, `build` and `check`.
|
|
8
|
+
- Clip specs in TOML: `[[run]]` sessions with recorded or hand-written output, or hand-timed `[[step]]`s.
|
|
9
|
+
- `zoetty record` runs commands in a pseudo-terminal the size of the clip, keeps their colours, types `input` after each prompt and ends with Ctrl-D.
|
|
10
|
+
- SVG output for READMEs and anywhere that takes images; HTML fragments for docs sites, safe to put several on one page.
|
|
11
|
+
- Long output wraps at `cols` and scrolls past `rows`. `[theme]` colours, optional window chrome, and reduced-motion support.
|
zoetty-0.1.0/CLAUDE.md
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
## Workflow
|
|
4
|
+
|
|
5
|
+
### Workflow for planned tasks
|
|
6
|
+
|
|
7
|
+
1. Read the plan, spec and todos, then present a short plan. STOP and wait for my approval.
|
|
8
|
+
2. Implement test-first in red-green slices. Keep 100% line and branch coverage.
|
|
9
|
+
3. Only tick checkboxes or approval boxes when I say so, or after CI is confirmed green.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# paulrun Code of Conduct
|
|
2
|
+
|
|
3
|
+
Like the technical community as a whole, the paulrun team and community is made up of a mixture of professionals and volunteers from all over the world, working on every aspect of the mission - including mentorship, teaching, and connecting people.
|
|
4
|
+
|
|
5
|
+
Diversity is one of our huge strengths, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to. This code applies equally to founders, mentors and those seeking help and guidance.
|
|
6
|
+
|
|
7
|
+
This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate.
|
|
8
|
+
|
|
9
|
+
This code of conduct applies to all spaces managed by the paulrun project or Paul Hallett. This includes the issue tracker, pull requests, discussions, and any other forums created by the project team which the community uses for communication. In addition, violations of this code outside these spaces may affect a person's ability to participate within them.
|
|
10
|
+
|
|
11
|
+
If you believe someone is violating the code of conduct, we ask that you report it by emailing [paulandrewhallett@gmail.com](mailto:paulandrewhallett@gmail.com).
|
|
12
|
+
|
|
13
|
+
- **Be friendly and patient.**
|
|
14
|
+
- **Be welcoming.** We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
|
|
15
|
+
- **Be considerate.** Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
|
|
16
|
+
- **Be respectful.** Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the paulrun community should be respectful when dealing with other members as well as with people outside the paulrun community.
|
|
17
|
+
- **Be careful in the words that you choose.** We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
|
|
18
|
+
- Violent threats or language directed against another person.
|
|
19
|
+
- Discriminatory jokes and language.
|
|
20
|
+
- Posting sexually explicit or violent material.
|
|
21
|
+
- Posting (or threatening to post) other people's personally identifying information ("doxing").
|
|
22
|
+
- Personal insults, especially those using racist or sexist terms.
|
|
23
|
+
- Unwelcome sexual attention.
|
|
24
|
+
- Advocating for, or encouraging, any of the above behavior.
|
|
25
|
+
- Repeated harassment of others. In general, if someone asks you to stop, then stop.
|
|
26
|
+
- **When we disagree, try to understand why.** Disagreements, both social and technical, happen all the time and paulrun is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of paulrun comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
|
|
27
|
+
|
|
28
|
+
Original text courtesy of the [Speak Up! project](http://web.archive.org/web/20141109123859/http://speakup.io/coc.html).
|
|
29
|
+
|
|
30
|
+
## Questions?
|
|
31
|
+
|
|
32
|
+
If you have questions, please see [CONTRIBUTING.md](CONTRIBUTING.md). If that doesn't answer your questions, feel free to [contact us](mailto:paulandrewhallett@gmail.com).
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
First things first: thank you for contributing! This project will be successful thanks to everyone who contributes, and we're happy to have you.
|
|
4
|
+
|
|
5
|
+
## AI disclosure
|
|
6
|
+
|
|
7
|
+
Within zoetty we use coding agents to prototype and build out ideas, and then take the idea to fruition using human reviewed and approved code.
|
|
8
|
+
|
|
9
|
+
You, the human and the author of changes are responsible for the contributions, and if you cannot confidently explain or demonstrate understanding of the changes you are contributing, then they will not be accepted.
|
|
10
|
+
|
|
11
|
+
## Bug or issue?
|
|
12
|
+
|
|
13
|
+
To raise a bug or issue please use [our GitHub](https://github.com/phalt/zoetty/issues).
|
|
14
|
+
|
|
15
|
+
Please check the issue has not been raised before by using the search feature.
|
|
16
|
+
|
|
17
|
+
When submitting an issue or bug, please make sure you provide thorough detail on:
|
|
18
|
+
|
|
19
|
+
1. The version of zoetty you are using (`zoetty --version`)
|
|
20
|
+
2. Your operating system and Python version
|
|
21
|
+
3. Any errors or outputs you see in your terminal
|
|
22
|
+
4. The smallest clip spec (and capture file, if there is one) that shows the problem. Take out any secrets first!
|
|
23
|
+
|
|
24
|
+
## Contribution
|
|
25
|
+
|
|
26
|
+
If you want to directly contribute you can do so in two ways:
|
|
27
|
+
|
|
28
|
+
1. Documentation
|
|
29
|
+
2. Code
|
|
30
|
+
|
|
31
|
+
### Documentation
|
|
32
|
+
|
|
33
|
+
We use [mkdocs](https://www.mkdocs.org/) and [GitHub pages](https://pages.github.com/) to deploy our docs.
|
|
34
|
+
|
|
35
|
+
Fixing grammar, spelling mistakes, or expanding the documentation to cover features that are not yet documented, are all valuable contributions.
|
|
36
|
+
|
|
37
|
+
Please see the **Set up** instructions below to run the docs locally on your computer, then:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
make docs-serve
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The examples in the docs and the README are tested, so if you change one, run `make test` too.
|
|
44
|
+
|
|
45
|
+
### Code
|
|
46
|
+
|
|
47
|
+
Contribution by writing code for new features, or fixing bugs, is a great way to contribute to the project.
|
|
48
|
+
|
|
49
|
+
Please [open an issue](https://github.com/phalt/zoetty/issues) to talk it through before changing the clip spec format (keys, markup or what `record` does), adding a command or flag, adding JavaScript to an output, or adding a dependency. These are hard to change once people's clips rely on them.
|
|
50
|
+
|
|
51
|
+
#### Set up
|
|
52
|
+
|
|
53
|
+
Clone the repo:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
git clone git@github.com:phalt/zoetty.git
|
|
57
|
+
cd zoetty
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Move to a feature branch:
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
git switch -c my-branch-name
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Install UV (if not already installed):
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
# On macOS and Linux:
|
|
70
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
71
|
+
|
|
72
|
+
# Or using pip:
|
|
73
|
+
pip install uv
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Install all the dependencies:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
make install
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
This will use UV to create a virtual environment and install all dependencies, including zoetty itself. UV handles the virtual environment automatically, so you don't need to manually activate it.
|
|
83
|
+
|
|
84
|
+
To make sure you have things set up correctly, please run the tests:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
make test
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
You can run your copy of zoetty with `uv run zoetty`, e.g. to rebuild the docs clips:
|
|
91
|
+
|
|
92
|
+
```sh
|
|
93
|
+
uv run zoetty build docs/clips/*.toml
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Run `make help` to see every command.
|
|
97
|
+
|
|
98
|
+
### Preparing changes for review
|
|
99
|
+
|
|
100
|
+
Once you've made changes, here's a good checklist to run through before publishing for review:
|
|
101
|
+
|
|
102
|
+
Format and lint the code:
|
|
103
|
+
|
|
104
|
+
```sh
|
|
105
|
+
make format
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Check the types:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
make ty
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Check the import contracts:
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
make lint-imports
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
[Import Linter](https://import-linter.readthedocs.io/) checks that modules only import in the directions we want: `zoetty.cli` sits on top and wires everything together, the renderers never import each other or the recorder, and only the CLI uses `click` and `rich`. The contracts, and the reasons for them, are under `[tool.importlinter]` in `pyproject.toml`. If one breaks, change the import rather than the contract.
|
|
121
|
+
|
|
122
|
+
Run the tests:
|
|
123
|
+
|
|
124
|
+
```sh
|
|
125
|
+
make test
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
New behaviour needs tests, and coverage stays at 100%. A new spec feature also gets an example in `docs/clips/` and on `docs/examples.md`.
|
|
129
|
+
|
|
130
|
+
If you've changed how clips are written or built, update `docs/clip-format.md` or `docs/cli.md` to match. If a change alters what zoetty draws, rebuild the docs clips with `uv run zoetty build docs/clips/*.toml`; a test fails if they're stale.
|
|
131
|
+
|
|
132
|
+
Make sure you add to `CHANGELOG.md` and `docs/CHANGELOG.md` what changes you have made. The two must be identical, and a test checks they are.
|
|
133
|
+
|
|
134
|
+
Make sure you add your name to `CONTRIBUTORS.md` as well!
|
|
135
|
+
|
|
136
|
+
### Making a pull request
|
|
137
|
+
|
|
138
|
+
Please push your changes up to a feature branch and make a new [pull request](https://github.com/phalt/zoetty/compare) on GitHub.
|
|
139
|
+
|
|
140
|
+
Please add a description to the PR and some information about why the change is being made.
|
|
141
|
+
|
|
142
|
+
After a review, you might need to make more changes.
|
|
143
|
+
|
|
144
|
+
Once accepted, a core contributor will merge your changes!
|
zoetty-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Paul Hallett
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
zoetty-0.1.0/Makefile
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
help:
|
|
2
|
+
@echo Developer commands for zoetty
|
|
3
|
+
@echo
|
|
4
|
+
@grep -E '^[ .a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
|
|
5
|
+
@echo
|
|
6
|
+
|
|
7
|
+
install: ## Install requirements ready for development
|
|
8
|
+
uv sync
|
|
9
|
+
|
|
10
|
+
deploy-docs: ## Build and deploy the documentation
|
|
11
|
+
uv run mkdocs build
|
|
12
|
+
uv run mkdocs gh-deploy
|
|
13
|
+
|
|
14
|
+
docs-serve: ## Run a local documentation server
|
|
15
|
+
uv run mkdocs serve
|
|
16
|
+
|
|
17
|
+
release: ## Build a new version and release it
|
|
18
|
+
uv build
|
|
19
|
+
uv publish
|
|
20
|
+
|
|
21
|
+
ty: ## Run a static syntax check
|
|
22
|
+
uv run ty check .
|
|
23
|
+
|
|
24
|
+
lint-imports: ## Check the import contracts in pyproject.toml
|
|
25
|
+
uv run lint-imports
|
|
26
|
+
|
|
27
|
+
format: ## Format the code correctly
|
|
28
|
+
uv run ruff format .
|
|
29
|
+
uv run ruff check --fix .
|
|
30
|
+
|
|
31
|
+
clean: ## Clear any cache files and test files
|
|
32
|
+
rm -rf .ty_cache
|
|
33
|
+
rm -rf .pytest_cache
|
|
34
|
+
rm -rf .ruff_cache
|
|
35
|
+
rm -rf .import_linter_cache
|
|
36
|
+
rm -rf site/
|
|
37
|
+
rm -rf dist/
|
|
38
|
+
find zoetty tests -name __pycache__ -prune -exec rm -rf {} +
|
|
39
|
+
rm -rf htmlcov/
|
|
40
|
+
rm -rf .coverage
|
|
41
|
+
|
|
42
|
+
test: ## Run tests
|
|
43
|
+
uv run pytest -vvv -x --cov=zoetty --cov-report=term-missing --cov-report=html --cov-config=pyproject.toml
|
|
44
|
+
|
|
45
|
+
shell: ## Run an ipython shell
|
|
46
|
+
uv run ipython
|
zoetty-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: zoetty
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Looping terminal demo clips as plain SVG or HTML and CSS
|
|
5
|
+
Project-URL: Homepage, https://github.com/phalt/zoetty
|
|
6
|
+
Project-URL: Documentation, https://phalt.github.io/zoetty/
|
|
7
|
+
Project-URL: Issues, https://github.com/phalt/zoetty/issues
|
|
8
|
+
Author-email: Paul Hallett <paulandrewhallett@gmail.com>
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: animation,cli,demo,docs,readme,svg,terminal
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Operating System :: MacOS
|
|
14
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
15
|
+
Classifier: Topic :: Documentation
|
|
16
|
+
Classifier: Topic :: Multimedia :: Graphics
|
|
17
|
+
Requires-Python: >=3.12
|
|
18
|
+
Requires-Dist: click>=8.5.0
|
|
19
|
+
Requires-Dist: rich>=15.0.0
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# ⚜ zoetty
|
|
23
|
+
|
|
24
|
+
## What is zoetty?
|
|
25
|
+
|
|
26
|
+
zoetty turns terminal sessions into small, looping, animated clips made of plain SVG or HTML and CSS. No video, no GIF, no JavaScript.
|
|
27
|
+
|
|
28
|
+
[](https://pypi.org/project/zoetty)
|
|
29
|
+

|
|
30
|
+

|
|
31
|
+
|
|
32
|
+

|
|
33
|
+
|
|
34
|
+
That's zoetty, recorded by zoetty. Every clip in this README is built from a spec in [`docs/clips/`](https://github.com/phalt/zoetty/tree/main/docs/clips).
|
|
35
|
+
|
|
36
|
+
## Why use zoetty?
|
|
37
|
+
|
|
38
|
+
Terminal GIFs go stale, weigh megabytes, look blurry, and have to be re-recorded by hand every time the output changes.
|
|
39
|
+
|
|
40
|
+
- **Real output** - `zoetty record` runs your commands in a real terminal and keeps their colours.
|
|
41
|
+
- **Small and sharp** - A clip is a few KB of text, crisp at any size.
|
|
42
|
+
- **Works in READMEs** - The SVG is just an image: it plays on GitHub, PyPI and anywhere else that shows one.
|
|
43
|
+
- **Or in your docs** - The HTML fragment drops into any page, with selectable text.
|
|
44
|
+
- **Kept in your repo** - The spec is a short TOML file. When your tool changes, re-record and rebuild.
|
|
45
|
+
- **Checked in CI** - `zoetty check` fails if a clip is out of date.
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
```sh
|
|
50
|
+
uv tool install zoetty
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Or with pip:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
pip install zoetty
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
zoetty needs Python 3.12 or later, and runs on **macOS and Linux**.
|
|
60
|
+
|
|
61
|
+
## Quick start
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
zoetty init docs/clips/hello.toml # write a starter spec
|
|
65
|
+
zoetty build docs/clips/hello.toml # render it to docs/clips/hello.svg
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Then put it in your README like any image:
|
|
69
|
+
|
|
70
|
+
```markdown
|
|
71
|
+

|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## A basic clip
|
|
75
|
+
|
|
76
|
+
Two commands, with their output written by hand:
|
|
77
|
+
|
|
78
|
+
```toml
|
|
79
|
+
title = "~/my-project"
|
|
80
|
+
label = "Typing two commands in a terminal: echo prints a greeting, ls lists three files"
|
|
81
|
+
cols = 60
|
|
82
|
+
|
|
83
|
+
[[run]]
|
|
84
|
+
cmd = "echo 'Hello from zoetty!'"
|
|
85
|
+
lines = ["Hello from zoetty!"]
|
|
86
|
+
|
|
87
|
+
[[run]]
|
|
88
|
+
cmd = "ls"
|
|
89
|
+
lines = ["[blue]docs[/] README.md [green]tool.py[/]"]
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+

|
|
93
|
+
|
|
94
|
+
## Recording real output
|
|
95
|
+
|
|
96
|
+
Give a run an `output` file and `zoetty record` runs the command for real and saves what it printed. `input` is typed into interactive programs, a line at a time, once each prompt is waiting:
|
|
97
|
+
|
|
98
|
+
```toml
|
|
99
|
+
title = "python"
|
|
100
|
+
label = "A Python REPL importing zoetty's markup parser and parsing some styled text"
|
|
101
|
+
cols = 64
|
|
102
|
+
|
|
103
|
+
[record]
|
|
104
|
+
env = { PYTHON_BASIC_REPL = "1" }
|
|
105
|
+
|
|
106
|
+
[[run]]
|
|
107
|
+
cmd = "python -q"
|
|
108
|
+
output = "captures/repl.ansi"
|
|
109
|
+
input = """
|
|
110
|
+
from zoetty.markup import parse, plain
|
|
111
|
+
plain(parse("[bold]zoe[/]tty"))
|
|
112
|
+
[s.styles for s in parse("[bold green]ok[/] done")]
|
|
113
|
+
"""
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
zoetty record docs/clips/repl.toml
|
|
118
|
+
zoetty build docs/clips/repl.toml
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+

|
|
122
|
+
|
|
123
|
+
Long output scrolls once it passes `rows`, and `[theme]` recolours the whole window:
|
|
124
|
+
|
|
125
|
+

|
|
126
|
+
|
|
127
|
+
See [more examples](https://phalt.github.io/zoetty/examples/), including the HTML output and hand-timed clips.
|
|
128
|
+
|
|
129
|
+
## Use it with your coding agent
|
|
130
|
+
|
|
131
|
+
zoetty is easy for coding agents to drive: specs are small text files, and every command says what it did. Paste this into Claude Code, Codex, Cursor or similar:
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
Use zoetty to add an animated terminal demo of this project to the README.
|
|
135
|
+
Read https://phalt.github.io/zoetty/agents/ first and follow it: install zoetty,
|
|
136
|
+
write a clip spec in docs/clips/ that shows the most useful commands, record the
|
|
137
|
+
real output with `zoetty record`, build it with `zoetty build`, look at the result,
|
|
138
|
+
embed the SVG in README.md, and add `zoetty check docs/clips/*.toml` to CI.
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Documentation
|
|
142
|
+
|
|
143
|
+
👉 Read the [full documentation](https://phalt.github.io/zoetty/) for the clip format, every command, embedding clips and more examples.
|
|
144
|
+
|
|
145
|
+
Want to help? See [CONTRIBUTING.md](https://github.com/phalt/zoetty/blob/main/CONTRIBUTING.md).
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Release zoetty
|
|
3
|
+
description: Release a new version of zoetty to GitHub, the docs site and PyPI.
|
|
4
|
+
output_path: logs/release-<VERSION>.md
|
|
5
|
+
inputs:
|
|
6
|
+
- name: VERSION
|
|
7
|
+
description: The version to release, e.g. 0.2.0
|
|
8
|
+
pattern: '^\d+\.\d+\.\d+$'
|
|
9
|
+
- name: UV_PUBLISH_TOKEN
|
|
10
|
+
description: PyPI API token for zoetty
|
|
11
|
+
secret: true
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# ⚜ Releasing zoetty
|
|
15
|
+
|
|
16
|
+
zoetty is released with [paulrun](https://github.com/phalt/paulrun), which runs this runbook:
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
uv tool install paulrun
|
|
20
|
+
paulrun check PUBLISHING.md
|
|
21
|
+
paulrun PUBLISHING.md --dry
|
|
22
|
+
paulrun PUBLISHING.md
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
You can also follow it by hand: each step's commands are in the order they run.
|
|
26
|
+
|
|
27
|
+
Before you start, add a `## <version>` section for the release to the top of
|
|
28
|
+
`CHANGELOG.md`, and copy it to `docs/CHANGELOG.md`. That change gets committed
|
|
29
|
+
with the version bump.
|
|
30
|
+
|
|
31
|
+
Each run is recorded in `logs/release-<version>.md`, which git ignores.
|
|
32
|
+
|
|
33
|
+
## Check before releasing
|
|
34
|
+
|
|
35
|
+
Releases are made from an up-to-date `main`, with nothing left uncommitted
|
|
36
|
+
except the changelog, for a version that hasn't been released yet.
|
|
37
|
+
|
|
38
|
+
```sh run
|
|
39
|
+
git switch main
|
|
40
|
+
git pull origin main
|
|
41
|
+
git fetch --tags
|
|
42
|
+
|
|
43
|
+
if [ -n "$(git status --porcelain -- . ':!CHANGELOG.md' ':!docs/CHANGELOG.md' ':!logs')" ]; then
|
|
44
|
+
echo "Commit or stash these changes first:"
|
|
45
|
+
git status --short
|
|
46
|
+
exit 1
|
|
47
|
+
fi
|
|
48
|
+
if git rev-parse --quiet --verify "refs/tags/<VERSION>" > /dev/null; then
|
|
49
|
+
echo "Tag <VERSION> already exists"
|
|
50
|
+
exit 1
|
|
51
|
+
fi
|
|
52
|
+
if ! grep -qx "## <VERSION>" CHANGELOG.md; then
|
|
53
|
+
echo "CHANGELOG.md has no '## <VERSION>' section"
|
|
54
|
+
exit 1
|
|
55
|
+
fi
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## Run the checks
|
|
59
|
+
|
|
60
|
+
The tests have to pass, but coverage isn't checked here: CI holds it at 100% on
|
|
61
|
+
Linux, and a few lines only run on Linux, so it reads a little lower on macOS.
|
|
62
|
+
|
|
63
|
+
```sh run
|
|
64
|
+
make ty
|
|
65
|
+
make lint-imports
|
|
66
|
+
uv run pytest -q
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Check the docs clips are up to date
|
|
70
|
+
|
|
71
|
+
The test suite checks this too, but it's worth seeing before a release.
|
|
72
|
+
|
|
73
|
+
```sh run
|
|
74
|
+
uv run zoetty check docs/clips/*.toml
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Update the version
|
|
78
|
+
|
|
79
|
+
`pyproject.toml` holds zoetty's only copy of its version. `uv version` sets
|
|
80
|
+
it and updates `uv.lock` to match.
|
|
81
|
+
|
|
82
|
+
```sh run
|
|
83
|
+
uv version <VERSION>
|
|
84
|
+
uv run zoetty --version
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Commit and push
|
|
88
|
+
|
|
89
|
+
There's nothing to commit if the version and changelog were already
|
|
90
|
+
committed, e.g. for the first release, or when rerunning one that failed
|
|
91
|
+
after this step.
|
|
92
|
+
|
|
93
|
+
```sh run
|
|
94
|
+
if git diff --quiet HEAD; then
|
|
95
|
+
echo "Nothing to commit"
|
|
96
|
+
else
|
|
97
|
+
git commit -am "version <VERSION>"
|
|
98
|
+
fi
|
|
99
|
+
git push origin main
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Tag the release
|
|
103
|
+
|
|
104
|
+
```sh run
|
|
105
|
+
git tag <VERSION>
|
|
106
|
+
git push origin <VERSION>
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
## Create the GitHub release
|
|
110
|
+
|
|
111
|
+
These are the release notes, from `CHANGELOG.md`:
|
|
112
|
+
|
|
113
|
+
```python run
|
|
114
|
+
import os
|
|
115
|
+
import re
|
|
116
|
+
from pathlib import Path
|
|
117
|
+
|
|
118
|
+
version = re.escape(os.environ["VERSION"])
|
|
119
|
+
changelog = Path("CHANGELOG.md").read_text()
|
|
120
|
+
notes = re.search(rf"^## {version}\n(.*?)(?=^## |\Z)", changelog, re.MULTILINE | re.DOTALL)
|
|
121
|
+
print(notes.group(1).strip())
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
```confirm
|
|
125
|
+
Create a release on GitHub from tag <VERSION>:
|
|
126
|
+
https://github.com/phalt/zoetty/releases/new?tag=<VERSION>
|
|
127
|
+
|
|
128
|
+
Paste in the release notes above, and mark it as the latest release.
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Publish the documentation
|
|
132
|
+
|
|
133
|
+
Takes about 5-10 minutes to deploy fully.
|
|
134
|
+
|
|
135
|
+
```sh run
|
|
136
|
+
make deploy-docs
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Release to PyPI
|
|
140
|
+
|
|
141
|
+
`uv publish` uploads everything in `dist/`, so clear it out first.
|
|
142
|
+
|
|
143
|
+
```sh run
|
|
144
|
+
rm -rf dist
|
|
145
|
+
# uv publish reads the token from $UV_PUBLISH_TOKEN.
|
|
146
|
+
make release
|
|
147
|
+
```
|