Metadata-Version: 2.1
Name: msgraph-py
Version: 1.0.0
Summary: This package contains API wrappers to simplify interaction with Microsoft Graph API through Python functions.
Author: fedamerd
License: MIT License
        
        Copyright (c) 2024 fedamerd
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests

# msgraph-py

## Description

This package contains API wrappers to simplify interaction with Microsoft Graph API through Python functions.

Some of the benefits of msgraph-py are:
- Automatic caching and renewal of access tokens, avoiding unnecessary API-calls.
- Sets the correct headers and parameters for you when required (advanced queries).
- Pages results automatically when retrieving large datasets.
- Useful logging and error messages with the Python logging module.
- Optional integration with Django settings.py for reading environment variables.

> [!NOTE]  
> The latest published version of this package can be found at [pypi.org/project/msgraph-py](https://pypi.org/project/msgraph-py/)

### List of available functions

#### msgraph.identity
- `get_user()`
- `get_user_risk()`
- `revoke_refresh_tokens()`
- `list_auth_methods()`
- `delete_auth_method()`
- `reset_strong_auth()`
- `get_signin()`

#### msgraph.groups
- `get_group()`
- `list_group_members()`
- `add_group_member()`
- `remove_group_member()`

#### msgraph.devices
- `get_device()`
- `delete_device()`

#### msgraph.mail
- `send_mail()`

## Getting Started

1. Create an app registration in Azure AD with the necessary Graph application permissions for the functions you intend to use:  
[Authentication and authorization steps](https://learn.microsoft.com/en-us/graph/auth-v2-service?tabs=http#authentication-and-authorization-steps)

2. Install the latest version of the package:  
`$ python3 -m pip install msgraph-py`

3. Configure environment variables:
    * If used within a Django project, `msgraph-py` will by default first attempt to load the following variables from the project's `settings.py`:

        ```python
        # project/settings.py

        AAD_TENANT_ID = "00000000-0000-0000-0000-000000000000"
        AAD_CLIENT_ID = "00000000-0000-0000-0000-000000000000"
        AAD_CLIENT_SECRET = "client-secret-value"
        ```

    * Alternatively you will need to set the following key-value pairs in `os.environ`:

        ```python
        import os

        os.environ["AAD_TENANT_ID"] = "00000000-0000-0000-0000-000000000000"
        os.environ["AAD_CLIENT_ID"] = "00000000-0000-0000-0000-000000000000"
        os.environ["AAD_CLIENT_SECRET"] = "client-secret-value"
        ```

> [!WARNING]  
> You should **never** store sensitive credentials or secrets in production code or commit them to your repository. Always load them at runtime from a secure location or from a local file excluded from the repository.

## Examples

### Get a single user by objectId or userPrincipalName
```python
from msgraph import get_user

user = get_user("user@example.com")
```

### Get a list of users using advanced query parameters

```python
from msgraph import get_user

filtered_users = get_user(
    filter="startsWith(department, 'sales')",
    select=[
        "displayName",
        "department",
        "createdDateTime",
    ],
    orderby="createdDateTime desc",
    all=True,
)
```

### Send an e-mail with attachments

```python
from msgraph import send_mail

send_mail(
    sender_id="noreply@example.com",
    recipients=[
        "john.doe@example.com",
        "jane.doe@example.com",
    ],
    subject="Mail from Graph API",
    body="<h1>Content of the mail body</h1>",
    is_html=True,
    priority="high",
    attachments=[
        "/path/to/file1.txt",
        "/path/to/file2.txt",
    ],
)
```

## References and documentation

- [Authentication and authorization basics](https://learn.microsoft.com/en-us/graph/auth/auth-concepts)
- [Use query parameters to customize responses](https://learn.microsoft.com/en-us/graph/query-parameters)
- [User resource type - Properties](https://learn.microsoft.com/en-us/graph/api/resources/user?view=graph-rest-1.0#properties)
- [Azure AD authentication methods API overview](https://learn.microsoft.com/en-us/graph/api/resources/authenticationmethods-overview)
