API

🚧 this page is still a work in progress 🚧

If you’d like to make a contribution, please join the project on GitHub

Personio

class personio_py.Personio(base_url: Optional[str] = None, client_id: Optional[str] = None, client_secret: Optional[str] = None, dynamic_fields: Optional[List[personio_py.mapping.DynamicMapping]] = None, session: Optional[requests.sessions.Session] = None)

Bases: object

the Personio API client.

Parameters

• base_url – use this custom base URL instead of the default https://api.personio.de/v1/

• client_id – the client id for API authentication (if not provided, defaults to the CLIENT_ID environment variable)

• client_secret – the client secret for API authentication (if not provided, defaults to the CLIENT_SECRET environment variable)

• dynamic_fields – definition of expected dynamic fields. List of DynamicMapping tuples.

ABSENCE_URL = 'company/time-offs'

ATTENDANCE_URL = 'company/attendances'

PROJECT_URL = 'company/attendances/projects'

authenticate()

Try to authenticate (using Personio’s /auth endpoint) with the credentials (client ID and secret) that were provided to this instance.

There should be no need to explicitly call this function, because you will be automatically authenticated when you make your first request.

If the authentication was successful, the authentication token is stored in the headers dictionary (self.headers). This token will be sent with every request and it will be automatically rotated whenever necessary. If the authentication failed, a PersonioApiError will be raised.

create_absence(absence: personio_py.models.Absence) → personio_py.models.Absence

Creates an absence record on the Personio servers

Parameters

absence – The absence object to be created

Raises

PersonioError – If the absence could not be created on the Personio servers

create_attendances(attendances: List[personio_py.models.Attendance]) → bool

Create all given attendance records.

Note: If one or more attendances can not be created, other attendances will be created but their corresponding objects passed as attendances will not be updated.

Parameters

attendances – A list of attendance records to be created.

create_employee(employee: personio_py.models.Employee, refresh=True) → personio_py.models.Employee

placeholder; not ready to be used

create_project(project: personio_py.models.Project) → personio_py.models.Project

Creates a project record on the Personio servers.

Parameters

project – The project object to be created

Raises

PersonioError – If the project could not be created on the Personio servers

delete_absence(absence: Union[personio_py.models.Absence, int])

Delete an existing record

An absence id is required.

Parameters

absence – The Absence object holding the new data or an absence record id to delete.

Raises

ValueError – If a query is required but not allowed or the query does not provide exactly one result.

delete_attendance(attendance: personio_py.models.Attendance)

Delete an existing record

Either an attendance id or o remote query is required. Remote queries are only executed if required. An Attendance object returned by get_attendances() include the attendance id. DO NOT SET THE ID YOURSELF.

Parameters

attendance – The Attendance object holding the new data or an attendance record id to delete.

Raises

ValueError: If a query is required but not allowed or the query does not provide exactly one result.

delete_project(project: Union[personio_py.models.Project, int]) → None

Deletes a project record on the Personio servers.

Parameters

project – The project object to be updated

Raises

ValueError – If a query is required but not allowed or the query does not provide exactly one result.

get_absence(absence: Union[personio_py.models.Absence, int]) → personio_py.models.Absence

Get an absence record from a given id.

Parameters

absence – The absence id to fetch.

get_absence_types() → List[personio_py.models.AbsenceType]

Get a list of all available absence types, e.g. “paid vacation” or “parental leave”.

The absence types are used to classify the absences of employees (see get_absences to get a list of all absences for the employees). Each Absence also contains the AbsenceType for this instance; the purpose of this function is to provide you with a list of all possible options that can show up.

get_absences(employees: Union[int, List[int], personio_py.models.Employee, List[personio_py.models.Employee]], start_date: Optional[datetime.datetime] = None, end_date: Optional[datetime.datetime] = None) → List[personio_py.models.Absence]

Get a list of all absence records for the employees with the specified IDs.

Note that internally, multiple requests may be made by this function due to limitations of the Personio API: Only a limited number of records can be retrieved in a single request and only a limited number of employee IDs can be passed as URL parameters. The results are still presented as a single list, no matter how many requests are made.

Parameters

• employees – a single employee or a list of employee objects or IDs. Absence records for all matching employees will be retrieved.

