178 lines
4.8 KiB
Markdown
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. |