Match

Matching functionality.

This module provides the functionality to define matching rules to be used within a Pact contract. These rules define the expected content of the data being exchanged in a way that is more flexible than a simple equality check.

As an example, a contract may define how a new record is to be created through a POST request. The consumer would define the new information to be sent, and the expected response. The response may contain additional data added by the provider, such as an ID and a creation timestamp. The contract would define that the ID is of a specific format (e.g., an integer or a UUID), and that the creation timestamp is ISO 8601 formatted.

Warning

Do not import functions directly from this module. Instead, import the match module and use the functions from there:

# Good
from pact import match

match.int(...)

# Bad
from pact.match import int

int(...)

A number of functions in this module are named after the types they match (e.g., int, str, bool). These functions will have aliases as well for better interoperability with the rest of the Pact ecosystem. It is important to note that these functions will shadow the built-in types if imported directly from this module. This is why we recommend importing the match module and using the functions from there.

Matching rules are frequently combined with generators which allow for Pact to generate values on the fly during contract testing. As a general rule for the functions below, if a value is not provided, a generator will be used; and conversely, if a value is provided, a generator will not be used.

Attributes

Classes

Matcher

Bases: ABC, Generic[_T_co]

Abstract matcher.

In Pact, a matcher is used to define how a value should be compared. This allows for more flexible matching of data, especially when the provider returns dynamically generated data.

This class is abstract and should not be used directly. Instead, use one of the concrete matcher classes. Alternatively, you can create your own matcher by subclassing this class.

The matcher provides methods to convert into an integration JSON object and a matching rule. These methods are used internally by the Pact library when communicating with the FFI and generating the Pact file.

Functions

to_integration_json() -> dict[str, Any] abstractmethod

Convert the matcher to an integration JSON object.

This method is used internally to convert the matcher to a JSON object which can be embedded directly in a number of places in the Pact FFI.

For more information about this format, see the docs:

https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson

RETURNS	DESCRIPTION
dict[str, Any]	The matcher as an integration JSON object.

Source code in src/pact/match/matcher.py

@abstractmethod
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    This method is used internally to convert the matcher to a JSON object
    which can be embedded directly in a number of places in the Pact FFI.

    For more information about this format, see the docs:

    > https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson

    Returns:
        The matcher as an integration JSON object.
    """

to_matching_rule() -> dict[str, Any] abstractmethod

Convert the matcher to a matching rule.

This method is used internally to convert the matcher to a matching rule which can be embedded directly in a Pact file.

For more information about this format, see the docs:

https://github.com/pact-foundation/pact-specification/tree/version-4

and

https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers

RETURNS	DESCRIPTION
dict[str, Any]	The matcher as a matching rule.

Source code in src/pact/match/matcher.py

@abstractmethod
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    This method is used internally to convert the matcher to a matching rule
    which can be embedded directly in a Pact file.

    For more information about this format, see the docs:

    > https://github.com/pact-foundation/pact-specification/tree/version-4

    and

    > https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers

    Returns:
        The matcher as a matching rule.
    """

Functions

array_containing(variants: Sequence[_T | Matcher[_T]]) -> Matcher[Sequence[_T]]

Match an array that contains the given variants.

Matching is successful if each variant occurs once in the array. Variants may be objects containing matching rules.

PARAMETER	DESCRIPTION
variants	A list of variants to match against. TYPE: Sequence[_T | Matcher[_T]]

RETURNS	DESCRIPTION
Matcher[Sequence[_T]]	Matcher for arrays containing the given variants.

Source code in src/pact/match/__init__.py

def array_containing(variants: Sequence[_T | Matcher[_T]], /) -> Matcher[Sequence[_T]]:
    """
    Match an array that contains the given variants.

    Matching is successful if each variant occurs once in the array. Variants
    may be objects containing matching rules.

    Args:
        variants:
            A list of variants to match against.

    Returns:
        Matcher for arrays containing the given variants.
    """
    return ArrayContainsMatcher(variants=variants)

bool(value: builtins.bool | Unset = UNSET) -> Matcher[builtins.bool]

