Add documentation

Various fixes:
Made to_graph private
Change format values to media types

.gitignore

@@ -71,6 +71,9 @@ instance/
 # Sphinx documentation
 docs/_build/
 
+# Pdoc documentation
+html
+
 # PyBuilder
 target/
 

Pipfile

@@ -11,10 +11,7 @@ rdflib-jsonld = "*"
 pytest = "*"
 flake8 = "*"
 pytest-cov = "*"
+pdoc3 = "*"
 
 [requires]
 python_version = "3.8"
-
-[dev-packages.e1839a8]
-path = "."
-editable = true

concepttordf/__init__.py

@@ -1,8 +1,43 @@
-"""
-Concept to rdf
+"""Concept collection to rdf
+
+This library maps a concept collection to skos according to
+[SKOS-AP-NO](https://doc.difi.no/data/begrep-skos-ap-no/),
+a Norwegian application profile for [SKOS](https://www.w3.org/TR/skos-primer/).
+
+The library wraps [rdflib](https://rdflib.readthedocs.io/en/stable/).
+The following serialization formats are available:\n
+ - `text/turtle`
+ - `application/rdf+xml`
+ - `application/ld+json`
+ - `application/n-triples`
+ - `text/n3`
+
+Typical usage example
+
+    from concepttordf import Collection, Concept, Definition
+
+    # Create collection object
+    collection = Collection()
+    collection.identifier = "http://example.com/collections/1"
+    collection.name = {"en": "A concept collection"}
+    collection.name = {"nb": "En begrepssamling"}
+    collection.publisher = "https://example.com/publishers/1"
+
+    # Create a concept:
+    c = Concept()
+    c.identifier = "http://example.com/concepts/1"
+    c.term = {"name": {"nb": "inntekt", "en": "income"}}
+    definition = Definition()
+    definition.text = {"nb": "ting man skulle hatt mer av",
+                       "en": "something you want more of"}
+    c.definition = definition
+
+    # Add concept to collection:
+    collection.members.append(c)
 
-Heading
--------
+    # get rdf representation in turtle (default)
+    rdf = collection.to_rdf()
+    print(rdf.decode())
 """
 from .alternativformulering import AlternativFormulering
 from .associativerelation import AssociativeRelation

concepttordf/associativerelation.py

@@ -27,7 +27,7 @@ def associatedconcepts(self) -> List:
 
 # ---
 
-    def to_graph(self) -> Graph:
+    def _to_graph(self) -> Graph:
 
         self._add_relation_to_graph()
 

concepttordf/collection.py

@@ -56,17 +56,17 @@ def members(self) -> list:
     def members(self, members: list):
         self._members = members
 
-    def to_rdf(self, format='turtle', includeconcepts=True) -> str:
+    def to_rdf(self, format='text/turtle', includeconcepts=True) -> str:
         """Maps the collection to rdf and returns a serialization
            as a string according to format"""
 
         self._add_collection_to_graph()
 
         if includeconcepts:
             for concept in self.members:
-                self._g += concept.to_graph()
+                self._g += concept._to_graph()
 
-        return self._g.serialize(format=format, encoding='utf-8')
+        return self._g.serialize(format=format)
 
     # ---
 
@@ -102,7 +102,7 @@ def _add_collection_to_graph(self) -> Graph:
         if hasattr(self, 'contactpoint'):
             contact = self.contactpoint
             contactPoint = BNode()
-            for s, p, o in contact.to_graph().triples((None, None, None)):
+            for s, p, o in contact._to_graph().triples((None, None, None)):
                 self._g.add((contactPoint, p, o))
             self._g.add((URIRef(self.identifier), DCAT.contactPoint,
                         contactPoint))

concepttordf/concept.py

@@ -21,7 +21,24 @@
 
 
 class Concept:
-    """A class representing a concept"""
+    """A class representing a concept
+
+
+    Attributes:
+        identifier: the uri identifying the concept
+        term: a dictionary describing the
+            [anbefaltterm](https://doc.difi.no/data/begrep-skos-ap-no/#_begrep_anbefaltterm)
+            , e.g.\n
+            ```
+            {"name": {"en": "concept"}, "modified":"2020-01-01"}
+            ```
+        alternativeterm: a dictionary describing the
+            [tillattTerm](https://doc.difi.no/data/begrep-skos-ap-no/#_begrep_tillattterm)
+
+        hiddenterm: a dictionary describing the
+            [frarådetTerm](https://doc.difi.no/data/begrep-skos-ap-no/#_begrep_frar%C3%A5detterm)
+
+    """
 
     def __init__(self):
         self._g = Graph()
@@ -54,6 +71,14 @@ def alternativeterm(self) -> dict:
     def alternativeterm(self, alternativeterm: dict):
         self._alternativeterm = alternativeterm
 
+    @property
+    def hiddenterm(self) -> dict:
+        return self._hiddenterm
+
+    @hiddenterm.setter
+    def hiddenterm(self, hiddenterm: dict):
+        self._hiddenterm = hiddenterm
+
     @property
     def datastrukturterm(self) -> dict:
         return self._datastrukturterm
@@ -176,18 +201,49 @@ def hasPart(self, gr: PartitiveRelation):
         self._hasPart = gr
 # ----------------------------------------------
 
-    def to_graph(self) -> Graph:
-        """Adds the concept to the Graph g and returns g"""
+    def _to_graph(self) -> Graph:
+        """Transforms the concept to an rdf graph
+
+        Returns:
+            An RDF [graph](https://rdflib.readthedocs.io/en/stable/apidocs/rdflib.html#graph) representing the concept.
+        """
 
         self._add_concept_to_graph()
 
         return self._g
 
-    def to_rdf(self, format='turtle') -> str:
+    def to_rdf(self, format='text/turtle') -> str:
         """Maps the concept to rdf and returns a serialization
-           as a string according to format"""
-
-        return self.to_graph().serialize(format=format, encoding='utf-8')
+           as a string according to format
+
+        Args:
+            format: a valid serialization format\n
+                 - `text/turtle` (default)
+                 - `application/rdf+xml`
+                 - `application/ld+json`
+                 - `application/n-triples`
+                 - `text/n3`
+
+        Returns:
+            A serialization of the RDF graph, for example:
+            ```
+            @prefix dct: <http://purl.org/dc/terms/> .
+            @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+            @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+            @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+            @prefix skosno: <https://data.norge.no/vocabulary/skosno#> .
+            @prefix xml: <http://www.w3.org/XML/1998/namespace> .
+            @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+            <http://example.com/concepts/1> a skos:Concept ;
+                    skosno:definisjon [ a skosno:Definisjon ;
+                    skosno:forholdTilKilde skosno:egendefinert ]
+                    .
+            ```
+
+           """
+
+        return self._to_graph().serialize(format=format)
 
 # ----------------------------------------------
 
@@ -287,7 +343,7 @@ def _add_concept_to_graph(self):
         if hasattr(self, 'contactpoint'):
             contact = self.contactpoint
             contactPoint = BNode()
-            for s, p, o in contact.to_graph().triples((None, None, None)):
+            for s, p, o in contact._to_graph().triples((None, None, None)):
                 self._g.add((contactPoint, p, o))
             self._g.add((URIRef(self.identifier), DCAT.contactPoint,
                          contactPoint))
@@ -346,23 +402,23 @@ def _add_concept_to_graph(self):
         if hasattr(self, 'related'):
             _related = self.related
             ar = BNode()
-            for s, p, o in _related.to_graph().triples((None, None, None)):
+            for s, p, o in _related._to_graph().triples((None, None, None)):
                 self._g.add((ar, p, o))
             self._g.add((URIRef(self.identifier), SKOS.related, ar))
 
         # generalizes
         if hasattr(self, 'generalizes'):
             _generalizes = self.generalizes
             ar = BNode()
-            for s, p, o in _generalizes.to_graph().triples((None, None, None)):
+            for s, p, o in _generalizes._to_graph().triples((None, None, None)):
                 self._g.add((ar, p, o))
             self._g.add((URIRef(self.identifier), XKOS.generalizes, ar))
 
         # hasPart
         if hasattr(self, 'hasPart'):
             _hasPart = self.hasPart
             ar = BNode()
-            for s, p, o in _hasPart.to_graph().triples((None, None, None)):
+            for s, p, o in _hasPart._to_graph().triples((None, None, None)):
                 self._g.add((ar, p, o))
             self._g.add((URIRef(self.identifier), XKOS.hasPart, ar))
 

concepttordf/contact.py

@@ -45,17 +45,17 @@ def url(self) -> str:
     def url(self, url: str):
         self._url = url
 
-    def to_graph(self) -> Graph:
+    def _to_graph(self) -> Graph:
 
         self._add_contact_to_graph()
 
         return self._g
 
-    def to_rdf(self, format='turtle') -> str:
+    def to_rdf(self, format='text/turtle') -> str:
         """Maps the contact to rdf and returns a serialization
            as a string according to format"""
 
-        return self.to_graph().serialize(format=format, encoding='utf-8')
+        return self._to_graph().serialize(format=format)
 
     # -----
 

concepttordf/genericrelation.py

@@ -26,7 +26,7 @@ def genericconcepts(self) -> List:
         return self._genericconcepts
 # ---
 
-    def to_graph(self) -> Graph:
+    def _to_graph(self) -> Graph:
 
         self._add_relation_to_graph()
 

concepttordf/partitiverelation.py

@@ -26,7 +26,7 @@ def partconcepts(self) -> List:
         return self._partconcepts
 # ---
 
-    def to_graph(self) -> Graph:
+    def _to_graph(self) -> Graph:
 
         self._add_relation_to_graph()