Skip to content

Latest commit

 

History

History
118 lines (82 loc) · 5.17 KB

README.md

File metadata and controls

118 lines (82 loc) · 5.17 KB
Raw

Documentation Status License: MIT GitHub issues GitHub release (latest by date) GitHub top language pre-commit.ci status

Python EasyVerein

Full documentation is available at Read The Docs

This package contains an unofficial API client for EasyVerein 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 Create, Read, Update and Delete 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-groups: CRUD, Soft-Delete
  • member/<id>/custom-fields: CRUD, plus some convenience methods
  • member/<id>/member-groups: 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:

poetry add python-easyverein

or pip:

pip install python-easyverein

Getting Started

This simple example shows how to setup the library and retrieve all invoices:

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 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 ruff based code linting, formatting and styling
  • Use mypy for static type checking

A pre-commit hook configuration is supplied as part of the project. You can run them prior to your commit using:

pre-commit

# Or run them for the entire project
pre-commit run --all-files

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.