python-gitea

A Python package for interacting with the Gitea API. It provides a simple, intuitive interface to access Gitea repositories, users, organizations, issues, and more, enabling seamless integration with Gitea instances for automation, data retrieval, and management tasks.

Features

• Full API Coverage: Repositories, users, organizations, issues, pull requests, comments, labels, milestones, notifications, projects, and Actions workflows, runs, and job logs.
• Easy Authentication: Token-based authentication, with multiple saved accounts and a default-account fallback.
• Asynchronous Support: Built with async/await for non-blocking operations alongside the synchronous client.
• Type Hints: Full type annotations for better IDE support and code reliability.
• Command-Line Interface: Interact with the Gitea API directly from the terminal for quick, scriptable operations without writing code.
• Comprehensive Documentation: Detailed guides and a generated API reference.

Quick Start

1. Install

uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install python-gitea

2. Configure an account

gitea-cli config add --name my_account --token YOUR_API_TOKEN --base-url https://gitea.example.com

3. Use the CLI

# List issues of a repository
gitea-cli issue list --owner my-org --repository my-repo

# Get a user
gitea-cli user get --username my-org

4. Use the Python API

from gitea.client.gitea import Gitea

with Gitea(token="YOUR_API_TOKEN", base_url="https://gitea.example.com") as client:
    issues, _ = client.issue.list_issues(owner="my-org", repository="my-repo")

For details, see the Quick Start, Configuration, and Python API guides in the documentation.

Installation

We recommend using uv to manage virtual environments for installing python-gitea.

If you don't have uv installed, you can install it with pip. See the project pages for more details:

• Install via pip: pip install --upgrade pip && pip install uv
• Project pages: uv on PyPI | uv on GitHub
• Full documentation and usage guide: uv docs

Requirements

• Python 3.12 or higher
• Operating System: Linux, macOS, or Windows

Install from PyPI

The recommended way to install python-gitea is from PyPI:

# Create a virtual environment (recommended with uv)
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install python-gitea

Optional Dependencies

For development or specific features:

# Development dependencies (testing, linting, etc.)
uv pip install python-gitea[dev]

# Documentation dependencies
uv pip install python-gitea[docs]

# All dependencies
uv pip install python-gitea[dev,docs]

Install from Source

For the latest development version:

git clone git@github.com:isaac-cf-wong/python-gitea.git
cd python-gitea
# Create a virtual environment (recommended with uv)
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install .

Development Installation

To set up for development:

git clone git@github.com:isaac-cf-wong/python-gitea.git
cd python-gitea

# Create a virtual environment (recommended with uv)
uv venv --python 3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync --group dev

# Install pre-commit hooks
uv run prek install

Verify Installation

Check that python-gitea is installed correctly:

gitea-cli --help

python -c "import gitea; print(gitea.__version__)"

Documentation

Full documentation is available at https://isaac-cf-wong.github.io/python-gitea.

Contributing

Contributions are welcome! Please read the Contributing Guide before opening a pull request.

Testing

Run the test suite:

uv run pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions, issues, or contributions, please:

• Check the documentation
• Open an issue on GitHub
• Join our discussions

Changelog

See Release Notes for version history.