### Install packaging and run standalone script

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/installation.rst

Installs the 'packaging' dependency and then runs the standalone 'req2flatpak.py' script. Ensure Python is installed.

```bash
pip install packaging
```

```bash
./req2flatpak.py --help
```

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

### Install req2flatpak from Git

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/installation.rst

Installs req2flatpak directly from its Git repository. Useful for testing experimental versions or specific branches/commits.

```bash
pip install git+https://github.com/johannesjh/req2flatpak
```

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

### Example Usage of req2flatpak Python API

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

This example demonstrates a basic workflow for generating a Flatpak build module using the req2flatpak Python API. It covers defining target platforms, specifying Python packages, querying PyPI, selecting compatible downloads, and generating the build module.

```APIDOC
## Example Usage of req2flatpak Python API

### Description
This example demonstrates a basic workflow for generating a Flatpak build module using the req2flatpak Python API. It covers defining target platforms, specifying Python packages, querying PyPI, selecting compatible downloads, and generating the build module.

### Code Example
```python
# This code is a placeholder and represents the structure of the example usage.
# Actual implementation details are found in the source file.

# Step 1: Define target platforms
# platform_factory = PlatformFactory()
# target_platforms = [platform_factory.create_platform(...)]

# Step 2: Specify Python packages
# requirements_parser = RequirementsParser()
# requirements = requirements_parser.parse_requirements_file('requirements.txt')

# Step 3: Query PyPi about available downloads
# releases = query_pypi(requirements, target_platforms)

# Step 4: Choose downloads compatible with target platforms
# compatible_releases = select_compatible_releases(releases, target_platforms)

# Step 5: Generate the flatpak-builder build module
# build_module = generate_build_module(compatible_releases)

# print(build_module)
```

### Notes
The process involves defining target platforms, specifying package requirements, querying package indices, selecting compatible releases, and finally generating the Flatpak build module.
```

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

### Install req2flatpak using pip

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/installation.rst

Installs the latest release of req2flatpak as a Python package. Use this to verify the installation.

```bash
pip install req2flatpak
```

```bash
req2flatpak --help
```

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

### List Installed Packages (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Prints all installed Python packages in a format compatible with requirements.txt.

```bash
# Print all installed packages in requirements.txt format
./req2flatpak.py --installed-packages
```

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

### Generate Flatpak Build Module for Python Packages

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Use this example to generate a Flatpak build module for installing Python packages on a specific target platform. It outlines the five key steps involved in the process.

```python
from pathlib import Path

from req2flatpak.platform_factory import PlatformFactory
from req2flatpak.requirements_parser import RequirementsParser


def example_usage1_start():
    # 1. Define the target platforms
    platforms = PlatformFactory.get_platforms("linux", "x86_64")

    # 2. Specify the python packages to be installed
    requirements = RequirementsParser.parse_requirements(
        Path("requirements.txt"), platforms=platforms
    )

    # 3. Query PyPi about available downloads
    releases = RequirementsParser.get_releases(requirements)

    # 4. Choose downloads that are compatible with the target platforms
    build_modules = RequirementsParser.get_build_modules(requirements, releases, platforms)

    # 5. Generate the flatpak-builder build module
    flatpak_module = build_modules[0].render_flatpak_module()

    return flatpak_module

example_usage1_end = None
```

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

### CLI - Query Platform and Installed Package Information

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Inspect the current runtime environment to determine platform strings and list installed packages in requirements.txt format.

```APIDOC
## CLI - Query Platform and Installed Package Information

Inspect the current runtime environment; useful for determining platform strings when building on the same machine as the target.

```bash
# Print the current platform's Python version and compatibility tags
./req2flatpak.py --platform-info
# Output (truncated):
# {
#     "python_version": ["3", "10", "6"],
#     "python_tags": [
#         "cp310-cp310-manylinux_2_35_x86_64",
#         "cp310-cp310-manylinux_2_34_x86_64",
#         ...
#     ]
# }

# Print all installed packages in requirements.txt format
./req2flatpak.py --installed-packages
# Output:
# requests==2.28.1
# numpy==1.23.4
# ...
```
```

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

