dulwich.pack.PackData

class documentation

class PackData:

Constructors: PackData.from_file(file, object_format, size), PackData.from_path(path, object_format), PackData(filename, object_format, file, size, ...)

View In Hierarchy

The data contained in a packfile.

Pack files can be accessed both sequentially for exploding a pack, and directly with the help of an index to retrieve a specific object.

The objects within are either complete or a delta against another.

The header is variable length. If the MSB of each byte is set then it indicates that the subsequent byte is still part of the header. For the first byte the next MS bits are the type, which tells you the type of object, and whether it is a delta. The LS byte is the lowest bits of the size. For each subsequent byte the LS 7 bits are the next MS bits of the size, i.e. the last byte of the header contains the MS bits of the size.

For the complete objects the data is stored as zlib deflated data. The size in the header is the uncompressed object size, so to uncompress you need to just keep feeding data to zlib until you get an object back, or it errors on bad data. This is done here by just giving the complete buffer from the start of the deflated object on. This is bad, but until I get mmap sorted out it will have to do.

Currently there are no integrity checks done. Also no attempt is made to try and detect the delta case, or a request for an object at the wrong position. It will all just throw a zlib or KeyError.

Class Method	`from_file`	Create a PackData object from an open file.
Class Method	`from_path`	Create a PackData object from a file path.
Method	`__del__`	Ensure pack file is closed when PackData is garbage collected.
Method	`__enter__`	Enter context manager.
Method	`__eq__`	Check equality with another object.
Method	`__exit__`	Exit context manager.
Method	`__init__`	Create a PackData object representing the pack in the given filename.
Method	`__len__`	Returns the number of objects in this pack.
Method	`calculate_checksum`	Calculate the checksum for this pack.
Method	`check`	Check the consistency of this pack.
Method	`close`	Close the underlying pack file.
Method	`create_index`	Create an index file for this data file.
Method	`create_index_v1`	Create a version 1 file for this data file.
Method	`create_index_v2`	Create a version 2 index file for this data file.
Method	`create_index_v3`	Create a version 3 index file for this data file.
Method	`get_object_at`	Given an offset in to the packfile return the object that is there.
Method	`get_stored_checksum`	Return the expected checksum stored in this pack.
Method	`get_unpacked_object_at`	Given offset in the packfile return a UnpackedObject.
Method	`iter_unpacked`	Iterate over unpacked objects in the pack.
Method	`iterentries`	Yield entries summarizing the contents of this pack.
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	`threads`	Undocumented
Instance Variable	`window_memory`	Undocumented
Property	`filename`	Get the filename of the pack file.
Property	`path`	Get the full path of the pack file.
Method	`_get_size`	Undocumented
Instance Variable	`_file`	Undocumented
Instance Variable	`_filename`	Undocumented
Instance Variable	`_header_size`	Undocumented
Instance Variable	`_num_objects`	Undocumented
Instance Variable	`_offset_cache`	Undocumented
Instance Variable	`_size`	Undocumented

@classmethod

def from_file(cls, file: IO[bytes], object_format: ObjectFormat, size: int | None = None) -> PackData: ¶

Create a PackData object from an open file.

Parameters
file:`IO[bytes]`	Open file object
object_format:`ObjectFormat`	Object format
size:`int \| None`	Optional file size

Returns
`PackData`	PackData instance

@classmethod

def from_path(cls, path: str | os.PathLike[str], object_format: ObjectFormat) -> PackData: ¶

Create a PackData object from a file path.

Parameters
path:`str \| os.PathLike[str]`	Path to the pack file
object_format:`ObjectFormat`	Object format

Returns
`PackData`	PackData instance

def __del__(self): ¶

Ensure pack file is closed when PackData is garbage collected.

def __enter__(self) -> PackData: ¶

Enter context manager.

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

Check equality with another object.

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

Exit context manager.

Create a PackData object representing the pack in the given filename.

The file must exist and stay readable until the object is disposed of. It must also stay the same size. It will be mapped whenever needed.

Currently there is a restriction on the size of the pack as the python mmap implementation is flawed.

def __len__(self) -> int: ¶

Returns the number of objects in this pack.

def calculate_checksum(self) -> bytes: ¶

Calculate the checksum for this pack.

Returns: Binary digest (size depends on hash algorithm)

def check(self): ¶

