### Install and Execute PythonFuzz

Source: https://github.com/fuzzitdev/pythonfuzz/blob/master/README.md

Instructions for installing the PythonFuzz package via pip and executing a fuzzing target script from the command line.

```bash
pip install pythonfuzz
python examples/htmlparser/fuzz.py
```

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

### Fuzzing Compression Libraries

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Shows an example of fuzzing zlib decompression to find edge cases in compressed data handling.

```APIDOC
## Fuzzing Compression Libraries

### Description
Example of fuzzing zlib decompression to find edge cases in compressed data handling.

### Method
N/A (Fuzzing function)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
import zlib
from pythonfuzz.main import PythonFuzz


@PythonFuzz
def fuzz(buf):
    try:
        zlib.decompress(buf)
    except zlib.error:
        pass


if __name__ == '__main__':
    fuzz()

# Run: python fuzz_zlib.py ./zlib_corpus
```

### Response
N/A (Fuzzing function does not return a response in the traditional sense)

#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### PythonFuzz Application-Level Bug Detection with JSON

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Demonstrates detecting application-level bugs by implementing custom assertions within a fuzz target. This example checks for round-trip consistency of JSON parsing and re-serialization.

```python
from pythonfuzz.main import PythonFuzz
import json

@PythonFuzz
def fuzz(buf):
    try:
        string = buf.decode("utf-8")

        # Parse and re-serialize to check round-trip consistency
        parsed = json.loads(string)
        reserialized = json.dumps(parsed)
        reparsed = json.loads(reserialized)

        # Application-level check: verify round-trip produces same result
        if parsed != reparsed:
            raise AssertionError(f"Round-trip mismatch: {parsed} != {reparsed}")

    except (UnicodeDecodeError, json.JSONDecodeError):
        # Expected exceptions for invalid input
        pass


if __name__ == '__main__':
    fuzz()
```

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

### Fuzzing Python's HTML Parser

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

This example demonstrates how to use PythonFuzz to fuzz the built-in `html.parser.HTMLParser`. It defines a fuzz target function that decodes input bytes to ASCII, feeds them to the HTMLParser, and catches `UnicodeDecodeError`. This setup helps identify unhandled exceptions and edge cases within the HTML parsing logic.

```python
try:
    from html.parser import HTMLParser
except ImportError:
    from HTMLParser import HTMLParser

from pythonfuzz.main import PythonFuzz


@PythonFuzz
def fuzz(buf):
    try:
        string = buf.decode("ascii")
        parser = HTMLParser()
        parser.feed(string)
    except UnicodeDecodeError:
        pass


if __name__ == '__main__':
    fuzz()

# Run: python fuzz_html.py ./html_corpus
# Output:
# #0 READ units: 0
# #394378 NEW     cov: 608 corp: 24 exec/s: 1119 rss: 10.73828125 MB
# crash was written to crash-dbfa437e5956643645681fe6a3ac76997be0b29a7c7af82d88c8c390f379502d
```

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

### Managing Fuzzing Corpus

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Illustrates how to initialize a Corpus object, load seed directories, generate mutated inputs, and save new interesting test cases.

```python
from pythonfuzz.corpus import Corpus

corpus = Corpus(
    dirs=["./corpus", "./seeds"],
    max_input_size=4096,
    mutators_filter=None,
    dict_path="./dict.txt"
)

print(f"Corpus length: {corpus.length}")
mutated_input = corpus.generate_input()
new_input = bytearray(b"interesting test case")
corpus.put(new_input)
buf = bytearray(b"seed input")
mutated = corpus.mutate(buf)
```

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

### PythonFuzz Coverage Tracing

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Illustrates how PythonFuzz uses Python's trace functionality for coverage-guided mutation. It shows how to manually set the trace function and execute code to be traced.

