Skip to main content

pbipy

PyPI GitHub tag (latest SemVer) PyPI - Python Version GitHub Static Badge Static Badge

pbipy is a Python Library for interacting with the Power BI Rest API. It aims to simplyify working with the Power BI Rest API and support programatic administration of Power BI in Python.

pbipy supports operations for Apps, Dataflows, Datasets, Reports, and Workspaces (Groups), allowing users to perform actions on their PowerBI instance using Python.

Installation

pip install pbipy

Or to install the latest development code:

pip install git+https://github.com/andrewvillazon/pbipy

Getting Started: Authentication

To use pbipy you'll first need to acquire a bearer_token.

How do I get a bearer_token?

To acquire a bearer_token you'll need to authenticate against your Registered Azure Power BI App. Registering is the first step in turning on the Power BI Rest API, so from here on it's assumed your Power BI Rest API is up and running.

To authenticate against the Registered App, Microsoft provides the MSAL and azure-identity python libraries. These libraries support different ways of acquiring a bearer_token and which to use will depend on how your cloud/tenant is configured.

Because there are multiple ways to acquire the token, pbipy leaves it up to do this in the way that suits, rather than directly handling authentication (of course, this might change in future).

This README doesn't cover authentication in detail, however, these are some helpful resources that look at acquiring a bearer_token in the context of Power BI:

The example below uses the msal library to to get a bearer_token.

import msal


#  msal auth setup
def acquire_bearer_token(username, password, azure_tenant_id, client_id, scopes):
    app = msal.PublicClientApplication(client_id, authority=azure_tenant_id)
    result = app.acquire_token_by_username_password(username, password, scopes)
    return result["access_token"]


bearer_token = acquire_bearer_token(
    username="your-username",
    password="your-password",
    azure_tenant_id="https://login.microsoftonline.com/your-azure-tenant-id",
    client_id="your-pbi-client-id",
    scopes=["https://analysis.windows.net/powerbi/api/.default"],
)

The code that follows assumes you've authenticated and acquired your bearer_token.

Useage

Start by creating the PowerBI() client. Interactions with the Power BI Rest API go through this object.

from pbipy import PowerBI

pbi = PowerBI(bearer_token)

To interact with the API, simply call the relevant method from the client.

# Grab the datasets from a workspace

pbi.datasets(group="f089354e-8366-4e18-aea3-4cb4a3a50b48")

pbipy converts API responses into regular Python objects, with snake case included! 🐍🐍

sales = pbi.dataset("cfafbeb1-8037-4d0c-896e-a46fb27ff229")

print(type(sales))
print(hasattr(sales, "configured_by"))

# <class 'pbipy.resources.Dataset'>
# True

Most methods take in an object id...

dataset = pbi.dataset(
    id="cfafbeb1-8037-4d0c-896e-a46fb27ff229",
    group="a2f89923-421a-464e-bf4c-25eab39bb09f"
)

... or just pass in the object itself.

group = pbi.group("a2f89923-421a-464e-bf4c-25eab39bb09f")

dataset = pbi.dataset(
    "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
    ,group=group
)

If you need to access the raw json representation, this is supported to.

sales = pbi.dataset("cfafbeb1-8037-4d0c-896e-a46fb27ff229")

print(sales.raw)

# {
#   "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
#   "name": "SalesMarketing",
#   "addRowsAPIEnabled": False,
#   "configuredBy": "john@contoso.com",
#   ...
# }

Example: Working with Datasets

Let's see how pbipy works by performing some operations on a Dataset.

First, we initialize our client.

from pbipy import PowerBI

pbi = PowerBI(bearer_token)

Now that we've got a client, we can load a Dataset from the API. To load a Dataset, we call the dataset() method with an id and group argument. In the Power BI Rest API, a Group and Workspace are synonymous and used interchangeably.

sales = pbi.dataset(
    id="cfafbeb1-8037-4d0c-896e-a46fb27ff229",
    group="f089354e-8366-4e18-aea3-4cb4a3a50b48",
)

print(sales)

# <Dataset id='cfafbeb1-8037-4d0c-896e-a46fb27ff229', name='SalesMarketing', ...>

Dataset not updating? Let's look at the Refresh History.

We call the refresh_history() method on our Dataset. Easy.

refresh_history = sales.refresh_history()

for entry in refresh_history:
    print(entry)

# {"refreshType":"ViaApi", "startTime":"2017-06-13T09:25:43.153Z", "status": "Completed" ...}

Need to kick off a refresh? That's easy too.

sales.refresh()

How about adding some user permissions to our Dataset? Just call the add_user() method with the User's details and permissions.

# Give John 'Read' access on the dataset
sales.add_user("john@contoso.com", "User", "Read")

Lastly, if we're feeling adventurous, we can execute DAX against a Dataset and use the results in Python.

dxq_result = sales.execute_queries("EVALUATE VALUES(MyTable)")
print(dxq_result)

# {
#   "results": [
#     {
#       "tables": [
#         {
#           "rows": [
#             {
#               "MyTable[Year]": 2010,
#               "MyTable[Quarter]": "Q1"
#             },
# ...
# }

Example: Working with the Admin object

pbypi also supports Administrator Operations, specialized operations available to users with Power BI Admin rights. Let's see how we can use these.

First, we need to initialize our client. Then we call the admin method and initialize an Admin object.

from pbipy import PowerBI

