Python Projects

/**
 * Python project with packaging, virtual environments, and testing
 * Supports pip, poetry, and setuptools for dependency management
 */
class PythonProject extends GitHubProject {
  constructor(options: PythonProjectOptions);
  
  /** Python module name (converted from package name) */
  readonly moduleName: string;
  /** Pip dependency management (if enabled) */
  readonly pip?: Pip;
  /** Poetry dependency management (if enabled) */
  readonly poetry?: Poetry;
  /** Virtual environment management */
  readonly venv?: Venv;
  /** Setuptools packaging (if enabled) */
  readonly setuptools?: Setuptools;
  /** Pytest testing framework (if enabled) */
  readonly pytest?: Pytest;
  /** Python version requirement */
  readonly pythonVersion: string;
}

interface PythonProjectOptions extends GitHubProjectOptions {
  /** Python module name (auto-generated from name if not provided) */
  moduleName?: string;
  /** Python version requirement (default: ">=3.8") */
  pythonVersion?: string;
  /** Package author name */
  authorName?: string;
  /** Package author email */
  authorEmail?: string;
  /** Package version */
  version?: string;
  /** Package description */
  description?: string;
  /** Package license */
  license?: string;
  /** Package homepage */
  homepage?: string;
  /** Package classifiers */
  classifiers?: string[];
  
  /** Runtime dependencies */
  deps?: string[];
  /** Development dependencies */
  devDeps?: string[];
  
  /** Use Poetry for dependency management */
  poetry?: boolean;
  /** Poetry configuration options */
  poetryOptions?: PoetryOptions;
  
  /** Use pip for dependency management */
  pip?: boolean;
  /** Pip configuration options */
  pipOptions?: PipOptions;
  
  /** Enable setuptools packaging */
  setuptools?: boolean;
  /** Setuptools configuration */
  setuptoolsOptions?: SetuptoolsOptions;
  
  /** Enable pytest testing */
  pytest?: boolean;
  /** Pytest configuration options */
  pytestOptions?: PytestOptions;
  
  /** Enable virtual environment */
  venv?: boolean;
  /** Virtual environment options */
  venvOptions?: VenvOptions;
  
  /** Generate sample code */
  sample?: boolean;
}

import { PythonProject } from "projen";

const project = new PythonProject({
  name: "my-python-package",
  moduleName: "my_python_package",
  defaultReleaseBranch: "main",
  
  // Package metadata
  authorName: "Jane Developer",
  authorEmail: "jane@example.com",
  version: "0.1.0",
  description: "My awesome Python package",
  license: "Apache-2.0",
  
  // Python version
  pythonVersion: ">=3.8",
  
  // Dependencies
  deps: [
    "requests>=2.28.0",
    "click>=8.0.0",
    "pydantic>=1.10.0",
  ],
  devDeps: [
    "pytest>=7.0.0",
    "black>=22.0.0",
    "flake8>=5.0.0",
    "mypy>=1.0.0",
  ],
  
  // Use Poetry for dependency management
  poetry: true,
  
  // Enable testing with pytest
  pytest: true,
  
  // Generate sample code
  sample: true,
});

/**
 * Poetry dependency management for Python projects
 * Manages pyproject.toml and poetry.lock files
 */
class Poetry extends Component {
  constructor(project: PythonProject, options?: PoetryOptions);
  
  /** Poetry configuration */
  readonly config: any;
  /** Install task */
  readonly installTask: Task;
  /** Update task */
  readonly updateTask: Task;
  
  /** Add runtime dependency */
  addDependency(name: string, requirement?: string): void;
  /** Add development dependency */
  addDevDependency(name: string, requirement?: string): void;
  /** Add dependency group */
  addGroup(name: string, dependencies: Record<string, string>): void;
  /** Add script */
  addScript(name: string, command: string): void;
}

interface PoetryOptions {
  /** Poetry version constraint */
  version?: string;
  /** Python version requirement */
  pythonVersion?: string;
  /** Package authors */
  authors?: string[];
  /** Package maintainers */
  maintainers?: string[];
  /** Package keywords */
  keywords?: string[];
  /** Package classifiers */
  classifiers?: string[];
  /** Include/exclude files */
  include?: string[];
  exclude?: string[];
}