```python
from pythonfuzz import tracer
import sys

# The tracer is automatically configured when using @PythonFuzz
# For manual usage:

# Set trace function
sys.settrace(tracer.trace)

# Execute code to trace
def target_function(data):
    if len(data) > 10:
        process_long(data)
    else:
        process_short(data)

target_function(b"test")

# Get total coverage (number of unique line transitions)
coverage = tracer.get_coverage()
print(f"Coverage: {coverage} unique transitions")

# Coverage is tracked as (previous_line, current_line) pairs per file
# Higher coverage numbers indicate more code paths explored
```

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

### CLI Interface

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

PythonFuzz provides a robust command-line interface for executing fuzzing sessions with various configuration flags.

```APIDOC
## CLI Execution

### Description
Run the fuzzer directly from the terminal using various flags to control behavior, resource limits, and mutation strategies.

### Common Flags
- **--rss-limit-mb** (int) - Memory limit in MB.
- **--timeout** (int) - Timeout per test case in seconds.
- **--runs** (int) - Number of iterations to perform.
- **--dict** (string) - Path to a dictionary file for smarter mutations.
- **--mutator-filter** (string) - Filter or exclude specific mutator types.

### Example
```bash
python fuzz.py --rss-limit-mb 1024 --timeout 60 ./corpus
```
```

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

### Using Dictionaries for Smarter Mutations

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Explains how to load and use dictionaries in PythonFuzz to inject domain-specific tokens into test inputs, enhancing the fuzzer's effectiveness.

```python
from pythonfuzz.dictionary import Dictionary

dictionary = Dictionary()
dictionary.load("./html.dict")
word = dictionary.get_word()
dictionary.load_directory("./dict_samples/")
```

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

### Fuzzing Archive Formats

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Demonstrates fuzz testing of Python's zipfile module to find issues in ZIP archive handling.

```APIDOC
## Fuzzing Archive Formats

### Description
Example demonstrating fuzz testing of Python's zipfile module to find issues in ZIP archive handling.

### Method
N/A (Fuzzing function)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
import io
import zipfile
from pythonfuzz.main import PythonFuzz

try:
    allowed_exceptions = (zipfile.BadZipFile, zipfile.LargeZipFile)
except AttributeError:
    # Python 2 compatibility
    allowed_exceptions = (zipfile.BadZipfile, zipfile.LargeZipFile)


@PythonFuzz
def fuzz(buf):
    f = io.BytesIO(buf)
    try:
        z = zipfile.ZipFile(f)
        z.testzip()
    except:
        pass


if __name__ == '__main__':
    fuzz()

# Run: python fuzz_zip.py ./zip_corpus
```

### Response
N/A (Fuzzing function does not return a response in the traditional sense)

#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Fuzzing Compression Libraries with PythonFuzz

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Shows how to fuzz the zlib decompression library. It catches zlib.error to prevent the fuzzer from crashing on malformed compressed data.

```python
import zlib
from pythonfuzz.main import PythonFuzz

@PythonFuzz
def fuzz(buf):
    try:
        zlib.decompress(buf)
    except zlib.error:
        pass

if __name__ == '__main__':
    fuzz()
```

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

### Fuzzing Archive Formats with PythonFuzz

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Demonstrates fuzz testing of the zipfile module. It includes compatibility logic for different Python versions and handles common ZIP-related exceptions.

```python
import io
import zipfile
from pythonfuzz.main import PythonFuzz

try:
    allowed_exceptions = (zipfile.BadZipFile, zipfile.LargeZipFile)
except AttributeError:
    allowed_exceptions = (zipfile.BadZipfile, zipfile.LargeZipFile)

@PythonFuzz
def fuzz(buf):
    f = io.BytesIO(buf)
    try:
        z = zipfile.ZipFile(f)
        z.testzip()
    except:
        pass

if __name__ == '__main__':
    fuzz()
```

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

### Dictionary Support

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Illustrates how PythonFuzz supports libFuzzer/AFL-style dictionaries for smarter mutations, enabling domain-specific token insertion.

