new repository

1 files changed, 123 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fselectors.html b/devdocs/python~3.12/library%2Fselectors.html
new file mode 100644
index 00000000..33c12f96
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fselectors.html
@@ -0,0 +1,123 @@
+ <span id="selectors-high-level-i-o-multiplexing"></span><h1>selectors — High-level I/O multiplexing</h1> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/selectors.py">Lib/selectors.py</a></p>  <section id="introduction"> <h2>Introduction</h2> <p>This module allows high-level and efficient I/O multiplexing, built upon the <a class="reference internal" href="select#module-select" title="select: Wait for I/O completion on multiple streams."><code>select</code></a> module primitives. Users are encouraged to use this module instead, unless they want precise control over the OS-level primitives used.</p> <p>It defines a <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> abstract base class, along with several concrete implementations (<a class="reference internal" href="#selectors.KqueueSelector" title="selectors.KqueueSelector"><code>KqueueSelector</code></a>, <a class="reference internal" href="#selectors.EpollSelector" title="selectors.EpollSelector"><code>EpollSelector</code></a>…), that can be used to wait for I/O readiness notification on multiple file objects. In the following, “file object” refers to any object with a <a class="reference internal" href="io#io.IOBase.fileno" title="io.IOBase.fileno"><code>fileno()</code></a> method, or a raw file descriptor. See <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a>.</p> <p><a class="reference internal" href="#selectors.DefaultSelector" title="selectors.DefaultSelector"><code>DefaultSelector</code></a> is an alias to the most efficient implementation available on the current platform: this should be the default choice for most users.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The type of file objects supported depends on the platform: on Windows, sockets are supported, but not pipes, whereas on Unix, both are supported (some other types may be supported as well, such as fifos or special file devices).</p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
+<code></code> <a class="reference internal" href="select#module-select" title="select: Wait for I/O completion on multiple streams."><code>select</code></a>
+</dt>
+<dd>
+<p>Low-level I/O multiplexing module.</p> </dd> </dl> </div> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p> <p>This module does not work or is not available on WebAssembly platforms <code>wasm32-emscripten</code> and <code>wasm32-wasi</code>. See <a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p> </div> </section> <section id="classes"> <h2>Classes</h2> <p>Classes hierarchy:</p> <pre data-language="python">BaseSelector
++-- SelectSelector
++-- PollSelector
++-- EpollSelector
++-- DevpollSelector
++-- KqueueSelector
+</pre> <p>In the following, <em>events</em> is a bitwise mask indicating which I/O events should be waited for on a given file object. It can be a combination of the modules constants below:</p>  <table class="docutils align-default">  <thead> <tr>
+<th class="head"><p>Constant</p></th> <th class="head"><p>Meaning</p></th> </tr> </thead>  <tr>
+<td>
+<dl class="py data"> <dt class="sig sig-object py" id="selectors.EVENT_READ">
+<code>selectors.EVENT_READ</code> </dt> <dd></dd>
+</dl> </td> <td><p>Available for read</p></td> </tr> <tr>
+<td>
+<dl class="py data"> <dt class="sig sig-object py" id="selectors.EVENT_WRITE">
+<code>selectors.EVENT_WRITE</code> </dt> <dd></dd>
+</dl> </td> <td><p>Available for write</p></td> </tr>  </table>  <dl class="py class"> <dt class="sig sig-object py" id="selectors.SelectorKey">
+<code>class selectors.SelectorKey</code> </dt> <dd>
+<p>A <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> is a <a class="reference internal" href="collections#collections.namedtuple" title="collections.namedtuple"><code>namedtuple</code></a> used to associate a file object to its underlying file descriptor, selected event mask and attached data. It is returned by several <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> methods.</p> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.fileobj">
+<code>fileobj</code> </dt> <dd>
+<p>File object registered.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.fd">
+<code>fd</code> </dt> <dd>
+<p>Underlying file descriptor.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.events">
+<code>events</code> </dt> <dd>
+<p>Events that must be waited for on this file object.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="selectors.SelectorKey.data">
+<code>data</code> </dt> <dd>
+<p>Optional opaque data associated to this file object: for example, this could be used to store a per-client session ID.</p> </dd>
+</dl> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.BaseSelector">
+<code>class selectors.BaseSelector</code> </dt> <dd>
+<p>A <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> is used to wait for I/O event readiness on multiple file objects. It supports file stream registration, unregistration, and a method to wait for I/O events on those streams, with an optional timeout. It’s an abstract base class, so cannot be instantiated. Use <a class="reference internal" href="#selectors.DefaultSelector" title="selectors.DefaultSelector"><code>DefaultSelector</code></a> instead, or one of <a class="reference internal" href="#selectors.SelectSelector" title="selectors.SelectSelector"><code>SelectSelector</code></a>, <a class="reference internal" href="#selectors.KqueueSelector" title="selectors.KqueueSelector"><code>KqueueSelector</code></a> etc. if you want to specifically use an implementation, and your platform supports it. <a class="reference internal" href="#selectors.BaseSelector" title="selectors.BaseSelector"><code>BaseSelector</code></a> and its concrete implementations support the <a class="reference internal" href="../glossary#term-context-manager"><span class="xref std std-term">context manager</span></a> protocol.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.register">
+<code>abstractmethod register(fileobj, events, data=None)</code> </dt> <dd>
+<p>Register a file object for selection, monitoring it for I/O events.</p> <p><em>fileobj</em> is the file object to monitor. It may either be an integer file descriptor or an object with a <code>fileno()</code> method. <em>events</em> is a bitwise mask of events to monitor. <em>data</em> is an opaque object.</p> <p>This returns a new <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance, or raises a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> in case of invalid event mask or file descriptor, or <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the file object is already registered.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.unregister">
+<code>abstractmethod unregister(fileobj)</code> </dt> <dd>
+<p>Unregister a file object from selection, removing it from monitoring. A file object shall be unregistered prior to being closed.</p> <p><em>fileobj</em> must be a file object previously registered.</p> <p>This returns the associated <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance, or raises a <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if <em>fileobj</em> is not registered. It will raise <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> if <em>fileobj</em> is invalid (e.g. it has no <code>fileno()</code> method or its <code>fileno()</code> method has an invalid return value).</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.modify">
+<code>modify(fileobj, events, data=None)</code> </dt> <dd>
+<p>Change a registered file object’s monitored events or attached data.</p> <p>This is equivalent to <code>BaseSelector.unregister(fileobj)</code> followed by <code>BaseSelector.register(fileobj, events, data)</code>, except that it can be implemented more efficiently.</p> <p>This returns a new <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance, or raises a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> in case of invalid event mask or file descriptor, or <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the file object is not registered.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.select">
+<code>abstractmethod select(timeout=None)</code> </dt> <dd>
+<p>Wait until some registered file objects become ready, or the timeout expires.</p> <p>If <code>timeout &gt; 0</code>, this specifies the maximum wait time, in seconds. If <code>timeout &lt;= 0</code>, the call won’t block, and will report the currently ready file objects. If <em>timeout</em> is <code>None</code>, the call will block until a monitored file object becomes ready.</p> <p>This returns a list of <code>(key, events)</code> tuples, one for each ready file object.</p> <p><em>key</em> is the <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance corresponding to a ready file object. <em>events</em> is a bitmask of events ready on this file object.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>This method can return before any file object becomes ready or the timeout has elapsed if the current process receives a signal: in this case, an empty list will be returned.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The selector is now retried with a recomputed timeout when interrupted by a signal if the signal handler did not raise an exception (see <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0475/"><strong>PEP 475</strong></a> for the rationale), instead of returning an empty list of events before the timeout.</p> </div> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.close">
+<code>close()</code> </dt> <dd>
+<p>Close the selector.</p> <p>This must be called to make sure that any underlying resource is freed. The selector shall not be used once it has been closed.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.get_key">
+<code>get_key(fileobj)</code> </dt> <dd>
+<p>Return the key associated with a registered file object.</p> <p>This returns the <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance associated to this file object, or raises <a class="reference internal" href="exceptions#KeyError" title="KeyError"><code>KeyError</code></a> if the file object is not registered.</p> </dd>
+</dl> <dl class="py method"> <dt class="sig sig-object py" id="selectors.BaseSelector.get_map">
+<code>abstractmethod get_map()</code> </dt> <dd>
+<p>Return a mapping of file objects to selector keys.</p> <p>This returns a <a class="reference internal" href="collections.abc#collections.abc.Mapping" title="collections.abc.Mapping"><code>Mapping</code></a> instance mapping registered file objects to their associated <a class="reference internal" href="#selectors.SelectorKey" title="selectors.SelectorKey"><code>SelectorKey</code></a> instance.</p> </dd>
+</dl> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.DefaultSelector">
+<code>class selectors.DefaultSelector</code> </dt> <dd>
+<p>The default selector class, using the most efficient implementation available on the current platform. This should be the default choice for most users.</p> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.SelectSelector">
+<code>class selectors.SelectSelector</code> </dt> <dd>
+<p><a class="reference internal" href="select#select.select" title="select.select"><code>select.select()</code></a>-based selector.</p> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.PollSelector">
+<code>class selectors.PollSelector</code> </dt> <dd>
+<p><a class="reference internal" href="select#select.poll" title="select.poll"><code>select.poll()</code></a>-based selector.</p> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.EpollSelector">
+<code>class selectors.EpollSelector</code> </dt> <dd>
+<p><a class="reference internal" href="select#select.epoll" title="select.epoll"><code>select.epoll()</code></a>-based selector.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.EpollSelector.fileno">
+<code>fileno()</code> </dt> <dd>
+<p>This returns the file descriptor used by the underlying <a class="reference internal" href="select#select.epoll" title="select.epoll"><code>select.epoll()</code></a> object.</p> </dd>
+</dl> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.DevpollSelector">
+<code>class selectors.DevpollSelector</code> </dt> <dd>
+<p><a class="reference internal" href="select#select.devpoll" title="select.devpoll"><code>select.devpoll()</code></a>-based selector.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.DevpollSelector.fileno">
+<code>fileno()</code> </dt> <dd>
+<p>This returns the file descriptor used by the underlying <a class="reference internal" href="select#select.devpoll" title="select.devpoll"><code>select.devpoll()</code></a> object.</p> </dd>
+</dl> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.5.</span></p> </div> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="selectors.KqueueSelector">
+<code>class selectors.KqueueSelector</code> </dt> <dd>
+<p><a class="reference internal" href="select#select.kqueue" title="select.kqueue"><code>select.kqueue()</code></a>-based selector.</p> <dl class="py method"> <dt class="sig sig-object py" id="selectors.KqueueSelector.fileno">
+<code>fileno()</code> </dt> <dd>
+<p>This returns the file descriptor used by the underlying <a class="reference internal" href="select#select.kqueue" title="select.kqueue"><code>select.kqueue()</code></a> object.</p> </dd>
+</dl> </dd>
+</dl> </section> <section id="examples"> <h2>Examples</h2> <p>Here is a simple echo server implementation:</p> <pre data-language="python">import selectors
+import socket
+
+sel = selectors.DefaultSelector()
+
+def accept(sock, mask):
+    conn, addr = sock.accept()  # Should be ready
+    print('accepted', conn, 'from', addr)
+    conn.setblocking(False)
+    sel.register(conn, selectors.EVENT_READ, read)
+
+def read(conn, mask):
+    data = conn.recv(1000)  # Should be ready
+    if data:
+        print('echoing', repr(data), 'to', conn)
+        conn.send(data)  # Hope it won't block
+    else:
+        print('closing', conn)
+        sel.unregister(conn)
+        conn.close()
+
+sock = socket.socket()
+sock.bind(('localhost', 1234))
+sock.listen(100)
+sock.setblocking(False)
+sel.register(sock, selectors.EVENT_READ, accept)
+
+while True:
+    events = sel.select()
+    for key, mask in events:
+        callback = key.data
+        callback(key.fileobj, mask)
+</pre> </section> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/selectors.html" class="_attribution-link">https://docs.python.org/3.12/library/selectors.html</a>
+  </p>
+</div>