python-easyverein

https://python-easyverein.readthedocs.io/en/latest/
Admin
An unofficial Python library providing a comprehensive interface to the EasyVerein API with support...
Tokens:21,837
Snippets:278
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install python-easyverein with Poetry

Source: https://python-easyverein.readthedocs.io/en/latest

Use this command to add the python-easyverein library to your project when using Poetry for dependency management.

```bash
poetry add python-easyverein
```

--------------------------------

### Install python-easyverein with Pip

Source: https://python-easyverein.readthedocs.io/en/latest

Use this command to add the python-easyverein library to your project when using pip for dependency management.

```bash
pip install python-easyverein
```

--------------------------------

### Pagination with get()

Source: https://python-easyverein.readthedocs.io/en/latest/usage

The `get()` method allows for manual control over pagination by specifying the `limit` and `page` parameters. It returns both the data and the total count of available resources.

```APIDOC
## GET /resource

### Description
Fetches resources with manual pagination control.

### Method
GET

### Endpoint
/resource

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The number of elements to return per page.
- **page** (int) - Optional - The specific page number to retrieve.

### Response
#### Success Response (200)
- **data** (list) - A list of resources.
- **total_count** (int) - The total number of available resources.

### Request Example
```python
members, total_count = ev_connection.member.get(limit=10, page=2)
```

### Response Example
```json
{
  "data": [
    { "id": 1, "name": "Member 1" },
    { "id": 2, "name": "Member 2" }
  ],
  "total_count": 50
}
```
```

--------------------------------

### Get Single Page of Resources

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Use the `get` method to fetch a paginated list of resources. You can specify a `query` string, a `search` filter, the `limit` of items per page (max 100), and the desired `page` number. It returns a tuple containing the list of objects and the total count of available objects.

```python
members, total_count = ev_client.member.get(limit=50, page=2, query="is_active=true")
```

--------------------------------

### get

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Fetches a single page of objects based on specified query, search filters, and pagination parameters.

```APIDOC
## get

### Description
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 containing the list of objects and the total count.

### Method Signature
```python
get(
    query: str = "",
    search: FilterType | None = None,
    limit: int = 10,
    page: int = 1,
) -> tuple[list[ModelType], int]
```

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (`str`) - Optional - Query to use with the API. Refer to the EV API help for more information.
- **search** (`FilterType | None`) - Optional - Filter to use with the API. Refer to the EV API help for more information.
- **limit** (`int`) - Optional - Defines how many resources to return per page. Defaults to 10.
- **page** (`int`) - Optional - Defines which page to return. Defaults to 1.

### Request Example
```python
members_page, total_count = ev_client.member.get(query="is_active=true", limit=20, page=2)
```

### Response
#### Success Response (200)
- **tuple[list[ModelType], int]** - A tuple where the first element is a list of `ModelType` objects and the second element is the total count of available objects.

#### Response Example
```json
{
  "example": "([{'id': 1, 'name': 'John Doe'}, {'id': 2, 'name': 'Jane Smith'}], 50)"
}
```
```

--------------------------------

### Bulk Create Contact Details

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Example of how to create multiple contact details records in a single API call. Ensure you import the necessary model.

```python
from easyverein import EasyvereinAPI
from easyverein.models import ContactDetailsCreate

ev_client = EasyvereinAPI("<your-token>")

results = ev_client.contact_details.bulk_create([
    ContactDetailsCreate(firstName="example1", lastName="Example1", isCompany=False),
    ContactDetailsCreate(firstName="example2", lastName="Example2", isCompany=False),
])

print(results)  # [True, True] if both were created successfully
```

--------------------------------

### Accessing get() Response

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Demonstrates different ways to unpack the tuple returned by the `get()` method, which includes the response data and the total count.

```APIDOC
## Accessing get() Response

### Description
Shows how to handle the tuple returned by the `get()` method, which contains both the data and the total count.

### Code Examples

1. **Unpacking both values:**
   ```python
   members, total_count = ev_connection.member.get()
   ```

2. **Accessing only the data (preferred):**
   ```python
   members = ev_connection.member.get()[0]
   ```

3. **Ignoring the total count using `_`:**
   ```python
   members, _ = ev_connection.member.get()
   ```
```

--------------------------------

### Manage Soft-Deleted Invoices

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Provides examples for retrieving, restoring, and permanently purging soft-deleted invoice records using specific library methods.

```python
from easyverein import EasyvereinAPI

ev_client = EasyvereinAPI("<your-token>")

# Get all soft-deleted invoices
invoices = ev_client.invoice.get_deleted()

# We can either restore them
for invoice in invoices:
    ev_client.invoice.restore(invoice)  # Also accepts the ID, so `invoice.id` would work, too.

# Or we can delete them for good
for invoice in invoices:
    ev_client.invoice.purge(invoice)  # Also accepts the ID, so `invoice.id` would work, too.
```

