### Create Version File from Explicit Parameters (Quick Start)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/index.md

A quick start example demonstrating the creation of a version file using explicit parameters. This is useful for simple, direct version file generation.

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="1.2.3.4",
    company_name="Acme Corp",
    product_name="My App",
    file_description="My Application"
)
```

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

### Create Version File from Installed Package (Quick Start)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/index.md

Generate a version file using metadata from an installed Python package. Specify the package name and the output file path.

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distname="my_package"
)
```

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

### Create Version File from YAML File (Quick Start)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/index.md

This example shows how to create a version file from a YAML configuration file. Ensure the YAML file contains the necessary metadata fields.

```yaml
Version: 1.2.3.4
CompanyName: Acme Corp
ProductName: My App
FileDescription: My Application
```

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml"
)
```

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

### Install pyinstaller-versionfile

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/README.md

Install the library using pip.

```bash
pip install pyinstaller-versionfile
```

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

### Install Project Dependencies

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/CONTRIBUTING.md

Run this command in the root directory to install all project requirements using Poetry.

```bash
poetry install
```

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

### API Reference Overview

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/INDEX.md

This section provides an overview of the library's API and quick start examples for common usage patterns.

```APIDOC
## API Reference

This library offers a functional API and class-based interfaces for creating version files.

### Functional API

- **`create_versionfile`**: Creates a version file from explicit parameters.
- **`create_versionfile_from_input_file`**: Creates a version file from a YAML configuration file.
- **`create_versionfile_from_distribution`**: Creates a version file from a Python package distribution.

### Class-based API

- **`MetaData`**: Represents the metadata for a version file.
- **`Writer`**: Handles the writing of version file content.

Refer to the specific API reference files for detailed signatures, parameters, and examples.
```

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

### YAML Configuration Example

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

A complete YAML configuration for version file metadata. The encoding must be UTF-8. All fields are optional.

```YAML
Version: 1.2.3.4
CompanyName: My Imaginary Company
FileDescription: Simple App
InternalName: Simple App
LegalCopyright: "© My Imaginary Company. All rights reserved."
OriginalFilename: SimpleApp.exe
ProductName: Simple App
Translation:
  - langID: 0
    charsetID: 1200
  - langID: 1033
    charsetID: 1252
```

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

### Create Version File with All Parameters and Custom Translations

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile.md

This example demonstrates how to use create_versionfile() with all available parameters, including custom language and character set IDs for translations.

```python
import pyinstaller_versionfile

# Create a version file with all parameters including custom translations
pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="2.0.1",
    company_name="Acme Corp",
    file_description="Professional Tool",
    internal_name="AcmeTool",
    legal_copyright="Copyright © 2024 Acme Corp. All rights reserved.",
    original_filename="acme_tool.exe",
    product_name="Acme Professional Suite",
    translations=[1033, 1200, 1031, 1200]  # English and German
)
```

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

### YAML Configuration for Version File

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/configuration.md

Example of a complete YAML file for configuring Windows version resource metadata. All fields are optional and will use defaults if omitted.

```yaml
# All fields are optional
Version: 1.2.3.4
CompanyName: Acme Corporation
FileDescription: Professional Application Suite
InternalName: AcmePro
LegalCopyright: Copyright © 2024 Acme Corp. All rights reserved.
OriginalFilename: acme_pro.exe
ProductName: Acme Professional
Translation:
  - langID: 1033
    charsetID: 1200
  - langID: 1031
    charsetID: 1200
```

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

### GitHub Actions CI/CD Pipeline

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/workflows.md

Example GitHub Actions workflow for automating the build and packaging process. It installs dependencies, generates a version file, builds the executable with PyInstaller, and uploads the artifact.

```yaml
name: Build and Package

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install -e .
          pip install pyinstaller pyinstaller-versionfile
      
      - name: Generate version file
        run: |
          $version = "${{ github.ref }}".TrimStart('refs/tags/v')
          pyivf-make_version \
            --source-format dist \
            --metadata-source my_package \
            --outfile version_file.txt \
            --version $version
      
      - name: Build executable
        run: |
          pyinstaller \
            --onefile \
            --version-file=version_file.txt \
            --name my_app \
            src/my_package/__main__.py
      
      - name: Upload release
        uses: actions/upload-artifact@v3
        with:
          name: executable
          path: dist/my_app.exe
```

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

### CI/CD with Automatic Versioning

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/index.md

This pattern shows how to integrate version file creation into a CI/CD pipeline, automatically fetching the version from a package manager like setuptools_scm. Ensure the package is installed and accessible.

```python
import pyinstaller_versionfile
from importlib.metadata import version

# Get version from setuptools_scm or similar
current_version = version("my_package")

pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version=current_version,
    product_name="My Application"
)
```

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

### Create Version File from Distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Command to create a version file by extracting metadata from an installed Python package. Specify the package name with --metadata-source.

```cmd
pyivf-make_version --source-format dist --metadata-source PackageName --outfile file_version_info.txt
```

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

### Create MetaData from Installed Distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/metadata.md

Factory method to create a MetaData instance from an installed Python distribution. Allows overriding specific fields.

```python
from pyinstaller_versionfile.metadata import MetaData

# Extract metadata from installed package
metadata = MetaData.from_distribution("my_package")

# Extract and override specific fields
metadata = MetaData.from_distribution(
    "my_package",
    product_name="Custom Product Name",
    version="2.0.0"
)
```

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

### CI/CD Workflow: Generate Version File from Distribution Metadata

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/cli.md

This bash script demonstrates a typical CI/CD workflow. It installs dependencies, generates a version file using package metadata, and then builds the executable with PyInstaller.

```bash
#!/bin/bash
set -e

# Step 1: Install the application and pyinstaller-versionfile
pip install -e .
pip install pyinstaller pyinstaller-versionfile

# Step 2: Generate version file from installed package metadata
pyivf-make_version \
  --source-format dist \
  --metadata-source my_package \
  --outfile version_file.txt \
  --product-name "My Application"

# Step 3: Build executable with version resource
pyinstaller \
  --version-file=version_file.txt \
  --onefile \
  my_package/__main__.py

# Step 4: Output artifacts
mkdir -p artifacts
cp dist/my_package artifacts/
```

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

### Create Version File from Distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile-from-distribution.md

Generates a version file by extracting metadata from an installed Python package. Ensure the package is installed in the current environment.

```python
import pyinstaller_versionfile

# Extract version info from an installed package
pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distname="my_package"
)
```

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

### Create Version File from Python Distribution (API)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/workflows.md

Use this API to synchronize version file metadata with an installed Python package's metadata. This is beneficial when package versions are managed by tools like setuptools_scm.

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distname="my_package",
    product_name="My Professional Application"
)
```

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

### Generate Version File from Installed Package using CLI

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/START_HERE.md

Use the pyivf-make_version CLI command to generate a version file by extracting metadata from an installed package.

```bash
pyivf-make_version --source-format dist --metadata-source my_package --outfile version_file.txt
```

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

### create_versionfile_from_distribution()

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/README.md

Creates a version file by extracting metadata from an installed Python package distribution.

