dulwich.objects

module documentation

Access to base git objects.

Class	`Blob`	A Git Blob object.
Class	`Commit`	A git commit object.
Class	`FixedSha`	SHA object that behaves like hashlib's but is given a fixed value.
Class	`ShaFile`	A git SHA file.
Class	`Tag`	A Git Tag object.
Class	`Tree`	A Git tree object.
Class	`TreeEntry`	Named tuple encapsulating a single tree entry.
Exception	`EmptyFileException`	An unexpectedly empty file was encountered.
Exception	`SubmoduleEncountered`	A submodule was encountered while resolving a path.
Function	`check_hexsha`	Check if a string is a valid hex sha string.
Function	`check_identity`	Check if the specified identity is valid.
Function	`check_time`	Check if the specified time is not prone to overflow error.
Function	`filename_to_hex`	Takes an object filename and returns its corresponding hex sha.
Function	`format_time_entry`	Format an event.
Function	`format_timezone`	Format a timezone for Git serialization.
Function	`git_line`	Formats items into a space separated line.
Function	`hex_to_filename`	Takes a hex sha and returns its filename relative to the given path.
Function	`hex_to_sha`	Takes a hex sha and returns a binary sha.
Function	`is_blob`	Check if a ShaFile is a Blob.
Function	`is_commit`	Check if a ShaFile is a Commit.
Function	`is_tag`	Check if a ShaFile is a Tag.
Function	`is_tree`	Check if a ShaFile is a Tree.
Function	`key_entry`	Sort key for tree entry.
Function	`key_entry_name_order`	Sort key for tree entry in name order.
Function	`object_class`	Get the object class corresponding to the given type.
Function	`object_header`	Return an object header for the given numeric type and text length.
Function	`parse_commit_broken`	Parse a commit with broken author/committer lines.
Function	`parse_time_entry`	Parse event.
Function	`parse_time_entry_broken`	Parse event, accepting broken formats.
Function	`parse_timezone`	Parse a timezone text fragment (e.g. '+0100').
Function	`parse_timezone_broken`	Parse a timezone text fragment, accepting broken formats.
Function	`parse_tree`	Parse a tree text.
Function	`pretty_format_tree_entry`	Pretty format tree entry.
Function	`S_ISGITLINK`	Check if a mode indicates a submodule.
Function	`serializable_property`	A property that helps tracking whether serialization is necessary.
Function	`serialize_tree`	Serialize the items in a tree to a text.
Function	`sha_to_hex`	Takes a string and returns the hex of the sha within.
Function	`sorted_tree_items`	Iterate over a tree entries dictionary.
Function	`valid_hexsha`	Check if a hex string is a valid SHA1 or SHA256.
Constant	`BEGIN_PGP_SIGNATURE`	Undocumented
Constant	`BEGIN_SSH_SIGNATURE`	Undocumented
Constant	`MAX_TIME`	Undocumented
Constant	`OBJECT_CLASSES`	Undocumented
Constant	`S_IFGITLINK`	Undocumented
Constant	`SIGNATURE_PGP`	Undocumented
Constant	`SIGNATURE_SSH`	Undocumented
Constant	`ZERO_SHA`	Undocumented
Type Variable	`PathT`	Undocumented
Variable	`ObjectID`	Undocumented
Variable	`RawObjectID`	Undocumented
Function	`_decompress`	Undocumented
Function	`_format_message`	Undocumented
Function	`_parse_commit`	Parse a commit object from chunks.
Function	`_parse_commit_broken`	Parse a commit object from chunks, accepting broken formats.
Function	`_parse_message`	Parse a message with a list of fields and a body.
Function	`_path_to_bytes`	Convert a path to bytes for use in error messages.
Constant	`_AUTHOR_HEADER`	Undocumented
Constant	`_COMMITTER_HEADER`	Undocumented
Constant	`_ENCODING_HEADER`	Undocumented
Constant	`_GPGSIG_HEADER`	Undocumented
Constant	`_MERGETAG_HEADER`	Undocumented
Constant	`_OBJECT_HEADER`	Undocumented
Constant	`_PARENT_HEADER`	Undocumented
Constant	`_TAG_HEADER`	Undocumented
Constant	`_TAGGER_HEADER`	Undocumented
Constant	`_TIME_ENTRY_RE`	Undocumented
Constant	`_TREE_HEADER`	Undocumented
Constant	`_TYPE_HEADER`	Undocumented
Constant	`_TYPE_MAP`	Undocumented

def check_hexsha(hex: str | bytes, error_msg: str): ¶

Check if a string is a valid hex sha string.

Parameters
hex:`str \| bytes`	Hex string to check
error_msg:`str`	Error message to use in exception

Raises
`ObjectFormatException`	Raised when the string is not valid

def check_identity(identity: bytes | None, error_msg: str): ¶

Check if the specified identity is valid.

This will raise an exception if the identity is not valid.

Parameters
identity:`bytes \| None`	Identity string
error_msg:`str`	Error message to use in exception

def check_time(time_seconds: int): ¶

Check if the specified time is not prone to overflow error.

This will raise an exception if the time is not valid.

Parameters
time_seconds:`int`	time in seconds

def filename_to_hex(filename: str | bytes) -> str: ¶

Takes an object filename and returns its corresponding hex sha.

def format_time_entry(person: bytes, time: int, timezone_info: tuple[int, bool]) -> bytes: ¶

Format an event.

def format_timezone(offset: int, unnecessary_negative_timezone: bool = False) -> bytes: ¶

Format a timezone for Git serialization.

Parameters
offset:`int`	Timezone offset as seconds difference to UTC
unnecessary_negative_timezone:`bool`	Whether to use a minus sign for UTC or positive timezones (-0000 and --700 rather than +0000 / +0700).

Returns
`bytes`	Undocumented

def git_line(*items: bytes) -> bytes: ¶

Formats items into a space separated line.

def hex_to_filename(path: PathT, hex: str | bytes) -> PathT: ¶

Takes a hex sha and returns its filename relative to the given path.

def hex_to_sha(hex: ObjectID | str) -> RawObjectID: ¶

Takes a hex sha and returns a binary sha.

def is_blob(obj: ShaFile) -> TypeGuard[Blob]: ¶

Check if a ShaFile is a Blob.

def is_commit(obj: ShaFile) -> TypeGuard[Commit]: ¶

Check if a ShaFile is a Commit.

def is_tag(obj: ShaFile) -> TypeGuard[Tag]: ¶

Check if a ShaFile is a Tag.

def is_tree(obj: ShaFile) -> TypeGuard[Tree]: ¶

Check if a ShaFile is a Tree.

def key_entry(entry: tuple[bytes, tuple[int, ObjectID]]) -> bytes: ¶

Sort key for tree entry.

Parameters
entry:`tuple[bytes, tuple[int, ObjectID]]`	(name, value) tuple

Returns
`bytes`	Undocumented

def key_entry_name_order(entry: tuple[bytes, tuple[int, ObjectID]]) -> bytes: ¶

Sort key for tree entry in name order.

def object_class(type: bytes | int) -> type[ShaFile] | None: ¶

Get the object class corresponding to the given type.

Returns: The ShaFile subclass corresponding to the given type, or None if: type is not a valid type name/number.

Parameters
type:`bytes \| int`	Either a type name string or a numeric type.

Returns
`type[ShaFile] \| None`	Undocumented

def object_header(num_type: int, length: int) -> bytes: ¶

Return an object header for the given numeric type and text length.

def parse_commit_broken(data: bytes) -> Commit: ¶

Parse a commit with broken author/committer lines.

This function handles various broken formats found in the wild: - Missing angle brackets around email addresses - Unsigned timezones (e.g., "0000" instead of "+0000") - Double-negative timezones (e.g., "--700") - Negative timestamps - Long/short/nonsensical timezone values

Warning: Commits parsed with this function may not round-trip correctly through serialization, as the broken formatting is normalized during parsing. The .check() method will likely fail for commits with malformed identity fields.

Example

>>> data = b'''tree d80c186a03f423a81b39df39dc87fd269736ca86
... author [email protected] 1234567890 -0500
... committer [email protected] 1234567890 -0500
...
... Commit message
... '''
>>> commit = parse_commit_broken(data)
>>> commit.author
b'[email protected]'

Parameters
data:`bytes`	Raw commit data as bytes

Returns
`Commit`	A Commit object with normalized fields

def parse_time_entry(value: bytes) -> tuple[bytes, int | None, tuple[int | None, bool]]: ¶

Parse event.

Returns: Tuple of (author, time, (timezone, timezone_neg_utc))

Parameters
value:`bytes`	Bytes representing a git commit/tag line

Returns
`tuple[bytes, int \| None, tuple[int \| None, bool]]`	Undocumented

Raises
`ObjectFormatException in case of parsing error (malformed`
`field date)`

def parse_time_entry_broken(value: bytes) -> tuple[bytes, int | None, tuple[int | None, bool]]: ¶

Parse event, accepting broken formats.

This function handles various broken author/committer/tagger line formats: - Missing angle brackets around email - Unsigned timezones - Double-negative timezones

Returns: Tuple of (author, time, (timezone, timezone_neg_utc))

Parameters
value:`bytes`	Bytes representing a git commit/tag line

Returns
`tuple[bytes, int \| None, tuple[int \| None, bool]]`	Undocumented

Raises
`ObjectFormatException in case of parsing error`

def parse_timezone(text: bytes) -> tuple[int, bool]: ¶

Parse a timezone text fragment (e.g. '+0100').

Returns: Tuple with timezone as seconds difference to UTC: and a boolean indicating whether this was a UTC timezone prefixed with a negative sign (-0000).

Parameters
text:`bytes`	Text to parse.

Returns
`tuple[int, bool]`	Undocumented

def parse_timezone_broken(text: bytes) -> tuple[int, bool]: ¶

Parse a timezone text fragment, accepting broken formats.

This function handles various broken timezone formats found in the wild: - Missing sign prefix (e.g., '0000' instead of '+0000') - Double negative (e.g., '--700')

Returns: Tuple with timezone as seconds difference to UTC: and a boolean indicating whether this was a UTC timezone prefixed with a negative sign (-0000).

Parameters
text:`bytes`	Text to parse.

Returns
`tuple[int, bool]`	Undocumented

def parse_tree(text: bytes, sha_len: int | None = None, *, strict: bool = False) -> Iterator[tuple[bytes, int, bytes]]: ¶

Parse a tree text.

Returns: iterator of tuples of (name, mode, sha)

Parameters
text:`bytes`	Serialized text to parse
sha_len:`int \| None`	Length of the object IDs in bytes
strict:`bool`	Whether to be strict about format

Returns
`Iterator[tuple[bytes, int, bytes]]`	Undocumented

Raises
`ObjectFormatException`	if the object was malformed in some way

def pretty_format_tree_entry(name: bytes, mode: int, hexsha: ObjectID, encoding: str = 'utf-8') -> str: ¶

Pretty format tree entry.

Returns: string describing the tree entry

Parameters
name:`bytes`	Name of the directory entry
mode:`int`	Mode of entry
hexsha:`ObjectID`	Hexsha of the referenced object
encoding:`str`	Character encoding for the name

Returns
`str`	Undocumented

def S_ISGITLINK(m: int) -> bool: ¶

Check if a mode indicates a submodule.

Returns: a boolean

Parameters
m:`int`	Mode to check

Returns
`bool`	Undocumented

def serializable_property(name: str, docstring: str | None = None) -> property: ¶

A property that helps tracking whether serialization is necessary.

def serialize_tree(items: Iterable[tuple[bytes, int, ObjectID]]) -> Iterator[bytes]: ¶

Serialize the items in a tree to a text.

Returns: Serialized tree text as chunks

Parameters
items:`Iterable[tuple[bytes, int, ObjectID]]`	Sorted iterable over (name, mode, sha) tuples

Returns
`Iterator[bytes]`	Undocumented

def sha_to_hex(sha: RawObjectID) -> ObjectID: ¶

Takes a string and returns the hex of the sha within.

def sorted_tree_items(entries: dict[bytes, tuple[int, ObjectID]], name_order: bool) -> Iterator[TreeEntry]: ¶

Iterate over a tree entries dictionary.

Returns: Iterator over (name, mode, hexsha)

Parameters
entries:`dict[bytes, tuple[int, ObjectID]]`	Dictionary mapping names to (mode, sha) tuples
name_order:`bool`	If True, iterate entries in order of their name. If False, iterate entries in tree order, that is, treat subtree entries as having '/' appended.

Returns
`Iterator[TreeEntry]`	Undocumented

def valid_hexsha(hex: bytes | str) -> bool: ¶

Check if a hex string is a valid SHA1 or SHA256.

Parameters
hex:`bytes \| str`	Hex string to validate

Returns
`bool`	True if valid SHA1 (40 chars) or SHA256 (64 chars), False otherwise

BEGIN_PGP_SIGNATURE: bytes = ¶

Undocumented

Value

b'-----BEGIN PGP SIGNATURE-----'

BEGIN_SSH_SIGNATURE: bytes = ¶

Undocumented

Value

b'-----BEGIN SSH SIGNATURE-----'

MAX_TIME: int = ¶

Undocumented

Value

9223372036854775807

OBJECT_CLASSES = ¶

Undocumented

Value

(Commit, Tree, Blob, Tag)

S_IFGITLINK: int = ¶

Undocumented

Value

SIGNATURE_PGP: bytes = ¶

Undocumented

