chore: add future deprecation warnings

JP-Ellis · JP-Ellis · commit 9fe9694654e2 · 2023-10-04T08:15:49.000+11:00
As work starts on the next major version of Pact for Python, we need to
start warning users that the current version will be deprecated in the
future.

This commit adds a warning to the top of all modules and standalone
functions that will be deprecated in the next major version. While the
class names themselves might remain, the way they are used may change to
accommodate the changes in the underlying workings, and to accommodate
versions 3 and 4 of the Pact specification.

Once the work on the Pact Python v3 is complete, a thorough migration
guide will be written.

Signed-off-by: JP-Ellis &lt;josh@jpellis.me&gt;
diff --git a/pact/broker.py b/pact/broker.py
@@ -4,6 +4,7 @@
 import fnmatch
 import os
 from subprocess import Popen
+import warnings
 
 from .constants import BROKER_CLIENT_PATH
 
@@ -36,6 +37,12 @@ def __init__(self, broker_base_url=None, broker_username=None, broker_password=N
             the PACT_BROKER_TOKEN environment variable instead.
             Defaults to None.
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.broker_base_url = broker_base_url
         self.broker_username = broker_username
         self.broker_password = broker_password
diff --git a/pact/consumer.py b/pact/consumer.py
@@ -1,4 +1,5 @@
 """Classes and methods to describe contract Consumers."""
+import warnings
 from .pact import Pact
 from .provider import Provider
 
@@ -47,6 +48,12 @@ def __init__(self, name, service_cls=Pact, tags=None,
             Defaults to False.
         :type auto_detect_version_properties: bool
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.name = name
         self.service_cls = service_cls
         self.tags = tags
diff --git a/pact/http_proxy.py b/pact/http_proxy.py
@@ -1,4 +1,5 @@
 """Http Proxy to be used as provider url in verifier."""
+import warnings
 from fastapi import FastAPI, status, Request, HTTPException
 import uvicorn as uvicorn
 import logging
@@ -55,4 +56,10 @@ async def setup(request: Request):
 
 def run_proxy():
     """Rub HTTP Proxy."""
+    warnings.warn(
+        "This class will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     uvicorn.run("pact.http_proxy:app", port=PROXY_PORT, log_level=UVICORN_LOGGING_LEVEL)
diff --git a/pact/matchers.py b/pact/matchers.py
@@ -1,4 +1,5 @@
 """Classes for defining request and response data that is variable."""
+import warnings
 import six
 import datetime
 
@@ -50,6 +51,12 @@ def __init__(self, matcher, minimum=1):
             Must be greater than or equal to 1.
         :type minimum: int
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.matcher = matcher
         assert minimum >= 1, 'Minimum must be greater than or equal to 1'
         self.minimum = minimum
@@ -100,6 +107,12 @@ def __init__(self, matcher):
             ignored.
         :type matcher: None, list, dict, int, float, str, unicode, Matcher
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         valid_types = (
             type(None), list, dict, int, float, six.string_types, Matcher)
 
@@ -158,6 +171,12 @@ def __init__(self, matcher, generate):
             generating the response to the consumer.
         :type generate: basestring
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.matcher = matcher
         self._generate = generate
 
@@ -188,6 +207,12 @@ def from_term(term):
     :return: The JSON representation for this term.
     :rtype: dict, list, str
     """
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     if term is None:
         return term
     elif isinstance(term, (six.string_types, six.binary_type, int, float)):
@@ -211,6 +236,12 @@ def get_generated_values(input):
     :return: The input resolved to its generated value(s)
     :rtype: None, list, dict, int, float, bool, str, unicode, Matcher
     """
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     if input is None:
         return input
     if isinstance(input, (six.string_types, int, float, bool)):
@@ -254,6 +285,12 @@ class Format:
 
     def __init__(self):
         """Create a new Formatter."""
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.identifier = self.integer_or_identifier()
         self.integer = self.integer_or_identifier()
         self.decimal = self.decimal()
diff --git a/pact/message_consumer.py b/pact/message_consumer.py
@@ -1,4 +1,5 @@
 """Classes and methods to describe contract Consumers."""
+import warnings
 from .message_pact import MessagePact
 from .provider import Provider
 
@@ -56,6 +57,12 @@ def __init__(
             Defaults to False.
         :type auto_detect_version_properties: bool
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.name = name
         self.service_cls = service_cls
         self.tags = tags
diff --git a/pact/message_pact.py b/pact/message_pact.py
@@ -4,6 +4,7 @@
 import json
 import os
 from subprocess import Popen
+import warnings
 
 from .broker import Broker
 from .constants import MESSAGE_PATH
@@ -84,6 +85,12 @@ def __init__(
             `merge`.
         :type file_write_mode: str
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(
             broker_base_url, broker_username, broker_password, broker_token
         )
diff --git a/pact/message_provider.py b/pact/message_provider.py
@@ -1,6 +1,7 @@
 """Contract Message Provider."""
 import os
 import time
+import warnings
 
 import requests
 from requests.adapters import HTTPAdapter
@@ -38,6 +39,12 @@ def __init__(
         proxy_port='1234'
     ):
         """Create a Message Provider instance."""
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.message_providers = message_providers
         self.provider = provider
         self.consumer = consumer
diff --git a/pact/pact.py b/pact/pact.py
@@ -4,6 +4,7 @@
 import os
 import platform
 from subprocess import Popen
+import warnings
 
 import psutil
 import requests
@@ -124,6 +125,12 @@ def __init__(
             `overwrite`.
         :type file_write_mode: str
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(
             broker_base_url, broker_username, broker_password, broker_token
         )
diff --git a/pact/provider.py b/pact/provider.py
@@ -1,6 +1,9 @@
 """Classes and methods to describe contract Providers."""
 
 
+import warnings
+
+
 class Provider(object):
     """A Pact provider."""
 
@@ -12,4 +15,10 @@ def __init__(self, name):
             when it is published.
         :type name: str
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.name = name
diff --git a/pact/verifier.py b/pact/verifier.py
@@ -1,5 +1,6 @@
 """Classes and methods to verify Contracts."""
 import json
+import warnings
 
 from pact.verify_wrapper import VerifyWrapper, path_exists, expand_directories
 
@@ -15,6 +16,12 @@ def __init__(self, provider, provider_base_url, **kwargs):
             provider_base_url ([String]): provider url
 
         """
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         self.provider = provider
         self.provider_base_url = provider_base_url
 
diff --git a/pact/verify_wrapper.py b/pact/verify_wrapper.py
@@ -1,5 +1,6 @@
 """Wrapper to verify previously created pacts."""
 
+import warnings
 from pact.constants import VERIFIER_PATH
 import sys
 import os
@@ -12,6 +13,12 @@
 
 def capture_logs(process, verbose):
     """Capture logs from ruby process."""
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     result = ''
     for line in process.stdout:
         result = result + line + '\n'
@@ -31,6 +38,12 @@ def path_exists(path):
     :return: True if the path exists and is a file, otherwise False.
     :rtype: bool
     """
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     if path.startswith('http://') or path.startswith('https://'):
         return True
 
@@ -46,6 +59,12 @@ def sanitize_logs(process, verbose):
     :type verbose: bool
     :rtype: None
     """
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     for line in process.stdout:
         if (not verbose and line.lstrip().startswith('#')
                 and ('vendor/ruby' in line or 'pact-provider-verifier.rb' in line)):
@@ -63,6 +82,12 @@ def expand_directories(paths):
         JSON files in those directories.
     :rtype: list
     """
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     paths_ = []
     for path in paths:
         if path.startswith('http://') or path.startswith('https://'):
@@ -83,6 +108,12 @@ def rerun_command():
 
     :rtype: str
     """
+    warnings.warn(
+        "This function will be deprecated Pact Python v3 "
+        "(see pact-foundation/pact-python#396)",
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
     is_windows = 'windows' in platform.platform().lower()
     command = ''
     if is_windows:
@@ -119,12 +150,26 @@ class PactException(Exception):
 
     def __init__(self, *args, **kwargs):
         """Create wrapper."""
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
         super().__init__(*args, **kwargs)
         self.message = args[0]
 
 class VerifyWrapper(object):
     """A Pact Verifier Wrapper."""
 
+    def __init__(self):
+        warnings.warn(
+            "This class will be deprecated Pact Python v3 "
+            "(see pact-foundation/pact-python#396)",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+
     def _broker_present(self, **kwargs):
         if kwargs.get('broker_url') is None:
             return False