### Install and Configure Pre-commit Hooks

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/development.rst

Install pre-commit using pipx and then initialize it in the local repository to enforce code quality checks before commits. Run pre-commit to lint all code or only staged changes.

```bash
# to install pre-commit on your system,
# follow instructions from https://pre-commit.com/, for example:
pipx install pre-commit

# to install the pre-commit git hooks in the cloned req2flatpak repo
pre-commit install  # activates pre-commit in the current git repo

# to prettify and lint all code
pre-commit run --all

# to prettify and lint only staged changes
pre-commit run
```

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

### Customization Options Example

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Demonstrates advanced customization using the req2flatpak Python API. This snippet is part of a larger test suite and shows how to modify build steps.

```python
def example_customization1_start():
    # This is a placeholder for the start of the example
    pass

def example_customization1_end():
    # This is a placeholder for the end of the example
    pass

# The actual code for customization would be between these markers in the test file.
```

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

### Full Pipeline: End-to-End Python API Example

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Combines all steps: parsing requirements, querying PyPI, choosing downloads for multiple platforms, and generating a JSON build module. Excludes common runtime packages like setuptools and pip.

```python
from req2flatpak import (
    DownloadChooser, FlatpakGenerator, PlatformFactory,
    PypiClient, RequirementsParser,
)
import json, shelve

# Step 1 – Define target platforms
platforms = [
    PlatformFactory.from_string("cp310-x86_64"),
    PlatformFactory.from_string("cp310-aarch64"),
]

# Step 2 – Parse pinned requirements
requirements = RequirementsParser.parse_file("requirements.txt")

# Remove any packages already bundled with the Flatpak runtime
requirements = [r for r in requirements if r.package not in {"setuptools", "pip"}]

```

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

### Create Platform Objects using PlatformFactory

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Demonstrates how to create platform objects using the PlatformFactory. These objects define the environment for package installation.

```python
from req2flatpak.platform_factory import PlatformFactory

def example_usage1_start():
    # Create platform objects for Linux x86_64
    platforms = PlatformFactory.get_platforms("linux", "x86_64")
    return platforms

example_usage1_end = None
```

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

### Query PyPI for available releases using PypiClient

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Use PypiClient to query the PyPI index for available package releases. This example demonstrates basic usage for fetching release information.

```python
client = PypiClient()
release = client.get_release(package_name='requests')
print(release.name, release.version)
```

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

### Query Platform Information

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/cli.rst

Run this command to get information about the current platform, including Python version and tags. This output can be used with req2flatpak's Python APIs.

```bash
./req2flatpak.py --platform-info
```

```json
{
    "python_version": [
	"3",
	"10",
	"6"
    ],
    "python_tags": [
	"cp310-cp310-manylinux_2_35_x86_64",
	"cp310-cp310-manylinux_2_34_x86_64",
	"cp310-cp310-manylinux_2_33_x86_64",
	"..."
    ]
}
```

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

### Platform Class

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Represents a target platform for Flatpak builds, containing all necessary information for package installation compatibility.

```APIDOC
## Platform Class

### Description
Represents a target platform for Flatpak builds, containing all necessary information for package installation compatibility.

### Class Definition
```python
# Placeholder for the Platform dataclass definition.
# Refer to the source for exact members and types.
class Platform:
    pass
```

### Members
(Refer to the source documentation for a detailed list of members and their descriptions.)
```

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

### Filter and choose the best compatible download using DownloadChooser

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Utilize the DownloadChooser class to filter a list of available downloads and select the best one compatible with a target platform. This is crucial for ensuring correct package installation.

```python
from req2flatpak.download_chooser import DownloadChooser

chooser = DownloadChooser(target_platform='linux-x86_64')
compatible_downloads = chooser.filter_compatible_downloads(release.downloads)
best_download = chooser.choose_best_download(compatible_downloads)
print(best_download.url)
```

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

### FlatpakGenerator

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

The FlatpakGenerator class provides methods for generating a build module that instructs flatpak-builder to install required Python packages.

