0
# Python Projects
1

2
Python projects with packaging, virtual environments, and testing frameworks. Provides comprehensive setup for Python applications and libraries with modern Python development tools.
3

4
## Capabilities
5

6
### PythonProject Class
7

8
Main Python project class with packaging, dependency management, and testing setup.
9

10
```typescript { .api }
11
/**
12
 * Python project with packaging, virtual environments, and testing
13
 * Supports pip, poetry, and setuptools for dependency management
14
 */
15
class PythonProject extends GitHubProject {
16
  constructor(options: PythonProjectOptions);
17
  
18
  /** Python module name (converted from package name) */
19
  readonly moduleName: string;
20
  /** Pip dependency management (if enabled) */
21
  readonly pip?: Pip;
22
  /** Poetry dependency management (if enabled) */
23
  readonly poetry?: Poetry;
24
  /** Virtual environment management */
25
  readonly venv?: Venv;
26
  /** Setuptools packaging (if enabled) */
27
  readonly setuptools?: Setuptools;
28
  /** Pytest testing framework (if enabled) */
29
  readonly pytest?: Pytest;
30
  /** Python version requirement */
31
  readonly pythonVersion: string;
32
}
33

34
interface PythonProjectOptions extends GitHubProjectOptions {
35
  /** Python module name (auto-generated from name if not provided) */
36
  moduleName?: string;
37
  /** Python version requirement (default: ">=3.8") */
38
  pythonVersion?: string;
39
  /** Package author name */
40
  authorName?: string;
41
  /** Package author email */
42
  authorEmail?: string;
43
  /** Package version */
44
  version?: string;
45
  /** Package description */
46
  description?: string;
47
  /** Package license */
48
  license?: string;
49
  /** Package homepage */
50
  homepage?: string;
51
  /** Package classifiers */
52
  classifiers?: string[];
53
  
54
  /** Runtime dependencies */
55
  deps?: string[];
56
  /** Development dependencies */
57
  devDeps?: string[];
58
  
59
  /** Use Poetry for dependency management */
60
  poetry?: boolean;
61
  /** Poetry configuration options */
62
  poetryOptions?: PoetryOptions;
63
  
64
  /** Use pip for dependency management */
65
  pip?: boolean;
66
  /** Pip configuration options */
67
  pipOptions?: PipOptions;
68
  
69
  /** Enable setuptools packaging */
70
  setuptools?: boolean;
71
  /** Setuptools configuration */
72
  setuptoolsOptions?: SetuptoolsOptions;
73
  
74
  /** Enable pytest testing */
75
  pytest?: boolean;
76
  /** Pytest configuration options */
77
  pytestOptions?: PytestOptions;
78
  
79
  /** Enable virtual environment */
80
  venv?: boolean;
81
  /** Virtual environment options */
82
  venvOptions?: VenvOptions;
83
  
84
  /** Generate sample code */
85
  sample?: boolean;
86
}
87
```
88

89
**Basic Python Project Example:**
90

91
```typescript
92
import { PythonProject } from "projen";
93

94
const project = new PythonProject({
95
  name: "my-python-package",
96
  moduleName: "my_python_package",
97
  defaultReleaseBranch: "main",
98
  
99
  // Package metadata
100
  authorName: "Jane Developer",
101
  authorEmail: "jane@example.com",
102
  version: "0.1.0",
103
  description: "My awesome Python package",
104
  license: "Apache-2.0",
105
  
106
  // Python version
107
  pythonVersion: ">=3.8",
108
  
109
  // Dependencies
110
  deps: [
111
    "requests>=2.28.0",
112
    "click>=8.0.0",
113
    "pydantic>=1.10.0",
114
  ],
115
  devDeps: [
116
    "pytest>=7.0.0",
117
    "black>=22.0.0",
118
    "flake8>=5.0.0",
119
    "mypy>=1.0.0",
120
  ],
121
  
122
  // Use Poetry for dependency management
123
  poetry: true,
124
  
125
  // Enable testing with pytest
126
  pytest: true,
127
  
128
  // Generate sample code
129
  sample: true,
130
});
131
```
132

