ahorn-loader 0.1.1__tar.gz → 0.2.0__tar.gz

ahorn_loader-0.2.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.3
+Name: ahorn-loader
+Version: 0.2.0
+Summary: Library and command-line application to interact with datasets in the Aachen Higher-Order Repository of Networks.
+Author: Florian Frantzen
+Author-email: Florian Frantzen <frantzen@netsci.rwth-aachen.de>
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: requests>=2.32.4
+Requires-Dist: typer>=0.16.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# `ahorn-loader`
+
+Library and command-line application to interact with datasets in [AHORN](https://ahorn.rwth-aachen.de/).
+
+<div align="center">
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
+[![license](https://badgen.net/github/license/netsci-rwth/ahorn-loader)](https://github.com/pyt-team/TopoNetX/blob/main/LICENSE)
+
+</div>
+
+## Usage
+
+`ahorn-loader` is both a command-line application and a Python package to interact with the AHORN repository for higher-order datasets.
+
+### Command-Line Usage
+
+To install and use `ahorn-loader` from the command line, you can run the following command:
+
+```bash
+uvx ahorn-loader [command] [args]
+```
+
+Commands include:
+- `ls`: List available datasets in AHORN.
+- `download`: Download a dataset from AHORN.
+- `validate`: Validate a specific dataset file (e.g., before adding it to AHORN).
+
+To get a full help of available commands and options, run `ahorn-loader --help`.
+
+### Python Package Usage
+
+To use `ahorn-loader` as a Python package, you can install it via `pip` (or some other package manager of your choice):
+
+```bash
+pip install ahorn-loader
+```
+
+Then, you can use it in your Python scripts:
+
+```python
+import ahorn_loader
+
+# Download a dataset:
+ahorn_loader.download_dataset("dataset_name", "target_path")
+
+# Download and read a dataset:
+# The dataset will be stored in your system's cache. For a more permanent storage
+# location, use `ahorn_loader.download_dataset` instead.
+with ahorn_loader.read_dataset("dataset_name") as dataset:
+    for line in dataset:
+        ...
+
+# Validate a specific dataset (e.g., before adding it to AHORN):
+ahorn_loader.validate("path_to_dataset_file")
+```
+
+## Funding
+
+<img align="right" width="200" src="https://raw.githubusercontent.com/netsci-rwth/ahorn/main/public/images/erc_logo.png">
+
+Funded by the European Union (ERC, HIGH-HOPeS, 101039827).
+Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency.
+Neither the European Union nor the granting authority can be held responsible for them.

ahorn_loader-0.2.0/README.md

@@ -0,0 +1,64 @@
+# `ahorn-loader`
+
+Library and command-line application to interact with datasets in [AHORN](https://ahorn.rwth-aachen.de/).
+
+<div align="center">
+
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](https://www.python.org/)
+[![license](https://badgen.net/github/license/netsci-rwth/ahorn-loader)](https://github.com/pyt-team/TopoNetX/blob/main/LICENSE)
+
+</div>
+
+## Usage
+
+`ahorn-loader` is both a command-line application and a Python package to interact with the AHORN repository for higher-order datasets.
+
+### Command-Line Usage
+
+To install and use `ahorn-loader` from the command line, you can run the following command:
+
+```bash
+uvx ahorn-loader [command] [args]
+```
+
+Commands include:
+- `ls`: List available datasets in AHORN.
+- `download`: Download a dataset from AHORN.
+- `validate`: Validate a specific dataset file (e.g., before adding it to AHORN).
+
+To get a full help of available commands and options, run `ahorn-loader --help`.
+
+### Python Package Usage
+
+To use `ahorn-loader` as a Python package, you can install it via `pip` (or some other package manager of your choice):
+
+```bash
+pip install ahorn-loader
+```
+
+Then, you can use it in your Python scripts:
+
+```python
+import ahorn_loader
+
+# Download a dataset:
+ahorn_loader.download_dataset("dataset_name", "target_path")
+
+# Download and read a dataset:
+# The dataset will be stored in your system's cache. For a more permanent storage
+# location, use `ahorn_loader.download_dataset` instead.
+with ahorn_loader.read_dataset("dataset_name") as dataset:
+    for line in dataset:
+        ...
+
+# Validate a specific dataset (e.g., before adding it to AHORN):
+ahorn_loader.validate("path_to_dataset_file")
+```
+
+## Funding
+
+<img align="right" width="200" src="https://raw.githubusercontent.com/netsci-rwth/ahorn/main/public/images/erc_logo.png">
+
+Funded by the European Union (ERC, HIGH-HOPeS, 101039827).
+Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency.
+Neither the European Union nor the granting authority can be held responsible for them.

{ahorn_loader-0.1.1 → ahorn_loader-0.2.0}/pyproject.toml

@@ -1,12 +1,24 @@
 [project]
 name = "ahorn-loader"
-version = "0.1.1"
+version = "0.2.0"
 description = "Library and command-line application to interact with datasets in the Aachen Higher-Order Repository of Networks."
 readme = "README.md"
 authors = [
-    { name = "Florian Frantzen", email = "florian.frantzen@cs.rwth-aachen.de" }
+    { name = "Florian Frantzen", email = "frantzen@netsci.rwth-aachen.de" }
 ]
-requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.11"
 dependencies = [
     "requests>=2.32.4",
     "typer>=0.16.0",
@@ -28,6 +40,7 @@ dev = [
 ]
 
 [tool.mypy]
+strict = true
 warn_redundant_casts = true
 warn_unreachable = true
 warn_unused_ignores = true
@@ -38,7 +51,7 @@ minversion = "7.0"
 addopts = ["-ra", "--showlocals", "--strict-markers", "--strict-config"]
 xfail_strict = true
 filterwarnings = ["error"]
-log_cli_level = "info"
+log_cli_level = "INFO"
 testpaths = ["tests"]
 
 [tool.ruff.format]

ahorn_loader-0.2.0/src/ahorn_loader/api.py

@@ -0,0 +1,199 @@
+"""Module to interact with the Ahorn dataset API."""
+
+import contextlib
+import gzip
+import json
+from collections.abc import Generator, Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TypedDict
+from urllib.parse import ParseResult, urlparse
+
+import requests
+
+from .utils import get_cache_dir
+
+__all__ = [
+    "download_dataset",
+    "load_dataset_data",
+    "load_datasets_data",
+    "read_dataset",
+]
+
+DATASET_API_URL = "https://ahorn.rwth-aachen.de/api/datasets.json"
+
+
+class AttachmentDict(TypedDict):
+    url: str
+    size: int
+
+
+class DatasetDict(TypedDict):
+    slug: str
+    title: str
+    tags: list[str]
+    attachments: dict[str, AttachmentDict]
+
+
+class DatasetsDataDict(TypedDict):
+    datasets: dict[str, DatasetDict]
+    time: str
+
+
+def load_datasets_data(*, cache_lifetime: int | None = None) -> dict[str, DatasetDict]:
+    """Load dataset data from the Ahorn API.
+
+    Parameters
+    ----------
+    cache_lifetime : int, optional
+        How long to reuse cached data in seconds. If not provided, the cache will not
+        be used.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary containing dataset information, where the keys are dataset slugs
+        and the values are dictionaries with dataset details such as title, tags, and
+        attachments.
+    """
+    datasets_data_cache = get_cache_dir() / "datasets.json"
+    if datasets_data_cache.exists() and cache_lifetime is not None:
+        cache_mtime = datetime.fromtimestamp(
+            datasets_data_cache.stat().st_mtime, tz=UTC
+        )
+        if (datetime.now(tz=UTC) - cache_mtime).total_seconds() < cache_lifetime:
+            with datasets_data_cache.open("r", encoding="utf-8") as cache_file:
+                cache: DatasetsDataDict = json.load(cache_file)
+                return cache["datasets"]
+
+    response = requests.get(DATASET_API_URL, timeout=10)
+    response.raise_for_status()
+
+    datasets_data_cache.parent.mkdir(parents=True, exist_ok=True)
+    with datasets_data_cache.open("w", encoding="utf-8") as cache_file:
+        cache_file.write(response.text)
+
+    response_json: DatasetsDataDict = response.json()
+    return response_json["datasets"]
+
+
+def load_dataset_data(slug: str, *, cache_lifetime: int | None = None) -> DatasetDict:
+    """Load data for a specific dataset by its slug.
+
+    Parameters
+    ----------
+    slug : str
+        The slug of the dataset to load.
+    cache_lifetime : int, optional
+        How long to reuse cached data in seconds. If not provided, the cache will not
+        be used.
+
+    Returns
+    -------
+    DatasetDict
+        Dictionary containing the dataset details.
+
+    Raises
+    ------
+    KeyError
+        If the dataset with the given `slug` does not exist.
+    """
+    datasets = load_datasets_data(cache_lifetime=cache_lifetime)
+
+    if slug not in datasets:
+        raise KeyError(f"Dataset with slug '{slug}' does not exist in AHORN.")
+
+    return datasets[slug]
+
+
+def download_dataset(
+    slug: str, folder: Path | str, *, cache_lifetime: int | None = None
+) -> Path:
+    """Download a dataset by its slug to the specified folder.
+
+    Parameters
+    ----------
+    slug : str
+        The slug of the dataset to download.
+    folder : Path | str
+        The folder where the dataset should be saved.
+    cache_lifetime : int, optional
+        How long to reuse cached data in seconds. If not provided, the cache will not
+        be used.
+
+    Returns
+    -------
+    Path
+        The path to the downloaded dataset file.
+
+    Raises
+    ------
+    KeyError
+        If the dataset with the given `slug` does not exist.
+    RuntimeError
+        If the dataset file could not be downloaded due to some error.
+    """
+    if isinstance(folder, str):
+        folder = Path(folder)
+
+    data = load_dataset_data(slug, cache_lifetime=cache_lifetime)
+    if "dataset" not in data["attachments"]:
+        raise RuntimeError(
+            f"Dataset '{slug}' does not contain required 'attachments/dataset' keys."
+        )
+    dataset_attachment = data["attachments"]["dataset"]
+
+    url: ParseResult = urlparse(dataset_attachment["url"])
+    folder.mkdir(parents=True, exist_ok=True)
+    filepath = folder / url.path.split("/")[-1]
+
+    response = requests.get(dataset_attachment["url"], timeout=10, stream=True)
+    response.raise_for_status()
+
+    with filepath.open("wb") as f:
+        for chunk in response.iter_content(chunk_size=8192):
+            if chunk:
+                f.write(chunk)
+
+    return filepath
+
+
+@contextlib.contextmanager
+def read_dataset(slug: str) -> Generator[Iterable[str], None, None]:
+    """Download and yield a context-managed file object for the dataset lines by slug.
+
+    The dataset file will be stored in your system cache and can be deleted according
+    to your system's cache policy. To ensure that costly re-downloads do not occur, use
+    the `download_dataset` function to store the dataset file at a more permanent
+    location.
+
+    Parameters
+    ----------
+    slug : str
+        The slug of the dataset to download.
+
+    Returns
+    -------
+    Context manager yielding an open file object (iterator over lines).
+
+    Raises
+    ------
+    KeyError
+        If the dataset with the given `slug` does not exist.
+    RuntimeError
+        If the dataset file could not be downloaded due to other errors.
+
+    Examples
+    --------
+    >>> import ahorn_loader
+    >>> with ahorn_loader.read_dataset("contact-high-school") as f:
+    >>>     for line in f:
+    >>>         ...
+    """
+    filepath = download_dataset(slug, get_cache_dir())
+    if filepath.suffix == ".gz":
+        with gzip.open(filepath, mode="rt", encoding="utf-8") as f:
+            yield f
+    else:
+        with filepath.open("r", encoding="utf-8") as f:
+            yield f

{ahorn_loader-0.1.1 → ahorn_loader-0.2.0}/src/ahorn_loader/cli.py

@@ -58,6 +58,7 @@ def download(
         typer.echo(f"Failed to download dataset: {e}")
         raise typer.Exit(code=1) from e
 
+
 @app.command()
 def validate(
     path: Annotated[

ahorn_loader-0.2.0/src/ahorn_loader/utils/__init__.py

@@ -0,0 +1,3 @@
+"""Utility functions used internally in `ahorn-loader`."""
+
+from .cache import *

ahorn_loader-0.2.0/src/ahorn_loader/utils/cache.py

@@ -0,0 +1,29 @@
+"""Module with cache-related utility functions."""
+
+import os
+import sys
+from pathlib import Path
+
+__all__ = ["get_cache_dir"]
+
+
+def get_cache_dir() -> Path:
+    """Return an appropriate cache location for the current platform.
+
+    Returns
+    -------
+    pathlib.Path
+        Platform-dependent cache directory.
+    """
+    match sys.platform:
+        case "win32":
+            base = os.getenv("LOCALAPPDATA") or Path("~\\AppData\\Local").expanduser()
+            return Path(base) / "ahorn-loader" / "Cache"
+        case "darwin":
+            return Path.home() / "Library" / "Caches" / "ahorn-loader"
+        case _:
+            # Linux and other Unix
+            xdg = os.getenv("XDG_CACHE_HOME")
+            if xdg:
+                return Path(xdg) / "ahorn-loader"
+            return Path.home() / ".cache" / "ahorn-loader"

ahorn_loader-0.1.1/PKG-INFO

@@ -1,53 +0,0 @@
-Metadata-Version: 2.3
-Name: ahorn-loader
-Version: 0.1.1
-Summary: Library and command-line application to interact with datasets in the Aachen Higher-Order Repository of Networks.
-Author: Florian Frantzen
-Author-email: Florian Frantzen <florian.frantzen@cs.rwth-aachen.de>
-Requires-Dist: requests>=2.32.4
-Requires-Dist: typer>=0.16.0
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
-# `ahorn-loader`
-
-Library and command-line application to interact with datasets in [AHORN](https://ahorn.rwth-aachen.de/).
-
-## Usage
-
-`ahorn-loader` is both a command-line application and a Python package to interact with the AHORN repository for higher-order datasets.
-
-### Command-Line Usage
-
-To install and use `ahorn-loader` from the command line, you can run the following command:
-
-```bash
-uvx ahorn-loader [command] [args]
-```
-
-Commands include:
-- `ls`: List available datasets in AHORN.
-- `download`: Download a dataset from AHORN.
-- `validate`: Validate a specific dataset file (e.g., before adding it to AHORN).
-
-To get a full help of available commands and options, run `ahorn-loader --help`.
-
-### Python Package Usage
-
-To use `ahorn-loader` as a Python package, you can install it via `pip` (or some other package manager of your choice):
-
-```bash
-pip install ahorn-loader
-```
-
-Then, you can use it in your Python scripts:
-
-```python
-import ahorn_loader
-
-# download a dataset
-ahorn_loader.download('dataset_name', 'target_path')
-
-# validate a specific dataset (e.g., before adding it to AHORN)
-ahorn_loader.validate('path_to_dataset_file')
-```

ahorn_loader-0.1.1/README.md

@@ -1,42 +0,0 @@
-# `ahorn-loader`
-
-Library and command-line application to interact with datasets in [AHORN](https://ahorn.rwth-aachen.de/).
-
-## Usage
-
-`ahorn-loader` is both a command-line application and a Python package to interact with the AHORN repository for higher-order datasets.
-
-### Command-Line Usage
-
-To install and use `ahorn-loader` from the command line, you can run the following command:
-
-```bash
-uvx ahorn-loader [command] [args]
-```
-
-Commands include:
-- `ls`: List available datasets in AHORN.
-- `download`: Download a dataset from AHORN.
-- `validate`: Validate a specific dataset file (e.g., before adding it to AHORN).
-
-To get a full help of available commands and options, run `ahorn-loader --help`.
-
-### Python Package Usage
-
-To use `ahorn-loader` as a Python package, you can install it via `pip` (or some other package manager of your choice):
-
-```bash
-pip install ahorn-loader
-```
-
-Then, you can use it in your Python scripts:
-
-```python
-import ahorn_loader
-
-# download a dataset
-ahorn_loader.download('dataset_name', 'target_path')
-
-# validate a specific dataset (e.g., before adding it to AHORN)
-ahorn_loader.validate('path_to_dataset_file')
-```

ahorn_loader-0.1.1/src/ahorn_loader/api.py

@@ -1,115 +0,0 @@
-"""Module to interact with the Ahorn dataset API."""
-
-import json
-from datetime import UTC, datetime
-from pathlib import Path
-from typing import Any
-from urllib.parse import ParseResult, urlparse
-
-import requests
-
-__all__ = ["download_dataset", "load_dataset_data", "load_datasets_data"]
-
-DATASET_API_URL = "https://ahorn.rwth-aachen.de/api/datasets.json"
-CACHE_PATH = Path(__file__).parent.parent.parent / "cache" / "datasets.json"
-
-
-def load_datasets_data(*, cache_lifetime: int | None = None) -> dict[str, Any]:
-    """Load dataset data from the Ahorn API.
-
-    Parameters
-    ----------
-    cache_lifetime : int, optional
-        How long to reuse cached data in seconds. If not provided, the cache will not
-        be used.
-
-    Returns
-    -------
-    dict[str, Any]
-        Dictionary containing dataset information, where the keys are dataset slugs
-        and the values are dictionaries with dataset details such as title, tags, and
-        attachments.
-    """
-    if CACHE_PATH.exists() and cache_lifetime is not None:
-        with CACHE_PATH.open("r", encoding="utf-8") as cache_file:
-            cache = json.load(cache_file)
-        if (
-            cache.get("time")
-            and (
-                datetime.now(tz=UTC) - datetime.fromisoformat(cache["time"])
-            ).total_seconds()
-            < cache_lifetime
-        ):
-            return cache["datasets"]
-
-    response = requests.get(DATASET_API_URL, timeout=10)
-    response.raise_for_status()
-
-    CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
-    with CACHE_PATH.open("w", encoding="utf-8") as cache_file:
-        cache_file.write(response.text)
-
-    return response.json()["datasets"]
-
-
-def load_dataset_data(
-    slug: str, *, cache_lifetime: int | None = None
-) -> dict[str, Any]:
-    """Load data for a specific dataset by its slug.
-
-    Parameters
-    ----------
-    slug : str
-        The slug of the dataset to load.
-    cache_lifetime : int, optional
-        How long to reuse cached data in seconds. If not provided, the cache will not
-        be used.
-
-    Returns
-    -------
-    dict[str, Any]
-        Dictionary containing the dataset details.
-    """
-    datasets = load_datasets_data(cache_lifetime=cache_lifetime)
-    if "error" in datasets:
-        return {"error": datasets["error"]}
-
-    return datasets.get(slug, {"error": f"Dataset '{slug}' not found."})
-
-
-def download_dataset(
-    slug: str, folder: Path | str, *, cache_lifetime: int | None = None
-) -> None:
-    """Download a dataset by its slug to the specified folder.
-
-    Parameters
-    ----------
-    slug : str
-        The slug of the dataset to download.
-    folder : Path | str
-        The folder where the dataset should be saved.
-    cache_lifetime : int, optional
-        How long to reuse cached data in seconds. If not provided, the cache will not
-        be used.
-    """
-    if isinstance(folder, str):
-        folder = Path(folder)
-
-    data = load_dataset_data(slug, cache_lifetime=cache_lifetime)
-    if "error" in data:
-        raise ValueError(f"Error loading dataset '{slug}': {data['error']}")
-    if "attachments" not in data or "dataset" not in data["attachments"]:
-        raise KeyError(f"Dataset '{slug}' does not contain required 'attachments/dataset' keys.")
-    dataset_attachment = data["attachments"]["dataset"]
-
-    url: ParseResult = urlparse(dataset_attachment["url"])
-    folder.mkdir(parents=True, exist_ok=True)
-    filepath = folder / url.path.split("/")[-1]
-
-    response = requests.get(dataset_attachment["url"], timeout=10, stream=True)
-    response.raise_for_status()
-
-    with filepath.open("wb") as f:
-        for chunk in response.iter_content(chunk_size=8192):
-            if chunk:
-                f.write(chunk)