Module aiogithubapi.const

Constants for aiogithubapi.

"""Constants for aiogithubapi."""
from __future__ import annotations

from dataclasses import dataclass
from enum import Enum
from logging import Logger, getLogger
from typing import Dict, Literal, TypeVar, Union

from aiohttp.hdrs import ACCEPT, CONTENT_TYPE, USER_AGENT

GenericType = TypeVar("GenericType")

PROJECT_VERSION = "main"
PROJECT_NAME = "aiogithubapi"
PROJECT_URL = "https://github.com/ludeeus/aiogithubapi"

# Deprecated, use `GitHubRequestAcceptHeader` instead
ACCEPT_HEADERS: Dict[str, str] = {
    "base": "application/vnd.github.v3.raw+json",
    "preview": "application/vnd.github.mercy-preview+json",
}

# This is the default user agent,
# but it is adviced to use your own when building out your application
DEFAULT_USER_AGENT = f"aiogithubapi/{PROJECT_VERSION}"

BASE_API_URL = "https://api.github.com"
BASE_GITHUB_URL = "https://github.com"
OAUTH_DEVICE_LOGIN_PATH = "/login/device/code"
OAUTH_ACCESS_TOKEN_PATH = "/login/oauth/access_token"
OAUTH_USER_LOGIN = "https://github.com/login/device"


LOGGER: Logger = getLogger(PROJECT_NAME)


@dataclass
class Repository:
    """Repository."""

    owner: str
    repo: str

    @property
    def full_name(self) -> str:
        """Full name."""
        return f"{self.owner}/{self.repo}"


RepositoryType = Union[str, Dict[Literal["owner", "repo"], str], Repository]


class GitHubRequestAcceptHeader(str, Enum):
    """
    GitHub uses vaious accept headers to enable certain features.

    https://docs.github.com/en/rest/overview/media-types
    """

    RAW_JSON = "application/vnd.github.v3.raw+json"
    BASE_JSON = "application/vnd.github.v3+json"
    PREVIEW_MERCY = "application/vnd.github.mercy-preview+json"

    BASE = RAW_JSON
    PREVIEW = PREVIEW_MERCY


class GitHubClientKwarg(str, Enum):
    """
    kwargs that are used by the client.

    These are used to construct the client and will affect all requests.

    HEADERS:
        Used to set the base headers for all requests.
    BASE_URL:
        Used to ovveride the base url for all requests. Defaults to https://api.github.com .
    TIMEOUT:
        Used to set the timeout for all requests. Defaults to 20
    CLIENT_NAME:
        This name will be used as the user agent header.
    """

    HEADERS = "headers"
    BASE_URL = "base_url"
    TIMEOUT = "timeout"
    CLIENT_NAME = "client_name"


class GitHubRequestKwarg(str, Enum):
    """
    kwargs that are used by requests.

    ETAG:
        Used to set the IF_NONE_MATCH header, if this is set and the content
        is not modified GitHubNotModifiedException will be raised.
    HEADERS:
        Used to set the headers of the request.
    METHOD:
        Used to set the method of the request. Defaults to GET.
    PARAMS:
        Used to set the params of the request.
    QUERY:
        Alias for PARAMS.
    SCOPE:
        Only used for github device login to request scopes for the token
    """

    ETAG = "etag"
    HEADERS = "headers"
    METHOD = "method"
    PARAMS = "params"
    QUERY = "query"
    SCOPE = "scope"


class HttpStatusCode(int, Enum):
    """HTTP Status codes."""

    OK = 200
    CREATED = 201
    ACCEPTED = 202
    NON_AUTHORITATIVE = 203
    NO_CONTENT = 204
    MULTIPLE_CHOICES = 300
    MOVED_PERMANENTLY = 301
    FOUND = 302
    SEE_OTHER = 303
    NOT_MODIFIED = 304
    BAD_REQUEST = 400
    UNAUTHORIZED = 401
    RATELIMIT = 403
    FORBIDDEN = 403
    NOT_FOUND = 404
    TEAPOT = 418
    UNPROCESSABLE_ENTITY = 422
    INTERNAL_SERVER_ERROR = 500
    BAD_GATEWAY = 502
    SERVICE_UNAVAILABLE = 503
    GATEWAY_TIMEOUT = 504


class GitHubIssueLockReason(str, Enum):
    """Reason for issue lock."""

    OFF_TOPIC = "off-topic"
    SPAM = "spam"
    TOO_HEATED = "too heated"
    RESOLVED = "resolved"


class HttpMethod(str, Enum):
    """HTTP Methods."""

    GET = "GET"
    POST = "POST"
    PATCH = "PATCH"
    DELETE = "DELETE"
    PUT = "PUT"


class HttpContentType(str, Enum):
    """HTTP Content Types."""

    BASE_JSON = "application/json"
    BASE_ZIP = "application/zip"
    BASE_GZIP = "application/x-gzip"

    JSON = "application/json;charset=utf-8"
    TEXT_PLAIN = "text/plain;charset=utf-8"
    TEXT_HTML = "text/html;charset=utf-8"


