preservationeval 1.2.2

A Python implementation of the calculations and evaluations done by the Dew Point Calculator found at https://www.dpcalc.org/.

preservationeval

A Python implementation of the calculations and evaluations done by the Dew Point Calculator found at https://www.dpcalc.org/.

Details

This project is a Python implementation of the Dew Point Calculator created by the Image Permanence Institute. The original lookup tables from their published JavaScript are not redistributed. Instead, during installation, dp.js is downloaded, its integrity is verified via a pinned SHA-256 hash, and the table data is extracted by executing the JavaScript in an embedded V8 engine (PyMiniRacer) and converted into a Python module.

Installation

pip install preservationeval

Usage

Basic Examples

from preservationeval import pi, emc, mold

# Calculate Preservation Index
pi_value = pi(20, 50)  # temperature=20°C, RH=50%
print(f"Preservation Index: {pi_value}")

# Calculate EMC (Equilibrium Moisture Content)
emc_value = emc(20, 50)
print(f"EMC: {emc_value}%")

# Calculate Mold Risk
mold_risk = mold(20, 50)
print(f"Mold Risk: {mold_risk}")

Evaluating Conditions

The package also provides functions to rate environmental conditions:

from preservationeval import (
    pi, mold, rate_natural_aging, rate_mold_growth, EnvironmentalRating
)

# Rate preservation conditions (returns GOOD, OK, or RISK)
aging_risk = rate_natural_aging(pi(20, 50))
print(f"Natural aging: {aging_risk}")  # EnvironmentalRating.GOOD

mold_risk = rate_mold_growth(mold(20, 50))
print(f"Mold risk: {mold_risk}")  # EnvironmentalRating.GOOD

Interpreting Results

For details of how to use, see:

• http://www.dpcalc.org/howtouse_step2.php
• https://s3.cad.rit.edu/ipi-assets/publications/understanding_preservation_metrics.pdf

Development

Setup

# Clone the repository
git clone https://github.com/petter-b/preservationeval
cd preservationeval

# Install development dependencies
uv sync --extra dev

Development Tools

• ruff: Code formatting, linting and code quality
• mypy: Static type checking
• pytest: Testing framework
• pre-commit: Git hooks for code quality

Common Tasks

# Format code
uv run ruff format .

# Run linter
uv run ruff check .

# Type checking
uv run mypy .

# Run tests with coverage
uv run pytest --cov

Testing

Validation Testing

The package includes a validation framework that compares the Python implementation against the original JavaScript implementation from dpcalc.org.

Requirements

• Node.js and npm must be installed (download)
• Python test dependencies: uv sync --extra test

Test Data Setup

The test framework automatically:

• Creates the tests/data directory (git-ignored)
• Downloads the JavaScript reference implementation
• Generates and saves test cases
• Caches results for future test runs

You can manually trigger this setup:

# Download JavaScript reference implementation
# This happens automatically when running tests, or manually:
uv run python -m tests.validate_core

# Run all tests
uv run pytest

# Run only validation tests
uv run pytest tests/test_validation.py

# Run with verbose output
uv run pytest -v tests/test_validation.py

# Generate new test cases (ignore cached)
uv run pytest tests/test_validation.py --force-update

Code Quality

Automation

Releasing

Releases are triggered through the python-cicd.yml workflow. There are two methods:

1. PR label — add one of these labels to a pull request: release-candidate, release-patch, release-minor, release-major
2. Manual dispatch — trigger from the Actions tab and select a release type

Release type	Version bump	Target
release-candidate	X.Y.ZrcN	TestPyPI
release-patch	X.Y.Z+1	PyPI
release-minor	X.Y+1.0	PyPI
release-major	X+1.0.0	PyPI

Production releases (patch/minor/major) require the [Unreleased] section in CHANGELOG.md to have entries. The workflow creates a git tag, publishes the sdist to PyPI, and creates a GitHub Release.

Development Notes

This project was developed with assistance from Claude AI (Anthropic) and to some extent Codeium and GitHub Copilot. All code has been validated and tested for accuracy.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for all changes and versioning details.