Init: mediaserver

lib/python3.10/site-packages/dockerpty/__init__.py

@@ -0,0 +1,50 @@
+# dockerpty.
+#
+# 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.
+
+from dockerpty.pty import PseudoTerminal, RunOperation, ExecOperation, exec_create
+
+
+def start(client, container, interactive=True, stdout=None, stderr=None, stdin=None, logs=None):
+    """
+    Present the PTY of the container inside the current process.
+
+    This is just a wrapper for PseudoTerminal(client, container).start()
+    """
+
+    operation = RunOperation(client, container, interactive=interactive, stdout=stdout,
+                             stderr=stderr, stdin=stdin, logs=logs)
+
+    PseudoTerminal(client, operation).start()
+
+
+def exec_command(
+        client, container, command, interactive=True, stdout=None, stderr=None, stdin=None):
+    """
+    Run provided command via exec API in provided container.
+
+    This is just a wrapper for PseudoTerminal(client, container).exec_command()
+    """
+    exec_id = exec_create(client, container, command, interactive=interactive)
+
+    operation = ExecOperation(client, exec_id,
+                              interactive=interactive, stdout=stdout, stderr=stderr, stdin=stdin)
+    PseudoTerminal(client, operation).start()
+
+
+def start_exec(client, exec_id, interactive=True, stdout=None, stderr=None, stdin=None):
+    operation = ExecOperation(client, exec_id,
+                              interactive=interactive, stdout=stdout, stderr=stderr, stdin=stdin)
+    PseudoTerminal(client, operation).start()

lib/python3.10/site-packages/dockerpty/io.py