--------------------------------

### Get All Resources

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

The `get_all` method simplifies fetching all resources from an endpoint by abstracting pagination. It retrieves all available pages and returns them as a single list. For efficiency, consider increasing `limit_per_page` to reduce the number of API calls, keeping in mind the API's maximum limit of 100 per page.

```python
all_members = ev_client.member.get_all(limit_per_page=100)
```

--------------------------------

### Get Deleted Resources

Source: https://python-easyverein.readthedocs.io/en/latest/api/recycle_bin

Fetches all deleted resources from the recycle bin and returns a list of these items.

```APIDOC
## get_deleted

### Description
Fetches all deleted resources from the recycle bin and returns a list.

### Method
GET

### Endpoint
/recycle_bin

### Response
#### Success Response (200)
- **items** (list[ModelType]) - A list of deleted resources.
- **count** (int) - The total number of deleted resources.

### Response Example
```json
{
  "items": [
    { "id": 1, "name": "Deleted Item 1" },
    { "id": 2, "name": "Deleted Item 2" }
  ],
  "count": 2
}
```
```

--------------------------------

### Create a Custom Field Resource

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Create a new custom field using the `CustomFieldCreate` model. This example demonstrates the minimal required fields for creating a custom field.

```python
from easyverein import EasyvereinAPI
from easyverein.models import CustomFieldCreate

ev_client = EasyvereinAPI("<your-token>")

custom_field_model = CustomFieldCreate(
    name="Test-Field",
    kind="e",
    settings_type="t"
)
response = ev_client.custom_field.create(custom_field_model)
```

--------------------------------

### Create Resource with EasyVerein API

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Use the `create` method to add a new resource to EasyVerein. This method sends a POST request to the relevant endpoint and returns the newly created object, parsed as a Pydantic model. Ensure you have the correct Pydantic model for creation, like `CustomFieldCreate` in the example.

```python
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")
)

```

--------------------------------

### Unpack Response and Total Count

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Use this method when you need both the returned data and the total count of resources. It unpacks the tuple returned by the get() method.

```python
members, total_count = ev_connection.member.get()
```

--------------------------------

### Fetch Member Data with Multiple Nesting Levels

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Retrieve all members and their associated group information, including nested fields like family name, first name, date of birth, and group short name. This example shows deep nesting.

```python
allmembers = ev_client.member.get_all(
    query="{membershipNumber,contactDetails{familyName,firstName,dateOfBirth},memberGroups{memberGroup{short}}}"
)
for m in allmembers:
    print(f"{m.membershipNumber} {m.contactDetails.familyName} {m.contactDetails.firstName} {m.contactDetails.dateOfBirth}")
    if m.memberGroups is not None:
        for g in m.memberGroups:
            print(f"     Group: {g.memberGroup.short}")
```

--------------------------------

### Get Invoice Attachment

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Downloads and returns the invoice attachment. It can accept either an invoice object or its ID. The response includes the file content and response headers.

```python
invoice = ev_connection.invoice.get_by_id(invoice_id, query="{id,path}")

attachment, headers = ev_connection.invoice.get_attachment(invoice)

```

--------------------------------

### MemberMemberGroup Model Attributes

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_member_group

Defines the attributes for the MemberMemberGroup model, including end date, associated member group, payment activity status, payment amount, start date, and user object reference.

```python
end: Date | None = None
```

```python
memberGroup: EasyVereinReference | MemberGroup | None = None
```

```python
paymentActive: bool = False
```

```python
paymentAmount: float | None = None
```

```python
start: Date | None = None
```

```python
userObject: EasyVereinReference | Member | None = None
```

--------------------------------

### Creating Resources

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Demonstrates how to create new resources using provided model types for type checking and basic validation.

```APIDOC
## POST /resource

### Description
Creates a new resource.

### Method
POST

### Endpoint
/resource

### Parameters
#### Request Body
- **model** (object) - Required - A model object representing the resource to be created.

### Request Example
```python
from easyverein.models import CustomFieldCreate

custom_field_model = CustomFieldCreate(
    name="Test-Field",
    kind="e",
    settings_type="t"
)
response = ev_client.custom_field.create(custom_field_model)
```

### Response
#### Success Response (201)
- **resource** (object) - The newly created resource object.

### Response Example
```json
{
  "id": 123456789,
  "name": "Test-Field",
  "kind": "e",
  "settings_type": "t"
}
```
```

--------------------------------

### Create EasyVerein API Client

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Instantiate the client object with your API key. The API key is the only mandatory parameter. Default values for api_version and base_url are recommended.

```python
from easyverein import EasyvereinAPI

c = EasyvereinAPI(api_key="your_key")

# Get invoices
invoices, total_count = c.invoice.get()
invoices = c.invoice.get_all()

# Members
c.member.get()
```

--------------------------------