```APIDOC
## create_versionfile_from_distribution()

### Description
Generates a version file by extracting metadata from an installed Python package.

### Signature
```python
create_versionfile_from_distribution(
    output_file: str,
    distribution_name: str,
    encoding: str = "utf-8"
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **output_file** (str) - Required - Path to the output version file.
- **distribution_name** (str) - Required - The name of the installed Python package.
- **encoding** (str) - Optional - Encoding for reading package metadata. Defaults to "utf-8".

### Request Example
```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distribution_name="my_package"
)
```

### Response
#### Success Response
None (writes to file)

#### Response Example
None
```

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

### create_versionfile_from_distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile-from-distribution.md

Create a Windows version file from metadata extracted from an installed Python distribution (package). It maps Python package metadata fields to version file fields.

```APIDOC
## create_versionfile_from_distribution

### Description
Create a Windows version file from metadata extracted from an installed Python distribution (package).

### Signature
```python
def create_versionfile_from_distribution(
    output_file: str,
    distname: str,
    version: Optional[str] = None,
    company_name: Optional[str] = None,
    file_description: Optional[str] = None,
    internal_name: Optional[str] = None,
    legal_copyright: Optional[str] = None,
    original_filename: Optional[str] = None,
    product_name: Optional[str] = None,
    translations: Optional[list[int]] = None,
) -> None
```

### Parameters
#### Path Parameters
- **output_file** (str) - Required - Path to write the generated version file
- **distname** (str) - Required - Name of the installed Python distribution (package) from which to extract metadata. The package must be installed in the current Python environment.

#### Query Parameters
- **version** (Optional[str]) - Optional - Override the version extracted from the distribution. Must match format `MAJOR.MINOR.PATCH.BUILD` or shorter.
- **company_name** (Optional[str]) - Optional - Override the company name extracted from the distribution.
- **file_description** (Optional[str]) - Optional - Override the file description extracted from the distribution.
- **internal_name** (Optional[str]) - Optional - Override the internal name extracted from the distribution.
- **legal_copyright** (Optional[str]) - Optional - Override the legal copyright extracted from the distribution.
- **original_filename** (Optional[str]) - Optional - Override the original filename extracted from the distribution.
- **product_name** (Optional[str]) - Optional - Override the product name extracted from the distribution.
- **translations** (Optional[list[int]]) - Optional - Override the translations. Format is flat list of language/charset ID pairs.

### Return Value
`None` — The function writes the generated version file to disk at the specified `output_file` path.

### Exceptions
- **InputError**: The specified distribution (package name) is not installed or found in the current Python environment
- **ValidationError**: Version string does not match the required format
- **InternalUsageError**: Template rendering error (missing parameters)
- **UsageError**: Output file is a directory instead of a file path

### Example
```python
import pyinstaller_versionfile

# Extract version info from an installed package
pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distname="my_package"
)

# Extract version info from distribution, overriding some fields
pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distname="my_package",
    product_name="My Awesome Application",  # Override package name
    version="2.0.0"  # Override the version from package metadata
)
```
```

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

### Quality Metrics Overview

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/MANIFEST.md

Lists the quantitative quality metrics for the documentation, including example count, table count, and cross-references.

```text
- **Code Examples**: 50+ realistic examples
- **Tables**: 30+ reference tables
- **Cross-References**: 100+ links between documents
- **Type Coverage**: 100% of all types documented
- **Source References**: Every item linked to source file:line
- **Constraint Documentation**: All limitations documented
- **Default Values**: All defaults documented
```

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

### Legacy CLI: Create version file from distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/cli.md

Use the deprecated `create-version-file` command to generate a version file from an installed Python package. Specify the package name and output file.

```bash
create-version-file my_package --source-format distribution --outfile version_file.txt
```

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

### Generate version file from Python distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/cli.md

Use `pyivf-make_version` to generate a version file from an installed Python package. Specify the package name and output file.

```bash
pyivf-make_version --source-format distribution --metadata-source my_package --outfile version_file.txt
```

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

### Create Version File from Distribution Metadata

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/module-reference.md

This function creates a version file by extracting metadata from an installed Python distribution. It simplifies version file generation when project metadata is already available.

```python
def create_versionfile_from_distribution(
    output_file: str,
    distname: str,
    version: Optional[str] = None,
    company_name: Optional[str] = None,
    file_description: Optional[str] = None,
    internal_name: Optional[str] = None,
    legal_copyright: Optional[str] = None,
    original_filename: Optional[str] = None,
    product_name: Optional[str] = None,
    translations: Optional[list[int]] = None,
) -> None
```

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

### Command-Line Overrides for Version File Generation

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/configuration.md

Example of using the pyivf-make_version command-line tool to generate a version file, overriding metadata fields like version, product name, and company name. This allows for dynamic configuration during build processes.

```bash
pyivf-make_version \
  --source-format yaml \
  --metadata-source metadata.yml \
  --outfile version_file.txt \
  --version 2.0.0 \
  --product-name "Updated Product Name" \
  --company-name "New Company"
```

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

### Create Version File from Python Distribution (CLI)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/workflows.md

This CLI command generates a version file by extracting metadata from an installed Python package. It's useful for aligning version file information with package metadata managed by tools like setuptools_scm.

```bash
pyivf-make_version \
  --source-format distribution \
  --metadata-source my_package \
  --outfile version_file.txt \
  --product-name "My Professional Application"
```

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

### Show pyivf-make_version help

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Run this command to see the full interface description for the pyinstaller-versionfile CLI.

```cmd
pyivf-make_version --help
```

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

### Create Version File with setuptools_scm

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile-from-distribution.md

Demonstrates using create_versionfile_from_distribution in conjunction with setuptools_scm for automated versioning. This approach is common in CI/CD pipelines where package versions are managed programmatically.

```python
# Use with setuptools_scm for automated versioning
# (assuming setuptools_scm is configured in your package)
pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="version_file.txt",
    distname="my_package"
)
```

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

### Create Basic Version File

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile.md

Use this snippet to generate a version file with essential parameters like output file, version, company name, product name, and file description.

```python
import pyinstaller_versionfile

# Create a basic version file with minimal parameters
pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="1.2.3.4",
    company_name="My Company",
    product_name="My Application",
    file_description="A sample application"
)
```

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

### Initialize Writer with MetaData

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/writer.md

Instantiate the Writer class by passing a MetaData object. This object should contain all necessary version file information.

```python
from pyinstaller_versionfile.metadata import MetaData
from pyinstaller_versionfile.writer import Writer

metadata = MetaData(
    version="1.0.0.0",
    company_name="Acme Corp",
    product_name="MyApp"
)
writer = Writer(metadata)
```

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

### Catching InternalUsageError Example

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/errors.md

Demonstrates how to catch the InternalUsageError exception when calling library functions. This error typically indicates a bug in the library itself.

```python
import pyinstaller_versionfile
from pyinstaller_versionfile import exceptions

try:
    # This would only happen due to a library bug
    pyinstaller_versionfile.create_versionfile(
        output_file="version_file.txt",
        version="1.0.0.0"
    )
