@typespec/http-client-python 0.28.2 → 0.28.3

package/eng/scripts/Build-Packages.ps1

@@ -1,4 +1,30 @@
 #Requires -Version 7.0
+<#
+.SYNOPSIS
+    Builds and packages the TypeSpec Python emitter for publishing.
+
+.DESCRIPTION
+    This script is called by the CI pipeline to create publishable packages.
+    It runs:
+      1. npm run build     - Compile TypeScript emitter and build Python wheel
+      2. npm run lint      - Run linting (Linux only)
+      3. npm pack          - Create npm tarball for publishing
+
+.PARAMETER BuildNumber
+    The build number for versioning.
+
+.PARAMETER Output
+    Output directory for built packages. Defaults to ./ci-build.
+
+.PARAMETER Prerelease
+    Flag indicating if this is a prerelease build.
+
+.PARAMETER PublishType
+    Type of publish: "internal" for dev feed, otherwise public.
+
+.EXAMPLE
+    ./Build-Packages.ps1 -Output ./dist
+#>
 
 param(
     [string] $BuildNumber,
@@ -7,6 +33,15 @@ param(
     [string] $PublishType
 )
 
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version 3.0
+
+# Setup paths and helpers
+$packageRoot = (Resolve-Path "$PSScriptRoot/../..").Path.Replace('\', '/')
+. "$packageRoot/../../eng/emitters/scripts/CommandInvocation-Helpers.ps1"
+Set-ConsoleEncoding
+
+# Helper function to write package info for downstream publishing
 function Write-PackageInfo {
     param(
         [string] $packageName,
@@ -15,81 +50,71 @@ function Write-PackageInfo {
     )
 
     $packageInfoPath = "$outputPath/PackageInfo"
-
     if (!(Test-Path $packageInfoPath)) {
         New-Item -ItemType Directory -Force -Path $packageInfoPath | Out-Null
     }
 
     @{
-        Name = $packageName
-        Version = $version
+        Name          = $packageName
+        Version       = $version
         DirectoryPath = $directoryPath
-        SdkType = "client"
-        IsNewSdk = $true
+        SdkType       = "client"
+        IsNewSdk      = $true
         ReleaseStatus = "Unreleased"
     } | ConvertTo-Json | Set-Content -Path "$packageInfoPath/$packageName.json"
 }
 
-$ErrorActionPreference = 'Stop'
-Set-StrictMode -Version 3.0
-$packageRoot = (Resolve-Path "$PSScriptRoot/../..").Path.Replace('\', '/')
-. "$packageRoot/../../eng/emitters/scripts/CommandInvocation-Helpers.ps1"
-Set-ConsoleEncoding
-
 Write-Host "Building packages for BuildNumber: '$BuildNumber', Output: '$Output', Prerelease: '$Prerelease', PublishType: '$PublishType'"
 
+# Setup output directory
 $outputPath = $Output ? $Output : "$packageRoot/ci-build"
-
-# create the output folders
 $outputPath = New-Item -ItemType Directory -Force -Path $outputPath | Select-Object -ExpandProperty FullName
 New-Item -ItemType Directory -Force -Path "$outputPath/packages" | Out-Null
 
-Write-Host "Getting existing version"
+# Get package version
 $emitterVersion = node -p -e "require('$packageRoot/package.json').version"
+Write-Host "Package version: $emitterVersion"
 
-# build the generator
-Push-Location "$packageRoot/generator"
-
-# build and pack the emitter with the generator
 Push-Location "$packageRoot"
 try {
-    Write-Host "Working in $PWD"
-
+    # Step 1: Build the emitter and generator
+    Write-Host "`n=== Building emitter and generator ===" -ForegroundColor Cyan
     Invoke-LoggedCommand "npm run build" -GroupOutput
 
-    # Only run lint:py on Linux OS
+    # Step 2: Run linting (Linux only, as CI runs on Linux)
     if ($IsLinux) {
-        Write-Host "run lint check for pygen"
-        Invoke-LoggedCommand "npm run lint:py" -GroupOutput
+        Write-Host "`n=== Running lint checks ===" -ForegroundColor Cyan
+        Invoke-LoggedCommand "npm run lint" -GroupOutput
     }
 
-    # pack the emitter
+    # Step 3: Create npm package
+    Write-Host "`n=== Creating npm package ===" -ForegroundColor Cyan
     Invoke-LoggedCommand "npm pack"
     Copy-Item "typespec-http-client-python-$emitterVersion.tgz" -Destination "$outputPath/packages"
 
-    # install packed emitter to check dependencies
+    # Step 4: Verify package can be installed
+    Write-Host "`n=== Verifying package installation ===" -ForegroundColor Cyan
     Invoke-LoggedCommand "npm install typespec-http-client-python-$emitterVersion.tgz" -GroupOutput
 
-    Write-PackageInfo -packageName "typespec-http-client-python" -directoryPath "packages/http-client-python/emitter/src" -version $emitterVersion
+    # Write package info for publishing pipeline
+    Write-PackageInfo -packageName "typespec-http-client-python" `
+                      -directoryPath "packages/http-client-python/emitter/src" `
+                      -version $emitterVersion
 }
 finally {
     Pop-Location
 }
 
+# Generate override URLs for internal publishing
+$overrides = @{}
 if ($PublishType -eq "internal") {
     $feedUrl = "https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-js/npm/registry"
-
-    $overrides = @{
-        "@typespec/http-client-python" = "$feedUrl/@typespec/http-client-python/-/http-client-python-$emitterVersion.tgz"
-    }
-} else {
-    $overrides = @{}
+    $overrides["@typespec/http-client-python"] = "$feedUrl/@typespec/http-client-python/-/http-client-python-$emitterVersion.tgz"
 }
-
 $overrides | ConvertTo-Json | Set-Content "$outputPath/overrides.json"
 
-$packageMatrix = [ordered]@{
-    "emitter" = $emitterVersion
-}
+# Write package version matrix
+@{ "emitter" = $emitterVersion } | ConvertTo-Json | Set-Content "$outputPath/package-versions.json"
 
-$packageMatrix | ConvertTo-Json | Set-Content "$outputPath/package-versions.json"
+Write-Host "`n=== Build complete ===" -ForegroundColor Green
+Write-Host "Output: $outputPath"

package/eng/scripts/Check-GitChanges.ps1

@@ -1,4 +1,21 @@
 #Requires -Version 7.0
+<#
+.SYNOPSIS
+    Checks for uncommitted git changes.
+
+.DESCRIPTION
+    This script verifies that there are no uncommitted changes in the repository.
+    It excludes package.json and package-lock.json from the check since those
+    may be modified during npm operations.
+
+    Used by CI to ensure regeneration produces consistent output.
+
+.PARAMETER Exceptions
+    Additional paths to exclude from the check (not currently used).
+
+.EXAMPLE
+    ./Check-GitChanges.ps1
+#>
 
 param(
     [string] $Exceptions
@@ -6,17 +23,27 @@ param(
 
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version 3.0
+
+# Setup paths and helpers
 $packageRoot = (Resolve-Path "$PSScriptRoot/../..").Path.Replace('\', '/')
 . "$packageRoot/../../eng/emitters/scripts/CommandInvocation-Helpers.ps1"
 Set-ConsoleEncoding
 
-$diffExcludes = @(
+# Files to exclude from diff check (these may change during npm operations)
+$excludedFiles = @(
     "$packageRoot/package.json"
     "$packageRoot/package-lock.json"
-) | ForEach-Object { "`":(exclude)$_`"" } | Join-String -Separator ' '
+)
 
+$diffExcludes = $excludedFiles | ForEach-Object { "`":(exclude)$_`"" } | Join-String -Separator ' '
+
+# Check for changes, ignoring whitespace differences at end of lines
 Invoke-LoggedCommand "git -c core.safecrlf=false diff --ignore-space-at-eol --exit-code -- $diffExcludes" -IgnoreExitCode
 
-if($LastExitCode -ne 0) {
+if ($LastExitCode -ne 0) {
+    Write-Host "`nUncommitted changes detected!" -ForegroundColor Red
+    Write-Host "Run 'npm run regenerate' locally and commit the changes."
     throw "Changes detected"
 }
+
+Write-Host "No changes detected." -ForegroundColor Green

package/eng/scripts/Functions.ps1

@@ -1,26 +1,65 @@
-# Return list of nupkg artifacts
-function Get-Package-Artifacts ($location, $filter)
-{
-    $filterToUse = $filter.StartsWith("typespec-") ? $filter.SubString(0, $filter.Length - 1) + ".api.json" : $filter
+<#
+.SYNOPSIS
+    Helper functions for finding package artifacts.
+
+.DESCRIPTION
+    These functions are used by the publishing pipeline to locate
+    built package artifacts for API review and publishing.
+#>
+
+<#
+.SYNOPSIS
+    Gets package artifacts from a directory.
+
+.PARAMETER location
+    The directory containing the packages folder.
+
+.PARAMETER filter
+    Filter pattern for matching package files.
+#>
+function Get-Package-Artifacts {
+    param(
+        [string] $location,
+        [string] $filter
+    )
+
+    # Convert typespec package filter to API json filter
+    $filterToUse = if ($filter.StartsWith("typespec-")) {
+        $filter.SubString(0, $filter.Length - 1) + ".api.json"
+    } else {
+        $filter
+    }
 
     $packages = Get-ChildItem -Path "$location/packages" -Filter $filterToUse -Recurse
-    if (!$packages)
-    {
-        Write-Host "$($location)/packages does not have any packages matching filter $($filterToUse)"
+    if (!$packages) {
+        Write-Host "$location/packages does not have any packages matching filter $filterToUse"
         return $null
     }
+
     return $packages[0]
 }
 
-function Find-Artifacts-For-Apireview($artifactDir, $packageName)
-{
-    # Find all nupkg files in given artifact directory
+<#
+.SYNOPSIS
+    Finds artifacts for API review.
+
+.PARAMETER artifactDir
+    Directory containing build artifacts.
+
+.PARAMETER packageName
+    Name of the package to find.
+#>
+function Find-Artifacts-For-Apireview {
+    param(
+        [string] $artifactDir,
+        [string] $packageName
+    )
+
     $package = Get-Package-Artifacts $artifactDir "$packageName*"
-    if (!$package)
-    {
-        Write-Host "Package is not available in artifact path $($artifactDir)/packages"
+    if (!$package) {
+        Write-Host "Package is not available in artifact path $artifactDir/packages"
         return $null
     }
-    $packages = @{ $package.Name = $package.FullName }
-    return $packages
+
+    return @{ $package.Name = $package.FullName }
 }

package/eng/scripts/Generate.ps1

@@ -1,14 +1,48 @@
 #Requires -Version 7.0
+<#
+.SYNOPSIS
+    Regenerates all test fixtures and documentation.
 
-Import-Module "$PSScriptRoot\Generation.psm1" -DisableNameChecking -Force;
+.DESCRIPTION
+    This script is called by the CI pipeline to regenerate test outputs.
+    It runs:
+      1. npm run build       - Compile TypeScript emitter and build Python wheel
+      2. npm run regenerate  - Regenerate all test fixtures from TypeSpec files
+      3. npm run regen-docs  - Regenerate API documentation
 
-$repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '..')
+.EXAMPLE
+    ./Generate.ps1
+#>
 
-Write-Host "Building project ..."
-& npm run build
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version 3.0
 
-Write-Host "Regenerating project ..."
-& npm run regenerate
+# Setup paths
+$packageRoot = (Resolve-Path "$PSScriptRoot/../..").Path.Replace('\', '/')
 
-Write-Host "Regenerating docs ..."
-& npm run regen-docs
+Push-Location "$packageRoot"
+try {
+    Write-Host "=== Building project ===" -ForegroundColor Cyan
+    & npm run build
+    if ($LASTEXITCODE -ne 0) { throw "Build failed" }
+
+    Write-Host "`n=== Regenerating test fixtures ===" -ForegroundColor Cyan
+    & npm run regenerate
+    if ($LASTEXITCODE -ne 0) { throw "Regeneration failed" }
+
+    Write-Host "`n=== Regenerating documentation ===" -ForegroundColor Cyan
+    # Check if tspd is available (requires full monorepo build)
+    $tspdCli = Join-Path $packageRoot "../../packages/tspd/dist/src/cli.js"
+    if (Test-Path $tspdCli) {
+        & npm run regen-docs
+        if ($LASTEXITCODE -ne 0) { throw "Documentation regeneration failed" }
+    } else {
+        Write-Host "Skipping documentation regeneration (tspd not built)" -ForegroundColor Yellow
+        Write-Host "Run from monorepo root with full build to regenerate docs" -ForegroundColor Yellow
+    }
+
+    Write-Host "`n=== Generation complete ===" -ForegroundColor Green
+}
+finally {
+    Pop-Location
+}

package/eng/scripts/Generation.psm1

@@ -1,22 +1,51 @@
+<#
+.SYNOPSIS
+    PowerShell module with helper functions for generation scripts.
+
+.DESCRIPTION
+    This module provides the Invoke function for running shell commands
+    cross-platform (Windows, Linux, macOS).
+#>
+
 $repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..')
 
-function Invoke($command, $executePath=$repoRoot)
-{
-    Write-Host "> $command"
+<#
+.SYNOPSIS
+    Invokes a shell command cross-platform.
+
+.PARAMETER command
+    The command to execute.
+
+.PARAMETER executePath
+    The directory to execute the command in. Defaults to repo root.
+
+.EXAMPLE
+    Invoke "npm run build"
+#>
+function Invoke {
+    param(
+        [string] $command,
+        [string] $executePath = $repoRoot
+    )
+
+    Write-Host "> $command" -ForegroundColor Cyan
+
     Push-Location $executePath
-    if ($IsLinux -or $IsMacOs)
-    {
-        sh -c "$command 2>&1"
-    }
-    else
-    {
-        cmd /c "$command 2>&1"
-    }
-    Pop-Location
+    try {
+        if ($IsLinux -or $IsMacOs) {
+            sh -c "$command 2>&1"
+        }
+        else {
+            cmd /c "$command 2>&1"
+        }
 
-    if($LastExitCode -ne 0)
-    {
-        Write-Error "Command failed to execute: $command"
+        if ($LastExitCode -ne 0) {
+            throw "Command failed: $command"
+        }
+    }
+    finally {
+        Pop-Location
     }
 }
+
 Export-ModuleMember -Function "Invoke"

package/eng/scripts/Initialize-Repository.ps1

@@ -1,4 +1,21 @@
 #Requires -Version 7.0
+<#
+.SYNOPSIS
+    Initializes the repository by installing npm dependencies.
+
+.DESCRIPTION
+    This script is called by the CI pipeline to set up the repository.
+    It runs `npm ci` to install dependencies from package-lock.json.
+
+.PARAMETER BuildArtifactsPath
+    Optional path to build artifacts (used in CI for caching lock files).
+
+.PARAMETER UseTypeSpecNext
+    Optional switch for using TypeSpec next version (not currently used).
+
+.EXAMPLE
+    ./Initialize-Repository.ps1
+#>
 
 param(
     [string] $BuildArtifactsPath,
@@ -7,32 +24,33 @@ param(
 
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version 3.0
+
+# Setup paths and helpers
 $packageRoot = (Resolve-Path "$PSScriptRoot/../..").Path.Replace('\', '/')
 . "$packageRoot/../../eng/emitters/scripts/CommandInvocation-Helpers.ps1"
 Set-ConsoleEncoding
 
 Push-Location "$packageRoot"
 try {
+    # Clean install of npm dependencies
     if (Test-Path "./node_modules") {
+        Write-Host "Removing existing node_modules..."
         Remove-Item -Recurse -Force "./node_modules"
     }
 
-    # install and list npm packages
-  
+    Write-Host "Installing npm dependencies..."
     Invoke-LoggedCommand "npm ci"
-
     Invoke-LoggedCommand "npm ls -a" -GroupOutput
 
-    Write-Host "artifactStagingDirectory: $env:BUILD_ARTIFACTSTAGINGDIRECTORY"
-    Write-Host "BuildArtifactsPath: $BuildArtifactsPath"
+    # Copy lock files to artifacts for CI caching (if running in Azure DevOps)
     $artifactStagingDirectory = $env:BUILD_ARTIFACTSTAGINGDIRECTORY
     if ($artifactStagingDirectory -and !$BuildArtifactsPath) {
-        $lockFilesPath = "$artifactStagingDirectory/lock-files"
-        New-Item -ItemType Directory -Path "$lockFilesPath/emitter" | Out-Null
-        
-        Write-Host "Copying emitter/package.json and emitter/package-lock.json to $lockFilesPath"
-        Copy-Item './package.json' "$lockFilesPath/emitter/package.json" -Force
-        Copy-Item './package-lock.json' "$lockFilesPath/emitter/package-lock.json" -Force
+        $lockFilesPath = "$artifactStagingDirectory/lock-files/emitter"
+        New-Item -ItemType Directory -Path $lockFilesPath -Force | Out-Null
+
+        Write-Host "Copying lock files to $lockFilesPath"
+        Copy-Item './package.json' "$lockFilesPath/package.json" -Force
+        Copy-Item './package-lock.json' "$lockFilesPath/package-lock.json" -Force
     }
 }
 finally {

package/eng/scripts/Test-Packages.ps1

@@ -1,4 +1,32 @@
 #Requires -Version 7.0
+<#
+.SYNOPSIS
+    Runs tests for the TypeSpec Python emitter.
+
+.DESCRIPTION
+    This script is called by the CI pipeline to run tests.
+
+    With -UnitTests:
+      - Runs npm run build (compile emitter)
+
+    With -GenerationChecks:
+      - Runs npm run build (compile emitter)
+      - Runs Generate.ps1 (regenerate test fixtures)
+      - Runs Check-GitChanges.ps1 (verify no uncommitted changes)
+      - Runs npm run ci (full test suite: pytest, lint, mypy, pyright)
+
+.PARAMETER UnitTests
+    Run unit tests only (just builds the project).
+
+.PARAMETER GenerationChecks
+    Run full generation checks and test suite.
+
+.PARAMETER Filter
+    Optional filter pattern for tests (not currently used).
+
+.EXAMPLE
+    ./Test-Packages.ps1 -GenerationChecks
+#>
 
 param(
     [switch] $UnitTests,
@@ -7,57 +35,45 @@ param(
 )
 
 $ErrorActionPreference = 'Stop'
-
 Set-StrictMode -Version 3.0
+
+# Setup paths and helpers
 $packageRoot = (Resolve-Path "$PSScriptRoot/../..").Path.Replace('\', '/')
 . "$packageRoot/../../eng/emitters/scripts/CommandInvocation-Helpers.ps1"
 Set-ConsoleEncoding
 
+Write-Host "Python version:"
 Invoke-LoggedCommand "python --version"
 
 Push-Location $packageRoot
 try {
     if ($UnitTests) {
-        Push-Location "$packageRoot"
-        try {
-
-            Write-Host "Updated PATH: $env:PATH"
-            # test the emitter
-            Invoke-LoggedCommand "npm run build" -GroupOutput
-            
-        }
-        finally {
-            Pop-Location
-        }
+        Write-Host "`n=== Running unit tests ===" -ForegroundColor Cyan
+        Invoke-LoggedCommand "npm run build" -GroupOutput
     }
+
     if ($GenerationChecks) {
-        Set-StrictMode -Version 1
-        
-        # run E2E Test for TypeSpec emitter
-        Write-Host "Generating test projects ..."
+        # Step 1: Regenerate all test fixtures
+        Write-Host "`n=== Regenerating test fixtures ===" -ForegroundColor Cyan
         & "$packageRoot/eng/scripts/Generate.ps1"
-        Write-Host 'Code generation is completed.'
 
+        # Step 2: Check for uncommitted changes (regeneration should be clean)
+        Write-Host "`n=== Checking for uncommitted changes ===" -ForegroundColor Cyan
         try {
-            Write-Host 'Checking for differences in generated code...'
             & "$packageRoot/eng/scripts/Check-GitChanges.ps1"
-            Write-Host 'Done. No code generation differences detected.'
+            Write-Host "No uncommitted changes detected." -ForegroundColor Green
         }
         catch {
-            Write-Error 'Generated code is not up to date. Please run: eng/Generate.ps1'
+            Write-Error "Generated code is not up to date. Please run: npm run regenerate"
         }
 
-        try {
-            Write-Host "Pip List" 
-            & pip list
-            # Run tox
-            Write-Host 'Running tests'
-            & npm run ci
-            Write-Host 'tox tests passed'
-        } 
-        catch {
-            Write-Error "Spector tests failed:  $_"
-        }
+        # Step 3: Run full test suite
+        Write-Host "`n=== Running full test suite ===" -ForegroundColor Cyan
+        Write-Host "Installed packages:"
+        & pip list
+
+        Invoke-LoggedCommand "npm run ci"
+        Write-Host "All tests passed." -ForegroundColor Green
     }
 }
 finally {

package/eng/scripts/ci/config/eslint-ci.config.mjs

@@ -0,0 +1,54 @@
+// @ts-check
+// Standalone eslint config for http-client-python package
+// This config is used in CI where monorepo dependencies may not be available
+import eslint from "@eslint/js";
+import tsEslint from "typescript-eslint";
+
+export default [
+  {
+    ignores: ["**/dist/**/*", "**/node_modules/**/*"],
+  },
+  eslint.configs.recommended,
+  ...tsEslint.configs.recommended,
+  {
+    rules: {
+      // TypeScript plugin overrides
+      "@typescript-eslint/no-non-null-assertion": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-inferrable-types": "off",
+      "@typescript-eslint/no-empty-function": "off",
+      "@typescript-eslint/no-empty-interface": "off",
+      "@typescript-eslint/no-empty-object-type": "off",
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          varsIgnorePattern: "^_",
+          argsIgnorePattern: ".*",
+          ignoreRestSiblings: true,
+          caughtErrorsIgnorePattern: ".*",
+        },
+      ],
+      "@typescript-eslint/no-unused-expressions": [
+        "warn",
+        { allowShortCircuit: true, allowTernary: true },
+      ],
+
+      // Core rules
+      "no-inner-declarations": "off",
+      "no-empty": "off",
+      "no-constant-condition": "off",
+      "no-case-declarations": "off",
+      "no-ex-assign": "off",
+      "no-undef": "off",
+      "prefer-const": [
+        "warn",
+        {
+          destructuring: "all",
+        },
+      ],
+      eqeqeq: ["warn", "always", { null: "ignore" }],
+      "no-console": "warn",
+      "symbol-description": "warn",
+    },
+  },
+];

package/eng/scripts/ci/dev_requirements.txt

@@ -1,6 +1,7 @@
 pyright==1.1.407
 pylint==4.0.4
 tox==4.16.0
+tox-uv
 mypy==1.19.1
 colorama==0.4.6
 debugpy==1.8.2