133
### Poetry Dependency Management
134

135
Modern Python dependency management with Poetry.
136

137
```typescript { .api }
138
/**
139
 * Poetry dependency management for Python projects
140
 * Manages pyproject.toml and poetry.lock files
141
 */
142
class Poetry extends Component {
143
  constructor(project: PythonProject, options?: PoetryOptions);
144
  
145
  /** Poetry configuration */
146
  readonly config: any;
147
  /** Install task */
148
  readonly installTask: Task;
149
  /** Update task */
150
  readonly updateTask: Task;
151
  
152
  /** Add runtime dependency */
153
  addDependency(name: string, requirement?: string): void;
154
  /** Add development dependency */
155
  addDevDependency(name: string, requirement?: string): void;
156
  /** Add dependency group */
157
  addGroup(name: string, dependencies: Record<string, string>): void;
158
  /** Add script */
159
  addScript(name: string, command: string): void;
160
}
161

162
interface PoetryOptions {
163
  /** Poetry version constraint */
164
  version?: string;
165
  /** Python version requirement */
166
  pythonVersion?: string;
167
  /** Package authors */
168
  authors?: string[];
169
  /** Package maintainers */
170
  maintainers?: string[];
171
  /** Package keywords */
172
  keywords?: string[];
173
  /** Package classifiers */
174
  classifiers?: string[];
175
  /** Include/exclude files */
176
  include?: string[];
177
  exclude?: string[];
178
}
179
```
180

181
**Poetry Configuration Example:**
182

183
```typescript
184
import { PythonProject } from "projen";
185

186
const project = new PythonProject({
187
  name: "poetry-example",
188
  poetry: true,
189
  poetryOptions: {
190
    authors: ["Jane Developer <jane@example.com>"],
191
    keywords: ["python", "example", "poetry"],
192
    classifiers: [
193
      "Development Status :: 4 - Beta",
194
      "Intended Audience :: Developers",
195
      "Programming Language :: Python :: 3",
196
      "Programming Language :: Python :: 3.8",
197
      "Programming Language :: Python :: 3.9",
198
      "Programming Language :: Python :: 3.10",
199
    ],
200
  },
201
});
202

203
// Add dependencies programmatically
204
if (project.poetry) {
205
  project.poetry.addDependency("fastapi", "^0.100.0");
206
  project.poetry.addDependency("uvicorn", "^0.23.0");
207
  
208
  project.poetry.addDevDependency("pytest-asyncio", "^0.21.0");
209
  project.poetry.addDevDependency("httpx", "^0.24.0");
210
  
211
  // Add dependency groups
212
  project.poetry.addGroup("docs", {
213
    "sphinx": "^7.0.0",
214
    "sphinx-rtd-theme": "^1.3.0",
215
  });
216
  
217
  // Add scripts
218
  project.poetry.addScript("serve", "uvicorn main:app --reload");
219
}
220
```
221

222
### Pytest Testing Framework
223

224
Comprehensive testing setup with pytest.
225

226
```typescript { .api }
227
/**
228
 * Pytest testing framework for Python projects
229
 * Provides unit testing, fixtures, and coverage reporting
230
 */
231
class Pytest extends Component {
232
  constructor(project: PythonProject, options?: PytestOptions);
233
  
234
  /** Pytest configuration */
235
  readonly config: any;
236
  /** Test task */
237
  readonly testTask: Task;
238
  
239
  /** Add pytest configuration */
240
  addConfig(key: string, value: any): void;
241
  /** Add test directory */
242
  addTestDir(dir: string): void;
243
  /** Add pytest marker */
244
  addMarker(name: string, description: string): void;
245
}
246

247
interface PytestOptions {
248
  /** Pytest version */
249
  version?: string;
250
  /** Test directories */
251
  testpaths?: string[];
252
  /** Python files pattern */
253
  pythonFiles?: string;
254
  /** Python classes pattern */
255
  pythonClasses?: string;
256
  /** Python functions pattern */
257
  pythonFunctions?: string;
258
  /** Minimum coverage threshold */
259
  minCoverage?: number;
260
  /** Coverage report format */
261
  coverageReports?: string[];
262
  /** Additional pytest markers */
263
  markers?: Record<string, string>;
264
}
265
```
266

