From 4d447866b4376bc567acd7a9b7c29300b23605e3 Mon Sep 17 00:00:00 2001
From: Ben Finney <ben+python@benfinney.id.au>
Date: Feb 19 2022 01:12:00 +0000
Subject: Deprecate helper function `is_socket`.


The function incorrectly causes `ValueError` when the file object is already
closed. Migrate to the new `is_socket_file` helper function instead.

---

diff --git a/ChangeLog b/ChangeLog
index e96fd9a..d75109d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -30,6 +30,11 @@ Changed:
 
   Closes: Pagure #62. Thanks to Miro Hrončok for the report.
 
+* Deprecate helper function `is_socket`.
+
+  The function incorrectly causes `ValueError` when the file object is already
+  closed. Migrate to the new `is_socket_file` helper function instead.
+
 Removed:
 
 * Drop backward-compatible helpers that provided Python 2 support.
diff --git a/daemon/daemon.py b/daemon/daemon.py
index 44c7077..ea6c671 100644
--- a/daemon/daemon.py
+++ b/daemon/daemon.py
@@ -15,6 +15,7 @@ import resource
 import signal
 import socket
 import sys
+import warnings
 
 
 class DaemonError(Exception):
@@ -720,6 +721,9 @@ def is_socket(fd):
         Query the socket type of `fd`. If there is no error, the file is a
         socket.
         """
+    warnings.warn(
+            DeprecationWarning("migrate to `is_socket_file` instead"))
+
     result = False
 
     try:
diff --git a/test/test_daemon.py b/test/test_daemon.py
index 7ee3a35..ff7a0e8 100644
--- a/test/test_daemon.py
+++ b/test/test_daemon.py
@@ -21,6 +21,7 @@ import sys
 import tempfile
 from types import ModuleType
 import unittest.mock
+import warnings
 
 from . import scaffold
 from .test_pidfile import (
@@ -1860,7 +1861,7 @@ class is_process_started_by_init_TestCase(scaffold.TestCase):
 
 
 class is_socket_TestCase(scaffold.TestCase):
-    """ Test cases for is_socket function. """
+    """ Test cases for `is_socket` function. """
 
     def setUp(self):
         """ Set up test fixtures. """
@@ -1890,6 +1891,17 @@ class is_socket_TestCase(scaffold.TestCase):
         func_patcher_socket_fromfd.start()
         self.addCleanup(func_patcher_socket_fromfd.stop)
 
+        warnings_catcher = warnings.catch_warnings(record=True)
+        self.caught_warnings = warnings_catcher.__enter__()
+        self.addCleanup(warnings_catcher.__exit__)
+
+    def test_issues_deprecation_warning(self):
+        """ Should issue a `DeprecationWarning`. """
+        self.assertWarns(
+                DeprecationWarning,
+                daemon.daemon.is_socket,
+                self.getUniqueInteger())
+
     def test_returns_false_by_default(self):
         """ Should return False under normal circumstances. """
         test_fd = 23