chore!: rename abstract generator

Make clear it is abstract by naming it `AbstractGenerator`.

BREAKING CHANGE: The abstract `pact.generate.Generator` class has been
    renamed to `pact.generate.AbstractGenerator`.

Signed-off-by: JP-Ellis <[email protected]>

Author: JP-Ellis

src/pact/generate/__init__.py

@@ -93,7 +93,7 @@
 
 from pact._util import strftime_to_simple_date_format
 from pact.generate.generator import (
-    Generator,
+    AbstractGenerator,
     GenericGenerator,
 )
 
@@ -116,7 +116,7 @@
 #
 # <https://github.com/pact-foundation/pact-reference/blob/303073c/rust/pact_models/src/generators/mod.rs#L121>
 __all__ = [
-    "Generator",
+    "AbstractGenerator",
     "bool",
     "boolean",
     "date",
@@ -172,7 +172,7 @@ def int(
     *,
     min: builtins.int | None = None,
     max: builtins.int | None = None,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Generate a random integer.
 
@@ -198,7 +198,7 @@ def integer(
     *,
     min: builtins.int | None = None,
     max: builtins.int | None = None,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Alias for [`generate.int`][pact.generate.int].
 
@@ -215,7 +215,7 @@ def integer(
     return int(min=min, max=max)
 
 
-def float(precision: builtins.int | None = None) -> Generator:
+def float(precision: builtins.int | None = None) -> AbstractGenerator:
     """
     Generate a random decimal number.
 
@@ -235,7 +235,7 @@ def float(precision: builtins.int | None = None) -> Generator:
     return GenericGenerator("RandomDecimal", extra_fields=params)
 
 
-def decimal(precision: builtins.int | None = None) -> Generator:
+def decimal(precision: builtins.int | None = None) -> AbstractGenerator:
     """
     Alias for [`generate.float`][pact.generate.float].
 
@@ -249,7 +249,7 @@ def decimal(precision: builtins.int | None = None) -> Generator:
     return float(precision=precision)
 
 
-def hex(digits: builtins.int | None = None) -> Generator:
+def hex(digits: builtins.int | None = None) -> AbstractGenerator:
     """
     Generate a random hexadecimal value.
 
@@ -266,7 +266,7 @@ def hex(digits: builtins.int | None = None) -> Generator:
     return GenericGenerator("RandomHexadecimal", extra_fields=params)
 
 
-def hexadecimal(digits: builtins.int | None = None) -> Generator:
+def hexadecimal(digits: builtins.int | None = None) -> AbstractGenerator:
     """
     Alias for [`generate.hex`][pact.generate.hex].
 
@@ -280,7 +280,7 @@ def hexadecimal(digits: builtins.int | None = None) -> Generator:
     return hex(digits=digits)
 
 
-def str(size: builtins.int | None = None) -> Generator:
+def str(size: builtins.int | None = None) -> AbstractGenerator:
     """
     Generate a random string.
 
@@ -297,7 +297,7 @@ def str(size: builtins.int | None = None) -> Generator:
     return GenericGenerator("RandomString", extra_fields=params)
 
 
-def string(size: builtins.int | None = None) -> Generator:
+def string(size: builtins.int | None = None) -> AbstractGenerator:
     """
     Alias for [`generate.str`][pact.generate.str].
 
@@ -311,7 +311,7 @@ def string(size: builtins.int | None = None) -> Generator:
     return str(size=size)
 
 
-def regex(regex: builtins.str) -> Generator:
+def regex(regex: builtins.str) -> AbstractGenerator:
     """
     Generate a string matching a regex pattern.
 
@@ -336,7 +336,7 @@ def regex(regex: builtins.str) -> Generator:
 
 def uuid(
     format: _UUID_FORMAT_NAMES = "lowercase",
-) -> Generator:
+) -> AbstractGenerator:
     """
     Generate a UUID.
 
@@ -354,7 +354,7 @@ def date(
     format: builtins.str = "%Y-%m-%d",
     *,
     disable_conversion: builtins.bool = False,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Generate a date value.
 
@@ -384,7 +384,7 @@ def time(
     format: builtins.str = "%H:%M:%S",
     *,
     disable_conversion: builtins.bool = False,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Generate a time value.
 
@@ -413,7 +413,7 @@ def datetime(
     format: builtins.str,
     *,
     disable_conversion: builtins.bool = False,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Generate a datetime value.
 
@@ -444,7 +444,7 @@ def timestamp(
     format: builtins.str,
     *,
     disable_conversion: builtins.bool = False,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Alias for [`generate.datetime`][pact.generate.datetime].
 
@@ -454,7 +454,7 @@ def timestamp(
     return datetime(format=format, disable_conversion=disable_conversion)
 
 
-def bool() -> Generator:
+def bool() -> AbstractGenerator:
     """
     Generate a random boolean value.
 
@@ -464,7 +464,7 @@ def bool() -> Generator:
     return GenericGenerator("RandomBoolean")
 
 
-def boolean() -> Generator:
+def boolean() -> AbstractGenerator:
     """
     Alias for [`generate.bool`][pact.generate.bool].
 
@@ -474,7 +474,7 @@ def boolean() -> Generator:
     return bool()
 
 
-def provider_state(expression: builtins.str | None = None) -> Generator:
+def provider_state(expression: builtins.str | None = None) -> AbstractGenerator:
     """
     Generate a value from provider state context.
 
@@ -494,7 +494,7 @@ def provider_state(expression: builtins.str | None = None) -> Generator:
 def mock_server_url(
     regex: builtins.str | None = None,
     example: builtins.str | None = None,
-) -> Generator:
+) -> AbstractGenerator:
     """
     Generate a mock server URL.
 

src/pact/generate/generator.py

@@ -14,7 +14,7 @@
     from pact.types import GeneratorType
 
 
-class Generator(ABC):
+class AbstractGenerator(ABC):
     """
     Abstract generator.
 
@@ -34,17 +34,11 @@ class Generator(ABC):
     @abstractmethod
     def to_integration_json(self) -> dict[str, Any]:
         """
-        Convert the matcher to an integration JSON object.
+        Convert the generator 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.
+        See
+        [`AbstractGenerator.to_integration_json`][pact.generate.generator.AbstractGenerator.to_integration_json]
+        for more information.
         """
 
     @abstractmethod
@@ -55,20 +49,17 @@ def to_generator_json(self) -> dict[str, Any]:
         This method is used internally to convert the generator 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://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
+        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 generator as a generator JSON object.
         """
 
 
-class GenericGenerator(Generator):
+class GenericGenerator(AbstractGenerator):
     """
     Generic generator.
 
@@ -108,17 +99,11 @@ def __init__(
 
     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:
+        Convert the generator to an integration JSON object.
 
-        > https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson
-
-        Returns:
-            The matcher as an integration JSON object.
+        See
+        [`AbstractGenerator.to_integration_json`][pact.generate.generator.AbstractGenerator.to_integration_json]
+        for more information.
         """
         return {
             "pact:generator:type": self.type,
@@ -129,19 +114,9 @@ def to_generator_json(self) -> dict[str, Any]:
         """
         Convert the generator to a generator JSON object.
 
-        This method is used internally to convert the generator 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://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 generator as a generator JSON object.
+        See
+        [`AbstractGenerator.to_generator_json`][pact.generate.generator.AbstractGenerator.to_generator_json]
+        for more information.
         """
         return {
             "type": self.type,

src/pact/match/__init__.py

@@ -261,7 +261,7 @@
     from collections.abc import Mapping, Sequence
     from types import ModuleType
 
-    from pact.generate import Generator
+    from pact.generate import AbstractGenerator
 
 # ruff: noqa: A001
 #       We provide a more 'Pythonic' interface by matching the names of the
@@ -541,7 +541,7 @@ def str(
     /,
     *,
     size: builtins.int | None = None,
-    generator: Generator | None = None,
+    generator: AbstractGenerator | None = None,
 ) -> AbstractMatcher[builtins.str]:
     """
     Match a string value, optionally with a specific length.
@@ -587,7 +587,7 @@ def string(
     /,
     *,
     size: builtins.int | None = None,
-    generator: Generator | None = None,
+    generator: AbstractGenerator | None = None,
 ) -> AbstractMatcher[builtins.str]:
     """
     Alias for [`match.str`][pact.match.str].
@@ -938,7 +938,7 @@ def type(
     *,
     min: builtins.int | None = None,
     max: builtins.int | None = None,
-    generator: Generator | None = None,
+    generator: AbstractGenerator | None = None,
 ) -> AbstractMatcher[_T]:
     """
     Match a value by type (primitive or complex).
@@ -973,7 +973,7 @@ def like(
     *,
     min: builtins.int | None = None,
     max: builtins.int | None = None,
-    generator: Generator | None = None,
+    generator: AbstractGenerator | None = None,
 ) -> AbstractMatcher[_T]:
     """
     Alias for [`match.type`][pact.match.type].
@@ -1016,7 +1016,7 @@ def includes(
     value: builtins.str,
     /,
     *,
-    generator: Generator | None = None,
+    generator: AbstractGenerator | None = None,
 ) -> AbstractMatcher[builtins.str]:
     """
     Match a string that includes a given value.

src/pact/match/matcher.py

@@ -15,7 +15,7 @@
 from json import JSONEncoder
 from typing import Any, Generic, TypeVar
 
-from pact.generate.generator import Generator
+from pact.generate.generator import AbstractGenerator
 from pact.types import UNSET, Matchable, MatcherType, Unset
 
 _T_co = TypeVar("_T_co", covariant=True)
@@ -85,7 +85,7 @@ def __init__(
         type: MatcherType,  # noqa: A002
         /,
         value: _T_co | Unset = UNSET,
-        generator: Generator | None = None,
+        generator: AbstractGenerator | None = None,
         extra_fields: Mapping[str, Any] | None = None,
         **kwargs: Matchable,
     ) -> None:
@@ -359,6 +359,6 @@ def default(self, o: Any) -> Any:  # noqa: ANN401
         """
         if isinstance(o, AbstractMatcher):
             return o.to_integration_json()
-        if isinstance(o, Generator):
+        if isinstance(o, AbstractGenerator):
             return o.to_integration_json()
         return super().default(o)