@dbx-tools/projen 0.6.76 → 0.6.77

package/src/project-predicate.ts

@@ -11,7 +11,7 @@ import { IConstruct } from "constructs";
 import { Project } from "projen";
 import { project } from "..";
 import { toPosix } from "./packages.ts";
-import { DBXToolsProject, DBXToolsNodeProject, DBXToolsTypeScriptProject } from "./project.ts";
+import { DBXToolsProject, DBXToolsNodeProject, DBXToolsTypeScriptProject } from "./project-js.ts";
 
 /**
  * Guard: the construct is a projen {@link Project} - the base every builder here

package/src/project-py.ts

@@ -0,0 +1,329 @@
+/** Reusable uv workspace generation for Python packages hosted in a projen tree. */
+import { string } from "@dbx-tools/shared-core";
+import { Component, TextFile, type Project, javascript, vscode } from "projen";
+import { GithubWorkflow } from "projen/lib/github";
+import { JobPermission } from "projen/lib/github/workflows-model";
+
+/** Git location used by direct `#subdirectory=` package dependencies. */
+export interface PythonRepositoryOptions {
+  readonly url: string;
+  readonly ref?: string;
+  readonly root?: string;
+}
+
+/** One independently installable Python package in the uv workspace. */
+export interface PythonPackageOptions {
+  readonly directory: string;
+  readonly name: string;
+  readonly module: string;
+  readonly description: string;
+  readonly dependencies?: readonly string[];
+}
+
+/** Python release workflow configuration. */
+export interface PythonReleaseOptions {
+  readonly workflowName?: string;
+  readonly environment?: string;
+  readonly environmentUrl?: string;
+}
+
+/** Options for {@link DBXToolsPythonWorkspace}. */
+export interface DBXToolsPythonWorkspaceOptions {
+  readonly packages: readonly PythonPackageOptions[];
+  readonly repository: PythonRepositoryOptions;
+  readonly requiresPython?: string;
+  readonly ruffTarget?: string;
+  readonly workspaceName?: string;
+  readonly devDependencies?: readonly string[];
+  readonly testPaths?: readonly string[];
+  readonly lintPaths?: readonly string[];
+  readonly ruffPerFileIgnores?: Readonly<Record<string, readonly string[]>>;
+  readonly interpreterPath?: string | false;
+  readonly release?: boolean | PythonReleaseOptions;
+}
+
+const DEFAULT_DEV_DEPENDENCIES = [
+  "pytest>=8.4,<9",
+  "pytest-asyncio>=1.1,<2",
+  "pyyaml>=6.0,<7",
+  "ruff>=0.12,<1",
+] as const;
+
+const quote = (value: string): string => JSON.stringify(value);
+
+/** Repository-relative path for a Python package directory. */
+export function pythonPackagePath(repository: PythonRepositoryOptions, directory: string): string {
+  return `${repository.root ?? "packages/py"}/${directory}`;
+}
+
+/** PEP 508 dependency pointing at a sibling package in a Git repository. */
+export function pythonGitDependency(
+  repository: PythonRepositoryOptions,
+  name: string,
+  directory: string,
+): string {
+  return `${name} @ git+${repository.url}@${repository.ref ?? "main"}#subdirectory=${pythonPackagePath(repository, directory)}`;
+}
+
+function projectVscode(project: Project): vscode.VsCode | undefined {
+  return (project as Project & { readonly vscode?: vscode.VsCode }).vscode;
+}
+
+/**
+ * Generates a root uv workspace, member package metadata, Python tasks, editor
+ * interpreter selection, and an optional trusted-publishing workflow.
+ */
+export class DBXToolsPythonWorkspace extends Component {
+  readonly packages: readonly PythonPackageOptions[];
+  readonly repository: Required<PythonRepositoryOptions>;
+  readonly requiresPython: string;
+
+  constructor(project: javascript.NodeProject, options: DBXToolsPythonWorkspaceOptions) {
+    super(project);
+    this.packages = options.packages;
+    this.repository = {
+      url: options.repository.url,
+      ref: options.repository.ref ?? "main",
+      root: options.repository.root ?? "packages/py",
+    };
+    this.requiresPython = options.requiresPython ?? ">=3.10";
+
+    this.emitWorkspace(project, options);
+    this.emitPackages(project);
+    this.addTasks(project, options);
+
+    const interpreterPath = options.interpreterPath ?? "${workspaceFolder}/.venv/bin/python";
+    if (interpreterPath !== false) {
+      projectVscode(project)?.settings.addSetting("python.defaultInterpreterPath", interpreterPath);
+    }
+
+    if (options.release) {
+      this.addReleaseWorkflow(project, options.release === true ? {} : options.release);
+    }
+  }
+
+  /** Repository-relative package directory. */
+  packagePath(directory: string): string {
+    return pythonPackagePath(this.repository, directory);
+  }
+
+  /** PEP 508 dependency pointing at a sibling package in the configured repository. */
+  gitDependency(name: string, directory: string): string {
+    return pythonGitDependency(this.repository, name, directory);
+  }
+
+  private emitWorkspace(
+    project: javascript.NodeProject,
+    options: DBXToolsPythonWorkspaceOptions,
+  ): void {
+    const devDependencies = options.devDependencies ?? DEFAULT_DEV_DEPENDENCIES;
+    const testPaths = options.testPaths ?? [this.repository.root];
+    const ruffTarget = options.ruffTarget ?? "py310";
+    const perFileIgnores = options.ruffPerFileIgnores ?? {};
+    new TextFile(project, "pyproject.toml", {
+      marker: false,
+      readonly: true,
+      lines: [
+        '# ~~ Generated by projen. To modify, edit .projenrc.ts and run "bunx projen".',
+        "[project]",
+        `name = ${quote(options.workspaceName ?? `${string.toSlug(project.name)}-python-workspace`)}`,
+        'version = "0.0.0"',
+        `requires-python = ${quote(this.requiresPython)}`,
+        "dependencies = []",
+        "",
+        "[dependency-groups]",
+        `dev = [${devDependencies.map(quote).join(", ")}]`,
+        "",
+        "[tool.uv]",
+        "package = false",
+        "",
+        "[tool.uv.workspace]",
+        `members = [${quote(`${this.repository.root}/*`)}]`,
+        "",
+        "[tool.uv.sources]",
+        ...this.packages.map((pkg) => `${pkg.name} = { workspace = true }`),
+        "",
+        "[tool.pytest.ini_options]",
+        'asyncio_mode = "auto"',
+        `testpaths = [${testPaths.map(quote).join(", ")}]`,
+        "",
+        "[tool.ruff]",
+        `target-version = ${quote(ruffTarget)}`,
+        "line-length = 100",
+        "",
+        "[tool.ruff.lint.per-file-ignores]",
+        ...Object.entries(perFileIgnores).map(
+          ([path, rules]) => `${quote(path)} = [${rules.map(quote).join(", ")}]`,
+        ),
+        "",
+      ],
+    });
+  }
+
+  private emitPackages(project: javascript.NodeProject): void {
+    for (const pkg of this.packages) {
+      new TextFile(project, `${this.packagePath(pkg.directory)}/pyproject.toml`, {
+        marker: false,
+        readonly: true,
+        lines: [
+          '# ~~ Generated by projen. To modify, edit .projenrc.ts and run "bunx projen".',
+          "[project]",
+          `name = ${quote(pkg.name)}`,
+          'version = "0.0.0"',
+          `description = ${quote(pkg.description)}`,
+          'readme = "README.md"',
+          `requires-python = ${quote(this.requiresPython)}`,
+          `dependencies = [${(pkg.dependencies ?? []).map(quote).join(", ")}]`,
+          "",
+          "[project.urls]",
+          `Source = ${quote(`${this.repository.url.replace(/\.git$/, "")}/tree/${this.repository.ref}/${this.packagePath(pkg.directory)}`)}`,
+          "",
+          "[build-system]",
+          'requires = ["uv_build>=0.11.28,<0.12.0"]',
+          'build-backend = "uv_build"',
+          "",
+          "[tool.uv.build-backend]",
+          `module-name = ${quote(pkg.module)}`,
+          'module-root = "src"',
+          "namespace = true",
+          "",
+        ],
+      });
+    }
+  }
+
+  private addTasks(project: javascript.NodeProject, options: DBXToolsPythonWorkspaceOptions): void {
+    const lintPaths = options.lintPaths ?? [this.repository.root];
+    project.addTask("py:sync", {
+      exec: "uv sync --all-packages",
+      description: "Resolve and install every Python workspace package",
+    });
+    project.addTask("py:test", {
+      exec: "uv run pytest",
+      description: "Run Python workspace tests",
+    });
+    project.addTask("py:lint", {
+      exec: `uv run ruff check ${lintPaths.join(" ")}`,
+      description: "Lint Python workspace packages",
+    });
+    project.addTask("py:format", {
+      exec: `uv run ruff format ${lintPaths.join(" ")}`,
+      description: "Format Python workspace packages",
+    });
+    project.addTask("py:build", {
+      exec: "uv build --all-packages",
+      description: "Build every Python workspace package",
+    });
+  }
+
+  private addReleaseWorkflow(project: javascript.NodeProject, options: PythonReleaseOptions): void {
+    if (!project.github) return;
+    const workflow = new GithubWorkflow(project.github, options.workflowName ?? "python-release");
+    workflow.file?.addOverride("permissions", { contents: "read" });
+    workflow.on({ workflowDispatch: {} });
+    workflow.file?.addOverride("on.workflow_dispatch", {
+      inputs: {
+        version: {
+          description: "Python package version to build",
+          type: "string",
+          required: true,
+        },
+        publish: {
+          description: "Upload the validated distributions to PyPI",
+          type: "boolean",
+          default: false,
+        },
+      },
+    });
+    workflow.addJob("build", {
+      runsOn: ["ubuntu-latest"],
+      permissions: { contents: JobPermission.READ },
+      timeoutMinutes: 20,
+      steps: [
+        { name: "Checkout", uses: "actions/checkout@v6" },
+        { name: "Setup uv", uses: "astral-sh/setup-uv@v7" },
+        {
+          name: "Stamp workspace versions",
+          env: { VERSION: "${{ inputs.version }}" },
+          run: this.renderVersionStampScript(),
+        },
+        { name: "Build distributions", run: "uv build --all-packages" },
+        {
+          name: "Validate distributions",
+          run: [
+            `test "$(find dist -maxdepth 1 -type f | wc -l | tr -d ' ')" -eq ${this.packages.length * 2}`,
+            "uvx twine check dist/*",
+          ].join("\n"),
+        },
+        {
+          name: "Upload distributions",
+          uses: "actions/upload-artifact@v7",
+          with: { name: "python-distributions", path: "dist" },
+        },
+      ],
+    });
+    workflow.addJob("publish", {
+      if: "${{ inputs.publish }}",
+      needs: ["build"],
+      environment: {
+        name: options.environment ?? "pypi",
+        url: options.environmentUrl ?? "https://pypi.org/",
+      },
+      runsOn: ["ubuntu-latest"],
+      permissions: { idToken: JobPermission.WRITE },
+      timeoutMinutes: 10,
+      steps: [
+        {
+          name: "Download distributions",
+          uses: "actions/download-artifact@v8",
+          with: { name: "python-distributions", path: "dist" },
+        },
+        {
+          name: "Publish to PyPI",
+          uses: "pypa/gh-action-pypi-publish@release/v1",
+          with: { "packages-dir": "dist" },
+        },
+      ],
+    });
+  }
+
+  private renderVersionStampScript(): string {
+    return [
+      `chmod -R u+w ${this.repository.root}`,
+      "python - <<'PY'",
+      "from pathlib import Path",
+      "import os",
+      "import re",
+      "",
+      'version = os.environ["VERSION"]',
+      `package_files = sorted(Path(${quote(this.repository.root)}).glob("*/pyproject.toml"))`,
+      "packages = {}",
+      "for path in package_files:",
+      '    source = path.read_text(encoding="utf-8")',
+      '    name = re.search(r\'^name = "([^"]+)"$\', source, re.MULTILINE)',
+      "    if name is None:",
+      '        raise ValueError(f"Missing project name in {path}")',
+      "    packages[name.group(1)] = path.parent.name",
+      "",
+      "for path in package_files:",
+      '    source = path.read_text(encoding="utf-8")',
+      "    source, count = re.subn(",
+      '        r\'^version = "[^"]+"$\',',
+      "        f'version = \"{version}\"',",
+      "        source,",
+      "        count=1,",
+      "        flags=re.MULTILINE,",
+      "    )",
+      "    if count != 1:",
+      '        raise ValueError(f"Expected one project version in {path}")',
+      "    for name, directory in packages.items():",
+      "        source = re.sub(",
+      `            rf'{re.escape(name)} @ git\\+[^" ]+#subdirectory=${this.repository.root}/{re.escape(directory)}',`,
+      '            f"{name}=={version}",',
+      "            source,",
+      "        )",
+      '    path.write_text(source, encoding="utf-8")',
+      "PY",
+    ].join("\n");
+  }
+}