stilo-cli 0.1.0__tar.gz → 0.3.0__tar.gz

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.
Files changed (67) hide show
  1. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/.gitignore +2 -1
  2. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/PKG-INFO +13 -11
  3. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/README.md +10 -8
  4. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/pyproject.toml +10 -4
  5. stilo_cli-0.3.0/src/stilo/cli/commands.py +136 -0
  6. stilo_cli-0.3.0/src/stilo/cli/errors.py +155 -0
  7. stilo_cli-0.3.0/src/stilo/cli/project.py +83 -0
  8. stilo_cli-0.3.0/src/stilo/server/app.py +142 -0
  9. stilo_cli-0.3.0/src/stilo/server/home.py +72 -0
  10. stilo_cli-0.3.0/src/stilo/server/storage.py +293 -0
  11. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_AMS-Regular-BQhdFMY1.woff2 +0 -0
  12. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Caligraphic-Bold-Dq_IR9rO.woff2 +0 -0
  13. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Caligraphic-Regular-Di6jR-x-.woff2 +0 -0
  14. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Fraktur-Bold-CL6g_b3V.woff2 +0 -0
  15. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Fraktur-Regular-CTYiF6lA.woff2 +0 -0
  16. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Main-Bold-Cx986IdX.woff2 +0 -0
  17. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Main-BoldItalic-DxDJ3AOS.woff2 +0 -0
  18. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Main-Italic-NWA7e6Wa.woff2 +0 -0
  19. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Main-Regular-B22Nviop.woff2 +0 -0
  20. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Math-BoldItalic-CZnvNsCZ.woff2 +0 -0
  21. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Math-Italic-t53AETM-.woff2 +0 -0
  22. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_SansSerif-Bold-D1sUS0GD.woff2 +0 -0
  23. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_SansSerif-Italic-C3H0VqGB.woff2 +0 -0
  24. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_SansSerif-Regular-DDBCnlJ7.woff2 +0 -0
  25. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Script-Regular-D3wIWfF6.woff2 +0 -0
  26. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Size1-Regular-mCD8mA8B.woff2 +0 -0
  27. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Size2-Regular-Dy4dx90m.woff2 +0 -0
  28. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2 +0 -0
  29. stilo_cli-0.3.0/src/stilo/web/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2 +0 -0
  30. stilo_cli-0.3.0/src/stilo/web/assets/index-BT3YAPgN.js +2349 -0
  31. stilo_cli-0.3.0/src/stilo/web/assets/index-kR4PIGIs.css +1 -0
  32. stilo_cli-0.3.0/src/stilo/web/assets/literata-cyrillic-ext-opsz-italic-5yUt4G_9.woff2 +0 -0
  33. stilo_cli-0.3.0/src/stilo/web/assets/literata-cyrillic-ext-opsz-normal-C5tfwALZ.woff2 +0 -0
  34. stilo_cli-0.3.0/src/stilo/web/assets/literata-cyrillic-opsz-italic-Bj0ndbyp.woff2 +0 -0
  35. stilo_cli-0.3.0/src/stilo/web/assets/literata-cyrillic-opsz-normal-DgmypKXX.woff2 +0 -0
  36. stilo_cli-0.3.0/src/stilo/web/assets/literata-greek-ext-opsz-italic-DFpO5j-Z.woff2 +0 -0
  37. stilo_cli-0.3.0/src/stilo/web/assets/literata-greek-ext-opsz-normal-DGm64vGR.woff2 +0 -0
  38. stilo_cli-0.3.0/src/stilo/web/assets/literata-greek-opsz-italic-CHERNRFq.woff2 +0 -0
  39. stilo_cli-0.3.0/src/stilo/web/assets/literata-greek-opsz-normal-DFglUmAd.woff2 +0 -0
  40. stilo_cli-0.3.0/src/stilo/web/assets/literata-latin-ext-opsz-italic-4y8iAqqs.woff2 +0 -0
  41. stilo_cli-0.3.0/src/stilo/web/assets/literata-latin-ext-opsz-normal-STiTPs0F.woff2 +0 -0
  42. stilo_cli-0.3.0/src/stilo/web/assets/literata-latin-opsz-italic-CJ93D38p.woff2 +0 -0
  43. stilo_cli-0.3.0/src/stilo/web/assets/literata-latin-opsz-normal-BHZsWIlc.woff2 +0 -0
  44. stilo_cli-0.3.0/src/stilo/web/assets/literata-vietnamese-opsz-italic-BdcrZMcO.woff2 +0 -0
  45. stilo_cli-0.3.0/src/stilo/web/assets/literata-vietnamese-opsz-normal-Gqw5JQlq.woff2 +0 -0
  46. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-cyrillic-ext-wght-normal-c-5QAGAI.woff2 +0 -0
  47. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-cyrillic-wght-normal-BMDVbyM7.woff2 +0 -0
  48. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-greek-ext-wght-normal-BXZfsJY4.woff2 +0 -0
  49. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-greek-wght-normal-Cc-u-6OI.woff2 +0 -0
  50. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-latin-ext-wght-normal-C8iNium2.woff2 +0 -0
  51. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-latin-wght-normal-Bo_j9asI.woff2 +0 -0
  52. stilo_cli-0.3.0/src/stilo/web/assets/source-sans-3-vietnamese-wght-normal-BDs68eHQ.woff2 +0 -0
  53. stilo_cli-0.3.0/src/stilo/web/assets/texl_wasm_bg-DXo4-iTL.wasm +0 -0
  54. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/src/stilo/web/index.html +2 -2
  55. stilo_cli-0.3.0/texl-lib/dataframe.texl +113 -0
  56. stilo_cli-0.3.0/texl-lib/index.texl +16 -0
  57. stilo_cli-0.1.0/src/stilo/cli/commands.py +0 -80
  58. stilo_cli-0.1.0/src/stilo/server/app.py +0 -78
  59. stilo_cli-0.1.0/src/stilo/server/storage.py +0 -140
  60. stilo_cli-0.1.0/src/stilo/web/assets/index-4AKEJowe.css +0 -1
  61. stilo_cli-0.1.0/src/stilo/web/assets/index-CM5cmnCe.js +0 -889
  62. stilo_cli-0.1.0/src/stilo/web/assets/texl_wasm_bg-DqOV-p_i.wasm +0 -0
  63. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/LICENSE +0 -0
  64. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/src/stilo/__init__.py +0 -0
  65. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/src/stilo/__main__.py +0 -0
  66. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/src/stilo/cli/__init__.py +0 -0
  67. {stilo_cli-0.1.0 → stilo_cli-0.3.0}/src/stilo/server/__init__.py +0 -0
