{"id":8411,"library":"pephubclient","title":"PEPhub Client Library","description":"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.","status":"active","version":"0.5.1","language":"en","source_language":"en","source_url":"https://github.com/databio/pephubclient/","tags":["data management","bioinformatics","PEP","PEPhub","client-library"],"install":[{"cmd":"pip install pephubclient","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"HTTP client for API communication","package":"requests"},{"reason":"Logging utility","package":"logmuse"},{"reason":"JSON schema validation","package":"jsonschema"},{"reason":"Core dependency for handling PEP objects locally","package":"peppy"},{"reason":"Data validation and settings management","package":"pydantic"},{"reason":"OAuth implementation for authentication","package":"oauthlib"},{"reason":"OAuth client for Requests","package":"requests-oauthlib"},{"reason":"Rich text and beautiful formatting in the terminal","package":"rich"},{"reason":"JSON Object Signing and Encryption for JWT handling","package":"python-jose"},{"reason":"Yet another configuration manager","package":"yacman"}],"imports":[{"note":"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`.","wrong":"from pephubclient.client import PEPHubClient","symbol":"PEPHubClient","correct":"from pephubclient import PEPHubClient"}],"quickstart":{"code":"import os\nfrom pephubclient import PEPHubClient\n\n# Initialize the client. The default host is https://pephub.databio.org\nphc = PEPHubClient()\n\n# Retrieve a publicly accessible project from PEPhub.\n# 'test/test_project:test' is a common example project for testing.\ntry:\n    project = phc.get_project(namespace='test', name='test_project', tag='test')\n    print(f\"Successfully retrieved project: {project.name}\")\n    print(f\"Project description: {project.description}\")\n    print(f\"Number of samples: {len(project.samples)}\")\nexcept Exception as e:\n    print(f\"Error retrieving project 'test/test_project:test': {e}\")\n    print(\"This project might not exist or might require authentication. \")\n    print(\"For private projects, set the PH_KEY environment variable and \")\n    print(\"then call `phc.login(api_key=os.environ.get('PH_KEY'))` before fetching.\")\n","lang":"python","description":"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)."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to the latest version of `pephubclient` using `pip install --upgrade pephubclient`.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Trying to access a project that does not exist or whose namespace/name/tag combination is incorrect will result in a `ProjectNotFoundException`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to perform an authenticated action (e.g., list private projects, fetch a private project) without a valid API key or correct login.","error":"requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://pephub.databio.org/api/v1/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.","cause":"The specified project (namespace, name, and tag combination) does not exist on PEPhub or is not accessible to your user.","error":"pephubclient.exceptions.ProjectNotFoundException: Project 'your_namespace/your_project:your_tag' not found."},{"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).","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.","error":"ImportError: cannot import name 'PEPHubClient' from 'pephubclient' (<path_to_pephubclient/__init__.py>)"}]}