Match a boolean value.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: bool | Unset DEFAULT: UNSET

RETURNS	DESCRIPTION
Matcher[bool]	Matcher for boolean values.

Source code in src/pact/match/__init__.py

def bool(value: builtins.bool | Unset = UNSET, /) -> Matcher[builtins.bool]:
    """
    Match a boolean value.

    Args:
        value:
            Default value to use when generating a consumer test.

    Returns:
        Matcher for boolean values.
    """
    if value is UNSET:
        return GenericMatcher("boolean", generator=generate.bool())
    return GenericMatcher("boolean", value)

boolean(value: builtins.bool | Unset = UNSET) -> Matcher[builtins.bool]

Alias for match.bool.

Source code in src/pact/match/__init__.py

def boolean(value: builtins.bool | Unset = UNSET, /) -> Matcher[builtins.bool]:
    """
    Alias for [`match.bool`][pact.match.bool].
    """
    return bool(value)

date(value: dt.date | builtins.str | Unset = UNSET, /, format: builtins.str | None = None, *, disable_conversion: builtins.bool = False) -> Matcher[builtins.str]

Match a date value.

A date value is a string that represents a date in a specific format. It does not have any time information.

Info

Pact internally uses the Java's SimpleDateFormat. To ensure compatibility with the rest of the Python ecosystem, this function accepts Python's strftime format and performs the conversion to Java's format internally.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: date | str | Unset DEFAULT: UNSET
format	Expected format of the date. If not provided, an ISO 8601 date format will be used: %Y-%m-%d. TYPE: str | None DEFAULT: None
disable_conversion	If True, the conversion from Python's strftime format to Java's SimpleDateFormat format will be disabled, and the format must be in Java's SimpleDateFormat format. As a result, the value must be a string as Python cannot format the date in the target format. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Matcher[str]	Matcher for date strings.

Source code in src/pact/match/__init__.py

def date(
    value: dt.date | builtins.str | Unset = UNSET,
    /,
    format: builtins.str | None = None,
    *,
    disable_conversion: builtins.bool = False,
) -> Matcher[builtins.str]:
    """
    Match a date value.

    A date value is a string that represents a date in a specific format. It
    does _not_ have any time information.

    !!! info

        Pact internally uses the Java's
        [`SimpleDateFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html).
        To ensure compatibility with the rest of the Python ecosystem, this
        function accepts Python's
        [`strftime`](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)
        format and performs the conversion to Java's format internally.

    Args:
        value:
            Default value to use when generating a consumer test.

        format:
            Expected format of the date.

            If not provided, an ISO 8601 date format will be used: `%Y-%m-%d`.

        disable_conversion:
            If True, the conversion from Python's `strftime` format to Java's
            `SimpleDateFormat` format will be disabled, and the format must be
            in Java's `SimpleDateFormat` format. As a result, the value must
            be a string as Python cannot format the date in the target format.

    Returns:
        Matcher for date strings.
    """
    if disable_conversion:
        if not isinstance(value, builtins.str):
            msg = "When disable_conversion is True, the value must be a string."
            raise ValueError(msg)
        format = format or "yyyy-MM-dd"
        if value is UNSET:
            return GenericMatcher(
                "date",
                format=format,
                generator=generate.date(format, disable_conversion=True),
            )
        return GenericMatcher(
            "date",
            value=value,
            format=format,
        )

    format = format or "%Y-%m-%d"
    if isinstance(value, dt.date):
        value = value.strftime(format)
    format = strftime_to_simple_date_format(format)

    if value is UNSET:
        return GenericMatcher(
            "date",
            format=format,
            generator=generate.date(format, disable_conversion=True),
        )
    return GenericMatcher(
        "date",
        value=value,
        format=format,
    )

datetime(value: dt.datetime | builtins.str | Unset = UNSET, /, format: builtins.str | None = None, *, disable_conversion: builtins.bool = False) -> Matcher[builtins.str]

Match a datetime value.

A timestamp value is a string that represents a date and time in a specific format.

Info

