# 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.