### Usage Examples for useCpythonVersion

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-python.md

Demonstrates how to use the `useCpythonVersion` function to install different CPython versions. Examples include installing the latest 3.11, a specific 3.12.1 with latest check, and a free-threaded 3.13.

```typescript
import * as finder from './find-python';

// Install latest Python 3.11
const result = await finder.useCpythonVersion(
  '3.11',
  'x64',
  true,
  false,
  false,
  false
);
console.log(result.version); // e.g., '3.11.5'

// Install specific version with check-latest
const result = await finder.useCpythonVersion(
  '3.12.1',
  'x64',
  true,
  true,
  false,
  false
);

// Install free-threaded Python 3.13
const result = await finder.useCpythonVersion(
  '3.13',
  'x64',
  true,
  false,
  false,
  true
);
```

--------------------------------

### Install Dependencies with setup-python

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Use the `pip-install` input to install dependencies directly during the Python setup step. This is suitable for standard pip-based installations.

```yaml
      steps:
      - uses: actions/checkout@v6
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.13'
          pip-install: -r requirements.txt
```

--------------------------------

### Usage Example: Install Latest GraalPy 24 Release

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-graalpy.md

Shows how to install the latest available GraalPy 24.x release for 'x64' architecture, ensuring you get the most recent stable version. This is useful when you need the latest features without specifying an exact patch version.

```typescript
// Install latest GraalPy 24 release
const latestVersion = await findGraalPyVersion(
  'graalpy24',
  'x64',
  true,
  true,
  false
);
```

--------------------------------

### Setup Python with Pip Caching

Source: https://github.com/actions/setup-python/blob/main/_autodocs/configuration.md

This example demonstrates how to set up a specific Python version and enable caching for pip dependencies. It also shows how to access the action's outputs for cache status, resolved Python version, and the Python executable path.

```yaml
- uses: actions/setup-python@v6
  with:
    python-version: '3.11'
    cache: 'pip'
  id: setup-py

- name: Check cache hit
  run: echo "Cache hit: ${{ steps.setup-py.outputs.cache-hit }}"

- name: Use resolved version
  run: echo "Python: ${{ steps.setup-py.outputs.python-version }}"

- name: Use Python executable
  run: ${{ steps.setup-py.outputs.python-path }} --version
```

--------------------------------

### Usage Example: Install GraalPy Version 24.0

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-graalpy.md

Demonstrates how to install a specific GraalPy version (24.0) for the 'x64' architecture, updating the environment. This is a common use case for setting up a project with a known GraalPy version.

```typescript
import {findGraalPyVersion} from './find-graalpy';

// Install GraalPy version 24.0
const version = await findGraalPyVersion(
  'graalpy24.0',
  'x64',
  true,
  false,
  false
);
console.log(`Installed GraalPy ${version}`);
```

--------------------------------

### Usage Example: Allow Prerelease GraalPy Versions

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-graalpy.md

Illustrates how to install a GraalPy version, allowing prerelease versions to be matched if no stable version is found. This is helpful for testing or using the newest, potentially unstable, features.

```typescript
// Allow prerelease versions
const prerelease = await findGraalPyVersion(
  'graalpy24',
  'x64',
  true,
  false,
  true
);
```

--------------------------------

### Install CPython from Release

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-python.md

Downloads and installs CPython from a release manifest entry. Handles extraction and running platform-specific installation scripts.

```typescript
import {findReleaseFromManifest, installCpythonFromRelease} from './install-python';

const release = await findReleaseFromManifest('3.12.1', 'x64', null);
if (release) {
  try {
    await installCpythonFromRelease(release);
    console.log('Installation completed successfully');
  } catch (err) {
    console.error(`Installation failed: ${err.message}`);
  }
}
```

--------------------------------

### installCpythonFromRelease

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-python.md

Downloads and installs CPython from a release manifest entry. It handles downloading the archive, extracting it, and running the platform-specific installation script.

```APIDOC
## installCpythonFromRelease()

### Description
Downloads and installs CPython from a release manifest entry. This function handles the entire process from downloading the release archive to executing the installation script.

### Method
`async installCpythonFromRelease(release: tc.IToolRelease): Promise<void>`

### Parameters
#### Path Parameters
- **release** (tc.IToolRelease) - Required - Release object obtained from `findReleaseFromManifest()`.

### Behavior
1. Extracts the first file's download URL from the release.
2. Downloads the archive using `tc.downloadTool()`.
3. Extracts the archive (using `tc.extractZip()` for Windows and `tc.extractTar()` for Unix-like systems).
4. Executes the platform-specific installation script (`./setup.ps1` on Windows, `./setup.sh` on Unix).
5. Sets up the environment for installation (e.g., `LD_LIBRARY_PATH` on Linux).
6. Logs all stdout/stderr output during installation.

### Throws
- **Error**: If there are no files in the release.
- **tc.HTTPError (403)**: If access is denied or restricted.
- **tc.HTTPError (429)**: If the rate limit is exceeded.
- **Error**: If download, extraction, or script execution fails.

### Usage Example
```typescript
import {findReleaseFromManifest, installCpythonFromRelease} from './install-python';

