chore: add comments

leehanjeong · leehanjeong · commit 163bd7c7a0ac · 2025-09-23T19:42:32.000+09:00
diff --git a/src/py/pyodide/webloop.py b/src/py/pyodide/webloop.py
@@ -742,13 +742,13 @@ def add_writer(self, fd, callback, *args):  # type: ignore[override]
         )
 
     def remove_reader(self, fd):
-        """Remove a reader callback for a file descriptor."""
+        """Remove a reader callback for a file descriptor (unsupported on WebLoop)."""
         raise NotImplementedError(
             "remove_reader() is not available in browser environments due to lack of POSIX file descriptors."
         )
 
     def remove_writer(self, fd):
-        """Remove a writer callback for a file descriptor."""
+        """Remove a writer callback for a file descriptor (unsupported on WebLoop)."""
         raise NotImplementedError(
             "remove_writer() is not available in browser environments due to lack of POSIX file descriptors."
         )
@@ -758,19 +758,19 @@ def remove_writer(self, fd):
     #
 
     async def connect_read_pipe(self, protocol_factory, pipe):
-        """Connect a read pipe to the event loop."""
+        """Connect a read pipe to the event loop (unsupported on WebLoop)."""
         raise NotImplementedError(
             "connect_read_pipe() is not available in browser environments due to absence of OS pipes."
         )
 
     async def connect_write_pipe(self, protocol_factory, pipe):
-        """Connect a write pipe to the event loop."""
+        """Connect a write pipe to the event loop (unsupported on WebLoop)."""
         raise NotImplementedError(
             "connect_write_pipe() is not available in browser environments due to absence of OS pipes."
         )
 
     async def sendfile(self, transport, file, offset=0, count=None, *, fallback=True):
