dulwich.pack.Pack

class documentation

class Pack:

Constructors: Pack.from_lazy_objects(data_fn, idx_fn), Pack.from_objects(data, idx), Pack(basename, object_format, resolve_ext_ref, delta_window_size, ...)

View In Hierarchy

A Git pack object.

Class Method	`from_lazy_objects`	Create a new pack object from callables to load pack data and index objects.
Class Method	`from_objects`	Create a new pack object from pack data and index objects.
Method	`__contains__`	Check whether this pack contains a particular SHA1.
Method	`__del__`	Ensure pack file is closed when Pack is garbage collected.
Method	`__enter__`	Enter context manager.
Method	`__eq__`	Check equality with another pack.
Method	`__exit__`	Exit context manager.
Method	`__getitem__`	Retrieve the specified SHA1.
Method	`__init__`	Initialize a Pack object.
Method	`__iter__`	Iterate over all the sha1s of the objects in this pack.
Method	`__len__`	Number of entries in this pack.
Method	`__repr__`	Return string representation of this pack.
Method	`check`	Check the integrity of this pack.
Method	`check_length_and_checksum`	Sanity check the length and checksum of the pack index and data.
Method	`close`	Close the pack file and index.
Method	`ensure_bitmap`	Ensure a bitmap exists for this pack, generating one if needed.
Method	`entries`	Yield entries summarizing the contents of this pack.
Method	`get_raw`	Get raw object data by SHA1.
Method	`get_ref`	Get the object for a ref SHA, only looking in this pack.
Method	`get_stored_checksum`	Return the stored checksum of the pack data.
Method	`get_unpacked_object`	Get the unpacked object for a sha.
Method	`iter_unpacked`	Iterate over all unpacked objects in this pack.
Method	`iter_unpacked_subset`	Iterate over unpacked objects in subset.
Method	`iterobjects`	Iterate over the objects in this pack.
Method	`iterobjects_subset`	Iterate over a subset of objects in this pack.
Method	`keep`	Add a .keep file for the pack, preventing git from garbage collecting it.
Method	`name`	The SHA over the SHAs of the objects in this pack.
Method	`pack_tuples`	Return pack tuples for all objects in pack.
Method	`resolve_object`	Resolve an object, possibly resolving deltas when necessary.
Method	`sorted_entries`	Return entries in this pack, sorted by SHA.
Instance Variable	`big_file_threshold`	Undocumented
Instance Variable	`delta_base_cache_limit`	Undocumented
Instance Variable	`delta_cache_size`	Undocumented
Instance Variable	`delta_window_size`	Undocumented
Instance Variable	`depth`	Undocumented
Instance Variable	`object_format`	Undocumented
Instance Variable	`resolve_ext_ref`	Undocumented
Instance Variable	`threads`	Undocumented
Instance Variable	`window_memory`	Undocumented
Property	`bitmap`	The bitmap being used, if available.
Property	`data`	The pack data object being used.
Property	`index`	The index being used.
Property	`mmap_size`	Return the total mmapped memory usage of this pack.
Instance Variable	`_basename`	Undocumented
Instance Variable	`_bitmap`	Undocumented
Instance Variable	`_bitmap_path`	Undocumented
Instance Variable	`_data`	Undocumented
Instance Variable	`_data_load`	Undocumented
Instance Variable	`_data_path`	Undocumented
Instance Variable	`_idx`	Undocumented
Instance Variable	`_idx_load`	Undocumented
Instance Variable	`_idx_path`	Undocumented

@classmethod

def from_lazy_objects(cls, data_fn: Callable[[], PackData], idx_fn: Callable[[], PackIndex]) -> Pack: ¶

Create a new pack object from callables to load pack data and index objects.

@classmethod

def from_objects(cls, data: PackData, idx: PackIndex) -> Pack: ¶

Create a new pack object from pack data and index objects.

def __contains__(self, sha1: ObjectID | RawObjectID) -> bool: ¶

Check whether this pack contains a particular SHA1.

def __del__(self): ¶

Ensure pack file is closed when Pack is garbage collected.

def __enter__(self) -> Pack: ¶

Enter context manager.

def __eq__(self, other: object) -> bool: ¶

Check equality with another pack.

def __exit__(self, exc_type: type | None, exc_val: BaseException | None, exc_tb: TracebackType | None): ¶

Exit context manager.

def __getitem__(self, sha1: ObjectID | RawObjectID) -> ShaFile: ¶

Retrieve the specified SHA1.

Initialize a Pack object.

Parameters
basename:`str`	Base path for pack files (without .pack/.idx extension)
object_format:`ObjectFormat`	Hash algorithm used by the repository
resolve_ext_ref:`ResolveExtRefFn \| None`	Optional function to resolve external references
delta_window_size:`int \| None`	Size of the delta compression window
window_memory:`int \| None`	Memory limit for delta compression window
delta_cache_size:`int \| None`	Size of the delta cache
depth:`int \| None`	Maximum depth for delta chains
threads:`int \| None`	Number of threads to use for operations
big_file_threshold:`int \| None`	Size threshold for big file handling
delta_base_cache_limit:`int \| None`	Maximum bytes for delta base object cache

def __iter__(self) -> Iterator[ObjectID]: ¶

Iterate over all the sha1s of the objects in this pack.

def __len__(self) -> int: ¶

Number of entries in this pack.

def __repr__(self) -> str: ¶

Return string representation of this pack.

def check(self): ¶

Check the integrity of this pack.

