docker
/
docker-py
mirror of https://github.com/docker/docker-py.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Removed trailing whitespace in docs

This commit is contained in:
Joffrey F 2014-11-14 01:37:46 +01:00
parent 8df3a3f5ae
commit bf077ace10
6 changed files with 76 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
docs/api.md
View File

@ -1,6 +1,6 @@
# Client API # Client API
To instantiate a `Client` class that will allow you to communicate with a To instantiate a `Client` class that will allow you to communicate with a
Docker daemon, simply do: Docker daemon, simply do:
```python ```python
@ -10,7 +10,7 @@ c = Client(base_url='unix://var/run/docker.sock')
**Params**: **Params**:
* base_url (str): Refers to the protocol+hostname+port where the Docker server * base_url (str): Refers to the protocol+hostname+port where the Docker server
is hosted. is hosted.
* version (str): The version of the API the client will use * version (str): The version of the API the client will use
* timeout (int): The HTTP request timeout, in seconds. * timeout (int): The HTTP request timeout, in seconds.
@ -20,8 +20,8 @@ is hosted.
## attach ## attach
The `.logs()` function is a wrapper around this method, which you can use The `.logs()` function is a wrapper around this method, which you can use
instead if you want to fetch/stream container output without first retrieving instead if you want to fetch/stream container output without first retrieving
the entire backlog. the entire backlog.
**Params**: **Params**:
@ -36,13 +36,13 @@ the entire backlog.
## build ## build
Similar to the `docker build` command. Either `path` or `fileobj` needs to be Similar to the `docker build` command. Either `path` or `fileobj` needs to be
set. `path` can be a local path (to a directory containing a Dockerfile) or a set. `path` can be a local path (to a directory containing a Dockerfile) or a
remote URL. `fileobj` must be a readable file-like object to a Dockerfile. remote URL. `fileobj` must be a readable file-like object to a Dockerfile.
If you have a tar file for the Docker build context (including a Dockerfile) If you have a tar file for the Docker build context (including a Dockerfile)
already, pass a readable file-like object to `fileobj` and also pass already, pass a readable file-like object to `fileobj` and also pass
`custom_context=True`. If the stream is compressed also, set `encoding` to the `custom_context=True`. If the stream is compressed also, set `encoding` to the
correct value (e.g `gzip`). correct value (e.g `gzip`).
**Params**: **Params**:
@ -53,7 +53,7 @@ correct value (e.g `gzip`).
* fileobj: A file object to use as the Dockerfile. (Or a file-like object) * fileobj: A file object to use as the Dockerfile. (Or a file-like object)
* nocache (bool): Don't use the cache when set to `True` * nocache (bool): Don't use the cache when set to `True`
* rm (bool): Remove intermediate containers * rm (bool): Remove intermediate containers
* stream (bool): Return a blocking generator you can iterate over to retrieve * stream (bool): Return a blocking generator you can iterate over to retrieve
build output as it happens build output as it happens
* timeout (int): HTTP timeout * timeout (int): HTTP timeout
* custom_context (bool): Optional if using `fileobj` * custom_context (bool): Optional if using `fileobj`
@ -94,7 +94,7 @@ build output as it happens
``` ```
**Raises:** [TypeError]( **Raises:** [TypeError](
https://docs.python.org/3.4/library/exceptions.html#TypeError) if `path` nor https://docs.python.org/3.4/library/exceptions.html#TypeError) if `path` nor
`fileobj` are specified `fileobj` are specified
## commit ## commit
@ -122,9 +122,9 @@ List containers. Identical to the `docker ps` command.
* trunc (bool): Truncate output * trunc (bool): Truncate output
* latest (bool): Show only the latest created container, include non-running * latest (bool): Show only the latest created container, include non-running
ones. ones.
* since (str): Show only containers created since Id or Name, include * since (str): Show only containers created since Id or Name, include
non-running ones non-running ones
* before (str): Show only container created before Id or Name, include * before (str): Show only container created before Id or Name, include
non-running ones non-running ones
* limit (int): Show `limit` last created containers, include non-running ones * limit (int): Show `limit` last created containers, include non-running ones
* size (bool): Display sizes * size (bool): Display sizes
@ -156,21 +156,21 @@ Identical to the `docker cp` command. Get files/folders from the container.
## create_container ## create_container
Creates a container that can then be `.start()` ed. Parameters are similar to Creates a container that can then be `.start()` ed. Parameters are similar to
those for the `docker run` command except it doesn't support the attach those for the `docker run` command except it doesn't support the attach
options (`-a`). options (`-a`).
See [Port bindings](port-bindings.md) and [Using volumes](volumes.md) for more See [Port bindings](port-bindings.md) and [Using volumes](volumes.md) for more
information on how to create port bindings and volume mappings. information on how to create port bindings and volume mappings.
The `mem_limit` variable accepts float values (which represent the memory limit The `mem_limit` variable accepts float values (which represent the memory limit
of the created container in bytes) or a string with a units identification char of the created container in bytes) or a string with a units identification char
('100000b', 1000k', 128m', '1g'). If a string is specified without a units ('100000b', 1000k', 128m', '1g'). If a string is specified without a units
character, bytes are assumed as an intended unit. character, bytes are assumed as an intended unit.
`volumes_from` and `dns` arguments raise [TypeError]( `volumes_from` and `dns` arguments raise [TypeError](
https://docs.python.org/3.4/library/exceptions.html#TypeError) exception if https://docs.python.org/3.4/library/exceptions.html#TypeError) exception if
they are used against v1.10 of the Docker remote API. Those arguments should be they are used against v1.10 of the Docker remote API. Those arguments should be
passed to `start()` instead. passed to `start()` instead.
**Params**: **Params**:
@ -179,18 +179,18 @@ passed to `start()` instead.
* command (str or list): The command to be run in the container * command (str or list): The command to be run in the container
* hostname (str): Optional hostname for the container * hostname (str): Optional hostname for the container
* user (str or int): Username or UID * user (str or int): Username or UID
* detach (bool): Detached mode: run container in the background and print new * detach (bool): Detached mode: run container in the background and print new
container Id container Id
* stdin_open (bool): Keep STDIN open even if not attached * stdin_open (bool): Keep STDIN open even if not attached
* tty (bool): Allocate a pseudo-TTY * tty (bool): Allocate a pseudo-TTY
* mem_limit (float or str): Memory limit (format: [number][optional unit], * mem_limit (float or str): Memory limit (format: [number][optional unit],
where unit = b, k, m, or g) where unit = b, k, m, or g)
* ports (list of ints): A list of port numbers * ports (list of ints): A list of port numbers
* environment (dict or list): A dictionary or a list of strings in the * environment (dict or list): A dictionary or a list of strings in the
following format `["PASSWORD=xxx"]` or `{"PASSWORD": "xxx"}`. following format `["PASSWORD=xxx"]` or `{"PASSWORD": "xxx"}`.
* dns (list): DNS name servers * dns (list): DNS name servers
* volumes (str or list): * volumes (str or list):
* volumes_from (str or list): List of container names or Ids to get volumes * volumes_from (str or list): List of container names or Ids to get volumes
from. Optionally a single string joining container id's with commas from. Optionally a single string joining container id's with commas
* network_disabled (bool): Disable networking * network_disabled (bool): Disable networking
* name (str): A name for the container * name (str): A name for the container
@ -292,11 +292,11 @@ layers)
## import_image ## import_image
Identical to the `docker import` command. If `src` is a string or unicode Identical to the `docker import` command. If `src` is a string or unicode
string, it will be treated as a URL to fetch the image from. To import an image string, it will be treated as a URL to fetch the image from. To import an image
from the local machine, `src` needs to be a file-like object or bytes from the local machine, `src` needs to be a file-like object or bytes
collection. To import from a tarball use your absolute path to your tarball. collection. To import from a tarball use your absolute path to your tarball.
To load arbitrary data as tarball use whatever you want as src and your To load arbitrary data as tarball use whatever you want as src and your
tarball content in data. tarball content in data.
**Params**: **Params**:
@ -347,7 +347,7 @@ Identical to the `docker inspect` command, but only for containers.
* container (str): The container to inspect * container (str): The container to inspect
**Returns** (dict): Nearly the same output as `docker inspect`, just as a **Returns** (dict): Nearly the same output as `docker inspect`, just as a
single dict single dict
## inspect_image ## inspect_image
@ -358,7 +358,7 @@ Identical to the `docker inspect` command, but only for images
* image_id (str): The image to inspect * image_id (str): The image to inspect
**Returns** (dict): Nearly the same output as `docker inspect`, just as a **Returns** (dict): Nearly the same output as `docker inspect`, just as a
single dict single dict
## kill ## kill
@ -387,7 +387,7 @@ Nearly identical to the `docker login` command, but non-interactive.
## logs ## logs
Identical to the `docker logs` command. The `stream` parameter makes the `logs` Identical to the `docker logs` command. The `stream` parameter makes the `logs`
function return a blocking generator you can iterate over to retrieve log function return a blocking generator you can iterate over to retrieve log
output as it happens. output as it happens.
**Params**: **Params**:
@ -411,13 +411,13 @@ Pauses all processes within a container.
## ping ## ping
Hits the `/_ping` endpoint of the remote API and returns the result. An Hits the `/_ping` endpoint of the remote API and returns the result. An
exception will be raised if the endpoint isn't responding. exception will be raised if the endpoint isn't responding.
**Returns** (bool) **Returns** (bool)
## port ## port
Lookup the public-facing port that is NAT-ed to `private_port`. Identical to Lookup the public-facing port that is NAT-ed to `private_port`. Identical to
the `docker port` command. the `docker port` command.
**Params**: **Params**:
@ -468,7 +468,7 @@ Identical to the `docker pull` command.
## push ## push
Push an image or a repository to the registry. Identical to the `docker push` Push an image or a repository to the registry. Identical to the `docker push`
command command
**Params**: **Params**:
@ -525,7 +525,7 @@ If `container` a dict, the `Id` key is used.
**Params**: **Params**:
* container (str or dict): The container to restart * container (str or dict): The container to restart
* timeout (int): Number of seconds to try to stop for before killing the * timeout (int): Number of seconds to try to stop for before killing the
container. Once killed it will then be restarted. Default is 10 seconds. container. Once killed it will then be restarted. Default is 10 seconds.
## search ## search
@ -554,34 +554,34 @@ Identical to the `docker search` command.
'star_count': 60}, 'star_count': 60},
... ...
``` ```
## start ## start
Similar to the `docker start` command, but doesn't support attach options. Use Similar to the `docker start` command, but doesn't support attach options. Use
`.logs()` to recover `stdout`/`stderr`. `.logs()` to recover `stdout`/`stderr`.
`binds` allows to bind a directory in the host to the container. See [Using `binds` allows to bind a directory in the host to the container. See [Using
volumes](volumes.md) for more information. `port_bindings` exposes container volumes](volumes.md) for more information. `port_bindings` exposes container
ports to the host. See [Port bindings](port-bindings.md) for more information. ports to the host. See [Port bindings](port-bindings.md) for more information.
`lxc_conf` allows to pass LXC configuration options using a dictionary. `lxc_conf` allows to pass LXC configuration options using a dictionary.
`privileged` starts the container in privileged mode. `privileged` starts the container in privileged mode.
[Links](http://docs.docker.io/en/latest/use/working_with_links_names/) can be [Links](http://docs.docker.io/en/latest/use/working_with_links_names/) can be
specified with the `links` argument. They can either be specified as a specified with the `links` argument. They can either be specified as a
dictionary mapping name to alias or as a list of `(name, alias)` tuples. dictionary mapping name to alias or as a list of `(name, alias)` tuples.
`dns` and `volumes_from` are only available if they are used with version v1.10 `dns` and `volumes_from` are only available if they are used with version v1.10
of docker remote API. Otherwise they are ignored. of docker remote API. Otherwise they are ignored.
`network_mode` is available since v1.11 and sets the Network mode for the `network_mode` is available since v1.11 and sets the Network mode for the
container ('bridge': creates a new network stack for the container on the container ('bridge': creates a new network stack for the container on the
Docker bridge, 'none': no networking for this container, 'container:[name|id]': Docker bridge, 'none': no networking for this container, 'container:[name|id]':
reuses another container network stack), 'host': use the host network stack reuses another container network stack), 'host': use the host network stack
inside the container. inside the container.
`restart_policy` is available since v1.2.0 and sets the RestartPolicy for how a `restart_policy` is available since v1.2.0 and sets the RestartPolicy for how a
container should or should not be restarted on exit. By default the policy is container should or should not be restarted on exit. By default the policy is
set to no meaning do not restart the container when it exits. The user may set to no meaning do not restart the container when it exits. The user may
specify the restart policy as a dictionary for example: specify the restart policy as a dictionary for example:
```python ```python
{ {
@ -590,7 +590,7 @@ specify the restart policy as a dictionary for example:
} }
``` ```
For always restarting the container on exit or can specify to restart the For always restarting the container on exit or can specify to restart the
container to restart on failure and can limit number of restarts. For example: container to restart on failure and can limit number of restarts. For example:
```python ```python
{ {
@ -599,8 +599,8 @@ container to restart on failure and can limit number of restarts. For example:
} }
``` ```
`cap_add` and `cap_drop` are available since v1.2.0 and can be used to add or `cap_add` and `cap_drop` are available since v1.2.0 and can be used to add or
drop certain capabilities. The user may specify the capabilities as an array drop certain capabilities. The user may specify the capabilities as an array
for example: for example:
```python ```python
[ [
@ -620,11 +620,11 @@ for example:
* privileged (bool): Give extended privileges to this container * privileged (bool): Give extended privileges to this container
* dns (list): Set custom DNS servers * dns (list): Set custom DNS servers
* dns_search (list): DNS search domains * dns_search (list): DNS search domains
* volumes_from (str or list): List of container names or Ids to get volumes * volumes_from (str or list): List of container names or Ids to get volumes
from. Optionally a single string joining container id's with commas from. Optionally a single string joining container id's with commas
* network_mode (str): One of `['bridge', None, 'container:<name|id>', * network_mode (str): One of `['bridge', None, 'container:<name|id>',
'host']` 'host']`
* restart_policy (dict): See note above. "Name" param must be one of * restart_policy (dict): See note above. "Name" param must be one of
`['on-failure', 'always']` `['on-failure', 'always']`
* cap_add (list of str): See note above * cap_add (list of str): See note above
* cap_drop (list of str): See note above * cap_drop (list of str): See note above
@ -647,7 +647,7 @@ Stops a container. Similar to the `docker stop` command.
**Params**: **Params**:
* container (str): The container to stop * container (str): The container to stop
* timeout (int): Timeout in seconds to wait for the container to stop before * timeout (int): Timeout in seconds to wait for the container to stop before
sending a `SIGKILL` sending a `SIGKILL`
## tag ## tag
@ -691,7 +691,7 @@ Unpauses all processes within a container.
* container (str): The container to unpause * container (str): The container to unpause
## version ## version
Nearly identical to the `docker version` command. Nearly identical to the `docker version` command.
**Returns** (dict): The server version information **Returns** (dict): The server version information
@ -700,20 +700,20 @@ Nearly identical to the `docker version` command.
>>> cli = Client(base_url='tcp://127.0.0.1:2375') >>> cli = Client(base_url='tcp://127.0.0.1:2375')
>>> cli.version() >>> cli.version()
{ {
"KernelVersion": "3.16.4-tinycore64", "KernelVersion": "3.16.4-tinycore64",
"Arch": "amd64", "Arch": "amd64",
"ApiVersion": "1.15", "ApiVersion": "1.15",
"Version": "1.3.0", "Version": "1.3.0",
"GitCommit": "c78088f", "GitCommit": "c78088f",
"Os": "linux", "Os": "linux",
"GoVersion": "go1.3.3" "GoVersion": "go1.3.3"
} }
``` ```
## wait ## wait
Identical to the `docker wait` command. Block until a container stops, then Identical to the `docker wait` command. Block until a container stops, then
print its exit code. Returns the value `-1` if no `StatusCode` is returned by print its exit code. Returns the value `-1` if no `StatusCode` is returned by
the API. the API.
If `container` a dict, the `Id` key is used. If `container` a dict, the `Id` key is used.

6
docs/contributing.md
View File

@ -1,5 +1,5 @@
# Contributing # Contributing
See the [Docker contributing guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md). See the [Docker contributing guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md).
The following is specific to docker-py. The following is specific to docker-py.
## Running the tests & Code Quality ## Running the tests & Code Quality
@ -14,7 +14,7 @@ $ tox
``` ```
## Building the docs ## Building the docs
Docs are built with [MkDocs](http://www.mkdocs.org/). For development, you can Docs are built with [MkDocs](http://www.mkdocs.org/). For development, you can
run the following in the project directory: run the following in the project directory:
``` ```
$ pip install -r docs-requirements.txt $ pip install -r docs-requirements.txt
@ -32,5 +32,5 @@ Before a new release, please go through the following checklist:
## Vulnerability Reporting ## Vulnerability Reporting
For any security issues, please do NOT file an issue or pull request on github! For any security issues, please do NOT file an issue or pull request on github!
Please contact [security@docker.com](mailto:security@docker.com) or read [the Please contact [security@docker.com](mailto:security@docker.com) or read [the
Docker security page](https://www.docker.com/resources/security/). Docker security page](https://www.docker.com/resources/security/).

3
docs/index.md
View File

@ -12,5 +12,4 @@ Our latest stable is always available on PyPi.
Full documentation is available in the `/docs/` directory. Full documentation is available in the `/docs/` directory.
## License ## License
Docker is licensed under the Apache License, Version 2.0. See LICENSE for full Docker is licensed under the Apache License, Version 2.0. See LICENSE for full license text
license text

4
docs/port-bindings.md
View File

@ -29,8 +29,8 @@ like such in both the `create_container()` and `start()` calls:
```python ```python
container_id = c.create_container( container_id = c.create_container(
'busybox', 'busybox',
'ls', 'ls',
ports=[(1111, 'udp'), 2222] ports=[(1111, 'udp'), 2222]
) )
c.start(container_id, port_bindings={'1111/udp': 4567, 2222: None}) c.start(container_id, port_bindings={'1111/udp': 4567, 2222: None})

4
docs/tls.md
View File

@ -28,7 +28,7 @@ https://docs.python.org/3.4/library/ssl.html#ssl.PROTOCOL_TLSv1)
client = docker.Client(base_url='<https_url>', tls=True) client = docker.Client(base_url='<https_url>', tls=True)
``` ```
Equivalent CLI options: Equivalent CLI options:
```bash ```bash
docker --tls ... docker --tls ...
``` ```
@ -48,7 +48,7 @@ tls_config = docker.tls.TLSConfig(ca_cert='/path/to/ca.pem')
client = docker.Client(base_url='<https_url>', tls=tls_config) client = docker.Client(base_url='<https_url>', tls=tls_config)
``` ```
Equivalent CLI options: Equivalent CLI options:
```bash ```bash
docker --tlsverify --tlscacert /path/to/ca.pem ...` docker --tlsverify --tlscacert /path/to/ca.pem ...`

4
docs/volumes.md
View File

@ -1,7 +1,7 @@
# Using volumes # Using volumes
Volume declaration is done in two parts. First, you have to provide a list of Volume declaration is done in two parts. First, you have to provide
mountpoints to the `Client().create_container()` method. a list of mountpoints to the `Client().create_container()` method.
```python ```python
c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2']) c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'])