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 - Find cartridges by .project files.

Code versions:

list_code_versions - List all code versions on an instance.
get_active_code_version - Get the currently active code version.
activate_code_version - Activate a code version.
reload_code_version - Reload (re-activate) a code version.
delete_code_version - Delete a code version.
create_code_version - Create a new code version.

Deployment:

find_and_deploy_cartridges - Find and deploy cartridges to an instance.
upload_cartridges - Low-level cartridge upload.
delete_cartridges - Low-level cartridge deletion.
watch_cartridges - Watch and sync file changes.

Download:

download_cartridges - Download cartridges from an instance.

Classes

CartridgeMapping

python

class CartridgeMapping

A discovered cartridge in the local filesystem.

Fields

Name	Type
`name`	`str`
`src`	`str`
`dest`	`str`

CodeVersion

python

class CodeVersion(BaseModel)

<p>Document representing a code version</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

python

class CodeVersionActivationResult

Result of requesting activation of a code version.

Fields

Name	Type
`already_active`	`bool`

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

python

class CodeVersionResult(BaseModel)

<p>Result document containing an array of code versions.</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

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

python

class DeployResult

Result of a cartridge deployment.

Fields

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

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

python

class DownloadProgressInfo

Progress info passed to the download on_progress callback.

Fields

Name	Type
`phase`	`DownloadPhase`
`elapsed_seconds`	`int`

DownloadResult

python

class DownloadResult

Result of a cartridge download.

Fields

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

FileChange

python

class FileChange

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

Fields

Name	Type
`src`	`str`
`dest`	`str`

FindCartridgesOptions

python

class FindCartridgesOptions

Options for 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

python

class OcapiScriptsBackend

Code-version operations against the legacy OCAPI Data API.

Fields

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

ScapiScriptsBackend

python

class ScapiScriptsBackend

Code-version operations against the SCAPI Scripts DX API.

Fields

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

ScriptsBackend

python

class ScriptsBackend(BackendBase, Protocol)

Backend-agnostic interface for code-version operations.

Implemented by OcapiScriptsBackend and ScapiScriptsBackend.

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

python

class UploadOptions

Options for upload progress reporting.

Fields

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

UploadProgressInfo

python

class UploadProgressInfo

Progress info passed to the upload on_progress callback.

Fields

Name	Type
`phase`	`UploadPhase`
`elapsed_seconds`	`int`

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

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

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

python

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

Create a new (empty) code version.

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.

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

python

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

Delete a code version.

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

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

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

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:

Finds cartridges in the specified directory (by .project files).
Applies include/exclude filters.
Optionally deletes existing cartridges first.
Creates a zip archive and uploads via WebDAV.
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

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

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

python

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

List all code versions on the instance.

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 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

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:

Creates a zip archive of the cartridges.
Uploads it to WebDAV.
Unzips on the server.
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

python

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

Watch cartridge directories and sync changes to an instance.

Finds cartridges in the specified directory.
Polls those directories for changes (see module docstring for why polling rather than native OS watching is used).
Batches file changes (debounced) and uploads them via WebDAV.
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

python

ScapiScriptsBackendConfig = ScapiBackendCtorConfig

ScriptsBackendConfig

python

ScriptsBackendConfig = DualBackendConfig

b2c_tooling_sdk.operations.code ​

Classes ​

CartridgeMapping ​

CodeVersion ​

CodeVersionActivationResult ​

CodeVersionInfo ​

CodeVersionResult ​

DeployOptions ​

DeployResult ​

DownloadOptions ​

DownloadProgressInfo ​

DownloadResult ​

FileChange ​

FindCartridgesOptions ​

OcapiScriptsBackend ​

ScapiScriptsBackend ​

ScriptsBackend ​

UploadFilesOptions ​

UploadOptions ​

UploadProgressInfo ​

WatchOptions ​

WatchResult ​

Functions ​

activate_code_version ​

create_code_version ​

create_scripts_backend ​

delete_cartridges ​

delete_code_version ​

download_cartridges ​

download_single_cartridge ​

file_to_cartridge_path ​

find_and_deploy_cartridges ​

find_cartridges ​

get_active_code_version ​

list_code_versions ​

reload_code_version ​

upload_cartridges ​

watch_cartridges ​

Attributes ​

ScapiScriptsBackendConfig ​

ScriptsBackendConfig ​

b2c_tooling_sdk.operations.code

Classes

CartridgeMapping

CodeVersion

CodeVersionActivationResult

CodeVersionInfo

CodeVersionResult

DeployOptions

DeployResult

DownloadOptions

DownloadProgressInfo

DownloadResult

FileChange

FindCartridgesOptions

OcapiScriptsBackend

ScapiScriptsBackend

ScriptsBackend

UploadFilesOptions

UploadOptions

UploadProgressInfo

WatchOptions

WatchResult

Functions

activate_code_version

create_code_version

create_scripts_backend

delete_cartridges

delete_code_version

download_cartridges

download_single_cartridge

file_to_cartridge_path

find_and_deploy_cartridges

find_cartridges

get_active_code_version

list_code_versions

reload_code_version

upload_cartridges

watch_cartridges

Attributes

ScapiScriptsBackendConfig

ScriptsBackendConfig