python-gitea 0.7.0__tar.gz → 0.9.0__tar.gz

{python_gitea-0.7.0 → python_gitea-0.9.0}/.github/workflows/codeql.yml

@@ -22,13 +22,13 @@ jobs:
               uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
 
             - name: Initialize CodeQL
-              uses: github/codeql-action/init@5595ccaf912efad79be6eef63a5619ff05969be3 # v4
+              uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
               with:
                   languages: python
                   queries: security-and-quality
 
             - name: Autobuild
-              uses: github/codeql-action/autobuild@5595ccaf912efad79be6eef63a5619ff05969be3 # v4
+              uses: github/codeql-action/autobuild@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4
 
             - name: Perform CodeQL Analysis
-              uses: github/codeql-action/analyze@5595ccaf912efad79be6eef63a5619ff05969be3 # v4
+              uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4

{python_gitea-0.7.0 → python_gitea-0.9.0}/.github/workflows/support_floor_update.yml

@@ -22,7 +22,7 @@ jobs:
 
             - name: Apply support policy (spec0, from pyproject tool table)
               id: policy
-              uses: isaac-cf-wong/dependency-support-policy-action@8cfabba7ba994cda4699cdbd0fbc7ede04dac145 # v0.2.3
+              uses: isaac-cf-wong/dependency-support-policy-action@7cce60e19b902747b4267c4f8e53820e3f3656ea # v0.2.4
               with:
                   mode: update
 

{python_gitea-0.7.0 → python_gitea-0.9.0}/.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
           - id: check-json
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.16.2
+      rev: v0.16.3
       hooks:
           - id: ruff
             args: [--fix, --config=pyproject.toml]
@@ -52,7 +52,7 @@ repos:
           - id: actionlint
 
     - repo: https://github.com/astral-sh/uv-pre-commit
-      rev: 0.12.3
+      rev: 0.12.5
       hooks:
           # Update the uv lockfile
           - id: uv-lock