### Run Pre-commit Hooks

Source: https://python-easyverein.readthedocs.io/en/latest

Execute pre-commit hooks to ensure code quality and style consistency before committing changes. This is a recommended step for all contributors.

```bash
pre-commit
```

```bash
pre-commit run --all-files
```

--------------------------------

### get_all

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Conveniently fetches all objects from the API, abstracting pagination.

```APIDOC
## get_all

### Description
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. It is advisable to set a higher limit to avoid many API calls. The maximum page size is 100.

### Method Signature
```python
get_all(
    query: str = "",
    search: FilterType | None = None,
    limit_per_page: int = 10,
) -> list[ModelType]
```

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (`str`) - Optional - Query to use with the API. Defaults to None. Refer to the EV API help for more information.
- **search** (`FilterType | None`) - Optional - Filter to use with the API. Refer to the EV API help for more information.
- **limit_per_page** (`int`) - Optional - Defines how many resources to return per page. Defaults to 10.

### Request Example
```python
all_members = ev_client.member.get_all(limit_per_page=50)
```

### Response
#### Success Response (200)
- **list[ModelType]** - A single list containing all fetched `ModelType` objects.

#### Response Example
```json
{
  "example": "[{'id': 1, 'name': 'John Doe'}, {'id': 2, 'name': 'Jane Smith'}, ...]"
}
```
```

--------------------------------

### Get Group Membership

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/member_member_group

Retrieves the membership object for a specific member within a given group. Returns None if the member is not in the group.

```APIDOC
## get_group_membership

### Description
Returns the membership object of this member in the given group, None if the member is not in the group. This method can be useful if the group membership should be updated or deleted.

### Method
`get_group_membership(
    group: MemberGroup | int,
) -> MemberMemberGroup | None`

### Parameters
#### Path Parameters
- **group** (MemberGroup | int) - Required - The group object or id to fetch.
```

--------------------------------

### Python: Initialize Member Custom Fields Client

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/member_custom_field

Instantiate the custom fields client for members, passing the member object to the constructor to avoid repeated arguments.

```python
evclient.member.custom_fields(member)
```

--------------------------------

### Set API Key for Testing

Source: https://python-easyverein.readthedocs.io/en/latest

Configure the EV_API_KEY environment variable with your API token to run the library's tests against the actual API.

```bash
EV_API_KEY=<your-api-key>
```

--------------------------------

### Get Group Membership

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/member_member_group

Retrieves the membership object for a member within a specific group. Returns `None` if the member is not part of the group. This can be used to update or delete an existing membership.

```python
get_group_membership(
    group: MemberGroup | int,
) -> MemberMemberGroup | None
```

--------------------------------

### Basic Usage: Retrieve Invoices

Source: https://python-easyverein.readthedocs.io/en/latest

Set up the EasyVerein API client and retrieve all invoices. Ensure the EV_API_KEY environment variable is set.

```python
import os
from easyverein import EasyvereinAPI

api_key = os.getenv('EV_API_KEY', '')

ev_client = EasyvereinAPI(api_key)

print(ev_client.invoice.get())
```

--------------------------------

### Create Invoice with Items

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

This helper method simplifies creating an invoice with multiple items, as the EV API does not support passing items directly during initial creation. The invoice is created in draft state by default.

```python
create_with_items(
    invoice: InvoiceCreate,
    items: List[InvoiceItemCreate],
    set_draft_state: bool = True,
)

```

--------------------------------

### create

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Creates an object of the specified type and returns the created object. This method uses the POST request of the respective endpoint.

```APIDOC
## create

### Description
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.

### Method Signature
```python
create(data: CreateModelType) -> ModelType
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **data** (`CreateModelType`) - Required - Object to be created

### Request Example
```python
from easyverein import EasyvereinAPI

ev_client = EasyvereinAPI("your_api_key")

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

### Response
#### Success Response (200)
- **ModelType** - The created object, parsed and validated as a Pydantic object.

#### Response Example
(Response structure depends on the specific endpoint and `ModelType`)
```

--------------------------------

### Fetch All Invoices with Pagination

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Fetches all available invoice resources, abstracting pagination. The total count can be derived from the list length. Set limit_per_page for efficient fetching.

```python
# Get all returns a simple list, you can obtain the total count based on the list length
invoices = ev_connection.invoice.get_all(limit_per_page=100)
```

--------------------------------

### Create Invoice with Attachment

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Use this method to create an invoice and upload a PDF attachment simultaneously. The invoice is created in draft state by default, which can be changed.

```python
create_with_attachment(
    invoice: InvoiceCreate,
    attachment: Path,
    set_draft_state: bool = True,
)

```

--------------------------------

### Fetch Deleted Resources

Source: https://python-easyverein.readthedocs.io/en/latest/api/recycle_bin

Retrieves all resources currently in the recycle bin. Returns a list of deleted items.

