dulwich.protocol

module documentation

Generic functions for talking the git smart server protocol.

Class	`BufferedPktLineWriter`	Writer that wraps its data in pkt-lines and has an independent buffer.
Class	`PktLineParser`	Packet line parser that hands completed packets off to a callback.
Class	`Protocol`	Class for interacting with a remote git process over the wire.
Class	`ReceivableProtocol`	Variant of Protocol that allows reading up to a size without blocking.
Function	`ack_type`	Extract the ack type from a capabilities list.
Function	`agent_string`	Generate the agent string for dulwich.
Function	`capability_agent`	Generate the agent capability string.
Function	`capability_object_format`	Generate the object-format capability string.
Function	`capability_symref`	Generate a symref capability string.
Function	`extract_capabilities`	Extract a capabilities list from a string, if present.
Function	`extract_capability_names`	Extract capability names from a list of capabilities.
Function	`extract_want_line_capabilities`	Extract a capabilities list from a want line, if present.
Function	`find_capability`	Find a capability value in a list of capabilities.
Function	`format_ack_line`	Format an ACK line.
Function	`format_capability_line`	Format a capabilities list for the wire protocol.
Function	`format_cmd_pkt`	Format a command packet.
Function	`format_ref_line`	Format a ref advertisement line.
Function	`format_shallow_line`	Format a shallow line.
Function	`format_unshallow_line`	Format an unshallow line.
Function	`parse_capability`	Parse a capability string into name and value.
Function	`parse_cmd_pkt`	Parse a command packet.
Function	`pkt_line`	Wrap data in a pkt-line.
Function	`pkt_seq`	Wrap a sequence of data in pkt-lines.
Function	`serialize_refs`	Serialize refs with peeled refs for Git protocol v0/v1.
Function	`split_peeled_refs`	Split peeled refs from regular refs.
Function	`strip_peeled_refs`	Remove all peeled refs from a refs dictionary.
Function	`symref_capabilities`	Generate symref capability strings from symref pairs.
Function	`write_info_refs`	Generate info refs in the format used by the dumb HTTP protocol.
Constant	`CAPABILITIES_REF`	Undocumented
Constant	`CAPABILITY_AGENT`	Undocumented
Constant	`CAPABILITY_ALLOW_REACHABLE_SHA1_IN_WANT`	Undocumented
Constant	`CAPABILITY_ALLOW_TIP_SHA1_IN_WANT`	Undocumented
Constant	`CAPABILITY_ATOMIC`	Undocumented
Constant	`CAPABILITY_DEEPEN_NOT`	Undocumented
Constant	`CAPABILITY_DEEPEN_RELATIVE`	Undocumented
Constant	`CAPABILITY_DEEPEN_SINCE`	Undocumented
Constant	`CAPABILITY_DELETE_REFS`	Undocumented
Constant	`CAPABILITY_FETCH`	Undocumented
Constant	`CAPABILITY_FILTER`	Undocumented
Constant	`CAPABILITY_INCLUDE_TAG`	Undocumented
Constant	`CAPABILITY_MULTI_ACK`	Undocumented
Constant	`CAPABILITY_MULTI_ACK_DETAILED`	Undocumented
Constant	`CAPABILITY_NO_DONE`	Undocumented
Constant	`CAPABILITY_NO_PROGRESS`	Undocumented
Constant	`CAPABILITY_OBJECT_FORMAT`	Undocumented
Constant	`CAPABILITY_OFS_DELTA`	Undocumented
Constant	`CAPABILITY_PACKFILE_URIS`	Undocumented
Constant	`CAPABILITY_PUSH_OPTIONS`	Undocumented
Constant	`CAPABILITY_QUIET`	Undocumented
Constant	`CAPABILITY_REPORT_STATUS`	Undocumented
Constant	`CAPABILITY_SHALLOW`	Undocumented
Constant	`CAPABILITY_SIDE_BAND`	Undocumented
Constant	`CAPABILITY_SIDE_BAND_64K`	Undocumented
Constant	`CAPABILITY_SYMREF`	Undocumented
Constant	`CAPABILITY_THIN_PACK`	Undocumented
Constant	`COMMAND_DEEPEN`	Undocumented
Constant	`COMMAND_DEEPEN_NOT`	Undocumented
Constant	`COMMAND_DEEPEN_SINCE`	Undocumented
Constant	`COMMAND_DONE`	Undocumented
Constant	`COMMAND_FILTER`	Undocumented
Constant	`COMMAND_HAVE`	Undocumented
Constant	`COMMAND_SHALLOW`	Undocumented
Constant	`COMMAND_UNSHALLOW`	Undocumented
Constant	`COMMAND_WANT`	Undocumented
Constant	`COMMON_CAPABILITIES`	Undocumented
Constant	`DEFAULT_GIT_PROTOCOL_VERSION_FETCH`	Undocumented
Constant	`DEFAULT_GIT_PROTOCOL_VERSION_SEND`	Undocumented
Constant	`DEPTH_INFINITE`	Undocumented
Constant	`GIT_PROTOCOL_VERSIONS`	Undocumented
Constant	`KNOWN_RECEIVE_CAPABILITIES`	Undocumented
Constant	`KNOWN_UPLOAD_CAPABILITIES`	Undocumented
Constant	`MULTI_ACK`	Undocumented
Constant	`MULTI_ACK_DETAILED`	Undocumented
Constant	`NAK_LINE`	Undocumented
Constant	`PEELED_TAG_SUFFIX`	Undocumented
Constant	`SIDE_BAND_CHANNEL_DATA`	Undocumented
Constant	`SIDE_BAND_CHANNEL_FATAL`	Undocumented
Constant	`SIDE_BAND_CHANNEL_PROGRESS`	Undocumented
Constant	`SINGLE_ACK`	Undocumented
Constant	`TCP_GIT_PORT`	Undocumented
Constant	`ZERO_SHA`	Undocumented
Variable	`logger`	Undocumented
Constant	`_RBUFSIZE`	Undocumented

