oc-lode 2.1.0__py3-none-any.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.
Files changed (79) hide show
  1. lode/__init__.py +2 -0
  2. lode/api.py +553 -0
  3. lode/builder.py +307 -0
  4. lode/cli.py +99 -0
  5. lode/exceptions.py +43 -0
  6. lode/helpers/__init__.py +1 -0
  7. lode/helpers/formats.py +32 -0
  8. lode/helpers/html_utils.py +32 -0
  9. lode/helpers/rdf.py +89 -0
  10. lode/helpers/spool.py +86 -0
  11. lode/models/__init__.py +38 -0
  12. lode/models/annotation.py +9 -0
  13. lode/models/atom.py +28 -0
  14. lode/models/attribute.py +13 -0
  15. lode/models/cardinality.py +29 -0
  16. lode/models/collection.py +29 -0
  17. lode/models/concept.py +156 -0
  18. lode/models/container.py +23 -0
  19. lode/models/datatype.py +9 -0
  20. lode/models/datatypeRestriction.py +28 -0
  21. lode/models/individual.py +40 -0
  22. lode/models/literal.py +40 -0
  23. lode/models/model.py +73 -0
  24. lode/models/oneOf.py +20 -0
  25. lode/models/property.py +96 -0
  26. lode/models/propertyConceptRestriction.py +37 -0
  27. lode/models/propertySelfRestriction.py +20 -0
  28. lode/models/quantifier.py +22 -0
  29. lode/models/relation.py +104 -0
  30. lode/models/resource.py +224 -0
  31. lode/models/restriction.py +10 -0
  32. lode/models/rule.py +27 -0
  33. lode/models/statement.py +49 -0
  34. lode/models/truthFunction.py +32 -0
  35. lode/models/value.py +28 -0
  36. lode/models/variable.py +9 -0
  37. lode/reader/README.md +215 -0
  38. lode/reader/__init__.py +16 -0
  39. lode/reader/config/base.yaml +201 -0
  40. lode/reader/config/owl.yaml +598 -0
  41. lode/reader/config/rdf.yaml +72 -0
  42. lode/reader/config/rdfs.yaml +69 -0
  43. lode/reader/config/skos.yaml +22 -0
  44. lode/reader/config_manager.py +295 -0
  45. lode/reader/loader.py +278 -0
  46. lode/reader/logic/__init__.py +15 -0
  47. lode/reader/logic/base_logic.py +892 -0
  48. lode/reader/logic/owl_logic.py +1104 -0
  49. lode/reader/logic/rdf_logic.py +253 -0
  50. lode/reader/logic/skos_logic.py +91 -0
  51. lode/reader/modules.py +229 -0
  52. lode/reader/provenance_graph.py +60 -0
  53. lode/reader/reader.py +292 -0
  54. lode/reader/security.py +221 -0
  55. lode/reader/warnings/__init__.py +15 -0
  56. lode/reader/warnings/owl_warnings.py +171 -0
  57. lode/static/style.css +1087 -0
  58. lode/templates/_card_owl.html +307 -0
  59. lode/templates/_card_skos.html +50 -0
  60. lode/templates/_toc_sidebar.html +95 -0
  61. lode/templates/_value.html +55 -0
  62. lode/templates/error.html +74 -0
  63. lode/templates/index.html +499 -0
  64. lode/templates/viewer.html +500 -0
  65. lode/viewer/__init__.py +28 -0
  66. lode/viewer/base_viewer.py +775 -0
  67. lode/viewer/config/model_annotations_deterministic_sorting.yaml +42 -0
  68. lode/viewer/config/owl_viewer.yaml +49 -0
  69. lode/viewer/config/rdf_viewer.yaml +39 -0
  70. lode/viewer/config/skos_viewer.yaml +17 -0
  71. lode/viewer/helpers.py +190 -0
  72. lode/viewer/owl_viewer.py +187 -0
  73. lode/viewer/rdf_viewer.py +8 -0
  74. lode/viewer/skos_viewer.py +172 -0
  75. oc_lode-2.1.0.dist-info/METADATA +169 -0
  76. oc_lode-2.1.0.dist-info/RECORD +79 -0
  77. oc_lode-2.1.0.dist-info/WHEEL +4 -0
  78. oc_lode-2.1.0.dist-info/entry_points.txt +2 -0
  79. oc_lode-2.1.0.dist-info/licenses/LICENSE.md +15 -0