const release = await findReleaseFromManifest('3.12.1', 'x64', null);
if (release) {
  try {
    await installCpythonFromRelease(release);
    console.log('Installation completed successfully');
  } catch (err) {
    console.error(`Installation failed: ${err.message}`);
  }
}
```
```

--------------------------------

### Main Action Flow

Source: https://github.com/actions/setup-python/blob/main/_autodocs/architecture.md

Illustrates the sequence of operations for the main setup-python action, from version resolution to package installation.

```typescript
setup-python.ts:run()
├── Resolve version input
│   ├── From --python-version input (multiline)
│   ├── Or from --python-version-file
│   └── Or default .python-version file
├── For each version:
│   ├── Detect type (CPython / PyPy / GraalPy)
│   └── Find and install:
│       ├── CPython → find-python.ts:useCpythonVersion()
│       ├── PyPy → find-pypy.ts:findPyPyVersion()
│       └── GraalPy → find-graalpy.ts:findGraalPyVersion()
├── Set environment variables and PATH
├── Handle caching:
│   └── cache-factory.ts:getCacheDistributor()
│       ├── Create PipCache / PipenvCache / PoetryCache
│       └── Call restoreCache()
└── Install pip packages (if --pip-install specified)
```

--------------------------------

### Required Permissions for Setup Python Action

Source: https://github.com/actions/setup-python/blob/main/_autodocs/configuration.md

Specifies the minimal permissions required for the actions/setup-python action to function correctly. This includes read access for checking out code and installing dependencies.

```yaml
permissions:
  contents: read  # Access to check out code and install dependencies
```

--------------------------------

### Python Installation Functions

Source: https://github.com/actions/setup-python/blob/main/_autodocs/INDEX.txt

Functions responsible for installing Python versions from manifests and releases. This includes fetching manifests, finding specific releases, and performing the actual installation for CPython, PyPy, and GraalPy.

```APIDOC
## Python Installation

### CPython Installation

- **getManifest()**: Fetches the CPython manifest.
- **getManifestFromRepo()**: Retrieves manifest from the GitHub repository.
- **getManifestFromURL()**: Fallback to fetch manifest from a raw URL.
- **findReleaseFromManifest()**: Searches the manifest for a suitable release.
- **installCpythonFromRelease()**: Downloads and installs a CPython release.

### PyPy Installation

- **installPyPy()**: Downloads and installs PyPy.
- **getAvailablePyPyVersions()**: Fetches a list of available PyPy versions.
- **findRelease()**: Finds a matching PyPy release based on criteria.
- **pypyVersionToSemantic()**: Converts PyPy version to semantic format.

### GraalPy Installation

- **installGraalPy()**: Downloads and installs GraalPy.
- **getAvailableGraalPyVersions()**: Fetches available GraalPy versions from GitHub.
- **findRelease()**: Finds a matching GraalPy release.
- **Version conversion functions**: Utility functions for version format conversion.
- **Platform/architecture helpers**: Functions for platform and architecture specific operations.
```

--------------------------------

### Install PyPy

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-pypy.md

Downloads and installs a specified PyPy version. Use this when you need to programmatically install PyPy for a specific Python version and architecture. It handles fetching releases, downloading, extraction, caching, and setting up symlinks.

```typescript
import {installPyPy, getAvailablePyPyVersions} from './install-pypy';

// Install without pre-fetching releases
const result = await installPyPy(
  '7.3.13',
  '3.10',
  'x64',
  false,
  undefined
);
console.log(`Installed at ${result.installDir}`);

// Pre-fetch releases and install
const releases = await getAvailablePyPyVersions();
const result = await installPyPy(
  '7.3.x',
  '3.11',
  'x64',
  false,
  releases
);
```

--------------------------------

### Download and Set Up Multiple Python and PyPy Versions

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Example workflow for setting up a mix of Python and PyPy versions. This is useful for comprehensive testing across different runtimes.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-python@v6
      with:
        python-version: |
            3.11
            3.12
            pypy3.10-nightly
            pypy3.10
            3.13
    - run: python my_script.py
```

--------------------------------

### Install GraalPy Version

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-graalpy.md

Downloads and installs a specified GraalPy version. It can optionally pre-fetch releases and allow prereleases. The function returns the installation directory and the resolved version.

```typescript
export async function installGraalPy(
  graalpyVersion: string,
  architecture: string,
  allowPreReleases: boolean,
  releases: IGraalPyManifestRelease[] | undefined
): Promise<{
  installDir: string;
  resolvedGraalPyVersion: string;
}>
```

```typescript
import {installGraalPy, getAvailableGraalPyVersions} from './install-graalpy';

