### Options Parameter Examples

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Examples showcasing various ways to use the 'options' parameter for barcode customization.

```python
import treepoem

# QR code with high error correction
image = treepoem.generate_barcode(
    "qrcode",
    "https://example.com",
    options={"eclevel": "H"},
)

# Code 128 with human-readable text
image = treepoem.generate_barcode(
    "code128",
    "BARCODE123",
    options={"includetext": True},
)

# EAN-13 with multiple options
image = treepoem.generate_barcode(
    "ean13",
    "5901234123457",
    options={
        "includetext": True,
        "width": "2",
    },
)

# PDF417 with custom dimensions
image = treepoem.generate_barcode(
    "pdf417",
    "Multi-line content",
    options={
        "columns": "3",
        "rows": "10",
    },
)

# Multiple mixed options
image = treepoem.generate_barcode(
    "code39",
    "HELLO",
    options={
        "includetext": True,
        "width": "1.5",
        "parse": True,
    },
)
```

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

### Error: Ghostscript Not Found

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Example of a traceback indicating that Ghostscript is not installed or cannot be found.

```bash
$ treepoem -o barcode.png "data"
Traceback (most recent call last):
  ...
treepoem.TreepoemError: Cannot determine path to ghostscript, is it installed?
```

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

### Scale Parameter Examples

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Examples demonstrating the use of the 'scale' parameter to control barcode image size.

```python
import treepoem

# Small barcode (scale=1)
image = treepoem.generate_barcode("qrcode", "data", scale=1)
# Size: ~83x83 pixels for typical QR code

# Default medium barcode (scale=2, default)
image = treepoem.generate_barcode("qrcode", "data")
# Size: ~166x166 pixels

# Large barcode (scale=4)
image = treepoem.generate_barcode("qrcode", "data", scale=4)
# Size: ~332x332 pixels
```

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

### Ghostscript installation check and install commands

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Commands to check if Ghostscript is installed and how to install it on Linux/macOS.

```bash
# Check if Ghostscript is installed
gs --version

# Install if missing
# Ubuntu/Debian: apt-get install ghostscript
# macOS: brew install ghostscript
```

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

### _hexify() Example

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

Example usage of the `_hexify` function demonstrating its output for short and long strings.

```python
_hexify("Hello")  # → "<48656c6c6f>"
_hexify("Long data...")  # → "<...\n ...>" (wrapped at 72 chars)
```

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

### CLI Usage

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/00-OVERVIEW.txt

Example of how to use the treepoem command-line interface.

```bash
treepoem -t qrcode -o out.png "data"
```

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

### Configuration from Dictionary

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Python example showing how to generate a barcode using a configuration dictionary.

```python
import treepoem

config = {
    "barcode_type": "code128",
    "data": "EXAMPLE123",
    "options": {"includetext": True, "width": "1.5"},
    "scale": 2,
}

image = treepoem.generate_barcode(**config)
```

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

### Install Treepoem

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Install Treepoem using pip.

```sh
python -m pip install treepoem
```

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

### BWIPP Options (CLI) Example

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Demonstrates how to pass BWIPP options as positional arguments in the CLI.

```sh
treepoem -t barcode_type "data" option1=value option2 option3=value
```

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

### Windows Installation

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/README.md

Instructions for installing Treepoem on Windows, including a note about Ghostscript.

```cmd
REM Install Ghostscript from https://ghostscript.com/download/gsdnld.html
pip install treepoem
```

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

### Installation

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/README.md

Installs the treepoem library and the ghostscript dependency.

```bash
pip install treepoem
apt-get install ghostscript  # or: brew install ghostscript
```

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

### Scenario 1: Ghostscript not installed

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Example scenario for handling the error when Ghostscript is not installed or accessible.

```python
# Scenario 1: Ghostscript not installed
try:
    image = treepoem.generate_barcode("qrcode", "test")
except treepoem.TreepoemError as e:
    if "Cannot determine path to ghostscript" in str(e):
        print("Please install Ghostscript: apt-get install ghostscript")
```

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

