Yiqun/gitea-shim/python/README.md

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:

pip install gitea

Configuration

The shim automatically detects whether to use GitHub or Gitea based on environment variables:

GitHub Mode (Default)

export GITHUB_TOKEN="your_github_token"
# USE_GITEA is not set or set to 'false'

Gitea Mode

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

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):

from github import Github

gh = Github("your_token")
repo = gh.get_repo("owner/repo")

After (with shim):

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

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:

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.