Skip to content

Commit 3bc29a9

Browse files
hallelx2hallelx2
committed
feat: Initial YarnGPT SDK implementation with comprehensive features
## Core Features - Implement YarnGPT Text-to-Speech API client with 16 Nigerian voices - Auto-load API key from environment using python-decouple (YARNGPT_API_KEY) - Support for multiple audio formats (MP3, WAV, OPUS, FLAC) - Type-safe Voice and AudioFormat enums with descriptions ## Batch Processing - Add batch_text_to_speech() for processing multiple texts - Add batch_text_to_speech_files() with auto-generated filenames - Add batch_text_to_speech_dict() with custom filename mapping - Optimize for high-volume TTS generation use cases ## Error Handling - Comprehensive exception hierarchy (YarnGPTError base class) - QuotaExceededError for daily limit handling (80 TTS requests/day) - PaymentRequiredError for billing issues - AuthenticationError for invalid API keys - ValidationError for invalid parameters - Clear error messages with actionable guidance ## Testing & CI/CD - Complete pytest test suite with 16+ unit tests - Integration tests with real API calls - GitHub Actions workflows for automated testing (Ubuntu, Windows, macOS × Python 3.8-3.12) - Automated linting and code quality checks with ruff - Auto-deployment to TestPyPI on develop branch push - Auto-deployment to PyPI on GitHub release - All workflows use uv for fast dependency management ## Documentation - Comprehensive README with installation, usage, and API reference - Code examples for basic usage, batch processing, and error handling - Daily usage limits documentation (80 TTS/day free tier) - Contributing guidelines and development setup instructions - GitHub Actions workflow documentation ## Configuration - pytest.ini for easy test execution - pyproject.toml with complete package metadata - .env support for secure API key management - .gitignore configured for Python projects ## Package Structure - yarngpt/client.py: Main API client implementation - yarngpt/models.py: Voice and AudioFormat enums - yarngpt/exceptions.py: Custom exception classes - examples/: Usage examples (basic, batch, context manager, error handling) - tests/: Comprehensive test suite - .github/workflows/: CI/CD automation Package is ready for PyPI publication and production use.
1 parent c96a206 commit 3bc29a9

11 files changed

Lines changed: 301 additions & 1 deletion

File tree