### Use the command-line tool

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Example of using the treepoem command-line tool to generate a QR code.

```bash
treepoem -t qrcode -o qr.png "https://example.com"
```

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

### Ubuntu/Debian Installation

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/README.md

Instructions for installing Treepoem and its dependencies on Ubuntu/Debian-based systems.

```bash
apt-get install ghostscript
python -m pip install treepoem
```

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

### Install Ghostscript on Ubuntu/Debian

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Install Ghostscript on Ubuntu/Debian systems.

```sh
apt-get install ghostscript
```

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

### Example with Type Checking

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/types.md

An example demonstrating how to use Treepoem with type hints and static type checking.

```python
import treepoem
from PIL import Image

def generate_and_save(
    barcode_code: str,
    data: str | bytes,
    output_file: str,
    scale: int = 2,
) -> None:
    """Generate a barcode and save it, with full type hints."""
    
    # This will be type-checked
    barcode_type: str = barcode_code
    barcode_data: str | bytes = data
    options: dict[str, str | bool] | None = None
    
    # Return type is Image.Image
    image: Image.Image = treepoem.generate_barcode(
        barcode_type,
        barcode_data,
        options,
        scale=scale,
    )
    
    # Type-safe image operations
    image.save(output_file)
    image.close()

# Type-safe call
generate_and_save("qrcode", "https://example.com", "out.png")
generate_and_save("code128", b"binary_data", "out.png", scale=4)
```

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

### macOS Installation

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/README.md

Instructions for installing Treepoem and its dependencies on macOS using Homebrew.

```bash
brew install ghostscript
pip install treepoem
```

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

### Type-Safe Configuration

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Python example using TypedDict for type-safe barcode configuration.

```python
from typing import TypedDict
import treepoem

class BarcodeConfig(TypedDict, total=False):
    """Type-safe barcode configuration."""
    barcode_type: str
    data: str
    options: dict[str, str | bool]
    scale: int

config: BarcodeConfig = {
    "barcode_type": "qrcode",
    "data": "https://example.com",
    "options": {"eclevel": "H"},
    "scale": 4,
}

image = treepoem.generate_barcode(**config)
```

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

### Command-Line

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/README.md

Example of using the treepoem command-line interface.

```bash
treepoem -t qrcode -o output.png "data"
```

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

### Default scale override

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Example showing how to override the default scale for barcode generation.

```sh
# Default scale 2, can override
trepoem -s 4 -t qrcode -o qr_large.png "data"
```

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

### Multiple BWIPP options

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Example demonstrating the use of multiple BWIPP options for an EAN-13 barcode.

```sh
# Multiple BWIPP options
trepoem -t ean13 -o barcode.png "5901234123457" includetext width=2
```

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

### Generate multiple QR codes and pipe to another process

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Examples of using the treepoem CLI in shell scripts for generating multiple QR codes and piping output to another process.

```bash
#!/bin/bash

# Generate multiple QR codes
for url in "https://example.com" "https://example.org"; do
    filename=$(echo "$url" | md5sum | cut -d' ' -f1).png
    treepoem -t qrcode -o "$filename" "$url"
done

# Pipe to another process
trepoem -f png "data" | convert - -background white -alpha off barcode.jpg
```

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

### Error: Unsupported Output Format

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Example of an error message when an unsupported output format is specified.

```bash
$ treepoem -f invalid-format -o output.png "data"
usage: treepoem [-t TYPE] [-o OUTPUT] [-f FORMAT] [-s SCALE] DATA [OPTIONS...]
treepoem: error: Image format 'invalid-format' is not supported
```

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

### Install Ghostscript on Mac OS X

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Install Ghostscript on Mac OS X systems.

```sh
brew install ghostscript
```

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

### Example of NotImplementedError

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Example demonstrating how to catch and handle NotImplementedError when an unsupported barcode type is requested.

