Welcome to pyfabricops

A Python wrapper library for Microsoft Fabric (and Power BI) operations, providing a simple interface to the official Fabric REST APIs. Falls back to Power BI REST APIs where needed. Designed to run in Python notebooks, pure Python scripts or integrated into YAML-based workflows for CI/CD. Access to the repositoy on GitHub.

🚀 Features

• Authenticate using environment variables (GitHub Secrets, ADO Secrets, .env ...)
• Manage workspaces, capacities, semantic models, lakehouses, reports and connections
• Execute Git operations and automate Fabric deployment flows (Power BI inclusive)
• Deploy from Git with a plan: plan_all_items() shows what would change, and deploy_all_items() deploys only what changed since the last deployment, in dependency order, with the state and a lock per environment kept in OneLake or on a branch of the repository (Deployment)
• Tell how a workspace stands against the source with reconcile_items(), and restore what drifted with restore_items() (Reconciliation)
• Capture and Manage Git branches automatically for CI/CD scenarios
• Many use cases and scenarios including yaml for test and deploy using GitHub Actions

📃 Documentation

Access: https://pyfabricops.readthedocs.io/en/latest/

✅ Requirements

• Requires Python >=3.10,<3.15

⚒️ Installation

pip install -U pyfabricops

🛠️ Development setup

# Install uv
pip install uv

# Sync dev dependencies (creates .venv automatically)
uv sync --group dev

⚙️ Usage

Create a repository and clone it locally. Create a notebook or a script and import the library:

# Import the library
import pyfabricops as pf

Set the authentication provider

Set auth environment variables acording to your authentication method

Environment variables (.env, GitHub Secrets, Ado Secrets...)

pf.set_auth_provider("env")

This is the default behavior. You can set these in a .env file or directly in your environment (GitHub Secrets, ADO Secrets...).

Example .env file:

FAB_CLIENT_ID=your_client_id_here
FAB_CLIENT_SECRET=your_client_secret_here
FAB_TENANT_ID=your_tenant_id_here
FAB_USERNAME=your_username_here   # Necessary for some functions with no SPN support
FAB_PASSWORD=your_password_here   # Necessary for some functions with no SPN support

By default the "env" provider uses the Service Principal (client_credentials) flow. To authenticate as a user (ROPC / password grant) — e.g. in CI/CD pipelines where a Service Principal is not available — pass credential_type="user":

pf.set_auth_provider("env", credential_type="user")

OAuth (Interactive)

pf.set_auth_provider("oauth")

This will open a browser window for user authentication.

Fabric Notebook (Authenticated User)

pf.set_auth_provider("fabric")

This method is designed for use inside Microsoft Fabric notebooks where the user is already authenticated. It uses notebookutils.credentials.getToken() to retrieve the access token automatically. No browser authentication required - perfect for notebooks running in Fabric!

See more details in the authentication guide

Create a repository and clone it locally. Prepare your environment with the required variables according to your authentication method (GitHub Secrets, ADO Secrets, .env ...)

Branches configuration

Create a branches.json file in the root of your repository to define your branch mappings:

{
    "main": "-PRD",
    "master": "-PRD",
    "dev": "-DEV",
    "develop": "-DEV",
    "staging": "-STG"
}

This file maps your local branches to Fabric branches, allowing the library to automatically manage branch names for CI/CD scenarios.

🪄 Examples

The examples/ folder has runnable scripts that authenticate and export a workspace.

Template repository

pyfabricops-template is a repository to start a project from, with Use this template on GitHub or an import in Azure DevOps. Its script and pipelines, for GitHub Actions and Azure DevOps, deploy the items of a Fabric workspace to one workspace per environment, DEV from develop and PRD from main:

• with DEV connected to Git, every item type pyfabricops deploys goes to PRD, the IDs of DEV mapped to those of PRD with WorkspaceIdMap;
• with no workspace connected, the repository is the source of every environment, for variable libraries, semantic models and reports;
• each workspace may be on a Fabric capacity or Pro;
• a file per environment gives its workspace, the value set of its variable libraries and the parameters of its semantic models;
• the deployment state is kept on a branch of the repository, and a weekday drift report can restore what changed by hand.

More examples: https://github.com/alisonpezzott/pyfabricops-examples

🧬 Project Structure

