🔍 Code Extractor

A collection class for managing OneNote notebooks, providing methods to create, retrieve, and query notebooks within Microsoft 365, SharePoint, or group contexts.

Purpose

NotebookCollection serves as a specialized entity collection for managing OneNote Notebook objects. It extends EntityCollection to provide notebook-specific operations including creating new notebooks, retrieving notebooks by web URL, and fetching recently accessed notebooks. This class is designed to work within the Office 365 API context and handles the underlying query operations for notebook management.

Source Code

class NotebookCollection(EntityCollection[Notebook]):
    def __init__(self, context, resource_path=None):
        super(NotebookCollection, self).__init__(context, Notebook, resource_path)

    def add(self, display_name):
        """
        Create a new OneNote notebook.

        :param str display_name: Name for the notebook. Notebook names must be unique. The name cannot contain more
            than 128 characters or contain the following characters: ?*/:<>|'"
        :rtype: Notebook
        """
        return super(NotebookCollection, self).add(displayName=display_name)

    def get_notebook_from_web_url(self, web_url):
        """
        Retrieve the properties and relationships of a notebook object by using its URL path.
        The location can be user notebooks on Microsoft 365, group notebooks,
        or SharePoint site-hosted team notebooks on Microsoft 365.

        :param str web_url: The URL path of the notebook to retrieve. It can also contain a "onenote:" prefix.
        """
        return_type = ClientResult(self.context, CopyNotebookModel())
        params = {"webUrl": web_url}
        qry = ServiceOperationQuery(
            self, "getNotebookFromWebUrl", params, None, None, return_type
        )
        self.context.add_query(qry)
        return return_type

    def get_recent_notebooks(self, include_personal_notebooks=True):
        """Get a list of recentNotebook instances that have been accessed by the signed-in user.

        :param bool include_personal_notebooks: Include notebooks owned by the user. Set to true to include notebooks
            owned by the user; otherwise, set to false. If you don't include the includePersonalNotebooks parameter,
            your request will return a 400 error response.
        """

        return_type = ClientResult(self.context, ClientValueCollection(RecentNotebook))
        params = {"includePersonalNotebooks": include_personal_notebooks}
        qry = FunctionQuery(self, "getRecentNotebooks", params, return_type)
        self.context.add_query(qry)
        return return_type

Parameters

Parameter Details

context: The Office 365 API context object that manages authentication, requests, and communication with the Microsoft Graph API. This is required for all API operations.

resource_path: Optional string representing the resource path in the API endpoint hierarchy. If not provided, defaults to None and the path is determined by the parent EntityCollection class.

Return Value

Instantiation returns a NotebookCollection object that can be used to manage notebooks. The add() method returns a Notebook object. The get_notebook_from_web_url() method returns a ClientResult containing a CopyNotebookModel. The get_recent_notebooks() method returns a ClientResult containing a ClientValueCollection of RecentNotebook objects.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.entity_collection import EntityCollection
from office365.onenote.notebooks.copy_notebook_model import CopyNotebookModel
from office365.onenote.notebooks.notebook import Notebook
from office365.onenote.notebooks.recent import RecentNotebook
from office365.runtime.client_result import ClientResult
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.queries.function import FunctionQuery
from office365.runtime.queries.service_operation import ServiceOperationQuery

Usage Example

# Assuming you have an authenticated Office 365 context
from office365.onenote.notebooks.collection import NotebookCollection

# Create a notebook collection instance
notebook_collection = NotebookCollection(context=office365_context)

# Create a new notebook
new_notebook = notebook_collection.add(display_name="My Project Notebook")
context.execute_query()

# Get a notebook from a web URL
web_url = "https://contoso.sharepoint.com/sites/team/SiteAssets/My%20Notebook"
notebook_result = notebook_collection.get_notebook_from_web_url(web_url)
context.execute_query()
notebook_model = notebook_result.value

# Get recent notebooks
recent_notebooks_result = notebook_collection.get_recent_notebooks(include_personal_notebooks=True)
context.execute_query()
recent_notebooks = recent_notebooks_result.value

Best Practices

• Always call context.execute_query() after operations to execute the queued API requests
• Notebook names must be unique and cannot exceed 128 characters
• Avoid using special characters (?*/:<>|'") in notebook display names
• When using get_recent_notebooks(), always explicitly set include_personal_notebooks parameter to avoid 400 errors
• Handle ClientResult objects properly by accessing the .value property after query execution
• Ensure proper authentication and API permissions are configured before instantiating the collection
• The collection inherits from EntityCollection, so standard collection operations (iteration, filtering) are available
• Web URLs passed to get_notebook_from_web_url() can optionally include the 'onenote:' prefix

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class OnenotePageCollection 84.0% similar

  A collection class for managing OneNote pages within a OneNote notebook, providing methods to create and manage multiple OnenotePage instances.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/onenote/pages/collection.py

• class Notebook 79.2% similar

  Represents a OneNote notebook entity with access to its sections and section groups, providing a hierarchical structure for organizing OneNote content.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/onenote/notebooks/notebook.py

• class Onenote 73.5% similar

  The Onenote class serves as the entry point for accessing Microsoft OneNote resources through the Microsoft Graph API, providing access to notebooks, pages, sections, and other OneNote entities.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/onenote/onenote.py

• class NavigationNodeCollection 66.9% similar

  A collection class for managing SharePoint navigation nodes, providing methods to add, retrieve, and manipulate navigation nodes within a SharePoint site's navigation structure.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/navigation/node_collection.py

• class RecentNotebook 63.6% similar

  A data class representing a recently accessed OneNote notebook with display name and navigation links.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/onenote/notebooks/recent.py