git-alternative 0.2.2__py3-none-any.whl

git_alternative/ssh_keys.py

@@ -0,0 +1,80 @@
+"""SSH key utilities for the Forge platform."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from git_alternative.exceptions import ForgeInvalidSshKeyError
+
+
+def compute_key_fingerprint(public_key_str: str) -> str:
+    """Compute the SHA256 fingerprint of an SSH public key.
+
+    Parses the key material (ignoring key type prefix variations and comment
+    fields) and returns the fingerprint in OpenSSH format: ``SHA256:<base64>``.
+
+    Args:
+        public_key_str: The full SSH public key string, e.g.
+            ``"ssh-ed25519 AAAA... optional-comment"``.
+
+    Returns:
+        The fingerprint string in the format ``"SHA256:<base64>"``.
+
+    Raises:
+        ForgeInvalidSshKeyError: If the key is malformed or contains invalid
+            base64 data.
+
+    Example:
+        >>> fp = compute_key_fingerprint("ssh-ed25519 AAAA... my-laptop")
+        >>> fp.startswith("SHA256:")
+        True
+    """
+    parts = public_key_str.strip().split()
+    if len(parts) < 2:
+        raise ForgeInvalidSshKeyError("Malformed public key: expected at least 2 fields")
+
+    key_type = parts[0]
+    valid_key_types = {
+        "ssh-rsa",
+        "ssh-dss",
+        "ssh-ed25519",
+        "ecdsa-sha2-nistp256",
+        "ecdsa-sha2-nistp384",
+        "ecdsa-sha2-nistp521",
+        "sk-ssh-ed25519@openssh.com",
+        "sk-ecdsa-sha2-nistp256@openssh.com",
+    }
+    if key_type not in valid_key_types:
+        raise ForgeInvalidSshKeyError(f"Unsupported key type: {key_type!r}")
+
+    try:
+        key_bytes = base64.b64decode(parts[1])
+    except Exception as exc:
+        raise ForgeInvalidSshKeyError(f"Invalid base64 in key: {exc}") from exc
+
+    digest = hashlib.sha256(key_bytes).digest()
+    # OpenSSH omits padding in the fingerprint base64
+    b64 = base64.b64encode(digest).decode().rstrip("=")
+    return f"SHA256:{b64}"
+
+
+def normalize_public_key(public_key_str: str) -> str:
+    """Return the canonical form of an SSH public key (type + base64 material only).
+
+    Strips the optional comment field so that keys with different comments but
+    the same key material are treated as identical.
+
+    Args:
+        public_key_str: The full SSH public key string.
+
+    Returns:
+        Normalized key string: ``"<type> <base64>"``.
+
+    Raises:
+        ForgeInvalidSshKeyError: If the key is malformed.
+    """
+    parts = public_key_str.strip().split()
+    if len(parts) < 2:
+        raise ForgeInvalidSshKeyError("Malformed public key: expected at least 2 fields")
+    return f"{parts[0]} {parts[1]}"

git_alternative/utils.py

@@ -0,0 +1,91 @@
+"""Utility functions for the git-alternative SDK."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+
+from git_alternative.exceptions import ForgeSshKeyError
+
+
+def compute_key_fingerprint(public_key_str: str) -> str:
+    """Compute the SHA-256 fingerprint of an SSH public key.
+
+    Parses the key material from a standard OpenSSH public key string,
+    ignoring the key type prefix and optional comment field. The fingerprint
+    is returned in OpenSSH format: ``SHA256:<base64>``.
+
+    Args:
+        public_key_str: An OpenSSH public key string, e.g.
+            ``ssh-rsa AAAA... optional-comment``
+
+    Returns:
+        The SHA-256 fingerprint in OpenSSH format, e.g.
+        ``SHA256:abc123...``
+
+    Raises:
+        ForgeSshKeyError: If the key string is malformed or contains
+            invalid base64 data.
+
+    Example:
+        >>> fingerprint = compute_key_fingerprint("ssh-ed25519 AAAA... mykey")
+        >>> fingerprint.startswith("SHA256:")
+        True
+    """
+    parts = public_key_str.strip().split()
+    if len(parts) < 2:
+        raise ForgeSshKeyError("Malformed public key: expected at least 2 space-separated parts")
+
+    key_b64 = parts[1]
+    try:
+        key_bytes = base64.b64decode(key_b64)
+    except Exception as exc:
+        raise ForgeSshKeyError(f"Invalid base64 in SSH key: {exc}") from exc
+
+    digest = hashlib.sha256(key_bytes).digest()
+    encoded = base64.b64encode(digest).decode("ascii")
+    return f"SHA256:{encoded}"
+
+
+def next_retry_delay(attempt: int, base_delay_secs: int = 10, max_delay_secs: int = 86400) -> int:
+    """Compute exponential backoff delay for webhook retries.
+
+    Uses the formula ``base_delay * 10^attempt``, capped at ``max_delay_secs``.
+
+    Args:
+        attempt: Zero-based attempt number (0 = first retry).
+        base_delay_secs: Base delay in seconds (default: 10).
+        max_delay_secs: Maximum delay in seconds (default: 86400 = 24 hours).
+
+    Returns:
+        Delay in seconds before the next retry attempt.
+
+    Example:
+        >>> next_retry_delay(0)  # 10s
+        10
+        >>> next_retry_delay(1)  # 100s
+        100
+        >>> next_retry_delay(5)  # capped at 86400s
+        86400
+    """
+    delay = base_delay_secs * (10**attempt)
+    return min(delay, max_delay_secs)
+
+
+def build_url(host: str, *path_parts: str) -> str:
+    """Build a full URL from a host and path parts.
+
+    Args:
+        host: Base host URL (trailing slash is stripped).
+        *path_parts: URL path segments to join with ``/``.
+
+    Returns:
+        The full URL string.
+
+    Example:
+        >>> build_url("https://forge.example.com", "api", "v1", "repos")
+        'https://forge.example.com/api/v1/repos'
+    """
+    base = host.rstrip("/")
+    path = "/".join(part.strip("/") for part in path_parts if part)
+    return f"{base}/{path}"