• start_date – only return absence records from this date (inclusive, optional)

• end_date – only return absence records up to this date (inclusive, optional)

Returns

list of Absence records for the specified employees

get_attendances(employees: Union[int, List[int], personio_py.models.Employee, List[personio_py.models.Employee]], start_date: Optional[datetime.datetime] = None, end_date: Optional[datetime.datetime] = None) → List[personio_py.models.Attendance]

Get a list of all attendance records for the employees with the specified IDs

Note that internally, multiple requests may be made by this function due to limitations of the Personio API: Only a limited number of records can be retrieved in a single request and only a limited number of employee IDs can be passed as URL parameters. The results are still presented as a single list, no matter how many requests are made.

Parameters

• employees – a single employee or a list of employee objects or IDs. Attendance records for all matching employees will be retrieved.

• start_date – only return attendance records from this date (inclusive, optional)

• end_date – only return attendance records up to this date (inclusive, optional)

Returns

list of Attendance records for the specified employees

get_employee(employee_id: int) → personio_py.models.Employee

Get a single employee with the specified ID. Does not involve pagination.

Parameters

employee_id – the Personio ID of the employee to fetch

Returns

an Employee instance or a PersonioApiError, if the employee does not exist

get_employee_picture(employee: Union[int, personio_py.models.Employee], width: Optional[int] = None) → Optional[bytes]

Get the profile picture of the specified employee as image file (usually png or jpg).

Parameters

• employee – get the picture of this employee or the employee with the specified Personio ID

• width – optionally scale the profile picture to this width. Defaults to the original width of the profile picture.

Returns

the profile picture as png or jpg file (bytes)

get_employees() → List[personio_py.models.Employee]

Get a list of all employee records in your account. Does not involve pagination.

Returns

list of Employee instances

get_projects() → List[personio_py.models.Project]

Get a list of all company projects.

Returns

list of Project records

invalidate_index()

Invalidates the search index. New data will be requested on the next search.

request(path: str, method='GET', params: Optional[Dict[str, Any]] = None, data: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, auth_rotation=True) → requests.models.Response

Make a request against the Personio API. Returns the HTTP response, which might be successful or not.

Rotation of authorization tokens is handled in this function. If no token is available (first request of this instance), the authenticate() function is called. On subsequent requests, the new authorization token is read from the response headers and replaces the previous one. Note that this behavior can be turned off by setting auth_rotation=False, which is required for some requests that do not return a new authorization token.

Parameters

• path – the URL path for this request (relative to the Personio API base URL)

• method – the HTTP request method (default: GET)

• params – dictionary of URL parameters (optional)

• data – dictionary of data to send in the request body (optional)

• headers – additional request headers (authentication is handled separately)

• auth_rotation – set to True, if authentication keys should be rotated during this request (default: True)

Returns

the HTTP response (the caller is responsible for handling HTTP errors)

request_image(path: str, method='GET', params: Optional[Dict[str, Any]] = None, auth_rotation=False) → Optional[bytes]

Request an image file (as png or jpg) from the Personio API. Returns the image as byte array, or None, if no image is available for this resource (HTTP status 404). When any other errors occur, a PersonioApiError is raised.

Parameters

• path – the URL path for this request (relative to the Personio API base URL)

• method – the HTTP request method (default: GET)

• params – dictionary of URL parameters (optional)

• auth_rotation – set to True, if authentication keys should be rotated during this request (default: False for image requests)

Returns

the image (bytes) or None, if no image is available

request_json(path: str, method='GET', params: Optional[Dict[str, Any]] = None, data: Optional[Dict[str, Any]] = None, auth_rotation=True) → Dict[str, Any]

Make a request against the Personio API, expecting a json response. Returns the parsed json response as dictionary. Will raise a PersonioApiError if the request fails.

Parameters

• path – the URL path for this request (relative to the Personio API base URL)

• method – the HTTP request method (default: GET)

• params – dictionary of URL parameters (optional)

• data – dictionary of data to send in the request body (optional)

• auth_rotation – set to True, if authentication keys should be rotated during this request (default: True for json requests)

Returns

the parsed json response, when the request was successful, or a PersonioApiError

