gh-94984: Add mode parameter to asyncio create_unix_server() (#155086)

https://github.com/python/cpython/commit/1617cbe1dc16db302d708c321b7b0a1579a382c9
commit: 1617cbe1dc16db302d708c321b7b0a1579a382c9
branch: main
author: Sam Bull <[email protected]>
committer: kumaraditya303 <[email protected]>
date: 2026-08-03T21:12:16+05:30
summary:

gh-94984: Add mode parameter to asyncio create_unix_server() (#155086)

files:
A Misc/NEWS.d/next/Library/2026-07-27-12-00-00.gh-issue-94984.Xr3vFq.rst
M Doc/library/asyncio-eventloop.rst
M Doc/library/asyncio-stream.rst
M Doc/whatsnew/3.16.rst
M Lib/asyncio/events.py
M Lib/asyncio/unix_events.py
M Lib/test/test_asyncio/test_unix_events.py

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index d24c8420ef8920..41abb2d7d0a53e 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -838,7 +838,7 @@ Creating network servers
                  *, sock=None, backlog=100, ssl=None, \
                  ssl_handshake_timeout=None, \
                  ssl_shutdown_timeout=None, \
-                 start_serving=True, cleanup_socket=True)
+                 start_serving=True, cleanup_socket=True, mode=None)
    :async:
 
    Similar to :meth:`loop.create_server` but works with the
@@ -853,6 +853,13 @@ Creating network servers
    be removed from the filesystem when the server is closed, unless the
    socket has been replaced after the server has been created.
 
+   If *mode* is not ``None``, the permissions of the socket file created
+   for *path* are changed to *mode* (as accepted by :func:`os.chmod`)
+   right after binding, before the server starts accepting connections,
+   so a connection can never be accepted while the default,
+   umask-derived permissions are still in effect.  *mode* cannot be
+   combined with *sock* and is not supported for abstract Unix sockets.
+
    See the documentation of the :meth:`loop.create_server` method
    for information about arguments to this method.
 
@@ -871,6 +878,10 @@ Creating network servers
 
       Added the *cleanup_socket* parameter.
 
+   .. versionchanged:: 3.16
+
+      Added the *mode* parameter.
+
 
 .. method:: loop.connect_accepted_socket(protocol_factory, \
                sock, *, ssl=None, ssl_handshake_timeout=None, \
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 05445219510ca5..4092f440f66ad3 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -171,7 +171,8 @@ and work with streams:
 .. function:: start_unix_server(client_connected_cb, path=None, \
                  *, limit=None, sock=None, backlog=100, ssl=None, \
                  ssl_handshake_timeout=None, \
-                 ssl_shutdown_timeout=None, start_serving=True, cleanup_socket=True)
+                 ssl_shutdown_timeout=None, start_serving=True, \
+                 cleanup_socket=True, mode=None)
    :async:
 
    Start a Unix socket server.
@@ -182,6 +183,9 @@ and work with streams:
    be removed from the filesystem when the server is closed, unless the
    socket has been replaced after the server has been created.
 
+   If *mode* is not ``None``, the permissions of the Unix socket file
+   are set to *mode* before the server starts accepting connections.
+
    See also the documentation of :meth:`loop.create_unix_server`.
 
    .. note::
@@ -205,6 +209,9 @@ and work with streams:
    .. versionchanged:: 3.13
       Added the *cleanup_socket* parameter.
 
+   .. versionchanged:: 3.16
+      Added the *mode* parameter.
+
 
 StreamReader
 ============
diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst
index 6e69737768d5e1..c607e3c620572f 100644
--- a/Doc/whatsnew/3.16.rst
+++ b/Doc/whatsnew/3.16.rst
@@ -95,6 +95,15 @@ New modules
 Improved modules
 ================
 
+asyncio
+-------
+
+* Add the *mode* parameter to :meth:`asyncio.loop.create_unix_server` and
+  :func:`asyncio.start_unix_server` to set the permissions of the Unix
+  socket file created for *path*.
+  (Contributed by Sam Bull in :gh:`94984`.)
+
+
 codecs
 ------
 
diff --git a/Lib/asyncio/events.py b/Lib/asyncio/events.py
index 807c70bc775aa2..6b2d34e733a6b1 100644
--- a/Lib/asyncio/events.py
+++ b/Lib/asyncio/events.py
@@ -451,7 +451,7 @@ async def create_unix_server(
             sock=None, backlog=100, ssl=None,
             ssl_handshake_timeout=None,
             ssl_shutdown_timeout=None,
-            start_serving=True):
+            start_serving=True, mode=None):
         """A coroutine which creates a UNIX Domain Socket server.
 
         The return value is a Server object, which can be used to stop
@@ -480,6 +480,10 @@ async def create_unix_server(
         the user should await Server.start_serving() or
         Server.serve_forever() to make the server to start accepting
         connections.
+
+        mode, if not None, is applied to the socket file created for
+        path with os.chmod() after binding and before the server
+        starts accepting connections.
         """
         raise NotImplementedError
 
