Code Reference¶
Provides tools for managing and publishing items in a Fabric workspace.
Classes:
| Name | Description |
|---|---|
DeploymentResult | Result of a config-based deployment operation. |
DeploymentStatus | Enumeration of deployment status values for deploy_with_config results. |
FabricWorkspace | A class to manage and publish workspace items to the Fabric API. |
FeatureFlag | Enumeration of supported feature flags for fabric-cicd. |
ItemType | Enumeration of supported Microsoft Fabric item types. |
Functions:
| Name | Description |
|---|---|
append_feature_flag | Append a feature flag to the global feature_flag set. |
change_log_level | Sets the log level for all loggers within the fabric_cicd package. Currently only supports DEBUG. |
configure_external_file_logging | Configure fabric_cicd package logging to integrate with an external logger's |
deploy_with_config | Deploy items using YAML configuration file with environment-specific settings. |
disable_file_logging | Disable file logging for the fabric_cicd package. |
publish_all_items | Publishes all items defined in the |
unpublish_all_orphan_items | Unpublishes all orphaned items not present in the repository except for those matching the exclude regex. |
DeploymentResult dataclass ¶
DeploymentResult(status: DeploymentStatus, message: str)
Result of a config-based deployment operation.
This class provides a structured way to return deployment results. Currently only returned on successful completion; failures raise exceptions.
Attributes:
| Name | Type | Description |
|---|---|---|
status | DeploymentStatus | The deployment status (DeploymentStatus.COMPLETED on success). |
message | str | A human-readable message describing the result. |
DeploymentStatus ¶
Bases: str, Enum
Enumeration of deployment status values for deploy_with_config results.
COMPLETED class-attribute instance-attribute ¶
Deployment completed successfully without any errors.
FabricWorkspace ¶
FabricWorkspace(
repository_directory: str,
item_type_in_scope: Optional[list[str]] = None,
environment: str = "N/A",
workspace_id: Optional[str] = None,
workspace_name: Optional[str] = None,
token_credential: TokenCredential = None,
**kwargs,
)
A class to manage and publish workspace items to the Fabric API.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
workspace_id | Optional[str] | The ID of the workspace to interact with. Either | None |
workspace_name | Optional[str] | The name of the workspace to interact with. Either | None |
repository_directory | str | Local directory path of the repository where items are to be deployed from. | required |
item_type_in_scope | Optional[list[str]] | Item types that should be deployed for a given workspace. If omitted, defaults to all available item types. | None |
environment | str | The environment to be used for parameterization. | 'N/A' |
token_credential | TokenCredential | The token credential to use for API requests. | None |
kwargs | Additional keyword arguments. | {} |
Examples:
Basic usage
>>> from fabric_cicd import FabricWorkspace
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
Basic usage with workspace_name
>>> from fabric_cicd import FabricWorkspace
>>> workspace = FabricWorkspace(
... workspace_name="your-workspace-name",
... repository_directory="/path/to/repo"
... )
With optional parameters
>>> from fabric_cicd import FabricWorkspace
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/your/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"],
... environment="your-target-environment"
... )
With token credential
>>> from fabric_cicd import FabricWorkspace
>>> from azure.identity import ClientSecretCredential
>>> client_id = "your-client-id"
>>> client_secret = "your-client-secret"
>>> tenant_id = "your-tenant-id"
>>> token_credential = ClientSecretCredential(
... client_id=client_id, client_secret=client_secret, tenant_id=tenant_id
... )
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/your/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"],
... token_credential=token_credential
... )
FeatureFlag ¶
Bases: str, Enum
Enumeration of supported feature flags for fabric-cicd.
CONTINUE_ON_SHORTCUT_FAILURE class-attribute instance-attribute ¶
Set to allow deployment to continue even when shortcuts fail to publish.
DISABLE_PRINT_IDENTITY class-attribute instance-attribute ¶
Set to disable printing the executing identity name.
DISABLE_WORKSPACE_FOLDER_PUBLISH class-attribute instance-attribute ¶
Set to disable deploying workspace sub folders.
ENABLE_ENVIRONMENT_VARIABLE_REPLACEMENT class-attribute instance-attribute ¶
Set to enable the use of pipeline variables.
ENABLE_EVENTHOUSE_UNPUBLISH class-attribute instance-attribute ¶
Set to enable the deletion of Eventhouses.
ENABLE_EXCLUDE_FOLDER class-attribute instance-attribute ¶
Set to enable folder-based exclusion during publish operations.
ENABLE_EXPERIMENTAL_FEATURES class-attribute instance-attribute ¶
Set to enable experimental features, such as selective deployments.
ENABLE_INCLUDE_FOLDER class-attribute instance-attribute ¶
Set to enable folder-based inclusion during publish operations.
ENABLE_ITEMS_TO_INCLUDE class-attribute instance-attribute ¶
Set to enable selective publishing/unpublishing of items.
ENABLE_KQLDATABASE_UNPUBLISH class-attribute instance-attribute ¶
Set to enable the deletion of KQL Databases (attached to Eventhouses).
ENABLE_LAKEHOUSE_UNPUBLISH class-attribute instance-attribute ¶
Set to enable the deletion of Lakehouses.
ENABLE_RESPONSE_COLLECTION class-attribute instance-attribute ¶
Set to enable collection of API responses during publish operations.
ENABLE_SHORTCUT_EXCLUDE class-attribute instance-attribute ¶
Set to enable selective publishing of shortcuts in a Lakehouse.
ENABLE_SHORTCUT_PUBLISH class-attribute instance-attribute ¶
Set to enable deploying shortcuts with the lakehouse.
ENABLE_SQLDATABASE_UNPUBLISH class-attribute instance-attribute ¶
Set to enable the deletion of SQL Databases.
ENABLE_WAREHOUSE_UNPUBLISH class-attribute instance-attribute ¶
Set to enable the deletion of Warehouses.
ItemType ¶
Bases: str, Enum
Enumeration of supported Microsoft Fabric item types.
append_feature_flag ¶
change_log_level ¶
configure_external_file_logging ¶
Configure fabric_cicd package logging to integrate with an external logger's file handler. This is an advanced alternative to the default file logging configuration when level is set to DEBUG via change_log_level().
Extracts the file handler from the provided logger and configures fabric_cicd to append only DEBUG logs (e.g., API request/response details) to the same file. The external logger retains full ownership of the handler, including file rotation (if applicable) and lifecycle management.
Note
-
This function resets logging configuration. Use as an alternative to
change_log_level()ordisable_file_logging(), not in combination -
Only DEBUG logs from the fabric_cicd package are written to the log file. Exception messages are displayed on the console, but full stack traces are not written to the external log file
-
Console output remains at INFO level (default fabric_cicd console behavior)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
external_logger | Logger | The external logger instance that has a | required |
Raises:
| Type | Description |
|---|---|
ValueError | If no file handler is found on the provided logger. |
Examples:
General usage:
>>> import logging
>>> from logging.handlers import RotatingFileHandler
>>> from fabric_cicd import configure_external_file_logging
...
>>> # Set up your own logger with a file handler
>>> my_logger = logging.getLogger("MyApp")
>>> handler = RotatingFileHandler("app.log", maxBytes=5*1024*1024, backupCount=7)
>>> handler.setFormatter(logging.Formatter("%(asctime)s - %(levelname)s - %(message)s"))
>>> my_logger.addHandler(handler)
...
>>> # Configure fabric_cicd to use the same file
>>> configure_external_file_logging(my_logger)
deploy_with_config ¶
deploy_with_config(
config_file_path: str,
environment: str = "N/A",
token_credential: Optional[TokenCredential] = None,
config_override: Optional[dict] = None,
) -> DeploymentResult
Deploy items using YAML configuration file with environment-specific settings. This function provides a simplified deployment interface that loads configuration from a YAML file and executes deployment operations based on environment-specific settings. It constructs the necessary FabricWorkspace object internally and handles publish/unpublish operations according to the configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config_file_path | str | Path to the YAML configuration file as a string. | required |
environment | str | Environment name to use for deployment (e.g., 'dev', 'test', 'prod'), if missing defaults to 'N/A'. | 'N/A' |
token_credential | Optional[TokenCredential] | Optional Azure token credential for authentication. | None |
config_override | Optional[dict] | Optional dictionary to override specific configuration values. | None |
Returns:
| Name | Type | Description |
|---|---|---|
DeploymentResult | DeploymentResult | A result object containing the deployment status and message. The status will be DeploymentStatus.COMPLETED on success. |
Raises:
| Type | Description |
|---|---|
InputError | If configuration file is invalid or environment not found. |
FileNotFoundError | If configuration file doesn't exist. |
Examples:
Basic usage
>>> from fabric_cicd import deploy_with_config
>>> result = deploy_with_config(
... config_file_path="workspace/config.yml",
... environment="prod"
... )
>>> print(result.status) # DeploymentStatus.COMPLETED
>>> print(result.message) # "Deployment completed successfully"
With custom authentication
>>> from fabric_cicd import deploy_with_config
>>> from azure.identity import ClientSecretCredential
>>> credential = ClientSecretCredential(tenant_id, client_id, client_secret)
>>> result = deploy_with_config(
... config_file_path="workspace/config.yml",
... environment="prod",
... token_credential=credential
... )
With override configuration
>>> from fabric_cicd import deploy_with_config
>>> from azure.identity import ClientSecretCredential
>>> credential = ClientSecretCredential(tenant_id, client_id, client_secret)
>>> result = deploy_with_config(
... config_file_path="workspace/config.yml",
... environment="prod",
... config_override={
... "core": {
... "item_types_in_scope": ["Notebook"]
... },
... "publish": {
... "skip": {
... "prod": False
... }
... }
... }
... )
disable_file_logging ¶
Disable file logging for the fabric_cicd package.
When called, no log file will be created and only console logging will occur at the default INFO level.
Note
- This function is intended to be used as an alternative to
change_log_level()orconfigure_external_file_logging(), not in combination with them as this will reset logging configurations to INFO-level console output only. - Exception messages will still be displayed on the console, but full stack traces will not be written to any log file or console.
Examples:
Basic usage
publish_all_items ¶
publish_all_items(
fabric_workspace_obj: FabricWorkspace,
item_name_exclude_regex: Optional[str] = None,
folder_path_exclude_regex: Optional[str] = None,
folder_path_to_include: Optional[list[str]] = None,
items_to_include: Optional[list[str]] = None,
shortcut_exclude_regex: Optional[str] = None,
) -> Optional[dict]
Publishes all items defined in the item_type_in_scope list of the given FabricWorkspace object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fabric_workspace_obj | FabricWorkspace | The FabricWorkspace object containing the items to be published. | required |
item_name_exclude_regex | Optional[str] | Regex pattern to exclude specific items from being published. | None |
folder_path_exclude_regex | Optional[str] | Regex pattern matched against folder paths (e.g., "/folder_name") to exclude folders and their items from being published. | None |
folder_path_to_include | Optional[list[str]] | List of folder paths in the format "/folder_name"; only the specified folders and their items will be published. | None |
items_to_include | Optional[list[str]] | List of items in the format "item_name.item_type" that should be published. | None |
shortcut_exclude_regex | Optional[str] | Regex pattern to exclude specific shortcuts from being published in lakehouses. | None |
Returns:
| Type | Description |
|---|---|
Optional[dict] | Dict containing all API responses if the "enable_response_collection" feature flag is enabled and responses were collected, otherwise None. |
folder_path_exclude_regex
This is an experimental feature in fabric-cicd. Use at your own risk as selective deployments are not recommended due to item dependencies. Cannot be used together with folder_path_to_include for the same environment. To enable this feature, see How To -> Optional Features for information on which flags to enable.
folder_path_to_include
This is an experimental feature in fabric-cicd. Use at your own risk as selective deployments are not recommended due to item dependencies. Cannot be used together with folder_path_exclude_regex for the same environment. To enable this feature, see How To -> Optional Features for information on which flags to enable.
items_to_include
This is an experimental feature in fabric-cicd. Use at your own risk as selective deployments are not recommended due to item dependencies. To enable this feature, see How To -> Optional Features for information on which flags to enable.
shortcut_exclude_regex
This is an experimental feature in fabric-cicd. Use at your own risk as selective shortcut deployments may result in missing data dependencies. To enable this feature, see How To -> Optional Features for information on which flags to enable.
Examples:
Basic usage
>>> from fabric_cicd import FabricWorkspace, publish_all_items
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
With regex name exclusion
>>> from fabric_cicd import FabricWorkspace, publish_all_items
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> exclude_regex = ".*_do_not_publish"
>>> publish_all_items(workspace, item_name_exclude_regex=exclude_regex)
With folder exclusion
>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_exclude_folder")
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> folder_exclude_regex = "^/legacy"
>>> publish_all_items(workspace, folder_path_exclude_regex=folder_exclude_regex)
With folder inclusion
>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_include_folder")
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> folder_path_to_include = ["/subfolder"]
>>> publish_all_items(workspace, folder_path_to_include=folder_path_to_include)
With items to include
>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_items_to_include")
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> items_to_include = ["Hello World.Notebook", "Hello.Environment"]
>>> publish_all_items(workspace, items_to_include=items_to_include)
With shortcut exclusion
>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_shortcut_exclude")
>>> append_feature_flag("enable_shortcut_publish")
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Lakehouse"]
... )
>>> shortcut_exclude_regex = "^temp_.*" # Exclude shortcuts starting with "temp_"
>>> publish_all_items(workspace, shortcut_exclude_regex=shortcut_exclude_regex)
With response collection
>>> from fabric_cicd import FabricWorkspace, publish_all_items, append_feature_flag
>>> append_feature_flag("enable_response_collection")
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> responses = publish_all_items(workspace)
>>> # Access all responses
>>> print(responses)
>>> # Access individual item responses
>>> notebook_response = workspace.responses["Notebook"]["Hello World"]
unpublish_all_orphan_items ¶
unpublish_all_orphan_items(
fabric_workspace_obj: FabricWorkspace,
item_name_exclude_regex: str = "^$",
items_to_include: Optional[list[str]] = None,
) -> None
Unpublishes all orphaned items not present in the repository except for those matching the exclude regex.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fabric_workspace_obj | FabricWorkspace | The FabricWorkspace object containing the items to be published. | required |
item_name_exclude_regex | str | Regex pattern to exclude specific items from being unpublished. Default is '^$' which will exclude nothing. | '^$' |
items_to_include | Optional[list[str]] | List of items in the format "item_name.item_type" that should be unpublished. | None |
items_to_include
This is an experimental feature in fabric-cicd. Use at your own risk as selective unpublishing is not recommended due to item dependencies. To enable this feature, see How To -> Optional Features for information on which flags to enable.
Examples:
Basic usage
>>> from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
>>> unpublish_orphaned_items(workspace)
With regex name exclusion
>>> from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
>>> exclude_regex = ".*_do_not_delete"
>>> unpublish_orphaned_items(workspace, item_name_exclude_regex=exclude_regex)
With items to include
>>> from fabric_cicd import FabricWorkspace, publish_all_items, unpublish_all_orphan_items, append_feature_flag
>>> append_feature_flag("enable_experimental_features")
>>> append_feature_flag("enable_items_to_include")
>>> workspace = FabricWorkspace(
... workspace_id="your-workspace-id",
... repository_directory="/path/to/repo",
... item_type_in_scope=["Environment", "Notebook", "DataPipeline"]
... )
>>> publish_all_items(workspace)
>>> items_to_include = ["Hello World.Notebook", "Run Hello World.DataPipeline"]
>>> unpublish_orphaned_items(workspace, items_to_include=items_to_include)