Skip to content

gh-76785: Multiple Interpreters in the Stdlib (PEP 554) #18817

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
nanjekyejoannah wants to merge 21 commits into from
Closed

gh-76785: Multiple Interpreters in the Stdlib (PEP 554) #18817

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
f5b464a
Add tests for the interpreters module
nanjekyejoannah Sep 10, 2019
331be62
create stdlib interpreters module and _interpreters internal module
nanjekyejoannah Sep 10, 2019
3f2f2f4
Global initial Sub-Interpreters functions
nanjekyejoannah Sep 10, 2019
4618343
update __all__
nanjekyejoannah Sep 10, 2019
ec63183
Implementation of all methods and relevant documentation
nanjekyejoannah Sep 12, 2019
80f6808
Update Lib/test/test_interpreters.py
nanjekyejoannah Sep 13, 2019
724e618
Update Lib/test/test_interpreters.py
nanjekyejoannah Sep 13, 2019
abd0011
Update Lib/test/test_interpreters.py
nanjekyejoannah Sep 13, 2019
d502415
Update Lib/test/test_interpreters.py
nanjekyejoannah Sep 13, 2019
a751e15
Update Doc/library/interpreters.rst
nanjekyejoannah Sep 13, 2019
56083c2
Update Doc/library/interpreters.rst
nanjekyejoannah Sep 13, 2019
14e97fc
Update Doc/library/interpreters.rst
nanjekyejoannah Sep 13, 2019
9ab54eb
Add tests
nanjekyejoannah Sep 13, 2019
b7dce73
Fix tests
nanjekyejoannah Mar 3, 2020
e9b56b8
Add send buffer functionality
nanjekyejoannah Mar 4, 2020
2bf89d4
Add tests for Global functions and Interpreter
nanjekyejoannah Mar 5, 2020
158e54f
Test coverage and documentation
nanjekyejoannah Mar 6, 2020
9e2f9d6
📜🤖 Added by blurb_it.
blurb-it[bot] Mar 6, 2020
2e608fb
Fix Merge conflict
Mar 6, 2020
71ad4d7
Update Doc/library/interpreters.rst
nanjekyejoannah May 7, 2020
b12e3d2
Update Doc/library/interpreters.rst
nanjekyejoannah May 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Test coverage and documentation
  • Loading branch information
@nanjekyejoannah
nanjekyejoannah committed Mar 6, 2020
commit 158e54fe848308287c66c6cc65683e46b3aae990
92 changes: 53 additions & 39 deletions Doc/library/interpreters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the module going to be provisional still in 3.9 or is this going to be part of the stable API? If it's going to be provisional, I think it could include a note in the header to explain that.

--------------

This module provides highlevel tools for working with sub-interpreters,
This module provides highlevel tools for working with sub-interpreters,
Comment thread
nanjekyejoannah marked this conversation as resolved.
Outdated
such as creating them, running code in them, or sending data between them.
It is a wrapper around the low-level :mod:`_interpreters` module.
Comment thread
nanjekyejoannah marked this conversation as resolved.
Outdated

Expand All @@ -25,16 +25,18 @@ The Interpreter object represents a single interpreter.
.. method:: is_running()

Return whether or not the identified interpreter is running.
It returns `True` and `False` otherwise.
Comment on lines +25 to +28
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, this could be better phrased as:

Return `True` if the identified interpreter is running.

For comparison, see https://docs.python.org/3/library/asyncio-eventloop.html#asyncio.loop.is_running or https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.Future.cancelled.


.. method:: destroy()

Destroy the identified interpreter. Attempting to destroy the current
interpreter results in a RuntimeError. So does an unrecognized ID.
Destroy the interpreter. Attempting to destroy the current
interpreter results in a `RuntimeError`.
Comment on lines +30 to +33
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IIRC, it also results in a RuntimeError if an interpreter is attempted to be destroyed which is presently running (from my recollection of the C-API function, interp_destroy()). Could this also be mentioned?


.. method:: run(self, src_str, /, *, channels=None):

Run the given source code in the interpreter. This blocks the current
thread until done.
Run the given source code in the interpreter. This blocks
the current thread until done. `channels` should be in
the form : `(RecvChannel, SendChannel)`.

RecvChannel Objects
-------------------
Expand All @@ -47,68 +49,78 @@ The RecvChannel object represents a recieving channel.

.. method:: recv()

Get the next object from the channel, and wait if none have been
sent. Associate the interpreter with the channel.
Get the next object from the channel, and wait if
none have been sent. Associate the interpreter
with the channel.

.. method:: recv_nowait(default=None)

Like ``recv()``, but return the default instead of waiting.
Like ``recv()``, but return the default result
instead of waiting.

.. method:: release()
.. method:: release()

Close the channel for the current interpreter. 'send' and 'recv' (bool) may
be used to indicate the ends to close. By default both ends are closed.
Closing an already closed end is a noop.
Release the channel for the current interpreter.
By default both ends are released. Releasing an already
released end results in a ``ChannelReleasedError`` exception.
Comment on lines +61 to +65
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, the second sentence could be better phrased as:

Releasing an end more than once results in a
:exc:`ChannelReleasedError`.

(Also added a Sphinx role, which should generate an inline link to the exception definition below)


.. method:: close(force=False)

