peppy

0.40.8 · active · verified Thu Apr 16

peppy is the official Python package for reading Portable Encapsulated Projects (PEPs). It provides a Python interface for managing project metadata, including samples and their attributes. The library facilitates loading, validating, and interacting with PEP-formatted metadata. The current stable version is 0.40.8, with significant breaking changes anticipated in the upcoming 0.50.0aX releases. It maintains an active development and release cadence.

Common errors

```
ModuleNotFoundError: No module named 'peppy'
```
cause The 'peppy' library is not installed in the current Python environment.

fix Install the library using pip: `pip install peppy`
```
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/project_config.yaml'
```
cause The configuration file specified during `Project` initialization either does not exist or the provided path is incorrect.

fix Verify that the `project_config.yaml` file exists at the specified path. Use an absolute path or ensure the relative path is correct from where your script is run. Consider cloning the `pepkit/example_peps` repository for test data.
```
AttributeError: 'Project' object has no attribute 'samples' (or similar errors when accessing project/sample data)
```
cause This often occurs if the project configuration (e.g., `sample_table.csv`) is empty, malformed, or if `defer_samples_creation=True` was used without subsequently creating samples.

fix Review your `project_config.yaml` and associated sample table(s) to ensure they correctly define samples. If you initialized with `defer_samples_creation=True`, call `prj.create_samples()` before attempting to access `prj.samples`.

Warnings

breaking Starting from version 0.50.0a1, functionality previously provided by external `pephubclient` and `eido` libraries has been merged directly into `peppy`. Code relying on direct imports or usage of these separate packages for PEP-related operations will break.
Fix: Review the `peppy` documentation for 0.50.0aX to understand how merged functionalities are accessed internally. Remove direct `pephubclient` and `eido` imports related to PEP processing.
breaking The command-line interface (CLI) in `peppy` has been completely revamped and switched to `typer` in version 0.50.0a1. Existing CLI commands will no longer work as before.
Fix: Consult the updated CLI documentation for version 0.50.0aX to learn the new command structure and usage with `typer`.
gotcha Project initialization (`peppy.Project(cfg=...)`) requires a correctly formatted PEP configuration file (typically YAML) that points to a sample table. Incorrect paths, malformed YAML, or missing files are common issues leading to errors.
Fix: Ensure the `cfg` path is absolute or correctly relative to the current working directory. Validate your YAML file for syntax errors and confirm that all referenced files (like `sample_table.csv`) exist and are accessible. Refer to the PEP specification for correct format.

Install

pip install peppy Install stable version

Imports

Project
```
from peppy import Project
```

Quickstart

Demonstrates how to initialize a `peppy.Project` object from a configuration file and access its samples and their attributes. Users should provide their own PEP configuration file.

import os
from peppy import Project

# For a runnable example, clone the example_peps repository:
# git clone https://github.com/pepkit/example_peps.git
# and adjust the path below to 'example_peps/example_basic/project_config.yaml'

# Placeholder for a project configuration file (YAML or CSV).
# In a real scenario, replace with the actual path to your PEP config.
project_path = os.environ.get('PEPPY_PROJECT_CONFIG', 'path/to/your/project_config.yaml')

try:
    # Instantiate an in-memory Project representation
    prj = Project(cfg=project_path)
    print(f"Successfully loaded Project: '{prj.name}'")
    print(f"Number of samples: {len(prj.samples)}")

    if prj.samples:
        first_sample = prj.samples[0]
        print(f"\nFirst sample name: {first_sample.sample_name}")
        # Access a sample attribute, e.g., 'protocol' or 'file'
        if 'protocol' in first_sample:
            print(f"First sample's protocol: {first_sample.protocol}")
    else:
        print("No samples found in the project.")

except FileNotFoundError:
    print(f"Error: Project configuration file not found at '{project_path}'.")
    print("Please ensure the path is correct or clone a PEP example.")
except Exception as e:
    print(f"An error occurred during project loading: {e}")

view raw JSON →