yurtle-rdflib 0.1.0__tar.gz

yurtle_rdflib-0.1.0/.gitignore

@@ -0,0 +1,111 @@
+# 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
+*.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/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# 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/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Yurtle store index files
+.yurtle-store-index.json

yurtle_rdflib-0.1.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-12
+
+### Added
+
+- Initial release of yurtle-rdflib
+- **YurtleRDFlibParser**: RDFlib parser plugin for Yurtle format
+  - Supports Turtle frontmatter (native RDF)
+  - Supports YAML frontmatter (converted to RDF)
+  - Automatic subject URI generation
+  - Provenance tracking via `prov:definedIn` triples
+- **YurtleRDFlibSerializer**: RDFlib serializer plugin for Yurtle format
+  - Serializes RDF triples to Turtle frontmatter
+  - Preserves markdown content on round-trip
+  - Filters provenance triples from output
+- **YurtleStore**: Bidirectional RDFlib Store
+  - Hash-based change detection for efficient sync
+  - Automatic write-back to source files
+  - Optional auto-flush for immediate persistence
+- **Convenience functions**:
+  - `load_workspace()`: Load all Yurtle files into a unified graph
+  - `save_workspace()`: Save graph back to workspace files
+  - `create_live_graph()`: Create store-backed graph with live sync
+  - `parse_file()`: Parse a single Yurtle file
+  - `serialize_file()`: Serialize graph to Yurtle file
+- **Standard namespaces**: `YURTLE`, `PM`, `BEING`, `VOYAGE`, `KNOWLEDGE`, `PROVENANCE`
+- Full type hints (PEP 561 compliant with py.typed marker)
+- Comprehensive documentation and examples
+
+### Dependencies
+
+- rdflib >= 6.0.0
+- pyyaml >= 6.0
+- Python >= 3.9
+
+[0.1.0]: https://github.com/hankh95/yurtle-rdflib/releases/tag/v0.1.0

yurtle_rdflib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hank Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yurtle_rdflib-0.1.0/PKG-INFO