```python
get_deleted() -> tuple[list[ModelType], int]
```

--------------------------------

### create_with_items

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Creates an invoice and adds a list of items. This is a helper method as the EV API does not support passing invoice items directly during creation.

```APIDOC
## create_with_items

### Description
Creates an invoice and adds a list of items. This is a helper method as the EV API does not support passing invoice items directly during creation.
Note that this endpoint performs multiple API requests, depending on the number of items and the final draft state. At least, the invoice needs to be created in draft state. Then the items have to be added (one API request per item, as the API does not support a bulk create endpoint here). Finally, if `set_draft_state` is set to `True` and the models attribute `isDraft` equals `False`, a final request is performed afterward to remove the draft state.
Starting with the Hexa v1.7 API, the API will automatically generate a PDF attachment based on the provided data and the settings configured in the realm settings.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **invoice** (InvoiceCreate) - Required - Invoice to create
- **items** (List[InvoiceItemCreate]) - Required - List of invoice items to add to the invoice
- **set_draft_state** (bool) - Optional - Whether to convert the invoice from draft state to an actual invoice after adding items. Defaults to `True`.
```

--------------------------------

### Updating Resources

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Explains how to update existing resources using update models, allowing for partial updates by specifying only the fields to be changed.

```APIDOC
## PATCH /resource/{id}

### Description
Updates an existing resource. Individual fields can be patched.

### Method
PATCH

### Endpoint
/resource/{id}

### Parameters
#### Path Parameters
- **id** (int) - Required - The ID of the resource to update.

#### Request Body
- **model** (object) - Required - An update model object containing the fields to be modified. All attributes are optional.

### Request Example
```python
from easyverein.models import CustomFieldUpdate

custom_field_id = 123456
update_model = CustomFieldUpdate(
    name="New Name"
)
response = ev_client.custom_field.update(custom_field_id, update_model)
```

### Response
#### Success Response (200)
- **resource** (object) - The updated resource object.

### Response Example
```json
{
  "id": 123456,
  "name": "New Name",
  "kind": "e",
  "settings_type": "t"
}
```
```

--------------------------------

### create_with_attachment

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Creates an invoice and uploads an attachment. The invoice is created in draft state by default, and can be finalized by setting `set_draft_state` to `True`.

```APIDOC
## create_with_attachment

### Description
Creates an invoice with an attachment. Note that the only valid file type is PDF.
This endpoint performs multiple API requests, depending on the final draft state. At least two requests are performed (create invoice draft and upload attachment). Then, if `set_draft_state` is set to `True` and the models attribute `isDraft` equals `False`, a third request is performed afterward to remove the draft state.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **invoice** (InvoiceCreate) - Required - The invoice object to be created
- **attachment** (Path) - Required - The path to the attachment to be uploaded. Must be a PDF file and a `pathlib.Path` object
- **set_draft_state** (bool) - Optional - Whether to set the draft state of the invoice to `False` after uploading the attachment. Defaults to `True`.
```

--------------------------------

### Booking Project Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

The project associated with the booking. Stored as a string or None.

```python
bookingProject: str | None = None
```

--------------------------------

### Handle Token Refresh (Synchronous)

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Implement a synchronous callback function to be triggered when a token refresh is needed. This function serves as a trigger for you to refresh and store the token externally. It does not extend the runtime of the initial request.

```python
from easyverein import BearerToken, EasyvereinAPI

def handle_token_refresh() -> None:
    # This merely serves as a trigger for you to refresh and store the token
    return None

c = EasyvereinAPI(api_key="your_key", api_version="v2.0", token_refresh_callback=handle_token_refresh)
```

--------------------------------

### Filter Invoices by Criteria

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Demonstrates filtering invoices using a Pydantic filter model. Supports complex queries like 'in' for multiple values and 'isnull' for null checks.

```python
search = InvoiceFilter(
    invNumber__in=["1", "3", "5"], canceledInvoice__isnull=True, isDraft=False
)

filtered_invoices, total_count = ev_connection.invoice.get(search=search)
```

--------------------------------

### bulk_create

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Creates multiple objects in a single API request and returns the created objects. This method is supported for specific endpoints like booking, contact-details, member, and invoice.

```APIDOC
## bulk_create

### Description
Creates multiple objects in a single API request and returns the created objects. This method is supported for specific endpoints like booking, contact-details, member, and invoice.

### Method Signature
`bulk_create(data: list[CreateModelType]) -> list[bool]`

### Parameters
#### Request Body
- **data** (list[CreateModelType]) - Required - List of Pydantic models containing the data for the objects to be created.

### Request Example
```python
from easyverein import EasyvereinAPI

ev_client = EasyvereinAPI("your_api_key")