except exceptions.InternalUsageError as e:
    print(f"Internal error (please report): {e}")
```

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

### Legacy CLI Entry Point for create_version_file

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/module-reference.md

This function is a legacy entry point for the `create-version-file` command-line command. It is maintained for backward compatibility.

```python
def create_version_file(args: Union[Namespace, Optional[Sequence[str]]] = None) -> None
```

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

### Create VersionFile from Explicit Parameters

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/INDEX.md

Documentation for creating a version file using explicit parameters, detailing function signatures and parameter descriptions.

```APIDOC
## `create_versionfile`

Creates a version file using explicitly provided parameters.

### Function Signature

```python
create_versionfile(output_path: str, metadata: MetadataKwargs, writer_cls: type[Writer] = Writer)
```

### Parameters

#### Path Parameters

- **`output_path`** (str) - Required - The path where the version file will be saved.

#### Request Body

- **`metadata`** (MetadataKwargs) - Required - A dictionary or object containing the metadata for the version file. See `configuration.md` for details on available fields.
- **`writer_cls`** (type[Writer]) - Optional - The specific Writer class to use for generating the version file. Defaults to the standard `Writer` class.

### Response

This function does not return a value directly but writes the version file to the specified `output_path`.

### Exceptions

- Raises exceptions defined in `errors.md` if metadata is invalid or writing fails.
```

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

### MetaData.from_distribution()

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/metadata.md

Factory method to create a MetaData instance from an installed Python distribution. It extracts metadata from the specified package and allows for overriding fields with keyword arguments.

```APIDOC
## `from_distribution()` (Class Method)

Factory method to create a `MetaData` instance from an installed Python distribution.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| distname | str | Yes | Name of the installed distribution (package) |
| **kwargs | dict[str, Any] | No | Override parameters (see `MetadataKwargs` for valid keys) |

#### Returns

`MetaData` — New instance with metadata extracted from the distribution, merged with any kwargs overrides.

#### Exceptions

| Exception | Condition |
|-----------|-----------|
| `InputError` | Distribution not found in the current Python environment |

#### Example

```python
from pyinstaller_versionfile.metadata import MetaData

# Extract metadata from installed package
metadata = MetaData.from_distribution("my_package")

# Extract and override specific fields
metadata = MetaData.from_distribution(
    "my_package",
    product_name="Custom Product Name",
    version="2.0.0"
)
```
```

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

### Create Version File Directly

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/workflows.md

Use this function to directly create a version file with specified metadata. Ensure all required parameters are provided.

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="1.0.0.0",
    company_name="Global Software Corp",
    file_description="Professional Application",
    internal_name="GlobalApp",
    legal_copyright="Copyright © 2024 Global Software Corp.",
    original_filename="global_app.exe",
    product_name="Global Application",
    translations=[
        1033, 1200,  # English - US, Unicode
        1031, 1200,  # German, Unicode
        1036, 1200,  # French, Unicode
        2052, 936    # Chinese Simplified, GB2312
    ]
)
```

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

### create_versionfile()

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile.md

Creates a Windows version file (VERSIONINFO resource) from explicitly provided parameters. All parameters are optional and will be filled with placeholder values if not provided.

```APIDOC
## create_versionfile()

### Description
Creates a Windows version file (VERSIONINFO resource) from explicitly provided parameters. All parameters are optional and will be filled with placeholder values (empty strings or default version '0.0.0.0') if not provided.

### Signature
```python
def create_versionfile(
    output_file: str,
    version: Optional[str] = None,
    company_name: Optional[str] = None,
    file_description: Optional[str] = None,
    internal_name: Optional[str] = None,
    legal_copyright: Optional[str] = None,
    original_filename: Optional[str] = None,
    product_name: Optional[str] = None,
    translations: Optional[list[int]] = None,
) -> None
```

### Parameters
#### Path Parameters
- **output_file** (str) - Required - Path to write the generated version file

#### Optional Parameters
- **version** (Optional[str]) - Optional - Version string in format `MAJOR.MINOR.PATCH.BUILD` or shorter (e.g., `1.2.3.4`, `1.0.0`, `1.2`). Defaults to `0.0.0.0` if not specified.
- **company_name** (Optional[str]) - Optional - Name of the company that produced the file. Replaced with empty string if not specified.
- **file_description** (Optional[str]) - Optional - Description presented to users during installation. Replaced with empty string if not specified.
- **internal_name** (Optional[str]) - Optional - Internal name of the file. Should be the original filename without extension if no internal name exists. Replaced with empty string if not specified.
- **legal_copyright** (Optional[str]) - Optional - Copyright notices and legal symbols. Replaced with empty string if not specified.
- **original_filename** (Optional[str]) - Optional - Original name of the file (not including path), used to detect if the file has been renamed by a user. Replaced with empty string if not specified.
- **product_name** (Optional[str]) - Optional - Name of the product with which the file is distributed. Replaced with empty string if not specified.
- **translations** (Optional[list[int]]) - Optional - Language and character set IDs as a flat list. Each pair of values represents one translation: `[langID_1, charsetID_1, langID_2, charsetID_2, ...]`. Defaults to `[1033, 1200]` (English, Unicode) if not specified.

### Return Value
`None` — The function writes the generated version file to disk at the specified `output_file` path.

### Exceptions
- **ValidationError**: Version string does not match the required format (digits and dots only, up to 4 parts).
- **InternalUsageError**: Internal error during template rendering (missing parameters or template issues).
- **UsageError**: Output file is a directory instead of a file path.

### Example
```python
import pyinstaller_versionfile