Value

b'pgp'

SIGNATURE_SSH: bytes = ¶

Undocumented

Value

b'ssh'

ZERO_SHA: ObjectID = ¶

Undocumented

Value

ObjectID((b'0' * 40))

PathT = ¶

Undocumented

Value

TypeVar('PathT', str, bytes)

ObjectID = ¶

Undocumented

RawObjectID = ¶

Undocumented

def _decompress(string: bytes) -> bytes: ¶

Undocumented

def _format_message(headers: Sequence[tuple[bytes, bytes]], body: bytes | None) -> Iterator[bytes]: ¶

Undocumented

def _parse_commit(chunks: Iterable[bytes]) ->

tuple[bytes | None, list[bytes], tuple[bytes | None, int | None, tuple[int | None, bool | None]], tuple[bytes | None, int | None, tuple[int | None, bool | None]], bytes | None, list[Tag], bytes | None, bytes | None, list[tuple[bytes, bytes]]]

: ¶

Parse a commit object from chunks.

Returns: Tuple of (tree, parents, author_info, commit_info,: encoding, mergetag, gpgsig, message, extra)

Parameters
chunks:`Iterable[bytes]`	Chunks to parse

Returns
`tuple[bytes \| None, list[bytes], tuple[bytes \| None, int \| None, tuple[int \| None, bool \| None]], tuple[bytes \| None, int \| None, tuple[int \| None, bool \| None]], bytes \| None, list[Tag], bytes \| None, bytes \| None, list[tuple[bytes, bytes]]]`	Undocumented

def _parse_commit_broken(chunks: Iterable[bytes]) ->

tuple[bytes | None, list[bytes], tuple[bytes | None, int | None, tuple[int | None, bool | None]], tuple[bytes | None, int | None, tuple[int | None, bool | None]], bytes | None, list[Tag], bytes | None, bytes | None, list[tuple[bytes, bytes]]]

: ¶

Parse a commit object from chunks, accepting broken formats.

This function handles various broken author/committer line formats: - Missing angle brackets around email - Unsigned timezones - Double-negative timezones

Returns: Tuple of (tree, parents, author_info, commit_info,: encoding, mergetag, gpgsig, message, extra)

Parameters
chunks:`Iterable[bytes]`	Chunks to parse

Returns
`tuple[bytes \| None, list[bytes], tuple[bytes \| None, int \| None, tuple[int \| None, bool \| None]], tuple[bytes \| None, int \| None, tuple[int \| None, bool \| None]], bytes \| None, list[Tag], bytes \| None, bytes \| None, list[tuple[bytes, bytes]]]`	Undocumented

def _parse_message(chunks: Iterable[bytes]) -> Iterator[tuple[None, None] | tuple[bytes | None, bytes]]: ¶

Parse a message with a list of fields and a body.

Returns: iterator of tuples of (field, value), one per header line, in the: order read from the text, possibly including duplicates. Includes a field named None for the freeform tag/commit text.

Parameters
chunks:`Iterable[bytes]`	the raw chunks of the tag or commit object.

Returns
`Iterator[tuple[None, None] \| tuple[bytes \| None, bytes]]`	Undocumented

def _path_to_bytes(path: str | bytes) -> bytes: ¶

Convert a path to bytes for use in error messages.

_AUTHOR_HEADER: bytes = ¶

Undocumented

Value

b'author'

_COMMITTER_HEADER: bytes = ¶

Undocumented

Value

b'committer'

_ENCODING_HEADER: bytes = ¶

Undocumented

Value

b'encoding'

_GPGSIG_HEADER: bytes = ¶

Undocumented

Value

b'gpgsig'

_MERGETAG_HEADER: bytes = ¶

Undocumented

Value

b'mergetag'

_OBJECT_HEADER: bytes = ¶

Undocumented

Value

b'object'

_PARENT_HEADER: bytes = ¶

Undocumented

Value

b'parent'

_TAG_HEADER: bytes = ¶

Undocumented

Value

b'tag'

_TAGGER_HEADER: bytes = ¶

Undocumented

Value

b'tagger'

_TIME_ENTRY_RE = ¶

Undocumented

Value

re.compile(rb'^(?P<person>.*) (?P<time>-?[0-9]+) (?P<timezone>[\+-]{,2}[0-9]+)$'↵
)

_TREE_HEADER: bytes = ¶

Undocumented

Value

b'tree'

_TYPE_HEADER: bytes = ¶

Undocumented

Value

b'type'

_TYPE_MAP: dict[bytes | int, type[ShaFile]] = ¶

Undocumented

Value

{}