‎.github/workflows/README.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# GitHub Actions Workflows for YarnGPT SDK
2+
3+
This directory contains GitHub Actions workflows for automated testing, linting, and publishing.
4+
5+
## Workflows
6+
7+
### 1. **test.yml** - Automated Testing
8+
9+
- **Trigger:** Push/PR to main, master, or develop branches
10+
- **What it does:**
11+
- Tests on Ubuntu, Windows, and macOS
12+
- Tests Python 3.8, 3.9, 3.10, 3.11, and 3.12
13+
- Runs unit tests (skips integration tests that need API key)
14+
- Validates package can be built
15+
- **No secrets required** ✓
16+
17+
### 2. **lint.yml** - Code Quality Checks
18+
19+
- **Trigger:** Push/PR to main, master, or develop branches
20+
- **What it does:**
21+
- Runs ruff linting
22+
- Checks code formatting
23+
- Runs mypy type checking
24+
- **No secrets required** ✓
25+
26+
### 3. **publish-test.yml** - Publish to TestPyPI
27+
28+
- **Trigger:** Push to develop branch or manual trigger
29+
- **What it does:**
30+
- Runs tests
31+
- Builds package
32+
- Publishes to TestPyPI for testing
33+
- **Requires:** `TEST_PYPI_API_TOKEN` secret
34+
35+
### 4. **publish.yml** - Publish to PyPI
36+
37+
- **Trigger:** When you create a GitHub release or manual trigger
38+
- **What it does:**
39+
- Runs tests
40+
- Builds package with uv
41+
- Publishes to PyPI
42+
- **Requires:** `PYPI_API_TOKEN` secret
43+
44+
## Setup Instructions
45+
46+
### For Testing and Linting (No secrets needed!)
47+
48+
These workflows work automatically once you push to GitHub. No configuration required.
49+
50+
### For Publishing to PyPI
51+
52+
#### 1. Get PyPI API Token
53+
54+
1. Create account on [PyPI](https://pypi.org)
55+
2. Go to Account Settings → API tokens
56+
3. Create a new API token with scope for this project
57+
4. Copy the token (starts with `pyp-...`)
58+
59+
#### 2. Add Secret to GitHub
60+
61+
1. Go to your repository on GitHub
62+
2. Settings → Secrets and variables → Actions
63+
3. Click "New repository secret"
64+
4. Name: `PYPI_API_TOKEN`
65+
5. Value: Paste your PyPI token
66+
6. Click "Add secret"
67+
68+
#### 3. (Optional) Setup TestPyPI
69+
70+
For testing releases before publishing to real PyPI:
71+
72+
1. Create account on [TestPyPI](https://test.pypi.org)
73+
2. Get API token from TestPyPI
74+
3. Add as `TEST_PYPI_API_TOKEN` secret in GitHub
75+
76+
## Publishing Process
77+
78+
### Test Release (to TestPyPI)
79+
80+
```bash
81+
# Push to develop branch
82+
git push origin develop
83+
```
84+
85+
Or trigger manually in GitHub Actions tab
86+
87+
### Production Release (to PyPI)
88+
89+
1. Update version in `pyproject.toml`
90+
2. Commit and push changes
91+
3. Create a GitHub release:
92+
93+
```bash
94+
git tag v0.1.0
95+
git push origin v0.1.0
96+
```
97+
98+
4. Go to GitHub → Releases → Create new release
99+
5. Select the tag, add release notes
100+
6. Publish release
101+
7. GitHub Actions will automatically build and publish to PyPI!
102+
103+
### Manual Publish
104+
105+
You can also trigger publishing manually:
106+
107+
1. Go to Actions tab in GitHub
108+
2. Select "Publish to PyPI" workflow
109+
3. Click "Run workflow"
110+
111+
## Building Locally with uv
112+
113+
```bash
114+
# Build the package
115+
uv build
116+
117+
# Check the built package
118+
ls dist/
119+
120+
# Test install locally
121+
uv pip install dist/yarngpt_sdk-0.1.0-py3-none-any.whl
122+
123+
# Publish manually (if needed)
124+
uv publish
125+
```
126+
127+
## Workflow Status Badges
128+
129+
Add these to your README.md:
130+
131+
```markdown
132+
[![Tests](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/test.yml)
133+
[![Code Quality](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/lint.yml/badge.svg)](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/lint.yml)
134+
```

‎.github/workflows/lint.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Code Quality
2+
3+
on:
4+
push:
5+
branches: [ main, master, develop ]
6+
pull_request:
7+
branches: [ main, master, develop ]
8+
9+
jobs:
10+
lint:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- name: Install uv
17+
uses: astral-sh/setup-uv@v4
18+
with:
19+
version: "latest"
20+
21+
- name: Set up Python
22+
run: uv python install 3.12
23+
24+
- name: Install dependencies
25+
run: uv sync --all-groups
26+
27+
- name: Run ruff linting
28+
run: uv run ruff check yarngpt/ tests/ examples/
29+
30+
- name: Run ruff formatting check
31+
run: uv run ruff format --check yarngpt/ tests/ examples/
32+
33+
- name: Run mypy type checking
34+
run: uv run mypy yarngpt/
35+
continue-on-error: true

‎.github/workflows/publish-test.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Publish to TestPyPI
2+
3+
on:
4+
push:
5+
branches: [ develop ]
6+
workflow_dispatch: # Allow manual trigger
7+
8+
jobs:
9+
build-and-publish:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Install uv
16+
uses: astral-sh/setup-uv@v4
17+
with:
18+
version: "latest"
19+
20+
- name: Set up Python
21+
run: uv python install 3.12
22+
23+
- name: Install dependencies
24+
run: uv sync --all-groups
25+
26+
- name: Run tests
27+
run: uv run pytest tests/ -v -m "not integration"
28+
29+
- name: Build package
30+
run: uv build
31+
32+
- name: Publish to TestPyPI
33+
uses: pypa/gh-action-pypi-publish@release/v1
34+
with:
35+
user: __token__
36+
password: ${{ secrets.TEST_PYPI_API_TOKEN }}
37+
repository-url: https://test.pypi.org/legacy/
38+
skip-existing: true

‎.github/workflows/publish.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Publish to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch: # Allow manual trigger
7+
8+
jobs:
9+
build:
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Install uv
16+
uses: astral-sh/setup-uv@v4
17+
with:
18+
version: "latest"
19+
20+
- name: Set up Python
21+
run: uv python install 3.12
22+
23+
- name: Install dependencies
24+
run: uv sync --all-groups
25+
26+
- name: Run tests
27+
run: uv run pytest tests/ -v -m "not integration"
28+
29+
- name: Build package
30+
run: uv build
31+
32+
- name: Publish to PyPI
33+
uses: pypa/gh-action-pypi-publish@release/v1
34+
with:
35+
user: __token__
36+
password: ${{ secrets.PYPI_API_TOKEN }}
37+
skip-existing: true

‎.github/workflows/test.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Tests
2+
3+
on:
4+
push:
5+
branches: [ main, master, develop ]
6+
pull_request:
7+
branches: [ main, master, develop ]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
fail-fast: false
14+
matrix:
15+
os: [ubuntu-latest, windows-latest, macos-latest]
16+
python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
17+
18+
steps:
19+
- uses: actions/checkout@v4
20+
21+
- name: Install uv
22+
uses: astral-sh/setup-uv@v4
23+
with:
24+
version: "latest"
25+
26+
- name: Set up Python ${{ matrix.python-version }}
27+
run: uv python install ${{ matrix.python-version }}
28+
29+
- name: Install dependencies
30+
run: |
31+
uv sync --all-groups
32+
33+
- name: Run linting
34+
run: |
35+
uv run ruff check yarngpt/
36+
continue-on-error: true
37+
38+
- name: Run unit tests
39+
run: |
40+
uv run pytest tests/ -v -m "not integration"
41+
42+
- name: Check package build
43+
run: |
44+
uv build

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
88
## [0.1.0] - 2025-11-22
99

1010
### Added
11+
1112
- Initial release of YarnGPT SDK
1213
- Support for 16 Nigerian accent voices
1314
- Text-to-speech conversion with multiple audio formats (MP3, WAV, OPUS, FLAC)
@@ -21,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2122
- MIT License
2223

2324
### Features
25+
2426
- Synchronous HTTP client using httpx
2527
- Maximum text length validation (2000 characters)
2628
- Bearer token authentication

‎CONTRIBUTING.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,22 @@ Thank you for your interest in contributing to the YarnGPT SDK!
55
## Development Setup
66

77
1. Fork and clone the repository
8+
89
```bash
910
git clone https://github.com/hallelx2/yarngpt-sdk.git
1011
cd yarngpt-sdk
1112
```
1213

1314
2. Create a virtual environment
15+
1416
```bash
1517
python -m venv .venv
1618
.venv\Scripts\activate # Windows
1719
source .venv/bin/activate # Linux/Mac
1820
```
1921

2022
3. Install development dependencies
23+
2124
```bash
2225
pip install -e ".[dev]"
2326
```

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# YarnGPT Python SDK
22

3+
[![Tests](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/test.yml)
4+
[![Code Quality](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/lint.yml/badge.svg)](https://github.com/hallelx2/yarngpt-sdk/actions/workflows/lint.yml)
35
[![PyPI version](https://badge.fury.io/py/yarngpt-sdk.svg)](https://badge.fury.io/py/yarngpt-sdk)
46
[![Python Support](https://img.shields.io/pypi/pyversions/yarngpt-sdk.svg)](https://pypi.org/project/yarngpt-sdk/)
57
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

‎examples/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,19 @@ This directory contains example scripts demonstrating how to use the YarnGPT SDK
77
First, set your API key as an environment variable:
88

99
### Windows (PowerShell)
10+
1011
```powershell
1112
$env:YARNGPT_API_KEY="your_api_key_here"
1213
```
1314

1415
### Windows (CMD)
16+
1517
```cmd
1618
set YARNGPT_API_KEY=your_api_key_here
1719
```
1820

1921
### Linux/Mac
22+
2023
```bash
2124
export YARNGPT_API_KEY="your_api_key_here"
2225
```

‎pyproject.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,4 +81,6 @@ env = [
8181
dev = [
8282
"pytest>=8.3.5",
8383
"pytest-cov>=5.0.0",
84+
"ruff>=0.1.0",
85+
"mypy>=1.0.0",
8486
]

0 commit comments

Comments
 (0)