linksql 0.1.0__tar.gz

linksql-0.1.0/.gitignore

@@ -0,0 +1,162 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+.playwright-mcp/
+
+# Optional stylelint cache
+.stylelintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.*
+!.env.example
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Sveltekit cache directory
+.svelte-kit/
+
+# vitepress build output
+**/.vitepress/dist
+
+# vitepress cache directory
+**/.vitepress/cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Firebase cache directory
+.firebase/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v3
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+
+# Vite logs files
+vite.config.js.timestamp-*
+vite.config.ts.timestamp-*
+
+# jscpd reports
+reports/
+
+# === Polyglot reference implementations (rust/, python/, csharp/) ===
+# Rust build output
+rust/target/
+# Python virtual environments and caches/build artifacts (scoped to python/ so the JS repo is unaffected)
+python/.venv/
+python/venv/
+python/**/__pycache__/
+python/**/*.py[cod]
+python/.pytest_cache/
+python/.mypy_cache/
+python/.ruff_cache/
+python/**/*.egg-info/
+python/.coverage
+python/coverage.xml
+# C# build output (scoped to csharp/ so the repo-root bin/linksql.js is never ignored)
+csharp/**/bin/
+csharp/**/obj/
+csharp/**/TestResults/

linksql-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: linksql
+Version: 0.1.0
+Summary: Python reference implementation of LinksQL — an associative query language built around a single substitution operation.
+Project-URL: Homepage, https://github.com/link-foundation/linksql
+Project-URL: Repository, https://github.com/link-foundation/linksql
+Project-URL: Issues, https://github.com/link-foundation/linksql/issues
+License: Unlicense
+Keywords: associative,doublets,links,linksql,query
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+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
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# LinksQL (Python reference implementation)
+
+A faithful, behaviourally-identical Python port of the JavaScript reference
+implementation of **LinksQL** — an associative query language built on **one data
+primitive** (the link, a doublet) and **one operation** (substitution).
+
+Everything is a link: a triple `(index: source target)` of positive integers. A
+link whose `source` and `target` both equal its own `index` is a *point*, the
+atom of the graph. A query is a pair of pattern lists — a *restriction* and a
+*substitution* — written `(restriction) (substitution)`; the four CRUD
+behaviours (read, create, update, delete) are derived from how the two lists line
+up positionally.
+
+The JavaScript implementation in `../js/src` is the ground truth, and the
+normative behaviour is defined in
+[`../docs/SPECIFICATION.md`](../docs/SPECIFICATION.md).
+
+A link has exactly two endpoints, so a relation like "alice loves bob" is the
+higher-order link `((alice loves) bob)` — every pattern carries 0 or 2 values.
+
+## Quick start
+
+```python
+from linksql import Database
+
+db = Database()
+db.query("() (((alice loves) bob))")  # create the higher-order link
+report = db.query("(($i: $s $t))")    # read every relation
+print(report.operation, report.matched)
+```
+
+## Development
+
+This package uses a src layout. Create a virtual environment and install it with
+the development extras:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Then run the checks (all must pass):
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest tests/ -v
+```
+
+## Public API
+
+The top-level `linksql` package re-exports the engine surface:
+
+- `linksql.lino` — `tokenize`, `parse`, `serialize`, `serialize_all`, the AST
+  types (`Ref`, `Link`/`LinkNode`, `Node`, `Token`) and `LinoSyntaxError`.
+- `linksql.store` — `LinksStore`, `Link`, `LinkIntegrityError`.
+- `linksql.names` — `Names`, `UnknownNameError`.
+- `linksql.substitution` — `link_slots`, `match_restriction`, `execute`,
+  `link_matches`, `Context`, and `SubstitutionError`.
+- `linksql.query` — `Database`, `split_query`, `link_to_lino`, `QueryReport`,
+  `QueryError`.
+- `linksql.schema` — the GraphQL-class schema model: `Schema`, `Relation`,
+  `NamedQuery`, `NamedSubscription`, and `SchemaError`.

linksql-0.1.0/README.md

@@ -0,0 +1,65 @@
+# LinksQL (Python reference implementation)
+
+A faithful, behaviourally-identical Python port of the JavaScript reference
+implementation of **LinksQL** — an associative query language built on **one data
+primitive** (the link, a doublet) and **one operation** (substitution).
+
+Everything is a link: a triple `(index: source target)` of positive integers. A
+link whose `source` and `target` both equal its own `index` is a *point*, the
+atom of the graph. A query is a pair of pattern lists — a *restriction* and a
+*substitution* — written `(restriction) (substitution)`; the four CRUD
+behaviours (read, create, update, delete) are derived from how the two lists line
+up positionally.
+
+The JavaScript implementation in `../js/src` is the ground truth, and the
+normative behaviour is defined in
+[`../docs/SPECIFICATION.md`](../docs/SPECIFICATION.md).
+
+A link has exactly two endpoints, so a relation like "alice loves bob" is the
+higher-order link `((alice loves) bob)` — every pattern carries 0 or 2 values.
+
+## Quick start
+
+```python
+from linksql import Database
+
+db = Database()
+db.query("() (((alice loves) bob))")  # create the higher-order link
+report = db.query("(($i: $s $t))")    # read every relation
+print(report.operation, report.matched)
+```
+
+## Development
+
+This package uses a src layout. Create a virtual environment and install it with
+the development extras:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Then run the checks (all must pass):
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest tests/ -v
+```
+
+## Public API
+
+The top-level `linksql` package re-exports the engine surface:
+
+- `linksql.lino` — `tokenize`, `parse`, `serialize`, `serialize_all`, the AST
+  types (`Ref`, `Link`/`LinkNode`, `Node`, `Token`) and `LinoSyntaxError`.
+- `linksql.store` — `LinksStore`, `Link`, `LinkIntegrityError`.
+- `linksql.names` — `Names`, `UnknownNameError`.
+- `linksql.substitution` — `link_slots`, `match_restriction`, `execute`,
+  `link_matches`, `Context`, and `SubstitutionError`.
+- `linksql.query` — `Database`, `split_query`, `link_to_lino`, `QueryReport`,
+  `QueryError`.
+- `linksql.schema` — the GraphQL-class schema model: `Schema`, `Relation`,
+  `NamedQuery`, `NamedSubscription`, and `SchemaError`.