{python_gitea-0.7.0 → python_gitea-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-gitea
-Version: 0.7.0
+Version: 0.9.0
 Summary: A Python package for interacting with the Gitea API, offering a simple interface to access repositories, users, organizations, issues, and more for automation and data management.
 Project-URL: Documentation, https://isaac-cf-wong.github.io/python-gitea
 Project-URL: Source, https://github.com/isaac-cf-wong/python-gitea
@@ -33,29 +33,71 @@ Description-Content-Type: text/markdown
 [![codecov](https://codecov.io/gh/isaac-cf-wong/python-gitea/graph/badge.svg?token=COF8341N60)](https://codecov.io/gh/isaac-cf-wong/python-gitea)
 [![PyPI Version](https://img.shields.io/pypi/v/python-gitea)](https://pypi.org/project/python-gitea/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/python-gitea)](https://pypi.org/project/python-gitea/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/isaac-cf-wong/python-gitea/blob/main/LICENSE)
 [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 [![DOI](https://zenodo.org/badge/1129170965.svg)](https://doi.org/10.5281/zenodo.18211496)
 
-**Note:** This project is still in progress. The promised features are not fully
-ready yet, and APIs are subject to change.
-
-A Python package for interacting with the Gitea API. This package provides a
-simple and intuitive interface to access Gitea repositories, users,
-organizations, issues, and more, enabling seamless integration with Gitea
-instances for automation, data retrieval, and management tasks.
+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: Access to repositories, users, organizations, issues, pull
-requests, and more.
+- **Full API Coverage**: Repositories, users, organizations, issues, pull
+  requests, comments, labels, milestones, notifications, and projects.
+- **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
+
+```bash
+uv venv --python 3.13
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install python-gitea
+```
+
+### 2. Configure an account
+
+```bash
+gitea-cli config add --name my_account --token YOUR_API_TOKEN --base-url https://gitea.example.com
+```
+
+### 3. Use the CLI
+
+```bash
+# List issues of a repository
+gitea-cli issue list --owner my-org --repository my-repo
 
-- Easy Authentication: Support for token-based authentication.
-- Asynchronous Support: Built with async/await for non-blocking operations.
-- Type Hints: Full type annotations for better IDE support and code reliability.
-- Comprehensive Documentation: Detailed guides and API reference.
-- Command-Line Interface: Interact with the Gitea API directly from the terminal
-  for quick, scriptable operations without writing code.
+# Get a user
+gitea-cli user get --username my-org
+```
+
+### 4. Use the Python API
+
+```python
+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](https://isaac-cf-wong.github.io/python-gitea/user-guide/quickstart/),
+[Configuration](https://isaac-cf-wong.github.io/python-gitea/user-guide/configuration/),
+and
+[Python API](https://isaac-cf-wong.github.io/python-gitea/user-guide/python-api/)
+guides in the documentation.
 
 ## Installation
 
@@ -125,14 +167,10 @@ 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 ".[dev]"
-
-# Install the commitlint dependencies
-npm install
+uv sync --group dev
 
 # Install pre-commit hooks
-pre-commit install
-pre-commit install --hook-type commit-msg
+uv run prek install
 ```
 
 ### Verify Installation
@@ -147,9 +185,29 @@ gitea-cli --help
 python -c "import gitea; print(gitea.__version__)"
 ```
 
+## Documentation
+
+Full documentation is available at
+[https://isaac-cf-wong.github.io/python-gitea](https://isaac-cf-wong.github.io/python-gitea).
+
+## Contributing
+
+Contributions are welcome! Please read the
+[Contributing Guide](https://isaac-cf-wong.github.io/python-gitea/contributing/)
+before opening a pull request.
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+This project is licensed under the MIT License - see the
+[LICENSE](https://github.com/isaac-cf-wong/python-gitea/blob/main/LICENSE) file
 for details.
 
 ## Support

{python_gitea-0.7.0 → python_gitea-0.9.0}/README.md

@@ -6,29 +6,71 @@
 [![codecov](https://codecov.io/gh/isaac-cf-wong/python-gitea/graph/badge.svg?token=COF8341N60)](https://codecov.io/gh/isaac-cf-wong/python-gitea)
 [![PyPI Version](https://img.shields.io/pypi/v/python-gitea)](https://pypi.org/project/python-gitea/)
 [![Python Versions](https://img.shields.io/pypi/pyversions/python-gitea)](https://pypi.org/project/python-gitea/)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/isaac-cf-wong/python-gitea/blob/main/LICENSE)
 [![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 [![DOI](https://zenodo.org/badge/1129170965.svg)](https://doi.org/10.5281/zenodo.18211496)
 
-**Note:** This project is still in progress. The promised features are not fully
-ready yet, and APIs are subject to change.
-
-A Python package for interacting with the Gitea API. This package provides a
-simple and intuitive interface to access Gitea repositories, users,
-organizations, issues, and more, enabling seamless integration with Gitea
-instances for automation, data retrieval, and management tasks.
+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: Access to repositories, users, organizations, issues, pull
-requests, and more.
+- **Full API Coverage**: Repositories, users, organizations, issues, pull
+  requests, comments, labels, milestones, notifications, and projects.
+- **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
+
+```bash
+uv venv --python 3.13
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv pip install python-gitea
+```
+
+### 2. Configure an account
+
+```bash
+gitea-cli config add --name my_account --token YOUR_API_TOKEN --base-url https://gitea.example.com
+```
+
+### 3. Use the CLI
+
+```bash
+# List issues of a repository
+gitea-cli issue list --owner my-org --repository my-repo
 
-- Easy Authentication: Support for token-based authentication.
-- Asynchronous Support: Built with async/await for non-blocking operations.
-- Type Hints: Full type annotations for better IDE support and code reliability.
-- Comprehensive Documentation: Detailed guides and API reference.
-- Command-Line Interface: Interact with the Gitea API directly from the terminal
-  for quick, scriptable operations without writing code.
+# Get a user
+gitea-cli user get --username my-org
+```
+
+### 4. Use the Python API
+
+```python
+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](https://isaac-cf-wong.github.io/python-gitea/user-guide/quickstart/),
+[Configuration](https://isaac-cf-wong.github.io/python-gitea/user-guide/configuration/),
+and
+[Python API](https://isaac-cf-wong.github.io/python-gitea/user-guide/python-api/)
+guides in the documentation.
 
 ## Installation
 
@@ -98,14 +140,10 @@ 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 ".[dev]"
-
-# Install the commitlint dependencies
-npm install
+uv sync --group dev
 
 # Install pre-commit hooks
-pre-commit install
-pre-commit install --hook-type commit-msg
+uv run prek install
 ```
 
 ### Verify Installation
@@ -120,9 +158,29 @@ gitea-cli --help
 python -c "import gitea; print(gitea.__version__)"
 ```
 
+## Documentation
+
+Full documentation is available at
+[https://isaac-cf-wong.github.io/python-gitea](https://isaac-cf-wong.github.io/python-gitea).
+
+## Contributing
+
+Contributions are welcome! Please read the
+[Contributing Guide](https://isaac-cf-wong.github.io/python-gitea/contributing/)
+before opening a pull request.
+
+## Testing
+
+Run the test suite:
+
+```bash
+uv run pytest
+```
+
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+This project is licensed under the MIT License - see the
+[LICENSE](https://github.com/isaac-cf-wong/python-gitea/blob/main/LICENSE) file
 for details.
 
 ## Support

python_gitea-0.9.0/docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

python_gitea-0.9.0/docs/dev/architecture.md

@@ -0,0 +1,145 @@
+# Architecture
+
+This document describes the high-level architecture and design of
+`python-gitea`: how the package is laid out, how the client and CLI relate, and
+the design principles behind them.
+
+## Overview
+
+`python-gitea` is a thin, typed wrapper around the
+[Gitea REST API](https://docs.gitea.com/api/1.0). It provides two user-facing
+surfaces that share the same domain model:
+
+- **Python client** - synchronous (`Gitea`) and asynchronous (`AsyncGitea`)
+  clients with one resource object per Gitea domain.
+- **CLI** - `gitea-cli`, a Typer application with one command group per domain.
+
+Both surfaces authenticate to Gitea with a personal access token and base URL.
+The CLI resolves configured accounts through `cli/utils/auth.py`
+([Configuration](../user-guide/configuration.md)), while Python callers pass
+their credentials directly to the `Gitea` or `AsyncGitea` constructor.
+
+## Package Layout
+
+```text
+src/gitea/
+├── __init__.py              # Top-level package (exports __version__)
+├── __main__.py              # python -m gitea
+├── version.py               # Version information
+├── client/                  # Client classes
+│   ├── base.py              # Client base class (token, base_url, URL building)
+│   ├── gitea.py             # Synchronous Gitea client
+│   └── async_gitea.py       # Asynchronous AsyncGitea client (aiohttp)
+├── config/                  # Configuration layer
+│   ├── model.py             # Pydantic models (AccountConfig, Config)
+│   └── manager.py           # ConfigManager (load/save/CRUD accounts)
+├── resource/                # Resource base class
+│   └── resource.py          # Shared request helpers for resources
+├── issue/                   # Issue resource (sync + async)
+├── pull_request/            # Pull request resource (sync + async)
+├── repository/              # Repository resource (sync + async)
+├── user/                    # User resource (sync + async)
+├── comment/                 # Comment resource (sync + async)
+├── label/                   # Label resource (sync + async)
+├── milestone/               # Milestone resource (sync + async)
+├── notification/            # Notification resource (sync + async)
+├── project/                 # Project resource (sync + async)
+├── cli/                     # Typer CLI application
+│   ├── main.py              # gitea-cli entry point, command registration
+│   ├── config/              # config commands
+│   ├── issue/               # issue + issue dependency commands
+│   ├── pull_request/        # pull-request commands
+│   ├── comment/             # comment commands
+│   ├── label/               # label commands
+│   ├── milestone/           # milestone commands
+│   ├── notification/        # notification commands
+│   ├── project/             # project, column, and project-issue commands
+│   ├── user/                # user commands
+│   └── utils/               # auth resolution, API helpers, conversions
+└── utils/                   # Logging, pagination, and response helpers
+    ├── log.py               # Logger setup
+    ├── pagination.py        # Paginated-listing walkers
+    └── response.py          # Response processing helpers
+```
+
+## Client Layer
+
+The client layer is the programmatic interface. Both clients inherit from
+`Client`, which stores the token and base URL and builds API URLs.
+
+- `gitea.client.gitea.Gitea` uses `requests` and must be used as a context
+  manager so its HTTP session is closed.
+- `gitea.client.async_gitea.AsyncGitea` uses `aiohttp` and must be used as an
+  async context manager.
+
+Each client exposes one attribute per resource:
+
+```python
+with Gitea(token="...", base_url="...") as client:
+    client.issue          # Issue
+    client.pull_request   # PullRequest
+    client.repository     # Repository
+    client.user           # User
+    client.comment        # Comment
+    client.label          # Label
+    client.milestone      # Milestone
+    client.notification   # Notification
+    client.project        # Project
+```
+
+## Resource Layer
+
+Each resource module contains a synchronous class (e.g. `gitea.issue.Issue`) and
+an asynchronous class (e.g. `gitea.issue.AsyncIssue`) with the same method
+names. Methods map one-to-one onto Gitea REST endpoints and return either:
+
+- a `(data, status)` tuple for list/get operations, where `data` is the decoded
+  JSON payload and `status` carries metadata such as the HTTP status code, or
+- the raw HTTP response for mutating operations.
+
+Work that spans several endpoints lives beside the resource rather than inside
+it, so the resource methods stay one-to-one with the API. For example,
+`gitea.issue.project_column` resolves the board column an issue's card sits in,
+which Gitea only reveals through the project's column listings.
+
+## CLI Layer
+
+The CLI is a single Typer application registered in `cli/main.py`. Each resource
+has a command group (e.g. `gitea-cli issue`, `gitea-cli project`), and nested
+groups exist where the domain nests (e.g. `project column`, `issue dependency`).
+
+CLI commands reuse the client through thin helper functions in `cli/utils/`
+(`auth.py` resolves authentication, `api.py` and `convert.py` handle requests
+and option conversion), so the CLI and the Python API stay in sync with the same
+endpoint definitions.
+
+## Configuration Layer
+
+The `config/` module stores named accounts in a YAML file:
+
+- `model.py` defines the Pydantic models `AccountConfig` and `Config`.
+- `manager.py` provides `ConfigManager` for loading, saving, and CRUD on
+  accounts, including the default-account concept.
+
+The CLI resolves authentication through `cli/utils/auth.py`, which implements
+the precedence rules documented in
+[Configuration](../user-guide/configuration.md). Python callers instead pass
+credentials directly to the client constructor; they can use `ConfigManager` to
+load stored accounts programmatically.
+
+## Design Principles
+
+1. **Thin wrappers, no business logic.** The package mirrors the Gitea API
+   surface instead of abstracting it, keeping behavior predictable.
+2. **Synchronous and asynchronous parity.** Sync and async classes expose the
+   same methods, so switching between them only changes the client and awaits.
+3. **One source of endpoint definitions.** CLI and client share the request
+   layer, avoiding drift between the two surfaces.
+4. **Type hints and validation everywhere.** Pydantic models for config, full
+   type annotations on all public methods, and validated option types on the
+   CLI.
+
+## See Also
+
+- [Contributing](../contributing.md)
+- [API Reference](../reference/index.md)