pcvs.helpers.git module

class pcvs.helpers.git.Blob(repo, id, prefix='', data='')[source]

Bases: Tree

Maps a Git ‘blob’ object, dedicated to hold data (“leaves” in Git trees)

class pcvs.helpers.git.Branch(repo, name='master')[source]

Bases: Reference

Maps to a regular Git branch.

property name
class pcvs.helpers.git.Commit(repo, obj, metadata={})[source]

Bases: Reference

Maps to a regular Git commit

get_info()[source]

Return commit metadata stored as a dict.

It may contains extra infos compared to what a commit usually contains

class pcvs.helpers.git.GitByAPI(prefix=None)[source]

Bases: GitByGeneric

Manage repository through a third-party Python module.

Currently, this work is based on pygit2.

property branches

Returns the list of available local branche names from this repo.

This is an abstract function as its behavior depends on derived classes.

close()[source]

Unlock the repository.

commit(tree, msg='No data', timestamp=None, parent=None, orphan=False)[source]

Create a commit from changes.

Parameters:
  • tree (any) – the changes tree to store as a commit

  • msg (str) – the commit msg

  • parent (any) – the parent commit

  • orphan (boolean) – flag to create a dangling commit (=no-parent)

Timestamp:

a commit date (current if not provided)

Type:

int

diff_tree(prefix=None, src_rev=None, dst_rev=None)[source]

Compare & return the list of patches

gc()[source]

Run the garbage collector

get_branch_from_str(name)[source]
get_parents(ref)[source]

Retrieve parents for a given ref.

This method is not a part of a Reference object as the approach changes depending on the Git method used (lazy resolution).

Parameters:

ref (Reference) – the revision

get_tree(rev=None, prefix='')[source]

Retrieve data associated with a given prefix. A tree can used to set which ref should be used.

Param[in] tree:

the ref from where get the data

Param[in] prefix:

the unique prefix associated with data

insert_tree(prefix, data, root=None)[source]

Create a new tree mapping a prefix filled with ‘data’.

Param[in] prefix:

the prefix under Git tree.

Param[in] data:

the data to store.

is_open()[source]

Is the directory currently open ?

iterate_over(rev=None)[source]

starting from the ref, iterate references backwards (from newest to oldest).

Parameters:

ref (Reference) – the starting point

list_commits(rev=None, since=None, until=None)[source]

List past commits finishing with ‘rev’.

The list can be shrunk with a start & end

Parameters:
  • rev – the revision to extract commit from

  • since (date) – the oldest commit should be newer than this date

  • until (date) – the newest commit should be older than this date

Typ rev:

any

list_files(rev=None, prefix='')[source]

For a given revision, list files (not only changed ones).

Parameters:

rev (Reference) – the revision

new_branch(name, cid=None)[source]
open(bare=True)[source]

Open a new directory. Also lock to avoid races.

revparse(ref)[source]

Convert a revision (tag, branch, commit) to a regular reference.

Parameters:

rev (Reference) – Reference

set_branch(branch, commit)[source]
class pcvs.helpers.git.GitByCLI(prefix='')[source]

Bases: GitByGeneric

Git endpoint ot manipulate a repository through basic CLI.

Currently relying on the sh module.

property branches

Returns the list of available local branche names from this repo.

This is an abstract function as its behavior depends on derived classes.

close()[source]

Unlock the repository.

commit(tree, msg='VOID', timestamp=None, parent=None, orphan=False)[source]

Create a commit from changes.

Parameters:
  • tree (any) – the changes tree to store as a commit

  • msg (str) – the commit msg

  • parent (any) – the parent commit

  • orphan (boolean) – flag to create a dangling commit (=no-parent)

Timestamp:

a commit date (current if not provided)

Type:

int

diff_tree(prefix=None, src_rev=None, dst_rev=None)[source]

Compare & return the list of patches

gc()[source]

Run the garbage collector

get_branch_from_str(name)[source]
get_parents(ref)[source]

Retrieve parents for a given ref.

This method is not a part of a Reference object as the approach changes depending on the Git method used (lazy resolution).

Parameters:

ref (Reference) – the revision

get_tree(rev=None, prefix='')[source]

Retrieve data associated with a given prefix. A tree can used to set which ref should be used.

Param[in] tree:

the ref from where get the data

Param[in] prefix:

the unique prefix associated with data

insert_tree(prefix, data, root=None)[source]

Create a new tree mapping a prefix filled with ‘data’.

Param[in] prefix:

the prefix under Git tree.

Param[in] data:

the data to store.

is_open()[source]

Is the directory currently open ?

iterate_over(ref)[source]

starting from the ref, iterate references backwards (from newest to oldest).

Parameters:

ref (Reference) – the starting point

list_commits(rev=None, since='', until='')[source]

List past commits finishing with ‘rev’.

The list can be shrunk with a start & end

Parameters:
  • rev – the revision to extract commit from

  • since (date) – the oldest commit should be newer than this date

  • until (date) – the newest commit should be older than this date

Typ rev:

any

list_files(prefix)[source]

For a given revision, list files (not only changed ones).

Parameters:

rev (Reference) – the revision

new_branch(name, cid=None)[source]
open(bare=True)[source]

Open a new directory. Also lock to avoid races.

revparse(rev)[source]

Convert a revision (tag, branch, commit) to a regular reference.

Parameters:

rev (Reference) – Reference

set_branch(branch, commit)[source]
class pcvs.helpers.git.GitByGeneric(prefix=None, head='unknown/00000000')[source]

Bases: ABC

Create a Git endpoint able to discuss efficiently with repositories.

This base classe serves abstract methods to be implemented to create a new derived class. Currently are provided: - GitByAPI: relies on python module pygit2 (requires libgit2) - GitByCLI: based on regular Git program invocations (require git program)

abstract property branches

Returns the list of available local branche names from this repo.

This is an abstract function as its behavior depends on derived classes.

abstract close()[source]

Unlock the repository.

abstract commit(tree, msg='No data', timestamp=None, parent=None, orphan=False)[source]

Create a commit from changes.

Parameters:
  • tree (any) – the changes tree to store as a commit

  • msg (str) – the commit msg

  • parent (any) – the parent commit

  • orphan (boolean) – flag to create a dangling commit (=no-parent)

Timestamp:

a commit date (current if not provided)

Type:

int

abstract diff_tree(prefix, src_rev, dst_rev)[source]

Compare & return the list of patches

abstract gc()[source]

Run the garbage collector

get_head()[source]

Get the current repo’s HEAD (used when no default)

Returns:

a ref to the HEAD as a branch

Return type:

Branch

abstract get_parents(ref)[source]

Retrieve parents for a given ref.

This method is not a part of a Reference object as the approach changes depending on the Git method used (lazy resolution).

Parameters:

ref (Reference) – the revision

abstract get_tree(tree, prefix)[source]

Retrieve data associated with a given prefix. A tree can used to set which ref should be used.

Param[in] tree:

the ref from where get the data

Param[in] prefix:

the unique prefix associated with data

abstract insert_tree(prefix, data)[source]

Create a new tree mapping a prefix filled with ‘data’.

Param[in] prefix:

the prefix under Git tree.

Param[in] data:

the data to store.

abstract is_open()[source]

Is the directory currently open ?

abstract iterate_over(ref)[source]

starting from the ref, iterate references backwards (from newest to oldest).

Parameters:

ref (Reference) – the starting point

abstract list_commits(rev, since, until)[source]

List past commits finishing with ‘rev’.

The list can be shrunk with a start & end

Parameters:
  • rev – the revision to extract commit from

  • since (date) – the oldest commit should be newer than this date

  • until (date) – the newest commit should be older than this date

Typ rev:

any

abstract list_files(rev)[source]

For a given revision, list files (not only changed ones).

Parameters:

rev (Reference) – the revision

abstract open()[source]

Open a new directory. Also lock to avoid races.

abstract revparse(rev)[source]

Convert a revision (tag, branch, commit) to a regular reference.

Parameters:

rev (Reference) – Reference

set_head(new_head)[source]

Move the repo HEAD (used when no default ref is provided)

set_identity(authname, authmail, commname, commmail)[source]

Identities to be used if a commit is created.

Parameters:
  • authname (str) – author’s name

  • authmail (str) – author’s email

  • commname (str) – Committer’s name

  • commmail (str) – Committer’s email

set_path(prefix)[source]

Associate a new directory to this bank.

Parameters:

prefix (str) – the prefix locating the Git repo

class pcvs.helpers.git.Reference(repo)[source]

Bases: object

Maps an object which can be “pointed” (as a Git semantic). It can usually be used to refer a commit, a simple hash or a branch.

property repo

Getter to the repo this reference comes from.

class pcvs.helpers.git.Tree(repo, id, prefix='', children=[])[source]

Bases: Reference

Maps to a git-lowlevel Tree object

classmethod as_root(repo, hdl, children=[])[source]

Create a Tree and attach it with the git-specific handler (if any)

Parameters:
  • repo (any) – the repo handle

  • hdl (any) – the git-specific root handle

  • children (any) – any prebuild children for this root node

Returns:

the created Tree object

Return type:

Tree

pcvs.helpers.git.elect_handler(prefix=None)[source]

Select the proper repository handler based on python support

Python 3.7+-based PCVS installations come with pygit2, thanks to provided wheels. Older versions are relying on regular Git commands (as wheels are not provided for Python3.6 and older & building pygit2 requires specific libgit2 version to be installed, hardening the installation process)

pcvs.helpers.git.generate_data_hash(data)[source]

Hash data with git protocol.

Parameters:

data (str) – data to hash

Returns:

hashed data

Return type:

str

pcvs.helpers.git.get_current_usermail()[source]

Get the git user mail.

Returns:

git user mail

Return type:

str

pcvs.helpers.git.get_current_username()[source]

Get the git username.

Returns:

git username

Return type:

str

pcvs.helpers.git.request_git_attr(k)[source]

Get a git configuration.

Parameters:

k (str) – parameter to get

Returns:

a git configuration

Return type:

str