devrev-Python-SDK 1.0.0__py3-none-any.whl

devrev/exceptions.py

@@ -0,0 +1,205 @@
+"""DevRev SDK Exception Hierarchy.
+
+All exceptions inherit from DevRevError, allowing users to catch
+all SDK errors with a single except clause, or be more specific.
+
+Exception Hierarchy:
+    DevRevError (base)
+    ├── AuthenticationError (401)
+    ├── ForbiddenError (403)
+    ├── NotFoundError (404)
+    ├── ValidationError (400)
+    ├── ConflictError (409)
+    ├── RateLimitError (429)
+    ├── ServerError (500)
+    ├── ServiceUnavailableError (503)
+    ├── ConfigurationError
+    ├── TimeoutError
+    └── NetworkError
+"""
+
+from typing import Any
+
+
+class DevRevError(Exception):
+    """Base exception for all DevRev SDK errors.
+
+    All DevRev-specific exceptions inherit from this class,
+    allowing users to catch all SDK errors with a single except clause.
+
+    Attributes:
+        message: Human-readable error description
+        status_code: HTTP status code (if applicable)
+        request_id: DevRev request ID for debugging
+        response_body: Raw API response body
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        response_body: dict[str, Any] | None = None,
+    ) -> None:
+        """Initialize the error.
+
+        Args:
+            message: Human-readable error description
+            status_code: HTTP status code (if applicable)
+            request_id: DevRev request ID for support tickets
+            response_body: Raw API response body for debugging
+        """
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        """Format error message with context."""
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"Status: {self.status_code}")
+        if self.request_id:
+            parts.append(f"Request ID: {self.request_id}")
+        return " | ".join(parts)
+
+
+# HTTP Error Exceptions (mapped to status codes)
+
+
+class AuthenticationError(DevRevError):
+    """401 Unauthorized - Invalid or missing authentication.
+
+    Raised when the API token is invalid, expired, or missing.
+    """
+
+
+class ForbiddenError(DevRevError):
+    """403 Forbidden - Authenticated but not authorized.
+
+    Raised when the user is authenticated but lacks permission
+    to perform the requested action.
+    """
+
+
+class NotFoundError(DevRevError):
+    """404 Not Found - Resource does not exist.
+
+    Raised when the requested resource (account, work item, etc.)
+    cannot be found.
+    """
+
+
+class ValidationError(DevRevError):
+    """400 Bad Request - Invalid request parameters.
+
+    Raised when the request contains invalid data or missing required fields.
+
+    Attributes:
+        field_errors: Mapping of field names to their validation errors
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field_errors: dict[str, list[str]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize validation error.
+
+        Args:
+            message: Human-readable error description
+            field_errors: Mapping of field names to their validation errors
+            **kwargs: Additional arguments passed to DevRevError
+        """
+        super().__init__(message, **kwargs)
+        self.field_errors = field_errors or {}
+
+
+class ConflictError(DevRevError):
+    """409 Conflict - Resource state conflict.
+
+    Raised when the request conflicts with the current state
+    of the resource (e.g., duplicate creation).
+    """
+
+
+class RateLimitError(DevRevError):
+    """429 Too Many Requests - Rate limit exceeded.
+
+    Raised when API rate limits are exceeded.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize rate limit error.
+
+        Args:
+            message: Human-readable error description
+            retry_after: Seconds to wait before retrying
+            **kwargs: Additional arguments passed to DevRevError
+        """
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class ServerError(DevRevError):
+    """500 Internal Server Error - DevRev server error.
+
+    Raised when DevRev's servers encounter an unexpected error.
+    """
+
+
+class ServiceUnavailableError(DevRevError):
+    """503 Service Unavailable - Temporary service outage.
+
+    Raised when the DevRev service is temporarily unavailable.
+    """
+
+
+# SDK-specific errors
+
+
+class ConfigurationError(DevRevError):
+    """SDK configuration error.
+
+    Raised when the SDK is misconfigured (e.g., missing API key).
+    """
+
+
+class TimeoutError(DevRevError):
+    """Request timed out.
+
+    Raised when a request exceeds the configured timeout.
+    """
+
+
+class NetworkError(DevRevError):
+    """Network connectivity error.
+
+    Raised when there's a network-level failure (DNS, connection, etc.).
+    """
+
+
+# Status code to exception mapping for use in HTTP layer
+STATUS_CODE_TO_EXCEPTION: dict[int, type[DevRevError]] = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+    429: RateLimitError,
+    500: ServerError,
+    503: ServiceUnavailableError,
+}

devrev/models/__init__.py

@@ -0,0 +1,499 @@
+"""DevRev SDK Pydantic Models.
+
+This module contains all Pydantic models for the DevRev API.
+"""
+
+from devrev.models.accounts import (
+    Account,
+    AccountsCreateRequest,
+    AccountsCreateResponse,
+    AccountsDeleteRequest,
+    AccountsDeleteResponse,
+    AccountsExportRequest,
+    AccountsExportResponse,
+    AccountsGetRequest,
+    AccountsGetResponse,
+    AccountsListRequest,
+    AccountsListResponse,
+    AccountsMergeRequest,
+    AccountsMergeResponse,
+    AccountSummary,
+    AccountsUpdateRequest,
+    AccountsUpdateResponse,
+    AccountTier,
+)
+from devrev.models.articles import (
+    Article,
+    ArticlesCreateRequest,
+    ArticlesCreateResponse,
+    ArticlesDeleteRequest,
+    ArticlesDeleteResponse,
+    ArticlesGetRequest,
+    ArticlesGetResponse,
+    ArticlesListRequest,
+    ArticlesListResponse,
+    ArticleStatus,
+    ArticleSummary,
+    ArticlesUpdateRequest,
+    ArticlesUpdateResponse,
+)
+from devrev.models.base import (
+    CustomSchemaSpec,
+    DateFilter,
+    DateTimeFilter,
+    DevRevBaseModel,
+    DevRevResponseModel,
+    ObjectSummary,
+    OrgSummary,
+    PaginatedResponse,
+    SetTagWithValue,
+    StageInfo,
+    StageUpdate,
+    TagWithValue,
+    UserSummary,
+)
+from devrev.models.code_changes import (
+    CodeChange,
+    CodeChangesCreateRequest,
+    CodeChangesCreateResponse,
+    CodeChangesDeleteRequest,
+    CodeChangesDeleteResponse,
+    CodeChangesGetRequest,
+    CodeChangesGetResponse,
+    CodeChangesListRequest,
+    CodeChangesListResponse,
+    CodeChangeSummary,
+    CodeChangesUpdateRequest,
+    CodeChangesUpdateResponse,
+)
+from devrev.models.conversations import (
+    Conversation,
+    ConversationsCreateRequest,
+    ConversationsCreateResponse,
+    ConversationsDeleteRequest,
+    ConversationsDeleteResponse,
+    ConversationsExportRequest,
+    ConversationsExportResponse,
+    ConversationsGetRequest,
+    ConversationsGetResponse,
+    ConversationsListRequest,
+    ConversationsListResponse,
+    ConversationSummary,
+    ConversationsUpdateRequest,
+    ConversationsUpdateResponse,
+)
+from devrev.models.dev_users import (
+    DevUser,
+    DevUserExternalIdentity,
+    DevUsersActivateRequest,
+    DevUsersActivateResponse,
+    DevUsersCreateRequest,
+    DevUsersCreateResponse,
+    DevUsersDeactivateRequest,
+    DevUsersDeactivateResponse,
+    DevUsersGetRequest,
+    DevUsersGetResponse,
+    DevUsersIdentitiesLinkRequest,
+    DevUsersIdentitiesLinkResponse,
+    DevUsersIdentitiesUnlinkRequest,
+    DevUsersIdentitiesUnlinkResponse,
+    DevUsersListRequest,
+    DevUsersListResponse,
+    DevUsersMergeRequest,
+    DevUsersMergeResponse,
+    DevUsersSelfRequest,
+    DevUsersSelfResponse,
+    DevUsersSelfUpdateRequest,
+    DevUsersSelfUpdateResponse,
+    DevUserState,
+    DevUserSummary,
+    DevUsersUpdateRequest,
+    DevUsersUpdateResponse,
+)
+from devrev.models.groups import (
+    Group,
+    GroupMember,
+    GroupMembersAddRequest,
+    GroupMembersAddResponse,
+    GroupMembersListRequest,
+    GroupMembersListResponse,
+    GroupMembersRemoveRequest,
+    GroupMembersRemoveResponse,
+    GroupsCreateRequest,
+    GroupsCreateResponse,
+    GroupsGetRequest,
+    GroupsGetResponse,
+    GroupsListRequest,
+    GroupsListResponse,
+    GroupSummary,
+    GroupsUpdateRequest,
+    GroupsUpdateResponse,
+    GroupType,
+)
+from devrev.models.links import (
+    Link,
+    LinksCreateRequest,
+    LinksCreateResponse,
+    LinksDeleteRequest,
+    LinksDeleteResponse,
+    LinksGetRequest,
+    LinksGetResponse,
+    LinksListRequest,
+    LinksListResponse,
+    LinkSummary,
+    LinkType,
+)
+from devrev.models.parts import (
+    Part,
+    PartsCreateRequest,
+    PartsCreateResponse,
+    PartsDeleteRequest,
+    PartsDeleteResponse,
+    PartsGetRequest,
+    PartsGetResponse,
+    PartsListRequest,
+    PartsListResponse,
+    PartSummary,
+    PartsUpdateRequest,
+    PartsUpdateResponse,
+    PartType,
+)
+from devrev.models.rev_users import (
+    RevUser,
+    RevUsersCreateRequest,
+    RevUsersCreateResponse,
+    RevUsersDeleteRequest,
+    RevUsersDeleteResponse,
+    RevUsersGetRequest,
+    RevUsersGetResponse,
+    RevUsersListRequest,
+    RevUsersListResponse,
+    RevUsersMergeRequest,
+    RevUsersMergeResponse,
+    RevUserState,
+    RevUserSummary,
+    RevUsersUpdateRequest,
+    RevUsersUpdateResponse,
+)
+from devrev.models.slas import (
+    Sla,
+    SlasCreateRequest,
+    SlasCreateResponse,
+    SlasGetRequest,
+    SlasGetResponse,
+    SlasListRequest,
+    SlasListResponse,
+    SlaStatus,
+    SlasTransitionRequest,
+    SlasTransitionResponse,
+    SlaSummary,
+    SlasUpdateRequest,
+    SlasUpdateResponse,
+    SlaTrackerStatus,
+)
+from devrev.models.tags import (
+    Tag,
+    TagsCreateRequest,
+    TagsCreateResponse,
+    TagsDeleteRequest,
+    TagsDeleteResponse,
+    TagsGetRequest,
+    TagsGetResponse,
+    TagsListRequest,
+    TagsListResponse,
+    TagSummary,
+    TagsUpdateRequest,
+    TagsUpdateResponse,
+)
+from devrev.models.timeline_entries import (
+    TimelineEntriesCreateRequest,
+    TimelineEntriesCreateResponse,
+    TimelineEntriesDeleteRequest,
+    TimelineEntriesDeleteResponse,
+    TimelineEntriesGetRequest,
+    TimelineEntriesGetResponse,
+    TimelineEntriesListRequest,
+    TimelineEntriesListResponse,
+    TimelineEntriesUpdateRequest,
+    TimelineEntriesUpdateResponse,
+    TimelineEntry,
+    TimelineEntryType,
+)
+from devrev.models.webhooks import (
+    Webhook,
+    WebhooksCreateRequest,
+    WebhooksCreateResponse,
+    WebhooksDeleteRequest,
+    WebhooksDeleteResponse,
+    WebhooksGetRequest,
+    WebhooksGetResponse,
+    WebhooksListRequest,
+    WebhooksListResponse,
+    WebhookStatus,
+    WebhookSummary,
+    WebhooksUpdateRequest,
+    WebhooksUpdateResponse,
+)
+from devrev.models.works import (
+    IssuePriority,
+    TicketChannels,
+    TicketSeverity,
+    Work,
+    WorksCountRequest,
+    WorksCountResponse,
+    WorksCreateRequest,
+    WorksCreateResponse,
+    WorksDeleteRequest,
+    WorksDeleteResponse,
+    WorksExportRequest,
+    WorksExportResponse,
+    WorksGetRequest,
+    WorksGetResponse,
+    WorksListRequest,
+    WorksListResponse,
+    WorkSummary,
+    WorksUpdateRequest,
+    WorksUpdateResponse,
+    WorkType,
+)
+
+__all__ = [
+    # Base models
+    "DevRevBaseModel",
+    "DevRevResponseModel",
+    "PaginatedResponse",
+    "DateFilter",
+    "DateTimeFilter",
+    "CustomSchemaSpec",
+    "UserSummary",
+    "ObjectSummary",
+    "OrgSummary",
+    "TagWithValue",
+    "SetTagWithValue",
+    "StageInfo",
+    "StageUpdate",
+    # Accounts
+    "Account",
+    "AccountSummary",
+    "AccountTier",
+    "AccountsCreateRequest",
+    "AccountsCreateResponse",
+    "AccountsGetRequest",
+    "AccountsGetResponse",
+    "AccountsListRequest",
+    "AccountsListResponse",
+    "AccountsUpdateRequest",
+    "AccountsUpdateResponse",
+    "AccountsDeleteRequest",
+    "AccountsDeleteResponse",
+    "AccountsMergeRequest",
+    "AccountsMergeResponse",
+    "AccountsExportRequest",
+    "AccountsExportResponse",
+    # Articles
+    "Article",
+    "ArticleSummary",
+    "ArticleStatus",
+    "ArticlesCreateRequest",
+    "ArticlesCreateResponse",
+    "ArticlesGetRequest",
+    "ArticlesGetResponse",
+    "ArticlesListRequest",
+    "ArticlesListResponse",
+    "ArticlesUpdateRequest",
+    "ArticlesUpdateResponse",
+    "ArticlesDeleteRequest",
+    "ArticlesDeleteResponse",
+    # Code Changes
+    "CodeChange",
+    "CodeChangeSummary",
+    "CodeChangesCreateRequest",
+    "CodeChangesCreateResponse",
+    "CodeChangesGetRequest",
+    "CodeChangesGetResponse",
+    "CodeChangesListRequest",
+    "CodeChangesListResponse",
+    "CodeChangesUpdateRequest",
+    "CodeChangesUpdateResponse",
+    "CodeChangesDeleteRequest",
+    "CodeChangesDeleteResponse",
+    # Conversations
+    "Conversation",
+    "ConversationSummary",
+    "ConversationsCreateRequest",
+    "ConversationsCreateResponse",
+    "ConversationsGetRequest",
+    "ConversationsGetResponse",
+    "ConversationsListRequest",
+    "ConversationsListResponse",
+    "ConversationsUpdateRequest",
+    "ConversationsUpdateResponse",
+    "ConversationsDeleteRequest",
+    "ConversationsDeleteResponse",
+    "ConversationsExportRequest",
+    "ConversationsExportResponse",
+    # Dev Users
+    "DevUser",
+    "DevUserSummary",
+    "DevUserState",
+    "DevUserExternalIdentity",
+    "DevUsersCreateRequest",
+    "DevUsersCreateResponse",
+    "DevUsersGetRequest",
+    "DevUsersGetResponse",
+    "DevUsersListRequest",
+    "DevUsersListResponse",
+    "DevUsersUpdateRequest",
+    "DevUsersUpdateResponse",
+    "DevUsersActivateRequest",
+    "DevUsersActivateResponse",
+    "DevUsersDeactivateRequest",
+    "DevUsersDeactivateResponse",
+    "DevUsersIdentitiesLinkRequest",
+    "DevUsersIdentitiesLinkResponse",
+    "DevUsersIdentitiesUnlinkRequest",
+    "DevUsersIdentitiesUnlinkResponse",
+    "DevUsersMergeRequest",
+    "DevUsersMergeResponse",
+    "DevUsersSelfRequest",
+    "DevUsersSelfResponse",
+    "DevUsersSelfUpdateRequest",
+    "DevUsersSelfUpdateResponse",
+    # Groups
+    "Group",
+    "GroupSummary",
+    "GroupType",
+    "GroupMember",
+    "GroupsCreateRequest",
+    "GroupsCreateResponse",
+    "GroupsGetRequest",
+    "GroupsGetResponse",
+    "GroupsListRequest",
+    "GroupsListResponse",
+    "GroupsUpdateRequest",
+    "GroupsUpdateResponse",
+    "GroupMembersAddRequest",
+    "GroupMembersAddResponse",
+    "GroupMembersRemoveRequest",
+    "GroupMembersRemoveResponse",
+    "GroupMembersListRequest",
+    "GroupMembersListResponse",
+    # Links
+    "Link",
+    "LinkSummary",
+    "LinkType",
+    "LinksCreateRequest",
+    "LinksCreateResponse",
+    "LinksGetRequest",
+    "LinksGetResponse",
+    "LinksListRequest",
+    "LinksListResponse",
+    "LinksDeleteRequest",
+    "LinksDeleteResponse",
+    # Parts
+    "Part",
+    "PartSummary",
+    "PartType",
+    "PartsCreateRequest",
+    "PartsCreateResponse",
+    "PartsGetRequest",
+    "PartsGetResponse",
+    "PartsListRequest",
+    "PartsListResponse",
+    "PartsUpdateRequest",
+    "PartsUpdateResponse",
+    "PartsDeleteRequest",
+    "PartsDeleteResponse",
+    # Rev Users
+    "RevUser",
+    "RevUserSummary",
+    "RevUserState",
+    "RevUsersCreateRequest",
+    "RevUsersCreateResponse",
+    "RevUsersGetRequest",
+    "RevUsersGetResponse",
+    "RevUsersListRequest",
+    "RevUsersListResponse",
+    "RevUsersUpdateRequest",
+    "RevUsersUpdateResponse",
+    "RevUsersDeleteRequest",
+    "RevUsersDeleteResponse",
+    "RevUsersMergeRequest",
+    "RevUsersMergeResponse",
+    # SLAs
+    "Sla",
+    "SlaSummary",
+    "SlaStatus",
+    "SlaTrackerStatus",
+    "SlasCreateRequest",
+    "SlasCreateResponse",
+    "SlasGetRequest",
+    "SlasGetResponse",
+    "SlasListRequest",
+    "SlasListResponse",
+    "SlasUpdateRequest",
+    "SlasUpdateResponse",
+    "SlasTransitionRequest",
+    "SlasTransitionResponse",
+    # Tags
+    "Tag",
+    "TagSummary",
+    "TagsCreateRequest",
+    "TagsCreateResponse",
+    "TagsGetRequest",
+    "TagsGetResponse",
+    "TagsListRequest",
+    "TagsListResponse",
+    "TagsUpdateRequest",
+    "TagsUpdateResponse",
+    "TagsDeleteRequest",
+    "TagsDeleteResponse",
+    # Timeline Entries
+    "TimelineEntry",
+    "TimelineEntryType",
+    "TimelineEntriesCreateRequest",
+    "TimelineEntriesCreateResponse",
+    "TimelineEntriesGetRequest",
+    "TimelineEntriesGetResponse",
+    "TimelineEntriesListRequest",
+    "TimelineEntriesListResponse",
+    "TimelineEntriesUpdateRequest",
+    "TimelineEntriesUpdateResponse",
+    "TimelineEntriesDeleteRequest",
+    "TimelineEntriesDeleteResponse",
+    # Webhooks
+    "Webhook",
+    "WebhookSummary",
+    "WebhookStatus",
+    "WebhooksCreateRequest",
+    "WebhooksCreateResponse",
+    "WebhooksGetRequest",
+    "WebhooksGetResponse",
+    "WebhooksListRequest",
+    "WebhooksListResponse",
+    "WebhooksUpdateRequest",
+    "WebhooksUpdateResponse",
+    "WebhooksDeleteRequest",
+    "WebhooksDeleteResponse",
+    # Works
+    "Work",
+    "WorkSummary",
+    "WorkType",
+    "IssuePriority",
+    "TicketSeverity",
+    "TicketChannels",
+    "WorksCreateRequest",
+    "WorksCreateResponse",
+    "WorksGetRequest",
+    "WorksGetResponse",
+    "WorksListRequest",
+    "WorksListResponse",
+    "WorksUpdateRequest",
+    "WorksUpdateResponse",
+    "WorksDeleteRequest",
+    "WorksDeleteResponse",
+    "WorksExportRequest",
+    "WorksExportResponse",
+    "WorksCountRequest",
+    "WorksCountResponse",
+]