```APIDOC
## FlatpakGenerator

### Description
Provides methods for generating a build module for `flatpak-builder` to install required Python packages.

### Methods

- `__init__(self)`: Initializes the FlatpakGenerator.
- `add_dependency(self, package_name, version)`: Adds a Python package dependency to the build module.
- `generate_build_module(self)`: Generates the build module content as a JSON object.

### Saving the Build Module

Generated build modules can be saved as .json files using Python's built-in file handling.
```

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

### Generate Flatpak Build Module with FlatpakGenerator

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

FlatpakGenerator converts requirements and chosen downloads into a flatpak-builder build module. The module uses pip3 install with --no-index --find-links for offline builds. Output can be a dictionary, JSON string, or YAML string.

```python
from req2flatpak import (
    DownloadChooser, FlatpakGenerator, PlatformFactory,
    PypiClient, RequirementsParser,
)
import json

platforms = [
    PlatformFactory.from_string("cp310-x86_64"),
    PlatformFactory.from_string("cp310-aarch64"),
]
requirements = RequirementsParser.parse_string(
    "requests == 2.28.1\nscikit-learn == 1.1.3"
)
releases = PypiClient.get_releases(requirements)
downloads = {
    DownloadChooser.wheel_or_sdist(rel, plat)
    for rel in releases
    for plat in platforms
}

# Returns a plain dict
build_module = FlatpakGenerator.build_module(
    requirements, downloads, module_name="python3-myapp-deps"
)
print(build_module["name"])            # python3-myapp-deps
print(build_module["buildsystem"])     # simple
print(build_module["build-commands"]) # ['pip3 install ... requests scikit-learn']
for src in build_module["sources"]:
    print(src["type"], src.get("only-arches"), src["url"][:60])

# Serialise to JSON string
json_str = FlatpakGenerator.build_module_as_str(requirements, downloads)
print(json_str)

# Serialise to YAML string (requires pyyaml: pip install req2flatpak[yaml])
yaml_str = FlatpakGenerator.build_module_as_yaml_str(requirements, downloads)

# Save directly to a .json file
with open("build-module.json", "w") as f:
    json.dump(build_module, f, indent=2)
```

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

### Generate a Flatpak build module using FlatpakGenerator

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Generate a build module for flatpak-builder using the FlatpakGenerator class. This module instructs flatpak-builder on how to install required Python packages into a Flatpak.

```python
from req2flatpak.flatpak_generator import FlatpakGenerator

generator = FlatpakGenerator()
build_module = generator.generate_build_module(package_name='requests', version='2.28.1')
print(build_module)
```

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

### CLI - Basic Usage

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Generate a flatpak-builder build module from a requirements.txt file for specified target platforms. Supports JSON output to stdout or a file, and YAML output to a file.

```APIDOC
## CLI - Basic Usage

Generate a `flatpak-builder` build module from a `requirements.txt` file for two target platforms (Python 3.10, x86_64 and aarch64). Output is JSON on stdout by default.

```bash
# From a requirements.txt file
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 cp310-aarch64

# Inline requirements without a file
./req2flatpak.py --requirements "requests==2.28.1" "numpy==1.23.4" \
    --target-platforms cp310-x86_64

# Write YAML output to a file (requires pyyaml)
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 \
    --yaml --outfile build-module.yaml

# Write JSON output directly to a file
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 cp310-aarch64 \
    --outfile build-module.json
```
```

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

### Query Current Platform Information (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Prints information about the current runtime environment, including Python version and compatibility tags. Useful for determining platform strings.

```bash
# Print the current platform's Python version and compatibility tags
./req2flatpak.py --platform-info
```

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

### Generate Flatpak Build Module with req2flatpak

Source: https://github.com/johannesjh/req2flatpak/blob/main/README.rst

Use this command to generate a flatpak-builder build module from a requirements.txt file. Specify target platforms using the format <pythonversion>-<architecture>.

```bash
./req2flatpak.py --requirements-file requirements.txt --target-platforms 310-x86_64 310-aarch64
```

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

