Update documentation

Author: kdouda

src/pyrdfrules/__init__.py

@@ -3,7 +3,93 @@
 # SPDX-License-Identifier: MIT
 
 """
+PyRDFRules is a Python wrapper for the RDFRules tool, providing an interface to interact with RDFRules for rule mining from RDF knowledge graphs.
 
-PyRDFRules is a Python library for working with RDFRules. It provides a simple interface for creating and managing RDFRules pipelines.
+Sample usage:
+```python
+import pyrdfrules.application
+from pyrdfrules.common.task.task import Task
+from pyrdfrules.config import Config
+from pyrdfrules.rdfrules.commondata import ConfidenceType, Constraint, RuleConsumer, RuleConsumerType, Threshold
+from pyrdfrules.rdfrules.jsonformats import PrefixFull
+from pyrdfrules.rdfrules.pipeline import ComputeConfidence, GetRules, GraphAwareRules, Index, LoadGraph, MergeDatasets, AddPrefixes, Mine, Pipeline, SortRuleset
 
+# Create an instance of the application.
+app = pyrdfrules.application.Application()
+
+# Connect to an existing instance of RDFRules.
+rdfrules = app.start_remote(
+    url = Url("http://example.com/api/"),
+    config=Config(
+        task_update_interval_ms=1000
+    )
+)
+
+# Create a pipeline, a sequence of steps to be executed.
+# You do not have to use fully qualified names for the classes, as they are imported in the example.
+pipeline = pyrdfrules.rdfrules.pipeline.Pipeline(
+    tasks=[
+        pyrdfrules.rdfrules.pipeline.LoadGraph(
+            graphName = "<dbpedia>",
+            path = "/dbpedia_yago/mappingbased_objects_sample.ttl"
+        ),
+        pyrdfrules.rdfrules.pipeline.LoadGraph(
+            graphName = "<yago>",
+            path = "/dbpedia_yago/yagoFacts.tsv",
+            settings = "tsvParsedUris"
+        ),
+        pyrdfrules.rdfrules.pipeline.LoadGraph(
+            graphName = "<dbpedia>",
+            path = "/dbpedia_yago/yagoDBpediaInstances.tsv",
+            settings = "tsvParsedUris"
+        ),
+        pyrdfrules.rdfrules.pipeline.MergeDatasets(),
+        pyrdfrules.rdfrules.jsonformats.AddPrefixes(
+            prefixes=[
+                pyrdfrules.rdfrules.jsonformats.PrefixFull(prefix="dbo", nameSpace="http://dbpedia.org/ontology/"),
+                pyrdfrules.rdfrules.jsonformats.PrefixFull(prefix="dbr", nameSpace="http://dbpedia.org/resource/")
+            ]
+        ),
+        pyrdfrules.rdfrules.pipeline.Index(train=[], test=[]),
+        pyrdfrules.rdfrules.pipeline.Mine(
+            thresholds=[
+                pyrdfrules.rdfrules.commondata.Threshold(name="MinHeadSize", value=100),
+                pyrdfrules.rdfrules.commondata.Threshold(name="MaxRuleLength", value=3),
+                pyrdfrules.rdfrules.commondata.Threshold(name="Timeout", value=5),
+                pyrdfrules.rdfrules.commondata.Threshold(name="MinHeadCoverage", value=0.01),
+            ],
+            ruleConsumers=[
+                pyrdfrules.rdfrules.commondata.RuleConsumer(
+                    name=pyrdfrules.rdfrules.commondata.RuleConsumerType.TOP_K,
+                    k=1000,
+                    allowOverflow=False
+                )
+            ],
+            patterns=[],
+            constraints=[
+                pyrdfrules.rdfrules.commondata.Constraint(name="WithoutConstants")
+            ],
+            parallelism=0
+        ),
+        pyrdfrules.rdfrules.pipeline.ComputeConfidence(confidenceType=ConfidenceType.PCA_CONFIDENCE, min=0.5, topk=50),
+        pyrdfrules.rdfrules.pipeline.SortRuleset(by=[]),
+        pyrdfrules.rdfrules.pipeline.GraphAwareRules(),
+        pyrdfrules.rdfrules.pipeline.GetRules()
+    ]
+)
+
+# Create a task, which represents the execution of the pipeline.
+task : Task = None
+
+# Submit the task to the RDFRules engine.
+task = rdfrules.task.create_task(pipeline)
+    
+# Run the task step by step.
+for step in rdfrules.task.run_task(task):
+    print(step)
+    # You can access the result of the task using the task object, read the logs, or interrupt the task here.
+
+# Access the result of the task.
+print(task.result)
+```        
 """

src/pyrdfrules/api/task/exception/task_not_found_exception.py

@@ -1,7 +1,8 @@
 from pyrdfrules.common.exception.pyrdfrules_exception import PyRDFRulesException
 
 class TaskNotFoundException(PyRDFRulesException):