# Create a basic version file with minimal parameters
pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="1.2.3.4",
    company_name="My Company",
    product_name="My Application",
    file_description="A sample application"
)

# Create a version file with all parameters including custom translations
pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="2.0.1",
    company_name="Acme Corp",
    file_description="Professional Tool",
    internal_name="AcmeTool",
    legal_copyright="Copyright © 2024 Acme Corp. All rights reserved.",
    original_filename="acme_tool.exe",
    product_name="Acme Professional Suite",
    translations=[1033, 1200, 1031, 1200]  # English and German
)
```
```

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

### Complete Workflow for Generating Version File

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/writer.md

Demonstrates the full process of creating, validating, sanitizing metadata, rendering, and saving a version file using the Writer class.

```python
from pyinstaller_versionfile.metadata import MetaData
from pyinstaller_versionfile.writer import Writer

# Step 1: Create metadata
metadata = MetaData(
    version="2.1.0.0",
    company_name="Acme Corporation",
    file_description="Professional Application Suite",
    internal_name="AcmeProApp",
    legal_copyright="Copyright © 2024 Acme Corp. All rights reserved.",
    original_filename="acme_pro.exe",
    product_name="Acme Professional"
)

# Step 2: Validate
metadata.validate()

# Step 3: Sanitize (Implicitly handled by render/save if not explicitly called)
# metadata.sanitize()

# Step 4: Create Writer instance
writer = Writer(metadata)

# Step 5: Render content
writer.render()

# Step 6: Save to disk
writer.save("acme_professional_version.txt")
```

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

### MetaData Constructor Signature

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/metadata.md

Initializes a MetaData instance with optional versioning and file information. All parameters are optional and default to placeholder or default values.

```python
def __init__(
    self,
    version: Optional[str] = None,
    company_name: Optional[str] = None,
    file_description: Optional[str] = None,
    internal_name: Optional[str] = None,
    legal_copyright: Optional[str] = None,
    original_filename: Optional[str] = None,
    product_name: Optional[str] = None,
    translations: Optional[list[int]] = None,
) -> None
```

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

### Create VersionFile from Input File

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/INDEX.md

Documentation for creating a version file from a YAML input file, including details on the expected file format and parameters.

```APIDOC
## `create_versionfile_from_input_file`

Creates a version file by reading metadata from a specified YAML input file.

### Function Signature

```python
create_versionfile_from_input_file(output_path: str, input_file: str, writer_cls: type[Writer] = Writer)
```

### Parameters

#### Path Parameters

- **`output_path`** (str) - Required - The path where the version file will be saved.
- **`input_file`** (str) - Required - The path to the YAML file containing the version file metadata.

#### Request Body

- **`writer_cls`** (type[Writer]) - Optional - The specific Writer class to use for generating the version file. Defaults to the standard `Writer` class.

### Response

This function does not return a value directly but writes the version file to the specified `output_path`.

### Exceptions

- Raises exceptions defined in `errors.md` if the input file is not found, is invalid YAML, or if writing fails.
```

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

### Generate version file with explicit parameters

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/cli.md

Create a version file using only explicit parameters provided on the command line, such as version, company name, and product name.

```bash
pyivf-make_version --outfile version_file.txt --version 1.0.0.0 --company-name "Acme Corp" --product-name "MyApp"
```

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

### Python Script for Version File Generation

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/writer.md

This Python script demonstrates the core steps for creating a version file: sanitizing metadata, initializing the Writer, rendering the content, and saving the file. Ensure all string parameters are present for validation.

```python
# Step 3: Sanitize
metadata.sanitize()

# Step 4: Create writer
writer = Writer(metadata)

# Step 5: Render
writer.render()

# Step 6: Save
writer.save("version_file.txt")
```

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

### Documentation Generation Process

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/MANIFEST.md

Outlines the steps involved in generating the project's documentation, from source analysis to verification.

