python-easyverein 0.1.0__py3-none-any.whl

easyverein/__init__.py

@@ -0,0 +1,8 @@
+"""
+Middleware for FastAPI that supports authenticating users against Keycloak
+"""
+
+__version__ = "0.0.1"
+
+# Export EasyVerein API directly
+from .api import EasyvereinAPI  # noqa: F401

easyverein/api.py

@@ -0,0 +1,43 @@
+"""
+Main EasyVerein API class
+"""
+import logging
+
+from .core.client import EasyvereinClient
+from .modules.contact_details import ContactDetailsMixin
+from .modules.custom_field import CustomFieldMixin
+from .modules.invoice import InvoiceMixin
+from .modules.invoice_item import InvoiceItemMixin
+from .modules.member import MemberMixin
+from .modules.member_custom_field import MemberCustomFieldMixin
+
+
+class EasyvereinAPI:
+    def __init__(
+        self,
+        api_key,
+        api_version="v1.7",
+        base_url: str = "https://hexa.easyverein.com/api/",
+        logger: logging.Logger = None,
+    ):
+        """
+        Constructor setting API key and logger. Test
+        """
+
+        super().__init__()
+
+        if logger:
+            self.logger = logger
+        else:
+            self.logger = logging.getLogger("easyverein")
+
+        self.c = EasyvereinClient(api_key, api_version, base_url, self.logger, self)
+
+        # Add methods
+
+        self.contact_details = ContactDetailsMixin(self.c, self.logger)
+        self.custom_field = CustomFieldMixin(self.c, self.logger)
+        self.invoice = InvoiceMixin(self.c, self.logger)
+        self.invoice_item = InvoiceItemMixin(self.c, self.logger)
+        self.member = MemberMixin(self.c, self.logger)
+        self.member_custom_field = MemberCustomFieldMixin(self.c, self.logger)

easyverein/core/client.py

