# dockerpty: pty.py
#
# Copyright 2014 Chris Corbyn <chris@w3style.co.uk>
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
import sys
import signal
import warnings
from ssl import SSLError
import dockerpty.io as io
import dockerpty.tty as tty
class WINCHHandler(object):
"""
WINCH Signal handler to keep the PTY correctly sized.
"""
def __init__(self, pty):
"""
Initialize a new WINCH handler for the given PTY.
Initializing a handler has no immediate side-effects. The `start()`
method must be invoked for the signals to be trapped.
"""
self.pty = pty
self.original_handler = None
def __enter__(self):
"""
Invoked on entering a `with` block.
"""
self.start()
return self
def __exit__(self, *_):
"""
Invoked on exiting a `with` block.
"""
self.stop()
def start(self):
"""
Start trapping WINCH signals and resizing the PTY.
This method saves the previous WINCH handler so it can be restored on
`stop()`.
"""
def handle(signum, frame):
if signum == signal.SIGWINCH:
self.pty.resize()
self.original_handler = signal.signal(signal.SIGWINCH, handle)
def stop(self):
"""
Stop trapping WINCH signals and restore the previous WINCH handler.
"""
if self.original_handler is not None:
signal.signal(signal.SIGWINCH, self.original_handler)
class Operation(object):
def israw(self, **kwargs):
"""
are we dealing with a tty or not?
"""
raise NotImplementedError()
def start(self, **kwargs):
"""
start execution
"""
raise NotImplementedError()
def resize(self, height, width, **kwargs):
"""
if we have terminal, resize it
"""
raise NotImplementedError()
def sockets(self):
"""Return sockets for streams."""
raise NotImplementedError()
class RunOperation(Operation):
"""
class for handling `docker run`-like command
"""
def __init__(self, client, container, interactive=True, stdout=None, stderr=None, stdin=None, logs=None):
"""
Initialize the PTY using the docker.Client instance and container dict.
"""
if logs is None:
warnings.warn("The default behaviour of dockerpty is changing. Please add logs=1 to your dockerpty.start call to maintain existing behaviour. See https://github.com/d11wtq/dockerpty/issues/51 for details.", DeprecationWarning)
logs = 1
self.client = client
self.container = container
self.raw = None
self.interactive = interactive
self.stdout = stdout or sys.stdout
self.stderr = stderr or sys.stderr
self.stdin = stdin or sys.stdin
self.logs = logs
def start(self, sockets=None, **kwargs):
"""
Present the PTY of the container inside the current process.
This will take over the current process' TTY until the container's PTY
is closed.
"""
pty_stdin, pty_stdout, pty_stderr = sockets or self.sockets()
pumps = []
if pty_stdin and self.interactive:
pumps.append(io.Pump(io.Stream(self.stdin), pty_stdin, wait_for_output=False))
if pty_stdout:
pumps.append(io.Pump(pty_stdout, io.Stream(self.stdout), propagate_close=False))
if pty_stderr:
pumps.append(io.Pump(pty_stderr, io.Stream(self.stderr), propagate_close=False))
if not self._container_info()['State']['Running']:
self.client.start(self.container, **kwargs)
return pumps
def israw(self, **kwargs):
"""
Returns True if the PTY should operate in raw mode.
If the container was not started with tty=True, this will return False.
"""
if self.raw is None:
info = self._container_info()
self.raw = self.stdout.isatty() and info['Config']['Tty']
return self.raw
def sockets(self):
"""
Returns a tuple of sockets connected to the pty (stdin,stdout,stderr).
If any of the sockets are not attached in the container, `None` is
returned in the tuple.
"""
info = self._container_info()
def attach_socket(key):
if info['Config']['Attach{0}'.format(key.capitalize())]:
socket = self.client.attach_socket(
self.container,
{key: 1, 'stream': 1, 'logs': self.logs},
)
stream = io.Stream(socket)
if info['Config']['Tty']:
return stream
else:
return io.Demuxer(stream)
else:
return None
return map(attach_socket, ('stdin', 'stdout', 'stderr'))
def resize(self, height, width, **kwargs):
"""
resize pty within container
"""
self.client.resize(self.container, height=height, width=width)
def _container_info(self):
"""
Thin wrapper around client.inspect_container().
"""
return self.client.inspect_container(self.container)
def exec_create(client, container, command, interactive=True):
exec_id = client.exec_create(container, command, tty=interactive, stdin=interactive)
return exec_id
class ExecOperation(Operation):
"""
class for handling `docker exec`-like command
"""
def __init__(self, client, exec_id, interactive=True, stdout=None, stderr=None, stdin=None):
self.exec_id = exec_id
self.client = client
self.raw = None
self.interactive = interactive
self.stdout = stdout or sys.stdout
self.stderr = stderr or sys.stderr
self.stdin = stdin or sys.stdin
self._info = None
def start(self, sockets=None, **kwargs):
"""
start execution
"""
stream = sockets or self.sockets()
pumps = []
if self.interactive:
pumps.append(io.Pump(io.Stream(self.stdin), stream, wait_for_output=False))
pumps.append(io.Pump(stream, io.Stream(self.stdout), propagate_close=False))
# FIXME: since exec_start returns a single socket, how do we
# distinguish between stdout and stderr?
# pumps.append(io.Pump(stream, io.Stream(self.stderr), propagate_close=False))
return pumps
def israw(self, **kwargs):
"""
Returns True if the PTY should operate in raw mode.
If the exec was not started with tty=True, this will return False.
"""
if self.raw is None:
self.raw = self.stdout.isatty() and self.is_process_tty()
return self.raw
def sockets(self):
"""
Return a single socket which is processing all I/O to exec
"""
socket = self.client.exec_start(self.exec_id, socket=True, tty=self.interactive)
stream = io.Stream(socket)
if self.is_process_tty():
return stream
else:
return io.Demuxer(stream)
def resize(self, height, width, **kwargs):
"""
resize pty of an execed process
"""
self.client.exec_resize(self.exec_id, height=height, width=width)
def is_process_tty(self):
"""
does execed process have allocated tty?
"""
return self._exec_info()["ProcessConfig"]["tty"]
def _exec_info(self):
"""
Caching wrapper around client.exec_inspect
"""
if self._info is None:
self._info = self.client.exec_inspect(self.exec_id)
return self._info
class PseudoTerminal(object):
"""
Wraps the pseudo-TTY (PTY) allocated to a docker container.
The PTY is managed via the current process' TTY until it is closed.
Example:
import docker
from dockerpty import PseudoTerminal
client = docker.Client()
container = client.create_container(
image='busybox:latest',
stdin_open=True,
tty=True,
command='/bin/sh',
)
# hijacks the current tty until the pty is closed
PseudoTerminal(client, container).start()
Care is taken to ensure all file descriptors are restored on exit. For
example, you can attach to a running container from within a Python REPL
and when the container exits, the user will be returned to the Python REPL
without adverse effects.
"""
def __init__(self, client, operation):
"""
Initialize the PTY using the docker.Client instance and container dict.
"""
self.client = client
self.operation = operation
def sockets(self):
return self.operation.sockets()
def start(self, sockets=None):
pumps = self.operation.start(sockets=sockets)
flags = [p.set_blocking(False) for p in pumps]
try:
with WINCHHandler(self):
self._hijack_tty(pumps)
finally:
if flags:
for (pump, flag) in zip(pumps, flags):
io.set_blocking(pump, flag)
def resize(self, size=None):
"""
Resize the container's PTY.
If `size` is not None, it must be a tuple of (height,width), otherwise
it will be determined by the size of the current TTY.
"""
if not self.operation.israw():
return
size = size or tty.size(self.operation.stdout)
if size is not None:
rows, cols = size
try:
self.operation.resize(height=rows, width=cols)
except IOError: # Container already exited
pass
def _hijack_tty(self, pumps):
with tty.Terminal(self.operation.stdin, raw=self.operation.israw()):
self.resize()
while True:
read_pumps = [p for p in pumps if not p.eof]
write_streams = [p.to_stream for p in pumps if p.to_stream.needs_write()]
read_ready, write_ready = io.select(read_pumps, write_streams, timeout=60)
try:
for write_stream in write_ready:
write_stream.do_write()
for pump in read_ready:
pump.flush()
if all([p.is_done() for p in pumps]):
break
except SSLError as e:
if 'The operation did not complete' not in e.strerror:
raise e
