Skip to content

Commit 583053a

Browse files
jaseemjaskpjaseemjaskp
committed
Initial commit
0 parents  commit 583053a

19 files changed

+4662
-0
lines changed

‎.env.example

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# API Hub Configuration
2+
# Copy this file to .env and fill in your actual values
3+
4+
# Your API Hub API Key
5+
API_KEY=your_api_key_here
6+
7+
# Base URL for the API Hub service
8+
BASE_URL=https://api-hub.us-central.unstract.com/api/v1
9+
10+
# Optional: Log level (DEBUG, INFO, WARNING, ERROR)
11+
LOG_LEVEL=INFO
12+
13+
# Optional: Default timeout for requests (in seconds)
14+
REQUEST_TIMEOUT=30
15+
16+
# Optional: Maximum wait time for extraction completion (in seconds)
17+
MAX_WAIT_TIMEOUT=300
18+
19+
# Optional: Polling interval for status checks (in seconds)
20+
POLL_INTERVAL=5

‎.github/RELEASE.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# Release Workflow Documentation
2+
3+
This document explains how to use the automated release workflow for the `apihub-python-client` package.
4+
5+
## Overview
6+
7+
The project has two GitHub Actions workflows for publishing:
8+
9+
1. **`publish.yml`** - Automated release creation and publishing (recommended)
10+
2. **`publish-on-release.yml`** - Publish when a release is manually created
11+
12+
## Automated Release Workflow (Recommended)
13+
14+
The main workflow (`publish.yml`) automates the entire release process:
15+
16+
### Features
17+
18+
- ✅ Automatic version bumping
19+
- ✅ Git tag creation
20+
- ✅ GitHub release creation with auto-generated notes
21+
- ✅ Code quality checks (linting, type checking)
22+
- ✅ Test execution
23+
- ✅ PyPI publishing
24+
- ✅ Support for pre-releases
25+
- ✅ Custom release notes
26+
27+
### How to Use
28+
29+
1. **Navigate to Actions tab** in the GitHub repository
30+
2. **Select "Release Tag and Publish Package"** workflow
31+
3. **Click "Run workflow"**
32+
4. **Configure the release:**
33+
- **Version bump type**: Choose `patch`, `minor`, or `major`
34+
- **Pre-release**: Check if this is a pre-release version
35+
- **Release notes**: Optional custom notes (auto-generated notes will also be included)
36+
5. **Click "Run workflow"** button
37+
38+
### Version Bumping
39+
40+
The workflow follows semantic versioning:
41+
42+
- **Patch** (e.g., 1.2.3 → 1.2.4): Bug fixes, small improvements
43+
- **Minor** (e.g., 1.2.3 → 1.3.0): New features, backwards compatible
44+
- **Major** (e.g., 1.2.3 → 2.0.0): Breaking changes
45+
46+
### What Happens During Release
47+
48+
1. **Version Update**: Updates `__version__` in `src/apihub_client/__init__.py`
49+
2. **Git Operations**:
50+
- Commits version change to main branch
51+
- Creates and pushes git tag (e.g., `v1.2.3`)
52+
3. **Quality Checks**:
53+
- Runs linting with `ruff`
54+
- Executes full test suite with `tox`
55+
4. **GitHub Release**: Creates release with auto-generated changelog
56+
5. **PyPI Publishing**: Builds and publishes package to PyPI
57+
58+
### Requirements
59+
60+
The workflow requires these repository secrets:
61+
62+
- `PUSH_TO_MAIN_APP_ID`: GitHub App ID for pushing to main
63+
- `PUSH_TO_MAIN_APP_PRIVATE_KEY`: GitHub App private key
64+
65+
And these repository variables:
66+
67+
- `PUSH_TO_MAIN_APP_ID`: GitHub App ID (can be same as secret)
68+
69+
**PyPI Setup**: This workflow uses PyPI Trusted Publishers with `uv publish` for secure publishing. You need to:
70+
1. Configure the GitHub repository as a trusted publisher on PyPI
71+
2. Set up the trusted publisher for the `apihub-python-client` package
72+
3. No API tokens required - `uv publish` automatically handles OIDC authentication
73+
74+
## Manual Release Workflow
75+
76+
The `publish-on-release.yml` workflow runs when you manually create a release through GitHub's interface.
77+
78+
### When to Use
79+
80+
- When you need more control over the release process
81+
- For hotfixes or special releases
82+
- When the automated workflow is not available
83+
84+
### How to Use
85+
86+
1. **Create a release manually** through GitHub's release interface
87+
2. **Use semantic version tag** (e.g., `v1.2.3`)
88+
3. **Publish the release** - this triggers the workflow automatically
89+
90+
## Best Practices
91+
92+
### Before Releasing
93+
94+
1. **Ensure all tests pass** on the main branch
95+
2. **Review recent changes** and prepare release notes if needed
96+
3. **Check dependencies** are up to date
97+
4. **Verify documentation** is current
98+
99+
### Version Strategy
100+
101+
- Use **patch** for bug fixes and small improvements
102+
- Use **minor** for new features that don't break existing code
103+
- Use **major** for breaking changes
104+
- Use **pre-release** for beta/alpha versions
105+
106+
### Release Notes
107+
108+
- Let GitHub auto-generate notes for most releases
109+
- Add custom notes for major releases or important changes
110+
- Include migration guides for breaking changes
111+
112+
## Troubleshooting
113+
114+
### Common Issues
115+
116+
**Workflow fails at version bump:**
117+
- Check that the current version in `__init__.py` follows semantic versioning
118+
- Ensure the main branch is up to date
119+
120+
**Tests fail during release:**
121+
- Check the latest test results on main branch
122+
- Fix failing tests before attempting release
123+
124+
**PyPI publish fails:**
125+
- Verify PyPI Trusted Publisher is configured correctly
126+
- Check if version already exists on PyPI
127+
- Ensure package builds successfully locally with `uv build`
128+
- Verify the repository and workflow file match the trusted publisher configuration
129+
- Check that `uv publish` has proper OIDC token access (requires `id-token: write` permission)
130+
131+
**Permission errors:**
132+
- Verify GitHub App has necessary permissions
133+
- Check that secrets and variables are properly configured
134+
135+
### Getting Help
136+
137+
1. Check the [Actions tab](../../actions) for detailed logs
138+
2. Review failed workflow runs for specific error messages
139+
3. Create an issue if you encounter persistent problems
140+
141+
## Local Testing
142+
143+
Before releasing, you can test the package locally:
144+
145+
```bash
146+
# Install dependencies
147+
uv sync --dev
148+
149+
# Run linting
150+
tox -e lint
151+
152+
# Run tests
153+
tox -e py312
154+
155+
# Build package
156+
uv build
157+
158+
# Test installation
159+
pip install dist/*.whl
160+
```
161+
162+
## Security Notes
163+
164+
- Never commit API tokens or secrets to the repository
165+
- The workflow uses `uv publish` with PyPI Trusted Publishers for secure, tokenless publishing
166+
- GitHub App tokens are used for secure repository access
167+
- All secrets should be stored in GitHub repository settings
168+
- Trusted Publishers with `uv publish` eliminate the need for long-lived PyPI API tokens
169+
- `uv publish` natively supports OIDC authentication without additional GitHub Actions
170+
171+
## PyPI Trusted Publishers Setup
172+
173+
To configure PyPI Trusted Publishers:
174+
175+
1. **Go to PyPI** → Your project → Manage → Publishing
176+
2. **Add a new trusted publisher** with these details:
177+
- **Owner**: `Unstract` (your GitHub organization/username)
178+
- **Repository name**: `apihub-python-client`
179+
- **Workflow filename**: `publish.yml`
180+
- **Environment name**: Leave empty (unless using GitHub environments)
181+
3. **Save the configuration**
182+
183+
For more details, see:
184+
- https://docs.pypi.org/trusted-publishers/
185+
- https://docs.astral.sh/uv/guides/publish/#trusted-publishing

