0
# Codecov Python Uploader
1

2
**⚠️ DEPRECATED:** This package has been deprecated by Codecov and will be completely removed. Users should migrate to the [new Codecov uploader](https://docs.codecov.com/docs/codecov-uploader).
3

4
A Python library and command-line tool for uploading code coverage reports to Codecov, a hosted service for tracking test coverage across multiple CI/CD platforms. The package automatically detects CI environments, processes various coverage report formats, and uploads compressed reports to Codecov with retry logic and comprehensive error handling.
5

6
## Package Information
7

8
- **Package Name**: codecov
9
- **Language**: Python
10
- **Installation**: `pip install codecov`
11
- **Dependencies**: requests>=2.7.9, coverage
12
- **License**: Apache 2.0
13
- **Version**: 2.1.13
14

15
## Core Imports
16

17
```python
18
import codecov
19
```
20

21
For direct function access:
22

23
```python
24
from codecov import main, write, read, try_to_run
25
```
26

27
For accessing version and metadata:
28

29
```python
30
from codecov import __version__, __author__, __url__
31
```
32

33
For accessing utility functions and constants:
34

35
```python
36
from codecov import find_files, generate_toc, COLOR, opj
37
```
38

39
## Basic Usage
40

41
### Command Line Usage
42

43
```bash
44
# Public repository (token auto-detected on supported CI platforms)
45
codecov
46

47
# Private repository with explicit token
48
codecov -t your-repository-upload-token
49

50
# Target specific coverage files
51
codecov -f coverage.xml -f coverage.txt
52

53
# Add custom flags for grouping reports
54
codecov -F unittests -F integration
55

56
# Include environment variables in report
57
codecov -e TOXENV -e PYTHON_VERSION
58

59
# Advanced usage examples
60
codecov --root /path/to/project --commit abc123 --branch main
61
codecov --disable search --disable gcov --verbose
62
codecov --url https://codecov.example.com --slug owner/repo
63
codecov --dump --verbose  # Debug mode without upload
64
```
65

66
## Command Line Interface Reference
67

68
The codecov CLI provides comprehensive upload configuration through command-line arguments organized in functional groups:
69

70
### Basic Options
71
- `--version`: Show version information
72
- `--token, -t TOKEN`: Repository upload token (default: $CODECOV_TOKEN)
73
- `--file, -f FILES`: Target specific coverage files (multiple allowed)
74
- `--flags, -F FLAGS`: Custom flags for report grouping (default: $CODECOV_FLAGS)
75
- `--env, -e VARS`: Environment variables to include (multiple allowed)
76
- `--required`: Exit with code 1 on upload failure
77
- `--name, -n NAME`: Custom upload name (default: $CODECOV_NAME)
78

79
### gcov Integration Options
80
- `--gcov-root ROOT`: Project root directory for gcov processing
81
- `--gcov-glob PATTERNS`: File patterns to ignore during gcov gathering
82
- `--gcov-exec EXECUTABLE`: gcov executable to use (default: 'gcov')
83
- `--no-gcov-out`: Disable gcov output
84
- `--gcov-args ARGS`: Additional arguments to pass to gcov
85

86
### Advanced Configuration
87
- `-X, --disable FEATURES`: Disable features (search, detect, gcov, pycov, fix, s3)
88
- `--root ROOT`: Override project directory detection
89
- `--commit, -c SHA`: Specify commit SHA manually
90
- `--prefix, -P PREFIX`: Network path prefix for path resolution
91
- `--branch, -b BRANCH`: Specify branch name manually
92
- `--build BUILD`: Custom build number
93
- `--pr PR`: Pull request number
94
- `--tag TAG`: Git tag for the build
95
- `--tries ATTEMPTS`: Number of upload retry attempts (default: 5)
96

97
### Enterprise/Self-hosted Options
98
- `--slug, -r SLUG`: Repository slug format owner/repo (default: $CODECOV_SLUG)
99
- `--url, -u URL`: Codecov endpoint URL (default: $CODECOV_URL or https://codecov.io)
100
- `--cacert BUNDLE`: Certificate bundle for HTTPS verification (default: $CODECOV_CACERT)
101

102
### Debugging Options
103
- `--dump`: Display collected data without uploading
104
- `-v, --verbose`: Enable verbose output
105
- `--no-color`: Disable colored terminal output
106

107
### Programmatic Usage
108

109
```python
110
import codecov
111

112
# Basic programmatic upload with default settings
113
codecov.main()
114

115
# Upload with custom arguments (equivalent to CLI usage)
116
codecov.main(['-t', 'token', '-f', 'coverage.xml'])
117

118
# Debug mode returns detailed information
119
result = codecov.main(debug=True)
120
print(result['query'])  # Upload parameters
121
print(result['reports'])  # Collected coverage data
122
```
123

124
## Capabilities
125

126
### Main Entry Point
127

128
Primary function for uploading coverage reports to Codecov with comprehensive CI detection and error handling.
129

130
```python { .api }
131
def main(*argv, **kwargs):
132
    """
133
    Main entry point for codecov functionality.
134
    
135
    Parameters:
136
    - *argv: Command line arguments (list of strings)
137
    - **kwargs: Additional options including 'debug' flag
138
    
139
    Returns:
140
    - None: Normal execution (uploads to Codecov)
141
    - dict: Debug information when debug=True in kwargs, containing:
142
        - reports: collected coverage data
143
        - codecov: parsed command line arguments  
144
        - query: upload parameters dict
145
        - urlargs: URL arguments for upload
146
        - result: HTTP response from upload
147
    
148
    Raises:
149
    - SystemExit: On critical errors or when --required flag fails
150
    - Exception: Re-raised when debug=True in kwargs
151
    """
152
```
153

154
### Console Output
155

156
Formatted output with color support for terminal display.
157

158
```python { .api }
159
def write(text, color=None):
160
    """
161
    Output text with optional color formatting.
162
    
163
    Parameters:
164
    - text (str): Text to output to stdout
165
    - color (str): Optional color ('red', 'green', or None)
166
    
167
    Returns:
168
    - None
169
    """
170
```
171

172
### File Operations
173

174
Safe file reading with encoding detection and error handling.
175

176
```python { .api }
177
def fopen(path):
178
    """
179
    Safely open and read file contents with encoding handling.
180
    
181
    Parameters:
182
    - path (str): File path to read
183
    
184
    Returns:
185
    - str: File contents or None on error
186
    """
187

188
def read(filepath):
189
    """
190
    Read coverage report file and format with path header.
191
    
192
    Parameters:
193
    - filepath (str): Path to coverage report file
194
    
195
    Returns:
196
    - str: Formatted coverage report with '# path=filepath' header
197
    """
198
```
199

200
### Command Execution
201

202
Execute system commands with error handling and output capture.
203

204
```python { .api }
205
def check_output(cmd, **popen_args):
206
    """
207
    Execute command and return output, raising CalledProcessError on failure.
208
    
209
    Parameters:
210
    - cmd (list): Command and arguments to execute
211
    - **popen_args: Additional arguments for subprocess.Popen
212
    
213
    Returns:
214
    - str: Command output decoded as UTF-8
215
    
216
    Raises:
217
    - CalledProcessError: When command returns non-zero exit code
218
    """
219

220
def try_to_run(cmd, shell=False, cwd=None):
221
    """
222
    Attempt to run command with graceful error handling.
223
    
224
    Parameters:
225
    - cmd (list): Command and arguments to execute
226
    - shell (bool): Whether to use shell execution (default: False)
227
    - cwd (str): Working directory for command execution
228
    
229
    Returns:
230
    - str: Command output or None on failure
231
    """
232
```
233

234
### Coverage Tool Integration
235

236
Execute Python coverage tool using importable module or PATH lookup.
237

238
```python { .api }
239
def run_python_coverage(args):
240
    """
241
    Run Python coverage tool using module import or PATH.
242
    
243
    Parameters:
244
    - args (list): Arguments to pass to coverage command
245
    
246
    Returns:
247
    - None
248
    """
249
```
250

251
### File Discovery
252

253
Find files matching patterns with directory exclusion support.
254

255
```python { .api }
256
def find_files(directory, patterns, recursive=True, exclude_dirs=[]):
257
    """
258
    Find files matching patterns in directory tree.
259
    
260
    Parameters:
261
    - directory (str): Directory to search
262
    - patterns (str or list): File patterns to match (glob style)
263
    - recursive (bool): Whether to search recursively (default: True)
264
    - exclude_dirs (list): Directory names to exclude from search
265
    
266
    Returns:
267
    - generator: Yields matching file paths as strings
268
    """
269
```
270

271
### Repository Analysis
272

273
Generate file listings from version control systems.
274

275
```python { .api }
276
def generate_toc(root):
277
    """
278
    Generate table of contents from git/hg file listings.
279
    
280
    Parameters:
281
    - root (str): Repository root directory path
282
    
283
    Returns:
284
    - str: Newline-separated list of tracked files
285
    """
286
```
287

288
### HTTP Upload with Retry
289

290
Robust HTTP upload with exponential backoff retry logic.
291

292
```python { .api }
293
def retry_upload(url, request_method, retries=5, break_codes=(200,), **kwargs):
294
    """
295
    Retry HTTP upload with backoff on failure.
296
    
297
    Parameters:
298
    - url (str): URL to upload to
299
    - request_method (callable): HTTP method function (requests.post, etc.)
300
    - retries (int): Maximum number of retry attempts (default: 5)
301
    - break_codes (tuple): HTTP status codes indicating success (default: (200,))
302
    - **kwargs: Additional arguments for request method
303
    
304
    Returns:
305
    - requests.Response: Final response object
306
    """
307
```
308

309
### Data Processing
310

311
Data sanitization and encoding utilities.
312

313
```python { .api }
314
def sanitize_arg(replacement, arg):
315
    """
316
    Sanitize command line arguments by replacing ampersands.
317
    
318
    Parameters:
319
    - replacement (str): String to replace ampersands with
320
    - arg (str): Argument to sanitize
321
    
322
    Returns:
323
    - str: Sanitized argument string
324
    """
325

326
def remove_non_ascii(data):
327
    """
328
    Remove non-ASCII characters from data.
329
    
330
    Parameters:
331
    - data (bytes or str): Input data to clean
332
    
333
    Returns:
334
    - str: ASCII-only string
335
    """
336
```
337

338
### Internal Utilities
339

340
Internal helper functions that are technically accessible but intended for internal use.
341

342
```python { .api }
343
def _add_env_if_not_empty(lst, value):
344
    """
345
    Add environment variable to set if value is not empty.
346
    
347
    Parameters:
348
    - lst (set): Set of environment variable names to add to
349
    - value (str): Environment variable name to potentially add
350
    
351
    Returns:
352
    - None: Modifies lst in place
353
    """
354
```
355

356
## Constants and Global Variables
357

358
### Package Metadata
359

360
```python { .api }
361
# Version information
362
version: str = "2.1.13"
363
__version__: str = "2.1.13"
364

365
# Package metadata (from codecov.__version__)
366
__author__: str = "Codecov"
367
__author_email__: str = "support@codecov.io"
368
__copyright__: str = "Copyright 2020 Codecov"
369
__license__: str = "Apache 2.0"
370
__title__: str = "codecov"
371
__url__: str = "https://github.com/codecov/codecov-python"
372
```
373

374
### Configuration
375

376
```python { .api }
377
# Global color output control
378
COLOR: bool = True
379
```
380

381
### Pattern Matching
382

383
```python { .api }
384
# Compiled regex patterns for file and path filtering
385
is_merge_commit: re.Pattern  # Detect git merge commits: r"^Merge\s\w{40}\sinto\s\w{40}$"
386
ignored_path: re.Pattern     # Paths to ignore during coverage collection: /vendor, /__pycache__, /node_modules, etc.
387
ignored_report: re.Pattern   # Files to ignore as coverage reports: .coverage, .pyc, .js, .html, etc.
388
is_report: re.Pattern        # Files that are coverage reports: coverage*, .gcov, .lcov, jacoco*.xml, etc.
389
remove_token: function       # Function to sanitize tokens from URLs: removes r"token=[^\&]+" patterns
390
```
391

392
### Utility Aliases
393

394
```python { .api }
395
# Platform-dependent utilities
396
quote: function              # Shell argument quoting (platform-specific: shlex.quote, pipes.quote, or subprocess.list2cmdline)
397
opj: function               # Alias for os.path.join for performance
398
```
399

400
## CI Provider Support
401

402
The package automatically detects and integrates with 15+ CI providers:
403

404
- **Travis CI**: Comprehensive integration with build matrix support
405
- **CircleCI**: Full build and workflow detection
406
- **Jenkins**: GitHub pull request builder plugin support
407
- **GitHub Actions**: Native workflow and PR detection
408
- **GitLab CI**: Pipeline and merge request support
409
- **AppVeyor**: Windows build environment support
410
- **Buildkite**: Pipeline and job detection
411
- **Codeship**: Build number and URL tracking
412
- **Drone.io**: Build directory and link support
413
- **Shippable**: Pull request and branch detection
414
- **Semaphore**: Thread-aware build tracking
415
- **TeamCity**: Version and build number detection
416
- **Wercker**: Git integration and build tracking
417
- **Greenhouse**: Pull request and build URL support
418
- **Cirrus CI**: Task and build URL generation
419
- **Magnum**: Branch and commit detection
420

421
Each provider is automatically detected through environment variables, with fallback to manual configuration.
422

423
## Coverage Report Formats
424

425
Automatically detects and processes multiple coverage formats:
426

427
- **Python**: coverage.py XML output, .coverage files
428
- **gcov**: GNU coverage format (.gcov files)
429
- **LCOV**: lcov.info format
430
- **Clover**: clover.xml format (Java, C#)
431
- **Cobertura**: cobertura.xml format
432
- **Jacoco**: jacoco.xml format (Java)
433
- **JavaScript**: coverage-final.json, coverage-summary.json
434

435
## Error Handling
436

437
The package includes comprehensive error handling:
438

439
- **Missing Reports**: Assertion error when no coverage reports found
440
- **CI Detection Failures**: Graceful fallback to manual configuration
441
- **Upload Failures**: Automatic retry with exponential backoff
442
- **File Reading Errors**: Individual file failures don't stop execution
443
- **Network Issues**: S3 upload fallback to direct HTTP endpoint
444

445
## Environment Variables
446

447
Key environment variables for configuration:
448

449
- `CODECOV_TOKEN`: Repository upload token
450
- `CODECOV_FLAGS`: Comma-separated flags for report grouping
451
- `CODECOV_ENV`: Environment variables to include in report
452
- `CODECOV_NAME`: Custom name for upload
453
- `CODECOV_SLUG`: Repository slug (owner/repo)
454
- `CODECOV_URL`: Custom Codecov endpoint URL
455

456
## Migration Notice
457

458
This package is deprecated and scheduled for removal. Users should migrate to the new Codecov uploader:
459

460
- **Migration Guide**: https://docs.codecov.com/docs/deprecated-uploader-migration-guide#python-uploader
461
- **New Uploader**: https://docs.codecov.com/docs/codecov-uploader
462
- **Open Source**: https://github.com/codecov/uploader
463

464
The deprecated package will stop working on February 1, 2022 and beyond.