pbi = PowerBI(bearer_token)
admin = pbi.admin()

Need to review some access on some reports? We can call the report_users method.

users = admin.report_users("5b218778-e7a5-4d73-8187-f10824047715")
print(users[0])

# {"displayName": "John Nick", "emailAddress": "john@contoso.com", ...}

What about understanding User activity on your Power BI tenant?

from datetime import datetime

start_dtm = datetime(2019, 8, 31, 0, 0, 0)
end_dtm = datetime(2019, 8, 31, 23, 59, 59)

activity_events = admin.activity_events(start_dtm, end_dtm)

print(activity_events)

# [
#   {
#       "Id": "41ce06d1", 
#       "CreationTime": "2019-08-13T07:55:15", 
#       "Operation": "ViewReport", 
#       ...
#   },
#   {
#       "Id": "c632aa64", 
#       "CreationTime": "2019-08-13T07:55:10", 
#       "Operation": "GetSnapshots", 
#       ...
#   }
# ]

More examples

Datasets in a Workspace

datasets = pbi.datasets(group="f089354e-8366-4e18-aea3-4cb4a3a50b48")

for dataset in datasets:
    print(dataset)

# <Dataset id='cfafbeb1-8037-4d0c-896e-a46fb27ff229', ...>
# <Dataset id='f7fc6510-e151-42a3-850b-d0805a391db0', ...>

List Workspaces

groups = pbi.groups()

for group in groups:
    print(group)

# <Group id='a2f89923-421a-464e-bf4c-25eab39bb09f', name='contoso'>
# <Group id='3d9b93c6-7b6d-4801-a491-1738910904fd', name='marketing'>

Create a Workspace

group = pbi.create_group("contoso")
print(group)

# <Group id='a2f89923-421a-464e-bf4c-25eab39bb09f', name='contoso'>

Users and their access

group = pbi.group("a2f89923-421a-464e-bf4c-25eab39bb09f")
users = group.users()

for user in users:
    print(user)

# {"identifier": "john@contoso.com", "groupUserAccessRight": "Admin", ... }
# {"identifier": "Adam@contoso.com", "groupUserAccessRight": "Member", ... }

Power BI Rest API Operations

pbipy methods wrap around the Operations described in the Power BI Rest API Reference:

Power BI REST APIs for embedded analytics and automation - Power BI REST API

What's implemented?

Most of the core operations on Datasets, Workspaces (Groups), Reports, Apps, and Dataflows are implemented. Given the many available endpoints, not everything is covered by pbipy, so expect a few features to be missing.

If an operation is missing and you think it'd be useful, feel free to suggest it on the Issues tab.

PowerBI Component Progress Notes
Datasets Done
Groups (Workspaces) Done
Reports Done
Apps Done
Dataflows Done
Admin Operations Done Implements operations related to Datasets, Groups, Reports, Apps, and Dataflows only.
Dashboards Todo
Everything else Backlog

Contributing

Contributions such as bug reports, fixes, documentation or docstrings, enhancements, and ideas are welcome. pbipy uses github to host code, track issues, record feature requests, and accept pull requests.

A contributing.md is in the works, but in the meantime below is a general guide.

Making a contribution

Pull requests are the best way to make a contribution to the code:

  1. Fork the repo and create your branch from master.
  2. If you've added code that should be tested, add tests.
  3. Add docstrings.
  4. Ensure the test suite passes.
  5. Format your code (pbipy uses black).
  6. Issue that pull request!

Reporting a bug

Great Bug Reports tend to have:

  • A quick summary and/or background
  • Steps to reproduce. Be specific! Give sample code if you can.
  • What you expected would happen
  • What actually happens
  • Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)

Acknowledgements

The design of this library was heavily inspired by (basically copied) the pycontribs/jira library. It also borrows elements of cmberryay's pypowerbi wrapper.

Thank You to all the contributors to these libraries for the great examples of what an API Wrapper can be.

Metadata

Release files for pbipy 2.5.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pbipy 2.5.9
File Size Uploaded Provenance Actions
pbipy-2.5.9.tar.gz 34.8 kB Without provenance Details for pbipy-2.5.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pbipy 2.5.9
File Interpreter ABI Platform Actions
pbipy-2.5.9-py2.py3-none-any.whl Python 3, Python 2 none any Details for pbipy-2.5.9-py2.py3-none-any.whl

Total release size: 83.6 kB

Release files / pbipy-2.5.9.tar.gz

Download URL pbipy-2.5.9.tar.gz
Size 34.8 kB
Tags Source
SHA-256 checksum
How to use checksums
5f9455f81165360cd0e0c5bd1cd421076b835b1b2114d20848395ae05e4f384a
BLAKE2b-256 checksum
How to use checksums
173d933a46b2d6d7422562464e0bba1cb0358a1d2355c4c3515c68e0f2cb5608
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.10.6

Release files / pbipy-2.5.9-py2.py3-none-any.whl

Download URL pbipy-2.5.9-py2.py3-none-any.whl
Size 48.7 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
11bd30e3a5ffb47ea79074af7fc7e13db8204dfa3ae56ae2ed97afe6205dab4e
BLAKE2b-256 checksum
How to use checksums
de1abe45363e5fd6c11e532b35f5e1991ac43ab9caf58dde7e93f25a92bd356b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.10.6

Security for pbipy 2.5.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page