// Install without pre-fetching releases
const result = await installGraalPy(
  '24.0',
  'x64',
  false,
  undefined
);
console.log(`Installed at ${result.installDir}`);

// Pre-fetch releases and install
const releases = await getAvailableGraalPyVersions();
const result = await installGraalPy(
  '24',
  'x64',
  false,
  releases
);
```

--------------------------------

### Usage Example: Find GraalPy in Tool Cache

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-graalpy.md

Demonstrates checking the tool cache for a specific GraalPy version ('24.0' for 'x64') and logging its location if found. This is useful for optimizing build times by reusing cached installations.

```typescript
import {findGraalPyToolCache} from './find-graalpy';

const {installDir, resolvedGraalPyVersion} = findGraalPyToolCache(
  '24.0',
  'x64'
);

if (installDir) {
  console.log(`Found GraalPy ${resolvedGraalPyVersion} at ${installDir}`);
} else {
  console.log('GraalPy not found in cache');
}
```

--------------------------------

### Recommended Permissions for Setup-Python

Source: https://github.com/actions/setup-python/blob/main/README.md

Set read permissions for contents when using the setup-python action to allow checking out code and installing dependencies.

```yaml
permissions:
  contents: read # access to check out code and install dependencies
```

--------------------------------

### getBinaryDirectory

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/utils.md

Gets the directory containing the Python executable for a given installation path. This is useful for locating the main Python binary.

```APIDOC
## getBinaryDirectory()

### Description
Gets the directory containing Python executable for a given installation.

### Parameters
#### Path Parameters
- **installDir** (string) - Required - Python installation directory path

### Return Type
string — Path to binary directory

### Behavior
- Windows: Returns `installDir` (executables at root)
- Unix: Returns `path.join(installDir, 'bin')`
```

--------------------------------

### Get Available PyPy Versions

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-pypy.md

Fetches a list of all available PyPy releases from the official PyPy repository. Use this to get a comprehensive list of PyPy versions and their bundled Python versions before installing.

```typescript
import {getAvailablePyPyVersions} from './install-pypy';

const releases = await getAvailablePyPyVersions();
console.log(`Found ${releases.length} PyPy releases`);

releases.forEach(release => {
  console.log(`PyPy ${release.pypy_version} with Python ${release.python_version}`);
});
```

--------------------------------

### Get Exact Python Version with python-version Output

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Use the `python-version` output to get the precise Python or PyPy version installed by the action. This is useful when the input `python-version` is a range and you need the exact installed version for conditional logic.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-python@v6
      id: cp312
      with:
        python-version: "3.9.0 - 3.12.0"
    - run: echo '${{ steps.cp312.outputs.python-version }}'
```

--------------------------------

### Install PyPy 3.10

Source: https://github.com/actions/setup-python/blob/main/README.md

Installs PyPy version 3.10. Ensure actions/checkout@v6 is used prior to this step.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6 
  with:
    python-version: 'pypy3.10'
- run: python my_script.py
```

--------------------------------

### Download and Set Up Multiple Python Versions

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Example of a GitHub Actions workflow to set up multiple Python versions. The last specified version in the list will be used as the default.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-python@v6
      with:
        python-version: |
            3.11
            3.12
            3.13
    - run: python my_script.py
```

--------------------------------

### Specify Python Version with Prerelease Tag

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Use this to install and set up an accurate pre-release version of Python.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.14.0-alpha.1'
- run: python my_script.py
```

--------------------------------

### Cache Projects Using setup.py

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Configure `cache: 'pip'` and `cache-dependency-path: setup.py` to cache dependencies for projects that use `setup.py` for installation.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.13'
    cache: 'pip'
    cache-dependency-path: setup.py
- run: pip install -e .
  # Or pip install -e '.[test]' to install test dependencies
```

--------------------------------

### Install GraalPy 24.0

Source: https://github.com/actions/setup-python/blob/main/README.md

Installs GraalPy version 24.0. Ensure actions/checkout@v6 is used prior to this step.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6 
  with:
    python-version: 'graalpy-24.0'
- run: python my_script.py
```

--------------------------------

### installPyPy

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-pypy.md

Downloads and installs a specified PyPy version along with a compatible Python version. It handles fetching releases, downloading archives, extracting them, caching the installation, and setting up necessary symlinks and pip.

```APIDOC
## installPyPy()

### Description
Downloads and installs a PyPy version from the PyPy distribution.

### Method Signature
```typescript
installPyPy(
  pypyVersion: string,
  pythonVersion: string,
  architecture: string,
  allowPreReleases: boolean,
  releases: IPyPyManifestRelease[] | undefined
): Promise<{ installDir: string; resolvedPythonVersion: string; resolvedPyPyVersion: string }>
```

### Parameters