def ack_type(capabilities: Iterable[bytes]) -> int: ¶

Extract the ack type from a capabilities list.

def agent_string() -> bytes: ¶

Generate the agent string for dulwich.

Returns
`bytes`	Agent string as bytes

def capability_agent() -> bytes: ¶

Generate the agent capability string.

Returns
`bytes`	Agent capability with dulwich version

def capability_object_format(fmt: str) -> bytes: ¶

Generate the object-format capability string.

Parameters
fmt:`str`	Object format name (e.g., "sha1" or "sha256")

Returns
`bytes`	Object-format capability with format name

def capability_symref(from_ref: bytes, to_ref: bytes) -> bytes: ¶

Generate a symref capability string.

Parameters
from_ref:`bytes`	Source reference name
to_ref:`bytes`	Target reference name

Returns
`bytes`	Symref capability string

def extract_capabilities(text: bytes) -> tuple[bytes, list[bytes]]: ¶

Extract a capabilities list from a string, if present.

Returns: Tuple with text with capabilities removed and list of capabilities

Parameters
text:`bytes`	String to extract from

Returns
`tuple[bytes, list[bytes]]`	Undocumented

def extract_capability_names(capabilities: Iterable[bytes]) -> set[bytes]: ¶

Extract capability names from a list of capabilities.

Parameters
capabilities:`Iterable[bytes]`	List of capability strings

Returns
`set[bytes]`	Set of capability names

def extract_want_line_capabilities(text: bytes) -> tuple[bytes, list[bytes]]: ¶

Extract a capabilities list from a want line, if present.

Note that want lines have capabilities separated from the rest of the line by a space instead of a null byte. Thus want lines have the form:

want obj-id cap1 cap2 ...

Returns: Tuple with text with capabilities removed and list of capabilities

Parameters
text:`bytes`	Want line to extract from

Returns
`tuple[bytes, list[bytes]]`	Undocumented

def find_capability(capabilities: Iterable[bytes], *capability_names: bytes) -> bytes | None: ¶

