From 48ff67de6ac87044146dc118870a8feecec315bc Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:21:47 -0600 Subject: [PATCH 01/15] docs: Fix typo in pytest plugin docs (set_getconfig -> set_gitconfig) and add Python syntax highlighting --- docs/pytest-plugin.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 22aeb435..7dda4ee7 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -86,7 +86,7 @@ def setup(set_home: None): You can override the default author used in {func}`git_remote_repo` and other fixtures via {func}`vcs_name`, {func}`vcs_email`, and {func}`vcs_user`: -``` +```python @pytest.fixture(scope="session") def vcs_name() -> str: return "My custom name" @@ -102,7 +102,7 @@ def setup(set_gitconfig: None): pass ``` -Sometimes, `set_getconfig` via `GIT_CONFIG` doesn't apply as expected. For those +Sometimes, `set_gitconfig` via `GIT_CONFIG` doesn't apply as expected. For those cases, you can use {func}`git_commit_envvars`: ```python From 49113eb59ed2d631d16f442989274c353525647b Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:22:04 -0600 Subject: [PATCH 02/15] docs: Improve formatting and clarity in developmental releases section --- docs/quickstart.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index e9508b34..e5ae440a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -21,18 +21,18 @@ $ pip install --user --upgrade libvcs ### Developmental releases New versions of libvcs are published to PyPI as alpha, beta, or release candidates. In their -versions you will see notification like `a1`, `b1`, and `rc1`, respectively. `1.10.0b4` would mean +versions, you will see notations like `a1`, `b1`, and `rc1`, respectively. For example, `1.10.0b4` would mean the 4th beta release of `1.10.0` before general availability. -- [pip]\: +Installation options: + +- Via pip (pre-release versions): ```console $ pip install --user --upgrade --pre libvcs ``` -via trunk (can break easily): - -- [pip]\: +- Via trunk (development version, may be unstable): ```console $ pip install --user -e git+https://github.com/vcs-python/libvcs.git#egg=libvcs From f1631644899a4ece9958d13e64fdbfc515138a63 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:22:25 -0600 Subject: [PATCH 03/15] docs: Fix incorrect module name in migration.md (libtmux -> libvcs) --- docs/migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/migration.md b/docs/migration.md index 7bd3f466..88016ebe 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -1,6 +1,6 @@ (migration)= -```{currentmodule} libtmux +```{currentmodule} libvcs ``` From ac81b5587443513f3cdc23e9fca019d9748f6b45 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:23:06 -0600 Subject: [PATCH 04/15] docs: Improve formatting consistency and type hints in pytest plugin docs --- docs/pytest-plugin.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 7dda4ee7..0efaa8f6 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -43,7 +43,7 @@ When the plugin is enabled and `pytest` is run, these overridable fixtures are a - `/home/` ({func}`home_path`) - `/home/${user}` ({func}`user_path`) - Set the home directory: - - Patch `$HOME` to point to {func}`user_path` using ({func}`set_home`) + - Patch `$HOME` to point to {func}`user_path` using {func}`set_home` - Create configuration files: - `.gitconfig` via {func}`gitconfig` - `.hgrc` via {func}`hgconfig` @@ -107,12 +107,14 @@ cases, you can use {func}`git_commit_envvars`: ```python import pytest +from typing import Dict, Any +from libvcs.pytest_plugin import CreateRepoPytestFixtureFn @pytest.fixture def my_git_repo( create_git_remote_repo: CreateRepoPytestFixtureFn, gitconfig: pathlib.Path, - git_commit_envvars: "_ENV", + git_commit_envvars: Dict[str, Any], ) -> pathlib.Path: """Copy the session-scoped Git repository to a temporary directory.""" repo_path = create_git_remote_repo() From 52c5b29f46ce44c95d8831d4ed517479c2c49c87 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:23:19 -0600 Subject: [PATCH 05/15] docs: Update installation commands to use python -m pip --- docs/quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index e5ae440a..e37e5e4f 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -7,13 +7,13 @@ For latest official version: ```console -$ pip install --user libvcs +$ python -m pip install libvcs ``` Upgrading: ```console -$ pip install --user --upgrade libvcs +$ python -m pip install --upgrade libvcs ``` (developmental-releases)= From 06e5786bea92eb21fe3d629b7318624dad37d752 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:26:31 -0600 Subject: [PATCH 06/15] docs: Make developmental releases installation commands consistent with main installation format --- docs/quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index e37e5e4f..ea511aea 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -29,13 +29,13 @@ Installation options: - Via pip (pre-release versions): ```console - $ pip install --user --upgrade --pre libvcs + $ python -m pip install --upgrade --pre libvcs ``` - Via trunk (development version, may be unstable): ```console - $ pip install --user -e git+https://github.com/vcs-python/libvcs.git#egg=libvcs + $ python -m pip install -e git+https://github.com/vcs-python/libvcs.git#egg=libvcs ``` [pip]: https://pip.pypa.io/en/stable/ From 74308e74e2cfa76915e535e9e94d9d0078b8a612 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:26:43 -0600 Subject: [PATCH 07/15] docs: Update pytest plugin installation command to match quickstart format --- docs/pytest-plugin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 0efaa8f6..cb205263 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -22,7 +22,7 @@ Looking for more flexibility, correctness, or power? Need different defaults? [C Install `libvcs` using your preferred Python package manager: ```console -$ pip install libvcs +$ python -m pip install libvcs ``` Pytest will automatically detect the plugin, and its fixtures will be available. From eb7fd7f5b42bcb152a77ff63c7c3be85000c3aa7 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:27:51 -0600 Subject: [PATCH 08/15] docs: Fix grammatical issues and improve clarity in pytest plugin docs --- docs/pytest-plugin.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index cb205263..488b1aee 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -6,7 +6,7 @@ With libvcs's pytest plugin for [pytest], you can easily create Git, SVN, and Me ```{seealso} Are you using libvcs? -Looking for more flexibility, correctness, or power? Need different defaults? [Connect with us] on GitHub. We'd love to hear about your use case—APIs won't be stabilized until we're confident everything meets expectations. +Looking for more flexibility, correctness, or power? Need different defaults? [Connect with us] on GitHub. We'd love to hear about your use case. Our APIs won't be stabilized until we're confident they meet all expectations. [connect with us]: https://github.com/vcs-python/libvcs/discussions ``` @@ -29,7 +29,7 @@ Pytest will automatically detect the plugin, and its fixtures will be available. ## Fixtures -This pytest plugin works by providing {ref}`pytest fixtures `. The plugin's fixtures ensure that a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes [session-scoped fixtures] to cache initial repositories, improving performance across tests. +This pytest plugin works by providing {ref}`pytest fixtures `. The plugin's fixtures ensure that a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes [session-scoped fixtures] to cache the initial repositories, improving performance across tests. [session-scoped fixtures]: https://docs.pytest.org/en/8.3.x/how-to/fixtures.html#fixture-scopes @@ -65,7 +65,7 @@ These ensure that repositories can be cloned and created without unnecessary war To configure the above fixtures with `autouse=True`, add them to your `conftest.py` file or test file, depending on the desired scope. -_Why aren't these fixtures added automatically by the plugin?_ This design choice promotes explicitness, adhering to best practices for pytest plugins and Python packages. +_Why aren't these fixtures added automatically by the plugin?_ This design choice promotes explicitness and adheres to best practices for pytest plugins and Python packages. ### Setting a Temporary Home Directory From 3d21a69c67844e843c036fb21b43ba6554712e5b Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:28:08 -0600 Subject: [PATCH 09/15] docs: Improve sentence structure and clarity in quickstart guide --- docs/quickstart.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/quickstart.md b/docs/quickstart.md index ea511aea..63d7b4f5 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -4,13 +4,13 @@ ## Installation -For latest official version: +For the latest official version: ```console $ python -m pip install libvcs ``` -Upgrading: +Upgrading to the latest version: ```console $ python -m pip install --upgrade libvcs @@ -20,9 +20,9 @@ $ python -m pip install --upgrade libvcs ### Developmental releases -New versions of libvcs are published to PyPI as alpha, beta, or release candidates. In their -versions, you will see notations like `a1`, `b1`, and `rc1`, respectively. For example, `1.10.0b4` would mean -the 4th beta release of `1.10.0` before general availability. +New versions of libvcs are published to PyPI as alpha, beta, or release candidates. These versions +are marked with notations like `a1`, `b1`, and `rc1`, respectively. For example, `1.10.0b4` indicates +the 4th beta release of version `1.10.0` before its general availability. Installation options: From 42e4d5dfb0dd1931d9d0424b4461bfc5a47425f6 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:29:12 -0600 Subject: [PATCH 10/15] docs: Improve consistency and clarity in fixture documentation --- docs/pytest-plugin.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 488b1aee..25a66445 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -37,26 +37,26 @@ This pytest plugin works by providing {ref}`pytest fixtures `_): {func}`vcs_user` - - For git only: {func}`git_commit_envvars` + - User (e.g., _`user `_): {func}`vcs_user` + - Git-specific: {func}`git_commit_envvars` -These ensure that repositories can be cloned and created without unnecessary warnings. +These fixtures ensure that repositories can be cloned and created without unnecessary warnings. [`HGRCPATH`]: https://www.mercurial-scm.org/doc/hg.1.html#:~:text=UNIX%2Dlike%20environments.-,HGRCPATH,-If%20not%20set [`GIT_CONFIG`]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-GITCONFIG From f05a68b364624a6b0d88be9e28e6ae312d22fbe6 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:31:06 -0600 Subject: [PATCH 11/15] docs: Improve clarity and consistency in introduction and usage sections --- docs/pytest-plugin.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 25a66445..4de33af2 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -2,7 +2,7 @@ # `pytest` Plugin -With libvcs's pytest plugin for [pytest], you can easily create Git, SVN, and Mercurial repositories on the fly. +With libvcs's pytest plugin for [pytest], you can easily create Git, Subversion (SVN), and Mercurial repositories on the fly. ```{seealso} Are you using libvcs? @@ -25,11 +25,11 @@ Install `libvcs` using your preferred Python package manager: $ python -m pip install libvcs ``` -Pytest will automatically detect the plugin, and its fixtures will be available. +Once installed, pytest will automatically detect the plugin and make its fixtures available. ## Fixtures -This pytest plugin works by providing {ref}`pytest fixtures `. The plugin's fixtures ensure that a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes [session-scoped fixtures] to cache the initial repositories, improving performance across tests. +This pytest plugin provides {ref}`pytest fixtures ` that ensure a fresh Git, Subversion, or Mercurial repository is available for each test. It utilizes [session-scoped fixtures] to cache the initial repositories, improving performance across tests. [session-scoped fixtures]: https://docs.pytest.org/en/8.3.x/how-to/fixtures.html#fixture-scopes From 2e89f17200f094964fec98d53e54fc9797e6b188 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:48:15 -0600 Subject: [PATCH 12/15] docs: Fix merge conflict in pytest plugin documentation --- docs/pytest-plugin.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 4de33af2..5b6a7adc 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -69,13 +69,13 @@ _Why aren't these fixtures added automatically by the plugin?_ This design choic ### Setting a Temporary Home Directory -To set a temporary home directory, use the {func}`set_home` fixture with `autouse=True`: +To set up a temporary home directory, use the {func}`set_home` fixture with `autouse=True`: ```python import pytest @pytest.fixture(autouse=True) -def setup(set_home: None): +def setup_home(set_home: None): pass ``` @@ -83,12 +83,13 @@ def setup(set_home: None): #### Git -You can override the default author used in {func}`git_remote_repo` and other -fixtures via {func}`vcs_name`, {func}`vcs_email`, and {func}`vcs_user`: +You can override the default author information used in {func}`git_remote_repo` and other +fixtures by customizing {func}`vcs_name`, {func}`vcs_email`, or {func}`vcs_user`: ```python @pytest.fixture(scope="session") def vcs_name() -> str: + """Provide a custom author name for Git commits.""" return "My custom name" ``` @@ -98,7 +99,7 @@ Use the {func}`set_gitconfig` fixture with `autouse=True`: import pytest @pytest.fixture(autouse=True) -def setup(set_gitconfig: None): +def setup_git(set_gitconfig: None): pass ``` @@ -133,7 +134,7 @@ Use the {func}`set_hgconfig` fixture with `autouse=True`: import pytest @pytest.fixture(autouse=True) -def setup(set_hgconfig: None): +def setup_hg(set_hgconfig: None): pass ``` From d649eaafe613a109f933c959b7f384f31e12718e Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:48:49 -0600 Subject: [PATCH 13/15] docs: Fix merge conflict in my_git_repo docstring --- docs/pytest-plugin.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 5b6a7adc..a2dafe40 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -109,7 +109,7 @@ cases, you can use {func}`git_commit_envvars`: ```python import pytest from typing import Dict, Any -from libvcs.pytest_plugin import CreateRepoPytestFixtureFn +from libvcs.pytest_plugin import CreateRepoPytestFixtureFn, git_remote_repo_single_commit_post_init @pytest.fixture def my_git_repo( @@ -117,7 +117,10 @@ def my_git_repo( gitconfig: pathlib.Path, git_commit_envvars: Dict[str, Any], ) -> pathlib.Path: - """Copy the session-scoped Git repository to a temporary directory.""" + """Create a fresh Git repository in a temporary directory. + + This fixture demonstrates how to create a Git repository with custom commit settings. + """ repo_path = create_git_remote_repo() git_remote_repo_single_commit_post_init( remote_repo_path=repo_path, @@ -134,13 +137,14 @@ Use the {func}`set_hgconfig` fixture with `autouse=True`: import pytest @pytest.fixture(autouse=True) -def setup_hg(set_hgconfig: None): +def setup_hg(set_hgconfig: None) -> None: + """Configure Mercurial settings for testing.""" pass ``` ## Examples -For usage examples, refer to libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests). +For more usage examples, refer to libvcs's own [tests/](https://github.com/vcs-python/libvcs/tree/master/tests). ## API Reference From 72976c6286a9145e55345fca528c981acd332e7f Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:32:31 -0600 Subject: [PATCH 14/15] docs: Add return type annotations and improve fixture docstrings --- docs/pytest-plugin.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index a2dafe40..64f2cd66 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -75,7 +75,8 @@ To set up a temporary home directory, use the {func}`set_home` fixture with `aut import pytest @pytest.fixture(autouse=True) -def setup_home(set_home: None): +def setup_home(set_home: None) -> None: + """Configure a temporary home directory for testing.""" pass ``` @@ -99,7 +100,8 @@ Use the {func}`set_gitconfig` fixture with `autouse=True`: import pytest @pytest.fixture(autouse=True) -def setup_git(set_gitconfig: None): +def setup_git(set_gitconfig: None) -> None: + """Configure Git settings for testing.""" pass ``` From ef267cc23e253950a86c08be87a8693aaa2e7585 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Mon, 17 Feb 2025 09:49:15 -0600 Subject: [PATCH 15/15] docs(pytest-plugin) Note how fixture is cached --- docs/pytest-plugin.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/pytest-plugin.md b/docs/pytest-plugin.md index 64f2cd66..1e3f2ee9 100644 --- a/docs/pytest-plugin.md +++ b/docs/pytest-plugin.md @@ -131,6 +131,10 @@ def my_git_repo( return repo_path ``` +```{note} +The `create_git_remote_repo` fixture creates a repository once per test session and reuses it, making copies for individual tests to avoid repeated `git init` operations. +``` + #### Mercurial Use the {func}`set_hgconfig` fixture with `autouse=True`: