dulwich.objects module

Access to base git objects.

class dulwich.objects.Blob

Bases: ShaFile

A Git Blob object.

Don’t call this directly

check()

Check this object for internal consistency.

Raises

ObjectFormatException – if the object is malformed in some way

property chunked

The text in the blob object, as chunks (not necessarily lines)

property data

The text contained within the blob object.

classmethod from_path(path)

Open a SHA file from disk.

splitlines() → List[bytes]

Return list of lines in this blob.

This preserves the original line endings.

type_name: bytes = b'blob'
type_num: int = 3
class dulwich.objects.Commit

Bases: ShaFile

A git commit object

Don’t call this directly

property author

The name of the author of the commit

property author_time

The timestamp the commit was written. As the number of seconds since the epoch.

property author_timezone

Returns the zone the author time is in.

check()

Check this object for internal consistency.

Raises

ObjectFormatException – if the object is malformed in some way

property commit_time

The timestamp of the commit. As the number of seconds since the epoch.

property commit_timezone

The zone the commit time is in

property committer

The name of the committer of the commit

property encoding

Encoding of the commit message.

property extra

Extra header fields not understood (presumably added in a newer version of git). Kept verbatim so the object can be correctly reserialized. For private commit metadata, use pseudo-headers in Commit.message, rather than this field.

classmethod from_path(path)

Open a SHA file from disk.

property gpgsig

GPG Signature.

property mergetag

Associated signed tag.

property message

The commit message

property parents

Parents of this commit, by their SHA1.

sign(keyid: Optional[str] = None)
property tree

Tree that is the state of this commit

type_name: bytes = b'commit'
type_num: int = 1
verify(keyids: Optional[Iterable[str]] = None)

Verify GPG signature for this commit (if it is signed).

Parameters

keyids – Optional iterable of trusted keyids for this commit. If this commit is not signed by any key in keyids verification will fail. If not specified, this function only verifies that the commit has a valid signature.

Raises

  • gpg.errors.BadSignatures – if GPG signature verification fails

  • gpg.errors.MissingSignatures – if commit was not signed by a key specified in keyids

exception dulwich.objects.EmptyFileException

Bases: FileFormatException

An unexpectedly empty file was encountered.

class dulwich.objects.FixedSha(hexsha)

Bases: object

SHA object that behaves like hashlib’s but is given a fixed value.

digest()

Return the raw SHA digest.

hexdigest()

Return the hex SHA digest.

Check if a mode indicates a submodule.

Parameters

m – Mode to check

Returns: a boolean

class dulwich.objects.ShaFile

Bases: object

A git SHA file.

Don’t call this directly

as_legacy_object(compression_level: int = -1) → bytes

Return string representing the object in the experimental format.

as_legacy_object_chunks(compression_level: int = -1) → Iterator[bytes]

Return chunks representing the object in the experimental format.

Returns: List of strings

as_pretty_string() → bytes

Return a string representing this object, fit for display.

as_raw_chunks() → List[bytes]

Return chunks with serialization of the object.

Returns: List of strings, not necessarily one per line

as_raw_string() → bytes

Return raw string with serialization of the object.

Returns: String object

check() → None

Check this object for internal consistency.

Raises
copy()

Create a new copy of this SHA1 object from its raw string

classmethod from_file(f)

Get the contents of a SHA file on disk.

classmethod from_path(path)

Open a SHA file from disk.

static from_raw_chunks(type_num: int, chunks: List[bytes], sha: Optional[bytes] = None)

Creates an object of the indicated type from the raw chunks given.

Parameters

  • type_num – The numeric type of the object.

  • chunks – An iterable of the raw uncompressed contents.

  • sha – Optional known sha for the object

static from_raw_string(type_num, string, sha=None)

Creates an object of the indicated type from the raw string given.

Parameters

  • type_num – The numeric type of the object.

  • string – The raw uncompressed contents.

  • sha – Optional known sha for the object

classmethod from_string(string)

Create a ShaFile from a string.

property id

The hex SHA of this object.

raw_length() → int

Returns the length of the raw string of this object.

set_raw_chunks(chunks: List[bytes], sha: Optional[bytes] = None) → None

Set the contents of this object from a list of chunks.

set_raw_string(text: bytes, sha: Optional[bytes] = None) → None

Set the contents of this object from a serialized string.

sha()

The SHA1 object that is the name of this object.

type_name: bytes
type_num: int
exception dulwich.objects.SubmoduleEncountered(path, sha)

Bases: Exception

A submodule was encountered while resolving a path.

class dulwich.objects.Tag

Bases: ShaFile

A Git Tag object.

Don’t call this directly

check()

Check this object for internal consistency.

Raises

ObjectFormatException – if the object is malformed in some way

classmethod from_path(filename)

Open a SHA file from disk.

property message

the message attached to this tag

property name

The name of this tag

property object

Get the object pointed to by this tag.

Returns: tuple of (object class, sha).

sign(keyid: Optional[str] = None)
property signature

Optional detached GPG signature

property tag_time

The creation timestamp of the tag. As the number of seconds since the epoch

property tag_timezone

The timezone that tag_time is in.

property tagger

Returns the name of the person who created this tag

type_name: bytes = b'tag'
type_num: int = 4
verify(keyids: Optional[Iterable[str]] = None)

Verify GPG signature for this tag (if it is signed).

