refactor!: libvcs.utils -> libvcs._internal (#345)

tony · web-flow · commit 66217cd20673 · 2022-05-15T11:42:12.000-05:00
This should make it more clear we're dealing with internal machinery
diff --git a/CHANGES b/CHANGES
@@ -15,16 +15,18 @@ $ pip install --user --upgrade --pre libvcs
 
 ### Breaking changes
 
-- {issue}`343`: `libvcs.cmd.core` (including {func}`~libvcs.utils.run.run`) have been moved to
-  `libvcs.utils.run`. It will be supported as an unstable, internal API.
+- {issue}`343`: `libvcs.cmd.core` (including {func}`~libvcs._internal.run.run`) have been moved to
+  `libvcs._internal.run`. It will be supported as an unstable, internal API.
 
 ### Internals
 
+- {issue}`345` `libvcs.utils` -> `libvcs._internal` to make it more obvious the APIs are strictly
+  closed.
 - `StrOrPath` -> `StrPath`
-- {issue}`#336`: {class}`~libvcs.utils.subprocess.SubprocessCommand`: Encapsulated {mod}`subprocess`
-  call in a {func}`dataclasses.dataclass` for introspecting, modifying, mocking and controlling
-  execution.
-- Dataclass helper: {class}`~libvcs.utils.dataclasses.SkipDefaultFieldsReprMixin`
+- {issue}`#336`: {class}`~libvcs._internal.subprocess.SubprocessCommand`: Encapsulated
+  {mod}`subprocess` call in a {func}`dataclasses.dataclass` for introspecting, modifying, mocking
+  and controlling execution.
+- Dataclass helper: {class}`~libvcs._internal.dataclasses.SkipDefaultFieldsReprMixin`
 
   Skip default fields in object representations.
 
diff --git a/docs/internals/dataclasses.md b/docs/internals/dataclasses.md
@@ -1,7 +1,7 @@
-# `libvcs.utils.dataclasses`
+# `libvcs._internal.dataclasses`
 
 ```{eval-rst}
-.. autoapimodule:: libvcs.utils.dataclasses
+.. autoapimodule:: libvcs._internal.dataclasses
    :members:
    :special-members:
 
diff --git a/docs/internals/query_list.md b/docs/internals/query_list.md
@@ -1,6 +1,6 @@
-# `libvcs.utils.query_list`
+# `libvcs._internal.query_list`
 
 ```{eval-rst}
-.. autoapimodule:: libvcs.utils.query_list
+.. autoapimodule:: libvcs._internal.query_list
    :members:
 ```
diff --git a/docs/internals/run.md b/docs/internals/run.md
@@ -1,7 +1,7 @@
-# `libvcs.utils.run`
+# `libvcs._internal.run`
 
 ```{eval-rst}
-.. autoapimodule:: libvcs.utils.run
+.. autoapimodule:: libvcs._internal.run
    :members:
    :show-inheritance:
    :undoc-members:
diff --git a/docs/internals/subprocess.md b/docs/internals/subprocess.md
@@ -1,7 +1,7 @@
-# `libvcs.utils.subprocess`
+# `libvcs._internal.subprocess`
 
 ```{eval-rst}
-.. autoapimodule:: libvcs.utils.subprocess
+.. autoapimodule:: libvcs._internal.subprocess
    :members:
    :exclude-members:
      StrOrBytesPath, F, args, bufsize,
diff --git a/libvcs/__init__.py b/libvcs/__init__.py
@@ -1,7 +1,7 @@
 """Project package for libvcs."""
 import logging
 
-from .utils.run import CmdLoggingAdapter
+from ._internal.run import CmdLoggingAdapter
 from .projects.base import BaseProject
 from .projects.git import GitProject
 from .projects.hg import MercurialProject
diff --git a/libvcs/_internal/__init__.py b/libvcs/_internal/__init__.py
diff --git a/libvcs/_internal/dataclasses.py b/libvcs/_internal/dataclasses.py
diff --git a/libvcs/_internal/query_list.py b/libvcs/_internal/query_list.py
diff --git a/libvcs/_internal/run.py b/libvcs/_internal/run.py
@@ -1,6 +1,7 @@
 """Misc. legacy helpers :mod:`subprocess` and finding VCS binaries.
 
-:class:`libvcs.utils.run.run` will be deprecated by :mod:`libvcs.utils.subprocess`.
+:class:`libvcs._internal.run.run` will be deprecated by
+:mod:`libvcs._internal.subprocess`.
 
 Note
 ----
diff --git a/libvcs/_internal/subprocess.py b/libvcs/_internal/subprocess.py
diff --git a/libvcs/cmd/git.py b/libvcs/cmd/git.py
@@ -3,7 +3,7 @@
 from typing import Any, Literal, Optional, Sequence, Union
 
 from ..types import StrOrBytesPath, StrPath
-from libvcs.utils.run import run
+from libvcs._internal.run import run
 
 _CMD = Union[StrOrBytesPath, Sequence[StrOrBytesPath]]
 
diff --git a/libvcs/cmd/hg.py b/libvcs/cmd/hg.py
@@ -3,7 +3,7 @@
 from typing import Optional, Sequence, Union
 
 from ..types import StrOrBytesPath, StrPath
-from libvcs.utils.run import run
+from libvcs._internal.run import run
 
 _CMD = Union[StrOrBytesPath, Sequence[StrOrBytesPath]]
 
diff --git a/libvcs/cmd/svn.py b/libvcs/cmd/svn.py
@@ -2,7 +2,7 @@
 from typing import Literal, Optional, Sequence, Union
 
 from ..types import StrOrBytesPath, StrPath
-from libvcs.utils.run import run
+from libvcs._internal.run import run
 
 _CMD = Union[StrOrBytesPath, Sequence[StrOrBytesPath]]
 
diff --git a/libvcs/conftest.py b/libvcs/conftest.py
@@ -10,7 +10,7 @@
 
 from faker import Faker
 
-from libvcs.utils.run import run, which
+from libvcs._internal.run import run, which
 from libvcs.projects.git import GitProject, GitRemoteDict
 
 skip_if_git_missing = pytest.mark.skipif(
diff --git a/libvcs/projects/base.py b/libvcs/projects/base.py
@@ -5,7 +5,7 @@
 from urllib import parse as urlparse
 
 from libvcs.types import StrPath
-from libvcs.utils.run import CmdLoggingAdapter, mkdir_p, run
+from libvcs._internal.run import CmdLoggingAdapter, mkdir_p, run
 
 logger = logging.getLogger(__name__)
 
diff --git a/tests/_internal/subprocess/conftest.py b/tests/_internal/subprocess/conftest.py
diff --git a/tests/_internal/subprocess/test_SubprocessCommand.py b/tests/_internal/subprocess/test_SubprocessCommand.py
@@ -4,7 +4,7 @@
 
 import pytest
 
-from libvcs.utils.subprocess import SubprocessCommand
+from libvcs._internal.subprocess import SubprocessCommand
 
 
 def idfn(val: Any) -> str:
diff --git a/tests/_internal/test_query_list.py b/tests/_internal/test_query_list.py
@@ -2,7 +2,7 @@
 
 import pytest
 
-from libvcs.utils.query_list import QueryList
+from libvcs._internal.query_list import QueryList
 
 
 @pytest.mark.parametrize(
diff --git a/tests/cmd/test_core.py b/tests/cmd/test_core.py
@@ -2,7 +2,7 @@
 
 import pytest
 
-from libvcs.utils.run import mkdir_p, which
+from libvcs._internal.run import mkdir_p, which
 
 
 def test_mkdir_p(tmp_path: pathlib.Path):
diff --git a/tests/projects/test_conftest.py b/tests/projects/test_conftest.py
@@ -2,7 +2,7 @@
 
 import pytest
 
-from libvcs.utils.run import which
+from libvcs._internal.run import which
 from libvcs.conftest import CreateProjectCallbackFixtureProtocol
 
 
diff --git a/tests/projects/test_git.py b/tests/projects/test_git.py
@@ -10,7 +10,7 @@
 from pytest_mock import MockerFixture
 
 from libvcs import exc
-from libvcs.utils.run import run, which
+from libvcs._internal.run import run, which
 from libvcs.conftest import CreateProjectCallbackFixtureProtocol
 from libvcs.projects.git import (
     GitFullRemoteDict,
diff --git a/tests/projects/test_hg.py b/tests/projects/test_hg.py
@@ -3,7 +3,7 @@
 
 import pytest
 
-from libvcs.utils.run import run, which
+from libvcs._internal.run import run, which
 from libvcs.shortcuts import create_project, create_project_from_pip_url
 
 if not which("hg"):
diff --git a/tests/projects/test_svn.py b/tests/projects/test_svn.py
@@ -4,7 +4,7 @@
 
 import pytest
 
-from libvcs.utils.run import which
+from libvcs._internal.run import which
 from libvcs.conftest import CreateProjectCallbackFixtureProtocol
 from libvcs.projects.svn import SubversionProject
 from libvcs.shortcuts import create_project_from_pip_url