### Fetch Release Metadata from PyPI with PypiClient

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Use PypiClient to query PyPI for release information. Supports in-memory caching by default, or persistent caching using shelve. Can query multiple requirements at once or a single requirement.

```python
from req2flatpak import PypiClient, RequirementsParser

requirements = RequirementsParser.parse_string("requests == 2.28.1")

# Basic usage — in-memory cache (default, dict-based)
releases = PypiClient.get_releases(requirements)
print(releases[0].package)   # requests
print(len(releases[0].downloads))  # number of available artifacts

# Persistent on-disk cache using shelve
import shelve
with shelve.open("pypi_cache.tmp") as cache:
    PypiClient.cache = cache
    releases = PypiClient.get_releases(requirements)

# Query a single requirement
from req2flatpak import Requirement
req = Requirement(package="requests", version="2.28.1")
release = PypiClient.get_release(req)
for dl in release.downloads:
    print(dl.filename, dl.sha256)
```

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

### Generate Flatpak Build Module

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

This snippet demonstrates the core functionality of req2flatpak: querying PyPI, selecting downloads, and generating a build module JSON file.

```python
with shelve.open("pypi_cache") as cache:
    PypiClient.cache = cache
    releases = PypiClient.get_releases(requirements)

downloads = {
    DownloadChooser.wheel_or_sdist(release, platform)
    for release in releases
    for platform in platforms
}
downloads.discard(None)

build_module = FlatpakGenerator.build_module(
    requirements, downloads, module_name="python3-myapp-deps"
)
with open("python3-myapp-deps.json", "w") as f:
    json.dump(build_module, f, indent=4)

print(f"Generated {len(build_module['sources'])} source entries.")
```

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

### Generate Flatpak Build Module from requirements.txt (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Generates a flatpak-builder build module from a requirements.txt file for specified target platforms. Output is JSON to stdout by default.

```bash
# From a requirements.txt file
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 cp310-aarch64
```

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

### Parse Requirements using RequirementsParser

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Shows how to parse package requirements from a requirements file using the RequirementsParser. Ensure all package versions are fully specified (pinned).

```python
from pathlib import Path

from req2flatpak.platform_factory import PlatformFactory
from req2flatpak.requirements_parser import RequirementsParser

def example_usage1_start():
    # Define target platforms
    platforms = PlatformFactory.get_platforms("linux", "x86_64")

    # Parse requirements from a file, specifying target platforms
    requirements = RequirementsParser.parse_requirements(
        Path("requirements.txt"), platforms=platforms
    )
    return requirements

example_usage1_end = None
```

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

### Customize Flatpak Generator and PyPI Client

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

This snippet shows how to subclass `PypiClient` to query a private index and modify `FlatpakGenerator.pip_install_template` to include custom pip flags like `--ignore-installed`.

```python
from req2flatpak import (
    DownloadChooser, FlatpakGenerator,
    PlatformFactory,
    PypiClient, RequirementsParser,
)

platforms     = [PlatformFactory.from_string("cp310-x86_64")]
requirements  = RequirementsParser.parse_file("requirements.txt")

# Exclude packages that are pre-installed in the Flatpak SDK
requirements = [r for r in requirements if r.package != "certifi"]

# Subclass PypiClient to query a private or mirror index
class MyClient(PypiClient):
    """Queries an internal package mirror."""
    # Override _query_from_pypi to redirect to another index if needed.

releases  = MyClient.get_releases(requirements)
downloads = {
    DownloadChooser.wheel_or_sdist(rel, plat)
    for rel in releases for plat in platforms
}

# Force --ignore-installed so pip always reinstalls packages
FlatpakGenerator.pip_install_template = (
    FlatpakGenerator.pip_install_template.replace(
        "pip3 install", "pip3 install --ignore-installed"
    )
)

build_module = FlatpakGenerator.build_module(requirements, downloads)

# Post-process: rename the module to something meaningful
build_module["name"] = "python3-myapp-runtime"

json_str  = FlatpakGenerator.build_module_as_str(requirements, downloads)
yaml_str  = FlatpakGenerator.build_module_as_yaml_str(requirements, downloads)
print(yaml_str)
```

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

