libvcs.sync.base

Base objects / classes for projects.

Adding your own VCS / Extending libvcs can be done through subclassing BaseSync.

Foundational tools to set up a VCS manager in libvcs.sync.

class libvcs.sync.base.VCSLocation(url, rev)[source]

Bases: NamedTuple

Generic VCS Location (URL and optional revision).

Create new instance of VCSLocation(url, rev)

Parameters:
url: str

Alias for field number 0

rev: Optional[str]

Alias for field number 1

_asdict()[source]

Return a new dict which maps field names to their values.

_field_defaults = {}
_fields = ('url', 'rev')
classmethod _make(iterable)[source]

Make a new VCSLocation object from a sequence or iterable

_replace(**kwds)[source]

Return a new VCSLocation object replacing specified fields with new values

libvcs.sync.base.convert_pip_url(pip_url)[source]

Parse pip URL via libvcs.sync.base.BaseSync.url.

Return type:

VCSLocation

Parameters:

pip_url (str)

class libvcs.sync.base.BaseSync(*, url, path, progress_callback=None, **kwargs)[source]

Bases: object

Base class for repositories.

Initialize a tool to manage a local VCS Checkout, Clone, Copy, or Work tree.

Parameters:
  • progress_callback (func) –

    Retrieve live progress from sys.stderr (useful for certain vcs commands like git pull. Use progress_callback:

    >>> import os
    >>> import sys
    >>> def progress_cb(output, timestamp):
    ...     sys.stdout.write(output)
    ...     sys.stdout.flush()
    >>> class Project(BaseSync):
    ...     bin_name = 'git'
    ...     def obtain(self, *args, **kwargs):
    ...         self.ensure_dir()
    ...         self.run(
    ...             ['clone', '--progress', self.url, self.path],
    ...             log_in_real_time=True
    ...         )
    >>> r = Project(
    ...     url=f'file://{create_git_remote_repo()}',
    ...     path=str(tmp_path),
    ...     progress_callback=progress_cb
    ... )
    >>> r.obtain()
    Cloning into '...'...
    remote: Enumerating objects: ...
    remote: Counting objects: ...% (...)...
    ...
    remote: Total ... (delta 0), reused 0 (delta 0), pack-reused 0
    ...
    Receiving objects: ...% (...)...
    ...
    >>> assert r.path.exists()
    >>> assert pathlib.Path(r.path / '.git').exists()
    

  • url (str)

  • path (str | PathLike[str])

  • kwargs (Any)

log_in_real_time = None

Log command output to buffer

bin_name: str = ''

VCS app name, e.g. ‘git’

schemes: tuple[str, ...] = ()

List of supported schemes to register in urlparse.uses_netloc

__init__(*, url, path, progress_callback=None, **kwargs)[source]

Initialize a tool to manage a local VCS Checkout, Clone, Copy, or Work tree.

Parameters:
  • progress_callback (func) –

    Retrieve live progress from sys.stderr (useful for certain vcs commands like git pull. Use progress_callback:

    >>> import os
    >>> import sys
    >>> def progress_cb(output, timestamp):
    ...     sys.stdout.write(output)
    ...     sys.stdout.flush()
    >>> class Project(BaseSync):
    ...     bin_name = 'git'
    ...     def obtain(self, *args, **kwargs):
    ...         self.ensure_dir()
    ...         self.run(
    ...             ['clone', '--progress', self.url, self.path],
    ...             log_in_real_time=True
    ...         )
    >>> r = Project(
    ...     url=f'file://{create_git_remote_repo()}',
    ...     path=str(tmp_path),
    ...     progress_callback=progress_cb
    ... )
    >>> r.obtain()
    Cloning into '...'...
    remote: Enumerating objects: ...
    remote: Counting objects: ...% (...)...
    ...
    remote: Total ... (delta 0), reused 0 (delta 0), pack-reused 0
    ...
    Receiving objects: ...% (...)...
    ...
    >>> assert r.path.exists()
    >>> assert pathlib.Path(r.path / '.git').exists()
    

  • url (str)

  • path (str | PathLike[str])

  • kwargs (Any)

Return type:

None

progress_callback

Callback for run updates

path: Path

Directory to check out

log: CmdLoggingAdapter

Logging attribute

property repo_name: str

Return the short name of a repo checkout.

classmethod from_pip_url(pip_url, **kwargs)[source]

Create synchronization object from pip-style URL.

Return type:

BaseSync

Parameters:
run(cmd, cwd=None, check_returncode=True, log_in_real_time=None, *args, **kwargs)[source]

Return combined stderr/stdout from a command.

This method will also prefix the VCS command bin_name. By default runs using the cwd libvcs.sync.base.BaseSync.path of the repo.

Parameters:
Returns:

combined stdout/stderr in a big string, newlines retained

Return type:

str

ensure_dir(*args, **kwargs)[source]

Assure destination path exists. If not, create directories.

Return type:

bool

Parameters:
update_repo(*args, **kwargs)[source]

Pull latest changes to here from remote repository.

Return type:

None

Parameters:
obtain(*args, **kwargs)[source]

Checkout initial VCS repository or working copy from remote repository.

Return type:

None

Parameters: