dulwich.object_store

module documentation

Git object store interfaces and implementation.

Class BaseObjectStore Object store interface.
Class BitmapReachability Bitmap-accelerated implementation of ObjectReachabilityProvider.
Class BucketBasedObjectStore Object store implementation that uses a bucket store like S3 as backend.
Class DiskObjectStore Git-style object store that exists on disk.
Class GraphTraversalReachability Naive graph traversal implementation of ObjectReachabilityProvider.
Class GraphWalker Protocol for graph walker objects.
Class MemoryObjectStore Object store that keeps all objects in memory.
Class MissingObjectFinder Find the objects missing from another object store.
Class ObjectIterator Interface for iterating over objects.
Class ObjectReachabilityProvider Protocol for computing object reachability queries.
Class ObjectStoreGraphWalker Graph walker that finds what commits are missing from an object store.
Class OverlayObjectStore Object store that can overlay multiple object stores.
Class PackBasedObjectStore Object store that uses pack files for storage.
Class PackCapableObjectStore Object store that supports pack operations.
Class PackContainer Protocol for containers that can accept pack files.
Function commit_tree_changes Commit a specified set of changes to a tree structure.
Function find_shallow Find shallow commits according to a given depth.
Function get_depth Return the current available depth for the given head.
Function iter_commit_contents Iterate the contents of the repository at the specified commit.
Function iter_tree_contents Iterate the contents of a tree and all subtrees.
Function peel_sha Peel all tags from a SHA.
Function read_packs_file Yield the packs listed in a packs file.
Function tree_lookup_path Look up an object in a Git tree.
Constant DEFAULT_TEMPFILE_GRACE_PERIOD Undocumented
Constant INFODIR Undocumented
Constant PACK_MODE Undocumented
Constant PACKDIR Undocumented
Function _collect_ancestors Collect all ancestors of heads up to (excluding) those in common.
Function _collect_filetree_revs Collect SHA1s of files and directories for specified tree.
Function _split_commits_and_tags Split object id list into three lists with commit, tag, and other SHAs.
def commit_tree_changes(object_store: BaseObjectStore, tree: ObjectID | Tree, changes: Sequence[tuple[bytes, int | None, ObjectID | None]]) -> ObjectID:

Commit a specified set of changes to a tree structure.

This will apply a set of changes on top of an existing tree, storing new objects in object_store.

changes are a list of tuples with (path, mode, object_sha). Paths can be both blobs and trees. See the mode and object sha to None deletes the path.

This method works especially well if there are only a small number of changes to a big tree. For a large number of changes to a large tree, use e.g. commit_tree.

Returns: New tree root object

Parameters
object_store:BaseObjectStoreObject store to store new objects in and retrieve old ones from.
tree:ObjectID | TreeOriginal tree root (SHA or Tree object)
changes:Sequence[tuple[bytes, int | None, ObjectID | None]]changes to apply
Returns
ObjectIDUndocumented
def find_shallow(store: ObjectContainer, heads: Iterable[ObjectID], depth: int) -> tuple[set[ObjectID], set[ObjectID]]:

Find shallow commits according to a given depth.

Returns: A tuple of (shallow, not_shallow), sets of SHAs that should be
considered shallow and unshallow according to the arguments. Note that these sets may overlap if a commit is reachable along multiple paths.
Parameters
store:ObjectContainerAn ObjectStore for looking up objects.
heads:Iterable[ObjectID]Iterable of head SHAs to start walking from.
depth:intThe depth of ancestors to include. A depth of one includes only the heads themselves.
Returns
tuple[set[ObjectID], set[ObjectID]]Undocumented
def get_depth(store: ObjectContainer, head: ObjectID, get_parents: Callable[..., list[ObjectID]] = lambda commit: commit.parents, max_depth: int | None = None) -> int:

Return the current available depth for the given head.

For commits with multiple parents, the largest possible depth will be returned.

Parameters
store:ObjectContainerObject store to search in
head:ObjectIDcommit to start from
get_parents:Callable[..., list[ObjectID]]optional function for getting the parents of a commit
max_depth:int | Nonemaximum depth to search
Returns
intUndocumented
def iter_commit_contents(store: ObjectContainer, commit: Commit | ObjectID | RawObjectID, *, include: Sequence[str | bytes | Path] | None = None) -> Iterator[TreeEntry]:

Iterate the contents of the repository at the specified commit.

This is a wrapper around iter_tree_contents() and tree_lookup_path() to simplify the common task of getting the contest of a repo at a particular commit. See also dulwich.index.build_file_from_blob() for writing individual files to disk.

Yields: TreeEntry namedtuples for all matching files in a commit.

Parameters
store:ObjectContainerObject store to get trees from
commit:Commit | ObjectID | RawObjectIDCommit object, or SHA1 of a commit
include:Sequence[str | bytes | Path] | Noneif provided, only the entries whose paths are in the list, or whose parent tree is in the list, will be included. Note that duplicate or overlapping paths (e.g. ["foo", "foo/bar"]) may result in duplicate entries
Returns
Iterator[TreeEntry]Undocumented
def iter_tree_contents(store: ObjectContainer, tree_id: ObjectID | None, *, include_trees: bool = False) -> Iterator[TreeEntry]:

Iterate the contents of a tree and all subtrees.

Iteration is depth-first pre-order, as in e.g. os.walk.

Yields: TreeEntry namedtuples for all the objects in a tree.

Parameters
store:ObjectContainerObject store to get trees from
tree_id:ObjectID | NoneSHA1 of the tree.
include_trees:boolIf True, include tree objects in the iteration.
Returns
Iterator[TreeEntry]Undocumented
def peel_sha(store: ObjectContainer, sha: ObjectID | RawObjectID) -> tuple[ShaFile, ShaFile]:

Peel all tags from a SHA.

Returns: The fully-peeled SHA1 of a tag object, after peeling all
intermediate tags; if the original ref does not point to a tag, this will equal the original SHA1.
Parameters
store:ObjectContainerObject store to get objects from
sha:ObjectID | RawObjectIDThe object SHA to peel.
Returns
tuple[ShaFile, ShaFile]Undocumented
def read_packs_file(f: BinaryIO) -> Iterator[str]:

Yield the packs listed in a packs file.

def tree_lookup_path(lookup_obj: Callable[[(ObjectID | RawObjectID)], ShaFile], root_sha: ObjectID | RawObjectID, path: bytes) -> tuple[int, ObjectID]:

Look up an object in a Git tree.

Returns: A tuple of (mode, SHA) of the resulting path.

Parameters
lookup_obj:Callable[[(ObjectID | RawObjectID)], ShaFile]Callback for retrieving object by SHA1
root_sha:ObjectID | RawObjectIDSHA1 of the root tree
path:bytesPath to lookup
Returns
tuple[int, ObjectID]Undocumented
DEFAULT_TEMPFILE_GRACE_PERIOD =

Undocumented

Value
14 * 24 * 60 * 60
INFODIR: str =

Undocumented

Value
'info'
PACK_MODE =

Undocumented

Value
292 if sys.platform != 'win32' else 420
PACKDIR: str =

Undocumented

Value
'pack'
def _collect_ancestors(store: ObjectContainer, heads: Iterable[ObjectID], common: frozenset[ObjectID] = frozenset(), shallow: frozenset[ObjectID] = frozenset(), get_parents: Callable[[Commit], list[ObjectID]] = lambda commit: commit.parents) -> tuple[set[ObjectID], set[ObjectID]]:

Collect all ancestors of heads up to (excluding) those in common.

Returns: a tuple (A, B) where A - all commits reachable
from heads but not present in common, B - common (shared) elements that are directly reachable from heads
Parameters
store:ObjectContainerObject store to get commits from
heads:Iterable[ObjectID]commits to start from
common:frozenset[ObjectID]commits to end at, or empty set to walk repository completely
shallow:frozenset[ObjectID]Set of shallow commits
get_parents:Callable[[Commit], list[ObjectID]]Optional function for getting the parents of a commit.
Returns
tuple[set[ObjectID], set[ObjectID]]Undocumented
def _collect_filetree_revs(obj_store: ObjectContainer, tree_sha: ObjectID, kset: set[ObjectID]):

Collect SHA1s of files and directories for specified tree.

Parameters
obj_store:ObjectContainerObject store to get objects by SHA from
tree_sha:ObjectIDtree reference to walk
kset:set[ObjectID]set to fill with references to files and directories
def _split_commits_and_tags(obj_store: ObjectContainer, lst: Iterable[ObjectID], *, unknown: str = 'error') -> tuple[set[ObjectID], set[ObjectID], set[ObjectID]]:

Split object id list into three lists with commit, tag, and other SHAs.

Commits referenced by tags are included into commits list as well. Only SHA1s known in this repository will get through, controlled by the unknown parameter.

Returns: A tuple of (commits, tags, others) SHA1s

Parameters
obj_store:ObjectContainerObject store to get objects by SHA1 from
lst:Iterable[ObjectID]Collection of commit and tag SHAs
unknown:strHow to handle unknown objects: "error", "warn", or "ignore"
Returns
tuple[set[ObjectID], set[ObjectID], set[ObjectID]]Undocumented