py2pd 0.1.1__tar.gz

py2pd-0.1.1/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: py2pd
+Version: 0.1.1
+Summary: Roundtrip parsing and generation of pure-data patches from python
+Keywords: puredata,pd,audio,dsp,music,synthesis,patching
+Author: Shakeeb Alireza
+Author-email: Shakeeb Alireza <shakfu@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/shakfu/py2pd
+Project-URL: Repository, https://github.com/shakfu/py2pd
+Project-URL: Issues, https://github.com/shakfu/py2pd/issues
+Project-URL: Changelog, https://github.com/shakfu/py2pd/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# py2pd - Python <-> PureData
+
+Roundtrip parsing and generation of [pure-data](https://puredata.info) patches from python.
+
+py2pd is a fork and extensive rewrite of Dylan Burati's [puredata-compiler](https://github.com/dylanburati/puredata-compiler) using some of the ideas from [py2max](https://github.com/shakfu/py2max).
+
+## Install
+
+```bash
+pip install py2pd
+```
+
+## Quick Start
+
+```python
+from py2pd import Patcher
+
+# Create a simple synthesizer patch
+p = Patcher('synth.pd')
+
+osc = p.add('osc~ 440')
+gain = p.add('*~ 0.3')
+dac = p.add('dac~')
+
+p.link(osc, gain)
+p.link(gain, dac)
+p.link(gain, dac, inlet=1)  # stereo
+
+p.save()
+```
+
+## Builder API
+
+The `Patcher` class provides methods to add nodes and connect them.
+
+### Adding Nodes
+
+```python
+from py2pd import Patcher
+
+p = Patcher('example.pd')
+
+# Objects
+osc = p.add('osc~ 440')
+filter_obj = p.add('lop~ 1000')
+
+# Messages
+bang = p.add_msg('bang')
+freq_msg = p.add_msg('440')
+
+# GUI Elements
+slider = p.add_hslider(min_val=20, max_val=20000, width=150)
+toggle = p.add_toggle(default_value=1, send='onoff')
+numbox = p.add_numberbox(min_val=0, max_val=127)
+bang_btn = p.add_bang(send='trigger', label='Click')
+```
+
+### Connecting Nodes
+
+Use `link()` to connect nodes. By default, outlet 0 connects to inlet 0:
+
+```python
+p.link(osc, gain)              # outlet 0 -> inlet 0
+p.link(gain, dac)              # left channel
+p.link(gain, dac, inlet=1)     # right channel (stereo)
+p.link(trigger, pack, outlet=1, inlet=2)  # specific ports
+```
+
+### Subpatches
+
+Create reusable subpatches:
+
+```python
+def make_envelope() -> Patcher:
+    p = Patcher()
+    inlet = p.add('inlet')
+    vline = p.add('vline~')
+    outlet = p.add('outlet~')
+    p.link(inlet, vline)
+    p.link(vline, outlet)
+    return p
+
+main = Patcher('main.pd')
+osc = main.add('osc~ 440')
+env = main.add_subpatch('envelope', make_envelope())
+vca = main.add('*~')
+
+main.link(osc, vca)
+main.link(env, vca, inlet=1)
+```
+
+### Layout Options
+
+**Default layout** - nodes flow top-to-bottom:
+```python
+p = Patcher('patch.pd')
+p.add('osc~ 440')   # Row 1
+p.add('*~ 0.5')     # Row 2
+p.add('dac~')       # Row 3
+```
+
+**Grid layout** - organized columns:
+```python
+from py2pd import Patcher, GridLayoutManager
+
+grid = GridLayoutManager(columns=4, cell_width=80, cell_height=35)
+p = Patcher('grid.pd', layout=grid)
+```
+
+**Auto layout** - arrange by signal flow:
+```python
+p = Patcher('patch.pd')
+# Add nodes in any order...
+p.auto_layout(margin=50, row_spacing=50, col_spacing=100)
+```
+
+### Saving and Export
+
+```python
+p.save()                    # Save to filename from constructor
+p.save('other.pd')          # Save to specific file
+p.save_svg('patch.svg')     # Export visualization as SVG
+svg_str = p.to_svg()        # Get SVG as string
+```
+
+### Validation
+
+```python
+p.validate_connections(check_cycles=True)  # Raises on invalid connections
+```
+
+## AST API (Round-trip Parsing)
+
+For modifying existing patches with immutable AST nodes:
+
+```python
+from py2pd import parse_file, serialize
+
+# Parse existing patch
+ast = parse_file('input.pd')
+
+# Modify the AST...
+
+# Write back
+with open('output.pd', 'w') as f:
+    f.write(serialize(ast))
+```
+
+### Converting Between APIs
+
+You can convert between AST and Builder representations:
+
+```python
+from py2pd import parse_file, to_builder, from_builder
+
+# AST -> Builder: parse then edit with the more convenient API
+ast = parse_file('input.pd')
+patch = to_builder(ast)
+patch.add('osc~ 880')
+patch.save('output.pd')
+
+# Builder -> AST: for analysis or transformation
+ast = from_builder(patch)
+```
+
+### When to Use Each API
+
+| Use Case | Recommended API |
+|----------|-----------------|
+| Creating patches from scratch | Builder |
+| Modifying existing patches | Builder (via `to_builder()`) |
+| Lossless round-trip of complex patches | AST |
+| Building analysis/refactoring tools | AST |
+| Batch search/replace across .pd files | AST |
+
+For most workflows, parse to AST then convert to Builder for editing. Use the AST API directly when you need to preserve elements the Builder doesn't model (e.g., `coords`, comments) or need immutable transformations.
+
+AST node types are available from the `py2pd.ast` module:
+
+```python
+from py2pd.ast import PdPatch, PdObj, PdMsg, Position, transform, find_objects
+```
+
+## GUI Elements
+
+| Method | Description |
+|--------|-------------|
+| `add_bang()` | Bang button |
+| `add_toggle()` | On/off toggle |
+| `add_numberbox()` | Editable number |
+| `add_float()` | Float atom |
+| `add_symbol()` | Symbol/text input |
+| `add_hslider()` | Horizontal slider |
+| `add_vslider()` | Vertical slider |
+| `add_hradio()` | Horizontal radio buttons |
+| `add_vradio()` | Vertical radio buttons |
+| `add_canvas()` | Background/label area |
+| `add_vu()` | VU meter |
+
+## Error Handling
+
+```python
+from py2pd import (
+    ConnectionError,        # Invalid connection arguments
+    NodeNotFoundError,      # Node not in patch
+    InvalidConnectionError, # Bad inlet/outlet index
+    CycleWarning,           # Feedback loop detected
+)
+```

py2pd-0.1.1/README.md

@@ -0,0 +1,209 @@
+# py2pd - Python <-> PureData
+
+Roundtrip parsing and generation of [pure-data](https://puredata.info) patches from python.
+
+py2pd is a fork and extensive rewrite of Dylan Burati's [puredata-compiler](https://github.com/dylanburati/puredata-compiler) using some of the ideas from [py2max](https://github.com/shakfu/py2max).
+
+## Install
+
+```bash
+pip install py2pd
+```
+
+## Quick Start
+
+```python
+from py2pd import Patcher
+
+# Create a simple synthesizer patch
+p = Patcher('synth.pd')
+
+osc = p.add('osc~ 440')
+gain = p.add('*~ 0.3')
+dac = p.add('dac~')
+
+p.link(osc, gain)
+p.link(gain, dac)
+p.link(gain, dac, inlet=1)  # stereo
+
+p.save()
+```
+
+## Builder API
+
+The `Patcher` class provides methods to add nodes and connect them.
+
+### Adding Nodes
+
+```python
+from py2pd import Patcher
+
+p = Patcher('example.pd')
+
+# Objects
+osc = p.add('osc~ 440')
+filter_obj = p.add('lop~ 1000')
+
+# Messages
+bang = p.add_msg('bang')
+freq_msg = p.add_msg('440')
+
+# GUI Elements
+slider = p.add_hslider(min_val=20, max_val=20000, width=150)
+toggle = p.add_toggle(default_value=1, send='onoff')
+numbox = p.add_numberbox(min_val=0, max_val=127)
+bang_btn = p.add_bang(send='trigger', label='Click')
+```
+
+### Connecting Nodes
+
+Use `link()` to connect nodes. By default, outlet 0 connects to inlet 0:
+
+```python
+p.link(osc, gain)              # outlet 0 -> inlet 0
+p.link(gain, dac)              # left channel
+p.link(gain, dac, inlet=1)     # right channel (stereo)
+p.link(trigger, pack, outlet=1, inlet=2)  # specific ports
+```
+
+### Subpatches
+
+Create reusable subpatches:
+
+```python
+def make_envelope() -> Patcher:
+    p = Patcher()
+    inlet = p.add('inlet')
+    vline = p.add('vline~')
+    outlet = p.add('outlet~')
+    p.link(inlet, vline)
+    p.link(vline, outlet)
+    return p
+
+main = Patcher('main.pd')
+osc = main.add('osc~ 440')
+env = main.add_subpatch('envelope', make_envelope())
+vca = main.add('*~')
+
+main.link(osc, vca)
+main.link(env, vca, inlet=1)
+```
+
+### Layout Options
+
+**Default layout** - nodes flow top-to-bottom:
+```python
+p = Patcher('patch.pd')
+p.add('osc~ 440')   # Row 1
+p.add('*~ 0.5')     # Row 2
+p.add('dac~')       # Row 3
+```
+
+**Grid layout** - organized columns:
+```python
+from py2pd import Patcher, GridLayoutManager
+
+grid = GridLayoutManager(columns=4, cell_width=80, cell_height=35)
+p = Patcher('grid.pd', layout=grid)
+```
+
+**Auto layout** - arrange by signal flow:
+```python
+p = Patcher('patch.pd')
+# Add nodes in any order...
+p.auto_layout(margin=50, row_spacing=50, col_spacing=100)
+```
+
+### Saving and Export
+
+```python
+p.save()                    # Save to filename from constructor
+p.save('other.pd')          # Save to specific file
+p.save_svg('patch.svg')     # Export visualization as SVG
+svg_str = p.to_svg()        # Get SVG as string
+```
+
+### Validation
+
+```python
+p.validate_connections(check_cycles=True)  # Raises on invalid connections
+```
+
+## AST API (Round-trip Parsing)
+
+For modifying existing patches with immutable AST nodes:
+
+```python
+from py2pd import parse_file, serialize
+
+# Parse existing patch
+ast = parse_file('input.pd')
+
+# Modify the AST...
+
+# Write back
+with open('output.pd', 'w') as f:
+    f.write(serialize(ast))
+```
+
+### Converting Between APIs
+
+You can convert between AST and Builder representations:
+
+```python
+from py2pd import parse_file, to_builder, from_builder
+
+# AST -> Builder: parse then edit with the more convenient API
+ast = parse_file('input.pd')
+patch = to_builder(ast)
+patch.add('osc~ 880')
+patch.save('output.pd')
+
+# Builder -> AST: for analysis or transformation
+ast = from_builder(patch)
+```
+
+### When to Use Each API
+
+| Use Case | Recommended API |
+|----------|-----------------|
+| Creating patches from scratch | Builder |
+| Modifying existing patches | Builder (via `to_builder()`) |
+| Lossless round-trip of complex patches | AST |
+| Building analysis/refactoring tools | AST |
+| Batch search/replace across .pd files | AST |
+
+For most workflows, parse to AST then convert to Builder for editing. Use the AST API directly when you need to preserve elements the Builder doesn't model (e.g., `coords`, comments) or need immutable transformations.
+
+AST node types are available from the `py2pd.ast` module:
+
+```python
+from py2pd.ast import PdPatch, PdObj, PdMsg, Position, transform, find_objects
+```
+
+## GUI Elements
+
+| Method | Description |
+|--------|-------------|
+| `add_bang()` | Bang button |
+| `add_toggle()` | On/off toggle |
+| `add_numberbox()` | Editable number |
+| `add_float()` | Float atom |
+| `add_symbol()` | Symbol/text input |
+| `add_hslider()` | Horizontal slider |
+| `add_vslider()` | Vertical slider |
+| `add_hradio()` | Horizontal radio buttons |
+| `add_vradio()` | Vertical radio buttons |
+| `add_canvas()` | Background/label area |
+| `add_vu()` | VU meter |
+
+## Error Handling
+
+```python
+from py2pd import (
+    ConnectionError,        # Invalid connection arguments
+    NodeNotFoundError,      # Node not in patch
+    InvalidConnectionError, # Bad inlet/outlet index
+    CycleWarning,           # Feedback loop detected
+)
+```

py2pd-0.1.1/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "py2pd"
+version = "0.1.1"
+description = "Roundtrip parsing and generation of pure-data patches from python"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+authors = [
+    { name = "Shakeeb Alireza", email = "shakfu@users.noreply.github.com" }
+]
+keywords = ["puredata", "pd", "audio", "dsp", "music", "synthesis", "patching"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Multimedia :: Sound/Audio :: Sound Synthesis",
+    "Topic :: Software Development :: Code Generators",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/shakfu/py2pd"
+Repository = "https://github.com/shakfu/py2pd"
+Issues = "https://github.com/shakfu/py2pd/issues"
+Changelog = "https://github.com/shakfu/py2pd/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "ruff>=0.14.13",
+    "twine>=6.2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.13"
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]

py2pd-0.1.1/src/py2pd/__init__.py

@@ -0,0 +1,86 @@
+"""
+py2pd - Python to PureData
+==========================
+
+Write PureData patches as Python programs.
+
+Builder API example:
+  >>> from py2pd import Patcher
+  >>> p = Patcher('patch.pd')
+  >>> osc = p.add('osc~ 440')
+  >>> dac = p.add('dac~')
+  >>> p.link(osc, dac)
+  >>> p.link(osc, dac, inlet=1)  # stereo
+  >>> p.save()
+
+AST API example (round-trip):
+  >>> from py2pd import parse_file, serialize
+  >>> ast = parse_file('input.pd')
+  >>> # Modify the AST...
+  >>> with open('output.pd', 'w') as f:
+  ...     f.write(serialize(ast))
+"""
+
+# Builder API
+from .api import (
+    COLUMN_WIDTH as COLUMN_WIDTH,
+)
+from .api import (
+    DEFAULT_MARGIN as DEFAULT_MARGIN,
+)
+from .api import (
+    # Layout constants
+    ROW_HEIGHT as ROW_HEIGHT,
+)
+from .api import (
+    SUBPATCH_CANVAS_HEIGHT as SUBPATCH_CANVAS_HEIGHT,
+)
+from .api import (
+    SUBPATCH_CANVAS_WIDTH as SUBPATCH_CANVAS_WIDTH,
+)
+from .api import (
+    ConnectionError as ConnectionError,
+)
+from .api import (
+    CycleWarning as CycleWarning,
+)
+from .api import (
+    GridLayoutManager as GridLayoutManager,
+)
+from .api import (
+    InvalidConnectionError as InvalidConnectionError,
+)
+from .api import (
+    LayoutManager as LayoutManager,
+)
+from .api import (
+    NodeNotFoundError as NodeNotFoundError,
+)
+from .api import (
+    Patcher as Patcher,
+)
+from .ast import (
+    ParseError as ParseError,
+)
+from .ast import (
+    from_builder as from_builder,
+)
+
+# AST API (node types available via: from py2pd.ast import PdPatch, PdObj, ...)
+from .ast import (
+    parse as parse,
+)
+from .ast import (
+    parse_file as parse_file,
+)
+from .ast import (
+    serialize as serialize,
+)
+from .ast import (
+    serialize_to_file as serialize_to_file,
+)
+from .ast import (
+    to_builder as to_builder,
+)
+
+__version__ = "0.1.1"