iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 554: Fix formatting for module API. (#947) 

* Fix formatting of module API descriptions.

* Fix the API tables.
This commit is contained in:
Eric Snow 2019-03-25 19:10:58 -06:00 committed by GitHub
parent 3a58dceead
commit 6a6f3efde1
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 321 additions and 297 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

618
pep-0554.rst
View File

@ -64,128 +64,127 @@ the `"interpreters" Module API`_ section below.
For creating and using interpreters: For creating and using interpreters:
+------------------------------+----------------------------------------------+ +----------------------------------+----------------------------------------------+
| signature | description | | signature | description |
+==============================+==============================================+ +==================================+==============================================+
| list_all() -> [Intepreter] | Get all existing interpreters. | | ``list_all() -> [Intepreter]`` | Get all existing interpreters. |
+------------------------------+----------------------------------------------+ +----------------------------------+----------------------------------------------+
| get_current() -> Interpreter | Get the currently running interpreter. | | ``get_current() -> Interpreter`` | Get the currently running interpreter. |
+------------------------------+----------------------------------------------+ +----------------------------------+----------------------------------------------+
| create() -> Interpreter | Initialize a new (idle) Python interpreter. | | ``create() -> Interpreter`` | Initialize a new (idle) Python interpreter. |
+------------------------------+----------------------------------------------+ +----------------------------------+----------------------------------------------+
| |
+-----------------------+-----------------------------------------------------+ +----------------------------------------+-----------------------------------------------------+
| signature | description | | signature | description |
+=======================+=====================================================+ +========================================+=====================================================+
| class Interpreter(id) | A single interpreter. | | ``class Interpreter(id)`` | A single interpreter. |
+-----------------------+-----------------------------------------------------+ +----------------------------------------+-----------------------------------------------------+
| .id | The interpreter's ID (read-only). | | ``.id`` | The interpreter's ID (read-only). |
+-----------------------+-----------------------------------------------------+ +----------------------------------------+-----------------------------------------------------+
| .is_running() -> bool | Is the interpreter currently executing code? | | ``.is_running() -> bool`` | Is the interpreter currently executing code? |
+-----------------------+-----------------------------------------------------+ +----------------------------------------+-----------------------------------------------------+
| .destroy() | Finalize and destroy the interpreter. | | ``.destroy()`` | Finalize and destroy the interpreter. |
+-----------------------+-----------------------------------------------------+ +----------------------------------------+-----------------------------------------------------+
| .run(src_str, /, \*, | | Run the given source code in the interpreter. | | ``.run(src_str, /, *, channels=None)`` | | Run the given source code in the interpreter. |
| channels=None) | | (This blocks the current thread until done.) | | | | (This blocks the current thread until done.) |
+-----------------------+-----------------------------------------------------+ +----------------------------------------+-----------------------------------------------------+
| |
+----------------+--------------+------------------------------------------------------+ +--------------------+------------------+------------------------------------------------------+
| exception | base | description | | exception | base | description |
+================+==============+======================================================+ +====================+==================+======================================================+
| RunFailedError | RuntimeError | Interpreter.run() resulted in an uncaught exception. | | ``RunFailedError`` | ``RuntimeError`` | Interpreter.run() resulted in an uncaught exception. |
+----------------+--------------+------------------------------------------------------+ +--------------------+------------------+------------------------------------------------------+
For sharing data between interpreters: For sharing data between interpreters:
+--------------------------------+--------------------------------------------+ +---------------------------------------------------------+--------------------------------------------+
| signature | description | | signature | description |
+================================+============================================+ +=========================================================+============================================+
| is_shareable(obj) -> Bool | | Can the object's data be shared | | ``is_shareable(obj) -> Bool`` | | Can the object's data be shared |
| | | between interpreters? | | | | between interpreters? |
+--------------------------------+--------------------------------------------+ +---------------------------------------------------------+--------------------------------------------+
| create_channel() -> | | Create a new channel for passing | | ``create_channel() -> (RecvChannel, SendChannel)`` | | Create a new channel for passing |
| (RecvChannel, SendChannel) | | data between interpreters. | | | | data between interpreters. |
+--------------------------------+--------------------------------------------+ +---------------------------------------------------------+--------------------------------------------+
| list_all_channels() -> | Get all open channels. | | ``list_all_channels() -> [(RecvChannel, SendChannel)]`` | Get all open channels. |
| [(RecvChannel, SendChannel)] | | +---------------------------------------------------------+--------------------------------------------+
+--------------------------------+--------------------------------------------+
| |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| signature | description | | signature | description |
+===============================+===============================================+ +==========================================+===============================================+
| class RecvChannel(id) | The receiving end of a channel. | | ``class RecvChannel(id)`` | The receiving end of a channel. |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| .id | The channel's unique ID. | | ``.id`` | The channel's unique ID. |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| .interpreters | The list of associated interpreters. | | ``.interpreters`` | The list of associated interpreters. |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| .recv() -> object | | Get the next object from the channel, | | ``.recv() -> object`` | | Get the next object from the channel, |
| | | and wait if none have been sent. | | | | and wait if none have been sent. |
| | | Associate the interpreter with the channel. | | | | Associate the interpreter with the channel. |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| .recv_nowait(default=None) -> | | Like recv(), but return the default | | ``.recv_nowait(default=None) -> object`` | | Like recv(), but return the default |
| object | | instead of waiting. | | | | instead of waiting. |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| .release() | | No longer associate the current interpreter | | ``.release()`` | | No longer associate the current interpreter |
| | | with the channel (on the receiving end). | | | | with the channel (on the receiving end). |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| .close(force=False) | | Close the channel in all interpreters. | | ``.close(force=False)`` | | Close the channel in all interpreters. |
+-------------------------------+-----------------------------------------------+ +------------------------------------------+-----------------------------------------------+
| |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| signature | description | | signature | description |
+===========================+=================================================+ +==============================+=================================================+
| class SendChannel(id) | The sending end of a channel. | | ``class SendChannel(id)`` | The sending end of a channel. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .id | The channel's unique ID. | | ``.id`` | The channel's unique ID. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .interpreters | The list of associated interpreters. | | ``.interpreters`` | The list of associated interpreters. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .send(obj) | | Send the object (i.e. its data) to the | | ``.send(obj)`` | | Send the object (i.e. its data) to the |
| | | receiving end of the channel and wait. | | | | receiving end of the channel and wait. |
| | | Associate the interpreter with the channel. | | | | Associate the interpreter with the channel. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .send_nowait(obj) | | Like send(), but fail if not received. | | ``.send_nowait(obj)`` | | Like send(), but fail if not received. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .send_buffer(obj) | | Send the object's (PEP 3118) buffer to the | | ``.send_buffer(obj)`` | | Send the object's (PEP 3118) buffer to the |
| | | receiving end of the channel and wait. | | | | receiving end of the channel and wait. |
| | | Associate the interpreter with the channel. | | | | Associate the interpreter with the channel. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .send_buffer_nowait(obj) | | Like send_buffer(), but fail if not received. | | ``.send_buffer_nowait(obj)`` | | Like send_buffer(), but fail if not received. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .release() | | No longer associate the current interpreter | | ``.release()`` | | No longer associate the current interpreter |
| | | with the channel (on the sending end). | | | | with the channel (on the sending end). |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| .close(force=False) | | Close the channel in all interpreters. | | ``.close(force=False)`` | | Close the channel in all interpreters. |
+---------------------------+-------------------------------------------------+ +------------------------------+-------------------------------------------------+
| |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| exception | base | description | | exception | base | description |
+======================+====================+================================================+ +==========================+========================+================================================+
| ChannelError | Exception | The base class for channel-related exceptions. | | ``ChannelError`` | ``Exception`` | The base class for channel-related exceptions. |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| ChannelNotFoundError | ChannelError | The identified channel was not found. | | ``ChannelNotFoundError`` | ``ChannelError`` | The identified channel was not found. |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| ChannelEmptyError | ChannelError | The channel was unexpectedly empty. | | ``ChannelEmptyError`` | ``ChannelError`` | The channel was unexpectedly empty. |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| ChannelNotEmptyError | ChannelError | The channel was unexpectedly not empty. | | ``ChannelNotEmptyError`` | ``ChannelError`` | The channel was unexpectedly not empty. |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| NotReceivedError | ChannelError | Nothing was waiting to receive a sent object. | | ``NotReceivedError`` | ``ChannelError`` | Nothing was waiting to receive a sent object. |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| ChannelClosedError | ChannelError | The channel is closed. | | ``ChannelClosedError`` | ``ChannelError`` | The channel is closed. |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
| ChannelReleasedError | ChannelClosedError | The channel is released (but not yet closed). | | ``ChannelReleasedError`` | ``ChannelClosedError`` | The channel is released (but not yet closed). |
+----------------------+--------------------+------------------------------------------------+ +--------------------------+------------------------+------------------------------------------------+
Examples Examples
@ -656,96 +655,102 @@ TBD
* micropython: ??? * micropython: ???
.. _interpreters-list-all:
.. _interpreters-get-current:
.. _interpreters-create:
.. _interpreters-Interpreter:
"interpreters" Module API "interpreters" Module API
========================= =========================
The module provides the following functions: The module provides the following functions::
``list_all()``:: list_all() -> [Interpreter]
Return a list of all existing interpreters. Return a list of all existing interpreters.
``get_current()``:: get_current() => Interpreter
Return the currently running interpreter. Return the currently running interpreter.
``create()``:: create() -> Interpreter
Initialize a new Python interpreter and return it. The Initialize a new Python interpreter and return it. The
interpreter will be created in the current thread and will remain interpreter will be created in the current thread and will remain
idle until something is run in it. The interpreter may be used idle until something is run in it. The interpreter may be used
in any thread and will run in whichever thread calls in any thread and will run in whichever thread calls
``interp.run()``. ``interp.run()``.
The module also provides the following class: The module also provides the following class::
``Interpreter(id)``:: class Interpreter(id):
id: id -> int:
The interpreter's ID (read-only). The interpreter's ID (read-only).
is_running(): is_running() -> bool:
Return whether or not the interpreter is currently executing code. Return whether or not the interpreter is currently executing
Calling this on the current interpreter will always return True. code. Calling this on the current interpreter will always
return True.
destroy(): destroy():
Finalize and destroy the interpreter. Finalize and destroy the interpreter.
This may not be called on an already running interpreter. Doing This may not be called on an already running interpreter.
so results in a RuntimeError. Doing so results in a RuntimeError.
run(source_str, /, *, channels=None): run(source_str, /, *, channels=None):
Run the provided Python source code in the interpreter. If the Run the provided Python source code in the interpreter. If
"channels" keyword argument is provided (and is a mapping of the "channels" keyword argument is provided (and is a mapping
attribute names to channels) then it is added to the interpreter's of attribute names to channels) then it is added to the
execution namespace (the interpreter's "__main__" module). If any interpreter's execution namespace (the interpreter's
of the values are not RecvChannel or SendChannel instances "__main__" module). If any of the values are not RecvChannel
then ValueError gets raised. or SendChannel instances then ValueError gets raised.
This may not be called on an already running interpreter. Doing This may not be called on an already running interpreter.
so results in a RuntimeError. Doing so results in a RuntimeError.
A "run()" call is similar to a function call. Once it completes, A "run()" call is similar to a function call. Once it
the code that called "run()" continues executing (in the original completes, the code that called "run()" continues executing
interpreter). Likewise, if there is any uncaught exception then (in the original interpreter). Likewise, if there is any
it effectively (see below) propagates into the code where uncaught exception then it effectively (see below) propagates
``run()`` was called. However, unlike function calls (but like into the code where ``run()`` was called. However, unlike
threads), there is no return value. If any value is needed, pass function calls (but like threads), there is no return value.
it out via a channel. If any value is needed, pass it out via a channel.
The big difference from functions is that "run()" executes the The big difference from functions is that "run()" executes
code in an entirely different interpreter, with entirely separate the code in an entirely different interpreter, with entirely
state. The state of the current interpreter in the current OS separate state. The state of the current interpreter in the
thread is swapped out with the state of the target interpreter current OS thread is swapped out with the state of the target
(the one that will execute the code). When the target finishes interpreter (the one that will execute the code). When the
executing, the original interpreter gets swapped back in and its target finishes executing, the original interpreter gets
execution resumes. swapped back in and its execution resumes.
So calling "run()" will effectively cause the current Python So calling "run()" will effectively cause the current Python
thread to pause. Sometimes you won't want that pause, in which thread to pause. Sometimes you won't want that pause, in
case you should make the "run()" call in another thread. To do which case you should make the "run()" call in another thread.
so, add a function that calls "run()" and then run that function To do so, add a function that calls "run()" and then run that
in a normal "threading.Thread". function in a normal "threading.Thread".
Note that the interpreter's state is never reset, neither before Note that the interpreter's state is never reset, neither
"run()" executes the code nor after. Thus the interpreter before "run()" executes the code nor after. Thus the
state is preserved between calls to "run()". This includes interpreter state is preserved between calls to "run()".
"sys.modules", the "builtins" module, and the internal state This includes "sys.modules", the "builtins" module, and the
of C extension modules. internal state of C extension modules.
Also note that "run()" executes in the namespace of the "__main__" Also note that "run()" executes in the namespace of the
module, just like scripts, the REPL, "-m", and "-c". Just as "__main__" module, just like scripts, the REPL, "-m", and
the interpreter's state is not ever reset, the "__main__" module "-c". Just as the interpreter's state is not ever reset, the
is never reset. You can imagine concatenating the code from each "__main__" module is never reset. You can imagine
"run()" call into one long script. This is the same as how the concatenating the code from each "run()" call into one long
REPL operates. script. This is the same as how the REPL operates.
Supported code: source text. Supported code: source text.
Uncaught Exceptions Uncaught Exceptions
@ -762,6 +767,11 @@ Raising (a proxy of) the exception directly is problematic since it's
harder to distinguish between an error in the ``run()`` call and an harder to distinguish between an error in the ``run()`` call and an
uncaught exception from the subinterpreter. uncaught exception from the subinterpreter.
.. _interpreters-is-shareable:
.. _interpreters-create-channel:
.. _interpreters-list-all-channels:
.. _interpreters-RecvChannel:
.. _interpreters-SendChannel:
API for sharing data API for sharing data
-------------------- --------------------
@ -773,16 +783,16 @@ for that here. Instead, only mimimum set of types will be supported.
Initially this will include ``None``, ``bytes``, ``str``, ``int``, Initially this will include ``None``, ``bytes``, ``str``, ``int``,
and channels. Further types may be supported later. and channels. Further types may be supported later.
The ``interpreters`` module provides a way for users to determine The ``interpreters`` module provides a function that users may call
whether an object is shareable or not: to determine whether an object is shareable or not::
``is_shareable(obj)``:: is_shareable(obj) -> bool:
Return True if the object may be shared between interpreters. This Return True if the object may be shared between interpreters.
does not necessarily mean that the actual objects will be shared. This does not necessarily mean that the actual objects will be
Insead, it means that the objects' underlying data will be shared in shared. Insead, it means that the objects' underlying data will
a cross-interpreter way, whether via a proxy, a copy, or some other be shared in a cross-interpreter way, whether via a proxy, a
means. copy, or some other means.
This proposal provides two ways to share such objects between This proposal provides two ways to share such objects between
interpreters. interpreters.
@ -800,155 +810,169 @@ to a pipe. The main difference is that channels can be associated with
zero or more interpreters on either end. Unlike queues, which are also zero or more interpreters on either end. Unlike queues, which are also
many-to-many, channels have no buffer. many-to-many, channels have no buffer.
The ``interpreters`` module provides the following functions and The ``interpreters`` module provides the following functions related
classes related to channels: to channels::
``create_channel()``:: create_channel() -> (RecvChannel, SendChannel):
Create a new channel and return (recv, send), the RecvChannel and Create a new channel and return (recv, send), the RecvChannel
SendChannel corresponding to the ends of the channel. The channel and SendChannel corresponding to the ends of the channel. The
is not closed and destroyed (i.e. garbage-collected) until the number channel is not closed and destroyed (i.e. garbage-collected)
of associated interpreters returns to 0 (including when the channel until the number of associated interpreters returns to 0
is explicitly closed). (including when the channel is explicitly closed).
An interpreter gets associated with a channel by calling its "send()" An interpreter gets associated with a channel by calling its
or "recv()" method. That association gets dropped by calling "send()" or "recv()" method. That association gets dropped
"release()" on the channel. by calling "release()" on the channel.
Both ends of the channel are supported "shared" objects (i.e. may be Both ends of the channel are supported "shared" objects (i.e.
safely shared by different interpreters. Thus they may be passed as may be safely shared by different interpreters. Thus they
keyword arguments to "Interpreter.run()". may be passed as keyword arguments to "Interpreter.run()".
``list_all_channels()``:: list_all_channels() -> [(RecvChannel, SendChannel)]:
Return a list of all open (RecvChannel, SendChannel) pairs. Return a list of all open channel-end pairs.
The module also provides the following channel-related classes::
class RecvChannel(id):
The receiving end of a channel. An interpreter may use this to
receive objects from another interpreter. At first only a few
of the simple, immutable builtin types will be supported.
id -> int:
The channel's unique ID. This is shared with the "send" end.
interpreters => [Interpreter]:
The list of interpreters associated with the "recv" end of
the channel. That means those that have called the "recv()"
(or "recv_nowait()") method, still hold a reference to the
channel end, and haven't called "release()". If the
channel has been closed then raise
ChannelClosedError.
recv():
Return the next object (i.e. the data from the sent object)
from the channel. If none have been sent then wait until
the next send. This associates the current interpreter
with the "recv" end of the channel.
If the channel is already closed then raise ChannelClosedError.
If the channel isn't closed but the current interpreter already
called the "release()" method for the "recv" end then raise
ChannelReleasedError (which is a subclass of
ChannelClosedError).
recv_nowait(default=None):
Return the next object from the channel. If none have been
sent then return the default. Otherwise, this is the same
as the "recv()" method.
release() -> bool:
No longer associate the current interpreter with the channel
(on the "recv" end) and block any future association (via the
"recv()" or ``recv_nowait()`` methods). If the interpreter
was never associated with the channel then still block any
future association. The "send" end of the channel is
unaffected by a released "recv" end.
Once an interpreter is no longer associated with the "recv"
end of the channel, any "recv()" and "recv_nowait()" calls
from that interpreter will fail (even ongoing calls). See
"recv()" for details.
Once the number of associated interpreters on both ends drops
to 0, the channel is actually marked as closed. The Python
runtime will garbage collect all closed channels, though it
may not happen immediately.
Note that the interpreter automatically loses its association
with the channel end when it is no longer used (i.e. has no
references) in that interpreter, as though "release()"
were called.
This operation is idempotent. Return True if "release()"
has not been called before by the current interpreter.
close(force=False):
Close both ends of the channel (in all interpreters). This
means that any further use of the channel anywhere raises
ChannelClosedError. If the channel is not empty then
raise ChannelNotEmptyError (if "force" is False) or
discard the remaining objects (if "force" is True)
and close it. Note that the behavior of closing
the "send" end is slightly different.
``RecvChannel(id)``:: class SendChannel(id):
The receiving end of a channel. An interpreter may use this to The sending end of a channel. An interpreter may use this to
receive objects from another interpreter. At first only a few of send objects to another interpreter. At first only a few of
the simple, immutable builtin types will be supported. the simple, immutable builtin types will be supported.
id: id -> int:
The channel's unique ID. This is shared with the "send" end. The channel's unique ID. This is shared with the "recv" end.
interpreters: interpreters -> [Interpreter]:
The list of associated interpreters: those that have called Like "RecvChannel.interpreters" but for the "send" end.
the "recv()" method and haven't called "release()" (and the
channel hasn't been explicitly closed).
recv(): send(obj):
Return the next object (i.e. the data from the sent object) from Send the object (i.e. its data) to the "recv" end of the
the channel. If none have been sent then wait until the next channel. Wait until the object is received. If the object
send. This associates the current interpreter with the "recv" is not shareable then ValueError is raised. This associates
end of the channel. the current interpreter with the "send" end of the channel.
If the channel is already closed then raise ChannelClosedError. This associates the current interpreter with the "send" end
If the channel isn't closed but the current interpreter already of the channel. If the channel send was already released
called the "release()" method (which drops its association with by the interpreter then raise ChannelReleasedError. If
the channel) then raise ChannelReleasedError (which is a subclass the channel is already closed then raise
of ChannelClosedError). ChannelClosedError.
recv_nowait(default=None): send_nowait(obj):
Return the next object from the channel. If none have been sent Send the object to the "recv" end of the channel. If no
then return the default. Otherwise, this is the same as the interpreter is currently receiving (waiting on the other
"recv()" method. end) then raise NotReceivedError. Otherwise this is the
same as "send()".
release(): send_buffer(obj):
No longer associate the current interpreter with the channel (on Send a MemoryView of the object rather than the object.
the receiving end) and block future association (via the "recv()" Otherwise this is the same as "send()". Note that the
method). If the interpreter was never associated with the channel object must implement the PEP 3118 buffer protocol.
then still block future association. Once an interpreter is no
longer associated with the channel, subsequent (or current) send()
and recv() calls from that interpreter will raise
ChannelReleasedError (or ChannelClosedError if the channel
is actually marked as closed).
Once the number of associated interpreters on both ends drops send_buffer_nowait(obj):
to 0, the channel is actually marked as closed. The Python
runtime will garbage collect all closed channels, though it may
not be immediately. Note that "release()" is automatically called
on behalf of the current interpreter when the channel is no longer
used (i.e. has no references) in that interpreter.
This operation is idempotent. Return True if "release()" has not Send a MemoryView of the object rather than the object.
been called before by the current interpreter. If the other end is not currently receiving then raise
NotReceivedError. Otherwise this is the same as
"send_buffer()".
close(force=False): release():
Close both ends of the channel (in all interpreters). This means This is the same as "RecvChannel.release(), but applied
that any further use of the channel anywhere raises to the sending end of the channel.
ChannelClosedError. If the channel is not empty then raise
ChannelNotEmptyError (if "force" is False) or discard the
remaining objects (if "force" is True) and close it.
close(force=False):
``SendChannel(id)``:: Close both ends of the channel (in all interpreters). No
matter what the "send" end of the channel is immediately
The sending end of a channel. An interpreter may use this to send closed. If the channel is empty then close the "recv"
objects to another interpreter. At first only a few of end immediately too. Otherwise, if "force" if False,
the simple, immutable builtin types will be supported. close the "recv" end (and hence the full channel)
once the channel becomes empty; or, if "force"
id: is True, discard the remaining items and
close immediately.
The channel's unique ID. This is shared with the "recv" end.
interpreters:
The list of associated interpreters (those that have called
the "send()" method).
send(obj):
Send the object (i.e. its data) to the receiving end of the
channel. Wait until the object is received. If the the
object is not shareable then ValueError is raised. This
associates the current interpreter with the "send" end of the
channel.
If the channel is already closed then raise ChannelClosedError.
If the channel isn't closed but the current interpreter already
called the "release()" method (which drops its association with
the channel) then raise ChannelReleasedError.
send_nowait(obj):
Send the object to the receiving end of the channel. If no
interpreter is currently receiving (waiting on the other end)
then raise NotReceivedError. Otherwise this is the same as
"send()".
send_buffer(obj):
Send a MemoryView of the object rather than the object. Otherwise
this is the same as send(). Note that the object must implement
the PEP 3118 buffer protocol.
send_buffer_nowait(obj):
Send a MemoryView of the object rather than the object. If the
other end is not currently receiving then raise NotReceivedError.
Otherwise this is the same as "send_buffer()".
release():
This is the same as "RecvChannel.release(), but applied to the
sending end of the channel.
close(force=False):
Close both ends of the channel (in all interpreters). No matter
what the "send" end of the channel is immediately closed. If the
channel is empty then close the "recv" end immediately too.
Otherwise, if "force" if False, close the "recv" end (and hence
the full channel) once the channel becomes empty; or, if "force"
is True, discard the remaining items and close immediately.
Note that ``send_buffer()`` is similar to how Note that ``send_buffer()`` is similar to how
``multiprocessing.Connection`` works. [mp-conn]_ ``multiprocessing.Connection`` works. [mp-conn]_