Adding documentation

Author: gtfierro

README.md

@@ -129,38 +129,58 @@ If GraphViz is installed, `ontoenv dep-graph` will output a PDF graph representa
 
 #### Usage
 
+Here is a basic example of how to use the `pyontoenv` Python library. This example will:
+1. Create a temporary directory.
+2. Write two simple ontologies to files in that directory, where one imports the other.
+3. Configure and initialize `ontoenv` to use this directory.
+4. Compute the dependency closure of one ontology to demonstrate that `ontoenv` correctly resolves and includes the imported ontology.
+
 ```python
+import tempfile
+from pathlib import Path
 from ontoenv import Config, OntoEnv
 from rdflib import Graph
 
-# create config object. This assumes you have a 'brick' folder locally storing some ontologies
-cfg = Config(search_directories=["brick"], strict=False, offline=True)
-# can also create an 'empty' config object if there are no local ontologies
-# cfg = Config(strict=False, offline=True)
-
-# make the environment
-env = OntoEnv(config=cfg)
-
-# compute closure for a given ontology and insert it into a graph
-g = Graph()
-env.get_closure("https://brickschema.org/schema/1.4/Brick", destination_graph=g)
-
-# import all dependencies from a graph
-brick = Graph()
-brick.parse("brick/Brick.ttl", format="turtle")
-env.import_dependencies(brick)
-
-# get a graph by IRI
-rec = env.get_graph("https://w3id.org/rec")
-
-# add an ontology to a graph by IRI
-env.import_graph(brick, "https://w3id.org/rec")
+# create a temporary directory to store our ontology files
+with tempfile.TemporaryDirectory() as temp_dir:
+    root = Path(temp_dir)
+    # create a dummy ontology file for ontology A
+    ontology_a_content = """
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix : <http://example.com/ontology_a#> .
+<http://example.com/ontology_a> a owl:Ontology .
+"""
+    (root / "ontology_a.ttl").write_text(ontology_a_content)
 
-# get an rdflib.Dataset (https://rdflib.readthedocs.io/en/stable/apidocs/rdflib.html#rdflib.Dataset)
-ds = env.to_rdflib_dataset()
-for graphname in ds.graphs():
-    graph = ds.graph(graphname)
-    print(f"Graph {graphname} has {len(graph)} triples")
+    # create a dummy ontology file for ontology B which imports A
+    ontology_b_content = """
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix : <http://example.com/ontology_b#> .
+<http://example.com/ontology_b> a owl:Ontology ;
+    owl:imports <http://example.com/ontology_a> .
+"""
+    (root / "ontology_b.ttl").write_text(ontology_b_content)
+
+    # create config object. We use temporary=True so it doesn't create a .ontoenv dir
+    cfg = Config(search_directories=[str(root)], strict=False, offline=True, temporary=True)
+    # make the environment
+    env = OntoEnv(config=cfg)
+
+    # list the ontologies found
+    print("Ontologies found:", env.get_ontology_names())
+
+    # compute closure for ontology B and insert it into a graph
+    g = Graph()
+    env.get_closure("http://example.com/ontology_b", destination_graph=g)
+    # The closure should contain triples from both A and B.
+    # Each ontology has 1 triple, so the union should have 2.
+    print(f"Closure of ontology_b has {len(g)} triples")
+    assert len(g) == 2
+
+    # get just the graph for ontology A
+    g_a = env.get_graph("http://example.com/ontology_a")
+    print(f"Graph of ontology_a has {len(g_a)} triples")
+    assert len(g_a) == 1
 ```
 
 ## Rust Library
@@ -171,16 +191,19 @@ for graphname in ds.graphs():
 
 Here is a basic example of how to use the `ontoenv` Rust library. This example will:
 1. Create a temporary directory.
-2. Write a simple ontology to a file in that directory.
+2. Write two simple ontologies to files in that directory, where one imports the other.
 3. Configure and initialize `ontoenv` to use this directory.
