pytest_plugin: pydocstyle manual fixes

Author: tony

src/libvcs/pytest_plugin.py

@@ -1,4 +1,4 @@
-"""pytest fixtures. Live inside libvcs for doctest."""
+"""pytest plugin for VCS Repository testing and management."""
 import functools
 import getpass
 import pathlib
@@ -20,7 +20,10 @@
 
 
 class MaxUniqueRepoAttemptsExceeded(exc.LibVCSException):
+    """Raised when exceeded threshold of attempts to find a unique repo destination."""
+
     def __init__(self, attempts: int, *args: object):
+        """Raise LibVCSException exception with message including attempts tried."""
         return super().__init__(
             f"Could not find unused repo destination (attempts: {attempts})"
         )
@@ -38,22 +41,27 @@ def __init__(self, attempts: int, *args: object):
 
 
 class RandomStrSequence:
+    """Create a random string sequence."""
+
     def __init__(
         self, characters: str = "abcdefghijklmnopqrstuvwxyz0123456789_"
     ) -> None:
         self.characters: str = characters
 
     def __iter__(self) -> "RandomStrSequence":
+        """Iterate across generated strings."""
         return self
 
     def __next__(self) -> str:
+        """Iterate to next string possibility."""
         return "".join(random.sample(self.characters, k=8))
 
 
 namer = RandomStrSequence()
 
 
 def pytest_ignore_collect(collection_path: pathlib.Path, config: pytest.Config) -> bool:
+    """Skip tests if VCS binaries are missing."""
     if not shutil.which("svn") and any(
         needle in str(collection_path) for needle in ["svn", "subversion"]
     ):
@@ -70,17 +78,19 @@ def pytest_ignore_collect(collection_path: pathlib.Path, config: pytest.Config)
 
 @pytest.fixture(scope="session")
 def home_path(tmp_path_factory: pytest.TempPathFactory) -> pathlib.Path:
+    """Return temporary directory to use as user's home path, pytest fixture."""
     return tmp_path_factory.mktemp("home")
 
 
 @pytest.fixture(scope="session")
 def home_user_name() -> str:
-    """Default username to set for :func:`user_path` fixture."""
+    """Return default username to set for :func:`user_path` fixture."""
     return getpass.getuser()
 
 
 @pytest.fixture(scope="session")
 def user_path(home_path: pathlib.Path, home_user_name: str) -> pathlib.Path:
+    """Return user's home directory, pytest fixture."""
     p = home_path / home_user_name
     p.mkdir()
     return p
@@ -91,12 +101,14 @@ def set_home(
     monkeypatch: pytest.MonkeyPatch,
     user_path: pathlib.Path,
 ) -> None:
+    """Set home directory, pytest fixture."""
     monkeypatch.setenv("HOME", str(user_path))
 
 
 @pytest.fixture
 @skip_if_git_missing
 def gitconfig(user_path: pathlib.Path, set_home: pathlib.Path) -> pathlib.Path:
+    """Return git configuration, pytest fixture."""
     gitconfig = user_path / ".gitconfig"
     user_email = "libvcs@git-pull.com"
     gitconfig.write_text(
@@ -131,6 +143,7 @@ def gitconfig(user_path: pathlib.Path, set_home: pathlib.Path) -> pathlib.Path:
 @pytest.fixture
 @skip_if_hg_missing
 def hgconfig(user_path: pathlib.Path, set_home: pathlib.Path) -> pathlib.Path:
+    """Return Mercurial configuration, pytest fixture."""
     hgrc = user_path / ".hgrc"
     hgrc.write_text(
         textwrap.dedent(
@@ -179,6 +192,7 @@ def clean() -> None:
 
 
 def unique_repo_name(remote_repos_path: pathlib.Path, max_retries: int = 15) -> str:
+    """Attempt to find and return a unique repo named based on path."""
     attempts = 1
     while True:
         if attempts > max_retries:
@@ -195,18 +209,24 @@ def unique_repo_name(remote_repos_path: pathlib.Path, max_retries: int = 15) ->
 
 
 class CreateRepoPostInitFn(Protocol):
+    """Typing for VCS repo creation callback."""
+
     def __call__(self, remote_repo_path: pathlib.Path) -> None:
+        """Ran after creating a repo from pytest fixture."""
         ...
 
 
 class CreateRepoPytestFixtureFn(Protocol):
+    """Typing for VCS pytest fixture callback."""
+
     def __call__(
         self,
         remote_repos_path: pathlib.Path = ...,
         remote_repo_name: Optional[str] = ...,
         remote_repo_post_init: Optional[CreateRepoPostInitFn] = ...,
         init_cmd_args: InitCmdArgs = ...,
     ) -> pathlib.Path:
+        """py.test fixture function to create a project in a remote repo."""
         ...
 
 
@@ -235,7 +255,7 @@ def _create_git_remote_repo(
 def create_git_remote_repo(
     remote_repos_path: pathlib.Path,
 ) -> CreateRepoPytestFixtureFn:
-    """Factory. Create git remote repo to for clone / push purposes."""
+    """Return factory to create git remote repo to for clone / push purposes."""
 
     def fn(
         remote_repos_path: pathlib.Path = remote_repos_path,
@@ -256,6 +276,7 @@ def fn(
 
 
 def git_remote_repo_single_commit_post_init(remote_repo_path: pathlib.Path) -> None:
+    """Post-initialization: Create a test git repo with a single commit."""
     testfile_filename = "testfile.test"
     run(["touch", testfile_filename], cwd=remote_repo_path)
     run(["git", "add", testfile_filename], cwd=remote_repo_path)
@@ -298,6 +319,7 @@ def _create_svn_remote_repo(
 
 
 def svn_remote_repo_single_commit_post_init(remote_repo_path: pathlib.Path) -> None:
+    """Post-initialization: Create a test SVN repo with a single commit."""
     assert remote_repo_path.exists()
     repo_dumpfile = pathlib.Path(__file__).parent / "data" / "repotest.dump"
     run(
@@ -372,6 +394,7 @@ def _create_hg_remote_repo(
 
 
 def hg_remote_repo_single_commit_post_init(remote_repo_path: pathlib.Path) -> None:
+    """Post-initialization: Create a test mercurial repo with a single commit."""
     testfile_filename = "testfile.test"
     run(["touch", testfile_filename], cwd=remote_repo_path)
     run(["hg", "add", testfile_filename], cwd=remote_repo_path)
@@ -470,6 +493,7 @@ def add_doctest_fixtures(
     create_hg_remote_repo: CreateRepoPytestFixtureFn,
     git_repo: pathlib.Path,
 ) -> None:
+    """Harness pytest fixtures to pytest's doctest namespace."""
     from _pytest.doctest import DoctestItem
 
     if not isinstance(request._pyfuncitem, DoctestItem):  # Only run on doctest items