@@ -0,0 +1,394 @@
+# dockerpty: io.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 os
+import fcntl
+import errno
+import struct
+import select as builtin_select
+import six
+
+
+def set_blocking(fd, blocking=True):
+    """
+    Set the given file-descriptor blocking or non-blocking.
+
+    Returns the original blocking status.
+    """
+
+    old_flag = fcntl.fcntl(fd, fcntl.F_GETFL)
+
+    if blocking:
+        new_flag = old_flag & ~ os.O_NONBLOCK
+    else:
+        new_flag = old_flag | os.O_NONBLOCK
+
+    fcntl.fcntl(fd, fcntl.F_SETFL, new_flag)
+
+    return not bool(old_flag & os.O_NONBLOCK)
+
+
+def select(read_streams, write_streams, timeout=0):
+    """
+    Select the streams from `read_streams` that are ready for reading, and
+    streams from `write_streams` ready for writing.
+
+    Uses `select.select()` internally but only returns two lists of ready streams.
+    """
+
+    exception_streams = []
+
+    try:
+        return builtin_select.select(
+            read_streams,
+            write_streams,
+            exception_streams,
+            timeout,
+        )[0:2]
+    except builtin_select.error as e:
+        # POSIX signals interrupt select()
+        no = e.errno if six.PY3 else e[0]
+        if no == errno.EINTR:
+            return ([], [])
+        else:
+            raise e
+
+
+class Stream(object):
+    """
+    Generic Stream class.
+
+    This is a file-like abstraction on top of os.read() and os.write(), which
+    add consistency to the reading of sockets and files alike.
+    """
+
+    """
+    Recoverable IO/OS Errors.
+    """
+    ERRNO_RECOVERABLE = [
+        errno.EINTR,
+        errno.EDEADLK,
+        errno.EWOULDBLOCK,
+    ]
+
+    def __init__(self, fd):
+        """
+        Initialize the Stream for the file descriptor `fd`.
+
+        The `fd` object must have a `fileno()` method.
+        """
+        self.fd = fd
+        self.buffer = b''
+        self.close_requested = False
+        self.closed = False
+
+    def fileno(self):
+        """
+        Return the fileno() of the file descriptor.
+        """
+
+        return self.fd.fileno()
+
+    def set_blocking(self, value):
+        if hasattr(self.fd, 'setblocking'):
+            self.fd.setblocking(value)
+            return True
+        else:
+            return set_blocking(self.fd, value)
+
+    def read(self, n=4096):
+        """
+        Return `n` bytes of data from the Stream, or None at end of stream.
+        """
+
+        while True:
+            try:
+                if hasattr(self.fd, 'recv'):
+                    return self.fd.recv(n)
+                return os.read(self.fd.fileno(), n)
+            except EnvironmentError as e:
+                if e.errno not in Stream.ERRNO_RECOVERABLE:
+                    raise e
+
+
+    def write(self, data):
+        """
+        Write `data` to the Stream. Not all data may be written right away.
+        Use select to find when the stream is writeable, and call do_write()
+        to flush the internal buffer.
+        """
+
+        if not data:
+            return None
+
+        self.buffer += data
+        self.do_write()
+
+        return len(data)
+
+    def do_write(self):
+        """
+        Flushes as much pending data from the internal write buffer as possible.
+        """
+        while True:
+            try:
+                written = 0
+
+                if hasattr(self.fd, 'send'):
+                    written = self.fd.send(self.buffer)
+                else:
+                    written = os.write(self.fd.fileno(), self.buffer)
+
+                self.buffer = self.buffer[written:]
+
+                # try to close after writes if a close was requested
+                if self.close_requested and len(self.buffer) == 0:
+                    self.close()
+
+                return written
+            except EnvironmentError as e:
+                if e.errno not in Stream.ERRNO_RECOVERABLE:
+                    raise e
+
+    def needs_write(self):
+        """
+        Returns True if the stream has data waiting to be written.
+        """
+        return len(self.buffer) > 0
+
+    def close(self):
+        self.close_requested = True
+
+        # We don't close the fd immediately, as there may still be data pending
+        # to write.
+        if not self.closed and len(self.buffer) == 0:
+            self.closed = True
+            if hasattr(self.fd, 'close'):
+                self.fd.close()
+            else:
+                os.close(self.fd.fileno())
+
+    def __repr__(self):
+        return "{cls}({fd})".format(cls=type(self).__name__, fd=self.fd)
+
+
+class Demuxer(object):
+    """
+    Wraps a multiplexed Stream to read in data demultiplexed.
+
+    Docker multiplexes streams together when there is no PTY attached, by
+    sending an 8-byte header, followed by a chunk of data.
+
+    The first 4 bytes of the header denote the stream from which the data came
+    (i.e. 0x01 = stdout, 0x02 = stderr). Only the first byte of these initial 4
+    bytes is used.
+
+    The next 4 bytes indicate the length of the following chunk of data as an
+    integer in big endian format. This much data must be consumed before the
+    next 8-byte header is read.
+    """
+
+    def __init__(self, stream):
+        """
+        Initialize a new Demuxer reading from `stream`.
+        """
+
+        self.stream = stream
+        self.remain = 0
+
+    def fileno(self):
+        """
+        Returns the fileno() of the underlying Stream.
+
+        This is useful for select() to work.
+        """
+
+        return self.stream.fileno()
+
+    def set_blocking(self, value):
+        return self.stream.set_blocking(value)
+
+    def read(self, n=4096):
+        """
+        Read up to `n` bytes of data from the Stream, after demuxing.
+
+        Less than `n` bytes of data may be returned depending on the available
+        payload, but the number of bytes returned will never exceed `n`.
+
+        Because demuxing involves scanning 8-byte headers, the actual amount of
+        data read from the underlying stream may be greater than `n`.
+        """
+
+        size = self._next_packet_size(n)
+
+        if size <= 0:
+            return
+        else:
+            data = six.binary_type()
+            while len(data) < size:
+                nxt = self.stream.read(size - len(data))
+                if not nxt:
+                    # the stream has closed, return what data we got
+                    return data
+                data = data + nxt
+            return data
+
+    def write(self, data):
+        """
+        Delegates the the underlying Stream.
+        """
+
+        return self.stream.write(data)
+
+    def needs_write(self):
+        """
+        Delegates to underlying Stream.
+        """
+
+        if hasattr(self.stream, 'needs_write'):
+            return self.stream.needs_write()
+
+        return False
+
+    def do_write(self):
+        """
+        Delegates to underlying Stream.
+        """
+
+        if hasattr(self.stream, 'do_write'):
+            return self.stream.do_write()
+
+        return False
+
+    def close(self):
+        """
+        Delegates to underlying Stream.
+        """
+
+        return self.stream.close()
+
+    def _next_packet_size(self, n=0):
+        size = 0
+
+        if self.remain > 0:
+            size = min(n, self.remain)
+            self.remain -= size
+        else:
+            data = six.binary_type()
+            while len(data) < 8:
+                nxt = self.stream.read(8 - len(data))
+                if not nxt:
+                    # The stream has closed, there's nothing more to read
+                    return 0
+                data = data + nxt
+
+            if data is None:
+                return 0
+            if len(data) == 8:
+                __, actual = struct.unpack('>BxxxL', data)
+                size = min(n, actual)
+                self.remain = actual - size
+
+        return size
+
+    def __repr__(self):
+        return "{cls}({stream})".format(cls=type(self).__name__,
+                                        stream=self.stream)
+
+
+class Pump(object):
+    """
+    Stream pump class.
+
+    A Pump wraps two Streams, reading from one and and writing its data into
+    the other, much like a pipe but manually managed.
+
+    This abstraction is used to facilitate piping data between the file
+    descriptors associated with the tty and those associated with a container's
+    allocated pty.
+
+    Pumps are selectable based on the 'read' end of the pipe.
+    """
+
+    def __init__(self,
+                 from_stream,
+                 to_stream,
+                 wait_for_output=True,
+                 propagate_close=True):
+        """
+        Initialize a Pump with a Stream to read from and another to write to.
+
+        `wait_for_output` is a flag that says that we need to wait for EOF
+        on the from_stream in order to consider this pump as "done".
+        """
+
+        self.from_stream = from_stream
+        self.to_stream = to_stream
+        self.eof = False
+        self.wait_for_output = wait_for_output
+        self.propagate_close = propagate_close
+
+    def fileno(self):
+        """
+        Returns the `fileno()` of the reader end of the Pump.
+
+        This is useful to allow Pumps to function with `select()`.
+        """
+
+        return self.from_stream.fileno()
+
+    def set_blocking(self, value):
+        return self.from_stream.set_blocking(value)
+
+    def flush(self, n=4096):
+        """
+        Flush `n` bytes of data from the reader Stream to the writer Stream.
+
+        Returns the number of bytes that were actually flushed. A return value
+        of zero is not an error.
+
+        If EOF has been reached, `None` is returned.
+        """
+
+        try:
+            read = self.from_stream.read(n)
+
+            if read is None or len(read) == 0:
+                self.eof = True
+                if self.propagate_close:
+                    self.to_stream.close()
+                return None
+
+            return self.to_stream.write(read)
+        except OSError as e:
+            if e.errno != errno.EPIPE:
+                raise e
+
+    def is_done(self):
+        """
+        Returns True if the read stream is done (either it's returned EOF or
+        the pump doesn't have wait_for_output set), and the write
+        side does not have pending bytes to send.
+        """
+
+        return (not self.wait_for_output or self.eof) and \
+                not (hasattr(self.to_stream, 'needs_write') and self.to_stream.needs_write())
+
+    def __repr__(self):
+        return "{cls}(from={from_stream}, to={to_stream})".format(
+            cls=type(self).__name__,
+            from_stream=self.from_stream,
+            to_stream=self.to_stream)