-4. Verify that the ontology has been loaded correctly.
+4. Compute the dependency closure of one ontology to demonstrate that `ontoenv` correctly resolves and includes the imported ontology.
 
 ```rust
 use ontoenv::config::Config;
-use ontoenv::api::OntoEnv;
+use ontoenv::api::{OntoEnv, ResolveTarget};
+use ontoenv::ToUriString;
+use oxigraph::model::NamedNode;
 use std::path::PathBuf;
 use std::fs;
 use std::io::Write;
+use std::collections::HashSet;
 
 # fn main() -> anyhow::Result<()> {
 // Set up a temporary directory for the example
@@ -191,14 +214,23 @@ if test_dir.exists() {
 fs::create_dir_all(&test_dir)?;
 let root = test_dir.canonicalize()?;
 
-// Create a dummy ontology file
-let ontology_path = root.join("my_ontology.ttl");
-let mut file = fs::File::create(&ontology_path)?;
-writeln!(file, r#"
+// Create a dummy ontology file for ontology A
+let ontology_a_path = root.join("ontology_a.ttl");
+let mut file_a = fs::File::create(&ontology_a_path)?;
+writeln!(file_a, r#"
 @prefix owl: <http://www.w3.org/2002/07/owl#> .
-@prefix : <http://example.com/my_ontology#> .
+@prefix : <http://example.com/ontology_a#> .
+<http://example.com/ontology_a> a owl:Ontology .
+"#)?;
 
-<http://example.com/my_ontology> a owl:Ontology .
+// Create a dummy ontology file for ontology B which imports A
+let ontology_b_path = root.join("ontology_b.ttl");
+let mut file_b = fs::File::create(&ontology_b_path)?;
+writeln!(file_b, r#"
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix : <http://example.com/ontology_b#> .
+<http://example.com/ontology_b> a owl:Ontology ;
+    owl:imports <http://example.com/ontology_a> .
 "#)?;
 
 // Configure ontoenv
@@ -212,11 +244,22 @@ let config = Config::builder()
 let mut env = OntoEnv::init(config, false)?;
 env.update()?;
 
-// Check that our ontology was loaded
+// Check that our ontologies were loaded
 let ontologies = env.ontologies();
-assert_eq!(ontologies.len(), 1);
-let ont_name = ontologies.keys().next().unwrap().name();
-assert_eq!(ont_name.as_str(), "http://example.com/my_ontology");
+assert_eq!(ontologies.len(), 2);
+
+// Get the dependency closure for ontology B
+let ont_b_name = NamedNode::new("http://example.com/ontology_b")?;
+let ont_b_id = env.resolve(ResolveTarget::Graph(ont_b_name)).unwrap();
+let closure = env.get_dependency_closure(&ont_b_id)?;
+
+// The closure should contain both ontology A and B
+assert_eq!(closure.len(), 2);
+let closure_names: HashSet<String> = closure.iter().map(|id| id.to_uri_string()).collect();
+println!("Closure contains: {:?}", closure_names);
+assert!(closure_names.contains("http://example.com/ontology_a"));
+assert!(closure_names.contains("http://example.com/ontology_b"));
+
 
 // Clean up
 fs::remove_dir_all(&test_dir)?;

cli/src/main.rs

@@ -5,6 +5,7 @@ use ontoenv::api::{OntoEnv, ResolveTarget};
 use ontoenv::config::Config;
 use ontoenv::ontology::{GraphIdentifier, OntologyLocation};
 use ontoenv::util::write_dataset_to_file;
+use ontoenv::ToUriString;
 use oxigraph::model::NamedNode;
 use std::env::current_dir;
 use std::path::PathBuf;
@@ -335,14 +336,14 @@ fn main() -> Result<()> {
                     ontologies.sort_by(|a, b| a.name().cmp(&b.name()));
                     ontologies.dedup_by(|a, b| a.name() == b.name());
                     for ont in ontologies {
-                        println!("{}", ont.name().as_str());
+                        println!("{}", ont.to_uri_string());
                     }
                 }
                 ListCommands::Missing => {
                     let mut missing_imports = env.missing_imports();
                     missing_imports.sort();
                     for import in missing_imports {
-                        println!("{}", import);
+                        println!("{}", import.to_uri_string());
                     }
                 }
             }
@@ -385,9 +386,9 @@ fn main() -> Result<()> {
             for ont in ontologies {
                 let iri = NamedNode::new(ont).map_err(|e| anyhow::anyhow!(e.to_string()))?;
                 let dependents = env.get_dependents(&iri)?;
-                println!("Dependents of {iri}: ");
+                println!("Dependents of {}: ", iri.to_uri_string());
                 for dep in dependents {
-                    println!("{dep}");
+                    println!("{}", dep.to_uri_string());
                 }
             }
         }

lib/src/lib.rs

@@ -1,4 +1,93 @@
-#[doc = include_str!("../../README.md")]
+//! `ontoenv` is an environment manager for ontologies. It can be used as a Rust library to manage local and remote RDF ontologies and their dependencies.
+//!
+//! It recursively discovers and resolves `owl:imports` statements, and provides an API for querying the dependency graph and retrieving a unified "imports closure" of an ontology.
+//!
+//! The environment is backed by an `Oxigraph` store.
+//!
+//! # Usage
+//!
+//! Here is a basic example of how to use the `ontoenv` Rust library. This example will:
+//! 1. Create a temporary directory.
+//! 2. Write two simple ontologies to files in that directory, where one imports the other.
+//! 3. Configure and initialize `ontoenv` to use this directory.
+//! 4. Compute the dependency closure of one ontology to demonstrate that `ontoenv` correctly resolves and includes the imported ontology.
+//!
+//! ```rust
+//! use ontoenv::config::Config;
+//! use ontoenv::ToUriString;
+//! use ontoenv::api::{OntoEnv, ResolveTarget};
+//! use oxigraph::model::NamedNode;
+//! use std::path::PathBuf;
+//! use std::fs;
+//! use std::io::Write;
+//! use std::collections::HashSet;
+//!
+//! # fn main() -> anyhow::Result<()> {
+//! // Set up a temporary directory for the example
+//! let test_dir = PathBuf::from("target/doc_test_temp_readme");
+//! if test_dir.exists() {
+//!     fs::remove_dir_all(&test_dir)?;
+//! }
+//! fs::create_dir_all(&test_dir)?;
+//! let root = test_dir.canonicalize()?;
+//!
+//! // Create a dummy ontology file for ontology A
+//! let ontology_a_path = root.join("ontology_a.ttl");
+//! let mut file_a = fs::File::create(&ontology_a_path)?;
+//! writeln!(file_a, r#"
+//! @prefix owl: <http://www.w3.org/2002/07/owl#> .
+//! @prefix : <http://example.com/ontology_a#> .
+//! <http://example.com/ontology_a> a owl:Ontology .
+//! "#)?;
+//!
+//! // Create a dummy ontology file for ontology B which imports A
+//! let ontology_b_path = root.join("ontology_b.ttl");
+//! let mut file_b = fs::File::create(&ontology_b_path)?;
+//! writeln!(file_b, r#"
+//! @prefix owl: <http://www.w3.org/2002/07/owl#> .
+//! @prefix : <http://example.com/ontology_b#> .
+//! <http://example.com/ontology_b> a owl:Ontology ;
+//!     owl:imports <http://example.com/ontology_a> .
+//! "#)?;
+//!
+//! // Configure ontoenv
+//! let config = Config::builder()
+//!     .root(root.clone())
+//!     .locations(vec![root.clone()])
+//!     .temporary(true) // Use a temporary environment
+//!     .build()?;
+//!
+//! // Initialize the environment
+//! let mut env = OntoEnv::init(config, false)?;
+//! env.update()?;
+//!
+//! // Check that our ontologies were loaded
+//! let ontologies = env.ontologies();
+//! assert_eq!(ontologies.len(), 2);
+//!
+//! // Get the dependency closure for ontology B
+//! let ont_b_name = NamedNode::new("http://example.com/ontology_b")?;
+//! let ont_b_id = env.resolve(ResolveTarget::Graph(ont_b_name)).unwrap();
+//! let closure_ids = env.get_dependency_closure(&ont_b_id)?;
+//!
+//! // The closure should contain both ontology A and B
+//! assert_eq!(closure_ids.len(), 2);
+//! let closure_names: HashSet<String> = closure_ids.iter().map(|id| id.to_uri_string()).collect();
+//! assert!(closure_names.contains("http://example.com/ontology_a"));
+//! assert!(closure_names.contains("http://example.com/ontology_b"));
+//!
+//! // We can also get the union graph of the closure
+//! let union_graph_result = env.get_union_graph(&closure_ids, Some(false), Some(false))?;
+//! // Each ontology has 1 triple, so the union should have 2.
+//! // the 'ontology_a' declaration gets removed by default so that the closure
+//! // only has one ontology declaration.
+//! assert_eq!(union_graph_result.dataset.len(), 2);
+//!
+//! // Clean up
+//! fs::remove_dir_all(&test_dir)?;
+//! # Ok(())
+//! # }
+//! ```
 
 extern crate derive_builder;
 
