> This page is for version 0.3.0.
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.

# nemo_gym.sandbox.testing

A fake sandbox provider for tests of code that owns or borrows sandboxes.

Tests drive a real `AsyncSandbox` over `FakeSandboxProvider`, so what the
sandbox guarantees, such as a stop that survives cancellation and is bounded in time, holds in the test as it does in
production. A test scripts the provider, not the sandbox: a slow, failing or hanging stop is a side effect on
`provider.on_close`.

## Module Contents

### Classes

| Name                                                                   | Description                                                                                                      |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [`FakeSandboxProvider`](#nemo_gym-sandbox-testing-FakeSandboxProvider) | An in-memory provider: sandboxes start at once, commands succeed with no output, and nothing leaves the process. |

### Functions

| Name                                                     | Description                                                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| [`fake_sandbox`](#nemo_gym-sandbox-testing-fake_sandbox) | A started sandbox on `provider` (a new `FakeSandboxProvider` by default), built without awaiting. |

### API

```python
class nemo_gym.sandbox.testing.FakeSandboxProvider()
```

An in-memory provider: sandboxes start at once, commands succeed with no output, and nothing leaves the process.

**`_created`** `= 0`

---

**`client_closed`** `= False`

Whether the provider's client was released (`aclose`).

---

**`closed`** `list[str] = []`

The ids of the sandboxes whose close succeeded, in order.

---

**`name`** `= 'fake'`

---

**`on_close`** `= AsyncMock()`

Awaited, with no arguments, every time a sandbox is closed. Give it a side effect to make the
provider's close slow, fail or hang: an async function, or a plain one that raises or returns an
awaitable, which the close awaits too.

---

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.aclose() -> None
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.close(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> None
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.connect(
    descriptor: collections.abc.Mapping[str, typing.Any]
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.create(
    spec: nemo_gym.sandbox.providers.base.SandboxSpec
) -> nemo_gym.sandbox.providers.base.SandboxHandle
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.download_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: str,
    target_path: pathlib.Path
) -> None
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.exec(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    command: str,
    kwargs: typing.Any = {}
) -> nemo_gym.sandbox.providers.base.SandboxExecResult
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.serialize_handle(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    scope: str | None = None
) -> dict[str, typing.Any]
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.status(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle
) -> nemo_gym.sandbox.providers.base.SandboxStatus
```

async

```python
nemo_gym.sandbox.testing.FakeSandboxProvider.upload_file(
    handle: nemo_gym.sandbox.providers.base.SandboxHandle,
    source_path: pathlib.Path,
    target_path: str
) -> None
```

async

```python
nemo_gym.sandbox.testing.fake_sandbox(
    sandbox_id: str = 'fake-1',
    provider: nemo_gym.sandbox.testing.FakeSandboxProvider | None = None,
    spec: nemo_gym.sandbox.providers.base.SandboxSpec | None = None,
    owns_provider: bool = False
) -> nemo_gym.sandbox.api.AsyncSandbox
```

A started sandbox on `provider` (a new `FakeSandboxProvider` by default), built without awaiting.

It is what `await AsyncSandbox(provider, spec).start()` returns, for tests that need one in a synchronous
fixture, and `sandbox.provider` is the provider to script. By default the sandbox does not own the provider,
so stopping it leaves the provider's client open; with `owns_provider` a successful stop closes it too.