dataflux-core 0.1.0__py3-none-any.whl

dataflux/__init__.py

@@ -0,0 +1,4 @@
+from .__version__ import __version__ as version
+from .flux import flux
+
+__all__ = ("version", "flux")

dataflux/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

dataflux/cache.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from dataflux.config import DATAFLUX_CACHE
+from dataflux.utils.filesystem import ensure_dir
+
+
+class Cache:
+    """
+    Generic JSON cache manager for DataFlux.
+
+    Examples
+    --------
+    >>> cache.write("search/iris", data)
+    >>> cache.read("search/iris")
+    >>> cache.exists("search/iris")
+    """
+
+    def __init__(self, root: str | Path = DATAFLUX_CACHE):
+        self.root = ensure_dir(root)
+
+    # -------------------------------------------------------------------------
+    # Internal
+    # -------------------------------------------------------------------------
+
+    def _path(self, key: str) -> Path:
+        """
+        Convert a cache key into a JSON file path.
+
+        Example
+        -------
+        search/iris -> ~/.cache/dataflux/search/iris.json
+        """
+        path = self.root / Path(key).with_suffix(".json")
+        ensure_dir(path.parent)
+        return path
+
+    # -------------------------------------------------------------------------
+    # Public API
+    # -------------------------------------------------------------------------
+
+    def exists(self, key: str) -> bool:
+        """Return True if a cache entry exists."""
+        return self._path(key).exists()
+
+    def read(self, key: str, default: Any = None) -> Any:
+        """
+        Read cached JSON data.
+
+        Returns
+        -------
+        Cached object or `default` if the key doesn't exist.
+        """
+        path = self._path(key)
+
+        if not path.exists():
+            return default
+
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+
+    def write(self, key: str, value: Any) -> Path:
+        """
+        Write JSON-serializable data to cache.
+        """
+        path = self._path(key)
+
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(
+                value,
+                f,
+                indent=2,
+                ensure_ascii=False,
+            )
+
+        return path
+
+    def delete(self, key: str) -> bool:
+        """
+        Delete a cached object.
+        """
+        path = self._path(key)
+
+        if not path.exists():
+            return False
+
+        path.unlink()
+        return True
+
+    def clear(self) -> None:
+        """
+        Remove every cached object.
+        """
+        shutil.rmtree(self.root, ignore_errors=True)
+        ensure_dir(self.root)
+
+    def list(self, pattern: str = "**/*.json") -> list[str]:
+        """
+        List cached keys.
+
+        Examples
+        --------
+        >>> cache.list()
+        >>> cache.list("search/*.json")
+        """
+        return sorted(
+            str(path.relative_to(self.root).with_suffix(""))
+            for path in self.root.glob(pattern)
+        )
+
+    def size(self) -> int:
+        """
+        Return the total number of cached objects.
+        """
+        return len(self.list())
+
+
+cache = Cache()

dataflux/config.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+DATAFLUX_CACHE = Path.home() / ".dataflux"
+
+UCI_CACHE = DATAFLUX_CACHE / "uci"
+KAGGLE_CACHE = DATAFLUX_CACHE / "kaggle"
+HF_CACHE = DATAFLUX_CACHE / "huggingface"
+TORCHVISION_CACHE = DATAFLUX_CACHE / "torchvision"
+TFDS_CACHE = DATAFLUX_CACHE / "tensorflow"
+
+for cache in (
+    UCI_CACHE,
+    KAGGLE_CACHE,
+    HF_CACHE,
+    TORCHVISION_CACHE,
+    TFDS_CACHE,
+):
+    cache.mkdir(parents=True, exist_ok=True)

dataflux/display/console.py

@@ -0,0 +1,4 @@
+from rich.console import Console
+from dataflux.display.theme import DATAFLUX_THEME
+
+console = Console(theme=DATAFLUX_THEME)

dataflux/display/info.py

