Skip to content

diff ¤

This module exports "breaking changes" related utilities.

Classes:

Functions:

AttributeChangedTypeBreakage ¤

AttributeChangedTypeBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.AttributeChangedTypeBreakage[AttributeChangedTypeBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.AttributeChangedTypeBreakage
              


          click griffe.diff.AttributeChangedTypeBreakage href "" "griffe.diff.AttributeChangedTypeBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for attributes whose type changed.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

AttributeChangedValueBreakage ¤

AttributeChangedValueBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.AttributeChangedValueBreakage[AttributeChangedValueBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.AttributeChangedValueBreakage
              


          click griffe.diff.AttributeChangedValueBreakage href "" "griffe.diff.AttributeChangedValueBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for attributes whose value changed.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

Breakage ¤

Breakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)

Breakages can explain what broke from a version to another.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

BreakageKind ¤


          flowchart TD
          griffe.diff.BreakageKind[BreakageKind]

          

          click griffe.diff.BreakageKind href "" "griffe.diff.BreakageKind"

Enumeration of the possible API breakages.

ClassRemovedBaseBreakage ¤

ClassRemovedBaseBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ClassRemovedBaseBreakage[ClassRemovedBaseBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ClassRemovedBaseBreakage
              


          click griffe.diff.ClassRemovedBaseBreakage href "" "griffe.diff.ClassRemovedBaseBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for removed base classes.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ExplanationStyle ¤


          flowchart TD
          griffe.diff.ExplanationStyle[ExplanationStyle]

          

          click griffe.diff.ExplanationStyle href "" "griffe.diff.ExplanationStyle"

Enumeration of the possible styles for explanations.

Attributes:

  • GITHUB (str) –

    Explanation as GitHub workflow commands warnings, adapted to CI.

  • MARKDOWN (str) –

    Explanations in Markdown, adapted to changelogs.

  • ONE_LINE (str) –

    Explanations on one-line.

  • VERBOSE (str) –

    Explanations on multiple lines.

GITHUB class-attribute instance-attribute ¤

GITHUB: str = 'github'

Explanation as GitHub workflow commands warnings, adapted to CI.

MARKDOWN class-attribute instance-attribute ¤

MARKDOWN: str = 'markdown'

Explanations in Markdown, adapted to changelogs.

ONE_LINE class-attribute instance-attribute ¤

ONE_LINE: str = 'oneline'

Explanations on one-line.

VERBOSE class-attribute instance-attribute ¤

VERBOSE: str = 'verbose'

Explanations on multiple lines.

ObjectChangedKindBreakage ¤

ObjectChangedKindBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ObjectChangedKindBreakage[ObjectChangedKindBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ObjectChangedKindBreakage
              


          click griffe.diff.ObjectChangedKindBreakage href "" "griffe.diff.ObjectChangedKindBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for objects whose kind changed.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ObjectRemovedBreakage ¤

ObjectRemovedBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ObjectRemovedBreakage[ObjectRemovedBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ObjectRemovedBreakage
              


          click griffe.diff.ObjectRemovedBreakage href "" "griffe.diff.ObjectRemovedBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for removed objects.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ParameterAddedRequiredBreakage ¤

ParameterAddedRequiredBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ParameterAddedRequiredBreakage[ParameterAddedRequiredBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ParameterAddedRequiredBreakage
              


          click griffe.diff.ParameterAddedRequiredBreakage href "" "griffe.diff.ParameterAddedRequiredBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for new parameters added as required.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ParameterChangedDefaultBreakage ¤

ParameterChangedDefaultBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ParameterChangedDefaultBreakage[ParameterChangedDefaultBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ParameterChangedDefaultBreakage
              


          click griffe.diff.ParameterChangedDefaultBreakage href "" "griffe.diff.ParameterChangedDefaultBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for parameters whose default value changed.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ParameterChangedKindBreakage ¤

ParameterChangedKindBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ParameterChangedKindBreakage[ParameterChangedKindBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ParameterChangedKindBreakage
              


          click griffe.diff.ParameterChangedKindBreakage href "" "griffe.diff.ParameterChangedKindBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for parameters whose kind changed.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ParameterChangedRequiredBreakage ¤

ParameterChangedRequiredBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ParameterChangedRequiredBreakage[ParameterChangedRequiredBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ParameterChangedRequiredBreakage
              


          click griffe.diff.ParameterChangedRequiredBreakage href "" "griffe.diff.ParameterChangedRequiredBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for parameters which became required.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ParameterMovedBreakage ¤

ParameterMovedBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ParameterMovedBreakage[ParameterMovedBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ParameterMovedBreakage
              


          click griffe.diff.ParameterMovedBreakage href "" "griffe.diff.ParameterMovedBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for moved parameters.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ParameterRemovedBreakage ¤

ParameterRemovedBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ParameterRemovedBreakage[ParameterRemovedBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ParameterRemovedBreakage
              


          click griffe.diff.ParameterRemovedBreakage href "" "griffe.diff.ParameterRemovedBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for removed parameters.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

ReturnChangedTypeBreakage ¤

ReturnChangedTypeBreakage(
    obj: Object,
    old_value: Any,
    new_value: Any,
    details: str = "",
)


          flowchart TD
          griffe.diff.ReturnChangedTypeBreakage[ReturnChangedTypeBreakage]
          griffe.diff.Breakage[Breakage]

                        griffe.diff.Breakage --> griffe.diff.ReturnChangedTypeBreakage
              


          click griffe.diff.ReturnChangedTypeBreakage href "" "griffe.diff.ReturnChangedTypeBreakage"
          click griffe.diff.Breakage href "" "griffe.diff.Breakage"

Specific breakage class for return values which changed type.

Parameters:

  • obj (Object) –

    The object related to the breakage.

  • old_value (Any) –

    The old value.

  • new_value (Any) –

    The new, incompatible value.

  • details (str, default: '' ) –

    Some details about the breakage.

Methods:

  • as_dict –

    Return this object's data as a dictionary.

  • explain –

    Explain the breakage by showing old and new value.

as_dict ¤

as_dict(
    *, full: bool = False, **kwargs: Any
) -> dict[str, Any]

Return this object's data as a dictionary.

Parameters:

  • full (bool, default: False ) –

    Whether to return full info, or just base info.

  • **kwargs (Any, default: {} ) –

    Additional serialization options.

Returns:

explain ¤

explain(style: ExplanationStyle = ONE_LINE) -> str

Explain the breakage by showing old and new value.

Parameters:

Returns:

  • str –

    An explanation.

find_breaking_changes ¤

find_breaking_changes(
    old_obj: Object | Alias,
    new_obj: Object | Alias,
    *,
    ignore_private: bool = True
) -> Iterator[Breakage]

Find breaking changes between two versions of the same API.

The function will iterate recursively on all objects and yield breaking changes with detailed information.

Parameters:

  • old_obj (Object | Alias) –

    The old version of an object.

  • new_obj (Object | Alias) –

    The new version of an object.

Yields:

Examples:

>>> import sys, griffe
>>> new = griffe.load("pkg")
>>> old = griffe.load_git("pkg", "1.2.3")
>>> for breakage in griffe.find_breaking_changes(old, new)
...     print(breakage.explain(style=style), file=sys.stderr)