CRUD Operations

Overview¶

The following methods are common to all endpoints and are therefore only documented once. All these methods are defined in a generic class and are therefore generically typed. Refer to the documentation of each endpoint to see the mapping between the generic types and the Pydantic models for the specific endpoint.

Additional parameters

Note that some endpoints require additional parameters, which can be mandatory. For example, to work with custom field values on members, you need to specify the member id to work with.

These cases are highlighted as part of the respective endpoint API documentation.

Generic Classes¶

ModelType: The pydantic model used for displaying data at the respective endpoint. Usually used parse the API response and returned to the user.
CreateModelType: The pydantic model used for creating resources using this endpoint. In some cases (where documented on the EasyVerein side) the Pydantic models are enforcing required fields when creating resources. As the EasyVerein documentation is incomplete, expect these checks to be incomplete, too.
UpdateModelType: Used when patching a certain resource. Patching can be done on single fields, therefore all attributes are optional.

Method Reference¶

create ¶

create(data: CreateModelType) -> ModelType

Creates an object of specified type and returns the created object. The POST method of the respective endpoint is used to create a new resource and the API result is parsed, validated and returned as Pydantic object.

Example:

This example uses the custom-field endpoint, but any other endpoint can be used similarly.

from easyverein import EasyvereinAPI

ev_client = EasyvereinAPI("your_api_key")

custom_field = ev.custom_field.create(
    CustomFieldCreate(name="Test-Field", kind="e", settings_type="t")
)

Parameters:

Name	Type	Description	Default
`data`	`CreateModelType`	Object to be created	required

delete ¶

delete(target: ModelType | int, delete_from_recycle_bin: bool = False) -> None

Deletes an object from the database and returns nothing. Can either take the object itself or the id of the object as argument.

Note that the EV API soft-deletes some objects by default. These objects are not fully deleted but instead placed in a recycle bin (official API calls this "wastebasket").

This library does provide methods to interact with soft deleted objects (see below), but you may also instruct the delete method to immediately purge the object. This will result in two API calls (first soft-delete the object, then remove it from recycle bin). This is only supported for some endpoints:

member
member-group
contact-details
invoice
custom-field

Parameters:

Name	Type	Description	Default
`target`	`ModelType \| int`	Object to delete	required
`delete_from_recycle_bin`	`bool`	Whether to delete the invoice also from the recycle bin. Defaults to False.	`False`

get ¶

get(query: str = '', search: FilterType | None = None, limit: int = 10, page: int = 1) -> tuple[list[ModelType], int]

Fetches a single page of a given page size. The page size is defined by the limit parameter with an API sided upper limit of 100.

Returns a tuple, where the first element is the returned objects and the second is the total count.

Parameters:

Name	Type	Description	Default
`query`	`str`	Query to use with API. Refer to the EV API help for more information on how to use queries	`''`
`search`	`FilterType \| None`	Filter to use with API. Refer to the EV API help for more information on how to use filters	`None`
`limit`	`int`	Defines how many resources to return.	`10`
`page`	`int`	Deinfines which page to return. Defaults to 1, which is the first page.	`1`

get_all ¶

get_all(query: str = '', search: FilterType | None = None, limit_per_page: int = 10) -> list[ModelType]

Convenient method that fetches all objects from the EV API, abstracting away the need to handle pagination.

Will fetch all pages of objects and return a single list. The default has been chosen to match the limit of the API. It is advisable to set a higher limit to avoid many API calls. The maximum page size is 100.

Parameters:

Name	Type	Description	Default
`query`	`str`	Query to use with API. Defaults to None. Refer to the EV API help for more information on how to use queries	`''`
`search`	`FilterType \| None`	Filter to use with API. Refer to the EV API help for more information on how to use filters	`None`
`limit_per_page`	`int`	Defines how many resources to return. Defaults to 10.	`10`

get_by_id ¶

get_by_id(obj_id: int, query: str = '') -> ModelType

Fetches a single object identified by its primary id.

Parameters:

Name	Type	Description	Default
`obj_id`	`int`	Id of the object to be retrieved	required
`query`	`str`	Query to use with API. Defaults to None. Refer to the EV API help for more information on how to use queries	`''`

update ¶

update(target: ModelType | int, data: UpdateModelType) -> ModelType

Updates (PATCHes) a certain object and returns the updated object. Accepts either an object or its id as first argument.

Parameters:

Name	Type	Description	Default
`target`	`ModelType \| int`	Model instance to update or id of the model to update	required
`data`	`UpdateModelType`	Pydantic Model holding data to update the model	required