Pact internally uses the Java's SimpleDateFormat. To ensure compatibility with the rest of the Python ecosystem, this function accepts Python's strftime format and performs the conversion to Java's format internally.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: datetime | str | Unset DEFAULT: UNSET
format	Expected format of the timestamp. If not provided, an ISO 8601 timestamp format will be used: %Y-%m-%dT%H:%M:%S%z. TYPE: str | None DEFAULT: None
disable_conversion	If True, the conversion from Python's strftime format to Java's SimpleDateFormat format will be disabled, and the format must be in Java's SimpleDateFormat format. As a result, the value must be a string as Python cannot format the timestamp in the target format. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Matcher[str]	Matcher for datetime strings.

Source code in src/pact/match/__init__.py

def datetime(
    value: dt.datetime | builtins.str | Unset = UNSET,
    /,
    format: builtins.str | None = None,
    *,
    disable_conversion: builtins.bool = False,
) -> Matcher[builtins.str]:
    """
    Match a datetime value.

    A timestamp value is a string that represents a date and time in a specific
    format.

    !!! info

        Pact internally uses the Java's
        [`SimpleDateFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html).
        To ensure compatibility with the rest of the Python ecosystem, this
        function accepts Python's
        [`strftime`](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)
        format and performs the conversion to Java's format internally.

    Args:
        value:
            Default value to use when generating a consumer test.

        format:
            Expected format of the timestamp.

            If not provided, an ISO 8601 timestamp format will be used:
            `%Y-%m-%dT%H:%M:%S%z`.

        disable_conversion:
            If True, the conversion from Python's `strftime` format to Java's
            `SimpleDateFormat` format will be disabled, and the format must be
            in Java's `SimpleDateFormat` format. As a result, the value must be
            a string as Python cannot format the timestamp in the target format.

    Returns:
        Matcher for datetime strings.
    """
    if disable_conversion:
        if not isinstance(value, builtins.str):
            msg = "When disable_conversion is True, the value must be a string."
            raise ValueError(msg)
        format = format or "yyyy-MM-dd'T'HH:mm:ssZ"
        if value is UNSET:
            return GenericMatcher(
                "timestamp",
                format=format,
                generator=generate.datetime(format, disable_conversion=True),
            )
        return GenericMatcher(
            "timestamp",
            value=value,
            format=format,
        )
    format = format or "%Y-%m-%dT%H:%M:%S%z"
    if isinstance(value, dt.datetime):
        value = value.strftime(format)
    format = strftime_to_simple_date_format(format)
    if value is UNSET:
        return GenericMatcher(
            "timestamp",
            format=format,
            generator=generate.datetime(format, disable_conversion=True),
        )
    return GenericMatcher(
        "timestamp",
        value=value,
        format=format,
    )

decimal(value: _NumberT | Unset = UNSET, /, *, precision: builtins.int | None = None) -> Matcher[_NumberT]

Alias for match.float.

Source code in src/pact/match/__init__.py

def decimal(
    value: _NumberT | Unset = UNSET,
    /,
    *,
    precision: builtins.int | None = None,
) -> Matcher[_NumberT]:
    """
    Alias for [`match.float`][pact.match.float].
    """
    return float(value, precision=precision)

each_key_matches(value: Mapping[_T, Any], /, *, rules: Matcher[_T] | list[Matcher[_T]]) -> Matcher[Mapping[_T, Matchable]]

Match each key in a dictionary against a set of rules.

PARAMETER	DESCRIPTION
value	The value to match against. TYPE: Mapping[_T, Any]
rules	The matching rules to match against each key. TYPE: Matcher[_T] | list[Matcher[_T]]

RETURNS	DESCRIPTION
Matcher[Mapping[_T, Matchable]]	Matcher for dictionaries where each key matches the given rules.

Source code in src/pact/match/__init__.py

def each_key_matches(
    value: Mapping[_T, Any],
    /,
    *,
    rules: Matcher[_T] | list[Matcher[_T]],
) -> Matcher[Mapping[_T, Matchable]]:
    """
    Match each key in a dictionary against a set of rules.

    Args:
        value:
            The value to match against.

        rules:
            The matching rules to match against each key.

    Returns:
        Matcher for dictionaries where each key matches the given rules.
    """
    if isinstance(rules, Matcher):
        rules = [rules]
    return EachKeyMatcher(value=value, rules=rules)