src/
└── pyfabricops/
    ├── api/
    │   ├── __init__.py
    │   ├── api.py
    │   ├── auth.py
    │   └── scopes.py
    ├── cd/
    │   ├── __init__.py
    │   └── support_files.py
    ├── core/
    │   ├── __init__.py
    │   ├── capacities.py
    │   ├── connections.py
    │   ├── deployment_pipelines.py
    │   ├── domains.py
    │   ├── folders.py
    │   ├── gateways.py
    │   ├── gateways_encryp_creds.py
    │   ├── git.py
    │   ├── tags.py
    │   └── workspaces.py
    ├── dmv/
    │   ├── __init__.py
    │   └── dmv.py
    ├── graph/
    │   ├── __init__.py
    │   └── users.py
    ├── helpers/
    │   ├── __init__.py
    │   ├── data_pipelines.py
    │   ├── data_pipelines.py
    │   ├── dataflows_gen1.py
    │   ├── dataflows_gen2.py
    │   ├── environments.py
    │   ├── folders.py
    │   ├── items.py
    │   ├── lakehouses.py
    │   ├── notebooks.py
    │   ├── reports.py
    │   ├── semantic_models.py
    │   ├── warehouses.py
    │   └── workspaces.py
    ├── items/
    │   ├── __init__.py
    │   ├── data_pipelines.py
    │   ├── dataflows_gen1.py
    │   ├── dataflows_gen2.py
    │   ├── environments.py
    │   ├── items.py
    │   ├── lakehouses.py
    │   ├── notebooks.py
    │   ├── reports.py
    │   ├── semantic_models.py
    │   ├── shortcuts.py
    │   ├── spark.py
    │   ├── variable_libraries.py
    │   └── warehouses.py
    ├── utils/
    │   ├── __init__.py
    │   ├── decorators.py
    │   ├── exceptions.py
    │   ├── logging.py
    │   ├── schemas.py
    │   └── utils.py
    ├── __init__.py
    └── _version.py

Logging configuration

The custom logging system implemented in pyfabricops provides a complete and flexible solution for monitoring and debugging the library.

🎨 Custom Formatting

• Automatic colors: Different colors for each log level (DEBUG=Cyan, INFO=Green, WARNING=Yellow, ERROR=Red, CRITICAL=Magenta)
• Multiple styles:
  • minimal: Only timestamp, level and message
  • standard: Includes module name in compact form
  • detailed: Complete format with all information

🎛️ Easy Configuration

import pyfabricops as pf

# Basic configuration
pf.setup_logging(level="INFO", format_style="standard")

# Debug mode for development
pf.enable_debug_mode(include_external=False)

# Disable logging completely
pf.disable_logging()

# Reset to default configuration
pf.reset_logging()

For complete logging configuration options, refer to the logging_system.md

❤️Contributing

1. Fork this repository
2. Create a new branch (feat/my-feature)
3. Run uv sync --group dev to set up the development environment
4. Run uv run ruff format --check --diff . && uv run ruff check .
5. Run uv run pytest -s -x --cov=pyfabricops -v to run tests
6. Submit a pull request to branch develop 🚀

🚀 Publishing

For Maintainers

To publish a new version to PyPI:

1. Update the version in pyproject.toml and src/pyfabricops/_version.py, then run uv lock
2. Add the version's section to CHANGELOG.md
3. Commit and push changes
4. Create a new release on GitHub, tagged v and the version (e.g., v0.7.0)
5. The GitHub Action will automatically:
   • Check that the tag matches the version
   • Run tests
   • Build and check the package
   • Publish to PyPI

Testing with TestPyPI

# Build and publish to TestPyPI
uv build
uv publish --publish-url https://test.pypi.org/legacy/ --token <your-testpypi-token>

# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ pyfabricops

Prerequisites for Publishing

• Set up a PyPI account at https://pypi.org/
• Generate an API token at https://pypi.org/manage/account/token/
• Add the token as PYPI_TOKEN secret in GitHub repository settings

🐞 Issues

If you encounter any issues, please report them at https://github.com/alisonpezzott/pyfabricops/issues

⚖️ License

This project is licensed under the MIT License – see the LICENSE file for details.

🌟 Acknowledgements

Created and maintained by Alison Pezzott Feedback, issues and stars are welcome 🌟