linksql-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "linksql"
+version = "0.1.0"
+description = "Python reference implementation of LinksQL — an associative query language built around a single substitution operation."
+readme = "README.md"
+license = {text = "Unlicense"}
+requires-python = ">=3.9"
+keywords = ["linksql", "links", "doublets", "associative", "query"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: The Unlicense (Unlicense)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.8.0",
+    "mypy>=1.13.0",
+    "pytest>=8.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/link-foundation/linksql"
+Repository = "https://github.com/link-foundation/linksql"
+Issues = "https://github.com/link-foundation/linksql/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/linksql"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "N", "UP", "B", "C4", "DTZ", "T10", "EM", "ISC",
+    "ICN", "PIE", "PT", "Q", "RSE", "RET", "SIM", "TID", "ARG", "PTH",
+    "ERA", "PL", "PERF", "RUF",
+]
+ignore = [
+    "E501",
+    "PLR0913",
+    "PLR2004",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "ARG", "PLR2004"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+skip-magic-trailing-comma = false
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+strict_equality = true
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers"
+testpaths = ["tests"]
+pythonpath = ["src"]

linksql-0.1.0/src/linksql/__init__.py

@@ -0,0 +1,117 @@
+"""LinksQL — a Python reference implementation.
+
+LinksQL is an associative query language built on **one data primitive** (the
+link, a doublet) and **one operation** (substitution). This package is a
+faithful, behaviourally-identical port of the JavaScript reference implementation
+in ``../src``; the normative specification lives in ``../docs/SPECIFICATION.md``.
+
+The public surface mirrors the JavaScript package entry point: parse and
+serialise LiNo, build a :class:`LinksStore`, and run queries through a
+:class:`Database`.
+"""
+
+from __future__ import annotations
+
+from .lino import (
+    Link as LinkNode,
+)
+from .lino import (
+    LinoSyntaxError,
+    Node,
+    Ref,
+    Token,
+    parse,
+    serialize,
+    serialize_all,
+    tokenize,
+)
+from .names import Names, UnknownNameError
+from .protocol import (
+    JSON_CONTENT_TYPE,
+    LINO_CONTENT_TYPE,
+    decode,
+    encode,
+    escape_reference,
+    prefers_json,
+)
+from .query import (
+    Database,
+    Introspection,
+    MatchRow,
+    QueryError,
+    QueryReport,
+    SplitQuery,
+    link_to_lino,
+    patterns_of,
+    split_query,
+)
+from .schema import (
+    NamedQuery,
+    NamedSubscription,
+    Relation,
+    Schema,
+    SchemaError,
+)
+from .store import Link, LinkIntegrityError, LinksStore
+from .substitution import (
+    Context,
+    RawResult,
+    Row,
+    Slots,
+    Spec,
+    SubstitutionError,
+    execute,
+    link_matches,
+    link_slots,
+    match_restriction,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "JSON_CONTENT_TYPE",
+    "LINO_CONTENT_TYPE",
+    "Context",
+    "Database",
+    "Introspection",
+    "Link",
+    "LinkIntegrityError",
+    "LinkNode",
+    "LinksStore",
+    "LinoSyntaxError",
+    "MatchRow",
+    "NamedQuery",
+    "NamedSubscription",
+    "Names",
+    "Node",
+    "QueryError",
+    "QueryReport",
+    "RawResult",
+    "Ref",
+    "Relation",
+    "Row",
+    "Schema",
+    "SchemaError",
+    "Slots",
+    "Spec",
+    "SplitQuery",
+    "SubstitutionError",
+    "Token",
+    "UnknownNameError",
+    "__version__",
+    "decode",
+    "encode",
+    "escape_reference",
+    "execute",
+    "link_matches",
+    "link_slots",
+    "link_to_lino",
+    "match_restriction",
+    "parse",
+    "patterns_of",
+    "prefers_json",
+    "serialize",
+    "serialize_all",
+    "split_query",
+    "tokenize",
+]