Find a capability value in a list of capabilities.

This function looks for capabilities that may include arguments after an equals sign and returns only the value part (after the '='). For capabilities without values, returns the capability name itself.

Example

>>> caps = [b'filter=blob:none', b'agent=git/2.0', b'thin-pack']
>>> find_capability(caps, b'filter')
b'blob:none'
>>> find_capability(caps, b'thin-pack')
b'thin-pack'
>>> find_capability(caps, b'missing')
None

Parameters
capabilities:`Iterable[bytes]`	List of capability strings
*capability_names:`bytes`	Capability name(s) to search for

Returns
`bytes \| None`	The value after '=' if found, or the capability name if no '=', or None if not found

def format_ack_line(sha: bytes, ack_type: bytes = b'') -> bytes: ¶

Format an ACK line.

Parameters
sha:`bytes`	SHA to acknowledge
ack_type:`bytes`	Optional ACK type (e.g. b"continue")

Returns
`bytes`	Formatted ACK line

def format_capability_line(capabilities: Iterable[bytes]) -> bytes: ¶

Format a capabilities list for the wire protocol.

Parameters
capabilities:`Iterable[bytes]`	List of capability strings

Returns
`bytes`	Space-separated capabilities as bytes

def format_cmd_pkt(cmd: bytes, *args: bytes) -> bytes: ¶

Format a command packet.

Parameters
cmd:`bytes`	Command name
*args:`bytes`	Command arguments

Returns
`bytes`	Formatted command packet

def format_ref_line(ref: bytes, sha: bytes, capabilities: Sequence[bytes] | None = None) -> bytes: ¶

Format a ref advertisement line.

Parameters
ref:`bytes`	Reference name
sha:`bytes`	SHA hash
capabilities:`Sequence[bytes] \| None`	Optional list of capabilities

Returns
`bytes`	Formatted ref line

def format_shallow_line(sha: bytes) -> bytes: ¶

Format a shallow line.

Parameters
sha:`bytes`	SHA to mark as shallow

Returns
`bytes`	Formatted shallow line

def format_unshallow_line(sha: bytes) -> bytes: ¶

Format an unshallow line.

Parameters
sha:`bytes`	SHA to unshallow

Returns
`bytes`	Formatted unshallow line

def parse_capability(capability: bytes) -> tuple[bytes, bytes | None]: ¶

Parse a capability string into name and value.

Parameters
capability:`bytes`	Capability string

Returns
`tuple[bytes, bytes \| None]`	Tuple of (capability_name, capability_value)

def parse_cmd_pkt(line: bytes) -> tuple[bytes, list[bytes]]: ¶

Parse a command packet.

Parameters
line:`bytes`	Command line to parse

Returns
`tuple[bytes, list[bytes]]`	Tuple of (command, [arguments])

def pkt_line(data: bytes | None) -> bytes: ¶

Wrap data in a pkt-line.

Returns: The data prefixed with its length in pkt-line format; if data was: None, returns the flush-pkt ('0000').

Parameters
data:`bytes \| None`	The data to wrap, as a str or None.

Returns
`bytes`	Undocumented

def pkt_seq(*seq: bytes | None) -> bytes: ¶

Wrap a sequence of data in pkt-lines.

Parameters
*seq:`bytes \| None`	An iterable of strings to wrap.

Returns
`bytes`	Undocumented

def serialize_refs(store: ObjectContainer, refs: Mapping[Ref, ObjectID]) -> dict[bytes, ObjectID]: ¶

Serialize refs with peeled refs for Git protocol v0/v1.

This function is used to prepare refs for transmission over the Git protocol. For tags, it includes both the tag object and the dereferenced object.

Parameters
store:`ObjectContainer`	Object store to peel refs from
refs:`Mapping[Ref, ObjectID]`	Dictionary of ref names to SHAs

Returns
`dict[bytes, ObjectID]`	Dictionary with refs and peeled refs (marked with ^{})

