Deprecate extract_ids

CHANGELOG.md

@@ -24,7 +24,8 @@ If breaking changes are needed do be done, they are:
 
 ### Deprecations
 
-*none*
+- If you've used `service_identity.(cryptography|pyopenssl).extract_ids()`, please switch to the new names `extract_patterns()`.
+  [#56](https://github.com/pyca/service-identity/pull/56)
 
 
 ### Changes

src/service_identity/cryptography.py

@@ -4,6 +4,8 @@
 
 from __future__ import annotations
 
+import warnings
+
 from cryptography.x509 import (
     Certificate,
     DNSName,
@@ -143,7 +145,15 @@ def extract_patterns(cert: Certificate) -> list[CertificatePattern]:
     return ids
 
 
-extract_ids = extract_patterns
-"""
-Deprecated and never public API.  Use :func:`extract_patterns` instead.
-"""
+def extract_ids(cert: Certificate) -> list[CertificatePattern]:
+    """
+    Deprecated and never public API.  Use :func:`extract_patterns` instead.
+
+    .. deprecated:: 23.1.0
+    """
+    warnings.warn(
+        category=DeprecationWarning,
+        message="`extract_ids()` is deprecated, please use `extract_patterns()`.",
+        stacklevel=2,
+    )
+    return extract_patterns(cert)

src/service_identity/pyopenssl.py

@@ -4,6 +4,8 @@
 
 from __future__ import annotations
 
+import warnings
+
 from pyasn1.codec.der.decoder import decode
 from pyasn1.type.char import IA5String
 from pyasn1.type.univ import ObjectIdentifier
@@ -130,3 +132,17 @@ def extract_patterns(cert: SSL.X509) -> list[CertificatePattern]:
                     pass
 
     return ids
+
+
+def extract_ids(cert: SSL.X509) -> list[CertificatePattern]:
+    """
+    Deprecated and never public API.  Use :func:`extract_patterns` instead.
+
+    .. deprecated:: 23.1.0
+    """
+    warnings.warn(
+        category=DeprecationWarning,
+        message="`extract_ids()` is deprecated, please use `extract_patterns()`.",
+        stacklevel=2,
+    )
+    return extract_patterns(cert)

tests/test_cryptography.py

@@ -13,6 +13,7 @@
     URIPattern,
 )
 from service_identity.cryptography import (
+    extract_ids,
     extract_patterns,
     verify_certificate_hostname,
     verify_certificate_ip_address,
@@ -74,7 +75,7 @@ def test_verify_ip_address_fail(self, ip):
         ] == ei.value.errors
 
 
-class TestExtractIDs:
+class TestExtractPatterns:
     def test_dns(self):
         """
         Returns the correct DNSPattern from a certificate.
@@ -118,3 +119,18 @@ def test_ip(self):
             IPAddressPattern(pattern=ipaddress.IPv4Address("2.2.2.2")),
             IPAddressPattern(pattern=ipaddress.IPv6Address("2a00:1c38::53")),
         ] == rv
+
+    def test_extract_ids_deprecated(self):
+        """
+        `extract_ids` raises a DeprecationWarning with correct stacklevel.
+        """
+        with pytest.deprecated_call() as wr:
+            extract_ids(CERT_EVERYTHING)
+
+        w = wr.pop()
+
+        assert (
+            "`extract_ids()` is deprecated, please use `extract_patterns()`."
+            == w.message.args[0]
+        )
+        assert __file__ == w.filename

tests/test_pyopenssl.py

@@ -15,6 +15,7 @@
     VerificationError,
 )
 from service_identity.pyopenssl import (
+    extract_ids,
     extract_patterns,
     verify_hostname,
     verify_ip_address,
@@ -94,7 +95,7 @@ def get_peer_certificate(self):
         ] == ei.value.errors
 
 
-class TestExtractIDs:
+class TestExtractPatterns:
     def test_dns(self):
         """
         Returns the correct DNSPattern from a certificate.
@@ -138,3 +139,18 @@ def test_ip(self):
             IPAddressPattern(pattern=ipaddress.IPv4Address("2.2.2.2")),
             IPAddressPattern(pattern=ipaddress.IPv6Address("2a00:1c38::53")),
         ] == rv
+
+    def test_extract_ids_deprecated(self):
+        """
+        `extract_ids` raises a DeprecationWarning with correct stacklevel.
+        """
+        with pytest.deprecated_call() as wr:
+            extract_ids(CERT_EVERYTHING)
+
+        w = wr.pop()
+
+        assert (
+            "`extract_ids()` is deprecated, please use `extract_patterns()`."
+            == w.message.args[0]
+        )
+        assert __file__ == w.filename

tox.ini

@@ -1,3 +1,11 @@
+[flake8]
+ignore =
+    # we rely on Black for line length enforcement.
+    E501
+    # conflict flake8 vs Black
+    W503
+
+
 [tox]
 min_version = 4
 env_list =