```text
1. **Source Analysis**: 5 Python modules analyzed
2. **Type Extraction**: All types extracted with signatures
3. **Parameter Documentation**: All parameters with constraints
4. **Exception Mapping**: All exceptions with conditions
5. **Example Creation**: Realistic usage patterns demonstrated
6. **Cross-Referencing**: All related items linked
7. **Verification**: All source references validated
```

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

### Main CLI Entry Point for make_version

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/module-reference.md

This function serves as the primary command-line interface entry point for the `make_version` command. It handles argument parsing and execution.

```python
def make_version(args: Union[Namespace, Optional[Sequence[str]]] = None) -> None
```

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

### Run Unit Tests

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/CONTRIBUTING.md

Execute the unit tests for the project using Tox.

```bash
tox -e tests
```

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

### Generate Version File using CLI

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/README.md

Use the command-line interface to generate a version file, specifying the metadata source format and output file.

```bash
pyivf-make_version \
  --source-format yaml \
  --metadata-source metadata.yml \
  --outfile version_file.txt
```

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

### Writer Class Constructor

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/writer.md

Initializes a new Writer instance. It requires a MetaData object which contains all the necessary information for the version file.

```APIDOC
## Writer(`__init__`)

### Description
Creates a new `Writer` instance bound to a `MetaData` object.

### Method
__init__

### Parameters
#### Parameters
- **metadata** (MetaData) - Required - The metadata object containing all version file information

### Request Example
```python
from pyinstaller_versionfile.metadata import MetaData
from pyinstaller_versionfile.writer import Writer

metadata = MetaData(
    version="1.0.0.0",
    company_name="Acme Corp",
    product_name="MyApp"
)
writer = Writer(metadata)
```
```

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

### Project File Structure

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/MANIFEST.md

Lists the root level files and the directory structure for API reference documentation.

```text
output/
├── INDEX.md (this index)
├── README.md (overview and getting started)
├── MANIFEST.md (this file)
├── types.md (type definitions)
├── errors.md (exception reference)
├── configuration.md (metadata configuration)
├── workflows.md (usage patterns)
└── module-reference.md (module structure)
```

```text
api-reference/
├── index.md (API overview)
├── create-versionfile.md
├── create-versionfile-from-input-file.md
├── create-versionfile-from-distribution.md
├── metadata.md
├── writer.md
└── cli.md
```

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

### Create Version File with Explicit Parameters

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/README.md

Generate a version file by providing all metadata as explicit function parameters.

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="1.0.0.0",
    company_name="My Company",
    product_name="My App"
)
```

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

### API Code with Error Handling

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/workflows.md

Demonstrates how to use the `create_versionfile_from_input_file` function with comprehensive error handling for various potential issues like invalid configuration, validation errors, or internal library problems. This ensures robust application behavior.

```python
import pyinstaller_versionfile
from pyinstaller_versionfile import exceptions
import sys

def generate_version_file(config_file, output_file, version=None):
    """Generate version file with error handling."""
    try:
        # Attempt to read from YAML file
        pyinstaller_versionfile.create_versionfile_from_input_file(
            output_file=output_file,
            input_file=config_file,
            version=version
        )
        print(f"Successfully created version file: {output_file}")
        return True
        
    except exceptions.InputError as e:
        print(f"ERROR: Configuration file issue: {e}")
        return False
        
    except exceptions.ValidationError as e:
        print(f"ERROR: Invalid metadata: {e}")
        return False
        
    except exceptions.UsageError as e:
        print(f"ERROR: Invalid output path: {e}")
        return False
        
    except exceptions.InternalUsageError as e:
        print(f"ERROR: Internal library error (please report): {e}")
        return False

# Example usage
if __name__ == "__main__":
    success = generate_version_file(
        config_file="metadata.yml",
        output_file="version_file.txt",
        version="2.0.0.0"
    )
    sys.exit(0 if success else 1)
```

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

### Create Version File from YAML Input

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/README.md

Generate a version file by reading metadata from a YAML file. Ensure the YAML file contains the necessary metadata fields.

```yaml
Version: 1.0.0.0
CompanyName: My Company
ProductName: My App
```

```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml"
)
```

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

### Create VersionFile from Distribution

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/INDEX.md

Documentation for creating a version file directly from a Python package distribution (e.g., wheel or sdist).

```APIDOC
## `create_versionfile_from_distribution`

Creates a version file by extracting metadata from a Python package distribution.

### Function Signature

```python
create_versionfile_from_distribution(output_path: str, distribution_path: str, writer_cls: type[Writer] = Writer)
```

### Parameters

#### Path Parameters

- **`output_path`** (str) - Required - The path where the version file will be saved.
- **`distribution_path`** (str) - Required - The path to the package distribution file (e.g., `.whl` or `.tar.gz`).

