Metadata-Version: 2.4
Name: borea_python
Version: 1.0.4
Summary: Generate extensible python HTTP client from OpenAPI spec
Project-URL: Homepage, https://github.com/Borea-dev/python-client-generator
Project-URL: Issues, https://github.com/Borea-dev/python-client-generator/issues
Author-email: David Bauch <pypi@borea.dev>
License: MIT
License-File: LICENSE
Keywords: Borea,Client,Generator,OpenAPI
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.9
Requires-Dist: click<9.0.0,>=8.0.0
Requires-Dist: datamodel-code-generator<1.0.0,>=0.28.0
Requires-Dist: httpx<0.28.0,>=0.20.0
Requires-Dist: jinja2<4.0.0,>=3.0.0
Requires-Dist: pydantic<2.7.0,>=2.1.1
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: ruff<0.3,>=0.2
Description-Content-Type: text/markdown

# Borea Python HTTP Client SDK Generator

Please learn more about Borea and our mission at [borea.dev](https://borea.dev) and our organization on GitHub [Borea-dev](https://github.com/Borea-dev).

This repository contains a Python HTTP client SDK generator. It generates a Python client from an OpenAPI specification.

## Table of Contents

-   [Getting Started](#getting-started)
-   [Installation](#installation)
-   [Usage](#usage)
-   [Running Tests](#running-tests)
-   [Project Structure](#project-structure)
-   [Manual Install](#manual-install)
-   [License](#license)

## Getting Started <a id="getting-started"></a>

### Prerequisites

-   Python 3.8 or higher
-   pip (Python package installer)

### Installation <a id="installation"></a>

Available as [borea-python](https://pypi.org/project/borea-python/) on PyPI.

```bash
pip install borea-python
```

For info on cloning and installing manually read [**Manual Install**](#manual-install).

## Usage <a id="usage"></a>

### Running the Python SDK Generator

1. Ensure you have a valid OpenAPI specification file (`openapi.json`) in the root directory. Command line arguments and configuration are detailed below.

2. Run the SDK generator after configuration:

```bash
python borea-python [OPTIONS]
```

The generator will create the Python HTTP client SDK based on the OpenAPI specification.

### Configuration

**IMPORTANT!**

Command line arguments take precedence over settings in `borea.config.json`.

The project uses `borea.config.json` for configuration settings. Example config with the `defaults`:

```json
{
	"input": {
		"openapi": ["openapi.json"]
	},
	"output": {
		"clientSDK": "Formatted OpenAPI Title by default",
		"models": "models",
		"tests": false,
		"xCodeSamples": false
	},
	"ignores": []
}
```

-   `input`: map input options to array of values, ordered by precedence. For example, first value is a file path and the second is a URL. If the file cannot be found, then the URL will be used.
-   `output`: map output options to values
-   `ignore`: array of `glob` patterns to ignore. No file or directory matching the pattern will be created.

### Command line help

Show this help message with `--help`:

```bash
Usage: python borea-python
           [OPTIONS]

  Generate a Python SDK from an OpenAPI specification.

  The OpenAPI specification can be provided as a local file path or a URL. For
  URLs, both JSON and YAML formats are supported.

Options:
  -i, --openapi-input TEXT   Path to OpenAPI specification file or URL
  -o, --sdk-output TEXT      Output directory for the generated SDK
  -m, --models-output TEXT   Output directory for the generated models
  -t, --tests TEXT           Generate tests
  -x, --x-code-samples TEXT  Generate x-code-samples
  -c, --config TEXT          Path to borea.config.json
  --help                     Show this message and exit.
```

## Running Tests <a id="running-tests"></a>

**To be implemented...**

To run the test suite:

```bash
python -m pytest
```

## Project Structure <a id="project-structure"></a>

-   `src/` - Contains the source code for the SDK generator
-   `openapi.json` - OpenAPI specification file or wherever you decide to put it
-   `borea.config.json` - Configuration file for the generator
-   `.venv/` - Python virtual environment (created during setup)

## Manual Install <a id="manual-install"></a>

### Clone repo

```bash
git clone https://github.com/Borea-dev/python-client-generator.git
```

Run the automated setup script:

_`source` is required to activate the virtual environment_

```bash
source ./setup.sh
```

This script will:

1. Create a Python virtual environment (`.venv`)
2. Activate the virtual environment
3. Install all required dependencies

Available options:

```bash
setup.sh [OPTIONS]

Options:
  -r, --recreate    Recreate virtual environment (deletes existing .venv)
  -i, --reinstall   Reinstall all requirements
  -h, --help        Show this help message
```

## License <a id="license"></a>

This project is licensed under the terms specified in the LICENSE file.
