Files
Yiqun/gitea-shim/python/README.md

178 lines
4.8 KiB
Markdown

# Gitea GitHub Shim
A Python library that provides a GitHub-compatible interface for Gitea, allowing you to use the same code with both GitHub and Gitea APIs.
## Features
- **Drop-in replacement** for PyGitHub's `Github` class
- **Automatic switching** between GitHub and Gitea based on environment variables
- **GitHub-compatible interface** - minimal code changes required
- **Error handling** and fallback mechanisms
- **Comprehensive model wrappers** for repositories, users, and pull requests
## Installation
1. Clone this repository or copy the `gitea-shim/python` directory to your project
2. Install the required dependencies:
```bash
pip install gitea
```
## Configuration
The shim automatically detects whether to use GitHub or Gitea based on environment variables:
### GitHub Mode (Default)
```bash
export GITHUB_TOKEN="your_github_token"
# USE_GITEA is not set or set to 'false'
```
### Gitea Mode
```bash
export USE_GITEA="true"
export GITEA_URL="http://your-gitea-instance:3000"
export GITEA_TOKEN="your_gitea_token" # or use GITHUB_TOKEN
```
## Usage
### Basic Usage
```python
from gitea_shim import get_github_client
# This will automatically use GitHub or Gitea based on your environment
gh = get_github_client()
# Get a repository (works the same for both APIs)
repo = gh.get_repo("owner/repo")
# Get user information
user = gh.get_user()
# Create a pull request
pr = repo.create_pull(
title="My PR",
body="Description",
head="feature-branch",
base="main"
)
```
### Migration from PyGitHub
**Before (PyGitHub only):**
```python
from github import Github
gh = Github("your_token")
repo = gh.get_repo("owner/repo")
```
**After (with shim):**
```python
from gitea_shim import get_github_client
gh = get_github_client() # Works with both GitHub and Gitea
repo = gh.get_repo("owner/repo") # Same interface!
```
### Advanced Configuration
```python
from gitea_shim import config, is_gitea_mode, get_api_info
# Check which API you're using
if is_gitea_mode():
print("Using Gitea API")
else:
print("Using GitHub API")
# Get detailed API information
api_info = get_api_info()
print(f"API Type: {api_info['type']}")
print(f"URL: {api_info['url']}")
print(f"Token Set: {api_info['token_set']}")
```
## Supported Methods
### Client Methods
- `get_repo(full_name)` - Get repository by owner/repo name
- `get_user(login=None)` - Get user (authenticated or by login)
- `get_organization(login)` - Get organization
- `create_repo(name, **kwargs)` - Create new repository
- `search_repositories(query, **kwargs)` - Search repositories
- `search_users(query, **kwargs)` - Search users
- `get_api_status()` - Get API status
- `get_rate_limit()` - Get rate limit info
- `get_emojis()` - Get available emojis
- `get_gitignore_templates()` - Get gitignore templates
- `get_license_templates()` - Get license templates
### Repository Methods
- `get_pull(number)` - Get pull request by number
- `get_pulls(**kwargs)` - Get list of pull requests
- `create_pull(title, body, head, base, **kwargs)` - Create pull request
- `get_contents(path, ref=None)` - Get file contents
- `get_branches()` - Get all branches
- `get_branch(branch)` - Get specific branch
- `create_fork(organization=None)` - Fork repository
- `get_commits(**kwargs)` - Get commits
- `get_commit(sha)` - Get specific commit
### Pull Request Methods
- `update(**kwargs)` - Update pull request
- `merge(**kwargs)` - Merge pull request
- `get_commits()` - Get commits in PR
- `get_files()` - Get files changed in PR
- `create_review_comment(body, commit_id, path, position)` - Add review comment
- `create_issue_comment(body)` - Add issue comment
## Testing
Run the test suite to verify the shim works correctly:
```bash
cd gitea-shim/python
python test_shim.py
```
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `USE_GITEA` | Enable Gitea mode | `false` |
| `GITEA_URL` | Gitea instance URL | `http://localhost:3000` |
| `GITHUB_TOKEN` | GitHub/Gitea API token | Required |
| `GITEA_TOKEN` | Gitea-specific token (optional) | Uses `GITHUB_TOKEN` |
## Error Handling
The shim includes comprehensive error handling:
- **Graceful fallbacks** when Gitea methods don't exist
- **Compatible error messages** with GitHub's error format
- **Automatic retry logic** for transient failures
- **Detailed logging** for debugging
## Limitations
- Some GitHub-specific features may not be available in Gitea
- Rate limiting is mocked for Gitea (returns unlimited)
- Some advanced search features may differ between APIs
- Draft pull requests may not be supported in all Gitea versions
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.