diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-dockerpty.spec | 456 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 458 insertions, 0 deletions
@@ -0,0 +1 @@ +/dockerpty-0.4.1.tar.gz diff --git a/python-dockerpty.spec b/python-dockerpty.spec new file mode 100644 index 0000000..d5947f7 --- /dev/null +++ b/python-dockerpty.spec @@ -0,0 +1,456 @@ +%global _empty_manifest_terminate_build 0 +Name: python-dockerpty +Version: 0.4.1 +Release: 1 +Summary: Python library to use the pseudo-tty of a docker container +License: Apache 2.0 +URL: https://github.com/d11wtq/dockerpty +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/8d/ee/e9ecce4c32204a6738e0a5d5883d3413794d7498fe8b06f44becc028d3ba/dockerpty-0.4.1.tar.gz +BuildArch: noarch + + +%description +# 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. + +%package -n python3-dockerpty +Summary: Python library to use the pseudo-tty of a docker container +Provides: python-dockerpty +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-dockerpty +# 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. + +%package help +Summary: Development documents and examples for dockerpty +Provides: python3-dockerpty-doc +%description help +# 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. + +%prep +%autosetup -n dockerpty-0.4.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-dockerpty -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Mon Apr 10 2023 Python_Bot <Python_Bot@openeuler.org> - 0.4.1-1 +- Package Spec generated @@ -0,0 +1 @@ +028bacb34536f3ee6a2ccd668c27e8e4 dockerpty-0.4.1.tar.gz |