Skip to content

Neptune API index#

This page lists all functions, parameters, and constants exposed by the Neptune Python client library.

Sections:

Functions#

run[field_name] (field lookup)#

Use to access the field of an object through a dict-like path lookup:

import neptune

run = neptune.init_run()

field_handler = run["namespace/subnamespace/field"]

=#

Convenience alias for assign().

add()#

StringSet method.

  • When called on run["sys/tags"], adds the provided strings to the run's tags.
  • When called on run["sys/group_tags"], assigns the run to the provided groups.

Related

add_project_member()#

management function for adding a user to a project.

add_project_service_account()#

management function for assigning a service account to a project.

append()#

Depending on the type of the logged metadata, creates a FileSeries, FloatSeries, or StringSeries field. Iteratively appends the provided value to the series.

Creating a FloatSeries
import neptune

run = neptune.init_run()

for epoch in range(parameters["n_epochs"]):
    ...  # My training loop
    run["train/epoch/loss"].append(loss)  # (1)!
  1. train/epoch/loss is now a FloatSeries field.

Related

Logging a series of values or files

as_html()#

File method.

Converts an object to a File value object.

Use to upload interactive charts or data frames.

as_image()#

File method.

Static method for converting image-like objects to a File value object.

Use to upload figures, arrays, and tensors as static images.

as_pickle()#

File method.

Pickles a Python object and stores it in a File value object.

assign()#

Assigns the provided value or dictionary to a field or namespace.

Works for the following Neptune field types:

change_stage()#

Deprecated

This function is deprecated.

For model management using runs, see Log model metadata.

ModelVersion method for changing the stage of a model version.

clear()#

StringSet method.

  • When called on the object["sys/tags"] field of a run, removes all tags from the object.
  • When called on the object["sys/group_tags"] field of a run, removes the run from all groups.

clear_trash()#

management function for emptying the trash of the specified project.

create_project()#

management function for creating a new project.

del#

Command that completely removes the field or namespace and all associated metadata stored under the path.

import neptune

run = neptune.init_run(with_id="NLI-8") # (1)!
del run["nlp-dataset"]
  1. NLI-8 is the ID of an existing run that has something stored in the field nlp-dataset

delete_files()#

FileSet method.

Deletes the specified files from the field.

delete_objects_from_trash()#

management function for deleting items from a project's trash.

delete_project()#

management function for deleting a project.

download()#

Downloads the file(s) stored in the field when called on an object path.

Available for the following field types:

download_last()#

Downloads the last file stored in a FileSeries field and saves it locally.

exists()#

Object-level method that checks if there is a field or namespace under the specified path.

>>> import neptune
>>> run = neptune.init_run(with_id="NLI-8") # (1)!
>>> run.exists("nlp-dataset")
True
  1. NLI-8 is the ID of an existing run that has something stored in the field nlp-dataset

extend()#

Depending on the type of the logged metadata, creates a FileSeries, FloatSeries, or StringSeries field. Iteratively appends the provided collection of values to the series.

fetch()#

Fetches the field value.

Available for the following Neptune field types:

fetch_extension()#

File method.

Returns the extension of a stored file.

fetch_files_list()#

Artifact method.

Fetches a list of artifact files.

fetch_hash()#

Artifact method.

Fetches the hash of the artifact.

fetch_last()#

FloatSeries and StringSeries method.

Fetches the last value stored in the series.

fetch_model_versions_table()#

Deprecated

This function is deprecated.

For model management using runs, see Log model metadata.

Model method for listing the metadata of all versions of the model as a table.

fetch_models_table()#

Deprecated

This function is deprecated.

For model management using runs, see Log model metadata.

Project method for listing the metadata of all models as a table.

fetch_runs_table()#

Project method for listing the metadata of all runs as a table.

fetch_values()#

FloatSeries and StringSeries method.

Fetches all values stored in the series.

from_content()#

File method.

Factory method for creating File value objects directly from binary and text content.

from_path()#

File method.

Creates a File value object from a given path.

Equivalent to File(path), but you can specify the extension separately.

from_stream()#

File method.

Factory method for creating File value objects directly from binary and text streams.

get_last_run()#

Deprecated

This function is deprecated as of neptune 1.0.

