Neptune Fetcher

Warnings

• breaking The `neptune-fetcher` library is officially deprecated. Users are strongly advised to migrate to the `neptune-query` library for future development and maintenance. The `neptune-fetcher` will receive only critical bug fixes and dependency updates, with no new features.
  Fix: Migrate your code to use `neptune-query`. Install with `pip install neptune-query` and refer to its documentation for updated usage patterns. The `get_project` and `fetch_*_df` methods have similar counterparts in `neptune-query` but with potentially different arguments and return types.
• gotcha Python compatibility is limited to versions 3.9 and higher, but strictly less than 4.0. Users on older Python versions (e.g., 3.8) or attempting to use it with Python 4.0 (if released) will encounter installation or runtime errors.
  Fix: Ensure your environment uses a compatible Python version (3.9, 3.10, 3.11, 3.12). Consider updating your Python environment or using virtual environments.
• gotcha Prior to version 0.22.0, fetching large DataFrames could lead to `PerformanceWarning` due to inefficient column insertion, potentially impacting performance with very wide datasets.
  Fix: Upgrade to `neptune-fetcher` version 0.22.0 or higher to benefit from performance improvements in DataFrame creation. Better yet, migrate to `neptune-query` which has optimized data handling.
• gotcha Default soft/hard retry timeouts for API calls were significantly increased in versions 0.20.1 and 0.21.0-beta.2/1. This can affect how long operations might hang before failing in case of network issues or server unresponsiveness.
  Fix: Update to `neptune-fetcher` 0.20.1 or newer to get updated default retry timeouts. If you need fine-grained control, consider implementing custom retry logic or checking for configuration options within the underlying `neptune-api`.

Install

• pip install neptune-fetcher Install stable version

Imports

• get_project

  from neptune_fetcher import get_project

  The `get_project` function is exposed directly at the top level of the package.

Quickstart

This quickstart demonstrates how to initialize a Neptune project using `neptune-client` and then use `neptune-fetcher`'s `get_project` to fetch run data. It explicitly warns about the library's deprecation and recommends `neptune-query`.

import neptune
from neptune_fetcher import get_project
import os

# NOTE: This library is deprecated. Use `neptune-query` instead.
# Ensure NEPTUNE_API_TOKEN and NEPTUNE_PROJECT are set as environment variables

# Initialize a Neptune project session (from neptune-client)
project_name = os.environ.get('NEPTUNE_PROJECT', 'common/quick-start') # Replace with your project
project_api_token = os.environ.get('NEPTUNE_API_TOKEN', 'ANONYMOUS')

if project_api_token == 'ANONYMOUS':
    print("Warning: Using anonymous access. Please set NEPTUNE_API_TOKEN for full functionality.")

# The neptune.init_project call is from neptune-client, required to authenticate
neptune_project = neptune.init_project(
    project=project_name,
    api_token=project_api_token, 
    mode="read-only"
)

print(f"Initialized Neptune Project: {neptune_project.full_id}")

# Use neptune-fetcher to get the project handler
fetcher_project = get_project(project=neptune_project.full_id)

# Fetch runs data as a Pandas DataFrame
runs_df = fetcher_project.fetch_runs_df(columns=['sys/name', 'training/acc'], states=['succeeded'])

print(f"Fetched {len(runs_df)} runs.")
if not runs_df.empty:
    print(runs_df.head())

# Stop the Neptune project session
neptune_project.stop()