@@ -0,0 +1,150 @@
+from collections.abc import Mapping, Sequence
+from textwrap import fill
+
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from dataflux.display.console import console
+from dataflux.models.dataset import DatasetInfo
+
+
+DESCRIPTION_LIMIT = 600
+
+
+def _truncate(text: str | None) -> str | None:
+    """Truncate long descriptions for prettier display."""
+    if not text:
+        return None
+
+    text = " ".join(text.split())
+
+    if len(text) <= DESCRIPTION_LIMIT:
+        return fill(text, width=80)
+
+    return (
+        fill(text[:DESCRIPTION_LIMIT].rsplit(" ", 1)[0], width=80)
+        + "\n\n[dim]... (description truncated)[/dim]"
+    )
+
+
+def _format(value):
+    """Pretty-format common Python objects."""
+
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        return "[success]Yes[/success]" if value else "[error]No[/error]"
+
+    if isinstance(value, Mapping):
+        return "\n".join(
+            f"• {k}: {v}"
+            for k, v in value.items()
+        )
+
+    if (
+        isinstance(value, Sequence)
+        and not isinstance(value, (str, bytes))
+    ):
+        if len(value) == 0:
+            return None
+
+        return "\n".join(
+            f"• {item}"
+            for item in value
+        )
+
+    return str(value)
+
+
+def _add_row(table: Table, label: str, value) -> None:
+    """Skip empty values automatically."""
+
+    value = _format(value)
+
+    if value is None:
+        return
+
+    table.add_row(label, value)
+
+
+def display_info(info: DatasetInfo) -> None:
+    """Pretty-print DatasetInfo."""
+
+    # -------------------------------------------------------------------------
+    # Header
+    # -------------------------------------------------------------------------
+
+    console.print(
+        Panel.fit(
+            Text(info.name, style="title"),
+            subtitle=f"[subtitle]{info.provider} • {info.id}[/subtitle]",
+            border_style="panel",
+        )
+    )
+
+    # -------------------------------------------------------------------------
+    # General Information
+    # -------------------------------------------------------------------------
+
+    table = Table(
+        title="[header]General Information[/header]",
+        show_header=False,
+        expand=True,
+        box=None,
+    )
+
+    table.add_column(style="label", width=20)
+    table.add_column(style="value")
+
+    _add_row(table, "Provider", info.provider)
+    _add_row(table, "Dataset ID", info.id)
+    _add_row(table, "Instances", info.instances)
+    _add_row(table, "Features", info.features)
+    _add_row(table, "Tasks", info.tasks)
+    _add_row(table, "Target", info.target)
+    _add_row(table, "Missing Values", info.has_missing_values)
+    _add_row(table, "URL", info.url)
+
+    console.print(table)
+
+    # -------------------------------------------------------------------------
+    # Description
+    # -------------------------------------------------------------------------
+
+    description = _truncate(info.description)
+
+    if description:
+        console.print(
+            Panel(
+                description,
+                title="[description]Description[/description]",
+                border_style="description",
+            )
+        )
+
+    # -------------------------------------------------------------------------
+    # Additional Information
+    # -------------------------------------------------------------------------
+
+    if info.extra:
+
+        extra = Table(
+            title="[header]Additional Information[/header]",
+            show_header=False,
+            expand=True,
+            box=None,
+        )
+
+        extra.add_column(style="warning", width=25)
+        extra.add_column(style="value")
+
+        for key, value in info.extra.items():
+            _add_row(
+                extra,
+                key.replace("_", " ").title(),
+                value,
+            )
+
+        console.print(extra)

dataflux/display/search.py

@@ -0,0 +1,122 @@
+from textwrap import shorten
+
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from dataflux.display.console import console
+
+
+DESCRIPTION_WIDTH = 60
+
+
+def _truncate(text: str | None) -> str:
+    """Truncate long descriptions cleanly."""
+    if not text:
+        return "-"
+
+    return shorten(
+        " ".join(text.split()),
+        width=DESCRIPTION_WIDTH,
+        placeholder="...",
+    )
+
+
+def display_search(results: list, limit: int = 10) -> None:
+    """
+    Pretty-print search results using Rich.
+    """
+
+    if not results:
+        console.print(
+            Panel(
+                "[error]No datasets found.[/error]",
+                title="[header]Search Results[/header]",
+                border_style="error",
+            )
+        )
+        return
+
+    # -------------------------------------------------------------------------
+    # Single Result
+    # -------------------------------------------------------------------------
+
+    if len(results) == 1:
+        result = results[0]
+
+        text = Text()
+
+        text.append("Name: ", style="label")
+        text.append(f"{result.name}\n", style="value")
+
+        text.append("Provider: ", style="label")
+        text.append(f"{result.provider}\n", style="provider")
+
+        text.append("ID: ", style="label")
+        text.append(f"{result.id}\n", style="value")
+
+        if result.description:
+            text.append("Description: ", style="label")
+            text.append(result.description, style="value")
+
+        if getattr(result, "match_score", None) is not None:
+            text.append("\nMatch Score: ", style="label")
+            text.append(
+                f"{result.match_score:.2f}",
+                style="highlight",
+            )
+
+        console.print(
+            Panel(
+                text,
+                title="[header]Search Result[/header]",
+                border_style="panel",
+            )
+        )
+        return
+
+    # -------------------------------------------------------------------------
+    # Multiple Results
+    # -------------------------------------------------------------------------
+
+    display_results = results[:limit]
+
+    table = Table(
+        title=f"[header]Search Results ({len(display_results)} of {len(results)})[/header]",
+        show_lines=False,
+        expand=True,
+    )
+
+    table.add_column("#", justify="right", style="label", no_wrap=True)
+    table.add_column("Name", style="title")
+    table.add_column("Provider", style="provider")
+    table.add_column("ID", style="value")
+    table.add_column("Description", style="dim")
+
+    # Uncomment later if match_score becomes public.
+    # table.add_column("Score", justify="right", style="highlight")
+
+    for index, result in enumerate(display_results, start=1):
+        table.add_row(
+            str(index),
+            result.name,
+            result.provider,
+            str(result.id),
+            _truncate(result.description),
+            # f"{result.match_score:.2f}" if result.match_score else "-",
+        )
+
+    console.print(table)
+
+    # -------------------------------------------------------------------------
+    # Footer
+    # -------------------------------------------------------------------------
+
+    if len(results) > limit:
+        console.print(
+            f"[dim]Showing {len(display_results)} of {len(results)} matching datasets.[/dim]"
+        )
+        console.print(
+            "[dim]Use [bold]limit=...[/bold] to display more results or "
+            "[bold]display=False[/bold] to suppress console output.[/dim]"
+        )

