# remote_file_downloader

Python API: `luxonis_ml.data.utils.remote_file_downloader`

## Classes

| Name | Description |
| --- | --- |
|
[`RemoteFileAPIClient`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |
|
[`RemoteFileDownloader`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| Download remote files with optional image validation. |
|
[`RequestsRemoteFileAPIClient`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |

### class `RemoteFileAPIClient`

```python
class RemoteFileAPIClient(Protocol)
```

Methods

| Name | Description |
| --- | --- |
|
[`download`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |

#### method `download`

```python
def download(url: str, destination: Path, *, timeout: float)
```

### class `RemoteFileDownloader`

```python
class RemoteFileDownloader
```

Download remote files with optional image validation.

Attributes

| Name | Description |
| --- | --- |
| `api_client` | Client used for HTTP and HTTPS downloads. |

Methods

| Name | Description |
| --- | --- |
|
[`__init__`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| Create a remote file downloader. |
|
[`download`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| Download a file to `destination`. |

#### method `__init__`

```python
def __init__(api_client: RemoteFileAPIClient | None = None)
```

Create a remote file downloader.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `api_client` | `RemoteFileAPIClient | None` | Optional client used for HTTP and HTTPS downloads. If omitted,
[RequestsRemoteFileAPIClient](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
is used. | `None` |

#### method `download`

```python
def download(
    url: str,
    destination: Path,
    *,
    timeout: float = 30.0,
    validate_image: bool = False,
) -> Path
```

Download a file to `destination`.

Existing destination files are reused. When `validate_image` is true, both reused and newly downloaded files are checked with
Pillow and the destination suffix.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `url` | `str` | Source URL. Supported schemes are `file`, `http`, `https`, `gcs`, `gs`, and `s3`. | required |
| `destination` | `Path` | Local destination path. | required |
| `timeout` | `float` | HTTP request timeout in seconds. | `30.0` |
| `validate_image` | `bool` | Whether to validate image content and format compatibility after download. | `False` |

Returns

| Type | Description |
| --- | --- |
| `Path` | Local destination path. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If the URL scheme is unsupported, the destination image suffix is unsupported, the downloaded file is not a valid
image, or the image format does not match the suffix. |

### class `RequestsRemoteFileAPIClient`

```python
class RequestsRemoteFileAPIClient
```

Methods

| Name | Description |
| --- | --- |
|
[`download`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |

#### method `download`

```python
def download(url: str, destination: Path, *, timeout: float)
```

## Functions

| Name | Description |
| --- | --- |
|
[`download_remote_file`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| Download a remote file to the requested destination. |

### function `download_remote_file`

```python
def download_remote_file(
    url: str,
    destination: Path,
    *,
    timeout: float = 30.0,
    validate_image: bool = False,
) -> Path
```

Download a remote file to the requested destination.

Args

| Name | Type | Description | Default |
| --- | --- | --- | --- |
| `url` | `str` | Source URL. | required |
| `destination` | `Path` | Local destination path. | required |
| `timeout` | `float` | HTTP request timeout in seconds. | `30.0` |
| `validate_image` | `bool` | Whether to validate image content and format compatibility after download. | `False` |

Returns

| Type | Description |
| --- | --- |
| `Path` | Local destination path. |

Raises

| Type | Description |
| --- | --- |
| `ValueError` | If the URL scheme is unsupported or image validation fails. |

## Module Attributes

| Name | Description |
| --- | --- |
|
[`ALLOWED_IMAGE_SUFFIXES`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |
|
[`ALLOWED_IMAGE_SUFFIXES_BY_FORMAT`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |
|
[`ALLOWED_PILLOW_FORMATS_BY_FORMAT`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |
|
[`ALLOWED_REMOTE_URL_SCHEMES`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |
|
[`FS_REMOTE_URL_SCHEMES`](https://docs.luxonis.com/software-v3/ai-inference/model-source/training/luxonis-ml/luxonis-ml-api-reference/data/utils/remote_file_downloader.md)
| |

### constant `ALLOWED_IMAGE_SUFFIXES`

```python
ALLOWED_IMAGE_SUFFIXES = frozenset(
    (suffix for suffixes in ALLOWED_IMAGE_SUFFIXES_BY_FORMAT.values() for suffix in suffixes),
)
```

### constant `ALLOWED_IMAGE_SUFFIXES_BY_FORMAT`

```python
ALLOWED_IMAGE_SUFFIXES_BY_FORMAT = {
    'JPEG': frozenset({'.jpeg', '.jpg'}),
    'PNG': frozenset({'.png'}),
    'WEBP': frozenset({'.webp'}),
    'BMP': frozenset({'.bmp'}),
    'TIFF': frozenset({'.tif', '.tiff'}),
    'HEIC': frozenset({'.heic'}),
    'AVIF': frozenset({'.avif'}),
    'JP2': frozenset({'.jp2'}),
    'DNG': frozenset({'.dng'}),
    'MPO': frozenset({'.mpo'}),
}
```

### constant `ALLOWED_PILLOW_FORMATS_BY_FORMAT`

```python
ALLOWED_PILLOW_FORMATS_BY_FORMAT = {
    'JPEG': frozenset({'JPEG'}),
    'PNG': frozenset({'PNG'}),
    'WEBP': frozenset({'WEBP'}),
    'BMP': frozenset({'BMP'}),
    'TIFF': frozenset({'TIFF'}),
    'HEIC': frozenset({'HEIC', 'HEIF'}),
    'AVIF': frozenset({'AVIF'}),
    'JP2': frozenset({'JP2', 'JPEG2000'}),
    'DNG': frozenset({'DNG', 'TIFF'}),
    'MPO': frozenset({'MPO'}),
}
```

### constant `ALLOWED_REMOTE_URL_SCHEMES`

```python
ALLOWED_REMOTE_URL_SCHEMES = frozenset(
    {'file', 'http', 'https', *FS_REMOTE_URL_SCHEMES},
)
```

### constant `FS_REMOTE_URL_SCHEMES`

```python
FS_REMOTE_URL_SCHEMES = frozenset({'gcs', 'gs', 's3'})
```