contact_details = ev_client.contact_details.bulk_create([
    ContactDetailsCreate(fistName="example1", lastName="Example1", isCompany=False),
    ContactDetailsCreate(fistName="example2", lastName="Example2", isCompany=False),
])
```
```

--------------------------------

### Bulk Create Objects

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Creates multiple objects in a single API request. This is useful for efficiency when adding many new records. Requires a list of Pydantic models containing the data for each object.

```python
bulk_create(data: list[CreateModelType]) -> list[bool]
```

```python
from easyverein import EasyvereinAPI

ev_client = EasyvereinAPI("your_api_key")

contact_details = ev_client.contact_details.bulk_create([
    ContactDetailsCreate(fistName="example1", lastName="Example1", isCompany=False),
    ContactDetailsCreate(fistName="example2", lastName="Example2", isCompany=False),
])
```

--------------------------------

### showInApplicationform Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Determines if the member group should be shown in application forms. Accepts a boolean value or None.

```python
showInApplicationform: bool | None = None
```

--------------------------------

### Bulk Update Members

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Shows how to update multiple member records simultaneously. Each update model must include the member's ID.

```python
from easyverein import EasyvereinAPI
from easyverein.models import MemberUpdate

ev_client = EasyvereinAPI("<your-token>")

results = ev_client.member.bulk_update([
    MemberUpdate(id=1, membershipNumber="M1"),
    MemberUpdate(id=2, membershipNumber="M2"),
])

print(results)  # [True, True] if both were updated successfully
```

--------------------------------

### Handle Token Refresh (Asynchronous with Auto-Refresh)

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Utilize automatic token refresh by providing a callback function that accepts the new token. This method automatically refreshes the token after a request and passes it to your callback for storage. It slightly extends the runtime of the request.

```python
from easyverein import BearerToken, EasyvereinAPI

def handle_token_refresh(new_token: BearerToken) -> None:
    print(f"New token: {new_token.Bearer}")
    return None

c = EasyvereinAPI(
    api_key="your_key",
    api_version="v2.0",
    token_refresh_callback=handle_token_refresh,
    auto_refresh_token=True
)
```

--------------------------------

### Model Classes for Custom Field Select Options

Source: https://python-easyverein.readthedocs.io/en/latest/models/custom_field_select_option

Overview of the model classes used for updating and creating custom field select options.

```APIDOC
## Model Classes

### Representative Model Class
`CustomFieldSelectOption`

### Update Model Class
`CustomFieldSelectOptionUpdate`

### Create Model Class
`CustomFieldSelectOptionCreate`
```

--------------------------------

### Update Custom Field by Model or ID

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Demonstrates two ways to update a custom field: first by fetching the model and then updating, and second by directly using the custom field ID.

```python
custom_field = ev_client.custom_field.get_by_id(custom_field_id)
ev_client.custom_field.update(
    custom_field,
    update_model
)
```

```python
ev_client.custom_field.update(
    custom_field_id,
    update_model
)
```

--------------------------------

### Booking Billing Account Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

Specifies the billing account for the booking. Accepts BillingAccount, EasyVereinReference, or None.

```python
billingAccount: (
    BillingAccount | EasyVereinReference | None
) = None
```

--------------------------------

### Read Member Data

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Demonstrates fetching a single page of members and the total count. Access attributes using Pydantic model properties.

```python
# get() returns the member and total count
members, total_count = ev_connection.member.get()
```

--------------------------------

### Custom Field Select Options Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/custom_field

A list of options for select-type custom fields, where each option can be a CustomFieldSelectOption or an EasyVereinReference. Can be None.

```python
selectOptions: (
    list[CustomFieldSelectOption | EasyVereinReference]
    | None
) = None
```

--------------------------------

### Upload Invoice Attachment

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Uploads a PDF attachment to an existing invoice. The invoice must be in draft state for the upload to be successful.

```python
upload_attachment(invoice: Invoice | int, file: Path)

```

--------------------------------

### MemberCustomField: selectedOptions Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_custom_field

Contains a list of selected options for a custom field, where each option can be a CustomFieldSelectOption or an EasyVereinReference. It can also be None.

```python
selectedOptions: (
    list[CustomFieldSelectOption | EasyVereinReference]
    | None
) = None
```

--------------------------------

### Fetch Object by ID

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Retrieves a single object using its unique identifier. An optional query parameter can be used for more specific data retrieval.

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

--------------------------------

### Fetch Invoice with Nested Address Fields

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Retrieve invoice data, including specific fields from the related address, using a query string. This demonstrates selecting fields from a nested model.

```python
invoices = ev_client.invoice.get(
    query="{id,date,dateItHappend,receiver,relatedAddress{id,street,zip}}"
)
```

--------------------------------

### get_attachment

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Downloads and returns the invoice attachment. It can accept either an invoice object or its ID.