```python
import treepoem

try:
    image = treepoem.generate_barcode("invalid-barcode-type", "data")
except NotImplementedError as e:
    print(f"Error: {e}")
    # Output: Error: unsupported barcode type 'invalid-barcode-type'
    
    # List available types
    print("Available types:", ", ".join(sorted(treepoem.barcode_types.keys())))
```

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

### Generate a QR code with a border and save to file

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Example of generating a QR code, adding a border, and saving it to a file.

```python
import treepoem
from PIL import ImageOps

image = treepoem.generate_barcode(
    barcode_type="qrcode",
    data="https://example.com",
)
image = ImageOps.expand(image, border=10, fill="white")
image.convert("1").save("barcode.png")
```

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

### Check Ghostscript version

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Check the installed Ghostscript version.

```sh
gs --version
```

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

### Function-Level Caching with functools.cache

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

Python code examples demonstrating the use of the @cache decorator for function-level caching of BWIPP loading and Ghostscript binary lookup.

```python
@cache  # from functools
def load_bwipp() -> str:
    # File I/O only happens on first call
    ...

@cache
def _ghostscript_binary() -> str:
    # Subprocess only spawned on first call
    ...

```

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

### PIL Image Usage Example

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/types.md

An example demonstrating the generation of a barcode and interaction with the returned PIL Image object.

```python
import treepoem
from PIL import Image

image = treepoem.generate_barcode("qrcode", "data")

# Check that it's a PIL Image
assert isinstance(image, Image.Image)

# Get image size
width, height = image.size
print(f"Image: {width}x{height} pixels")

# Convert to monochrome and save
image.convert("1").save("barcode.png")

# Clean up
image.close()
```

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

### Generate Barcode with Custom Options

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Example showing how to use custom options and scale parameters when generating a barcode.

```python
import treepoem

image = treepoem.generate_barcode(
    "qrcode",
    "data",
    options={"eclevel": "H"},
    scale=4,
)
```

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

### Generate and Save Barcode

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Basic usage example showing how to generate a barcode image and save it to a file.

```python
import treepoem

image = treepoem.generate_barcode("qrcode", "data")
image.save("barcode.png")
```

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

### Error: BWIPP Error

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Example of a traceback for a BWIPP error, such as invalid data for a barcode type.

```bash
$ treepoem -t code39 "invalid@#$"
Traceback (most recent call last):
  ...
treepoem.TreepoemError: BWIPP error message describing why the barcode could not be generated
```

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

### Code 128 with text

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Example of generating a Code 128 barcode that includes the text.

```sh
# Code 128 with text
trepoem -t code128 -o barcode.png "DATA" includetext width=1.5
```

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

### Generate a barcode

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Example of generating a QR code image using the treepoem library.

```python
import treepoem
image = treepoem.generate_barcode("qrcode", "https://example.com")
image.save("qr.png")
```

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

### QR code with high error correction

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Example of generating a QR code with high error correction level.

```sh
# QR code with high error correction
trepoem -t qrcode -o qr.png "https://example.com" eclevel=H
```

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

### Error: Unsupported Barcode Type

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Example of an error message when an unsupported barcode type is provided.

```bash
$ treepoem -t invalid-type "data"
usage: treepoem [-t TYPE] [-o OUTPUT] [-f FORMAT] [-s SCALE] DATA [OPTIONS...]
treepoem: error: Barcode type "invalid-type" is not supported. Supported barcode types are:
    auspost, azteccode, azteccodecompact, ...
```

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

### Barcode Options Usage Examples

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/types.md

Illustrates various ways to use the Barcode Options dictionary with treepoem.generate_barcode.

```python
import treepoem

# QR code with high error correction
options: dict[str, str | bool] = {"eclevel": "H"}
image = treepoem.generate_barcode("qrcode", "data", options=options)

# EAN-13 with text and custom width
options = {
    "includetext": True,
    "width": "2",
}
image = treepoem.generate_barcode("ean13", "5901234123457", options=options)

# Multiple boolean options
options = {
    "includetext": True,
    "parse": True,
}
image = treepoem.generate_barcode("code128", "data", options=options)

# Mixed string and boolean
options = {
    "width": "1.5",
    "includetext": True,
}
image = treepoem.generate_barcode("code39", "HELLO", options=options)
```

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

