0
# Main Workflow and CLI
1

2
The main workflow module provides the primary entry point and command-line interface for uploading coverage results to coveralls.io. It orchestrates the complete process from argument parsing through data collection to API submission.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The primary function that coordinates the entire coverage upload workflow.
9

10
```python { .api }
11
def wear(args=None):
12
    """
13
    Main workflow function for uploading coverage to coveralls.io.
14
    
15
    Args:
16
        args (Arguments, optional): Parsed arguments object. If None, 
17
                                  arguments are parsed from command line.
18
    
19
    Returns:
20
        int: Exit code (0 for success, 1 for error)
21
    
22
    Process:
23
        1. Parse arguments and configuration
24
        2. Load coverage data using coverage.py
25
        3. Extract repository information (git/hg)
26
        4. Generate coveralls-formatted report
27
        5. Submit to coveralls.io API
28
        6. Return success/failure status
29
    """
30
```
31

32
### Argument Parsing
33

34
Parses command-line arguments and merges with configuration file settings.
35

36
```python { .api }
37
def parse_args():
38
    """
39
    Parse command-line arguments and configuration files.
40
    
41
    Returns:
42
        Arguments: Parsed arguments object with all configuration options
43
        
44
    Configuration Sources (in order of precedence):
45
        1. Command-line arguments
46
        2. .coveralls.yml file
47
        3. Environment variables
48
        4. Default values
49
    """
50
```
51

52
## Command-Line Interface
53

54
### Installation and Setup
55

56
```bash
57
pip install python-coveralls
58
```
59

60
### Basic Usage
61

62
```bash
63
# Upload coverage after running tests
64
coveralls
65

66
# Common CI workflow
67
python -m pytest --cov=mypackage
68
coveralls
69
```
70

71
### Command-Line Options
72

73
```bash
74
usage: coveralls [-h] [--coveralls_url COVERALLS_URL] [--base_dir BASE_DIR]
75
                 [--data_file DATA_FILE] [--config_file CONFIG_FILE]
76
                 [--coveralls_yaml COVERALLS_YAML] [--ignore-errors]
77
                 [--merge_file MERGE_FILE] [--nogit] [--skip_ssl_verify]
78
```
79

80
### Option Details
81

82
```python { .api }
83
# URL Configuration
84
--coveralls_url, -u: str  # coveralls.io API URL (default: 'https://coveralls.io/api/v1/jobs')
85

86
# File Paths
87
--base_dir, -b: str       # project root directory (default: '.')
88
--data_file, -d: str      # coverage file name (default: None - auto-detect)
89
--config_file, -c: str    # coverage config file name (default: None - auto-detect)
90
--coveralls_yaml, -y: str # coveralls yaml file name (default: '.coveralls.yml')
91
--merge_file, -m: str     # json file for merging JavaScript coverage (default: None)
92

93
# Behavior Options
94
--ignore-errors, -i: bool # ignore errors while reading source files (default: False)
95
--nogit: bool            # do not gather git repo info (default: False)
96
--skip_ssl_verify: bool  # skip SSL certificate verification (default: False)
97
```
98

99
## Configuration Integration
100

101
### YAML Configuration
102

103
```yaml
104
# .coveralls.yml
105
repo_token: "your_repository_token"
106
service_name: "travis-ci"  # or "travis-pro", "circle-ci", etc.
107
parallel: true            # for parallel CI builds
108
```
109

110
### Environment Variables
111

112
```python { .api }
113
# Authentication
114
COVERALLS_REPO_TOKEN: str     # Repository token (overrides yaml)
115

116
# CI Service Configuration
117
COVERALLS_SERVICE_NAME: str   # Service name (overrides yaml)
118
COVERALLS_PARALLEL: bool      # Parallel builds flag (overrides yaml)
119

120
# Travis CI Integration
121
TRAVIS_JOB_ID: str           # Automatically detected job ID
122
TRAVIS_BRANCH: str           # Automatically detected branch
123

124
# Circle CI Integration  
125
CIRCLE_BRANCH: str           # Automatically detected branch
126
```
127

128
## Usage Examples
129

130
### Basic CI Integration
131

132
```bash
133
# In .travis.yml after_success section
134
after_success:
135
  - coveralls
136

137
# In GitHub Actions
138
- name: Upload coverage to Coveralls
139
  run: coveralls
140
  env:
141
    COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
142
```
143

144
### Custom Configuration
145

146
```bash
147
# Specify custom paths and options
148
coveralls --base_dir /path/to/project \
149
          --data_file .coverage \
150
          --config_file .coveragerc \
151
          --ignore-errors
152

153
# Skip git info for Docker builds
154
coveralls --nogit
155

156
# Corporate environment with SSL issues
157
coveralls --skip_ssl_verify
158
```
159

160
### Merging JavaScript Coverage
161

162
```bash
163
# Generate JavaScript coverage in JSON format first
164
npm run test:coverage
165

166
# Merge with Python coverage
167
coveralls --merge_file coverage/coverage.json
168
```
169

170
## Package Metadata
171

172
```python { .api }
173
# Package metadata constants
174
__version__: str = "2.9.3"
175
__author__: str = "Andrea De Marco <24erre@gmail.com>"
176
__license__: str = "Apache License 2.0"
177
__classifiers__: list[str]  # Development status, audience, license, OS, Python versions
178
__copyright__: str = "2013, Andrea De Marco <24erre@gmail.com>"
179
__docformat__: str = "restructuredtext en"
180
```
181

182
## Error Handling
183

184
The main workflow handles various error conditions gracefully:
185

186
- **Missing coverage files**: Auto-detection with fallback to common locations
187
- **Source file read errors**: Optional with `--ignore-errors` flag
188
- **Network errors**: SSL verification bypass option
189
- **Repository detection**: Optional git/hg integration with `--nogit` flag
190
- **Configuration errors**: Graceful fallback to defaults