-        """Send a file over a transport. Return the total number of bytes sent."""
+        """Send a file over a transport (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sendfile() is not available in browser environments due to missing OS file descriptors and zero-copy facilities."
         )
@@ -780,55 +780,55 @@ async def sendfile(self, transport, file, offset=0, count=None, *, fallback=True
     #
 
     async def getaddrinfo(self, host, port, *, family=0, type=0, proto=0, flags=0):
-        """Asynchronous version of socket.getaddrinfo().""" ""
+        """Asynchronous version of socket.getaddrinfo() (unsupported on WebLoop)."""
         raise NotImplementedError(
             "getaddrinfo() is not available in browser environments due to restricted raw network access."
         )
 
     async def getnameinfo(self, sockaddr, flags=0):
-        """Asynchronous version of socket.getnameinfo()."""
+        """Asynchronous version of socket.getnameinfo() (unsupported on WebLoop)."""
         raise NotImplementedError(
             "getnameinfo() is not available in browser environments due to restricted raw network access."
         )
 
     async def create_connection(self, protocol_factory, host=None, port=None, **kwargs):
-        """Open a streaming transport connection to a given address (host, port)."""
+        """Open a streaming transport connection to a given address (unsupported on WebLoop)."""
         raise NotImplementedError(
             "create_connection() is not available in browser environments due to restricted raw socket access."
         )
 
     async def create_server(self, protocol_factory, host=None, port=None, **kwargs):
-        """Create a TCP server (SOCK_STREAM); return a Server object."""
+        """Create a TCP server (unsupported on WebLoop)."""
         raise NotImplementedError(
             "create_server() is not available in browser environments due to restricted raw socket access."
         )
 
     async def create_unix_connection(self, protocol_factory, path=None, **kwargs):
-        """Open a connection to a UNIX domain socket."""
+        """Open a connection to a UNIX domain socket (unsupported on WebLoop)."""
         raise NotImplementedError(
             "create_unix_connection() is not available in browser environments due to absence of Unix domain sockets."
         )
 
     async def create_unix_server(self, protocol_factory, path=None, **kwargs):
-        """Create a UNIX domain socket server."""
+        """Create a UNIX domain socket server (unsupported on WebLoop)."""
         raise NotImplementedError(
             "create_unix_server() is not available in browser environments due to absence of Unix domain sockets."
         )
 
     async def connect_accepted_socket(self, protocol_factory, sock, **kwargs):
-        """Wrap an already accepted socket into a (transport, protocol) pair."""
+        """Wrap an already accepted socket into a transport and protocol pair (unsupported on WebLoop)."""
         raise NotImplementedError(
             "connect_accepted_socket() is not available in browser environments due to restricted raw socket access."
         )
 
     async def create_datagram_endpoint(self, protocol_factory, **kwargs):  # type: ignore[override]
-        """Create a datagram (UDP) connection; return (transport, protocol)."""
+        """Create a datagram (UDP) connection (unsupported on WebLoop)."""
         raise NotImplementedError(
             "create_datagram_endpoint() is not available in browser environments due to restricted raw socket access."
         )
 
     async def start_tls(self, transport, protocol, sslcontext, **kwargs):
-        """Upgrade an existing connection to TLS."""
+        """Upgrade an existing connection to TLS (unsupported on WebLoop)."""
         raise NotImplementedError(
             "start_tls() is not available in browser environments due to lack of low-level TLS controls."
         )
@@ -838,55 +838,55 @@ async def start_tls(self, transport, protocol, sslcontext, **kwargs):
     #
 
     async def sock_recv(self, sock, nbytes):
-        """Receive up to nbytes; return bytes."""
+        """Receive up to nbytes (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_recv() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_recv_into(self, sock, buf):
-        """Receive into buf; return number of bytes written."""
+        """Receive into buf (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_recv_into() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_recvfrom(self, sock, bufsize):
-        """Receive a datagram up to bufsize; return (data, address)."""
+        """Receive a datagram up to bufsize (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_recvfrom() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_recvfrom_into(self, sock, buf, nbytes=0):
-        """Receive a datagram into buf; return (nbytes, address)."""
+        """Receive a datagram into buf (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_recvfrom_into() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_sendall(self, sock, data):
-        """Send all data to the socket; return None on success."""
+        """Send all data to the socket (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_sendall() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_sendto(self, sock, data, address):
-        """Send a datagram to address; return number of bytes sent."""
+        """Send a datagram to address (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_sendto() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_connect(self, sock, address):
-        """Connect the socket to a remote address."""
+        """Connect the socket to a remote address (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_connect() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_accept(self, sock):
-        """Accept a connection; return (conn, address)."""
+        """Accept a connection (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_accept() is not available in browser environments due to restricted raw socket access."
         )
 
     async def sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=None):
-        """Send a file (uses os.sendfile if possible); return total bytes sent."""
+        """Send a file (uses os.sendfile if possible) (unsupported on WebLoop)."""
         raise NotImplementedError(
             "sock_sendfile() is not available in browser environments due to missing OS file descriptors and zero-copy facilities."
         )
@@ -896,13 +896,13 @@ async def sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=None
     #
 
     async def subprocess_shell(self, protocol_factory, cmd, **kwargs):
-        """Create a subprocess from string args; return (transport, protocol)."""
+        """Create a subprocess from string args (unsupported on WebLoop)."""
         raise NotImplementedError(
             "subprocess_shell() is not available in browser environments due to absence of OS process APIs."
         )
 
     async def subprocess_exec(self, protocol_factory, *args, **kwargs):
-        """Run a subprocess from a shell command line; return (transport, protocol)."""
+        """Run a subprocess from a shell command line (unsupported on WebLoop)."""
         raise NotImplementedError(
             "subprocess_exec() is not available in browser environments due to absence of OS process APIs."
         )
@@ -912,13 +912,13 @@ async def subprocess_exec(self, protocol_factory, *args, **kwargs):
     #
 
     def add_signal_handler(self, sig, callback, *args):  # type: ignore[override]
-        """Set callback as the handler for the given signal (Unix)."""
+        """Set callback as the handler for the given signal (unsupported on WebLoop)."""
         raise NotImplementedError(
             "add_signal_handler() is not available in browser environments due to lack of POSIX signals."
         )
 
     def remove_signal_handler(self, sig):
-        """Remove the handler for the given signal; return True if removed (Unix)."""
+        """Remove the handler for the given signal (unsupported on WebLoop)."""
         raise NotImplementedError(
             "remove_signal_handler() is not available in browser environments due to lack of POSIX signals."
         )

Original file line number	Diff line number	Diff line change
`@@ -742,13 +742,13 @@ def add_writer(self, fd, callback, *args): # type: ignore[override]`
`742`	`742`	`)`
`743`	`743`
`744`	`744`	`def remove_reader(self, fd):`
`745`		`- """Remove a reader callback for a file descriptor."""`
	`745`	`+ """Remove a reader callback for a file descriptor (unsupported on WebLoop)."""`
`746`	`746`	`raise NotImplementedError(`
`747`	`747`	`"remove_reader() is not available in browser environments due to lack of POSIX file descriptors."`
`748`	`748`	`)`
`749`	`749`
`750`	`750`	`def remove_writer(self, fd):`
`751`		`- """Remove a writer callback for a file descriptor."""`
	`751`	`+ """Remove a writer callback for a file descriptor (unsupported on WebLoop)."""`
`752`	`752`	`raise NotImplementedError(`
`753`	`753`	`"remove_writer() is not available in browser environments due to lack of POSIX file descriptors."`
`754`	`754`	`)`
`@@ -758,19 +758,19 @@ def remove_writer(self, fd):`
`758`	`758`	`#`
`759`	`759`
`760`	`760`	`async def connect_read_pipe(self, protocol_factory, pipe):`
`761`		`- """Connect a read pipe to the event loop."""`
	`761`	`+ """Connect a read pipe to the event loop (unsupported on WebLoop)."""`
`762`	`762`	`raise NotImplementedError(`
`763`	`763`	`"connect_read_pipe() is not available in browser environments due to absence of OS pipes."`
`764`	`764`	`)`
`765`	`765`
`766`	`766`	`async def connect_write_pipe(self, protocol_factory, pipe):`
`767`		`- """Connect a write pipe to the event loop."""`
	`767`	`+ """Connect a write pipe to the event loop (unsupported on WebLoop)."""`
`768`	`768`	`raise NotImplementedError(`
`769`	`769`	`"connect_write_pipe() is not available in browser environments due to absence of OS pipes."`
`770`	`770`	`)`
`771`	`771`
`772`	`772`	`async def sendfile(self, transport, file, offset=0, count=None, *, fallback=True):`
`773`		`- """Send a file over a transport. Return the total number of bytes sent."""`
	`773`	`+ """Send a file over a transport (unsupported on WebLoop)."""`
`774`	`774`	`raise NotImplementedError(`
`775`	`775`	`"sendfile() is not available in browser environments due to missing OS file descriptors and zero-copy facilities."`
`776`	`776`	`)`
`@@ -780,55 +780,55 @@ async def sendfile(self, transport, file, offset=0, count=None, *, fallback=True`
`780`	`780`	`#`
`781`	`781`
`782`	`782`	`async def getaddrinfo(self, host, port, *, family=0, type=0, proto=0, flags=0):`
`783`		`- """Asynchronous version of socket.getaddrinfo().""" ""`
	`783`	`+ """Asynchronous version of socket.getaddrinfo() (unsupported on WebLoop)."""`
`784`	`784`	`raise NotImplementedError(`
`785`	`785`	`"getaddrinfo() is not available in browser environments due to restricted raw network access."`
`786`	`786`	`)`
`787`	`787`
`788`	`788`	`async def getnameinfo(self, sockaddr, flags=0):`
`789`		`- """Asynchronous version of socket.getnameinfo()."""`
	`789`	`+ """Asynchronous version of socket.getnameinfo() (unsupported on WebLoop)."""`
`790`	`790`	`raise NotImplementedError(`
`791`	`791`	`"getnameinfo() is not available in browser environments due to restricted raw network access."`
`792`	`792`	`)`
`793`	`793`
`794`	`794`	`async def create_connection(self, protocol_factory, host=None, port=None, **kwargs):`
`795`		`- """Open a streaming transport connection to a given address (host, port)."""`
	`795`	`+ """Open a streaming transport connection to a given address (unsupported on WebLoop)."""`
`796`	`796`	`raise NotImplementedError(`
`797`	`797`	`"create_connection() is not available in browser environments due to restricted raw socket access."`
`798`	`798`	`)`
`799`	`799`
`800`	`800`	`async def create_server(self, protocol_factory, host=None, port=None, **kwargs):`
`801`		`- """Create a TCP server (SOCK_STREAM); return a Server object."""`
	`801`	`+ """Create a TCP server (unsupported on WebLoop)."""`
`802`	`802`	`raise NotImplementedError(`
`803`	`803`	`"create_server() is not available in browser environments due to restricted raw socket access."`
`804`	`804`	`)`
`805`	`805`
`806`	`806`	`async def create_unix_connection(self, protocol_factory, path=None, **kwargs):`
`807`		`- """Open a connection to a UNIX domain socket."""`
	`807`	`+ """Open a connection to a UNIX domain socket (unsupported on WebLoop)."""`
`808`	`808`	`raise NotImplementedError(`
`809`	`809`	`"create_unix_connection() is not available in browser environments due to absence of Unix domain sockets."`
`810`	`810`	`)`
`811`	`811`
`812`	`812`	`async def create_unix_server(self, protocol_factory, path=None, **kwargs):`
`813`		`- """Create a UNIX domain socket server."""`
	`813`	`+ """Create a UNIX domain socket server (unsupported on WebLoop)."""`
`814`	`814`	`raise NotImplementedError(`
`815`	`815`	`"create_unix_server() is not available in browser environments due to absence of Unix domain sockets."`
`816`	`816`	`)`
`817`	`817`
`818`	`818`	`async def connect_accepted_socket(self, protocol_factory, sock, **kwargs):`
`819`		`- """Wrap an already accepted socket into a (transport, protocol) pair."""`
	`819`	`+ """Wrap an already accepted socket into a transport and protocol pair (unsupported on WebLoop)."""`
`820`	`820`	`raise NotImplementedError(`
`821`	`821`	`"connect_accepted_socket() is not available in browser environments due to restricted raw socket access."`
`822`	`822`	`)`
`823`	`823`
`824`	`824`	`async def create_datagram_endpoint(self, protocol_factory, **kwargs): # type: ignore[override]`
`825`		`- """Create a datagram (UDP) connection; return (transport, protocol)."""`
	`825`	`+ """Create a datagram (UDP) connection (unsupported on WebLoop)."""`
`826`	`826`	`raise NotImplementedError(`
`827`	`827`	`"create_datagram_endpoint() is not available in browser environments due to restricted raw socket access."`
`828`	`828`	`)`
`829`	`829`
`830`	`830`	`async def start_tls(self, transport, protocol, sslcontext, **kwargs):`
`831`		`- """Upgrade an existing connection to TLS."""`
	`831`	`+ """Upgrade an existing connection to TLS (unsupported on WebLoop)."""`
`832`	`832`	`raise NotImplementedError(`
`833`	`833`	`"start_tls() is not available in browser environments due to lack of low-level TLS controls."`
`834`	`834`	`)`
`@@ -838,55 +838,55 @@ async def start_tls(self, transport, protocol, sslcontext, **kwargs):`
`838`	`838`	`#`
`839`	`839`
`840`	`840`	`async def sock_recv(self, sock, nbytes):`
`841`		`- """Receive up to nbytes; return bytes."""`
	`841`	`+ """Receive up to nbytes (unsupported on WebLoop)."""`
`842`	`842`	`raise NotImplementedError(`
`843`	`843`	`"sock_recv() is not available in browser environments due to restricted raw socket access."`
`844`	`844`	`)`
`845`	`845`
`846`	`846`	`async def sock_recv_into(self, sock, buf):`
`847`		`- """Receive into buf; return number of bytes written."""`
	`847`	`+ """Receive into buf (unsupported on WebLoop)."""`
`848`	`848`	`raise NotImplementedError(`
`849`	`849`	`"sock_recv_into() is not available in browser environments due to restricted raw socket access."`
`850`	`850`	`)`
`851`	`851`
`852`	`852`	`async def sock_recvfrom(self, sock, bufsize):`
`853`		`- """Receive a datagram up to bufsize; return (data, address)."""`
	`853`	`+ """Receive a datagram up to bufsize (unsupported on WebLoop)."""`
`854`	`854`	`raise NotImplementedError(`
`855`	`855`	`"sock_recvfrom() is not available in browser environments due to restricted raw socket access."`
`856`	`856`	`)`
`857`	`857`
`858`	`858`	`async def sock_recvfrom_into(self, sock, buf, nbytes=0):`
`859`		`- """Receive a datagram into buf; return (nbytes, address)."""`
	`859`	`+ """Receive a datagram into buf (unsupported on WebLoop)."""`
`860`	`860`	`raise NotImplementedError(`
`861`	`861`	`"sock_recvfrom_into() is not available in browser environments due to restricted raw socket access."`
`862`	`862`	`)`
`863`	`863`
`864`	`864`	`async def sock_sendall(self, sock, data):`
`865`		`- """Send all data to the socket; return None on success."""`
	`865`	`+ """Send all data to the socket (unsupported on WebLoop)."""`
`866`	`866`	`raise NotImplementedError(`
`867`	`867`	`"sock_sendall() is not available in browser environments due to restricted raw socket access."`
`868`	`868`	`)`
`869`	`869`
`870`	`870`	`async def sock_sendto(self, sock, data, address):`
`871`		`- """Send a datagram to address; return number of bytes sent."""`
	`871`	`+ """Send a datagram to address (unsupported on WebLoop)."""`
`872`	`872`	`raise NotImplementedError(`
`873`	`873`	`"sock_sendto() is not available in browser environments due to restricted raw socket access."`
`874`	`874`	`)`
`875`	`875`
`876`	`876`	`async def sock_connect(self, sock, address):`
`877`		`- """Connect the socket to a remote address."""`
	`877`	`+ """Connect the socket to a remote address (unsupported on WebLoop)."""`
`878`	`878`	`raise NotImplementedError(`
`879`	`879`	`"sock_connect() is not available in browser environments due to restricted raw socket access."`
`880`	`880`	`)`
`881`	`881`
`882`	`882`	`async def sock_accept(self, sock):`
`883`		`- """Accept a connection; return (conn, address)."""`
	`883`	`+ """Accept a connection (unsupported on WebLoop)."""`
`884`	`884`	`raise NotImplementedError(`
`885`	`885`	`"sock_accept() is not available in browser environments due to restricted raw socket access."`
`886`	`886`	`)`
`887`	`887`
`888`	`888`	`async def sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=None):`
`889`		`- """Send a file (uses os.sendfile if possible); return total bytes sent."""`
	`889`	`+ """Send a file (uses os.sendfile if possible) (unsupported on WebLoop)."""`
`890`	`890`	`raise NotImplementedError(`
`891`	`891`	`"sock_sendfile() is not available in browser environments due to missing OS file descriptors and zero-copy facilities."`
`892`	`892`	`)`
`@@ -896,13 +896,13 @@ async def sock_sendfile(self, sock, file, offset=0, count=None, *, fallback=None`
`896`	`896`	`#`
`897`	`897`
`898`	`898`	`async def subprocess_shell(self, protocol_factory, cmd, **kwargs):`
`899`		`- """Create a subprocess from string args; return (transport, protocol)."""`
	`899`	`+ """Create a subprocess from string args (unsupported on WebLoop)."""`
`900`	`900`	`raise NotImplementedError(`
`901`	`901`	`"subprocess_shell() is not available in browser environments due to absence of OS process APIs."`
`902`	`902`	`)`
`903`	`903`
`904`	`904`	`async def subprocess_exec(self, protocol_factory, args, *kwargs):`
`905`		`- """Run a subprocess from a shell command line; return (transport, protocol)."""`
	`905`	`+ """Run a subprocess from a shell command line (unsupported on WebLoop)."""`
`906`	`906`	`raise NotImplementedError(`
`907`	`907`	`"subprocess_exec() is not available in browser environments due to absence of OS process APIs."`
`908`	`908`	`)`
`@@ -912,13 +912,13 @@ async def subprocess_exec(self, protocol_factory, args, *kwargs):`
`912`	`912`	`#`
`913`	`913`
`914`	`914`	`def add_signal_handler(self, sig, callback, *args): # type: ignore[override]`
`915`		`- """Set callback as the handler for the given signal (Unix)."""`
	`915`	`+ """Set callback as the handler for the given signal (unsupported on WebLoop)."""`
`916`	`916`	`raise NotImplementedError(`
`917`	`917`	`"add_signal_handler() is not available in browser environments due to lack of POSIX signals."`
`918`	`918`	`)`
`919`	`919`
`920`	`920`	`def remove_signal_handler(self, sig):`
`921`		`- """Remove the handler for the given signal; return True if removed (Unix)."""`
	`921`	`+ """Remove the handler for the given signal (unsupported on WebLoop)."""`
`922`	`922`	`raise NotImplementedError(`
`923`	`923`	`"remove_signal_handler() is not available in browser environments due to lack of POSIX signals."`
`924`	`924`	`)`