#### Parameters
- **pypyVersion** (string) - Required - PyPy version spec using SemVer syntax (e.g., `7.3.x`, `7.3.13`) or `nightly`
- **pythonVersion** (string) - Required - Python version in `x.y` format (e.g., `3.10`, `3.11`)
- **architecture** (string) - Required - Target architecture: `x86`, `x64`, or `arm64`
- **allowPreReleases** (boolean) - Required - If true, allows matching prerelease PyPy versions when no stable version is found
- **releases** (IPyPyManifestRelease[] | undefined) - Required - Array of available PyPy releases, or undefined to fetch automatically

### Return Type

#### Return Value
- **installDir** (string) - Absolute path to installed PyPy directory
- **resolvedPythonVersion** (string) - Resolved Python version (e.g., `3.10`)
- **resolvedPyPyVersion** (string) - Resolved PyPy version (e.g., `7.3.13`)

### Behavior
1. If releases is undefined, fetches available versions from PyPy manifest
2. Searches for a matching release using `findRelease()` with `includePrerelease=false`
3. If not found and `allowPreReleases=true`, searches again with `includePrerelease=true`
4. Downloads the matching release archive
5. Extracts the archive (zip on Windows, tar on Unix)
6. Caches the installation using `tc.cacheDir()` (unless version is nightly)
7. Creates PyPy binary symlinks (e.g., `python3`, `python3.10`, `pypy3`)
8. Installs and updates pip using `ensurepip` and pip upgrade

### Throws
- **Error**: No releases found in PyPy version.json
- **Error**: PyPy version not found for specified Python version and architecture
- **tc.HTTPError (403 or 429)**: Rate limit exceeded or permission denied
- **Error**: Download, extraction, or installation fails

### Usage Example
```typescript
import {installPyPy, getAvailablePyPyVersions} from './install-pypy';

// Install without pre-fetching releases
const result = await installPyPy(
  '7.3.13',
  '3.10',
  'x64',
  false,
  undefined
);
console.log(`Installed at ${result.installDir}`);

// Pre-fetch releases and install
const releases = await getAvailablePyPyVersions();
const result = await installPyPy(
  '7.3.x',
  '3.11',
  'x64',
  false,
  releases
);
```
```

--------------------------------

### Find and Install PyPy Version

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-pypy.md

Finds and installs a PyPy version, downloading it if not found in the tool cache. Use this to ensure a specific PyPy version is available for your project.

```typescript
export async function findPyPyVersion(
  versionSpec: string,
  architecture: string,
  updateEnvironment: boolean,
  checkLatest: boolean,
  allowPreReleases: boolean
): Promise<{resolvedPyPyVersion: string; resolvedPythonVersion: string}>
```

```typescript
{ resolvedPyPyVersion: string;
  resolvedPythonVersion: string;
}
```

```typescript
import {findPyPyVersion} from './find-pypy';

// Install PyPy with Python 3.10, any PyPy version
const result = await findPyPyVersion(
  'pypy3.10',
  'x64',
  true,
  false,
  false
);
console.log(`PyPy ${result.resolvedPyPyVersion} with Python ${result.resolvedPythonVersion}`);

// Install specific PyPy version
const result = await findPyPyVersion(
  'pypy-3.10-7.3.13',
  'x64',
  true,
  false,
  false
);

// Use check-latest to get newest version
const result = await findPyPyVersion(
  'pypy3.11',
  'x64',
  true,
  true,
  false
);
```

--------------------------------

### Setup Python Action File Organization

Source: https://github.com/actions/setup-python/blob/main/_autodocs/README.md

This snippet displays the directory structure of the setup-python GitHub Action project. It helps understand the location of source files, build artifacts, and tests.

```tree
setup-python/
├── src/                          # TypeScript source
│   ├── setup-python.ts           # Main action entry point
│   ├── cache-save.ts             # Post action entry point
│   ├── find-python.ts            # CPython finding
│   ├── find-pypy.ts              # PyPy finding
│   ├── find-graalpy.ts           # GraalPy finding
│   ├── install-python.ts         # CPython installation
│   ├── install-pypy.ts           # PyPy installation
│   ├── install-graalpy.ts        # GraalPy installation
│   ├── utils.ts                  # Shared utilities
│   └── cache-distributions/
│       ├── cache-factory.ts      # Factory function
│       ├── cache-distributor.ts  # Abstract base class
│       ├── pip-cache.ts          # Pip caching
│       ├── pipenv-cache.ts       # Pipenv caching
│       ├── poetry-cache.ts       # Poetry caching
│       └── constants.ts          # Cache constants
├── action.yml                    # Action manifest
├── dist/                         # Compiled output (build artifacts)
└── __tests__/                    # Unit tests
```

--------------------------------

### Usage Examples for desugarVersion

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-python.md

Illustrates the usage of `desugarVersion` to parse version strings. Examples show how to extract the version and freethreaded status from inputs like '3.13t' and '3.13.1t-dev'.

```typescript
import {desugarVersion} from './find-python';

const {version, freethreaded} = desugarVersion('3.13t');
// version: '3.13', freethreaded: true

const {version: v2, freethreaded: f2} = desugarVersion('3.13.1t-dev');
// v2: '3.13.1-dev', f2: true