import { PythonProject } from "projen";

const project = new PythonProject({
  name: "poetry-example",
  poetry: true,
  poetryOptions: {
    authors: ["Jane Developer <jane@example.com>"],
    keywords: ["python", "example", "poetry"],
    classifiers: [
      "Development Status :: 4 - Beta",
      "Intended Audience :: Developers",
      "Programming Language :: Python :: 3",
      "Programming Language :: Python :: 3.8",
      "Programming Language :: Python :: 3.9",
      "Programming Language :: Python :: 3.10",
    ],
  },
});

// Add dependencies programmatically
if (project.poetry) {
  project.poetry.addDependency("fastapi", "^0.100.0");
  project.poetry.addDependency("uvicorn", "^0.23.0");
  
  project.poetry.addDevDependency("pytest-asyncio", "^0.21.0");
  project.poetry.addDevDependency("httpx", "^0.24.0");
  
  // Add dependency groups
  project.poetry.addGroup("docs", {
    "sphinx": "^7.0.0",
    "sphinx-rtd-theme": "^1.3.0",
  });
  
  // Add scripts
  project.poetry.addScript("serve", "uvicorn main:app --reload");
}

/**
 * Pytest testing framework for Python projects
 * Provides unit testing, fixtures, and coverage reporting
 */
class Pytest extends Component {
  constructor(project: PythonProject, options?: PytestOptions);
  
  /** Pytest configuration */
  readonly config: any;
  /** Test task */
  readonly testTask: Task;
  
  /** Add pytest configuration */
  addConfig(key: string, value: any): void;
  /** Add test directory */
  addTestDir(dir: string): void;
  /** Add pytest marker */
  addMarker(name: string, description: string): void;
}

interface PytestOptions {
  /** Pytest version */
  version?: string;
  /** Test directories */
  testpaths?: string[];
  /** Python files pattern */
  pythonFiles?: string;
  /** Python classes pattern */
  pythonClasses?: string;
  /** Python functions pattern */
  pythonFunctions?: string;
  /** Minimum coverage threshold */
  minCoverage?: number;
  /** Coverage report format */
  coverageReports?: string[];
  /** Additional pytest markers */
  markers?: Record<string, string>;
}

/**
 * Setuptools packaging configuration for Python projects
 * Manages setup.py and setup.cfg files
 */
class Setuptools extends Component {
  constructor(project: PythonProject, options?: SetuptoolsOptions);
  
  /** Add console script entry point */
  addEntryPoint(name: string, module: string, function?: string): void;
  /** Add package data */
  addPackageData(package: string, patterns: string[]): void;
}

interface SetuptoolsOptions {
  /** Package description */
  description?: string;
  /** Long description content type */
  longDescriptionContentType?: string;
  /** Package URL */
  url?: string;
  /** Package classifiers */
  classifiers?: string[];
  /** Console scripts */
  scripts?: Record<string, string>;
  /** Package data */
  packageData?: Record<string, string[]>;
  /** Include package data */
  includePackageData?: boolean;
}

/**
 * Virtual environment management for Python projects
 * Handles venv creation and activation
 */
class Venv extends Component {
  constructor(project: PythonProject, options?: VenvOptions);
  
  /** Virtual environment path */
  readonly venvPath: string;
  /** Activation script path */
  readonly activateScript: string;
}

interface VenvOptions {
  /** Virtual environment directory name */
  envdir?: string;
  /** Python interpreter to use */
  pythonExec?: string;
}

/**
 * Python sample code generation
 * Creates example Python modules and tests
 */
class PythonSample extends Component {
  constructor(project: PythonProject, options?: PythonSampleOptions);
}

interface PythonSampleOptions {
  /** Source directory */
  srcdir?: string;
  /** Test directory */
  testdir?: string;
  /** Sample module name */
  sampleModule?: string;
}

import { PythonProject } from "projen";