### BarcodeType Usage Example

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/types.md

Demonstrates how to access and use BarcodeType instances from the treepoem.barcode_types dictionary.

```python
import treepoem

qr = treepoem.barcode_types["qrcode"]
assert isinstance(qr, treepoem.BarcodeType)
assert qr.type_code == "qrcode"
assert qr.description == "QR Code"
```

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

### Generate Barcode with Error Handling

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Example demonstrating how to handle potential errors during barcode generation, including NotImplementedError and custom TreepoemError.

```python
import treepoem

try:
    image = treepoem.generate_barcode("qrcode", "data")
except NotImplementedError:
    print("Type not supported")
except treepoem.TreepoemError as e:
    print(f"Generation failed: {e}")
```

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

### Options Parameter Structure

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Illustrates the structure for passing BWIPP-specific options as a dictionary.

```python
options: dict[str, str | bool] = {
    "option_name": "string_value",      # String option: renders as option_name=string_value
    "flag_option": True,                # Boolean True: renders as flag_option
    "disabled_option": False,           # Boolean False: omitted from options
}
```

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

### Import

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/00-OVERVIEW.txt

How to import necessary components from the treepoem library.

```python
from treepoem import generate_barcode, BarcodeType, barcode_types, TreepoemError
```

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

### Generate QR Code to File

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Generates a QR code encoding a URL and saves it to a PNG file.

```bash
treepoem -o qrcode.png "https://example.com"
```

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

### Help command

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Shows complete usage instructions.

```bash
treepoem --help
```

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

### Clearing Ghostscript and BWIPP caches for testing

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Python code demonstrating how to manually clear the Ghostscript and BWIPP caches.

```python
import treepoem

# Clear the ghostscript binary cache (for testing)
trepoem._ghostscript_binary.cache_clear()

# Clear the BWIPP code cache (for testing)
trepoem.load_bwipp.cache_clear()
```

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

### Basic Usage

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/00-OVERVIEW.txt

Demonstrates the fundamental steps to generate and save a barcode.

```python
image = generate_barcode("qrcode", "data")
image.save("barcode.png")
```

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

### Type-Safe Code Example

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Example of a type-hinted function for generating barcodes, ensuring type safety.

```python
from PIL import Image
import treepoem

def generate(barcode_type: str, data: str) -> Image.Image:
    return treepoem.generate_barcode(barcode_type, data)
```

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

### _format_options() function

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

Converts a dictionary of BWIPP options into a PostScript string format.

```python
def _format_options(options: dict[str, str | bool]) -> str:
    """Format BWIPP options dictionary into PostScript string."""
    items = []
    for name, value in options.items():
        if isinstance(value, bool):
            if value:
                items.append(name)
        else:
            items.append(f"{name}={value}")
    return " ".join(items)
```

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

### Example of ValueError for scale

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Example demonstrating how to catch and handle ValueError when the 'scale' parameter is invalid (less than 1).

```python
import treepoem

try:
    image = treepoem.generate_barcode("qrcode", "data", scale=0)
except ValueError as e:
    print(f"Error: {e}")
    # Output: Error: scale must be at least 1

# Correct usage
image = treepoem.generate_barcode("qrcode", "data", scale=1)
```

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

### QR Code to stdout with Explicit Format

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Generates a QR code and outputs raw PNG bytes to stdout, which can be piped to a file.

```bash
treepoem -f png -t qrcode "data" > barcode.png
```

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

### CLI Argument Parsing Errors Examples

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Examples of command-line interface errors for unsupported barcode types, invalid scale values, and unsupported image formats.

```sh
# Unsupported barcode type
$ treepoem -t invalid "data"
trepoem: error: Barcode type "invalid" is not supported. ...

# Invalid scale
$ treepoem -s abc "data"
trepoem: error: Scale should be a positive integer value. Found "abc" instead.

# Unsupported format
$ treepoem -f unknown -o out.png "data"
trepoem: error: Image format 'unknown' is not supported
```

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

