ynab-cli 0.3.0__py3-none-any.whl

ynab_cli/adapters/ynab/client.py

@@ -0,0 +1,268 @@
+import ssl
+from typing import Any
+
+import httpx
+from attrs import define, evolve, field
+
+
+@define
+class Client:
+    """A class for keeping track of data related to the API
+
+    The following are accepted as keyword arguments and will be used to construct httpx Clients internally:
+
+        ``base_url``: The base URL for the API, all requests are made to a relative path to this URL
+
+        ``cookies``: A dictionary of cookies to be sent with every request
+
+        ``headers``: A dictionary of headers to be sent with every request
+
+        ``timeout``: The maximum amount of a time a request can take. API functions will raise
+        httpx.TimeoutException if this is exceeded.
+
+        ``verify_ssl``: Whether or not to verify the SSL certificate of the API server. This should be True in production,
+        but can be set to False for testing purposes.
+
+        ``follow_redirects``: Whether or not to follow redirects. Default value is False.
+
+        ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
+
+
+    Attributes:
+        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatusError if the API returns a
+            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
+            argument to the constructor.
+    """
+
+    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
+    _base_url: str = field(alias="base_url")
+    _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
+    _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
+    _timeout: httpx.Timeout | None = field(default=None, kw_only=True, alias="timeout")
+    _verify_ssl: str | bool | ssl.SSLContext = field(default=True, kw_only=True, alias="verify_ssl")
+    _follow_redirects: bool = field(default=False, kw_only=True, alias="follow_redirects")
+    _httpx_args: dict[str, Any] = field(factory=dict, kw_only=True, alias="httpx_args")
+    _client: httpx.Client | None = field(default=None, init=False)
+    _async_client: httpx.AsyncClient | None = field(default=None, init=False)
+
+    def with_headers(self, headers: dict[str, str]) -> "Client":
+        """Get a new client matching this one with additional headers"""
+        if self._client is not None:
+            self._client.headers.update(headers)
+        if self._async_client is not None:
+            self._async_client.headers.update(headers)
+        return evolve(self, headers={**self._headers, **headers})
+
+    def with_cookies(self, cookies: dict[str, str]) -> "Client":
+        """Get a new client matching this one with additional cookies"""
+        if self._client is not None:
+            self._client.cookies.update(cookies)
+        if self._async_client is not None:
+            self._async_client.cookies.update(cookies)
+        return evolve(self, cookies={**self._cookies, **cookies})
+
+    def with_timeout(self, timeout: httpx.Timeout) -> "Client":
+        """Get a new client matching this one with a new timeout (in seconds)"""
+        if self._client is not None:
+            self._client.timeout = timeout
+        if self._async_client is not None:
+            self._async_client.timeout = timeout
+        return evolve(self, timeout=timeout)
+
+    def set_httpx_client(self, client: httpx.Client) -> "Client":
+        """Manually set the underlying httpx.Client
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._client = client
+        return self
+
+    def get_httpx_client(self) -> httpx.Client:
+        """Get the underlying httpx.Client, constructing a new one if not previously set"""
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._client
+
+    def __enter__(self) -> "Client":
+        """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
+        self.get_httpx_client().__enter__()
+        return self
+
+    def __exit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for internal httpx.Client (see httpx docs)"""
+        self.get_httpx_client().__exit__(*args, **kwargs)
+
+    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> "Client":
+        """Manually the underlying httpx.AsyncClient
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._async_client = async_client
+        return self
+
+    def get_async_httpx_client(self) -> httpx.AsyncClient:
+        """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
+        if self._async_client is None:
+            self._async_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._async_client
+
+    async def __aenter__(self) -> "Client":
+        """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
+        await self.get_async_httpx_client().__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
+        await self.get_async_httpx_client().__aexit__(*args, **kwargs)
+
+
+@define
+class AuthenticatedClient:
+    """A Client which has been authenticated for use on secured endpoints
+
+    The following are accepted as keyword arguments and will be used to construct httpx Clients internally:
+
+        ``base_url``: The base URL for the API, all requests are made to a relative path to this URL
+
+        ``cookies``: A dictionary of cookies to be sent with every request
+
+        ``headers``: A dictionary of headers to be sent with every request
+
+        ``timeout``: The maximum amount of a time a request can take. API functions will raise
+        httpx.TimeoutException if this is exceeded.
+
+        ``verify_ssl``: Whether or not to verify the SSL certificate of the API server. This should be True in production,
+        but can be set to False for testing purposes.
+
+        ``follow_redirects``: Whether or not to follow redirects. Default value is False.
+
+        ``httpx_args``: A dictionary of additional arguments to be passed to the ``httpx.Client`` and ``httpx.AsyncClient`` constructor.
+
+
+    Attributes:
+        raise_on_unexpected_status: Whether or not to raise an errors.UnexpectedStatusError if the API returns a
+            status code that was not documented in the source OpenAPI document. Can also be provided as a keyword
+            argument to the constructor.
+        token: The token to use for authentication
+        prefix: The prefix to use for the Authorization header
+        auth_header_name: The name of the Authorization header
+    """
+
+    raise_on_unexpected_status: bool = field(default=False, kw_only=True)
+    _base_url: str = field(alias="base_url")
+    _cookies: dict[str, str] = field(factory=dict, kw_only=True, alias="cookies")
+    _headers: dict[str, str] = field(factory=dict, kw_only=True, alias="headers")
+    _timeout: httpx.Timeout | None = field(default=None, kw_only=True, alias="timeout")
+    _verify_ssl: str | bool | ssl.SSLContext = field(default=True, kw_only=True, alias="verify_ssl")
+    _follow_redirects: bool = field(default=False, kw_only=True, alias="follow_redirects")
+    _httpx_args: dict[str, Any] = field(factory=dict, kw_only=True, alias="httpx_args")
+    _client: httpx.Client | None = field(default=None, init=False)
+    _async_client: httpx.AsyncClient | None = field(default=None, init=False)
+
+    token: str
+    prefix: str = "Bearer"
+    auth_header_name: str = "Authorization"
+
+    def with_headers(self, headers: dict[str, str]) -> "AuthenticatedClient":
+        """Get a new client matching this one with additional headers"""
+        if self._client is not None:
+            self._client.headers.update(headers)
+        if self._async_client is not None:
+            self._async_client.headers.update(headers)
+        return evolve(self, headers={**self._headers, **headers})
+
+    def with_cookies(self, cookies: dict[str, str]) -> "AuthenticatedClient":
+        """Get a new client matching this one with additional cookies"""
+        if self._client is not None:
+            self._client.cookies.update(cookies)
+        if self._async_client is not None:
+            self._async_client.cookies.update(cookies)
+        return evolve(self, cookies={**self._cookies, **cookies})
+
+    def with_timeout(self, timeout: httpx.Timeout) -> "AuthenticatedClient":
+        """Get a new client matching this one with a new timeout (in seconds)"""
+        if self._client is not None:
+            self._client.timeout = timeout
+        if self._async_client is not None:
+            self._async_client.timeout = timeout
+        return evolve(self, timeout=timeout)
+
+    def set_httpx_client(self, client: httpx.Client) -> "AuthenticatedClient":
+        """Manually set the underlying httpx.Client
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._client = client
+        return self
+
+    def get_httpx_client(self) -> httpx.Client:
+        """Get the underlying httpx.Client, constructing a new one if not previously set"""
+        if self._client is None:
+            self._headers[self.auth_header_name] = f"{self.prefix} {self.token}" if self.prefix else self.token
+            self._client = httpx.Client(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._client
+
+    def __enter__(self) -> "AuthenticatedClient":
+        """Enter a context manager for self.client—you cannot enter twice (see httpx docs)"""
+        self.get_httpx_client().__enter__()
+        return self
+
+    def __exit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for internal httpx.Client (see httpx docs)"""
+        self.get_httpx_client().__exit__(*args, **kwargs)
+
+    def set_async_httpx_client(self, async_client: httpx.AsyncClient) -> "AuthenticatedClient":
+        """Manually the underlying httpx.AsyncClient
+
+        **NOTE**: This will override any other settings on the client, including cookies, headers, and timeout.
+        """
+        self._async_client = async_client
+        return self
+
+    def get_async_httpx_client(self) -> httpx.AsyncClient:
+        """Get the underlying httpx.AsyncClient, constructing a new one if not previously set"""
+        if self._async_client is None:
+            self._headers[self.auth_header_name] = f"{self.prefix} {self.token}" if self.prefix else self.token
+            self._async_client = httpx.AsyncClient(
+                base_url=self._base_url,
+                cookies=self._cookies,
+                headers=self._headers,
+                timeout=self._timeout,
+                verify=self._verify_ssl,
+                follow_redirects=self._follow_redirects,
+                **self._httpx_args,
+            )
+        return self._async_client
+
+    async def __aenter__(self) -> "AuthenticatedClient":
+        """Enter a context manager for underlying httpx.AsyncClient—you cannot enter twice (see httpx docs)"""
+        await self.get_async_httpx_client().__aenter__()
+        return self
+
+    async def __aexit__(self, *args: Any, **kwargs: Any) -> None:
+        """Exit a context manager for underlying httpx.AsyncClient (see httpx docs)"""
+        await self.get_async_httpx_client().__aexit__(*args, **kwargs)

