relateby-pattern 0.7.2__tar.gz

relateby_pattern-0.7.2/Cargo.toml

@@ -0,0 +1,32 @@
+[workspace]
+members = [
+    "crates/pattern-core",
+    "crates/gram-codec",
+    "benches",
+]
+exclude = ["external/tree-sitter-gram"]
+resolver = "2"
+
+[workspace.package]
+version = "0.7.2"
+edition = "2021"
+rust-version = "1.70.0"
+authors = ["gram-data"]
+license = "BSD-3-Clause"
+description = "Rust port of gram-hs pattern data structure and graph views"
+repository = "https://github.com/relateby/pattern-rs"
+
+[workspace.dependencies]
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+thiserror = "2.0"
+proptest = "1.0"
+insta = "1.0"
+criterion = { version = "0.5", default-features = false, features = ["html_reports"] }
+clap = { version = "4", features = ["derive"] }
+strsim = "0.11"
+
+# Note: Previously had `[profile.release]` with opt-level="z" and lto=true,
+# but this affected ALL workspace crates (not just WASM). Removed to avoid
+# performance degradation in non-WASM binaries. For WASM size optimization,
+# use wasm-pack which applies appropriate settings: `wasm-pack build --release`

relateby_pattern-0.7.2/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.1
+Name: relateby-pattern
+Version: 0.7.2
+Summary: Combined Python distribution for relateby.pattern and relateby.gram
+License: Apache-2.0
+Requires-Python: >=3.8,<3.14
+Provides-Extra: dev
+Requires-Dist: maturin>=1.0,<2.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Requires-Dist: pdoc>=14.0; extra == 'dev'
+Provides-Extra: all
+Requires-Dist: relateby-pattern[dev]; extra == 'all'

relateby_pattern-0.7.2/README.md

