linked-data-python 0.2.0__tar.gz → 0.5.1__tar.gz

{linked_data_python-0.2.0 → linked_data_python-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linked-data-python
-Version: 0.2.0
+Version: 0.5.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
@@ -96,31 +96,31 @@ From Python: `import ldpy; ldpy.install()` then `import yourmodule` finds
 
 ## Documentation
 
-Read it at [`docs/`](docs/README.md) — start with the
-[home page](docs/README.md) for an overview, then:
+Read it at **<https://linked-data-python.readthedocs.io/>** — start with the
+home page for an overview, then:
 
-- **Tutorials** — [first steps](docs/tutorials/getting-started.md), then
-  [build a knowledge graph](docs/tutorials/build-a-knowledge-graph.md) from
+- **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](docs/how-to/run-and-import.md),
-  [build graphs from tables](docs/how-to/build-graphs-from-tables.md),
-  [read and query](docs/how-to/query-a-graph.md),
-  [migrate from rdflib](docs/how-to/migrate-from-rdflib.md),
-  [VS Code](docs/how-to/use-vscode.md), [debugging](docs/how-to/debug.md),
-  [language server](docs/how-to/language-server.md),
-  [highlighting](docs/how-to/highlight-ldpy.md).
-- **Reference** — [the language](docs/reference/language/index.md), one page
-  per island family; [SPARQL expressions](docs/reference/sparql-expressions.md);
-  [CLI](docs/reference/cli.md); [Python API](docs/reference/api.md);
-  [language map formats](docs/reference/language-map.md).
-- **Explanation** — [why](docs/explanation/why.md),
-  [what real RDF code does](docs/explanation/what-real-code-does.md) (the
+- **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](docs/explanation/designing-the-syntax.md),
-  [island parsing](docs/explanation/island-parsing.md),
-  [emission & semantics](docs/explanation/emission-and-semantics.md),
-  [tooling](docs/explanation/tooling.md),
-  [how this is tested](docs/explanation/how-it-is-tested.md).
+  [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.

{linked_data_python-0.2.0 → linked_data_python-0.5.1}/README.md

@@ -54,31 +54,31 @@ From Python: `import ldpy; ldpy.install()` then `import yourmodule` finds
 
 ## Documentation
 
-Read it at [`docs/`](docs/README.md) — start with the
-[home page](docs/README.md) for an overview, then:
+Read it at **<https://linked-data-python.readthedocs.io/>** — start with the
+home page for an overview, then:
 
-- **Tutorials** — [first steps](docs/tutorials/getting-started.md), then
-  [build a knowledge graph](docs/tutorials/build-a-knowledge-graph.md) from
+- **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](docs/how-to/run-and-import.md),
-  [build graphs from tables](docs/how-to/build-graphs-from-tables.md),
-  [read and query](docs/how-to/query-a-graph.md),
-  [migrate from rdflib](docs/how-to/migrate-from-rdflib.md),
-  [VS Code](docs/how-to/use-vscode.md), [debugging](docs/how-to/debug.md),
-  [language server](docs/how-to/language-server.md),
-  [highlighting](docs/how-to/highlight-ldpy.md).
-- **Reference** — [the language](docs/reference/language/index.md), one page
-  per island family; [SPARQL expressions](docs/reference/sparql-expressions.md);
-  [CLI](docs/reference/cli.md); [Python API](docs/reference/api.md);
-  [language map formats](docs/reference/language-map.md).
-- **Explanation** — [why](docs/explanation/why.md),
-  [what real RDF code does](docs/explanation/what-real-code-does.md) (the
+- **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](docs/explanation/designing-the-syntax.md),
-  [island parsing](docs/explanation/island-parsing.md),
-  [emission & semantics](docs/explanation/emission-and-semantics.md),
-  [tooling](docs/explanation/tooling.md),
-  [how this is tested](docs/explanation/how-it-is-tested.md).
+  [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.

{linked_data_python-0.2.0 → linked_data_python-0.5.1}/ldpy/__init__.py

@@ -11,7 +11,19 @@ package but is no longer imported by default.
 from ldpy.transpiler import transpile, LdpySyntaxError, LdpyWarning
 from ldpy.importer import install, uninstall, install_excepthook
 
-__version__ = "0.1.0.dev0"
+#: 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"
 
 

{linked_data_python-0.2.0 → linked_data_python-0.5.1}/ldpy/debug.py

@@ -211,9 +211,13 @@ def main(argv=None):
 
     if args.breakpoints:
         lines = [int(x) for x in args.breakpoints.split(",") if x.strip()]
+        # ABSOLUTE paths: this output crosses a process boundary, and a
+        # relative path means nothing to a reader that does not share our
+        # working directory. An editor turning ".ldpy-build/x.py" into a URI
+        # gets "/.ldpy-build/x.py", rooted at the filesystem root.
         print(json.dumps({
-            "shadow": py_path,
-            "map": map_path,
+            "shadow": os.path.abspath(py_path),
+            "map": os.path.abspath(map_path),
             "breakpoints": dict(zip(
                 lines, translate_breakpoints(result.map, lines)))}))
         return 0

{linked_data_python-0.2.0 → linked_data_python-0.5.1}/ldpy/lsp/backend.py

@@ -12,6 +12,18 @@ import threading
 
 from ldpy.lsp.rpc import Endpoint, read_message, RpcClosed
 
+#: The backend judges GENERATED code. Style findings (line length, blank
+#: lines, continuation indents, semicolons…) describe the transpiler's
+#: output, not the user's source; re-projected onto the .ldpy they underline
+#: whole islands (record vscode/107). The shadow therefore opts out of every
+#: style plugin; semantic analyses (pyflakes' undefined names, unused
+#: imports) stay on.
+STYLE_PLUGINS = ("autopep8", "flake8", "mccabe", "pycodestyle",
+                 "pydocstyle", "pylint", "yapf")
+
+SHADOW_SETTINGS = {"pylsp": {"plugins": {
+    name: {"enabled": False} for name in STYLE_PLUGINS}}}
+
 
 class PythonBackend:
     """Lifecycle and delegation to `python -m pylsp` (or another argv)."""
@@ -45,6 +57,8 @@ class PythonBackend:
             }},
         }, timeout=30.0)
         self.endpoint.notify("initialized", {})