267
### Setuptools Packaging
268

269
Traditional Python packaging with setuptools.
270

271
```typescript { .api }
272
/**
273
 * Setuptools packaging configuration for Python projects
274
 * Manages setup.py and setup.cfg files
275
 */
276
class Setuptools extends Component {
277
  constructor(project: PythonProject, options?: SetuptoolsOptions);
278
  
279
  /** Add console script entry point */
280
  addEntryPoint(name: string, module: string, function?: string): void;
281
  /** Add package data */
282
  addPackageData(package: string, patterns: string[]): void;
283
}
284

285
interface SetuptoolsOptions {
286
  /** Package description */
287
  description?: string;
288
  /** Long description content type */
289
  longDescriptionContentType?: string;
290
  /** Package URL */
291
  url?: string;
292
  /** Package classifiers */
293
  classifiers?: string[];
294
  /** Console scripts */
295
  scripts?: Record<string, string>;
296
  /** Package data */
297
  packageData?: Record<string, string[]>;
298
  /** Include package data */
299
  includePackageData?: boolean;
300
}
301
```
302

303
### Virtual Environment Management
304

305
Python virtual environment setup and management.
306

307
```typescript { .api }
308
/**
309
 * Virtual environment management for Python projects
310
 * Handles venv creation and activation
311
 */
312
class Venv extends Component {
313
  constructor(project: PythonProject, options?: VenvOptions);
314
  
315
  /** Virtual environment path */
316
  readonly venvPath: string;
317
  /** Activation script path */
318
  readonly activateScript: string;
319
}
320

321
interface VenvOptions {
322
  /** Virtual environment directory name */
323
  envdir?: string;
324
  /** Python interpreter to use */
325
  pythonExec?: string;
326
}
327
```
328

329
### Python Sample Files
330

331
Generate sample Python code and test files.
332

333
```typescript { .api }
334
/**
335
 * Python sample code generation
336
 * Creates example Python modules and tests
337
 */
338
class PythonSample extends Component {
339
  constructor(project: PythonProject, options?: PythonSampleOptions);
340
}
341

342
interface PythonSampleOptions {
343
  /** Source directory */
344
  srcdir?: string;
345
  /** Test directory */
346
  testdir?: string;
347
  /** Sample module name */
348
  sampleModule?: string;
349
}
350
```
351

352
**Complete Python Project Example:**
353