#### Request Body

- **`writer_cls`** (type[Writer]) - Optional - The specific Writer class to use for generating the version file. Defaults to the standard `Writer` class.

### Response

This function does not return a value directly but writes the version file to the specified `output_path`.

### Exceptions

- Raises exceptions defined in `errors.md` if the distribution file is not found, is invalid, or if writing fails.
```

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

### create_versionfile_from_input_file

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile-from-input-file.md

Creates a Windows version file from metadata specified in a YAML input file. Optional parameters can be used to override values from the YAML file.

```APIDOC
## create_versionfile_from_input_file

### Description
Creates a Windows version file from metadata specified in a YAML input file. Optional parameters can be used to override values from the YAML file.

### Signature
```python
def create_versionfile_from_input_file(
    output_file: str,
    input_file: str,
    version: Optional[str] = None,
    company_name: Optional[str] = None,
    file_description: Optional[str] = None,
    internal_name: Optional[str] = None,
    legal_copyright: Optional[str] = None,
    original_filename: Optional[str] = None,
    product_name: Optional[str] = None,
    translations: Optional[list[int]] = None,
) -> None
```

### Parameters
#### Path Parameters
- **output_file** (str) - Required - Path to write the generated version file
- **input_file** (str) - Required - Path to YAML configuration file containing metadata. File must be UTF-8 encoded.

#### Query Parameters
- **version** (Optional[str]) - Optional - Override the version from the YAML file. Must match format `MAJOR.MINOR.PATCH.BUILD` or shorter.
- **company_name** (Optional[str]) - Optional - Override the company name from the YAML file.
- **file_description** (Optional[str]) - Optional - Override the file description from the YAML file.
- **internal_name** (Optional[str]) - Optional - Override the internal name from the YAML file.
- **legal_copyright** (Optional[str]) - Optional - Override the legal copyright from the YAML file.
- **original_filename** (Optional[str]) - Optional - Override the original filename from the YAML file.
- **product_name** (Optional[str]) - Optional - Override the product name from the YAML file.
- **translations** (Optional[list[int]]) - Optional - Override the translations from the YAML file. Format is flat list of language/charset ID pairs.

### Return Value
`None` — The function writes the generated version file to disk at the specified `output_file` path.

### Exceptions
- `InputError` - Input file does not exist or is a directory
- `InputError` - File is not readable or has I/O errors
- `InputError` - YAML content is invalid (scanner error)
- `InputError` - YAML file does not contain a mapping (dict) at top level
- `ValidationError` - Version string does not match the required format
- `InternalUsageError` - Template rendering error (missing parameters)
- `UsageError` - Output file is a directory instead of a file path

### Example
```python
import pyinstaller_versionfile

# Create version file from YAML with no overrides
pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml"
)

# Create version file from YAML, overriding the version from CI/build system
pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml",
    version="2.1.0.0"
)

# Create version file from YAML, overriding multiple fields
pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml",
    version="1.5.0.0",
    product_name="Updated Product Name",
    company_name="New Company Name"
)
```
```

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

### Using Version File with PyInstaller

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/writer.md

This command shows how to integrate the generated version file into your PyInstaller build process.

```bash
pyinstaller --version-file=version_file.txt myapp.spec
```

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

### Handle Errors During Version File Creation

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/index.md

This snippet demonstrates how to catch specific exceptions when creating a version file from an input file. It handles configuration, validation, and usage errors.

```python
import pyinstaller_versionfile
from pyinstaller_versionfile import exceptions

try:
    pyinstaller_versionfile.create_versionfile_from_input_file(
        output_file="version_file.txt",
        input_file="metadata.yml"
    )
except exceptions.InputError as e:
    print(f"Configuration error: {e}")
except exceptions.ValidationError as e:
    print(f"Invalid version: {e}")
except exceptions.UsageError as e:
    print(f"Usage error: {e}")
```

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

### Create version file from YAML with no overrides

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/create-versionfile-from-input-file.md

This snippet demonstrates the basic usage of creating a version file by specifying the output and input file paths. No metadata is overridden.

```python
import pyinstaller_versionfile

# Create version file from YAML with no overrides
pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml"
)
```

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

### Create Version File with Direct Values (Python API)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Use the functional API to create a version file by directly specifying all metadata values. All parameters are optional and will be filled with placeholders if not provided.

```Python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile(
    output_file="versionfile.txt",
    version="1.2.3.4",
    company_name="My Imaginary Company",
    file_description="Simple App",
    internal_name="Simple App",
    legal_copyright="© My Imaginary Company. All rights reserved.",
    original_filename="SimpleApp.exe",
    product_name="Simple App",
    translations=[0, 1200]
)
```

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

### Python API: create_versionfile_from_input_file

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Creates a version file by reading metadata from a specified input file (e.g., YAML).

```APIDOC
## Python API: create_versionfile_from_input_file

