stilo-cli 0.2.0__tar.gz → 0.4.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 (92) hide show
  1. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/.gitignore +3 -0
  2. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/PKG-INFO +7 -2
  3. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/README.md +4 -0
  4. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/pyproject.toml +14 -3
  5. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/cli/commands.py +33 -10
  6. stilo_cli-0.4.0/src/stilo/cli/project.py +105 -0
  7. stilo_cli-0.4.0/src/stilo/cli/tutor.py +152 -0
  8. stilo_cli-0.4.0/src/stilo/cli/web.py +37 -0
  9. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/server/app.py +22 -3
  10. stilo_cli-0.4.0/src/stilo/server/home.py +72 -0
  11. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/server/storage.py +70 -54
  12. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_AMS-Regular-BQhdFMY1.woff2 +0 -0
  13. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Caligraphic-Bold-Dq_IR9rO.woff2 +0 -0
  14. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Caligraphic-Regular-Di6jR-x-.woff2 +0 -0
  15. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Fraktur-Bold-CL6g_b3V.woff2 +0 -0
  16. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Fraktur-Regular-CTYiF6lA.woff2 +0 -0
  17. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Main-Bold-Cx986IdX.woff2 +0 -0
  18. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Main-BoldItalic-DxDJ3AOS.woff2 +0 -0
  19. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Main-Italic-NWA7e6Wa.woff2 +0 -0
  20. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Main-Regular-B22Nviop.woff2 +0 -0
  21. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Math-BoldItalic-CZnvNsCZ.woff2 +0 -0
  22. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Math-Italic-t53AETM-.woff2 +0 -0
  23. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_SansSerif-Bold-D1sUS0GD.woff2 +0 -0
  24. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_SansSerif-Italic-C3H0VqGB.woff2 +0 -0
  25. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_SansSerif-Regular-DDBCnlJ7.woff2 +0 -0
  26. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Script-Regular-D3wIWfF6.woff2 +0 -0
  27. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Size1-Regular-mCD8mA8B.woff2 +0 -0
  28. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Size2-Regular-Dy4dx90m.woff2 +0 -0
  29. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Size4-Regular-Dl5lxZxV.woff2 +0 -0
  30. stilo_cli-0.4.0/src/stilo/web/assets/KaTeX_Typewriter-Regular-CO6r4hn1.woff2 +0 -0
  31. stilo_cli-0.4.0/src/stilo/web/assets/atkinson-hyperlegible-next-latin-ext-wght-italic-Cigfgs4r.woff2 +0 -0
  32. stilo_cli-0.4.0/src/stilo/web/assets/atkinson-hyperlegible-next-latin-ext-wght-normal-C6vrW8VD.woff2 +0 -0
  33. stilo_cli-0.4.0/src/stilo/web/assets/atkinson-hyperlegible-next-latin-wght-italic-DC5MiAaX.woff2 +0 -0
  34. stilo_cli-0.4.0/src/stilo/web/assets/atkinson-hyperlegible-next-latin-wght-normal-BcXVPD7q.woff2 +0 -0
  35. stilo_cli-0.4.0/src/stilo/web/assets/index-B8RYzswc.css +1 -0
  36. stilo_cli-0.4.0/src/stilo/web/assets/index-CVdAQRVd.js +2480 -0
  37. stilo_cli-0.4.0/src/stilo/web/assets/texl_wasm_bg-CzhWLYga.wasm +0 -0
  38. stilo_cli-0.4.0/src/stilo/web/favicon.svg +1 -0
  39. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/web/index.html +3 -2
  40. stilo_cli-0.4.0/texl-lib/charts.texl +161 -0
  41. stilo_cli-0.4.0/texl-lib/dataframe.texl +117 -0
  42. stilo_cli-0.4.0/texl-lib/index.texl +19 -0
  43. stilo_cli-0.4.0/tutorial/01-welcome.texl +73 -0
  44. stilo_cli-0.4.0/tutorial/02-cells.texl +79 -0
  45. stilo_cli-0.4.0/tutorial/03-rich-text.texl +57 -0
  46. stilo_cli-0.4.0/tutorial/04-formulas.texl +75 -0
  47. stilo_cli-0.4.0/tutorial/05-cell-types.texl +56 -0
  48. stilo_cli-0.4.0/tutorial/06-tables-and-equations.texl +77 -0
  49. stilo_cli-0.4.0/tutorial/07-data-tables.texl +107 -0
  50. stilo_cli-0.4.0/tutorial/08-linking.texl +66 -0
  51. stilo_cli-0.4.0/tutorial/09-errors.texl +56 -0
  52. stilo_cli-0.4.0/tutorial/10-organising.texl +86 -0
  53. stilo_cli-0.4.0/tutorial/11-command-line.texl +81 -0
  54. stilo_cli-0.4.0/tutorial/12-your-first-project.texl +72 -0
  55. stilo_cli-0.4.0/tutorial/13-formula-language.texl +77 -0
  56. stilo_cli-0.4.0/tutorial/14-libraries.texl +57 -0
  57. stilo_cli-0.4.0/tutorial/files/beam-drawing.pdf +50 -0
  58. stilo_cli-0.4.0/tutorial/files/beam.svg +18 -0
  59. stilo_cli-0.4.0/tutorial/files/report.texl +15 -0
  60. stilo_cli-0.4.0/tutorial/index.texl +62 -0
  61. stilo_cli-0.4.0/tutorial/lib/steel/sections.texl +17 -0
  62. stilo_cli-0.4.0/tutorial/lib/tutorial/index.texl +36 -0
  63. stilo_cli-0.2.0/src/stilo/web/assets/index-BUxoyfxd.js +0 -1712
  64. stilo_cli-0.2.0/src/stilo/web/assets/index-kR4PIGIs.css +0 -1
  65. stilo_cli-0.2.0/src/stilo/web/assets/literata-cyrillic-ext-opsz-italic-5yUt4G_9.woff2 +0 -0
  66. stilo_cli-0.2.0/src/stilo/web/assets/literata-cyrillic-ext-opsz-normal-C5tfwALZ.woff2 +0 -0
  67. stilo_cli-0.2.0/src/stilo/web/assets/literata-cyrillic-opsz-italic-Bj0ndbyp.woff2 +0 -0
  68. stilo_cli-0.2.0/src/stilo/web/assets/literata-cyrillic-opsz-normal-DgmypKXX.woff2 +0 -0
  69. stilo_cli-0.2.0/src/stilo/web/assets/literata-greek-ext-opsz-italic-DFpO5j-Z.woff2 +0 -0
  70. stilo_cli-0.2.0/src/stilo/web/assets/literata-greek-ext-opsz-normal-DGm64vGR.woff2 +0 -0
  71. stilo_cli-0.2.0/src/stilo/web/assets/literata-greek-opsz-italic-CHERNRFq.woff2 +0 -0
  72. stilo_cli-0.2.0/src/stilo/web/assets/literata-greek-opsz-normal-DFglUmAd.woff2 +0 -0
  73. stilo_cli-0.2.0/src/stilo/web/assets/literata-latin-ext-opsz-italic-4y8iAqqs.woff2 +0 -0
  74. stilo_cli-0.2.0/src/stilo/web/assets/literata-latin-ext-opsz-normal-STiTPs0F.woff2 +0 -0
  75. stilo_cli-0.2.0/src/stilo/web/assets/literata-latin-opsz-italic-CJ93D38p.woff2 +0 -0
  76. stilo_cli-0.2.0/src/stilo/web/assets/literata-latin-opsz-normal-BHZsWIlc.woff2 +0 -0
  77. stilo_cli-0.2.0/src/stilo/web/assets/literata-vietnamese-opsz-italic-BdcrZMcO.woff2 +0 -0
  78. stilo_cli-0.2.0/src/stilo/web/assets/literata-vietnamese-opsz-normal-Gqw5JQlq.woff2 +0 -0
  79. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-cyrillic-ext-wght-normal-c-5QAGAI.woff2 +0 -0
  80. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-cyrillic-wght-normal-BMDVbyM7.woff2 +0 -0
  81. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-greek-ext-wght-normal-BXZfsJY4.woff2 +0 -0
  82. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-greek-wght-normal-Cc-u-6OI.woff2 +0 -0
  83. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-latin-ext-wght-normal-C8iNium2.woff2 +0 -0
  84. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-latin-wght-normal-Bo_j9asI.woff2 +0 -0
  85. stilo_cli-0.2.0/src/stilo/web/assets/source-sans-3-vietnamese-wght-normal-BDs68eHQ.woff2 +0 -0
  86. stilo_cli-0.2.0/src/stilo/web/assets/texl_wasm_bg-2_KrrXbk.wasm +0 -0
  87. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/LICENSE +0 -0
  88. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/__init__.py +0 -0
  89. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/__main__.py +0 -0
  90. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/cli/__init__.py +0 -0
  91. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/cli/errors.py +0 -0
  92. {stilo_cli-0.2.0 → stilo_cli-0.4.0}/src/stilo/server/__init__.py +0 -0