lib/python3.10/site-packages/dockerpty/pty.py

@@ -0,0 +1,380 @@
+# 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

lib/python3.10/site-packages/dockerpty/tty.py

@@ -0,0 +1,130 @@
+# dockerpty: tty.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.
+
+from __future__ import absolute_import
+
+import os
+import termios
+import tty
+import fcntl
+import struct
+
+
+def size(fd):
+    """
+    Return a tuple (rows,cols) representing the size of the TTY `fd`.
+
+    The provided file descriptor should be the stdout stream of the TTY.
+
+    If the TTY size cannot be determined, returns None.
+    """
+
+    if not os.isatty(fd.fileno()):
+        return None
+
+    try:
+        dims = struct.unpack('hh', fcntl.ioctl(fd, termios.TIOCGWINSZ, 'hhhh'))
+    except:
+        try:
+            dims = (os.environ['LINES'], os.environ['COLUMNS'])
+        except:
+            return None
+
+    return dims
+
+
+class Terminal(object):
+    """
+    Terminal provides wrapper functionality to temporarily make the tty raw.
+
+    This is useful when streaming data from a pseudo-terminal into the tty.
+
+    Example:
+
+        with Terminal(sys.stdin, raw=True):
+            do_things_in_raw_mode()
+    """
+
+    def __init__(self, fd, raw=True):
+        """
+        Initialize a terminal for the tty with stdin attached to `fd`.
+
+        Initializing the Terminal has no immediate side effects. The `start()`
+        method must be invoked, or `with raw_terminal:` used before the
+        terminal is affected.
+        """
+
+        self.fd = fd
+        self.raw = raw
+        self.original_attributes = None
+
+
+    def __enter__(self):
+        """
+        Invoked when a `with` block is first entered.
+        """
+
+        self.start()
+        return self
+
+
+    def __exit__(self, *_):
+        """
+        Invoked when a `with` block is finished.
+        """
+
+        self.stop()
+
+
+    def israw(self):
+        """
+        Returns True if the TTY should operate in raw mode.
+        """
+
+        return self.raw
+
+
+    def start(self):
+        """
+        Saves the current terminal attributes and makes the tty raw.
+
+        This method returns None immediately.
+        """
+
+        if os.isatty(self.fd.fileno()) and self.israw():
+            self.original_attributes = termios.tcgetattr(self.fd)
+            tty.setraw(self.fd)
+
+
+    def stop(self):
+        """
+        Restores the terminal attributes back to before setting raw mode.
+
+        If the raw terminal was not started, does nothing.
+        """
+
+        if self.original_attributes is not None:
+            termios.tcsetattr(
+                self.fd,
+                termios.TCSADRAIN,
+                self.original_attributes,
+            )
+
+    def __repr__(self):
+        return "{cls}({fd}, raw={raw})".format(
+            cls=type(self).__name__,
+            fd=self.fd,
+            raw=self.raw)