@@ -21,6 +110,35 @@ use oxigraph::model::NamedNode;
 use pretty_bytes::converter::convert as pretty_bytes;
 use std::fmt::{self, Display};
 
+pub trait ToUriString {
+    fn to_uri_string(&self) -> String;
+}
+
+impl ToUriString for NamedNode {
+    fn to_uri_string(&self) -> String {
+        self.as_str().to_string()
+    }
+}
+
+impl ToUriString for &NamedNode {
+    fn to_uri_string(&self) -> String {
+        self.as_str().to_string()
+    }
+}
+
+impl ToUriString for GraphIdentifier {
+    fn to_uri_string(&self) -> String {
+        self.name().as_str().to_string()
+    }
+}
+
+impl ToUriString for &GraphIdentifier {
+    fn to_uri_string(&self) -> String {
+        self.name().as_str().to_string()
+    }
+}
+
+
 pub struct FailedImport {
     ontology: GraphIdentifier,
     error: String,
@@ -37,7 +155,8 @@ impl Display for FailedImport {
         write!(
             f,
             "Failed to import ontology {}: {}",
-            self.ontology, self.error
+            self.ontology.to_uri_string(),
+            self.error
         )
     }
 }
@@ -84,7 +203,7 @@ impl std::fmt::Display for EnvironmentStatus {
         if !self.missing_imports.is_empty() {
             write!(f, "\n\nMissing Imports:")?;
             for import in &self.missing_imports {
-                write!(f, "\n  - {}", import)?;
+                write!(f, "\n  - {}", import.to_uri_string())?;
             }
         }
         Ok(())

python/src/lib.rs

@@ -1,6 +1,8 @@
+#[doc = include_str!("../../README.md")]
 use ::ontoenv::api::{OntoEnv as OntoEnvRs, ResolveTarget};
 use ::ontoenv::config;
 use ::ontoenv::consts::{IMPORTS, ONTOLOGY, TYPE};
+use ::ontoenv::ToUriString;
 use ::ontoenv::ontology::OntologyLocation;
 use ::ontoenv::transform;
 use anyhow::Error;
@@ -321,7 +323,7 @@ impl OntoEnv {
         let closure = env
             .get_dependency_closure(ont.id())
             .map_err(anyhow_to_pyerr)?;
-        let names: Vec<String> = closure.iter().map(|ont| ont.name().to_string()).collect();
+        let names: Vec<String> = closure.iter().map(|ont| ont.to_uri_string()).collect();
         Ok(names)
     }
 
@@ -462,10 +464,7 @@ impl OntoEnv {
         let inner = self.inner.clone();
         let env = inner.lock().unwrap();
         let dependents = env.get_dependents(&iri).map_err(anyhow_to_pyerr)?;
-        let names: Vec<String> = dependents
-            .iter()
-            .map(|ont| ont.name().to_string())
-            .collect();
+        let names: Vec<String> = dependents.iter().map(|ont| ont.to_uri_string()).collect();
         Ok(names)
     }
 
@@ -515,7 +514,7 @@ impl OntoEnv {
         let names: Vec<String> = env
             .ontologies()
             .keys()
-            .map(|k| k.name().to_string())
+            .map(|k| k.to_uri_string())
             .collect();
         Ok(names)
     }