mapkgsutils 0.0.2__py3-none-any.whl

mapkgsutils/exports.py

@@ -0,0 +1,180 @@
+"""Generic mapping-set export functions (SSSOM, RDF, JSON, OWL)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sssom import MappingSetDataFrame
+
+if TYPE_CHECKING:
+    from mapkgsutils.parsers.base import BaseMappingSet
+
+__all__ = [
+    "write_json",
+    "write_owl",
+    "write_rdf",
+    "write_sssom",
+]
+
+
+def write_sssom(
+    mapping_set: BaseMappingSet,
+    output_path: Path | str,
+) -> Path:
+    """Write a mapping set to an SSSOM TSV file.
+
+    Args:
+        mapping_set: The mapping set to write.
+        output_path: Destination ``.sssom.tsv`` file path.
+
+    Returns:
+        Path to the written file.
+    """
+    import codecs
+    import re
+    from typing import cast
+
+    import curies
+    from sssom.parsers import to_mapping_set_dataframe  # type: ignore[attr-defined]
+    from sssom.sssom_document import MappingSetDocument
+    from sssom.writers import write_table
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Build a curies.Converter from the curie_map stored on the mapping set.
+    # Using Converter(records=...) preserves prefix casing exactly as declared
+    # and handles pydantic-wrapped Prefix objects (which expose .prefix_url).
+    raw_curie_map: object = mapping_set.curie_map or {}
+    records: list[curies.Record] = []
+    if isinstance(raw_curie_map, dict):
+        for k, v in raw_curie_map.items():
+            if isinstance(v, str):
+                uri_prefix: str = v
+            elif hasattr(v, "prefix_url"):
+                uri_prefix = cast(str, v.prefix_url)
+            else:
+                continue
+            records.append(curies.Record(prefix=k, uri_prefix=uri_prefix))
+    converter = curies.Converter(records=records)
+    doc = MappingSetDocument(mapping_set=mapping_set, converter=converter)
+    msdf = to_mapping_set_dataframe(doc)
+
+    with output_path.open("w", encoding="utf-8") as f:
+        write_table(msdf, f)
+
+    # Fix escaped unicode in YAML header (sssom issue)
+    content = output_path.read_text(encoding="utf-8")
+    content = re.sub(
+        r"\\x([0-9a-fA-F]{2})",
+        lambda m: codecs.decode(bytes([int(m.group(1), 16)]), "latin-1"),
+        content,
+    )
+    output_path.write_text(content, encoding="utf-8")
+
+    return output_path
+
+
+def _to_msdf_via_sssom_parser(mapping_set: BaseMappingSet) -> MappingSetDataFrame | None:
+    """Write to a temporary SSSOM TSV then parse back with sssom's own parser.
+
+    Args:
+        mapping_set: The mapping set to convert.
+
+    Returns:
+        A fully-validated ``MappingSetDataFrame`` ready for RDF/JSON/OWL serialisation.
+    """
+    import tempfile
+
+    from sssom.parsers import parse_sssom_table
+
+    with tempfile.NamedTemporaryFile(
+        suffix=".sssom.tsv", mode="w", encoding="utf-8", delete=False
+    ) as tmp:
+        tmp_path = Path(tmp.name)
+
+    try:
+        write_sssom(mapping_set, tmp_path)
+        return parse_sssom_table(str(tmp_path))
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def write_rdf(
+    mapping_set: BaseMappingSet,
+    output_path: Path | str,
+    serialisation: str = "turtle",
+) -> Path:
+    """Write a mapping set to an RDF file.
+
+    Args:
+        mapping_set: The mapping set to write.
+        output_path: Destination file path (e.g. ``mappings.ttl``).
+        serialisation: RDFLib serialisation format.
+
+    Returns:
+        Path to the written file.
+    """
+    from sssom.writers import write_rdf as _sssom_write_rdf
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    msdf = _to_msdf_via_sssom_parser(mapping_set)
+    if msdf is None:
+        raise ValueError("Failed to parse mapping set for RDF serialisation.")
+    with output_path.open("w", encoding="utf-8") as f:
+        _sssom_write_rdf(msdf, f, serialisation=serialisation)
+    return output_path
+
+
+def write_json(
+    mapping_set: BaseMappingSet,
+    output_path: Path | str,
+) -> Path:
+    """Write a mapping set to an SSSOM JSON file.
+
+    Args:
+        mapping_set: The mapping set to write.
+        output_path: Destination file path (e.g. ``mappings.json``).
+
+    Returns:
+        Path to the written file.
+    """
+    from sssom.writers import write_json as _sssom_write_json
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    msdf = _to_msdf_via_sssom_parser(mapping_set)
+    if msdf is None:
+        raise ValueError("Failed to parse mapping set for JSON serialisation.")
+    with output_path.open("w", encoding="utf-8") as f:
+        _sssom_write_json(msdf, f)
+    return output_path
+
+
+def write_owl(
+    mapping_set: BaseMappingSet,
+    output_path: Path | str,
+    serialisation: str = "turtle",
+) -> Path:
+    """Write a mapping set to an OWL/RDF file (default: Turtle).
+
+    Args:
+        mapping_set: The mapping set to write.
+        output_path: Destination file path (e.g. ``mappings_owl.ttl``).
+        serialisation: RDFLib serialisation format.
+
+    Returns:
+        Path to the written file.
+    """
+    from sssom.writers import write_owl as _sssom_write_owl
+
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    msdf = _to_msdf_via_sssom_parser(mapping_set)
+    if msdf is None:
+        raise ValueError("Failed to parse mapping set for OWL serialisation.")
+    with output_path.open("w", encoding="utf-8") as f:
+        _sssom_write_owl(msdf, f, serialisation=serialisation)
+    return output_path

mapkgsutils/logging.py

@@ -0,0 +1,65 @@
+"""Logging configuration for mapkgsutils.
+
+This module provides a centralized logger for the package.
+By default, only CRITICAL messages are shown. Use set_log_level()
+to adjust verbosity.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+__all__ = [
+    "LOG_LEVELS",
+    "logger",
+    "set_log_level",
+]
+
+# Package logger
+logger = logging.getLogger("mapkgsutils")
+
+# Default to CRITICAL (minimal output)
+logger.setLevel(logging.CRITICAL)
+
+# Add a handler if none exists
+if not logger.handlers:
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    logger.addHandler(handler)
+
+# Map of log level names to logging constants
+LOG_LEVELS: dict[str, int] = {
+    "critical": logging.CRITICAL,
+    "error": logging.ERROR,
+    "warning": logging.WARNING,
+    "warn": logging.WARNING,
+    "info": logging.INFO,
+    "debug": logging.DEBUG,
+}
+
+
+def set_log_level(level: str | int) -> None:
+    """Set the logging level for mapkgsutils.
+
+    Args:
+        level: Log level as string ('debug', 'info', 'warning', 'error', 'critical')
+               or as an int (logging.DEBUG, logging.INFO, etc.)
+
+    Example:
+        >>> from mapkgsutils.logging import set_log_level
+        >>> set_log_level("warning")  # Show warnings and above
+        >>> set_log_level("debug")  # Show all messages
+    """
+    if isinstance(level, str):
+        level_int = LOG_LEVELS.get(level.lower())
+        if level_int is None:
+            raise ValueError(f"Unknown log level: {level}. Available: {list(LOG_LEVELS.keys())}")
+        logger.setLevel(level_int)
+    else:
+        logger.setLevel(level)

mapkgsutils/parsers/__init__.py

@@ -0,0 +1 @@
+"""Datasource-agnostic parser and downloader framework."""