Merge pull request #22 from saezlab/feat/add-download-manager-port

Enhance downloader options and update documentation for OntoGraph

Author: ecarrenolozano

README.md

@@ -30,10 +30,16 @@ uv pip install -e .
 
 ```python
 from ontograph.client import ClientCatalog
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
 
 # Instantiate a client for your catalog
 client_catalog = ClientCatalog(cache_dir="./data/out")
 
+# Optional: choose a downloader adapter explicitly
+# downloader = DownloadManagerAdapter(cache_dir=DEFAULT_CACHE_DIR, backend="requests")
+# client_catalog = ClientCatalog(cache_dir="./data/out", downloader=downloader)
+
 # Load the catalog, in case this one doesn't exist it will be downloaded automatically in the cache folder you specify.
 client_catalog.load_catalog()
 ```
@@ -56,12 +62,18 @@ metadata_go = client_catalog.get_ontology_metadata(ontology_id="go", show_metada
 #### Create a client for your ontology
 ```python
 from ontograph.client import ClientOntology
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
 
 # Instantiate a client for your ontology
 client_dummy_ontology = ClientOntology(cache_dir="./data/out")
 
 # Load a dummy ontology, we prepare a simple one to try out this package.
-client_dummy_ontology.load(file_path_ontology="./tests/resources/dummy_ontology.obo")
+client_dummy_ontology.load(source="./tests/resources/dummy_ontology.obo")
+
+# Optional: choose a downloader adapter explicitly
+# downloader = DownloadManagerAdapter(cache_dir=DEFAULT_CACHE_DIR, backend="requests")
+# client_dummy_ontology = ClientOntology(cache_dir="./data/out", downloader=downloader)
 ```
 #### Queries for your ontology
 
@@ -138,7 +150,17 @@ If you are interested in loading an ontology from the catalog, just use the `nam
 
 ```bash
 client_go = ClientOntology()
-client_go.load(name_id="go", format="obo")
+client_go.load(source="go")
+```
+
+### Downloader configuration
+
+By default, the project uses a configurable downloader backend. You can set a global default in `ontograph/config/settings.py`:
+
+```python
+DEFAULT_DOWNLOADER = "pooch"
+# or
+DEFAULT_DOWNLOADER = "download_manager"
 ```
 
 ## Contributing

docs/index.md

@@ -24,7 +24,7 @@
   Analyze ontology structure, calculate paths and trajectories, and visualize term hierarchies.
 
 - **Caching & Download Management**  
-  Efficiently download and cache ontology files for offline use.
+  Efficiently download and cache ontology files for offline use with configurable downloader backends.
 
 ---
 

docs/learn/tutorials/quickstart.md

@@ -11,12 +11,18 @@ First, let's interact with the OBO Foundry catalog to discover available ontolog
 
 ```python
 from ontograph.client import ClientCatalog
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
 
 # Create a catalog client (specify a cache directory for downloads)
 client_catalog = ClientCatalog(cache_dir="./data/out")
 
 # Load the catalog (downloads if not cached)
 client_catalog.load_catalog()
+
+# Optional: choose a downloader adapter explicitly
+# downloader = DownloadManagerAdapter(cache_dir=DEFAULT_CACHE_DIR, backend="requests")
+# client_catalog = ClientCatalog(cache_dir="./data/out", downloader=downloader)
 ```
 
 ### List Available Ontologies
@@ -48,12 +54,18 @@ Now, let's load an ontology and explore its structure.
 
 ```python
 from ontograph.client import ClientOntology
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
 
 # Create an ontology client
 client_ontology = ClientOntology(cache_dir="./data/out")
 
 # Load a sample ontology (provided in the repo for testing)
-client_ontology.load(file_path_ontology="./tests/resources/dummy_ontology.obo")
+client_ontology.load(source="./tests/resources/dummy_ontology.obo")
+
+# Optional: choose a downloader adapter explicitly
+# downloader = DownloadManagerAdapter(cache_dir=DEFAULT_CACHE_DIR, backend="requests")
+# client_ontology = ClientOntology(cache_dir="./data/out", downloader=downloader)
 ```
 
 ---

docs/learn/tutorials/tutorial0001_basics.md

@@ -0,0 +1,74 @@
+# Basics: Downloading Ontologies
+
+This minimal tutorial shows how to download ontologies using either Pooch or Download Manager, and how to load from the catalog or a URL.
+
+---
+
+## 1. Choose a Global Default Downloader
+
+Set the default once in `ontograph/config/settings.py`:
+
+```python
+DEFAULT_DOWNLOADER = "pooch"
+# or
+DEFAULT_DOWNLOADER = "download_manager"
+```
+
+Now any client will use the configured backend unless you pass a downloader explicitly.
+
+---
+
+## 2. Use Pooch Explicitly
+
+```python
+from ontograph.client import ClientCatalog, ClientOntology
+from ontograph.downloader import PoochDownloaderAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
+
+downloader = PoochDownloaderAdapter(cache_dir=DEFAULT_CACHE_DIR)
+
+catalog = ClientCatalog(cache_dir="./data/out", downloader=downloader)
+catalog.load_catalog()
+
+client = ClientOntology(cache_dir="./data/out", downloader=downloader)
+client.load(source="go")  # catalog download
+```
+
+---
+
+## 3. Use Download Manager Explicitly
+
+```python
+from ontograph.client import ClientCatalog, ClientOntology
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
+
+downloader = DownloadManagerAdapter(
+    cache_dir=DEFAULT_CACHE_DIR,
+    backend="requests",
+)
+
+catalog = ClientCatalog(cache_dir="./data/out", downloader=downloader)
+catalog.load_catalog()
+
+client = ClientOntology(cache_dir="./data/out", downloader=downloader)
+client.load(source="go")  # catalog download
+```
+
+---
+
+## 4. Download From a URL
+
+```python
+from ontograph.client import ClientOntology
+from ontograph.downloader import PoochDownloaderAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
+
+downloader = PoochDownloaderAdapter(cache_dir=DEFAULT_CACHE_DIR)
+
+# URL to GO ontology
+source_go = "https://purl.obolibrary.org/obo/go.obo"
+
+client = ClientOntology(cache_dir=DEFAULT_CACHE_DIR, downloader=downloader)
+client.load(source=source_go)
+```

docs/reference/source/ontograph/client-catalog.md

@@ -15,6 +15,20 @@ This class is ideal for users who want to explore the catalog of available ontol
 - Get download URLs and available formats for each ontology
 - Print the catalog schema tree for exploration
 
+## Usage
+
+```python
+from ontograph.client import ClientCatalog
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
+
+client_catalog = ClientCatalog(cache_dir="./data/out")
+
+# Optional: use Download Manager for all catalog downloads
+# downloader = DownloadManagerAdapter(cache_dir=DEFAULT_CACHE_DIR, backend="requests")
+# client_catalog = ClientCatalog(cache_dir="./data/out", downloader=downloader)
+```
+
 ---
 
 ## API Reference

docs/reference/source/ontograph/client-ontology.md

@@ -15,6 +15,20 @@ This class is ideal for users who want to work directly with a specific ontology
 - Introspect ontology structure: calculate paths, trajectories, and visualize term hierarchies
 - Modular query adapters for navigation, relations, and introspection
 
+## Usage
+
+```python
+from ontograph.client import ClientOntology
+from ontograph.downloader import DownloadManagerAdapter
+from ontograph.config.settings import DEFAULT_CACHE_DIR
+
+client_ontology = ClientOntology(cache_dir="./data/out")
+
+# Optional: use Download Manager for all remote downloads
+# downloader = DownloadManagerAdapter(cache_dir=DEFAULT_CACHE_DIR, backend="requests")
+# client_ontology = ClientOntology(cache_dir="./data/out", downloader=downloader)
+```
+
 ---
 
 ## API Reference

docs/reference/source/ontograph/downloader.md

@@ -2,6 +2,19 @@
 
 This module provides interfaces and adapters for downloading ontology files from URLs and catalogs.
 
+## Default Downloader
+
+OntoGraph selects a default downloader backend via `DEFAULT_DOWNLOADER` in
+`ontograph/config/settings.py`. You can also override this per client by
+passing a downloader adapter.
+
+```python
+from ontograph.downloader import get_default_downloader
+from ontograph.config.settings import DEFAULT_CACHE_DIR
+
+downloader = get_default_downloader(cache_dir=DEFAULT_CACHE_DIR)
+```
+
 ---
 
 ## API Reference

ontograph/client.py

@@ -73,13 +73,22 @@ class ClientCatalog:
         {'id': 'ado', 'title': "Alzheimer's Disease Ontology"}
     """
 
-    def __init__(self, cache_dir: str = DEFAULT_CACHE_DIR) -> None:
+    def __init__(
+        self,
+        cache_dir: str = DEFAULT_CACHE_DIR,
+        downloader: DownloaderPort | None = None,
+    ) -> None:
         """Initialize the ClientCatalog.
 
         Args:
             cache_dir (str, optional): Directory for caching catalog data. Defaults to DEFAULT_CACHE_DIR.
+            downloader (DownloaderPort | None, optional): Downloader adapter for remote resources. Defaults to None.
         """
-        self.__catalog_adapter = CatalogOntologies(cache_dir=Path(cache_dir))
+        self.__catalog_adapter = CatalogOntologies(
+            cache_dir=Path(cache_dir),
+            downloader=downloader,
+        )
+        self._downloader = downloader
 
     def load_catalog(self, force_download: bool = False) -> None:
         """Load the ontology catalog.
@@ -92,7 +101,8 @@ def load_catalog(self, force_download: bool = False) -> None:
             >>> catalog.load_catalog()
         """
         return self.__catalog_adapter.load_catalog(
-            force_download=force_download
+            force_download=force_download,
+            downloader=self._downloader,
         )
 
     def catalog_as_dict(self) -> dict:
@@ -218,14 +228,20 @@ class ClientOntology:
         [Term('Z', name='root')]
     """
 
-    def __init__(self, cache_dir: str = DEFAULT_CACHE_DIR) -> None:
+    def __init__(
+        self,
+        cache_dir: str = DEFAULT_CACHE_DIR,
+        downloader: DownloaderPort | None = None,
+    ) -> None:
         """Initialize the ClientOntology.
 
         Args:
             cache_dir (str, optional): Directory for caching ontology data. Defaults to DEFAULT_CACHE_DIR.
+            downloader (DownloaderPort | None, optional): Downloader adapter for remote resources. Defaults to None.
         """
         self._cache_dir = Path(cache_dir)
         self._ontology = None
+        self._downloader = downloader
         self._lookup_tables = None
         self._navigator = None
         self._relations = None
@@ -346,20 +362,28 @@ def load(
             >>> client.load(source="./tests/resources/dummy_ontology.obo")
         """
         logger.info(f'Loading ontology from source: {source} ...')
-        loader = ProntoLoaderAdapter(cache_dir=self._cache_dir)
+        logger.debug(
+            'Using downloader: %s',
+            type(downloader).__name__ if downloader else 'default',
+        )
+        loader = ProntoLoaderAdapter(
+            cache_dir=self._cache_dir, downloader=self._downloader
+        )
 
         path = Path(source)
         ontology = None
 
         # 1. Case 1: Local file exists
         if path.exists():
+            logger.debug('Resolved source type: file')
             logger.info(
                 f'Found local file at {path}, loading with ProntoLoaderAdapter...'
             )
             ontology = loader.load_from_file(file_path_ontology=path)
 
         # 2. Case 2: Provided source is a URL
         elif re.match(r'^https?://', source):
+            logger.debug('Resolved source type: url')
             logger.info(
                 f'Detected URL source, downloading ontology from {source}'
             )
@@ -368,7 +392,11 @@ def load(
 
         # 3. Case 3: Try OBO catalog (if file missing or simple ID)
         else:
-            catalog_client = ClientCatalog(cache_dir=self._cache_dir)
+            logger.debug('Resolved source type: catalog')
+            catalog_client = ClientCatalog(
+                cache_dir=self._cache_dir,
+                downloader=self._downloader,
+            )
             catalog_client.load_catalog()
             available = [
                 o['id'] for o in catalog_client.list_available_ontologies()
@@ -380,7 +408,9 @@ def load(
                     f"Ontology '{name_id}' found in catalog, downloading..."
                 )
                 ontology = loader.load_from_catalog(
-                    name_id=name_id, format='obo'
+                    name_id=name_id,
+                    format='obo',
+                    downloader=self._downloader,
                 )
             else:
                 msg = f"Ontology '{source}' not found as file, URL, or catalog entry."

ontograph/config/settings.py

@@ -11,6 +11,7 @@
     'PACKAGE_VERSION',
     'SUPPORTED_FORMATS_ONTOGRAPH',
     'DEFAULT_FORMAT_ONTOLOGY',
+    'DEFAULT_DOWNLOADER',
 ]
 
 # Package metadata from installed package
@@ -31,4 +32,7 @@
 SUPPORTED_FORMATS_ONTOGRAPH = ['obo', 'owl']
 DEFAULT_FORMAT_ONTOLOGY = 'obo'
 
+# Default downloader backend for remote resources ('pooch' or 'download_manager')
+DEFAULT_DOWNLOADER = 'pooch'
+
 # TODO: Ready for improvement