@@ -18,3 +18,6 @@ src/stilo/web/
18
18
  local/
19
19
  *.todo.md
20
20
 
21
+
22
+ # Files deleted by the server (stilo serve moves them here)
23
+ .trash/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: stilo-cli
3
- Version: 0.2.0
3
+ Version: 0.4.0
4
4
  Summary: Stilo: edit and render a folder of linked Texl documents
5
5
  Project-URL: Documentation, https://www.onlabs.org/manual/
6
6
  Project-URL: Source, https://github.com/onlabsorg/stilo
@@ -8,7 +8,8 @@ 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.6.0
11
+ Requires-Dist: platformdirs>=4
12
+ Requires-Dist: pytexl>=0.9.0
12
13
  Requires-Dist: uvicorn>=0.30
13
14
  Description-Content-Type: text/markdown
14
15
 
@@ -35,10 +36,14 @@ Requires Python 3.11 or later. Install the `stilo` command from PyPI, with
35
36
 
36
37
  ```bash
37
38
  uv tool install stilo-cli # or: pip install stilo-cli
39
+ stilo tutor # the tutorial, in your browser
38
40
  stilo serve my-folder # http://127.0.0.1:8000
39
41
  stilo render my-folder/report.texl
40
42
  ```
41
43
 
44
+ `stilo tutor` opens a guided tutorial of short lessons, in your own copy:
45
+ the best way to start.
46
+
42
47
  To try the sample documents, or to work on Stilo itself, use a checkout