```APIDOC
## Dictionary Support

### Description
PythonFuzz supports libFuzzer/AFL-style dictionaries for smarter mutations, allowing domain-specific tokens to be inserted into test inputs.

### Method
N/A (Class usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from pythonfuzz.dictionary import Dictionary

# Create and load dictionary from file
dictionary = Dictionary()
dictionary.load("./html.dict")

# Get random word from dictionary for mutation
word = dictionary.get_word()

# Dictionary file format (html.dict):
# # Comments start with #
# tag_html="<html>"
# tag_body="<body>"
# tag_script="<script>"
# attr_src="src="
# entity_amp="&amp;"
# entity_lt="&lt;"
# quote_double="\x22"
# quote_single="\x27"

# Load dictionary from directory of binary files
dictionary.load_directory("./dict_samples/")
```

### Response
N/A (Class usage)

#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Corpus Management

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Explains how to use the Corpus class for managing seed inputs and generated test cases, including mutation-based input generation and loading from files.

```APIDOC
## Corpus Management

### Description
The Corpus class manages seed inputs and generated test cases, providing mutation-based input generation with support for loading from files and directories.

### Method
N/A (Class usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from pythonfuzz.corpus import Corpus

# Initialize corpus with seed directories and configuration
corpus = Corpus(
    dirs=["./corpus", "./seeds"],  # First dir is used for saving new inputs
    max_input_size=4096,            # Maximum input size
    mutators_filter=None,           # Filter for mutator types
    dict_path="./dict.txt"          # Optional dictionary file
)

# Check corpus statistics
print(f"Corpus length: {corpus.length}")
print(f"Active mutators: {len(corpus.mutators)}")

# Generate mutated input from corpus
mutated_input = corpus.generate_input()

# Add new interesting input to corpus (saves to disk if dir exists)
new_input = bytearray(b"interesting test case")
corpus.put(new_input)

# Manually mutate a buffer
buf = bytearray(b"seed input")
mutated = corpus.mutate(buf)
```

### Response
N/A (Class usage)

#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Fuzzing XML Parser

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Demonstrates fuzz testing of Python's ElementTree XML parser with exception handling for parsing and encoding errors.

```APIDOC
## Fuzzing XML Parser

### Description
Example demonstrating fuzz testing of Python's ElementTree XML parser with proper exception handling for both parsing errors and encoding issues.

### Method
N/A (Fuzzing function)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
import xml.etree.ElementTree as ET
from xml.etree.ElementTree import ParseError
import sys

from pythonfuzz.main import PythonFuzz


@PythonFuzz
def fuzz(buf):
    try:
        # Handle Python 2/3 compatibility
        if sys.version_info[0] == 2:
            string = bytes(buf)
        else:
            string = buf.decode("utf-8")
        ET.fromstring(string)
    except (UnicodeDecodeError, ParseError):
        pass


if __name__ == '__main__':
    fuzz()

# Run: python fuzz_xml.py ./xml_corpus
```

### Response
N/A (Fuzzing function does not return a response in the traditional sense)

#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Fuzzing XML Parser with PythonFuzz

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Demonstrates how to fuzz the ElementTree XML parser. It handles potential UnicodeDecodeError and ParseError exceptions to ensure the fuzzer continues running.

```python
import xml.etree.ElementTree as ET
from xml.etree.ElementTree import ParseError
import sys
from pythonfuzz.main import PythonFuzz

@PythonFuzz
def fuzz(buf):
    try:
        if sys.version_info[0] == 2:
            string = bytes(buf)
        else:
            string = buf.decode("utf-8")
        ET.fromstring(string)
    except (UnicodeDecodeError, ParseError):
        pass

if __name__ == '__main__':
    fuzz()
```

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

### PythonFuzz Command Line Arguments

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

PythonFuzz offers a rich set of command-line arguments to control various aspects of the fuzzing process. These include specifying corpus directories, setting memory limits and timeouts, controlling the number of runs, defining maximum input size, using dictionary files for smarter mutations, and managing artifact paths and output suppression.