git_alternative/webhooks.py

@@ -0,0 +1,104 @@
+"""Webhook delivery utilities with exponential backoff retry logic."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+_MAX_RETRIES: int = 5
+_BASE_DELAY_SECS: int = 10
+_MAX_DELAY_SECS: int = 86400  # 24 hours
+
+
+def next_retry_delay(attempt: int) -> timedelta:
+    """Calculate the exponential backoff delay for a webhook retry attempt.
+
+    Uses the formula: ``BASE_DELAY * 10^attempt``, capped at 24 hours.
+
+    Args:
+        attempt: Zero-based attempt index (0 = first retry, 4 = fifth retry).
+
+    Returns:
+        A :class:`datetime.timedelta` representing how long to wait before the
+        next delivery attempt.
+
+    Example:
+        >>> next_retry_delay(0).total_seconds()
+        10.0
+        >>> next_retry_delay(1).total_seconds()
+        100.0
+        >>> next_retry_delay(4).total_seconds()
+        86400.0
+    """
+    secs = _BASE_DELAY_SECS * (10**attempt)
+    return timedelta(seconds=min(secs, _MAX_DELAY_SECS))
+
+
+@dataclass
+class WebhookDeliveryConfig:
+    """Configuration for webhook delivery retry behaviour.
+
+    Attributes:
+        max_retries: Maximum number of retry attempts before marking the
+            delivery as permanently failed.
+        base_delay_secs: Base delay in seconds for exponential backoff.
+        max_delay_secs: Maximum delay cap in seconds.
+    """
+
+    max_retries: int = _MAX_RETRIES
+    base_delay_secs: int = _BASE_DELAY_SECS
+    max_delay_secs: int = _MAX_DELAY_SECS
+
+    def delay_for_attempt(self, attempt: int) -> timedelta:
+        """Return the retry delay for the given attempt index.
+
+        Args:
+            attempt: Zero-based attempt index.
+
+        Returns:
+            Backoff delay as a :class:`datetime.timedelta`.
+        """
+        secs = self.base_delay_secs * (10**attempt)
+        return timedelta(seconds=min(secs, self.max_delay_secs))
+
+    def should_retry(self, attempt: int) -> bool:
+        """Return True if another retry should be attempted.
+
+        Args:
+            attempt: The number of attempts already made.
+
+        Returns:
+            ``True`` if ``attempt < max_retries``.
+        """
+        return attempt < self.max_retries
+
+
+@dataclass
+class WebhookDelivery:
+    """Represents a webhook delivery record.
+
+    Attributes:
+        id: Unique delivery identifier (UUID string).
+        webhook_id: ID of the parent webhook configuration.
+        event_type: The event type that triggered this delivery.
+        payload: The JSON payload to deliver.
+        attempt_count: Number of delivery attempts made so far.
+        state: Current state: ``"pending"``, ``"success"``, or ``"failed"``.
+        next_attempt_at: When the next delivery attempt should be made.
+        created_at: When this delivery record was created.
+        last_response_code: HTTP status code from the last attempt.
+        last_response_body: Response body from the last attempt.
+        completed_at: When the delivery reached a terminal state.
+    """
+
+    id: str
+    webhook_id: str
+    event_type: str
+    payload: dict
+    attempt_count: int = 0
+    state: str = "pending"
+    next_attempt_at: datetime | None = None
+    created_at: datetime | None = None
+    last_response_code: int | None = None
+    last_response_body: str | None = None
+    completed_at: datetime | None = None

git_alternative-0.2.2.dist-info/METADATA

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: git-alternative
+Version: 0.2.2
+Summary: A Python SDK and CLI toolkit for Forge — a keyboard-driven, self-hosted Git collaboration platform
+License: MIT
+License-File: LICENSE
+Keywords: git,forge,collaboration,devtools,cli
+Author: AgentSoft
+Author-email: agentsoft@example.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control
+Requires-Dist: pyyaml (>=6.0,<7.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: tomli (>=2.0,<3.0) ; python_version < "3.11"
+Project-URL: Homepage, https://github.com/agentsoft/git-alternative
+Project-URL: Repository, https://github.com/agentsoft/git-alternative
+Description-Content-Type: text/markdown
+
+# git-alternative
+
+A Python SDK and CLI toolkit for interacting with **Forge** — a keyboard-driven, self-hosted Git collaboration platform. This package provides a clean Python API for managing repositories, issues, pull requests, CI pipelines, and more via the Forge REST API.
+
+## Installation
+
+

git_alternative-0.2.2.dist-info/RECORD

@@ -0,0 +1,26 @@
+git_alternative/__init__.py,sha256=Wbbo8fP0kHvbbbcQ46Wr4_8ILHpT9KXjZ7c1VGmWUBA,1248
+git_alternative/ci.py,sha256=ORFyCX3peykbYPSqXaMzX7D7p6VXl-k1If1ycl2UeF0,4750
+git_alternative/cli.py,sha256=8cGA0L8YDzjlo2fKMohWaXn9MjUlU3WKECJnXSuPFcE,3629
+git_alternative/client.py,sha256=NHqpDC_HurT_1IEK4FJh6TxUHvpOB60BoTg7i-RJw_A,2442
+git_alternative/exceptions.py,sha256=4Dg4spDAMz4pxlLSWY1keyAI7LZhxnv7DAusRoBapjU,1214
+git_alternative/http.py,sha256=vPTNDDxwl6e3_qSBA2_4mSMyC3qL0sfxD6pBHWkHTNU,4153
+git_alternative/managers/__init__.py,sha256=pOYHc-FjvECzsBlG4XPWe9qtak4H7VdCjGEuDnG_7a0,50
+git_alternative/managers/issues.py,sha256=qPQuSqUu8Eg9aKjoTxeuO2zlDbATjDnBl8dfH5a0nNQ,9074
+git_alternative/managers/repos.py,sha256=Sj2Lo7UZPQCRaeTxWFX5qsew4c7aUzmOUgbNRBUwiZY,6913
+git_alternative/models.py,sha256=goIdtwZM7T8qdUV6KCDK0y4q8lHZUdCx_dh3_JtCeTY,5836
+git_alternative/pagination.py,sha256=Zf9PeQvzuEvlP-SVascX5N9i35vZ7RLRFarqdwXFpAo,1336
+git_alternative/resources/__init__.py,sha256=vts06S5CWAN05oQ7yGkjBU5AnQgLqxwvVnfjHxMvDdk,46
+git_alternative/resources/issues.py,sha256=VmwKFOEWj8iCofCQU-Wh6Ekr4beZHdDXCSo9Lo2c48Y,9338
+git_alternative/resources/labels.py,sha256=NtPHU-o1m2chMkXEZxcx3sonAXVt33Ci14P96fP36OY,2547
+git_alternative/resources/pipelines.py,sha256=LwmqQTtnjdgKwRwlQZLHgxvGYdkAqhgFKizx0iezj4Y,3772
+git_alternative/resources/pulls.py,sha256=dXzldj8OovlwTF-oXXR82XyLSWnrDxeoFTiykQ6gong,6752
+git_alternative/resources/repos.py,sha256=wYTQsC3ArUaPL_XBcwxjZ701_ZeFZfZSCYsYeSTVkPo,5995
+git_alternative/resources/ssh_keys.py,sha256=3BJG39p2x3kI5IXC9Ynj-xhXzWTRPqwWEEGMXS8JpJs,1998
+git_alternative/ssh_keys.py,sha256=sfYTZWBs3dr8sV1okuq0XW4VZxLWZL2h6VXwEnvQy3Q,2523
+git_alternative/utils.py,sha256=1kfjTplxTT1JzJIoLvx_oqEteJb0EfUBqSNSz093dd0,2821
+git_alternative/webhooks.py,sha256=BSWjqLZtTkA8a_WsR6jkmpPTS2BnRYluy2LaeS2z1VA,3324
+git_alternative-0.2.2.dist-info/METADATA,sha256=Y54SW-EIMqANRbBBQJAPqgMMJUg7PHCkzrnDpm8eJS8,1573
+git_alternative-0.2.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+git_alternative-0.2.2.dist-info/entry_points.txt,sha256=pafcoPXxfuhP6LL3yzDmX3NM5FniKrC71aP6_AiEkY4,50
+git_alternative-0.2.2.dist-info/licenses/LICENSE,sha256=6Y47RSQ-wXvZrjkkdspmKQ7pAlT-Qq6N6eWBjFqOjoo,1066
+git_alternative-0.2.2.dist-info/RECORD,,

git_alternative-0.2.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

git_alternative-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+forge=git_alternative.cli:main
+

git_alternative-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AgentSoft
+
+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.