@@ -0,0 +1,104 @@
+# Relateby
+
+Combined Python distribution for the pattern-rs library. One install provides both subpackages:
+
+- **relateby.pattern** — Pattern data structures (from pattern-core)
+- **relateby.gram** — Gram notation parser and serializer (from gram-codec)
+
+The published distribution name is **relateby-pattern** while the import namespace remains `relateby.*`.
+
+## Install
+
+```bash
+# Combined distribution (pattern + gram)
+pip install relateby-pattern
+
+# With optional dependencies (e.g. dev tools)
+pip install relateby-pattern[dev]      # maturin, pytest, pytest-cov
+pip install relateby-pattern[all]      # all optional extras
+```
+
+For a local source checkout, prefer `uv` with a project-local virtual environment:
+
+```bash
+cd python/packages/relateby
+uv venv --python 3.13 .venv
+source .venv/bin/activate
+uv pip install '.[dev]'
+```
+
+`python/packages/relateby` does not currently support editable installs (`pip install -e .`) because the custom build backend only implements wheel and sdist builds.
+The supported Python range is `>=3.8,<3.14`; `3.13` is the recommended local development target.
+
+After installation, run import checks and examples from outside `python/packages/relateby` so the source tree does not shadow the installed package.
+
+## Use
+
+```python
+import relateby.pattern
+import relateby.gram
+```
+
+There are no top-level `pattern_core` or `gram_codec` imports; use `relateby.pattern` and `relateby.gram` only.
+
+Representative public imports:
+
+```python
+from relateby.pattern import Pattern, StandardGraph, StringVal, Subject
+from relateby.gram import gram_validate, parse_gram, round_trip
+```
+
+Example public workflow:
+
+```python
+alice = Subject.from_id("alice").with_label("Person").with_property("name", StringVal("Alice"))
+graph = StandardGraph.from_patterns([Pattern.point(alice)])
+
+assert graph.node_count == 1
+assert len(parse_gram("(alice:Person)")) == 1
+assert gram_validate("(alice:Person)") == []
+assert round_trip("(alice:Person)") == "(alice:Person)"
+```
+
+## JSON Interchange
+
+`Pattern<Subject>` can be serialized to and from a plain JSON-compatible format defined by the [gram interchange schema](https://github.com/gram-data/tree-sitter-gram/blob/main/docs/pattern.schema.json). This is useful when you need to pass patterns across a process or network boundary without re-parsing gram notation on the other side.
+
+**Producer** (parse gram → emit raw JSON):
+
+```python
+from relateby.gram import parse_raw
+import json
+
+raw = parse_raw("(alice:Person)-[:KNOWS]->(bob:Person)")
+payload = json.dumps(raw)
+```
+
+**Consumer** (receive raw JSON → reconstruct patterns):
+
+```python
+from relateby.pattern import pattern_from_dict, validate_payload
+import json
+
+raw = json.loads(payload)
+patterns = [pattern_from_dict(item) for item in validate_payload(raw)]
+```
+
+**Round-trip** (native ↔ JSON):
+
+```python
+from relateby.pattern import pattern_from_dict, pattern_to_dict
+
+raw = pattern_to_dict(pattern)        # Pattern[Subject] → RawPattern dict
+restored = pattern_from_dict(raw)     # RawPattern dict → Pattern[Subject]
+```
+
+`RawPattern` and `RawSubject` are `TypedDict` types exported from `relateby.pattern` for use in type annotations.
+
+## Building from source
+
+From the repository root, build the wheel from the combined package directory (requires maturin and Rust; Python 3.8–3.13 for the extension build):
+
+```bash
+cd python/packages/relateby && uv build --wheel --python 3.13 --out-dir dist
+```

relateby_pattern-0.7.2/benches/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "pattern-rs-benches"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+description = "Benchmarks for pattern-rs"
+
+[[bench]]
+name = "pattern_operations"
+harness = false
+
+[dependencies]
+criterion = { workspace = true }
+pattern_core = { package = "relateby-pattern", path = "../crates/pattern-core" }
+gram_codec = { package = "relateby-gram", path = "../crates/gram-codec" }

relateby_pattern-0.7.2/benches/benches/README.md

@@ -0,0 +1,18 @@
+# Benchmark Suite
+
+This directory contains performance benchmarks using Criterion.
+
+## Running Benchmarks
+
+```bash
+cargo bench
+```
+
+## Benchmark Organization
+
+- `pattern_operations.rs` - Core pattern operation benchmarks
+
+## WASM Compatibility
+
+Benchmarks use conditional compilation for WASM targets due to timing limitations.
+

relateby_pattern-0.7.2/benches/benches/pattern_operations.rs

@@ -0,0 +1,13 @@
+//! Benchmarks for pattern operations
+//!
+//! These benchmarks measure performance of pattern operations to track
+//! performance over time and detect regressions.
+
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn benchmark_placeholder(c: &mut Criterion) {
+    c.bench_function("placeholder", |b| b.iter(|| black_box(42)));
+}
+
+criterion_group!(benches, benchmark_placeholder);
+criterion_main!(benches);

relateby_pattern-0.7.2/benches/src/lib.rs

@@ -0,0 +1,3 @@
+//! Benchmark package for pattern-rs
+//!
+//! This package contains performance benchmarks for the pattern-rs workspace.

relateby_pattern-0.7.2/crates/gram-codec/Cargo.toml

@@ -0,0 +1,67 @@
+[package]
+name = "relateby-gram"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+description = "Bidirectional codec between Gram notation and Pattern data structures"
+readme = "README.md"
+documentation = "https://docs.rs/relateby-gram"
+repository = "https://github.com/relateby/pattern-rs"
+
+[package.metadata.docs.rs]
+all-features = false
+features = []
+
+[dependencies]
+# Version must match workspace [workspace.package] version when publishing to crates.io.
+pattern_core = { package = "relateby-pattern", path = "../pattern-core", version = "0.7.2" }
+nom = "7"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+thiserror.workspace = true
+tree-sitter = { version = "0.25", optional = true }
+tree-sitter-gram = { version = "0.6", optional = true }
+
+# WASM support
+wasm-bindgen = { version = "0.2", optional = true }
+js-sys = { version = "0.3", optional = true }
+
+# Python support
+pyo3 = { version = "0.23", optional = true, features = ["extension-module"] }
+pythonize = { version = "0.23", optional = true }
+
+[dev-dependencies]
+insta.workspace = true
+criterion.workspace = true
+proptest = "1.0"
+
+[features]
+default = []
+wasm = ["wasm-bindgen", "js-sys"]
+python = ["pyo3", "pythonize", "pyo3/abi3-py38"]
+cst = ["dep:tree-sitter", "dep:tree-sitter-gram"]
+
+[lib]
+name = "gram_codec"
+path = "src/lib.rs"
+crate-type = ["cdylib", "rlib"]
+
+[[bench]]
+name = "codec_benchmarks"
+harness = false
+required-features = []
+
+[[example]]
+name = "interop_check"
+path = "examples/interop_check.rs"
+
+[[example]]
+name = "basic_usage"
+path = "examples/basic_usage.rs"
+
+[[example]]
+name = "advanced_usage"
+path = "examples/advanced_usage.rs"
+

relateby_pattern-0.7.2/crates/gram-codec/README.md

@@ -0,0 +1,387 @@
+# Gram Codec
+
+Bidirectional codec between [Gram notation](https://github.com/gram-data/tree-sitter-gram) (human-readable text format) and Pattern data structures.
+
+[![CI Status](https://github.com/relateby/pattern-rs/workflows/CI/badge.svg)](https://github.com/relateby/pattern-rs/actions)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+## Features
+
+- **Full Grammar Support**: Parses all Gram syntax forms (nodes, relationships, subject patterns, annotations)
+- **Round-Trip Correctness**: Parse → serialize → parse produces structurally equivalent patterns
+- **Error Recovery**: Reports all syntax errors, not just the first
+- **Value Types**: Supports strings, integers, decimals, booleans, arrays, ranges, tagged strings
+- **Unicode Support**: Full Unicode identifier and property value support
+- **Comprehensive Testing**: 139+ tests covering all syntax forms and edge cases
+
+## Installation
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+gram-codec = { path = "../gram-codec" }
+pattern-core = { path = "../pattern-core" }
+```
+
+## Quick Start
+
+### Parsing Gram Notation
+
+```rust
+use gram_codec::parse_gram;
+
+// Parse a simple node
+let patterns = parse_gram("(hello)")?;
+println!("Identifier: {}", patterns[0].value.identity.0);
+
+// Parse a relationship
+let patterns = parse_gram("(alice)-[:KNOWS]->(bob)")?;
+println!("Relationship with {} elements", patterns[0].elements.len());
+
+// Parse a subject pattern
+let patterns = parse_gram("[team | (alice), (bob)]")?;
+println!("Team has {} members", patterns[0].elements.len());
+```
+
+### Serializing Patterns
+
+```rust
+use gram_codec::{to_gram_pattern, to_gram};
+use pattern_core::{Pattern, Subject, Symbol};
+use std::collections::{HashMap, HashSet};
+
+// Create a pattern
+let subject = Subject {
+    identity: Symbol("hello".to_string()),
+    labels: HashSet::new(),
+    properties: HashMap::new(),
+};
+let pattern = Pattern::point(subject);
+
+// Serialize a single pattern
+let gram_text = to_gram_pattern(&pattern)?;
+println!("{}", gram_text); // Output: (hello)
+
+// Serialize multiple patterns
+let multiple = to_gram(&[pattern.clone(), pattern])?;
+println!("{}", multiple); // Output: (hello)\n(hello)
+```
+
+### Round-Trip Correctness
+
+```rust
+use gram_codec::{parse_gram, to_gram_pattern};
+
+let original = "(alice:Person {name: \"Alice\"})";
+
+// Parse
+let parsed = parse_gram(original)?;
+
+// Serialize
+let serialized = to_gram_pattern(&parsed[0])?;
+
+// Re-parse
+let reparsed = parse_gram(&serialized)?;
+
+// Verify structural equivalence
+assert_eq!(parsed[0].value.identity, reparsed[0].value.identity);
+```
+
+## Supported Gram Syntax
+
+### Node Patterns (0 elements)
+
+```gram
+()                              // Empty node
+(hello)                         // Node with identifier
+(a:Person)                      // Node with label
+(a:Person {name: "Alice"})      // Node with properties
+```
+
+### Relationship Patterns (2 elements)
+
+The grammar accepts **multiple visual arrow styles** that normalize to **4 semantic arrow kinds**:
+
+#### Right Arrow (`right_arrow`) - Directed left-to-right
+```gram
+(a)-->(b)                       // Single-stroke (canonical)
+(a)==>(b)                       // Double-stroke
+(a)~~>(b)                       // Squiggle
+(a)-[:KNOWS]->(b)               // With label
+(a)-[:KNOWS {since: 2020}]->(b) // With properties
+```
+
+#### Left Arrow (`left_arrow`) - Directed right-to-left (elements reversed)
+```gram
+(a)<--(b)                       // Single-stroke (canonical)
+(a)<==(b)                       // Double-stroke
+(a)<~~(b)                       // Squiggle
+// Note: (a)<--(b) stores elements as [b, a] (reversed!)
+```
+
+#### Bidirectional Arrow (`bidirectional_arrow`) - Mutual connection
+```gram
+(a)<-->(b)                      // Single-stroke (canonical)
+(a)<==>(b)                      // Double-stroke
+```
+
+#### Undirected Arrow (`undirected_arrow`) - No directionality
+```gram
+(a)~~(b)                        // Squiggle (canonical)
+(a)==(b)                        // Double-stroke
+```
+
+**Element Ordering:**
+- **Right arrows**: Elements stored as `[left, right]` (as written)
+- **Left arrows**: Elements stored as `[right, left]` (reversed from visual order!)
+- **Bidirectional/Undirected**: Elements stored as `[first, second]` (as written)
+
+### Subject Patterns (N elements)
+
+```gram
+[team | (alice), (bob)]         // Pattern with elements
+[outer | [inner | (leaf)]]      // Nested patterns
+[root:Type {p: 1} | e1, e2]     // With identifier, label, properties
+```
+
+### Annotated Patterns (1 element)
+
+```gram
+@type(node) (a)                 // Annotation on node
+@depth(2) [x | y, z]            // Annotation on subject pattern
+```
+
+### Property Values
+
+```gram
+{
+  name: "Alice",                // String
+  age: 30,                      // Integer
+  score: 95.5,                  // Decimal
+  active: true,                 // Boolean
+  tags: ["rust", "wasm"],       // Array
+  range: 1..10                  // Range
+}
+```
+
+### Comments
+
+```gram
+// This is a line comment
+(hello)-->(world)  // End-of-line comment
+```
+
+## Advanced Usage
+
+### Complex Relationships
+
+```rust
+let gram_text = "(alice:Person {name: \"Alice\", age: 30})-[:KNOWS {since: 2020}]->(bob:Person {name: \"Bob\"})";
+let patterns = parse_gram_notation(gram_text)?;
+
+// Access left node
+println!("Left: {}", patterns[0].elements[0].value.identity.0);
+
+// Access edge
+println!("Edge labels: {:?}", patterns[0].value.labels);
+
+// Access right node
+println!("Right: {}", patterns[0].elements[1].value.identity.0);
+```
+
+### Nested Patterns
+
+```rust
+let gram_text = "[outer:Group | [inner:Team | (alice), (bob)], (charlie)]";
+let patterns = parse_gram_notation(gram_text)?;
+
+println!("Outer: {}", patterns[0].value.identity.0);
+println!("Elements: {}", patterns[0].elements.len());
+println!("First element is nested: {}", 
+    !patterns[0].elements[0].elements.is_empty());
+```
+
+### Path Patterns
+
+```rust
+// Chained relationships
+let gram_text = "(a)-->(b)-->(c)-->(d)";
+let patterns = parse_gram_notation(gram_text)?;
+
+// Creates nested relationship structure
+println!("Path pattern parsed");
+```
+
+### Unicode Support
+
+```rust
+// Unicode identifiers must be quoted
+let gram_text = "(\"世界\" {greeting: \"こんにちは\"})";
+let patterns = parse_gram_notation(gram_text)?;
+
+println!("Identifier: {}", patterns[0].value.identity.0);
+```
+
+### Error Handling
+
+```rust
+use gram_codec::parse_gram_notation;
+
+let invalid_gram = "(unclosed";
+match parse_gram_notation(invalid_gram) {
+    Ok(_) => println!("Success"),
+    Err(e) => {
+        println!("Parse error: {}", e.message);
+        println!("Error count: {}", e.error_count());
+        // Access location information
+        println!("Location: line {}, column {}", 
+            e.location.line, e.location.column);
+    }
+}
+```
+
+## Examples
+
+> 📚 **See [`../../examples/gram-codec-README.md`](../../examples/gram-codec-README.md) for complete examples across all platforms!**
+
+Run the included examples:
+
+```bash
+# Basic usage (10 examples)
+cargo run --package gram-codec --example basic_usage
+
+# Advanced usage (10 examples)
+cargo run --package gram-codec --example advanced_usage
+
+# Interactive Python demo
+python examples/gram-codec-python/demo.py
+
+# Interactive browser demo
+# (After building: wasm-pack build --target web . -- --features wasm)
+python3 -m http.server 8000
+# Open http://localhost:8000/examples/gram-codec-wasm-web/
+```
+
+## Testing
+
+Run the comprehensive test suite:
+
+```bash
+# All tests (159 tests total)
+cargo test --package gram-codec
+
+# Specific test suite
+cargo test --package gram-codec --test parser_tests              # 18 tests
+cargo test --package gram-codec --test serializer_tests          # 15 tests
+cargo test --package gram-codec --test value_types_tests         # 13 tests
+cargo test --package gram-codec --test arrow_types_tests         # 14 tests (1 ignored)
+cargo test --package gram-codec --test arrow_style_variants_tests # 19 tests
+cargo test --package gram-codec --test edge_cases_tests          # 28 tests
+cargo test --package gram-codec --test advanced_features_tests   # 22 tests
+```
+
+### Test Coverage
+
+- **159 tests total** (158 passing + 1 ignored)
+- Unit tests for error handling, parser core, serializer core
+- Comprehensive arrow style variant tests (all 10 visual forms documented)
+- Integration tests for all gram syntax forms
+- Edge case handling (nesting, whitespace, comments, error recovery)
+- Round-trip correctness validation
+
+## Grammar Authority
+
+This codec uses [`tree-sitter-gram`](https://github.com/gram-data/tree-sitter-gram) as the authoritative grammar specification. The pure Rust implementation is validated for 100% conformance with the tree-sitter-gram test corpus.
+
+## Architecture
+
+The codec consists of several modules:
+
+- **`parser`**: Transforms Gram notation text → Pattern structures using a pure Rust `nom` implementation
+- **`serializer`**: Transforms Pattern structures → Gram notation text
+- **`ast`**: AST (Abstract Syntax Tree) types for cross-language JSON serialization
+- **`value`**: Value enum for property types (String, Integer, Decimal, Boolean, Array, Range)
+- **`error`**: Error types with location information
+
+## Multi-Platform Support
+
+### WASM (WebAssembly)
+
+Build for browser and Node.js environments:
+
+```bash
+# Using wasm-pack
+wasm-pack build --target web crates/gram-codec -- --features wasm
+
+# JavaScript usage
+import init, { parse_gram, validate_gram, round_trip } from './pkg/gram_codec.js';
+await init();
+const result = parse_gram("(hello)-->(world)");
+```
+
+**Examples:**
+- `../../examples/gram-codec-wasm-web/` - Interactive browser demo with UI
+- `../../examples/gram-codec-wasm-node/` - Node.js command-line examples
+
+### Python
+
+Build and install Python bindings:
+
+```bash
+pip install maturin
+cd crates/gram-codec
+maturin develop --features python
+
+# Python usage
+from gram_codec import parse_gram, validate_gram, round_trip
+result = parse_gram("(hello)-->(world)")
+print(f"Parsed {result['pattern_count']} patterns")
+```
+
+**Examples:**
+- `../../examples/gram-codec-python/demo.py` - Interactive demo with REPL mode
+- `../../examples/gram-codec-python/quickstart.py` - Quick 5-minute introduction
+- `../../examples/gram-codec-python/gram_codec.py` - Template with 10 example functions
+
+See `pyproject.toml` for packaging configuration.
+
+## Performance
+
+The codec includes comprehensive benchmarks:
+
+```bash
+# Run all benchmarks
+cargo bench --package gram-codec
+
+# Specific benchmarks
+cargo bench --package gram-codec --bench codec_benchmarks -- parse_simple_nodes
+cargo bench --package gram-codec --bench codec_benchmarks -- round_trip
+```
+
+Benchmarks cover:
+- Parsing simple nodes (10, 100, 1000 patterns)
+- Parsing relationships and chains
+- Parsing subject patterns with many elements
+- Serialization (single and multiple patterns)
+- Round-trip correctness (parse → serialize → parse)
+- Complex patterns with mixed syntax
+
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](../../LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+- All tests pass: `cargo test --package gram-codec`
+- Code is formatted: `cargo fmt --all`
+- No clippy warnings: `cargo clippy --package gram-codec -- -D warnings`
+- Examples run successfully
+
+## Resources
+
+- [Gram Notation Specification](https://github.com/gram-data/tree-sitter-gram)
+- [Pattern Core Library](../pattern-core/)
+- [Project Documentation](../../specs/019-gram-codec/)