msdev-kit 0.1.0__tar.gz → 0.1.1__tar.gz

{msdev_kit-0.1.0 → msdev_kit-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: msdev-kit
-Version: 0.1.0
+Version: 0.1.1
 Summary: Microsoft developer toolkit: Fabric, MS Graph, and SharePoint
 License: MIT
 Author: Bernardo Rufino
@@ -32,21 +32,35 @@ Description-Content-Type: text/markdown
 
 Microsoft developer toolkit for Python: Fabric/Power BI, MS Graph (Entra), and SharePoint.
 
-## Installation
+[![PyPI version](https://img.shields.io/pypi/v/msdev-kit)](https://pypi.org/project/msdev-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/msdev-kit)](https://pypi.org/project/msdev-kit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
 
-### Install from PyPI (recommended)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Fabric & Power BI](#fabric--power-bi) — workspaces, datasets, reports, dataflows, pipelines, notebooks, and more
+- [MS Graph (Entra)](#ms-graph-entra) — users and groups via MS Graph API
+- [SharePoint](#sharepoint) — files and folders via MS Graph API
+- [Limitations](#limitations)
+
+---
+
+## Installation
 
 ```shell
 pip install msdev-kit
 ```
 
-### Install from GitHub
+Or install from GitHub:
 
 ```shell
 pip install git+https://github.com/Bernardo-Rufino/msdev-kit.git
 ```
 
-### Install for local development
+For local development:
 
 ```shell
 git clone https://github.com/Bernardo-Rufino/msdev-kit.git
@@ -54,32 +68,64 @@ cd msdev-kit
 pip install -e .
 ```
 
+**Requirements:** Python >= 3.10, an Azure app registration with a client ID and client secret.
+
 ---
 
-## Prerequisites
+## Quick Start
 
-- Python >= 3.10
-- An Azure app registration with a client ID and client secret
+```python
+from msdev_kit import Auth
+from msdev_kit.fabric import Workspace
+from msdev_kit.graph import GraphClient
+from msdev_kit.sharepoint import SharePointClient
 
-## Getting Started
+# authenticate
+auth = Auth(tenant_id="...", client_id="...", client_secret="...")
 
-### Authentication
+# fabric: list workspaces
+ws = Workspace(auth.get_token('fabric'))
+workspaces = ws.list_workspaces_for_user()
 
-All classes use a shared `Auth` object. You can use different service principals for different services:
+# graph: look up a user
+graph = GraphClient(auth)
+user_id = graph.get_user_id('user@company.com')
+
+# sharepoint: download a file
+sp = SharePointClient(auth, sp_hostname='company', sp_site_path='sites/DataTeam')
+sp.download_file('/Reports/monthly.xlsx', local_dir='./downloads')
+```
+
+---
+
+## Authentication
+
+All classes use a shared `Auth` object. You can use different service principals for different services — instantiate one `Auth` per SPN:
 
 ```python
 from msdev_kit import Auth
 
 # service principal auth
-auth = Auth(tenant_id="...", client_id="...", client_secret="...")
+fabric_auth = Auth(tenant_id="...", client_id="spn-a", client_secret="...")
+graph_auth  = Auth(tenant_id="...", client_id="spn-b", client_secret="...")
+```
 
-token = auth.get_token()             # Power BI API (default)
-token = auth.get_token('fabric')     # Fabric API
-token = auth.get_token('graph')      # MS Graph API
-token = auth.get_token('azure')      # Azure Management API
+### Supported scopes
 
-# interactive user auth
-token = auth.get_token_for_user('pbi')
+| Service | Scope | Usage |
+|---|---|---|
+| `pbi` (default) | Power BI API | `auth.get_token()` or `auth.get_token('pbi')` |
+| `fabric` | Fabric API | `auth.get_token('fabric')` |
+| `graph` | MS Graph API | `auth.get_token('graph')` |
+| `azure` | Azure Management API | `auth.get_token('azure')` |
+
+### Interactive user auth
+
+For scenarios requiring user context (e.g., RLS-enabled datasets):
+
+```python
+token = auth.get_token_for_user('pbi')     # opens browser for login
+token = auth.get_token_for_user('fabric')
 ```
 
 ### Credentials
@@ -94,24 +140,34 @@ CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
 
 ---
 
-## Sub-packages
-
-### `msdev_kit.fabric` — Fabric & Power BI
-
-All existing Fabric/Power BI classes, accessed via the `fabric` sub-package:
+## Fabric & Power BI
 
 ```python
-from msdev_kit.fabric import Workspace, Dataset, Report, Dataflow, Pipeline
 from msdev_kit import Auth
+from msdev_kit.fabric import Workspace, Dataset, Report, Dataflow, Pipeline
 
 auth = Auth(tenant_id, client_id, client_secret)
-ws = Workspace(auth.get_token('fabric'))
 ```
 
-#### Workspace
+Fabric classes take a token string — call `auth.get_token('fabric')` or `auth.get_token('pbi')` depending on the API.
+
+- [Workspace](#workspace) — workspaces, users, permissions
+- [Dataset](#dataset) — semantic models, DAX queries, permissions
+- [Report](#report) — metadata, definitions, visuals, measures
+- [Dataflow](#dataflow) — Gen1, Gen2, Gen2 CI/CD management
+- [Pipeline](#pipeline) — Data Pipeline management
+- [Other modules](#other-modules) — Capacity, Admin, KQL, Notebook, Database
+
+### Workspace
 
 Manage Power BI workspaces, users, and permissions.
 
+```python
+ws = Workspace(auth.get_token('pbi'))
+workspaces = ws.list_workspaces_for_user()
+ws.add_user('user@company.com', workspace_id, 'Member', 'User')
+```
+
 | Method | Description |
 |---|---|
 | `list_workspaces_for_user(...)` | List all workspaces the user has access to, with optional filters. |
@@ -123,16 +179,21 @@ Manage Power BI workspaces, users, and permissions.
 | `remove_user(user_principal_name, workspace_id)` | Remove a user from a workspace. |
 | `batch_update_user(user, workspaces_list)` | Batch update a user across multiple workspaces. |
 
-#### Dataset
+### Dataset
 
 Manage datasets (semantic models), permissions, and execute DAX queries.
 
+```python
+ds = Dataset(auth.get_token('pbi'))
+result = ds.execute_query(workspace_id, dataset_id, "EVALUATE Sales")
+```
+
 | Method | Description |
 |---|---|
 | `list_datasets(workspace_id)` | List all datasets in a workspace. |
 | `get_dataset_details(workspace_id, dataset_id)` | Get details of a specific dataset. |
-| `get_dataset_name(workspace_id, dataset_id)` | Resolve the display name of a dataset. Tries the PBI API first, falls back to the Fabric semantic models API. |
-| `execute_query(workspace_id, dataset_id, query)` | Execute a DAX query against a dataset. Runs a COUNTROWS pre-check to detect if API row/value limits would truncate the result and returns truncation metadata. |
+| `get_dataset_name(workspace_id, dataset_id)` | Resolve the display name of a dataset. Tries PBI API first, falls back to Fabric semantic models API. |
+| `execute_query(workspace_id, dataset_id, query)` | Execute a DAX query. Runs a COUNTROWS pre-check to detect truncation. |
 | `list_users(workspace_id, dataset_id)` | List users with access to a dataset. |
 | `add_user(user_principal_name, workspace_id, dataset_id, access_right)` | Grant a user access to a dataset. |
 | `update_user(user_principal_name, workspace_id, dataset_id, access_right)` | Update a user's access to a dataset. |
@@ -140,29 +201,46 @@ Manage datasets (semantic models), permissions, and execute DAX queries.
 | `list_dataset_related_reports(workspace_id, dataset_id)` | List all reports linked to a dataset. |
 | `export_dataset_related_reports(workspace_id, dataset_id)` | Export all reports linked to a dataset as `.pbix` files. |
 
-#### Report
+### Report
 
 Retrieve report metadata, definitions, visuals, and report-level measures.
 
+```python
+rpt = Report(auth.get_token('pbi'))
+pages = rpt.list_report_pages(workspace_id, report_id)
+```
+
 | Method | Description |
 |---|---|
 | `list_reports(workspace_id)` | List all reports in a workspace. |
 | `get_report_metadata(workspace_id, report_id)` | Get metadata for a specific report. |
 | `get_report_name(workspace_id, report_id)` | Get a report's display name. |
 | `list_report_pages(workspace_id, report_id)` | List all pages in a report. |
-| `get_report_json_pages_and_visuals(json_data, workspace_id, report_id)` | Parse a PBIR-Legacy report JSON and extract pages and visual details into a DataFrame. |
+| `get_report_json_pages_and_visuals(json_data, workspace_id, report_id)` | Parse a PBIR-Legacy report JSON and extract pages/visuals into a DataFrame. |
 | `get_legacy_report_json(workspace_id, report_id, operations)` | Get and decode the full report definition for PBIR-Legacy reports. |
 | `export_report(workspace_id, report_id, ...)` | Export a report as a `.pbix` file. |
-| `get_report_measures(workspace_id, report_id, operations)` | Extract report-level measures and generate a DAX Query View script. Supports both PBIR and PBIR-Legacy formats. |
-| `rebind_report(workspace_id, report_id, new_dataset_id, new_dataset_workspace_id, admin, dataset)` | Rebind a report to a new dataset/semantic model and migrate Read access to the new dataset. |
+| `get_report_measures(workspace_id, report_id, operations)` | Extract report-level measures and generate a DAX Query View script. |
+| `rebind_report(workspace_id, report_id, new_dataset_id, ...)` | Rebind a report to a new dataset and migrate Read access. |
 
-#### Dataflow
+### Dataflow
 
 Manage Power BI and Fabric dataflows, including Gen1, Gen2, and Gen2 CI/CD.
 
+```python
+df = Dataflow(auth.get_token('fabric'))
+
+# upgrade Gen1 to Gen2 CI/CD
+result = df.upgrade_to_gen2_cicd(
+    workspace_id='<workspace_id>',
+    dataflow_id='<gen1_dataflow_id>',
+    display_name='my_dataflow_cicd',
+    source_type='gen1'
+)
+```
+
 | Method | Description |
 |---|---|
-| `list_dataflows(workspace_id)` | List all dataflows in a workspace (Gen1, Gen2 standard, and Gen2 CI/CD). Results are merged and deduplicated with a `source` column. |
+| `list_dataflows(workspace_id)` | List all dataflows (Gen1, Gen2, Gen2 CI/CD), merged and deduplicated. |
 | `get_dataflow_details(workspace_id, dataflow_id)` | Get details of a specific dataflow. |
 | `get_dataflow_name(workspace_id, dataflow_id)` | Resolve the display name of a dataflow. |
 | `create_dataflow(workspace_id, dataflow_content)` | Create a new Power BI dataflow. |
@@ -171,39 +249,83 @@ Manage Power BI and Fabric dataflows, including Gen1, Gen2, and Gen2 CI/CD.
 | `get_dataflow_gen2_definition(workspace_id, dataflow_id)` | Get the definition of a Dataflow Gen2 CI/CD item. |
 | `create_dataflow_gen2_from_definition(workspace_id, display_name, definition)` | Create a Dataflow Gen2 CI/CD from a definition. |
 | `update_dataflow_gen2_from_definition(workspace_id, dataflow_id, display_name, definition)` | Update an existing Dataflow Gen2 CI/CD definition. |
-| `get_data_destinations(workspace_id, dataflow_id)` | Get the data destination details for each table in a dataflow. |
-| `change_data_destination(workspace_id, dataflow_id, destination_type, ...)` | Change a dataflow's data destination (Lakehouse/Warehouse). Supports `preview`, `replace`, and `create` modes. |
-| `create_dataflow_with_new_destination(workspace_id, dataflow_id, ...)` | Create a new Gen2 CI/CD dataflow from an existing one with a different data destination. |
+| `get_data_destinations(workspace_id, dataflow_id)` | Get data destination details for each table in a dataflow. |
+| `change_data_destination(workspace_id, dataflow_id, destination_type, ...)` | Change data destination (Lakehouse/Warehouse). Modes: `preview`, `replace`, `create`. |
+| `create_dataflow_with_new_destination(workspace_id, dataflow_id, ...)` | Create a new Gen2 CI/CD dataflow with a different data destination. |
 | `upgrade_to_gen2_cicd(...)` | Upgrade a Gen1 or Gen2 (standard) dataflow to Gen2 CI/CD. |
 
-#### Pipeline
+### Pipeline
 
 Manage Fabric Data Pipelines.
 
+```python
+pipe = Pipeline(auth.get_token('fabric'))
+activities = pipe.get_pipeline_activities(workspace_id, 'My Pipeline')
+```
+
 | Method | Description |
 |---|---|
 | `list_pipelines(workspace_id)` | List all Fabric Data Pipelines in a workspace. |
 | `get_pipeline(workspace_id, pipeline_id)` | Get the metadata of a specific pipeline. |
-| `get_pipeline_definition(workspace_id, pipeline_id)` | Get the full definition of a Fabric Data Pipeline. |
+| `get_pipeline_definition(workspace_id, pipeline_id)` | Get the full definition of a pipeline. |
 | `update_pipeline_definition(workspace_id, pipeline_id, definition)` | Update an existing pipeline definition. |
-| `get_pipeline_activities(workspace_id, pipeline_id_or_name)` | Get the list of activities from a pipeline. |
-| `find_pipelines_by_dataflow(workspace_id, dataflow_id_or_name)` | Find all pipelines in a workspace that reference a specific dataflow. |
-| `replace_dataflow_id_in_pipeline(workspace_id, pipeline_id, old_dataflow_id, new_dataflow_id)` | Replace a dataflow ID in all RefreshDataflow activities of a pipeline. |
+| `get_pipeline_activities(workspace_id, pipeline_id_or_name)` | Get activities from a pipeline. Accepts ID or display name. |
+| `find_pipelines_by_dataflow(workspace_id, dataflow_id_or_name)` | Find pipelines that reference a specific dataflow. |
+| `replace_dataflow_id_in_pipeline(workspace_id, pipeline_id, old_id, new_id)` | Replace a dataflow ID in all RefreshDataflow activities. |
 
-#### Other modules
+<details>
+<summary><strong>Example: replacing a dataflow destination and updating pipelines</strong></summary>
 
-| Module | Description |
-|---|---|
-| `Capacity` | Monitor and manage Power BI and Fabric capacities. |
-| `Operations` | Track long-running Fabric API operations. |
-| `Admin` | Power BI Admin API operations. |
-| `KQLDatabase` | Query Kusto (KQL) databases in Microsoft Fabric. |
-| `Notebook` | Manage Fabric notebooks. |
-| `Database` | Query and write to SQL databases (Lakehouse, Warehouse) via ODBC. |
+When `change_data_destination(mode='replace')` is used on a standard Gen2 dataflow, the original is deleted and a new CI/CD dataflow is created with a new ID. Pipelines referencing the old ID must be updated:
+
+```python
+from msdev_kit import Auth
+from msdev_kit.fabric import Dataflow, Pipeline
+
+auth = Auth(tenant_id, client_id, client_secret)
+dataflow = Dataflow(auth.get_token('pbi'))
+pipeline = Pipeline(auth.get_token('fabric'))
+
+workspace_id = '<workspace_id>'
+old_dataflow_id = '<dataflow_id>'
+
+# 1. replace dataflow destination (creates new CI/CD, deletes original)
+result = dataflow.change_data_destination(
+    workspace_id=workspace_id,
+    dataflow_id=old_dataflow_id,
+    destination_type='Warehouse',
+    destination_workspace_id=workspace_id,
+    destination_item_id='<warehouse_id>',
+    mode='replace'
+)
+new_dataflow_id = result['content']['id']
+
+# 2. find pipelines referencing the old dataflow ID
+matches = pipeline.find_pipelines_by_dataflow(workspace_id, old_dataflow_id)
+
+# 3. update each pipeline to use the new ID
+for m in matches['content']:
+    pipeline.replace_dataflow_id_in_pipeline(
+        workspace_id, m['pipeline_id'], old_dataflow_id, new_dataflow_id
+    )
+```
+
+</details>
+
+### Other modules
+
+| Module | Class | Description |
+|---|---|---|
+| Capacity | `Capacity` | Monitor and manage Power BI and Fabric capacities. |
+| Operations | `Operations` | Track long-running Fabric API operations. |
+| Admin | `Admin` | Power BI Admin API operations. |
+| KQL | `KQLDatabase` | Query Kusto (KQL) databases in Microsoft Fabric. |
+| Notebook | `Notebook` | Manage Fabric notebooks (list, get metadata). |
+| Database | `Database` | Query and write to SQL databases (Lakehouse, Warehouse) via ODBC. |
 
 ---
 
-### `msdev_kit.graph` — MS Graph (Entra)
+## MS Graph (Entra)
 
 Manage Entra ID (Azure AD) users and groups via the MS Graph API.
 
@@ -214,8 +336,12 @@ from msdev_kit.graph import GraphClient
 auth = Auth(tenant_id, client_id, client_secret)
 graph = GraphClient(auth)
 
+# look up a user and add them to a group
 user_id = graph.get_user_id('user@company.com')
 group_id = graph.get_group_id('Data Team')
+graph.add_group_member(group_id, user_id)
+
+# list all members of a group
 members = graph.list_group_members(group_id)
 ```
 
@@ -229,7 +355,7 @@ members = graph.list_group_members(group_id)
 
 ---
 
-### `msdev_kit.sharepoint` — SharePoint
+## SharePoint
 
 Manage SharePoint files and folders via MS Graph API (no ACS/Office365 dependency).
 
@@ -240,9 +366,15 @@ from msdev_kit.sharepoint import SharePointClient
 auth = Auth(tenant_id, client_id, client_secret)
 sp = SharePointClient(auth, sp_hostname='company', sp_site_path='sites/DataTeam')
 
+# download a file
 sp.download_file('/Reports/monthly.xlsx', local_dir='./downloads')
+
+# upload a file (from path or bytes)
 sp.upload_file('/Reports/updated.xlsx', source='./local/updated.xlsx')
-sp.create_folder('/Reports/2026')
+sp.upload_file('/Reports/data.csv', source=csv_bytes, content_type='text/csv')
+
+# create nested folders
+sp.create_folder('/Reports/2026/Q1')
 ```
 
 | Method | Description |
@@ -251,7 +383,16 @@ sp.create_folder('/Reports/2026')
 | `upload_file(remote_path, source, content_type?)` | Upload/overwrite a file. `source` is a local file path (str) or raw bytes. |
 | `create_folder(folder_path)` | Create a folder and all intermediate folders. |
 
-Hostname and site path inputs are normalized automatically — accepts short names (`company`), FQDNs (`company.sharepoint.com`), or full URLs (`https://company.sharepoint.com`).
+Hostname and site path inputs are normalized automatically:
+
+| Input | Normalized to |
+|---|---|
+| `company` | `company.sharepoint.com` |
+| `company.sharepoint.com` | `company.sharepoint.com` |
+| `https://company.sharepoint.com` | `company.sharepoint.com` |
+| `DataTeam` | `sites/DataTeam` |
+| `sites/DataTeam` | `sites/DataTeam` |
+| `/sites/DataTeam` | `sites/DataTeam` |
 
 ---
 

{msdev_kit-0.1.0 → msdev_kit-0.1.1}/README.md

@@ -2,21 +2,35 @@
 
 Microsoft developer toolkit for Python: Fabric/Power BI, MS Graph (Entra), and SharePoint.
 
-## Installation
+[![PyPI version](https://img.shields.io/pypi/v/msdev-kit)](https://pypi.org/project/msdev-kit/)
+[![Python](https://img.shields.io/pypi/pyversions/msdev-kit)](https://pypi.org/project/msdev-kit/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Table of Contents
 
-### Install from PyPI (recommended)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Authentication](#authentication)
+- [Fabric & Power BI](#fabric--power-bi) — workspaces, datasets, reports, dataflows, pipelines, notebooks, and more
+- [MS Graph (Entra)](#ms-graph-entra) — users and groups via MS Graph API
+- [SharePoint](#sharepoint) — files and folders via MS Graph API
+- [Limitations](#limitations)
+
+---
+
+## Installation
 
 ```shell
 pip install msdev-kit
 ```
 
-### Install from GitHub
+Or install from GitHub:
 
 ```shell
 pip install git+https://github.com/Bernardo-Rufino/msdev-kit.git
 ```
 
-### Install for local development
+For local development:
 
 ```shell
 git clone https://github.com/Bernardo-Rufino/msdev-kit.git
@@ -24,32 +38,64 @@ cd msdev-kit
 pip install -e .
 ```
 
+**Requirements:** Python >= 3.10, an Azure app registration with a client ID and client secret.
+
 ---
 
-## Prerequisites
+## Quick Start
 
-- Python >= 3.10
-- An Azure app registration with a client ID and client secret
+```python
+from msdev_kit import Auth
+from msdev_kit.fabric import Workspace
+from msdev_kit.graph import GraphClient
+from msdev_kit.sharepoint import SharePointClient
 
-## Getting Started
+# authenticate
+auth = Auth(tenant_id="...", client_id="...", client_secret="...")
 
-### Authentication
+# fabric: list workspaces
+ws = Workspace(auth.get_token('fabric'))
+workspaces = ws.list_workspaces_for_user()
 
-All classes use a shared `Auth` object. You can use different service principals for different services:
+# graph: look up a user
+graph = GraphClient(auth)
+user_id = graph.get_user_id('user@company.com')
+
+# sharepoint: download a file
+sp = SharePointClient(auth, sp_hostname='company', sp_site_path='sites/DataTeam')
+sp.download_file('/Reports/monthly.xlsx', local_dir='./downloads')
+```
+
+---
+
+## Authentication
+
+All classes use a shared `Auth` object. You can use different service principals for different services — instantiate one `Auth` per SPN:
 
 ```python
 from msdev_kit import Auth
 
 # service principal auth
-auth = Auth(tenant_id="...", client_id="...", client_secret="...")
+fabric_auth = Auth(tenant_id="...", client_id="spn-a", client_secret="...")
+graph_auth  = Auth(tenant_id="...", client_id="spn-b", client_secret="...")
+```
 
-token = auth.get_token()             # Power BI API (default)
-token = auth.get_token('fabric')     # Fabric API
-token = auth.get_token('graph')      # MS Graph API
-token = auth.get_token('azure')      # Azure Management API
+### Supported scopes
 
-# interactive user auth
-token = auth.get_token_for_user('pbi')
+| Service | Scope | Usage |
+|---|---|---|
+| `pbi` (default) | Power BI API | `auth.get_token()` or `auth.get_token('pbi')` |
+| `fabric` | Fabric API | `auth.get_token('fabric')` |
+| `graph` | MS Graph API | `auth.get_token('graph')` |
+| `azure` | Azure Management API | `auth.get_token('azure')` |
+
+### Interactive user auth
+
+For scenarios requiring user context (e.g., RLS-enabled datasets):
+
+```python
+token = auth.get_token_for_user('pbi')     # opens browser for login
+token = auth.get_token_for_user('fabric')
 ```
 
 ### Credentials
@@ -64,24 +110,34 @@ CLIENT_SECRET='<YOUR_CLIENT_SECRET>'
 
 ---
 
-## Sub-packages
-
-### `msdev_kit.fabric` — Fabric & Power BI
-
-All existing Fabric/Power BI classes, accessed via the `fabric` sub-package:
+## Fabric & Power BI
 
 ```python
-from msdev_kit.fabric import Workspace, Dataset, Report, Dataflow, Pipeline
 from msdev_kit import Auth
+from msdev_kit.fabric import Workspace, Dataset, Report, Dataflow, Pipeline
 
 auth = Auth(tenant_id, client_id, client_secret)
-ws = Workspace(auth.get_token('fabric'))
 ```
 
-#### Workspace
+Fabric classes take a token string — call `auth.get_token('fabric')` or `auth.get_token('pbi')` depending on the API.
+
+- [Workspace](#workspace) — workspaces, users, permissions
+- [Dataset](#dataset) — semantic models, DAX queries, permissions
+- [Report](#report) — metadata, definitions, visuals, measures
+- [Dataflow](#dataflow) — Gen1, Gen2, Gen2 CI/CD management
+- [Pipeline](#pipeline) — Data Pipeline management
+- [Other modules](#other-modules) — Capacity, Admin, KQL, Notebook, Database
+
+### Workspace
 
 Manage Power BI workspaces, users, and permissions.
 
+```python
+ws = Workspace(auth.get_token('pbi'))
+workspaces = ws.list_workspaces_for_user()
+ws.add_user('user@company.com', workspace_id, 'Member', 'User')
+```
+
 | Method | Description |
 |---|---|
 | `list_workspaces_for_user(...)` | List all workspaces the user has access to, with optional filters. |
@@ -93,16 +149,21 @@ Manage Power BI workspaces, users, and permissions.
 | `remove_user(user_principal_name, workspace_id)` | Remove a user from a workspace. |
 | `batch_update_user(user, workspaces_list)` | Batch update a user across multiple workspaces. |
 
-#### Dataset
+### Dataset
 
 Manage datasets (semantic models), permissions, and execute DAX queries.
 
+```python
+ds = Dataset(auth.get_token('pbi'))
+result = ds.execute_query(workspace_id, dataset_id, "EVALUATE Sales")
+```
+
 | Method | Description |
 |---|---|
 | `list_datasets(workspace_id)` | List all datasets in a workspace. |
 | `get_dataset_details(workspace_id, dataset_id)` | Get details of a specific dataset. |
-| `get_dataset_name(workspace_id, dataset_id)` | Resolve the display name of a dataset. Tries the PBI API first, falls back to the Fabric semantic models API. |
-| `execute_query(workspace_id, dataset_id, query)` | Execute a DAX query against a dataset. Runs a COUNTROWS pre-check to detect if API row/value limits would truncate the result and returns truncation metadata. |
+| `get_dataset_name(workspace_id, dataset_id)` | Resolve the display name of a dataset. Tries PBI API first, falls back to Fabric semantic models API. |
+| `execute_query(workspace_id, dataset_id, query)` | Execute a DAX query. Runs a COUNTROWS pre-check to detect truncation. |
 | `list_users(workspace_id, dataset_id)` | List users with access to a dataset. |
 | `add_user(user_principal_name, workspace_id, dataset_id, access_right)` | Grant a user access to a dataset. |
 | `update_user(user_principal_name, workspace_id, dataset_id, access_right)` | Update a user's access to a dataset. |
@@ -110,29 +171,46 @@ Manage datasets (semantic models), permissions, and execute DAX queries.
 | `list_dataset_related_reports(workspace_id, dataset_id)` | List all reports linked to a dataset. |
 | `export_dataset_related_reports(workspace_id, dataset_id)` | Export all reports linked to a dataset as `.pbix` files. |
 
-#### Report
+### Report
 
 Retrieve report metadata, definitions, visuals, and report-level measures.
 
+```python
+rpt = Report(auth.get_token('pbi'))
+pages = rpt.list_report_pages(workspace_id, report_id)
+```
+
 | Method | Description |
 |---|---|
 | `list_reports(workspace_id)` | List all reports in a workspace. |
 | `get_report_metadata(workspace_id, report_id)` | Get metadata for a specific report. |
 | `get_report_name(workspace_id, report_id)` | Get a report's display name. |
 | `list_report_pages(workspace_id, report_id)` | List all pages in a report. |
-| `get_report_json_pages_and_visuals(json_data, workspace_id, report_id)` | Parse a PBIR-Legacy report JSON and extract pages and visual details into a DataFrame. |
+| `get_report_json_pages_and_visuals(json_data, workspace_id, report_id)` | Parse a PBIR-Legacy report JSON and extract pages/visuals into a DataFrame. |
 | `get_legacy_report_json(workspace_id, report_id, operations)` | Get and decode the full report definition for PBIR-Legacy reports. |
 | `export_report(workspace_id, report_id, ...)` | Export a report as a `.pbix` file. |
-| `get_report_measures(workspace_id, report_id, operations)` | Extract report-level measures and generate a DAX Query View script. Supports both PBIR and PBIR-Legacy formats. |
-| `rebind_report(workspace_id, report_id, new_dataset_id, new_dataset_workspace_id, admin, dataset)` | Rebind a report to a new dataset/semantic model and migrate Read access to the new dataset. |
+| `get_report_measures(workspace_id, report_id, operations)` | Extract report-level measures and generate a DAX Query View script. |
+| `rebind_report(workspace_id, report_id, new_dataset_id, ...)` | Rebind a report to a new dataset and migrate Read access. |
 
-#### Dataflow
+### Dataflow
 
 Manage Power BI and Fabric dataflows, including Gen1, Gen2, and Gen2 CI/CD.
 
+```python
+df = Dataflow(auth.get_token('fabric'))
+
+# upgrade Gen1 to Gen2 CI/CD
+result = df.upgrade_to_gen2_cicd(
+    workspace_id='<workspace_id>',
+    dataflow_id='<gen1_dataflow_id>',
+    display_name='my_dataflow_cicd',
+    source_type='gen1'
+)
+```
+
 | Method | Description |
 |---|---|
-| `list_dataflows(workspace_id)` | List all dataflows in a workspace (Gen1, Gen2 standard, and Gen2 CI/CD). Results are merged and deduplicated with a `source` column. |
+| `list_dataflows(workspace_id)` | List all dataflows (Gen1, Gen2, Gen2 CI/CD), merged and deduplicated. |
 | `get_dataflow_details(workspace_id, dataflow_id)` | Get details of a specific dataflow. |
 | `get_dataflow_name(workspace_id, dataflow_id)` | Resolve the display name of a dataflow. |
 | `create_dataflow(workspace_id, dataflow_content)` | Create a new Power BI dataflow. |
@@ -141,39 +219,83 @@ Manage Power BI and Fabric dataflows, including Gen1, Gen2, and Gen2 CI/CD.
 | `get_dataflow_gen2_definition(workspace_id, dataflow_id)` | Get the definition of a Dataflow Gen2 CI/CD item. |
 | `create_dataflow_gen2_from_definition(workspace_id, display_name, definition)` | Create a Dataflow Gen2 CI/CD from a definition. |
 | `update_dataflow_gen2_from_definition(workspace_id, dataflow_id, display_name, definition)` | Update an existing Dataflow Gen2 CI/CD definition. |
-| `get_data_destinations(workspace_id, dataflow_id)` | Get the data destination details for each table in a dataflow. |
-| `change_data_destination(workspace_id, dataflow_id, destination_type, ...)` | Change a dataflow's data destination (Lakehouse/Warehouse). Supports `preview`, `replace`, and `create` modes. |
-| `create_dataflow_with_new_destination(workspace_id, dataflow_id, ...)` | Create a new Gen2 CI/CD dataflow from an existing one with a different data destination. |
+| `get_data_destinations(workspace_id, dataflow_id)` | Get data destination details for each table in a dataflow. |
+| `change_data_destination(workspace_id, dataflow_id, destination_type, ...)` | Change data destination (Lakehouse/Warehouse). Modes: `preview`, `replace`, `create`. |
+| `create_dataflow_with_new_destination(workspace_id, dataflow_id, ...)` | Create a new Gen2 CI/CD dataflow with a different data destination. |
 | `upgrade_to_gen2_cicd(...)` | Upgrade a Gen1 or Gen2 (standard) dataflow to Gen2 CI/CD. |
 
-#### Pipeline
+### Pipeline
 
 Manage Fabric Data Pipelines.
 
+```python
+pipe = Pipeline(auth.get_token('fabric'))
+activities = pipe.get_pipeline_activities(workspace_id, 'My Pipeline')
+```
+
 | Method | Description |
 |---|---|
 | `list_pipelines(workspace_id)` | List all Fabric Data Pipelines in a workspace. |
 | `get_pipeline(workspace_id, pipeline_id)` | Get the metadata of a specific pipeline. |
-| `get_pipeline_definition(workspace_id, pipeline_id)` | Get the full definition of a Fabric Data Pipeline. |
+| `get_pipeline_definition(workspace_id, pipeline_id)` | Get the full definition of a pipeline. |
 | `update_pipeline_definition(workspace_id, pipeline_id, definition)` | Update an existing pipeline definition. |
-| `get_pipeline_activities(workspace_id, pipeline_id_or_name)` | Get the list of activities from a pipeline. |
-| `find_pipelines_by_dataflow(workspace_id, dataflow_id_or_name)` | Find all pipelines in a workspace that reference a specific dataflow. |
-| `replace_dataflow_id_in_pipeline(workspace_id, pipeline_id, old_dataflow_id, new_dataflow_id)` | Replace a dataflow ID in all RefreshDataflow activities of a pipeline. |
+| `get_pipeline_activities(workspace_id, pipeline_id_or_name)` | Get activities from a pipeline. Accepts ID or display name. |
+| `find_pipelines_by_dataflow(workspace_id, dataflow_id_or_name)` | Find pipelines that reference a specific dataflow. |
+| `replace_dataflow_id_in_pipeline(workspace_id, pipeline_id, old_id, new_id)` | Replace a dataflow ID in all RefreshDataflow activities. |
 
-#### Other modules
+<details>
+<summary><strong>Example: replacing a dataflow destination and updating pipelines</strong></summary>
 
-| Module | Description |
-|---|---|
-| `Capacity` | Monitor and manage Power BI and Fabric capacities. |
-| `Operations` | Track long-running Fabric API operations. |
-| `Admin` | Power BI Admin API operations. |
-| `KQLDatabase` | Query Kusto (KQL) databases in Microsoft Fabric. |
-| `Notebook` | Manage Fabric notebooks. |
-| `Database` | Query and write to SQL databases (Lakehouse, Warehouse) via ODBC. |
+When `change_data_destination(mode='replace')` is used on a standard Gen2 dataflow, the original is deleted and a new CI/CD dataflow is created with a new ID. Pipelines referencing the old ID must be updated:
+
+```python
+from msdev_kit import Auth
+from msdev_kit.fabric import Dataflow, Pipeline
+
+auth = Auth(tenant_id, client_id, client_secret)
+dataflow = Dataflow(auth.get_token('pbi'))
+pipeline = Pipeline(auth.get_token('fabric'))
+
+workspace_id = '<workspace_id>'
+old_dataflow_id = '<dataflow_id>'
+
+# 1. replace dataflow destination (creates new CI/CD, deletes original)
+result = dataflow.change_data_destination(
+    workspace_id=workspace_id,
+    dataflow_id=old_dataflow_id,
+    destination_type='Warehouse',
+    destination_workspace_id=workspace_id,
+    destination_item_id='<warehouse_id>',
+    mode='replace'
+)
+new_dataflow_id = result['content']['id']
+
+# 2. find pipelines referencing the old dataflow ID
+matches = pipeline.find_pipelines_by_dataflow(workspace_id, old_dataflow_id)
+
+# 3. update each pipeline to use the new ID
+for m in matches['content']:
+    pipeline.replace_dataflow_id_in_pipeline(
+        workspace_id, m['pipeline_id'], old_dataflow_id, new_dataflow_id
+    )
+```
+
+</details>
+
+### Other modules
+
+| Module | Class | Description |
+|---|---|---|
+| Capacity | `Capacity` | Monitor and manage Power BI and Fabric capacities. |
+| Operations | `Operations` | Track long-running Fabric API operations. |
+| Admin | `Admin` | Power BI Admin API operations. |
+| KQL | `KQLDatabase` | Query Kusto (KQL) databases in Microsoft Fabric. |
+| Notebook | `Notebook` | Manage Fabric notebooks (list, get metadata). |
+| Database | `Database` | Query and write to SQL databases (Lakehouse, Warehouse) via ODBC. |
 
 ---
 
-### `msdev_kit.graph` — MS Graph (Entra)
+## MS Graph (Entra)
 
 Manage Entra ID (Azure AD) users and groups via the MS Graph API.
 
@@ -184,8 +306,12 @@ from msdev_kit.graph import GraphClient
 auth = Auth(tenant_id, client_id, client_secret)
 graph = GraphClient(auth)
 
+# look up a user and add them to a group
 user_id = graph.get_user_id('user@company.com')
 group_id = graph.get_group_id('Data Team')
+graph.add_group_member(group_id, user_id)
+
+# list all members of a group
 members = graph.list_group_members(group_id)
 ```
 
@@ -199,7 +325,7 @@ members = graph.list_group_members(group_id)
 
 ---
 
-### `msdev_kit.sharepoint` — SharePoint
+## SharePoint
 
 Manage SharePoint files and folders via MS Graph API (no ACS/Office365 dependency).
 
@@ -210,9 +336,15 @@ from msdev_kit.sharepoint import SharePointClient
 auth = Auth(tenant_id, client_id, client_secret)
 sp = SharePointClient(auth, sp_hostname='company', sp_site_path='sites/DataTeam')
 
+# download a file
 sp.download_file('/Reports/monthly.xlsx', local_dir='./downloads')
+
+# upload a file (from path or bytes)
 sp.upload_file('/Reports/updated.xlsx', source='./local/updated.xlsx')
-sp.create_folder('/Reports/2026')
+sp.upload_file('/Reports/data.csv', source=csv_bytes, content_type='text/csv')
+
+# create nested folders
+sp.create_folder('/Reports/2026/Q1')
 ```
 
 | Method | Description |
@@ -221,7 +353,16 @@ sp.create_folder('/Reports/2026')
 | `upload_file(remote_path, source, content_type?)` | Upload/overwrite a file. `source` is a local file path (str) or raw bytes. |
 | `create_folder(folder_path)` | Create a folder and all intermediate folders. |
 
-Hostname and site path inputs are normalized automatically — accepts short names (`company`), FQDNs (`company.sharepoint.com`), or full URLs (`https://company.sharepoint.com`).
+Hostname and site path inputs are normalized automatically:
+
+| Input | Normalized to |
+|---|---|
+| `company` | `company.sharepoint.com` |
+| `company.sharepoint.com` | `company.sharepoint.com` |
+| `https://company.sharepoint.com` | `company.sharepoint.com` |
+| `DataTeam` | `sites/DataTeam` |
+| `sites/DataTeam` | `sites/DataTeam` |
+| `/sites/DataTeam` | `sites/DataTeam` |
 
 ---
 

{msdev_kit-0.1.0 → msdev_kit-0.1.1}/msdev_kit/__init__.py

@@ -1,3 +1,3 @@
 from .auth import Auth
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{msdev_kit-0.1.0 → msdev_kit-0.1.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "msdev-kit"
 description = "Microsoft developer toolkit: Fabric, MS Graph, and SharePoint"
-version = "0.1.0"
+version = "0.1.1"
 requires-python = ">=3.10"
 readme = "README.md"
 license = {text = "MIT"}