libvcs


Namelibvcs JSON
Version 0.34.0 PyPI version JSON
download
home_pageNone
SummaryLite, typed, python utilities for Git, SVN, Mercurial, etc.
upload_time2024-11-22 19:37:37
maintainerNone
docs_urlNone
authorNone
requires_python<4.0,>=3.9
licenseMIT
keywords abstraction checkout clone git hg lib library libvcs mercurial scm subversion svn vcs version control version-control wrapper
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # `libvcs` &middot; [![Python Package](https://img.shields.io/pypi/v/libvcs.svg)](https://pypi.org/project/libvcs/) [![License](https://img.shields.io/github/license/vcs-python/libvcs.svg)](https://github.com/vcs-python/libvcs/blob/master/LICENSE) [![Code Coverage](https://codecov.io/gh/vcs-python/libvcs/branch/master/graph/badge.svg)](https://codecov.io/gh/vcs-python/libvcs)

libvcs is a lite, [typed](https://docs.python.org/3/library/typing.html), pythonic tool box for
detection and parsing of URLs, commanding, and syncing with `git`, `hg`, and `svn`. Powers
[vcspull](https://www.github.com/vcs-python/vcspull/).

## Overview

### Key Features

- **URL Detection and Parsing**: Validate and parse Git, Mercurial, and Subversion URLs.
- **Command Abstraction**: Interact with VCS systems through a Python API.
- **Repository Synchronization**: Clone and update repositories locally via
  Python API.
- **py.test fixtures**: Create temporary local repositories and working copies for testing for unit tests.

_Supports Python 3.9 and above, Git (including AWS CodeCommit), Subversion, and Mercurial._

To **get started**, see the [quickstart guide](https://libvcs.git-pull.com/quickstart.html) for more information.

```console
$ pip install --user libvcs
```

## URL Detection and Parsing

Easily validate and parse VCS URLs using the
[`libvcs.url`](https://libvcs.git-pull.com/url/index.html) module:

### Validate URLs

```python
>>> from libvcs.url.git import GitURL

>>> GitURL.is_valid(url='https://github.com/vcs-python/libvcs.git')
True
```

### Parse and adjust Git URLs:

```python
>>> from libvcs.url.git import GitURL

>>> git_location = GitURL(url='git@github.com:vcs-python/libvcs.git')

>>> git_location
GitURL(url=git@github.com:vcs-python/libvcs.git,
        user=git,
        hostname=github.com,
        path=vcs-python/libvcs,
        suffix=.git,
        rule=core-git-scp)
```

Switch repo libvcs -> vcspull:

```python
>>> from libvcs.url.git import GitURL

>>> git_location = GitURL(url='git@github.com:vcs-python/libvcs.git')

>>> git_location.path = 'vcs-python/vcspull'

>>> git_location.to_url()
'git@github.com:vcs-python/vcspull.git'

# Switch them to gitlab:
>>> git_location.hostname = 'gitlab.com'

# Export to a `git clone` compatible URL.
>>> git_location.to_url()
'git@gitlab.com:vcs-python/vcspull.git'
```

See more in the [parser document](https://libvcs.git-pull.com/parse/index.html).

## Command Abstraction

Abstracts CLI commands for `git(1)`, `hg(1)`, `svn(1)` via a lightweight [`subprocess`](https://docs.python.org/3/library/subprocess.html) wrapper.

### Run Git Commands

```python
import pathlib
from libvcs.cmd.git import Git

git = Git(path=pathlib.Path.cwd() / 'my_git_repo')
git.clone(url='https://github.com/vcs-python/libvcs.git')
```

Above: [`libvcs.cmd.git.Git`](https://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git) using
[`Git.clone()`](http://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git.clone).

## Repository Synchronization

Synchronize your repositories using the
[`libvcs.sync`](https://libvcs.git-pull.com/sync/) module.

### Clone and Update Repositories

```python
import pathlib
from libvcs.sync.git import GitSync

repo = GitSync(
   url="https://github.com/vcs-python/libvcs",
   path=pathlib.Path().cwd() / "my_repo",
   remotes={
       'gitlab': 'https://gitlab.com/vcs-python/libvcs'
   }
)

# Update / clone repo:
>>> repo.update_repo()

# Get revision:
>>> repo.get_revision()
u'5c227e6ab4aab44bf097da2e088b0ff947370ab8'
```

Above: [`libvcs.sync.git.GitSync`](https://libvcs.git-pull.com/projects/git.html#libvcs.sync.git.GitSync) repository
object using
[`GitSync.update_repo()`](https://libvcs.git-pull.com/sync/git.html#libvcs.sync.git.GitSync.update_repo)
and
[`GitSync.get_revision()`](https://libvcs.git-pull.com/sync/git.html#libvcs.sync.git.GitSync.get_revision).

## Pytest plugin: Temporary VCS repositories for testing

libvcs [pytest plugin](https://libvcs.git-pull.com/pytest-plugin.html) provides [py.test fixtures] to swiftly create local VCS repositories and working repositories to test with. Repositories are automatically cleaned on test teardown.

[py.test fixtures]: https://docs.pytest.org/en/8.2.x/explanation/fixtures.html

### Use temporary, local VCS in py.test

```python
import pathlib

from libvcs.pytest_plugin import CreateRepoPytestFixtureFn
from libvcs.sync.git import GitSync


def test_repo_git_remote_checkout(
    create_git_remote_repo: CreateRepoPytestFixtureFn,
    tmp_path: pathlib.Path,
    projects_path: pathlib.Path,
) -> None:
    git_server = create_git_remote_repo()
    git_repo_checkout_dir = projects_path / "my_git_checkout"
    git_repo = GitSync(path=str(git_repo_checkout_dir), url=f"file://{git_server!s}")

    git_repo.obtain()
    git_repo.update_repo()

    assert git_repo.get_revision() == "initial"

    assert git_repo_checkout_dir.exists()
    assert pathlib.Path(git_repo_checkout_dir / ".git").exists()
```

Under the hood: fixtures bootstrap a temporary `$HOME` environment in a
[`TmpPathFactory`](https://docs.pytest.org/en/7.1.x/reference/reference.html#tmp-path-factory-factory-api)
for automatic cleanup and `pytest-xdist` compatibility..

## Donations

Your donations fund development of new features, testing and support. Your money will go directly to
maintenance and development of the project. If you are an individual, feel free to give whatever
feels right for the value you get out of the project.

See donation options at <https://www.git-pull.com/support.html>.

## More information

- Python support: 3.9+, pypy
- VCS supported: git(1), svn(1), hg(1)
- Source: <https://github.com/vcs-python/libvcs>
- Docs: <https://libvcs.git-pull.com>
- Changelog: <https://libvcs.git-pull.com/history.html>
- APIs for git, hg, and svn:
  - [`libvcs.url`](https://libvcs.git-pull.com/url/): URL Parser
  - [`libvcs.cmd`](https://libvcs.git-pull.com/cmd/): Commands
  - [`libvcs.sync`](https://libvcs.git-pull.com/sync/): Clone and update
- Issues: <https://github.com/vcs-python/libvcs/issues>
- Test Coverage: <https://codecov.io/gh/vcs-python/libvcs>
- pypi: <https://pypi.python.org/pypi/libvcs>
- Open Hub: <https://www.openhub.net/p/libvcs>
- License: [MIT](https://opensource.org/licenses/MIT).

[![Docs](https://github.com/vcs-python/libvcs/workflows/docs/badge.svg)](https://libvcs.git-pull.com/)
[![Build Status](https://github.com/vcs-python/libvcs/workflows/tests/badge.svg)](https://github.com/vcs-python/libvcs/actions?query=workflow%3A%22tests%22)

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "libvcs",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.9",
    "maintainer_email": null,
    "keywords": "abstraction, checkout, clone, git, hg, lib, library, libvcs, mercurial, scm, subversion, svn, vcs, version control, version-control, wrapper",
    "author": null,
    "author_email": "Tony Narlock <tony@git-pull.com>",
    "download_url": "https://files.pythonhosted.org/packages/fe/e8/e35647f031fa80a195303611256a3ba8f84c7028eb648876c0cb35a41227/libvcs-0.34.0.tar.gz",
    "platform": null,
    "description": "# `libvcs` &middot; [![Python Package](https://img.shields.io/pypi/v/libvcs.svg)](https://pypi.org/project/libvcs/) [![License](https://img.shields.io/github/license/vcs-python/libvcs.svg)](https://github.com/vcs-python/libvcs/blob/master/LICENSE) [![Code Coverage](https://codecov.io/gh/vcs-python/libvcs/branch/master/graph/badge.svg)](https://codecov.io/gh/vcs-python/libvcs)\n\nlibvcs is a lite, [typed](https://docs.python.org/3/library/typing.html), pythonic tool box for\ndetection and parsing of URLs, commanding, and syncing with `git`, `hg`, and `svn`. Powers\n[vcspull](https://www.github.com/vcs-python/vcspull/).\n\n## Overview\n\n### Key Features\n\n- **URL Detection and Parsing**: Validate and parse Git, Mercurial, and Subversion URLs.\n- **Command Abstraction**: Interact with VCS systems through a Python API.\n- **Repository Synchronization**: Clone and update repositories locally via\n  Python API.\n- **py.test fixtures**: Create temporary local repositories and working copies for testing for unit tests.\n\n_Supports Python 3.9 and above, Git (including AWS CodeCommit), Subversion, and Mercurial._\n\nTo **get started**, see the [quickstart guide](https://libvcs.git-pull.com/quickstart.html) for more information.\n\n```console\n$ pip install --user libvcs\n```\n\n## URL Detection and Parsing\n\nEasily validate and parse VCS URLs using the\n[`libvcs.url`](https://libvcs.git-pull.com/url/index.html) module:\n\n### Validate URLs\n\n```python\n>>> from libvcs.url.git import GitURL\n\n>>> GitURL.is_valid(url='https://github.com/vcs-python/libvcs.git')\nTrue\n```\n\n### Parse and adjust Git URLs:\n\n```python\n>>> from libvcs.url.git import GitURL\n\n>>> git_location = GitURL(url='git@github.com:vcs-python/libvcs.git')\n\n>>> git_location\nGitURL(url=git@github.com:vcs-python/libvcs.git,\n        user=git,\n        hostname=github.com,\n        path=vcs-python/libvcs,\n        suffix=.git,\n        rule=core-git-scp)\n```\n\nSwitch repo libvcs -> vcspull:\n\n```python\n>>> from libvcs.url.git import GitURL\n\n>>> git_location = GitURL(url='git@github.com:vcs-python/libvcs.git')\n\n>>> git_location.path = 'vcs-python/vcspull'\n\n>>> git_location.to_url()\n'git@github.com:vcs-python/vcspull.git'\n\n# Switch them to gitlab:\n>>> git_location.hostname = 'gitlab.com'\n\n# Export to a `git clone` compatible URL.\n>>> git_location.to_url()\n'git@gitlab.com:vcs-python/vcspull.git'\n```\n\nSee more in the [parser document](https://libvcs.git-pull.com/parse/index.html).\n\n## Command Abstraction\n\nAbstracts CLI commands for `git(1)`, `hg(1)`, `svn(1)` via a lightweight [`subprocess`](https://docs.python.org/3/library/subprocess.html) wrapper.\n\n### Run Git Commands\n\n```python\nimport pathlib\nfrom libvcs.cmd.git import Git\n\ngit = Git(path=pathlib.Path.cwd() / 'my_git_repo')\ngit.clone(url='https://github.com/vcs-python/libvcs.git')\n```\n\nAbove: [`libvcs.cmd.git.Git`](https://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git) using\n[`Git.clone()`](http://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git.clone).\n\n## Repository Synchronization\n\nSynchronize your repositories using the\n[`libvcs.sync`](https://libvcs.git-pull.com/sync/) module.\n\n### Clone and Update Repositories\n\n```python\nimport pathlib\nfrom libvcs.sync.git import GitSync\n\nrepo = GitSync(\n   url=\"https://github.com/vcs-python/libvcs\",\n   path=pathlib.Path().cwd() / \"my_repo\",\n   remotes={\n       'gitlab': 'https://gitlab.com/vcs-python/libvcs'\n   }\n)\n\n# Update / clone repo:\n>>> repo.update_repo()\n\n# Get revision:\n>>> repo.get_revision()\nu'5c227e6ab4aab44bf097da2e088b0ff947370ab8'\n```\n\nAbove: [`libvcs.sync.git.GitSync`](https://libvcs.git-pull.com/projects/git.html#libvcs.sync.git.GitSync) repository\nobject using\n[`GitSync.update_repo()`](https://libvcs.git-pull.com/sync/git.html#libvcs.sync.git.GitSync.update_repo)\nand\n[`GitSync.get_revision()`](https://libvcs.git-pull.com/sync/git.html#libvcs.sync.git.GitSync.get_revision).\n\n## Pytest plugin: Temporary VCS repositories for testing\n\nlibvcs [pytest plugin](https://libvcs.git-pull.com/pytest-plugin.html) provides [py.test fixtures] to swiftly create local VCS repositories and working repositories to test with. Repositories are automatically cleaned on test teardown.\n\n[py.test fixtures]: https://docs.pytest.org/en/8.2.x/explanation/fixtures.html\n\n### Use temporary, local VCS in py.test\n\n```python\nimport pathlib\n\nfrom libvcs.pytest_plugin import CreateRepoPytestFixtureFn\nfrom libvcs.sync.git import GitSync\n\n\ndef test_repo_git_remote_checkout(\n    create_git_remote_repo: CreateRepoPytestFixtureFn,\n    tmp_path: pathlib.Path,\n    projects_path: pathlib.Path,\n) -> None:\n    git_server = create_git_remote_repo()\n    git_repo_checkout_dir = projects_path / \"my_git_checkout\"\n    git_repo = GitSync(path=str(git_repo_checkout_dir), url=f\"file://{git_server!s}\")\n\n    git_repo.obtain()\n    git_repo.update_repo()\n\n    assert git_repo.get_revision() == \"initial\"\n\n    assert git_repo_checkout_dir.exists()\n    assert pathlib.Path(git_repo_checkout_dir / \".git\").exists()\n```\n\nUnder the hood: fixtures bootstrap a temporary `$HOME` environment in a\n[`TmpPathFactory`](https://docs.pytest.org/en/7.1.x/reference/reference.html#tmp-path-factory-factory-api)\nfor automatic cleanup and `pytest-xdist` compatibility..\n\n## Donations\n\nYour donations fund development of new features, testing and support. Your money will go directly to\nmaintenance and development of the project. If you are an individual, feel free to give whatever\nfeels right for the value you get out of the project.\n\nSee donation options at <https://www.git-pull.com/support.html>.\n\n## More information\n\n- Python support: 3.9+, pypy\n- VCS supported: git(1), svn(1), hg(1)\n- Source: <https://github.com/vcs-python/libvcs>\n- Docs: <https://libvcs.git-pull.com>\n- Changelog: <https://libvcs.git-pull.com/history.html>\n- APIs for git, hg, and svn:\n  - [`libvcs.url`](https://libvcs.git-pull.com/url/): URL Parser\n  - [`libvcs.cmd`](https://libvcs.git-pull.com/cmd/): Commands\n  - [`libvcs.sync`](https://libvcs.git-pull.com/sync/): Clone and update\n- Issues: <https://github.com/vcs-python/libvcs/issues>\n- Test Coverage: <https://codecov.io/gh/vcs-python/libvcs>\n- pypi: <https://pypi.python.org/pypi/libvcs>\n- Open Hub: <https://www.openhub.net/p/libvcs>\n- License: [MIT](https://opensource.org/licenses/MIT).\n\n[![Docs](https://github.com/vcs-python/libvcs/workflows/docs/badge.svg)](https://libvcs.git-pull.com/)\n[![Build Status](https://github.com/vcs-python/libvcs/workflows/tests/badge.svg)](https://github.com/vcs-python/libvcs/actions?query=workflow%3A%22tests%22)\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Lite, typed, python utilities for Git, SVN, Mercurial, etc.",
    "version": "0.34.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/vcs-python/libvcs/issues",
        "Changes": "https://github.com/vcs-python/libvcs/blob/master/CHANGES",
        "Documentation": "https://libvcs.git-pull.com",
        "Repository": "https://github.com/vcs-python/libvcs"
    },
    "split_keywords": [
        "abstraction",
        " checkout",
        " clone",
        " git",
        " hg",
        " lib",
        " library",
        " libvcs",
        " mercurial",
        " scm",
        " subversion",
        " svn",
        " vcs",
        " version control",
        " version-control",
        " wrapper"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "3edef7fe7dab67efaada11b4826bd707a6368fdb0b36f7192d38259d9dabfb35",
                "md5": "4493016d071d4d406025733847a3f5f1",
                "sha256": "7323ad11ccd0d2eeab17e2c1ce4011019271ee47e33d160ee66a2e5d0935a240"
            },
            "downloads": -1,
            "filename": "libvcs-0.34.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "4493016d071d4d406025733847a3f5f1",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.9",
            "size": 76559,
            "upload_time": "2024-11-22T19:37:35",
            "upload_time_iso_8601": "2024-11-22T19:37:35.120827Z",
            "url": "https://files.pythonhosted.org/packages/3e/de/f7fe7dab67efaada11b4826bd707a6368fdb0b36f7192d38259d9dabfb35/libvcs-0.34.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "fee8e35647f031fa80a195303611256a3ba8f84c7028eb648876c0cb35a41227",
                "md5": "61bbd0aaeca49157599ae605a851d61c",
                "sha256": "ab760edcb8bc40dc4bc56615fd3e5f024dfe65828d2991f1af9326cb39a42a13"
            },
            "downloads": -1,
            "filename": "libvcs-0.34.0.tar.gz",
            "has_sig": false,
            "md5_digest": "61bbd0aaeca49157599ae605a851d61c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.9",
            "size": 509749,
            "upload_time": "2024-11-22T19:37:37",
            "upload_time_iso_8601": "2024-11-22T19:37:37.046112Z",
            "url": "https://files.pythonhosted.org/packages/fe/e8/e35647f031fa80a195303611256a3ba8f84c7028eb648876c0cb35a41227/libvcs-0.34.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-22 19:37:37",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "vcs-python",
    "github_project": "libvcs",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "libvcs"
}
        
Elapsed time: 0.65759s