@@ -16,4 +16,5 @@ src/stilo/web/
16
16
 
17
17
  # Locals
18
18
  local/
19
- target/
19
+ *.todo.md
20
+
@@ -1,14 +1,14 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: stilo-cli
3
- Version: 0.1.0
3
+ Version: 0.3.0
4
4
  Summary: Stilo: edit and render a folder of linked Texl documents
5
- Project-URL: Homepage, https://www.onlabs.org/stilo/
5
+ Project-URL: Documentation, https://www.onlabs.org/manual/
6
6
  Project-URL: Source, https://github.com/onlabsorg/stilo
7
7
  License-Expression: MIT
8
8
  License-File: LICENSE
9
9
  Requires-Python: >=3.11
10
10
  Requires-Dist: fastapi>=0.115
11
- Requires-Dist: pytexl>=0.4
11
+ Requires-Dist: pytexl>=0.8.0
12
12
  Requires-Dist: uvicorn>=0.30
13
13
  Description-Content-Type: text/markdown
14
14
 
@@ -48,9 +48,7 @@ cd web && npm install && npm run build && cd ..
48
48
  uv run stilo serve examples
49
49
  ```
50
50
 
51
- Open <http://127.0.0.1:8000/projects/beam/beam-check.texl>. See the
52
- [getting started guide](https://www.onlabs.org/stilo/book/getting-started.html)
53
- and the developer guide.
51
+ Open <http://127.0.0.1:8000/projects/beam/beam-check.texl>.
54
52
 
55
53
  ## Parts
56
54
 
@@ -60,15 +58,19 @@ and the developer guide.
60
58
  | `src/stilo/` | The Python package `stilo`: `server/` (FastAPI, one folder of documents), `cli/` (the `stilo` command, `render` and `serve`), `web/` (the built web app) |
61
59
  | `tests/` | The Python tests |
62
60
  | `pyproject.toml` | The package `stilo`, the only one published (on PyPI: `stilo-cli`) |
63
- | `docs/` | The documentation (manual, editor manual, landing page), published on <https://www.onlabs.org/stilo/>; `docs/build.sh` builds it into `target/site` |
61
+ | `docs/` | The developer documentation (plain Markdown) |
64
62
  | `examples/` | Sample documents |
65
63
 
66
64
  ## Documentation
67
65
 
68
- <https://www.onlabs.org/stilo/>: getting started, the `stilo` command, the
69
- web editor (with an interactive editor manual), the protocol, the editor
70
- component and a developer guide. See also [CONTRIBUTING.md](https://github.com/onlabsorg/stilo/blob/main/CONTRIBUTING.md)
71
- and [CHANGELOG.md](https://github.com/onlabsorg/stilo/blob/main/CHANGELOG.md).
66
+ - **Using Stilo:** the [OnLabs.org user manual](https://www.onlabs.org/manual/)
67
+ covers getting started, the web editor, the `stilo` command and the
68
+ document format.
69
+ - **Working on Stilo:** the [developer documentation](https://github.com/onlabsorg/stilo/tree/main/docs)
70
+ covers the architecture, the protocol, the editor component and its API,
71
+ and the development setup. See also
72
+ [CONTRIBUTING.md](https://github.com/onlabsorg/stilo/blob/main/CONTRIBUTING.md)
73
+ and [CHANGELOG.md](https://github.com/onlabsorg/stilo/blob/main/CHANGELOG.md).
72
74
 
73
75
  ## License
74
76
 
@@ -34,9 +34,7 @@ cd web && npm install && npm run build && cd ..
34
34
  uv run stilo serve examples
35
35
  ```