### Generate YAML Output to File (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Generates a flatpak-builder build module in YAML format and writes it to a specified file. Requires the 'pyyaml' package.

```bash
# Write YAML output to a file (requires pyyaml)
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 \
    --yaml --outfile build-module.yaml
```

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

### Generate JSON Output to File (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Generates a flatpak-builder build module in JSON format and writes it directly to a specified file.

```bash
# Write JSON output directly to a file
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 cp310-aarch64 \
    --outfile build-module.json
```

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

### Create Platform Objects from String (Python API)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Creates Platform dataclass instances from compact platform strings (e.g., 'cp310-x86_64'). These objects encode Python version and PEP 425 compatibility tags.

```python
from req2flatpak import PlatformFactory

# From a compact platform string  (format: "<py_version>-<arch>")
platform_x86 = PlatformFactory.from_string("cp310-x86_64")
platform_arm  = PlatformFactory.from_string("cp310-aarch64")

# From explicit minor version and architecture
platform_py39 = PlatformFactory.from_python_version_and_arch(
    minor_version=9, arch="x86_64"
)

# Reflect the currently running interpreter
current_platform = PlatformFactory.from_current_interpreter()

print(platform_x86.python_version)   # ['3', '10']
print(platform_x86.python_tags[:3])  # ['cp310-cp310-manylinux_2_35_x86_64', ...]
```

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

### Invoke req2flatpak CLI

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/cli.rst

Use this command to generate a Flatpak build module by specifying requirements and target platforms.

```bash
./req2flatpak.py --requirements-file requirements.txt --target-platforms cp310-x86_64 cp310-aarch64
```

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

### Select Compatible Artifacts with DownloadChooser

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

DownloadChooser filters release downloads based on platform compatibility tags. It prioritizes binary wheels over source distributions by default, but this can be reversed. It can also iterate through all compatible downloads or collect one download per (release, platform) pair.

```python
from req2flatpak import (
    DownloadChooser, PlatformFactory, PypiClient, RequirementsParser,
)

platform = PlatformFactory.from_string("cp310-x86_64")
requirements = RequirementsParser.parse_string("scikit-learn == 1.1.3")
releases = PypiClient.get_releases(requirements)
release = releases[0]

# Best wheel for the platform (None if no compatible wheel exists)
wheel = DownloadChooser.wheel(release, platform)
print(wheel.filename)   # scikit_learn-1.1.3-cp310-cp310-manylinux_2_17_x86_64...whl
print(wheel.arch)       # x86_64

# Source distribution (arch-independent fallback)
sdist = DownloadChooser.sdist(release)
print(sdist.filename)   # scikit_learn-1.1.3.tar.gz  (if published)

# Wheel preferred, sdist as fallback
best = DownloadChooser.wheel_or_sdist(release, platform)

# Iterate all compatible downloads in preference order
for dl in DownloadChooser.downloads(release, platform, wheels_only=True):
    print(dl.filename)

# Multi-platform: collect one download per (release, platform) pair
platforms = [
    PlatformFactory.from_string("cp310-x86_64"),
    PlatformFactory.from_string("cp310-aarch64"),
]
downloads = {
    DownloadChooser.wheel_or_sdist(rel, plat)
    for rel in releases
    for plat in platforms
}
```

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

### Enable Persistent PyPI Cache (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Enables a persistent on-disk cache for PyPI metadata, reducing redundant network requests across multiple invocations. Creates or reuses a 'pypi_cache' shelve database.

```bash
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 \
    --cache
# Creates/reuses a shelve database named "pypi_cache" in the current directory.
```

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

### Generate Flatpak Build Module with Inline Requirements (CLI)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Generates a flatpak-builder build module using inline package requirements for a specified target platform.

```bash
# Inline requirements without a file
./req2flatpak.py --requirements "requests==2.28.1" "numpy==1.23.4" \
    --target-platforms cp310-x86_64
```

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

### Configure PypiClient with a persistent cache

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Configure PypiClient to use a persistent cache, such as a shelve.Shelf, to reduce traffic when querying PyPI. This improves performance by storing responses locally.