const {version: v3, freethreaded: f3} = desugarVersion('3.11-dev');
// v3: '3.11-dev', f3: false
```

--------------------------------

### Install Python 3.13

Source: https://github.com/actions/setup-python/blob/main/README.md

Installs Python version 3.13. Ensure actions/checkout@v6 is used prior to this step.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.13'
- run: python my_script.py
```

--------------------------------

### installGraalPy() Return Type

Source: https://github.com/actions/setup-python/blob/main/_autodocs/types.md

This object is returned by the `installGraalPy()` function. It contains the installation directory and the resolved GraalPy version.

```typescript
{
  installDir: string;
  resolvedGraalPyVersion: string;
}
```

--------------------------------

### Install Free-threaded Python 3.13

Source: https://github.com/actions/setup-python/blob/main/README.md

Installs a free-threaded build of Python version 3.13. Ensure actions/checkout@v6 is used prior to this step.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.13t'
- run: python my_script.py
```

--------------------------------

### installGraalPy()

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/install-graalpy.md

Downloads and installs a GraalPy version from the GraalVM GitHub releases. It handles fetching releases, finding the correct version for the specified architecture, downloading, extracting, caching, and setting up symlinks.

```APIDOC
## `installGraalPy()`

### Description
Downloads and installs a GraalPy version from the GraalVM GitHub releases. It handles fetching releases, finding the correct version for the specified architecture, downloading, extracting, caching, and setting up symlinks.

### Parameters
#### Path Parameters
- **graalpyVersion** (string) - Required - GraalPy version spec using SemVer syntax (e.g., `24.0`, `24`, `24.1.0`) or `nightly`
- **architecture** (string) - Required - Target architecture: `x86`, `x64`, or `arm64`
- **allowPreReleases** (boolean) - Required - If true, allows matching prerelease GraalPy versions when no stable version is found
- **releases** (IGraalPyManifestRelease[] | undefined) - Required - Array of available GraalPy releases, or undefined to fetch automatically

### Return Type
- **installDir** (string) - Absolute path to installed GraalPy directory
- **resolvedGraalPyVersion** (string) - Resolved GraalPy version (e.g., `24.0`)

### Throws
- **Error** - No releases found in GraalPy
- **Error** - GraalPy version not found for specified architecture
- **tc.HTTPError (403 or 429)** - Rate limit exceeded or permission denied
- **Error** - Download, extraction, or installation fails

### Usage Example
```typescript
import {installGraalPy} from './install-graalpy';

const result = await installGraalPy(
  '24.0',
  'x64',
  false,
  undefined
);
console.log(`Installed at ${result.installDir}`);
```
```

--------------------------------

### getOSInfo

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/utils.md

Gets the current operating system name and version.

```APIDOC
## getOSInfo()

### Description
Gets the current operating system name and version.

### Return Type
Object with `osName` and `osVersion`, or undefined if detection fails

### Behavior
1. On Windows: Runs PowerShell to get `Win32_OperatingSystem` Caption
2. On macOS: Runs `sw_vers -productVersion`
3. On Linux: Runs `lsb_release -i -r -s`
4. Returns undefined if any error occurs

### Usage
Used by caching to include OS information in cache keys for better cache isolation.
```

--------------------------------

### Find and Install GraalPy Version

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-graalpy.md

Finds and installs a specified GraalPy version. It can update environment variables and the PATH, check for the latest releases, and allow pre-release versions. Use this when you need to ensure a specific GraalPy version is available and configured on the runner.

```typescript
export async function findGraalPyVersion(
  versionSpec: string,
  architecture: string,
  updateEnvironment: boolean,
  checkLatest: boolean,
  allowPreReleases: boolean
): Promise<string>
```

--------------------------------

### installPyPy() Return Type

Source: https://github.com/actions/setup-python/blob/main/_autodocs/types.md

This object is returned by the `installPyPy()` function. It includes the installation directory and the resolved versions of Python and PyPy.

```typescript
{
  installDir: string;
  resolvedPythonVersion: string;
  resolvedPyPyVersion: string;
}
```

--------------------------------

### Cache Poetry Dependencies

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Configure the `cache: 'poetry'` input to cache Poetry dependencies. Ensure Poetry is installed before running `poetry install`.

```yaml
steps:
- uses: actions/checkout@v6
- name: Install poetry
  run: pipx install poetry
- uses: actions/setup-python@v6
  with:
    python-version: '3.13'
    cache: 'poetry'
- run: poetry install
- run: poetry run pytest
```

--------------------------------

### PoetryCache Usage Example

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/cache.md

Demonstrates how to instantiate and use the PoetryCache to restore a cache for a specific Python version. Ensure the PoetryCache class is imported.

```typescript
import PoetryCache from './cache-distributions/poetry-cache';

