linked-data-python 0.0.4__tar.gz → 0.2.1__tar.gz

linked_data_python-0.2.1/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: linked-data-python
+Version: 0.2.1
+Summary: Python extended with Semantic Web primitives: IRIs, RDF literals and Turtle-notation graphs as expressions, transpiled by island parsing.
+Author-email: Maxime Lefrançois <maxime.lefrancois@emse.fr>
+License: MIT
+Project-URL: Homepage, https://github.com/linked-data-python/ldpy
+Project-URL: Documentation, https://linked-data-python.readthedocs.io/
+Project-URL: Source, https://github.com/linked-data-python/ldpy
+Keywords: rdf,semantic-web,turtle,sparql,transpiler,linked-data,knowledge-graph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Pre-processors
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: rdflib>=6.0
+Provides-Extra: lsp
+Requires-Dist: python-lsp-server; extra == "lsp"
+Requires-Dist: pyflakes; extra == "lsp"
+Provides-Extra: debug
+Requires-Dist: debugpy; extra == "debug"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: highlight
+Requires-Dist: pygments>=2.14; extra == "highlight"
+Provides-Extra: format
+Requires-Dist: black>=24; extra == "format"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: pygments>=2.14; extra == "docs"
+Dynamic: license-file
+
+# Linked-Data Python
+
+**Python, with the Semantic Web in its syntax.** IRIs, prefixed names, RDF
+literals, SPARQL variables and whole graphs written in Turtle's notation are
+expressions of the language — interpolated with arbitrary Python, transpiled to
+plain Python, running on rdflib.
+
+![](ldpyIcon.png)
+
+```text
+@prefix sosa: <http://www.w3.org/ns/sosa/> .
+@base <http://example.org/building/> .
+
+def observation(sensor, value):
+    return g{ f<sensor/{sensor}> a sosa:Sensor ;
+                  sosa:madeObservation [ sosa:hasSimpleResult {value} ] }
+```
+
+The language also reads and queries, writes into a current graph, and turns
+rows into triples:
+
+```text
+@prefix ex: <http://example.org/> .
+@graph as kg
+for @bindings in csv.DictReader(f):             # any iterable of mappings
+    +{ e<http://example.org/{?id}> ex:value ?v }
+
+for s, v in m{ ?s ex:value ?v }:                # a graph pattern, no engine
+    ...
+rows = s{ SELECT ?s WHERE { ?s ex:value ?v } }  # all of SPARQL, checked early
+adult = e{ ?age >= 18 && BOUND(?name) }         # deferred, over bindings
+```
+
+`.ldpy` files are **transpiled to plain Python** by an *island parser*: the
+Python is copied verbatim — every valid Python file is a valid ldpy file,
+returned byte-identical — and only the RDF islands are parsed and rewritten.
+The transpiler is ~1 500 lines with no parsing dependency and sustains
+56 000–110 000 source lines/s depending on island density.
+
+## Quick start
+
+```text
+git clone https://github.com/linked-data-python/ldpy.git
+cd linked-data-python && pip install -e .       # or: pip install -e .[lsp,debug]
+
+ldpy program.ldpy             # run a file
+ldpy                          # interactive console
+ldpy-lsp                      # language server (LSP, stdio)
+ldpy-debug program.ldpy       # debug via the shadow .py + debugpy
+```
+
+From Python: `import ldpy; ldpy.install()` then `import yourmodule` finds
+`yourmodule.ldpy` on `sys.path`.
+
+## Documentation
+
+Read it at **<https://linked-data-python.readthedocs.io/>** — start with the
+home page for an overview, then:
+
+- **Tutorials** — [first steps](https://linked-data-python.readthedocs.io/en/latest/tutorials/getting-started/), then
+  [build a knowledge graph](https://linked-data-python.readthedocs.io/en/latest/tutorials/build-a-knowledge-graph/) from
+  tabular data.
+- **How-to guides** — [run & import](https://linked-data-python.readthedocs.io/en/latest/how-to/run-and-import/),
+  [build graphs from tables](https://linked-data-python.readthedocs.io/en/latest/how-to/build-graphs-from-tables/),
+  [read and query](https://linked-data-python.readthedocs.io/en/latest/how-to/query-a-graph/),
+  [migrate from rdflib](https://linked-data-python.readthedocs.io/en/latest/how-to/migrate-from-rdflib/),
+  [VS Code](https://linked-data-python.readthedocs.io/en/latest/how-to/use-vscode/), [debugging](https://linked-data-python.readthedocs.io/en/latest/how-to/debug/),
+  [language server](https://linked-data-python.readthedocs.io/en/latest/how-to/language-server/),
+  [highlighting](https://linked-data-python.readthedocs.io/en/latest/how-to/highlight-ldpy/).
+- **Reference** — [the language](https://linked-data-python.readthedocs.io/en/latest/reference/language/), one page
+  per island family; [SPARQL expressions](https://linked-data-python.readthedocs.io/en/latest/reference/sparql-expressions/);
+  [CLI](https://linked-data-python.readthedocs.io/en/latest/reference/cli/); [Python API](https://linked-data-python.readthedocs.io/en/latest/reference/api/);
+  [language map formats](https://linked-data-python.readthedocs.io/en/latest/reference/language-map/).
+- **Explanation** — [why](https://linked-data-python.readthedocs.io/en/latest/explanation/why/),
+  [what real RDF code does](https://linked-data-python.readthedocs.io/en/latest/explanation/what-real-code-does/) (the
+  corpus study that drove the language's second wave),
+  [designing the syntax](https://linked-data-python.readthedocs.io/en/latest/explanation/designing-the-syntax/),
+  [island parsing](https://linked-data-python.readthedocs.io/en/latest/explanation/island-parsing/),
+  [emission & semantics](https://linked-data-python.readthedocs.io/en/latest/explanation/emission-and-semantics/),
+  [tooling](https://linked-data-python.readthedocs.io/en/latest/explanation/tooling/),
+  [how this is tested](https://linked-data-python.readthedocs.io/en/latest/explanation/how-it-is-tested/).
+
+Every `ldpy` and `python` block in the documentation is executed by the test
+suite, and its assertions are the test.
+
+## Tooling
+
+- **VS Code extension** (`vscode-ldpy`): highlighting (TextMate + LSP semantic
+  tokens), diagnostics as you type, completion/hover/definition, run and debug.
+- **Language server**: dependency-free, LSP over stdio; delegates Python
+  intelligence to an unmodified `pylsp` through the language map.
+- **Debugging**: `.ldpy` code compiles in `.ldpy` coordinates, so `pdb` and
+  `debugpy` work directly; `ldpy.build` also materialises real `.py` shadow
+  files with JSON and Source Map v3 maps.
+- **Highlighting anywhere else**: the package registers a Pygments lexer built
+  on the language map — MkDocs, Sphinx and `pygmentize` colour `.ldpy` with no
+  further setup.
+- **Benchmark harness** (`bench/`): seeded random program generator and
+  reproducible throughput campaigns.
+
+## Project
+
+- Tests: `python -m pytest tests/ -q` — byte-identity over the CPython standard
+  library, golden transpilation, RDF isomorphism against rdflib as an oracle,
+  LSP end to end, executable documentation.
+- Licence: MIT. Author: Maxime Lefrançois (Mines Saint-Étienne).
+- The 2023 ANTLR-based release (v1, PyPI 0.0.4) is preliminary work, superseded
+  by this island-parsing rewrite (the `main` branch of this repository; the 2023
+  code remains on the legacy gitlab.com/coswot/ldpy).
+
+## Design records
+
+Every non-trivial choice in this repository is written down, one file per
+decision, in the [`pilotage`](https://github.com/linked-data-python/pilotage) repository. Comments and docs
+cite them by identifier — `ldpy/024`, `vscode/103` — which resolves to
+[`design/`](https://github.com/linked-data-python/pilotage/tree/main/design).

linked_data_python-0.2.1/README.md

@@ -0,0 +1,116 @@
+# Linked-Data Python
+
+**Python, with the Semantic Web in its syntax.** IRIs, prefixed names, RDF
+literals, SPARQL variables and whole graphs written in Turtle's notation are
+expressions of the language — interpolated with arbitrary Python, transpiled to
+plain Python, running on rdflib.
+
+![](ldpyIcon.png)
+
+```text
+@prefix sosa: <http://www.w3.org/ns/sosa/> .
+@base <http://example.org/building/> .
+
+def observation(sensor, value):
+    return g{ f<sensor/{sensor}> a sosa:Sensor ;
+                  sosa:madeObservation [ sosa:hasSimpleResult {value} ] }
+```
+
+The language also reads and queries, writes into a current graph, and turns
+rows into triples:
+
+```text
+@prefix ex: <http://example.org/> .
+@graph as kg
+for @bindings in csv.DictReader(f):             # any iterable of mappings
+    +{ e<http://example.org/{?id}> ex:value ?v }
+
+for s, v in m{ ?s ex:value ?v }:                # a graph pattern, no engine
+    ...
+rows = s{ SELECT ?s WHERE { ?s ex:value ?v } }  # all of SPARQL, checked early
+adult = e{ ?age >= 18 && BOUND(?name) }         # deferred, over bindings
+```
+
+`.ldpy` files are **transpiled to plain Python** by an *island parser*: the
+Python is copied verbatim — every valid Python file is a valid ldpy file,
+returned byte-identical — and only the RDF islands are parsed and rewritten.
+The transpiler is ~1 500 lines with no parsing dependency and sustains
+56 000–110 000 source lines/s depending on island density.
+
+## Quick start
+
+```text
+git clone https://github.com/linked-data-python/ldpy.git
+cd linked-data-python && pip install -e .       # or: pip install -e .[lsp,debug]
+
+ldpy program.ldpy             # run a file
+ldpy                          # interactive console
+ldpy-lsp                      # language server (LSP, stdio)
+ldpy-debug program.ldpy       # debug via the shadow .py + debugpy
+```
+
+From Python: `import ldpy; ldpy.install()` then `import yourmodule` finds
+`yourmodule.ldpy` on `sys.path`.
+
+## Documentation
+
+Read it at **<https://linked-data-python.readthedocs.io/>** — start with the
+home page for an overview, then:
+
+- **Tutorials** — [first steps](https://linked-data-python.readthedocs.io/en/latest/tutorials/getting-started/), then
+  [build a knowledge graph](https://linked-data-python.readthedocs.io/en/latest/tutorials/build-a-knowledge-graph/) from
+  tabular data.
+- **How-to guides** — [run & import](https://linked-data-python.readthedocs.io/en/latest/how-to/run-and-import/),
+  [build graphs from tables](https://linked-data-python.readthedocs.io/en/latest/how-to/build-graphs-from-tables/),
+  [read and query](https://linked-data-python.readthedocs.io/en/latest/how-to/query-a-graph/),
+  [migrate from rdflib](https://linked-data-python.readthedocs.io/en/latest/how-to/migrate-from-rdflib/),
+  [VS Code](https://linked-data-python.readthedocs.io/en/latest/how-to/use-vscode/), [debugging](https://linked-data-python.readthedocs.io/en/latest/how-to/debug/),
+  [language server](https://linked-data-python.readthedocs.io/en/latest/how-to/language-server/),
+  [highlighting](https://linked-data-python.readthedocs.io/en/latest/how-to/highlight-ldpy/).
+- **Reference** — [the language](https://linked-data-python.readthedocs.io/en/latest/reference/language/), one page
+  per island family; [SPARQL expressions](https://linked-data-python.readthedocs.io/en/latest/reference/sparql-expressions/);
+  [CLI](https://linked-data-python.readthedocs.io/en/latest/reference/cli/); [Python API](https://linked-data-python.readthedocs.io/en/latest/reference/api/);
+  [language map formats](https://linked-data-python.readthedocs.io/en/latest/reference/language-map/).
+- **Explanation** — [why](https://linked-data-python.readthedocs.io/en/latest/explanation/why/),
+  [what real RDF code does](https://linked-data-python.readthedocs.io/en/latest/explanation/what-real-code-does/) (the
+  corpus study that drove the language's second wave),
+  [designing the syntax](https://linked-data-python.readthedocs.io/en/latest/explanation/designing-the-syntax/),
+  [island parsing](https://linked-data-python.readthedocs.io/en/latest/explanation/island-parsing/),
+  [emission & semantics](https://linked-data-python.readthedocs.io/en/latest/explanation/emission-and-semantics/),
+  [tooling](https://linked-data-python.readthedocs.io/en/latest/explanation/tooling/),
+  [how this is tested](https://linked-data-python.readthedocs.io/en/latest/explanation/how-it-is-tested/).
+
+Every `ldpy` and `python` block in the documentation is executed by the test
+suite, and its assertions are the test.
+
+## Tooling
+
+- **VS Code extension** (`vscode-ldpy`): highlighting (TextMate + LSP semantic
+  tokens), diagnostics as you type, completion/hover/definition, run and debug.
+- **Language server**: dependency-free, LSP over stdio; delegates Python
+  intelligence to an unmodified `pylsp` through the language map.
+- **Debugging**: `.ldpy` code compiles in `.ldpy` coordinates, so `pdb` and
+  `debugpy` work directly; `ldpy.build` also materialises real `.py` shadow
+  files with JSON and Source Map v3 maps.
+- **Highlighting anywhere else**: the package registers a Pygments lexer built
+  on the language map — MkDocs, Sphinx and `pygmentize` colour `.ldpy` with no
+  further setup.
+- **Benchmark harness** (`bench/`): seeded random program generator and
+  reproducible throughput campaigns.
+
+## Project
+
+- Tests: `python -m pytest tests/ -q` — byte-identity over the CPython standard
+  library, golden transpilation, RDF isomorphism against rdflib as an oracle,
+  LSP end to end, executable documentation.
+- Licence: MIT. Author: Maxime Lefrançois (Mines Saint-Étienne).
+- The 2023 ANTLR-based release (v1, PyPI 0.0.4) is preliminary work, superseded
+  by this island-parsing rewrite (the `main` branch of this repository; the 2023
+  code remains on the legacy gitlab.com/coswot/ldpy).
+
+## Design records
+
+Every non-trivial choice in this repository is written down, one file per
+decision, in the [`pilotage`](https://github.com/linked-data-python/pilotage) repository. Comments and docs
+cite them by identifier — `ldpy/024`, `vscode/103` — which resolves to
+[`design/`](https://github.com/linked-data-python/pilotage/tree/main/design).

linked_data_python-0.2.1/ldpy/__init__.py

@@ -0,0 +1,47 @@
+"""Linked-Data Python (ldpy) v2.
+
+An "island parsing" transpiler: Python is copied through untouched, the RDF
+islands (@prefix, @base, IRIs, prefixed names, RDF literals, variables,
+graphs g{...}) are rewritten into Python expressions built on ldpy.runtime.
+
+The historical ANTLR chain (v1) is still reachable through the ldpy.rewriter
+package but is no longer imported by default.
+"""
+
+from ldpy.transpiler import transpile, LdpySyntaxError, LdpyWarning
+from ldpy.importer import install, uninstall, install_excepthook
+
+#: Read from the installed distribution rather than written here: two copies
+#: of a version number drift, and this one had — a 0.2.0 install announced
+#: itself as 0.1.0.dev0 in the editor status bar. The fallback covers a source
+#: tree that was never installed.
+try:
+    from importlib.metadata import PackageNotFoundError, version as _version
+    try:
+        __version__ = _version("linked-data-python")
+    except PackageNotFoundError:                      # pragma: no cover
+        __version__ = "0.0.0+unknown"
+    del _version, PackageNotFoundError
+except ImportError:                                   # pragma: no cover
+    __version__ = "0.0.0+unknown"
+__date__ = "2026-08-26"
+
+
+def transform_source(source, filename="<ldpy>"):
+    """Simplified v1 compatibility: returns (python_code, prefixes, map)."""
+    result = transpile(source, filename)
+    return result.code, result.prefixes, result.map
+
+
+def Coercion(rules):
+    """Politique de conversion Python -> RDF (fiche 020) — voir
+    ldpy.runtime.Coercion; exposed here as public API."""
+    from ldpy.runtime import Coercion as _C
+    return _C(rules)
+
+
+def instantiateBGP(input, solutionMappings, initialGraph=None):
+    """Instantiate a graph template with solution mappings
+    (re-export of ldpy.runtime.instantiateBGP, v1 compatibility)."""
+    from ldpy.runtime import instantiateBGP as _f
+    return _f(input, solutionMappings, initialGraph)

linked_data_python-0.2.1/ldpy/__main__.py

@@ -0,0 +1,82 @@
+"""ldpy — command-line execution.
+
+Usage :
+    python -m ldpy source.ldpy       # transpile and run
+    python -m ldpy -s source.ldpy    # also print the transformed code
+    python -m ldpy -t source.ldpy    # transpile seulement (stdout)
+"""
+
+import argparse
+import os
+import sys
+
+import ldpy
+from ldpy.transpiler import transpile, LdpySyntaxError
+from ldpy.transpiler.linemap import compile_mapped
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="ldpy",
+        description="ldpy extends Python syntax with Semantic Web "
+                    "primitives (IRIs, RDF literals, graphs).")
+    parser.add_argument("-v", "--version", action="store_true",
+                        help="print the version and exit.")
+    parser.add_argument("-s", "--show-changes", action="store_true",
+                        help="print the transformed code before running it.")
+    parser.add_argument("-t", "--transpile-only", action="store_true",
+                        help="write the transformed code to stdout, do not run.")
+    parser.add_argument("-i", "--interactive", action="store_true",
+                        help="open the interactive console after the script.")
+    parser.add_argument("-m", "--map", action="store_true",
+                        help="also write the language map (<source>.map).")
+    parser.add_argument("source", nargs="?",
+                        help=".ldpy (or .py) file to run.")
+    args = parser.parse_args(argv)
+
+    if args.version:
+        print("ldpy " + ldpy.__version__)
+        return 0
+    if not args.source:
+        from ldpy.console import interact
+        interact()
+        return 0
+
+    with open(args.source, "r", encoding="utf-8") as f:
+        source = f.read()
+    try:
+        result = transpile(source, args.source)
+    except LdpySyntaxError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    for w in result.warnings:
+        print(str(w), file=sys.stderr)
+    if args.map:
+        with open(args.source + ".map", "w", encoding="utf-8") as f:
+            f.write(result.map.to_json(indent=1))
+    if args.transpile_only:
+        sys.stdout.write(result.code)
+        return 0
+    if args.show_changes:
+        print("ldpy>>> ======== transformed code ========", file=sys.stderr)
+        for lineno, line in enumerate(result.code.split("\n"), 1):
+            print("ldpy>>> %3d: %s" % (lineno, line), file=sys.stderr)
+        print("ldpy>>> =================================", file=sys.stderr)
+
+    ldpy.install()
+    from ldpy.importer import MAPS
+    src_path = os.path.abspath(args.source)
+    MAPS[args.source] = MAPS[src_path] = result.map
+    # remapped compilation: tracebacks, pdb and debugpy all speak in
+    # .ldpy coordinates (record ldpy/011)
+    code = compile_mapped(result.code, result.map, src_path)
+    g = {"__name__": "__main__", "__file__": src_path}
+    exec(code, g)
+    if args.interactive:
+        from ldpy.console import interact
+        interact(locals=g, prefixes=result.prefixes, base=result.base)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

linked_data_python-0.2.1/ldpy/build.py

@@ -0,0 +1,91 @@
+"""Materialisation: transpile .ldpy files into a shadow directory.
+
+`python -m ldpy.build src/ -o .ldpy-build` mirrors the tree and writes:
+  - <module>.py        (generated code)
+  - <module>.ldpy.map  (language map JSON)
+
+This is the base of debugging (debugpy runs on the shadow .py files) and of
+language server (voir docs/explanation/tooling.md)."""
+
+import os
+import sys
+import argparse
+
+from ldpy.transpiler import transpile, LdpySyntaxError
+
+DEFAULT_OUT = ".ldpy-build"
+
+
+def build_file(src_path, out_dir, rel=None):
+    """Transpile one file; returns (py_path, map_path, result)."""
+    with open(src_path, "r", encoding="utf-8") as f:
+        source = f.read()
+    rel = rel or os.path.basename(src_path)
+    stem = rel[:-5] if rel.endswith(".ldpy") else rel
+    py_path = os.path.join(out_dir, stem + ".py")
+    map_path = os.path.join(out_dir, stem + ".ldpy.map")
+    result = transpile(source, src_path)
+    result.map.generated_name = py_path
+    os.makedirs(os.path.dirname(py_path) or ".", exist_ok=True)
+    with open(py_path, "w", encoding="utf-8") as f:
+        f.write(result.code)
+    with open(map_path, "w", encoding="utf-8") as f:
+        f.write(result.map.to_json(indent=1))
+    # Source Map v3: for standard tooling
+    with open(py_path + ".map", "w", encoding="utf-8") as f:
+        f.write(result.map.to_sourcemap_v3_json())
+    return py_path, map_path, result
+
+
+def build_tree(root, out_dir):
+    """Recursively transpile every .ldpy under root. Plain .py files are
+    copied as they are (a mixed package must stay importable)."""
+    built, errors = [], []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames
+                       if d not in (DEFAULT_OUT, "__pycache__", ".git")]
+        for name in filenames:
+            src = os.path.join(dirpath, name)
+            rel = os.path.relpath(src, root)
+            if name.endswith(".ldpy"):
+                try:
+                    built.append(build_file(src, out_dir, rel))
+                except LdpySyntaxError as e:
+                    errors.append(e)
+            elif name.endswith(".py"):
+                dst = os.path.join(out_dir, rel)
+                os.makedirs(os.path.dirname(dst) or ".", exist_ok=True)
+                with open(src, "rb") as fi, open(dst, "wb") as fo:
+                    fo.write(fi.read())
+    return built, errors
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="ldpy.build",
+        description="Transpile .ldpy files into a shadow directory "
+                    "(.py + .ldpy.map).")
+    parser.add_argument("source", help=".ldpy file or directory")
+    parser.add_argument("-o", "--out", default=DEFAULT_OUT,
+                        help="output directory (default: %(default)s)")
+    args = parser.parse_args(argv)
+
+    if os.path.isdir(args.source):
+        built, errors = build_tree(args.source, args.out)
+        for e in errors:
+            print(str(e), file=sys.stderr)
+        print("%d file(s) transpiled into %s" % (len(built), args.out))
+        return 1 if errors else 0
+    try:
+        py_path, _, result = build_file(args.source, args.out)
+    except LdpySyntaxError as e:
+        print(str(e), file=sys.stderr)
+        return 1
+    for w in result.warnings:
+        print(str(w), file=sys.stderr)
+    print(py_path)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

linked_data_python-0.2.1/ldpy/console.py

@@ -0,0 +1,116 @@
+"""Console interactive Linked-Data Python .
+
+The point of the `ideas` package in v1 was to enter the interpreter and type
+ldpy directly. This console does it without `ideas`: every entry is
+transpiled then compiled; the state of top-level @prefix/@base persists from
+one entry to the next (declarations made inside a block die with the entry —
+block scope obliges).
+
+    $ python -m ldpy                      # console
+    $ python -m ldpy -i script.ldpy       # run, then open the console
+"""
+
+import atexit
+import code
+import codeop
+import os
+import sys
+
+import ldpy
+from ldpy.transpiler import LdpySyntaxError
+from ldpy.transpiler.core import Transpiler, PRELUDE
+
+HISTORY_FILE = os.path.join(os.path.expanduser("~"), ".ldpy_history")
+HISTORY_LENGTH = 1000
+
+
+def _setup_readline(locals):
+    """Line editing (arrows, Ctrl-A/E…), persistent history and Tab
+    completion on console names. A no-op if the readline module is missing
+    (Windows without pyreadline)."""
+    try:
+        import readline
+        import rlcompleter
+    except ImportError:
+        return
+    readline.set_completer(rlcompleter.Completer(locals).complete)
+    if "libedit" in (getattr(readline, "__doc__", "") or ""):
+        readline.parse_and_bind("bind ^I rl_complete")   # macOS libedit
+    else:
+        readline.parse_and_bind("tab: complete")
+    try:
+        readline.read_history_file(HISTORY_FILE)
+    except OSError:
+        pass
+    readline.set_history_length(HISTORY_LENGTH)
+
+    def _save():
+        try:
+            readline.write_history_file(HISTORY_FILE)
+        except OSError:
+            pass
+    atexit.register(_save)
+
+BANNER = ("ldpy %s — console Linked-Data Python (Python %s)\n"
+          "RDF islands are accepted: @prefix, <iri>, ex:name, g{ ... }, ?v")
+
+
+class LdpyConsole(code.InteractiveConsole):
+    """Interactive console: transpile every entry before compiling it;
+    top-level @prefix/@base persist between entries."""
+
+    def __init__(self, locals=None, filename="<console>",
+                 prefixes=None, base=None):
+        if locals is None:
+            locals = {"__name__": "__console__", "__doc__": None}
+        super().__init__(locals=locals, filename=filename)
+        # the runtime prelude is installed once and for all
+        if "__namespaces__" not in self.locals:
+            exec(PRELUDE, self.locals)
+        self._prefixes = dict(prefixes or {})
+        self._prefix_cols = {k: 0 for k in self._prefixes}
+        self._base = base
+
+    def runsource(self, source, filename=None, symbol="single"):
+        """Transpile then compile one entry; True = incomplete entry
+        (unclosed island or Python block), False = handled."""
+        filename = filename or self.filename
+        t = Transpiler(source, filename, emit_prelude=False)
+        t.prefixes = dict(self._prefixes)
+        t._prefix_col = dict(self._prefix_cols)
+        t.base = self._base
+        try:
+            result = t.run()
+        except LdpySyntaxError as e:
+            if getattr(e, "at_eof", False):
+                return True          # unclosed island: wait for more
+            self.write(str(e) + "\n")
+            return False
+        try:
+            code_obj = codeop.compile_command(result.code, filename, symbol)
+        except (SyntaxError, ValueError, OverflowError):
+            self.showsyntaxerror(filename)
+            return False
+        if code_obj is None:
+            return True              # Python incomplet (def, if, ...)
+        # the entry is complete: top-level declarations persist
+        t._unwind_scopes(0)
+        self._prefixes = dict(t.prefixes)
+        self._prefix_cols = dict(t._prefix_col)
+        self._base = t.base
+        for w in result.warnings:
+            self.write(str(w) + "\n")
+        self.runcode(code_obj)
+        return False
+
+
+def interact(locals=None, prefixes=None, base=None):
+    """Open the ldpy console (banner, Ctrl-D to leave)."""
+    console = LdpyConsole(locals=locals, prefixes=prefixes, base=base)
+    _setup_readline(console.locals)
+    banner = BANNER % (ldpy.__version__, sys.version.split()[0])
+    try:
+        console.interact(banner=banner, exitmsg="")
+    except SystemExit:
+        pass
+    return console