pylode 2.12.0__tar.gz → 3.0.0__tar.gz

{pyLODE-2.12.0 → pyLODE-3.0.0}/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2019-2021, Nicholas J. Car
+Copyright (c) 2002-2021, RDFLib Team
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

pyLODE-3.0.0/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.1
+Name: pyLODE
+Version: 3.0.0
+Summary: An OWL ontology documentation tool using Python and templating, based on LODE.
+Home-page: https://github.com/rdflib/pyLODE
+Author: Nicholas J. Car
+Author-email: nicholas.car@surroundaustralia.com
+License: LICENSE
+Download-URL: https://github.com/RDFLib/pyLODE/releases/tag/3.0.0
+Project-URL: Bug Reports, https://github.com/rdflib/pyLODE/issues
+Project-URL: Source, https://github.com/rdflib/pyLODE/
+Keywords: Semantic Web,OWL,ontology,template,HTML,documentation
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+
+.. image:: https://rawcdn.githack.com/RDFLib/pyLODE/b1ff1b1e19262cdc21ee28c7362b1690ca18e30b/img/pyLODE-250.png
+
+.. image:: https://badge.fury.io/py/pyLODE.svg
+    :target: https://badge.fury.io/py/pyLODE
+
+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`_.
+
+.. note::
+
+    This is pyLODE version 3.0.0 and it's vastly different from pyLODE < 3.0.0. 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, BUT, 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 <https://pypi.org/project/pyLODE/2.13.2/>`_, `check it out from GitHub <https://github.com/RDFLib/pyLODE/releases/tag/2.13.2>`_ or access it via the `online service <http://pylode.surroundaustralia.com/>`_.
+
+
+Contents
+========
+1. `Quick Intro`_
+2. Use_
+3. `What pyLODE understands`_
+4. Examples_
+5. Installation_
+6. `Differences from LODE`_
+7. `Releases`_
+8. License_
+9. Citation_
+10. Collaboration_
+11. Contacts_
+
+
+Quick Intro
+===========
+The Live OWL Documentation Environment tool
+(`LODE <https://github.com/essepuntato/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 (old-style HTML, use of older technologies like XSLT)
+and it's (`online version <https://www.essepuntato.it/lode>`__) is not always
+online.
+
+This tool is a complete re-implementation of LODE's functionality using
+Python and Python's RDF manipulation module,
+`rdflib <https://pypi.org/project/rdflib/>`__. An ontology to be
+documented is parsed and inspected using rdflib and HTML is generated
+directly, using Python's `dominate <https://pypi.org/project/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 popular `Falcon framework <https://falconframework.org/>`__.
+    - see server.py in the main folder
+- as-a-service online
+    - hosted at https://pylode.surroundaustralia.com
+
+Command line arguments
+----------------------
+
+The BASH, Windows EXE and Python Script methods all use the same 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
+                            A name you wish to assign to the output file. Will be
+                            postfixed with .html if not already added. If no
+                            output file is given, output will be printed to screen
+        -c {true,false},
+        --css {true,false}
+                            Whether (true) or not (false) to include CSS within an
+                            output HTML file.
+
+Basic Use
+^^^^^^^^^
+
+* as a Python script
+* executed in this directory
+
+::
+
+    python pylode examples/minimal.ttl -o minimal.html
+
+This will produce the file ``minimal.html`` in this directory which should
+match exactly the file ``examples/minimal.html``.
+
+
+Examples
+========
+
+The `examples/ directory <https://github.com/RDFLib/pyLODE/tree/master/examples>`_
+contains multiple pairs of RDF & HTML files generated from them using this
+version of pyLODE.
+
+You can also see rendered versions of these example files online too:
+
+* `minimal.html <http://rdflib.dev/pyLODE/examples/ontdoc/minimal.html>`_
+* `agift.html <http://rdflib.dev/pyLODE/examples/ontdoc/agift.html>`_
+* `alternates.html <http://rdflib.dev/pyLODE/examples/ontdoc/alternates.html>`_
+* `asgs.html <http://rdflib.dev/pyLODE/examples/ontdoc/asgs.html>`_
+
+
+What pyLODE understands
+=======================
+
+pyLODE knows about definitional ontologies (``owl:Ontology``) and the major
+elements usually fount in them, such as classes (``owl:Class`` or ``rdf:Class)
+and properties (``rdf:Property`` & ``owl:ObjectProperty`` etc.).
+
+To see what properties for ontology, class and RDF property documentation
+pyLODE currently supports, just look in the ``rdf_elements.py`` file. All
+elements' properties supported are given in property lists there.
+
+pyLODES won't just translate everything that you can describe in RDF into
+HTML! This is a conscious design choice to ensure that a certain conventional
+style of documented ontology is produced. However, surrport for new
+properties and ontology patterns can be made - just create an Issue on
+`this project's Issue tracker <https://github.com/RDFLib/pyLODE/issues>`__.
+
+While it *does* know about instance data, such as Named Individuals, it's
+not really designed to document large ontologies containing class instances.
+
+Notes on Agents
+---------------
+pyLODE can understand both simple and complex Agent objects. You can use
+simple string properties like ``dc:contributor "Nicholas J. Car"`` too if
+you really must but better would be to take advantage of real Linked Data
+representation, e.g. complex Agent objects with web addresses, emails,
+affiliations, ORCIDs and so on, e.g.:
+
+::
+
+    <ontology_x>
+        dct:creator [
+            sdo:name "Nicholas J. Car" ;
+            sdo:identifier <http://orcid.org/0000-0002-8742-7730> ;
+            sdo:affiliation [
+                sdo:name "SURROUND Australia Pty Ldt." ;
+                sdo:url "https://surroundaustralia.com"^^xsd:anyURI ;
+            ] ;
+        ] ;
+
+See all the properties in ``rdf_elements.py:AGENT_PROPS`` for a list of
+all the Agent properties pyLODE can handle.
+
+Installation
+============
+
+pyLODE is `on PyPI <https://pypi.org/project/pyLODE/>`_, so you can install
+it using `pip <https://pypi.org/project/pip/>`_ as normal:
+
+::
+
+    pip install pylode
+
+
+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 <https://github.com/sifrproject/MOD-Ontology>`__ will be
+      handled, if requested
+
+
+Releases
+========
+pyLODE is under continual and constant development. The current developers have a roadmap for enhancements in mind,
+which is given here, however, since this is an open source project, new developers may join the pyLODE dev community
+and change/add development priorities.
+
+Current Release
+---------------
+
+The current release, as of December, 2021, is **2.13.2**.
+
+Release Schedule
+----------------
+
+.. csv-table:: **pyLODE Release Schedule**
+   :header: "Version", "Date", "Description"
+   :widths: 15, 10, 30
+
+   **3.0.0**, **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 20201, "Fixing char encoding issues, updated examples, new test files style - per issue"
+   2.8.5, 5 Jan 20201, "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, 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 <LICENSE>`_ 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
+=============
+The maintainers welcome any collaboration.
+
+If you have suggestions, please email the contacts below or leave Issues
+in this repository's `Issue tracker <https://github.com/rdflib/pyLODE/issues>`_.
+
+But the very best thing you could do is create a Pull Request for us to
+action!
+
+
+Contacts
+========
+| *Author*:
+| **Nicholas Car**
+| *Data System Architect*
+| `SURROUND Australia Pty Ltd <https://surroundaustralia.com>`_
+| nicholas.car@surroundaustralia.com
+
+

pyLODE-3.0.0/README.rst

@@ -0,0 +1,287 @@
+.. image:: https://rawcdn.githack.com/RDFLib/pyLODE/b1ff1b1e19262cdc21ee28c7362b1690ca18e30b/img/pyLODE-250.png
+
+.. image:: https://badge.fury.io/py/pyLODE.svg
+    :target: https://badge.fury.io/py/pyLODE
+
+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`_.
+
+.. note::
+
+    This is pyLODE version 3.0.0 and it's vastly different from pyLODE < 3.0.0. 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, BUT, 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 <https://pypi.org/project/pyLODE/2.13.2/>`_, `check it out from GitHub <https://github.com/RDFLib/pyLODE/releases/tag/2.13.2>`_ or access it via the `online service <http://pylode.surroundaustralia.com/>`_.
+
+
+Contents
+========
+1. `Quick Intro`_
+2. Use_
+3. `What pyLODE understands`_
+4. Examples_
+5. Installation_
+6. `Differences from LODE`_
+7. `Releases`_
+8. License_
+9. Citation_
+10. Collaboration_
+11. Contacts_
+
+
+Quick Intro
+===========
+The Live OWL Documentation Environment tool
+(`LODE <https://github.com/essepuntato/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 (old-style HTML, use of older technologies like XSLT)
+and it's (`online version <https://www.essepuntato.it/lode>`__) is not always
+online.
+
+This tool is a complete re-implementation of LODE's functionality using
+Python and Python's RDF manipulation module,
+`rdflib <https://pypi.org/project/rdflib/>`__. An ontology to be
+documented is parsed and inspected using rdflib and HTML is generated
+directly, using Python's `dominate <https://pypi.org/project/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 popular `Falcon framework <https://falconframework.org/>`__.
+    - see server.py in the main folder
+- as-a-service online
+    - hosted at https://pylode.surroundaustralia.com
+
+Command line arguments
+----------------------
+
+The BASH, Windows EXE and Python Script methods all use the same 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
+                            A name you wish to assign to the output file. Will be
+                            postfixed with .html if not already added. If no
+                            output file is given, output will be printed to screen
+        -c {true,false},
+        --css {true,false}
+                            Whether (true) or not (false) to include CSS within an
+                            output HTML file.
+
+Basic Use
+^^^^^^^^^
+
+* as a Python script
+* executed in this directory
+
+::
+
+    python pylode examples/minimal.ttl -o minimal.html
+
+This will produce the file ``minimal.html`` in this directory which should
+match exactly the file ``examples/minimal.html``.
+
+
+Examples
+========
+
+The `examples/ directory <https://github.com/RDFLib/pyLODE/tree/master/examples>`_
+contains multiple pairs of RDF & HTML files generated from them using this
+version of pyLODE.
+
+You can also see rendered versions of these example files online too:
+
+* `minimal.html <http://rdflib.dev/pyLODE/examples/ontdoc/minimal.html>`_
+* `agift.html <http://rdflib.dev/pyLODE/examples/ontdoc/agift.html>`_
+* `alternates.html <http://rdflib.dev/pyLODE/examples/ontdoc/alternates.html>`_
+* `asgs.html <http://rdflib.dev/pyLODE/examples/ontdoc/asgs.html>`_
+
+
+What pyLODE understands
+=======================
+
+pyLODE knows about definitional ontologies (``owl:Ontology``) and the major
+elements usually fount in them, such as classes (``owl:Class`` or ``rdf:Class)
+and properties (``rdf:Property`` & ``owl:ObjectProperty`` etc.).
+
+To see what properties for ontology, class and RDF property documentation
+pyLODE currently supports, just look in the ``rdf_elements.py`` file. All
+elements' properties supported are given in property lists there.
+
+pyLODES won't just translate everything that you can describe in RDF into
+HTML! This is a conscious design choice to ensure that a certain conventional
+style of documented ontology is produced. However, surrport for new
+properties and ontology patterns can be made - just create an Issue on
+`this project's Issue tracker <https://github.com/RDFLib/pyLODE/issues>`__.
+
+While it *does* know about instance data, such as Named Individuals, it's
+not really designed to document large ontologies containing class instances.
+
+Notes on Agents
+---------------
+pyLODE can understand both simple and complex Agent objects. You can use
+simple string properties like ``dc:contributor "Nicholas J. Car"`` too if
+you really must but better would be to take advantage of real Linked Data
+representation, e.g. complex Agent objects with web addresses, emails,
+affiliations, ORCIDs and so on, e.g.:
+
+::
+
+    <ontology_x>
+        dct:creator [
+            sdo:name "Nicholas J. Car" ;
+            sdo:identifier <http://orcid.org/0000-0002-8742-7730> ;
+            sdo:affiliation [
+                sdo:name "SURROUND Australia Pty Ldt." ;
+                sdo:url "https://surroundaustralia.com"^^xsd:anyURI ;
+            ] ;
+        ] ;
+
+See all the properties in ``rdf_elements.py:AGENT_PROPS`` for a list of
+all the Agent properties pyLODE can handle.
+
+Installation
+============
+
+pyLODE is `on PyPI <https://pypi.org/project/pyLODE/>`_, so you can install
+it using `pip <https://pypi.org/project/pip/>`_ as normal:
+
+::
+
+    pip install pylode
+
+
+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 <https://github.com/sifrproject/MOD-Ontology>`__ will be
+      handled, if requested
+
+
+Releases
+========
+pyLODE is under continual and constant development. The current developers have a roadmap for enhancements in mind,
+which is given here, however, since this is an open source project, new developers may join the pyLODE dev community
+and change/add development priorities.
+
+Current Release
+---------------
+
+The current release, as of December, 2021, is **2.13.2**.
+
+Release Schedule
+----------------
+
+.. csv-table:: **pyLODE Release Schedule**
+   :header: "Version", "Date", "Description"
+   :widths: 15, 10, 30
+
+   **3.0.0**, **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 20201, "Fixing char encoding issues, updated examples, new test files style - per issue"
+   2.8.5, 5 Jan 20201, "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, 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 <LICENSE>`_ 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
+=============
+The maintainers welcome any collaboration.
+
+If you have suggestions, please email the contacts below or leave Issues
+in this repository's `Issue tracker <https://github.com/rdflib/pyLODE/issues>`_.
+
+But the very best thing you could do is create a Pull Request for us to
+action!
+
+
+Contacts
+========
+| *Author*:
+| **Nicholas Car**
+| *Data System Architect*
+| `SURROUND Australia Pty Ltd <https://surroundaustralia.com>`_
+| nicholas.car@surroundaustralia.com