diff --git a/Lib/asyncio/unix_events.py b/Lib/asyncio/unix_events.py
index 94c5fb726e5933..3a66cee93da4f5 100644
--- a/Lib/asyncio/unix_events.py
+++ b/Lib/asyncio/unix_events.py
@@ -276,7 +276,7 @@ async def create_unix_server(
             sock=None, backlog=100, ssl=None,
             ssl_handshake_timeout=None,
             ssl_shutdown_timeout=None,
-            start_serving=True, cleanup_socket=True):
+            start_serving=True, cleanup_socket=True, mode=None):
         if isinstance(ssl, bool):
             raise TypeError('ssl argument must be an SSLContext or None')
 
@@ -294,6 +294,9 @@ async def create_unix_server(
                     'path and sock can not be specified at the same time')
 
             path = os.fspath(path)
+            if mode is not None and path and path[0] in (0, '\x00'):
+                raise ValueError(
+                    'mode is not supported for abstract sockets')
             sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
 
             # Check for abstract socket. `str` and `bytes` paths are supported.
@@ -322,11 +325,26 @@ async def create_unix_server(
             except:
                 sock.close()
                 raise
+
+            if mode is not None:
+                # The socket cannot accept connections until listen() is
+                # called, which happens later in Server._start_serving(),
+                # so no connection can be accepted while the socket still
+                # has the default permissions.
+                try:
+                    os.chmod(path, mode)
+                except:
+                    sock.close()
+                    raise
         else:
             if sock is None:
                 raise ValueError(
                     'path was not specified, and no sock specified')
 
+            if mode is not None:
+                raise ValueError(
+                    'mode is only meaningful with path')
+
             if (sock.family != socket.AF_UNIX or
                     sock.type != socket.SOCK_STREAM):
                 raise ValueError(
diff --git a/Lib/test/test_asyncio/test_unix_events.py b/Lib/test/test_asyncio/test_unix_events.py
index e88437eb2337ff..c383a3bff962d7 100644
--- a/Lib/test/test_asyncio/test_unix_events.py
+++ b/Lib/test/test_asyncio/test_unix_events.py
@@ -411,6 +411,57 @@ def test_create_unix_server_bind_error(self, m_socket):
             self.loop.run_until_complete(coro)
         self.assertTrue(sock.close.called)
 
+    @socket_helper.skip_unless_bind_unix_socket
+    def test_create_unix_server_mode(self):
+        # Two distinct modes: whatever the umask, at most one of them
+        # can coincide with the default permissions, so a no-op chmod
+        # cannot pass both subtests.
+        for mode in (0o600, 0o644):
+            with self.subTest(mode=mode):
+                with test_utils.unix_socket_path() as path:
+                    srv = self.loop.run_until_complete(
+                        self.loop.create_unix_server(
+                            lambda: None, path, mode=mode))
+                    try:
+                        self.assertEqual(
+                            stat.S_IMODE(os.stat(path).st_mode), mode)
+                    finally:
+                        srv.close()
+                        self.loop.run_until_complete(srv.wait_closed())
+
+    def test_create_unix_server_mode_sock(self):
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        with sock:
+            coro = self.loop.create_unix_server(lambda: None, path=None,
+                                                sock=sock, mode=0o600)
+            with self.assertRaisesRegex(ValueError,
+                                        'mode is only meaningful with path'):
+                self.loop.run_until_complete(coro)
+
+    def test_create_unix_server_mode_abstract(self):
+        # The check is a pure string test, so it runs on all platforms.
+        for path in ('\x00spam', b'\x00spam'):
+            with self.subTest(path=path):
+                coro = self.loop.create_unix_server(lambda: None, path,
+                                                    mode=0o600)
+                with self.assertRaisesRegex(
+                        ValueError, 'mode is not supported for abstract'):
+                    self.loop.run_until_complete(coro)
+
+    @mock.patch('asyncio.unix_events.socket')
+    def test_create_unix_server_chmod_error(self, m_socket):
+        # Ensure that the socket is closed when os.chmod() fails
+        sock = mock.Mock()
+        m_socket.socket.return_value = sock
+
+        with mock.patch('asyncio.unix_events.os.chmod',
+                        side_effect=PermissionError):
+            coro = self.loop.create_unix_server(lambda: None, path='/test',
+                                                mode=0o600)
+            with self.assertRaises(PermissionError):
+                self.loop.run_until_complete(coro)
+        self.assertTrue(sock.close.called)
+
     def test_create_unix_connection_path_sock(self):
         coro = self.loop.create_unix_connection(
             lambda: None, os.devnull, sock=object())
diff --git a/Misc/NEWS.d/next/Library/2026-07-27-12-00-00.gh-issue-94984.Xr3vFq.rst b/Misc/NEWS.d/next/Library/2026-07-27-12-00-00.gh-issue-94984.Xr3vFq.rst
new file mode 100644
index 00000000000000..648287680cf156
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2026-07-27-12-00-00.gh-issue-94984.Xr3vFq.rst
@@ -0,0 +1,4 @@
+Add the *mode* parameter to :meth:`asyncio.loop.create_unix_server` and
+:func:`asyncio.start_unix_server` to set the permissions of the Unix
+socket file created for *path*, applied before the server starts
+accepting connections.

_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]