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)

Bases: NamedTuple

Generic VCS Location (URL and optional revision).

Create new instance of VCSLocation(url, rev)

Parameters:

• url (str) –

• rev (str | None) –

url: str

Alias for field number 0

rev: Optional[str]

Alias for field number 1

_asdict()

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

_field_defaults = {}

_fields = ('url', 'rev')

classmethod _make(iterable)

Make a new VCSLocation object from a sequence or iterable

_replace(**kwds)

Return a new VCSLocation object replacing specified fields with new values

libvcs.sync.base.convert_pip_url(pip_url)

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

Return type:

VCSLocation

Parameters:

pip_url (str) –

class libvcs.sync.base.BaseSync(*, url, dir, progress_callback=None, **kwargs)

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.dir],
  ...             log_in_real_time=True
  ...         )
  >>> r = Project(
  ...     url=f'file://{create_git_remote_repo()}',
  ...     dir=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.dir.exists()
  >>> assert pathlib.Path(r.dir / '.git').exists()
  

• url (str) –

• dir (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, dir, progress_callback=None, **kwargs)

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.dir],
  ...             log_in_real_time=True
  ...         )
  >>> r = Project(
  ...     url=f'file://{create_git_remote_repo()}',
  ...     dir=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.dir.exists()
  >>> assert pathlib.Path(r.dir / '.git').exists()
  

• url (str) –

• dir (str | PathLike[str]) –

• kwargs (Any) –

Return type:

None

progress_callback

Callback for run updates

dir: 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)

Create synchronization object from pip-style URL.

Return type:

BaseSync

Parameters:

• pip_url (str) –

• kwargs (Any) –

run(cmd, cwd=None, check_returncode=True, log_in_real_time=None, *args, **kwargs)

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.dir of the repo.

Parameters:

• cwd (str) – dir command is run from, defaults to libvcs.sync.base.BaseSync.dir.

• check_returncode (bool) – Indicate whether a CommandError should be raised if return code is different from 0.

• cmd (str | bytes | PathLike[str] | PathLike[bytes] | Sequence[str | bytes | PathLike[str] | PathLike[bytes]]) –

• log_in_real_time (bool | None) –

• args (Any) –

• kwargs (Any) –

Returns:

combined stdout/stderr in a big string, newlines retained

Return type:

str

ensure_dir(*args, **kwargs)

Assure destination path exists. If not, create directories.

Return type:

bool

Parameters:

• args (Any) –

• kwargs (Any) –

update_repo(*args, **kwargs)

Pull latest changes to here from remote repository.

Return type:

None

Parameters:

• args (Any) –

• kwargs (Any) –

obtain(*args, **kwargs)

Checkout initial VCS repository or working copy from remote repository.

Return type:

None

Parameters:

• args (Any) –

• kwargs (Any) –