```APIDOC
## get_attachment

### Description
Downloads and returns the invoice attachment if available. It accepts either an invoice object or its ID. If the invoice is given, and the path attribute is set, it will simply use this path to download and return the file. In all other cases, it first retrieves the invoice object by id and then proceeds to download the file.
Returns a tuple, where the first element is the file and the second contains the headers of the response.

**Usage**
```python
invoice = ev_connection.invoice.get_by_id(invoice_id, query="{id,path}")

attachment, headers = ev_connection.invoice.get_attachment(invoice)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **invoice** (Invoice | int) - Required - The invoice object or its id for which the attachment should be retrieved.
```

--------------------------------

### primaryEmail Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/contact_details

Sets the primary email address for a contact. Defaults to 'email'.

```python
primaryEmail: str | None = 'email'

```

--------------------------------

### MemberCustomField: value Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_custom_field

The actual value assigned to the custom field for the member. This is a string or None.

```python
value: str | None = None
```

--------------------------------

### MemberCustomField: requestedValue Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_custom_field

Represents the value requested for the custom field. This is a string or None.

```python
requestedValue: str | None = None
```

--------------------------------

### Add Member to Group

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/member_member_group

Adds a member to a specified group. By default, it ignores existing memberships and does not activate billing. Set `ignore_existing` to `False` to raise an exception if the member is already in the group.

```python
add_to_group(
    group: MemberGroup | int,
    payment_active: bool = False,
    ignore_existing: bool = False,
)
```

--------------------------------

### user_inventory Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user inventory access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_inventory: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### sepaDate Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/contact_details

Represents the SEPA direct debit mandate date.

```python
sepaDate: DateTime | None = None

```

--------------------------------

### salutation Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/contact_details

Defines the salutation for a contact, limited to '', 'Herr', or 'Frau'.

```python
salutation: Literal['', 'Herr', 'Frau'] | None = None

```

--------------------------------

### Custom Field Select Options Management

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/custom_field_select_option

This section outlines the API endpoint and namespace for managing select options associated with custom fields. The operations supported are CRUD (Create, Read, Update, Delete).

```APIDOC
## Custom Field Select Options

### API Endpoint
`custom-field/<custom_field_id>/select-options`

### Namespace
`evclient.custom_field.select_options(<custom_field>).<method>`

### Supported Operations
CRUD (Create, Read, Update, Delete)

### Parameters
#### Path Parameters
- **custom_field_id** (`CustomField | int`) - Required - Identifies the custom field to modify select options for. Can be either an id or a `CustomField` object.

### Generic Model Mappings
- **ModelType**: `CustomFieldSelectOption`
- **CreateModelType**: `CustomFieldSelectOptionCreate`
- **UpdateModelType**: `CustomFieldSelectOptionUpdate`
```

--------------------------------

### descriptionOnInvoice Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Provides a description for the member group to be displayed on invoices. Accepts a string or None.

```python
descriptionOnInvoice: str | None = None
```

--------------------------------

### user_bookings Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user bookings access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_bookings: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### usePaymentFormula Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Indicates whether to use the payment formula for the member group. Accepts a boolean value or None.

```python
usePaymentFormula: bool | None = None
```

--------------------------------

### Contact Details API Operations

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/contact_details

The Contact Details API provides CRUD (Create, Read, Update, Delete) operations and supports a Recycle Bin feature. The namespace for these operations is `evclient.contact_details.<method>`.

```APIDOC
## Contact Details API

### Description
Provides CRUD operations for contact details and supports a recycle bin.

### Namespace
`evclient.contact_details.<method>`

### Supported Generics
CRUD, RecycleBin
```

--------------------------------

### Delete Invoice by Model or ID with Purge Option

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Illustrates deleting an invoice, with options for soft-delete (default) or immediate purging from the recycle bin. Both the model object and its ID can be used for deletion.

```python
from easyverein import EasyvereinAPI

ev_client = EasyvereinAPI("<your-token>")

invoice_id = 123456

# We can either update the model
invoice = ev_client.invoice.get_by_id(invoice_id)

# Delete the model by using the model. Will soft-delete by default
ev_client.invoice.delete(invoice)
# As we didn't fully delete the item, we can view, restore or purge it, see below.

# Alternatively, we can use the model. Also, we set the second parameter to make sure the object gets purged
ev_client.invoice.delete(invoice_id, delete_from_recycle_bin=True)
```

--------------------------------

### Booking Blocked Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

Indicates if the booking is blocked. A boolean value or None.

```python
blocked: bool | None = None
```

--------------------------------

### upload_attachment

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/invoice

Uploads an attachment to an existing invoice. The invoice must be in draft state for the upload to succeed.

```APIDOC
## upload_attachment