Fetches the last created run object of the session.

get_project()#

Deprecated

This function is deprecated as of neptune 1.0.

Use neptune.init_project(mode="read-only") instead.

Initializes a connection to a project in read-only mode.

get_project_list()#

management function for listing projects that a given Neptune account has access to.

get_project_member_list()#

management function for listing members of a project.

get_project_service_account_list()#

management function for listing the service accounts assigned to a project.

get_root_object()#

Returns the root-level object of a namespace handler.

In other words, if called on a path inside a run, returns the run.

get_run_url()#

Deprecated

This function is deprecated as of neptune-client 0.16.10.

Use get_url() instead.

get_structure()#

Object-level method.

Returns the metadata structure of an object in the form of a dictionary.

>>> import neptune
>>> run = neptune.init_run(with_id="NLI-8")
>>> run.get_structure()
{'data': {'val': <neptune.attributes.atoms.artifact.Artifact object at 0x0000020374B822C0>}, 'f1_score': <neptune.attributes.atoms.float.Float object at 0x0000020374B81A50>, 'monitoring': {'cpu': <neptune.attributes.series.float_series.FloatSeries object at 0x0000020374B81A80>, ... }}

See also: print_structure()

get_url()#

Object-level method.

Returns a direct link to the object.

>>> import neptune
>>> run = neptune.init_run(with_id="NLI-8")
>>> run.get_url()
https://app.neptune.ai/jackie/named-entity-recognition/e/NLI-8

get_workspace_member_list()#

management function for listing the members of a workspace.

get_workspace_service_account_list()#

management function for listing the service accounts of a workspace.

get_workspace_status()#

management function for retrieving status information about a workspace's storage, projects, and members.

init()#

Deprecated

This function is deprecated as of neptune 1.0.

Use neptune.init_run() instead.

Convenience alias for init_run().

init_model()#

Deprecated

This function is deprecated.

For model management using runs, see Log model metadata.

init_model_version()#

Deprecated

This function is deprecated.

For model management using runs, see Log model metadata.

init_project()#

Calling neptune.init_project() onnects to a Neptune project as a container for metadata.

Use to log metadata in the Project metadata section.

init_run()#

Calling neptune.init_run() creates a new Neptune run and an entry in the experiments table of the specified project.

To reinitialize an existing run for logging or fetching metadata:

  • Pass the run's auto-generated Neptune ID to the with_id argument.
  • If set, pass the run's custom ID to the custom_run_id argument.

invite_to_workspace()#

management function for inviting a user to a workspace.

list_fileset_files()#

FileSet method.

Fetches metadata on the file set. If the top-level artifact of the field is a directory, only metadata on this directory is returned.

log()#

See append() (append one value at a time) or extend() (append a collection of values at once).

pop()#

Object- or field-level method that completely removes a field or namespace and all associated metadata stored under the path.

If called on the root object, pass the field to remove as the argument.

# The following line
run.pop("parameters/learninggg_rata")
# is equiavlent to this line
run["parameters/learninggg_rata"].pop()
# and this line
run["parameters"].pop("learninggg_rata")

See also del.

Object-level method.

Pretty-prints the metadata structure of the run or project.

>>> import neptune
>>> run = neptune.init_run(with_id="NER-35")
>>> run.print_structure()
'data':
    'val': Artifact
'f1_score': Float
...

See also: get_structure()

remove()#

StringSet method.

  • When called on the object["sys/tags"] field of a run, removes the specified tags from the object.
  • When called on the object["sys/group_tags"] field of a run, removes the run from the specified groups.

remove_project_member()#

management function for removing a member from a project.

remove_project_service_account()#

management function for removing a service account from a project.

stop_synchronization_callback()#

utils function. Default callback function that is called if the synchronization lags too much or has not progressed at all.

For details, see How to use callbacks when sync is interrupted.

stop()#

Object-level method. Stops the connection to Neptune and synchronizes all data with the Neptune servers.

If you're running Neptune in a Python script, Neptune stops any initialized objects automatically when the script finishes execution.

Interactive sessions

Always call stop() in interactive environments, such as a Python interpreter or Jupyter notebook. The connection to Neptune is not stopped when the cell has finished executing, but rather when the entire notebook stops.

