p5py-vibe 0.1.0__tar.gz

p5py_vibe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+      - run: uv sync --dev
+      - run: uv run ruff check .
+      - run: uv run mypy src
+      - run: uv run pytest
+      - run: uv run python examples/basic_shapes.py --backend headless --frames 1
+
+  build-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+      - run: uv build
+
+  build-rust:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+      - uses: dtolnay/rust-toolchain@stable
+      - run: uvx maturin build --release

p5py_vibe-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,105 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      repository:
+        description: Package index to publish to
+        required: true
+        type: choice
+        options:
+          - testpypi
+          - pypi
+        default: testpypi
+  push:
+    tags:
+      - "v*"
+
+permissions: {}
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: .python-version
+
+      - name: Install dev dependencies
+        run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy src
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Smoke test headless example
+        run: uv run python examples/basic_shapes.py --backend headless --frames 1
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Verify distribution metadata
+        run: uv tool run twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && inputs.repository == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/p5-py
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+      - name: Publish package distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.repository == 'pypi')
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/p5-py
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

p5py_vibe-0.1.0/.gitignore

@@ -0,0 +1,226 @@
+examples/output/
+
+# Created by https://www.toptal.com/developers/gitignore/api/python,macos,rust
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,macos,rust
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### Rust ###
+# Generated by Cargo
+# will have compiled files and executables
+debug/
+
+# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
+# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
+Cargo.lock
+
+# These are backup files generated by rustfmt
+**/*.rs.bk
+
+# MSVC Windows builds of rustc generate these, which store debugging information
+*.pdb
+
+# End of https://www.toptal.com/developers/gitignore/api/python,macos,rust

p5py_vibe-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

p5py_vibe-0.1.0/AGENTS.md

@@ -0,0 +1,349 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project overview
+
+This repository contains `p5-py`, a Pythonic creative-coding package inspired by p5.js.
+
+The goal is to provide a familiar p5-style sketching model for Python while keeping the implementation idiomatic, maintainable, typed, testable, and backend-agnostic.
+
+The package must remain native Python. Do not add JavaScript or HTML code.
+
+## Package workflow
+
+This project uses `uv`.
+
+Use `uv` for dependency and command execution:
+
+```sh
+uv sync --dev
+uv run pytest
+uv run ruff check .
+uv run ruff format .
+uv run python examples/basic_shapes.py --backend headless --frames 1
+```
+
+Do not use raw `pip install` or unmanaged virtual environments unless explicitly requested.
+
+The active Python version is defined by `.python-version` and `pyproject.toml`.
+
+## Source layout
+
+Primary package code lives under:
+
+```text
+src/p5_py/
+```
+
+Important areas:
+
+```text
+src/p5_py/api/          global-mode API, p5.js aliases, compatibility stubs
+src/p5_py/backends/     backend implementations and backend registry
+src/p5_py/core/         color, geometry, state, transforms, math-like core systems
+src/p5_py/drawing/      renderer protocol and drawing abstractions
+src/p5_py/events/       normalized input/event state
+src/p5_py/pixels/       future pixel-buffer functionality
+src/p5_py/plugins/      future plugin architecture
+src/p5_py/rust/         future Rust acceleration integration
+src/p5_py/testing/      future testing helpers
+```
+
+Tests live under:
+
+```text
+tests/
+```
+
+Examples live under:
+
+```text
+examples/
+```
+
+Docs live under:
+
+```text
+docs/
+```
+
+Backlog items live under:
+
+```text
+backlog/<three_digit_epic_name>/<pbi_name>.toml
+```
+
+## Architecture principles
+
+### Keep public API backend-agnostic
+
+The public p5-py API must not directly depend on Pillow, Pyglet, or any future renderer.
+
+The intended layering is:
+
+```text
+user sketch
+  ↓
+p5_py public API
+  ↓
+Sketch / SketchContext
+  ↓
+Renderer + Backend protocols
+  ↓
+Concrete backend / renderer
+```
+
+### Separate backend responsibilities from renderer responsibilities
+
+Backends own platform/window/runtime concerns.
+
+Renderers own drawing.
+
+For example:
+
+- `PygletBackend` should own window creation, the event loop, input normalization, frame scheduling, and shutdown.
+- A future `PygletRenderer` should own native Pyglet drawing.
+- `PillowRenderer` should remain the deterministic headless/export renderer.
+
+Do not push sketch lifecycle, p5.js aliasing, or argument parsing into backend-specific code.
+
+### Preserve custom backend support
+
+Future custom backends should be able to integrate by implementing the backend and renderer protocols and registering themselves through the backend registry.
+
+Avoid hardcoding backend classes outside `p5_py.backends.registry` and backend selection logic.
+
+### Keep p5 compatibility and Pythonic API together
+
+Canonical Python APIs should use `snake_case`, for example:
+
+```python
+create_canvas()
+frame_rate()
+no_loop()
+pixel_density()
+```
+
+p5.js-style aliases may be provided where useful:
+
+```python
+createCanvas()
+frameRate()
+noLoop()
+pixelDensity()
+```
+
+Aliases must delegate to the same implementation. Do not duplicate behavior.
+
+### Keep exports type-checker friendly
+
+`src/p5_py/__init__.py` should use explicit imports for public APIs. Avoid dynamic wildcard export machinery that makes Zed/Pyright unable to see package attributes.
+
+## Rendering guidance
+
+### Current rendering state
+
+The current Pyglet backend is a bridge backend:
+
+```text
+PillowRenderer renders the frame
+PygletBackend presents that image in a native Pyglet window
+```
+
+This is intentional for now. See:
+
+```text
+docs/technical/native_pyglet_renderer.md
+```
+
+The planned next rendering milestone is a native `PygletRenderer`.
+
+### HiDPI and pixel density
+
+p5-py distinguishes logical canvas dimensions from physical backing-buffer dimensions.
+
+- `width()` and `height()` are logical p5 dimensions.
+- `pixel_density()` controls physical backing scale.
+- `display_density()` reports native display scale when the backend supports it.
+- `load_pixels()` and `update_pixels()` currently operate on physical RGBA buffers.
+
+See:
+
+```text
+docs/technical/hidpi_rendering.md
+```
+
+Do not regress Retina/HiDPI behavior when changing renderers or backends.
+
+## Exclusions
+
+Do not add:
+
+- JavaScript code
+- HTML code
+- DOM APIs
+- browser-only APIs
+- `p5.XML`
+- `p5.Table`
+- `p5.TableRow`
+
+Excluded APIs should raise clear package-specific errors when exposed as compatibility stubs.
+
+## Backlog conventions
+
+Backlog epics use a three-digit prefix to allow insertion between epics, for example:
+
+```text
+010_foundation_runtime
+020_api_compatibility
+030_rendering_2d
+031_native_pyglet_renderer
+040_color_style_transform
+```
+
+Each PBI file must use this TOML layout:
+
+```toml
+[my_pbi]
+title = "..."
+description = '''
+As a ...,
+I want ...,
+So that ...
+'''
+acceptance_criteria = '''
+...
+'''
+priotity = 'high|medium|low'
+status = 'TODO|IN_PROGRESS|DONE'
+
+[my_pbi.task_1]
+order = 1
+status = 'TODO|IN_PROGRESS|DONE'
+description = '''
+...
+'''
+```
+
+Note: the existing schema intentionally uses the misspelled key `priotity`. Preserve it unless the user explicitly requests a schema migration.
+
+When completing work that corresponds to backlog items, update both PBI and task statuses.
+
+Allowed status values are:
+
+```text
+TODO
+IN_PROGRESS
+DONE
+```
+
+Validate backlog TOML after edits:
+
+```sh
+python - <<'PY'
+from pathlib import Path
+import tomllib
+for path in sorted(Path('backlog').glob('**/*.toml')):
+    with path.open('rb') as f:
+        tomllib.load(f)
+print('Backlog TOML parsed successfully')
+PY
+```
+
+## Testing and validation
+
+Before finishing code changes, run:
+
+```sh
+uv run ruff check .
+uv run pytest
+```
+
+If formatting changes are needed, run:
+
+```sh
+uv run ruff format .
+```
+
+Also check Zed diagnostics when practical.
+
+For rendering changes, run at least one headless example smoke test, such as:
+
+```sh
+uv run python examples/basic_shapes.py --backend headless --frames 1
+```
+
+If examples generate output files, do not accidentally commit generated artifacts unless the user explicitly wants them tracked.
+
+## Test expectations
+
+Add or update tests when changing behavior.
+
+Current useful test areas:
+
+```text
+tests/contracts/       backend and renderer contract behavior
+tests/integration/     end-to-end sketch rendering behavior
+tests/unit/            API, lifecycle, color, transforms, density, backend details
+```
+
+Prefer deterministic headless tests for renderer behavior where possible.
+
+For interactive Pyglet behavior, use focused unit tests with fake window/module objects when possible, and document any manual smoke tests.
+
+## Documentation expectations
+
+Update docs when changing architecture, public APIs, rendering behavior, backend behavior, or compatibility status.
+
+Relevant docs include:
+
+```text
+docs/technical/project_plan.md
+docs/technical/hidpi_rendering.md
+docs/technical/native_pyglet_renderer.md
+```
+
+## Rust guidance
+
+Rust acceleration is planned but should remain optional and contained.
+
+Future Rust code should live under:
+
+```text
+crates/
+```
+
+Rust should be used only for pure computational hot paths such as:
+
+- noise generation
+- pixel filters
+- blend modes
+- color conversion
+- geometry tessellation
+- path flattening
+
+Every Rust-accelerated feature must have a Python fallback unless the user explicitly changes this requirement.
+
+## Dependency guidance
+
+Prefer existing dependencies already in `pyproject.toml`.
+
+Current core dependencies include:
+
+- Pillow
+- Pyglet
+
+Current dev dependencies include:
+
+- pytest
+- ruff
+
+Add new dependencies only when justified by the task, and use `uv add` or `uv add --dev` so `pyproject.toml` and `uv.lock` stay in sync.
+
+## Safety notes
+
+- Do not modify the sibling `p5.js` repository unless the user explicitly asks.
+- Do not commit changes unless the user explicitly asks.
+- Do not remove or overwrite generated/user files unless you are sure they are artifacts from your own validation commands.
+- Keep changes focused on the requested task.