0
# Python Coveralls
1

2
A Python interface to the coveralls.io API for uploading code coverage results from Python projects. The library handles authentication, processes coverage data files, extracts git repository information, and uploads formatted coverage reports to coveralls.io with support for various coverage tools and CI services.
3

4
## Package Information
5

6
- **Package Name**: python-coveralls
7
- **Language**: Python
8
- **Installation**: `pip install python-coveralls`
9

10
## Core Imports
11

12
```python
13
import coveralls
14
```
15

16
For programmatic usage:
17

18
```python
19
from coveralls import api, control, repository
20
from coveralls.control import coveralls
21
from coveralls.api import post, build_file
22
from coveralls.repository import repo
23
```
24

25
## Basic Usage
26

27
### Command-Line Usage
28

29
The simplest way to upload coverage results after running your test suite:
30

31
```bash
32
# Run your tests with coverage
33
python -m pytest --cov=mypackage
34

35
# Upload to coveralls.io
36
coveralls
37
```
38

39
### Programmatic Usage
40

41
```python
42
import coveralls
43

44
# Upload coverage using the main workflow function
45
exit_code = coveralls.wear()
46

47
# Or with custom arguments
48
args = coveralls.parse_args()
49
args.base_dir = '/path/to/project'
50
args.repo_token = 'your_repo_token'
51
exit_code = coveralls.wear(args)
52
```
53

54
## Architecture
55

56
The package is organized into distinct functional modules:
57

58
- **Main Module** (`coveralls`): Entry point with command-line interface and main workflow coordination
59
- **Control Module** (`coveralls.control`): Coverage data processing and integration with coverage.py
60
- **Report Module** (`coveralls.report`): Coverage report generation in coveralls.io format
61
- **API Module** (`coveralls.api`): HTTP communication with coveralls.io API
62
- **Repository Module** (`coveralls.repository`): Git and Mercurial repository information extraction
63

64
## Capabilities
65

66
### Main Workflow and CLI
67

68
Primary entry point providing command-line interface and orchestrating the complete coverage upload workflow from data collection to API submission.
69

70
```python { .api }
71
def wear(args=None): ...
72
def parse_args(): ...
73
```
74

75
[Main Workflow](./main-workflow.md)
76

77
### Coverage Processing
78

79
Extended coverage functionality that integrates with coverage.py to generate coveralls-specific reports with line-by-line coverage data and source file information.
80

81
```python { .api }
82
class coveralls(Coverage):
83
    def coveralls(base_dir, ignore_errors=False, merge_file=None): ...
84

85
class CoverallsReporter(Reporter):
86
    def report(base_dir, ignore_errors=False, merge_file=None): ...
87
```
88

89
[Coverage Processing](./coverage-processing.md)
90

91
### API Communication
92

93
HTTP interface for communicating with the coveralls.io API, handling authentication, request formatting, and response processing.
94

95
```python { .api }
96
def post(url, repo_token, service_job_id, service_name, git, source_files, parallel, skip_ssl_verify=False): ...
97
def build_file(repo_token, service_job_id, service_name, git, source_files, parallel): ...
98
```
99

100
[API Communication](./api-communication.md)
101

102
### Repository Integration
103

104
Version control system integration for extracting git and mercurial repository information including commit details, branch information, and remote URLs.
105

106
```python { .api }
107
def repo(root): ...
108
def gitrepo(root): ...
109
def hgrepo(root): ...
110
```
111

112
[Repository Integration](./repository-integration.md)
113

114
## Configuration
115

116
### Environment Variables
117

118
```python { .api }
119
# Authentication
120
COVERALLS_REPO_TOKEN: str  # Repository token for authentication
121

122
# CI Service Integration  
123
COVERALLS_SERVICE_NAME: str  # CI service name (default: 'travis-ci')
124
COVERALLS_PARALLEL: bool    # Enable parallel builds
125
TRAVIS_JOB_ID: str         # Travis CI job identifier
126
TRAVIS_BRANCH: str         # Git branch from Travis CI
127
CIRCLE_BRANCH: str         # Git branch from Circle CI
128
```
129

130
### Configuration Files
131

132
The package supports YAML configuration files and coverage.py configuration:
133

134
```yaml
135
# .coveralls.yml
136
repo_token: "your_repo_token"
137
service_name: "travis-ci"
138
parallel: true
139
```
140

141
## Types
142

143
```python { .api }
144
class Arguments:
145
    """Parsed command-line arguments and configuration."""
146
    coveralls_url: str
147
    base_dir: str
148
    data_file: str | None
149
    config_file: str | None
150
    coveralls_yaml: str
151
    ignore_errors: bool
152
    merge_file: str | None
153
    nogit: bool
154
    skip_ssl_verify: bool
155
    repo_token: str
156
    service_name: str
157
    service_job_id: str
158
    parallel: bool
159

160
class GitInfo:
161
    """Git repository information."""
162
    head: dict[str, str]  # commit info (id, author_name, author_email, etc.)
163
    branch: str
164
    remotes: list[dict[str, str]]  # remote info (name, url)
165

166
class SourceFile:
167
    """Coverage information for a single source file."""
168
    name: str               # relative file path
169
    source: str             # file content
170
    coverage: list[int | None]  # line-by-line coverage (None=non-executable, 0=missed, 1=hit)
171
```