@@ -0,0 +1,320 @@
+Metadata-Version: 2.4
+Name: yurtle-rdflib
+Version: 0.1.0
+Summary: RDFlib plugin for Yurtle format (Markdown with Turtle/YAML frontmatter)
+Project-URL: Homepage, https://github.com/hankh95/yurtle-rdflib
+Project-URL: Documentation, https://github.com/hankh95/yurtle-rdflib#readme
+Project-URL: Repository, https://github.com/hankh95/yurtle-rdflib
+Project-URL: Changelog, https://github.com/hankh95/yurtle-rdflib/blob/main/CHANGELOG.md
+Project-URL: Yurtle Spec, https://github.com/hankh95/yurtle
+Author-email: Hank Huang <hank@nusy.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: knowledge-graph,markdown,rdf,rdflib,semantic-web,turtle,yurtle
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rdflib>=6.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yurtle-rdflib
+
+[![PyPI version](https://badge.fury.io/py/yurtle-rdflib.svg)](https://badge.fury.io/py/yurtle-rdflib)
+[![Python versions](https://img.shields.io/pypi/pyversions/yurtle-rdflib.svg)](https://pypi.org/project/yurtle-rdflib/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/hankh95/yurtle-rdflib/actions/workflows/ci.yml/badge.svg)](https://github.com/hankh95/yurtle-rdflib/actions/workflows/ci.yml)
+
+RDFlib plugin for [Yurtle format](https://github.com/hankh95/yurtle) - Markdown files with Turtle/YAML frontmatter that form a queryable knowledge graph.
+
+## What is Yurtle?
+
+Yurtle (YAML/RDF + Turtle) is a file format that combines:
+- **Markdown content** for human-readable documentation
+- **Turtle or YAML frontmatter** for machine-readable RDF triples
+
+This enables every `.md` file to be both a document AND a node in a knowledge graph.
+
+```markdown
+---
+@prefix yurtle: <https://yurtle.dev/schema/> .
+@prefix pm: <https://yurtle.dev/pm/> .
+
+<urn:task:F-048> a yurtle:WorkItem ;
+    pm:status "in-progress" ;
+    pm:priority 2 ;
+    yurtle:title "Production Hardening" .
+---
+
+# F-048: Production Hardening
+
+Human-readable content here...
+```
+
+## Installation
+
+```bash
+pip install yurtle-rdflib
+```
+
+## Quick Start
+
+### Parse a Yurtle file
+
+```python
+from rdflib import Graph
+import yurtle_rdflib  # Registers the plugin
+
+# Parse a single file
+graph = Graph()
+graph.parse("document.md", format="yurtle")
+
+# Query with SPARQL
+results = graph.query("""
+    SELECT ?title ?status WHERE {
+        ?task yurtle:title ?title ;
+              pm:status ?status .
+    }
+""")
+```
+
+### Load an entire workspace
+
+```python
+import yurtle_rdflib
+
+# Load all .md files in a directory
+graph = yurtle_rdflib.load_workspace("my-project/")
+
+# Query across all documents
+results = graph.query("""
+    SELECT ?doc ?title WHERE {
+        ?doc yurtle:title ?title .
+    }
+""")
+```
+
+### Serialize to Yurtle format
+
+```python
+from rdflib import Graph, URIRef, Literal
+import yurtle_rdflib
+
+graph = Graph()
+graph.add((
+    URIRef("urn:task:T-001"),
+    yurtle_rdflib.YURTLE.title,
+    Literal("My Task")
+))
+
+# Serialize with markdown content
+graph.serialize(
+    "output.md",
+    format="yurtle",
+    markdown_content="# My Task\n\nDescription here..."
+)
+```
+
+### Live bidirectional sync
+
+```python
+import yurtle_rdflib
+
+# Create a graph backed by the filesystem
+graph = yurtle_rdflib.create_live_graph("workspace/", auto_flush=True)
+
+# Changes persist immediately to files
+graph.add((subject, predicate, object))
+
+# File changes sync automatically
+graph.store.sync()
+```
+
+## Features
+
+### Parser
+
+- **Turtle frontmatter**: Native RDF parsing
+- **YAML frontmatter**: Automatic conversion to RDF triples
+- **Provenance tracking**: Each triple knows its source file
+- **Works with rdflib**: `graph.parse("file.md", format="yurtle")`
+
+### Serializer
+
+- **Round-trip safe**: Preserves markdown content
+- **Clean output**: Filters internal provenance triples
+- **Standard prefixes**: Auto-binds common namespaces
+- **Works with rdflib**: `graph.serialize("file.md", format="yurtle")`
+
+### YurtleStore
+
+- **Bidirectional sync**: Graph ↔ Filesystem
+- **Hash-based change detection**: Efficient incremental sync
+- **Auto-flush mode**: Immediate persistence
+- **SPARQL queries**: Query files as a graph
+
+## Standard Namespaces
+
+```python
+from yurtle_rdflib import YURTLE, PM, BEING, VOYAGE, KNOWLEDGE, PROVENANCE
+
+# Use in your graphs
+graph.add((subject, YURTLE.title, Literal("My Document")))
+graph.add((task, PM.status, Literal("completed")))
+```
+
+| Prefix | Namespace | Purpose |
+|--------|-----------|---------|
+| `yurtle` | `https://yurtle.dev/schema/` | Core document properties |
+| `pm` | `https://yurtle.dev/pm/` | Project management |
+| `being` | `https://yurtle.dev/being/` | Agent/being properties |
+| `voyage` | `https://yurtle.dev/voyage/` | Journey/process tracking |
+| `knowledge` | `https://yurtle.dev/knowledge/` | Learning/knowledge |
+| `prov` | `https://yurtle.dev/provenance/` | Source file tracking |
+
+## API Reference
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `load_workspace(path)` | Load all Yurtle files into a unified graph |
+| `save_workspace(graph, path)` | Save graph back to workspace files |
+| `create_live_graph(path)` | Create store-backed graph with live sync |
+| `parse_file(path)` | Parse a single Yurtle file |
+| `serialize_file(graph, path)` | Serialize graph to Yurtle file |
+| `verify_plugins()` | Check plugin registration status |
+
+### Classes
+
+| Class | Description |
+|-------|-------------|
+| `YurtleParser` | Core parser for Yurtle documents |
+| `YurtleWriter` | Core writer for Yurtle documents |
+| `YurtleDocument` | Parsed document with graph + content |
+| `YurtleStore` | RDFlib Store for bidirectional sync |
+| `YurtleRDFlibParser` | RDFlib Parser plugin |
+| `YurtleRDFlibSerializer` | RDFlib Serializer plugin |
+
+## Examples
+
+### Task Management System
+
+```python
+import yurtle_rdflib
+from rdflib import URIRef, Literal
+
+# Load all tasks
+graph = yurtle_rdflib.load_workspace("tasks/")
+
+# Find incomplete tasks
+results = graph.query("""
+    PREFIX pm: <https://yurtle.dev/pm/>
+    SELECT ?task ?title WHERE {
+        ?task pm:status "pending" ;
+              yurtle:title ?title .
+    }
+""")
+
+for row in results:
+    print(f"TODO: {row.title}")
+```
+
+### Knowledge Base
+
+```python
+import yurtle_rdflib
+
+# Create live-synced knowledge base
+kb = yurtle_rdflib.create_live_graph("knowledge/", auto_flush=True)
+
+# Add knowledge (persists immediately)
+kb.add((
+    URIRef("urn:concept:python"),
+    yurtle_rdflib.KNOWLEDGE.relatedTo,
+    URIRef("urn:concept:programming")
+))
+
+# Query relationships
+results = kb.query("""
+    SELECT ?concept ?related WHERE {
+        ?concept knowledge:relatedTo ?related .
+    }
+""")
+```
+
+## Yurtle Format Specification
+
+See the [Yurtle Specification](https://github.com/hankh95/yurtle) for the full format documentation.
+
+### Supported Frontmatter Types
+
+**Turtle (recommended)**:
+```markdown
+---
+@prefix yurtle: <https://yurtle.dev/schema/> .
+
+<urn:doc:example> a yurtle:Document ;
+    yurtle:title "Example" .
+---
+```
+
+**YAML (auto-converted)**:
+```markdown
+---
+id: example
+title: Example
+type: document
+tags: [example, demo]
+---
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/hankh95/yurtle-rdflib.git
+cd yurtle-rdflib
+
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=yurtle_rdflib
+
+# Format code
+black src tests
+ruff check src tests
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Related Projects
+
+- [Yurtle Specification](https://github.com/hankh95/yurtle) - The Yurtle format spec
+- [RDFlib](https://github.com/RDFLib/rdflib) - Python RDF library