<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>pty — Pseudo-terminal utilities — Python 3.7.10 documentation</title>
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/sidebar.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Python 3.7.10 documentation"
href="../_static/opensearch.xml"/>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="fcntl — The fcntl and ioctl system calls" href="fcntl.html" />
<link rel="prev" title="tty — Terminal control functions" href="tty.html" />
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
<link rel="canonical" href="https://docs.python.org/3/library/pty.html" />
<script type="text/javascript" src="../_static/copybutton.js"></script>
<style>
@media only screen {
table.full-width-table {
width: 100%;
}
}
</style>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="fcntl.html" title="fcntl — The fcntl and ioctl system calls"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="tty.html" title="tty — Terminal control functions"
accesskey="P">previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">3.7.10 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="unix.html" accesskey="U">Unix Specific Services</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-pty">
<span id="pty-pseudo-terminal-utilities"></span><h1><a class="reference internal" href="#module-pty" title="pty: Pseudo-Terminal Handling for Linux. (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pty</span></code></a> — Pseudo-terminal utilities<a class="headerlink" href="#module-pty" title="Permalink to this headline">¶</a></h1>
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/pty.py">Lib/pty.py</a></p>
<hr class="docutils" />
<p>The <a class="reference internal" href="#module-pty" title="pty: Pseudo-Terminal Handling for Linux. (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pty</span></code></a> module defines operations for handling the pseudo-terminal
concept: starting another process and being able to write to and read from its
controlling terminal programmatically.</p>
<p>Because pseudo-terminal handling is highly platform dependent, there is code to
do it only for Linux. (The Linux code is supposed to work on other platforms,
but hasn’t been tested yet.)</p>
<p>The <a class="reference internal" href="#module-pty" title="pty: Pseudo-Terminal Handling for Linux. (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pty</span></code></a> module defines the following functions:</p>
<dl class="function">
<dt id="pty.fork">
<code class="sig-prename descclassname">pty.</code><code class="sig-name descname">fork</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pty.fork" title="Permalink to this definition">¶</a></dt>
<dd><p>Fork. Connect the child’s controlling terminal to a pseudo-terminal. Return
value is <code class="docutils literal notranslate"><span class="pre">(pid,</span> <span class="pre">fd)</span></code>. Note that the child gets <em>pid</em> 0, and the <em>fd</em> is
<em>invalid</em>. The parent’s return value is the <em>pid</em> of the child, and <em>fd</em> is a
file descriptor connected to the child’s controlling terminal (and also to the
child’s standard input and output).</p>
</dd></dl>
<dl class="function">
<dt id="pty.openpty">
<code class="sig-prename descclassname">pty.</code><code class="sig-name descname">openpty</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pty.openpty" title="Permalink to this definition">¶</a></dt>
<dd><p>Open a new pseudo-terminal pair, using <a class="reference internal" href="os.html#os.openpty" title="os.openpty"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.openpty()</span></code></a> if possible, or
emulation code for generic Unix systems. Return a pair of file descriptors
<code class="docutils literal notranslate"><span class="pre">(master,</span> <span class="pre">slave)</span></code>, for the master and the slave end, respectively.</p>
</dd></dl>
<dl class="function">
<dt id="pty.spawn">
<code class="sig-prename descclassname">pty.</code><code class="sig-name descname">spawn</code><span class="sig-paren">(</span><em class="sig-param">argv</em><span class="optional">[</span>, <em class="sig-param">master_read</em><span class="optional">[</span>, <em class="sig-param">stdin_read</em><span class="optional">]</span><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#pty.spawn" title="Permalink to this definition">¶</a></dt>
<dd><p>Spawn a process, and connect its controlling terminal with the current
process’s standard io. This is often used to baffle programs which insist on
reading from the controlling terminal. It is expected that the process
spawned behind the pty will eventually terminate, and when it does <em>spawn</em>
will return.</p>
<p>The functions <em>master_read</em> and <em>stdin_read</em> are passed a file descriptor
which they should read from, and they should always return a byte string. In
order to force spawn to return before the child process exits an
<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> should be thrown.</p>
<p>The default implementation for both functions will read and return up to 1024
bytes each time the function is called. The <em>master_read</em> callback is passed
the pseudoterminal’s master file descriptor to read output from the child
process, and <em>stdin_read</em> is passed file descriptor 0, to read from the
parent process’s standard input.</p>
<p>Returning an empty byte string from either callback is interpreted as an
end-of-file (EOF) condition, and that callback will not be called after
that. If <em>stdin_read</em> signals EOF the controlling terminal can no longer
communicate with the parent process OR the child process. Unless the child
process will quit without any input, <em>spawn</em> will then loop forever. If
<em>master_read</em> signals EOF the same behavior results (on linux at least).</p>
<p>If both callbacks signal EOF then <em>spawn</em> will probably never return, unless
<em>select</em> throws an error on your platform when passed three empty lists. This
is a bug, documented in <a class="reference external" href="https://bugs.python.org/issue26228">issue 26228</a>.</p>
<div class="versionchanged">
<p><span class="versionmodified changed">Changed in version 3.4: </span><a class="reference internal" href="#pty.spawn" title="pty.spawn"><code class="xref py py-func docutils literal notranslate"><span class="pre">spawn()</span></code></a> now returns the status value from <a class="reference internal" href="os.html#os.waitpid" title="os.waitpid"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.waitpid()</span></code></a>
on the child process.</p>
</div>
</dd></dl>
<div class="section" id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
<p>The following program acts like the Unix command <em class="manpage">script(1)</em>, using a
pseudo-terminal to record all input and output of a terminal session in a
“typescript”.</p>
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">argparse</span>
<span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">pty</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">import</span> <span class="nn">time</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-a'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'append'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-p'</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'use_python'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">)</span>
<span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'filename'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'?'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'typescript'</span><span class="p">)</span>
<span class="n">options</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
<span class="n">shell</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">executable</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">use_python</span> <span class="k">else</span> <span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'SHELL'</span><span class="p">,</span> <span class="s1">'sh'</span><span class="p">)</span>
<span class="n">filename</span> <span class="o">=</span> <span class="n">options</span><span class="o">.</span><span class="n">filename</span>
<span class="n">mode</span> <span class="o">=</span> <span class="s1">'ab'</span> <span class="k">if</span> <span class="n">options</span><span class="o">.</span><span class="n">append</span> <span class="k">else</span> <span class="s1">'wb'</span>
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">mode</span><span class="p">)</span> <span class="k">as</span> <span class="n">script</span><span class="p">:</span>
<span class="k">def</span> <span class="nf">read</span><span class="p">(</span><span class="n">fd</span><span class="p">):</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">fd</span><span class="p">,</span> <span class="mi">1024</span><span class="p">)</span>
<span class="n">script</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="k">return</span> <span class="n">data</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'Script started, file is'</span><span class="p">,</span> <span class="n">filename</span><span class="p">)</span>
<span class="n">script</span><span class="o">.</span><span class="n">write</span><span class="p">((</span><span class="s1">'Script started on </span><span class="si">%s</span><span class="se">\n</span><span class="s1">'</span> <span class="o">%</span> <span class="n">time</span><span class="o">.</span><span class="n">asctime</span><span class="p">())</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span>
<span class="n">pty</span><span class="o">.</span><span class="n">spawn</span><span class="p">(</span><span class="n">shell</span><span class="p">,</span> <span class="n">read</span><span class="p">)</span>
<span class="n">script</span><span class="o">.</span><span class="n">write</span><span class="p">((</span><span class="s1">'Script done on </span><span class="si">%s</span><span class="se">\n</span><span class="s1">'</span> <span class="o">%</span> <span class="n">time</span><span class="o">.</span><span class="n">asctime</span><span class="p">())</span><span class="o">.</span><span class="n">encode</span><span class="p">())</span>
<span class="nb">print</span><span class="p">(</span><span class="s1">'Script done, file is'</span><span class="p">,</span> <span class="n">filename</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pty</span></code> — Pseudo-terminal utilities</a><ul>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="tty.html"
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">tty</span></code> — Terminal control functions</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="fcntl.html"
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">fcntl</span></code> — The <code class="docutils literal notranslate"><span class="pre">fcntl</span></code> and <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> system calls</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../bugs.html">Report a Bug</a></li>
<li>
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/pty.rst"
rel="nofollow">Show Source
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="fcntl.html" title="fcntl — The fcntl and ioctl system calls"
>next</a> |</li>
<li class="right" >
<a href="tty.html" title="tty — Terminal control functions"
>previous</a> |</li>
<li><img src="../_static/py.png" alt=""
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a> »</li>
<li>
<a href="../index.html">3.7.10 Documentation</a> »
</li>
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
<li class="nav-item nav-item-2"><a href="unix.html" >Unix Specific Services</a> »</li>
<li class="right">
<div class="inline-search" style="display: none" role="search">
<form class="inline-search" action="../search.html" method="get">
<input placeholder="Quick search" type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('.inline-search').show(0);</script>
|
</li>
</ul>
</div>
<div class="footer">
© <a href="../copyright.html">Copyright</a> 2001-2021, Python Software Foundation.
<br />
The Python Software Foundation is a non-profit corporation.
<a href="https://www.python.org/psf/donations/">Please donate.</a>
<br />
Last updated on Feb 26, 2021.
<a href="../bugs.html">Found a bug</a>?
<br />
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.3.1.
</div>
</body>
</html>
