Neptune API Client

Warnings

• gotcha This library (`neptune-api`) is primarily an internal dependency for the main `neptune` client library. For most users, it is recommended to install and use the `neptune` library (`pip install neptune`) for a higher-level, more user-friendly experience.
  Fix: Consider using the `neptune` library unless you specifically need low-level API access or are developing an integration for the Neptune platform.
• breaking Version 0.25.0 removed support for `protobuf` versions older than 4.0.0. If you are using an older `protobuf` version, this will cause dependency resolution issues or runtime errors.
  Fix: Ensure your `protobuf` dependency is `~=4.0` or higher. Version 0.21.0 also updated allowed protobuf to include 6.x, so `protobuf>=4.0,<7.0` is generally safe.
• gotcha The `ApiClient` methods are often low-level, directly mapping to HTTP verbs and API endpoints (e.g., `post_create_run`, `get_project_details`). Interacting with them often requires detailed knowledge of the Neptune API's request/response structure and protobuf models.
  Fix: Refer to the Neptune API documentation or the source code of the higher-level `neptune` client for examples on constructing appropriate request bodies and interpreting responses using `neptune_api.models`.
• deprecated The `neptune-api` library is under continuous development, and internal API structures (like storage, ingestion APIs) are frequently updated. This can lead to breaking changes in specific service methods or models between minor versions, even without explicit 'breaking change' notes if used directly.
  Fix: Pin your `neptune-api` version if relying on specific low-level API calls to ensure stability. Regularly review release notes for changes if you need to upgrade.

Install

• pip install neptune-api Install latest version

Imports

• ApiClient

  from neptune_api.api.client import Client as ApiClient

  The primary entry point for direct API interaction.
• models

  from neptune_api import models

  Accesses the generated protobuf data models (e.g., Run, Project, Metric).
• UnauthorizedException

  from neptune_api.exceptions import UnauthorizedException

  Common exception for authentication failures.

Quickstart

This quickstart demonstrates how to instantiate the low-level Neptune API client and perform a basic authenticated call to retrieve the current user's identity. This library is generally used internally by the `neptune` client, so direct interaction often requires a deeper understanding of the specific API endpoints and their corresponding request/response models. Ensure `NEPTUNE_API_TOKEN` is set as an environment variable or replaced directly.

import os
from neptune_api.api.client import Client as ApiClient
from neptune_api.exceptions import UnauthorizedException

NEPTUNE_API_TOKEN = os.environ.get("NEPTUNE_API_TOKEN", "YOUR_API_TOKEN")

if NEPTUNE_API_TOKEN == "YOUR_API_TOKEN":
    print("Please set the NEPTUNE_API_TOKEN environment variable or replace 'YOUR_API_TOKEN' directly.")
    exit(1)

try:
    # Initialize the low-level API client
    api_client = ApiClient(api_token=NEPTUNE_API_TOKEN)

    # Example: Get the current user's identity
    # This is a basic authenticated call to verify setup.
    user_identity = api_client.post_get_user_identity()
    print(f"Successfully authenticated as user ID: {user_identity.id}")

    # To interact with specific resources (e.g., runs, projects), you would use
    # methods like `api_client.post_create_run` or `api_client.post_get_project_member_v2`
    # along with corresponding models from `neptune_api.models`.

except UnauthorizedException:
    print("Authentication failed. Please check your NEPTUNE_API_TOKEN.")
except Exception as e:
    print(f"An error occurred: {e}")