def split_peeled_refs(refs: Mapping[Ref, ObjectID]) -> tuple[dict[Ref, ObjectID], dict[Ref, ObjectID]]: ¶

Split peeled refs from regular refs.

Parameters
refs:`Mapping[Ref, ObjectID]`	Dictionary of refs (may include peeled refs with ^{} suffix)

Returns
`tuple[dict[Ref, ObjectID], dict[Ref, ObjectID]]`	Tuple of (regular_refs, peeled_refs) where peeled_refs keys have the ^{} suffix removed

def strip_peeled_refs(refs: Mapping[Ref, ObjectID | None]) -> dict[Ref, ObjectID | None]: ¶

Remove all peeled refs from a refs dictionary.

Parameters
refs:`Mapping[Ref, ObjectID \| None]`	Dictionary of refs (may include peeled refs with ^{} suffix)

Returns
`dict[Ref, ObjectID \| None]`	Dictionary with peeled refs removed

def symref_capabilities(symrefs: Iterable[tuple[bytes, bytes]]) -> list[bytes]: ¶

Generate symref capability strings from symref pairs.

Parameters
symrefs:`Iterable[tuple[bytes, bytes]]`	Iterable of (from_ref, to_ref) tuples

Returns
`list[bytes]`	List of symref capability strings

def write_info_refs(refs: Mapping[Ref, ObjectID], store: ObjectContainer) -> Iterator[bytes]: ¶

Generate info refs in the format used by the dumb HTTP protocol.

Parameters
refs:`Mapping[Ref, ObjectID]`	Dictionary of refs
store:`ObjectContainer`	Object store to peel tags from

Returns
`Iterator[bytes]`	Undocumented

Yields
Lines in info/refs format (sha + tab + refname)

CAPABILITIES_REF: bytes = ¶

Undocumented

Value

b'capabilities^{}'

CAPABILITY_AGENT: bytes = ¶

Undocumented

Value

b'agent'

CAPABILITY_ALLOW_REACHABLE_SHA1_IN_WANT: bytes = ¶

Undocumented

Value

b'allow-reachable-sha1-in-want'

CAPABILITY_ALLOW_TIP_SHA1_IN_WANT: bytes = ¶

Undocumented

Value

b'allow-tip-sha1-in-want'

CAPABILITY_ATOMIC: bytes = ¶

Undocumented

Value

b'atomic'

CAPABILITY_DEEPEN_NOT: bytes = ¶

Undocumented

Value

b'deepen-not'

CAPABILITY_DEEPEN_RELATIVE: bytes = ¶

Undocumented

Value

b'deepen-relative'

CAPABILITY_DEEPEN_SINCE: bytes = ¶

Undocumented

Value

b'deepen-since'

CAPABILITY_DELETE_REFS: bytes = ¶

Undocumented

Value

b'delete-refs'

CAPABILITY_FETCH: bytes = ¶

Undocumented

Value

b'fetch'

CAPABILITY_FILTER: bytes = ¶

Undocumented

Value

b'filter'

CAPABILITY_INCLUDE_TAG: bytes = ¶

Undocumented

Value

b'include-tag'

CAPABILITY_MULTI_ACK: bytes = ¶

Undocumented

Value

b'multi_ack'

CAPABILITY_MULTI_ACK_DETAILED: bytes = ¶

Undocumented

Value

b'multi_ack_detailed'

CAPABILITY_NO_DONE: bytes = ¶

Undocumented

Value

b'no-done'

CAPABILITY_NO_PROGRESS: bytes = ¶

Undocumented

Value

b'no-progress'

CAPABILITY_OBJECT_FORMAT: bytes = ¶

Undocumented

Value

b'object-format'

CAPABILITY_OFS_DELTA: bytes = ¶

Undocumented

Value

b'ofs-delta'

CAPABILITY_PACKFILE_URIS: bytes = ¶

Undocumented

Value

b'packfile-uris'

CAPABILITY_PUSH_OPTIONS: bytes = ¶

Undocumented

Value

b'push-options'

