csobpg 0.0.1__tar.gz

csobpg-0.0.1/LICENSE

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

csobpg-0.0.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.1
+Name: csobpg
+Version: 0.0.1
+Summary: Library for communication with ČSOB API
+Home-page: https://github.com/litteratum/csobpg
+License: MIT
+Author: Andrii Nechaiev
+Author-email: andrewnech@gmail.com
+Requires-Python: >=3.7,<3.12
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Provides-Extra: requests-client
+Requires-Dist: pycryptodome (>=3.17,<4.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0) ; extra == "requests-client"
+Project-URL: Repository, https://github.com/litteratum/csobpg
+Description-Content-Type: text/markdown
+
+# CSOB client
+Python library for communicating with ČSOB (<https://platbakartou.csob.cz/>) payment gateway API. The API is described here: <https://github.com/csob/paymentgateway>.
+
+The library currently implements API v.1.9 only.
+
+
+## Installation
+```bash
+pip install csobpg
+```
+
+## Basic usage
+### API client initialization
+```python
+from csobpg.v19 import APIClient
+
+client = APIClient("merchantId", "merch_private.key", "csob.pub", base_url=..., http_client=...)
+```
+
+### HTTP client
+The library uses the `HTTPClient` interface for making HTTP requests.
+
+It provides the following HTTP clients:
+  * `csobpg.http.urllib_client.UrllibHTTPClient` - the default one using the `urllib` under the hood
+  * `csobpg.http.requests_client.RequestsHTTPClient` - an extra HTTP client using the `requests` under the hood. The library must be installed with the `requests-client` extra to be able to use this client
+
+It is also possible to implement the `HTTPClient` interface to use your custom HTTP client.
+
+The HTTP client is set as the following:
+
+```python
+from csobpg.v19 import APIClient
+from csobpg.http import HTTPClient
+
+class CustomHTTPClient(HTTPClient):
+    ...
+
+client = APIClient(..., http_client=CustomHTTPClient(...))
+```
+
+### Payment initialization
+```python
+from csobpg.v19 import Cart, CartItem
+
+response = client.init_payment(
+    order_no="2233823251",
+    total_amount=100,
+    return_url="http://127.0.0.1:5000/",
+    cart=Cart([CartItem("Apples", 1, 100)]),
+    merchant_data=b"Hello, World!",
+)
+```
+
+### Get payment URL
+```python
+url = client.get_payment_process_url(pay_id)
+```
+
+### Process the gateway redirect
+```python
+response = client.process_gateway_return(data_dict)
+```
+
+### Get payment status
+```python
+response = client.get_payment_status(pay_id)
+```
+
+### Reverse payment
+```python
+response = client.reverse_payment(pay_id)
+```
+
+### Refund payment
+```python
+response = client.refund_payment(pay_id, amount=100)
+```
+
+### Exceptions handling
+```python
+from csobpg.v19.errors import APIError, APIClientError
+from csobpg.http import HTTPRequestError
+
+try:
+    response = client.<operation>(...)
+except APIError as exc:
+    # handle API error
+    # it is raised on any API error. You may also catch the specific API error
+except APIClientError as exc:
+    # handle API client error
+    # it is raised when API returns unexpected response (e.g. invalid JSON, invalid signature)
+except HTTPRequestError as exc:
+    # handle HTTP error
+    # it is raised on any HTTP error
+except ValueError as exc:
+    # handle value error
+    # it is raised on any library's misuse (e.g. passing invalid parameters)
+    # it always means developer's mistake
+```
+
+### RSA keys management
+The simples way to pass RSA keys is to pass their file paths:
+
+```python
+from csobpg.v19 import APIClient
+
+client = APIClient(..., "merch_private.key", "csob.pub")
+```
+
+The library will read the private key from the file when needed. The public key will be cached into the RAM.
+
+If you want to change it, use special classes:
+
+```python
+from csobpg.v19 import APIClient, FileRSAKey, CachedRSAKey
+
+client = APIClient(..., FileRSAKey("merch_private.key"), FileRSAKey("csob.pub"))
+```
+
+You may also override the base RSAKey class to define your own key access strategy:
+
+```python
+from csobpg.v19 import RSAKey
+
+class MyRSAKey(RSAKey):
+
+    def __str__(self) -> str:
+        return "my key"
+```
+

csobpg-0.0.1/README.md

@@ -0,0 +1,129 @@
+# CSOB client
+Python library for communicating with ČSOB (<https://platbakartou.csob.cz/>) payment gateway API. The API is described here: <https://github.com/csob/paymentgateway>.
+
+The library currently implements API v.1.9 only.
+
+
+## Installation
+```bash
+pip install csobpg
+```
+
+## Basic usage
+### API client initialization
+```python
+from csobpg.v19 import APIClient
+
+client = APIClient("merchantId", "merch_private.key", "csob.pub", base_url=..., http_client=...)
+```
+
+### HTTP client
+The library uses the `HTTPClient` interface for making HTTP requests.
+
+It provides the following HTTP clients:
+  * `csobpg.http.urllib_client.UrllibHTTPClient` - the default one using the `urllib` under the hood
+  * `csobpg.http.requests_client.RequestsHTTPClient` - an extra HTTP client using the `requests` under the hood. The library must be installed with the `requests-client` extra to be able to use this client
+
+It is also possible to implement the `HTTPClient` interface to use your custom HTTP client.
+
+The HTTP client is set as the following:
+
+```python
+from csobpg.v19 import APIClient
+from csobpg.http import HTTPClient
+
+class CustomHTTPClient(HTTPClient):
+    ...
+
+client = APIClient(..., http_client=CustomHTTPClient(...))
+```
+
+### Payment initialization
+```python
+from csobpg.v19 import Cart, CartItem
+
+response = client.init_payment(
+    order_no="2233823251",
+    total_amount=100,
+    return_url="http://127.0.0.1:5000/",
+    cart=Cart([CartItem("Apples", 1, 100)]),
+    merchant_data=b"Hello, World!",
+)
+```
+
+### Get payment URL
+```python
+url = client.get_payment_process_url(pay_id)
+```
+
+### Process the gateway redirect
+```python
+response = client.process_gateway_return(data_dict)
+```
+
+### Get payment status
+```python
+response = client.get_payment_status(pay_id)
+```
+
+### Reverse payment
+```python
+response = client.reverse_payment(pay_id)
+```
+
+### Refund payment
+```python
+response = client.refund_payment(pay_id, amount=100)
+```
+
+### Exceptions handling
+```python
+from csobpg.v19.errors import APIError, APIClientError
+from csobpg.http import HTTPRequestError
+
+try:
+    response = client.<operation>(...)
+except APIError as exc:
+    # handle API error
+    # it is raised on any API error. You may also catch the specific API error
+except APIClientError as exc:
+    # handle API client error
+    # it is raised when API returns unexpected response (e.g. invalid JSON, invalid signature)
+except HTTPRequestError as exc:
+    # handle HTTP error
+    # it is raised on any HTTP error
+except ValueError as exc:
+    # handle value error
+    # it is raised on any library's misuse (e.g. passing invalid parameters)
+    # it always means developer's mistake
+```
+
+### RSA keys management
+The simples way to pass RSA keys is to pass their file paths:
+
+```python
+from csobpg.v19 import APIClient
+
+client = APIClient(..., "merch_private.key", "csob.pub")
+```
+
+The library will read the private key from the file when needed. The public key will be cached into the RAM.
+
+If you want to change it, use special classes:
+
+```python
+from csobpg.v19 import APIClient, FileRSAKey, CachedRSAKey
+
+client = APIClient(..., FileRSAKey("merch_private.key"), FileRSAKey("csob.pub"))
+```
+
+You may also override the base RSAKey class to define your own key access strategy:
+
+```python
+from csobpg.v19 import RSAKey
+
+class MyRSAKey(RSAKey):
+
+    def __str__(self) -> str:
+        return "my key"
+```

csobpg-0.0.1/csobpg/__init__.py

@@ -0,0 +1 @@
+"""The library package."""

csobpg-0.0.1/csobpg/http/__init__.py

@@ -0,0 +1,17 @@
+"""Package for dealing with HTTP."""
+
+from .base import (
+    HTTPClient,
+    HTTPConnectionError,
+    HTTPRequestError,
+    HTTPResponse,
+    HTTPTimeoutError,
+)
+
+__all__ = [
+    "HTTPClient",
+    "HTTPConnectionError",
+    "HTTPRequestError",
+    "HTTPResponse",
+    "HTTPTimeoutError",
+]

csobpg-0.0.1/csobpg/http/base.py

@@ -0,0 +1,104 @@
+"""Base client."""
+
+import json as jsonlib
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class HTTPRequestError(Exception):
+    """Base HTTP request error."""
+
+
+class HTTPConnectionError(HTTPRequestError):
+    """Any error related to connection."""
+
+
+class HTTPTimeoutError(HTTPRequestError):
+    """HTTP request timed out."""
+
+
+class HTTPInvalidResponseError(HTTPRequestError):
+    """HTTP response is invalid."""
+
+
+class HTTPResponse:
+    """HTTP response wrapper."""
+
+    def __init__(
+        self, status_code: int, body: Optional[bytes], headers: dict
+    ) -> None:
+        self.status_code = status_code
+        self.body = body or b""
+        self._headers = headers
+
+        self._json = None
+
+    @property
+    # TODO: return dict
+    def json(self) -> Optional[dict]:
+        """Return body as JSON."""
+        if self._json is not None:
+            return self._json
+
+        headers = {key.lower(): val for key, val in self._headers.items()}
+        if "application/json" in headers.get("content-type", ""):
+            try:
+                self._json = jsonlib.loads(self.body)
+            except Exception as exc:
+                raise HTTPInvalidResponseError(
+                    f"Invalid JSON in response: {exc}"
+                ) from exc
+
+        return self._json
+
+    def __str__(self) -> str:
+        return f"{self.__class__.__name__}(status={self.status_code})"
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"status={self.status_code}, "
+            f"body={self.body}, "
+            f"headers={self._headers}"
+            ")"
+        )
+
+
+class HTTPClient(ABC):
+    """Base HTTP client."""
+
+    def __init__(self, request_timeout: float = 5) -> None:
+        self.request_timeout = request_timeout
+
+    # pylint: disable=too-many-arguments
+    @abstractmethod
+    def _request(
+        self,
+        method: str,
+        url: str,
+        json: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> HTTPResponse:
+        """Perform request.
+
+        This method must handle all possible HTTP exceptions and raise them
+        as `HTTPRequestError`.
+
+        Headers may be extended if necessary.
+        """
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        json: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> HTTPResponse:
+        """Perform HTTP request with a given HTTP method.
+
+        :param method: HTTP method to use
+        :param url: API URL
+        :param json: JSON data to post
+        :param headers: headers
+        """
+        return self._request(method, url, json, headers=headers)

csobpg-0.0.1/csobpg/http/requests_client.py

@@ -0,0 +1,46 @@
+"""HTTP client which uses `requests` under the hood."""
+
+from typing import Optional
+
+import requests
+
+from .base import (
+    HTTPClient,
+    HTTPConnectionError,
+    HTTPRequestError,
+    HTTPResponse,
+    HTTPTimeoutError,
+)
+
+
+class RequestsHTTPClient(HTTPClient):
+    """`requests` HTTP client."""
+
+    def __init__(self, request_timeout: float = 5) -> None:
+        super().__init__(request_timeout)
+        self._session = requests.Session()
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        json: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> HTTPResponse:
+        try:
+            response: requests.Response = getattr(
+                self._session, method.lower()
+            )(url, json=json, timeout=self.request_timeout, headers=headers)
+        except ConnectionError as exc:
+            raise HTTPConnectionError(exc) from exc
+        except requests.Timeout as exc:
+            raise HTTPTimeoutError(exc) from exc
+        except requests.RequestException as exc:
+            raise HTTPRequestError(exc) from exc
+
+        return HTTPResponse(
+            response.status_code, response.content, dict(response.headers)
+        )
+
+    def __str__(self) -> str:
+        return self.__class__.__name__

csobpg-0.0.1/csobpg/http/urllib_client.py

@@ -0,0 +1,62 @@
+"""HTTP client which uses `urllib` under the hood."""
+
+import json as _jsonlib
+import urllib
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Optional
+
+from .base import (
+    HTTPClient,
+    HTTPConnectionError,
+    HTTPRequestError,
+    HTTPResponse,
+    HTTPTimeoutError,
+)
+
+
+class UrllibHTTPClient(HTTPClient):
+    """`urllib` HTTP client."""
+
+    # pylint: disable=too-many-arguments
+    def _request(
+        self,
+        method: str,
+        url: str,
+        json: Optional[dict] = None,
+        headers: Optional[dict] = None,
+    ) -> HTTPResponse:
+        headers = headers or {}
+        data = None
+
+        if json:
+            headers["Content-Type"] = "application/json"
+            data = _jsonlib.dumps(json).encode()
+
+        try:
+            with urllib.request.urlopen(
+                urllib.request.Request(
+                    url,
+                    data=data,
+                    headers=headers,
+                    method=method.upper(),
+                ),
+                timeout=self.request_timeout,
+            ) as response:
+                return HTTPResponse(
+                    response.status, response.read(), dict(response.headers)
+                )
+        except ConnectionError as exc:
+            raise HTTPConnectionError(exc) from exc
+        except TimeoutError as exc:
+            raise HTTPTimeoutError(exc) from exc
+        except urllib.error.HTTPError as exc:
+            return HTTPResponse(
+                exc.status or 500, exc.read(), dict(exc.headers)
+            )
+        except urllib.error.URLError as exc:
+            raise HTTPRequestError(exc) from exc
+
+    def __str__(self) -> str:
+        return self.__class__.__name__

csobpg-0.0.1/csobpg/v19/__init__.py

@@ -0,0 +1,18 @@
+"""Client for API v.1.9."""
+
+from .api import APIClient
+from .key import FileRSAKey, RAMRSAKey, RSAKey
+from .request.payment_init.cart import Cart, CartItem
+from .request.payment_init.currency import Currency
+from .response import PaymentStatus
+
+__all__ = (
+    "APIClient",
+    "Cart",
+    "CartItem",
+    "Currency",
+    "RAMRSAKey",
+    "FileRSAKey",
+    "RSAKey",
+    "PaymentStatus",
+)