each_like(value: _T, /, *, min: builtins.int | None = None, max: builtins.int | None = None) -> Matcher[Sequence[_T]]

Match each item in an array against a given value.

The value itself is arbitrary, and can include other matchers.

PARAMETER	DESCRIPTION
value	The value to match against. TYPE: _T
min	The minimum number of items that must match the value. The minimum value is always 1, even if min is set to 0. TYPE: int | None DEFAULT: None
max	The maximum number of items that must match the value. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[Sequence[_T]]	Matcher for arrays where each item matches the given value.

Source code in src/pact/match/__init__.py

def each_like(
    value: _T,
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
) -> Matcher[Sequence[_T]]:  # type: ignore[type-var]
    """
    Match each item in an array against a given value.

    The value itself is arbitrary, and can include other matchers.

    Args:
        value:
            The value to match against.

        min:
            The minimum number of items that must match the value. The minimum
            value is always 1, even if min is set to 0.

        max:
            The maximum number of items that must match the value.

    Returns:
        Matcher for arrays where each item matches the given value.
    """
    if min is not None and min < 1:
        warnings.warn(
            "The minimum number of items must be at least 1.",
            stacklevel=2,
        )
    return GenericMatcher("type", value=[value], min=min, max=max)  # type: ignore[return-value]

each_value_matches(value: Mapping[Any, _T], /, *, rules: Matcher[_T] | list[Matcher[_T]]) -> Matcher[Mapping[Matchable, _T]]

Returns a matcher that matches each value in a dictionary against a set of rules.

PARAMETER	DESCRIPTION
value	The value to match against. TYPE: Mapping[Any, _T]
rules	The matching rules to match against each value. TYPE: Matcher[_T] | list[Matcher[_T]]

RETURNS	DESCRIPTION
Matcher[Mapping[Matchable, _T]]	Matcher for dictionaries where each value matches the given rules.

Source code in src/pact/match/__init__.py

def each_value_matches(
    value: Mapping[Any, _T],
    /,
    *,
    rules: Matcher[_T] | list[Matcher[_T]],
) -> Matcher[Mapping[Matchable, _T]]:
    """
    Returns a matcher that matches each value in a dictionary against a set of rules.

    Args:
        value:
            The value to match against.

        rules:
            The matching rules to match against each value.

    Returns:
        Matcher for dictionaries where each value matches the given rules.
    """
    if isinstance(rules, Matcher):
        rules = [rules]
    return EachValueMatcher(value=value, rules=rules)

float(value: _NumberT | Unset = UNSET, /, *, precision: builtins.int | None = None) -> Matcher[_NumberT]

Match a floating point number.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: _NumberT | Unset DEFAULT: UNSET
precision	The number of decimal precision to generate. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[_NumberT]	Matcher for floating point numbers.

Source code in src/pact/match/__init__.py

def float(
    value: _NumberT | Unset = UNSET,
    /,
    *,
    precision: builtins.int | None = None,
) -> Matcher[_NumberT]:
    """
    Match a floating point number.

    Args:
        value:
            Default value to use when generating a consumer test.

        precision:
            The number of decimal precision to generate.

    Returns:
        Matcher for floating point numbers.
    """
    if value is UNSET:
        return GenericMatcher(
            "decimal",
            generator=generate.float(precision),
        )
    return GenericMatcher(
        "decimal",
        value,
    )

includes(value: builtins.str, /, *, generator: Generator | None = None) -> Matcher[builtins.str]

Match a string that includes a given value.

PARAMETER	DESCRIPTION
value	The value to match against. TYPE: str
generator	The generator to use when generating the value. TYPE: Generator | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[str]	Matcher for strings that include the given value.

Source code in src/pact/match/__init__.py