If you're running a script, the connection is stopped automatically when the script finishes executing. However, it's a best practice to call stop() when the connection is no longer needed.

import neptune

run = neptune.init_run()

[...]  # Your training or monitoring code

# stop() is automatically called at the end for every Neptune object

Using with statement and context manager:

for config in configs:
    with neptune.init_run() as run:
        [...]  # Your training or monitoring code
        # stop() is automatically called when code execution exits the with statement

stringify_unsupported()#

utils function. Converts unsupported values in a dictionary or collection to strings.

sync()#

Object-level method.

Synchronizes the local representation of the object with the representation on the Neptune servers.

# Connect to a run from Worker #3
worker_id = 3
run = neptune.init_run(
    with_id="DIST-43",
    monitoring_namespace=f"monitoring/{worker_id}",
)

# Try to access logs that were created in the meantime by Worker #2
worker_2_status = run["status/2"].fetch()
# Error if this field was created after this script starts

run.sync() # Synchronize local representation with Neptune servers
worker_2_status = run["status/2"].fetch() # No error

to_pandas()#

Table method. Converts the object returned by fetch_runs_table() to a pandas DataFrame.

track_files()#

Creates an Artifact field when called on an object path.

Iteratively adds references to new files if called on an existing Artifact field.

import neptune

run = neptune.init_run()

run["nlp-dataset"].track_files("path/to/dir/")
...
run["nlp-dataset"].track_files("path/to/another/file")

trash_objects()#

management function for moving objects to the project trash.

Note

Emptying the trash is a separate action. A trashed item is permanently deleted only when the trash is emptied.

upload()#

Creates a File field when called on an object path.

Uploads the provided file under the specified field path.

upload_files()#

Creates a FileSet field when called on an object path.

Uploads the provided directory or file(s) and stores them under the FileSet field.

wait()#

Object-level method.

Wait for all the logging calls (queued operations) to reach the Neptune servers before continuing execution.

import neptune

run = neptune.init_run()
run["parameters"] = PARAMS

run.wait()

The logged metadata can now be fetched from the Neptune server:

fetched_params = run["parameters"].fetch()

Parameters#

api_token#

Neptune initialization parameter that takes the API token of a user or service account as the argument.

Used to ensure that the account which performs the logging has access to the target project.

To keep your token secure, avoid placing it in source code. Instead, save it as an environment variable.

ascending#

Parameter for controlling the sorting order when fetching a project's runs with fetch_runs_table().

async_lag_callback#

Neptune initialization parameter that takes a callback function as the argument.

If a lag callback is enabled, it's triggered if the lag between a queued operation and its synchronization with the server exceeds the duration defined by async_lag_threshold.

async_lag_threshold#

Neptune initialization parameter that represents a threshold for the duration between the queueing and synchronization of an operation (in seconds).

If a lag callback is enabled, the callback is called when this duration is exceeded.

async_no_progress_callback#

Neptune initialization parameter that takes a callback function as the argument.

If a no-progress callback is enabled, it's triggered if no data has been synchronized with the server for a duration defined by async_lag_threshold.

async_no_progress_threshold#

Neptune initialization parameter that represents a threshold for the duration of no data being synchronized to the server.

If a no-progress callback is enabled, the callback is called when this duration is exceeded.

autoscale#

File.as_image() parameter for controlling whether Neptune should try to scale image pixel values, to better render them in the web app.

chart#

File.as_html() parameter for converting interactive charts to HTML. Takes an Altair, Bokeh, Plotly, Matplotlib, Seaborn, or pandas DataFrame object as the argument.

content#

File.from_content() parameter that takes binary or text content as the argument.

custom_run_id#

Related

Setting custom run ID

Neptune run initialization parameter that takes a unique, user-defined identifier as the argument.

Can be used to log metadata to a single run from multiple locations.

description#

  • When creating a new run, an editable description of the object, stored in sys/description. Can be added as a column in the experiments table.
  • Series parameter used to set a custom name for an entry.

destination#

Available for fetching methods that download metadata from the Neptune servers to the local machine.

disk_only#

wait() parameter. Controls whether the process should wait only for the data to be saved locally from memory and not for it to reach Neptune servers.

expand#