const cache = new PoetryCache('3.11.5');
await cache.restoreCache();
```

--------------------------------

### Matrix Testing with Version Exclusion

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Example of matrix testing in GitHub Actions, showing how to exclude specific combinations of operating systems and Python/PyPy versions. Includes conditional execution of a step.

```yaml
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
        python-version: ['3.9', '3.10', '3.11', 'pypy3.9']
        exclude:
          - os: macos-latest
            python-version: '3.9'
          - os: windows-latest
            python-version: '3.9'
    steps:
      - uses: actions/checkout@v6
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: ${{ matrix.python-version }}
      - name: Display Python version
        if: ${{ matrix.python-version != 'pypy3.9' }}  # Use single quotes in expressions for input `python-version`
        run: python --version
```

--------------------------------

### PyPy Version Finding Module

Source: https://github.com/actions/setup-python/blob/main/_autodocs/architecture.md

Explains the PyPy version finding process, covering cache validation and installation.

```typescript
find-pypy.ts (PyPy)
├── Imports: install-pypy.ts, utils.ts
├── Main: findPyPyVersion(spec, arch, updateEnv, checkLatest, allowPre)
├── Logic:
│   ├── Parse spec → parsePyPyVersion()
│   ├── Check cache → findPyPyToolCache()
│   │   └── Validates version with semver
│   └── If not cached:
│       └── Download and install → install-pypy.ts:installPyPy()
└── Output: Sets python-version, python-path, env vars
```

--------------------------------

### CPython Version Finding Module

Source: https://github.com/actions/setup-python/blob/main/_autodocs/architecture.md

Details the CPython version finding logic, including manifest fetching and installation from releases.

```typescript
find-python.ts (CPython)
├── Imports: install-python.ts, utils.ts
├── Main: useCpythonVersion(version, arch, updateEnv, checkLatest, allowPre, freethreaded)
├── Logic:
│   ├── Parse version (desugarVersion, pythonVersionToSemantic)
│   ├── Check tool cache (tc.find)
│   ├── If not cached AND checkLatest:
│   │   └── Fetch manifest → install-python.ts:getManifest()
│   └── If not found:
│       └── Download and install → install-python.ts:installCpythonFromRelease()
└── Output: Sets python-version, python-path, env vars
```

--------------------------------

### findPyPyInstallDirForWindows

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-pypy.md

A Windows-specific helper function that searches all configured Windows architectures for a PyPy installation matching the specified Python version.

```APIDOC
## findPyPyInstallDirForWindows

### Description
A Windows-specific helper function that searches all configured Windows architectures for a PyPy installation matching the specified Python version.

### Parameters
#### Path Parameters
- **pythonVersion** (string) - Required - Python version in `x.y` format (e.g., `3.10`)

### Return Type
string — Absolute path to PyPy installation directory, or empty string if not found

### Behavior
1. Iterates through all Windows architectures: `x86`, `x64`
2. Searches each architecture for a matching Python version
3. Returns the first match found
4. Returns empty string if not found in any architecture

### Usage Example
```typescript
import {findPyPyInstallDirForWindows} from './find-pypy';

const installDir = findPyPyInstallDirForWindows('3.10');
if (installDir) {
  console.log(`Found at ${installDir}`);
}
```
```

--------------------------------

### Platform and Symlink Utilities

Source: https://github.com/actions/setup-python/blob/main/_autodocs/architecture.md

Functions for determining the binary directory and creating symbolic links, essential for managing Python installations across different platforms.

```typescript
utils.ts
├── Platform utilities:
│   ├── getBinaryDirectory(installDir)
│   └── createSymlinkInFolder(folderPath, source, target, executable)
```

--------------------------------

### useCpythonVersion

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-python.md

Finds and installs a CPython version in the runner's tool cache, or downloads it if not available. It handles version resolution, environment variable updates, and PATH modifications.

```APIDOC
## `useCpythonVersion()`

### Description
Finds and installs a CPython version in the runner's tool cache, or downloads it if not available. It handles version resolution, environment variable updates, and PATH modifications.

### Method Signature
```typescript
export async function useCpythonVersion(
  version: string,
  architecture: string,
  updateEnvironment: boolean,
  checkLatest: boolean,
  allowPreReleases: boolean,
  freethreaded: boolean
): Promise<InstalledVersion>
```

### Parameters
#### Parameters
- **version** (string) - Required - Version specification using SemVer syntax (e.g., `3.11`, `3.11.5`, `~3.11.0`). Supports prerelease syntax like `3.11.0b2`, dev versions like `3.11-dev`. Can include freethreaded suffix like `3.13t`.
- **architecture** (string) - Required - Target architecture: `x86`, `x64`, or `arm64`
- **updateEnvironment** (boolean) - Required - Whether to update environment variables and PATH
- **checkLatest** (boolean) - Required - If true, fetches the latest manifest to resolve the version to the most recent available release
- **allowPreReleases** (boolean) - Required - If true, allows matching prerelease versions when no GA version is found. Only supports `x.y` version ranges for CPython
- **freethreaded** (boolean) - Required - If true, uses the free-threaded variant (Python 3.13+)