### Module Organization: Resource Files

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

Location of the vendored BWIPP PostScript library within the Treepoem package.

```text
treepoem/postscriptbarcode/
└── barcode.ps — BWIPP library (vendored, ~900KB PostScript)
```

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

### QR Code to stdout in XBM Format (Default)

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Generates a barcode to stdout, defaulting to XBM format when no format is specified.

```bash
treepoem "barcodedata" > barcode.xbm
```

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

### Python API

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/README.md

Example of using the generate_barcode function from the Python API.

```python
from treepoem import generate_barcode

image = generate_barcode(barcode_type="qrcode", data="data")
```

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

### Basic Barcode Generation

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/barcode_types.md

Example of generating a Code128 barcode and saving it to a file.

```python
image = user_generate_barcode("code128", "Hello123")
image.save("barcode.png")
```

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

### QR Code with High Error Correction

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Generates a QR code with high error correction level by passing 'eclevel=H' to BWIPP.

```bash
treepoem -t qrcode -o qrcode.png "Test data" eclevel=H
```

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

### Error: Invalid Scale Value

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Example of an error message when an invalid scale value is provided.

```bash
$ treepoem -s invalid-scale "data"
usage: treepoem [-t TYPE] [-o OUTPUT] [-f FORMAT] [-s SCALE] DATA [OPTIONS...]
treepoem: error: Scale should be a positive integer value. Found "invalid-scale" instead.
```

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

### Download BWIPP script

Source: https://github.com/adamchainz/treepoem/blob/main/README.rst

Script to download a specific version of BWIPP.

```bash
./download_bwipp.py
```

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

### Handle errors properly

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/INDEX.md

Example of handling potential Treepoem errors during barcode generation.

```python
try:
    image = treepoem.generate_barcode("qrcode", data)
except treepoem.TreepoemError as e:
    print(f"Error: {e}")
```

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

### Ghostscript caching implementation details

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Python code illustrating the use of the `@cache` decorator for Ghostscript and BWIPP library loading.

```python
@cache
def load_bwipp() -> str:
    # Loads and caches BWIPP PostScript library
    ...

@cache
def _ghostscript_binary() -> str:
    # Finds and caches Ghostscript binary path
    ...
```

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

### Safe Configuration with Defaults

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/configuration.md

Python function demonstrating safe barcode creation with default values and validation.

```python
import treepoem

def create_barcode(
    barcode_type: str = "qrcode",
    data: str = "",
    options: dict[str, str | bool] | None = None,
    scale: int = 2,
):
    """Create a barcode with validation."""
    
    # Validate barcode type
    if barcode_type not in treepoem.barcode_types:
        raise ValueError(f"Unknown barcode type: {barcode_type}")
    
    # Validate scale
    if scale < 1:
        raise ValueError(f"Scale must be >= 1, got {scale}")
    
    # Validate data
    if not data:
        raise ValueError("Data cannot be empty")
    
    # Generate
    return treepoem.generate_barcode(
        barcode_type=barcode_type,
        data=data,
        options=options or {},
        scale=scale,
    )
```

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

### _format_data_options_encoder() function

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

Prepares data, options, and barcode type for a BWIPP invocation in PostScript format.

```python
def _format_data_options_encoder(
    data: str | bytes,
    options: dict[str, str | bool],
    barcode_type: str,
) -> str:
    """Format data, options, and barcode type for PostScript."""
    return (
        f"{_hexify(data)}
{_hexify(_format_options(options))}
"
        f"{_hexify(barcode_type)} cvn"
    )
```

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

### System Overview

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

The overall flow of generating a barcode using Treepoem, involving user code, validation, Ghostscript for bounding box calculation and rendering, and finally returning a PIL Image.

```text
User Code
    ↓
generate_barcode()
    ↓
Validation & Encoding
    ↓
Ghostscript (Pass 1: bbox) → Bounding Box
    ↓
Ghostscript (Pass 2: render) → PNG Image
    ↓
PIL Image.Image (returned)
```

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

