feat: Add client for Notebook & Notebook Execution APIs (#105)

Co-authored-by: rmilea <[email protected]>

Author: MileaRobertStefan

docs/api_reference.rst

@@ -14,6 +14,7 @@ API Reference
    api_reference/dataframe
    api_reference/spec
    api_reference/file
+   api_reference/notebook
    api_reference/feeds
 
 Indices and tables

docs/api_reference/notebook.rst

@@ -0,0 +1,23 @@
+.. _api_tag_page:
+
+nisystemlink.clients.notebook
+======================
+
+.. autoclass:: nisystemlink.clients.notebook.NotebookClient
+   :exclude-members: __init__
+
+   .. automethod:: __init__
+   .. automethod:: get_notebook
+   .. automethod:: update_notebook
+   .. automethod:: delete_notebook
+   .. automethod:: create_notebook
+   .. automethod:: query_notebooks
+   .. automethod:: get_notebook_content
+   .. automethod:: create_executions
+   .. automethod:: get_execution_by_id
+   .. automethod:: query_executions
+
+
+.. automodule:: nisystemlink.clients.notebook.models
+    :members:
+    :imported-members:

docs/getting_started.rst

@@ -106,7 +106,6 @@ Create, query, update, and delete some products
 
 DataFrame API
 -------
-
 Overview
 ~~~~~~~~
 
@@ -186,6 +185,7 @@ Update and Delete Specifications
    :language: python
    :linenos:
 
+
 File API
 -------
 
@@ -285,5 +285,38 @@ Create, query, update, and delete some results
 Create, update, query, and delete steps
 
 .. literalinclude:: ../examples/testmonitor/steps.py
+   :language: python
+   :linenos
+
+Notebook API
+-------
+
+Overview
+~~~~~~~~
+
+The :class:`.NotebookClient` class is the primary entry point of the Notebook API.
+
+When constructing a :class:`.NotebookClient`, you can pass an
+:class:`.HttpConfiguration` (like one retrieved from the
+:class:`.HttpConfigurationManager`), or let :class:`.NotebookClient` use the
+default connection. The default connection depends on your environment.
+
+With a :class:`.NotebookClient` object, you can:
+
+* Create, update, query, and delete Notebooks
+* Create, get and query Notebook Executions
+
+Examples
+~~~~~~~~
+
+Create, query, update, and delete some notebooks.
+
+.. literalinclude:: ../examples/notebook/notebook.py
+   :language: python
+   :linenos:
+
+Create, query, retry, and cancel notebook executions.
+
+.. literalinclude:: ../examples/notebook/notebook_execution.py
    :language: python
    :linenos:

examples/notebook/notebook.py

@@ -0,0 +1,60 @@
+from nisystemlink.clients.core import HttpConfiguration
+from nisystemlink.clients.notebook import NotebookClient
+from nisystemlink.clients.notebook.models import NotebookMetadata, QueryNotebookRequest
+
+# Setup the server configuration to point to your instance of SystemLink Enterprise
+server_configuration = HttpConfiguration(
+    server_uri="https://yourserver.yourcompany.com",
+    api_key="YourAPIKeyGeneratedFromSystemLink",
+)
+client = NotebookClient(configuration=server_configuration)
+
+# Create a notebook with metadata and content
+metadata = NotebookMetadata(
+    name="Example Notebook",
+    parameters={"param1": "value1"},
+    properties={"property1": "value1"},
+)
+
+with open("example.ipynb", "rb") as file:
+    notebook_response = client.create_notebook(metadata=metadata, content=file)
+
+# Get the notebook by ID
+notebook = client.get_notebook("your_notebook_id")
+
+# Update the notebook with new metadata and content
+metadata = NotebookMetadata(
+    name="Updated Example Notebook",
+    parameters={"param1": "value2"},
+    properties={"property1": "value2"},
+)
+
+with open("example_updated.ipynb", "rb") as file:
+    notebook_response = client.update_notebook(
+        id="your_notebook_id",
+        metadata=metadata,
+        content=file,
+    )
+
+# Get notebook content by ID
+notebook_content = client.get_notebook_content("your_notebook_id")
+
+# Query notebook by name
+query_request = QueryNotebookRequest(
+    filter='name="Example Notebook"',
+)
+
+query_response = client.query_notebooks(query_request)
+
+# Query notebooks by take
+query_request = QueryNotebookRequest(take=2)
+query_response = client.query_notebooks(query_request)
+
+query_request = QueryNotebookRequest(
+    continuation_token=query_response.continuation_token,
+    take=1,
+)
+query_response = client.query_notebooks(query_request)
+
+# Delete the notebook by ID
+client.delete_notebook("your_notebook_id")

examples/notebook/notebook_execution.py

@@ -0,0 +1,66 @@
+from nisystemlink.clients.core import HttpConfiguration
+from nisystemlink.clients.notebook import NotebookClient
+from nisystemlink.clients.notebook.models import (
+    CreateExecutionRequest,
+    ExecutionField,
+    ExecutionPriority,
+    ExecutionResourceProfile,
+    ExecutionSortField,
+    ExecutionStatus,
+    QueryExecutionsRequest,
+    ReportSettings,
+    ReportType,
+)
+
+# Setup the server configuration to point to your instance of SystemLink Enterprise
+server_configuration = HttpConfiguration(
+    server_uri="https://yourserver.yourcompany.com",
+    api_key="YourAPIKeyGeneratedFromSystemLink",
+)
+client = NotebookClient(configuration=server_configuration)
+
+
+# Create a notebook execution
+execution_request = CreateExecutionRequest(
+    notebook_id="your_notebook_id",
+    parameters={"param1": "value1"},
+    workspace_id="your_workspace_id",
+    timeout=300,
+    result_cache_period=3600,
+    report_settings=ReportSettings(
+        format=ReportType.HTML,
+        exclude_code=False,
+    ),
+    client_requests_id="your_client_request_id",
+    priority=ExecutionPriority.HIGH,
+    resource_profile=ExecutionResourceProfile.DEFAULT,
+)
+
+# Pass the list of execution requests to the create_executions method
+create_execution_response = client.create_executions([execution_request])
+
+# Get the execution by ID
+execution = client.get_execution_by_id("your_execution_id")
+
+# Query executions
+query_request = QueryExecutionsRequest(
+    filter=f"(status = {ExecutionStatus.FAILED.value}))",
+    order_by=ExecutionSortField.COMPLETED_AT,
+    descending=True,
+    projection=[
+        ExecutionField.ID,
+        ExecutionField.NOTEBOOK_ID,
+        ExecutionField.STATUS,
+    ],
+)
+
+query_executions_response = client.query_executions(query_request)
+
+# Cancel execution
+cancel_execution_response = client.cancel_executions(["your_execution_id"])
+
+# Retry execution
+retry_execution_response = client.retry_executions(["your_execution_id"])
+
+# Create execution from existing one
+run_new = client.create_executions_from_existing(["your_execution_id"])

nisystemlink/clients/core/_uplink/_methods.py

@@ -40,6 +40,17 @@ def decorator(func: F) -> F:
     return decorator
 
 
+def put(path: str, args: Optional[Sequence[Any]] = None) -> Callable[[F], F]:
+    """Annotation for a PUT request with a JSON request body. If args is not
+    specified, defaults to a single argument that represents the request body.
+    """
+
+    def decorator(func: F) -> F:
+        return json(commands.put(path, args=args or (Body,))(func))  # type: ignore
+
+    return decorator
+
+
 def patch(path: str, args: Optional[Sequence[Any]] = None) -> Callable[[F], F]:
     """Annotation for a PATCH request with a JSON request body."""
 

nisystemlink/clients/notebook/__init__.py

@@ -0,0 +1,3 @@
+from ._notebook_client import NotebookClient
+
+# flake8: noqa