```bash
# Basic fuzzing with default settings
python fuzz.py

# Use corpus directories for seed inputs and saving new test cases
python fuzz.py ./corpus ./seeds

# Set memory limit to 1024 MB and timeout to 60 seconds per test case
python fuzz.py --rss-limit-mb 1024 --timeout 60 ./corpus

# Run specific number of iterations then stop
python fuzz.py --runs 10000 ./corpus

# Set maximum input size to 8192 bytes
python fuzz.py --max-input-size 8192 ./corpus

# Use a dictionary file for smarter mutations
python fuzz.py --dict ./html.dict ./corpus

# Specify exact path for crash artifacts
python fuzz.py --exact-artifact-path ./crash.bin ./corpus

# Suppress stdout/stderr (close-fd-mask: 1=stdout, 2=stderr, 3=both)
python fuzz.py --close-fd-mask 3 ./corpus

# Run in regression mode to test existing corpus files
python fuzz.py --regression true ./corpus

# Filter mutators by type
python fuzz.py --mutator-filter "byte replace" ./corpus

# Exclude specific mutator types
python fuzz.py --mutator-filter "!dictionary" ./corpus

# Display available mutators and their types
python fuzz.py --help-mutators
```

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

### Implement a PythonFuzz Fuzz Target

Source: https://github.com/fuzzitdev/pythonfuzz/blob/master/README.md

This snippet demonstrates how to define a fuzz target using the @PythonFuzz decorator. The function receives a buffer of random data, which is then passed to the target library, with exceptions handled to prevent the fuzzer from stopping prematurely.

```python
from html.parser import HTMLParser
from pythonfuzz.main import PythonFuzz

@PythonFuzz
def fuzz(buf):
    try:
        string = buf.decode("ascii")
        parser = HTMLParser()
        parser.feed(string)
    except UnicodeDecodeError:
        pass

if __name__ == '__main__':
    fuzz()
```

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

### Basic PythonFuzz Fuzz Target

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

A basic fuzz target function decorated with @PythonFuzz. It processes input buffer 'buf' and handles expected exceptions.

```python
from pythonfuzz.main import PythonFuzz

@PythonFuzz
def fuzz(buf):
    try:
        process(buf)
    except ExpectedException:
        pass

if __name__ == '__main__':
    fuzz()
```

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

### Custom Mutators

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

Explains how to use custom mutators in PythonFuzz, including filtering mutator types and viewing available mutators.

```APIDOC
## Custom Mutators

### Description
PythonFuzz includes multiple built-in mutators that can be filtered by type. Available mutator types include: byte, bit, short, long, longlong, ascii, text, dictionary, remove, insert, duplicate, copy, replace, swap, addsub, and append.

### Method
N/A (Command-line arguments and code usage)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
from pythonfuzz.main import PythonFuzz

# Run with only byte-level mutations
# python fuzz.py --mutator-filter "byte" ./corpus

# Run with replace operations only
# python fuzz.py --mutator-filter "replace" ./corpus

# Exclude dictionary-based mutations
# python fuzz.py --mutator-filter "!dictionary" ./corpus

# Combine filters: byte operations that are replacements
# python fuzz.py --mutator-filter "byte replace" ./corpus

# View all available mutators and their types
# python fuzz.py --help-mutators
# Output:
#   Remove a range of bytes                                      [byte, remove]
#   Insert a range of random bytes                               [byte, insert]
#   Duplicate a range of bytes                                   [byte, duplicate]
#   Copy a range of bytes                                        [byte, copy]
#   Bit flip                                                     [bit, replace]
#   Set a byte to a random value.                                [byte, replace]
#   Swap 2 bytes                                                 [byte, swap]
#   Add/subtract from a byte                                     [byte, addsub]
#   Add/subtract from a uint16                                   [short, addsub]
#   Add/subtract from a uint32                                   [long, addsub]
```

