python-easyverein 0.1.0__tar.gz

python_easyverein-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2023 Daniel Herrmann
+
+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.

python_easyverein-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.1
+Name: python-easyverein
+Version: 0.1.0
+Summary: Python library to interact with the EasyVerein API
+Author: Daniel Herrmann
+Author-email: daniel.herrmann1@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: email-validator (>=2,<3)
+Requires-Dist: pydantic (>=2,<3)
+Requires-Dist: requests (>=2,<3)
+Description-Content-Type: text/markdown
+
+[![Documentation Status](https://readthedocs.org/projects/python-easyverein/badge/?version=latest)](https://python-easyverein.readthedocs.io/en/latest/?badge=latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
+![GitHub issues](https://img.shields.io/github/issues/waza-ari/python-easyverein)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/waza-ari/python-easyverein)
+![GitHub top language](https://img.shields.io/github/languages/top/waza-ari/python-easyverein)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/waza-ari/python-easyverein/development.svg)](https://results.pre-commit.ci/latest/github/waza-ari/python-easyverein/development)
+
+
+# Python EasyVerein
+
+**Full documentation** is [available at Read The Docs](https://python-easyverein.readthedocs.io/en/latest/)
+
+This package contains an unofficial API client for [EasyVerein](http://easyverein.com) written in Python. Please note that this
+library is unofficial and therefore not supported in any way by SD Software Design GmbH. If you have issues using this
+library, please do not open a support request within EasyVerein but report it to our GitHub repository instead.
+
+## State of the API
+
+This client was written against and tested against the Hexa v1.7 API version of EasyVerein. It may or may not work
+with newer / older API versions, so please use them at your own risk. As the EasyVerein API does not expose model
+information, the models used as part of this library are specific to this library and are based on information obtained
+from the API responses (e.g. required fields when creating an item).
+
+In addition to the official endpoints, the client provides some convenience functions that are not included in the
+official API (e.g. setting a custom field of a member to certain value, no matter if it has been set before or not
+or create an invoice with items in one go) which makes it much simpler to work with the API.
+
+Not all endpoints offered by the EasyVerein API are supported. For now, only the following endpoints are implemented.
+When saying CRUD, it means the library supports various methods to **C**reate, **R**ead, **U**pdate and
+**D**elete objects. See the API reference for details on supported CRUD operations.
+
+* `contact-details`: CRUD, Soft-Delete
+* `custom-fields`: CRUD, Soft-Delete
+* `invoice`: CRUD, Soft-Delete, plus some convenience methods
+* `invoice-item`: CRUD
+* `member`: CRUD, Soft-Delete
+* `member/<id>/custom-fields`: CRUD, plus some convenience methods
+* `wastebasket` (its the official name used by the EasyVerein API to reference soft-deleted objects)
+
+In addition to that, the library supports nested queries using the query syntax, included nested model validation.
+See the Usage section of this documentation for more details.
+
+## Installation
+
+Install the package using `poetry`:
+
+```bash
+poetry add python-easyverein
+```
+
+or `pip`:
+
+```bash
+pip install python-easyverein
+```
+
+## Getting Started
+
+This simple example shows how to setup the library and retrieve all invoices:
+
+```python
+import os
+from easyverein import EasyvereinAPI
+
+api_key = os.getenv('EV_API_KEY', '')
+
+ev_client = EasyvereinAPI(api_key)
+
+print(ev_client.invoice.get())
+```
+
+The result will be a list of invoice objects. All returned objects are [Pydantic](https://pydantic.dev) models under
+the hood, so you get auto-completion and a guaranteed interface for these models. For details please refer to the usage
+section of this documentation.
+
+## Tests
+
+All features of this client are automatically tested against the actual API using pytest. If you want to run the tests
+yourself, it is advisable to create a separate demo account for that. Then, set the following environment variable to
+your API token and simply run `pytest`:
+
+```
+EV_API_KEY=<your-api-key>
+```
+
+## Contributing
+
+The client is written in pure Python, using `mkdocs` with `mkdocstrings` for documentation. Any changes or
+pull requests are more than welcome, but please adhere to the code style:
+
+- Use `black` for code formatting
+- Use `isort` based import sorting
+- Use `ruff` based code linting
+
+A pre-commit hook configuration is supplied as part of the project.
+
+Please make sure that any additions are properly tested. PRs won't get accepted if they don't have test cases to
+cover them.
+
+## Getting Help
+
+Once more, this library is not officially supported by SD Software Design GmbH, the company behind EasyVerein.
+If you have troubles, please ask yourself the following questions:
+
+- Is your problem around API usage in general, which endpoint to call, which fields to set to achieve a certain thing?
+  Do you have questions around attribute naming, usage, or why the API behaves a certain way? Those questions should be
+  directed towards their support, as I cannot help with them.
+- is your question around how to use this library, a mistake in the Pydantic models it's using, an error in the library
+  code or other questions around this library? Please open a GitHub issue for those questions.
+

python_easyverein-0.1.0/README.md

@@ -0,0 +1,109 @@
+[![Documentation Status](https://readthedocs.org/projects/python-easyverein/badge/?version=latest)](https://python-easyverein.readthedocs.io/en/latest/?badge=latest)
+[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
+![GitHub issues](https://img.shields.io/github/issues/waza-ari/python-easyverein)
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/waza-ari/python-easyverein)
+![GitHub top language](https://img.shields.io/github/languages/top/waza-ari/python-easyverein)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/waza-ari/python-easyverein/development.svg)](https://results.pre-commit.ci/latest/github/waza-ari/python-easyverein/development)
+
+
+# Python EasyVerein
+
+**Full documentation** is [available at Read The Docs](https://python-easyverein.readthedocs.io/en/latest/)
+
+This package contains an unofficial API client for [EasyVerein](http://easyverein.com) written in Python. Please note that this
+library is unofficial and therefore not supported in any way by SD Software Design GmbH. If you have issues using this
+library, please do not open a support request within EasyVerein but report it to our GitHub repository instead.
+
+## State of the API
+
+This client was written against and tested against the Hexa v1.7 API version of EasyVerein. It may or may not work
+with newer / older API versions, so please use them at your own risk. As the EasyVerein API does not expose model
+information, the models used as part of this library are specific to this library and are based on information obtained
+from the API responses (e.g. required fields when creating an item).
+
+In addition to the official endpoints, the client provides some convenience functions that are not included in the
+official API (e.g. setting a custom field of a member to certain value, no matter if it has been set before or not
+or create an invoice with items in one go) which makes it much simpler to work with the API.
+
+Not all endpoints offered by the EasyVerein API are supported. For now, only the following endpoints are implemented.
+When saying CRUD, it means the library supports various methods to **C**reate, **R**ead, **U**pdate and
+**D**elete objects. See the API reference for details on supported CRUD operations.
+
+* `contact-details`: CRUD, Soft-Delete
+* `custom-fields`: CRUD, Soft-Delete
+* `invoice`: CRUD, Soft-Delete, plus some convenience methods
+* `invoice-item`: CRUD
+* `member`: CRUD, Soft-Delete
+* `member/<id>/custom-fields`: CRUD, plus some convenience methods
+* `wastebasket` (its the official name used by the EasyVerein API to reference soft-deleted objects)
+
+In addition to that, the library supports nested queries using the query syntax, included nested model validation.
+See the Usage section of this documentation for more details.
+
+## Installation
+
+Install the package using `poetry`:
+
+```bash
+poetry add python-easyverein
+```
+
+or `pip`:
+
+```bash
+pip install python-easyverein
+```
+
+## Getting Started
+
+This simple example shows how to setup the library and retrieve all invoices:
+
+```python
+import os
+from easyverein import EasyvereinAPI
+
+api_key = os.getenv('EV_API_KEY', '')
+
+ev_client = EasyvereinAPI(api_key)
+
+print(ev_client.invoice.get())
+```
+
+The result will be a list of invoice objects. All returned objects are [Pydantic](https://pydantic.dev) models under
+the hood, so you get auto-completion and a guaranteed interface for these models. For details please refer to the usage
+section of this documentation.
+
+## Tests
+
+All features of this client are automatically tested against the actual API using pytest. If you want to run the tests
+yourself, it is advisable to create a separate demo account for that. Then, set the following environment variable to
+your API token and simply run `pytest`:
+
+```
+EV_API_KEY=<your-api-key>
+```
+
+## Contributing
+
+The client is written in pure Python, using `mkdocs` with `mkdocstrings` for documentation. Any changes or
+pull requests are more than welcome, but please adhere to the code style:
+
+- Use `black` for code formatting
+- Use `isort` based import sorting
+- Use `ruff` based code linting
+
+A pre-commit hook configuration is supplied as part of the project.
+
+Please make sure that any additions are properly tested. PRs won't get accepted if they don't have test cases to
+cover them.
+
+## Getting Help
+
+Once more, this library is not officially supported by SD Software Design GmbH, the company behind EasyVerein.
+If you have troubles, please ask yourself the following questions:
+
+- Is your problem around API usage in general, which endpoint to call, which fields to set to achieve a certain thing?
+  Do you have questions around attribute naming, usage, or why the API behaves a certain way? Those questions should be
+  directed towards their support, as I cannot help with them.
+- is your question around how to use this library, a mistake in the Pydantic models it's using, an error in the library
+  code or other questions around this library? Please open a GitHub issue for those questions.

python_easyverein-0.1.0/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

python_easyverein-0.1.0/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)

python_easyverein-0.1.0/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

python_easyverein-0.1.0/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

python_easyverein-0.1.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]:
+        ...