43
48
  (Node.js 22+ builds the web app):
44
49
 
@@ -21,10 +21,14 @@ Requires Python 3.11 or later. Install the `stilo` command from PyPI, with
21
21
 
22
22
  ```bash
23
23
  uv tool install stilo-cli # or: pip install stilo-cli
24
+ stilo tutor # the tutorial, in your browser
24
25
  stilo serve my-folder # http://127.0.0.1:8000
25
26
  stilo render my-folder/report.texl
26
27
  ```
27
28
 
29
+ `stilo tutor` opens a guided tutorial of short lessons, in your own copy:
30
+ the best way to start.
31
+
28
32
  To try the sample documents, or to work on Stilo itself, use a checkout
29
33
  (Node.js 22+ builds the web app):
30
34
 
@@ -6,6 +6,10 @@
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
11
+ # tutorial/ the lessons `stilo tutor` copies and serves, shipped
12
+ # in the wheel as stilo/tutorial
9
13
  #
10
14
  # Build:
11
15
  #
@@ -14,7 +18,7 @@
14
18
 
15
19
  [project]
16
20
  name = "stilo-cli"
17
- version = "0.2.0"
21
+ version = "0.4.0"
18
22
  description = "Stilo: edit and render a folder of linked Texl documents"
19
23
  readme = "README.md"
20
24
  license = "MIT"
@@ -22,7 +26,8 @@ license-files = ["LICENSE"]
22
26
  requires-python = ">=3.11"
23
27
  dependencies = [
24
28
  "fastapi>=0.115",
25
- "pytexl>=0.6.0",
29
+ "platformdirs>=4",
30
+ "pytexl>=0.9.0",
26
31
  "uvicorn>=0.30",
27
32
  ]
28
33
 
@@ -44,11 +49,17 @@ requires = ["hatchling"]
44
49
  build-backend = "hatchling.build"
45
50
 
46
51
  [tool.hatch.build.targets.sdist]
47
- only-include = ["src/stilo", "README.md", "LICENSE"]
52
+ only-include = ["src/stilo", "texl-lib", "tutorial", "README.md", "LICENSE"]
48
53
 
49
54
  [tool.hatch.build.targets.wheel]
50
55
  packages = ["src/stilo"]
51
56
 
57
+ # In a checkout the CLI reads texl-lib/ and tutorial/ where they are
58
+ # (stilo/cli/project.py, stilo/cli/tutor.py).
59
+ [tool.hatch.build.targets.wheel.force-include]
60
+ "texl-lib" = "stilo/texl-lib"
61
+ "tutorial" = "stilo/tutorial"
62
+
52
63
  # src/stilo/web is git-ignored: include it anyway when it is there. Not a
53
64
  # forced include, so that editable installs (`uv run`) work without it.
54
65
  [tool.hatch.build]
@@ -12,15 +12,11 @@ from pathlib import Path
12
12
  from typing import Callable
13
13
 
14
14
  import pytexl
15
- import uvicorn
16
-
17
- from stilo.server import create_app
18
15
 
