pydiffx.writer#

A streaming writer for DiffX files.

Classes

DiffXWriter(fp[, encoding, version])

A streaming writer for DiffX files.
class pydiffx.writer.DiffXWriter(fp, encoding='utf-8', version='1.0')#

Bases: object

A streaming writer for DiffX files.

This is a low-level interface for writing a DiffX file to an existing stream, such as an opened file handle or an in-progress web server response.

Consumers can incrementally write change, file, metadata, preamble, and diff contents to the stream without keeping it all in memory up-front. Consumers are responsible for including any necessary metadata for each section.

VERSION = '1.0'#

The supported version of the DiffX specification.

DEFAULT_PREAMBLE_INDENT = 4#

Default indentation to apply to preamble sections.

DEFAULT_ENCODING = 'utf-8'#

Default encoding to use for the DiffX file.

__init__(fp, encoding='utf-8', version='1.0')#

Initialize the writer.

Parameters

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

  • encoding (unicode, optional) – The default encoding for content in the file. This will generally be left as the default of “utf-8”.

  • version (unicode, optional) –

    The version of the DiffX file to write.

    This must currently be 1.0.

new_change(encoding=None)#

Write a new change section to the stream.

Parameters

encoding (unicode, optional) – The encoding to use for the section. Defaults to the main DiffX file encoding.

Raises

pydiffx.errors.DiffXSectionOrderError – This was called at the wrong point in diff generation.

new_file(encoding=None)#

Write a new file section to the stream.

new_change() must have been called at least once before this is called.

Parameters

encoding (unicode, optional) – The encoding to use for the section. Defaults to the parent change section’s encoding.

Raises

pydiffx.errors.DiffXSectionOrderError – This was called at the wrong point in diff generation.

write_preamble(text, encoding=None, indent=4, line_endings=None, mimetype=None)#

Write a new preamble section for a change or a file.

If called as the first operation on a new stream, this will write a top-level DiffX preamble.

If called immediately after a call to new_change(), this will write a change preamble.

This cannot be called at any other time.

This must be called before write_meta() in the section.

Parameters

  • text (unicode) – The text to write.

  • encoding (unicode, optional) – The encoding to use for the section. Defaults to the parent change section’s encoding.

  • indent (int, optional) –

    The optional indentation level for the text. This defaults to 4 spaces.

    This is used to ensure preamble text cannot interfere with the parsing of any DiffX or diff content.

  • line_endings (unicode, optional) –

    The line endings used for the preamble. This can be “dos” or “unix”.

    If not provided, a value will be computed based on content, and then inserted into the header.

  • mimetype (unicode, optional) –

    The optional mimetype for the file contents. If not provided, this will be plain text.

    Supported values are text/plain or text/markdown.

Raises
write_meta(metadata, encoding=None, meta_format='json')#

Write a new meta section for DiffX, a change, or a file.

If called before new_change(), this will write a top-level DiffX meta section.

If called after new_change() but before new_file(), this will write a change meta section.

If called after new_file(), this will write a file meta section.

This cannot be called before write_preamble() in the section, or after write_diff() in file sections.

Parameters

  • metadata (dict) – The metadata to write.

  • encoding (unicode, optional) – The encoding to use for the section. Defaults to the parent change section’s encoding.

  • meta_format (unicode, optional) –

    The format for this metadata section.

    Valid values are in MetaFormat.

Raises
write_diff(content, diff_type=None, encoding=None, line_endings=None)#

Write a new diff section for a file.

This must be called after new_file(), and must be after the write_meta() call.

Parameters

  • content (bytes) – The diff content to write.

  • diff_type (unicode, optional) – The type of diff to write. This must be one of DIFF_TYPE_TEXT or DIFF_TYPE_BINARY.

  • encoding (unicode, optional) – The encoding to use for the section. This does not inherit from previous sections.

  • line_endings (unicode, optional) –

    The line endings used for the diff. This can be “dos” or “unix”.

    If not provided, a value will be computed based on content, and then inserted into the header.

Raises