### Return Type
```typescript
interface InstalledVersion {
  impl: string;  // Always 'CPython' for this function
  version: string;  // Resolved and installed version (e.g., '3.11.5', or '3.13.1t' if freethreaded)
}
```

### Behavior
1. Converts the version spec to semantic versioning (e.g., `3.11.0b2` becomes `3.11.0-b2`)
2. For `x.y` version ranges with `allowPreReleases=true`, converts to `~x.y.0-0` to match prerelease versions
3. If freethreaded is enabled, appends `-freethreaded` to the architecture
4. Checks the local tool cache for a matching version using `tc.find()`
5. If not found locally and `checkLatest=true`, fetches the manifest to resolve the version
6. Downloads the version from GitHub releases if not in cache
7. Sets environment variables: `pythonLocation`, `Python_ROOT_DIR`, `Python2_ROOT_DIR`, `Python3_ROOT_DIR`, `PKG_CONFIG_PATH`
8. Adds Python installation directory and Scripts directory to PATH
9. On Windows, also adds per-user Scripts directory to PATH
10. On Linux, updates `LD_LIBRARY_PATH` if needed
11. Installs/upgrades pip if `pip-version` input is specified
12. Sets outputs: `python-version` and `python-path`

### Throws
- **Error**: Version not found in tool cache or available releases
- **Error**: Invalid pip-version format (expected `major[.minor][.patch]`)

### Usage Example
```typescript
import * as finder from './find-python';

// Install latest Python 3.11
const result = await finder.useCpythonVersion(
  '3.11',
  'x64',
  true,
  false,
  false,
  false
);
console.log(result.version); // e.g., '3.11.5'

// Install specific version with check-latest
const result = await finder.useCpythonVersion(
  '3.12.1',
  'x64',
  true,
  true,
  false,
  false
);

// Install free-threaded Python 3.13
const result = await finder.useCpythonVersion(
  '3.13',
  'x64',
  true,
  false,
  false,
  true
);
```
```

--------------------------------

### Get OS Information

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/utils.md

Fetches the current operating system name and version. Used for cache key isolation. Returns undefined if detection fails.

```typescript
export async function getOSInfo(): Promise<{
  osName: string;
  osVersion: string;
} | undefined>
```

--------------------------------

### CPython InstalledVersion Type

Source: https://github.com/actions/setup-python/blob/main/_autodocs/types.md

Represents a successfully installed Python implementation, including its implementation identifier and resolved version string. Used by `useCpythonVersion()`.

```typescript
interface InstalledVersion {
  impl: string;
  version: string;
}
```

--------------------------------

### Pip Cache Configuration

Source: https://github.com/actions/setup-python/blob/main/_autodocs/architecture.md

Defines the default and backup patterns for caching Pip dependencies, and how to get the global pip cache directory.

```typescript
pip-cache.ts
├── Default pattern: **/requirements.txt
├── Backup pattern: **/pyproject.toml
├── getCacheGlobalDirectories()
│   └── Run `pip cache dir` command
```

--------------------------------

### Cache Dependencies Using Wildcard Patterns

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Use `cache-dependency-path` with wildcard patterns to cache dependencies based on matching file names. This example caches any `requirements-dev.txt` file.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.13'
    cache: 'pip'
    cache-dependency-path: '**/requirements-dev.txt'
- run: pip install -r subdirectory/requirements-dev.txt
```

--------------------------------

### findPyPyVersion

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-pypy.md

Finds and installs a PyPy version in the runner's tool cache, or downloads it if not available. It handles version parsing, checking the cache, downloading if necessary, and setting up the environment.

```APIDOC
## `findPyPyVersion()`

### Description
Finds and installs a PyPy version in the runner's tool cache, or downloads it if not available. It handles version parsing, checking the cache, downloading if necessary, and setting up the environment.

### Parameters

#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* None

### Method
* Not applicable (function call)

### Endpoint
* Not applicable (function call)

### Parameters
- **versionSpec** (string) - Required - PyPy version specification in format `pypy<python-version>` or `pypy-<python-version>[-<pypy-version>]` (e.g., `pypy3.10`, `pypy-3.10-7.3.13`)
- **architecture** (string) - Required - Target architecture: `x86`, `x64`, or `arm64`
- **updateEnvironment** (boolean) - Required - Whether to update environment variables and PATH
- **checkLatest** (boolean) - Required - If true, fetches the latest manifest to resolve to the most recent available release
- **allowPreReleases** (boolean) - Required - If true, allows matching prerelease PyPy versions when no stable version is found

### Return Type
* **resolvedPyPyVersion** (string) - E.g., '7.3.13'
* **resolvedPythonVersion** (string) - E.g., '3.10'

### Usage Example
```typescript
import {findPyPyVersion} from './find-pypy';

