0
# Development Tools
1

2
Command-line interface and utilities for IDE integration, type checking configuration, and development workflow support with mypy and Pyright. These tools help developers configure their development environment to work effectively with QtPy's binding abstraction.
3

4
## Capabilities
5

6
### Version Information
7

8
Access to QtPy version information for development and debugging.
9

10
```python { .api }
11
def print_version() -> None:
12
    """Print the current version of QtPy package to stdout."""
13
```
14

15
Usage example:
16

17
```python
18
from qtpy.cli import print_version
19

20
print_version()  # Output: QtPy version 2.4.3
21
```
22

23
### API Status Functions
24

25
Functions to determine which Qt binding is currently active and available.
26

27
```python { .api }
28
def get_api_status() -> dict[str, bool]:
29
    """
30
    Get the status of each Qt API usage.
31
    
32
    Returns:
33
        dict[str, bool]: Mapping of API names to boolean indicating if active
34
                        Keys: 'pyqt5', 'pyside2', 'pyqt6', 'pyside6' 
35
                        Values: True if currently active, False otherwise
36
    """
37
```
38

39
Usage example:
40

41
```python
42
from qtpy.cli import get_api_status
43

44
status = get_api_status()
45
print(status)  # {'pyqt5': True, 'pyside2': False, 'pyqt6': False, 'pyside6': False}
46

47
# Check which binding is active
48
active_binding = [name for name, active in status.items() if active][0]
49
print(f"Currently using: {active_binding}")
50
```
51

52
### MyPy Integration
53

54
Generate command-line arguments for using mypy with QtPy to enable proper type checking.
55

56
```python { .api }
57
def generate_mypy_args() -> str:
58
    """
59
    Generate mypy command line arguments for QtPy.
60
    
61
    Generates strings like:
62
    "--always-false=PYQT5 --always-false=PYQT6 --always-true=PYSIDE2 --always-false=PYSIDE6"
63
    
64
    This helps guide mypy through which library QtPy would have used
65
    so that mypy can get the proper underlying type hints.
66
    
67
    Returns:
68
        str: Space-separated mypy arguments for current binding
69
    """
70

71
def print_mypy_args() -> None:
72
    """Print generated mypy args to stdout."""
73
```
74

75
Usage example:
76

77
```python
78
from qtpy.cli import generate_mypy_args, print_mypy_args
79

80
# Get mypy args as string
81
args = generate_mypy_args()
82
print(args)  # "--always-false=PYQT5 --always-false=PYQT6 --always-true=PYSIDE2 --always-false=PYSIDE6"
83

84
# Print directly
85
print_mypy_args()
86
```
87

88
Command line usage:
89

90
```bash
91
# Use in shell command
92
mypy --package mypackage $(qtpy mypy-args)
93

94
# Or get the args directly
95
qtpy mypy-args
96
```
97

98
### Pyright Configuration
99

100
Generate Pyright configuration for type checking with QtPy in various formats.
101

102
```python { .api }
103
def generate_pyright_config_json() -> str:
104
    """
105
    Generate Pyright config JSON for pyrightconfig.json.
106
    
107
    Returns:
108
        str: JSON string with defineConstant configuration
109
    """
110

111
def generate_pyright_config_toml() -> str:
112
    """
113
    Generate Pyright config TOML for pyproject.toml.
114
    
115
    Returns:
116
        str: TOML format configuration section
117
    """
118

119
def print_pyright_config_json() -> None:
120
    """Print generated Pyright JSON config to stdout."""
121

122
def print_pyright_config_toml() -> None:
123
    """Print generated Pyright TOML config to stdout."""
124

125
def print_pyright_configs() -> None:
126
    """Print both Pyright config formats to stdout."""
127
```
128

129
Usage example:
130

