Skip to content

Commit

Permalink
Tutorial: add info about non-blocking !() (#5449)
Browse files Browse the repository at this point in the history
Closes #3394

### Motivation

After reading [the history of threading and
operators](#5444) I realized that
this was intended, to make the `!()` operator non-blocking. So let's
write about this in tutorial.

### Next steps

In the future we need to solve these points:
* Confusion around `.output` and `.out`.
* Show good cases where non-blocking is doing perfect work to people. Or
remove the non-blocking functionality [to remove
threading](#4710).

## For community
⬇️ **Please click the 👍 reaction instead of leaving a `+1` or 👍
comment**

---------

Co-authored-by: a <1@1.1>
Co-authored-by: Gil Forsyth <gforsyth@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
  • Loading branch information
4 people committed May 28, 2024
1 parent b55e6a4 commit 499bbf8
Showing 1 changed file with 27 additions and 6 deletions.
33 changes: 27 additions & 6 deletions docs/tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -387,23 +387,44 @@ input and output were redirected. For example:
>>> !(ls nonexistent_directory)
CommandPipeline(
stdin=<_io.BytesIO object at 0x7f1948182bf8>,
stdout=<_io.BytesIO object at 0x7f1948182af0>,
stderr=<_io.BytesIO object at 0x7f19483a6200>,
pid=26968,
returncode=2,
args=['ls', 'nonexistent_directory'],
alias=['ls', '--color=auto', '-v'],
stdin_redirect=['<stdin>', 'r'],
stdout_redirect=[9, 'wb'],
stderr_redirect=[11, 'w'],
timestamps=[1485235484.5016758, None],
executed_cmd=['ls', '--color=auto', '-v', 'nonexistent_directory'],
input=None,
output=,
errors=None
)
The captured object ``!()`` operator allows for non-blocking execution.
You can call a long-running command, intersperse other commands and
read the captured output later:

.. code-block:: xonshcon
>>> p = !(echo snail)
>>> p.output
''
>>> p.end()
>>> p.output
'snail'
You can force ``xonsh`` to block and wait for the command to complete by asking for the return code,
printing the object or reading the ``out`` attribute:

.. code-block:: xonshcon
>>> p = !(echo snail)
>>> p.out
'snail'
>>> p = !(echo party)
>>> p.rtn
0
>>> p.output
'party'
This object will be "truthy" if its return code was 0, and it is equal (via
``==``) to its return code. It also hashes to its return code. Converting the object
to the string will return the output. This allows for some interesting new
Expand Down

0 comments on commit 499bbf8

Please sign in to comment.