19
16
  from .errors import count_returned, find_errors, format_report, numbered_text
20
-
21
- # The built web app, `stilo/web`: written there by `npm run build` in a
22
- # checkout, shipped there in the package
23
- WEB_DIST = Path(__file__).resolve().parents[1] / "web"
17
+ from .project import LIB, LIBRARY_NAME, MANIFEST, create_engine, make_project
18
+ from .tutor import tutor, tutor_arguments
19
+ from .web import WEB_DIST, run_server
24
20
 
25
21
 
26
22
  @dataclass
@@ -46,7 +42,7 @@ def render(args) -> int:
46
42
  """Renders a document to standard output or a file, like `texl`."""
47
43
  path = args.file.resolve()
48
44
  try:
49
- doc = asyncio.run(pytexl.Engine().load(path.as_uri()))
45
+ doc = asyncio.run(create_engine().load(path.as_uri()))
50
46
  except pytexl.LoadError as e:
51
47
  print(f"stilo: {args.file}: could not be loaded: {e.reason}", file=sys.stderr)
52
48
  return 1
@@ -91,12 +87,39 @@ def serve(args) -> int:
91
87
  if not args.folder.is_dir():
92
88
  print(f"stilo: {args.folder}: not a folder", file=sys.stderr)
93
89
  return 1
94
- print(f"Stilo: serving {args.folder.resolve()} at http://{args.host}:{args.port}/")
95
- uvicorn.run(create_app(args.folder, args.web), host=args.host, port=args.port)
90
+ print(f"Stilo: serving {args.folder.resolve()} at http://{args.host}:{args.port}/ "
91
+ "(press Ctrl+C here to stop)")
92
+ run_server(args.folder, args.host, args.port, args.web)
93
+ return 0
94
+
95
+
96
+ def init_arguments(parser):
97
+ parser.add_argument("folder", type=Path, nargs="?", default=Path("."),
98
+ help="folder of the project, created if missing (default: the current folder)")
99
+ parser.add_argument("--name", help="project name (default: the folder's name)")
100
+
101
+
102
+ def init(args) -> int:
103
+ """Makes a folder a Stilo project: writes project.texl, creates lib/ and
104
+ copies the bundled library into lib/stilo/, never over an existing one."""
105
+ folder = args.folder.resolve()
106
+ if (folder / MANIFEST).exists():
107
+ print(f"stilo: {args.folder}: already a project ({MANIFEST} exists)", file=sys.stderr)
108
+ return 1
109
+ try:
110
+ kept = make_project(folder, args.name or folder.name)
111
+ except OSError as e:
112
+ print(f"stilo: {args.folder}: {e}", file=sys.stderr)
113
+ return 1
114
+ print(f"Stilo: {folder} is a project: {MANIFEST}, {LIB}/")
115
+ if kept:
116
+ print(f"Stilo: {LIB}/{LIBRARY_NAME}/ already exists: left as it is")
96
117
  return 0
97
118
 
98
119
 
99
120
  COMMANDS = [
121
+ Command("init", "make a folder a Stilo project, with the Stilo library", init_arguments, init),
100
122
  Command("render", "render a Texl document", render_arguments, render),
101
123
  Command("serve", "serve a folder of Texl documents with the web app", serve_arguments, serve),
124
+ Command("tutor", "learn Stilo: open the tutorial in the web app", tutor_arguments, tutor),
102
125
  ]
