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.
Files changed (71) hide show
  1. terminal_cells-0.1.0/.gitattributes +5 -0
  2. terminal_cells-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +24 -0
  3. terminal_cells-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md +7 -0
  4. terminal_cells-0.1.0/.github/dependabot.yml +10 -0
  5. terminal_cells-0.1.0/.github/pull_request_template.md +9 -0
  6. terminal_cells-0.1.0/.github/workflows/ci.yml +77 -0
  7. terminal_cells-0.1.0/.github/workflows/publish.yml +128 -0
  8. terminal_cells-0.1.0/.gitignore +14 -0
  9. terminal_cells-0.1.0/CHANGELOG.md +68 -0
  10. terminal_cells-0.1.0/CONTRIBUTING.md +88 -0
  11. terminal_cells-0.1.0/LICENSE +12 -0
  12. terminal_cells-0.1.0/MANIFEST.in +7 -0
  13. terminal_cells-0.1.0/PKG-INFO +88 -0
  14. terminal_cells-0.1.0/README.md +181 -0
  15. terminal_cells-0.1.0/SECURITY.md +14 -0
  16. terminal_cells-0.1.0/cells +4 -0
  17. terminal_cells-0.1.0/cells.py +8 -0
  18. terminal_cells-0.1.0/docs/BIOLOGY.md +207 -0
  19. terminal_cells-0.1.0/docs/COLORS.md +51 -0
  20. terminal_cells-0.1.0/docs/INTERACTION.md +104 -0
  21. terminal_cells-0.1.0/docs/PYPI.md +63 -0
  22. terminal_cells-0.1.0/docs/RARE_EVENTS.md +70 -0
  23. terminal_cells-0.1.0/docs/RELEASING.md +196 -0
  24. terminal_cells-0.1.0/docs/TERMINALS.md +65 -0
  25. terminal_cells-0.1.0/docs/cells.1 +107 -0
  26. terminal_cells-0.1.0/docs/colors.svg +215 -0
  27. terminal_cells-0.1.0/docs/demo.gif +0 -0
  28. terminal_cells-0.1.0/docs/diversity.svg +761 -0
  29. terminal_cells-0.1.0/docs/ecology.svg +375 -0
  30. terminal_cells-0.1.0/docs/experiments.svg +174 -0
  31. terminal_cells-0.1.0/docs/ingestion.svg +2260 -0
  32. terminal_cells-0.1.0/docs/mitosis.svg +2020 -0
  33. terminal_cells-0.1.0/docs/phages.svg +273 -0
  34. terminal_cells-0.1.0/docs/preview.svg +436 -0
  35. terminal_cells-0.1.0/docs/sightings.svg +510 -0
  36. terminal_cells-0.1.0/pyproject.toml +54 -0
  37. terminal_cells-0.1.0/requirements-build.txt +6 -0
  38. terminal_cells-0.1.0/requirements-dev.txt +8 -0
  39. terminal_cells-0.1.0/setup.cfg +4 -0
  40. terminal_cells-0.1.0/terminal_cells/__init__.py +157 -0
  41. terminal_cells-0.1.0/terminal_cells/__main__.py +3 -0
  42. terminal_cells-0.1.0/terminal_cells/cli.py +558 -0
  43. terminal_cells-0.1.0/terminal_cells/event_render.py +121 -0
  44. terminal_cells-0.1.0/terminal_cells/events.py +356 -0
  45. terminal_cells-0.1.0/terminal_cells/interaction.py +242 -0
  46. terminal_cells-0.1.0/terminal_cells/lab.py +399 -0
  47. terminal_cells-0.1.0/terminal_cells/lab_render.py +58 -0
  48. terminal_cells-0.1.0/terminal_cells/models.py +471 -0
  49. terminal_cells-0.1.0/terminal_cells/render.py +996 -0
  50. terminal_cells-0.1.0/terminal_cells/world.py +1321 -0
  51. terminal_cells-0.1.0/terminal_cells.egg-info/PKG-INFO +88 -0
  52. terminal_cells-0.1.0/terminal_cells.egg-info/SOURCES.txt +69 -0
  53. terminal_cells-0.1.0/terminal_cells.egg-info/dependency_links.txt +1 -0
  54. terminal_cells-0.1.0/terminal_cells.egg-info/entry_points.txt +2 -0
  55. terminal_cells-0.1.0/terminal_cells.egg-info/top_level.txt +2 -0
  56. terminal_cells-0.1.0/tests/test_cells.py +1469 -0
  57. terminal_cells-0.1.0/tests/test_events.py +277 -0
  58. terminal_cells-0.1.0/tests/test_interaction.py +386 -0
  59. terminal_cells-0.1.0/tests/test_packaging.py +53 -0
  60. terminal_cells-0.1.0/tests/test_properties.py +75 -0
  61. terminal_cells-0.1.0/tests/test_scale.py +129 -0
  62. terminal_cells-0.1.0/tests/test_terminal.py +201 -0
  63. terminal_cells-0.1.0/tools/benchmark.py +38 -0
  64. terminal_cells-0.1.0/tools/check_dist.py +340 -0
  65. terminal_cells-0.1.0/tools/check_reproducible.py +54 -0
  66. terminal_cells-0.1.0/tools/colors.py +44 -0
  67. terminal_cells-0.1.0/tools/demo.py +97 -0
  68. terminal_cells-0.1.0/tools/experiments.py +56 -0
  69. terminal_cells-0.1.0/tools/manpage.py +70 -0
  70. terminal_cells-0.1.0/tools/preview.py +303 -0
  71. terminal_cells-0.1.0/tools/sightings.py +63 -0
@@ -0,0 +1,5 @@
1
+ * text=auto
2
+ *.py text eol=lf
3
+ *.yml text eol=lf
4
+ cells text eol=lf
5
+ *.gif binary
@@ -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,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: pip
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -0,0 +1,9 @@
1
+ Describe the problem and the resulting behavior.
2
+
3
+ For visible changes, include a screenshot or recording, seed, terminal size, and
4
+ simulation time when useful.
5
+
6
+ Validation performed:
7
+
8
+ - Tests or manual checks:
9
+ - Relevant platform/terminal:
@@ -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,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ build/
5
+ dist/
6
+ .venv/
7
+ .DS_Store
8
+ .coverage
9
+ htmlcov/
10
+ .ruff_cache/
11
+ .hypothesis/
12
+ .env
13
+ .env.*
14
+ !.env.example
@@ -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.