‎.github/workflows/publish-on-release.yml

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Publish on Manual Release
2+
3+
on:
4+
release:
5+
types:
6+
- published
7+
8+
jobs:
9+
pypi-publish:
10+
name: upload release to PyPI
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: read
14+
id-token: write
15+
steps:
16+
- uses: actions/checkout@v4
17+
with:
18+
ref: ${{ github.event.release.tag_name }}
19+
20+
- uses: actions/setup-python@v5
21+
with:
22+
python-version: "3.12"
23+
24+
- name: Install uv
25+
uses: astral-sh/setup-uv@v6
26+
with:
27+
version: "0.6.14"
28+
enable-cache: true
29+
30+
- name: Install dependencies
31+
run: uv sync --dev
32+
33+
# Install tox for testing
34+
- name: Install tox with UV
35+
run: uv tool install tox
36+
37+
# Create test environment
38+
- name: Create test env
39+
shell: bash
40+
run: |
41+
if [ -f ".env.example" ]; then
42+
cp .env.example .env
43+
sed -i "s|API_KEY=your_api_key_here|API_KEY=test_api_key|" .env
44+
sed -i "s|BASE_URL=https://api.example.com|BASE_URL=https://api.test.com|" .env
45+
else
46+
echo "API_KEY=test_api_key" > .env
47+
echo "BASE_URL=https://api.test.com" >> .env
48+
fi
49+
50+
# Run linting
51+
- name: Run linting
52+
run: tox -e lint
53+
54+
# Run tests
55+
- name: Run tests
56+
run: tox -e py312
57+
58+
- name: Build package
59+
run: uv build
60+
61+
# Publish to PyPI using Trusted Publishers
62+
- name: Publish to PyPI
63+
run: uv publish

0 commit comments

Comments
 (0)