0
# Pyroma
1

2
A Python packaging quality assessment tool that evaluates how well Python projects comply with best practices of the Python packaging ecosystem, primarily PyPI, pip, and setuptools. It provides ratings and detailed feedback on project metadata quality, helping developers create more professional and usable packages.
3

4
## Package Information
5

6
- **Package Name**: pyroma
7
- **Language**: Python
8
- **Installation**: `pip install pyroma`
9
- **Python Requires**: >=3.9
10

11
## Core Imports
12

13
```python
14
import pyroma
15
```
16

17
For running the analysis programmatically:
18

19
```python
20
from pyroma import run
21
from pyroma.ratings import rate
22
```
23

24
For data extraction modules:
25

26
```python
27
from pyroma import projectdata, distributiondata, pypidata
28
```
29

30
## Basic Usage
31

32
### Command Line Usage
33

34
```bash
35
# Analyze a project directory
36
pyroma .
37

38
# Analyze a distribution file  
39
pyroma my-package-1.0.tar.gz
40

41
# Analyze a PyPI package
42
pyroma requests
43

44
# Set minimum rating for clean exit
45
pyroma --min 8 .
46

47
# Skip specific tests
48
pyroma --skip-tests "BusFactor,SDist" .
49

50
# Quiet mode (only show rating)
51
pyroma --quiet .
52
```
53

54
### Programmatic Usage
55

56
```python
57
import pyroma
58
from pyroma.ratings import rate
59

60
# Run analysis on a directory
61
rating = pyroma.run('directory', '/path/to/project')
62
print(f"Rating: {rating}/10")
63

64
# Get detailed analysis with failures
65
from pyroma.projectdata import get_data
66
from pyroma.ratings import rate
67

68
data = get_data('/path/to/project')
69
rating, failures = rate(data)
70
print(f"Rating: {rating}/10")
71
for failure in failures:
72
    print(f"- {failure}")
73
```
74

75
## Architecture
76

77
Pyroma follows a modular architecture with clear separation of concerns:
78

79
- **Analysis Engine**: Core rating system with pluggable tests
80
- **Data Extractors**: Specialized modules for different source types (projects, distributions, PyPI)
81
- **Rating System**: Comprehensive test suite evaluating packaging best practices
82
- **CLI Interface**: Command-line tool with flexible analysis modes
83

84
The tool supports three analysis modes: directory analysis for local projects, file analysis for distribution packages, and PyPI analysis for published packages, with automatic mode detection for user convenience.
85

86
## Capabilities
87

88
### Core Analysis Functions
89

90
Main functions for running pyroma analysis programmatically. These functions provide the primary interface for integrating pyroma into development workflows and automation scripts.
91

92
```python { .api }
93
def main(): ...
94
def run(mode: str, argument: str, quiet: bool = False, skip_tests: list = None) -> int: ...
95
def zester(data: dict): ...
96
```
97

98
[Core Analysis](./core-analysis.md)
99

100
### Data Extraction
101

102
Functions for extracting package metadata from different sources including project directories, distribution files, and PyPI packages. These modules handle the complexities of parsing various packaging formats and configurations.
103

104
```python { .api }
105
# Project data extraction
106
def get_data(path: str) -> dict: ...
107
def build_metadata(path: str, isolated: bool = None): ...
108

109
# Distribution file data extraction  
110
def get_data(path: str) -> dict: ...
111

112
# PyPI data extraction
113
def get_data(project: str) -> dict: ...
114
```
115

116
[Data Extraction](./data-extraction.md)
117

118
### Rating System
119

120
Comprehensive quality assessment system with pluggable tests that evaluate various aspects of Python packaging best practices. The rating system provides detailed feedback and actionable recommendations.
121

122
```python { .api }
123
def rate(data: dict, skip_tests: list = None) -> tuple: ...
124
def get_all_tests() -> list: ...
125
def get_code_licenses() -> dict: ...
126
```
127

128
[Rating System](./rating-system.md)