Audit and tighten top-level public API exports (config + IO convenience aliases) (#1306)

* Initial plan

* Export config and IO convenience APIs at top-level

Agent-Logs-Url: https://github.com/SkBlaz/py3plex/sessions/49273dd3-4fd5-4b72-af96-60555bbf4034

Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com>

* Refine public API export test dependency check

Agent-Logs-Url: https://github.com/SkBlaz/py3plex/sessions/49273dd3-4fd5-4b72-af96-60555bbf4034

Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com>

* Fix Python 3.8 CI by lazily exposing top-level IO aliases

Agent-Logs-Url: https://github.com/SkBlaz/py3plex/sessions/45f0a857-b71d-4c02-a004-ae360f90e34d

Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: SkBlaz <10035780+SkBlaz@users.noreply.github.com>

Author: Copilot

py3plex/__init__.py

@@ -123,6 +123,7 @@
     profile_performance,
     timed_section,
 )
+import py3plex.config as config
 
 # Plugin system - import for easy access
 from py3plex.plugins import (
@@ -163,7 +164,6 @@
     make_random_multiplex,
     make_social_network,
 )
-
 # Dynamics module for simulating dynamical processes
 from py3plex.dynamics import (
     D,
@@ -199,6 +199,34 @@
     estimate_uncertainty,
 )
 
+
+def save_to_arrow(network, path, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.save_to_arrow`."""
+    from py3plex.io import save_to_arrow as _save_to_arrow
+
+    return _save_to_arrow(network, path, **kwargs)
+
+
+def load_from_arrow(path, as_multinet=True, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.load_from_arrow`."""
+    from py3plex.io import load_from_arrow as _load_from_arrow
+
+    return _load_from_arrow(path, as_multinet=as_multinet, **kwargs)
+
+
+def save_network_to_parquet(network, path, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.save_network_to_parquet`."""
+    from py3plex.io import save_network_to_parquet as _save_network_to_parquet
+
+    return _save_network_to_parquet(network, path, **kwargs)
+
+
+def load_network_from_parquet(path, **kwargs):
+    """Lazy top-level alias for :func:`py3plex.io.load_network_from_parquet`."""
+    from py3plex.io import load_network_from_parquet as _load_network_from_parquet
+
+    return _load_network_from_parquet(path, **kwargs)
+
 __all__ = [
     # Version info
     "__version__",
@@ -299,6 +327,13 @@
     "make_social_network",
     "list_datasets",
     "get_data_dir",
+    # Config module
+    "config",
+    # I/O convenience functions
+    "save_to_arrow",
+    "load_from_arrow",
+    "save_network_to_parquet",
+    "load_network_from_parquet",
     # Dynamics (simulation)
     "D",
     "SimulationBuilder",

tests/test_public_api_exports.py

@@ -0,0 +1,60 @@
+"""Tests for top-level py3plex public API exports."""
+import pytest
+
+
+def _import_py3plex_or_skip():
+    """Import py3plex or skip when optional heavy deps are unavailable."""
+    try:
+        import py3plex
+    except ModuleNotFoundError as exc:
+        if exc.name in {"matplotlib", "networkx"}:
+            pytest.skip(f"optional dependency missing for top-level import: {exc.name}")
+        raise
+    return py3plex
+
+
+def test_config_exported_from_main_package():
+    """config should be exported from top-level py3plex package."""
+    py3plex = _import_py3plex_or_skip()
+
+    assert "config" in py3plex.__all__
+    assert hasattr(py3plex, "config")
+
+    from py3plex import config as config_from_main
+    import py3plex.config as config_module
+
+    assert config_from_main is config_module
+
+
+def test_io_convenience_functions_exported_from_main_package():
+    """Arrow/Parquet convenience I/O functions should be top-level exports."""
+    py3plex = _import_py3plex_or_skip()
+
+    names = [
+        "save_to_arrow",
+        "load_from_arrow",
+        "save_network_to_parquet",
+        "load_network_from_parquet",
+    ]
+
+    for name in names:
+        assert name in py3plex.__all__
+        assert hasattr(py3plex, name)
+        assert callable(getattr(py3plex, name))
+
+
+def test_io_convenience_functions_match_io_module():
+    """Top-level I/O convenience exports should be callable lazy aliases."""
+    py3plex = _import_py3plex_or_skip()
+
+    names = [
+        "save_to_arrow",
+        "load_from_arrow",
+        "save_network_to_parquet",
+        "load_network_from_parquet",
+    ]
+
+    for name in names:
+        fn = getattr(py3plex, name)
+        assert callable(fn)
+        assert fn.__module__ == "py3plex"