Rename IndexConfig -> PackageIndexConfig (#47)

* Rename IndexConfig -> PackageIndexConfig

Previous name was ambiguous, make it more explicit.

Closes #21

* Rename API docs file

docs/api/venvstacks.stacks.PackageIndexConfig.rst

@@ -0,0 +1,28 @@
+venvstacks.stacks.PackageIndexConfig
+====================================
+
+.. currentmodule:: venvstacks.stacks
+
+.. autoclass:: PackageIndexConfig
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~PackageIndexConfig.disabled
+      ~PackageIndexConfig.resolve_lexical_paths
+
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~PackageIndexConfig.allow_source_builds
+      ~PackageIndexConfig.local_wheel_dirs
+      ~PackageIndexConfig.query_default_index
+      ~PackageIndexConfig.local_wheel_paths
+

docs/api/venvstacks.stacks.rst

@@ -23,7 +23,7 @@
       ExportedEnvironmentPaths
       FrameworkEnv
       FrameworkSpec
-      IndexConfig
+      PackageIndexConfig
       LayerCategories
       LayerSpecMetadata
       LayerVariants

src/venvstacks/_util.py

@@ -82,26 +82,24 @@ def run_python_command_unchecked(
     command: list[str],
     *,
     env: Mapping[str, str] | None = ...,
-    text: Literal[True]|None = ...,
-    **kwds: Any
-) -> subprocess.CompletedProcess[str]:
-    ...
+    text: Literal[True] | None = ...,
+    **kwds: Any,
+) -> subprocess.CompletedProcess[str]: ...
 @overload
 def run_python_command_unchecked(
     command: list[str],
     *,
     env: Mapping[str, str] | None = ...,
     text: Literal[False] = ...,
-    **kwds: Any
-) -> subprocess.CompletedProcess[bytes]:
-    ...
+    **kwds: Any,
+) -> subprocess.CompletedProcess[bytes]: ...
 def run_python_command_unchecked(
     command: list[str],
     *,
     env: Mapping[str, str] | None = None,
-    text: bool|None = True,
+    text: bool | None = True,
     **kwds: Any,
-) -> subprocess.CompletedProcess[str]|subprocess.CompletedProcess[bytes]:
+) -> subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]:
     # Ensure required env vars are passed down on Windows,
     # and run Python in isolated mode with UTF-8 as the text encoding
     run_env = os.environ.copy()

src/venvstacks/cli.py

@@ -7,7 +7,7 @@
 
 import typer
 
-from .stacks import StackSpec, BuildEnvironment, _format_json, IndexConfig
+from .stacks import StackSpec, BuildEnvironment, _format_json, PackageIndexConfig
 
 # Inspired by the Python 3.13+ `argparse` feature,
 # but reports `python -m venvstacks` whenever `__main__`
@@ -183,7 +183,7 @@ def _define_build_environment(
 ) -> BuildEnvironment:
     """Load given stack specification and define a build environment"""
     stack_spec = StackSpec.load(spec_path)