const project = new PythonProject({
  name: "advanced-python-project",
  moduleName: "advanced_python_project",
  defaultReleaseBranch: "main",
  
  // Package metadata
  authorName: "Python Developer",
  authorEmail: "python@example.com",
  version: "0.1.0",
  description: "An advanced Python project with all features",
  license: "MIT",
  homepage: "https://github.com/user/advanced-python-project",
  
  // Python version
  pythonVersion: ">=3.8",
  
  // Dependencies
  deps: [
    "fastapi>=0.100.0",
    "uvicorn[standard]>=0.23.0",
    "pydantic>=2.0.0",
    "sqlalchemy>=2.0.0",
  ],
  devDeps: [
    "pytest>=7.4.0",
    "pytest-asyncio>=0.21.0",
    "pytest-cov>=4.1.0",
    "black>=23.0.0",
    "isort>=5.12.0",
    "flake8>=6.0.0",
    "mypy>=1.5.0",
    "pre-commit>=3.3.0",
  ],
  
  // Use Poetry for modern dependency management
  poetry: true,
  poetryOptions: {
    authors: ["Python Developer <python@example.com>"],
    keywords: ["fastapi", "python", "api"],
    classifiers: [
      "Development Status :: 3 - Alpha",
      "Intended Audience :: Developers",
      "License :: OSI Approved :: MIT License",
      "Programming Language :: Python :: 3",
      "Programming Language :: Python :: 3.8",
      "Programming Language :: Python :: 3.9",
      "Programming Language :: Python :: 3.10",
      "Programming Language :: Python :: 3.11",
    ],
  },
  
  // Testing with pytest
  pytest: true,
  pytestOptions: {
    testpaths: ["tests"],
    minCoverage: 80,
    coverageReports: ["term", "html", "xml"],
    markers: {
      "slow": "marks tests as slow",
      "integration": "marks tests as integration tests",
    },
  },
  
  // Setuptools for packaging
  setuptools: true,
  setuptoolsOptions: {
    scripts: {
      "my-cli": "advanced_python_project.cli:main",
    },
    includePackageData: true,
  },
  
  // Generate sample code
  sample: true,
});

// Add Poetry dependency groups
if (project.poetry) {
  project.poetry.addGroup("docs", {
    "sphinx": "^7.1.0",
    "sphinx-rtd-theme": "^1.3.0",
    "myst-parser": "^2.0.0",
  });
  
  project.poetry.addGroup("dev", {
    "pre-commit": "^3.3.0",
    "commitizen": "^3.5.0",
  });
  
  // Add Poetry scripts
  project.poetry.addScript("serve", "uvicorn advanced_python_project.main:app --reload");
  project.poetry.addScript("format", "black . && isort .");
  project.poetry.addScript("lint", "flake8 . && mypy .");
}

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

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

project.addTask("format:check", {
  description: "Check code formatting",
  exec: "black --check . && isort --check-only .",
});

interface PyprojectToml {
  tool?: {
    poetry?: {
      name?: string;
      version?: string;
      description?: string;
      authors?: string[];
      maintainers?: string[];
      license?: string;
      homepage?: string;
      repository?: string;
      documentation?: string;
      keywords?: string[];
      classifiers?: string[];
      dependencies?: Record<string, string>;
      group?: Record<string, { dependencies?: Record<string, string> }>;
      scripts?: Record<string, string>;
    };
    pytest?: {
      ini_options?: Record<string, any>;
    };
    black?: Record<string, any>;
    isort?: Record<string, any>;
    mypy?: Record<string, any>;
  };
}

interface SetupPy {
  name?: string;
  version?: string;
  description?: string;
  long_description?: string;
  long_description_content_type?: string;
  author?: string;
  author_email?: string;
  url?: string;
  license?: string;
  classifiers?: string[];
  packages?: string[];
  install_requires?: string[];
  extras_require?: Record<string, string[]>;
  entry_points?: {
    console_scripts?: string[];
  };
  include_package_data?: boolean;
  package_data?: Record<string, string[]>;
}