class DeviceFlowError(str, Enum):
    """
    Errors for Device Flow.

    https://docs.github.com/en/developers/apps/authorizing-oauth-apps#error-codes-for-the-device-flow
    """

    ACCESS_DENIED = "access_denied"
    AUTHORIZATION_PENDING = "authorization_pending"
    EXPIRED_TOKEN = "expired_token"
    INCORRECT_CLIENT_CREDENTIALS = "incorrect_client_credentials"
    INCORRECT_DEVICE_CODE = "incorrect_device_code"
    SLOW_DOWN = "slow_down"
    UNSUPPORTED_GRANT_TYPE = "unsupported_grant_type"


HTTP_STATUS_CODE_GOOD_LIST: list[HttpStatusCode] = [
    HttpStatusCode.OK,
    HttpStatusCode.CREATED,
    HttpStatusCode.ACCEPTED,
    HttpStatusCode.NON_AUTHORITATIVE,
]


BASE_API_HEADERS: Dict[str, str] = {
    ACCEPT: GitHubRequestAcceptHeader.BASE.value,
    CONTENT_TYPE: HttpContentType.JSON.value,
    USER_AGENT: DEFAULT_USER_AGENT,
}

Classes

class DeviceFlowError (value, names=None, *, module=None, qualname=None, type=None, start=1)

Errors for Device Flow.

https://docs.github.com/en/developers/apps/authorizing-oauth-apps#error-codes-for-the-device-flow

Expand source code

class DeviceFlowError(str, Enum):
    """
    Errors for Device Flow.

    https://docs.github.com/en/developers/apps/authorizing-oauth-apps#error-codes-for-the-device-flow
    """

    ACCESS_DENIED = "access_denied"
    AUTHORIZATION_PENDING = "authorization_pending"
    EXPIRED_TOKEN = "expired_token"
    INCORRECT_CLIENT_CREDENTIALS = "incorrect_client_credentials"
    INCORRECT_DEVICE_CODE = "incorrect_device_code"
    SLOW_DOWN = "slow_down"
    UNSUPPORTED_GRANT_TYPE = "unsupported_grant_type"

Ancestors

• builtins.str
• enum.Enum

Class variables

var ACCESS_DENIED

var AUTHORIZATION_PENDING

var EXPIRED_TOKEN

var INCORRECT_CLIENT_CREDENTIALS

var INCORRECT_DEVICE_CODE

var SLOW_DOWN

var UNSUPPORTED_GRANT_TYPE

class GitHubClientKwarg (value, names=None, *, module=None, qualname=None, type=None, start=1)

kwargs that are used by the client.

These are used to construct the client and will affect all requests.

Headers

Used to set the base headers for all requests.

Base_Url

Used to ovveride the base url for all requests. Defaults to https://api.github.com .

Timeout

Used to set the timeout for all requests. Defaults to 20

Client_Name

This name will be used as the user agent header.

Expand source code

class GitHubClientKwarg(str, Enum):
    """
    kwargs that are used by the client.

    These are used to construct the client and will affect all requests.

    HEADERS:
        Used to set the base headers for all requests.
    BASE_URL:
        Used to ovveride the base url for all requests. Defaults to https://api.github.com .
    TIMEOUT:
        Used to set the timeout for all requests. Defaults to 20
    CLIENT_NAME:
        This name will be used as the user agent header.
    """

    HEADERS = "headers"
    BASE_URL = "base_url"
    TIMEOUT = "timeout"
    CLIENT_NAME = "client_name"

Ancestors

• builtins.str
• enum.Enum

Class variables

var BASE_URL

var CLIENT_NAME

var HEADERS

var TIMEOUT

class GitHubIssueLockReason (value, names=None, *, module=None, qualname=None, type=None, start=1)

Reason for issue lock.

Expand source code

class GitHubIssueLockReason(str, Enum):
    """Reason for issue lock."""

    OFF_TOPIC = "off-topic"
    SPAM = "spam"
    TOO_HEATED = "too heated"
    RESOLVED = "resolved"

Ancestors

• builtins.str
• enum.Enum

Class variables

var OFF_TOPIC

var RESOLVED

var SPAM

var TOO_HEATED

class GitHubRequestAcceptHeader (value, names=None, *, module=None, qualname=None, type=None, start=1)

GitHub uses vaious accept headers to enable certain features.

https://docs.github.com/en/rest/overview/media-types

Expand source code

class GitHubRequestAcceptHeader(str, Enum):
    """
    GitHub uses vaious accept headers to enable certain features.

    https://docs.github.com/en/rest/overview/media-types
    """

    RAW_JSON = "application/vnd.github.v3.raw+json"
    BASE_JSON = "application/vnd.github.v3+json"
    PREVIEW_MERCY = "application/vnd.github.mercy-preview+json"

    BASE = RAW_JSON
    PREVIEW = PREVIEW_MERCY