CAPABILITY_QUIET: bytes = ¶

Undocumented

Value

b'quiet'

CAPABILITY_REPORT_STATUS: bytes = ¶

Undocumented

Value

b'report-status'

CAPABILITY_SHALLOW: bytes = ¶

Undocumented

Value

b'shallow'

CAPABILITY_SIDE_BAND: bytes = ¶

Undocumented

Value

b'side-band'

CAPABILITY_SIDE_BAND_64K: bytes = ¶

Undocumented

Value

b'side-band-64k'

CAPABILITY_SYMREF: bytes = ¶

Undocumented

Value

b'symref'

CAPABILITY_THIN_PACK: bytes = ¶

Undocumented

Value

b'thin-pack'

COMMAND_DEEPEN: bytes = ¶

Undocumented

Value

b'deepen'

COMMAND_DEEPEN_NOT: bytes = ¶

Undocumented

Value

b'deepen-not'

COMMAND_DEEPEN_SINCE: bytes = ¶

Undocumented

Value

b'deepen-since'

COMMAND_DONE: bytes = ¶

Undocumented

Value

b'done'

COMMAND_FILTER: bytes = ¶

Undocumented

Value

b'filter'

COMMAND_HAVE: bytes = ¶

Undocumented

Value

b'have'

COMMAND_SHALLOW: bytes = ¶

Undocumented

Value

b'shallow'

COMMAND_UNSHALLOW: bytes = ¶

Undocumented

Value

b'unshallow'

COMMAND_WANT: bytes = ¶

Undocumented

Value

b'want'

COMMON_CAPABILITIES = ¶

Undocumented

Value

[CAPABILITY_OFS_DELTA,
 CAPABILITY_SIDE_BAND,
 CAPABILITY_SIDE_BAND_64K,
 CAPABILITY_AGENT,
 CAPABILITY_NO_PROGRESS]

DEFAULT_GIT_PROTOCOL_VERSION_FETCH: int = ¶

Undocumented

Value

DEFAULT_GIT_PROTOCOL_VERSION_SEND: int = ¶

Undocumented

Value

DEPTH_INFINITE: int = ¶

Undocumented

Value

2147483647

GIT_PROTOCOL_VERSIONS: list[int] = ¶

Undocumented

Value

[0, 1, 2]

KNOWN_RECEIVE_CAPABILITIES = ¶

Undocumented

Value

set([*COMMON_CAPABILITIES,
     CAPABILITY_REPORT_STATUS,
     CAPABILITY_DELETE_REFS,
     CAPABILITY_QUIET,
     CAPABILITY_ATOMIC,
     CAPABILITY_PUSH_OPTIONS])

KNOWN_UPLOAD_CAPABILITIES = ¶

Undocumented

Value

set([*COMMON_CAPABILITIES,
     CAPABILITY_THIN_PACK,
     CAPABILITY_MULTI_ACK,
     CAPABILITY_MULTI_ACK_DETAILED,
     CAPABILITY_INCLUDE_TAG,
     CAPABILITY_DEEPEN_SINCE,
     CAPABILITY_SYMREF,
...

MULTI_ACK: int = ¶

Undocumented

Value

MULTI_ACK_DETAILED: int = ¶

Undocumented

Value

NAK_LINE: bytes = ¶

Undocumented

Value

b'''NAK
'''

PEELED_TAG_SUFFIX: bytes = ¶

Undocumented

Value

b'^{}'

SIDE_BAND_CHANNEL_DATA: int = ¶

Undocumented

Value

SIDE_BAND_CHANNEL_FATAL: int = ¶

Undocumented

Value

SIDE_BAND_CHANNEL_PROGRESS: int = ¶

Undocumented

Value

SINGLE_ACK: int = ¶

Undocumented

Value

TCP_GIT_PORT: int = ¶

Undocumented

Value

ZERO_SHA: ObjectID = ¶

Undocumented

Value

ObjectID((b'0' * 40))

logger = ¶

Undocumented

_RBUFSIZE: int = ¶

Undocumented

Value