terminal-cells 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.
- terminal_cells-0.1.0/.gitattributes +5 -0
- terminal_cells-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +24 -0
- terminal_cells-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md +7 -0
- terminal_cells-0.1.0/.github/dependabot.yml +10 -0
- terminal_cells-0.1.0/.github/pull_request_template.md +9 -0
- terminal_cells-0.1.0/.github/workflows/ci.yml +77 -0
- terminal_cells-0.1.0/.github/workflows/publish.yml +128 -0
- terminal_cells-0.1.0/.gitignore +14 -0
- terminal_cells-0.1.0/CHANGELOG.md +68 -0
- terminal_cells-0.1.0/CONTRIBUTING.md +88 -0
- terminal_cells-0.1.0/LICENSE +12 -0
- terminal_cells-0.1.0/MANIFEST.in +7 -0
- terminal_cells-0.1.0/PKG-INFO +88 -0
- terminal_cells-0.1.0/README.md +181 -0
- terminal_cells-0.1.0/SECURITY.md +14 -0
- terminal_cells-0.1.0/cells +4 -0
- terminal_cells-0.1.0/cells.py +8 -0
- terminal_cells-0.1.0/docs/BIOLOGY.md +207 -0
- terminal_cells-0.1.0/docs/COLORS.md +51 -0
- terminal_cells-0.1.0/docs/INTERACTION.md +104 -0
- terminal_cells-0.1.0/docs/PYPI.md +63 -0
- terminal_cells-0.1.0/docs/RARE_EVENTS.md +70 -0
- terminal_cells-0.1.0/docs/RELEASING.md +196 -0
- terminal_cells-0.1.0/docs/TERMINALS.md +65 -0
- terminal_cells-0.1.0/docs/cells.1 +107 -0
- terminal_cells-0.1.0/docs/colors.svg +215 -0
- terminal_cells-0.1.0/docs/demo.gif +0 -0
- terminal_cells-0.1.0/docs/diversity.svg +761 -0
- terminal_cells-0.1.0/docs/ecology.svg +375 -0
- terminal_cells-0.1.0/docs/experiments.svg +174 -0
- terminal_cells-0.1.0/docs/ingestion.svg +2260 -0
- terminal_cells-0.1.0/docs/mitosis.svg +2020 -0
- terminal_cells-0.1.0/docs/phages.svg +273 -0
- terminal_cells-0.1.0/docs/preview.svg +436 -0
- terminal_cells-0.1.0/docs/sightings.svg +510 -0
- terminal_cells-0.1.0/pyproject.toml +54 -0
- terminal_cells-0.1.0/requirements-build.txt +6 -0
- terminal_cells-0.1.0/requirements-dev.txt +8 -0
- terminal_cells-0.1.0/setup.cfg +4 -0
- terminal_cells-0.1.0/terminal_cells/__init__.py +157 -0
- terminal_cells-0.1.0/terminal_cells/__main__.py +3 -0
- terminal_cells-0.1.0/terminal_cells/cli.py +558 -0
- terminal_cells-0.1.0/terminal_cells/event_render.py +121 -0
- terminal_cells-0.1.0/terminal_cells/events.py +356 -0
- terminal_cells-0.1.0/terminal_cells/interaction.py +242 -0
- terminal_cells-0.1.0/terminal_cells/lab.py +399 -0
- terminal_cells-0.1.0/terminal_cells/lab_render.py +58 -0
- terminal_cells-0.1.0/terminal_cells/models.py +471 -0
- terminal_cells-0.1.0/terminal_cells/render.py +996 -0
- terminal_cells-0.1.0/terminal_cells/world.py +1321 -0
- terminal_cells-0.1.0/terminal_cells.egg-info/PKG-INFO +88 -0
- terminal_cells-0.1.0/terminal_cells.egg-info/SOURCES.txt +69 -0
- terminal_cells-0.1.0/terminal_cells.egg-info/dependency_links.txt +1 -0
- terminal_cells-0.1.0/terminal_cells.egg-info/entry_points.txt +2 -0
- terminal_cells-0.1.0/terminal_cells.egg-info/top_level.txt +2 -0
- terminal_cells-0.1.0/tests/test_cells.py +1469 -0
- terminal_cells-0.1.0/tests/test_events.py +277 -0
- terminal_cells-0.1.0/tests/test_interaction.py +386 -0
- terminal_cells-0.1.0/tests/test_packaging.py +53 -0
- terminal_cells-0.1.0/tests/test_properties.py +75 -0
- terminal_cells-0.1.0/tests/test_scale.py +129 -0
- terminal_cells-0.1.0/tests/test_terminal.py +201 -0
- terminal_cells-0.1.0/tools/benchmark.py +38 -0
- terminal_cells-0.1.0/tools/check_dist.py +340 -0
- terminal_cells-0.1.0/tools/check_reproducible.py +54 -0
- terminal_cells-0.1.0/tools/colors.py +44 -0
- terminal_cells-0.1.0/tools/demo.py +97 -0
- terminal_cells-0.1.0/tools/experiments.py +56 -0
- terminal_cells-0.1.0/tools/manpage.py +70 -0
- terminal_cells-0.1.0/tools/preview.py +303 -0
- terminal_cells-0.1.0/tools/sightings.py +63 -0
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: Report an animation, simulation, installation, or terminal problem.
|
|
3
|
+
body:
|
|
4
|
+
- type: textarea
|
|
5
|
+
id: problem
|
|
6
|
+
attributes:
|
|
7
|
+
label: What happened?
|
|
8
|
+
description: Describe what you expected and what you saw instead.
|
|
9
|
+
validations:
|
|
10
|
+
required: true
|
|
11
|
+
- type: textarea
|
|
12
|
+
id: environment
|
|
13
|
+
attributes:
|
|
14
|
+
label: Environment
|
|
15
|
+
description: Include cells --diagnostics output, your terminal application, and whether it has a light or dark background.
|
|
16
|
+
validations:
|
|
17
|
+
required: true
|
|
18
|
+
- type: textarea
|
|
19
|
+
id: reproduce
|
|
20
|
+
attributes:
|
|
21
|
+
label: Reproduction
|
|
22
|
+
description: Include the command, seed, approximate simulation time, and any resize or key input. A screenshot or recording is useful for visual issues.
|
|
23
|
+
validations:
|
|
24
|
+
required: true
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Feature request
|
|
3
|
+
about: Suggest an organism, interaction, accessibility improvement, or other change.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Describe the behavior you would like and how it would look or feel in a terminal.
|
|
7
|
+
For biological behavior, reference microscope imagery or a source when useful.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: ["**"]
|
|
6
|
+
pull_request:
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
workflow_call:
|
|
9
|
+
|
|
10
|
+
permissions:
|
|
11
|
+
contents: read
|
|
12
|
+
|
|
13
|
+
jobs:
|
|
14
|
+
tests:
|
|
15
|
+
name: ${{ matrix.os }} / Python ${{ matrix.python }}
|
|
16
|
+
runs-on: ${{ matrix.os }}
|
|
17
|
+
timeout-minutes: 10
|
|
18
|
+
strategy:
|
|
19
|
+
fail-fast: false
|
|
20
|
+
matrix:
|
|
21
|
+
os: [ubuntu-latest, macos-latest]
|
|
22
|
+
python: ["3.10", "3.11", "3.12", "3.13", "3.14"]
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
25
|
+
with:
|
|
26
|
+
persist-credentials: false
|
|
27
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
28
|
+
with:
|
|
29
|
+
python-version: ${{ matrix.python }}
|
|
30
|
+
- name: Install test tools
|
|
31
|
+
run: python -m pip install "hypothesis>=6.100" "ruff==0.17.4"
|
|
32
|
+
- name: Lint and formatting
|
|
33
|
+
run: |
|
|
34
|
+
ruff check .
|
|
35
|
+
ruff format --check .
|
|
36
|
+
- name: Run simulation, CLI, and pseudo-terminal tests
|
|
37
|
+
run: python -m unittest discover -s tests -v
|
|
38
|
+
- name: Install package build tools
|
|
39
|
+
run: python -m pip install build "setuptools>=77" wheel
|
|
40
|
+
- name: Build a wheel on this platform
|
|
41
|
+
run: python -m build --wheel --outdir "${{ runner.temp }}/cells-wheel"
|
|
42
|
+
- name: Check an isolated installed wheel outside the checkout
|
|
43
|
+
run: python tools/check_dist.py --wheel-only --dist "${{ runner.temp }}/cells-wheel"
|
|
44
|
+
|
|
45
|
+
distributions:
|
|
46
|
+
name: Build and verify distributions
|
|
47
|
+
needs: tests
|
|
48
|
+
runs-on: ubuntu-latest
|
|
49
|
+
timeout-minutes: 15
|
|
50
|
+
steps:
|
|
51
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
52
|
+
with:
|
|
53
|
+
persist-credentials: false
|
|
54
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
55
|
+
with:
|
|
56
|
+
python-version: "3.14"
|
|
57
|
+
- run: python -m pip install -r requirements-dev.txt
|
|
58
|
+
- run: python -m pip install -r requirements-build.txt
|
|
59
|
+
- name: Set reproducible build timestamp
|
|
60
|
+
run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
|
|
61
|
+
- run: python -m build --no-isolation
|
|
62
|
+
- run: python tools/check_reproducible.py
|
|
63
|
+
- run: python -m twine check --strict dist/*.whl dist/*.tar.gz
|
|
64
|
+
- name: Test source archive and isolated installed wheels
|
|
65
|
+
run: python tools/check_dist.py
|
|
66
|
+
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
67
|
+
with:
|
|
68
|
+
name: distributions
|
|
69
|
+
path: |
|
|
70
|
+
dist/*.whl
|
|
71
|
+
dist/*.tar.gz
|
|
72
|
+
if-no-files-found: error
|
|
73
|
+
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
74
|
+
with:
|
|
75
|
+
name: distribution-checksums
|
|
76
|
+
path: dist/SHA256SUMS
|
|
77
|
+
if-no-files-found: error
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
workflow_dispatch:
|
|
5
|
+
inputs:
|
|
6
|
+
target:
|
|
7
|
+
description: Package index
|
|
8
|
+
type: choice
|
|
9
|
+
options: [testpypi, pypi]
|
|
10
|
+
default: testpypi
|
|
11
|
+
required: true
|
|
12
|
+
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
|
|
16
|
+
jobs:
|
|
17
|
+
release-ref:
|
|
18
|
+
name: Validate release selection
|
|
19
|
+
runs-on: ubuntu-latest
|
|
20
|
+
timeout-minutes: 5
|
|
21
|
+
outputs:
|
|
22
|
+
version: ${{ steps.version.outputs.version }}
|
|
23
|
+
steps:
|
|
24
|
+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
|
25
|
+
with:
|
|
26
|
+
persist-credentials: false
|
|
27
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
28
|
+
with:
|
|
29
|
+
python-version: "3.14"
|
|
30
|
+
- name: Production releases require a matching version tag
|
|
31
|
+
id: version
|
|
32
|
+
env:
|
|
33
|
+
RELEASE_TARGET: ${{ inputs.target }}
|
|
34
|
+
run: |
|
|
35
|
+
python - <<'PY'
|
|
36
|
+
import os
|
|
37
|
+
import cells
|
|
38
|
+
target = os.environ['RELEASE_TARGET']
|
|
39
|
+
if target not in ('testpypi', 'pypi'):
|
|
40
|
+
raise SystemExit('Unsupported package index')
|
|
41
|
+
if target == 'pypi' and os.environ['GITHUB_REF'] != f'refs/tags/v{cells.__version__}':
|
|
42
|
+
raise SystemExit(f'Production publishing requires tag v{cells.__version__}')
|
|
43
|
+
print(f'Preparing {cells.__version__} for {target}')
|
|
44
|
+
with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
|
|
45
|
+
output.write(f'version={cells.__version__}\n')
|
|
46
|
+
PY
|
|
47
|
+
|
|
48
|
+
verify:
|
|
49
|
+
needs: release-ref
|
|
50
|
+
uses: ./.github/workflows/ci.yml
|
|
51
|
+
permissions:
|
|
52
|
+
contents: read
|
|
53
|
+
|
|
54
|
+
publish:
|
|
55
|
+
name: Upload verified distributions
|
|
56
|
+
needs: [release-ref, verify]
|
|
57
|
+
runs-on: ubuntu-latest
|
|
58
|
+
timeout-minutes: 10
|
|
59
|
+
environment:
|
|
60
|
+
name: ${{ inputs.target }}
|
|
61
|
+
permissions:
|
|
62
|
+
actions: read
|
|
63
|
+
id-token: write
|
|
64
|
+
steps:
|
|
65
|
+
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
|
66
|
+
with:
|
|
67
|
+
name: distributions
|
|
68
|
+
path: dist/
|
|
69
|
+
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
|
70
|
+
with:
|
|
71
|
+
name: distribution-checksums
|
|
72
|
+
path: checksums/
|
|
73
|
+
- name: Verify exactly the tested archives before upload
|
|
74
|
+
run: |
|
|
75
|
+
python - <<'PY'
|
|
76
|
+
import hashlib
|
|
77
|
+
from pathlib import Path
|
|
78
|
+
directory = Path('dist')
|
|
79
|
+
entries = [line.split() for line in Path('checksums/SHA256SUMS').read_text().splitlines()]
|
|
80
|
+
names = [name for digest, name in entries]
|
|
81
|
+
if len(names) != 2 or len(set(names)) != 2 or set(names) != {p.name for p in directory.iterdir()}:
|
|
82
|
+
raise SystemExit('Expected exactly the verified wheel and source archive')
|
|
83
|
+
for digest, name in entries:
|
|
84
|
+
if Path(name).name != name or hashlib.sha256((directory / name).read_bytes()).hexdigest() != digest:
|
|
85
|
+
raise SystemExit('Distribution checksum mismatch')
|
|
86
|
+
print('Verified both distribution checksums')
|
|
87
|
+
PY
|
|
88
|
+
- name: Publish using the configured Trusted Publisher
|
|
89
|
+
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
|
|
90
|
+
with:
|
|
91
|
+
packages-dir: dist/
|
|
92
|
+
repository-url: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
|
|
93
|
+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
|
|
94
|
+
with:
|
|
95
|
+
python-version: "3.14"
|
|
96
|
+
- name: Install the published wheel in a fresh environment
|
|
97
|
+
env:
|
|
98
|
+
RELEASE_VERSION: ${{ needs.release-ref.outputs.version }}
|
|
99
|
+
INDEX_URL: ${{ inputs.target == 'testpypi' && 'https://test.pypi.org/simple/' || 'https://pypi.org/simple/' }}
|
|
100
|
+
run: |
|
|
101
|
+
python - <<'PY'
|
|
102
|
+
import os
|
|
103
|
+
from pathlib import Path
|
|
104
|
+
import subprocess
|
|
105
|
+
import sys
|
|
106
|
+
import tempfile
|
|
107
|
+
with tempfile.TemporaryDirectory() as directory:
|
|
108
|
+
root = Path(directory)
|
|
109
|
+
environment = root / 'venv'
|
|
110
|
+
subprocess.run([sys.executable, '-m', 'venv', str(environment)], check=True)
|
|
111
|
+
python = environment / 'bin/python'
|
|
112
|
+
version = os.environ['RELEASE_VERSION']
|
|
113
|
+
subprocess.run([
|
|
114
|
+
str(python), '-m', 'pip', 'install', '--no-cache-dir', '--no-deps',
|
|
115
|
+
'--only-binary=:all:', '--index-url', os.environ['INDEX_URL'],
|
|
116
|
+
f'terminal-cells=={version}',
|
|
117
|
+
], cwd=root, check=True)
|
|
118
|
+
command = str(environment / 'bin/cells')
|
|
119
|
+
result = subprocess.check_output([command, '--version'], cwd=root, text=True)
|
|
120
|
+
if result.strip() != f'cells {version}':
|
|
121
|
+
raise SystemExit(f'Unexpected installed version: {result!r}')
|
|
122
|
+
snapshot = subprocess.check_output([
|
|
123
|
+
command, '--snapshot', '--seed', '42', '--size', '80x24',
|
|
124
|
+
], cwd=root, text=True)
|
|
125
|
+
if len(snapshot.splitlines()) != 24 or not snapshot.strip():
|
|
126
|
+
raise SystemExit('Published installation produced an invalid snapshot')
|
|
127
|
+
print(f'Installed and exercised terminal-cells {version} from the selected index')
|
|
128
|
+
PY
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
## 0.1.0 — 2026-11-16
|
|
6
|
+
|
|
7
|
+
First release. Published to TestPyPI and prepared for production PyPI.
|
|
8
|
+
|
|
9
|
+
- Let immune cells crawl against ordinary slide flow and turn away from screen
|
|
10
|
+
edges instead of accumulating at the right boundary.
|
|
11
|
+
- Hide microscope-tool instructions in ambient help and space interactive tools,
|
|
12
|
+
targeting controls, and the species legend into separate groups.
|
|
13
|
+
|
|
14
|
+
- Fix animation freezing on mouse release: receive release events from curses
|
|
15
|
+
and discard them without applying a second tool action.
|
|
16
|
+
- Add opt-in `--interactive` mode with Inspect, Lyse, Feed, and Stir tools, a
|
|
17
|
+
single-line `? help` footer, visible selection, left-click input, and keyboard targeting.
|
|
18
|
+
- Add immediate rupture with organelle debris, red-cell ghosts, local fungal cuts,
|
|
19
|
+
assembly-aware viral release, and containment of disrupted phagosome contents.
|
|
20
|
+
- Add bounded local stirring and clear-fluid food deposits; restore mouse settings
|
|
21
|
+
on every exit and retain unattended/snapshot behavior.
|
|
22
|
+
- Make tool effects immediate without freezing targets; strengthen stirring,
|
|
23
|
+
move particles at the click center, and carry capsids and rupture debris.
|
|
24
|
+
- Add tool/terminal/property tests and an illustrated interactive guide.
|
|
25
|
+
|
|
26
|
+
- Add rare rotifer feeding visits, destructive neutrophil DNA traps, and nutrient
|
|
27
|
+
micropipettes with seeded scheduling, cooldowns, and bounded population effects.
|
|
28
|
+
- Pace interactive sightings by unpaused wall time; add `--no-events`, captions,
|
|
29
|
+
and calm-mode exclusion of microscope interventions.
|
|
30
|
+
- Review every palette: distinguish all microbial body hues, reserve red/lime
|
|
31
|
+
for red cells/phages, and add coral/lilac/gray rare-event identities.
|
|
32
|
+
- Render the help legend in the active palette and add complete color/sighting
|
|
33
|
+
guides and reproducible preview generators.
|
|
34
|
+
|
|
35
|
+
- Enlarge macrophages by about 18% where space permits, keeping neutrophils
|
|
36
|
+
and compact-terminal fitting unchanged.
|
|
37
|
+
- Render phages as compact directional Runic/ASCII glyphs, shrink their
|
|
38
|
+
collision footprint, and use the host outline for infection contact.
|
|
39
|
+
- Preserve genome injection, replication, assembly, and lysis with compact phages.
|
|
40
|
+
|
|
41
|
+
- Adopt Zero-Clause BSD (`0BSD`) for the project, package metadata, and
|
|
42
|
+
contributions, without requiring downstream attribution or copyleft.
|
|
43
|
+
|
|
44
|
+
- Split models, simulation, rendering, and CLI into `terminal_cells` modules;
|
|
45
|
+
preserve source-checkout entry points.
|
|
46
|
+
- Add blood/microbial scenes, calm defaults, light theme, observation captions,
|
|
47
|
+
startup statistics, explicit color/Unicode policies, and JSON diagnostics.
|
|
48
|
+
- Keep help, version, snapshots, and diagnostics usable without curses.
|
|
49
|
+
- Correct empty `NO_COLOR` handling; support scrolling in short help windows.
|
|
50
|
+
- Honor duration expiry even at low display rates.
|
|
51
|
+
- Bound catch-up/input work and remove duplicate cell-outline calculations.
|
|
52
|
+
- Add fake-terminal and generated resize/lifecycle tests, Ruff checks, benchmarks,
|
|
53
|
+
biology references, terminal guidance, and a manual page.
|
|
54
|
+
- Pin release action commits and build tools; check byte-identical wheel rebuilds.
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
- A Python/curses microscope slide with macrophages, neutrophils, red blood
|
|
58
|
+
cells, nine microbial types, fungal networks, and bacteriophages.
|
|
59
|
+
- Staged mitosis, phagocytosis, digestion, budding, longitudinal fission,
|
|
60
|
+
organelle inheritance, and viral infection through lysis.
|
|
61
|
+
- Nutrient gathering, fungal highways, selective escape, and population-aware
|
|
62
|
+
arrivals that enter gradually from outside the screen.
|
|
63
|
+
- Seeded simulation, pause and speed controls, three color themes, ASCII mode,
|
|
64
|
+
screensaver mode, and headless snapshots.
|
|
65
|
+
- Python 3.10+ on Linux and macOS; Windows users can run through WSL.
|
|
66
|
+
|
|
67
|
+
- Add project URLs, cover all supported Python versions in CI, reject stale
|
|
68
|
+
package builds, and verify archive checksums again before publishing.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Small improvements to animation, organism behavior, accessibility, performance,
|
|
4
|
+
and platform support are welcome. This is a biological illustration: shapes and
|
|
5
|
+
timings are exaggerated so they remain readable in a terminal.
|
|
6
|
+
|
|
7
|
+
## Local setup
|
|
8
|
+
|
|
9
|
+
Use Python 3.10+ with curses on Linux or macOS, or inside WSL. Runtime code uses
|
|
10
|
+
only the standard library. Work in an isolated environment for development:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
python3 -m venv .venv
|
|
14
|
+
. .venv/bin/activate
|
|
15
|
+
python -m pip install -r requirements-dev.txt
|
|
16
|
+
python -m pip install --no-deps -e .
|
|
17
|
+
ruff check .
|
|
18
|
+
ruff format --check .
|
|
19
|
+
python -m unittest discover -s tests -v
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
Run `./cells --seed 42` to explore interactively, or use a reproducible snapshot:
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
cells --snapshot --seed 42 --size 100x32 --at 30
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Making changes
|
|
29
|
+
|
|
30
|
+
- Keep data/geometry in `terminal_cells/models.py`, updates in `world.py`,
|
|
31
|
+
pure drawing in `render.py`, and terminal/argument handling in `cli.py`.
|
|
32
|
+
Drawing must not mutate the world or consume its random number generator.
|
|
33
|
+
- Use `world.rng` for simulation randomness. Within a program version, a seed, size, and sequence of
|
|
34
|
+
simulation steps must reproduce the same world.
|
|
35
|
+
- Respect membrane boundaries, ownership during capture, and population caps.
|
|
36
|
+
- Preserve ASCII, colorless, and small-terminal behavior when changing visuals.
|
|
37
|
+
- Add focused regression tests for behavior changes. Use simulated time rather
|
|
38
|
+
than sleeping; pseudo-terminal tests cover terminal interaction and cleanup.
|
|
39
|
+
|
|
40
|
+
Run the test suite before submitting a pull request. For visible changes,
|
|
41
|
+
include a screenshot or short recording and the seed, size, and simulation time.
|
|
42
|
+
Regenerate relevant previews with `python tools/preview.py`. To regenerate the
|
|
43
|
+
animated demo, run `python tools/demo.py`; Pillow is a development dependency.
|
|
44
|
+
The generator uses Noto Sans Runic or FreeMono when available for compact phages;
|
|
45
|
+
use `--symbol-font PATH` to supply a Runic-capable font on other systems.
|
|
46
|
+
|
|
47
|
+
For packaging changes, run the release validation commands in
|
|
48
|
+
[the release guide](docs/RELEASING.md). The source archive and installed wheel
|
|
49
|
+
must work outside the repository.
|
|
50
|
+
|
|
51
|
+
## Reporting issues
|
|
52
|
+
|
|
53
|
+
Include the program version (`cells --version`), operating system, Python
|
|
54
|
+
version, terminal application, terminal size, and any relevant flags. A seed
|
|
55
|
+
and approximate simulation time make animation problems much easier to reproduce.
|
|
56
|
+
Native Windows support is not yet claimed; identify WSL separately from Windows.
|
|
57
|
+
|
|
58
|
+
Submit a focused pull request describing the problem, resulting behavior, and
|
|
59
|
+
validation. Contributions are accepted under the same [Zero-Clause BSD license](LICENSE)
|
|
60
|
+
(SPDX: `0BSD`) as the project. By submitting a contribution, you license it under
|
|
61
|
+
those terms. No copyright assignment or separate contributor license agreement
|
|
62
|
+
is required. Only submit work you have the right to contribute, and identify any
|
|
63
|
+
third-party material and its applicable terms.
|
|
64
|
+
|
|
65
|
+
## Generated tests and performance
|
|
66
|
+
|
|
67
|
+
Hypothesis explores seeded update/resize sequences, including tiny windows and
|
|
68
|
+
scene presets. It checks finite geometry, population bounds, determinism, and
|
|
69
|
+
rendering purity. The optional test is skipped when Hypothesis is absent; CI
|
|
70
|
+
installs it. Preserve regressions as focused ordinary tests if an example exposes
|
|
71
|
+
a bug. `python tools/benchmark.py` reports update/render p50 and p95 latencies;
|
|
72
|
+
it excludes terminal output and does not impose hardware-dependent test limits.
|
|
73
|
+
|
|
74
|
+
Regenerate `docs/cells.1` with `python tools/manpage.py` after changing CLI help.
|
|
75
|
+
Run `ruff format .` before submitting formatting changes. `cells.py` and the
|
|
76
|
+
`cells` executable remain source-checkout entry points; installed commands use
|
|
77
|
+
`terminal_cells.cli:main`. Curses is imported only when interactive mode starts.
|
|
78
|
+
|
|
79
|
+
Rare-event state and behavior live in `terminal_cells/events.py`; drawings live
|
|
80
|
+
in `event_render.py`. Keep event scheduling on the director's seeded RNG and
|
|
81
|
+
interactive wall-time clock, independent of simulation speed. Regenerate
|
|
82
|
+
`tools/sightings.py` and `tools/colors.py` previews when changing events or inks.
|
|
83
|
+
|
|
84
|
+
Experimental tools keep model effects in `terminal_cells/lab.py`, input and the
|
|
85
|
+
targeting and single-line footer in `interaction.py`, and pure drawing in
|
|
86
|
+
`lab_render.py`. Preserve compartment ownership, immediate rupture, bounded
|
|
87
|
+
feedback, and mouse restoration
|
|
88
|
+
on every exit path. `python tools/experiments.py` regenerates the tool previews.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
Zero-Clause BSD
|
|
2
|
+
|
|
3
|
+
Permission to use, copy, modify, and/or distribute this software for
|
|
4
|
+
any purpose with or without fee is hereby granted.
|
|
5
|
+
|
|
6
|
+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
|
|
7
|
+
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES
|
|
8
|
+
OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE
|
|
9
|
+
FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY
|
|
10
|
+
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
|
|
11
|
+
AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
|
|
12
|
+
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
include cells LICENSE README.md CHANGELOG.md CONTRIBUTING.md requirements-dev.txt requirements-build.txt SECURITY.md
|
|
2
|
+
include .gitignore .gitattributes
|
|
3
|
+
recursive-include docs *.md *.svg *.gif *.1
|
|
4
|
+
recursive-include tests *.py
|
|
5
|
+
recursive-include tools *.py
|
|
6
|
+
recursive-include .github *.yml *.md
|
|
7
|
+
global-exclude __pycache__ *.py[cod] .DS_Store
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: terminal-cells
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A living microscope slide in your terminal
|
|
5
|
+
Author: cells contributors
|
|
6
|
+
License-Expression: 0BSD
|
|
7
|
+
Project-URL: Homepage, https://github.com/kborer/cells
|
|
8
|
+
Project-URL: Repository, https://github.com/kborer/cells
|
|
9
|
+
Project-URL: Issues, https://github.com/kborer/cells/issues
|
|
10
|
+
Project-URL: Documentation, https://github.com/kborer/cells#readme
|
|
11
|
+
Project-URL: Changelog, https://github.com/kborer/cells/blob/main/CHANGELOG.md
|
|
12
|
+
Keywords: terminal,screensaver,microscopy,biology,ascii
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Environment :: Console :: Curses
|
|
15
|
+
Classifier: Operating System :: POSIX
|
|
16
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
17
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Topic :: Games/Entertainment :: Simulation
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
# cells
|
|
27
|
+
|
|
28
|
+
A living microscope slide in your terminal, inspired by the quiet procedural
|
|
29
|
+
animation of cbonsai and asciiquarium.
|
|
30
|
+
|
|
31
|
+
Macrophages and neutrophils pursue microbes, wrap them in membrane cups, and
|
|
32
|
+
digest them. Bacterial chains, spirochetes, vibrios, coccal colonies, budding
|
|
33
|
+
yeast, and trypanosomes share the slide with red blood cells, branching fungi,
|
|
34
|
+
and bacteriophages. Watch mitosis, viral replication and lysis, nutrient
|
|
35
|
+
gathering, and swimmers following fungal branches. Occasional arrivals keep
|
|
36
|
+
long runs varied. Rare rotifer visitors, neutrophil DNA traps, and nutrient
|
|
37
|
+
micropipettes add occasional longer vignettes. Use `--observe` for captions or
|
|
38
|
+
`--no-events` to disable them; `--calm` excludes micropipettes.
|
|
39
|
+
|
|
40
|
+
This is biological illustration with exaggerated sizes and timing, rather than
|
|
41
|
+
a scientific model.
|
|
42
|
+
|
|
43
|
+
## Installation
|
|
44
|
+
|
|
45
|
+
Python 3.10+ with the standard-library curses module is required. Linux and
|
|
46
|
+
macOS are supported platforms; Windows users should use WSL. There are no
|
|
47
|
+
third-party runtime dependencies. Some Linux distributions package curses
|
|
48
|
+
separately.
|
|
49
|
+
|
|
50
|
+
Install a published release in its own environment with pipx:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
pipx install terminal-cells
|
|
54
|
+
cells
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
The distribution is named `terminal-cells`; its executable is `cells`.
|
|
58
|
+
|
|
59
|
+
## Examples
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
cells --seed 42
|
|
63
|
+
cells --theme amber --speed 0.7
|
|
64
|
+
cells --ascii --screensaver
|
|
65
|
+
cells --scene microbial --calm
|
|
66
|
+
cells --theme light --observe
|
|
67
|
+
cells --diagnostics
|
|
68
|
+
cells --interactive
|
|
69
|
+
cells --snapshot --seed 42 --size 100x32 --at 30
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Use a terminal of at least 80 columns by 24 rows; 120 by 40 gives the detailed
|
|
73
|
+
organisms more space. `--theme mono` selects grayscale, and `NO_COLOR=1`
|
|
74
|
+
disables colors in automatic mode; `--color always` overrides it. Use
|
|
75
|
+
`--color never` to explicitly disable colors. Snapshots are plain ASCII and work without an interactive
|
|
76
|
+
terminal, including Python builds without curses.
|
|
77
|
+
|
|
78
|
+
Press `q` or Escape to quit, Space to pause, `+`/`-` to change speed, `r` for a
|
|
79
|
+
new slide, `s` for observations, and `?` for help with a colored species legend. Screensaver mode exits on any
|
|
80
|
+
key. Terminal resizing is supported.
|
|
81
|
+
|
|
82
|
+
Opt into microscope tools with `--interactive`: 1 Inspect, 2 Lyse, 3 Feed, and
|
|
83
|
+
4 Stir. Left-click or use arrows/hjkl, Tab, and Enter. A single bottom line shows
|
|
84
|
+
`? help`, leaving the rest of the screen for animation. Tools apply immediately;
|
|
85
|
+
keyboard targeting also works when mouse reporting is unavailable.
|
|
86
|
+
|
|
87
|
+
Released under Zero-Clause BSD (SPDX: `0BSD`). Attribution and copyleft are not
|
|
88
|
+
required for downstream use or redistribution.
|