pyLODE

An OWL ontology documentation tool using Python, based on LODE.

In addition to making web page, human-readable forms of ontologies, pyLODE encourages ontology annotation best practice by only producing good results for well documented inputs! pyLODE defines what it considers “well documented” in sections below, e.g. What pyLODE understands.

New mode: In v3.1.0, pyLODE now has a new mode called supermodel, in addition to the existing ontpub mode. This new mode allows for documenting profiles and modules of multipart models. See supermodel.md for more information.

---

A note on the v 3.x change

This is pyLODE version 3.0.1 and it’s vastly different from pyLODE 2.x. It doesn’t yet handle all the various “profiles” that pyLODE 2.13.2 does, such as SKOS “vocabularies” & Profiles Vocabulary “profiles”, it only handles OWL “ontologies”, nor all the special data types, such as JSON literals.

However, it generates HTML in a much more straightforward manner and the code is both more efficient and much more maintainable, which is why it’s been made.

v 3.x will eventually catch up to all of v 2.13.2’s features.

To access v 2.13.2 of pyLODE, either:

• Download it from PyPI
• Check it out from GitHub
• Access it via the online service

---

Contents

1. Quick Intro
2. Use
3. What pyLODE understands
4. Examples
5. Installation
6. Testing
7. Differences from LODE
8. Releases
9. License
10. Citation
11. Collaboration
12. Contacts

Quick Intro

The Live OWL Documentation Environment tool
(LODE) is a well-known (in Semantic Web circles) Java & XSLT-based tool used to generate human-readable HTML documents for OWL and RDF ontologies. That tool is now a bit dated and its online version is not always online.

This tool is a complete re-implementation of LODE’s functionality using Python and Python’s RDF manipulation module, rdflib. An ontology to be documented is parsed and inspected using rdflib and HTML is generated directly using Python’s dominate package.

Use

The tool can be used in multiple ways:

• BASH command line script
  • pyLODE.sh in bin/
• Windows EXE
  • pyLODE.exe in bin/
• Mac executable
  • pyLODE in bin/
• Python script
  • cli.py or module
• As-a-service locally
  • via the Falcon framework
  • see server.py
• As-a-service online
  • https://tools.kurrawong.ai/pylode

Command line arguments

usage: cli.py [-h] [-v] [-o OUTPUTFILE] [-c {true,false}] input

positional arguments:
    input                 Input file location or URL

optional arguments:
    -h, --help            show this help message and exit
    -v, --version         show program's version number and exit
    -o OUTPUTFILE,
    --outputfile OUTPUTFILE
                          Output file name (postfixed with .html if needed)
    -c {true,false},
    --css {true,false}
                          Include CSS in the output HTML

Basic Use

As a Python script

python pylode examples/ontpub/minimal.ttl -o minimal.html

As a Docker container

docker build -t pylode:latest .

docker run --mount 'type=bind,src=<ttl_directory>,target=/app/pylode/data' \
  pylode:latest python3.10 pylode/cli.py data/<ttl_file> -o data/<html_file>

Note: <ttl_directory> must be absolute

Module Use

For OWL

from pylode.profiles.ontpub import OntPub

od = OntPub(ontology="some-ontology-file.ttl")
html = od.make_html()
od.make_html(destination="some-resulting-html-file.html")

For SKOS

from pylode.profiles.vocpub import VocPub

od = VocPub(ontology="some-ontology-file.ttl")
html = od.make_html()
od.make_html(destination="some-resulting-html-file.html")

Examples

The examples/ directory contains multiple RDF & HTML pairs.

Rendered examples:

• minimal.html
• agift.html
• alternates.html
• asgs.html

What pyLODE understands

pyLODE understands definitional ontologies (owl:Ontology), classes, and properties.

Supported properties can be found in rdf_elements.py.

pyLODE deliberately does not translate everything in RDF to HTML, enforcing a conventional ontology documentation style. Support for new patterns can be requested via the issue tracker.

Notes on Agents

pyLODE supports simple and complex Agent objects, including ORCIDs, affiliations, and contact details.

<ontology_x>
    schema:creator [
        schema:name "Nicholas J. Car" ;
        schema:identifier <http://orcid.org/0000-0002-8742-7730> ;
        schema:email "nick@kurrawong.ai"^^xsd:anyURI ;
        schema:affiliation [
            schema:name "KurrawongAI" ;
            schema:url "https://kurrawong.ai"^^xsd:anyURI ;
        ] ;
    ] ;
.

Installation

pyLODE is available on PyPI:

pip install pylode

Testing

python -m pytest tests --disable-warnings

Differences from LODE

• command line access
  • you can use this on your own desktop so you don't need me to maintain a live service for use
• use of modern simple HTML
  • no JavaScript: pyLODE generates static HTML pages
• catering for a wider range of ontology options such as:
  • schema.org domainIncludes & rangeIncludes for properties
• better Agent representation
  • see the Notes on Agents section above
• smarter CURIES
  • pyLODE caches and looks up well-known prefixes to make more/better CURIES
  • it tries to be smart with CURIE presentation by CURIE-ising all URIs it finds, rather than printing them
• reference ontologies property labels
  • pyLODE caches ~ 10 well-known ontologies (RDFS, SKOS etc), properties from which people often use for their ontology documentation. Where these properties are used, the background ontology's labels are use
• active development
  • pyLODE has been under active development since mid-2019 and is still very much actively developed - it's not just staying still
  • it will be improved in foreseeable to cater for more and more things
  • recent ontology documentation initiatives such as the MOD Ontology will be handled, if requested

Releases

Current release: 3.2.3

Release Schedule

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
3.0.1	6 Jan 2022	Direct HTML generation using dominate; easier to maintain and extend
2.13.2	21 December 2021	Updated RDFlib to 6.1.1, improved test to properly use pytest
2.10.0	24 May 2021	Update Windows EXE build process, simplified versioning
2.9.1	28 Apr 2021	Support for ASCIIDOC format (OntDoc profile only)
2.8.11	28 Apr 2021	Further changes for PyPI only
2.8.10	27 Apr 2021	Further changes for PyPI only
2.8.9	27 Apr 2021	PyPI enhancements only
2.8.8	27 Apr 2021	Several small bugs fixed, auto-generation of version no. from Git tag
2.8.6	23 Feb 2021	Fixing char encoding issues, updated examples, new test files style - per issue
2.8.5	5 Jan 2021	Small enhancements to the Falcon server deployment option
2.8.3	3 July 2020	Packaging bugfixes only
2.7	1 July 2020	Much refactoring for new profile creation ease
2.6	15 June 2020	Supports PROF profiles as well as taxonomies & ontologies
2.4	27 May 2020	Small improvements over 2.0
2.0	18 Apr 2020	Includes multiple profiles - OWP & vocpub
1.0	15 Dec 2019	Initial working release

License

This code is licensed using the BSD 3-Clause licence. See the LICENSE file for the deed. Note Citation below though for attribution.

Citation

If you use pyLODE, please leave the pyLODE logo with a hyperlink back here in the top left of published HTML pages.

Collaboration

Contributions are welcome!

Please submit issues or pull requests via the issue tracker.

But the very best thing you could do is create a Pull Request for us to action!

Contacts

Author:
Nicholas Car
Data Architect
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'
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 artifacts
10. increment version number to next release in pyproject.toml
11. commit all changes $ git commit -a "..."
12. push changes $ git push