---
editLink: false
lastUpdated: false
outline: [2, 3]
---

<!-- Generated by python/b2c-tooling-sdk/scripts/generate_api_docs.py. Do not edit. -->

# b2c_tooling_sdk.operations.code

Code deployment operations for B2C Commerce.

Mirrors `src/operations/code/index.ts`. Provides functions for managing
cartridge code versions on B2C Commerce instances via WebDAV and OCAPI/SCAPI.

Cartridge discovery:

- [`find_cartridges`](/python/api/operations/code#find-cartridges) - Find cartridges by `.project` files.

Code versions:

- [`list_code_versions`](/python/api/operations/code#list-code-versions) - List all code versions on an instance.
- [`get_active_code_version`](/python/api/operations/code#get-active-code-version) - Get the currently active code version.
- [`activate_code_version`](/python/api/operations/code#activate-code-version) - Activate a code version.
- [`reload_code_version`](/python/api/operations/code#reload-code-version) - Reload (re-activate) a code version.
- [`delete_code_version`](/python/api/operations/code#delete-code-version) - Delete a code version.
- [`create_code_version`](/python/api/operations/code#create-code-version) - Create a new code version.

Deployment:

- [`find_and_deploy_cartridges`](/python/api/operations/code#find-and-deploy-cartridges) - Find and deploy cartridges to an instance.
- [`upload_cartridges`](/python/api/operations/code#upload-cartridges) - Low-level cartridge upload.
- [`delete_cartridges`](/python/api/operations/code#delete-cartridges) - Low-level cartridge deletion.
- [`watch_cartridges`](/python/api/operations/code#watch-cartridges) - Watch and sync file changes.

Download:

- [`download_cartridges`](/python/api/operations/code#download-cartridges) - Download cartridges from an instance.

## Classes

### CartridgeMapping {#cartridgemapping}

```python
class CartridgeMapping
```

A discovered cartridge in the local filesystem.

**Fields**

| Name | Type |
| --- | --- |
| `name` | `str` |
| `src` | `str` |
| `dest` | `str` |

### CodeVersion {#codeversion}

```python
class CodeVersion(BaseModel)
```

&lt;p>Document representing a code version&lt;/p>

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `activation_time` | `AwareDatetime \| None` | `Field(None, description='The code version activation time.')` |
| `active` | `bool \| None` |  |
| `cartridges` | `list[str] \| None` |  |
| `compatibility_mode` | `str \| None` |  |
| `id` | `str \| None` | `Field(None, description='The code version id.')` |
| `last_modification_time` | `AwareDatetime \| None` |  |
| `rollback` | `bool \| None` |  |
| `total_size` | `int \| None` |  |
| `web_dav_url` | `str \| None` |  |

### CodeVersionActivationResult {#codeversionactivationresult}

```python
class CodeVersionActivationResult
```

Result of requesting activation of a code version.

**Fields**

| Name | Type |
| --- | --- |
| `already_active` | `bool` |

### CodeVersionInfo {#codeversioninfo}

```python
class CodeVersionInfo
```

A code version, normalized across the OCAPI and SCAPI representations.

`activation_time`/`last_modification_time` are kept as ISO-8601 strings
(matching the TypeScript `string` fields) even though the underlying
generated Pydantic models parse them as `datetime` — each backend
converts via `.isoformat()` at the mapping boundary.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `id` | `str` |  |
| `active` | `bool \| None` | `None` |
| `cartridges` | `list[str] \| None` | `None` |
| `compatibility_mode` | `str \| None` | `None` |
| `activation_time` | `str \| None` | `None` |
| `last_modification_time` | `str \| None` | `None` |
| `rollback` | `bool \| None` | `None` |
| `total_size` | `int \| None` | `None` |
| `web_dav_url` | `str \| None` | `None` |
| `raw` | `Any` | `None` |

### CodeVersionResult {#codeversionresult}

```python
class CodeVersionResult(BaseModel)
```

&lt;p>Result document containing an array of code versions.&lt;/p>

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `count` | `int \| None` | `Field(None, description='The number of returned documents.')` |
| `data` | `list[CodeVersion] \| None` | `Field(None, description='The array of code versions')` |
| `next` | `str \| None` | `Field(None, description='The URL of the next result page.')` |
| `previous` | `str \| None` |  |
| `select` | `str \| None` |  |
| `start` | `int \| None` |  |
| `total` | `int \| None` | `Field(None, description='The total number of documents.')` |

### DeployOptions {#deployoptions}

```python
class DeployOptions(FindCartridgesOptions)
```

Options for deploying cartridges.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `scripts_backend` | `ScriptsBackend \| None` | `None` |
| `activate` | `bool` | `False` |
| `reload` | `bool` | `False` |
| `delete` | `bool` | `False` |
| `on_progress` | `Callable[[UploadProgressInfo], None] \| None` | `None` |

### DeployResult {#deployresult}

```python
class DeployResult
```

Result of a cartridge deployment.

**Fields**

| Name | Type |
| --- | --- |
| `cartridges` | `list[CartridgeMapping]` |
| `code_version` | `str` |
| `activated` | `bool` |
| `reloaded` | `bool` |

### DownloadOptions {#downloadoptions}

```python
class DownloadOptions
```

Options for downloading cartridges.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `scripts_backend` | `ScriptsBackend \| None` | `None` |
| `include` | `list[str]` | `field(default_factory=list)` |
| `exclude` | `list[str]` | `field(default_factory=list)` |
| `mirror` | `dict[str, str] \| None` | `None` |
| `on_progress` | `Callable[[DownloadProgressInfo], None] \| None` | `None` |

### DownloadProgressInfo {#downloadprogressinfo}

```python
class DownloadProgressInfo
```

Progress info passed to the download `on_progress` callback.

**Fields**

| Name | Type |
| --- | --- |
| `phase` | `DownloadPhase` |
| `elapsed_seconds` | `int` |

### DownloadResult {#downloadresult}

```python
class DownloadResult
```

Result of a cartridge download.

**Fields**

| Name | Type |
| --- | --- |
| `cartridges` | `list[str]` |
| `code_version` | `str` |
| `output_directory` | `str` |

### FileChange {#filechange}

```python
class FileChange
```

A file to upload or delete, with source and destination paths.

**Fields**

| Name | Type |
| --- | --- |
| `src` | `str` |
| `dest` | `str` |

### FindCartridgesOptions {#findcartridgesoptions}

```python
class FindCartridgesOptions
```

Options for [`find_cartridges`](/python/api/operations/code#find-cartridges).

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `include` | `list[str]` | `field(default_factory=list)` |
| `exclude` | `list[str]` | `field(default_factory=list)` |
| `max_depth` | `int \| None` | `None` |
| `first_match_only` | `bool` | `False` |

### OcapiScriptsBackend {#ocapiscriptsbackend}

```python
class OcapiScriptsBackend
```

Code-version operations against the legacy OCAPI Data API.

**Fields**

| Name | Type |
| --- | --- |
| `name` | `Literal['ocapi']` |

### ScapiScriptsBackend {#scapiscriptsbackend}

```python
class ScapiScriptsBackend
```

Code-version operations against the SCAPI Scripts DX API.

**Fields**

| Name | Type |
| --- | --- |
| `name` | `Literal['scapi']` |

### ScriptsBackend {#scriptsbackend}

```python
class ScriptsBackend(BackendBase, Protocol)
```

Backend-agnostic interface for code-version operations.

Implemented by [`OcapiScriptsBackend`](/python/api/operations/code#ocapiscriptsbackend)
and [`ScapiScriptsBackend`](/python/api/operations/code#scapiscriptsbackend).

### UploadFilesOptions {#uploadfilesoptions}

```python
class UploadFilesOptions
```

Callbacks for file upload/delete operations.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `on_upload` | `Callable[[list[str]], None] \| None` | `None` |
| `on_delete` | `Callable[[list[str]], None] \| None` | `None` |
| `on_error` | `Callable[[Exception], None] \| None` | `None` |

### UploadOptions {#uploadoptions}

```python
class UploadOptions
```

Options for upload progress reporting.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `on_progress` | `Callable[[UploadProgressInfo], None] \| None` | `None` |

### UploadProgressInfo {#uploadprogressinfo}

```python
class UploadProgressInfo
```

Progress info passed to the upload `on_progress` callback.

**Fields**

| Name | Type |
| --- | --- |
| `phase` | `UploadPhase` |
| `elapsed_seconds` | `int` |

### WatchOptions {#watchoptions}

```python
class WatchOptions(FindCartridgesOptions)
```

Options for watching cartridges.

**Fields**

| Name | Type | Default |
| --- | --- | --- |
| `scripts_backend` | `ScriptsBackend \| None` | `None` |
| `debounce_time_ms` | `int` | `_DEFAULT_DEBOUNCE_MS` |
| `on_upload` | `Callable[[list[str]], None] \| None` | `None` |
| `on_delete` | `Callable[[list[str]], None] \| None` | `None` |
| `on_error` | `Callable[[Exception], None] \| None` | `None` |
| `poll_interval_seconds` | `float` | `_DEFAULT_POLL_INTERVAL_SECONDS` |

### WatchResult {#watchresult}

```python
class WatchResult
```

Result of starting a watcher.

**Fields**

| Name | Type |
| --- | --- |
| `cartridges` | `list[CartridgeMapping]` |
| `code_version` | `str` |
| `stop` | `Callable[[], Awaitable[None]]` |

## Functions

### activate_code_version {#activate-code-version}

```python
async def activate_code_version(instance: B2CInstance, code_version_id: str) -> CodeVersionActivationResult
```

Activate a code version.

Idempotent: if OCAPI reports the code version is already active, this
returns `already_active=True` rather than raising.

### create_code_version {#create-code-version}

```python
async def create_code_version(instance: B2CInstance, code_version_id: str) -> None
```

Create a new (empty) code version.

### create_scripts_backend {#create-scripts-backend}

```python
def create_scripts_backend(config: ScriptsBackendConfig) -> ScriptsBackend
```

Create a code-version backend, choosing SCAPI or OCAPI per `config`.

Delegates to [`create_dual_backend`](/python/api/clients#create-dual-backend).

### delete_cartridges {#delete-cartridges}

```python
async def delete_cartridges(instance: B2CInstance, cartridges: list[CartridgeMapping]) -> None
```

Delete cartridges from an instance via WebDAV.

Low-level function that deletes cartridge directories from the specified
code version. Errors are silently ignored for cartridges that don't exist.

Requires `instance.config.code_version` to be set.

**Raises**

- `RuntimeError` — if the instance has no code version configured.

### delete_code_version {#delete-code-version}

```python
async def delete_code_version(instance: B2CInstance, code_version_id: str) -> None
```

Delete a code version.

### download_cartridges {#download-cartridges}

```python
async def download_cartridges(instance: B2CInstance, output_directory: str, options: DownloadOptions | None = None) -> DownloadResult
```

Download cartridges from an instance via WebDAV.

When `include` specifies cartridges, each is downloaded individually
using per-cartridge server-side zipping for efficiency. When downloading
all cartridges (no include filter), the entire code version is zipped at
once.

If `instance.config.code_version` is not set, attempts to discover the
active code version via the scripts backend. If that also fails, raises.

### download_single_cartridge {#download-single-cartridge}

```python
async def download_single_cartridge(instance: B2CInstance, code_version: str, cartridge_name: str, output_path: str, on_progress: Callable[[DownloadProgressInfo], None] | None = None) -> None
```

Download a single cartridge from an instance via WebDAV.

More efficient than downloading the entire code version when only one
cartridge is needed, since it ZIPs only the cartridge subdirectory
server-side.

### file_to_cartridge_path {#file-to-cartridge-path}

```python
def file_to_cartridge_path(absolute_path: str, cartridges: list[CartridgeMapping]) -> FileChange | None
```

Map an absolute file path to its cartridge-relative destination.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `absolute_path` | `str` | The absolute path to a file. |
| `cartridges` | `list[CartridgeMapping]` | The list of discovered cartridge mappings. |

**Returns:** The file change with `src`/`dest`, or `None` if the path is not inside any cartridge.

### find_and_deploy_cartridges {#find-and-deploy-cartridges}

```python
async def find_and_deploy_cartridges(instance: B2CInstance, directory: str, options: DeployOptions | None = None) -> DeployResult
```

Find and deploy cartridges from a directory to an instance.

High-level function that orchestrates the deployment process:

1. Finds cartridges in the specified directory (by `.project` files).
2. Applies include/exclude filters.
3. Optionally deletes existing cartridges first.
4. Creates a zip archive and uploads via WebDAV.
5. Optionally activates or reloads the code version.

Requires `instance.config.code_version` to be set.

**Raises**

- `RuntimeError` — if code version is not set, no cartridges are found, or deployment fails.

### find_cartridges {#find-cartridges}

```python
def find_cartridges(directory: str | None = None, options: FindCartridgesOptions | None = None) -> list[CartridgeMapping]
```

Find cartridges recursively in a directory.

Cartridges are identified by the presence of a `.project` file (Eclipse
project marker commonly used in SFCC development).

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `directory` | `str \| None` | Directory to search for cartridges (defaults to the current working directory). |
| `options` | `FindCartridgesOptions \| None` | Filter options for including/excluding cartridges. |

**Returns:** List of discovered cartridge mappings.

### get_active_code_version {#get-active-code-version}

```python
async def get_active_code_version(instance: B2CInstance) -> CodeVersion | None
```

Return the currently active code version, or `None` if none is active.

### list_code_versions {#list-code-versions}

```python
async def list_code_versions(instance: B2CInstance) -> list[CodeVersion]
```

List all code versions on the instance.

### reload_code_version {#reload-code-version}

```python
async def reload_code_version(backend: ScriptsBackend, code_version_id: str | None = None) -> None
```

Reload (re-activate) a code version using a toggle-activate technique.

Activates an alternate version, then re-activates the target. This forces
the instance to reload the code (rebuild caches, re-register custom APIs,
etc.). Works on top of any [`ScriptsBackend`](/python/api/operations/code#scriptsbackend) since it only uses
list/activate primitives.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `code_version_id` | `str \| None` | Code version to reload (defaults to the current active version). |

**Raises**

- `RuntimeError` — if no code version is specified and none is active, or if the target is already active and no alternate code version exists to toggle through.

### upload_cartridges {#upload-cartridges}

```python
async def upload_cartridges(instance: B2CInstance, cartridges: list[CartridgeMapping], options: UploadOptions | None = None) -> None
```

Upload cartridges to an instance via WebDAV.

Low-level upload function that:

1. Creates a zip archive of the cartridges.
2. Uploads it to WebDAV.
3. Unzips on the server.
4. Cleans up the temporary zip file.

Requires `instance.config.code_version` to be set.

**Raises**

- `RuntimeError` — if code version is not set or no cartridges are given.

### watch_cartridges {#watch-cartridges}

```python
async def watch_cartridges(instance: B2CInstance, directory: str, options: WatchOptions | None = None) -> WatchResult
```

Watch cartridge directories and sync changes to an instance.

1. Finds cartridges in the specified directory.
2. Polls those directories for changes (see module docstring for why
   polling rather than native OS watching is used).
3. Batches file changes (debounced) and uploads them via WebDAV.
4. Handles file deletions.

**Raises**

- `RuntimeError` — if no code version is configured and none is active, or if no cartridges are found in `directory`.

## Attributes

### ScapiScriptsBackendConfig {#scapiscriptsbackendconfig}

```python
ScapiScriptsBackendConfig = ScapiBackendCtorConfig
```

### ScriptsBackendConfig {#scriptsbackendconfig}

```python
ScriptsBackendConfig = DualBackendConfig
```