refactor!: libvcs.utils -> libvcs._internal

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.
 

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:
 

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:
 ```

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:

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,

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

libvcs/utils/run.py → 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
 ----

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]]
 

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]]
 

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]]
 

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(

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__)
 

tests/utils/subprocess/test_SubprocessCommand.py → 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:

tests/utils/test_query_list.py → 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(

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):

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
 
 

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,

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"):

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