Metadata-Version: 2.1
Name: docker-lite-python
Version: 1.0.3
Summary: Sandbox running code in Docker.
Home-page: https://github.com/jeff-vincent/docker-lite-python
Author: Jeff Vincent
Author-email: jeff.d.vincent@gmail.com
License: MIT
Description: [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![made-with-python](https://img.shields.io/badge/Made%20with-Python-1f425f.svg)](https://www.python.org/) [![Open Source? Yes!](https://badgen.net/badge/Open%20Source%20%3F/Yes%21/blue?icon=github)](https://github.com/Naereen/badges/) ![PyTest](https://github.com/jeff-vincent/docker-lite-python/workflows/PyTest/badge.svg)
        
        
        
        
        # docker-lite-python
        A simple, Python-based Docker interface built on top of the [Docker SDK for Python](https://docker-py.readthedocs.io/en/stable/). 
        Intended to programmatically spin up, pass communications to, and ultimately tear down single Docker containers.
        Requires a local instance of Docker.
        
        **[Quick Start](#quick-start)** | **[Reference](#reference)** | **[Examples](#examples)**
        
        
        ## Quick Start:
        ```
        $ sudo python3
        >>>from docker_light import DockerLite
        >>>dl = DockerLite()
        ```
        
        start an Alpine container and keep it running
        ```
        >>>dl.run_container('alpine:latest', 'alpine-container', 'sleep infinity')
        ```
        exec into the running container
        ```
        >>>dl.exec_into_running_container('alpine-container', 'echo "Hello World!"')
        ExecResult(exit_code=0, output=b'Hello World!\n')
        ```
        tear down that container!
        ```
        >>>dl.kill_container('alpine-container')
        0
        ```
        
        ## Reference:
        
        | Methods | Args | Overview |
        |---------|------|----------|
        |`build_image()`|`*path_to_dockerfile*: string`|`Build a Docker image from a local Dockerfile.`|
        ||`*resulting_image_name*: string`|`Enforces best practice of explicitly naming images.`|
        ||||
        |`list_containers()`|`*all*: bool: default=False`|`List running containers by default.`|
        ||||
        |`run_container()`|`*image_name*: string`|`Run a Docker container, optionally with a command.`|
        ||`*resulting_container_name*: string`|`Enforces best practice of explicitly naming containers.`|
        ||`*command*: string: The command to run. `|`Optional.`|
        ||||
        |`get_container_by_name()`|`*existing_container_name*: string`|`Get a Docker container by name.`|
        ||||
        |`exec_into_running_container()`|`*existing_container_name*: string`|`Run a command in an active container.`|
        ||`*command*: string: The command to execute in the running Docker container.`|
        ||||
        |`list_images()`|`None`|`List all images in the local Docker instance.`|
        ||||
        |`remove_unused_images()`|`None`|`Equivalent of docker images prune`|
        ||||
        |`remove_all_images()`|`None`|`Force removal of all images. Purge system.`|
        ||||
        |`kill_container()`|`*existing_container_name*: string`|`Shut down and delete a container.`|
        |||`NOTE: kill_container() technically just stops the containers, as they are self-removing.`|
        
        ## Examples:
        ```
        from docker_lite import DockerLite
        
        dl = DockerLite()
        ```
        build a Docker image called 'my-image' from a Dockerfile
        ```
        dl.build_image('./Dockerfile', 'my-image')
        ```
        list all containers. Default is to list running containers
        
        ```
        containers = dl.list_containers(all=True)
        ```
        
        run a Docker container called 'my-container' based on a Docker image called 'my-image'
        
        ```
        my_container = dl.run_container('my-image', 'my-container')
        ``` 
        
        run a terminal command in a running Docker container called 'my-container'. Be creative
        
        ```
        output = dl.exec_into_running_container('my-container', 'echo "Hello World!"')
        ```
        
        get a container called 'my-container' by its unique name
        ```
        container = dl.get_container('my-container')
        ``` 
         - [Python Docker SDK documentation on container objects here](https://docker-py.readthedocs.io/en/stable/containers.html#container-objects)
        
        kill a container called 'my-container' by its unique name
        ```
        dl.kill_container('my-container')
        ```
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
