API Reference

pidiff includes a public API which may be used to diff interfaces programmatically.

class pidiff.ChangeType(value)

Enum representing types of API changes.

This is an integer enum, with values given in increasing level of severity.

MAJOR = 300

Major interface changes; functionality was removed or changed in a backwards-incompatible manner.

Type

int

MINOR = 200

Minor interface changes; new but backwards-compatible functionality.

Type

int

NONE = 0

No interface changes.

Type

int

class pidiff.DiffOptions

Options to be used for an interface diff.

property disabled: Set[str]

The set of disabled checks.

Return type

Set[str]

property enabled: Set[str]

The set of enabled checks.

Return type

Set[str]

full_symbol_names

if True, produced log messages will include fully qualified symbol names (e.g. mymodule.submodule.SomeClass) rather than the default short names (e.g. SomeClass).

Type

boolean

set_disabled(check)

Add a check to the set of disabled checks.

Parameters

check (str) – An error code or check name; see Error Reference.

Return type

None

set_enabled(check)

Add a check to the set of enabled checks.

Parameters

check (str) – An error code or check name; see Error Reference.

Return type

None

summarize

If True, a human-readable summary will be logged at the end of the diff.

Type

boolean

class pidiff.DiffResult(max_change_type, max_change_allowed, proposed_version=None)

The result of a diff.

property failed: bool

True if this diff discovered changes in violation of the SemVer spec.

Return type

bool

max_change_allowed

The most severe ChangeType which should be permitted during this diff, according to the version numbers of the diffed modules and SemVer.

max_change_type

The most severe ChangeType encountered during this diff.

proposed_version

Proposed version number for the new version of the diffed module, according to SemVer rules. None if the version of the old module is unknown.

New in version 1.5.0.

pidiff.diff(api_old, api_new, options=None)

Perform a diff between two interfaces.

Parameters

  • api_old (dump) – An interface dump as returned by dump_module(); typically, the dump of an old version of an interface would be provided.

  • api_new (dump) – A second interface dump.

  • options (DiffOptions) – Options to adjust the behavior of the diff.

Returns

Result of the diff.

Return type

DiffResult

Logging:

This function returns only an overall result of a diff. If more details are required, the caller should listen for log messages sent to the pidiff.diff logger.

Records will be streamed to this logger during the diff, including fields:

message:

Human-oriented message explaining a change

extra.change_type:

A ChangeType representing the severity of this change; or absent, for summary log messages

pidiff.dump_module(root_name)

Dump a module.

Parameters

root_name (str) –

Fully qualified name of the module serving as root of a public API, e.g. mypackage.mymodule.

This module must be importable (and will be imported) by the current Python interpreter.

Returns

Information on the module’s public API.

The specific data structure returned is undefined, but is valid for the following uses:

  • serialization and deserialization by JSON or pickling

  • as an argument to diff()

Return type

dump