ynab_cli/adapters/ynab/errors.py

@@ -0,0 +1,16 @@
+"""Contains shared errors types that can be raised from API functions"""
+
+
+class UnexpectedStatusError(Exception):
+    """Raised by api functions when the response status an undocumented status and Client.raise_on_unexpected_status is True"""
+
+    def __init__(self, status_code: int, content: bytes):
+        self.status_code = status_code
+        self.content = content
+
+        super().__init__(
+            f"Unexpected status code: {status_code}\n\nResponse content:\n{content.decode(errors='ignore')}"
+        )
+
+
+__all__ = ["UnexpectedStatusError"]

ynab_cli/adapters/ynab/models/__init__.py

@@ -0,0 +1,229 @@
+"""Contains all the data models used in inputs/outputs"""
+
+from .account import Account
+from .account_response import AccountResponse
+from .account_response_data import AccountResponseData
+from .account_type import AccountType
+from .accounts_response import AccountsResponse
+from .accounts_response_data import AccountsResponseData
+from .budget_detail import BudgetDetail
+from .budget_detail_response import BudgetDetailResponse
+from .budget_detail_response_data import BudgetDetailResponseData
+from .budget_settings import BudgetSettings
+from .budget_settings_response import BudgetSettingsResponse
+from .budget_settings_response_data import BudgetSettingsResponseData
+from .budget_summary import BudgetSummary
+from .budget_summary_response import BudgetSummaryResponse
+from .budget_summary_response_data import BudgetSummaryResponseData
+from .bulk_response import BulkResponse
+from .bulk_response_data import BulkResponseData
+from .bulk_response_data_bulk import BulkResponseDataBulk
+from .bulk_transactions import BulkTransactions
+from .categories_response import CategoriesResponse
+from .categories_response_data import CategoriesResponseData
+from .category import Category
+from .category_goal_type_type_1 import CategoryGoalTypeType1
+from .category_goal_type_type_2_type_1 import CategoryGoalTypeType2Type1
+from .category_goal_type_type_3_type_1 import CategoryGoalTypeType3Type1
+from .category_group import CategoryGroup
+from .category_group_with_categories import CategoryGroupWithCategories
+from .category_response import CategoryResponse
+from .category_response_data import CategoryResponseData
+from .currency_format_type_0 import CurrencyFormatType0
+from .date_format_type_0 import DateFormatType0
+from .error_detail import ErrorDetail
+from .error_response import ErrorResponse
+from .existing_transaction import ExistingTransaction
+from .get_transactions_by_account_type import GetTransactionsByAccountType
+from .get_transactions_by_category_type import GetTransactionsByCategoryType
+from .get_transactions_by_month_type import GetTransactionsByMonthType
+from .get_transactions_by_payee_type import GetTransactionsByPayeeType
+from .get_transactions_type import GetTransactionsType
+from .hybrid_transaction import HybridTransaction
+from .hybrid_transaction_type import HybridTransactionType
+from .hybrid_transactions_response import HybridTransactionsResponse
+from .hybrid_transactions_response_data import HybridTransactionsResponseData
+from .loan_account_periodic_value_type_0 import LoanAccountPeriodicValueType0
+from .month_detail import MonthDetail
+from .month_detail_response import MonthDetailResponse
+from .month_detail_response_data import MonthDetailResponseData
+from .month_summaries_response import MonthSummariesResponse
+from .month_summaries_response_data import MonthSummariesResponseData
+from .month_summary import MonthSummary
+from .new_transaction import NewTransaction
+from .patch_category_wrapper import PatchCategoryWrapper
+from .patch_month_category_wrapper import PatchMonthCategoryWrapper
+from .patch_payee_wrapper import PatchPayeeWrapper
+from .patch_transactions_wrapper import PatchTransactionsWrapper
+from .payee import Payee
+from .payee_location import PayeeLocation
+from .payee_location_response import PayeeLocationResponse
+from .payee_location_response_data import PayeeLocationResponseData
+from .payee_locations_response import PayeeLocationsResponse
+from .payee_locations_response_data import PayeeLocationsResponseData
+from .payee_response import PayeeResponse
+from .payee_response_data import PayeeResponseData
+from .payees_response import PayeesResponse
+from .payees_response_data import PayeesResponseData
+from .post_account_wrapper import PostAccountWrapper
+from .post_scheduled_transaction_wrapper import PostScheduledTransactionWrapper
+from .post_transactions_wrapper import PostTransactionsWrapper
+from .put_scheduled_transaction_wrapper import PutScheduledTransactionWrapper
+from .put_transaction_wrapper import PutTransactionWrapper
+from .save_account import SaveAccount
+from .save_category import SaveCategory
+from .save_category_response import SaveCategoryResponse
+from .save_category_response_data import SaveCategoryResponseData
+from .save_month_category import SaveMonthCategory
+from .save_payee import SavePayee
+from .save_payee_response import SavePayeeResponse
+from .save_payee_response_data import SavePayeeResponseData
+from .save_scheduled_transaction import SaveScheduledTransaction
+from .save_sub_transaction import SaveSubTransaction
+from .save_transaction_with_id_or_import_id import SaveTransactionWithIdOrImportId
+from .save_transaction_with_optional_fields import SaveTransactionWithOptionalFields
+from .save_transactions_response import SaveTransactionsResponse
+from .save_transactions_response_data import SaveTransactionsResponseData
+from .scheduled_sub_transaction import ScheduledSubTransaction
+from .scheduled_transaction_detail import ScheduledTransactionDetail
+from .scheduled_transaction_frequency import ScheduledTransactionFrequency
+from .scheduled_transaction_response import ScheduledTransactionResponse
+from .scheduled_transaction_response_data import ScheduledTransactionResponseData
+from .scheduled_transaction_summary import ScheduledTransactionSummary
+from .scheduled_transaction_summary_frequency import ScheduledTransactionSummaryFrequency
+from .scheduled_transactions_response import ScheduledTransactionsResponse
+from .scheduled_transactions_response_data import ScheduledTransactionsResponseData
+from .sub_transaction import SubTransaction
+from .transaction_cleared_status import TransactionClearedStatus
+from .transaction_detail import TransactionDetail
+from .transaction_flag_color_type_1 import TransactionFlagColorType1
+from .transaction_flag_color_type_2_type_1 import TransactionFlagColorType2Type1
+from .transaction_flag_color_type_3_type_1 import TransactionFlagColorType3Type1
+from .transaction_response import TransactionResponse
+from .transaction_response_data import TransactionResponseData
+from .transaction_summary import TransactionSummary
+from .transaction_summary_debt_transaction_type_type_1 import TransactionSummaryDebtTransactionTypeType1
+from .transaction_summary_debt_transaction_type_type_2_type_1 import TransactionSummaryDebtTransactionTypeType2Type1
+from .transaction_summary_debt_transaction_type_type_3_type_1 import TransactionSummaryDebtTransactionTypeType3Type1
+from .transactions_import_response import TransactionsImportResponse
+from .transactions_import_response_data import TransactionsImportResponseData
+from .transactions_response import TransactionsResponse
+from .transactions_response_data import TransactionsResponseData
+from .user import User
+from .user_response import UserResponse
+from .user_response_data import UserResponseData
+
+__all__ = (
+    "Account",
+    "AccountResponse",
+    "AccountResponseData",
+    "AccountType",
+    "AccountsResponse",
+    "AccountsResponseData",
+    "BudgetDetail",
+    "BudgetDetailResponse",
+    "BudgetDetailResponseData",
+    "BudgetSettings",
+    "BudgetSettingsResponse",
+    "BudgetSettingsResponseData",
+    "BudgetSummary",
+    "BudgetSummaryResponse",
+    "BudgetSummaryResponseData",
+    "BulkResponse",
+    "BulkResponseData",
+    "BulkResponseDataBulk",
+    "BulkTransactions",
+    "CategoriesResponse",
+    "CategoriesResponseData",
+    "Category",
+    "CategoryGoalTypeType1",
+    "CategoryGoalTypeType2Type1",
+    "CategoryGoalTypeType3Type1",
+    "CategoryGroup",
+    "CategoryGroupWithCategories",
+    "CategoryResponse",
+    "CategoryResponseData",
+    "CurrencyFormatType0",
+    "DateFormatType0",
+    "ErrorDetail",
+    "ErrorResponse",
+    "ExistingTransaction",
+    "GetTransactionsByAccountType",
+    "GetTransactionsByCategoryType",
+    "GetTransactionsByMonthType",
+    "GetTransactionsByPayeeType",
+    "GetTransactionsType",
+    "HybridTransaction",
+    "HybridTransactionType",
+    "HybridTransactionsResponse",
+    "HybridTransactionsResponseData",
+    "LoanAccountPeriodicValueType0",
+    "MonthDetail",
+    "MonthDetailResponse",
+    "MonthDetailResponseData",
+    "MonthSummariesResponse",
+    "MonthSummariesResponseData",
+    "MonthSummary",
+    "NewTransaction",
+    "PatchCategoryWrapper",
+    "PatchMonthCategoryWrapper",
+    "PatchPayeeWrapper",
+    "PatchTransactionsWrapper",
+    "Payee",
+    "PayeeLocation",
+    "PayeeLocationResponse",
+    "PayeeLocationResponseData",
+    "PayeeLocationsResponse",
+    "PayeeLocationsResponseData",
+    "PayeeResponse",
+    "PayeeResponseData",
+    "PayeesResponse",
+    "PayeesResponseData",
+    "PostAccountWrapper",
+    "PostScheduledTransactionWrapper",
+    "PostTransactionsWrapper",
+    "PutScheduledTransactionWrapper",
+    "PutTransactionWrapper",
+    "SaveAccount",
+    "SaveCategory",
+    "SaveCategoryResponse",
+    "SaveCategoryResponseData",
+    "SaveMonthCategory",
+    "SavePayee",
+    "SavePayeeResponse",
+    "SavePayeeResponseData",
+    "SaveScheduledTransaction",
+    "SaveSubTransaction",
+    "SaveTransactionWithIdOrImportId",
+    "SaveTransactionWithOptionalFields",
+    "SaveTransactionsResponse",
+    "SaveTransactionsResponseData",
+    "ScheduledSubTransaction",
+    "ScheduledTransactionDetail",
+    "ScheduledTransactionFrequency",
+    "ScheduledTransactionResponse",
+    "ScheduledTransactionResponseData",
+    "ScheduledTransactionSummary",
+    "ScheduledTransactionSummaryFrequency",
+    "ScheduledTransactionsResponse",
+    "ScheduledTransactionsResponseData",
+    "SubTransaction",
+    "TransactionClearedStatus",
+    "TransactionDetail",
+    "TransactionFlagColorType1",
+    "TransactionFlagColorType2Type1",
+    "TransactionFlagColorType3Type1",
+    "TransactionResponse",
+    "TransactionResponseData",
+    "TransactionSummary",
+    "TransactionSummaryDebtTransactionTypeType1",
+    "TransactionSummaryDebtTransactionTypeType2Type1",
+    "TransactionSummaryDebtTransactionTypeType3Type1",
+    "TransactionsImportResponse",
+    "TransactionsImportResponseData",
+    "TransactionsResponse",
+    "TransactionsResponseData",
+    "User",
+    "UserResponse",
+    "UserResponseData",
+)