# Docker PTY
Provides the functionality needed to operate the pseudo-tty (PTY) allocated to
a docker container, using the Python client.
[]
(https://travis-ci.org/d11wtq/dockerpty)
## Installation
Via pip:
```
pip install dockerpty
```
Dependencies:
* docker-py>=0.3.2
However, this library does not explicitly declare this dependency in PyPi for a
number of reasons. It is assumed you have it installed.
## Usage
The following example will run busybox in a docker container and place the user
at the shell prompt via Python.
This obviously only works when run in a terminal.
``` python
import docker
import dockerpty
client = docker.Client()
container = client.create_container(
image='busybox:latest',
stdin_open=True,
tty=True,
command='/bin/sh',
)
dockerpty.start(client, container)
```
Keyword arguments passed to `start()` will be forwarded onto the client to
start the container.
When the dockerpty is started, control is yielded to the container's PTY until
the container exits, or the container's PTY is closed.
This is a safe operation and all resources are restored back to their original
states.
> **Note:** dockerpty does support attaching to non-tty containers to stream
container output, though it is obviously not possible to 'control' the
container if you do not allocate a pseudo-tty.
If you press `C-p C-q`, the container's PTY will be closed, but the container
will keep running. In other words, you will have detached from the container
and can re-attach with another `dockerpty.start()` call.
## Tests
If you want to hack on dockerpty and send a PR, you'll need to run the tests.
In the features/ directory, are features/user stories for how dockerpty is
supposed to work. To run them:
```
-bash$ pip install -r requirements-dev.txt
-bash$ behave features/
```
You'll need to have docker installed and running locally. The tests use busybox
container as a test fixture, so are not too heavy.
Step definitions are defined in features/steps/.
There are also unit tests for the parts of the code that are not inherently
dependent on controlling a TTY. To run those:
```
-bash$ pip install -r requirements-dev.txt
-bash$ py.test tests/
```
Travis CI runs this build inside a UML kernel that is new enough to run docker.
Your PR will need to pass the build before I can merge it.
- Travis CI build: https://travis-ci.org/d11wtq/dockerpty
## How it works
In a terminal, the three file descriptors stdin, stdout and stderr are all
connected to the controlling terminal (TTY). When you pass the `tty=True` flag
to docker's `create_container()`, docker allocates a fake TTY inside the
container (a PTY) to which the container's stdin, stdout and stderr are all
connected.
The docker API provides a way to access the three sockets connected to the PTY.
If with access to the host system's TTY file descriptors and the container's
PTY file descriptors, it is trivial to simply 'pipe' data written to these file
descriptors between the host and the container. Doing this makes the user's
terminal effectively become the pseudo-terminal from inside the container.
In reality it's a bit more complicated than this, since care must be taken to
put the host terminal into raw mode (where keys such as enter are not
interpreted with any special meaning) and restore it on exit. Additionally, the
container's stdout and stderr streams along with `sys.stdin` must be made
non-blocking so that they can be used with `select()` without blocking the main
process. These attributes are restored on exit.
The size of a terminal cannot be controlled by sending data to stdin and can
only be controlled by the terminal program itself. Since the pseudo-terminal is
running inside a real terminal, it is import that the size of the PTY be kept
the same as that of the presenting TTY. For this reason, docker provides an API
call to resize the allocated PTY. A SIGWINCH handler is used to detect window
size changes and resize the pseudo-terminal as needed.
## Contributors
- Primary author: [Chris Corbyn](https://github.com/d11wtq)
- Collaborator: [Daniel Nephin](https://github.com/dnephin)
- Contributor: [Stephen Moore](https://github.com/delfick)
- Contributor: [Ben Firshman](https://github.com/bfirsh)
## Copyright & Licensing
Copyright © 2014 Chris Corbyn. See the LICENSE.txt file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/d11wtq/dockerpty",
"name": "dockerpty",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "docker,tty,pty,terminal",
"author": "Chris Corbyn",
"author_email": "chris@w3style.co.uk",
"download_url": "https://files.pythonhosted.org/packages/8d/ee/e9ecce4c32204a6738e0a5d5883d3413794d7498fe8b06f44becc028d3ba/dockerpty-0.4.1.tar.gz",
"platform": "UNKNOWN",
"description": "# Docker PTY\n\nProvides the functionality needed to operate the pseudo-tty (PTY) allocated to\na docker container, using the Python client.\n\n[]\n(https://travis-ci.org/d11wtq/dockerpty)\n\n## Installation\n\nVia pip:\n\n```\npip install dockerpty\n```\n\nDependencies:\n\n * docker-py>=0.3.2\n\nHowever, this library does not explicitly declare this dependency in PyPi for a\nnumber of reasons. It is assumed you have it installed.\n\n## Usage\n\nThe following example will run busybox in a docker container and place the user\nat the shell prompt via Python.\n\nThis obviously only works when run in a terminal.\n\n``` python\nimport docker\nimport dockerpty\n\nclient = docker.Client()\ncontainer = client.create_container(\n image='busybox:latest',\n stdin_open=True,\n tty=True,\n command='/bin/sh',\n)\n\ndockerpty.start(client, container)\n```\n\nKeyword arguments passed to `start()` will be forwarded onto the client to\nstart the container.\n\nWhen the dockerpty is started, control is yielded to the container's PTY until\nthe container exits, or the container's PTY is closed.\n\nThis is a safe operation and all resources are restored back to their original\nstates.\n\n> **Note:** dockerpty does support attaching to non-tty containers to stream\ncontainer output, though it is obviously not possible to 'control' the\ncontainer if you do not allocate a pseudo-tty.\n\nIf you press `C-p C-q`, the container's PTY will be closed, but the container\nwill keep running. In other words, you will have detached from the container\nand can re-attach with another `dockerpty.start()` call.\n\n## Tests\n\nIf you want to hack on dockerpty and send a PR, you'll need to run the tests.\nIn the features/ directory, are features/user stories for how dockerpty is\nsupposed to work. To run them:\n\n```\n-bash$ pip install -r requirements-dev.txt\n-bash$ behave features/\n```\n\nYou'll need to have docker installed and running locally. The tests use busybox\ncontainer as a test fixture, so are not too heavy.\n\nStep definitions are defined in features/steps/.\n\nThere are also unit tests for the parts of the code that are not inherently\ndependent on controlling a TTY. To run those:\n\n```\n-bash$ pip install -r requirements-dev.txt\n-bash$ py.test tests/\n```\n\nTravis CI runs this build inside a UML kernel that is new enough to run docker.\nYour PR will need to pass the build before I can merge it.\n\n - Travis CI build: https://travis-ci.org/d11wtq/dockerpty\n\n## How it works\n\nIn a terminal, the three file descriptors stdin, stdout and stderr are all\nconnected to the controlling terminal (TTY). When you pass the `tty=True` flag\nto docker's `create_container()`, docker allocates a fake TTY inside the\ncontainer (a PTY) to which the container's stdin, stdout and stderr are all\nconnected.\n\nThe docker API provides a way to access the three sockets connected to the PTY.\nIf with access to the host system's TTY file descriptors and the container's\nPTY file descriptors, it is trivial to simply 'pipe' data written to these file\ndescriptors between the host and the container. Doing this makes the user's\nterminal effectively become the pseudo-terminal from inside the container.\n\nIn reality it's a bit more complicated than this, since care must be taken to\nput the host terminal into raw mode (where keys such as enter are not\ninterpreted with any special meaning) and restore it on exit. Additionally, the\ncontainer's stdout and stderr streams along with `sys.stdin` must be made\nnon-blocking so that they can be used with `select()` without blocking the main\nprocess. These attributes are restored on exit.\n\nThe size of a terminal cannot be controlled by sending data to stdin and can\nonly be controlled by the terminal program itself. Since the pseudo-terminal is\nrunning inside a real terminal, it is import that the size of the PTY be kept\nthe same as that of the presenting TTY. For this reason, docker provides an API\ncall to resize the allocated PTY. A SIGWINCH handler is used to detect window\nsize changes and resize the pseudo-terminal as needed.\n\n## Contributors\n\n - Primary author: [Chris Corbyn](https://github.com/d11wtq)\n - Collaborator: [Daniel Nephin](https://github.com/dnephin)\n - Contributor: [Stephen Moore](https://github.com/delfick)\n - Contributor: [Ben Firshman](https://github.com/bfirsh)\n\n## Copyright & Licensing\n\nCopyright © 2014 Chris Corbyn. See the LICENSE.txt file for details.",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Python library to use the pseudo-tty of a docker container",
"version": "0.4.1",
"split_keywords": [
"docker",
"tty",
"pty",
"terminal"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "028bacb34536f3ee6a2ccd668c27e8e4",
"sha256": "69a9d69d573a0daa31bcd1c0774eeed5c15c295fe719c61aca550ed1393156ce"
},
"downloads": -1,
"filename": "dockerpty-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "028bacb34536f3ee6a2ccd668c27e8e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 13924,
"upload_time": "2016-02-04T18:57:13",
"upload_time_iso_8601": "2016-02-04T18:57:13.442227Z",
"url": "https://files.pythonhosted.org/packages/8d/ee/e9ecce4c32204a6738e0a5d5883d3413794d7498fe8b06f44becc028d3ba/dockerpty-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2016-02-04 18:57:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "d11wtq",
"github_project": "dockerpty",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "six",
"specs": [
[
">=",
"1.3.0"
]
]
}
],
"tox": true,
"lcname": "dockerpty"
}
JSON