Ancestors

• builtins.str
• enum.Enum

Class variables

var BASE

var BASE_JSON

var PREVIEW

var PREVIEW_MERCY

var RAW_JSON

class GitHubRequestKwarg (value, names=None, *, module=None, qualname=None, type=None, start=1)

kwargs that are used by requests.

Etag

Used to set the IF_NONE_MATCH header, if this is set and the content is not modified GitHubNotModifiedException will be raised.

Headers

Used to set the headers of the request.

Method

Used to set the method of the request. Defaults to GET.

Params

Used to set the params of the request.

Query

Alias for PARAMS.

Scope

Only used for github device login to request scopes for the token

Expand source code

class GitHubRequestKwarg(str, Enum):
    """
    kwargs that are used by requests.

    ETAG:
        Used to set the IF_NONE_MATCH header, if this is set and the content
        is not modified GitHubNotModifiedException will be raised.
    HEADERS:
        Used to set the headers of the request.
    METHOD:
        Used to set the method of the request. Defaults to GET.
    PARAMS:
        Used to set the params of the request.
    QUERY:
        Alias for PARAMS.
    SCOPE:
        Only used for github device login to request scopes for the token
    """

    ETAG = "etag"
    HEADERS = "headers"
    METHOD = "method"
    PARAMS = "params"
    QUERY = "query"
    SCOPE = "scope"

Ancestors

• builtins.str
• enum.Enum

Class variables

var ETAG

var HEADERS

var METHOD

var PARAMS

var QUERY

var SCOPE

class HttpContentType (value, names=None, *, module=None, qualname=None, type=None, start=1)

HTTP Content Types.

Expand source code

class HttpContentType(str, Enum):
    """HTTP Content Types."""

    BASE_JSON = "application/json"
    BASE_ZIP = "application/zip"
    BASE_GZIP = "application/x-gzip"

    JSON = "application/json;charset=utf-8"
    TEXT_PLAIN = "text/plain;charset=utf-8"
    TEXT_HTML = "text/html;charset=utf-8"

Ancestors

• builtins.str
• enum.Enum

Class variables

var BASE_GZIP

var BASE_JSON

var BASE_ZIP

var JSON

var TEXT_HTML

var TEXT_PLAIN

class HttpMethod (value, names=None, *, module=None, qualname=None, type=None, start=1)

HTTP Methods.

Expand source code

class HttpMethod(str, Enum):
    """HTTP Methods."""

    GET = "GET"
    POST = "POST"
    PATCH = "PATCH"
    DELETE = "DELETE"
    PUT = "PUT"

Ancestors

• builtins.str
• enum.Enum

Class variables

var DELETE

var GET

var PATCH

var POST

var PUT

class HttpStatusCode (value, names=None, *, module=None, qualname=None, type=None, start=1)

HTTP Status codes.

Expand source code

class HttpStatusCode(int, Enum):
    """HTTP Status codes."""

    OK = 200
    CREATED = 201
    ACCEPTED = 202
    NON_AUTHORITATIVE = 203
    NO_CONTENT = 204
    MULTIPLE_CHOICES = 300
    MOVED_PERMANENTLY = 301
    FOUND = 302
    SEE_OTHER = 303
    NOT_MODIFIED = 304
    BAD_REQUEST = 400
    UNAUTHORIZED = 401
    RATELIMIT = 403
    FORBIDDEN = 403
    NOT_FOUND = 404
    TEAPOT = 418
    UNPROCESSABLE_ENTITY = 422
    INTERNAL_SERVER_ERROR = 500
    BAD_GATEWAY = 502
    SERVICE_UNAVAILABLE = 503
    GATEWAY_TIMEOUT = 504

Ancestors

• builtins.int
• enum.Enum

Class variables

var ACCEPTED

var BAD_GATEWAY

var BAD_REQUEST

var CREATED

var FORBIDDEN

var FOUND

var GATEWAY_TIMEOUT

var INTERNAL_SERVER_ERROR

var MOVED_PERMANENTLY

var MULTIPLE_CHOICES

var NON_AUTHORITATIVE

var NOT_FOUND

var NOT_MODIFIED

var NO_CONTENT

var OK

var RATELIMIT

var SEE_OTHER

var SERVICE_UNAVAILABLE

var TEAPOT

var UNAUTHORIZED

var UNPROCESSABLE_ENTITY

class Repository (owner: str, repo: str)

Repository.

Expand source code

class Repository:
    """Repository."""

    owner: str
    repo: str

    @property
    def full_name(self) -> str:
        """Full name."""
        return f"{self.owner}/{self.repo}"

Class variables

var owner : str

var repo : str

Instance variables

var full_name : str

Full name.

Expand source code

@property
def full_name(self) -> str:
    """Full name."""
    return f"{self.owner}/{self.repo}"