Deprecate instead of remove renamed parameters (#107)

In #94 and #102, we renamed several method parameters. This brings back the old names, but with deprecation warnings. We'll remove them fully in v0.5.0. This does *not* support parameters that were completely *removed*, though.

Author: Mr0grog

docs/source/release-history.rst

@@ -10,21 +10,21 @@ Breaking Changes
 
 This release includes a significant overhaul of parameters for :meth:`wayback.WaybackClient.search`.
 
-- The ``limit`` parameter now has a default value. There are very few cases where you should not set a ``limit`` (not doing so will typically break pagination), and there is now a default value to help prevent mistakes. We’ve also added documentation to explain how and when to adjust this value, since it is pretty complex. (:issue:`65`)
-
 - Removed parameters that did nothing, could break search, or that were for internal use only: ``gzip``, ``showResumeKey``, ``resumeKey``, ``page``, ``pageSize``, ``previous_result``.
 
 - Removed support for extra, arbitrary keyword parameters that could be added to each request to the search API.
 
-- All parameters now use snake_case. (Previously, parameters that were passed unchanged to the HTTP API used camelCase, while others used snake_case.)
+- All parameters now use snake_case. (Previously, parameters that were passed unchanged to the HTTP API used camelCase, while others used snake_case.) The old, non-snake-case names are deprecated, but still work. They’ll be completely removed in v0.5.0.
 
   - ``matchType`` → ``match_type``
   - ``fastLatest`` → ``fast_latest``
   - ``resolveRevisits`` → ``resolve_revisits``
 
+- The ``limit`` parameter now has a default value. There are very few cases where you should not set a ``limit`` (not doing so will typically break pagination), and there is now a default value to help prevent mistakes. We’ve also added documentation to explain how and when to adjust this value, since it is pretty complex. (:issue:`65`)
+
 - Expanded the method documentation to explain things in more depth and link to more external references.
 
-While we were at it, we renamed the ``datetime`` parameter of :meth:`wayback.WaybackClient.get_memento` to ``timestamp`` for consistency with :class:`wayback.CdxRecord` and :class:`wayback.Memento`.
+While we were at it, we also renamed the ``datetime`` parameter of :meth:`wayback.WaybackClient.get_memento` to ``timestamp`` for consistency with :class:`wayback.CdxRecord` and :class:`wayback.Memento`. The old name still works for now, but it will be fully removed in v0.5.0.
 
 
 Features

wayback/_client.py

@@ -31,6 +31,7 @@
 from urllib3.exceptions import (ConnectTimeoutError,
                                 MaxRetryError,
                                 ReadTimeoutError)
+from warnings import warn
 from . import _utils, __version__
 from ._models import CdxRecord, Memento
 from .exceptions import (WaybackException,
@@ -369,7 +370,9 @@ def close(self):
     def search(self, url, *, match_type=None, limit=1000, offset=None,
                fast_latest=None, from_date=None, to_date=None,
                filter_field=None, collapse=None, resolve_revisits=True,
-               skip_malformed_results=True):
+               skip_malformed_results=True,
+               # Deprecated Parameters
+               matchType=None, fastLatest=None, resolveRevisits=None):
         """
         Search archive.org's CDX API for all captures of a given URL. This
         returns an iterator of :class:`CdxRecord` objects. The `StopIteration`
@@ -510,6 +513,27 @@ def search(self, url, *, match_type=None, limit=1000, offset=None,
         pagination because they work differently from the `resumeKey` method
         this uses, and results do not include recent captures when using them.
         """
+        if matchType is not None:
+            warn('The `matchType` parameter for search() was renamed to '
+                 '`match_type`. Support for the old name will be removed in '
+                 'wayback v0.5.0; please update your code.',
+                 DeprecationWarning,
+                 stacklevel=2)
+            match_type = match_type or matchType
+        if fastLatest is not None:
+            warn('The `fastLatest` parameter for search() was renamed to '
+                 '`fast_latest`. Support for the old name will be removed in '
+                 'wayback v0.5.0; please update your code.',
+                 DeprecationWarning,
+                 stacklevel=2)
+            fast_latest = fast_latest or fastLatest
+        if resolveRevisits is not None:
+            warn('The `resolveRevisits` parameter for search() was renamed to '
+                 '`resolve_revisits`. Support for the old name will be removed '
+                 'in wayback v0.5.0; please update your code.',
+                 DeprecationWarning,
+                 stacklevel=2)
+            resolve_revisits = resolve_revisits or resolveRevisits
 
         # TODO: support args that can be set multiple times: filter, collapse
         # Should take input as a sequence and convert to repeat query args
@@ -619,7 +643,9 @@ def search(self, url, *, match_type=None, limit=1000, offset=None,
 
     def get_memento(self, url, timestamp=None, mode=Mode.original, *,
                     exact=True, exact_redirects=None,
-                    target_window=24 * 60 * 60, follow_redirects=True):
+                    target_window=24 * 60 * 60, follow_redirects=True,
+                    # Deprecated Parameters
+                    datetime=None):
         """
         Fetch a memento (an archived HTTP response) from the Wayback Machine.
 
@@ -690,6 +716,14 @@ def get_memento(self, url, timestamp=None, mode=Mode.original, *,
             A :class:`Memento` object with information about the archived HTTP
             response.
         """
+        if datetime:
+            warn('The `datetime` parameter for get_memento() was renamed to '
+                 '`timestamp`. Support for the old name will be removed '
+                 'in wayback v0.5.0; please update your code.',
+                 DeprecationWarning,
+                 stacklevel=2)
+            timestamp = timestamp or datetime
+
         if exact_redirects is None:
             exact_redirects = exact