refactor!: Move run() and core functions to utils (#343)

tony · web-flow · commit 7a99e5e41bb1 · 2022-05-15T09:54:49.000-05:00
This is not to be considered a stable API in the near future - though
we're open to it after they're stable and battle-tested.
diff --git a/CHANGES b/CHANGES
@@ -13,6 +13,11 @@ $ pip install --user --upgrade --pre libvcs
 
 - _Add your latest changes from PRs here_
 
+### 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.
+
 ### Internals
 
 - `StrOrPath` -> `StrPath`
diff --git a/docs/cmd/core.md b/docs/cmd/core.md
diff --git a/docs/cmd/index.md b/docs/cmd/index.md
@@ -19,5 +19,4 @@ versions.
 git
 hg
 svn
-core
 ```
diff --git a/docs/internals/index.md b/docs/internals/index.md
@@ -14,5 +14,6 @@ exc
 types
 dataclasses
 query_list
+run
 subprocess
 ```
diff --git a/docs/internals/run.md b/docs/internals/run.md
@@ -0,0 +1,9 @@
+# `libvcs.utils.run`
+
+```{eval-rst}
+.. autoapimodule:: libvcs.utils.run
+   :members:
+   :show-inheritance:
+   :undoc-members:
+   :exclude-members: StrOrBytesPath, StrPath, logger
+```
diff --git a/libvcs/__init__.py b/libvcs/__init__.py
@@ -1,7 +1,7 @@
 """Project package for libvcs."""
 import logging
 
-from .cmd.core import CmdLoggingAdapter
+from .utils.run import CmdLoggingAdapter
 from .projects.base import BaseProject
 from .projects.git import GitProject
 from .projects.hg import MercurialProject
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 .core import run
+from libvcs.utils.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 .core import run
+from libvcs.utils.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 .core import run
+from libvcs.utils.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.cmd.core import run, which
+from libvcs.utils.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
@@ -4,7 +4,7 @@
 from typing import NamedTuple
 from urllib import parse as urlparse
 
-from libvcs.cmd.core import CmdLoggingAdapter, mkdir_p, run
+from libvcs.utils.run import CmdLoggingAdapter, mkdir_p, run
 from libvcs.types import StrPath
 
 logger = logging.getLogger(__name__)
diff --git a/libvcs/utils/run.py b/libvcs/utils/run.py
diff --git a/tests/cmd/test_core.py b/tests/cmd/test_core.py
@@ -2,7 +2,7 @@
 
 import pytest
 
-from libvcs.cmd.core import mkdir_p, which
+from libvcs.utils.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.cmd.core import which
+from libvcs.utils.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.cmd.core import run, which
+from libvcs.utils.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.cmd.core import run, which
+from libvcs.utils.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.cmd.core import which
+from libvcs.utils.run import which
 from libvcs.conftest import CreateProjectCallbackFixtureProtocol
 from libvcs.projects.svn import SubversionProject
 from libvcs.shortcuts import create_project_from_pip_url

-Original file line number
+Diff line change
 git
 hg
 svn
 -core
 ```