+        self.endpoint.notify("workspace/didChangeConfiguration",
+                             {"settings": SHADOW_SETTINGS})
         return self
 
     def _pump(self):

linked_data_python-0.5.1/ldpy/lsp/hover.py

@@ -0,0 +1,62 @@
+"""Rendering the hover panel — record vscode/108.
+
+Three blocks separated by rules, in the shape Python tooling has taught
+people to read: a signature line, the description with a link to the
+documentation, and the Python the transpiler produced. The translation can
+be turned off (`ldpy.hover.showTranslation`); the first two blocks are what
+tells you *what you are looking at*, so they always show.
+
+Kept apart from `server.py`: rendering is a function of strings, and it is
+tested as one.
+"""
+
+from ldpy.lsp import islanddoc
+
+RULE = "\n\n---\n\n"
+
+
+def format_python(code, line_length=88):
+    """`code` through black, or unchanged when black cannot take it.
+
+    What a hover shows is a FRAGMENT: the expression one term became, or the
+    head of a statement the source splits in two (`for @bindings in`). Those
+    are not modules, and black rightly refuses them. Showing the generated
+    text as it stands beats showing nothing, so a refusal is silent.
+
+    black normalises what it accepts — quotes above all — so the block is the
+    translation *formatted*, not a byte-for-byte extract of the generated
+    file. `ldpy -t` remains the place to read that.
+    """
+    code = code.strip()
+    if not code:
+        return code
+    try:
+        import black
+    except ImportError:                                   # pragma: no cover
+        return code
+    try:
+        return black.format_str(
+            code, mode=black.Mode(line_length=line_length)).rstrip("\n")
+    except Exception:
+        return code
+
+
+def render(kind, code, line_length=88, show_translation=True):
+    """The markdown of a hover over an island element.
+
+    `kind` is an island kind (with or without the `island:` prefix), `code`
+    the Python it became. An unknown kind still renders: the table can lag
+    the transpiler by a commit, and a hover must degrade rather than vanish.
+    """
+    doc = islanddoc.get(kind)
+    blocks = []
+    if doc is None:
+        short = kind[len("island:"):] if kind.startswith("island:") else kind
+        blocks.append("```ldpy\n(%s island)\n```" % short)
+    else:
+        blocks.append("```ldpy\n%s\n```" % doc.signature)
+        blocks.append("%s [Documentation](%s)" % (doc.summary, doc.url))
+    if show_translation and code and code.strip():
+        blocks.append("```python\n%s\n```"
+                      % format_python(code, line_length))
+    return RULE.join(blocks)

