lsdocs-plugin 0.1.0__cp311-abi3-win_arm64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,140 @@
1
+ """Write lsdocs plugins in Python.
2
+
3
+ A plugin is a :class:`Plugin` with handlers registered by decorator. Each
4
+ handler receives the request params (a dict shaped like the protocol schema)
5
+ and a :class:`Context`, and returns the result::
6
+
7
+ from lsdocs_plugin import Plugin
8
+
9
+ plugin = Plugin("shout", "0.1.0")
10
+
11
+ @plugin.transform(nodes=["text"])
12
+ def shout(params, ctx):
13
+ doc = params["document"]
14
+ for node in doc["children"]:
15
+ if node["type"] == "text":
16
+ node["value"] = node["value"].upper()
17
+ return doc # the bare document is shorthand for {"document": doc}
18
+
19
+ if __name__ == "__main__":
20
+ plugin.serve()
21
+
22
+ Shorthand results: ``parse`` and ``transform`` handlers may return just the
23
+ document; ``read`` may return any value (taken as ``data``); ``render`` may
24
+ return a ``str`` or ``bytes`` (taken as ``output``, with ``extension`` set to
25
+ the format); ``render_all`` may return a list of files.
26
+
27
+ Handlers may be ``async def``: coroutines run on one event loop shared by
28
+ all calls, so loop-bound objects (client sessions, locks) can be reused::
29
+
30
+ @plugin.transform(nodes=["link"])
31
+ async def check_links(params, ctx):
32
+ async with session.head(url) as response: ...
33
+
34
+ Handlers run one at a time unless ``max_concurrency`` is raised, which lets
35
+ async handlers overlap. The protocol itself (framing, handshake,
36
+ cancellation, shutdown) is handled in Rust.
37
+ """
38
+
39
+ from __future__ import annotations
40
+
41
+ import sys
42
+ from collections.abc import Callable, Iterable
43
+ from typing import Any, TypeVar
44
+
45
+ from . import _aio, _native
46
+ from ._native import PROTOCOL_VERSION, Context
47
+
48
+ __all__ = ["PROTOCOL_VERSION", "Context", "Handler", "Plugin"]
49
+
50
+ Handler = Callable[[dict[str, Any], Context], Any]
51
+ """A handler: ``(params, ctx) -> result``, or an ``async def`` returning it."""
52
+
53
+ F = TypeVar("F", bound=Handler)
54
+
55
+
56
+ class Plugin:
57
+ """An lsdocs plugin: a name, a version and its handlers."""
58
+
59
+ def __init__(
60
+ self,
61
+ name: str,
62
+ version: str = "0.0.0",
63
+ *,
64
+ max_concurrency: int = 1,
65
+ config_files: Iterable[str] = (),
66
+ ) -> None:
67
+ self.name = name
68
+ self.version = version
69
+ self._native = _native.NativePlugin(name, version, max_concurrency, list(config_files))
70
+
71
+ def parse(self, *, extensions: Iterable[str]) -> Callable[[F], F]:
72
+ """Registers the parser for files with these extensions (no dot)."""
73
+ exts = list(extensions)
74
+
75
+ def register(func: F) -> F:
76
+ self._native.set_parse(exts, _aio.adapt(func))
77
+ return func
78
+
79
+ return register
80
+
81
+ def read(self, func: F | None = None) -> Any:
82
+ """Registers the ``parse/transform/each`` handler, run on every
83
+ document (reading it, not changing it) before :meth:`transform`.
84
+ Usable as ``@plugin.read`` or ``@plugin.read()``."""
85
+
86
+ def register(f: F) -> F:
87
+ self._native.set_read(_aio.adapt(f))
88
+ return f
89
+
90
+ return register(func) if func is not None else register
91
+
92
+ def transform(self, *, nodes: Iterable[str] = ()) -> Callable[[F], F]:
93
+ """Registers the transformer (``render/transform/each``). ``nodes`` are the node kinds it looks
94
+ at (e.g. ``["heading", "custom:toc"]``); documents without any of them
95
+ are not sent. Empty means every document."""
96
+ kinds = list(nodes)
97
+
98
+ def register(func: F) -> F:
99
+ self._native.set_apply(kinds, _aio.adapt(func))
100
+ return func
101
+
102
+ return register
103
+
104
+ def render(self, *, formats: Iterable[str]) -> Callable[[F], F]:
105
+ """Registers the renderer for these output formats."""
106
+ fmts = list(formats)
107
+
108
+ def register(func: F) -> F:
109
+ self._native.set_render(fmts, _aio.adapt(func))
110
+ return func
111
+
112
+ return register
113
+
114
+ def render_all(self, func: F) -> F:
115
+ """Registers the ``render/transform/all`` handler, called once after
116
+ every page is rendered with the list of rendered pages
117
+ (``{"format", "pages": [{"source", "path", "metadata", "data"}]}``,
118
+ ``data`` being what the page's render returned as ``data``, if
119
+ anything). It
120
+ returns files no single page makes: ``{"files": [{"path", "output"}]}`` or just
121
+ the list, each ``output`` a ``str`` or ``bytes``. Only used with a
122
+ renderer (:meth:`render`)."""
123
+ self._native.set_render_all(_aio.adapt(func))
124
+ return func
125
+
126
+ @property
127
+ def capabilities(self) -> dict[str, Any]:
128
+ """The capabilities reported to the host."""
129
+ return self._native.capabilities()
130
+
131
+ def serve(self) -> None:
132
+ """Runs the plugin until the host is done with it.
133
+
134
+ Talks to the host over stdin/stdout, or over the pipe in
135
+ ``LSDOCS_PIPE``. ``print()`` output goes to stderr from here on, so
136
+ it cannot corrupt the protocol stream.
137
+ """
138
+ sys.stdout.flush()
139
+ sys.stdout = sys.stderr
140
+ _native.serve(self._native)
lsdocs_plugin/_aio.py ADDED
@@ -0,0 +1,67 @@
1
+ """Runs ``async def`` handlers on one persistent event loop.
2
+
3
+ Handlers are called from Rust on worker threads. A coroutine handler is
4
+ submitted to a single asyncio loop running on a daemon thread, and the
5
+ worker waits for its result (releasing the GIL while it waits). Sharing one
6
+ loop for the life of the plugin means loop-bound objects created in one call,
7
+ such as client sessions or locks, keep working in the next. With
8
+ ``max_concurrency`` above 1, several async handlers can be in flight at once.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import asyncio
14
+ import functools
15
+ import inspect
16
+ import threading
17
+ from collections.abc import Awaitable, Callable
18
+ from typing import Any, TypeVar
19
+
20
+ T = TypeVar("T")
21
+
22
+ _lock = threading.Lock()
23
+ _loop: asyncio.AbstractEventLoop | None = None
24
+
25
+
26
+ def loop() -> asyncio.AbstractEventLoop:
27
+ """The shared event loop, started on first use."""
28
+ global _loop
29
+ with _lock:
30
+ if _loop is None:
31
+ new_loop = asyncio.new_event_loop()
32
+ started = threading.Event()
33
+
34
+ def run() -> None:
35
+ asyncio.set_event_loop(new_loop)
36
+ new_loop.call_soon(started.set)
37
+ new_loop.run_forever()
38
+
39
+ threading.Thread(target=run, name="lsdocs-asyncio", daemon=True).start()
40
+ started.wait()
41
+ _loop = new_loop
42
+ return _loop
43
+
44
+
45
+ async def _await(awaitable: Awaitable[T]) -> T:
46
+ return await awaitable
47
+
48
+
49
+ def run(awaitable: Awaitable[T]) -> T:
50
+ """Runs ``awaitable`` on the shared loop and waits for its result."""
51
+ if threading.current_thread().name == "lsdocs-asyncio":
52
+ raise RuntimeError("cannot wait for a handler from inside the event loop")
53
+ return asyncio.run_coroutine_threadsafe(_await(awaitable), loop()).result()
54
+
55
+
56
+ def adapt(func: Callable[..., Any]) -> Callable[..., Any]:
57
+ """Wraps a handler so that coroutine results are awaited on the shared
58
+ loop; plain results pass through."""
59
+
60
+ @functools.wraps(func)
61
+ def call(*args: Any) -> Any:
62
+ result = func(*args)
63
+ if inspect.isawaitable(result):
64
+ return run(result)
65
+ return result
66
+
67
+ return call
Binary file
@@ -0,0 +1,61 @@
1
+ """Type stubs for the Rust extension. Use the ``lsdocs_plugin`` API instead."""
2
+
3
+ from collections.abc import Callable
4
+ from typing import Any
5
+
6
+ PROTOCOL_VERSION: str
7
+
8
+ class Context:
9
+ """What a handler receives alongside its params."""
10
+
11
+ @property
12
+ def site(self) -> dict[str, Any]:
13
+ """The site being built: ``title``, ``base_url``, ``root``,
14
+ ``source_dir`` and ``files`` (every source file, relative to the
15
+ source directory)."""
16
+
17
+ @property
18
+ def settings(self) -> dict[str, str | None] | None:
19
+ """Each of the plugin's ``config_files`` (``{name}`` resolved)
20
+ mapped to its text, or None if missing; None if it names none."""
21
+
22
+ @property
23
+ def config(self) -> dict[str, str]:
24
+ """``dir`` (the site's ``.config/``) and ``name`` (the plugin's
25
+ name in the site config)."""
26
+
27
+ def log(self, level: str, message: str) -> None:
28
+ """Logs at ``"error"``, ``"warn"``, ``"info"``, ``"debug"`` or ``"trace"``."""
29
+
30
+ def debug(self, message: str) -> None: ...
31
+ def info(self, message: str) -> None: ...
32
+ def warn(self, message: str) -> None: ...
33
+ def progress(self, message: str, percentage: int | None = None) -> None: ...
34
+ def diagnostic(self, diagnostic: dict[str, Any]) -> None:
35
+ """Reports a diagnostic: ``severity``, ``message``, and optionally
36
+ ``source``, ``span`` and ``code``."""
37
+
38
+ class NativePlugin:
39
+ def __init__(
40
+ self,
41
+ name: str,
42
+ version: str,
43
+ max_concurrency: int | None = 1,
44
+ config_files: list[str] = ...,
45
+ ) -> None: ...
46
+ def set_parse(self, extensions: list[str], func: Callable[..., Any]) -> None: ...
47
+ def set_read(self, func: Callable[..., Any]) -> None: ...
48
+ def set_apply(self, nodes: list[str], func: Callable[..., Any]) -> None: ...
49
+ def set_render(self, formats: list[str], func: Callable[..., Any]) -> None: ...
50
+ def set_render_all(self, func: Callable[..., Any]) -> None: ...
51
+ def capabilities(self) -> dict[str, Any]: ...
52
+
53
+ def serve(plugin: NativePlugin) -> None: ...
54
+ def call(
55
+ plugin: NativePlugin,
56
+ method: str,
57
+ params: dict[str, Any] | None = None,
58
+ site: dict[str, Any] | None = None,
59
+ settings: Any = None,
60
+ config: dict[str, str] | None = None,
61
+ ) -> tuple[dict[str, Any], list[dict[str, Any]]]: ...
lsdocs_plugin/py.typed ADDED
File without changes
@@ -0,0 +1,65 @@
1
+ """Run a plugin's handlers in-process, as the host would, for tests.
2
+
3
+ Each function returns ``(result, events)``: the handler's result normalized
4
+ to the full protocol shape, and the events it sent (log lines, progress,
5
+ diagnostics) as dicts with a ``kind`` key::
6
+
7
+ from lsdocs_plugin import testing
8
+
9
+ result, events = testing.parse(plugin, "a.txt", "hello")
10
+ assert result["document"]["children"][0]["value"] == "hello"
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ from typing import Any
16
+
17
+ from . import Plugin, _native
18
+
19
+ Result = tuple[dict[str, Any], list[dict[str, Any]]]
20
+
21
+
22
+ def call(
23
+ plugin: Plugin,
24
+ method: str,
25
+ params: dict[str, Any] | None = None,
26
+ *,
27
+ site: dict[str, Any] | None = None,
28
+ settings: Any = None,
29
+ config: dict[str, str] | None = None,
30
+ ) -> Result:
31
+ """Calls ``method`` (``"parse"``, ``"parse/transform/each"``,
32
+ ``"render/transform/each"``, ``"render"``, ``"render/transform/all"`` or
33
+ ``"initialize"``) with ``params``. ``settings`` are given to the
34
+ handler as ``ctx.settings``; without them, the plugin's
35
+ ``config_files`` are read from ``config["dir"]`` (``config`` is
36
+ ``ctx.config``: ``dir`` and ``name``)."""
37
+ return _native.call(plugin._native, method, params, site, settings, config)
38
+
39
+
40
+ def parse(plugin: Plugin, source: str, text: str, **kwargs: Any) -> Result:
41
+ """Parses ``text`` as the file ``source``."""
42
+ return call(plugin, "parse", {"source": source, "text": text}, **kwargs)
43
+
44
+
45
+ def read(plugin: Plugin, document: dict[str, Any], **kwargs: Any) -> Result:
46
+ """Runs ``parse/transform/each`` on ``document``."""
47
+ return call(plugin, "parse/transform/each", {"document": document}, **kwargs)
48
+
49
+
50
+ def apply(plugin: Plugin, document: dict[str, Any], collected: Any = None, **kwargs: Any) -> Result:
51
+ """Runs the transformer on ``document`` with ``collected`` data."""
52
+ return call(plugin, "render/transform/each", {"document": document, "collected": collected}, **kwargs)
53
+
54
+
55
+ def render(plugin: Plugin, document: dict[str, Any], format: str = "html", **kwargs: Any) -> Result:
56
+ """Renders ``document`` to ``format``. ``output`` is returned as bytes."""
57
+ return call(plugin, "render", {"document": document, "format": format}, **kwargs)
58
+
59
+
60
+ def render_all(
61
+ plugin: Plugin, pages: list[dict[str, Any]], format: str = "html", **kwargs: Any
62
+ ) -> Result:
63
+ """Runs ``render/transform/all`` for ``pages`` (dicts with ``source``, ``path``
64
+ and optional ``metadata`` and ``data``). Each file's ``output`` is returned as bytes."""
65
+ return call(plugin, "render/transform/all", {"format": format, "pages": pages}, **kwargs)
@@ -0,0 +1,57 @@
1
+ Metadata-Version: 2.4
2
+ Name: lsdocs-plugin
3
+ Version: 0.1.0
4
+ Classifier: Programming Language :: Python :: 3
5
+ Classifier: Programming Language :: Rust
6
+ Classifier: Topic :: Documentation
7
+ Classifier: Topic :: Text Processing :: Markup
8
+ Summary: Write lsdocs plugins in Python.
9
+ License-Expression: Apache-2.0 OR MIT
10
+ Requires-Python: >=3.11
11
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
12
+
13
+ # lsdocs-plugin
14
+
15
+ Write [lsdocs](../../../ROADMAP.md) plugins in Python.
16
+
17
+ ```python
18
+ from lsdocs_plugin import Plugin
19
+
20
+ plugin = Plugin("shout", "0.1.0")
21
+
22
+ @plugin.transform(nodes=["text"])
23
+ def shout(params, ctx):
24
+ doc = params["document"]
25
+ for node in doc["children"]:
26
+ if node["type"] == "text":
27
+ node["value"] = node["value"].upper()
28
+ return doc
29
+
30
+ if __name__ == "__main__":
31
+ plugin.serve()
32
+ ```
33
+
34
+ Use it from `lsdocs.toml`:
35
+
36
+ ```toml
37
+ [[plugins]]
38
+ name = "shout"
39
+ runtime = "python"
40
+ module = "shout"
41
+ ```
42
+
43
+ Handlers may be `async def`. Coroutines run on one event loop shared by all
44
+ calls, so loop-bound objects (client sessions, locks) can be reused across
45
+ documents. Raise `max_concurrency` (`Plugin("x", max_concurrency=8)`) to let
46
+ async handlers overlap.
47
+
48
+ `lsdocs_plugin.testing` runs handlers in-process for unit tests.
49
+ `examples/transform_toc.py` is a full plugin: a Python port of the
50
+ first-party table-of-contents transformer.
51
+
52
+ ## Development
53
+
54
+ ```sh
55
+ nur test python # from the repository root: builds the extension, runs pytest
56
+ ```
57
+
@@ -0,0 +1,10 @@
1
+ lsdocs_plugin/__init__.py,sha256=-a18Jv9o18X_Xfhp2LS_BnEYeyDBq1W3GO6ShpuclPQ,4995
2
+ lsdocs_plugin/_aio.py,sha256=CmKXr7kequrP2pjt4R31zcekE5C9O27JmZ3Pf0in-ys,2146
3
+ lsdocs_plugin/_native.pyd,sha256=EtR7hg1TIHQC2PwfBDwuAzd_ZoTKFziBpvDzu8TXGkM,2800128
4
+ lsdocs_plugin/_native.pyi,sha256=bna7pyatl2qHGrJGQIsIprbCnkCF43ZLb2G8K6Z1esk,2312
5
+ lsdocs_plugin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ lsdocs_plugin/testing.py,sha256=ImylMG4lprcsMj2HTA5MPCsPPSmNLnb8TeM7qrOyuGg,2623
7
+ lsdocs_plugin-0.1.0.dist-info/METADATA,sha256=fMXMtZuAIwxhqoGNpGkYB2jLETFavX5saZdgTLsBFRU,1464
8
+ lsdocs_plugin-0.1.0.dist-info/WHEEL,sha256=AB0n2KXAFWr2JzDd_LuXB_UDGUZDka69EZ-W9r4WIQU,96
9
+ lsdocs_plugin-0.1.0.dist-info/sboms/lsdocs-plugin-python.cyclonedx.json,sha256=G3wVcRvPsJA8sExSEeljDFg9z3IIhk6dtTJoactyTvI,67786
10
+ lsdocs_plugin-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: maturin (1.16.0)
3
+ Root-Is-Purelib: false
4
+ Tag: cp311-abi3-win_arm64