request_paginated(path: str, method='GET', params: Optional[Dict[str, Any]] = None, data: Optional[Dict[str, Any]] = None, auth_rotation=True, limit=200) → Dict[str, Any]

Make a request against the Personio API, expecting a json response that may be paginated, i.e. not all results might have been returned after the first request. Will continue to make requests until no more results are provided by the Personio API. Returns the parsed json response as dictionary. Will raise a PersonioApiError if the request fails.

Parameters

• path – the URL path for this request (relative to the Personio API base URL)

• method – the HTTP request method (default: GET)

• params – dictionary of URL parameters (optional)

• data – dictionary of data to send in the request body (optional)

• auth_rotation – set to True, if authentication keys should be rotated during this request (default: True for json requests)

• limit – the max. number of items to return in response to a single request. A higher limit means fewer requests will be made (though there is an upper bound that is enforced on the server side)

Returns

the parsed json response, when the request was successful, or a PersonioApiError

search(query: str, active_only=True) → List[personio_py.models.Employee]

Execute a search on the search index.

If the index does not exist, or has been invalidated or is expired, the full list of employees will be requested from the API.

During the search we perform a case insensitive match on the keywords in the search index. All tokens of the query will be matched individually. Tokens are separated by whitespace. A full match (i.e. all tokens match the keywords in order) is preferred over a partial match (only one or more tokens match).

For more details, please refer to SearchIndex.

Parameters

• query – the query string

• active_only – exclude inactive employees from the results (default: yes)

Returns

the list of employees that matches the search query

search_first(query: str, active_only=True) → Optional[personio_py.models.Employee]

Execute a search on the search index and return the first result (if there is one) or None.

This is basically the “I’m Feeling Lucky” button. For details about the search function, please refer to SearchIndex.

Parameters

• query – the query string

• active_only – exclude inactive employees from the results (default: yes)

Returns

the first search result or None, if there were no results

update_attendance(attendance: personio_py.models.Attendance)

Update an existing attendance record

Either an attendance id or o remote query is required. Remote queries are only executed if required. An Attendance object returned by get_attendances() include the attendance id. DO NOT SET THE ID YOURSELF.

Parameters

attendance – The Attendance object holding the new data.

Raises

ValueError: If a query is required but not allowed or the query does not provide exactly one result.

update_employee(employee: personio_py.models.Employee)

placeholder; not ready to be used

update_project(project: personio_py.models.Project) → personio_py.models.Project

Updates a project record on the Personio servers.

Parameters

project – The project object to be updated

Raises

PersonioErrror – If the project could not be created on the Personio servers

models

Definition of ORMs for objects that are available in the Personio API

class personio_py.models.Absence(client: Personio = None, dynamic: Dict[str, Any] = None, dynamic_raw: List[DynamicAttr] = None, id_: int = None, status: str = None, comment: str = None, start_date: datetime.datetime = None, end_date: datetime.datetime = None, days_count: float = None, half_day_start: bool = False, half_day_end: bool = False, time_off_type: personio_py.models.AbsenceType = None, employee: personio_py.models.ShortEmployee = None, created_by: str = None, certificate: personio_py.models.Certificate = None, created_at: datetime.datetime = None, updated_at: datetime.datetime = None, **kwargs)

Bases: personio_py.models.WritablePersonioResource

to_body_params()