### Description
Uploads an attachment to an already existing invoice. The invoice must be in draft state, otherwise the upload will fail.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **invoice** (Invoice | int) - Required - The invoice to upload the attachment to. Can be either an `Invoice` object or its ID
- **file** (Path) - Required - The path to the attachment to be uploaded. Must be a PDF file and a `pathlib.Path` object.
```

--------------------------------

### Booking Bank Account Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

References the bank account related to the booking. Uses EasyVereinReference or can be None.

```python
bankAccount: EasyVereinReference | None = None
```

--------------------------------

### sepaMandate Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/contact_details

Stores the SEPA direct debit mandate, with a maximum length of 60 characters.

```python
sepaMandate: str | None = Field(default=None, max_length=60)

```

--------------------------------

### isOnlyVisibleToAdmins Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Controls the visibility of the member group to administrators only. Accepts a boolean value or None.

```python
isOnlyVisibleToAdmins: bool | None = None
```

--------------------------------

### paymentFormula Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Specifies a formula for payment calculations. Accepts a string with a maximum length of 512 characters, or None.

```python
paymentFormula: str | None = Field(
    default=None, max_length=512
)
```

--------------------------------

### Nested Queries

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Utilizes the API's query syntax to select specific fields and retrieve nested model data, simplifying data access.

```APIDOC
## GET /resource

### Description
Fetches resources with nested data using a query syntax.

### Method
GET

### Endpoint
/resource

### Parameters
#### Query Parameters
- **query** (string) - Required - A string specifying the fields to retrieve, including nested fields.

### Request Example
```python
invoices = ev_client.invoice.get(
    query="{id,date,dateItHappend,receiver,relatedAddress{id,street,zip}}"
)

# Accessing nested data
for invoice in invoices:
    print(invoice.relatedAddress.street)
```

### Response Example
```json
{
    "id": 183495599,
    "relatedAddress": {
        "id": 113185254,
        "street": "Warner-Allee 1",
        "zip": "46244"
    },
    "date": "2023-11-28",
    "dateItHappend": "2023-11-26",
    "receiver": "Herr Max Mustermann\nWarner-Allee 1\n46244 Bottrop\nDeutschland"
}
```
```

--------------------------------

### Update a Custom Field Resource

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Update an existing custom field by providing its ID and an `CustomFieldUpdate` model. Only the fields to be changed need to be included in the update model.

```python
from easyverein import EasyvereinAPI
from easyverein.models import CustomFieldUpdate

ev_client = EasyvereinAPI("<your-token>")

custom_field_id = 123456

update_model = CustomFieldUpdate(
    name="New Name"
)

```

--------------------------------

### Booking API Endpoint

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/booking

The booking API endpoint provides CRUD (Create, Read, Update, Delete) operations and supports a recycle bin feature. It maps generic models to specific booking models.

```APIDOC
## Booking API

### Description
Provides CRUD operations and recycle bin functionality for bookings.

### Namespace
`evclient.booking.<method>`

### Supported Generics
CRUD, RecycleBin

### Generic Model Mappings
- `ModelType` maps to `Booking`
- `CreateModelType` maps to `BookingCreate`
- `UpdateModelType` maps to `BookingUpdate`

### Additional Parameters
None

### Additional Methods
None
```

--------------------------------

### Define useBalanceForMembershipFee Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member

This attribute determines if a member's balance should be used to offset their membership fees. It can be set to a boolean or left as None.

```python
useBalanceForMembershipFee: bool | None = None
```

--------------------------------

### Booking Description Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

A textual description for the booking. Expected to be a string or None.

```python
description: str | None = None
```

--------------------------------

### Booking Payment Difference Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

The difference in payment for the booking. A float value or None.

```python
paymentDifference: float | None = None
```

--------------------------------

### BillingAccount Name Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/billing_account

The name of the billing account. Can be a string or None.

```python
name: str | None = None
```

--------------------------------

### Member Custom Fields Namespace

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/member_custom_field

The namespace for accessing and managing member custom fields. It requires a member identifier during initialization.

```APIDOC
## Member Custom Fields

### Description
Access and manage custom fields associated with a specific member.

### Namespace
`evclient.member.custom_fields(<member>).<method>`

### Supported Operations
CRUD (Create, Read, Update, Delete)

### Parameters
#### Member Parameter
- **member** (Member | int) - Required - Identifies the member to modify custom field values on. Can be either an id or a `Member` object.
```

--------------------------------

### user_forum Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user forum access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_forum: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### Booking Amount Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

Represents the monetary amount associated with the booking. Can be a float or None.

```python
amount: float | None = None
```

--------------------------------

### user_protocols Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user protocols access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_protocols: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### user_importcalendar Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user calendar import access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_importcalendar: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### Custom Field Order Sequence Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/custom_field

An integer attribute defining the sequence order for the custom field, must be a non-negative integer. Defaults to None.

```python
orderSequence: PositiveIntWithZero | None = None
```

--------------------------------

### update

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

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

```APIDOC
## update

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

### Method Signature
`update(target: ModelType | int, data: UpdateModelType, exclude_none: bool = True) -> ModelType`