dataflux/display/theme.py

@@ -0,0 +1,32 @@
+from rich.theme import Theme
+
+DATAFLUX_THEME = Theme(
+    {
+        # General
+        "header": "bold cyan",
+        "title": "bold bright_cyan",
+        "subtitle": "dim cyan",
+
+        # Tables
+        "label": "bold cyan",
+        "value": "white",
+
+        # Status
+        "success": "bold green",
+        "warning": "bold yellow",
+        "error": "bold red",
+        "info": "cyan",
+
+        # Panels
+        "panel": "cyan",
+        "description": "green",
+        "extra": "yellow",
+
+        # Search
+        "provider": "magenta",
+        "highlight": "bold bright_green",
+
+        # Misc
+        "dim": "dim",
+    }
+)

dataflux/display/utils.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from textwrap import fill, shorten
+
+
+# ============================================================================
+# Constants
+# ============================================================================
+
+DESCRIPTION_LIMIT = 600
+DESCRIPTION_WIDTH = 60
+
+
+# ============================================================================
+# Text Formatting
+# ============================================================================
+
+def truncate_description(
+    text: str | None,
+    *,
+    limit: int = DESCRIPTION_LIMIT,
+    width: int = 80,
+) -> str | None:
+    """
+    Truncate long descriptions for panels.
+    """
+
+    if not text:
+        return None
+
+    text = " ".join(text.split())
+
+    if len(text) <= limit:
+        return fill(text, width=width)
+
+    return (
+        fill(text[:limit].rsplit(" ", 1)[0], width=width)
+        + "\n\n[dim]... (description truncated)[/dim]"
+    )
+
+
+def truncate_text(
+    text: str | None,
+    *,
+    width: int = DESCRIPTION_WIDTH,
+) -> str:
+    """
+    Truncate text for table cells.
+    """
+
+    if not text:
+        return "-"
+
+    return shorten(
+        " ".join(text.split()),
+        width=width,
+        placeholder="...",
+    )
+
+
+# ============================================================================
+# Value Formatting
+# ============================================================================
+
+def format_value(value):
+    """
+    Pretty-format common Python objects for Rich.
+    """
+
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        return "[success]Yes[/success]" if value else "[error]No[/error]"
+
+    if isinstance(value, Mapping):
+        return "\n".join(
+            f"• {k}: {v}"
+            for k, v in value.items()
+        )
+
+    if (
+        isinstance(value, Sequence)
+        and not isinstance(value, (str, bytes))
+    ):
+        if len(value) == 0:
+            return None
+
+        return "\n".join(
+            f"• {item}"
+            for item in value
+        )
+
+    return str(value)
+
+
+def add_row(table, label: str, value) -> None:
+    """
+    Add a row to a Rich table while skipping empty values.
+    """
+
+    value = format_value(value)
+
+    if value is None:
+        return
+
+    table.add_row(label, value)
+
+
+# ============================================================================
+# Provider Display Names
+# ============================================================================
+
+_PROVIDER_NAMES = {
+    "uci": "UCI Machine Learning Repository",
+    "sklearn": "Scikit-Learn",
+    "huggingface": "Hugging Face",
+    "kaggle": "Kaggle",
+    "torchvision": "TorchVision",
+    "pyg": "PyTorch Geometric",
+    "seaborn": "Seaborn",
+    "statsmodels": "StatsModels",
+    "vega": "Vega Datasets",
+    "worldbank": "World Bank",
+}
+
+
+def provider_name(provider: str) -> str:
+    """
+    Convert an internal provider identifier into a display name.
+
+    Examples
+    --------
+    >>> provider_name("sklearn")
+    'Scikit-Learn'
+    """
+    return _PROVIDER_NAMES.get(provider.lower(), provider.title())