linked_data_python-0.5.1/ldpy/lsp/islanddoc.py

@@ -0,0 +1,215 @@
+"""What each island IS, in the three lines a hover shows — record vscode/108.
+
+Per island kind: a signature line in the shape Python tooling uses, a short
+prose description, and the documentation page (with anchor) that explains it.
+Nothing here knows about LSP; `server.py` renders it, `pygments_lexer.py` and
+the semantic tokens name the same kinds.
+
+The table is CLOSED: `tests/test_islanddoc.py` fails when the transpiler grows
+a kind with no entry here, and when an anchor no longer exists under `docs/`.
+That second test is what keeps the links from rotting silently — a dead link
+in a hover is worse than no link, because nothing ever reports it.
+"""
+
+DOCS = "https://linked-data-python.readthedocs.io/en/latest/"
+
+
+class IslandDoc:
+    """Signature, description and documentation target of one island kind."""
+
+    __slots__ = ("signature", "summary", "page", "anchor")
+
+    def __init__(self, signature, summary, page, anchor):
+        self.signature = signature
+        self.summary = summary
+        self.page = page            # path under docs/, with the .md suffix
+        self.anchor = anchor
+
+    @property
+    def url(self):
+        """The published URL — mkdocs serves `x/y.md` as `x/y/`."""
+        return "%s%s/#%s" % (DOCS, self.page[:-len(".md")], self.anchor)
+
+
+_TERMS = "reference/language/terms.md"
+_DECLS = "reference/language/declarations.md"
+_GRAPHS = "reference/language/graphs.md"
+_CURRENT = "reference/language/current-graph.md"
+_QUERY = "reference/language/querying.md"
+_BINDINGS = "reference/language/bindings.md"
+_SPARQL_EXPR = "reference/sparql-expressions.md"
+
+
+ISLANDS = {
+
+    # -- declarations -------------------------------------------------------
+
+    "prefix": IslandDoc(
+        "(declaration) @prefix ex: <IRI> .",
+        "Binds `ex:` to a namespace IRI for the rest of the enclosing block. "
+        "A prefix is lexical: it has no run-time object, and `ex:` on its own "
+        "is never a value. Declaring it again in a deeper block shadows it, "
+        "the way a Python name would.",
+        _DECLS, "prefix-bind-a-prefix"),
+
+    "base": IslandDoc(
+        "(declaration) @base <IRI> .",
+        "Sets the base against which relative IRIs are resolved for the rest "
+        "of the block, so that `<sensor/1>` means `<IRI>sensor/1`.",
+        _DECLS, "base-set-the-base-iri"),
+
+    "import": IslandDoc(
+        "(declaration) from MODULE import ex:, unit: as u:",
+        "Imports prefixes declared by another module, optionally renaming "
+        "them. The module is imported as usual; what travels is the prefix "
+        "bindings, which have no value to import by ordinary means.",
+        _DECLS, "prefixes-across-modules"),
+
+    "graph-decl": IslandDoc(
+        "(declaration) @graph EXPR | @graph as NAME -> Graph",
+        "Designates the current graph for the block — the one `+{ }`, `-{ }` "
+        "and a receiver-less `m{ }` act on. `as NAME` creates a fresh graph "
+        "and binds it to NAME; `global` and `nonlocal` widen the scope.",
+        _CURRENT, "graph-designate-or-create"),
+
+    "bindings-decl": IslandDoc(
+        "(declaration) @bindings EXPR | @bindings as NAME -> Bindings",
+        "Designates the current bindings: the mapping that gives `?name` its "
+        "value in the enclosing block. Any mapping will do, and `as NAME` "
+        "creates an empty one.",
+        _BINDINGS, "bindings-the-current-bindings"),
+
+    "for-bindings": IslandDoc(
+        "(statement) for @bindings [as NAME] in ITER:",
+        "Loops over an iterable of mappings, making each row the current "
+        "bindings for the body. A `csv.DictReader` and the solutions of "
+        "`m{ }` are both iterables of mappings, so both drive this loop.",
+        _BINDINGS, "for-bindings-in-iter-the-loop-that-carries-them"),
+
+    "for-bindings-close": IslandDoc(
+        "(statement) the ':' closing a for @bindings header",
+        "The end of a `for @bindings` header. It is mapped on its own "
+        "because the header is rewritten in two pieces, around the iterable "
+        "that stays verbatim Python.",
+        _BINDINGS, "for-bindings-in-iter-the-loop-that-carries-them"),
+
+    # -- graphs and the current graph ---------------------------------------
+
+    "graph": IslandDoc(
+        "(expression) g{ ... } -> Graph",
+        "Builds an RDF graph from Turtle written in place. `{expr}` "
+        "interpolates a Python value in term position, and each occurrence "
+        "is evaluated once. The braces are an expression, so a `g{ }` goes "
+        "anywhere a value goes — a default argument, a comprehension, a "
+        "return.",
+        _GRAPHS, "turtle-inside-the-braces"),
+
+    "addto": IslandDoc(
+        "(statement) +{ ... } [ (GRAPH) ]",
+        "Adds the triples to the current graph. `?name` takes its value from "
+        "the current bindings, and a triple with an unbound variable is "
+        "dropped rather than written half-way. A trailing `(g)` names "
+        "another receiver.",
+        _CURRENT, "and-write-to-it"),
+
+    "removefrom": IslandDoc(
+        "(statement) -{ ... } [ (GRAPH) ]",
+        "Removes from the current graph every triple matching the pattern. "
+        "An unbound variable is a wildcard here, not a hole: this is a "
+        "SPARQL `DELETE WHERE`, not a list of triples to subtract.",
+        _CURRENT, "and-write-to-it"),
+
+    # -- reading ------------------------------------------------------------
+
+    "match": IslandDoc(
+        "(expression) m{ ... } -> Solutions",
+        "Matches a basic graph pattern against the current graph, lazily. "
+        "Iterating yields a bare term when one variable is projected and a "
+        "tuple otherwise; `.one()`, `.first()`, `.count()` and `bool()` are "
+        "the usual reductions. A `(graph)` suffix names another source.",
+        _QUERY, "m-match-a-basic-graph-pattern"),
+
+    "sparql": IslandDoc(
+        "(expression) s{ ... } -> Query",
+        "A SPARQL query or update, parsed when the file is transpiled rather "
+        "than at run time. `{expr}` in term position becomes an initial "
+        "binding — never string pasting, so nothing here can be injected. "
+        "Call it on a graph to run it; `.execute()` runs an update.",
+        _QUERY, "s-a-sparql-query"),
+
+    # -- terms --------------------------------------------------------------
+
+    "iri": IslandDoc(
+        "(term) <IRI> -> URIRef",
+        "An absolute IRI, or a relative one resolved against the `@base` in "
+        "scope.",
+        _TERMS, "iris"),
+
+    "pname": IslandDoc(
+        "(term) ex:local -> URIRef",
+        "A prefixed name: the local part is appended to the IRI bound to "
+        "`ex:`. Turtle's character set applies inside an island, so "
+        "`o-pizza:topping` and `ex:café` are names here although neither is "
+        "a legal Python expression. `ex:{expr}` computes the local part.",
+        _TERMS, "prefixed-names-exlocal"),
+
+    "literal": IslandDoc(
+        "(term) \"...\"@lang | \"...\"^^dt -> Literal",
+        "An RDF literal carrying a language tag or a datatype. The quoted "
+        "part may be an f-string, and `{expr}` may supply the datatype "
+        "itself.",
+        _TERMS, "rdf-literals-lang-dt"),
+
+    "var": IslandDoc(
+        "(term) ?name | $name -> Variable",
+        "A SPARQL variable. In a pattern it is what gets matched and "
+        "projected; in `g{ }` or `+{ }` it takes its value from the current "
+        "bindings, and leaves the triple out when it has none.",
+        _TERMS, "variables-name-name"),
+
+    "firi": IslandDoc(
+        "(term) f<...{expr}...> -> URIRef",
+        "A formatted IRI: the braces interpolate as in an f-string, the "
+        "result is percent-encoded and then resolved against `@base`. "
+        "Encoding first is what keeps a space or a slash in a value from "
+        "changing the IRI's structure.",
+        _TERMS, "formatted-iris-f"),
+
+    "fnode": IslandDoc(
+        "(term) f{expr} | ?{expr} -> Node",
+        "Coerces any Python value into an RDF term, by the coercion policy "
+        "in scope. Two spellings of one operation: `?{ }` reads better in "
+        "term position, `f{ }` beside `f<...>`.",
+        _TERMS, "formatted-nodes-fexpr-expr"),
+
+    "bnode": IslandDoc(
+        "(term) _:{expr} -> BNode",
+        "A blank node whose identity is its data: the same value gives the "
+        "same node anywhere in the program, so two rows that share a key "
+        "join without inventing an IRI for them.",
+        _GRAPHS, "data-keyed-blank-nodes-_expr"),
+
+    # -- deferred evaluation ------------------------------------------------
+
+    "enode": IslandDoc(
+        "(expression) e{ ... } -> Expr",
+        "A deferred SPARQL expression. It is not evaluated where it is "
+        "written, but against the bindings in force when the island holding "
+        "it is instantiated — once per row of a `for @bindings` loop. "
+        "`{python}` holes are evaluated where they are written.",
+        _BINDINGS, "e-in-term-position"),
+
+    "eiri": IslandDoc(
+        "(expression) e<...{?var}...> -> Expr",
+        "A deferred IRI: `f<...>`'s interpolation, except that the holes are "
+        "SPARQL expressions re-evaluated for each set of bindings.",
+        _SPARQL_EXPR, "deferred-iris-e"),
+}
+
+
+def get(kind):
+    """The entry for an island kind, `island:` prefix optional; None if the
+    kind is unknown — a hover must degrade, never raise."""
+    if kind.startswith("island:"):
+        kind = kind[len("island:"):]
+    return ISLANDS.get(kind)

