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.v3 import match

match.int(...)

# Bad
from pact.v3.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]

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/v3/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/v3/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]]

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.
    """
    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/v3/match/__init__.py

def boolean(value: builtins.bool | Unset = UNSET, /) -> Matcher[builtins.bool]:
    """
    Alias for [`match.bool`][pact.v3.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.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: date | str | Unset DEFAULT: UNSET
format	Expected format of the date. This uses Python's strftime format Pact internally uses the Java SimpleDateFormat and the conversion from Python's strftime format to Java's SimpleDateFormat format is done in strftime_to_simple_date_format. 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

Source code in src/pact/v3/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.

    Args:
        value:
            Default value to use when generating a consumer test.
        format:
            Expected format of the date. This uses Python's [`strftime`
            format](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)

            Pact internally uses the [Java
            SimpleDateFormat](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)
            and the conversion from Python's `strftime` format to Java's
            `SimpleDateFormat` format is done in
            [`strftime_to_simple_date_format`][pact.v3.util.strftime_to_simple_date_format].

            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.
    """
    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.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: datetime | str | Unset DEFAULT: UNSET
format	Expected format of the timestamp. This uses Python's strftime format Pact internally uses the Java SimpleDateFormat and the conversion from Python's strftime format to Java's SimpleDateFormat format is done in strftime_to_simple_date_format. 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

Source code in src/pact/v3/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.

    Args:
        value:
            Default value to use when generating a consumer test.
        format:
            Expected format of the timestamp. This uses Python's [`strftime`
            format](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)

            Pact internally uses the [Java
            SimpleDateFormat](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)
            and the conversion from Python's `strftime` format to Java's
            `SimpleDateFormat` format is done in
            [`strftime_to_simple_date_format`][pact.v3.util.strftime_to_simple_date_format].

            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.
    """
    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.%f%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/v3/match/__init__.py

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

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.
    """
    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]]

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.
    """
    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/v3/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.v3.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/v3/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.v3.match.type].
    """
    return type(value, min=min, max=max, generator=generator)

none() -> Matcher[None]

Match a null value.

Source code in src/pact/v3/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/v3/match/__init__.py

def null() -> Matcher[None]:
    """
    Alias for [`match.none`][pact.v3.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. Defaults to None. TYPE: int | None DEFAULT: None
max	The maximum value of the number to generate. Only used when value is an integer. Defaults to None. TYPE: int | None DEFAULT: None
precision	The number of decimal digits to generate. Only used when value is a float. Defaults to None. TYPE: int | None DEFAULT: None

Source code in src/pact/v3/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.v3.match.integer]
    and [`decimal`][pact.v3.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. Defaults to None.
        max:
            The maximum value of the number to generate. Only used when value is
            an integer. Defaults to None.
        precision:
            The number of decimal digits to generate. Only used when value is a
            float. Defaults to None.
    """
    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

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.
    """
    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/v3/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.v3.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.

PARAMETER	DESCRIPTION
value	Default value to use when generating a consumer test. TYPE: time | str | Unset DEFAULT: UNSET
format	Expected format of the time. This uses Python's strftime format Pact internally uses the Java SimpleDateFormat and the conversion from Python's strftime format to Java's SimpleDateFormat format is done in strftime_to_simple_date_format. 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

Source code in src/pact/v3/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.

    Args:
        value:
            Default value to use when generating a consumer test.
        format:
            Expected format of the time. This uses Python's [`strftime`
            format](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes)

            Pact internally uses the [Java
            SimpleDateFormat](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)
            and the conversion from Python's `strftime` format to Java's
            `SimpleDateFormat` format is done in
            [`strftime_to_simple_date_format`][pact.v3.util.strftime_to_simple_date_format].

            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.
    """
    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/v3/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.v3.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

Source code in src/pact/v3/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.
    """
    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

Source code in src/pact/v3/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.v3.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.
    """
    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,
    )