pylode 3.3.3__tar.gz → 3.3.4__tar.gz

{pylode-3.3.3 → pylode-3.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pylode
-Version: 3.3.3
+Version: 3.3.4
 Summary: An OWL ontology documentation tool using Python, based on LODE.
 Author: Nicholas Car
 Author-email: Nicholas Car <nick@kurrawong.ai>
@@ -17,11 +17,16 @@ Requires-Dist: markdown>=3.3.7,<4
 Requires-Dist: dominate>=2.6.0,<3
 Requires-Dist: html5lib>=1.1,<2
 Requires-Dist: httpx>=0.25.0,<1.0.0
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: bs4>=0.0.2 ; extra == 'server'
+Requires-Dist: falcon>=4.2.0 ; extra == 'server'
+Requires-Dist: validators>=0.35.0 ; extra == 'server'
 Requires-Python: >=3.9, <4
 Project-URL: Homepage, https://github.com/RDFLib/pyLODE
 Project-URL: Documentation, https://github.com/RDFLib/pyLODE
 Project-URL: Source, https://github.com/RDFLib/pyLODE
 Project-URL: Changelog, https://github.com/RDFLib/pyLODE/releases
+Provides-Extra: server
 Description-Content-Type: text/markdown
 
 ![pyLODE logo](https://rawcdn.githack.com/RDFLib/pyLODE/master/img/pyLODE-250.png)
@@ -114,13 +119,13 @@ optional arguments:
 
 ### Basic Use
 
-**As a Python script**
+#### As a Python script
 
 ```bash
 python pylode examples/ontpub/minimal.ttl -o minimal.html
 ```
 
-**As a Docker container**
+#### As a Docker container
 
 ```bash
 docker build -t pylode:latest .
@@ -133,9 +138,71 @@ docker run --mount 'type=bind,src=<ttl_directory>,target=/app/pylode/data' \
 
 > Note: `<ttl_directory>` must be absolute
 
+#### Via a stand-alone server
+
+The pyLODE server uses the popular [Falcon framework](https://falconframework.org/) to implement a lightweight web api.
+
+It can be run standalone as a single-thread, single process HTTP server, or more robustly as a WSGI application with
+[GUnicorn](https://gunicorn.org/).
+
+In all launch methods listed here, the server will be available at http://localhost:8000 for the landing page and http://localhost:8000/pylode for the active endpoint.
+
+The active endpoint accepts the following querystring parameters:
+
+* `url` for the absolute URL of the ontology document that you wish to render. The server hosting that ontology document must be capable of responding to Content Negotiation,
+i.e. it must supply RDF according to an HTTP `Accept` request for `text/turtle`, `application/rdf+xml` etc.
+* `profile` for the profile to use to generate HTML. Must be one of:
+    * `ontpub` (https://w3id.org/profile/ontpub) for ontologies. This is the default if no ``profile`` is provided.
+    * `vocpub` (https://w3id.org/profile/vocpub) for SKOS vocabularies
+    * `supermodel` for profiles of profiles
+* `sort` to indicate whether subjects should be sorted in the rendered output. Must be one of:
+    * `true` to sort the subjects (this is the default)
+    * `false` to NOT sort the subjects
+
+Here's an example of use with the [AGIF Ontology](https://linked.data.gov.au/def/agrif) using the source in this repository:
+
+```bash
+http://localhost:8000/pylode?url=https://raw.githubusercontent.com/RDFLib/pyLODE/refs/heads/master/examples/ontpub/agrif.ttl
+```
+
+The LODE responses generated by the server can be globally customised by setting the following optional environment variables:
+
+* `CSS_URL` can be set to the absolute URL of a CSS stylesheet hosted elsewhere that should be referenced by pyLODE documents
+* `FAVICON_URL` can be set to the absolute URL of a favicon image hosted elsewhere that should be referenced by pyLODE documents
+* `FAVICON_MIME` should be set to the MIME type of the resource at ``FAVICON_URL`` if that has been configured (e.g. ``image/png`)
+* `GTAGID` can be set to a Google Analytics Tag ID that you would like to use for tracking requests to your server.
+
+**Launch the pyLODE server standalone from your local directory:**
+
+You will need a few extra python modules installed locally:
+
+```
+pip install bs4 falcon validators
+```
+
+You can then run the pyLODE Server in standalone mode like this:
+
+```
+python -m pylode.server
+```
+
+**Build and run the docker image for the pyLODE Standalone Server:**
+
+```
+docker build --target=pylode-server -t pylode-server:latest .
+docker run --rm -p 8000:8000 pylode-server:latest
+```
+
+**Build and run the docker image for the pyLODE GUnicorn Server:**
+
+```
+docker build --target=pylode-gunicorn -t pylode-gunicorn:latest .
+docker run --rm -p 8000:8000 pylode-gunicorn:latest
+```
+
 ### Module Use
 
-**For OWL**
+#### For OWL
 
 ```python
 from pylode.profiles.ontpub import OntPub
@@ -145,7 +212,7 @@ html = od.make_html()
 od.make_html(destination="some-resulting-html-file.html")
 ```
 
-**For SKOS**
+#### For SKOS
 
 ```python
 from pylode.profiles.vocpub import VocPub
@@ -229,20 +296,12 @@ python -m pytest tests --disable-warnings
 
 ## Releases
 
-**Current release:** **3.2.3**
+Since version 3.0.1, we have moved to documenting releases in GitHub: https://github.com/RDFLib/pyLODE/releases
 
-### Release Schedule
+Older releasese
 
 | Version | Date             | Description                                                                     |
 |---------|------------------|---------------------------------------------------------------------------------|
-| 3.2.3   | 27 January 2026  | Updating dependencies & release procedure. Tidy testing cleanup                 |
-| 3.2.1   | 31 January 2025  | Fix version number in version.py                                                |
-| 3.2.0   | 27 July 2024     | dependency updates and merged multiple small PRs                                |
-| 3.1.4   | 6 April 2024     | Fix load_ontology function's detection of data input                            |
-| 3.1.3   | 18 March 2024    | Relax rdflib version constraint                                                 |
-| 3.1.2   | 18 March 2024    | Relax httpx version constraint                                                  |
-| 3.1.1   | 19 February 2024 | Fix release                                                                     |
-| 3.1.0   | 19 February 2024 | Add supermodel mode - supports documenting profiles and modules                 |
 | 3.0.5   | 27 April 2023    | Minor patching                                                                  |
 | 3.0.4   | 24 May 2022      | Use of Poetry                                                                   |
 | 3.0.2   | 24 May 2022      | Support for preformatted skos:example literals                                  |
@@ -284,25 +343,20 @@ But the very best thing you could do is create a Pull Request for us to action!
 **Author:**  
 Nicholas Car  
 *Data Architect*  
-[Kurrawong AI](https://kurrawong.ai)  
+[KurrawongAI](https://kurrawong.ai)  
 <nick@kurrawong.ai>
 
 ## Release Procedure
 
 1. tidy code: `$ task format`
 2. pass all tests: `$ task test`
-3. increment version number 
-    * in `pyproject.toml`
-    * in README.md, 'Current Release' & 'Release Schedule'
+3. increment version number in `pyproject.toml`
 4. commit all changes `$ git commit -a "..."`
 5. tag with version number: `$git tag ...`
 6. push changes `$ git push`
 7. push version `git push --tags`
-8. publish on PyPI: 
-    * `poetry build`
-    * `poetry publish -u __token__ -p {TOKEN}`
-9. make a GitHub release
-    * include `/dist` build artefacts
-10. increment version number to next release in `pyproject.toml`
-11. commit all changes `$ git commit -a "..."`
-12. push changes `$ git push`
+8make a GitHub release
+    * PyPI release is automated from this in `pypi.yml`
+9. increment version number to next release alpha in `pyproject.toml`
+10. commit all changes `$ git commit -a "..."`
+1push changes `$ git push`

{pylode-3.3.3 → pylode-3.3.4}/README.md

@@ -88,13 +88,13 @@ optional arguments:
 
 ### Basic Use
 
-**As a Python script**
+#### As a Python script
 
 ```bash
 python pylode examples/ontpub/minimal.ttl -o minimal.html
 ```
 
-**As a Docker container**
+#### As a Docker container
 
 ```bash
 docker build -t pylode:latest .
@@ -107,9 +107,71 @@ docker run --mount 'type=bind,src=<ttl_directory>,target=/app/pylode/data' \
 
 > Note: `<ttl_directory>` must be absolute
 
+#### Via a stand-alone server
+
+The pyLODE server uses the popular [Falcon framework](https://falconframework.org/) to implement a lightweight web api.
+
+It can be run standalone as a single-thread, single process HTTP server, or more robustly as a WSGI application with
+[GUnicorn](https://gunicorn.org/).
+
+In all launch methods listed here, the server will be available at http://localhost:8000 for the landing page and http://localhost:8000/pylode for the active endpoint.
+
+The active endpoint accepts the following querystring parameters:
+
+* `url` for the absolute URL of the ontology document that you wish to render. The server hosting that ontology document must be capable of responding to Content Negotiation,
+i.e. it must supply RDF according to an HTTP `Accept` request for `text/turtle`, `application/rdf+xml` etc.
+* `profile` for the profile to use to generate HTML. Must be one of:
+    * `ontpub` (https://w3id.org/profile/ontpub) for ontologies. This is the default if no ``profile`` is provided.
+    * `vocpub` (https://w3id.org/profile/vocpub) for SKOS vocabularies
+    * `supermodel` for profiles of profiles
+* `sort` to indicate whether subjects should be sorted in the rendered output. Must be one of:
+    * `true` to sort the subjects (this is the default)
+    * `false` to NOT sort the subjects
+
+Here's an example of use with the [AGIF Ontology](https://linked.data.gov.au/def/agrif) using the source in this repository:
+
+```bash
+http://localhost:8000/pylode?url=https://raw.githubusercontent.com/RDFLib/pyLODE/refs/heads/master/examples/ontpub/agrif.ttl
+```
+
+The LODE responses generated by the server can be globally customised by setting the following optional environment variables:
+
+* `CSS_URL` can be set to the absolute URL of a CSS stylesheet hosted elsewhere that should be referenced by pyLODE documents
+* `FAVICON_URL` can be set to the absolute URL of a favicon image hosted elsewhere that should be referenced by pyLODE documents
+* `FAVICON_MIME` should be set to the MIME type of the resource at ``FAVICON_URL`` if that has been configured (e.g. ``image/png`)
+* `GTAGID` can be set to a Google Analytics Tag ID that you would like to use for tracking requests to your server.
+
+**Launch the pyLODE server standalone from your local directory:**
+
+You will need a few extra python modules installed locally:
+
+```
+pip install bs4 falcon validators
+```
+
+You can then run the pyLODE Server in standalone mode like this:
+
+```
+python -m pylode.server
+```
+
+**Build and run the docker image for the pyLODE Standalone Server:**
+
+```
+docker build --target=pylode-server -t pylode-server:latest .
+docker run --rm -p 8000:8000 pylode-server:latest
+```
+
+**Build and run the docker image for the pyLODE GUnicorn Server:**
+
+```
+docker build --target=pylode-gunicorn -t pylode-gunicorn:latest .
+docker run --rm -p 8000:8000 pylode-gunicorn:latest
+```
+
 ### Module Use
 
-**For OWL**
+#### For OWL
 
 ```python
 from pylode.profiles.ontpub import OntPub
@@ -119,7 +181,7 @@ html = od.make_html()
 od.make_html(destination="some-resulting-html-file.html")
 ```
 
-**For SKOS**
+#### For SKOS
 
 ```python
 from pylode.profiles.vocpub import VocPub
@@ -203,20 +265,12 @@ python -m pytest tests --disable-warnings
 
 ## Releases
 
-**Current release:** **3.2.3**
+Since version 3.0.1, we have moved to documenting releases in GitHub: https://github.com/RDFLib/pyLODE/releases
 
-### Release Schedule
+Older releasese
 
 | Version | Date             | Description                                                                     |
 |---------|------------------|---------------------------------------------------------------------------------|
-| 3.2.3   | 27 January 2026  | Updating dependencies & release procedure. Tidy testing cleanup                 |
-| 3.2.1   | 31 January 2025  | Fix version number in version.py                                                |
-| 3.2.0   | 27 July 2024     | dependency updates and merged multiple small PRs                                |
-| 3.1.4   | 6 April 2024     | Fix load_ontology function's detection of data input                            |
-| 3.1.3   | 18 March 2024    | Relax rdflib version constraint                                                 |
-| 3.1.2   | 18 March 2024    | Relax httpx version constraint                                                  |
-| 3.1.1   | 19 February 2024 | Fix release                                                                     |
-| 3.1.0   | 19 February 2024 | Add supermodel mode - supports documenting profiles and modules                 |
 | 3.0.5   | 27 April 2023    | Minor patching                                                                  |
 | 3.0.4   | 24 May 2022      | Use of Poetry                                                                   |
 | 3.0.2   | 24 May 2022      | Support for preformatted skos:example literals                                  |
@@ -258,25 +312,20 @@ But the very best thing you could do is create a Pull Request for us to action!
 **Author:**  
 Nicholas Car  
 *Data Architect*  
-[Kurrawong AI](https://kurrawong.ai)  
+[KurrawongAI](https://kurrawong.ai)  
 <nick@kurrawong.ai>
 
 ## Release Procedure
 
 1. tidy code: `$ task format`
 2. pass all tests: `$ task test`
-3. increment version number 
-    * in `pyproject.toml`
-    * in README.md, 'Current Release' & 'Release Schedule'
+3. increment version number in `pyproject.toml`
 4. commit all changes `$ git commit -a "..."`
 5. tag with version number: `$git tag ...`
 6. push changes `$ git push`
 7. push version `git push --tags`
-8. publish on PyPI: 
-    * `poetry build`
-    * `poetry publish -u __token__ -p {TOKEN}`
-9. make a GitHub release
-    * include `/dist` build artefacts
-10. increment version number to next release in `pyproject.toml`
-11. commit all changes `$ git commit -a "..."`
-12. push changes `$ git push`
+8make a GitHub release
+    * PyPI release is automated from this in `pypi.yml`
+9. increment version number to next release alpha in `pyproject.toml`
+10. commit all changes `$ git commit -a "..."`
+1push changes `$ git push`

{pylode-3.3.3 → pylode-3.3.4}/pylode/profiles/ontpub.py

@@ -275,7 +275,7 @@ class OntPub:
     def _make_head(
         self, schema_org: Graph, include_css: bool = True, destination: Path = None
     ):
-        """Healper function for make_html(). Makes <head>???</head> content"""
+        """Helper function for make_html(). Makes <head>???</head> content"""
         with self.doc.head:
             # use standard pyLODE stylesheet
             if include_css:
@@ -312,7 +312,7 @@ class OntPub:
             )
 
     def _make_body(self):
-        """Healper function for make_html(). Makes <body>???</body> content.
+        """Helper function for make_html(). Makes <body>???</body> content.
 
         Just calls other helper functions in order"""
         make_pylode_logo(