lode/__init__.py ADDED
@@ -0,0 +1,2 @@
1
+ """LODE: Live OWL Documentation Environment, maintained by OpenCitations."""
2
+
lode/api.py ADDED
@@ -0,0 +1,553 @@
1
+ # lode/api.py
2
+ """LODE 2.0 — HTTP API.
3
+
4
+ Endpoints:
5
+ GET / web form
6
+ GET /health liveness probe
7
+ GET /extract render an artefact (HTML, or RDF via content negotiation)
8
+ POST /extract same, from an uploaded file
9
+ GET /build static documentation site, as a ZIP archive
10
+ POST /build same, from an uploaded file
11
+ """
12
+
13
+ # ==========================================================================
14
+ # 1. IMPORTS
15
+ # ==========================================================================
16
+ from pathlib import Path
17
+ from typing import Optional
18
+ from urllib.parse import urlencode
19
+ import hashlib
20
+ import logging
21
+ import os
22
+ import re
23
+ import shutil
24
+ import tempfile
25
+ import threading
26
+ import time
27
+ import traceback
28
+ from pathlib import Path
29
+
30
+ from fastapi import FastAPI, File, Form, HTTPException, Query, Request, UploadFile
31
+ from fastapi.responses import FileResponse, HTMLResponse, Response
32
+ from fastapi.staticfiles import StaticFiles
33
+ from fastapi.templating import Jinja2Templates
34
+ from starlette.background import BackgroundTask
35
+ from starlette.concurrency import run_in_threadpool
36
+ from starlette.middleware.gzip import GZipMiddleware
37
+ from uvicorn.middleware.proxy_headers import ProxyHeadersMiddleware
38
+
39
+ # Internal modules
40
+ from lode.helpers.formats import (
41
+ ENABLED_FORMATS, ReadAsFormat,
42
+ check_format_enabled as _check_format_enabled,
43
+ )
44
+ from lode.helpers.html_utils import minify as _minify
45
+ import lode.helpers.spool as spool
46
+ from lode.reader import Reader
47
+ from lode.reader import security
48
+ from lode.exceptions import LODEError, ArtefactValidationError
49
+ from lode.viewer.base_viewer import SERIALIZATION_FORMATS
50
+ from lode.reader.provenance_graph import ProvenanceGraph
51
+ from lode.helpers.rdf import iri_local_name
52
+
53
+
54
+ # ==========================================================================
55
+ # 2. APP SETUP
56
+ # ==========================================================================
57
+ LOG_LEVEL = os.getenv("LODE_LOG_LEVEL", "WARNING").strip().upper()
58
+
59
+ logging.basicConfig(
60
+ level=LOG_LEVEL,
61
+ format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
62
+ )
63
+ # Third-party loggers: silence per-request HTTP noise and URI warnings.
64
+ logging.getLogger("urllib3").setLevel(logging.WARNING)
65
+ logging.getLogger("rdflib").setLevel(logging.ERROR)
66
+ logger = logging.getLogger(__name__)
67
+
68
+ # When enabled, error pages include the full traceback (development only).
69
+ DEBUG = os.getenv("LODE_DEBUG", "").strip().lower() in ("1", "true", "yes", "on")
70
+
71
+ TAGS_METADATA = [
72
+ {"name": "extract", "description": "Render a semantic artefact as HTML or serialized RDF."},
73
+ {"name": "build", "description": "Generate a full static documentation site, delivered as a ZIP."},
74
+ {"name": "ops", "description": "Operational endpoints: web form and health probe."},
75
+ ]
76
+
77
+ app = FastAPI(
78
+ title="LODE 2.0 API",
79
+ version="0.3.12",
80
+ description="Live OWL Documentation Environment — extract and document "
81
+ "RDF/OWL/SKOS semantic artefacts as browsable HTML.",
82
+ license_info={"name": "ISC"},
83
+ contact={"name": "OpenCitations", "url": "https://github.com/opencitations/lode"},
84
+ openapi_tags=TAGS_METADATA,
85
+ )
86
+
87
+ # Compress HTML responses on the wire.
88
+ app.add_middleware(GZipMiddleware, minimum_size=1000)
89
+ # Fix "blocked loading mixed active content" on style.css behind a proxy.
90
+ app.add_middleware(ProxyHeadersMiddleware, trusted_hosts="*")
91
+
92
+ _PKG_DIR = Path(__file__).resolve().parent
93
+ templates = Jinja2Templates(directory=str(_PKG_DIR / "templates"))
94
+ app.mount("/static", StaticFiles(directory=str(_PKG_DIR / "static")), name="static")
95
+
96
+ # Beautify produced HTML.
97
+ templates.env.trim_blocks = True
98
+ templates.env.lstrip_blocks = True
99
+
100
+ # ==========================================================================
101
+ # 5. BUILD WORKSPACE — quota and concurrency for /build
102
+ # ==========================================================================
103
+ # Builds write hundreds of files each, so they get their own directory with an
104
+ # explicit budget instead of filling up /tmp.
105
+ BUILD_DIR = os.path.realpath(
106
+ os.getenv("LODE_BUILD_DIR", os.path.join(tempfile.gettempdir(), "lode-builds"))
107
+ )
108
+ os.makedirs(BUILD_DIR, exist_ok=True)
109
+ _BUILD_TTL = 30 * 60 # orphans (aborted downloads) age out
110
+ _BUILD_MAX_BYTES = 2 * 1024 ** 3 # 2 GB for all pending builds
111
+ _BUILD_SLOTS = threading.BoundedSemaphore(2) # concurrent builds, per worker process
112
+ _BUILD_WAIT = 5 # seconds a request waits for a slot
113
+
114
+
115
+ def _prune_builds() -> int:
116
+ """Drop orphaned build directories and return the bytes still in use.
117
+
118
+ A build is orphaned when its BackgroundTask never fired, i.e. the client
119
+ opened the connection and never finished reading the archive.
120
+ """
121
+ cutoff = time.time() - _BUILD_TTL
122
+ total = 0
123
+ for name in os.listdir(BUILD_DIR):
124
+ p = os.path.join(BUILD_DIR, name)
125
+ try:
126
+ st = os.stat(p)
127
+ except OSError:
128
+ continue
129
+ if st.st_mtime < cutoff:
130
+ shutil.rmtree(p, ignore_errors=True)
131
+ continue
132
+ for root, _, files in os.walk(p):
133
+ for f in files:
134
+ try:
135
+ total += os.path.getsize(os.path.join(root, f))
136
+ except OSError:
137
+ pass
138
+ return total
139
+
140
+
141
+ # ==========================================================================
142
+ # 6. HTML HELPERS
143
+ # ==========================================================================
144
+
145
+ def _nav_qs(read_as: str, url, upload_id, lang, imported, closure, partial_import) -> str:
146
+ """Build the query string that keeps the current view parameters in navigation links.
147
+
148
+ Exactly one of `upload_id` and `url` is emitted, so a link never mixes the two
149
+ sources. Boolean options are included only when enabled.
150
+ """
151
+ p = {"read_as": read_as, "lang": lang or ""}
152
+ p["upload_id" if upload_id else "url"] = upload_id or (url or "")
153
+ if imported:
154
+ p["imported"] = "true"
155
+ if closure:
156
+ p["closure"] = "true"
157
+ if partial_import:
158
+ p["partial_import"] = "true"
159
+
160
+ return urlencode(p)
161
+
162
+ def _render_view(request, reader, *, resource, lang, source_url, upload_id, read_as,
163
+ imported=None, closure=None, partial_import=None):
164
+ """Render one resource (or the whole artefact) as the minified viewer page.
165
+
166
+ The body is minified after rendering, so Content-Length is recomputed:
167
+ keeping the old value would truncate the response.
168
+ """
169
+ viewer = reader.get_viewer()
170
+ data = viewer.get_view_data(resource_uri=resource, language=lang)
171
+ data["warnings"] = viewer.format_warnings(reader.get_warnings())
172
+ resp = templates.TemplateResponse(request, "viewer.html", {
173
+ "source_url": source_url,
174
+ "upload_id": upload_id,
175
+ "nav_qs": _nav_qs(read_as, source_url, upload_id, lang, imported, closure, partial_import),
176
+ **data,
177
+ })
178
+ resp.body = _minify(resp.body.decode("utf-8")).encode("utf-8")
179
+ resp.headers["content-length"] = str(len(resp.body))
180
+ return resp
181
+
182
+
183
+ # ==========================================================================
184
+ # 7. READER RESOLUTION
185
+ # ==========================================================================
186
+ def _url_token(url, read_as, imported, closure, partial_import) -> str:
187
+ """Return the stable cache key for a URL and its load options.
188
+
189
+ Every option that changes the loaded graph is part of the key, so two
190
+ requests share a cached copy only if they would produce the same result.
191
+ """
192
+ key =f"{url}|{read_as}|{imported}|{closure}|{partial_import}".encode()
193
+ return "url_" + hashlib.sha256(key).hexdigest()[:32]
194
+
195
+
196
+ def _load_url(url, read_as, imported, closure, partial_import, warnings, use_cache=True):
197
+ """Load an artefact from a URL, through the disk cache when allowed.
198
+
199
+ The URL is validated first (SSRF protection). Only the main document is
200
+ cached: modules (imports, closure) are re-applied on every hit, so the cache
201
+ never goes stale on remote ontologies. Blocking: network and disk I/O.
202
+ """
203
+ # Enforce http(s)://host up front: a non-URL value (local path, file://, ...)
204
+ # must never reach the loader and be opened as a local file.
205
+ security.check_url_safe(url)
206
+ spool.prune()
207
+ token = _url_token(url, read_as, imported, closure, partial_import)
208
+ path = spool.get_path(token)
209
+ if use_cache and os.path.exists(path):
210
+ # cache hit: rebuild from the saved Turtle
211
+ reader = Reader()
212
+ reader.load_instances(path, read_as, imported=imported, closure=closure, partial_import=partial_import,
213
+ warnings=warnings, source_name=url)
214
+ return reader
215
+ if not use_cache:
216
+ # cache=false: drop the stale copy so the fresh fetch replaces it
217
+ try:
218
+ os.unlink(path)
219
+ except OSError:
220
+ pass
221
+ # cache miss (or forced refresh): fetch and process the URL
222
+ reader = Reader()
223
+ reader.load_instances(url, read_as, imported=imported, closure=closure, partial_import=partial_import,
224
+ warnings=warnings)
225
+ # persist ONLY the main document: modules are re-applied on every hit.
226
+ try:
227
+ g = reader._graph
228
+ main = g.graph(reader._ontology_iri) if isinstance(g, ProvenanceGraph) else g
229
+ with open(path, "wb") as f:
230
+ f.write(main.serialize(format="turtle").encode("utf-8"))
231
+ except OSError:
232
+ pass
233
+ return reader
234
+
235
+ def _resolve_reader(read_as: str, url, upload_id, imported, closure, partial_import, warnings,
236
+ use_cache=True):
237
+ """Build a Reader from an uploaded file or from a URL.
238
+
239
+ Raises ArtefactValidationError when the upload has expired or when neither
240
+ source is given. Uploads win over URLs and are never re-fetched.
241
+ """
242
+ if upload_id:
243
+ # Uploads are not re-fetched, so the cache flag does not apply to them.
244
+ path = spool.get_path(upload_id)
245
+ if not os.path.exists(path):
246
+ raise ArtefactValidationError("Upload expired, please re-upload",
247
+ context={"upload_id": upload_id})
248
+ reader = Reader()
249
+ reader.load_instances(path, read_as, imported=imported, closure=closure, partial_import=partial_import,
250
+ warnings=warnings)
251
+ return reader
252
+ if url:
253
+ return _load_url(url, read_as, imported, closure, partial_import, warnings, use_cache=use_cache)
254
+ raise ArtefactValidationError("Missing 'url' or 'upload_id'")
255
+
256
+
257
+ async def _read_validated_upload(file: UploadFile) -> bytes:
258
+ """Run every upload check in one place, then return the raw bytes."""
259
+ security.check_extension(file.filename)
260
+ content = await security.read_upload_capped(file)
261
+ security.check_is_text(content)
262
+ security.check_safe_xml(content.decode("utf-8-sig"))
263
+ return content
264
+
265
+
266
+ # ==========================================================================
267
+ # 8. ZIP BUILD HELPERS
268
+ # ==========================================================================
269
+ def _slug(name: Optional[str]) -> str:
270
+ """Safe directory/file stem derived from a URL or filename.
271
+
272
+ Must never yield '.' or '..': those would let make_archive(base_dir=...)
273
+ escape the build directory and archive its parent.
274
+ """
275
+ if not name:
276
+ return "ontology"
277
+ raw = name.rstrip("/").split("#")[0].split("/")[-1]
278
+ raw = re.sub(r"\.(ttl|rdf|owl|n3|nt|jsonld|xml)$", "", raw, flags=re.I)
279
+ raw = re.sub(r"[^A-Za-z0-9._-]", "-", raw).strip("-.")
280
+ if not raw or raw in {".", ".."}:
281
+ return "ontology"
282
+ return raw[:64]
283
+
284
+
285
+ def _zip_response(reader, slug: str, lang: Optional[str] = None) -> FileResponse:
286
+ """Render the whole static site and return it as a ZIP download.
287
+
288
+ Blocking and disk-heavy: callers must keep it off the event loop.
289
+ """
290
+ from lode.builder import build_html # lazy: avoids a circular import
291
+
292
+ if not _BUILD_SLOTS.acquire(timeout=_BUILD_WAIT):
293
+ raise HTTPException(503, "Server busy: too many concurrent builds",
294
+ headers={"Retry-After": "30"})
295
+ workdir = None
296
+ try:
297
+ if _prune_builds() > _BUILD_MAX_BYTES:
298
+ raise HTTPException(503, "Build storage full, retry shortly",
299
+ headers={"Retry-After": "60"})
300
+
301
+ workdir = tempfile.mkdtemp(prefix="build_", dir=BUILD_DIR)
302
+ site_dir = Path(workdir) / slug
303
+ site_dir.mkdir(parents=True, exist_ok=True)
304
+
305
+ build_html(reader.get_viewer(), site_dir, lang=lang or "en", reader=reader)
306
+
307
+ zip_path = shutil.make_archive(
308
+ os.path.join(workdir, f"{slug}-lode"), "zip",
309
+ root_dir=workdir, base_dir=slug,
310
+ )
311
+ # The loose pages are redundant once archived: halve the disk peak.
312
+ shutil.rmtree(site_dir, ignore_errors=True)
313
+ except BaseException:
314
+ if workdir:
315
+ shutil.rmtree(workdir, ignore_errors=True)
316
+ raise
317
+ finally:
318
+ # Free the slot as soon as the build ends, not when the client is done
319
+ # downloading: a slow reader must not hold a build slot hostage.
320
+ _BUILD_SLOTS.release()
321
+
322
+ return FileResponse(
323
+ zip_path,
324
+ media_type="application/zip",
325
+ filename=f"{slug}-lode.zip",
326
+ background=BackgroundTask(shutil.rmtree, workdir, True),
327
+ )
328
+
329
+
330
+ # ==========================================================================
331
+ # 9. ERROR RENDERING
332
+ # ==========================================================================
333
+ def _error_payload(exc: Exception) -> dict:
334
+ """Build the dict used by error.html for any exception.
335
+
336
+ The traceback is included only for non-LODE errors and only when LODE_DEBUG
337
+ is set: it is always logged server-side and never shown to users otherwise.
338
+ """
339
+ is_lode = isinstance(exc, LODEError)
340
+ return {
341
+ "type": type(exc).__name__,
342
+ "message": str(exc),
343
+ "context": exc.context if is_lode else {},
344
+ "request_id": exc.request_id if is_lode else None,
345
+ # Never leak the traceback to the user in production: it is always logged
346
+ # server-side; it is only surfaced in the page when LODE_DEBUG is set.
347
+ "traceback": traceback.format_exc() if (not is_lode and DEBUG) else None,
348
+ }
349
+
350
+
351
+ @app.exception_handler(LODEError)
352
+ async def lode_error_handler(request: Request, exc: LODEError):
353
+ """Show a domain error (LODEError) as an HTML page with HTTP 400."""
354
+ logger.error(f"{type(exc).__name__}: {exc}")
355
+ return templates.TemplateResponse(
356
+ "error.html", {"request": request, "error": _error_payload(exc)}, status_code=400
357
+ )
358
+
359
+
360
+ @app.exception_handler(Exception)
361
+ async def unexpected_error_handler(request: Request, exc: Exception):
362
+ """Show an unhandled exception as an HTML page with HTTP 500.
363
+
364
+ The full traceback goes to the server log; the page shows it only in debug mode.
365
+ """
366
+ logger.exception("Unexpected error")
367
+ return templates.TemplateResponse(
368
+ "error.html", {"request": request, "error": _error_payload(exc)}, status_code=500
369
+ )
370
+
371
+
372
+ # ==========================================================================
373
+ # 10. MIDDLEWARE
374
+ # ==========================================================================
375
+ @app.middleware("http")
376
+ async def limit_upload_size(request: Request, call_next):
377
+ """Reject oversized POST bodies early, before reading them, when the client
378
+ declares a Content-Length. (Chunked bodies omit it: those are still capped
379
+ in read_upload_capped; the hard limit belongs at the reverse proxy.)"""
380
+ if request.method == "POST":
381
+ declared = request.headers.get("content-length")
382
+ if declared and declared.isdigit() and int(declared) > security.MAX_BYTES:
383
+ exc = ArtefactValidationError(
384
+ "File too large",
385
+ context={"bytes": int(declared), "max": security.MAX_BYTES},
386
+ )
387
+ return templates.TemplateResponse(
388
+ "error.html", {"request": request, "error": _error_payload(exc)},
389
+ status_code=400,
390
+ )
391
+ return await call_next(request)
392
+
393
+
394
+ # ==========================================================================
395
+ # 11. ROUTES — pages
396
+ # ==========================================================================
397
+ @app.get("/", response_class=HTMLResponse, tags=["ops"], summary="Web input form")
398
+ async def input_web_interface(request: Request):
399
+ """Serve the HTML input form, the entry point of the web interface."""
400
+ return templates.TemplateResponse(request, "index.html", {
401
+ "formats": [format.value for format in ReadAsFormat],
402
+ "enabled_formats": sorted(ENABLED_FORMATS),
403
+ })
404
+
405
+
406
+ @app.get("/health", tags=["ops"], summary="Liveness probe")
407
+ async def health_check():
408
+ """Return 200 with a fixed body. Used by Docker/K8s readiness checks."""
409
+ return {"status": "ok"}
410
+
411
+
412
+ # ==========================================================================
413
+ # 12. ROUTES — /extract
414
+ # ==========================================================================
415
+ @app.get("/extract", tags=["extract"], summary="Render an artefact as HTML or RDF")
416
+ def extract_get(
417
+ request: Request,
418
+ read_as: ReadAsFormat = Query(description="Read the source as this artefact type"),
419
+ url: Optional[str] = Query(None, description="Public http(s) URL of the artefact"),
420
+ upload_id: Optional[str] = Query(None, description="Token of a previously uploaded file"),
421
+ resource: Optional[str] = Query(None, description="IRI of a single resource; omit for the whole ontology"),
422
+ lang: Optional[str] = Query(None, description="Language tag for labels, e.g. 'en', 'it'"),
423
+ imported: Optional[bool] = Query(None, description="Also load owl:imports (depth 1)"),
424
+ closure: Optional[bool] = Query(None, description="Load the full owl:imports closure"),
425
+ partial_import: Optional[bool] = Query(None, description="Additionally load only explicitly mentioned entities from other ontologies"),
426
+ format: Optional[str] = Query(None, description="Force a serialization (ttl, rdf, jsonld…) instead of HTML"),
427
+ warnings: bool = Query(False, description="Collect and show reader warnings"),
428
+ cache: bool = Query(True, description="Use the disk cache for fetched URLs"),
429
+ ):
430
+ """Render an artefact. Returns HTML by default, or RDF when a serialization
431
+ is requested via the `format` query or the `Accept` header."""
432
+ _check_format_enabled(read_as)
433
+
434
+ reader = _resolve_reader(read_as.value, url, upload_id, imported, closure, partial_import,
435
+ warnings, use_cache=cache)
436
+
437
+ # Content negotiation: triples of the loaded artefact only, quads are never negotiable
438
+ accept = request.headers.get("accept", "text/html")
439
+ available = SERIALIZATION_FORMATS
440
+ serial = None
441
+
442
+ if format:
443
+ fmt_l = format.lower()
444
+ serial = next((f for f in available if f["ext"] == fmt_l), None)
445
+ if serial is None:
446
+ raise HTTPException(406, f"Format '{format}' not available for this request")
447
+ else:
448
+ for part in accept.split(","):
449
+ mime = part.split(";", 1)[0].strip()
450
+ serial = next((f for f in available if f["mime"] == mime), None)
451
+ if serial:
452
+ break
453
+
454
+ if serial:
455
+ if resource:
456
+ serialized = reader.get_viewer().export_resource(resource, serial["fmt"])
457
+ filename = iri_local_name(resource) or "resource"
458
+ else:
459
+ serialized = reader.get_main_graph().serialize(format=serial["fmt"])
460
+ filename = (iri_local_name(url) if url else "") or "graph"
461
+ return Response(content=serialized, media_type=serial["mime"],
462
+ headers={"Content-Disposition": f'inline; filename="{filename}.{serial["ext"]}"'})
463
+
464
+ logger.info("=== REQUEST SUCCESS ===")
465
+ return _render_view(request, reader, resource=resource, lang=lang,
466
+ source_url=url, upload_id=upload_id, read_as=read_as.value,
467
+ imported=imported, closure=closure, partial_import=partial_import)
468
+
469
+
470
+ @app.post("/extract", response_class=HTMLResponse, tags=["extract"],
471
+ summary="Render an uploaded artefact as HTML")
472
+ async def extract_post(
473
+ request: Request,
474
+ read_as: ReadAsFormat = Form(..., description="Read the uploaded file as this artefact type"),
475
+ file: UploadFile = File(..., description="The artefact file (ttl, rdf, owl…)"),
476
+ resource: Optional[str] = Form(None, description="IRI of a single resource; omit for the whole ontology"),
477
+ lang: Optional[str] = Form(None, description="Language tag for labels, e.g. 'en', 'it'"),
478
+ imported: Optional[bool] = Form(None, description="Also load owl:imports (depth 1)"),
479
+ partial_import: Optional[bool] = Form(None, description="Additionally load only explicitly mentioned entities from other ontologies"),
480
+ closure: Optional[bool] = Form(None, description="Load the full owl:imports closure"),
481
+ warnings: bool = Form(False, description="Collect and show reader warnings"),
482
+ ):
483
+ """Render an artefact from an uploaded file instead of a URL."""
484
+ logger.info("=== FILE UPLOAD START ===")
485
+ logger.info(f"Filename: {file.filename}")
486
+ logger.info(f"Format: {read_as.value}")
487
+
488
+ _check_format_enabled(read_as)
489
+ content = await _read_validated_upload(file)
490
+ token = spool.save(content)
491
+
492
+ reader = Reader()
493
+ await run_in_threadpool(
494
+ reader.load_instances, spool.get_path(token), read_as.value,
495
+ imported=imported, closure=closure, partial_import=partial_import, warnings=warnings,
496
+ )
497
+ return _render_view(request, reader, resource=resource, lang=lang,
498
+ source_url=None, upload_id=token, read_as=read_as.value,
499
+ imported=imported, closure=closure, partial_import=partial_import)
500
+
501
+
502
+ # ==========================================================================
503
+ # 13. ROUTES — /build
504
+ # ==========================================================================
505
+ @app.get("/build", tags=["build"], summary="Build a static site (ZIP) from a URL")
506
+ def build_get(
507
+ read_as: ReadAsFormat = Query(description="Read the source as this artefact type"),
508
+ url: Optional[str] = Query(None, description="Public http(s) URL of the artefact"),
509
+ upload_id: Optional[str] = Query(None, description="Token of a previously uploaded file"),
510
+ lang: Optional[str] = Query(None, description="Language tag for labels, e.g. 'en', 'it'"),
511
+ imported: Optional[bool] = Query(None, description="Also load owl:imports (depth 1)"),
512
+ closure: Optional[bool] = Query(None, description="Load the full owl:imports closure"),
513
+ partial_import: Optional[bool] = Query(None, description="Additionally load only explicitly mentioned entities from other ontologies"),
514
+ warnings: bool = Query(False, description="Collect and show reader warnings"),
515
+ cache: bool = Query(True, description="Use the disk cache for fetched URLs"),
516
+ ):
517
+ """Static documentation site as a ZIP. Sync on purpose: FastAPI runs
518
+ non-async endpoints in the threadpool, keeping the event loop free."""
519
+ _check_format_enabled(read_as)
520
+ reader = _resolve_reader(read_as.value, url, upload_id, imported, closure, partial_import,
521
+ warnings, use_cache=cache)
522
+ return _zip_response(reader, _slug(url), lang)
523
+
524
+
525
+ @app.post("/build", tags=["build"], summary="Build a static site (ZIP) from an upload")
526
+ async def build_post(
527
+ read_as: ReadAsFormat = Form(..., description="Read the uploaded file as this artefact type"),
528
+ file: UploadFile = File(..., description="The artefact file (ttl, rdf, owl…)"),
529
+ lang: Optional[str] = Form(None, description="Language tag for labels, e.g. 'en', 'it'"),
530
+ imported: Optional[bool] = Form(None, description="Also load owl:imports (depth 1)"),
531
+ closure: Optional[bool] = Form(None, description="Load the full owl:imports closure"),
532
+ partial_import: Optional[bool] = Form(None, description="Additionally load only explicitly mentioned entities from other ontologies"),
533
+ warnings: bool = Form(False, description="Collect and show reader warnings"),
534
+ ):
535
+ """Build the static site from an uploaded file instead of a URL."""
536
+ _check_format_enabled(read_as)
537
+ content = await _read_validated_upload(file)
538
+ token = spool.save(content)
539
+
540
+ reader = Reader()
541
+ await run_in_threadpool(
542
+ reader.load_instances, spool.get_path(token), read_as.value,
543
+ imported=imported, closure=closure, partial_import=partial_import, warnings=warnings,
544
+ )
545
+ return await run_in_threadpool(_zip_response, reader, _slug(file.filename), lang)
546
+
547
+
548
+ # ==========================================================================
549
+ # 14. ENTRY POINT
550
+ # ==========================================================================
551
+ if __name__ == "__main__":
552
+ import uvicorn
553
+ uvicorn.run(app, host="0.0.0.0", port=8000)