class personio_py.models.AbsenceEntitlement(id_: Optional[int] = None, name: Optional[str] = None, entitlement: Optional[float] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.AbsenceType(id_: Optional[int] = None, name: Optional[str] = None, category: Optional[str] = None, **kwargs)

Bases: personio_py.models.PersonioResource

to_dict(nested=False) → Dict[str, Any]

Convert this PersonioResource to a dictionary that has the same structure as the json data from the Personio API.

Parameters

nested – indicate that this resource is part of a nested dictionary (Personio resources can have a different serialization when they are part of a nested dictionary…)

Returns

the Personio resource as dictionary (same structure as in the Personio API)

class personio_py.models.Attendance(client: Personio = None, dynamic: Dict[str, Any] = None, dynamic_raw: List[DynamicAttr] = None, id_: int = None, employee_id: int = None, date: datetime.datetime = None, start_time: str = None, end_time: str = None, break_duration: int = None, comment: str = None, is_holiday: bool = None, is_on_time_off: bool = None, **kwargs)

Bases: personio_py.models.WritablePersonioResource

to_body_params(patch_existing_attendance=False)

Return the Attendance object in the representation expected by the Personio API

For an attendance record to be created all_values_required needs to be True. For patch operations only the attendance id is required, but it is not included into the body params.

:param patch_existing_attendance Get patch body. If False a create body is returned.

to_dict(nested=False) → Dict[str, Any]

Convert this PersonioResource to a dictionary that has the same structure as the json data from the Personio API.

Parameters

nested – indicate that this resource is part of a nested dictionary (Personio resources can have a different serialization when they are part of a nested dictionary…)

Returns

the Personio resource as dictionary (same structure as in the Personio API)

class personio_py.models.Certificate(status: Optional[str] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.CostCenter(id_: Optional[int] = None, name: Optional[str] = None, percentage: Optional[float] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.Department(id_: Optional[int] = None, name: Optional[str] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.DynamicAttr(field_id, label, value)

Bases: NamedTuple

clone(new_value: Optional[Any] = None)

field_id: int

Alias for field number 0

classmethod from_attributes(d: Dict[str, Dict[str, Any]]) → List[personio_py.models.DynamicAttr]

classmethod from_dict(key: str, d: Dict[str, Any]) → personio_py.models.DynamicAttr

label: str

Alias for field number 1

classmethod to_attributes(dyn_attrs: List[personio_py.models.DynamicAttr]) → Dict[str, Dict[str, Any]]

to_dict() → Dict[str, Any]

value: Any

Alias for field number 2

class personio_py.models.Employee(client: Personio = None, dynamic: Dict[str, Any] = None, dynamic_raw: List[DynamicAttr] = None, id_: int = None, first_name: str = None, last_name: str = None, email: str = None, gender: str = None, status: str = None, position: str = None, supervisor: personio_py.models.ShortEmployee = None, employment_type: str = None, weekly_working_hours: str = None, hire_date: datetime.datetime = None, contract_end_date: datetime.datetime = None, termination_date: datetime.datetime = None, termination_type: str = None, termination_reason: str = None, probation_period_end: datetime.datetime = None, created_at: datetime.datetime = None, last_modified_at: datetime.datetime = None, subcompany: str = None, office: personio_py.models.Office = None, department: personio_py.models.Department = None, cost_centers: List[personio_py.models.CostCenter] = None, holiday_calendar: personio_py.models.HolidayCalendar = None, absence_entitlement: List[personio_py.models.AbsenceEntitlement] = None, work_schedule: personio_py.models.WorkSchedule = None, fix_salary: float = None, fix_salary_interval: str = None, hourly_salary: float = None, vacation_day_balance: float = None, last_working_day: datetime.datetime = None, profile_picture: str = None, team: personio_py.models.Team = None, **kwargs)

Bases: personio_py.models.WritablePersonioResource, personio_py.models.LabeledAttributesMixin

picture(client: Personio = None, width: int = None) → bytes

class personio_py.models.HolidayCalendar(id_: Optional[int] = None, name: Optional[str] = None, country: Optional[str] = None, state: Optional[str] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.LabeledAttributesMixin(*args, **kwargs)

Bases: personio_py.models.PersonioResource

Personio Resources that use the LabeledAttributesMixin expect data in a different format than the regular key-value pattern. Example:

"first_name": {
  "label": "First name",
  "value": "Richard"
}

Instead of "first_name": "Richard" we get a dictionary where the label of the field and its value are attributes of another dictionary.

This format is currently used by Employee and ShortEmployee and was probably chosen because Personio allows to specify custom fields for employees with custom label names.

to_dict(nested=False) → Dict[str, Any]

Convert this PersonioResource to a dictionary that has the same structure as the json data from the Personio API.

Parameters

nested – indicate that this resource is part of a nested dictionary (Personio resources can have a different serialization when they are part of a nested dictionary…)

Returns

the Personio resource as dictionary (same structure as in the Personio API)

class personio_py.models.Office(id_: Optional[int] = None, name: Optional[str] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.PersonioResource(client: Personio = None, **kwargs)

Bases: object

classmethod from_dict(d: Dict[str, Any], client: Personio = None) → __class__

Create an instance of this PersonioResource from the specified dictionary data, which is parsed version of the json data from the Personio API.

Parameters

• d – create an instance from this data

• client – the Personio API client (optional). Used to provide additional operations on this resource, when available (e.g. request more data or write changes back to Personio)

Returns

a new instance of this class based on the provided data

to_dict(nested=False) → Dict[str, Any]

Convert this PersonioResource to a dictionary that has the same structure as the json data from the Personio API.

Parameters

nested – indicate that this resource is part of a nested dictionary (Personio resources can have a different serialization when they are part of a nested dictionary…)

Returns

the Personio resource as dictionary (same structure as in the Personio API)

to_tuple() → Tuple

class personio_py.models.Project(client: Personio = None, dynamic: Dict[str, Any] = None, dynamic_raw: List[DynamicAttr] = None, id_: int = None, name: str = None, active: bool = None, created_at: datetime.datetime = None, updated_at: datetime.datetime = None, **kwargs)

Bases: personio_py.models.WritablePersonioResource

to_body_params()

to_dict(nested=False) → Dict[str, Any]

Convert this PersonioResource to a dictionary that has the same structure as the json data from the Personio API.

Parameters

nested – indicate that this resource is part of a nested dictionary (Personio resources can have a different serialization when they are part of a nested dictionary…)

Returns

the Personio resource as dictionary (same structure as in the Personio API)

class personio_py.models.ShortEmployee(client: Personio = None, id_: int = None, first_name: str = None, last_name: str = None, email: str = None, **kwargs)

Bases: personio_py.models.LabeledAttributesMixin

resolve(client: Personio = None) → Employee

class personio_py.models.Team(id_: Optional[int] = None, name: Optional[str] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.WorkSchedule(id_: Optional[int] = None, name: Optional[str] = None, valid_from: Optional[datetime.datetime] = None, monday: Optional[datetime.timedelta] = None, tuesday: Optional[datetime.timedelta] = None, wednesday: Optional[datetime.timedelta] = None, thursday: Optional[datetime.timedelta] = None, friday: Optional[datetime.timedelta] = None, saturday: Optional[datetime.timedelta] = None, sunday: Optional[datetime.timedelta] = None, **kwargs)

Bases: personio_py.models.PersonioResource

class personio_py.models.WritablePersonioResource(client: Personio = None, dynamic: List[DynamicAttr] = None, dynamic_fields: List[personio_py.mapping.DynamicMapping] = None, **kwargs)

Bases: personio_py.models.PersonioResource

create(client: Personio = None)

delete(client: Personio = None)

classmethod from_dict(d: Dict[str, Any], client: Personio = None, dynamic_fields: List[personio_py.mapping.DynamicMapping] = None) → __class__

Create an instance of this PersonioResource from the specified dictionary data, which is parsed version of the json data from the Personio API.

Parameters

• d – create an instance from this data

• client – the Personio API client (optional). Used to provide additional operations on this resource, when available (e.g. request more data or write changes back to Personio)

Returns

a new instance of this class based on the provided data

to_dict(nested=False) → Dict[str, Any]

Convert this PersonioResource to a dictionary that has the same structure as the json data from the Personio API.

Parameters

nested – indicate that this resource is part of a nested dictionary (Personio resources can have a different serialization when they are part of a nested dictionary…)

Returns

the Personio resource as dictionary (same structure as in the Personio API)

update(client: Personio = None)

personio_py.models.get_client(resource: personio_py.models.PersonioResource, client: Personio = None)

mapping

mappings from Personio API fields to Python data types and vice versa are defined in this module

class personio_py.mapping.BooleanFieldMapping(api_field: str, class_field: str)

Bases: personio_py.mapping.FieldMapping

deserialize(value: str, **kwargs) → bool

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(value: bool) → bool

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.DateFieldMapping(api_field: str, class_field: str)

Bases: personio_py.mapping.FieldMapping

deserialize(value: str, **kwargs) → datetime.date

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(value: datetime.datetime) → str

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.DateTimeFieldMapping(api_field: str, class_field: str)

Bases: personio_py.mapping.FieldMapping

deserialize(value: str, **kwargs) → datetime.datetime

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(value: datetime.datetime) → str

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.DurationFieldMapping(api_field: str, class_field: str)

Bases: personio_py.mapping.FieldMapping

deserialize(value: str, **kwargs) → datetime.timedelta

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

pattern = re.compile('\\d\\d?:\\d\\d')

serialize(value: datetime.timedelta) → str

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

classmethod str_to_timedelta(s: str) → datetime.timedelta

class personio_py.mapping.DynamicMapping(field_id: int, alias: str, data_type: Type[personio_py.mapping.T])

Bases: NamedTuple

Defines a mapping from a dynamic field to a more memorable name and its actual data type, so that it may be converted into a proper python type, if possible.

alias: str

a more memorable name than the field_id, will be used as dictionary key

data_type: Type[personio_py.mapping.T]

the data type of the field, for automatic conversion (e.g. str to datetime)

field_id: int

the id number of the dynamic field, e.g. for ‘dynamic_123456’, field_id=123456

get_field_mapping() → personio_py.mapping.FieldMappingType

class personio_py.mapping.FieldMapping(api_field: str, class_field: str, field_type: Type[personio_py.mapping.T])

Bases: object

A generic mapping from a Personio API field to a Python object. The default implementation works great for strings, but for more complex types, please refer to the subclasses of FieldMapping.

Parameters

• api_field – name of the field in the Personio API

• class_field – name of the attribute in the target Python object

• field_type – data type of the field

deserialize(value: Union[str, Dict], **kwargs) → personio_py.mapping.T

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(value: personio_py.mapping.T) → Union[str, Dict]

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.ListFieldMapping(item_mapping: personio_py.mapping.FieldMapping)

Bases: personio_py.mapping.FieldMapping

deserialize(values: List[Any], client: Personio = None) → List[Any]

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(values: List[Any]) → List[Any]

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.MultiTagFieldMapping(api_field: str, class_field: str)

Bases: personio_py.mapping.FieldMapping

deserialize(value: str, **kwargs) → List[str]

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(values: List[str]) → str

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.NumericFieldMapping(api_field: str, class_field: str, field_type=<class 'float'>)

Bases: personio_py.mapping.FieldMapping

deserialize(value: Union[int, float, str], **kwargs) → Union[int, float, str]

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(value: Union[int, float, str]) → Union[int, float, str]

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

class personio_py.mapping.ObjectFieldMapping(api_field: str, class_field: str, field_type: Type[PersonioResourceType])

Bases: personio_py.mapping.FieldMapping

deserialize(value: Dict, client: Personio = None) → Optional[PersonioResourceType]

Deserialize the Personio API value to a more useful Python data type.

Parameters

• value – the value as provided by the Personio API

• kwargs – additional parameters (to be used by subclasses)

Returns

the deserialized value

serialize(value: PersonioResourceType) → Dict

Serialize the parsed value to the format that the Personio API expects.

Parameters

value – the value to serialize

Returns

the serialized value

Errors

exception personio_py.PersonioError

Bases: Exception

A generic error caused by personio-py

exception personio_py.MissingCredentialsError

Bases: personio_py.errors.PersonioError

you are missing some strictly required credentials

exception personio_py.PersonioApiError(status_code: int, message: str, error_code: Optional[int] = None, errors: Optional[Dict[str, Any]] = None, response: Optional[requests.models.Response] = None)

Bases: personio_py.errors.PersonioError

An error response from the Personio HTTP API

Parameters

• status_code – the HTTP status code of the API response

• message – the error message from the Personio API

• error_code – the error code that is provided with the Personio API response (not the HTTP status code!)

• errors – details about the errors that are provided by the Personio API as dictionary

• response – the HTTP response

classmethod from_response(response: requests.models.Response)

Creates a PersonioApiError from the specified HTTP response.

Parameters

response – a HTTP error response from Personio

Returns

a PersonioApiError that matches the HTTP error

exception personio_py.UnsupportedMethodError(method: str, clazz: Type)

Bases: personio_py.errors.PersonioError

this method is not supported by this class (but it might be by a similar one)