Match

Matching functionality.

This module defines flexible matching rules for use in Pact contracts. These rules specify the expected content of exchanged data, allowing for more robust contract testing than simple equality checks.

For example, a contract may specify how a new record is created via a POST request. The consumer defines the data to send and the expected response. The response may include additional fields from the provider, such as an ID or creation timestamp. The contract can require the ID to match a specific format (e.g., integer or UUID) and the timestamp to be ISO 8601.

Warning

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

# Recommended
from pact import match

match.int(...)

# Not recommended
from pact.match import int

int(...)

Many functions in this module are named after the types they match (e.g., int, str, bool). Importing directly from this module may shadow Python built-in types, so always use the match module.

Matching rules are often combined with generators, which allow Pact to produce values dynamically during contract tests. If a value is not provided, a generator is used; if a value is provided, a generator is not used. This is not advised, as leads to non-deterministic tests.

Note

You do not need to specify everything that will be returned from the provider in a JSON response. Any extra data that is received will be ignored and the tests will still pass, as long as the expected fields match the defined patterns.

For more information about the Pact matching specification, see Matching.

Type Matching

The most common matchers validate that values are of a specific type. These matchers can optionally accept example values:

from pact import match

response = {
    "id": match.int(123),  # Any integer (example: 123)
    "name": match.str("Alice"),  # Any string (example: "Alice")
    "score": match.float(98.5),  # Any float (example: 98.5)
    "active": match.bool(True),  # Any boolean (example: True)
    "tags": match.each_like("admin"),  # Array of strings (example: ["admin"])
}

When no example value is provided, Pact will generate appropriate values automatically, but this is not advised, as it leads to non-deterministic tests.

Regular Expression Matching

For values that must match a specific pattern, use match.regex() with a regular expression:

response = {
    "reference": match.regex("X1234-456def", regex=r"[A-Z]\d{3,6}-[0-9a-f]{6}"),
    "phone": match.regex("+1-555-123-4567", regex=r"\+1-\d{3}-\d{3}-\d{4}"),
}

Note that the regular expression should be provided as a raw string (using the r"..." syntax) to avoid issues with escape sequences. Advanced regex features like lookaheads and lookbehinds should be avoided, as they may not be supported by all Pact implementations.

Complex Objects

For complex nested objects, matchers can be combined to create sophisticated matching rules:

from pact import match

user_response = {
    "id": match.int(123),
    "name": match.str("Alice"),
    "email": match.regex(
        "alice@example.com",
        regex=r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}",
    ),
    "confirmed": match.bool(True),
    "address": {
        "street": match.str("123 Main St"),
        "city": match.str("Anytown"),
        "postal_code": match.regex("12345", regex=r"\d{5}"),
    },
    "roles": match.each_like(match.str("admin")),  # Array of strings
}

The match.type() (or its alias match.like()) function provides generic type matching for any value:

# These are equivalent to the specific type matchers
response = {
    "id": match.type(123),  # Same as match.int(123)
    "name": match.like("Alice"),  # Same as match.str("Alice")
}

Array Matching

For arrays where each element should match a specific pattern, use match.each_like():

from pact import match

# Simple arrays
response = {
    "tags": match.each_like(match.str("admin")),  # Array of strings
    "scores": match.each_like(match.int(95)),  # Array of integers
    "active": match.each_like(match.bool(True)),  # Array of booleans
}

# Complex nested objects in arrays
users_response = {
    "users": match.each_like({
        "id": match.int(123),
        "username": match.regex("alice123", regex=r"[a-zA-Z]+\d*"),
        "roles": match.each_like(match.str("user")),  # Nested array
    })
}

You can also control the minimum and maximum number of array elements:

response = {"items": match.each_like(match.str("item"), min=1, max=10)}

For arrays that must contain specific elements regardless of order, use match.array_containing(). For example, to ensure an array includes certain permissions:

response = {
    "permissions": match.array_containing([
        match.str("read"),
        match.str("write"),
        match.regex("admin-edit", regex=r"admin-\w+"),
    ])
}

Note that additional elements may be present in the array; the matcher only ensures the specified elements are included.

Date and Time Matching

The match module provides specialized matchers for date and time values:

from pact import match
from datetime import date, time, datetime