// Install PyPy with Python 3.10, any PyPy version
const result = await findPyPyVersion(
  'pypy3.10',
  'x64',
  true,
  false,
  false
);
console.log(`PyPy ${result.resolvedPyPyVersion} with Python ${result.resolvedPythonVersion}`);

// Install specific PyPy version
const result = await findPyPyVersion(
  'pypy-3.10-7.3.13',
  'x64',
  true,
  false,
  false
);

// Use check-latest to get newest version
const result = await findPyPyVersion(
  'pypy3.11',
  'x64',
  true,
  true,
  false
);
```

### Throws
* Error - Invalid version spec format for PyPy
* Error - Invalid Python or PyPy version (not valid SemVer)
* Error - Invalid Python version format (must be `x.y` format)
* Error - PyPy version with specified arch not found
```

--------------------------------

### Download and Set Up PyPy with Specific Versions

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

A GitHub Actions workflow example demonstrating how to set up specific PyPy versions for a build job using matrix strategy. This allows testing against different PyPy and Python version combinations.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
        - 'pypy3.10' # the latest available version of PyPy that supports Python 3.10
        - 'pypy3.10-v7.3.17' # Python 3.10 and PyPy 7.3.17
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-python@v6
      with:
        python-version: ${{ matrix.python-version }}
    - run: python my_script.py
```

--------------------------------

### Cache Dependencies Using Specific File Paths

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Use `cache-dependency-path` with a list of specific file paths to define which dependency files should be used for caching. This example caches Pipfile.lock files.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.13'
    cache: 'pipenv'
    cache-dependency-path: |
      server/app/Pipfile.lock
      __test__/app/Pipfile.lock
- name: Install pipenv
  run: curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
- run: pipenv install
```

--------------------------------

### findGraalPyVersion

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/find-graalpy.md

Finds and installs a GraalPy version in the runner's tool cache, or downloads it if not available. It handles version parsing, checking the cache, downloading if necessary, and setting up the environment.

```APIDOC
## findGraalPyVersion()

### Description
Finds and installs a GraalPy version in the runner's tool cache, or downloads it if not available. It handles version parsing, checking the cache, downloading if necessary, and setting up the environment.

### Method
Asynchronous function call

### Parameters
#### Path Parameters
- **versionSpec** (string) - Required - GraalPy version specification in format `graalpy<version>` or `graalpy-<version>` (e.g., `graalpy24.0`, `graalpy-24.1`)
- **architecture** (string) - Required - Target architecture: `x86`, `x64`, or `arm64`
- **updateEnvironment** (boolean) - Required - Whether to update environment variables and PATH
- **checkLatest** (boolean) - Required - If true, fetches the latest manifest to resolve to the most recent available release
- **allowPreReleases** (boolean) - Required - If true, allows matching prerelease GraalPy versions when no stable version is found

### Return Type
string — Resolved GraalPy version (e.g., `24.0`, `24.1.0`)

### Throws
- Error: Invalid version spec format for GraalPy
- Error: Invalid version (not valid SemVer)
- Error: GraalPy version with specified arch not found

### Usage Example
```typescript
import {findGraalPyVersion} from './find-graalpy';

// Install GraalPy version 24.0
const version = await findGraalPyVersion(
  'graalpy24.0',
  'x64',
  true,
  false,
  false
);
console.log(`Installed GraalPy ${version}`);

// Install latest GraalPy 24 release
const latestVersion = await findGraalPyVersion(
  'graalpy24',
  'x64',
  true,
  true,
  false
);

// Allow prerelease versions
const prerelease = await findGraalPyVersion(
  'graalpy24',
  'x64',
  true,
  false,
  true
);
```
```

--------------------------------

### Post Action Flow

Source: https://github.com/actions/setup-python/blob/main/_autodocs/architecture.md

Outlines the steps executed by the post-action of setup-python, focusing on cache saving and optimization.

```typescript
cache-save.ts:run()
├── Check if caching enabled
├── Get paths from state (set by main action)
├── Save cache using @actions/cache
└── Exit early (optimization for slow post steps)
```

--------------------------------

### Get Python Binary Directory

Source: https://github.com/actions/setup-python/blob/main/_autodocs/api-reference/utils.md

Retrieves the directory containing Python executables based on the installation path. Handles differences between Windows and Unix-like systems.

```typescript
export function getBinaryDirectory(installDir: string): string
```

--------------------------------

### Specify Exact Python Version

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

Use this to ensure a specific patch version of Python is installed, preventing unexpected changes from minor updates. This may increase setup time if the version is not pre-installed.

```yaml
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
  with:
    python-version: '3.12.6'
- run: python my_script.py
```

--------------------------------

### Download and Set Up Multiple PyPy Versions

Source: https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md

A GitHub Actions workflow snippet for setting up multiple PyPy versions. This allows testing against various PyPy distributions and versions.

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-python@v6
      with:
        python-version: |
            pypy-3.10-v7.3.x
            pypy3.10-nightly
            pypy3.9
    - run: python my_script.py
```