36
36
 
37
- Open <http://127.0.0.1:8000/projects/beam/beam-check.texl>. See the
38
- [getting started guide](https://www.onlabs.org/stilo/book/getting-started.html)
39
- and the developer guide.
37
+ Open <http://127.0.0.1:8000/projects/beam/beam-check.texl>.
40
38
 
41
39
  ## Parts
42
40
 
@@ -46,15 +44,19 @@ and the developer guide.
46
44
  | `src/stilo/` | The Python package `stilo`: `server/` (FastAPI, one folder of documents), `cli/` (the `stilo` command, `render` and `serve`), `web/` (the built web app) |
47
45
  | `tests/` | The Python tests |
48
46
  | `pyproject.toml` | The package `stilo`, the only one published (on PyPI: `stilo-cli`) |
49
- | `docs/` | The documentation (manual, editor manual, landing page), published on <https://www.onlabs.org/stilo/>; `docs/build.sh` builds it into `target/site` |
47
+ | `docs/` | The developer documentation (plain Markdown) |
50
48
  | `examples/` | Sample documents |
51
49
 
52
50
  ## Documentation
53
51
 
54
- <https://www.onlabs.org/stilo/>: getting started, the `stilo` command, the
55
- web editor (with an interactive editor manual), the protocol, the editor
56
- component and a developer guide. See also [CONTRIBUTING.md](https://github.com/onlabsorg/stilo/blob/main/CONTRIBUTING.md)
57
- and [CHANGELOG.md](https://github.com/onlabsorg/stilo/blob/main/CHANGELOG.md).
52
+ - **Using Stilo:** the [OnLabs.org user manual](https://www.onlabs.org/manual/)
53
+ covers getting started, the web editor, the `stilo` command and the
54
+ document format.
55
+ - **Working on Stilo:** the [developer documentation](https://github.com/onlabsorg/stilo/tree/main/docs)
56
+ covers the architecture, the protocol, the editor component and its API,
57
+ and the development setup. See also
58
+ [CONTRIBUTING.md](https://github.com/onlabsorg/stilo/blob/main/CONTRIBUTING.md)
59
+ and [CHANGELOG.md](https://github.com/onlabsorg/stilo/blob/main/CHANGELOG.md).
58
60
 
59
61
  ## License
60
62
 
@@ -6,6 +6,8 @@
6
6
  # src/stilo/web the built web app, written by `npm run build` in web/
7
7
  # (git-ignored; built into the package when present —
8
8
  # the release workflow checks that the wheel has it)
9
+ # texl-lib/ the Texl library `stilo init` copies into projects,
10
+ # shipped in the wheel as stilo/texl-lib
9
11
  #
10
12
  # Build:
11
13
  #
@@ -14,7 +16,7 @@
14
16
 
15
17
  [project]
16
18
  name = "stilo-cli"
17
- version = "0.1.0"
19
+ version = "0.3.0"
18
20
  description = "Stilo: edit and render a folder of linked Texl documents"
19
21
  readme = "README.md"
20
22
  license = "MIT"
@@ -22,7 +24,7 @@ license-files = ["LICENSE"]
22
24
  requires-python = ">=3.11"
23
25
  dependencies = [
24
26
  "fastapi>=0.115",
25
- "pytexl>=0.4",
27
+ "pytexl>=0.8.0",
26
28
  "uvicorn>=0.30",
27
29
  ]
28
30
 
@@ -30,7 +32,7 @@ dependencies = [
30
32
  stilo = "stilo.cli:main"
31
33
 
32
34
  [project.urls]
33
- Homepage = "https://www.onlabs.org/stilo/"
35
+ Documentation = "https://www.onlabs.org/manual/"
34
36
  Source = "https://github.com/onlabsorg/stilo"
35
37
 
36
38
  [dependency-groups]
@@ -44,11 +46,15 @@ requires = ["hatchling"]
44
46
  build-backend = "hatchling.build"
45
47
 
46
48
  [tool.hatch.build.targets.sdist]
47
- only-include = ["src/stilo", "README.md", "LICENSE"]
49
+ only-include = ["src/stilo", "texl-lib", "README.md", "LICENSE"]
48
50
 
49
51
  [tool.hatch.build.targets.wheel]
50
52
  packages = ["src/stilo"]
51
53
 
54
+ # In a checkout the CLI reads texl-lib/ where it is (stilo/cli/project.py).
55
+ [tool.hatch.build.targets.wheel.force-include]
56
+ "texl-lib" = "stilo/texl-lib"
57
+
52
58
  # src/stilo/web is git-ignored: include it anyway when it is there. Not a
53
59
  # forced include, so that editable installs (`uv run`) work without it.
54
60
  [tool.hatch.build]
@@ -0,0 +1,136 @@
1
+ """The `stilo` subcommands.
2
+
3
+ Each command is a `Command`: a name, a help line, a function that adds its
4
+ arguments to a parser and a function that runs it. `COMMANDS` lists them in
5
+ the order `stilo --help` shows them; a plugin system can later add its own.
6
+ """
7
+
8
+ import asyncio
9
+ import shutil
10
+ import sys
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+ from typing import Callable
14
+
15
+ import pytexl
16
+ import uvicorn
17
+
18
+ from stilo.server import create_app
19
+
20
+ from .errors import count_returned, find_errors, format_report, numbered_text
21
+ from .project import LIB, LIBRARY_NAME, MANIFEST, TEXL_LIB, create_engine, manifest
22
+
23
+ # The built web app, `stilo/web`: written there by `npm run build` in a
24
+ # checkout, shipped there in the package
25
+ WEB_DIST = Path(__file__).resolve().parents[1] / "web"
26
+
27
+
28
+ @dataclass
29
+ class Command:
30
+ name: str
31
+ help: str
32
+ add_arguments: Callable
33
+ run: Callable # (args) -> exit status
34
+
35
+
36
+ def render_arguments(parser):
37
+ parser.add_argument("file", type=Path,
38
+ help="document to render; relative imports resolve from its folder")
39
+ parser.add_argument("-o", "--output", type=Path,
40
+ help="output file (default: standard output)")
41
+ parser.add_argument("-d", "--debug", action="store_true",
42
+ help="number the undefined values in the output and explain each one on standard error")
43
+ parser.add_argument("--strict", action="store_true",
44
+ help="exit with status 1 if the document returned an undefined value")
45
+
46
+
47
+ def render(args) -> int:
48
+ """Renders a document to standard output or a file, like `texl`."""
49
+ path = args.file.resolve()
50
+ try:
51
+ doc = asyncio.run(create_engine().load(path.as_uri()))
52
+ except pytexl.LoadError as e:
53
+ print(f"stilo: {args.file}: could not be loaded: {e.reason}", file=sys.stderr)
54
+ return 1
55
+ errors = find_errors(doc)
56
+ text = numbered_text(doc, errors) if args.debug else doc.text
57
+ if args.output:
58
+ try:
59
+ args.output.write_text(text, encoding="utf-8")
60
+ except OSError as e:
61
+ print(f"stilo: {args.output}: {e}", file=sys.stderr)
62
+ return 1
63
+ else:
64
+ sys.stdout.write(text)
65
+ sys.stdout.flush() # the document comes before the report on a terminal
66
+ if errors:
67
+ report_errors(args, doc, errors)
68
+ return 1 if errors and args.strict else 0
69
+
70
+
71
+ def report_errors(args, doc, errors):
72
+ """Says on standard error how many undefined values `doc` returned, and, with `--debug`, why."""
73
+ count = count_returned(errors)
74
+ summary = f"stilo: {args.file}: {count} undefined value{'' if count == 1 else 's'}"
75
+ if args.debug:
76
+ print(f"{summary}\n\n{format_report(doc, errors)}", file=sys.stderr)
77
+ else:
78
+ print(f"{summary} (use --debug to list them)", file=sys.stderr)
79
+
80
+
81
+ def serve_arguments(parser):
82
+ parser.add_argument("folder", type=Path, nargs="?", default=Path("."),
83
+ help="folder of the documents (default: the current folder)")
84
+ parser.add_argument("--host", default="127.0.0.1",
85
+ help="address to listen on (default: 127.0.0.1)")
86
+ parser.add_argument("--port", type=int, default=8000)
87
+ parser.add_argument("--web", type=Path, default=WEB_DIST,
88
+ help="built web app (default: the one installed with stilo)")
89
+
90
+
91
+ def serve(args) -> int:
92
+ """Serves a folder of documents and the Stilo web app over HTTP."""
93
+ if not args.folder.is_dir():
94
+ print(f"stilo: {args.folder}: not a folder", file=sys.stderr)
95
+ return 1
96
+ print(f"Stilo: serving {args.folder.resolve()} at http://{args.host}:{args.port}/")
97
+ uvicorn.run(create_app(args.folder, args.web), host=args.host, port=args.port)
98
+ return 0
99
+
100
+
101
+ def init_arguments(parser):
102
+ parser.add_argument("folder", type=Path, nargs="?", default=Path("."),
103
+ help="folder of the project, created if missing (default: the current folder)")
104
+ parser.add_argument("--name", help="project name (default: the folder's name)")
105
+
106
+
107
+ def init(args) -> int:
108
+ """Makes a folder a Stilo project: writes project.texl, creates lib/ and
109
+ copies the bundled library into lib/stilo/, never over an existing one."""
110
+ folder = args.folder.resolve()
111
+ if (folder / MANIFEST).exists():
112
+ print(f"stilo: {args.folder}: already a project ({MANIFEST} exists)", file=sys.stderr)
113
+ return 1
114
+ library = folder / LIB / LIBRARY_NAME
115
+ try:
116
+ folder.mkdir(parents=True, exist_ok=True)
117
+ with open(folder / MANIFEST, "x", encoding="utf-8") as file:
118
+ file.write(manifest(args.name or folder.name))
119
+ (folder / LIB).mkdir(exist_ok=True)
120
+ kept = library.exists()
121
+ if not kept:
122
+ shutil.copytree(TEXL_LIB, library)
123
+ except OSError as e:
124
+ print(f"stilo: {args.folder}: {e}", file=sys.stderr)
125
+ return 1
126
+ print(f"Stilo: {folder} is a project: {MANIFEST}, {LIB}/")
127
+ if kept:
128
+ print(f"Stilo: {LIB}/{LIBRARY_NAME}/ already exists: left as it is")
129
+ return 0
130
+
131
+
132
+ COMMANDS = [
133
+ Command("init", "make a folder a Stilo project, with the Stilo library", init_arguments, init),
134
+ Command("render", "render a Texl document", render_arguments, render),
135
+ Command("serve", "serve a folder of Texl documents with the web app", serve_arguments, serve),
136
+ ]
@@ -0,0 +1,155 @@
1
+ """The errors of a rendered document, and how `stilo render` reports them.
2
+
3
+ An error is an undefined value that a tag returned, directly or as an item of
4
+ a returned tuple: the Swan counterpart of an exception that was thrown. An
5
+ undefined value that was only assigned, or that sits inside a list or a
6
+ namespace, is not one, and neither is `Nothing`.
7
+ """
8
+
9
+ import os
10
+ from dataclasses import dataclass, field
11
+ from urllib.parse import urlparse
12
+ from urllib.request import url2pathname
13
+
14
+ import pytexl
15
+
16
+ # How Texl renders an undefined value
17
+ UNDEFINED_TEXT = "[[Undefined]]"
18
+
19
+ # The longest source line shown in a report; longer ones are cut around the error
20
+ MAX_EXCERPT = 100
21
+
22
+
23
+ @dataclass
24
+ class Place:
25
+ """Where a document returned an error: the tag, and the span of its text."""
26
+
27
+ tag: pytexl.Tag
28
+ out_start: int
29
+ out_end: int
30
+
31
+
32
+ @dataclass
33
+ class DocumentError:
34
+ """One error, with every place where the document returned it."""
35
+
36
+ number: int
37
+ value: pytexl.Undefined
38
+ places: list[Place] = field(default_factory=list)
39
+
40
+
41
+ def find_errors(doc: pytexl.Document) -> list[DocumentError]:
42
+ """The errors of `doc`, numbered in order of first appearance.
43
+
44
+ The same value returned by several tags is one error with several places.
45
+ """
46
+ errors: dict[tuple, DocumentError] = {}
47
+ for tag in doc.tags:
48
+ for value, out_start, out_end in _returned(doc, tag):
49
+ # A value with no position can only be told apart by its tag
50
+ where = (value.uri, value.pos) if value.pos is not None else tag.start
51
+ key = (where, value.description)
52
+ if key not in errors:
53
+ errors[key] = DocumentError(len(errors) + 1, value)
54
+ errors[key].places.append(Place(tag, out_start, out_end))
55
+ return list(errors.values())
56
+
57
+
58
+ def _returned(doc, tag):
59
+ """The undefined values `tag` returned, each with the span of its text."""
60
+ if isinstance(tag.value, pytexl.Undefined):
61
+ yield tag.value, tag.out_start, tag.out_end
62
+ elif isinstance(tag.value, tuple):
63
+ # A tuple shows its items in order. A text item may itself read
64
+ # "[[Undefined]]", so the search moves past each text item too.
65
+ cursor = tag.out_start
66
+ for item in tag.value:
67
+ if isinstance(item, pytexl.Undefined):
68
+ start = doc.text.index(UNDEFINED_TEXT, cursor, tag.out_end)
69
+ cursor = start + len(UNDEFINED_TEXT)
70
+ yield item, start, cursor
71
+ elif isinstance(item, str):
72
+ found = doc.text.find(item, cursor, tag.out_end)
73
+ cursor = found + len(item) if found >= 0 else cursor
74
+
75
+
76
+ def count_returned(errors: list[DocumentError]) -> int:
77
+ """How many undefined values the document returned, repeats included."""
78
+ return sum(len(error.places) for error in errors)
79
+
80
+
81
+ def numbered_text(doc: pytexl.Document, errors: list[DocumentError]) -> str:
82
+ """The text of `doc`, with each error shown as `[[Undefined #n]]`."""
83
+ spans = [(place.out_start, place.out_end, error.number)
84
+ for error in errors for place in error.places]
85
+ text = doc.text
86
+ for start, end, number in sorted(spans, reverse=True):
87
+ text = f"{text[:start]}[[Undefined #{number}]]{text[end:]}"
88
+ return text
89
+
90
+
91
+ def format_report(doc: pytexl.Document, errors: list[DocumentError]) -> str:
92
+ """The errors of `doc` in plain words: where, what, and what caused them."""
93
+ return "\n\n".join(_format_error(doc, error) for error in errors)
94
+
95
+
96
+ def _format_error(doc, error):
97
+ value = error.value
98
+ if value.pos is not None:
99
+ uri, source, pos = value.uri, value.source, value.pos
100
+ else:
101
+ # No position of its own: point at the tag that returned it
102
+ uri, source, pos = doc.uri, doc.source, error.places[0].tag.start
103
+ lines = [f"#{error.number} {_location(uri, source, pos)} {value.description}"]
104
+ lines += [f" {line}" for line in _excerpt(source, pos)]
105
+
106
+ cause = value.cause
107
+ while cause is not None: # not `while cause`: an undefined value is falsy
108
+ where = f" {_location(cause.uri, cause.source, cause.pos)}:" if cause.pos is not None else ":"
109
+ lines.append(f" caused by{where} {cause.description}")
110
+ cause = cause.cause
111
+
112
+ shown = sorted({_line_number(doc.source, place.tag.start) for place in error.places})
113
+ if shown != [_line_number(source, pos)] or uri != doc.uri:
114
+ label = "line" if len(shown) == 1 else "lines"
115
+ numbers = ", ".join(str(n) for n in shown)
116
+ lines.append(f" shown at {_document_name(doc.uri)} {label} {numbers}")
117
+ return "\n".join(lines)
118
+
119
+
120
+ def _location(uri, source, pos):
121
+ """`file:line:column`, counted from 1."""
122
+ start = source.rfind("\n", 0, pos) + 1
123
+ return f"{_document_name(uri)}:{_line_number(source, pos)}:{pos - start + 1}"
124
+
125
+
126
+ def _line_number(source, pos):
127
+ return source.count("\n", 0, pos) + 1
128
+
129
+
130
+ def _document_name(uri):
131
+ """A file's path relative to the current folder; any other URI as it is."""
132
+ if uri is None:
133
+ return "(parsed code)" # code run by Swan's `parse` has no document
134
+ parsed = urlparse(uri)
135
+ if parsed.scheme != "file":
136
+ return uri
137
+ path = url2pathname(parsed.path)
138
+ try:
139
+ return os.path.relpath(path)
140
+ except ValueError: # another drive, on Windows
141
+ return path
142
+
143
+
144
+ def _excerpt(source, pos):
145
+ """The source line holding `pos`, and a caret under `pos`."""
146
+ start = source.rfind("\n", 0, pos) + 1
147
+ end = source.find("\n", pos)
148
+ line = source[start:end if end >= 0 else len(source)].rstrip("\r")
149
+ column = pos - start
150
+ if len(line) > MAX_EXCERPT:
151
+ first = max(0, min(column - MAX_EXCERPT // 2, len(line) - MAX_EXCERPT))
152
+ line, column = line[first:first + MAX_EXCERPT], column - first
153
+ # Tabs stay tabs, so the caret lines up however wide they are
154
+ padding = "".join("\t" if c == "\t" else " " for c in line[:column])
155
+ return [line, f"{padding}^"]
@@ -0,0 +1,83 @@
1
+ """Projects in the CLI (DECISIONS.md S10): the engine that resolves `~` in
2
+ file paths, and what `stilo init` writes.
3
+
4
+ The rule itself is in `stilo.server.home`, shared with the server.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import re
10
+ from importlib.metadata import PackageNotFoundError, version
11
+ from pathlib import Path
12
+
13
+ import pytexl
14
+ from pytexl.loaders import file_path, load_file
15
+
16
+ from stilo.server.home import MANIFEST, expand_home, has_home
17
+
18
+ # The Texl library Stilo bundles, copied into a project's lib/stilo/ by
19
+ # `stilo init`. Its source is `texl-lib/` at the root of the checkout; the
20
+ # wheel ships it as `stilo/texl-lib` (pyproject.toml).
21
+ PACKAGE = Path(__file__).resolve().parents[1]
22
+ _INSTALLED_LIB = PACKAGE / "texl-lib"
23
+ TEXL_LIB = _INSTALLED_LIB if _INSTALLED_LIB.is_dir() else PACKAGE.parents[1] / "texl-lib"
24
+
25
+ LIB = "lib"
26
+ LIBRARY_NAME = "stilo"
27
+
28
+
29
+ def stilo_version() -> str:
30
+ """The version of the installed package (pyproject.toml), the one place it is set."""
31
+ try:
32
+ return version("stilo-cli")
33
+ except PackageNotFoundError: # a checkout run without installing
34
+ return "0.0.0"
35
+
36
+
37
+ def top_of(folder: Path) -> Path:
38
+ """The highest folder the search for a home may reach from `folder`: the
39
+ user's home directory, or the file-system root for a folder outside it."""
40
+ user_home = Path.home().resolve()
41
+ return user_home if folder.is_relative_to(user_home) else Path(folder.anchor)
42
+
43
+
44
+ def resolve_file(uri: str) -> Path:
45
+ """The file a `file://` URL or an absolute path stands for, `~` resolved."""
46
+ path = file_path(uri)
47
+ if not has_home(path):
48
+ return path
49
+ return expand_home(Path(path.anchor), path.parts[1:], top_of)
50
+
51
+
52
+ async def load_project_file(uri: str) -> str | tuple[str, str]:
53
+ """pytexl's file loader, with `~` resolved. A path with `~` gives the
54
+ real file as the document's final URL (Texl 0.8): its identity, so
55
+ imports of one library by different paths share it, and a cycle
56
+ through `~` ends."""
57
+ if not has_home(file_path(uri)):
58
+ return await load_file(uri)
59
+ final_url = resolve_file(uri).as_uri()
60
+ return final_url, await load_file(final_url)
61
+
62
+
63
+ def create_engine() -> pytexl.Engine:
64
+ """The engine of every CLI command that renders."""
65
+ engine = pytexl.Engine()
66
+ engine.add_loader("file", load_project_file)
67
+ engine.set_default_loader(load_project_file)
68
+ return engine
69
+
70
+
71
+ def manifest(name: str) -> str:
72
+ """The text of a new `project.texl`. Swan strings have no escapes, so
73
+ the name loses any `"` and `%>`."""
74
+ name = re.sub(r'"|%>', "", name).strip() or "project"
75
+ return f"""# {name}
76
+
77
+ This folder is a Stilo project. This file marks its home folder: in an
78
+ import, `~` stands for it, as in `~/lib/stilo/index.texl`. The values below
79
+ configure the project.
80
+
81
+ <% project_name = "{name}" %>
82
+ <% stilo_version = "{stilo_version()}" %>
83
+ """
@@ -0,0 +1,142 @@
1
+ """HTTP layer: protocol v0 (docs/protocol.md) and the web app's files."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import mimetypes
6
+ from pathlib import Path
7
+ from urllib.parse import quote
8
+
9
+ from fastapi import FastAPI, Query, Request
10
+ from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, RedirectResponse, Response
11
+ from fastapi.staticfiles import StaticFiles
12
+
13
+ from .home import has_home
14
+ from .storage import BadRequest, Storage, StorageError
15
+
16
+ TEXT = "text/plain; charset=utf-8"
17
+
18
+ # Document contents change and the editor fetches imports on every rendering:
19
+ # browsers must not reuse a stored copy without asking the server again.
20
+ NO_CACHE = {"Cache-Control": "no-cache"}
21
+
22
+ # Python's own table of types, not the machine's, so that every installation
23
+ # answers the same. WebP is missing from the table of Python 3.11.
24
+ FILE_TYPES = mimetypes.MimeTypes()
25
+ FILE_TYPES.add_type("image/webp", ".webp")
26
+
27
+ NO_BUILD = """<!doctype html><meta charset="utf-8"><title>Stilo</title>
28
+ <p>The web app is not built. Run <code>npm run build</code> in <code>web/</code>
29
+ of the Stilo checkout, or use the Vite dev server (<code>npm run dev</code>).</p>"""
30
+
31
+
32
+ def other_file_response(path: str, content: bytes, tag: str) -> Response:
33
+ """A file that is not a Texl document, by its public URL. Files are
34
+ untrusted: one opened by its URL must not run scripts on this origin, which
35
+ can write to every document (docs/protocol.md)."""
36
+ media_type, encoding = FILE_TYPES.guess_type(path)
37
+ if media_type is None or encoding is not None:
38
+ media_type = "application/octet-stream"
39
+ headers = {"ETag": tag, "X-Content-Type-Options": "nosniff", **NO_CACHE, "Vary": "Accept"}
40
+ if media_type.endswith(("/html", "/xml", "+xml")):
41
+ headers["Content-Security-Policy"] = "sandbox"
42
+ return Response(content, media_type=media_type, headers=headers)
43
+
44
+
45
+ def create_app(root: Path | str, web_dist: Path | str | None = None) -> FastAPI:
46
+ """The server app for the documents under `root`. `web_dist` is the built
47
+ web app (`stilo/web` in the CLI); without it, app pages show a notice."""
48
+ storage = Storage(root)
49
+ app = FastAPI(title="Stilo server", version="0.3.0")
50
+
51
+ @app.exception_handler(StorageError)
52
+ async def storage_error(request: Request, error: StorageError):
53
+ return JSONResponse({"error": str(error)}, status_code=error.status)
54
+
55
+ def home_redirect(prefix: str, path: str, request: Request) -> Response | None:
56
+ """A read whose path has `~` segments is redirected to the real path
57
+ (docs/protocol.md): the document is the one at the URL a redirect
58
+ leads to, its identity for Texl (final URLs, Texl 0.8), so imports of
59
+ one library by different paths share it, and a cycle through `~`
60
+ ends. Temporary, since the home depends on manifests that can change."""
61
+ if not has_home(path):
62
+ return None
63
+ url = prefix + quote(storage.expand_home(path), safe="/")
64
+ if request.url.query:
65
+ url += "?" + request.url.query
66
+ return RedirectResponse(url, status_code=307, headers=NO_CACHE)
67
+
68
+ @app.api_route("/_api/files/{path:path}", methods=["GET", "HEAD"])
69
+ async def get_file(path: str, request: Request):
70
+ if redirect := home_redirect("/_api/files/", path, request):
71
+ return redirect
72
+ content, tag = storage.read(path)
73
+ return Response(content, media_type=TEXT, headers={"ETag": tag, **NO_CACHE})
74
+
75
+ @app.post("/_api/files/{path:path}", status_code=201)
76
+ async def create_file(path: str, request: Request):
77
+ tag = storage.create(path, await request.body())
78
+ return Response(status_code=201,
79
+ headers={"ETag": tag, "Location": f"/_api/files/{path}"})
80
+
81
+ @app.put("/_api/files/{path:path}")
82
+ async def update_file(path: str, request: Request):
83
+ tag = storage.update(path, await request.body(), request.headers.get("if-match"))
84
+ return Response(status_code=200, headers={"ETag": tag})
85
+
86
+ @app.delete("/_api/files/{path:path}", status_code=204)
87
+ async def delete_file(path: str):
88
+ storage.delete_file(path)
89
+ return Response(status_code=204)
90
+
91
+ @app.post("/_api/move/{path:path}")
92
+ async def move(path: str, request: Request):
93
+ try:
94
+ to = (await request.json())["to"]
95
+ except (ValueError, KeyError, TypeError):
96
+ raise BadRequest('expected a JSON body {"to": "<new path>"}') from None
97
+ if not isinstance(to, str):
98
+ raise BadRequest('expected a JSON body {"to": "<new path>"}')
99
+ return {"path": storage.move(path, to)}
100
+
101
+ @app.post("/_api/tree/{path:path}", status_code=201)
102
+ async def create_folder(path: str):
103
+ storage.create_folder(path)
104
+ return Response(status_code=201, headers={"Location": f"/_api/tree/{path}"})
105
+
106
+ @app.delete("/_api/tree/{path:path}")
107
+ async def delete_folder(path: str):
108
+ return storage.delete_folder(path)
109
+
110
+ @app.get("/_api/tree/{path:path}")
111
+ async def get_tree(path: str, depth: int | None = Query(None, ge=1)):
112
+ return storage.tree(path, depth)
113
+
114
+ @app.api_route("/_api/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH"])
115
+ async def unknown_api(path: str):
116
+ return JSONResponse({"error": f"unknown endpoint: /_api/{path}"}, status_code=404)
117
+
118
+ dist = Path(web_dist) if web_dist else None
119
+ if dist and (dist / "index.html").is_file():
120
+ # The bundle is built with base "/_app/" (web/vite.config.js).
121
+ app.mount("/_app", StaticFiles(directory=dist), name="app")
122
+
123
+ # Every other path is a public URL. A file that is not a document is served
124
+ # as itself to everyone. For the rest, browsers asking for HTML get the web
125
+ # app, which reads the open document from the URL path (and the navigation
126
+ # root from ?root=); any other client (texl.import) gets the file itself.
127
+ @app.api_route("/{path:path}", methods=["GET", "HEAD"], include_in_schema=False)
128
+ async def page(path: str, request: Request):
129
+ if redirect := home_redirect("/", path, request):
130
+ return redirect
131
+ vary = {"Vary": "Accept"}
132
+ if storage.is_other_file(path):
133
+ return other_file_response(path, *storage.read(path))
134
+ if "text/html" not in request.headers.get("accept", ""):
135
+ content, tag = storage.read(path)
136
+ return Response(content, media_type=TEXT,
137
+ headers={"ETag": tag, **NO_CACHE, **vary})
138
+ if dist and (dist / "index.html").is_file():
139
+ return FileResponse(dist / "index.html", media_type="text/html", headers=vary)
140
+ return HTMLResponse(NO_BUILD, headers=vary)
141
+
142
+ return app