response = {
    # Date matching (YYYY-MM-DD format by default)
    "birth_date": match.date("2024-07-20"),
    "birth_date_obj": match.date(date(2024, 7, 20)),
    # Time matching (HH:MM:SS format by default)
    "start_time": match.time("14:30:00"),
    "start_time_obj": match.time(time(14, 30, 0)),
    # DateTime matching (ISO 8601 format by default)
    "created_at": match.datetime("2024-07-20T14:30:00+00:00"),
    "updated_at": match.datetime(datetime(2024, 7, 20, 14, 30, 0)),
    # Custom formats using Python strftime patterns
    "custom_date": match.date("07/20/2024", format="%m/%d/%Y"),
    "custom_time": match.time("2:30 PM", format="%I:%M %p"),
}

Specialized Matchers

Other commonly used matchers include:

from pact import match

response = {
    # UUID matching with different formats
    "id": match.uuid("550e8400-e29b-41d4-a716-446655440000"),
    "simple_id": match.uuid(format="simple"),  # No hyphens
    "uppercase_id": match.uuid(format="uppercase"),  # Uppercase letters
    # Number matching with constraints
    "age": match.int(25, min=18, max=99),
    "price": match.float(19.99, precision=2),
    "count": match.number(42),  # Generic number matcher
    # String matching with constraints
    "username": match.str("alice123", size=8),
    "description": match.str(),  # Any string
    # Null values
    "optional_field": match.none(),  # or match.null()
    # String inclusion matching
    "message": match.includes("success"),  # Must contain "success"
}

Advanced Dictionary Matching

For dynamic dictionary structures, you can match keys and values separately:

# Match each key against a pattern
user_permissions = match.each_key_matches(
    {"admin-read": True, "admin-write": False},
    rules=match.regex("admin-read", regex=r"admin-\w+"),
)

# Match each value against a pattern
user_scores = match.each_value_matches(
    {"math": 95, "science": 87}, rules=match.int(85, min=0, max=100)
)

Attributes

Classes

AbstractMatcher

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 integration JSON docs.

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 [integration JSON
    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, refer to the Pact specification and the matchers section

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, refer to the [Pact
    specification](https://github.com/pact-foundation/pact-specification/tree/version-4)
    and the [matchers
    section](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 | AbstractMatcher[_T]]) -> AbstractMatcher[Sequence[_T]]

Match an array containing the given variants.

Each variant must occur at least once. Variants may be matchers or objects.

PARAMETER	DESCRIPTION
variants	List of variants to match against. TYPE: Sequence[_T | AbstractMatcher[_T]]

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

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

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

    Each variant must occur at least once. Variants may be matchers or objects.

    Args:
        variants:
            List of variants to match against.

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

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

Match a boolean value.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: bool | Unset DEFAULT: UNSET

RETURNS	DESCRIPTION
AbstractMatcher[bool]	Matcher for boolean values.

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

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

    Args:
        value:
            Example value for consumer test generation.

    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) -> AbstractMatcher[builtins.bool]

Alias for match.bool.

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

def boolean(value: builtins.bool | Unset = UNSET, /) -> AbstractMatcher[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) -> AbstractMatcher[builtins.str]

Match a date value (string, no time component).