### Response
N/A (Command-line arguments and code usage)

#### Success Response (200)
N/A

#### Response Example
N/A
```

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

### Fuzzer Class

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

The Fuzzer class allows for programmatic control over the fuzzing process, providing granular configuration options for memory limits, timeouts, and corpus management.

```APIDOC
## Fuzzer Class

### Description
The Fuzzer class provides a programmatic interface to configure and start the fuzzing engine without relying on CLI arguments.

### Configuration Parameters
- **target** (callable) - Required - The function to fuzz.
- **dirs** (list) - Optional - List of directories for corpus and seed files.
- **rss_limit_mb** (int) - Optional - Memory limit in MB.
- **timeout** (int) - Optional - Timeout per test case in seconds.
- **max_input_size** (int) - Optional - Maximum input size in bytes.
- **runs** (int) - Optional - Number of iterations (-1 for infinite).

### Usage Example
```python
from pythonfuzz.fuzzer import Fuzzer

fuzzer = Fuzzer(target=my_target, rss_limit_mb=2048, timeout=120)
fuzzer.start()
```
```

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

### Python Fuzzer Class for Programmatic Control

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

The Fuzzer class in PythonFuzz allows for programmatic configuration and execution of fuzzing operations. It enables users to instantiate the fuzzer, define a target function, and set various fuzzing parameters such as corpus directories, memory limits, timeouts, and mutator filters directly within their Python code.

```python
from pythonfuzz.fuzzer import Fuzzer

def my_target(buf):
    try:
        data = buf.decode("utf-8")
        process_data(data)
    except UnicodeDecodeError:
        pass

# Create fuzzer with custom configuration
fuzzer = Fuzzer(
    target=my_target,
    dirs=["./corpus", "./seeds"],      # Corpus directories
    exact_artifact_path=None,           # Path for crash files (None = auto-generated)
    rss_limit_mb=2048,                  # Memory limit in MB
    timeout=120,                        # Timeout per test case in seconds
    regression=False,                   # Regression testing mode
    max_input_size=4096,                # Maximum input size in bytes
    close_fd_mask=0,                    # FD closing mask (1=stdout, 2=stderr)
    runs=-1,                            # Number of runs (-1 = infinite)
    mutators_filter=None,               # Mutator type filter
    dict_path=None                      # Dictionary file path
)

# Display available mutators
fuzzer.help_mutators()

# Start the fuzzing loop
fuzzer.start()
```

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

### PythonFuzz Decorator for Fuzz Targets

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

The @PythonFuzz decorator transforms a Python function into a fuzz target. The decorated function accepts random byte buffers as input and should contain the logic to test the target code, including catching expected exceptions for invalid inputs. This enables easy integration with the PythonFuzz framework.

```python
from pythonfuzz.main import PythonFuzz

@PythonFuzz
def fuzz(buf):
    try:
        # Convert bytes to string and test target
        string = buf.decode("utf-8")
        my_parser.parse(string)
    except (UnicodeDecodeError, ValueError):
        # Catch expected exceptions for invalid input
        pass

if __name__ == '__main__':
    fuzz()
```

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

### @PythonFuzz Decorator

Source: https://context7.com/fuzzitdev/pythonfuzz/llms.txt

The @PythonFuzz decorator is the primary interface for creating a fuzz target, transforming a standard function into a fuzzer-compatible entry point.

```APIDOC
## @PythonFuzz Decorator

### Description
The @PythonFuzz decorator wraps a target function, allowing it to receive random byte buffers for fuzzing. It automatically handles the execution loop and crash detection.

### Method
Decorator

### Parameters
- **target_function** (callable) - Required - The function to be fuzzed. It must accept a single argument (the byte buffer).

### Request Example
```python
from pythonfuzz.main import PythonFuzz

@PythonFuzz
def fuzz(buf):
    try:
        string = buf.decode("utf-8")
        my_parser.parse(string)
    except (UnicodeDecodeError, ValueError):
        pass
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.