Metadata-Version: 2.4
Name: code_sandboxes
Version: 1.0.3
Project-URL: Home, https://github.com/datalayer/code-sandboxes
Author-email: Datalayer <info@datalayer.io>
License: BSD 3-Clause License
        
        Copyright (c) 2025, Datalayer
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: AI,AI Agent,Code Sandboxes
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: jupyter-kernel-client
Requires-Dist: jupyter-server
Requires-Dist: jupyter-server-client
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: agent-runtimes; extra == 'all'
Requires-Dist: docker>=6.0; extra == 'all'
Requires-Dist: kaggle>=1.6; extra == 'all'
Requires-Dist: modal>=0.64; extra == 'all'
Requires-Dist: pydantic-monty; extra == 'all'
Provides-Extra: datalayer
Requires-Dist: agent-runtimes>=1.0.16; extra == 'datalayer'
Provides-Extra: docker
Requires-Dist: docker>=6.0; extra == 'docker'
Provides-Extra: google-colab
Provides-Extra: kaggle
Requires-Dist: kaggle>=1.6; extra == 'kaggle'
Provides-Extra: lint
Requires-Dist: mdformat-gfm>=0.3.5; extra == 'lint'
Requires-Dist: mdformat>0.7; extra == 'lint'
Requires-Dist: ruff; extra == 'lint'
Provides-Extra: modal
Requires-Dist: modal>=0.64; extra == 'modal'
Provides-Extra: monty
Requires-Dist: pydantic-monty; extra == 'monty'
Provides-Extra: test
Requires-Dist: ipykernel; extra == 'test'
Requires-Dist: jupyter-server<3,>=1.6; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest-cov>=4.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Provides-Extra: typing
Requires-Dist: mypy>=0.990; extra == 'typing'
Description-Content-Type: text/markdown

<!--
  ~ Copyright (c) 2025-2026 Datalayer, Inc.
  ~
  ~ BSD 3-Clause License
-->

[![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io)

[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)
[![PyPI - Version](https://img.shields.io/pypi/v/code-sandboxes)](https://pypi.org/project/code-sandboxes)

# { } 📦 Code Sandboxes

Code Sandboxes (`code_sandboxes`) is a Python package for running code in isolated sandbox variants through a unified API.

Canonical variant names:

- `datalayer`
- `docker`
- `eval`
- `google_colab`
- `jupyter`
- `kaggle`
- `modal`
- `monty`

## Documentation

The full documentation is the single source of truth:

- Docs home: [https://code-sandboxes.datalayer.tech](https://code-sandboxes.datalayer.tech)
- Sandboxes and variant setup: [https://code-sandboxes.datalayer.tech/sandboxes](https://code-sandboxes.datalayer.tech/sandboxes)
- Installation: [https://code-sandboxes.datalayer.tech/installation](https://code-sandboxes.datalayer.tech/installation)
- CLI usage: [https://code-sandboxes.datalayer.tech/cli](https://code-sandboxes.datalayer.tech/cli)
- API reference: [https://code-sandboxes.datalayer.tech/api-reference](https://code-sandboxes.datalayer.tech/api-reference)
- Examples: [https://code-sandboxes.datalayer.tech/examples](https://code-sandboxes.datalayer.tech/examples)
- Comparison: [https://code-sandboxes.datalayer.tech/comparison](https://code-sandboxes.datalayer.tech/comparison)

Published site:

- [https://code-sandboxes.datalayer.tech](https://code-sandboxes.datalayer.tech)

## Install

```bash
pip install code-sandboxes
```

For backend-specific extras and credentials, see [https://code-sandboxes.datalayer.tech/installation](https://code-sandboxes.datalayer.tech/installation) and [https://code-sandboxes.datalayer.tech/sandboxes](https://code-sandboxes.datalayer.tech/sandboxes).

### Jupyter Sandbox

```python
from code_sandboxes import Sandbox

# Option 1: manage a local Jupyter server automatically
with Sandbox.create(variant="jupyter") as sandbox:
  print(sandbox.run_code("1 + 1").text)  # 2

# Option 2: connect to an existing Jupyter server
with Sandbox.create(
  variant="jupyter",
  server_url="http://localhost:8888",
  token="MY_TOKEN",
) as sandbox:
  sandbox.run_code("x = 40")
  print(sandbox.run_code("x + 2").text)  # 42
```

## Kaggle Sandbox

Kaggle supports both batch execution and interactive connections through the
`kaggle` sandbox. Install its optional dependency first:

```bash
pip install "code-sandboxes[kaggle]"
```

Required credentials for batch mode:

- `~/.kaggle/kaggle.json`, or
- `KAGGLE_API_KEY`

```bash
# Install Kaggle support
pip install code-sandboxes[kaggle]

# Optional: env-based credentials (if not using ~/.kaggle/kaggle.json)
export KAGGLE_API_KEY="<your-kaggle-api-key>"

# Launch the REPL
sandbox repl --variant kaggle
```

For batch execution, configure Kaggle credentials and create the sandbox
without a runtime URL:

```python
from code_sandboxes import Sandbox

with Sandbox.create(variant="kaggle") as sandbox:
    result = sandbox.run_code("print('hello from kaggle')")
    print(result.stdout)
```

The lower-level batch API is also available directly:

```python
from code_sandboxes import KaggleKernelExecutor

executor = KaggleKernelExecutor()
result = executor.execute(
    "print('hello from kaggle')",
    title="code-sandboxes-demo",
    accelerator="NvidiaTeslaT4",
    wait=True,
)
print(result.status, result.stdout)
print(result.to_kernel_reply())
```

For interactive execution, copy the WebSocket channels URL from an active
Kaggle notebook session and pass it to the sandbox or client:

```python
from code_sandboxes import KaggleKernelClient

with KaggleKernelClient.from_channels_url(channels_url, token=None) as kernel:
    print(kernel.execute("x = 1 + 1; print(x)"))
```

See the [complete Kaggle guide](https://code-sandboxes.datalayer.tech/sandboxes/kaggle) for authentication,
accelerators, channels URL retrieval, and execution options.

## Google Colab

Google Colab exposes an already-running kernel through an authenticating proxy.
Copy its WebSocket channels URL from the browser's Network tools, then pass it
directly to the sandbox:

```python
from code_sandboxes import Sandbox

with Sandbox.create(variant="google_colab", channels_url=channels_url) as sandbox:
    print(sandbox.run_code("x = 1 + 1; print(x)").stdout)
```

The lower-level client and parser are owned by Code Sandboxes as well:

```python
from code_sandboxes import GoogleColabKernelClient, parse_google_colab_channels_url

server_url, kernel_id, proxy_token = parse_google_colab_channels_url(channels_url)
with GoogleColabKernelClient.from_channels_url(channels_url) as kernel:
    print(kernel.execute("print('hello from colab')"))
```

See the [complete Google Colab guide](https://code-sandboxes.datalayer.tech/sandboxes/google-colab) for
proxy authentication, explicit connection values, and channels URL retrieval.

## License

BSD 3-Clause License