@@ -0,0 +1,314 @@
+"""
+Main EasyVerein API class
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING, TypeVar
+
+import requests
+from pydantic import BaseModel
+
+from .exceptions import EasyvereinAPIException, EasyvereinAPITooManyRetriesException
+
+if TYPE_CHECKING:
+    from .. import EasyvereinAPI
+
+T = TypeVar("T")
+
+
+class EasyvereinClient:
+    """
+    Class encapsulating common function used by all API methods
+    """
+
+    def __init__(
+        self,
+        api_key,
+        api_version,
+        base_url,
+        logger: logging.Logger,
+        instance: EasyvereinAPI,
+    ):
+        """
+        Constructor setting API key and logger
+        """
+        self.api_key = api_key
+        self.base_url = base_url
+        self.api_version = api_version
+        self.logger = logger
+        self.api_instance = instance
+
+    def _get_header(self):
+        """
+        Constructs a header for the API request
+        """
+        return {"Authorization": "Bearer " + self.api_key}
+
+    def get_url(self, path: str, url_params: dict = None) -> str:
+        """
+        Constructs a URL for the API request.
+
+        :param path: Base path of the request
+        :param url_params: additional path parameters to append
+        """
+        url = f"{self.base_url}{self.api_version}{path}"
+
+        self.logger.debug(f"Base URL is {url}")
+
+        if url_params:
+            for key, value in url_params.items():
+                if not value:
+                    continue
+                self.logger.debug(f"Adding {key}={value} path parameter to URL")
+                if "?" not in url:
+                    url += f"?{key}={value}"
+                else:
+                    url += f"&{key}={value}"
+
+        self.logger.debug(f"Final constructed URL is {url}")
+
+        return url
+
+    def _do_request(  # noqa: PLR0913
+        self, method, url, data=None, headers=None, files=None
+    ):
+        """
+        Helper method that performs an actual call against the API,
+        fetching the most common errors
+        """
+        self.logger.debug("Performing %s request to %s", method, url)
+        if data:
+            self.logger.debug("Request data: %s", data)
+        if headers:
+            self.logger.debug("Provided request headers: %s", headers)
+
+        # Merge auth header with custom headers
+        final_headers = self._get_header() | (headers or {})
+
+        self.logger.debug("Final request headers: %s", final_headers)
+
+        func = getattr(requests, method)
+        if data:
+            res = func(url, headers=final_headers, json=data, files=files or {})
+        else:
+            res = func(url, headers=final_headers, files=files)
+
+        self.logger.debug("Request returned status code %d", res.status_code)
+
+        if res.status_code == 429:
+            retry_after = res.headers("Retry-After")
+            self.logger.warning(
+                "Request returned status code 429, too many requests. Wait %d seconds",
+                retry_after,
+            )
+            raise EasyvereinAPITooManyRetriesException(
+                retry_after,
+                f"Too many requests, please wait {retry_after} seconds and try again.",
+            )
+
+        if res.status_code == 404:
+            self.logger.warning("Request returned status code 404, resource not found")
+            raise EasyvereinAPIException("Requested resource not found")
+
+        # In some cases (for example on 204 delete) the response is empty
+        if res.content == b"":
+            return res.status_code, None
+
+        # Try to parse response as JSON and return it for further processing
+        try:
+            content = res.json()
+        except ValueError:
+            self.logger.error("Unable to parse response content as JSON")
+            self.logger.debug("Response content: %s", res.content)
+            content = None
+
+        return res.status_code, content
+
+    def create(
+        self,
+        url,
+        data: BaseModel = None,
+        return_model: type[T] = None,
+        status_code: int = 201,
+    ) -> T:
+        """
+        Method to create an object in the API
+        """
+        return self._handle_response(
+            self._do_request(
+                "post",
+                url,
+                data=data.model_dump(
+                    exclude_none=True, exclude_unset=True, by_alias=True
+                ),
+            ),
+            return_model,
+            status_code,
+        )
+
+    def delete(self, url, status_code: int = 204):
+        """
+        Method to delete an object in the API
+        """
+        return self._handle_response(
+            self._do_request("delete", url), expected_status_code=status_code
+        )
+
+    def update(
+        self, url, data: BaseModel = None, model: type[T] = None, status_code: int = 200
+    ) -> T:
+        """
+        Method to update an object in the API
+        """
+        return self._handle_response(
+            self._do_request(
+                "patch",
+                url,
+                data=data.model_dump(
+                    exclude_none=True, exclude_unset=True, by_alias=True
+                ),
+            ),
+            model,
+            expected_status_code=status_code,
+        )
+
+    def upload(
+        self,
+        url: str,
+        field_name: str,
+        file: Path,
+        model: type[T] = None,
+        status_code: int = 200,
+    ) -> T:
+        """
+        This method uploads a file to a certain endpoint.
+
+        Only tested with invoices so far
+        """
+        # Check that path is a file and it exists
+        if not file.exists() or not file.is_file():
+            self.logger.error("File does not exist or is not a file.")
+            raise FileNotFoundError("File does not exist")
+
+        files = {field_name: open(file, "rb")}
+        headers = {"Content-Disposition": f'name="file"; filename="{file.name}"'}
+
+        return self._handle_response(
+            self._do_request(
+                "patch",
+                url,
+                headers=headers,
+                files=files,
+            ),
+            model,
+            status_code,
+        )
+
+    def fetch(self, url, model: type[T] = None) -> list[T]:
+        """
+        Helper method that fetches a result from an API call
+
+        Only supports GET endpoints
+        """
+        res = self._do_request("get", url)
+        return self._handle_response(res, model, 200)
+
+    def fetch_one(self, url, model: type[T] = None) -> T | None:
+        """
+        Helper method that fetches a result from an API call
+
+        Only supports GET endpoints
+        """
+        reply = self.fetch(url, model)
+        if isinstance(reply, list):
+            if len(reply) == 0:
+                return None
+
+            self.logger.warning(
+                "One object was requested, but multiple objects were returned. Returning first."
+            )
+            self.logger.debug(f"In total {len(reply)} objects where returned.")
+            return reply[0]
+
+        return reply
+
+    def fetch_paginated(self, url, model: type[T] = None, limit=100) -> list[T]:
+        """
+        Helper method that fetches all pages of a paginated API call
+
+        Only supports GET endpoints
+        """
+
+        self.logger.debug("Fetching paginated API call %s, limit is %d", url, limit)
+
+        # Add limit parameter to URL
+        if "?" not in url:
+            url += f"?limit={limit}"
+        else:
+            url += f"&limit={limit}"
+
+        resources = []
+        status_code: int = 0
+
+        while url is not None:
+            self.logger.debug("Fetching page of paginated API call %s", url)
+
+            status_code, result = self._do_request("get", url)
+            self.logger.debug("Request returned status code %d", status_code)
+
+            if not status_code == 200:
+                self.logger.error(
+                    "Could not fetch paginated API %s, status code %d", url, status_code
+                )
+                self.logger.debug("API response: %s", result)
+                raise EasyvereinAPIException(
+                    f"Could not fetch paginated API {url}, "
+                    f"status code {status_code}. API response: {result}"
+                )
+
+            resources.extend(result["results"])
+            url = result["next"]
+
+        return self._handle_response((status_code, resources), model, 200)
+
+    def _handle_response(
+        self,
+        res: tuple[int, list | dict],
+        model: type[T] = None,
+        expected_status_code=200,
+    ) -> T | list[T]:
+        """
+        Helper method that handles API responses
+        """
+        status_code, data = res
+        if status_code != expected_status_code:
+            raise EasyvereinAPIException(
+                f"API returned status code {status_code}. API response: {data}"
+            )
+        else:
+            self.logger.debug("API returned status code %d", status_code)
+
+        # if no data is expected return raw data (usually None)
+        if not model:
+            self.logger.debug("No model provided. Returning raw data: %s", data)
+            return data
+
+        self.logger.debug("Received raw data: %s", data)
+
+        # if data is a list, parse each entry
+        # fetch_paginated returns a list of result entries instead of raw data, this is why this case is here.
+        if isinstance(data, list):
+            objects = []
+            for obj in data:
+                objects.append(model.model_validate(obj))
+        elif isinstance(data, dict) and "results" in data:
+            objects = []
+            for obj in data["results"]:
+                objects.append(model.model_validate(obj))
+        else:
+            # Handle the case when data is not a list
+            objects = model.model_validate(data)
+
+        return objects

easyverein/core/exceptions.py

@@ -0,0 +1,18 @@
+"""
+This module contains exceptions used by the library.
+"""
+
+
+class EasyvereinAPIException(Exception):
+    """
+    Exception describing an error that occurred while interacting
+    with the easyVerein API
+    """
+
+
+class EasyvereinAPITooManyRetriesException(EasyvereinAPIException):
+    """
+    Exception if the API returns a 429 Too Many Requests error
+    """
+
+    retry_after = 0

easyverein/core/protocol.py

@@ -0,0 +1,29 @@
+import logging
+from typing import Protocol, Type, TypeVar
+
+from pydantic import BaseModel
+
+from .client import EasyvereinClient
+
+
+# noinspection PyPropertyDefinition
+class IsEVClientProtocol(Protocol):
+    @property
+    def logger(self) -> logging.Logger:
+        ...
+
+    @property
+    def c(self) -> EasyvereinClient:
+        ...
+
+    @property
+    def endpoint_name(self) -> str:
+        ...
+
+    @property
+    def model_class(self) -> TypeVar:
+        ...
+
+    @property
+    def return_type(self) -> Type[BaseModel]:
+        ...

easyverein/core/types.py

@@ -0,0 +1,41 @@
+"""
+Custom types used for model validation
+"""
+import datetime
+import json
+from typing import Annotated
+
+from pydantic import BeforeValidator, EmailStr, Field, PlainSerializer, UrlConstraints
+from pydantic_core import Url
+
+from .validators import empty_string_to_none, parse_json_string
+
+AnyHttpURL = Annotated[
+    Url,
+    UrlConstraints(allowed_schemes=["http", "https"]),
+    PlainSerializer(lambda x: str(x), return_type=str),
+]
+EasyVereinReference = Annotated[
+    int | AnyHttpURL | None, BeforeValidator(empty_string_to_none)
+]
+PositiveIntWithZero = Annotated[int, Field(ge=0)]
+Date = Annotated[
+    datetime.date, PlainSerializer(lambda x: x.strftime("%Y-%m-%d"), return_type=str)
+]
+DateTime = Annotated[
+    datetime.datetime,
+    PlainSerializer(lambda x: x.strftime("%Y-%m-%dT%H:%M:%S"), return_type=str),
+]
+OptionsField = Annotated[
+    list[str] | None,
+    PlainSerializer(lambda x: json.dumps(x), return_type=str),
+    BeforeValidator(parse_json_string),
+    BeforeValidator(empty_string_to_none),
+]
+HexColor = Annotated[
+    str | None,
+    Field(min_length=7, max_length=7),
+    BeforeValidator(empty_string_to_none),
+]
+
+Email = Annotated[EmailStr | None, BeforeValidator(empty_string_to_none)]

easyverein/core/validators.py

@@ -0,0 +1,14 @@
+import json
+from typing import Any
+
+
+def empty_string_to_none(v: Any) -> Any:
+    if isinstance(v, str) and v == "":
+        return None
+    return v
+
+
+def parse_json_string(v: Any) -> Any:
+    if isinstance(v, str):
+        return json.loads(v)
+    return v

easyverein/models/__init__.py

@@ -0,0 +1,18 @@
+# noqa: F401
+from .contact_details import ContactDetails, ContactDetailsCreate, ContactDetailsUpdate
+from .custom_field import CustomField, CustomFieldCreate, CustomFieldUpdate
+from .invoice import Invoice, InvoiceCreate, InvoiceUpdate
+from .invoice_item import InvoiceItem, InvoiceItemCreate, InvoiceItemUpdate
+from .member import Member, MemberCreate, MemberUpdate
+from .member_custom_field import (
+    MemberCustomField,
+    MemberCustomFieldCreate,
+    MemberCustomFieldUpdate,
+)
+
+ContactDetails.model_rebuild()
+CustomField.model_rebuild()
+Invoice.model_rebuild()
+InvoiceItem.model_rebuild()
+Member.model_rebuild()
+MemberCustomField.model_rebuild()

easyverein/models/base.py

@@ -0,0 +1,17 @@
+from pydantic import BaseModel, Field, PositiveInt
+
+from ..core.types import DateTime, EasyVereinReference
+
+
+class EasyVereinBase(BaseModel):
+    """
+    Base class encapsulating common fields for all models
+    """
+
+    id: PositiveInt | None = None
+    org: EasyVereinReference | None = None
+    # TODO: Add reference to Organization once implemented
+    deleteAfterDate: DateTime | None = Field(default=None, alias="_deleteAfterDate")
+    """Alias for `_deleteAfterDate` field. See [Pydantic Models](../usage.md#pydantic-models) for details."""
+    deletedBy: str | None = Field(default=None, alias="_deletedBy")
+    """Alias for `_deletedBy` field. See [Pydantic Models](../usage.md#pydantic-models) for details."""

easyverein/models/contact_details.py

@@ -0,0 +1,137 @@
+"""
+Contact Details related models
+"""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import Field
+
+from ..core.types import Date, Email
+from .base import EasyVereinBase
+from .mixins.required_attributes import required_mixin
+
+
+class ContactDetails(EasyVereinBase):
+    """
+    | Representative Model Class | Update Model Class | Create Model Class |
+    | --- | --- | --- |
+    | `ContactDetails` | `ContactDetailsUpdate` | `ContactDetailsCreate` |
+
+    !!! info "Contact Details and Members"
+        Note that contact details can be created standalone (independently of members), but members
+        are required to have a contact details object linked.
+    """
+
+    isCompany: bool | None = Field(default=None, alias="_isCompany")
+    """Alias for `_isCompany` field. See [Pydantic Models](../usage.md#pydantic-models) for details."""
+    salutation: Literal["", "Herr", "Frau"] | None = None
+    firstName: str | None = Field(default=None, max_length=128)
+    familyName: str | None = Field(default=None, max_length=128)
+    nameAffix: str | None = Field(default=None, max_length=100)
+    dateOfBirth: Date | None = None
+    internalNote: str | None = None
+    privateEmail: Email | None = None
+    companyEmail: Email | None = None
+    companyEmailInvoice: Email | None = None
+    primaryEmail: str | None = "email"
+    preferredEmailField: Literal[0, 1, 2] | None = Field(
+        default=None, alias="_preferredEmailField"
+    )
+    """
+    Alias for `_preferredEmailField` field. See [Pydantic Models](../usage.md#pydantic-models) for details.
+
+    Possible values:
+
+    - 0: same as login
+    - 1: private
+    - 2: company
+    """
+    # Hint: 0 = mail, 1 = phone, 3 = no communication
+    preferredCommunicationWay: Literal[0, 1, 2] | None = None
+    companyName: str | None = None
+    invoiceCompany: bool | None = None
+    sendInvoiceCompanyMail: bool | None = None
+    addressCompany: bool | None = None
+    privatePhone: str | None = Field(default=None, max_length=100)
+    companyPhone: str | None = Field(default=None, max_length=100)
+    mobilePhone: str | None = Field(default=None, max_length=100)
+    street: str | None = Field(default=None, max_length=128)
+    city: str | None = Field(default=None, max_length=100)
+    state: str | None = Field(default=None, max_length=64)
+    additionalAdressInfo: str | None = Field(
+        default=None, max_length=128
+    )  # Intentionally written wrong, as per API
+    zip: str | None = Field(default=None, max_length=20)
+    country: str | None = Field(default=None, max_length=50)
+    companyStreet: str | None = Field(default=None, max_length=100)
+    companyCity: str | None = Field(default=None, max_length=64)
+    companyState: str | None = Field(default=None, max_length=100)
+    companyZip: str | None = Field(default=None, max_length=20)
+    companyCountry: str | None = Field(default=None, max_length=50)
+    professionalRole: str | None = Field(default=None, max_length=500)
+    balance: float | None = None
+    iban: str | None = Field(default=None, max_length=50)
+    bic: str | None = Field(default=None, max_length=100)
+    bankAccountOwner: str | None = Field(default=None, max_length=128)
+    sepaMandate: str | None = Field(default=None, max_length=60)
+    sepaDate: Date | None = None
+    methodOfPayment: int | None = None
+    """
+    Defines the method of payment preferred by the user.
+
+    Possible values:
+
+    - 0: not selected
+    - 1: direct debit
+    - 2: bank transfer
+    - 3: cash
+    - 4: other
+    """
+    datevAccountNumber: int | None = None
+    # TODO: Refine once available from API description
+    copiedFromParent: Any | None = Field(default=None, alias="_copiedFromParent")
+    """
+    Alias for `_copiedFromParent` field. See [Pydantic Models](../usage.md#pydantic-models) for details.
+    """
+    # TODO: Refine once available from API description
+    copiedFromParentStartDate: Any | None = Field(
+        default=None,
+        alias="_copiedFromParentStartDate",
+    )
+    """
+    Alias for `_copiedFromParentStartDate` field. See [Pydantic Models](../usage.md#pydantic-models) for details.
+    """
+    # TODO: Refine once available from API description
+    copiedFromParentEndDate: Any | None = Field(
+        default=None,
+        alias="_copiedFromParentEndDate",
+    )
+    """
+    Alias for `_copiedFromParentEndDate` field. See [Pydantic Models](../usage.md#pydantic-models) for details.
+    """
+    # TODO: Refine once available from API description
+    copiedFromParentEndDateAction: Any | None = Field(
+        default=None,
+        alias="_copiedFromParentEndDateAction",
+    )
+    """
+    Alias for `_copiedFromParentEndDateAction` field. See [Pydantic Models](../usage.md#pydantic-models) for details.
+    """
+
+
+class ContactDetailsUpdate(ContactDetails):
+    """
+    Pydantic model used to update contact details
+    """
+
+    isCompany: bool | None = Field(default=None, serialization_alias="_isCompany")
+    preferredEmailField: Literal[0, 1, 2] | None = Field(
+        default=None, alias="_preferredEmailField"
+    )
+
+
+class ContactDetailsCreate(ContactDetailsUpdate, required_mixin(["isCompany"])):
+    """
+    Pydantic model for creating new contact details
+    """