O365

https://o365.github.io/python-o365/latest/
Admin
O365 is a Python library designed to interact with various Microsoft 365 services, including...
Tokens:345,473
Snippets:2,524
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Stable Version with uv

Source: https://o365.github.io/python-o365/latest/getting_started.html

Installs the latest stable version of the o365 library from PyPI using uv.

```bash
uv add o365

```

--------------------------------

### Working with the Schedule instance

Source: https://o365.github.io/python-o365/latest/_sources/usage/calendar.rst.txt

Demonstrates how to get the default calendar, create a new event, set its properties like subject, location, start time, recurrence, and reminders, and then save the event.

```APIDOC
## Working with the Schedule instance

### Description
This section shows how to obtain a `Schedule` instance, retrieve the default calendar, create a new event object, populate its details (subject, location, start time, recurrence, reminders), and save it to the calendar.

### Method
```python
account.schedule()
calendar.new_event()
new_event.save()
```

### Parameters
**For `account.schedule()`:**
No explicit parameters shown.

**For `calendar.new_event()`:**
No explicit parameters shown.

**For `new_event.save()`:**
No explicit parameters shown.

### Request Example
```python
import datetime as dt

# Assuming 'account' is an authenticated Account object
schedule = account.schedule()

calendar = schedule.get_default_calendar()
new_event = calendar.new_event()  # creates a new unsaved event
new_event.subject = 'Recruit George Best!'
new_event.location = 'England'

# naive datetimes will automatically be converted to timezone aware datetime objects
new_event.start = dt.datetime(2019, 9, 5, 19, 45)

new_event.recurrence.set_daily(1, end=dt.datetime(2019, 9, 10))
new_event.remind_before_minutes = 45

new_event.save()
```

### Response
**Success Response:**
The event is saved to the default calendar.

**Response Example:**
No explicit response example provided in the source.
```

--------------------------------

### Install Sphinx for documentation

Source: https://o365.github.io/python-o365/latest/_sources/overview.rst.txt

This command installs the necessary Sphinx libraries and the Read the Docs theme for building documentation.

```console
pip install sphinx sphinx-rtd-theme
```

--------------------------------

### Install python-o365 using uv

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Use this command to install the latest stable version of the library using uv.

```console
uv add o365
```

--------------------------------

### Install development version using uv

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Install the latest development version from GitHub using uv. This may be unstable.

```console
uv add "o365 @ git+https://github.com/O365/python-o365"
```

--------------------------------

### Install Sphinx and Theme

Source: https://o365.github.io/python-o365/latest/overview.html

Installs the necessary Python libraries, Sphinx and the Read the Docs theme, for rebuilding HTML documentation.

```Shell
pip install sphinx sphinx-rtd-theme

```

--------------------------------

### Install python-o365 using pip

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Use this command to install the latest stable version of the library from PyPI.

```console
pip install o365
```

--------------------------------

### Subscription Creation Response Example

Source: https://o365.github.io/python-o365/latest/usage/subscriptions.html

This is an example of the JSON response received after successfully creating a subscription. It includes details about the subscription's configuration and lifecycle.

```json
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "applicationId": "12345678-bad9-4c34-94d6-f9a1388522f8",
    "changeType": "created",
    "clientState": "abc123",
    "creatorId": "12345678-a5c7-46da-8107-b25090a1ed66",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "expirationDateTime": "2026-01-07T11:20:42.305776Z",
    "id": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb1",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "lifecycleNotificationUrl": null,
    "notificationQueryOptions": null,
    "notificationUrl": "https://<your-tunnel-host>/webhook",
    "notificationUrlAppId": null,
    "resource": "/me/mailFolders('inbox')/messages"
}

```

--------------------------------

### Install Latest Development Version with uv

Source: https://o365.github.io/python-o365/latest/getting_started.html

Installs the latest development version from GitHub using uv. This version may be unstable.

```bash
uv add "o365 @ git+https://github.com/O365/python-o365"

```

--------------------------------

### Event.start property

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

Gets or sets the start date and time of the event.

```APIDOC
## Event.start

### Description
Represents the start date and time of the calendar event. It can be retrieved or modified.

### Method
```python
@property
def start(self)

@start.setter
def start(self, value)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **value** (datetime) - The new start date and time for the event.

### Request Example
```python
from datetime import datetime

# Get the start time
start_time = event.start

# Set the start time
new_start_time = datetime(2023, 10, 27, 9, 0, 0)
event.start = new_start_time
```

### Response
#### Success Response (datetime)
- **start** (datetime) - The current start date and time of the event.

#### Response Example
```python
# Example datetime object
# datetime.datetime(2023, 10, 27, 10, 0)
```
```

--------------------------------

### Install development version using pip

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Install the latest development version directly from GitHub using pip. This may be unstable.

```console
pip install git+https://github.com/O365/python-o365.git
```

--------------------------------

### tasks

Source: https://o365.github.io/python-o365/latest/api/account.html

Get an instance to read information from Microsoft ToDo.

```APIDOC
## tasks

### Description
Get an instance to read information from Microsoft ToDo.

### Method
GET

### Endpoint
/account/tasks

### Parameters
#### Path Parameters
None

#### Query Parameters
- **resource** (str) - Custom resource to be used in this task object (Defaults to parent main_resource)

### Request Example
```json
{
  "resource": ""
}
```

### Response
#### Success Response (200)
- **Tasks object** - An object to interact with Microsoft ToDo.