@@ -0,0 +1,105 @@
1
+ """Projects in the CLI (DECISIONS.md S10): the engine that resolves `~` in
2
+ file paths, and what `stilo init` (and `stilo tutor`, S14) 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
+ import shutil
11
+ from importlib.metadata import PackageNotFoundError, version
12
+ from pathlib import Path
13
+
14
+ import pytexl
15
+ from pytexl.loaders import file_path, load_file
16
+
17
+ from stilo.server.home import MANIFEST, expand_home, has_home
18
+
19
+ # The Texl library Stilo bundles, copied into a project's lib/stilo/ by
20
+ # `stilo init`. Its source is `texl-lib/` at the root of the checkout; the
21
+ # wheel ships it as `stilo/texl-lib` (pyproject.toml).
22
+ PACKAGE = Path(__file__).resolve().parents[1]
23
+ _INSTALLED_LIB = PACKAGE / "texl-lib"
24
+ TEXL_LIB = _INSTALLED_LIB if _INSTALLED_LIB.is_dir() else PACKAGE.parents[1] / "texl-lib"
25
+
26
+ LIB = "lib"
27
+ LIBRARY_NAME = "stilo"
28
+
29
+
30
+ def make_project(folder: Path, name: str) -> bool:
31
+ """Makes `folder` a project: creates it if missing, writes `project.texl`
32
+ (never over an existing one: `FileExistsError`), creates `lib/` and
33
+ copies the bundled library into `lib/stilo/`. Returns whether a
34
+ `lib/stilo/` was already there, which is then left as it is."""
35
+ library = folder / LIB / LIBRARY_NAME
36
+ folder.mkdir(parents=True, exist_ok=True)
37
+ with open(folder / MANIFEST, "x", encoding="utf-8") as file:
38
+ file.write(manifest(name))
39
+ (folder / LIB).mkdir(exist_ok=True)
40
+ kept = library.exists()
41
+ if not kept:
42
+ shutil.copytree(TEXL_LIB, library)
43
+ return kept
44
+
45
+
46
+ def stilo_version() -> str:
47
+ """The version of the installed package (pyproject.toml), the one place it is set."""
48
+ try:
49
+ return version("stilo-cli")
50
+ except PackageNotFoundError: # a checkout run without installing
51
+ return "0.0.0"
52
+
53
+
54
+ def top_of(folder: Path) -> Path:
55
+ """The highest folder the search for a home may reach from `folder`: the
56
+ user's home directory, or the file-system root for a folder outside it."""
57
+ user_home = Path.home().resolve()
58
+ return user_home if folder.is_relative_to(user_home) else Path(folder.anchor)
59
+
60
+
61
+ def resolve_file(uri: str) -> Path:
62
+ """The file a `file://` URL or an absolute path stands for, `~` resolved."""
63
+ path = file_path(uri)
64
+ if not has_home(path):
65
+ return path
66
+ return expand_home(Path(path.anchor), path.parts[1:], top_of)
67
+
68
+
69
+ async def load_project_file(uri: str) -> str | tuple[str, str]:
70
+ """pytexl's file loader, with `~` resolved. A path with `~` gives the
71
+ real file as the document's final URL (Texl 0.8): its identity, so
72
+ imports of one library by different paths share it, and a cycle
73
+ through `~` ends."""
74
+ if not has_home(file_path(uri)):
75
+ return await load_file(uri)
76
+ final_url = resolve_file(uri).as_uri()
77
+ return final_url, await load_file(final_url)
78
+
79
+
80
+ def create_engine() -> pytexl.Engine:
81
+ """The engine of every CLI command that renders."""
82
+ engine = pytexl.Engine()
83
+ engine.add_loader("file", load_project_file)
84
+ engine.set_default_loader(load_project_file)
85
+ return engine
86
+
87
+
88
+ def swan_text(value: str) -> str:
89
+ """`value` made safe for a Swan text literal in a tag: Swan strings have
90
+ no escapes, so it loses any `"` and `%>`."""
91
+ return re.sub(r'"|%>', "", value).strip()
92
+
93
+
94
+ def manifest(name: str) -> str:
95
+ """The text of a new `project.texl`."""
96
+ name = swan_text(name) or "project"
97
+ return f"""# {name}
98
+
99
+ This folder is a Stilo project. This file marks its home folder: in an
100
+ import, `~` stands for it, as in `~/lib/stilo/index.texl`. The values below
101
+ configure the project.
102
+
103
+ <% project_name = "{name}" %>
104
+ <% stilo_version = "{stilo_version()}" %>
105
+ """
@@ -0,0 +1,152 @@
1
+ """`stilo tutor`: the tutorial, in a working copy (DECISIONS.md S14).
2
+
3
+ The tutorial's source is `tutorial/` at the root of the checkout, shipped in
4
+ the wheel as `stilo/tutorial` (pyproject.toml). The user never edits it:
5
+ `stilo tutor` copies it into a working folder, makes the copy a project with
6
+ the code of `stilo init`, and serves it. An existing copy is reused, so
7
+ progress is kept; `--reset` moves it aside first, never deleting it.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ import shutil
14
+ import sys
15
+ from datetime import datetime
16
+ from pathlib import Path
17
+
18
+ import platformdirs
19
+
20
+ from .project import MANIFEST, PACKAGE, make_project, stilo_version, swan_text
21
+ from .web import WEB_DIST, run_server
22
+
23
+ _INSTALLED_TUTORIAL = PACKAGE / "tutorial"
24
+ TUTORIAL = _INSTALLED_TUTORIAL if _INSTALLED_TUTORIAL.is_dir() else PACKAGE.parents[1] / "tutorial"
25
+
26
+ PROJECT_NAME = "Stilo tutorial"
27
+ INDEX = "index.texl"
28
+
29
+ # The value `stilo tutor` adds to the copy's project.texl: the folder of the
30
+ # copy, shown by the command-line lessons. It also tells a copy from any
31
+ # other folder.
32
+ FOLDER_NAME = "tutorial_folder"
33
+ _FOLDER_VALUE = re.compile(rf"<%\s*{FOLDER_NAME}\s*=")
34
+ _VERSION_VALUE = re.compile(r'stilo_version\s*=\s*"([^"]*)"')
35
+
36
+
37
+ def default_folder() -> Path:
38
+ """Where the copy goes by default: `tutorial` in Stilo's user data folder."""
39
+ return platformdirs.user_data_path("stilo", appauthor=False) / "tutorial"
40
+
41
+
42
+ def is_copy(folder: Path) -> bool:
43
+ """Whether `folder` is a working copy of the tutorial."""
44
+ try:
45
+ return bool(_FOLDER_VALUE.search((folder / MANIFEST).read_text(encoding="utf-8")))
46
+ except OSError:
47
+ return False
48
+
49
+
50
+ def is_empty(folder: Path) -> bool:
51
+ return not folder.exists() or (folder.is_dir() and not any(folder.iterdir()))
52
+
53
+
54
+ def create_copy(folder: Path):
55
+ """Copies the tutorial into `folder` (missing or empty) and makes it a project."""
56
+ shutil.copytree(TUTORIAL, folder, dirs_exist_ok=True)
57
+ make_project(folder, PROJECT_NAME)
58
+ with open(folder / MANIFEST, "a", encoding="utf-8") as file:
59
+ file.write(f'<% {FOLDER_NAME} = "{swan_text(str(folder))}" %>\n')
60
+
61
+
62
+ def move_aside(folder: Path) -> Path:
63
+ """Renames `folder` to a free name next to it, with the date and time."""
64
+ stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
65
+ target = folder.with_name(f"{folder.name}-old-{stamp}")
66
+ n = 1
67
+ while target.exists():
68
+ n += 1
69
+ target = folder.with_name(f"{folder.name}-old-{stamp}-{n}")
70
+ folder.rename(target)
71
+ return target
72
+
73
+
74
+ def copy_version(folder: Path) -> str | None:
75
+ """The `stilo_version` written in the copy's project.texl, if any."""
76
+ try:
77
+ match = _VERSION_VALUE.search((folder / MANIFEST).read_text(encoding="utf-8"))
78
+ except OSError:
79
+ return None
80
+ return match.group(1) if match else None
81
+
82
+
83
+ def version_key(text: str) -> tuple[int, ...]:
84
+ """A version for comparison: its leading numbers, `0.3.0rc1` as (0, 3, 0)."""
85
+ numbers = []
86
+ for part in text.split("."):
87
+ digits = re.match(r"\d+", part)
88
+ if not digits:
89
+ break
90
+ numbers.append(int(digits.group()))
91
+ return tuple(numbers)
92
+
93
+
94
+ def is_older(version: str | None, than: str) -> bool:
95
+ return version_key(version or "0") < version_key(than)
96
+
97
+
98
+ def prepare(folder: Path, reset: bool, out=None, err=None) -> bool:
99
+ """Makes sure `folder` holds a working copy, as `stilo tutor` does before
100
+ serving it. Says what it did on `out` (standard output); returns False
101
+ on an error, reported on `err` (standard error)."""
102
+ out, err = out or sys.stdout, err or sys.stderr
103
+ if folder.exists() and not folder.is_dir():
104
+ print(f"stilo: {folder}: not a folder", file=err)
105
+ return False
106
+ if not is_empty(folder) and not is_copy(folder):
107
+ print(f"stilo: {folder}: not a copy of the tutorial, and not empty: "
108
+ "choose another folder with --dir", file=err)
109
+ return False
110
+ try:
111
+ if reset and not is_empty(folder):
112
+ old = move_aside(folder)
113
+ print(f"Stilo: your old copy of the tutorial is now in {old}", file=out)
114
+ if is_empty(folder):
115
+ create_copy(folder)
116
+ print(f"Stilo: a new copy of the tutorial is in {folder}", file=out)
117
+ return True
118
+ except OSError as e:
119
+ print(f"stilo: {folder}: {e}", file=err)
120
+ return False
121
+ print(f"Stilo: your copy of the tutorial is in {folder}", file=out)
122
+ version, installed = copy_version(folder), stilo_version()
123
+ if is_older(version, installed):
124
+ print(f"Stilo: this copy was made by Stilo {version or '(unknown)'}, and Stilo "
125
+ f"{installed} may have changed lessons. To start again with the new "
126
+ f"lessons, run: stilo tutor --reset (your copy will be kept, moved aside)",
127
+ file=out)
128
+ return True
129
+
130
+
131
+ def tutor_arguments(parser):
132
+ parser.add_argument("--dir", type=Path, default=None,
133
+ help="folder of your copy of the tutorial (default: "
134
+ f"{default_folder()})")
135
+ parser.add_argument("--reset", action="store_true",
136
+ help="start again from a fresh copy; the old one is moved aside, not deleted")
137
+ parser.add_argument("--port", type=int, default=8000)
138
+ parser.add_argument("--no-browser", action="store_true",
139
+ help="do not open the browser")
140
+
141
+
142
+ def tutor(args) -> int:
143
+ """Copies the tutorial if needed, serves the copy and opens its index."""
144
+ folder = (args.dir or default_folder()).expanduser().resolve()
145
+ if not prepare(folder, args.reset):
146
+ return 1
147
+ host = "127.0.0.1"
148
+ url = f"http://{host}:{args.port}/{INDEX}"
149
+ print(f"Stilo: the tutorial is at {url} (press Ctrl+C here to stop)")
150
+ sys.stdout.flush()
151
+ run_server(folder, host, args.port, WEB_DIST, open_url=None if args.no_browser else url)
152
+ return 0
@@ -0,0 +1,37 @@
1
+ """Serving a folder with the web app, for `stilo serve` and `stilo tutor`."""
2
+
3
+ import threading
4
+ import time
5
+ import webbrowser
6
+ from pathlib import Path
7
+
8
+ import uvicorn
9
+
10
+ from stilo.server import create_app
11
+
12
+ # The built web app, `stilo/web`: written there by `npm run build` in a
13
+ # checkout, shipped there in the package
14
+ WEB_DIST = Path(__file__).resolve().parents[1] / "web"
15
+
16
+
17
+ def run_server(folder: Path, host: str, port: int, web: Path = WEB_DIST, open_url: str | None = None):
18
+ """Serves `folder` until the process is stopped. With `open_url`, opens
19
+ it in the browser once the server accepts connections. Ctrl+C stops it
20
+ with a goodbye instead of a traceback."""
21
+ server = uvicorn.Server(uvicorn.Config(create_app(folder, web), host=host, port=port))
22
+ if open_url:
23
+ threading.Thread(target=_open_when_started, args=(server, open_url), daemon=True).start()
24
+ try:
25
+ server.run()
26
+ except KeyboardInterrupt:
27
+ # uvicorn has already shut down cleanly; it re-raises the interrupt
28
+ # for its caller, and asyncio raises it out of a CancelledError
29
+ print("Stilo: stopped. Goodbye!")
30
+
31
+
32
+ def _open_when_started(server, url):
33
+ while not server.should_exit:
34
+ if server.started:
35
+ webbrowser.open(url)
36
+ return
37
+ time.sleep(0.1)
@@ -4,11 +4,13 @@ from __future__ import annotations
4
4
 
