# `libvcs` · [](https://pypi.org/project/libvcs/) [](https://github.com/vcs-python/libvcs/blob/master/LICENSE) [](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
_Supports Python 3.9 and above_
Features for Git, Subversion, and Mercurial:
- **Detect and parse** VCS URLs
- **Command** VCS via python API
- **Sync** repos locally
- **Test fixtures** for temporary local repos and working copies
To **get started**, see the [quickstart](https://libvcs.git-pull.com/quickstart.html) for more.
```console
$ pip install --user libvcs
```
## URL Parser
You can validate and parse Git, Mercurial, and Subversion URLs through
[`libvcs.url`](https://libvcs.git-pull.com/url/index.html):
Validate:
```python
>>> from libvcs.url.git import GitURL
>>> GitURL.is_valid(url='https://github.com/vcs-python/libvcs.git')
True
```
Parse and adjust a Git URL:
```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).
## Commands
Simple [`subprocess`](https://docs.python.org/3/library/subprocess.html) wrappers around `git(1)`,
`hg(1)`, `svn(1)`. Here is [`Git`](https://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git) w/
[`Git.clone`](http://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git.clone):
```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')
```
## Sync
Create a [`GitSync`](https://libvcs.git-pull.com/projects/git.html#libvcs.sync.git.GitProject)
object of the project to inspect / checkout / update:
```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'
```
## Pytest plugin
libvcs also provides a test rig for local repositories. It automatically can provide clean local
repositories and working copies for git, svn, and mercurial. They are automatically cleaned up after
each test.
It works by bootstrapping 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.
```python
import pathlib
from libvcs.pytest_plugin import CreateProjectCallbackFixtureProtocol
from libvcs.sync.git import GitSync
def test_repo_git_remote_checkout(
create_git_remote_repo: CreateProjectCallbackFixtureProtocol,
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()
```
Learn more on the docs at https://libvcs.git-pull.com/pytest-plugin.html
## 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).
[](https://libvcs.git-pull.com/)
[](https://github.com/vcs-python/libvcs/actions?query=workflow%3A%22tests%22)
Raw data
{
"_id": null,
"home_page": "http://github.com/vcs-python/libvcs/",
"name": "libvcs",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "libvcs, git, mercurial, hg, svn, subversion, library, lib, wrapper, vcs, version control, scm, clone, checkout, abstraction, version-control",
"author": "Tony Narlock",
"author_email": "tony@git-pull.com",
"download_url": "https://files.pythonhosted.org/packages/0a/a5/8720ebc47f75636a1abd307e459ffa802428bf64a16117cf31a27ee7988e/libvcs-0.29.0.tar.gz",
"platform": null,
"description": "# `libvcs` · [](https://pypi.org/project/libvcs/) [](https://github.com/vcs-python/libvcs/blob/master/LICENSE) [](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_Supports Python 3.9 and above_\n\nFeatures for Git, Subversion, and Mercurial:\n\n- **Detect and parse** VCS URLs\n- **Command** VCS via python API\n- **Sync** repos locally\n- **Test fixtures** for temporary local repos and working copies\n\nTo **get started**, see the [quickstart](https://libvcs.git-pull.com/quickstart.html) for more.\n\n```console\n$ pip install --user libvcs\n```\n\n## URL Parser\n\nYou can validate and parse Git, Mercurial, and Subversion URLs through\n[`libvcs.url`](https://libvcs.git-pull.com/url/index.html):\n\nValidate:\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\nParse and adjust a Git URL:\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## Commands\n\nSimple [`subprocess`](https://docs.python.org/3/library/subprocess.html) wrappers around `git(1)`,\n`hg(1)`, `svn(1)`. Here is [`Git`](https://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git) w/\n[`Git.clone`](http://libvcs.git-pull.com/cmd/git.html#libvcs.cmd.git.Git.clone):\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\n## Sync\n\nCreate a [`GitSync`](https://libvcs.git-pull.com/projects/git.html#libvcs.sync.git.GitProject)\nobject of the project to inspect / checkout / update:\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\n## Pytest plugin\n\nlibvcs also provides a test rig for local repositories. It automatically can provide clean local\nrepositories and working copies for git, svn, and mercurial. They are automatically cleaned up after\neach test.\n\nIt works by bootstrapping 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.\n\n```python\nimport pathlib\n\nfrom libvcs.pytest_plugin import CreateProjectCallbackFixtureProtocol\nfrom libvcs.sync.git import GitSync\n\n\ndef test_repo_git_remote_checkout(\n create_git_remote_repo: CreateProjectCallbackFixtureProtocol,\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\nLearn more on the docs at https://libvcs.git-pull.com/pytest-plugin.html\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[](https://libvcs.git-pull.com/)\n[](https://github.com/vcs-python/libvcs/actions?query=workflow%3A%22tests%22)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lite, typed, python utilities for Git, SVN, Mercurial, etc.",
"version": "0.29.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",
"Homepage": "http://github.com/vcs-python/libvcs/",
"Repository": "https://github.com/vcs-python/libvcs"
},
"split_keywords": [
"libvcs",
" git",
" mercurial",
" hg",
" svn",
" subversion",
" library",
" lib",
" wrapper",
" vcs",
" version control",
" scm",
" clone",
" checkout",
" abstraction",
" version-control"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ba63c62a45861dc8c023d2f721629c00cd53868eeb7a64471a19dbffa68be7c8",
"md5": "f73b5593b80068f4064e405a04e1effb",
"sha256": "1c2ffeb8587900f59b6cb4447e409faeedb48e55406a7c215aa0944017403e0a"
},
"downloads": -1,
"filename": "libvcs-0.29.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f73b5593b80068f4064e405a04e1effb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 74067,
"upload_time": "2024-03-24T17:26:15",
"upload_time_iso_8601": "2024-03-24T17:26:15.945112Z",
"url": "https://files.pythonhosted.org/packages/ba/63/c62a45861dc8c023d2f721629c00cd53868eeb7a64471a19dbffa68be7c8/libvcs-0.29.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0aa58720ebc47f75636a1abd307e459ffa802428bf64a16117cf31a27ee7988e",
"md5": "0e72eab3cb61d77cb3bf8161d693dbf1",
"sha256": "c043ba8423ae6976e1310f7c6d654ee3d4b8b9c974e95e18b0f8ec7ec8ea6552"
},
"downloads": -1,
"filename": "libvcs-0.29.0.tar.gz",
"has_sig": false,
"md5_digest": "0e72eab3cb61d77cb3bf8161d693dbf1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 448334,
"upload_time": "2024-03-24T17:26:18",
"upload_time_iso_8601": "2024-03-24T17:26:18.887298Z",
"url": "https://files.pythonhosted.org/packages/0a/a5/8720ebc47f75636a1abd307e459ffa802428bf64a16117cf31a27ee7988e/libvcs-0.29.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-24 17:26:18",
"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"
}
JSON
