Pyroma

Warnings

• breaking In Pyroma v5.0.0, the programmatic API (`run_pyroma`) and the command-line interface (CLI) shifted to operate on a *directory path* rather than directly on a `setup.py` file. Calls explicitly passing a `setup.py` file path will no longer work.
  Fix: Update your code to pass the project's root directory: `pyroma.ratings.run_pyroma('/path/to/project_root')`. For the CLI, use `pyroma /path/to/project_root` or simply `pyroma .` from within the project's root.
• breaking Pyroma v5.0.0 raised the minimum required Python version to 3.9. Projects attempting to use Pyroma on older Python runtimes will encounter an `ImportError` or installation failure.
  Fix: Ensure your environment uses Python 3.9 or newer. If you must use an older Python version, pin Pyroma to a compatible version, e.g., `pyroma<5.0.0`.
• gotcha Pyroma assesses a project's 'packaging friendliness' based on its metadata and structure, not the functional correctness or code quality of the Python application itself. A project can be fully functional but receive a low Pyroma score if its packaging configuration is non-standard or incomplete.
  Fix: Understand Pyroma's scope as a packaging linter. Focus on addressing specific warnings related to `setup.py`, `pyproject.toml`, `README`, and package structure to improve its distribution readiness, rather than expecting it to validate application logic.
• gotcha When using Pyroma via the CLI, ensure you are in the project's root directory or explicitly specify the project's root. If run without arguments from a non-project directory, it will attempt to analyze the current directory and might report 'No setup.py or pyproject.toml found' errors.
  Fix: Always execute `pyroma .` from your project's root directory, or provide the full path to the root: `pyroma /path/to/my/project`.

Install

• pip install pyroma Install Pyroma

Imports

• run_pyroma
  wrong:

  import pyroma; pyroma.run_pyroma(...)

  correct:

  from pyroma import ratings; ratings.run_pyroma

  In Pyroma v5.0.0, the `run_pyroma` function was moved from the top-level `pyroma` module to `pyroma.ratings.run_pyroma`. Direct import from `pyroma` will raise an `AttributeError`.

Quickstart

This quickstart demonstrates how to programmatically use Pyroma. It creates a temporary, minimal Python project directory, runs `pyroma.ratings.run_pyroma` on it, prints the score and any messages, and then cleans up the temporary files. This pattern is useful for integrating Pyroma checks into custom scripts or CI/CD pipelines.

import os
import shutil
from pathlib import Path
from pyroma import ratings

# Create a dummy project directory for testing
project_root = Path("temp_pyroma_project")
project_root.mkdir(exist_ok=True)

# Create a minimal setup.py, README.md, and __init__.py
(project_root / "setup.py").write_text(
    "from setuptools import setup; setup(name='dummy', version='0.1.0', description='A dummy project for pyroma test', packages=['dummy_pkg'])"
)
(project_root / "README.md").write_text("# Dummy Project\n\nThis is a temporary project for pyroma testing.")
(project_root / "dummy_pkg").mkdir(exist_ok=True)
(project_root / "dummy_pkg" / "__init__.py").touch() 

# Run pyroma on the dummy project
print(f"Running pyroma on: {project_root.resolve()}")
score, messages = ratings.run_pyroma(project_root)

print(f"\nPyroma Score: {score}/10")
print("Messages:")
if messages:
    for message in messages:
        print(f"- {message}")
else:
    print("No messages (perfect score).")

# Clean up the dummy project
if project_root.exists():
    shutil.rmtree(project_root)
    print(f"\nCleaned up {project_root}")