def includes(
    value: builtins.str,
    /,
    *,
    generator: Generator | None = None,
) -> Matcher[builtins.str]:
    """
    Match a string that includes a given value.

    Args:
        value:
            The value to match against.

        generator:
            The generator to use when generating the value.

    Returns:
        Matcher for strings that include the given value.
    """
    return GenericMatcher(
        "include",
        value=value,
        generator=generator,
    )

int(value: builtins.int | Unset = UNSET, /, *, min: builtins.int | None = None, max: builtins.int | None = None) -> Matcher[builtins.int]

Match an integer value.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: int | Unset DEFAULT: UNSET
min	If provided, the minimum value of the integer to generate. TYPE: int | None DEFAULT: None
max	If provided, the maximum value of the integer to generate. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[int]	Matcher for integer values.

Source code in src/pact/match/__init__.py

def int(
    value: builtins.int | Unset = UNSET,
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
) -> Matcher[builtins.int]:
    """
    Match an integer value.

    Args:
        value:
            Default value to use when generating a consumer test.

        min:
            If provided, the minimum value of the integer to generate.

        max:
            If provided, the maximum value of the integer to generate.

    Returns:
        Matcher for integer values.
    """
    if value is UNSET:
        return GenericMatcher(
            "integer",
            generator=generate.int(min=min, max=max),
        )
    return GenericMatcher(
        "integer",
        value=value,
    )

integer(value: builtins.int | Unset = UNSET, /, *, min: builtins.int | None = None, max: builtins.int | None = None) -> Matcher[builtins.int]

Alias for match.int.

Source code in src/pact/match/__init__.py

def integer(
    value: builtins.int | Unset = UNSET,
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
) -> Matcher[builtins.int]:
    """
    Alias for [`match.int`][pact.match.int].
    """
    return int(value, min=min, max=max)

like(value: _T, /, *, min: builtins.int | None = None, max: builtins.int | None = None, generator: Generator | None = None) -> Matcher[_T]

Alias for match.type.

Source code in src/pact/match/__init__.py

def like(
    value: _T,
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
    generator: Generator | None = None,
) -> Matcher[_T]:
    """
    Alias for [`match.type`][pact.match.type].
    """
    return type(value, min=min, max=max, generator=generator)

none() -> Matcher[None]

Match a null value.

Source code in src/pact/match/__init__.py

def none() -> Matcher[None]:
    """
    Match a null value.
    """
    return GenericMatcher("null")

null() -> Matcher[None]

Alias for match.none.

Source code in src/pact/match/__init__.py

def null() -> Matcher[None]:
    """
    Alias for [`match.none`][pact.match.none].
    """
    return none()

number(value: builtins.int | builtins.float | Decimal | Unset = UNSET, /, *, min: builtins.int | None = None, max: builtins.int | None = None, precision: builtins.int | None = None) -> Matcher[builtins.int] | Matcher[builtins.float] | Matcher[Decimal]

number(
    value: builtins.int,
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
) -> Matcher[builtins.int]

number(
    value: builtins.float,
    /,
    *,
    precision: builtins.int | None = None,
) -> Matcher[builtins.float]

number(
    value: Decimal,
    /,
    *,
    precision: builtins.int | None = None,
) -> Matcher[Decimal]

number(value: Unset = UNSET) -> Matcher[builtins.float]

Match a general number.

This matcher is a generalization of the integer and decimal matchers. It can be used to match any number, whether it is an integer or a float.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: int | float | Decimal | Unset DEFAULT: UNSET
min	The minimum value of the number to generate. Only used when value is an integer. TYPE: int | None DEFAULT: None
max	The maximum value of the number to generate. Only used when value is an integer. TYPE: int | None DEFAULT: None
precision	The number of decimal digits to generate. Only used when value is a float. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[int] | Matcher[float] | Matcher[Decimal]	Matcher for numbers (integer, float, or Decimal).

Source code in src/pact/match/__init__.py

