dulwich.mbox

module documentation

Classes for dealing with mbox files and Maildir.

This module provides functionality to split mbox files and Maildir into individual message files, similar to git mailsplit, and to extract patch information from email messages, similar to git mailinfo.

Function	`mailinfo`	Extract patch information from an email message.
Function	`split_maildir`	Split a Maildir into individual message files.
Function	`split_mbox`	Split an mbox file into individual message files.
Function	`_parse_mbox_from_file`	Parse mbox format from a file-like object.
Function	`_reverse_mboxrd_escaping`	Reverse mboxrd escaping (^>+From lines).

def mailinfo(input_file: str | bytes | BinaryIO | TextIO, keep_subject: bool = False, keep_non_patch: bool = False, encoding: str | None = None, scissors: bool = False, message_id: bool = False) -> MailinfoResult: ¶

Extract patch information from an email message.

High-level wrapper around patch.mailinfo() that handles file I/O.

Parameters
input_file:`str \| bytes \| BinaryIO \| TextIO`	Path to email file or file-like object (binary or text)
keep_subject:`bool`	If True, keep subject intact without munging (-k)
keep_non_patch:`bool`	If True, only strip [PATCH] from brackets (-b)
encoding:`str \| None`	Character encoding to use (default: detect from message)
scissors:`bool`	If True, remove everything before scissors line
message_id:`bool`	If True, include Message-ID in commit message (-m)

Returns
`MailinfoResult`	MailinfoResult with parsed information (from patch.mailinfo)

Raises
`ValueError`	If message is malformed or missing required fields
`OSError`	If there are issues reading the file

def split_maildir(maildir_path: str | bytes | Path, output_dir: str | bytes | Path, start_number: int = 1, precision: int = 4, keep_cr: bool = False) -> list[str]: ¶

Split a Maildir into individual message files.

Maildir splitting relies upon filenames being sorted to output patches in the correct order.

Parameters
maildir_path:`str \| bytes \| Path`	Path to the Maildir directory (should contain cur, tmp, new subdirectories)
output_dir:`str \| bytes \| Path`	Directory where individual messages will be written
start_number:`int`	Starting number for output files (default: 1)
precision:`int`	Number of digits for output filenames (default: 4)
keep_cr:`bool`	If True, preserve r in lines ending with rn (default: False)

Returns
`list[str]`	List of output file paths that were created

Raises
`ValueError`	If maildir_path or output_dir don't exist or aren't valid
`OSError`	If there are issues reading/writing files

def split_mbox(input_file: str | bytes | BinaryIO, output_dir: str | bytes | Path, start_number: int = 1, precision: int = 4, keep_cr: bool = False, mboxrd: bool = False) -> list[str]: ¶

Split an mbox file into individual message files.

Parameters
input_file:`str \| bytes \| BinaryIO`	Path to mbox file or file-like object. If None, reads from stdin.
output_dir:`str \| bytes \| Path`	Directory where individual messages will be written
start_number:`int`	Starting number for output files (default: 1)
precision:`int`	Number of digits for output filenames (default: 4)
keep_cr:`bool`	If True, preserve r in lines ending with rn (default: False)
mboxrd:`bool`	If True, treat input as mboxrd format and reverse escaping (default: False)

Returns
`list[str]`	List of output file paths that were created

Raises
`ValueError`	If output_dir doesn't exist or isn't a directory
`OSError`	If there are issues reading/writing files

def _parse_mbox_from_file(file_obj: BinaryIO) -> Iterator[mailbox.mboxMessage]: ¶

Parse mbox format from a file-like object.

Parameters
file_obj:`BinaryIO`	Binary file-like object containing mbox data

Returns
`Iterator[mailbox.mboxMessage]`	Undocumented

Yields
Individual mboxMessage objects

def _reverse_mboxrd_escaping(message_bytes: bytes) -> bytes: ¶

Reverse mboxrd escaping (^>+From lines).

In mboxrd format, lines matching ^>+From have one leading ">" removed.

Parameters
message_bytes:`bytes`	Message content with mboxrd escaping

Returns
`bytes`	Message content with escaping reversed