### Parameters
#### Path Parameters
- **target** (ModelType | int) - Required - Model instance to update or id of the model to update

#### Request Body
- **data** (UpdateModelType) - Required - Pydantic Model holding data to update the model

#### Query Parameters
- **exclude_none** (bool) - Optional - exclude fields with None, set to False to explicitly unset fields. Defaults to True.
```

--------------------------------

### Member API Endpoint

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/member

The `member` endpoint supports CRUD operations and RecycleBin functionality within the `evclient.member` namespace.

```APIDOC
## Member API

### Description
Provides access to member-related operations including Create, Read, Update, Delete, and Recycle Bin functionality.

### Namespace
`evclient.member`

### Supported Generics
- CRUD
- RecycleBin

### Generic Model Mappings
- `ModelType` maps to `Member`
- `CreateModelType` maps to `MemberCreate`
- `UpdateModelType` maps to `MemberUpdate`
```

--------------------------------

### user_board Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user board access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_board: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### Booking Date Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

The date of the booking. Uses the DateTime type or can be None.

```python
date: DateTime | None = None
```

--------------------------------

### agePermission Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the age permission for a member group. Can be a positive integer or None.

```python
agePermission: PositiveIntWithZero | None = None
```

--------------------------------

### assignmentDeleteAfterBooking Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Indicates if assignments should be deleted after booking. Accepts a boolean value or None.

```python
assignmentDeleteAfterBooking: bool | None = None
```

--------------------------------

### Generic Model Mappings

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/custom_field

Defines the mapping between generic model types and their corresponding CustomField models.

```APIDOC
## Generic Model Mappings

| Generic Model     | CustomField Model     |
|-------------------|-----------------------|
| `ModelType`       | `CustomField`         |
| `CreateModelType` | `CustomFieldCreate`   |
| `UpdateModelType` | `CustomFieldUpdate`   |
```

--------------------------------

### Booking Billing ID Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

The billing identifier for the booking. Expected to be a string or None.

```python
billingId: str | None = None
```

--------------------------------

### user_boardLinks Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/member_group

Defines the user board links access level for the member group. Options are 'n' (standard), 'a' (allowed), or 'd' (forbidden). Accepts Literal['n', 'a', 'd'] or None.

```python
user_boardLinks: Literal['n', 'a', 'd'] | None = None
```

--------------------------------

### Iterate and Access Invoice Attributes

Source: https://python-easyverein.readthedocs.io/en/latest/usage

Iterates through a list of Invoice objects obtained from get_all() and accesses specific attributes like isDraft and invNumber.

```python
# Invoices now is a list of Invoice objects
for invoice in invoices:
    print(invoice.isDraft)
    print(invoice.invNumber)
```

--------------------------------

### Billing Account API Operations

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/billing_account

The Billing Account API endpoint supports CRUD (Create, Read, Update, Delete) operations and RecycleBin functionality. It is accessible through the `evclient.booking` namespace.

```APIDOC
## Billing Account

### Description
Provides access to billing account management, supporting CRUD operations and RecycleBin functionality.

### Namespace
`evclient.booking`

### Supported Generics
- CRUD
- RecycleBin

### Generic Model Mappings
- `ModelType`: `BillingAccount`
- `CreateModelType`: `BillingAccountCreate`
- `UpdateModelType`: `BillingAccountUpdate`
```

--------------------------------

### Custom Field Description Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/custom_field

A string field for the description of the custom field, with a maximum length of 500 characters. Defaults to None.

```python
description: str | None = Field(
    default=None, max_length=500
)
```

--------------------------------

### Generic Model Mappings

Source: https://python-easyverein.readthedocs.io/en/latest/api/endpoints/contact_details

Defines the mapping between generic model types and specific ContactDetails models for various operations.

```APIDOC
## Generic Model Mappings

Generic Model | ContactDetails Model
---|---
`ModelType` | `ContactDetails`
`CreateModelType` | `ContactDetailsCreate`
`UpdateModelType` | `ContactDetailsUpdate`
```

--------------------------------

### get_by_id

Source: https://python-easyverein.readthedocs.io/en/latest/api/crud

Fetches a single object identified by its primary ID. Supports optional query parameters for advanced filtering.

```APIDOC
## get_by_id

### Description
Fetches a single object identified by its primary ID. Supports optional query parameters for advanced filtering.

### Method Signature
`get_by_id(obj_id: int, query: str = '') -> ModelType`

### Parameters
#### Path Parameters
- **obj_id** (int) - Required - Id of the object to be retrieved

#### Query Parameters
- **query** (str) - Optional - Query to use with API. Defaults to ''. Refer to the EV API help for more information on how to use queries
```

--------------------------------

### Booking Receiver Attribute

Source: https://python-easyverein.readthedocs.io/en/latest/models/booking

The receiver of the booking. A string or None.

```python
receiver: str | None = None
```
Tokens:
Raw