-    index_config = IndexConfig(
+    index_config = PackageIndexConfig(
         query_default_index=index,
         allow_source_builds=allow_source,
         local_wheel_dirs=local_wheels,

src/venvstacks/stacks.py

@@ -114,7 +114,7 @@ def _resolve_lexical_path(path: StrPath, base_path: Path, /) -> Path:
 
 
 @dataclass
-class IndexConfig:
+class PackageIndexConfig:
     """Python package index access configuration"""
 
     query_default_index: bool = field(default=True)
@@ -970,7 +970,7 @@ class _PythonEnvironment(ABC):
     _env_spec: _PythonEnvironmentSpec = field(repr=False)
     build_path: Path = field(repr=False)
     requirements_path: Path = field(repr=False)
-    index_config: IndexConfig = field(repr=False)
+    index_config: PackageIndexConfig = field(repr=False)
 
     # Derived from target path and spec in __post_init__
     env_path: Path = field(init=False)
@@ -1843,7 +1843,7 @@ def all_environment_specs(self) -> Iterable[_PythonEnvironmentSpec]:
     def _define_envs(
         self,
         build_path: Path,
-        index_config: IndexConfig,
+        index_config: PackageIndexConfig,
         env_class: type[BuildEnv],
         specs: Mapping[LayerBaseName, _PythonEnvironmentSpec],
     ) -> MutableMapping[LayerBaseName, BuildEnv]:
@@ -1869,11 +1869,11 @@ def resolve_lexical_path(self, related_location: StrPath, /) -> Path:
     def define_build_environment(
         self,
         build_dir: StrPath = "",
-        index_config: IndexConfig | None = None,
+        index_config: PackageIndexConfig | None = None,
     ) -> "BuildEnvironment":
         build_path = self.resolve_lexical_path(build_dir)
         if index_config is None:
-            index_config = IndexConfig()
+            index_config = PackageIndexConfig()
         index_config.resolve_lexical_paths(self.spec_path.parent)
         print("Defining runtime environments:")
         runtimes = self._define_envs(

tests/support.py

@@ -18,7 +18,7 @@
     BuildEnvironment,
     EnvNameDeploy,
     LayerBaseName,
-    IndexConfig,
+    PackageIndexConfig,
 )
 
 _THIS_DIR = Path(__file__).parent
@@ -30,6 +30,7 @@
 # Basic marking uses the pytest.mark API directly
 # See pyproject.toml and tests/README.md for the defined marks
 
+
 def requires_venv(description: str) -> pytest.MarkDecorator:
     """Skip test case when running tests outside a virtual environment"""
     return pytest.mark.skipif(
@@ -173,9 +174,9 @@ def __init__(self, metadata_path: Path, snippet_paths: list[Path] | None = None)
 ##################################
 
 
-def make_mock_index_config(reference_config: IndexConfig | None = None) -> Any:
+def make_mock_index_config(reference_config: PackageIndexConfig | None = None) -> Any:
     if reference_config is None:
-        reference_config = IndexConfig()
+        reference_config = PackageIndexConfig()
     mock_config = create_autospec(reference_config, spec_set=True)
     # Make conditional checks and iteration reflect the actual field values
     checked_methods = ("__bool__", "__len__", "__iter__")

tests/test_cli_invocation.py

@@ -19,11 +19,12 @@
 from typer.testing import CliRunner
 
 from venvstacks import cli
-from venvstacks.stacks import BuildEnvironment, EnvironmentLock, IndexConfig
+from venvstacks.stacks import BuildEnvironment, EnvironmentLock, PackageIndexConfig
 from venvstacks._util import run_python_command_unchecked
 
 from support import requires_venv
 
+
 def report_traceback(exc: BaseException | None) -> str:
     if exc is None:
         return "Expected exception was not raised"
@@ -96,7 +97,7 @@ def invoke(self, cli_args: list[str]) -> click.testing.Result:
         return self.runner.invoke(self.app, cli_args)
 
     def assert_build_config(
-        self, expected_build_dir: str, expected_index_config: IndexConfig
+        self, expected_build_dir: str, expected_index_config: PackageIndexConfig
     ) -> None:
         """Check environment build path and index configuration details"""
         env_definition = self.mocked_stack_spec.define_build_environment
@@ -195,11 +196,11 @@ def test_entry_point_help(self) -> None:
 ACCEPTS_INDEX_CONFIG = ["lock", "build"]
 
 
-def _get_default_index_config(command: str) -> IndexConfig:
+def _get_default_index_config(command: str) -> PackageIndexConfig:
     if command in ACCEPTS_INDEX_CONFIG:
-        return IndexConfig()
+        return PackageIndexConfig()
     # Commands that don't support index access should turn it off in their config
-    return IndexConfig.disabled()
+    return PackageIndexConfig.disabled()
 
 
 ARGUMENT_PREFIX = "_CLI_ARG"
@@ -334,44 +335,44 @@ def _cli_args_case_id(cli_args_test_case: tuple[Any, ...]) -> str:
         return f"({' '.join(extra_cli_args)})"
 
     # CLI option handling test cases for package index access configuration
-    IndexConfigCase = tuple[tuple[str, ...], IndexConfig]
+    IndexConfigCase = tuple[tuple[str, ...], PackageIndexConfig]
     _INDEX_CONFIG_ARGS = (
         # Define how the relevant CLI options map to build environment config settings
         (
             (),
-            IndexConfig(
+            PackageIndexConfig(
                 query_default_index=True,
                 allow_source_builds=False,
                 local_wheel_dirs=None,
             ),
         ),
         (
             ("--index", "--no-allow-source"),
-            IndexConfig(
+            PackageIndexConfig(
                 query_default_index=True,
                 allow_source_builds=False,
                 local_wheel_dirs=None,
             ),
         ),
         (
             ("--no-index",),
-            IndexConfig(
+            PackageIndexConfig(
                 query_default_index=False,
                 allow_source_builds=False,
                 local_wheel_dirs=None,
             ),
         ),
         (
             ("--allow-source",),
-            IndexConfig(
+            PackageIndexConfig(
                 query_default_index=True,
                 allow_source_builds=True,
                 local_wheel_dirs=None,
             ),
         ),
         (
             ("--local-wheels", "/some_dir", "--local-wheels", "some/other/dir"),
-            IndexConfig(
+            PackageIndexConfig(
                 query_default_index=True,
                 allow_source_builds=False,
                 local_wheel_dirs=["/some_dir", "some/other/dir"],
@@ -481,7 +482,7 @@ def test_mock_build_op_selection(
         expected_build_dir = "_build"
         expected_output_dir = "_artifacts"
         mocked_stack_spec.load.assert_called_once_with(spec_path_to_mock)
-        mocked_runner.assert_build_config(expected_build_dir, IndexConfig())
+        mocked_runner.assert_build_config(expected_build_dir, PackageIndexConfig())
         # Defaults to selecting operations rather than stacks
         mocked_build_env = mocked_runner.mocked_build_env
         mocked_build_env.select_operations.assert_called_once_with(
@@ -534,7 +535,7 @@ def test_mock_lock_op_selection(
         mocked_stack_spec.assert_not_called()
         expected_build_dir = "_build"
         mocked_stack_spec.load.assert_called_once_with(spec_path_to_mock)
-        mocked_runner.assert_build_config(expected_build_dir, IndexConfig())
+        mocked_runner.assert_build_config(expected_build_dir, PackageIndexConfig())
         # Defaults to selecting operations rather than stacks
         mocked_build_env = mocked_runner.mocked_build_env
         mocked_build_env.select_operations.assert_called_once_with(
@@ -627,7 +628,9 @@ def test_mock_publish_op_selection(
         expected_build_dir = "_build"
         expected_output_dir = "_artifacts"
         mocked_stack_spec.load.assert_called_once_with(spec_path_to_mock)
-        mocked_runner.assert_build_config(expected_build_dir, IndexConfig.disabled())
+        mocked_runner.assert_build_config(
+            expected_build_dir, PackageIndexConfig.disabled()
+        )
         # Defaults to selecting operations rather than stacks
         mocked_build_env = mocked_runner.mocked_build_env
         mocked_build_env.select_operations.assert_called_once_with(
@@ -715,7 +718,9 @@ def test_mock_export_op_selection(
         expected_build_dir = "_build"
         expected_output_dir = "_export"
         mocked_stack_spec.load.assert_called_once_with(spec_path_to_mock)
-        mocked_runner.assert_build_config(expected_build_dir, IndexConfig.disabled())
+        mocked_runner.assert_build_config(
+            expected_build_dir, PackageIndexConfig.disabled()
+        )
         # Defaults to selecting operations rather than stacks
         mocked_build_env = mocked_runner.mocked_build_env
         mocked_build_env.select_operations.assert_called_once_with(

tests/test_index_config.py

@@ -6,11 +6,11 @@
 
 import pytest
 
-from venvstacks.stacks import IndexConfig
+from venvstacks.stacks import PackageIndexConfig
 
 
 class TestDefaultOptions:
-    TEST_CONFIG = IndexConfig()
+    TEST_CONFIG = PackageIndexConfig()
 
     def test_uv_pip_compile(self) -> None:
         # Nominal config is always used when locking
@@ -33,7 +33,7 @@ def test_pip_sync(self) -> None:
 
 
 class TestConfiguredOptions:
-    TEST_CONFIG = IndexConfig(
+    TEST_CONFIG = PackageIndexConfig(
         query_default_index=False,
         allow_source_builds=True,
         local_wheel_dirs=["/some_dir"],
@@ -80,7 +80,7 @@ def test_pip_sync(self) -> None:
 # Miscellaneous test cases
 def test_wheel_dir_not_in_sequence() -> None:
     with pytest.raises(TypeError):
-        IndexConfig(local_wheel_dirs="/some_dir")
+        PackageIndexConfig(local_wheel_dirs="/some_dir")
 
 
 def test_lexical_path_resolution() -> None:
@@ -100,6 +100,6 @@ def test_lexical_path_resolution() -> None:
         Path.home() / "some/path",
         Path.home() / "some/path",
     ]
-    config = IndexConfig(local_wheel_dirs=paths_to_resolve)
+    config = PackageIndexConfig(local_wheel_dirs=paths_to_resolve)
     config.resolve_lexical_paths("/base_path")
     assert config.local_wheel_paths == expected_paths

tests/test_minimal_project.py

@@ -34,7 +34,7 @@
     LayerVariants,
     ExportedEnvironmentPaths,
     ExportMetadata,
-    IndexConfig,
+    PackageIndexConfig,
     PublishedArchivePaths,
     get_build_platform,
 )
@@ -366,7 +366,7 @@ def _load_build_manifest(metadata_path: Path) -> BuildManifest:
             return _filter_manifest(json.load(f))[0]
 
     def mock_index_config_options(
-        self, reference_config: IndexConfig | None = None
+        self, reference_config: PackageIndexConfig | None = None
     ) -> None:
         # Mock the index configs in order to check for
         # expected CLI argument lookups
@@ -700,7 +700,7 @@ def test_implicit_source_builds(self) -> None:
         # declarations, since actual build failures need to fail the entire test method.
         subtests_started = subtests_passed = 0  # Track subtest failures
         build_env = self.build_env
-        source_build_index_config = IndexConfig(allow_source_builds=True)
+        source_build_index_config = PackageIndexConfig(allow_source_builds=True)
         self.mock_index_config_options(source_build_index_config)
         platform_tag = build_env.build_platform
         expected_tag = f"-{platform_tag}"