Close the channel in all interpreters.
Close the channel in all interpreters. By default
both ends are closed. closing an already closed end
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
both ends are closed. closing an already closed end
both ends are closed. Closing an already closed end

results in a ``ChannelClosedError`` exception. Without
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
results in a ``ChannelClosedError`` exception. Without
results in a :exc:`ChannelClosedError` exception. Without

seeting ``force`` to ``True`` a ``ChannelNotEmptyError``
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Grammar fix and changed parameter name to use italics instead of backticks. Also adds sphinx role.

Suggested change
seeting ``force`` to ``True`` a ``ChannelNotEmptyError``
setting *force* to ``True``, a :exc:`ChannelNotEmptyError`

will be returned when a channel with data is closed.
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
will be returned when a channel with data is closed.
will be raised when a channel with data is closed.



SendChannel Objects
--------------------

The SendChannel object represents a sending channel.
The ``SendChannel`` object represents a sending channel.

.. class:: SendChannel(id)

This class represents the receiving end of a channel.
This class represents the sending end of a channel.

.. method:: send(obj)

Send the object (i.e. its data) to the receiving end of the channel
and wait.Associate the interpreter with the channel.
Send the object ``obj`` to the receiving end of the channel
and wait. Associate the interpreter with the channel.

.. method:: send_nowait(obj)

Like ``send()``, but return False if not received.
Like ``send()`` but return ``False`` if not received.
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Phrasing suggestion and clarification:

Suggested change
Like ``send()`` but return ``False`` if not received.
Similar to ``send()``, but returns ``False`` if
*obj* is not immediately received instead of blocking.


.. method:: send_buffer(obj)

Send the object's buffer to the receiving end of the channel and wait.
Associate the interpreter with the channel.
Send the object's buffer to the receiving end of the
channel and wait. Associate the interpreter with the
channel.

.. method:: send_buffer_nowait(obj)

Like ``send_buffer()``, but return False if not received.
Like ``send_buffer()`` but return ``False`` if not received.
Comment on lines +100 to +102
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my above comment on send_nowait().


.. method:: release()

Close the channel for the current interpreter. 'send' and 'recv' (bool) may
be used to indicate the ends to close. By default both ends are closed.
Closing an already closed end is a noop.
Release the channel for the current interpreter.
By default both ends are released. Releasing an already
released end results in a ``ChannelReleasedError`` exception.
Comment thread
nanjekyejoannah marked this conversation as resolved.

.. method:: close(force=False)

Close the channel in all interpreters.
Close the channel in all interpreters. By default
both ends are closed. closing an already closed end
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
both ends are closed. closing an already closed end
both ends are closed. Closing an already closed end

results in a ``ChannelClosedError`` exception.
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
results in a ``ChannelClosedError`` exception.
results in a :exc:`ChannelClosedError`.



This module defines the following global functions:


.. function:: is_shareable(obj)

Return `True` if the object's data can be shared between interpreters.
Return ``True`` if the object's data can be shared between
interpreters.

.. function:: create_channel()

Expand All @@ -120,16 +132,18 @@ This module defines the following global functions:

.. function:: create()

Initialize a new (idle) Python interpreter.
Initialize a new (idle) Python interpreter. Get the currently
running interpreter. This method returns an ``Interpreter`` object.
Comment on lines +133 to +136
Copy link
Copy Markdown
Contributor

@aeros aeros Mar 8, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was "Get the currently running interpreter" accidentally included here?


.. function:: get_current()

Get the currently running interpreter. This method returns
an `interpreter` object.
an ``Interpreter`` object.

.. function:: list_all()

Get all existing interpreters.
Get all existing interpreters. Returns a list
of ``Interpreter`` objects.

This module also defines the following exceptions.

Expand All @@ -140,35 +154,35 @@ This module also defines the following exceptions.

.. exception:: ChannelError

This exception, a subclass of :exc:`Exception`, and is the base class for
channel-related exceptions.
This exception is a subclass of :exc:`Exception`, and is the base
class for all channel-related exceptions.

.. exception:: ChannelNotFoundError

This exception, a subclass of :exc:`ChannelError`, is raised when the
the identified channel was not found.
This exception is a subclass of :exc:`ChannelError`, and is raised
when the the identified channel is not found.

.. exception:: ChannelEmptyError

This exception, a subclass of :exc:`ChannelError`, is raised when
This exception is a subclass of :exc:`ChannelError`, and is raised when
the channel is unexpectedly empty.

.. exception:: ChannelNotEmptyError

This exception, a subclass of :exc:`ChannelError`, is raised when
This exception is a subclass of :exc:`ChannelError`, and is raised when
the channel is unexpectedly not empty.

.. exception:: NotReceivedError

This exception, a subclass of :exc:`ChannelError`, is raised when
This exception is a subclass of :exc:`ChannelError`, and is raised when
nothing was waiting to receive a sent object.

.. exception:: ChannelClosedError

This exception, a subclass of :exc:`ChannelError`, is raised when
This exception is a subclass of :exc:`ChannelError`, and is raised when
the channel is closed.

.. exception:: ChannelReleasedError

This exception, a subclass of :exc:`ChannelClosedError`, is raised when
the channel is released (but not yet closed).
This exception is a subclass of :exc:`ChannelClosedError`, and is raised
when the channel is released (but not yet closed).
Loading