stringify_unsupported() parameter, to help log series values in a proper folder structure instead of a string.

extension#

Parameter for setting or interpreting file types when creating File fields.

flush_period#

Neptune initialization parameter. Controls how often Neptune should trigger disk flushing in asynchronous mode.

Note

The OS can trigger disk flushing implicitly. As such, setting flush_period=600 will flush the disk at least every 600 seconds, but it can happen more frequently for other reasons.

globs#

FileSet.upload_files parameter that takes the paths of the files to be uploaded.

include_timestamp#

fetch_values() parameter used to control whether to include timestamps when fetching values from a FloatSeries or StringSeries field.

key#

Deprecated

This parameter is deprecated.

For model management using runs, see Log model metadata.

limit#

Parameter for limiting the number of returned entries when fetching a project's runs with fetch_runs_table().

mode#

Neptune initialization parameter. Sets the connection mode in which the logging will work. Possible values are async, sync, offline, read-only, and debug.

For more, see Using Neptune in different modes.

model#

Deprecated

This function is deprecated.

For model management using runs, see Log model metadata.

name#

  • When creating a new run, a custom name for the object, stored in sys/name.
  • Series parameter used to set a custom name for an entry.

obj#

File.as_pickle() parameter that takes a pickleable Python object as the argument.

path#

Available for several logging methods that concern tracking or uploading files.

paths#

FileSet.delete_files() parameter that takes the paths of the files to be deleted from the fileset (relativ to the set root).

progress_bar#

Parameter for disabling the progress bar or passing your own progress bar type when querying the API.

Available when

project#

Used to specify the Neptune project when initializing Neptune objects or performing management actions.

Typically given in the form workspace-name/project-name.

For management functions, a separate optional workspace argument is available. If it's provided, the project argument can consist of the project-name part alone.

proxies#

Neptune initialization parameter whose argument is passed to HTTP calls made via the Requests library.

query#

Available when fetching runs with the fetch_runs_table() function.

Takes a raw NQL string as the argument.

project = neptune.init_project()
project.fetch_runs_table(query="`f1_score`:float > 0.6")

repository_path#

GitRef parameter for specifying where Neptune should look for a Git repository when a run is created.

seconds#

stop() parameter that specifies for how long Neptune should wait before terminating the connection. (By default, Neptune waits for all logging calls and operations to finish before actually stopping the connection.)

seek#

File.from_stream() parameter that takes a byte offset as the argument.

sort_by#

Parameter for controlling the sorting column when fetching a project's runs with fetch_runs_table().

source_files#

Available for neptune.init_run().

Used to specify which source files to upload.

Info

Files uploaded this way are displayed in the Source code dashboard in the web app.

step#

Series parameter used to set a custom index.

steps#

Series parameter used to set custom indexes when appending multiple values at a time with the extend() function.

stream#

File.from_stream() parameter that takes a binary or text stream as the argument.

tags#

Available for neptune.init_run().

Used to apply tags to a Neptune run. Takes a list of strings as the argument.

timestamp#

Series parameter used to set custom timestamps.

timestamps#

Series parameter used to set custom timestamps when appending multiple values at a time with the extend() function.

value#

Available for logging functions that are used to assign a single value to a field.

values#

Available for logging functions that are used to assign multiple values to a field at a time (or remove them).

wait#

Available for all logging functions.

By default, logging calls and other Neptune operations are periodically synchronized with the server in the background. If True, Neptune first waits to complete any queued operations, then executes the call and continues script execution.

with_id#

Neptune initialization parameter for connecting to an existing run. Takes the Neptune ID of the object to resume (for example, NLI-8).

The Neptune ID is a unique identifier for the object. It's assigned automatically when the object is created.

In the table view, it's displayed in the leftmost column.

workspace#

Used to specify the Neptune workspace when performing management actions.

Constants#

ANONYMOUS#

Deprecated

This constant is deprecated as of neptune 1.0.

Equivalent to ANONYMOUS_API_TOKEN.

ANONYMOUS_API_TOKEN#

API token for anonymous logging.

You can use this value for the api_token argument of the init functions in order to log metadata to one of Neptune's public projects.

DISABLED#

Constant for GitRef that disables Git tracking for a run.

Related