Parameters

keyids – Optional iterable of trusted keyids for this tag. If this tag is not signed by any key in keyids verification will fail. If not specified, this function only verifies that the tag has a valid signature.

Raises

  • gpg.errors.BadSignatures – if GPG signature verification fails

  • gpg.errors.MissingSignatures – if tag was not signed by a key specified in keyids

class dulwich.objects.Tree

Bases: ShaFile

A Git tree object

Don’t call this directly

add(name, mode, hexsha)

Add an entry to the tree.

Parameters

  • mode – The mode of the entry as an integral type. Not all possible modes are supported by git; see check() for details.

  • name – The name of the entry, as a string.

  • hexsha – The hex SHA of the entry as a string.

as_pretty_string()

Return a string representing this object, fit for display.

check()

Check this object for internal consistency.

Raises

ObjectFormatException – if the object is malformed in some way

classmethod from_path(filename)

Open a SHA file from disk.

items()

Return the sorted entries in this tree.

Returns: List with (name, mode, sha) tuples

iteritems(name_order=False)

Iterate over entries.

Parameters

name_order – If True, iterate in name order instead of tree order.

Returns: Iterator over (name, mode, sha) tuples

lookup_path(lookup_obj, path)

Look up an object in a Git tree.

Parameters

  • lookup_obj – Callback for retrieving object by SHA1

  • path – Path to lookup

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

type_name: bytes = b'tree'
type_num: int = 2
class dulwich.objects.TreeEntry(path, mode, sha)

Bases: TreeEntry

Named tuple encapsulating a single tree entry.

Create new instance of TreeEntry(path, mode, sha)

in_path(path)

Return a copy of this entry with the given path prepended.

dulwich.objects.check_hexsha(hex, error_msg)

Check if a string is a valid hex sha string.

Parameters

  • hex – Hex string to check

  • error_msg – Error message to use in exception

Raises

ObjectFormatException – Raised when the string is not valid

dulwich.objects.check_identity(identity: bytes, error_msg: str) → None

Check if the specified identity is valid.

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

Parameters

  • identity – Identity string

  • error_msg – Error message to use in exception

dulwich.objects.check_time(time_seconds)

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 – time in seconds

dulwich.objects.cls

alias of Tag

dulwich.objects.filename_to_hex(filename)

Takes an object filename and returns its corresponding hex sha.

dulwich.objects.format_timezone(offset, unnecessary_negative_timezone=False)

Format a timezone for Git serialization.

Parameters

  • offset – Timezone offset as seconds difference to UTC

  • unnecessary_negative_timezone – Whether to use a minus sign for UTC or positive timezones (-0000 and –700 rather than +0000 / +0700).

dulwich.objects.git_line(*items)

Formats items into a space separated line.

dulwich.objects.hex_to_filename(path, hex)

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

dulwich.objects.hex_to_sha(hex)

Takes a hex sha and returns a binary sha

dulwich.objects.key_entry(entry)

Sort key for tree entry.

Parameters

entry – (name, value) tuplee

dulwich.objects.key_entry_name_order(entry)

Sort key for tree entry in name order.

dulwich.objects.object_class(type: Union[bytes, int]) → Optional[Type[ShaFile]]

Get the object class corresponding to the given type.

Parameters

type – Either a type name string or a numeric type.

Returns: The ShaFile subclass corresponding to the given type, or None if

type is not a valid type name/number.

dulwich.objects.object_header(num_type: int, length: int) → bytes

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

dulwich.objects.parse_commit(chunks)

Parse a commit object from chunks.

Parameters

chunks – Chunks to parse

Returns: Tuple of (tree, parents, author_info, commit_info,

encoding, mergetag, gpgsig, message, extra)

dulwich.objects.parse_time_entry(value)

Parse time entry behavior

Parameters

value – Bytes representing a git commit/tag line

Raises

  • ObjectFormatException in case of parsing error (malformed –

  • field date) –

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

dulwich.objects.parse_timezone(text)

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

Parameters

text – Text to parse.

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).

dulwich.objects.parse_tree(text, strict=False)

Parse a tree text.

Parameters

text – Serialized text to parse

Returns: iterator of tuples of (name, mode, sha) :raises ObjectFormatException: if the object was malformed in some way

dulwich.objects.pretty_format_tree_entry(name, mode, hexsha, encoding='utf-8')

Pretty format tree entry.

Parameters

  • name – Name of the directory entry

  • mode – Mode of entry

  • hexsha – Hexsha of the referenced object

Returns: string describing the tree entry

dulwich.objects.serializable_property(name: str, docstring: Optional[str] = None)

A property that helps tracking whether serialization is necessary.

dulwich.objects.serialize_tree(items)

Serialize the items in a tree to a text.

Parameters

items – Sorted iterable over (name, mode, sha) tuples

Returns: Serialized tree text as chunks

dulwich.objects.sha_to_hex(sha)

Takes a string and returns the hex of the sha within

dulwich.objects.sorted_tree_items(entries, name_order: bool)

Iterate over a tree entries dictionary.

Parameters

  • name_order – If True, iterate entries in order of their name. If False, iterate entries in tree order, that is, treat subtree entries as having ‘/’ appended.

  • entries – Dictionary mapping names to (mode, sha) tuples

Returns: Iterator over (name, mode, hexsha)

dulwich.objects.valid_hexsha(hex)