```python
import shelve

cache_filename = 'pypi_cache.tmp'
with shelve.open(cache_filename) as shelf:
    PypiClient.set_cache(shelf)
    client = PypiClient()
    release = client.get_release(package_name='requests')
    print(release.name, release.version)
```

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

### PypiClient

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

The PypiClient class allows querying the PyPI python package index for available releases. It supports caching responses to reduce traffic.

```APIDOC
## PypiClient

### Description
Allows querying the PyPI python package index about available releases.

### Methods

- `__init__(self, cache=None)`: Initializes the PypiClient with an optional cache.
- `get_release_data(self, package_name)`: Retrieves release data for a given package name.

### Caching

PypiClient caches responses to reduce traffic. A simple `dict` is used as an in-memory cache by default. Persistent caches like `shelve.Shelf` can be configured for improved caching.
```

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

### CLI - Persistent PyPI Cache

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Enable a persistent on-disk cache for PyPI metadata to avoid re-fetching across multiple invocations.

```APIDOC
## CLI - Persistent PyPI Cache

Enable a persistent on-disk cache to avoid re-fetching PyPI metadata across multiple invocations.

```bash
./req2flatpak.py --requirements-file requirements.txt \
    --target-platforms cp310-x86_64 \
    --cache
# Creates/reuses a shelve database named "pypi_cache" in the current directory.
```
```

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

### PlatformFactory - Create Target Platform Objects

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Create `Platform` dataclass instances that encode a Python version and compatibility tags for a given target.

```APIDOC
## `PlatformFactory` — Create Target Platform Objects

`PlatformFactory` creates `Platform` dataclass instances that encode a Python version and the full list of PEP 425 compatibility tags for a given CPython/Linux target.

```python
from req2flatpak import PlatformFactory

# From a compact platform string  (format: "<py_version>-<arch>")
platform_x86 = PlatformFactory.from_string("cp310-x86_64")
platform_arm  = PlatformFactory.from_string("cp310-aarch64")

# From explicit minor version and architecture
platform_py39 = PlatformFactory.from_python_version_and_arch(
    minor_version=9, arch="x86_64"
)

# Reflect the currently running interpreter
current_platform = PlatformFactory.from_current_interpreter()

print(platform_x86.python_version)   # ['3', '10']
print(platform_x86.python_tags[:3])  # ['cp310-cp310-manylinux_2_35_x86_64', ...]
```
```

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

### PlatformFactory Class

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Provides methods for creating platform objects, simplifying the process of defining target environments for Flatpak builds.

```APIDOC
## PlatformFactory Class

### Description
Provides methods for creating platform objects, simplifying the process of defining target environments for Flatpak builds.

### Example Usage
```python
# This code is a placeholder and represents the structure of the example usage.
# Actual implementation details are found in the source file.

# from req2flatpak import PlatformFactory

# platform_factory = PlatformFactory()
# platform = platform_factory.create_platform(...)
```

### Methods
(Refer to the source documentation for a detailed list of methods and their descriptions.)
```

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

### Parse Requirements from File (Python API)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Parses requirements from a specified file path into a list of Requirement dataclass instances. Requires package versions to be pinned with '=='.

```python
from req2flatpak import RequirementsParser

# Parse from a file path
requirements = RequirementsParser.parse_file("requirements.txt")
```

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

### DownloadChooser

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

The DownloadChooser class provides methods for filtering compatible downloads and choosing the 'best' download for a given target platform.

```APIDOC
## DownloadChooser

### Description
Provides methods for filtering compatible downloads and choosing the 'best' download for a given target platform.

### Methods

- `__init__(self, target_platform_tags)`: Initializes the DownloadChooser with target platform tags.
- `filter_compatible_downloads(self, downloads)`: Filters a list of downloads to include only those compatible with the target platform.
- `choose_best_download(self, compatible_downloads)`: Chooses the best download from a list of compatible downloads based on tag ranking.
```

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

### RequirementsParser - Parse Pinned Requirements

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Parse `requirements.txt` content from a file path, file object, or raw string into a list of `Requirement` objects. Versions must be pinned with `==`.

