vcs-python · tony · Apr 4, 2022 · Apr 3, 2022 · Apr 4, 2022 · Apr 3, 2022
diff --git a/CHANGES b/CHANGES
@@ -11,9 +11,14 @@ $ pip install --user --upgrade --pre libvcs
 
 ## libvcs 0.12.0 (unreleased, beta 0)
 
+### Breaking
+
+- `GitRepo`, `SVNRepo`, `MercurialRepo`, `BaseRepo` have been moved to
+  `libvcs.states.{module}.{Module}Repo`
+
 ### What's new
 
-- {class}`libvcs.git.GitRepo` now accepts remotes in `__init__`
+- {class}`libvcs.states.git.GitRepo` now accepts remotes in `__init__`
 
   ```python
   repo = GitRepo(
@@ -38,7 +43,7 @@ $ pip install --user --upgrade --pre libvcs
   )
   ```
 
-- {meth}`libvcs.git.GitRepo.update_repo` now accepts `set_remotes=True`
+- {meth}`libvcs.states.git.GitRepo.update_repo` now accepts `set_remotes=True`
 
 ### Compatibility
 
@@ -55,9 +60,9 @@ $ pip install --user --upgrade --pre libvcs
   [@actions/setup v3.1](https://github.com/actions/setup-python/releases/tag/v3.1.0), (:issue:`316`)
 - New constants for `str` -> class mappings
 
-  - {data}`libvcs.constants.DEFAULT_VCS_CLASS_MAP`
-  - {data}`libvcs.constants.DEFAULT_VCS_CLASS_UNION`
-  - {data}`libvcs.constants.DEFAULT_VCS_LITERAL`
+  - {data}`libvcs.states.constants.DEFAULT_VCS_CLASS_MAP`
+  - {data}`libvcs.states.constants.DEFAULT_VCS_CLASS_UNION`
+  - {data}`libvcs.states.constants.DEFAULT_VCS_LITERAL`
 
 - Remove tox and tox-poetry-installer. It turns out installing poetry inside a poetry project
   doesn't work well. (`poetry update`, `poetry publish`, etc. commands would fail)

diff --git a/docs/api/git.md b/docs/api/git.md
diff --git a/docs/index.md b/docs/index.md
@@ -9,7 +9,7 @@
 :hidden:
 
 quickstart
-api/index
+states/index
 ```
 
 ```{toctree}

diff --git a/docs/redirects.txt b/docs/redirects.txt
@@ -1 +1,5 @@
-"api.md" "api/index.md"
+"api.md" "states/index.md"
+"api/base.md" "states/base.md"
+"api/git.md" "states/git.md"
+"api/hg.md" "states/hg.md"
+"api/svn.md" "states/svn.md"
diff --git a/docs/api/base.md → docs/states/base.md b/docs/api/base.md → docs/states/base.md
@@ -1,16 +1,18 @@
-# Base objects
+# `libvcs.states.base`
+
+Base objects / classes for states.
 
 Adding your own VCS / Extending libvcs can be done through subclassing `BaseRepo`.
 
 ```{eval-rst}
 .. autosummary::
    :recursive:
 
-   libvcs.base.BaseRepo
+   libvcs.states.base.BaseRepo
 ```
 
 ```{eval-rst}
-.. automodule:: libvcs.base
+.. automodule:: libvcs.states.base
    :members:
    :show-inheritance:
 ```
diff --git a/docs/states/git.md b/docs/states/git.md
@@ -0,0 +1,24 @@
+# `libvcs.states.git`
+
+For `git(1)`.
+
+Compare to:
+[`fabtools.require.git`](https://fabtools.readthedocs.io/en/0.19.0/api/require/git.html),
+[`salt.states.git`](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.git.html),
+[`ansible.builtin.git`](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html)
+
+```{eval-rst}
+.. autosummary::
+   :recursive:
+
+   libvcs.states.git.GitRemote
+   libvcs.states.git.GitRepo
+```
+
+```{eval-rst}
+.. automodule:: libvcs.states.git
+   :members:
+   :show-inheritance:
+   :undoc-members:
+   :inherited-members:
+```
diff --git a/docs/api/hg.md → docs/states/hg.md b/docs/api/hg.md → docs/states/hg.md
@@ -1,16 +1,16 @@
-# Mercurial (hg)
+# `libvcs.states.hg`
 
-aka `hg(1)`
+For mercurial, aka `hg(1)`.
 
 ```{eval-rst}
 .. autosummary::
    :recursive:
 
-   libvcs.hg.MercurialRepo
+   libvcs.states.hg.MercurialRepo
 ```
 
 ```{eval-rst}
-.. automodule:: libvcs.hg
+.. automodule:: libvcs.states.hg
    :members:
    :show-inheritance:
    :undoc-members:

diff --git a/docs/api/index.md → docs/states/index.md b/docs/api/index.md → docs/states/index.md
@@ -1,6 +1,11 @@
-(api)=
+(states)=
 
-# API Reference
+# `libvcs.states`
+
+Compare to:
+[`fabtools.require.git`](https://fabtools.readthedocs.io/en/0.19.0/api/require/git.html),
+[`salt.states.git`](https://docs.saltproject.io/en/latest/ref/states/all/salt.states.git.html),
+[`ansible.builtin.git`](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/git_module.html)
 
 :::{warning}
 
@@ -33,7 +38,7 @@ See examples below of git, mercurial, and subversion.
 ## Constants
 
 ```{eval-rst}
-.. automodule:: libvcs.constants
+.. automodule:: libvcs.states.constants
    :members:
 ```
 

diff --git a/docs/api/svn.md → docs/states/svn.md b/docs/api/svn.md → docs/states/svn.md
@@ -1,16 +1,16 @@
-# Subversion (svn)
+# `libvcs.states.svn`
 
-aka `svn(1)`
+For subversion, aka `svn(1)`
 
 ```{eval-rst}
 .. autosummary::
    :recursive:
 
-   libvcs.svn.SubversionRepo
+   libvcs.states.svn.SubversionRepo
 ```
 
 ```{eval-rst}
-.. automodule:: libvcs.svn
+.. automodule:: libvcs.states.svn
    :members:
    :show-inheritance:
    :undoc-members:

diff --git a/libvcs/__init__.py b/libvcs/__init__.py
@@ -1,10 +1,11 @@
 """Repo package for libvcs."""
 import logging
 
-from .base import BaseRepo, RepoLoggingAdapter
-from .git import GitRepo
-from .hg import MercurialRepo
-from .svn import SubversionRepo
+from .states.base import BaseRepo
+from .states.git import GitRepo
+from .states.hg import MercurialRepo
+from .states.svn import SubversionRepo
+from .util import RepoLoggingAdapter
 
 __all__ = [
     "GitRepo",

diff --git a/libvcs/base.py → libvcs/states/base.py b/libvcs/base.py → libvcs/states/base.py
@@ -4,7 +4,7 @@
 from typing import NamedTuple
 from urllib import parse as urlparse
 
-from .util import RepoLoggingAdapter, mkdir_p, run
+from ..util import RepoLoggingAdapter, mkdir_p, run
 
 logger = logging.getLogger(__name__)
 

diff --git a/libvcs/constants.py → libvcs/states/constants.py b/libvcs/constants.py → libvcs/states/constants.py
diff --git a/libvcs/git.py → libvcs/states/git.py b/libvcs/git.py → libvcs/states/git.py
@@ -20,8 +20,8 @@
 from typing import Dict, NamedTuple, Optional, TypedDict, Union
 from urllib import parse as urlparse
 
-from . import exc
-from .base import BaseRepo, VCSLocation, convert_pip_url as base_convert_pip_url
+from .. import exc
+from ..states.base import BaseRepo, VCSLocation, convert_pip_url as base_convert_pip_url
 
 logger = logging.getLogger(__name__)
 

diff --git a/libvcs/hg.py → libvcs/states/hg.py b/libvcs/hg.py → libvcs/states/hg.py
diff --git a/libvcs/svn.py → libvcs/states/svn.py b/libvcs/svn.py → libvcs/states/svn.py
diff --git a/tests/test_base.py → tests/states/test_base.py b/tests/test_base.py → tests/states/test_base.py
@@ -1,8 +1,8 @@
 """tests for libvcs repo abstract base class."""
 import pathlib
 
-from libvcs.base import BaseRepo, convert_pip_url
 from libvcs.shortcuts import create_repo
+from libvcs.states.base import BaseRepo, convert_pip_url
 
 
 def test_repr():

diff --git a/tests/test_git.py → tests/states/test_git.py b/tests/test_git.py → tests/states/test_git.py
@@ -11,14 +11,14 @@
 from pytest_mock import MockerFixture
 
 from libvcs import exc
-from libvcs.git import (
+from libvcs.shortcuts import create_repo_from_pip_url
+from libvcs.states.git import (
     FullRemoteDict,
     GitRemote,
     GitRepo,
     convert_pip_url as git_convert_pip_url,
     extract_status,
 )
-from libvcs.shortcuts import create_repo_from_pip_url
 from libvcs.util import run, which
 
 if not which("git"):

diff --git a/tests/test_hg.py → tests/states/test_hg.py b/tests/test_hg.py → tests/states/test_hg.py
diff --git a/tests/test_svn.py → tests/states/test_svn.py b/tests/test_svn.py → tests/states/test_svn.py