#### Response Example
```json
{
  "tasks_instance": "..."
}
```
```

--------------------------------

### Initialize Account with Credentials

Source: https://o365.github.io/python-o365/latest/_sources/usage/account.rst.txt

Shows how to create an Account instance by providing your client ID and client secret credentials. This is the basic setup required to connect to the API.

```python
from O365 import Account

account = Account(credentials=('my_client_id', 'my_client_secret'))
```

--------------------------------

### Get Apps in Team

Source: https://o365.github.io/python-o365/latest/_modules/O365/teams.html

Retrieves a list of all applications installed in a specified team.

```APIDOC
## Get Apps in Team

### Description
Returns a list of applications installed in a specified team.

### Method
GET

### Endpoint
/teams/{team_id}/apps

### Parameters
#### Path Parameters
- **team_id** (string) - Required - The ID of the team to get the apps of.

### Response
#### Success Response (200)
- **App** (list[App]) - A list of App objects installed in the team. Returns an empty list if no apps are found or the team does not exist.
```

--------------------------------

### Configure Account with Proxy Server (Option 1)

Source: https://o365.github.io/python-o365/latest/_sources/usage/account.rst.txt

Illustrates setting up an Account instance with proxy server details, including server address, port, username, and password. This is useful when network requests need to go through a proxy.

```python
# Option 1
account = Account(credentials=('my_client_id', 'my_client_secret'),
                  proxy_server='myserver.com', proxy_port=8080,
                  proxy_username='username', proxy_password='password)
```

--------------------------------

### Basic Authentication with Credentials

Source: https://o365.github.io/python-o365/latest/getting_started.html

This snippet demonstrates the initial setup for authentication using provided credentials and a tenant ID. It checks if the authentication was successful.

```python
from O365 import Account

credentials = ('client_id', 'client_secret')
account = Account(credentials, auth_flow_type='credentials', tenant_id='my-tenant-id')
if account.authenticate():
   print('Authenticated!')
```

--------------------------------

### Get User Availability

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

Retrieves free/busy availability for multiple users within a specified time range and interval. Requires a list of email addresses, start and end datetimes, and an interval in minutes.

```python
def get_availability(self, schedules, start, end, interval=60):
        """
        Returns the free/busy availability for a set of users in a given time frame
        :param list schedules: a list of strings (email addresses)
        :param datetime start: the start time frame to look for available space
        :param datetime end: the end time frame to look for available space
        :param int interval: the number of minutes to look for space
        """
        url = self.build_url(self._endpoints.get('get_availability'))

        data = {
            'startTime': self._build_date_time_time_zone(start),
            'endTime': self._build_date_time_time_zone(end),
            'availabilityViewInterval': interval,
            'schedules': schedules
        }

        response = self.con.post(url, data=data)
        if not response:
            return []

        data = response.json().get('value', [])

        # transform dates and availabilityView
        availability_view_codes = {
            '0': 'free',
            '1': 'tentative',
            '2': 'busy',
            '3': 'out of office',
            '4': 'working elsewhere',
        }
        for schedule in data:
            a_view = schedule.get('availabilityView', '')
            schedule['availabilityView'] = [availability_view_codes.get(code, 'unkknown') for code in a_view]
            for item in schedule.get('scheduleItems', []):
                item['start'] = self._parse_date_time_time_zone(item.get('start'))
                item['end'] = self._parse_date_time_time_zone(item.get('end'))

        return data
```

--------------------------------

### planner

Source: https://o365.github.io/python-o365/latest/api/account.html

Get an instance to read information from Microsoft planner.

```APIDOC
## planner

### Description
Get an instance to read information from Microsoft planner.

### Method
GET

### Endpoint
/account/planner

### Parameters
#### Path Parameters
None

#### Query Parameters
- **resource** (str) - Custom resource to be used in this planner object (Defaults to parent main_resource)

### Request Example
```json
{
  "resource": ""
}
```

### Response
#### Success Response (200)
- **Planner object** - An object to interact with Microsoft Planner.

#### Response Example
```json
{
  "planner_instance": "..."
}
```
```

--------------------------------

### Get Apps in Team - O365 Teams

Source: https://o365.github.io/python-o365/latest/_modules/O365/teams.html

Fetches a list of applications installed in a specified team. Requires the team ID. Returns a list of App objects, or an empty list if no apps are found or the response is empty.

```python
        url = self.build_url(
            self._endpoints.get('get_apps_in_team').format(team_id=team_id))
        response = self.con.get(url)

        if not response:
            return []

        data = response.json()

        return [
            self.app_constructor(parent=self, **{self._cloud_data_key: site})
            for site in data.get('value', [])]
```

--------------------------------

### Initialize Storage and List Drives

Source: https://o365.github.io/python-o365/latest/_sources/usage/onedrive.rst.txt

Initializes the storage instance and demonstrates how to retrieve a list of available drives and the default drive. It also shows how to access root and special folders, and iterate through items within a folder, printing metadata for files and photos.

```python
account = Account(credentials=my_credentials)

storage = account.storage()  # here we get the storage instance that handles all the storage options.

# list all the drives:
drives = storage.get_drives()

# get the default drive
my_drive = storage.get_default_drive()  # or get_drive('drive-id')

# get some folders:
root_folder = my_drive.get_root_folder()
attachments_folder = my_drive.get_special_folder('attachments')

# iterate over the first 25 items on the root folder
for item in root_folder.get_items(limit=25):
    if item.is_folder:
        print(list(item.get_items(2)))  # print the first to element on this folder.
    elif item.is_file:
        if item.is_photo:
            print(item.camera_model)  # print some metadata of this photo
        elif item.is_image:
            print(item.dimensions)  # print the image dimensions
        else:
            # regular file:
            print(item.mime_type)  # print the mime type
```

--------------------------------

### Event Properties

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

This section details the properties of a calendar event that can be accessed and modified through the O365 Calendar API. It covers setting and getting the start and end times, importance level, all-day status, location, and reminder settings.

```APIDOC
## Event Properties

### Description
This section details the properties of a calendar event that can be accessed and modified through the O365 Calendar API. It covers setting and getting the start and end times, importance level, all-day status, location, and reminder settings.

### Properties

- **start** (datetime) - The start time of the event. If not set, it defaults to the current date and time. If the event is an all-day event, the start time is set to midnight.
- **end** (datetime) - The end time of the event. If not set, it defaults to 30 minutes after the start time. If the event is an all-day event, the end time is set to midnight of the next day if it's less than 24 hours from the start.
- **importance** (ImportanceLevel or str) - The priority level of the event. Can be set using an `ImportanceLevel` enum or a string representation.
- **is_all_day** (bool) - A flag indicating whether the event is an all-day event. When set to true, start and end times are adjusted to midnight.
- **location** (str) - The physical or virtual location of the event.
- **is_reminder_on** (bool) - A flag indicating whether a reminder is enabled for the event.
- **remind_before_minutes** (int) - The number of minutes before the event start time that the reminder should be triggered. Setting this automatically enables the reminder.
- **response_requested** (bool) - A flag indicating whether responses are requested from attendees.
```

--------------------------------

### get

Source: https://o365.github.io/python-o365/latest/api/connection.html

Sends a GET request to the specified URL with optional query parameters. This is a shorthand for calling the `oauth_request` method with the 'get' HTTP method.

```APIDOC
## get

### Description
Shorthand for `self.oauth_request(url, ‘get’)`.

### Method
GET

### Endpoint
[URL provided in the `url` parameter]

### Parameters
- **url** (str) - Required - The URL to send the GET request to.
- **params** (dict or None) - Optional - Request parameters to get the service data.
- **kwargs** - Optional - Extra parameters to send to the request API.

### Returns
- **Response** - The response object from the request.

### Return Type
requests.Response
```

--------------------------------

### Configure Account with Proxy Server (Option 2)

Source: https://o365.github.io/python-o365/latest/_sources/usage/account.rst.txt

Demonstrates setting the proxy server details on an existing Account instance using the 'set' method on the connection object. This provides an alternative way to configure proxy settings after initialization.

```python
# Option 2
account = Account(credentials=('my_client_id', 'my_client_secret'))
account.connection.set('myserver.com',8080,'username', 'password')
```

--------------------------------

### Initialize DjangoTokenBackend with Account

Source: https://o365.github.io/python-o365/latest/_modules/O365/utils/token.html

Demonstrates how to initialize the DjangoTokenBackend and use it with an Account object. Requires importing necessary classes and defining credentials.

```python
from O365.utils import DjangoTokenBackend
from models import TokenModel

token_backend = DjangoTokenBackend(token_model=TokenModel)
account = Account(credentials, token_backend=token_backend)
```

--------------------------------

### Initialize FileSystemTokenBackend

Source: https://o365.github.io/python-o365/latest/usage/utils/token.html

Use FileSystemTokenBackend to store authentication tokens on the local file system. This backend requires a path and filename for token storage.

```python
from O365 import Account, FileSystemTokenBackend

token_backend = FileSystemTokenBackend(token_path=token_path, token_filename=token_filename)

account = Account(credentials=('my_client_id', 'my_client_secret'), token_backend=token_backend)

```

--------------------------------

### Get User Direct Reports

Source: https://o365.github.io/python-o365/latest/_modules/O365/directory.html

Gets a list of direct reports for a given user. Supports OData querying and ordering.

```APIDOC
## GET /users/{user}/directReports

### Description
Gets a list of direct reports for the user provided from the active directory.

### Method
GET

### Endpoint
/users/{user}/directReports

### Parameters
#### Path Parameters
- **user** (str) - Required - The user id or user principal name.

#### Query Parameters
- **limit** (int or None) - Optional - Maximum number of contacts to get. Defaults to 100. Uses batching if over 999 or if batch is specified.
- **query** (Query or str) - Optional - Applies an OData filter to the request.
- **order_by** (Query or str) - Optional - Orders the result set based on this condition.
- **batch** (int) - Optional - Batch size, retrieves items in batches allowing to retrieve more items than the limit.

### Response
#### Success Response (200)
- **list[User] or Pagination** - A list of User objects or a Pagination object if batching is used.

### Request Example
```json
{
  "example": "List of User objects or Pagination object"
}
```

### Response Example
```json
{
  "example": "List of User objects or Pagination object"
}
```
```

--------------------------------

### Account.__init__()

Source: https://o365.github.io/python-o365/latest/api/account.html

Initializes the Account object with credentials and optional configuration. This is the entry point for accessing O365 resources.

```APIDOC
## Account.__init__()

### Description
Creates an object which is used to access resources related to the specified credentials.

### Parameters
* **credentials** (str | tuple[str, str]) - A tuple containing the client_id and client_secret.
* **username** (str | None) - The username to be used by this account.
* **protocol** (Protocol | None) - The protocol to be used in this account.
* **main_resource** (str | None) - The resource to be used by this account (‘me’ or ‘users’, etc.).
* **kwargs** - Any extra args to be passed to the Connection instance.

### Raises
* **ValueError** - If an invalid protocol is passed.
```

--------------------------------

### Setting Recurrence Start Date

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

Defines the start date for the recurrence pattern. The date is parsed and stored as a date object.

```python
self.__start_date = parse(self.__start_date).date() if self.__start_date else None
```

--------------------------------

### QueryFilter Initialization Example

Source: https://o365.github.io/python-o365/latest/api/utils/query.html

Demonstrates the initialization of a QueryFilter with a name, operator, and value.

```python
filter_instance = QueryFilter(name='subject', op='eq', value='test')
```

--------------------------------

### Get Nested Folder by Name

Source: https://o365.github.io/python-o365/latest/_sources/usage/mailbox.rst.txt

Shows how to get a nested folder by first retrieving its parent folder and then calling get_folder on the parent.

```python
# By Name - If Todo folder is under Inbox
mail_folder = (mailbox.get_folder(folder_name='Inbox')
                      .get_folder(folder_name='Todo'))
```

--------------------------------

### Modular Account Initialization

Source: https://o365.github.io/python-o365/latest/_sources/usage/account.rst.txt

Demonstrates initializing the Account class without immediately assigning specific functionalities like new_message or mailbox. This allows for more granular control over which O365 services are accessed.

```python
from O365 import Account

account = Account(('client_id', 'client_secret'))
message = account.new_message()
# ...
mailbox = account.mailbox()
# ...
```

--------------------------------

### Initialize BitwardenSecretsManagerBackend

Source: https://o365.github.io/python-o365/latest/_modules/O365/utils/token.html

Initializes the BitwardenSecretsManagerBackend. Requires the 'bitwarden-sdk' package to be installed. Logs in using the provided access token and sets the secret ID.

```python
try:
            from bitwarden_sdk import BitwardenClient
        except ModuleNotFoundError as e:
            raise Exception(
                "Please install the bitwarden-sdk package to use this token backend."
            ) from e
        super().__init__()
        #: Bitwarden client.  |br| **Type:** BitWardenClient
        self.client = BitwardenClient()
        #: Bitwarden login access token.  |br| **Type:** str
        self.client.auth().login_access_token(access_token)
        #: Bitwarden secret is.  |br| **Type:** str
        self.secret_id = secret_id
        #: Bitwarden secret.  |br| **Type:** str
        self.secret = None
```

--------------------------------

### Initialize Account with Main Resource

Source: https://o365.github.io/python-o365/latest/_sources/usage/account.rst.txt

Shows how to initialize an Account instance specifying a 'main_resource'. This is used when interacting with resources that are not directly tied to the authenticated user, such as shared mailboxes.

```python
from O365 import Account

account = Account(credentials=('my_client_id', 'my_client_secret'), main_resource='shared_mail@example.com')
```

--------------------------------

### Get Range by Address

Source: https://o365.github.io/python-o365/latest/_modules/O365/excel.html

Retrieves a specific range from a worksheet using its address. If no address is provided, it attempts to get the entire worksheet range.

```python
def get_range(self, address=None):
        """
        Returns a Range instance from whitin this worksheet
        :param str address: Optional, the range address you want
        :return: a Range instance
        """
        url = self.build_url(self._endpoints.get("get_range"))
        if address is not None:
            address = self.remove_sheet_name_from_address(address)
            url = "{}(address='{}')".format(url, address)
        response = self.session.get(url)
        if not response:
            return None
        return self.range_constructor(
            parent=self, **{self._cloud_data_key: response.json()}
        )
```

--------------------------------

### Create SharePoint Instance and Connect to a Site

Source: https://o365.github.io/python-o365/latest/_sources/usage/sharepoint.rst.txt

Instantiates a SharePoint object and connects to a specific site using provided application credentials.

```python
from O365 import Account
acct = Account(('app_id', 'app_pw'))
sp_site = acct.sharepoint().get_site('root', 'path/tosite')
```

--------------------------------

### O365 Connection GET Request

Source: https://o365.github.io/python-o365/latest/_modules/O365/connection.html

Shorthand for making a GET request using an authenticated OAuth session. Use this for retrieving service data.

```python
def get(self, url, params=None, **kwargs):
        """ Shorthand for self.oauth_request(url, 'get')

        :param str url: url to send get oauth request to
        :param dict params: request parameter to get the service data
        :param kwargs: extra params to send to request api
        :return: Response of the request
        :rtype: requests.Response
        """
        return self.oauth_request(url, 'get', params=params, **kwargs)
```

--------------------------------

### Site Initialization

Source: https://o365.github.io/python-o365/latest/_modules/O365/sharepoint.html

Initializes a Site object. It requires either a parent object or a connection, but not both. It sets up the main resource path and parses site details like name, description, and URLs.

```APIDOC
## __init__ Site

### Description
Initializes a Site object. It requires either a parent object or a connection, but not both. It sets up the main resource path and parses site details like name, description, and URLs.

### Parameters
* **parent** (Sharepoint) - Optional - The parent Sharepoint object.
* **con** (Connection) - Optional - The connection object to use if no parent is specified.
* **protocol** (Protocol) - Optional - The protocol to use if no parent is specified.
* **main_resource** (str) - Optional - Use this resource instead of the parent resource.
* **_cloud_data_key** (dict) - Internal use for cloud data.
* **name** (str) - Optional - The name of the site.

### Request Example
```python
# Example of initializing a Site object (conceptual)
# site = Site(con=my_connection)
```

### Response
This method does not return a value directly but initializes the Site object.
```

--------------------------------

### Renew Subscription Response Example

Source: https://o365.github.io/python-o365/latest/usage/subscriptions.html

Example JSON response after renewing a subscription. The expirationDateTime field will be updated to reflect the new expiration time.

```json
{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "applicationId": "12345678-bad9-4c34-94d6-f9a1388522f8",
    "changeType": "created",
    "clientState": "abc123",
    "creatorId": "12345678-a5c7-46da-8107-b25090a1ed66",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "expirationDateTime": "2026-01-07T11:35:40.301594Z",
    "id": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb1",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "lifecycleNotificationUrl": null,
    "notificationQueryOptions": null,
    "notificationUrl": "https://<your-tunnel-host>/webhook",
    "notificationUrlAppId": null,
    "resource": "/me/mailFolders('inbox')/messages"
}

```

--------------------------------

### Initialize O365 Connection and Services

Source: https://o365.github.io/python-o365/latest/_sources/usage/account.rst.txt

Demonstrates how to initialize a connection to O365 services using client ID and secret, and create Message and MailBox objects. It also shows how to inherit connection and protocol from a parent object.

```python
from O365 import Connection, MSGraphProtocol
from O365.message import Message
from O365.mailbox import MailBox

protocol = MSGraphProtocol()
requested_scopes = ['...']
con = Connection(('client_id', 'client_secret'), requested_scopes=requested_scopes)

message = Message(con=con, protocol=protocol)
# ...
mailbox = MailBox(con=con, protocol=protocol)
message2 = Message(parent=mailbox)  # message will inherit the connection and protocol from mailbox when using parent.
# ...
```

--------------------------------

### FileSystemTokenBackend Initialization

Source: https://o365.github.io/python-o365/latest/api/utils/token.html

Initialize the FileSystemTokenBackend to store tokens in a file. Specify the directory path and filename for the token file.

```python
from O365.utils import FileSystemTokenBackend

token_backend = FileSystemTokenBackend(token_path='/path/to/tokens', token_filename='o365_token.json')
```

--------------------------------

### O365 Excel API Component GET Method

Source: https://o365.github.io/python-o365/latest/_modules/O365/excel.html

Implements the GET request for the O365 Excel API component. It prepares the request and sends it using the established connection.

```python
[docs]
    def get(self, *args, **kwargs):
        self.prepare_request(kwargs)
        return self.con.get(*args, **kwargs)
```

--------------------------------

### Get Scopes using MSGraphProtocol Scope Helpers

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Shows how to use the MSGraphProtocol to get protocol-specific scopes for a given scope helper. The resulting scopes are formatted for the Microsoft Graph API.

```python
protocol_graph = MSGraphProtocol()

scopes_graph = protocol.get_scopes_for('message_all')
# scopes here are: ['https://graph.microsoft.com/Mail.ReadWrite', 'https://graph.microsoft.com/Mail.Send']

account = Account(credentials, requested_scopes=scopes_graph)
```

--------------------------------

### Create a Planner Plan

Source: https://o365.github.io/python-o365/latest/_sources/usage/planner.rst.txt

Instantiate the planner and create a new plan within a specified group. Ensure you have the correct scopes for reading and writing groups.

```python
from O365 import Account
account = Account(('app_id', 'app_pw'))
planner = account.planner()
plan = planner.create_plan(
    owner="group_object_id", title="Test Plan"
)
```

--------------------------------

### Download, Upload, and Restore File Versions

Source: https://o365.github.io/python-o365/latest/_sources/usage/onedrive.rst.txt

Provides examples for downloading a file to a local path, uploading a local file (with notes on chunking for large files), and restoring a specific version of a file.

```python
# download files:
file.download(to_path='/quotes/')

# upload files:

# if the uploaded file is bigger than 4MB the file will be uploaded in chunks of 5 MB until completed.
# this can take several requests and can be time consuming.
uploaded_file = folder.upload_file(item='path_to_my_local_file')

# restore versions:
versions = file.get_versions()
for version in versions:
    if version.name == '2.0':
        version.restore()  # restore the version 2.0 of this file
```

--------------------------------

### Set Event Start Time - O365 Calendar

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

Sets the start time for an event. Ensures the value is a datetime object, localizes it if necessary, and adjusts the end time if it's not set.

```python
@start.setter
    def start(self, value):
        if not isinstance(value, dt.date):
            raise ValueError("'start' must be a valid datetime object")
        if not isinstance(value, dt.datetime):
            # force datetime
            value = dt.datetime(value.year, value.month, value.day)
        if value.tzinfo is None:
            # localize datetime
            value = self.protocol.timezone.localize(value)
        elif value.tzinfo != self.protocol.timezone:
            value = value.astimezone(self.protocol.timezone)
        self.__start = value
        if not self.end:
            self.end = self.__start + dt.timedelta(minutes=30)
        self._track_changes.add(self._cc('start'))
```

--------------------------------

### Set Recurrence Range

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

Sets the recurrence range for an event, specifying either a start and end date or a number of occurrences. If no start date is provided, it defaults to today's date.

```python
def set_range(self, start=None, end=None, occurrences=None):
    """ Set the range of recurrence

    :param date start: Start date of repetition
    :param date end: End date of repetition
    :param int occurrences: no of occurrences
    """
    if start is None:
        if self.__start_date is None:
            self.__start_date = dt.date.today()
    else:
        self.start_date = start

    if end:
        self.end_date = end
    elif occurrences:
        self.__occurrences = occurrences
    self._track_changes()
```

--------------------------------

### Webhook Payload Example

Source: https://o365.github.io/python-o365/latest/usage/subscriptions.html

This is an example of a JSON payload received when a subscription event occurs, such as a new message being created. The 'clientState' should be validated for security. This payload structure is typical for Microsoft Graph API notifications.

```json
{
    "value": [
        {
            "subscriptionId": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb12",
            "subscriptionExpirationDateTime": "2026-01-07T11:35:40.301594+00:00",
            "changeType": "created",
            "resource": "Users/12345678-a5c7-46da-8107-b25090a1ed66/Messages/<long_guid>=",
            "resourceData": {
                "@odata.type": "#Microsoft.Graph.Message",
                "@odata.id": "Users/12345678-a5c7-46da-8107-b25090a1ed66/Messages/<long_guid>=",
                "@odata.etag": "W/\"CQAAABYACCCoiRErLbiNRJDCFyMjq4khBBnH4N7A\"",
                "id": "<long_guid>="
            },
            "clientState": "abc123",
            "tenantId": "12345678-abcd-1234-abcd-1234567890ab"
        }
    ]
}
```

--------------------------------

### Authenticate with O365 Account using Scopes

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Demonstrates how to initialize an Account object with specific requested scopes and authenticate. The scopes can also be passed directly to the authenticate method.

```python
from O365 import Account

credentials = ('client_id', 'client_secret')

requested_scopes = ['Mail.ReadWrite', 'Mail.Send']

account = Account(credentials, requested_scopes=requested_scopes)
account.authenticate()

# The latter is exactly the same as passing scopes to the authenticate method like so:
# account = Account(credentials)
# account.authenticate(requested_scopes=requested_scopes)
```

--------------------------------

### Webhook Notification Example

Source: https://o365.github.io/python-o365/latest/_sources/usage/subscriptions.rst.txt

This is an example of a webhook notification received when a subscription event occurs, such as a new message being created. It includes details like subscription ID, change type, resource, and client state.

```json
    {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
        "applicationId": "12345678-bad9-4c34-94d6-f9a1388522f8",
        "changeType": "created",
        "clientState": "abc123",
        "creatorId": "12345678-a5c7-46da-8107-b25090a1ed66",
        "encryptionCertificate": null,
        "encryptionCertificateId": null,
        "expirationDateTime": "2026-01-07T11:35:40.301594Z",
        "id": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb1",
        "includeResourceData": null,
        "latestSupportedTlsVersion": "v1_2",
        "lifecycleNotificationUrl": null,
        "notificationQueryOptions": null,
        "notificationUrl": "https://<your-tunnel-host>/webhook",
        "notificationUrlAppId": null,
        "resource": "/me/mailFolders('inbox')/messages"
    }
```

```json
    {
        'value': [
            {
                'subscriptionId': '548355f8-c2c0-47ae-aac7-3ad02b2dfdb12', 
                'subscriptionExpirationDateTime': '2026-01-07T11:35:40.301594+00:00',
                'changeType': 'created', 
                'resource': 'Users/12345678-a5c7-46da-8107-b25090a1ed66/Messages/<long_guid>=', 
                'resourceData': {
                    '@odata.type': '#Microsoft.Graph.Message', 
                    '@odata.id': 'Users/12345678-a5c7-46da-8107-b25090a1ed66/Messages/<long_guid>=', 
                    '@odata.etag': 'W/"CQAAABYACCCoiRErLbiNRJDCFyMjq4khBBnH4N7A"', 
                    'id': '<long_guid>='
                }, 
                'clientState': 'abc123', 
                'tenantId': '12345678-abcd-1234-abcd-1234567890ab'
            }
        ]
    }
```

--------------------------------

### Get Filter Criteria from Excel Column

Source: https://o365.github.io/python-o365/latest/_modules/O365/excel.html

Retrieves the filter criteria currently applied to a specific column in an Excel sheet. It constructs a query to select the column name and expand the filter, then sends a GET request.

```python
def get_filter(self):
    """Returns the filter applie to this column"""
    q = self.q().select("name").expand("filter")
    response = self.session.get(self.build_url(""), params=q.as_params())
    if not response:
        return None
    data = response.json()
    return data.get("criteria", None)
```

--------------------------------

### Create and Rename Task Folders

Source: https://o365.github.io/python-o365/latest/_sources/usage/tasks.rst.txt

Shows how to create a new task folder and how to rename an existing folder. It also demonstrates listing tasks within a specific folder.

```python
#create a new folder
new_folder = todo.new_folder('Defenders')

#rename a folder
folder = todo.get_folder(folder_name='Strikers')
folder.name = 'Forwards'
folder.update()

#list current tasks
task_list = folder.get_tasks()
for task in task_list:
    print(task)
    print('')
```

--------------------------------

### Task.subject

Source: https://o365.github.io/python-o365/latest/api/tasks.html

Gets or sets the subject of the task.

```APIDOC
## Task.subject

### Description
Get or set the subject of the task.

### Method
GET or PUT

### Endpoint
/me/todo/tasks/{task_id}/subject

### Parameters
#### Request Body (for PUT)
- **subject** (str) - The subject of the task.

### Returns:
str
```

--------------------------------

### Initialize O365 Account

Source: https://o365.github.io/python-o365/latest/api/account.html

Instantiate the Account class with credentials and optional parameters like username, protocol, and main resource. This is the first step to interact with O365 services.

```python
from O365 import Account, MSGraphProtocol

credentials = ('client_id', 'client_secret')
protocol = MSGraphProtocol()

account = Account(credentials, protocol=protocol, username='user@domain.com')

```

--------------------------------

### get_details

Source: https://o365.github.io/python-o365/latest/_modules/O365/excel.html

Gets workbook application details.

```APIDOC
## get_details

### Description
Gets workbook application details.

### Method
GET

### Endpoint
/application

### Response
#### Success Response (200)
- **Details** (object) - Workbook application details.

#### Response Example
{
  "example": "Workbook application details object"
}
```

--------------------------------

### Retrieve Calendar Events with Query Options

Source: https://o365.github.io/python-o365/latest/_modules/O365/calendar.html

Fetches calendar events using query parameters like filtering, ordering, and including recurring events. Requires 'start' and 'end' datetimes when 'include_recurring' is true. Ensures 'end' is not before 'start'.

```python
if start is None or end is None:
                raise ValueError("When 'include_recurring' is True you must provide a 'start' and 'end' datetimes inside a Query instance.")

            if end < start:
                raise ValueError('When using "include_recurring=True", the date asigned to the "end" datetime' 
                                 ' should be greater or equal than the date asigned to the "start" datetime.')

            params[self._cc('startDateTime')] = start
            params[self._cc('endDateTime')] = end

        if order_by:
            params['$orderby'] = order_by

        if query:
            if isinstance(query, str):
                params['$filter'] = query
            else:
                params.update(query.as_params())

        response = self.con.get(url, params=params,
                                headers={'Prefer': 'outlook.timezone="UTC"'})
        if not response:
            return iter(())

        data = response.json()

        # Everything received from cloud must be passed as self._cloud_data_key
        events = (self.event_constructor(parent=self,
                                         download_attachments=
                                         download_attachments,
                                         **{self._cloud_data_key: event})
                  for event in data.get('value', []))
        next_link = data.get(NEXT_LINK_KEYWORD, None)
        if batch and next_link:
            return Pagination(parent=self, data=events,
                              constructor=self.event_constructor,
                              next_link=next_link, limit=limit)
        else:
            return events
```

--------------------------------

### FileSystemTokenBackend Initialization

Source: https://o365.github.io/python-o365/latest/_modules/O365/utils/token.html

Initializes the FileSystemTokenBackend, setting the path for token storage. It can accept a specific token path or derive it from a provided path and filename.

```python
def __init__(self, token_path=None, token_filename=None):
        """
        Init Backend
        :param str or Path token_path: the path where to store the token
        :param str token_filename: the name of the token file
        """
        super().__init__()
        if not isinstance(token_path, Path):
            token_path = Path(token_path) if token_path else Path()

        if token_path.is_file():
            #: Path to the token stored in the file system.  |br| **Type:** str
            self.token_path = token_path
        else:
            token_filename = token_filename or "o365_token.txt"
            self.token_path = token_path / token_filename
```

--------------------------------

### Create a Bucket

Source: https://o365.github.io/python-o365/latest/api/planner.html

Creates a new bucket within a plan. The order_hint parameter can be used to specify the bucket's position.

```python
create_bucket(_name_ , _order_hint =' !'_)
```

--------------------------------

### property Recipient.name

Source: https://o365.github.io/python-o365/latest/api/utils/utils.html

Gets or sets the name of the recipient.

```APIDOC
## property Recipient.name

### Description
Gets or sets the name of the recipient.

### Return type
str
```

--------------------------------

### Get Parent

Source: https://o365.github.io/python-o365/latest/api/onedrive.html

Retrieves the parent of the current DriveItem.

```APIDOC
## get_parent()

### Description
Returns the parent of this DriveItem.

### Returns
Parent of this item

### Return type
Drive or drive.Folder
```

--------------------------------

### Configure FileSystemTokenBackend

Source: https://o365.github.io/python-o365/latest/_sources/getting_started.rst.txt

Use FileSystemTokenBackend to store tokens as text files on the file system. Specify the token path and filename for storage.

```python
from O365 import Account, FileSystemTokenBackend

credentials = ('id', 'secret')

# this will store the token under: "my_project_folder/my_folder/my_token.txt".
# you can pass strings to token_path or Path instances from pathlib
token_backend = FileSystemTokenBackend(token_path='my_folder', token_filename='my_token.txt')
account = Account(credentials, token_backend=token_backend)

# This account instance tokens will be stored on the token_backend configured before.
# You don't have to do anything more
# ...
```

--------------------------------

### Task.reminder

Source: https://o365.github.io/python-o365/latest/api/tasks.html

Gets or sets the reminder time for the task.

```APIDOC
## Task.reminder

### Description
Get or set the reminder time of the task.

### Method
GET or PUT

### Endpoint
/me/todo/tasks/{task_id}/reminderDateTime

### Parameters
#### Request Body (for PUT)
- **reminder** (datetime) - The reminder time of the task.

### Returns:
datetime
```

--------------------------------

### Task.is_completed

Source: https://o365.github.io/python-o365/latest/api/tasks.html

Gets or sets whether the task is completed.

```APIDOC
## Task.is_completed

### Description
Get or set whether the task is completed.

### Method
GET or PUT

### Endpoint
/me/todo/tasks/{task_id}/isCompleted

### Parameters
#### Request Body (for PUT)
- **is_completed** (bool) - Set the task to completed or not.

### Returns:
bool
```

--------------------------------

### Create a Plan Instance

Source: https://o365.github.io/python-o365/latest/usage/planner.html

Instantiates a Planner object and creates a new plan within a specified group. Requires an authenticated account and a group object ID.

```python
#Create a plan instance
from O365 import Account
account = Account(('app_id', 'app_pw'))
planner = account.planner()
plan = planner.create_plan(
    owner="group_object_id", title="Test Plan"
)

```

--------------------------------

### Account Initialization

Source: https://o365.github.io/python-o365/latest/_modules/O365/account.html

Initializes an Account object with credentials and optional protocol configurations. Defaults to MSGraphProtocol. Handles different authentication flow types and scope conversions.

```python
from O365 import Account

credentials = ('client_id', 'client_secret')
acc = Account(credentials)
# Or with specific protocol and main resource
# acc = Account(credentials, protocol=MSGraphProtocol, main_resource='me')
# Or with custom connection arguments
# acc = Account(credentials, auth_flow_type='credentials', scopes=['basic.read'])

```

--------------------------------

### Task.due

Source: https://o365.github.io/python-o365/latest/api/tasks.html

Gets or sets the due time of the task.

```APIDOC
## Task.due

### Description
Get or set the due time of the task.

### Method
GET or PUT

### Endpoint
/me/todo/tasks/{task_id}/dueDateTime

### Parameters
#### Request Body (for PUT)
- **due** (datetime) - The due time of the task.

### Returns:
datetime
```

--------------------------------

### Task.completed

Source: https://o365.github.io/python-o365/latest/api/tasks.html

Gets or sets the completion time of the task.

```APIDOC
## Task.completed

### Description
Get or set the completed time of the task.

### Method
GET or PUT

### Endpoint
/me/todo/tasks/{task_id}/completedDateTime

### Parameters
#### Request Body (for PUT)
- **completed** (datetime) - The completed time of the task.

### Returns:
datetime
```

--------------------------------

### Get and Manage Contacts and Folders

Source: https://o365.github.io/python-o365/latest/_sources/usage/addressbook.rst.txt

Demonstrates retrieving all contacts, specific folders, creating messages to folder contacts, listing child folders, and creating new contact folders.

```python
address_book = account.address_book()

contacts = address_book.get_contacts(limit=None)  # get all the contacts in the Personal Contacts root folder

work_contacts_folder = address_book.get_folder(folder_name='Work Contacts')  # get a folder with 'Work Contacts' name

message_to_all_contats_in_folder = work_contacts_folder.new_message()  # creates a draft message with all the contacts as recipients

message_to_all_contats_in_folder.subject = 'Hallo!'
message_to_all_contats_in_folder.body = """
George Best quote:

If you'd given me the choice of going out and beating four men and smashing a goal in
from thirty yards against Liverpool or going to bed with Miss World,
it would have been a difficult choice. Luckily, I had both.
"""
message_to_all_contats_in_folder.send()

# querying folders is easy:
child_folders = address_book.get_folders(25) # get at most 25 child folders

for folder in child_folders:
    print(folder.name, folder.parent_id)

# creating a contact folder:
address_book.create_child_folder('new folder')
```

--------------------------------

### Task.body

Source: https://o365.github.io/python-o365/latest/api/tasks.html

Gets or sets the body content of the task.

```APIDOC
## Task.body

### Description
Get or set the Body of the task.

### Method
GET or PUT

### Endpoint
/me/todo/tasks/{task_id}/body

### Parameters
#### Request Body (for PUT)
- **body** (str) - The body text of the task.

### Returns:
str
```

--------------------------------

### Configure Proxy Server with Authentication

Source: https://o365.github.io/python-o365/latest/_modules/O365/connection.html

Sets up proxy configuration for HTTP and HTTPS connections, including optional username and password authentication.

```python
if proxy_server and proxy_port:
            if proxy_username and proxy_password:
                self.proxy = {
                    "http": "http://{}:{}@{}:{}".format(proxy_username,
                                                        proxy_password,
                                                        proxy_server,
                                                        proxy_port),
                    "https": "https://{}:{}@{}:{}".format(proxy_username,
                                                              proxy_password,
                                                              proxy_server,
                                                              proxy_port),
                }
            else:
                self.proxy = {
                    "http": "http://{}:{}".format(proxy_server, proxy_port),
                    "https": "https://{}:{}".format(proxy_server, proxy_port),
                }
```

--------------------------------

### Initialize AWS S3 Token Backend

Source: https://o365.github.io/python-o365/latest/_modules/O365/utils/token.html

Initializes the AWS S3 token backend, requiring bucket name and filename. It ensures the 'boto3' package is installed.

```python
def __init__(self, bucket_name, filename):
        """
        Init Backend
        :param str bucket_name: Name of the S3 bucket
        :param str filename: Name of the S3 file
        """
        try:
            import boto3
        except ModuleNotFoundError as e:
            raise Exception(
                "Please install the boto3 package to use this token backend."
            ) from e
        super().__init__()
        #: S3 bucket name.  |br| **Type:** str
        self.bucket_name = bucket_name
        #: S3 file name.  |br| **Type:** str
        self.filename = filename
        self._client = boto3.client("s3")
```

--------------------------------

### get_worksheet

Source: https://o365.github.io/python-o365/latest/_modules/O365/excel.html

Gets a specific worksheet by its ID or name.

```APIDOC
## GET /get_worksheet/{id}

### Description
Gets a specific worksheet by its ID or name.

### Method
GET

### Endpoint
/get_worksheet/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the worksheet to retrieve.

### Response
#### Success Response (200)
- **worksheet_constructor** (object) - The constructed worksheet object.
```

--------------------------------

### get_column

Source: https://o365.github.io/python-o365/latest/_modules/O365/excel.html

Gets a column from a table by its ID or name.

```APIDOC
## get_column

### Description
Retrieves a specific column from an Excel table using its unique identifier or name.

### Method
GET

### Endpoint
/get_column/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID or name of the column to retrieve.

### Response
#### Success Response (200)
- **WorkBookTableColumn** - The retrieved column object.

### Response Example
{
  "example": "WorkBookTableColumn object"
}
```
Tokens:
Raw