Metadata-Version: 1.0
Name: hlbox
Version: 1.0.1.dev4
Summary: HLBox runs untrusted code in secure Docker based sandboxes (forked from [EpicBox](https://github.com/StepicOrg/epicbox))
Home-page: UNKNOWN
Author: Alex Gajewski
Author-email: agajews@gmail.com
License: UNKNOWN
Description: # hlbox
        
        A Python library to run untrusted code in secure, isolated [Docker](https://www.docker.com/)
        based sandboxes.
        
        > It allows to spawn a process inside one-time Docker container, send data
        > to stdin, and obtain its exit code and stdout/stderr output.  It's very similar
        > to what the [`subprocess`](https://docs.python.org/3/library/subprocess.html#module-subprocess)
        > module does but additionally you can specify a custom environment for the process
        > (a Docker [image](https://docs.docker.com/v17.09/engine/userguide/storagedriver/imagesandcontainers/))
        > and limit the CPU, memory, disk, and network usage for the running process.
        
        > ## Usage
        > Run a simple Python script in a one-time Docker container using the
        > [`python:3.6.5-alpine`](https://hub.docker.com/_/python/) image:
        > ```python
        > import epicbox
        
        > epicbox.configure(
        >     profiles=[
        >         epicbox.Profile('python', 'python:3.6.5-alpine')
        >     ]
        > )
        > files = [{'name': 'main.py', 'content': b'print(42)'}]
        > limits = {'cputime': 1, 'memory': 64}
        > result = epicbox.run('python', 'python3 main.py', files=files, limits=limits)
        
        > ```
        > The `result` value is:
        > ```python
        > {'exit_code': 0,
        >  'stdout': b'42\n',
        >  'stderr': b'',
        >  'duration': 0.143358,
        >  'timeout': False,
        >  'oom_killed': False}
        > ```
        
        > ### Advanced usage
        > A more advanced usage example of `epicbox` is to compile a C++ program and then
        > run it multiple times on different input data.  In this example `epicbox` will
        > run containers on a dedicated [Docker Swarm](https://docs.docker.com/swarm/overview/)
        > cluster instead of locally installed Docker engine:
        > ```python
        > import epicbox
        
        > PROFILES = {
        >     'gcc_compile': {
        >         'docker_image': 'stepik/epicbox-gcc:6.3.0',
        >         'user': 'root',
        >     },
        >     'gcc_run': {
        >         'docker_image': 'stepik/epicbox-gcc:6.3.0',
        >         # It's safer to run untrusted code as a non-root user (even in a container)
        >         'user': 'sandbox',
        >         'read_only': True,
        >         'network_disabled': False,
        >     },
        > }
        > epicbox.configure(profiles=PROFILES, docker_url='tcp://1.2.3.4:2375')
        
        > untrusted_code = b"""
        > // C++ program
        > #include <iostream>
        
        > int main() {
        >     int a, b;
        >     std::cin >> a >> b;
        >     std::cout << a + b << std::endl;
        > }
        > """
        > # A working directory allows to preserve files created in a one-time container
        > # and access them from another one. Internally it is a temporary Docker volume.
        > with epicbox.working_directory() as workdir:
        >     epicbox.run('gcc_compile', 'g++ -pipe -O2 -static -o main main.cpp',
        >                 files=[{'name': 'main.cpp', 'content': untrusted_code}],
        >                 workdir=workdir)
        >     epicbox.run('gcc_run', './main', stdin='2 2',
        >                 limits={'cputime': 1, 'memory': 64},
        >                 workdir=workdir)
        >     # {'exit_code': 0, 'stdout': b'4\n', 'stderr': b'', 'duration': 0.095318, 'timeout': False, 'oom_killed': False}
        >     epicbox.run('gcc_run', './main', stdin='14 5',
        >                 limits={'cputime': 1, 'memory': 64},
        >                 workdir=workdir)
        >     # {'exit_code': 0, 'stdout': b'19\n', 'stderr': b'', 'duration': 0.10285, 'timeout': False, 'oom_killed': False}
        > ```
        
        > ## Installation
        > `epicbox` can be installed by running `pip install epicbox`. It's tested on Python 3.4+ and
        > Docker 1.12+.
        
        > You can also check the [epicbox-images](https://github.com/StepicOrg/epicbox-images)
        > repository that contains Docker images used to automatically grade programming
        > assignments on [Stepik.org](https://stepik.org/).
        
        > ## Contributing
        > Contributions are welcome, and they are greatly appreciated!
        > More details can be found in [CONTRIBUTING](CONTRIBUTING.rst).
        
        
Platform: UNKNOWN