### Description
Generates a version file from a specified input file, such as a YAML configuration.

### Function Signature
```python
create_versionfile_from_input_file(
    output_file: str,
    input_file: str,
    version: Optional[str] = None
)
```

### Parameters
- `output_file` (str): The path to the file where the version information will be saved.
- `input_file` (str): The path to the input metadata file (e.g., a YAML file).
- `version` (Optional[str]): An optional version string to override the version information found in the input file.

### Example
```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="versionfile.txt",
    input_file="metadata.yml",
    version="1.2.3.4"
)
```
```

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

### Parse Arguments for create_version_file CLI (Legacy)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/module-reference.md

This helper function parses command-line arguments for the legacy `create_version_file` command. It returns a `Namespace` object.

```python
def parse_args_create_version_file(args: Optional[Sequence[str]]) -> Namespace
```

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

### Create Version File from YAML

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Command to create a version file from a YAML configuration. Specify the YAML file path using --metadata-source and the output file with --outfile.

```cmd
pyivf-make_version --source-format yaml --metadata-source metadata.yml --outfile file_version_info.txt
```

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

### Create Version File from Distribution (Python API)

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Use the functional API to create a version file by extracting metadata from a specified Python distribution. This is advantageous for automated versioning with tools like setuptools_scm.

```Python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_distribution(
    output_file="versionfile.txt",
    distname="myPackage"
)
```

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

### create_versionfile()

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/api-reference/index.md

Creates a Windows version file from explicit parameters. This is the recommended function for programmatic use when all metadata is known.

```APIDOC
## create_versionfile()

### Description
Creates a Windows version file (VERSIONINFO resource) from explicit parameters provided as arguments. This function is suitable for direct programmatic use within Python scripts.

### Method
```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile(
    output_file: str,
    version: str,
    company_name: str = None,
    product_name: str = None,
    file_description: str = None,
    internal_name: str = None,
    original_filename: str = None,
    legal_copyright: str = None,
    legal_trademarks: str = None,
    private_build: str = None,
    special_build: str = None,
    language: str = 'neutral', # e.g., '0409' for US English
    code_page: str = '1200' # e.g., '1200' for UTF-16
)
```

### Parameters
#### Path Parameters
- **output_file** (str) - Required - The path to the output file where the version information will be saved.
- **version** (str) - Required - The version string for the file (e.g., "1.0.0.0").

#### Other Parameters
- **company_name** (str) - Optional - The name of the company.
- **product_name** (str) - Optional - The name of the product.
- **file_description** (str) - Optional - A description of the file.
- **internal_name** (str) - Optional - The internal name of the file.
- **original_filename** (str) - Optional - The original filename.
- **legal_copyright** (str) - Optional - Copyright information.
- **legal_trademarks** (str) - Optional - Trademark information.
- **private_build** (str) - Optional - Information about private builds.
- **special_build** (str) - Optional - Information about special builds.
- **language** (str) - Optional - The language identifier for the version resource. Defaults to 'neutral'.
- **code_page** (str) - Optional - The code page identifier for the version resource. Defaults to '1200' (UTF-16).

### Request Example
```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile(
    output_file="version_file.txt",
    version="1.2.3.4",
    company_name="Acme Corp",
    product_name="My App",
    file_description="My Application"
)
```

### Response
This function does not return a value but creates a file at the specified `output_file` path.
```

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

### create_versionfile_from_input_file()

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/_autodocs/README.md

Creates a version file by reading metadata from a specified input file, typically in YAML format.

```APIDOC
## create_versionfile_from_input_file()

### Description
Generates a version file by parsing metadata from an input file, commonly a YAML file.

### Signature
```python
create_versionfile_from_input_file(
    output_file: str,
    input_file: str,
    encoding: str = "utf-8"
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **output_file** (str) - Required - Path to the output version file.
- **input_file** (str) - Required - Path to the input metadata file (e.g., YAML).
- **encoding** (str) - Optional - Encoding of the input file. Defaults to "utf-8".

### Request Example
```python
import pyinstaller_versionfile

pyinstaller_versionfile.create_versionfile_from_input_file(
    output_file="version_file.txt",
    input_file="metadata.yml"
)
```

### Response
#### Success Response
None (writes to file)

#### Response Example
None
```

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

### Set Version from Command Line

Source: https://github.com/dudenr33/pyinstaller-versionfile/blob/master/README.md

Command to create a version file from YAML metadata, overwriting the version with a specific value using the --version option. Useful for CI build numbers.

```cmd
pyivf-make_version --source-format yaml --metadata-source metadata.yml --outfile file_version_info.txt --version 0.8.1.5
```