def number(
    value: builtins.int | builtins.float | Decimal | Unset = UNSET,  # noqa: PYI041
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
    precision: builtins.int | None = None,
) -> Matcher[builtins.int] | Matcher[builtins.float] | Matcher[Decimal]:
    """
    Match a general number.

    This matcher is a generalization of the [`integer`][pact.match.integer]
    and [`decimal`][pact.match.decimal] matchers. It can be used to match any
    number, whether it is an integer or a float.

    Args:
        value:
            Default value to use when generating a consumer test.

        min:
            The minimum value of the number to generate. Only used when value is
            an integer.

        max:
            The maximum value of the number to generate. Only used when value is
            an integer.

        precision:
            The number of decimal digits to generate. Only used when value is a
            float.

    Returns:
        Matcher for numbers (integer, float, or Decimal).
    """
    if value is UNSET:
        if min is not None or max is not None:
            generator = generate.int(min=min, max=max)
        elif precision is not None:
            generator = generate.float(precision)
        else:
            msg = "At least one of min, max, or precision must be provided."
            raise ValueError(msg)
        return GenericMatcher("number", generator=generator)

    if isinstance(value, builtins.int):
        if precision is not None:
            warnings.warn(
                "The precision argument is ignored when value is an integer.",
                stacklevel=2,
            )
        return GenericMatcher(
            "number",
            value=value,
        )

    if isinstance(value, builtins.float):
        if min is not None or max is not None:
            warnings.warn(
                "The min and max arguments are ignored when value is not an integer.",
                stacklevel=2,
            )
        return GenericMatcher(
            "number",
            value=value,
        )

    if isinstance(value, Decimal):
        if min is not None or max is not None:
            warnings.warn(
                "The min and max arguments are ignored when value is not an integer.",
                stacklevel=2,
            )
        return GenericMatcher(
            "number",
            value=value,
        )

    msg = f"Unsupported number type: {builtins.type(value)}"
    raise TypeError(msg)

regex(value: builtins.str | Unset = UNSET, /, *, regex: builtins.str | None = None) -> Matcher[builtins.str]

Match a string against a regular expression.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: str | Unset DEFAULT: UNSET
regex	The regular expression to match against. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[str]	Matcher for strings matching the given regular expression.

Source code in src/pact/match/__init__.py

def regex(
    value: builtins.str | Unset = UNSET,
    /,
    *,
    regex: builtins.str | None = None,
) -> Matcher[builtins.str]:
    """
    Match a string against a regular expression.

    Args:
        value:
            Default value to use when generating a consumer test.

        regex:
            The regular expression to match against.

    Returns:
        Matcher for strings matching the given regular expression.
    """
    if regex is None:
        msg = "A regex pattern must be provided."
        raise ValueError(msg)

    if value is UNSET:
        return GenericMatcher(
            "regex",
            generator=generate.regex(regex),
            regex=regex,
        )
    return GenericMatcher(
        "regex",
        value,
        regex=regex,
    )

str(value: builtins.str | Unset = UNSET, /, *, size: builtins.int | None = None, generator: Generator | None = None) -> Matcher[builtins.str]

Match a string value.

This function can be used to match a string value, merely verifying that the value is a string, possibly with a specific length.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: str | Unset DEFAULT: UNSET
size	The size of the string to generate during a consumer test. TYPE: int | None DEFAULT: None
generator	Alternative generator to use when generating a consumer test. If set, the size argument is ignored. TYPE: Generator | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[str]	Matcher for string values.

Source code in src/pact/match/__init__.py

def str(
    value: builtins.str | Unset = UNSET,
    /,
    *,
    size: builtins.int | None = None,
    generator: Generator | None = None,
) -> Matcher[builtins.str]:
    """
    Match a string value.

    This function can be used to match a string value, merely verifying that the
    value is a string, possibly with a specific length.

    Args:
        value:
            Default value to use when generating a consumer test.

        size:
            The size of the string to generate during a consumer test.

        generator:
            Alternative generator to use when generating a consumer test.
            If set, the `size` argument is ignored.

    Returns:
        Matcher for string values.
    """
    if value is UNSET:
        if size and generator:
            warnings.warn(
                "The size argument is ignored when a generator is provided.",
                stacklevel=2,
            )
        return GenericMatcher(
            "type",
            value="string",
            generator=generator or generate.str(size),
        )

    if size is not None or generator:
        warnings.warn(
            "The size and generator arguments are ignored when a value is provided.",
            stacklevel=2,
        )
    return GenericMatcher(
        "type",
        value=value,
    )