354
```typescript
355
import { PythonProject } from "projen";
356

357
const project = new PythonProject({
358
  name: "advanced-python-project",
359
  moduleName: "advanced_python_project",
360
  defaultReleaseBranch: "main",
361
  
362
  // Package metadata
363
  authorName: "Python Developer",
364
  authorEmail: "python@example.com",
365
  version: "0.1.0",
366
  description: "An advanced Python project with all features",
367
  license: "MIT",
368
  homepage: "https://github.com/user/advanced-python-project",
369
  
370
  // Python version
371
  pythonVersion: ">=3.8",
372
  
373
  // Dependencies
374
  deps: [
375
    "fastapi>=0.100.0",
376
    "uvicorn[standard]>=0.23.0",
377
    "pydantic>=2.0.0",
378
    "sqlalchemy>=2.0.0",
379
  ],
380
  devDeps: [
381
    "pytest>=7.4.0",
382
    "pytest-asyncio>=0.21.0",
383
    "pytest-cov>=4.1.0",
384
    "black>=23.0.0",
385
    "isort>=5.12.0",
386
    "flake8>=6.0.0",
387
    "mypy>=1.5.0",
388
    "pre-commit>=3.3.0",
389
  ],
390
  
391
  // Use Poetry for modern dependency management
392
  poetry: true,
393
  poetryOptions: {
394
    authors: ["Python Developer <python@example.com>"],
395
    keywords: ["fastapi", "python", "api"],
396
    classifiers: [
397
      "Development Status :: 3 - Alpha",
398
      "Intended Audience :: Developers",
399
      "License :: OSI Approved :: MIT License",
400
      "Programming Language :: Python :: 3",
401
      "Programming Language :: Python :: 3.8",
402
      "Programming Language :: Python :: 3.9",
403
      "Programming Language :: Python :: 3.10",
404
      "Programming Language :: Python :: 3.11",
405
    ],
406
  },
407
  
408
  // Testing with pytest
409
  pytest: true,
410
  pytestOptions: {
411
    testpaths: ["tests"],
412
    minCoverage: 80,
413
    coverageReports: ["term", "html", "xml"],
414
    markers: {
415
      "slow": "marks tests as slow",
416
      "integration": "marks tests as integration tests",
417
    },
418
  },
419
  
420
  // Setuptools for packaging
421
  setuptools: true,
422
  setuptoolsOptions: {
423
    scripts: {
424
      "my-cli": "advanced_python_project.cli:main",
425
    },
426
    includePackageData: true,
427
  },
428
  
429
  // Generate sample code
430
  sample: true,
431
});
432

433
// Add Poetry dependency groups
434
if (project.poetry) {
435
  project.poetry.addGroup("docs", {
436
    "sphinx": "^7.1.0",
437
    "sphinx-rtd-theme": "^1.3.0",
438
    "myst-parser": "^2.0.0",
439
  });
440
  
441
  project.poetry.addGroup("dev", {
442
    "pre-commit": "^3.3.0",
443
    "commitizen": "^3.5.0",
444
  });
445
  
446
  // Add Poetry scripts
447
  project.poetry.addScript("serve", "uvicorn advanced_python_project.main:app --reload");
448
  project.poetry.addScript("format", "black . && isort .");
449
  project.poetry.addScript("lint", "flake8 . && mypy .");
450
}
451

452
// Add custom tasks
453
project.addTask("docs:build", {
454
  description: "Build documentation",
455
  exec: "sphinx-build -b html docs docs/_build",
456
});
457

458
project.addTask("docs:serve", {
459
  description: "Serve documentation locally",
460
  exec: "python -m http.server 8000 --directory docs/_build",
461
});
462

463
project.addTask("format:check", {
464
  description: "Check code formatting",
465
  exec: "black --check . && isort --check-only .",
466
});
467
```
468

469
## Types
470

471
### Python-Specific Types
472

473
```typescript { .api }
474
interface PyprojectToml {
475
  tool?: {
476
    poetry?: {
477
      name?: string;
478
      version?: string;
479
      description?: string;
480
      authors?: string[];
481
      maintainers?: string[];
482
      license?: string;
483
      homepage?: string;
484
      repository?: string;
485
      documentation?: string;
486
      keywords?: string[];
487
      classifiers?: string[];
488
      dependencies?: Record<string, string>;
489
      group?: Record<string, { dependencies?: Record<string, string> }>;
490
      scripts?: Record<string, string>;
491
    };
492
    pytest?: {
493
      ini_options?: Record<string, any>;
494
    };
495
    black?: Record<string, any>;
496
    isort?: Record<string, any>;
497
    mypy?: Record<string, any>;
498
  };
499
}
500

501
interface SetupPy {
502
  name?: string;
503
  version?: string;
504
  description?: string;
505
  long_description?: string;
506
  long_description_content_type?: string;
507
  author?: string;
508
  author_email?: string;
509
  url?: string;
510
  license?: string;
511
  classifiers?: string[];
512
  packages?: string[];
513
  install_requires?: string[];
514
  extras_require?: Record<string, string[]>;
515
  entry_points?: {
516
    console_scripts?: string[];
517
  };
518
  include_package_data?: boolean;
519
  package_data?: Record<string, string[]>;
520
}
521
```