Uses Python's strftime format, converted to Java SimpleDateFormat for Pact compatibility.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: date | str | Unset DEFAULT: UNSET
format	Date format string. Defaults to ISO 8601 (%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
AbstractMatcher[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,
) -> AbstractMatcher[builtins.str]:
    """
    Match a date value (string, no time component).

    Uses Python's
    [strftime](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)
    format, converted to [Java
    `SimpleDateFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)
    for Pact compatibility.

    Args:
        value:
            Example value for consumer test generation.

        format:
            Date format string. Defaults to ISO 8601 (`%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) -> AbstractMatcher[builtins.str]

Match a datetime value (string, date and time).

Uses Python's strftime format, converted to Java SimpleDateFormat for Pact compatibility.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: datetime | str | Unset DEFAULT: UNSET
format	Datetime format string. Defaults to ISO 8601 (%Y-%m-%dT%H:%M:%S%z). TYPE: str | None DEFAULT: None
disable_conversion	If True, disables conversion and expects Java format. Value must be a string. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
AbstractMatcher[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,
) -> AbstractMatcher[builtins.str]:
    """
    Match a datetime value (string, date and time).

    Uses Python's
    [strftime](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)
    format, converted to [Java
    `SimpleDateFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)
    for Pact compatibility.

    Args:
        value:
            Example value for consumer test generation.

        format:
            Datetime format string. Defaults to ISO 8601 (`%Y-%m-%dT%H:%M:%S%z`).

        disable_conversion:
            If True, disables conversion and expects Java format. Value must be
            a string.

    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) -> AbstractMatcher[_NumberT]

Alias for match.float.

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

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

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

Match each key in a dictionary against rules.

PARAMETER	DESCRIPTION
value	Dictionary to match against. TYPE: Mapping[_T, Any]
rules	Matching rules for each key. TYPE: AbstractMatcher[_T] | list[AbstractMatcher[_T]]

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

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

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

    Args:
        value:
            Dictionary to match against.

        rules:
            Matching rules for each key.

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

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

Match each item in an array against a value (can be a matcher).

PARAMETER	DESCRIPTION
value	Value to match against (can be a matcher). TYPE: _T
min	Minimum number of items to match (minimum is always 1). TYPE: int | None DEFAULT: None
max	Maximum number of items to match. TYPE: int | None DEFAULT: None

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

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

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

    Args:
        value:
            Value to match against (can be a matcher).

        min:
            Minimum number of items to match (minimum is always 1).

        max:
            Maximum number of items to match.

    Returns:
        Matcher for arrays where each item matches 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: AbstractMatcher[_T] | list[AbstractMatcher[_T]]) -> AbstractMatcher[Mapping[Matchable, _T]]

Match each value in a dictionary against rules.

PARAMETER	DESCRIPTION
value	Dictionary to match against. TYPE: Mapping[Any, _T]
rules	Matching rules for each value. TYPE: AbstractMatcher[_T] | list[AbstractMatcher[_T]]

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

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

def each_value_matches(
    value: Mapping[Any, _T],
    /,
    *,
    rules: AbstractMatcher[_T] | list[AbstractMatcher[_T]],
) -> AbstractMatcher[Mapping[Matchable, _T]]:
    """
    Match each value in a dictionary against rules.

    Args:
        value:
            Dictionary to match against.

        rules:
            Matching rules for each value.

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

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

Match a floating-point number.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: _NumberT | Unset DEFAULT: UNSET
precision	Number of decimal places to generate. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[_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,
) -> AbstractMatcher[_NumberT]:
    """
    Match a floating-point number.

    Args:
        value:
            Example value for consumer test generation.

        precision:
            Number of decimal places 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: AbstractGenerator | None = None) -> AbstractMatcher[builtins.str]

Match a string that includes a given value.

PARAMETER	DESCRIPTION
value	Value to match against. TYPE: str
generator	Generator to use for value generation. TYPE: AbstractGenerator | None DEFAULT: None

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

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

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

    Args:
        value:
            Value to match against.

        generator:
            Generator to use for value generation.

    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) -> AbstractMatcher[builtins.int]

Match an integer value.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: int | Unset DEFAULT: UNSET
min	Minimum value to generate, if set. TYPE: int | None DEFAULT: None
max	Maximum value to generate, if set. TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[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,
) -> AbstractMatcher[builtins.int]:
    """
    Match an integer value.

    Args:
        value:
            Example value for consumer test generation.

        min:
            Minimum value to generate, if set.

        max:
            Maximum value to generate, if set.

    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) -> AbstractMatcher[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,
) -> AbstractMatcher[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: AbstractGenerator | None = None) -> AbstractMatcher[_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: AbstractGenerator | None = None,
) -> AbstractMatcher[_T]:
    """
    Alias for [`match.type`][pact.match.type].
    """
    return type(value, min=min, max=max, generator=generator)

none() -> AbstractMatcher[None]

Match a null value.

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

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

null() -> AbstractMatcher[None]

Alias for match.none.

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

def null() -> AbstractMatcher[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) -> AbstractMatcher[builtins.int] | AbstractMatcher[builtins.float] | AbstractMatcher[Decimal]

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

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

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

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

Match any number (integer, float, or Decimal).

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: int | float | Decimal | Unset DEFAULT: UNSET
min	Minimum value to generate (for integers). TYPE: int | None DEFAULT: None
max	Maximum value to generate (for integers). TYPE: int | None DEFAULT: None
precision	Number of decimal digits to generate (for floats). TYPE: int | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[int] | AbstractMatcher[float] | AbstractMatcher[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,
) -> (
    AbstractMatcher[builtins.int]
    | AbstractMatcher[builtins.float]
    | AbstractMatcher[Decimal]
):
    """
    Match any number (integer, float, or Decimal).

    Args:
        value:
            Example value for consumer test generation.

        min:
            Minimum value to generate (for integers).

        max:
            Maximum value to generate (for integers).

        precision:
            Number of decimal digits to generate (for floats).

    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) -> AbstractMatcher[builtins.str]

Match a string against a regular expression.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: str | Unset DEFAULT: UNSET
regex	Regular expression pattern to match. TYPE: str | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[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,
) -> AbstractMatcher[builtins.str]:
    """
    Match a string against a regular expression.

    Args:
        value:
            Example value for consumer test generation.

        regex:
            Regular expression pattern to match.

    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: AbstractGenerator | None = None) -> AbstractMatcher[builtins.str]

Match a string value, optionally with a specific length.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: str | Unset DEFAULT: UNSET
size	Length of string to generate for consumer test. TYPE: int | None DEFAULT: None
generator	Alternative generator for consumer test. If set, ignores size. TYPE: AbstractGenerator | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[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: AbstractGenerator | None = None,
) -> AbstractMatcher[builtins.str]:
    """
    Match a string value, optionally with a specific length.

    Args:
        value:
            Example value for consumer test generation.

        size:
            Length of string to generate for consumer test.

        generator:
            Alternative generator for consumer test. If set, ignores `size`.

    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: AbstractGenerator | None = None) -> AbstractMatcher[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: AbstractGenerator | None = None,
) -> AbstractMatcher[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) -> AbstractMatcher[builtins.str]

Match a time value (string, no date component).

Uses Python's strftime format, converted to Java SimpleDateFormat for Pact compatibility.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: time | str | Unset DEFAULT: UNSET
format	Time format string. Defaults to ISO 8601 (%H:%M:%S). TYPE: str | None DEFAULT: None
disable_conversion	If True, disables conversion and expects Java format. Value must be a string. TYPE: bool DEFAULT: False

RETURNS	DESCRIPTION
AbstractMatcher[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,
) -> AbstractMatcher[builtins.str]:
    """
    Match a time value (string, no date component).

    Uses Python's
    [strftime](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)
    format, converted to [Java
    `SimpleDateFormat`](https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html)
    for Pact compatibility.

    Args:
        value:
            Example value for consumer test generation.

        format:
            Time format string. Defaults to ISO 8601 (`%H:%M:%S`).

        disable_conversion:
            If True, disables conversion and expects Java format. Value must be
            a string.

    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) -> AbstractMatcher[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,
) -> AbstractMatcher[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: AbstractGenerator | None = None) -> AbstractMatcher[_T]

Match a value by type (primitive or complex).

PARAMETER	DESCRIPTION
value	Value to match (primitive or complex). TYPE: _T
min	Minimum number of items to match. TYPE: int | None DEFAULT: None
max	Maximum number of items to match. TYPE: int | None DEFAULT: None
generator	Generator to use for value generation. TYPE: AbstractGenerator | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[_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: AbstractGenerator | None = None,
) -> AbstractMatcher[_T]:
    """
    Match a value by type (primitive or complex).

    Args:
        value:
            Value to match (primitive or complex).

        min:
            Minimum number of items to match.

        max:
            Maximum number of items to match.

        generator:
            Generator to use for value generation.

    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: _UUID_FORMAT_NAMES | None = None) -> AbstractMatcher[builtins.str]

Match a UUID value.

See RFC 4122 for details about the UUID format. Some common, albeit non-compliant, alternative formats are also supported.

PARAMETER	DESCRIPTION
value	Example value for consumer test generation. TYPE: str | Unset DEFAULT: UNSET
format	Specify UUID format: simple: 32 hexadecimal digits, no hyphens (not standard, for convenience). lowercase: Lowercase hexadecimal digits with hyphens. uppercase: Uppercase hexadecimal digits with hyphens. urn: Lowercase hexadecimal digits with hyphens and urn:uuid: prefix. If not set, matches any case. TYPE: _UUID_FORMAT_NAMES | None DEFAULT: None

RETURNS	DESCRIPTION
AbstractMatcher[str]	Matcher for UUID strings.

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

def uuid(
    value: builtins.str | Unset = UNSET,
    /,
    *,
    format: _UUID_FORMAT_NAMES | None = None,
) -> AbstractMatcher[builtins.str]:
    """
    Match a UUID value.

    See [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) for details
    about the UUID format. Some common, albeit non-compliant, alternative
    formats are also supported.

    Args:
        value:
            Example value for consumer test generation.

        format:
            Specify UUID format:

            -   `simple`: 32 hexadecimal digits, no hyphens (not standard, for
                convenience).
            -   `lowercase`: Lowercase hexadecimal digits with hyphens.
            -   `uppercase`: Uppercase hexadecimal digits with hyphens.
            -   `urn`: Lowercase hexadecimal digits with hyphens and `urn:uuid:` prefix.

            If not set, matches any case.

    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,
    )