{linked_data_python-0.2.0 → linked_data_python-0.5.1}/ldpy/lsp/server.py

@@ -21,6 +21,7 @@ import sys
 from ldpy.transpiler import transpile, LdpySyntaxError
 from ldpy.lsp.rpc import Endpoint, read_message, RpcClosed
 from ldpy.lsp import translate as tr
+from ldpy.lsp import hover as hv
 from ldpy.transpiler.linemap import snap_breakpoint_lines
 
 
@@ -29,6 +30,28 @@ def fmt_default():
     from ldpy.formatter import DEFAULT_LINE_LENGTH
     return DEFAULT_LINE_LENGTH
 
+
+def _ldpy_version():
+    """The installed package version — never duplicated here."""
+    from ldpy import __version__
+    return __version__
+
+def _setting(settings, *path, default=None):
+    """Read a nested setting, whether the client sends the whole tree
+    (`{"ldpy": {"hover": ...}}`) or just our section (`{"hover": ...}`).
+    Clients differ on this and both spellings are legitimate."""
+    for root in (settings, (settings or {}).get("ldpy")):
+        node = root
+        for key in path:
+            if not isinstance(node, dict) or key not in node:
+                node = None
+                break
+            node = node[key]
+        if node is not None:
+            return node
+    return default
+
+
 FORWARDED = {
     "textDocument/completion",
     "textDocument/definition",
@@ -64,6 +87,9 @@ class LdpyServer:
         self.backend_argv = backend_argv
         self.backend = None
         self.line_length = line_length
+        # `ldpy.hover.showTranslation` — the generated Python in the hover.
+        # On by default: it is the point of the feature (record vscode/108).
+        self.hover_translation = True
         self._shutdown = False
 
     # ------------------------------------------------------------ backend
@@ -123,13 +149,20 @@ class LdpyServer:
 
     def _on_backend_diags(self, shadow, diags):
         """The backend's Python diagnostics, re-projected onto the .ldpy.
-        Those landing on synthetic text (the prelude) are dropped."""
+        Those landing on synthetic text (the prelude) are dropped, and so is
+        everything a style linter says about the shadow: it judges GENERATED
+        code (record vscode/107). The backend is asked not to compute style
+        at all (SHADOW_SETTINGS); this filter covers a backend that does not
+        honour the configuration."""
+        from ldpy.lsp.backend import STYLE_PLUGINS
         doc = self.docs.get(tr.unshadow_uri(shadow))
         if doc is None or doc.result is None:
             return
         lmap = doc.result.map
         kept = []
         for d in diags:
+            if d.get("source") in STYLE_PLUGINS:
+                continue
             rng = d.get("range", {})
             start = tr.pos_to_ldpy(lmap, rng.get("start", {}))
             if start is None:
@@ -173,6 +206,7 @@ class LdpyServer:
 
     def _dispatch(self, method, params, rid):
         if method == "initialize":
+            self._apply_settings(params.get("initializationOptions"))
             self._ensure_backend(params.get("rootUri"))
             return {
                 "capabilities": {
@@ -185,18 +219,18 @@ class LdpyServer:
                     "referencesProvider": True,
                     "signatureHelpProvider": {
                         "triggerCharacters": ["(", ","]},
-                    "semanticTokensProvider": {
-                        "legend": {"tokenTypes": tr.TOKEN_TYPES,
-                                   "tokenModifiers": []},
-                        "full": True},
                     # our own extension, announced so the client can detect
                     # it instead of assuming it (record vscode/103)
                     "experimental": {"ldpyBreakpointLines": True},
                 },
-                "serverInfo": {"name": "ldpy-lsp", "version": "0.2.0"},
+                "serverInfo": {"name": "ldpy-lsp", "version": _ldpy_version()},
             }
-        if method in ("initialized", "workspace/didChangeConfiguration",
-                      "$/setTrace", "$/cancelRequest"):
+        if method == "workspace/didChangeConfiguration":
+            # a live toggle: no restart, and no re-transpilation either —
+            # only the rendering of the next hover changes
+            self._apply_settings(params.get("settings"))
+            return None
+        if method in ("initialized", "$/setTrace", "$/cancelRequest"):
             return None
         if method == "shutdown":
             self._shutdown = True
@@ -240,12 +274,6 @@ class LdpyServer:
                 return {"lines": lines}
             return {"lines": snap_breakpoint_lines(doc.result.map, lines)}
 
-        if method == "textDocument/semanticTokens/full":
-            doc = self.docs.get(params["textDocument"]["uri"])
-            if doc is None or doc.result is None:
-                return {"data": []}
-            return {"data": tr.semantic_tokens(doc.result.map)}
-
         if method == "textDocument/hover":
             return self._hover(params)
 
@@ -292,28 +320,49 @@ class LdpyServer:
         return [{"range": {"start": {"line": 0, "character": 0}, "end": end},
                  "newText": new}]
 
+    def _apply_settings(self, settings):
+        """Client configuration, from `initialize` or a later change."""
+        value = _setting(settings, "hover", "showTranslation")
+        if isinstance(value, bool):
+            self.hover_translation = value
+
+    def _gen_text(self, doc, gen):
+        """The generated Python covered by a map range."""
+        gl0, gc0, gl1, gc1 = gen
+        lines = doc.result.code.split("\n")[gl0:gl1 + 1]
+        if not lines:
+            return ""
+        if len(lines) == 1:
+            return lines[0][gc0:gc1]
+        lines[0] = lines[0][gc0:]
+        lines[-1] = lines[-1][:gc1]
+        return "\n".join(lines)
+
     def _hover(self, params):
+        """Native on an island, delegated on the Python around it.
+
+        Inside an island we answer on the SMALLEST described element under
+        the cursor (record vscode/108): hovering a prefixed name in a
+        forty-line `g{ }` should explain that name, not dump the whole
+        translated block."""
         doc = self.docs.get(params["textDocument"]["uri"])
         if doc is None or doc.result is None:
             return None
         pos = params["position"]
         seg = tr.island_at(doc.result.map, pos["line"], pos["character"])
-        if seg is not None:
-            gl0, gc0, gl1, gc1 = seg.gen
-            lines = doc.result.code.split("\n")[gl0:gl1 + 1]
-            if len(lines) == 1:
-                excerpt = lines[0][gc0:gc1]
-            else:
-                lines[0] = lines[0][gc0:]
-                lines[-1] = lines[-1][:gc1]
-                excerpt = "\n".join(lines)
-            sl0, sc0, sl1, sc1 = seg.src
-            return {"contents": {"kind": "markdown", "value":
-                    "**%s island**\n```python\n%s\n```" % (
-                        seg.kind.split(":", 1)[1], excerpt)},
-                    "range": {"start": {"line": sl0, "character": sc0},
-                              "end": {"line": sl1, "character": sc1}}}
-        return self._forward("textDocument/hover", params)
+        if seg is None:
+            return self._forward("textDocument/hover", params)
+        kind, src, code = tr.island_target(seg, pos["line"],
+                                           pos["character"])
+        if code is None:
+            code = self._gen_text(doc, seg.gen)
+        width = self.line_length or fmt_default()
+        sl0, sc0, sl1, sc1 = src
+        return {"contents": {"kind": "markdown",
+                             "value": hv.render(kind, code, width,
+                                                self.hover_translation)},
+                "range": {"start": {"line": sl0, "character": sc0},
+                          "end": {"line": sl1, "character": sc1}}}
 
     # --------------------------------------------------------- delegation