### Scenario 3: Invalid BWIPP option

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Example scenario for handling a BWIPP error caused by an invalid option.

```python
# Scenario 3: Invalid BWIPP option
try:
    image = treepoem.generate_barcode(
        "qrcode", 
        "data",
        options={"invalidoption": "value"}
    )
except treepoem.TreepoemError as e:
    print(f"Invalid option: {e}")
```

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

### Multiple BWIPP Options

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/cli.md

Generates an EAN-13 barcode with BWIPP options 'includetext' and 'width=1.5'.

```bash
treepoem -t ean13 -o barcode.png "5901234123457" includetext width=1.5
```

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

### Basic QR Code

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/generate_barcode.md

Generates a basic QR code and saves it as a PNG file.

```python
import treepoem

image = treepoem.generate_barcode(
    barcode_type="qrcode",
    data="https://example.com",
)
image.save("qrcode.png")
```

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

### Get Barcode Type Information

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/barcode_types.md

Illustrates how to retrieve a `BarcodeType` object from the `barcode_types` dictionary and access its attributes.

```python
import treepoem

# Get metadata for a specific barcode type
aztec_type = treepoem.barcode_types["azteccode"]
print(f"Type code: {aztec_type.type_code}")
print(f"Description: {aztec_type.description}")
```

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

### Checking Before Generation for NotImplementedError

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Example showing how to check if a barcode type is supported before attempting to generate it, thus preventing NotImplementedError.

```python
import treepoem

barcode_type = "qrcode"
if barcode_type not in treepoem.barcode_types:
    raise NotImplementedError(f"unsupported barcode type {barcode_type!r}")

image = treepoem.generate_barcode(barcode_type, "data")
```

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

### Document Dependencies

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/MANIFEST.md

A visual representation of how the documentation files are interconnected, showing the main entry points and their related pages.

```markdown
INDEX.md (start here)
  ├─ README.md (overview)
  ├─ api-reference/generate_barcode.md (main function)
  │   ├─ types.md (parameter types)
  │   ├─ errors.md (exceptions)
  │   └─ configuration.md (parameters)
  │
  ├─ api-reference/barcode_types.md (type list)
  │   ├─ api-reference/barcode_type.md (metadata)
  │   └─ types.md (BarcodeType definition)
  │
  ├─ api-reference/cli.md (command-line)
  │   ├─ configuration.md (CLI arguments)
  │   └─ errors.md (CLI errors)
  │
  ├─ types.md (type system)
  │
  ├─ errors.md (error handling)
  │
  ├─ configuration.md (all options)
  │
  └─ ARCHITECTURE.md (internals)

```

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

### Scenario 2: BWIPP error (invalid data for barcode type)

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/errors.md

Example scenario for handling a BWIPP error due to invalid data for the barcode type.

```python
# Scenario 2: BWIPP error (invalid data for barcode type)
try:
    # Code 39 only supports uppercase letters and numbers
    image = treepoem.generate_barcode("code39", "hello123")
except treepoem.TreepoemError as e:
    print(f"BWIPP error: {e}")
    # BWIPP might report: "Must be alphanumeric uppercase" or similar
```

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

### Windows-Specific Ghostscript Binary Handling

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/ARCHITECTURE.md

Python code snippet for handling different Ghostscript binary names on Windows platforms.

```python
if sys.platform.startswith("win"):
    options = ("gswin32c", "gswin64c", "gs")

```

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

### Building a UI Dropdown of Supported Types

Source: https://github.com/adamchainz/treepoem/blob/main/_autodocs/api-reference/barcode_type.md

Illustrates how to prepare a list of barcode types for use in a UI dropdown, sorted by description.

```python
import treepoem

# Sort barcode types by description for display
sorted_types = sorted(
    treepoem.barcode_types.items(),
    key=lambda item: item[1].description,
)

# Create UI options
options = [
    (barcode_type.type_code, barcode_type.description)
    for _, barcode_type in sorted_types
]
```