string(value: builtins.str | Unset = UNSET, /, *, size: builtins.int | None = None, generator: Generator | None = None) -> Matcher[builtins.str]

Alias for match.str.

Source code in src/pact/match/__init__.py

def string(
    value: builtins.str | Unset = UNSET,
    /,
    *,
    size: builtins.int | None = None,
    generator: Generator | None = None,
) -> Matcher[builtins.str]:
    """
    Alias for [`match.str`][pact.match.str].
    """
    return str(value, size=size, generator=generator)

time(value: dt.time | builtins.str | Unset = UNSET, /, format: builtins.str | None = None, *, disable_conversion: builtins.bool = False) -> Matcher[builtins.str]

Match a time value.

A time value is a string that represents a time in a specific format. It does not have any date information.

Info

Pact internally uses the Java's SimpleDateFormat. To ensure compatibility with the rest of the Python ecosystem, this function accepts Python's strftime format and performs the conversion to Java's format internally.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: time | str | Unset DEFAULT: UNSET
format	Expected format of the time. If not provided, an ISO 8601 time format will be used: %H:%M:%S. TYPE: str | None DEFAULT: None
disable_conversion	If True, the conversion from Python's strftime format to Java's SimpleDateFormat format will be disabled, and the format must be in Java's SimpleDateFormat format. As a result, the value must be a string as Python cannot format the time in the target format. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
Matcher[str]	Matcher for time strings.

Source code in src/pact/match/__init__.py

def time(
    value: dt.time | builtins.str | Unset = UNSET,
    /,
    format: builtins.str | None = None,
    *,
    disable_conversion: builtins.bool = False,
) -> Matcher[builtins.str]:
    """
    Match a time value.

    A time value is a string that represents a time in a specific format. It
    does _not_ have any date information.

    !!! info

        Pact internally uses the Java's
        [`SimpleDateFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html).
        To ensure compatibility with the rest of the Python ecosystem, this
        function accepts Python's [`strftime`](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)
        format and performs the conversion to Java's format internally.

    Args:
        value:
            Default value to use when generating a consumer test.

        format:
            Expected format of the time.

            If not provided, an ISO 8601 time format will be used: `%H:%M:%S`.

        disable_conversion:
            If True, the conversion from Python's `strftime` format to Java's
            `SimpleDateFormat` format will be disabled, and the format must be
            in Java's `SimpleDateFormat` format. As a result, the value must
            be a string as Python cannot format the time in the target format.

    Returns:
        Matcher for time strings.
    """
    if disable_conversion:
        if not isinstance(value, builtins.str):
            msg = "When disable_conversion is True, the value must be a string."
            raise ValueError(msg)
        format = format or "HH:mm:ss"
        if value is UNSET:
            return GenericMatcher(
                "time",
                format=format,
                generator=generate.time(format, disable_conversion=True),
            )
        return GenericMatcher(
            "time",
            value=value,
            format=format,
        )
    format = format or "%H:%M:%S"
    if isinstance(value, dt.time):
        value = value.strftime(format)
    format = strftime_to_simple_date_format(format)
    if value is UNSET:
        return GenericMatcher(
            "time",
            format=format,
            generator=generate.time(format, disable_conversion=True),
        )
    return GenericMatcher(
        "time",
        value=value,
        format=format,
    )

timestamp(value: dt.datetime | builtins.str | Unset = UNSET, /, format: builtins.str | None = None, *, disable_conversion: builtins.bool = False) -> Matcher[builtins.str]

Alias for match.datetime.

Source code in src/pact/match/__init__.py

def timestamp(
    value: dt.datetime | builtins.str | Unset = UNSET,
    /,
    format: builtins.str | None = None,
    *,
    disable_conversion: builtins.bool = False,
) -> Matcher[builtins.str]:
    """
    Alias for [`match.datetime`][pact.match.datetime].
    """
    return datetime(value, format, disable_conversion=disable_conversion)

