pydiffx.reader

A streaming reader for DiffX files.

Classes

DiffXReader(fp)

A streaming reader for DiffX files.

class pydiffx.reader.DiffXReader(fp)

Bases: object

A streaming reader for DiffX files.

This is a low-level interface for reading a DiffX file from an existing stream, such as an opened file handle or a web server response.

Consumers can iterate through each section of the DiffX file, reading sections one-by-one and processing them. This can be used to process the metadata on-the-fly without retaining the entirety of the file in memory, or to convert it into another data structure.

See iter_sections() for details on the information returned during iteration.

__init__(fp)

Initialize the reader.

Parameters

fp (file or io.IOBase) – The file pointer/stream to read from. This must be opened in binary (bytes) mode.

__iter__()

Iterate through all sections of a DiffX file.

This is a convenience wrapper around iter_sections(). See that method for details.

Yields

dict – Information on the section.

Raises

pydiffx.errors.DiffXParseError – The file or a section was unable to be parsed. Information will be provided in the message and the instance’s attributes.

iter_sections()

Iterate through all sections of a DiffX file.

Each section and subsection will be parsed individually, returning the following data on each new section:

level (int):

The 0-based section level (corresponding to the number of . level indicator characters in the section ID).

line (int):

The 0-based line number where the section starts.

options (dict):

A dictionary of options found for the section.

section (unicode):

The ID of the section. This corresponds to one of:

• MAIN

• MAIN_PREAMBLE

• MAIN_META

• CHANGE

• CHANGE_PREAMBLE

• CHANGE_META

• FILE

• FILE_META

• FILE_DIFF

type (unicode):

The type of section (the ID in the file following the . level indicator characters).

Preamble sections will also contain:

text (unicode):

The decoded text content of the preamble.

Metadata sections will also contain:

metadata (dict):

A dictionary containing all metadata for the section.

Diff sections will also contain:

diff (bytes or unicode):

The diff content. If an encoding is specified, this will be decoded to a Unicode string. Otherwise, it will be a byte string. Callers must check for this.

Note

If any given section fails to parse, an error will be raised and parsing will stop.

Yields

dict – Information on the section.

Raises

pydiffx.errors.DiffXParseError – The file or a section was unable to be parsed. Information will be provided in the message and the instance’s attributes.