PEPhub Client Library

0.5.1 · active · verified Thu Apr 16

The `pephubclient` is a Python client library for interacting with PEPhub, a web-based platform for managing Portable Encapsulated Projects (PEPs). It provides an interface to access, create, and manage PEPs programmatically, wrapping the PEPhub REST API. The current version is 0.5.1, with a release cadence that generally follows new features and bug fixes for the PEPhub platform itself.

Common errors

```
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://pephub.databio.org/api/v1/user/
```
cause Attempting to perform an authenticated action (e.g., list private projects, fetch a private project) without a valid API key or correct login.

fix Set the `PH_KEY` environment variable with your PEPhub API key and call `phc.login(api_key=os.environ.get('PH_KEY'))` before the authenticated action.
```
pephubclient.exceptions.ProjectNotFoundException: Project 'your_namespace/your_project:your_tag' not found.
```
cause The specified project (namespace, name, and tag combination) does not exist on PEPhub or is not accessible to your user.

fix Verify the project details (namespace, name, tag). Ensure the project is public or that you are correctly authenticated and have permissions to access it. You can use `phc.list_namespaces()` and `phc.list_projects(namespace=...)` to inspect available projects.
```
ImportError: cannot import name 'PEPHubClient' from 'pephubclient' (<path_to_pephubclient/__init__.py>)
```
cause You might be using an older version of `pephubclient` where `PEPHubClient` was not directly exposed at the package root, or the library is not correctly installed.

fix Upgrade to the latest `pephubclient` (`pip install --upgrade pephubclient`). If the issue persists, try `from pephubclient.client import PEPHubClient` (though this is not the recommended path for current versions).

Warnings

gotcha Authentication is required for private projects and many write operations. If you attempt an authenticated action without logging in or with an invalid API key, you will receive an `Unauthorized` error.
Fix: Ensure your `PH_KEY` environment variable is set with a valid PEPhub API key or pass it directly to `phc.login(api_key=...)`. Public projects can often be accessed without explicit login.
gotcha The `pephubclient` wraps the PEPhub REST API. Changes to the PEPhub API on the server side might occasionally require updates to the client library to maintain compatibility. If you encounter unexpected errors after a PEPhub server update, check for a new client version.
Fix: Upgrade to the latest version of `pephubclient` using `pip install --upgrade pephubclient`.
gotcha Trying to access a project that does not exist or whose namespace/name/tag combination is incorrect will result in a `ProjectNotFoundException`.
Fix: Double-check the namespace, name, and tag for the project you are trying to retrieve. Use `list_namespaces()` and `list_projects(namespace=...)` to verify available projects if you have authentication.

Install

pip install pephubclient Install stable version

Imports

PEPHubClient
wrong:
```
from pephubclient.client import PEPHubClient
```
correct:
```
from pephubclient import PEPHubClient
```
The primary client class is directly exposed at the top level of the package since version 0.5.0. Older versions might have required `from pephubclient.client import PEPHubClient`.

Quickstart

Initializes the PEPhub client and attempts to retrieve a public project. For private projects or authenticated actions, you would typically log in using an API key (e.g., from the `PH_KEY` environment variable).

import os
from pephubclient import PEPHubClient

# Initialize the client. The default host is https://pephub.databio.org
phc = PEPHubClient()

# Retrieve a publicly accessible project from PEPhub.
# 'test/test_project:test' is a common example project for testing.
try:
    project = phc.get_project(namespace='test', name='test_project', tag='test')
    print(f"Successfully retrieved project: {project.name}")
    print(f"Project description: {project.description}")
    print(f"Number of samples: {len(project.samples)}")
except Exception as e:
    print(f"Error retrieving project 'test/test_project:test': {e}")
    print("This project might not exist or might require authentication. ")
    print("For private projects, set the PH_KEY environment variable and ")
    print("then call `phc.login(api_key=os.environ.get('PH_KEY'))` before fetching.")

view raw JSON →