type(value: _T, /, *, min: builtins.int | None = None, max: builtins.int | None = None, generator: Generator | None = None) -> Matcher[_T]

Match a value by type.

PARAMETER	DESCRIPTION
value	A value to match against. This can be a primitive value, or a more complex object or array. TYPE: _T
min	The minimum number of items that must match the value. TYPE: int | None DEFAULT: None
max	The maximum number of items that must match the value. TYPE: int | None DEFAULT: None
generator	The generator to use when generating the value. TYPE: Generator | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[_T]	Matcher for the given value type.

Source code in src/pact/match/__init__.py

def type(
    value: _T,
    /,
    *,
    min: builtins.int | None = None,
    max: builtins.int | None = None,
    generator: Generator | None = None,
) -> Matcher[_T]:
    """
    Match a value by type.

    Args:
        value:
            A value to match against. This can be a primitive value, or a more
            complex object or array.

        min:
            The minimum number of items that must match the value.

        max:
            The maximum number of items that must match the value.

        generator:
            The generator to use when generating the value.

    Returns:
        Matcher for the given value type.
    """
    if value is UNSET:
        if not generator:
            msg = "A generator must be provided when value is not set."
            raise ValueError(msg)
        return GenericMatcher("type", min=min, max=max, generator=generator)
    return GenericMatcher("type", value, min=min, max=max, generator=generator)

uuid(value: builtins.str | Unset = UNSET, /, *, format: Literal['uppercase', 'lowercase', 'urn', 'simple'] | None = None) -> Matcher[builtins.str]

Match a UUID value.

This matcher internally combines the regex matcher with a UUID regex pattern. See RFC 4122 for details about the UUID format.

While RFC 4122 requires UUIDs to be output as lowercase, UUIDs are case insensitive on input. Some common alternative formats can be enforced using the format parameter.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: str | Unset DEFAULT: UNSET
format	Enforce a specific UUID format. The following formats are supported: simple: 32 hexadecimal digits with no hyphens. This is not a valid UUID format, but is provided for convenience. lowercase: Lowercase hexadecimal digits with hyphens. uppercase: Uppercase hexadecimal digits with hyphens. urn: Lowercase hexadecimal digits with hyphens and a urn:uuid: If not provided, the matcher will accept any lowercase or uppercase. TYPE: Literal['uppercase', 'lowercase', 'urn', 'simple'] | None DEFAULT: None

RETURNS	DESCRIPTION
Matcher[str]	Matcher for UUID strings.

Source code in src/pact/match/__init__.py

def uuid(
    value: builtins.str | Unset = UNSET,
    /,
    *,
    format: Literal["uppercase", "lowercase", "urn", "simple"] | None = None,
) -> Matcher[builtins.str]:
    """
    Match a UUID value.

    This matcher internally combines the [`regex`][pact.match.regex] matcher
    with a UUID regex pattern. See [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122)
    for details about the UUID format.

    While RFC 4122 requires UUIDs to be output as lowercase, UUIDs are case
    insensitive on input. Some common alternative formats can be enforced using
    the `format` parameter.

    Args:
        value:
            Default value to use when generating a consumer test.

        format:
            Enforce a specific UUID format. The following formats are supported:

            -   `simple`: 32 hexadecimal digits with no hyphens. This is _not_ a
                valid UUID format, but is provided for convenience.
            -   `lowercase`: Lowercase hexadecimal digits with hyphens.
            -   `uppercase`: Uppercase hexadecimal digits with hyphens.
            -   `urn`: Lowercase hexadecimal digits with hyphens and a
                `urn:uuid:`

            If not provided, the matcher will accept any lowercase or uppercase.

    Returns:
        Matcher for UUID strings.
    """
    pattern = (
        rf"^{_UUID_FORMATS[format]}$"
        if format
        else rf"^({_UUID_FORMATS['lowercase']}|{_UUID_FORMATS['uppercase']})$"
    )
    if value is UNSET:
        return GenericMatcher(
            "regex",
            generator=generate.uuid(format or "lowercase"),
            regex=pattern,
        )
    return GenericMatcher(
        "regex",
        value=value,
        regex=pattern,
    )