https://img.shields.io/pypi/v/pycomex.svg

☄️ PyComex - Python Computational Experiments

Microframework to improve the experience of running and managing archival records of computational experiments, such as machine learning and data science experiments, in Python.

🔥 Features

Automatically create (nested) folder structure for results of each run of an experiment
Simply attach metadata such as performance metrics to experiment object and they will be automatically stored as JSON file
Easily attach file artifacts such as matplotlib figures to experiment records
Log messages to stdout as well as permanently store into log file
Ready-to-use automatically generated boilerplate code for the analysis and post-processing of experiment data after experiments have terminated.
Experiment inheritance: Experiment modules can inherit from other modules and extend their functionality via parameter overwrites and hooks!
Configuration files: Create YAML config files to run parameter variations without duplicating code
Built-in hyperparameter optimization with Optuna integration (available with full installation)

📦 Installation by Package

Install the stable version with pip

pip3 install pycomex

📦 Installation by Source

Or the most recent development version by cloning the source:

git clone https://github.com/the16thpythonist/pycomex.git

and then installing with either pip

cd pycomex
pip3 install -e .

or poetry

cd pycomex
poetry install

🚀 Quickstart

Each computational experiment has to be bundled as a standalone python module. Important experiment parameters are placed at the top of this module. All variable names written in upper case will automatically be detected as parameters of the experiment.

The actual implementation of the experiment execution is placed into a single file which will have to be decorated with the Experiment decorator.

Upon execution the experiment, a new archive folder is automatically created. This archive folder can be used to store all the file artifacts that are created during the experiment. Some artifacts are stored automatically by default, such as a JSON file containing all data stored in the main experiment storage, a snapshot of the experiment module and more…

Archiving of metadata, file artifacts and error handling is automatically managed on context exit.

# my_experiment.py
"""
A minimal example demonstrating PyComex experiment structure.
This docstring is saved as experiment metadata.
"""
from pycomex.functional.experiment import Experiment
from pycomex.utils import file_namespace, folder_path

# Experiment parameters (uppercase variables are auto-detected)
MESSAGE: str = "Hello PyComex!"
ITERATIONS: int = 5

# Debug mode: reuses same archive folder for development
__DEBUG__ = True

@Experiment(
    base_path=folder_path(__file__),     # Results stored relative to this file
    namespace=file_namespace(__file__),  # Creates folder based on filename
    glob=globals(),                      # Provides access to parameters
)
def experiment(e: Experiment) -> None:
    e.log("Starting experiment...")

    # Store structured data (creates nested JSON structure)
    e["config/message"] = MESSAGE
    e["config/iterations"] = ITERATIONS

    # Run experiment loop
    for i in range(ITERATIONS):
        metric = i * 0.1
        e.track("metrics/value", metric)  # Track time-series data
        e.log(f"Iteration {i}: {MESSAGE} (metric: {metric})")

    # Save final results and artifacts
    e["results/final_metric"] = metric
    e.commit_raw("results.txt", f"Final result: {metric}")

# Run experiment when executed directly
experiment.run_if_main()

Running the Experiment:

# print help
python my_experiment.py --help

# Basic execution
python my_experiment.py

# Override parameters via command line
python my_experiment.py --MESSAGE "Custom message!" --ITERATIONS 10

This example would create the following folder structure:

my_experiment/
└── debug/
    ├── experiment_out.log      # Complete execution log
    ├── experiment_meta.json    # Experiment metadata and parameters
    ├── experiment_data.json    # All tracked data and stored values
    ├── experiment_code.py      # Snapshot of the original experiment code
    ├── results.txt            # Custom artifact saved via commit_raw()
    └── .track/                # Time-series visualizations
        └── metrics_value_001.png  # Auto-generated plot of tracked metrics

Key Features:

Automatic Archiving: Each experiment run creates a timestamped folder with complete execution records
Parameter Management: Uppercase variables are automatically detected as configurable parameters
Command-line Overrides: Parameters can be modified without editing code
Structured Data Storage: Nested data organization using path-like keys (e.g., "config/learning_rate")
Time-series Tracking: Built-in support for tracking metrics over time with automatic visualization
Artifact Management: Easy saving of files, figures, and custom data formats

🔧 Command Line Interface

PyComex provides a powerful CLI accessible via the pycomex command:

Creating New Experiments:

# Create a new experiment module from template
pycomex template experiment my_new_experiment.py

# Create a configuration file from an existing experiment
pycomex template config -e experiment.py -n config_name

Running Experiments:

# Run an experiment directly
pycomex run experiment.py

# Run a configuration file
pycomex run config.yml

Managing Experiment Archives:

# List recent experiments
pycomex archive list

# Show detailed information about an experiment
pycomex archive overview

# Compress and archive old experiments
pycomex archive compress results/

For more command line options use pycomex --help.

NOTE. For an introduction to more advanced features take a look at the examples in pycomex/examples ( https://github.com/the16thpythonist/pycomex/tree/master/pycomex/examples )

📖 Documentation

Complete documentation is available at: https://the16thpythonist.github.io/pycomex/

Additional details on specific topics can be found in the DOCUMENTATION.rst file.

The pycomex/examples ( https://github.com/the16thpythonist/pycomex/tree/master/pycomex/examples ) folder contains practical example modules that illustrate key features of the framework.

🤝 Credits

PyComex is built on top of these excellent open source libraries:

Click - Command line interface toolkit
Rich - Rich text and beautiful formatting in the terminal
Jinja2 - Modern and designer-friendly templating language
NumPy - The fundamental package for scientific computing
Matplotlib - Comprehensive 2D plotting library
pytest - Testing framework

Metadata

Release files for pycomex 0.29.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pycomex 0.29.0
File	Size	Uploaded	Provenance
pycomex-0.29.0.tar.gz	314.1 kB	Jul 21, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pycomex 0.29.0
File	Interpreter	ABI	Platform	Reset
pycomex-0.29.0-py3-none-any.whl 192.5 kB Jul 21, 2026 Without provenance	Python 3	none	any	Details

Total release size: 506.6 kB

Release files / pycomex-0.29.0.tar.gz

Download URL	pycomex-0.29.0.tar.gz
Size	314.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`d80a0a9d0e8b55b992094753629d833b2ce821478eb2b0bd4cb77da2a6fb6d8a`
BLAKE2b-256 checksum How to use checksums	`3cc467d440524101c4fdca041aca8fc989f4bab3e9961a1b04867892f08ac63c`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.4.30`

Release files / pycomex-0.29.0-py3-none-any.whl

Download URL	pycomex-0.29.0-py3-none-any.whl
Size	192.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`aac8767c8eb96fc5ec4c147ed1cf3d8351b9161e6054cf144965631de6d10fae`
BLAKE2b-256 checksum How to use checksums	`288e0eb49b4ba7e234868e7a80c7aba76474062365822672fcd1189de7cecac9`
Upload date	Jul 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.4.30`

Security for pycomex 0.29.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.