Raises
`ChecksumMismatch`	if a checksum for the index or data is wrong

def check_length_and_checksum(self): ¶

Sanity check the length and checksum of the pack index and data.

def close(self): ¶

Close the pack file and index.

def ensure_bitmap(self, object_store: BaseObjectStore, refs: dict[Ref, ObjectID], commit_interval: int | None = None, progress: Callable[[str], None] | None = None) -> PackBitmap: ¶

Ensure a bitmap exists for this pack, generating one if needed.

Parameters
object_store:`BaseObjectStore`	Object store to read objects from
refs:`dict[Ref, ObjectID]`	Dictionary of ref names to commit SHAs
commit_interval:`int \| None`	Include every Nth commit in bitmap index
progress:`Callable[[str], None] \| None`	Optional progress reporting callback

Returns
`PackBitmap`	PackBitmap instance (either existing or newly generated)

def entries(self, progress: Callable[[int, int], None] | None = None) -> Iterator[PackIndexEntry]: ¶

Yield entries summarizing the contents of this pack.

Returns: iterator of tuples with (sha, offset, crc32)

Parameters
progress:`Callable[[int, int], None] \| None`	Progress function, called with current and total object count.

Returns
`Iterator[PackIndexEntry]`	Undocumented

def get_raw(self, sha1: RawObjectID | ObjectID) -> tuple[int, bytes]: ¶

Get raw object data by SHA1.

def get_ref(self, sha: RawObjectID | ObjectID) -> tuple[int | None, int, OldUnpackedObject]: ¶

Get the object for a ref SHA, only looking in this pack.

def get_stored_checksum(self) -> bytes: ¶

Return the stored checksum of the pack data.

def get_unpacked_object(self, sha: ObjectID | RawObjectID, *, include_comp: bool = False, convert_ofs_delta: bool = True) -> UnpackedObject: ¶

Get the unpacked object for a sha.

Parameters
sha:`ObjectID \| RawObjectID`	SHA of object to fetch
include_comp:`bool`	Whether to include compression data in UnpackedObject
convert_ofs_delta:`bool`	Whether to convert offset deltas to ref deltas

Returns
`UnpackedObject`	Undocumented

def iter_unpacked(self, include_comp: bool = False) -> Iterator[UnpackedObject]: ¶

Iterate over all unpacked objects in this pack.

def iter_unpacked_subset(self, shas: Iterable[ObjectID | RawObjectID], *, include_comp: bool = False, allow_missing: bool = False, convert_ofs_delta: bool = False) -> Iterator[UnpackedObject]: ¶

Iterate over unpacked objects in subset.

def iterobjects(self) -> Iterator[ShaFile]: ¶

Iterate over the objects in this pack.

def iterobjects_subset(self, shas: Iterable[ObjectID], *, allow_missing: bool = False) -> Iterator[ShaFile]: ¶

Iterate over a subset of objects in this pack.

def keep(self, msg: bytes | None = None) -> str: ¶

Add a .keep file for the pack, preventing git from garbage collecting it.

Returns: The path of the .keep file, as a string.

Parameters
msg:`bytes \| None`	A message written inside the .keep file; can be used later to determine whether or not a .keep file is obsolete.

Returns
`str`	Undocumented

def name(self) -> bytes: ¶

The SHA over the SHAs of the objects in this pack.

def pack_tuples(self) -> list[tuple[ShaFile, None]]: ¶

Return pack tuples for all objects in pack.

def resolve_object(self, offset: int, type: int, obj: OldUnpackedObject, get_ref: Callable[[(RawObjectID | ObjectID)], tuple[int | None, int, OldUnpackedObject]] | None = None) -> tuple[int, OldUnpackedObject]: ¶

Resolve an object, possibly resolving deltas when necessary.

Returns: Tuple with object type and contents.

def sorted_entries(self, progress: Callable[[int, int], None] | None = None) -> Iterator[PackIndexEntry]: ¶

Return entries in this pack, sorted by SHA.

Returns: Iterator of tuples with (sha, offset, crc32)

Parameters
progress:`Callable[[int, int], None] \| None`	Progress function, called with current and total object count

Returns
`Iterator[PackIndexEntry]`	Undocumented

big_file_threshold = ¶

Undocumented

delta_base_cache_limit = ¶

Undocumented

delta_cache_size = ¶

Undocumented

delta_window_size = ¶

Undocumented

depth = ¶

Undocumented

object_format = ¶

Undocumented

resolve_ext_ref = ¶

Undocumented

threads = ¶

Undocumented

window_memory = ¶

Undocumented

@property

bitmap: PackBitmap | None = ¶

The bitmap being used, if available.

Returns
PackBitmap instance or None if no bitmap exists

Raises
`ValueError`	If bitmap file is invalid or corrupt

@property

data: PackData = ¶

The pack data object being used.

@property

index: PackIndex = ¶

The index being used.

Note: This may be an in-memory index

@property

mmap_size: int = ¶

Return the total mmapped memory usage of this pack.

This includes the pack data file and index file sizes, but only for components that have been loaded (and thus mmapped).

_basename = ¶

Undocumented

_bitmap: PackBitmap | None = ¶

Undocumented

_bitmap_path = ¶

Undocumented

_data: PackData | None = ¶

Undocumented

_data_load: Callable[[], PackData] | None = ¶

Undocumented

_data_path = ¶

Undocumented

_idx: PackIndex | None = ¶

Undocumented

_idx_load: Callable[[], PackIndex] | None = ¶

Undocumented

_idx_path = ¶

Undocumented