Gitea Python SDK

Official Python SDK for the Gitea API with chunked upload support for large files.

Installation

pip install gitea-sdk

Quick Start

from gitea import GiteaClient

# Create client
client = GiteaClient("https://gitea.example.com", token="your_token")

# Get current user
user = client.get_current_user()
print(f"Logged in as {user.login}")

# Get a repository
repo = client.get_repository("owner", "repo")
print(f"Repository: {repo.full_name}")

Chunked Upload

Upload large files with progress tracking and resume capability:

from gitea import GiteaClient

client = GiteaClient("https://gitea.example.com", token="your_token")

# Upload a release asset with progress callback
def on_progress(p):
    print(f"\rProgress: {p.percent:.1f}% ({p.speed_formatted}) ETA: {p.eta}", end="")

with open("large-file.tar.gz", "rb") as f:
    result = client.upload_release_asset(
        owner="myorg",
        repo="myrepo",
        release_id=123,
        file=f,
        filename="large-file.tar.gz",
        chunk_size=50 * 1024 * 1024,  # 50MB chunks
        parallel=4,
        verify_checksum=True,
        progress_callback=on_progress,
    )

print(f"\nUploaded: {result.download_url}")

Resume Interrupted Uploads

# Resume an interrupted upload
result = client.resume_upload(
    session_id="sess_abc123",
    file=open("large-file.tar.gz", "rb"),
    progress_callback=on_progress,
)

API Reference

GiteaClient

Constructor

client = GiteaClient(
    base_url="https://gitea.example.com",
    token="your_api_token",
    timeout=30,  # Request timeout in seconds
)

User Methods

get_current_user() - Get authenticated user
get_user(username) - Get user by username

Repository Methods

get_repository(owner, repo) - Get repository
list_user_repos(username) - List user's repositories

Release Methods

get_release(owner, repo, release_id) - Get release by ID
get_release_by_tag(owner, repo, tag) - Get release by tag
list_releases(owner, repo) - List all releases

Upload Methods

upload_release_asset(...) - Upload release asset with chunked upload
resume_upload(session_id, file) - Resume interrupted upload
get_upload_session(session_id) - Get upload session status
cancel_upload(session_id) - Cancel upload session

Error Handling

from gitea import GiteaClient, APIError, AuthenticationError, NotFoundError

client = GiteaClient("https://gitea.example.com", token="your_token")

try:
    repo = client.get_repository("owner", "nonexistent")
except NotFoundError as e:
    print(f"Repository not found: {e}")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except APIError as e:
    print(f"API error [{e.code}]: {e.message}")

License

MIT License - See LICENSE file for details.