forgejo 1.0.0__tar.gz

forgejo-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AboveColin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

forgejo-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: forgejo
+Version: 1.0.0
+Summary: Async client library for the Forgejo and Gitea REST API
+Author-email: AboveColin <colin@cdevries.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/AboveColin/forgejo
+Project-URL: Issues, https://github.com/AboveColin/forgejo/issues
+Keywords: forgejo,gitea,git,forge,async,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: yarl>=1.9
+Dynamic: license-file
+
+# forgejo
+
+Async Python client for the [Forgejo](https://forgejo.org/) REST API. Forgejo
+keeps API compatibility with Gitea, so this works against Gitea instances too.
+
+The library covers the read-only surface needed to monitor a forge: version,
+account, unread notifications, repository counters, the latest Actions run, and
+the tip commit. It has no Home Assistant dependency — if that is what you are
+after, see [HA-Forgejo](https://github.com/AboveColin/HA-Forgejo).
+
+## Install
+
+```bash
+pip install forgejo
+```
+
+Requires Python 3.12+.
+
+## Use
+
+```python
+import asyncio
+
+from forgejo import ForgejoClient
+
+
+async def main() -> None:
+    async with ForgejoClient("https://git.example.com", token="your-api-token") as client:
+        server = await client.get_version()
+        print(f"Forgejo {server.version}")
+
+        me = await client.get_authenticated_user()
+        print(f"Signed in as {me.login}")
+
+        print(f"{await client.get_new_notification_count()} unread notifications")
+
+        repo = await client.get_repository("example-user", "example-repo")
+        print(f"{repo.full_name}: {repo.open_issues} issues, {repo.open_pull_requests} PRs")
+
+        run = await client.get_latest_workflow_run("example-user", "example-repo")
+        if run is not None:
+            print(f"Last CI run: {run.name} -> {run.status}")
+
+
+asyncio.run(main())
+```
+
+### Bring your own session
+
+Pass an existing `aiohttp.ClientSession` and the client will use it and leave it
+open. This is what you want inside a larger application that already pools
+connections.
+
+```python
+async with aiohttp.ClientSession() as session:
+    client = ForgejoClient("https://git.example.com", token="...", session=session)
+```
+
+### Self-signed certificates
+
+Instances on a private network often use a certificate the system trust store
+does not know about.
+
+```python
+client = ForgejoClient("https://git.internal", token="...", verify_ssl=False)
+```
+
+Turning verification off means the connection is encrypted but unauthenticated.
+Prefer installing the CA certificate where possible.
+
+## Getting a token
+
+In the web UI: **Settings → Applications → Generate New Token**. Read-only
+scopes are enough:
+
+- `read:repository` — repository counters, Actions runs, commits
+- `read:issue` — issue and pull-request counts
+- `read:notification` — unread notification count
+- `read:user` — the account the token belongs to
+
+Everything except `get_version()` needs a token.
+
+## API
+
+| Method | Returns |
+|---|---|
+| `get_version()` | `ServerInfo` |
+| `get_authenticated_user()` | `User` |
+| `get_new_notification_count()` | `int` |
+| `list_repositories(limit=50)` | `list[Repository]` |
+| `get_repository(owner, repo)` | `Repository` |
+| `get_latest_workflow_run(owner, repo)` | `WorkflowRun \| None` |
+| `get_latest_commit(owner, repo)` | `Commit \| None` |
+
+Methods return dataclasses, never raw dictionaries. `None` means the thing does
+not exist — a repository with no workflows, or an empty repository with no
+commits — which is different from an error.
+
+## Errors
+
+All exceptions derive from `ForgejoError`:
+
+- `ForgejoConnectionError` — unreachable or timed out
+- `ForgejoAuthenticationError` — token rejected or missing a scope
+- `ForgejoNotFoundError` — no such repository or endpoint
+- `ForgejoResponseError` — answered, but not with usable JSON
+
+A common cause of `ForgejoResponseError` is an auth proxy in front of the
+instance returning its own login page with HTTP 200.
+
+## Notes on the API
+
+- `open_issues` excludes pull requests. Pull requests are counted separately in
+  `open_pull_requests`. This surprises people coming from the GitHub API, where
+  the equivalent field includes both.
+- A workflow run status is only meaningful once it reaches a terminal state.
+  `TERMINAL_RUN_STATUSES` holds the set; anything else means still running,
+  which is not the same as failing.
+
+## License
+
+MIT

forgejo-1.0.0/README.md

@@ -0,0 +1,122 @@
+# forgejo
+
+Async Python client for the [Forgejo](https://forgejo.org/) REST API. Forgejo
+keeps API compatibility with Gitea, so this works against Gitea instances too.
+
+The library covers the read-only surface needed to monitor a forge: version,
+account, unread notifications, repository counters, the latest Actions run, and
+the tip commit. It has no Home Assistant dependency — if that is what you are
+after, see [HA-Forgejo](https://github.com/AboveColin/HA-Forgejo).
+
+## Install
+
+```bash
+pip install forgejo
+```
+
+Requires Python 3.12+.
+
+## Use
+
+```python
+import asyncio
+
+from forgejo import ForgejoClient
+
+
+async def main() -> None:
+    async with ForgejoClient("https://git.example.com", token="your-api-token") as client:
+        server = await client.get_version()
+        print(f"Forgejo {server.version}")
+
+        me = await client.get_authenticated_user()
+        print(f"Signed in as {me.login}")
+
+        print(f"{await client.get_new_notification_count()} unread notifications")
+
+        repo = await client.get_repository("example-user", "example-repo")
+        print(f"{repo.full_name}: {repo.open_issues} issues, {repo.open_pull_requests} PRs")
+
+        run = await client.get_latest_workflow_run("example-user", "example-repo")
+        if run is not None:
+            print(f"Last CI run: {run.name} -> {run.status}")
+
+
+asyncio.run(main())
+```
+
+### Bring your own session
+
+Pass an existing `aiohttp.ClientSession` and the client will use it and leave it
+open. This is what you want inside a larger application that already pools
+connections.
+
+```python
+async with aiohttp.ClientSession() as session:
+    client = ForgejoClient("https://git.example.com", token="...", session=session)
+```
+
+### Self-signed certificates
+
+Instances on a private network often use a certificate the system trust store
+does not know about.
+
+```python
+client = ForgejoClient("https://git.internal", token="...", verify_ssl=False)
+```
+
+Turning verification off means the connection is encrypted but unauthenticated.
+Prefer installing the CA certificate where possible.
+
+## Getting a token
+
+In the web UI: **Settings → Applications → Generate New Token**. Read-only
+scopes are enough:
+
+- `read:repository` — repository counters, Actions runs, commits
+- `read:issue` — issue and pull-request counts
+- `read:notification` — unread notification count
+- `read:user` — the account the token belongs to
+
+Everything except `get_version()` needs a token.
+
+## API
+
+| Method | Returns |
+|---|---|
+| `get_version()` | `ServerInfo` |
+| `get_authenticated_user()` | `User` |
+| `get_new_notification_count()` | `int` |
+| `list_repositories(limit=50)` | `list[Repository]` |
+| `get_repository(owner, repo)` | `Repository` |
+| `get_latest_workflow_run(owner, repo)` | `WorkflowRun \| None` |
+| `get_latest_commit(owner, repo)` | `Commit \| None` |
+
+Methods return dataclasses, never raw dictionaries. `None` means the thing does
+not exist — a repository with no workflows, or an empty repository with no
+commits — which is different from an error.
+
+## Errors
+
+All exceptions derive from `ForgejoError`:
+
+- `ForgejoConnectionError` — unreachable or timed out
+- `ForgejoAuthenticationError` — token rejected or missing a scope
+- `ForgejoNotFoundError` — no such repository or endpoint
+- `ForgejoResponseError` — answered, but not with usable JSON
+
+A common cause of `ForgejoResponseError` is an auth proxy in front of the
+instance returning its own login page with HTTP 200.
+
+## Notes on the API
+
+- `open_issues` excludes pull requests. Pull requests are counted separately in
+  `open_pull_requests`. This surprises people coming from the GitHub API, where
+  the equivalent field includes both.
+- A workflow run status is only meaningful once it reaches a terminal state.
+  `TERMINAL_RUN_STATUSES` holds the set; anything else means still running,
+  which is not the same as failing.
+
+## License
+
+MIT

forgejo-1.0.0/forgejo/__init__.py

@@ -0,0 +1,33 @@
+"""Async client library for the Forgejo (and Gitea) REST API."""
+
+from __future__ import annotations
+
+from .client import ForgejoClient
+from .constants import TERMINAL_RUN_STATUSES
+from .exceptions import (
+    ForgejoAuthenticationError,
+    ForgejoConnectionError,
+    ForgejoError,
+    ForgejoNotFoundError,
+    ForgejoResponseError,
+)
+from .models import Commit, Release, Repository, ServerInfo, User, WorkflowRun
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "TERMINAL_RUN_STATUSES",
+    "Commit",
+    "ForgejoAuthenticationError",
+    "ForgejoClient",
+    "ForgejoConnectionError",
+    "ForgejoError",
+    "ForgejoNotFoundError",
+    "ForgejoResponseError",
+    "Release",
+    "Repository",
+    "ServerInfo",
+    "User",
+    "WorkflowRun",
+    "__version__",
+]

forgejo-1.0.0/forgejo/client.py

@@ -0,0 +1,242 @@
+"""Async client for the Forgejo (and Gitea) REST API."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any, Self
+
+import aiohttp
+from yarl import URL
+
+from .constants import (
+    API_PREFIX,
+    COUNT_HEADER,
+    DEFAULT_TIMEOUT,
+    EP_ISSUE_SEARCH,
+    EP_NEW_NOTIFICATIONS,
+    EP_REPO,
+    EP_REPO_COMMITS,
+    EP_REPO_RELEASES,
+    EP_REPO_TASKS,
+    EP_USER,
+    EP_USER_REPOS,
+    EP_VERSION,
+    REPO_PAGE_SIZE,
+)
+from .exceptions import (
+    ForgejoAuthenticationError,
+    ForgejoConnectionError,
+    ForgejoNotFoundError,
+    ForgejoResponseError,
+)
+from .models import Commit, Release, Repository, ServerInfo, User, WorkflowRun
+
+__all__ = ["ForgejoClient"]
+
+
+class ForgejoClient:
+    """Talk to one Forgejo instance.
+
+    The client is safe to reuse across many requests and holds no state beyond
+    the session and credentials.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        *,
+        session: aiohttp.ClientSession | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        verify_ssl: bool = True,
+    ) -> None:
+        """Configure the client.
+
+        Pass ``session`` to reuse an existing one; the caller keeps ownership of
+        it and ``close()`` will leave it open.
+        """
+        self._base = URL(base_url.rstrip("/") + API_PREFIX + "/")
+        self._token = token
+        self._session = session
+        self._owns_session = session is None
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._verify_ssl = verify_ssl
+
+    async def __aenter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Leave the context manager, closing an owned session."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the session, but only if this client created it."""
+        if self._owns_session and self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    async def _request(self, path: str, **params: Any) -> Any:
+        """Perform one GET and return decoded JSON."""
+        payload, _ = await self._request_with_headers(path, **params)
+        return payload
+
+    async def _request_with_headers(
+        self, path: str, **params: Any
+    ) -> tuple[Any, Mapping[str, str]]:
+        """Perform one GET and return decoded JSON plus the response headers."""
+        if self._session is None:
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+
+        headers = {"Accept": "application/json"}
+        if self._token:
+            headers["Authorization"] = f"token {self._token}"
+
+        url = self._base.join(URL(path.lstrip("/")))
+        try:
+            response = await self._session.get(
+                url,
+                headers=headers,
+                params={k: str(v) for k, v in params.items() if v is not None},
+                timeout=self._timeout,
+                ssl=self._verify_ssl,
+            )
+        except asyncio.TimeoutError as err:
+            raise ForgejoConnectionError(f"Timeout talking to {url.host}") from err
+        except (aiohttp.ClientError, socket.gaierror) as err:
+            raise ForgejoConnectionError(f"Cannot reach {url.host}: {err}") from err
+
+        async with response:
+            if response.status in (401, 403):
+                raise ForgejoAuthenticationError(
+                    "Forgejo rejected the token; check that it is valid and has "
+                    "the required read scopes"
+                )
+            if response.status == 404:
+                raise ForgejoNotFoundError(f"Not found: {path}")
+            if response.status >= 400:
+                raise ForgejoResponseError(
+                    f"Forgejo returned HTTP {response.status} for {path}"
+                )
+            # A reverse proxy that intercepts the request (an auth portal, a
+            # captive login page) answers 200 with HTML. Decoding rather than
+            # trusting Content-Type keeps the error message honest.
+            try:
+                return await response.json(content_type=None), response.headers
+            except ValueError as err:
+                raise ForgejoResponseError(
+                    f"Expected JSON from {path}; got something else. Is this URL "
+                    "really a Forgejo instance, and is it behind an auth proxy?"
+                ) from err
+
+    async def get_version(self) -> ServerInfo:
+        """Read the instance version. Works without a token on most installs."""
+        data = await self._request(EP_VERSION)
+        if not isinstance(data, dict) or "version" not in data:
+            raise ForgejoResponseError("No version in response; not a Forgejo API")
+        return ServerInfo.from_api(data)
+
+    async def get_authenticated_user(self) -> User:
+        """Read the account the token belongs to."""
+        data = await self._request(EP_USER)
+        if not isinstance(data, dict):
+            raise ForgejoResponseError("Unexpected payload for the current user")
+        return User.from_api(data)
+
+    async def get_new_notification_count(self) -> int:
+        """Count unread notifications for the authenticated user."""
+        data = await self._request(EP_NEW_NOTIFICATIONS)
+        if not isinstance(data, dict):
+            raise ForgejoResponseError("Unexpected payload for notifications")
+        return int(data.get("new", 0))
+
+    async def _count(self, path: str, **params: Any) -> int:
+        """Ask for a single item and read the total out of the count header.
+
+        Forgejo reports the size of the full result set in ``X-Total-Count``,
+        so paging through everything just to count it would be wasted traffic.
+        """
+        _, headers = await self._request_with_headers(path, limit=1, **params)
+        try:
+            return int(headers.get(COUNT_HEADER, 0))
+        except (TypeError, ValueError):
+            raise ForgejoResponseError(f"No usable {COUNT_HEADER} for {path}") from None
+
+    async def get_assigned_issue_count(self) -> int:
+        """Count open issues assigned to the authenticated user."""
+        return await self._count(EP_ISSUE_SEARCH, state="open", assigned="true")
+
+    async def get_review_request_count(self) -> int:
+        """Count open pull requests waiting on the user's review."""
+        return await self._count(
+            EP_ISSUE_SEARCH, state="open", type="pulls", review_requested="true"
+        )
+
+    async def get_latest_release(self, owner: str, repo: str) -> Release | None:
+        """Return the newest release, or ``None`` if the repo has none.
+
+        ``/releases/latest`` answers 404 for a repository without releases, so
+        the list endpoint is used instead: an empty list is a state, not an
+        error.
+        """
+        data = await self._request(
+            EP_REPO_RELEASES.format(owner=owner, repo=repo), limit=1
+        )
+        if not isinstance(data, list) or not data or not isinstance(data[0], dict):
+            return None
+        return Release.from_api(data[0])
+
+    async def list_repositories(self, limit: int = REPO_PAGE_SIZE) -> list[Repository]:
+        """List repositories the token can see, newest activity first."""
+        data = await self._request(EP_USER_REPOS, limit=limit)
+        if not isinstance(data, list):
+            raise ForgejoResponseError("Unexpected payload for the repository list")
+        return [Repository.from_api(item) for item in data if isinstance(item, dict)]
+
+    async def get_repository(self, owner: str, repo: str) -> Repository:
+        """Read one repository and its counters."""
+        data = await self._request(EP_REPO.format(owner=owner, repo=repo))
+        if not isinstance(data, dict):
+            raise ForgejoResponseError(f"Unexpected payload for {owner}/{repo}")
+        return Repository.from_api(data)
+
+    async def get_latest_workflow_run(
+        self, owner: str, repo: str
+    ) -> WorkflowRun | None:
+        """Return the most recent Actions run, or ``None`` if there are none.
+
+        No runs is a legitimate answer for a repository without workflows, so
+        it is not an error.
+        """
+        data = await self._request(
+            EP_REPO_TASKS.format(owner=owner, repo=repo), limit=1
+        )
+        if not isinstance(data, dict):
+            raise ForgejoResponseError(f"Unexpected payload for {owner}/{repo} runs")
+        runs = data.get("workflow_runs") or []
+        if not runs or not isinstance(runs[0], dict):
+            return None
+        return WorkflowRun.from_api(runs[0])
+
+    async def get_latest_commit(self, owner: str, repo: str) -> Commit | None:
+        """Return the tip commit of the default branch, if the repo has one."""
+        try:
+            data = await self._request(
+                EP_REPO_COMMITS.format(owner=owner, repo=repo), limit=1, stat="false"
+            )
+        except ForgejoNotFoundError:
+            # An empty repository has no commits and answers 404 here. That is
+            # a state, not a failure.
+            return None
+        if not isinstance(data, list) or not data or not isinstance(data[0], dict):
+            return None
+        return Commit.from_api(data[0])

forgejo-1.0.0/forgejo/constants.py

@@ -0,0 +1,46 @@
+"""Endpoints and magic values for the Forgejo/Gitea REST API."""
+
+from __future__ import annotations
+
+from typing import Final
+
+API_PREFIX: Final = "/api/v1"
+
+DEFAULT_TIMEOUT: Final = 10.0
+
+# The version endpoint is the only one that answers without a token on a
+# default install, which makes it the cheapest way to prove a URL points at a
+# Forgejo instance before we ask the user for credentials.
+EP_VERSION: Final = "/version"
+EP_USER: Final = "/user"
+EP_USER_REPOS: Final = "/user/repos"
+EP_NEW_NOTIFICATIONS: Final = "/notifications/new"
+EP_REPO: Final = "/repos/{owner}/{repo}"
+EP_REPO_TASKS: Final = "/repos/{owner}/{repo}/actions/tasks"
+EP_REPO_COMMITS: Final = "/repos/{owner}/{repo}/commits"
+EP_REPO_RELEASES: Final = "/repos/{owner}/{repo}/releases"
+EP_ISSUE_SEARCH: Final = "/repos/issues/search"
+
+# Counting endpoints report the total in a header, so asking for a single item
+# is enough to learn how many there are.
+COUNT_HEADER: Final = "X-Total-Count"
+
+# Forgejo pages repository listings; 50 is the server-side default maximum on
+# most instances and keeps the picker in a config flow to one round trip.
+REPO_PAGE_SIZE: Final = 50
+
+# Terminal states reported by the Actions API. Anything else means the run is
+# still going, which is not the same thing as a run that succeeded.
+RUN_STATUS_SUCCESS: Final = "success"
+RUN_STATUS_FAILURE: Final = "failure"
+RUN_STATUS_CANCELLED: Final = "cancelled"
+RUN_STATUS_SKIPPED: Final = "skipped"
+
+TERMINAL_RUN_STATUSES: Final = frozenset(
+    {
+        RUN_STATUS_SUCCESS,
+        RUN_STATUS_FAILURE,
+        RUN_STATUS_CANCELLED,
+        RUN_STATUS_SKIPPED,
+    }
+)

forgejo-1.0.0/forgejo/exceptions.py

@@ -0,0 +1,31 @@
+"""Exceptions raised by the Forgejo client."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ForgejoAuthenticationError",
+    "ForgejoConnectionError",
+    "ForgejoError",
+    "ForgejoNotFoundError",
+    "ForgejoResponseError",
+]
+
+
+class ForgejoError(Exception):
+    """Base class for every error raised by this library."""
+
+
+class ForgejoConnectionError(ForgejoError):
+    """The server could not be reached, or it did not answer in time."""
+
+
+class ForgejoAuthenticationError(ForgejoError):
+    """The token was rejected, or it lacks the scope for this request."""
+
+
+class ForgejoNotFoundError(ForgejoError):
+    """The requested repository, user or endpoint does not exist."""
+
+
+class ForgejoResponseError(ForgejoError):
+    """The server answered, but not with something we can use."""

forgejo-1.0.0/forgejo/models.py

@@ -0,0 +1,208 @@
+"""Typed models returned by the client.
+
+Callers never see raw JSON. Every ``from_api`` classmethod is defensive about
+missing keys: Forgejo has been through several API generations and a field that
+exists on one instance may be absent on an older or newer one. A missing value
+becomes ``None`` rather than a guess.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+__all__ = ["Commit", "Release", "Repository", "ServerInfo", "User", "WorkflowRun"]
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+    """Parse an API timestamp, tolerating the ``Z`` suffix and junk."""
+    if not isinstance(value, str) or not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    # Forgejo returns the zero time for "never happened"; surfacing year 1 as a
+    # real timestamp makes template sensors render nonsense dates.
+    return None if parsed.year <= 1 else parsed
+
+
+@dataclass(frozen=True, slots=True)
+class ServerInfo:
+    """Version banner of the instance."""
+
+    version: str
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> ServerInfo:
+        """Build from a ``/version`` payload."""
+        return cls(version=str(data.get("version", "")))
+
+
+@dataclass(frozen=True, slots=True)
+class User:
+    """The account the token belongs to."""
+
+    id: int
+    login: str
+    full_name: str | None
+    is_admin: bool
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> User:
+        """Build from a ``/user`` payload."""
+        return cls(
+            id=int(data.get("id", 0)),
+            login=str(data.get("login", "")),
+            full_name=data.get("full_name") or None,
+            is_admin=bool(data.get("is_admin", False)),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Repository:
+    """A single repository and its counters."""
+
+    id: int
+    name: str
+    owner: str
+    full_name: str
+    private: bool
+    archived: bool
+    fork: bool
+    mirror: bool
+    default_branch: str | None
+    description: str | None
+    language: str | None
+    html_url: str | None
+    has_actions: bool
+    open_issues: int
+    open_pull_requests: int
+    stars: int
+    forks: int
+    watchers: int
+    releases: int
+    size_kb: int
+    updated_at: datetime | None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Repository:
+        """Build from a ``/repos/{owner}/{repo}`` payload."""
+        owner = data.get("owner") or {}
+        return cls(
+            id=int(data.get("id", 0)),
+            name=str(data.get("name", "")),
+            owner=str(owner.get("login", "")),
+            full_name=str(data.get("full_name", "")),
+            private=bool(data.get("private", False)),
+            archived=bool(data.get("archived", False)),
+            fork=bool(data.get("fork", False)),
+            mirror=bool(data.get("mirror", False)),
+            default_branch=data.get("default_branch") or None,
+            description=data.get("description") or None,
+            language=data.get("language") or None,
+            html_url=data.get("html_url") or None,
+            has_actions=bool(data.get("has_actions", False)),
+            # open_issues_count excludes pull requests on Forgejo and Gitea;
+            # open_pr_counter is the separate figure. Adding them together
+            # would double-count nothing, but reporting either as "issues"
+            # silently changes meaning between forge versions.
+            open_issues=int(data.get("open_issues_count", 0)),
+            open_pull_requests=int(data.get("open_pr_counter", 0)),
+            stars=int(data.get("stars_count", 0)),
+            forks=int(data.get("forks_count", 0)),
+            watchers=int(data.get("watchers_count", 0)),
+            releases=int(data.get("release_counter", 0)),
+            size_kb=int(data.get("size", 0)),
+            updated_at=_parse_timestamp(data.get("updated_at")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowRun:
+    """One Forgejo Actions run."""
+
+    id: int
+    name: str | None
+    workflow_id: str | None
+    status: str | None
+    event: str | None
+    head_branch: str | None
+    head_sha: str | None
+    run_number: int | None
+    display_title: str | None
+    url: str | None
+    started_at: datetime | None
+    updated_at: datetime | None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> WorkflowRun:
+        """Build from an entry of ``/actions/tasks``."""
+        return cls(
+            id=int(data.get("id", 0)),
+            name=data.get("name") or None,
+            workflow_id=data.get("workflow_id") or None,
+            status=data.get("status") or None,
+            event=data.get("event") or None,
+            head_branch=data.get("head_branch") or None,
+            head_sha=data.get("head_sha") or None,
+            run_number=data.get("run_number"),
+            display_title=data.get("display_title") or None,
+            url=data.get("url") or None,
+            started_at=_parse_timestamp(data.get("run_started_at")),
+            updated_at=_parse_timestamp(data.get("updated_at")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Release:
+    """A published (or drafted) release."""
+
+    id: int
+    tag_name: str
+    name: str | None
+    draft: bool
+    prerelease: bool
+    html_url: str | None
+    published_at: datetime | None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Release:
+        """Build from an entry of ``/releases``."""
+        return cls(
+            id=int(data.get("id", 0)),
+            tag_name=str(data.get("tag_name", "")),
+            name=data.get("name") or None,
+            draft=bool(data.get("draft", False)),
+            prerelease=bool(data.get("prerelease", False)),
+            html_url=data.get("html_url") or None,
+            published_at=_parse_timestamp(data.get("published_at")),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Commit:
+    """The tip commit of a branch."""
+
+    sha: str
+    message: str | None
+    author: str | None
+    html_url: str | None
+    created_at: datetime | None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Commit:
+        """Build from an entry of ``/commits``."""
+        commit = data.get("commit") or {}
+        author = commit.get("author") or {}
+        message = commit.get("message")
+        return cls(
+            sha=str(data.get("sha", "")),
+            # Only the subject line is useful as a state attribute; the body
+            # can run to kilobytes and Home Assistant caps attribute size.
+            message=message.strip().splitlines()[0] if message else None,
+            author=author.get("name") or None,
+            html_url=data.get("html_url") or None,
+            created_at=_parse_timestamp(commit.get("created") or data.get("created")),
+        )

forgejo-1.0.0/forgejo.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: forgejo
+Version: 1.0.0
+Summary: Async client library for the Forgejo and Gitea REST API
+Author-email: AboveColin <colin@cdevries.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/AboveColin/forgejo
+Project-URL: Issues, https://github.com/AboveColin/forgejo/issues
+Keywords: forgejo,gitea,git,forge,async,api,client
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: yarl>=1.9
+Dynamic: license-file
+
+# forgejo
+
+Async Python client for the [Forgejo](https://forgejo.org/) REST API. Forgejo
+keeps API compatibility with Gitea, so this works against Gitea instances too.
+
+The library covers the read-only surface needed to monitor a forge: version,
+account, unread notifications, repository counters, the latest Actions run, and
+the tip commit. It has no Home Assistant dependency — if that is what you are
+after, see [HA-Forgejo](https://github.com/AboveColin/HA-Forgejo).
+
+## Install
+
+```bash
+pip install forgejo
+```
+
+Requires Python 3.12+.
+
+## Use
+
+```python
+import asyncio
+
+from forgejo import ForgejoClient
+
+
+async def main() -> None:
+    async with ForgejoClient("https://git.example.com", token="your-api-token") as client:
+        server = await client.get_version()
+        print(f"Forgejo {server.version}")
+
+        me = await client.get_authenticated_user()
+        print(f"Signed in as {me.login}")
+
+        print(f"{await client.get_new_notification_count()} unread notifications")
+
+        repo = await client.get_repository("example-user", "example-repo")
+        print(f"{repo.full_name}: {repo.open_issues} issues, {repo.open_pull_requests} PRs")
+
+        run = await client.get_latest_workflow_run("example-user", "example-repo")
+        if run is not None:
+            print(f"Last CI run: {run.name} -> {run.status}")
+
+
+asyncio.run(main())
+```
+
+### Bring your own session
+
+Pass an existing `aiohttp.ClientSession` and the client will use it and leave it
+open. This is what you want inside a larger application that already pools
+connections.
+
+```python
+async with aiohttp.ClientSession() as session:
+    client = ForgejoClient("https://git.example.com", token="...", session=session)
+```
+
+### Self-signed certificates
+
+Instances on a private network often use a certificate the system trust store
+does not know about.
+
+```python
+client = ForgejoClient("https://git.internal", token="...", verify_ssl=False)
+```
+
+Turning verification off means the connection is encrypted but unauthenticated.
+Prefer installing the CA certificate where possible.
+
+## Getting a token
+
+In the web UI: **Settings → Applications → Generate New Token**. Read-only
+scopes are enough:
+
+- `read:repository` — repository counters, Actions runs, commits
+- `read:issue` — issue and pull-request counts
+- `read:notification` — unread notification count
+- `read:user` — the account the token belongs to
+
+Everything except `get_version()` needs a token.
+
+## API
+
+| Method | Returns |
+|---|---|
+| `get_version()` | `ServerInfo` |
+| `get_authenticated_user()` | `User` |
+| `get_new_notification_count()` | `int` |
+| `list_repositories(limit=50)` | `list[Repository]` |
+| `get_repository(owner, repo)` | `Repository` |
+| `get_latest_workflow_run(owner, repo)` | `WorkflowRun \| None` |
+| `get_latest_commit(owner, repo)` | `Commit \| None` |
+
+Methods return dataclasses, never raw dictionaries. `None` means the thing does
+not exist — a repository with no workflows, or an empty repository with no
+commits — which is different from an error.
+
+## Errors
+
+All exceptions derive from `ForgejoError`:
+
+- `ForgejoConnectionError` — unreachable or timed out
+- `ForgejoAuthenticationError` — token rejected or missing a scope
+- `ForgejoNotFoundError` — no such repository or endpoint
+- `ForgejoResponseError` — answered, but not with usable JSON
+
+A common cause of `ForgejoResponseError` is an auth proxy in front of the
+instance returning its own login page with HTTP 200.
+
+## Notes on the API
+
+- `open_issues` excludes pull requests. Pull requests are counted separately in
+  `open_pull_requests`. This surprises people coming from the GitHub API, where
+  the equivalent field includes both.
+- A workflow run status is only meaningful once it reaches a terminal state.
+  `TERMINAL_RUN_STATUSES` holds the set; anything else means still running,
+  which is not the same as failing.
+
+## License
+
+MIT

forgejo-1.0.0/forgejo.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+forgejo/__init__.py
+forgejo/client.py
+forgejo/constants.py
+forgejo/exceptions.py
+forgejo/models.py
+forgejo/py.typed
+forgejo.egg-info/PKG-INFO
+forgejo.egg-info/SOURCES.txt
+forgejo.egg-info/dependency_links.txt
+forgejo.egg-info/requires.txt
+forgejo.egg-info/top_level.txt

forgejo-1.0.0/forgejo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

forgejo-1.0.0/forgejo.egg-info/requires.txt

@@ -0,0 +1,2 @@
+aiohttp>=3.9
+yarl>=1.9

forgejo-1.0.0/forgejo.egg-info/top_level.txt

@@ -0,0 +1 @@
+forgejo

forgejo-1.0.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "forgejo"
+version = "1.0.0"
+description = "Async client library for the Forgejo and Gitea REST API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "AboveColin", email = "colin@cdevries.dev" }]
+keywords = ["forgejo", "gitea", "git", "forge", "async", "api", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.9", "yarl>=1.9"]
+
+[project.urls]
+Homepage = "https://github.com/AboveColin/forgejo"
+Issues = "https://github.com/AboveColin/forgejo/issues"
+
+[tool.setuptools.packages.find]
+include = ["forgejo*"]
+
+[tool.setuptools.package-data]
+forgejo = ["py.typed"]
+
+[tool.pylint.main]
+py-version = "3.12"
+
+[tool.pylint."messages control"]
+disable = ["too-many-instance-attributes", "too-many-arguments", "too-few-public-methods"]

forgejo-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+