```APIDOC
## `RequirementsParser` — Parse Pinned Requirements

`RequirementsParser` reads `requirements.txt` content (file path, file object, or raw string) and returns a list of `Requirement(package, version)` dataclass instances. All versions **must** be pinned with `==`.

```python
from req2flatpak import RequirementsParser

# Parse from a file path
requirements = RequirementsParser.parse_file("requirements.txt")

# Parse from an open file object
with open("requirements.txt") as f:
    requirements = RequirementsParser.parse_file(f)

# Parse from a string (e.g., inline or dynamically generated)
requirements = RequirementsParser.parse_string("""
    # popular data-science stack
    numpy == 1.23.4
    pandas == 1.5.1
    matplotlib == 3.6.1
    scikit-learn == 1.1.3
"""
)

for req in requirements:
    print(req.package, req.version)
# numpy 1.23.4
# pandas 1.5.1
# matplotlib 3.6.1
# scikit-learn 1.1.3
```
```

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

### Parse Requirements from File Object (Python API)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Parses requirements from an open file object into a list of Requirement dataclass instances. Requires package versions to be pinned with '=='.

```python
# Parse from an open file object
with open("requirements.txt") as f:
    requirements = RequirementsParser.parse_file(f)
```

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

### Export Build Module to JSON

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Serializes a Python dictionary representing a build module and saves it to a JSON file. Assumes the build module data is stored in the 'build_module' variable.

```python
# example showing how to export a build module to json
import json

# write the json data to file:
with open("build-module.json", "w") as outfile:
 json.dump(build_module, outfile, indent=2)
```

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

### Parse Requirements from String (Python API)

Source: https://context7.com/johannesjh/req2flatpak/llms.txt

Parses requirements directly from a string into a list of Requirement dataclass instances. Useful for inline or dynamically generated requirements. Versions must be pinned with '=='.

```python
# Parse from a string (e.g., inline or dynamically generated)
requirements = RequirementsParser.parse_string("""
    # popular data-science stack
    numpy == 1.23.4
    pandas == 1.5.1
    matplotlib == 3.6.1
    scikit-learn == 1.1.3
""")

for req in requirements:
    print(req.package, req.version)
# numpy 1.23.4
# pandas 1.5.1
# matplotlib 3.6.1
# scikit-learn 1.1.3
```

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

### RequirementsParser Class

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Parses package requirements, typically from a requirements file, ensuring that all package versions are fully specified.

```APIDOC
## RequirementsParser Class

### Description
Parses package requirements, typically from a requirements file, ensuring that all package versions are fully specified. It expects versions to be pinned using the `==` operator.

### Example Usage
```python
# This code is a placeholder and represents the structure of the example usage.
# Actual implementation details are found in the source file.

# from req2flatpak import RequirementsParser

# requirements_parser = RequirementsParser()
# requirements = requirements_parser.parse_requirements_file('requirements.txt')
```

### Methods
(Refer to the source documentation for a detailed list of methods and their descriptions.)

### Important Note
This parser expects fully specified package versions (e.g., `package==1.2.3`) and does not handle version ranges or abstract specifications.
```

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

### Release Class

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Represents an available release of a Python package from a package index, including version and compatibility information.

```APIDOC
## Release Class

### Description
Represents an available release of a Python package from a package index, including version and compatibility information.

### Class Definition
```python
# Placeholder for the Release dataclass definition.
# Refer to the source for exact members and types.
class Release:
    pass
```

### Members
(Refer to the source documentation for a detailed list of members and their descriptions.)
```

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

### Requirement Class

Source: https://github.com/johannesjh/req2flatpak/blob/main/docs/source/api.rst

Represents a Python package requirement, including its name and exact version, used for specifying dependencies.

```APIDOC
## Requirement Class

### Description
Represents a Python package requirement, including its name and exact version, used for specifying dependencies.

### Class Definition
```python
# Placeholder for the Requirement dataclass definition.
# Refer to the source for exact members and types.
class Requirement:
    pass
```

### Members
(Refer to the source documentation for a detailed list of members and their descriptions.)
```

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