131
```python
132
from qtpy.cli import (
133
    generate_pyright_config_json, 
134
    generate_pyright_config_toml,
135
    print_pyright_configs
136
)
137

138
# Generate JSON config
139
json_config = generate_pyright_config_json()
140
print(json_config)
141
# Output: {"defineConstant": {"PYQT5": false, "PYSIDE2": true, "PYQT6": false, "PYSIDE6": false}}
142

143
# Generate TOML config  
144
toml_config = generate_pyright_config_toml()
145
print(toml_config)
146
# Output:
147
# [tool.pyright.defineConstant]
148
# PYQT5 = false
149
# PYSIDE2 = true
150
# PYQT6 = false
151
# PYSIDE6 = false
152

153
# Print both formats
154
print_pyright_configs()
155
```
156

157
Command line usage:
158

159
```bash
160
# Generate Pyright configuration
161
qtpy pyright-config
162
```
163

164
### CLI Parser Functions
165

166
Functions for creating and managing the command-line interface.
167

168
```python { .api }
169
def generate_arg_parser():
170
    """
171
    Generate the argument parser for the dev CLI for QtPy.
172
    
173
    Returns:
174
        argparse.ArgumentParser: Configured argument parser with subcommands
175
                                for mypy-args and pyright-config
176
    """
177

178
def main(args: list[str] | None = None) -> None:
179
    """
180
    Run the development CLI for QtPy.
181
    Entry point for the console script.
182
    
183
    Args:
184
        args: Command line arguments, uses sys.argv if None
185
    """
186
```
187

188
Usage example:
189

190
```python
191
from qtpy.cli import generate_arg_parser, main
192

193
# Create argument parser programmatically
194
parser = generate_arg_parser()
195
parsed_args = parser.parse_args(['mypy-args'])
196

197
# Run CLI programmatically
198
main(['--version'])  # Prints version
199
main(['mypy-args'])  # Prints mypy arguments
200
main(['pyright-config'])  # Prints Pyright configuration
201
```
202

203
## Command Line Interface
204

205
QtPy provides a command-line interface accessible via the `qtpy` command or `python -m qtpy`.
206

207
### Available Commands
208

209
```bash
210
# Show version
211
qtpy --version
212

213
# Generate mypy arguments
214
qtpy mypy-args
215

216
# Generate Pyright configuration
217
qtpy pyright-config
218

219
# Show help
220
qtpy --help
221
```
222

223
### Usage Examples
224

225
**MyPy Integration:**
226

227
```bash
228
# Use QtPy with mypy for type checking
229
mypy --package myproject $(qtpy mypy-args)
230

231
# This expands to something like:
232
# mypy --package myproject --always-false=PYQT5 --always-true=PYSIDE2 --always-false=PYQT6 --always-false=PYSIDE6
233
```
234

235
**Pyright Configuration:**
236

237
```bash
238
# Generate pyrightconfig.json content
239
qtpy pyright-config > pyrightconfig.json
240

241
# Or manually copy the configuration:
242
qtpy pyright-config
243
```
244

245
The generated configuration helps IDEs and type checkers understand which Qt binding QtPy is using, enabling proper type hints and autocompletion.
246

247
## Integration with Development Workflow
248

249
### IDE Setup
250

251
1. **MyPy Integration**: Use `qtpy mypy-args` to configure mypy for proper type checking
252
2. **Pyright/Pylance**: Use `qtpy pyright-config` to configure Pyright for VS Code
253
3. **Type Hints**: The CLI ensures IDEs understand which Qt binding is active
254

255
### Continuous Integration
256

257
```yaml
258
# Example GitHub Actions workflow
259
- name: Type check with mypy
260
  run: mypy --package myproject $(qtpy mypy-args)
261
```
262

263
### Development Environment Detection
264

265
```python
266
# Programmatically check binding in development scripts
267
from qtpy.cli import get_api_status
268

269
def setup_dev_environment():
270
    status = get_api_status()
271
    active_binding = next(name for name, active in status.items() if active)
272
    print(f"Setting up development environment for {active_binding}")
273
    
274
    # Configure tools based on active binding
275
    if active_binding in ['pyqt5', 'pyqt6']:
276
        setup_pyqt_tools()
277
    else:  # pyside2, pyside6
278
        setup_pyside_tools()
279
```