-    """Thrown when a task is not found in the RDFRules instance.
+    """
+    Thrown when a task is not found in the RDFRules instance.
     """
 
     def __init__(self, task_id: str):

src/pyrdfrules/application.py

@@ -9,6 +9,9 @@
 from pyrdfrules.rdfrules.rdfrules import RDFRules
 
 class Application(BaseModel):
+    """
+    The Application class provides methods to start and stop local or remote instances of RDFRules.
+    """
 
     __rdfrules: RDFRules|None = None
 

src/pyrdfrules/common/__init__.py

@@ -0,0 +1,13 @@
+"""
+Common module for pyRDFRules.
+
+This module contains the common classes and functions used by the other modules of pyRDFRules.
+
+Contains:
+- task: Task class and related classes.
+- rule: Rule class and related classes.
+- result: Result class and related classes.
+- logging: Logging functions.
+- config: Configuration class.
+- utils: Utility functions.
+"""

src/pyrdfrules/common/base_actions.py

@@ -1,14 +1,20 @@
 class EventDispatcher():
+    """
+    The EventDispatcher class manages event listeners and dispatches events to them.
+    """
     def __init__(self):
         self._listeners = []
 
     def add_listener(self, callback: callable):
+        """Adds a listener to the event dispatcher."""
         self._listeners.append(callback)
 
     def remove_listener(self, callback: callable):
+        """Removes a listener from the event dispatcher."""
         self._listeners.remove(callback)
 
     def dispatch(self, *args, **kwargs):
+        """Dispatches an event to all listeners."""
         for listener in self._listeners:
             listener(*args, **kwargs)
 

src/pyrdfrules/common/base_transformations.py

@@ -0,0 +1,3 @@
+"""
+Common exceptions for pyRDFRules.
+"""

src/pyrdfrules/common/event/event_dispatcher.py

@@ -0,0 +1,26 @@
+"""
+RDFRules file representations.
+
+Read all files in the workspace:
+
+```python
+rdfrules = app.start_remote(
+    url = Url("...")
+)
+
+rdfrules.workspace.get_files()
+```
+
+Upload a file:
+
+```python
+with open(path, "r") as file:        
+    rdfrules.workspace.upload_file("data/asset.txt", file)
+```
+
+Delete a file:
+
+```python
+rdfrules.workspace.delete_file("data/asset.txt")
+```
+"""

src/pyrdfrules/common/exception/__init__.py

@@ -6,7 +6,7 @@
 
 class Workspace():
     """
-    Path in which RDFRules can find datasets and store results.
+    The Workspace class provides methods to interact with the RDFRules workspace, including file management.
     """
 
     api: WorkspaceApi

src/pyrdfrules/common/file/__init__.py

@@ -6,6 +6,9 @@
 from pyrdfrules.common.file.workspace_file import WorkspaceFile
 
 class WorkspaceTree(BaseModel):
+    """
+    The WorkspaceTree class represents the structure of the workspace directory, including files and subdirectories.
+    """
 
     root: WorkspaceDirectory|None = None
 

src/pyrdfrules/common/file/workspace.py

@@ -0,0 +1,3 @@
+"""
+HTTP module exposing interactions via the HTTP protocol.
+"""

src/pyrdfrules/common/file/workspace_tree.py

@@ -1,4 +1,9 @@
 from pydantic_core import Url
 
 class Url(Url):
+    """Represents a URL. Wrapped so there is no need to explicitly import any Pydantic classes.
+
+    Args:
+        Url (Url): Wrapper for a URL.
+    """
     pass

src/pyrdfrules/common/http/__init__.py

@@ -0,0 +1,7 @@
+"""
+Logging module exposing logging functionality.
+
+Configurable logging is provided by the `Config` class. The `Logger` class provides the logging functionality. The `log` function provides a global logger instance. The `configure_logging` function configures the logging, and is called automatically upon application startup.
+
+By default, the logging level is set to `logging.INFO`. This can be changed by setting the `log_level` attribute of the `Config` class.
+"""

src/pyrdfrules/common/http/url.py

@@ -2,9 +2,16 @@
 
 from pyrdfrules.config import Config
 
-pyrdfrules_logger = None
+pyrdfrules_logger : logging.Logger = None
+"""Global instance of the logger.
+Empty by default.
+Obtain the logger by calling the `log` function from this package.
+"""
 
 class Logger():
+    """
+    The Logger class provides methods to configure and retrieve the logger for the application.
+    """
 
     logger: logging.Logger = None
 

src/pyrdfrules/common/logging/__init__.py

@@ -0,0 +1,3 @@
+"""
+Package for translating the resulting JSON into internal object representations.
+"""

src/pyrdfrules/common/logging/logger.py

@@ -4,20 +4,31 @@
 
 
 class Result():
+    """Class representing the result of a task.
+    """
 
     ruleset: Ruleset = None
     """Ruleset generated by RDFRules.
     """
 
+    data: dict
+    """Raw JSON response from RDFRules."""
+    
     def __init__(self, data: dict) -> None:
-        self.id = id
+        """Creates a new Result object.
+
+        Args:
+            data (dict): JSON response from RDFRules.
+        """
         self.data = data
 
         self._parse_data()
 
         pass
 
     def _parse_data(self):
+        """Internal function translating the resulting JSON into internal object representations.
+        """
 
         rules = []
 
@@ -35,4 +46,6 @@ def _parse_data(self):
         self.ruleset = Ruleset(rules = rules)
 
     def get_ruleset(self) -> Ruleset:
+        """Returns the ruleset generated by RDFRules.
+        """
         return self.ruleset

src/pyrdfrules/common/predictontasks/predictiontasks_actions.py

@@ -0,0 +1,3 @@
+"""
+Contains representations of a generated rule from RDFRules.
+"""

src/pyrdfrules/common/predictontasks/predictiontasks_transformations.py

@@ -1,7 +1,6 @@
 from typing import List
 from pydantic import BaseModel
 
-from pyrdfrules.common.graph.graph import Graph
 from pyrdfrules.common.rule.measure.measure import RuleMeasure
 from pyrdfrules.common.rule.rule.body import RuleBody
 from pyrdfrules.common.rule.rule.head import RuleHead
@@ -24,4 +23,10 @@ class ResultRule(BaseModel):
     """
     Measures of the rule.
     """
-    measures: List[RuleMeasure]
+    measures: List[RuleMeasure]
+    
+    def as_test(self) -> str:
+        return ''
+    
+    def as_json(self) -> str:
+        return ''