5
5
  import mimetypes
6
6
  from pathlib import Path
7
+ from urllib.parse import quote
7
8
 
8
9
  from fastapi import FastAPI, Query, Request
9
- from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, Response
10
+ from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, RedirectResponse, Response
10
11
  from fastapi.staticfiles import StaticFiles
11
12
 
13
+ from .home import has_home
12
14
  from .storage import BadRequest, Storage, StorageError
13
15
 
14
16
  TEXT = "text/plain; charset=utf-8"
@@ -44,14 +46,29 @@ def create_app(root: Path | str, web_dist: Path | str | None = None) -> FastAPI:
44
46
  """The server app for the documents under `root`. `web_dist` is the built
45
47
  web app (`stilo/web` in the CLI); without it, app pages show a notice."""
46
48
  storage = Storage(root)
47
- app = FastAPI(title="Stilo server", version="0.2.0")
49
+ app = FastAPI(title="Stilo server", version="0.4.0")
48
50
 
49
51
  @app.exception_handler(StorageError)
50
52
  async def storage_error(request: Request, error: StorageError):
51
53
  return JSONResponse({"error": str(error)}, status_code=error.status)
52
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
+
53
68
  @app.api_route("/_api/files/{path:path}", methods=["GET", "HEAD"])
54
- async def get_file(path: str):
69
+ async def get_file(path: str, request: Request):
70
+ if redirect := home_redirect("/_api/files/", path, request):
71
+ return redirect
55
72
  content, tag = storage.read(path)
