Deprecated Makefile in favor of StreamReader and StreamWriter.

We replace the `MakeFile` factory function with direct class instantiation.
The `MakeFile` function now emits a `DeprecationWarning` and will be
removed in a future release.

SSL adapters continue to use their own `makefile()` methods which
return SSL-aware file object subclasses.

Author: julianz-

cheroot/connections.py

@@ -1,6 +1,7 @@
 """Utilities to manage open connections."""
 
 import contextlib as _cm
+import io
 import os
 import selectors
 import socket
@@ -11,7 +12,7 @@
 
 from . import errors
 from ._compat import IS_WINDOWS
-from .makefile import MakeFile
+from .makefile import StreamReader, StreamWriter
 
 
 try:
@@ -123,6 +124,15 @@ def _suppress_socket_io_errors(socket, /):
             raise
 
 
+def _make_file_object(sock, mode='r', bufsize=io.DEFAULT_BUFFER_SIZE):
+    """Create a file object from a socket."""
+    return (
+        StreamReader(sock, mode, bufsize)
+        if 'r' in mode
+        else StreamWriter(sock, mode, bufsize)
+    )
+
+
 class ConnectionManager:
     """Class which manages HTTPConnection objects.
 
@@ -304,7 +314,7 @@ def _from_server_socket(self, server_socket):  # noqa: C901  # FIXME
             if hasattr(s, 'settimeout'):
                 s.settimeout(self.server.timeout)
 
-            mf = MakeFile
+            mf = _make_file_object
             ssl_env = {}
             # if ssl cert and key are set, we try to be a secure HTTP server
             if self.server.ssl_adapter is not None:

cheroot/makefile.py

@@ -3,6 +3,7 @@
 # prefer slower Python-based io module
 import _pyio as io
 import socket
+from warnings import warn as _warn
 
 
 # Write only 16K at a time to sockets
@@ -70,6 +71,15 @@ def write(self, val, *args, **kwargs):
 
 
 def MakeFile(sock, mode='r', bufsize=io.DEFAULT_BUFFER_SIZE):
-    """File object attached to a socket object."""
+    """
+    File object attached to a socket object.
+
+    This method is now deprecated: Use StreamReader or StreamWriter directly.
+    """
+    _warn(
+        'MakeFile is deprecated. Use StreamReader or StreamWriter directly.',
+        DeprecationWarning,
+        stacklevel=2,
+    )
     cls = StreamReader if 'r' in mode else StreamWriter
     return cls(sock, mode, bufsize)

cheroot/test/test_makefile.py

@@ -1,5 +1,7 @@
 """Tests for :py:mod:`cheroot.makefile`."""
 
+import pytest
+
 from cheroot import makefile
 
 
@@ -39,7 +41,7 @@ def test_bytes_read():
     """Reader should capture bytes read."""
     sock = MockSocket()
     sock.messages.append(b'foo')
-    rfile = makefile.MakeFile(sock, 'r')
+    rfile = makefile.StreamReader(sock, 'r')
     rfile.read()
     assert rfile.bytes_read == 3
 
@@ -48,6 +50,21 @@ def test_bytes_written():
     """Writer should capture bytes written."""
     sock = MockSocket()
     sock.messages.append(b'foo')
-    wfile = makefile.MakeFile(sock, 'w')
+    wfile = makefile.StreamWriter(sock, 'w')
     wfile.write(b'bar')
     assert wfile.bytes_written == 3
+
+
+def test_makefile_deprecated():
+    """MakeFile function should emit a deprecation warning."""
+    sock = MockSocket()
+    sock.messages.append(b'foo')
+
+    with pytest.warns(
+        DeprecationWarning,
+        match='Use StreamReader or StreamWriter directly',
+    ) as warning_info:
+        makefile.MakeFile(sock, 'r')
+
+    assert len(warning_info) == 1
+    assert 'MakeFile is deprecated' in str(warning_info[0].message)

docs/changelog-fragments.d/805.deprecation.rst

@@ -0,0 +1,9 @@
+Deprecated :py:meth:`~cheroot.makefile.MakeFile` in favor of py:meth:`~cheroot.makefile.StreamReader`
+and :py:meth:`~cheroot.makefile.StreamWriter`.
+
+We replace the MakeFile factory function with direct class instantiation.
+The MakeFile function now emits a DeprecationWarning and will be
+removed in a future release.
+
+SSL adapters continue to use their own makefile() methods which
+return SSL-aware file object subclasses.