Check the consistency of this pack.

def close(self): ¶

Close the underlying pack file.

def create_index(self, filename: str, progress: Callable[..., None] | None = None, version: int = 2, resolve_ext_ref: ResolveExtRefFn | None = None, hash_format: int | None = None) -> bytes: ¶

Create an index file for this data file.

Returns: Checksum of index file

Parameters
filename:`str`	Index filename.
progress:`Callable[..., None] \| None`	Progress report function
version:`int`	Index version (1, 2, or 3)
resolve_ext_ref:`ResolveExtRefFn \| None`	Function to resolve external references
hash_format:`int \| None`	Hash algorithm identifier for v3 (1 = SHA-1, 2 = SHA-256)

Returns
`bytes`	Undocumented

def create_index_v1(self, filename: str, progress: Callable[..., None] | None = None, resolve_ext_ref: ResolveExtRefFn | None = None) -> bytes: ¶

Create a version 1 file for this data file.

Returns: Checksum of index file

Parameters
filename:`str`	Index filename.
progress:`Callable[..., None] \| None`	Progress report function
resolve_ext_ref:`ResolveExtRefFn \| None`	Optional function to resolve external references

Returns
`bytes`	Undocumented

def create_index_v2(self, filename: str, progress: Callable[..., None] | None = None, resolve_ext_ref: ResolveExtRefFn | None = None) -> bytes: ¶

Create a version 2 index file for this data file.

Returns: Checksum of index file

Parameters
filename:`str`	Index filename.
progress:`Callable[..., None] \| None`	Progress report function
resolve_ext_ref:`ResolveExtRefFn \| None`	Optional function to resolve external references

Returns
`bytes`	Undocumented

def create_index_v3(self, filename: str, progress: Callable[..., None] | None = None, resolve_ext_ref: ResolveExtRefFn | None = None, hash_format: int | None = None) -> bytes: ¶

Create a version 3 index file for this data file.

Returns: Checksum of index file

Parameters
filename:`str`	Index filename.
progress:`Callable[..., None] \| None`	Progress report function
resolve_ext_ref:`ResolveExtRefFn \| None`	Function to resolve external references
hash_format:`int \| None`	Hash algorithm identifier (1 = SHA-1, 2 = SHA-256)

Returns
`bytes`	Undocumented

def get_object_at(self, offset: int) -> tuple[int, OldUnpackedObject]: ¶

Given an offset in to the packfile return the object that is there.

Using the associated index the location of an object can be looked up, and then the packfile can be asked directly for that object using this function.

def get_stored_checksum(self) -> bytes: ¶

Return the expected checksum stored in this pack.

def get_unpacked_object_at(self, offset: int, *, include_comp: bool = False) -> UnpackedObject: ¶

Given offset in the packfile return a UnpackedObject.

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

Iterate over unpacked objects in the pack.

def iterentries(self, progress: Callable[[int, int], None] | None = None, resolve_ext_ref: ResolveExtRefFn | 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.
resolve_ext_ref:`ResolveExtRefFn \| None`	Optional function to resolve external references

Returns
`Iterator[PackIndexEntry]`	Undocumented

def sorted_entries(self, progress: Callable[[int, int], None] | None = None, resolve_ext_ref: ResolveExtRefFn | None = None) -> list[tuple[RawObjectID, int, int]]: ¶

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
resolve_ext_ref:`ResolveExtRefFn \| None`	Optional function to resolve external references

Returns
`list[tuple[RawObjectID, int, int]]`	Undocumented

big_file_threshold = ¶

Undocumented

delta_base_cache_limit = ¶

Undocumented

delta_cache_size = ¶

Undocumented

delta_window_size = ¶

Undocumented

depth = ¶

Undocumented

object_format = ¶

Undocumented

threads = ¶

Undocumented

window_memory = ¶

Undocumented

@property

filename: str = ¶

Get the filename of the pack file.

Returns
Base filename without directory path

@property

path: str | os.PathLike[str] = ¶

Get the full path of the pack file.

Returns
Full path to the pack file

def _get_size(self) -> int: ¶

Undocumented

_file: IO[bytes] = ¶

Undocumented

_filename = ¶

Undocumented

_header_size: int = ¶

Undocumented

_num_objects = ¶

Undocumented

_offset_cache = ¶

Undocumented

_size = ¶

Undocumented