56
73
  return Response(content, media_type=TEXT, headers={"ETag": tag, **NO_CACHE})
57
74
 
@@ -109,6 +126,8 @@ def create_app(root: Path | str, web_dist: Path | str | None = None) -> FastAPI:
109
126
  # root from ?root=); any other client (texl.import) gets the file itself.
110
127
  @app.api_route("/{path:path}", methods=["GET", "HEAD"], include_in_schema=False)
111
128
  async def page(path: str, request: Request):
129
+ if redirect := home_redirect("/", path, request):
130
+ return redirect
112
131
  vary = {"Vary": "Accept"}
113
132
  if storage.is_other_file(path):
114
133
  return other_file_response(path, *storage.read(path))
@@ -0,0 +1,72 @@
1
+ """The project home and the `~` segment of import paths (DECISIONS.md S10).
2
+
3
+ A project is a folder holding a manifest, `project.texl`. The home of a
4
+ folder is the nearest folder at or above it that holds one, or, without
5
+ one, the top: the highest folder the caller lets the search reach (the
6
+ served folder for the server; the user's home directory, or the file-system
7
+ root, for the CLI).
8
+
9
+ In a path, a segment `~` stands for the home of the folder before it. Texl
10
+ gives `~` no meaning, so an import of `~/lib/x.texl` from `/p/docs/a.texl`
11
+ asks for `/p/docs/~/lib/x.texl`; `expand_home` turns that into the real
12
+ path, one `~` at a time from the left. Several `~` occur naturally: a
13
+ library loaded as `.../~/lib/a/a.texl` that imports `~/lib/b/b.texl` asks
14
+ for `.../~/lib/a/~/lib/b/b.texl`, whose second `~` is the home of `lib/a`
15
+ (the library's own, if it has a manifest, else the project's).
16
+
17
+ Hosts give Texl the real path as the document's final URL (Texl 0.8): the
18
+ server redirects, the CLI's loader returns it. So a library is the document
19
+ at its real path, and a library importing itself through `~` asks again for
20
+ that path, an import cycle Texl ends. A path with more than `MAX_HOMES` `~`
21
+ segments is still refused, a safeguard for clients that keep the `~` URL
22
+ (`a/~/lib/x/~/lib/x/...` would grow at every turn).
23
+
24
+ Used by the server (`storage.py`) and by the CLI's file loader, so that
25
+ both resolve the same way. It reads the file system only to look for
26
+ manifests; validating the result is the caller's job.
27
+ """
28
+
29
+ from __future__ import annotations
30
+
31
+ from pathlib import Path, PurePath
32
+ from typing import Callable, Iterable
33
+
34
+ MANIFEST = "project.texl"
35
+ HOME = "~"
36
+ MAX_HOMES = 16
37
+
38
+
39
+ class HomeCycle(ValueError):
40
+ """A path with more `~` segments than any real chain of imports needs."""
41
+
42
+
43
+ def home_of(folder: Path, top: Path) -> Path:
44
+ """The nearest folder at or above `folder`, up to `top`, that holds a
45
+ manifest; `top` if none does. `folder` is expected inside `top`."""
46
+ for candidate in (folder, *folder.parents):
47
+ if (candidate / MANIFEST).is_file():
48
+ return candidate
49
+ if candidate == top:
50
+ break
51
+ return top
52
+
53
+
54
+ def expand_home(base: Path, segments: Iterable[str],
55
+ top_of: Callable[[Path], Path]) -> Path:
56
+ """The path of `segments` under `base`, with every `~` segment replaced,
57
+ from the left, by the home of the folder built so far. `top_of(folder)`
58
+ gives the highest folder the search for that folder's home may reach.
59
+ Raises `HomeCycle` beyond `MAX_HOMES` `~` segments."""
60
+ segments = list(segments)
61
+ if segments.count(HOME) > MAX_HOMES:
62
+ raise HomeCycle(f"more than {MAX_HOMES} {HOME} segments: an import cycle through {HOME}?")
63
+ current = base
64
+ for segment in segments:
65
+ current = home_of(current, top_of(current)) if segment == HOME else current / segment
66
+ return current
67
+
68
+
69
+ def has_home(path: str | PurePath) -> bool:
70
+ """Whether a path (a "/"-separated string or a path object) has a `~` segment."""
71
+ parts = path.parts if isinstance(path, PurePath) else str(path).split("/")
72
+ return HOME in parts