Add utils subpackage and data loader from pypath_common

Migrate general-purpose utility functions from pypath_common._misc,
_constants, and _process into pkg_infra.utils. This allows packages
(cachedir, dlmachine, omnipath-utils) to depend on pkg-infra instead
of the soon-to-be-retired pypath_common.

- utils/constants.py: SIMPLE_TYPES, LIST_LIKE, BOOLEAN_*, etc.
- utils/_process.py: swap_dict
- utils/_misc.py: ~80 functions (to_set, first, md5, ext, etc.)
- data/__init__.py: simplified package data loader (load, path, builtins)
- numpy, psutil, tabulate made optional imports
- Bump version to 0.1.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: deeenes

.bumpversion.cfg

@@ -1,7 +1,7 @@
 [bumpversion]
-current_version = 0.0.1
+current_version = 0.1.0
 commit = True
 tag = True
-files = pyproject.toml pkg_infra/_metadata.py
+files = pyproject.toml src/pkg_infra/_metadata.py
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)
 serialize = {major}.{minor}.{patch}

pyproject.toml

@@ -48,7 +48,7 @@ name = "pkg-infra"
 # ]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.0.2"
+version = "0.1.0"
 
 [project.optional-dependencies]
 dev = [

src/pkg_infra/_metadata.py

@@ -23,7 +23,7 @@
 
 import toml
 
-_VERSION = '0.0.1'
+_VERSION = '0.1.0'
 
 
 def get_metadata() -> dict:

src/pkg_infra/data/__init__.py

@@ -0,0 +1,165 @@
+"""Access built-in data files shipped with Python packages.
+
+Provides a simple API to load YAML, JSON, and other data files from a
+package's ``data/`` or ``_data/`` subdirectory.
+
+Example::
+
+    from pkg_infra.data import load
+
+    # Load data from the calling package's data/ directory
+    config = load('default_config.yaml')
+
+    # Load data from a specific package
+    ids = load('id_types.json', module='omnipath_utils')
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+import os
+import json
+import pathlib as pl
+import functools
+import collections
+import logging
+
+import yaml
+
+__all__ = ['builtins', 'load', 'path']
+
+_logger = logging.getLogger(__name__)
+
+_FORMATS = {
+    'json': functools.partial(
+        json.load,
+        object_pairs_hook=collections.OrderedDict,
+    ),
+    'yaml': functools.partial(yaml.load, Loader=yaml.FullLoader),
+    'txt': None,
+    '': None,
+}
+
+
+def _caller_module() -> str:
+    """Get the name of the module that called this function."""
+
+    import inspect
+
+    frame = inspect.currentframe()
+
+    try:
+        caller = frame.f_back.f_back
+        return caller.f_globals.get('__name__', '__main__').split('.')[0]
+    finally:
+        del frame
+
+
+def _module_datadir(module: str) -> pl.Path | None:
+    """Find the data directory for a module."""
+
+    import importlib
+
+    try:
+        mod = importlib.import_module(module)
+    except ModuleNotFoundError:
+        return None
+
+    if mod_path := getattr(mod, '__path__', None):
+        base = pl.Path(mod_path[0])
+    elif mod_file := getattr(mod, '__file__', None):
+        base = pl.Path(mod_file).parent
+    else:
+        return None
+
+    for dirname in ('data', '_data'):
+        datadir = base / dirname
+        if datadir.is_dir():
+            return datadir
+
+    return None
+
+
+def path(label: str, module: str | None = None) -> pl.Path | None:
+    """Find path to a data file shipped with a package.
+
+    Args:
+        label: Filename or label of a built-in dataset.
+        module: Package name. Defaults to the calling package.
+
+    Returns:
+        Path to the file, or None if not found.
+    """
+
+    if os.path.exists(label):
+        return pl.Path(label).absolute()
+
+    available = builtins(module or _caller_module())
+    stem = label.rsplit('.', maxsplit=1)[0] if '.' in label else label
+    return available.get(label) or available.get(stem)
+
+
+def load(
+    label: str,
+    module: str | None = None,
+    reader: Callable | None = None,
+    **kwargs,
+) -> Any:
+    """Load a data file shipped with a package.
+
+    Args:
+        label: Filename or label of a built-in dataset.
+        module: Package name. Defaults to the calling package.
+        reader: Custom reader function. Auto-detected from extension if None.
+        kwargs: Extra arguments passed to the reader.
+
+    Returns:
+        The loaded data (typically dict or list).
+    """
+
+    module = module or _caller_module()
+
+    if _path := path(label, module):
+
+        if not reader:
+            ext = _path.name.rsplit('.', maxsplit=1)[-1].lower()
+            if ext == 'tsv':
+                kwargs['sep'] = '\t'
+            reader = _FORMATS.get(ext, lambda x: x.readlines())
+
+        _logger.debug(
+            'Loading built-in data `%s` from module `%s`; path: `%s`.',
+            label, module, _path,
+        )
+
+        with open(_path) as fp:
+            return reader(fp, **kwargs)
+
+    else:
+        _logger.debug(
+            'Could not find built-in data `%s` in module `%s`.', label, module,
+        )
+
+
+def builtins(module: str | None = None) -> dict[str, pl.Path]:
+    """List built-in data files available in a package.
+
+    Args:
+        module: Package name. Defaults to the calling package.
+
+    Returns:
+        Dict mapping filenames (without extension) to full paths.
+    """
+
+    module = module or _caller_module()
+    datadir = _module_datadir(module)
+
+    if not datadir or not datadir.is_dir():
+        return {}
+
+    return {
+        str((pl.Path(d) / pl.Path(f).stem).relative_to(datadir)): pl.Path(d) / f
+        for d, dirs, files in os.walk(datadir)
+        for f in files
+        if pl.Path(f).suffix[1:].lower() in _FORMATS
+    }

src/pkg_infra/utils.py

@@ -0,0 +1,21 @@
+"""General-purpose utility functions.
+
+Migrated from pypath_common._misc, _constants, and _process.
+Organized into submodules for clarity; all public functions are
+re-exported here for convenience::
+
+    from pkg_infra.utils import to_set, first, ext, swap_dict
+"""
+
+from pkg_infra.utils.constants import *  # noqa: F401, F403
+from pkg_infra.utils._process import swap_dict  # noqa: F401
+from pkg_infra.utils._misc import *  # noqa: F401, F403
+
+# Preserved from original utils.py
+import datetime
+
+def get_timestamp_now() -> str:
+    """Get the current UTC timestamp with an explicit ``Z`` suffix."""
+    return datetime.datetime.now(datetime.timezone.utc).strftime(
+        "%Y%m%dT%H%M%SZ",
+    )