# personio-py
[](https://github.com/at-gmbh/personio-py/actions?query=workflow%3Abuild)
[](https://pypi.org/project/personio-py/)
[](https://pypi.org/project/personio-py/)
[](https://at-gmbh.github.io/personio-py/)
[](https://codecov.io/gh/at-gmbh/personio-py)
[](https://matrix.to/#/#personio-py:matrix.org)
[](https://github.com/at-gmbh/personio-py/blob/master/LICENSE)
**personio-py** is a lightweight [Personio](https://www.personio.de/) API client library for Python. Also, it's pretty intuitive to use. But don't take my word for it, please have a look:
```python
>>> from personio_py import Personio
>>> p = Personio(client_id='***', client_secret='***')
>>> ada = p.search_first("Ada")
>>> ada.last_name
'Lovelace'
>>> absences = p.get_absences(ada)
>>> len(absences)
12
>>> absences[0].to_dict()
{'id': 42, 'status': 'approved', 'start_date': '2020-08-01', 'end_date': '2020-08-16', ...}
```
**personio-py** aims to provide Python function wrappers and object mappings for all endpoints of the [Personio REST API](https://developer.personio.de/reference). Because personio-py is a third party library, and the REST API may change from time to time, we cannot guarantee that all functions are covered, but we try our best.
If something appears to be broken, please have a look at the [open issues](https://github.com/at-gmbh/personio-py/issues) and vote for an existing issue or create a new one, if you can't find an issue that describes your problem.
**📖 Documentation is available at [at-gmbh.github.io/personio-py](https://at-gmbh.github.io/personio-py/)**
## Features
* Aims to cover all functions of the Personio API (work in progress)
* Python function wrappers for all API endpoints as part of the Personio class
* Object mappings for all API resources, e.g. an Employee is an object with properties for all the information that is provided by the REST API.
* Completely transparent handling of authentication and key rotation
* Support for Type Hints
* Only one dependency: [requests](https://pypi.org/project/requests/)
## Getting Started
The package is available on [PyPI](https://pypi.org/project/personio-py/) and can be installed with
pip install personio-py
Now you can `import personio_py` and start coding. Please have a look at the [User Guide](https://at-gmbh.github.io/personio-py/guide.html) and the [Examples](https://at-gmbh.github.io/personio-py/examples.html) section for more details.
## Contributing
Contributions are very welcome! For our contribution guidelines, please have a look at [CONTRIBUTING.md](./CONTRIBUTING.md).
To set up your local development environment, please use a fresh virtual environment, then run
pip install -r requirements.txt -r requirements-dev.txt
This project is intended to be used as library, so there is no command line interface or stuff like that.
We use `pytest` as test framework. To execute the tests, please run
python setup.py test
To build a distribution package (wheel), please use
python setup.py dist
this will clean up the build folder and then run the `bdist_wheel` command.
Before contributing code, please set up the pre-commit hooks to reduce errors and ensure consistency
pip install -U pre-commit && pre-commit install
### PyPI Release
This project is released on [PyPI](https://pypi.org/project/personio-py/). Most of the tedious steps that are required to test & publish your release are automated by [CI pipelines](https://github.com/at-gmbh/personio-py/actions). All you have to do is to write your code and when the time comes to make a release, please follow these steps:
* update the program version in [`src/personio_py/version.py`](./src/personio_py/version.py)
* write a summary of your changes in [`CHANGELOG.md`](./CHANGELOG.md)
* add a tag on the master branch with the new version number preceded by the letter `v`, e.g. for version 1.0.0 the tag would be `v1.0.0`. To tag the head of the current branch, use `git tag v1.0.0`
* push your changes to github and don't forget to push the tag with `git push origin v1.0.0`
* now have a look at the [release pipeline](https://github.com/at-gmbh/personio-py/actions?query=workflow%3Arelease) on GitHub. If it finishes without errors, you can find your release on [TestPyPI](https://test.pypi.org/project/personio-py). Please verify that your release works as expected.
* Now for the live deployment on PyPI. To avoid mistakes, this is only triggered, when a release is published on GitHub first. Please have a look at the [Releases](https://github.com/at-gmbh/personio-py/releases) now; there should be a draft release with your version number (this was created by the CI pipeline which also made the TestPyPI release). Edit the draft release, copy the text you added to [`CHANGELOG.md`](./CHANGELOG.md) into the description field and publish it.
* After you publish the release, the [deploy pipeline](https://github.com/at-gmbh/personio-py/actions?query=workflow%3Adeploy) is triggered on GitHub. It will publish the release directly to [PyPI](https://pypi.org/project/personio-py/) where everyone can enjoy your latest features.
## API Functions
Since the [Personio API](https://developer.personio.de/reference/introduction) gets extended over time, personio-py usually only implements a subset of all available API features. This section gives an overview, which API functions are accessible through personio-py.
### Available
Authentication
* [`POST /auth`](https://developer.personio.de/reference/post_auth-1): fully transparent authentication handling
Employees
* [`GET /company/employees`](https://developer.personio.de/reference/get_company-employees): list all employees
* [`POST /company/employees`](https://developer.personio.de/reference/post_company-employees): create a new employee
* [`GET /company/employees/{id}`](https://developer.personio.de/reference/get_company-employees-employee-id): get the employee with the specified ID
* [`GET /company/employees/{id}/profile-picture/{width}`](https://developer.personio.de/reference/get_company-employees-employee-id-profile-picture-width): get the profile picture of the specified employee
Attendances
* [`GET /company/attendances`](https://developer.personio.de/reference/get_company-attendances): fetch attendance data for the company employees
* [`POST /company/attendances`](https://developer.personio.de/reference/post_company-attendances): add attendance data for the company employees
* [`DELETE /company/attendances/{id}`](https://developer.personio.de/reference/delete_company-attendances-id): delete the attendance entry with the specified ID
* [`PATCH /company/attendances/{id}`](https://developer.personio.de/reference/patch_company-attendances-id): update the attendance entry with the specified ID
Projects
* [`GET /company/attendances/projects`](https://developer.personio.de/reference/get_company-attendances-projects): provides a list of all company projects
* [`POST /company/attendances/projects`](https://developer.personio.de/reference/post_company-attendances-projects): creates a project into the company account
* [`DELETE /company/attendances/projects/{id}`](https://developer.personio.de/reference/delete_company-attendances-projects-id): deletes a project from the company account
* [`PATCH /company/attendances/projects/{id}`](https://developer.personio.de/reference/patch_company-attendances-projects-id): updates a project with the given data
Absences
* [`GET /company/time-off-types`](https://developer.personio.de/reference/get_company-time-off-types): get a list of available absences types
* [`GET /company/time-offs`](https://developer.personio.de/reference/get_company-time-offs): fetch absence data for the company employees
* [`POST /company/time-offs`](https://developer.personio.de/reference/post_company-time-offs): add absence data for the company employees
* [`GET /company/time-offs/{id}`](https://developer.personio.de/reference/get_company-time-offs-id): get the absence entry with the specified ID
* [`DELETE /company/time-offs/{id}`](https://developer.personio.de/reference/delete_company-time-offs-id): delete the absence entry with the specified ID
### Not yet implemented
* [`PATCH /company/employees/{id}`](https://developer.personio.de/reference/patch_company-employees-employee-id): update an existing employee entry
* [`GET /company/employees/{employee_id}/absences/balance`](https://developer.personio.de/reference/get_company-employees-employee-id-absences-balance): retrieve the absence balance for a specific employee
* [`GET /company/employees/custom-attributes`](https://developer.personio.de/reference/get_company-employees-custom-attributes): this endpoint is an alias for /company/employees/attributes
* [`GET /company/employees/attributes`](https://developer.personio.de/reference/get_company-employees-attributes): lists all the allowed attributes per API credentials including custom (dynamic) attributes.
* [`GET /company/absence-periods`](https://developer.personio.de/reference/get_company-absence-periods)
* [`POST /company/absence-periods`](https://developer.personio.de/reference/post_company-absence-periods)
* [`DELETE /company/absence-periods/{id}`](https://developer.personio.de/reference/delete_company-absence-periods-id)
* [`GET /company/document-categories`](https://developer.personio.de/reference/get_company-document-categories): this endpoint is responsible for fetching all document categories of the company
* [`POST /company/documents`](https://developer.personio.de/reference/post_company-documents): this endpoint is responsible for uploading documents for the company employees
* [`GET /company/custom-reports/reports`](https://developer.personio.de/reference/listreports): this endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe
* [`GET /company/custom-reports/reports/{report_id}`](https://developer.personio.de/reference/listreportitems): this endpoint provides you with the data of an existing Custom Report
* [`GET /company/custom-reports/columns`](https://developer.personio.de/reference/listcolumns): this endpoint provides human-readable labels for report table columns
* all of the [recruiting API](https://developer.personio.de/reference/introduction-1)
## Contact
Sebastian Straub (sebastian.straub [at] alexanderthamm.com)
Developed with ❤ at [Alexander Thamm GmbH](https://www.alexanderthamm.com/)
## License
Copyright 2020 Alexander Thamm GmbH
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Raw data
{
"_id": null,
"home_page": "https://github.com/at-gmbh/personio-py",
"name": "personio-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Sebastian Straub",
"author_email": "sebastian.straub@alexanderthamm.com",
"download_url": "https://files.pythonhosted.org/packages/12/f3/3c2d875128d3a4296a5e6a2817ce0c14ba9ab65af54de4e3dd7c5a1cc97b/personio-py-0.2.3.tar.gz",
"platform": "any",
"description": "# personio-py\n\n[](https://github.com/at-gmbh/personio-py/actions?query=workflow%3Abuild)\n[](https://pypi.org/project/personio-py/)\n[](https://pypi.org/project/personio-py/)\n[](https://at-gmbh.github.io/personio-py/)\n[](https://codecov.io/gh/at-gmbh/personio-py)\n[](https://matrix.to/#/#personio-py:matrix.org)\n[](https://github.com/at-gmbh/personio-py/blob/master/LICENSE)\n\n**personio-py** is a lightweight [Personio](https://www.personio.de/) API client library for Python. Also, it's pretty intuitive to use. But don't take my word for it, please have a look:\n\n```python\n>>> from personio_py import Personio\n>>> p = Personio(client_id='***', client_secret='***')\n>>> ada = p.search_first(\"Ada\")\n>>> ada.last_name\n'Lovelace'\n>>> absences = p.get_absences(ada)\n>>> len(absences)\n12\n>>> absences[0].to_dict()\n{'id': 42, 'status': 'approved', 'start_date': '2020-08-01', 'end_date': '2020-08-16', ...}\n```\n\n**personio-py** aims to provide Python function wrappers and object mappings for all endpoints of the [Personio REST API](https://developer.personio.de/reference). Because personio-py is a third party library, and the REST API may change from time to time, we cannot guarantee that all functions are covered, but we try our best.\n\nIf something appears to be broken, please have a look at the [open issues](https://github.com/at-gmbh/personio-py/issues) and vote for an existing issue or create a new one, if you can't find an issue that describes your problem.\n\n**\ud83d\udcd6 Documentation is available at [at-gmbh.github.io/personio-py](https://at-gmbh.github.io/personio-py/)**\n\n## Features\n\n* Aims to cover all functions of the Personio API (work in progress)\n* Python function wrappers for all API endpoints as part of the Personio class\n* Object mappings for all API resources, e.g. an Employee is an object with properties for all the information that is provided by the REST API.\n* Completely transparent handling of authentication and key rotation\n* Support for Type Hints\n* Only one dependency: [requests](https://pypi.org/project/requests/)\n\n## Getting Started\n\nThe package is available on [PyPI](https://pypi.org/project/personio-py/) and can be installed with\n\n pip install personio-py\n\nNow you can `import personio_py` and start coding. Please have a look at the [User Guide](https://at-gmbh.github.io/personio-py/guide.html) and the [Examples](https://at-gmbh.github.io/personio-py/examples.html) section for more details.\n\n## Contributing\n\nContributions are very welcome! For our contribution guidelines, please have a look at [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nTo set up your local development environment, please use a fresh virtual environment, then run\n\n pip install -r requirements.txt -r requirements-dev.txt\n\nThis project is intended to be used as library, so there is no command line interface or stuff like that.\n\nWe use `pytest` as test framework. To execute the tests, please run\n\n python setup.py test\n\nTo build a distribution package (wheel), please use\n\n python setup.py dist\n\nthis will clean up the build folder and then run the `bdist_wheel` command.\n\nBefore contributing code, please set up the pre-commit hooks to reduce errors and ensure consistency\n\n pip install -U pre-commit && pre-commit install\n\n### PyPI Release\n\nThis project is released on [PyPI](https://pypi.org/project/personio-py/). Most of the tedious steps that are required to test & publish your release are automated by [CI pipelines](https://github.com/at-gmbh/personio-py/actions). All you have to do is to write your code and when the time comes to make a release, please follow these steps:\n\n* update the program version in [`src/personio_py/version.py`](./src/personio_py/version.py)\n* write a summary of your changes in [`CHANGELOG.md`](./CHANGELOG.md)\n* add a tag on the master branch with the new version number preceded by the letter `v`, e.g. for version 1.0.0 the tag would be `v1.0.0`. To tag the head of the current branch, use `git tag v1.0.0`\n* push your changes to github and don't forget to push the tag with `git push origin v1.0.0`\n* now have a look at the [release pipeline](https://github.com/at-gmbh/personio-py/actions?query=workflow%3Arelease) on GitHub. If it finishes without errors, you can find your release on [TestPyPI](https://test.pypi.org/project/personio-py). Please verify that your release works as expected.\n* Now for the live deployment on PyPI. To avoid mistakes, this is only triggered, when a release is published on GitHub first. Please have a look at the [Releases](https://github.com/at-gmbh/personio-py/releases) now; there should be a draft release with your version number (this was created by the CI pipeline which also made the TestPyPI release). Edit the draft release, copy the text you added to [`CHANGELOG.md`](./CHANGELOG.md) into the description field and publish it.\n* After you publish the release, the [deploy pipeline](https://github.com/at-gmbh/personio-py/actions?query=workflow%3Adeploy) is triggered on GitHub. It will publish the release directly to [PyPI](https://pypi.org/project/personio-py/) where everyone can enjoy your latest features.\n\n## API Functions\n\nSince the [Personio API](https://developer.personio.de/reference/introduction) gets extended over time, personio-py usually only implements a subset of all available API features. This section gives an overview, which API functions are accessible through personio-py.\n\n### Available\n\nAuthentication\n\n* [`POST /auth`](https://developer.personio.de/reference/post_auth-1): fully transparent authentication handling\n\nEmployees\n\n* [`GET /company/employees`](https://developer.personio.de/reference/get_company-employees): list all employees\n* [`POST /company/employees`](https://developer.personio.de/reference/post_company-employees): create a new employee\n* [`GET /company/employees/{id}`](https://developer.personio.de/reference/get_company-employees-employee-id): get the employee with the specified ID\n* [`GET /company/employees/{id}/profile-picture/{width}`](https://developer.personio.de/reference/get_company-employees-employee-id-profile-picture-width): get the profile picture of the specified employee\n\nAttendances\n\n* [`GET /company/attendances`](https://developer.personio.de/reference/get_company-attendances): fetch attendance data for the company employees\n* [`POST /company/attendances`](https://developer.personio.de/reference/post_company-attendances): add attendance data for the company employees\n* [`DELETE /company/attendances/{id}`](https://developer.personio.de/reference/delete_company-attendances-id): delete the attendance entry with the specified ID\n* [`PATCH /company/attendances/{id}`](https://developer.personio.de/reference/patch_company-attendances-id): update the attendance entry with the specified ID\n\nProjects\n\n* [`GET /company/attendances/projects`](https://developer.personio.de/reference/get_company-attendances-projects): provides a list of all company projects\n* [`POST /company/attendances/projects`](https://developer.personio.de/reference/post_company-attendances-projects): creates a project into the company account\n* [`DELETE /company/attendances/projects/{id}`](https://developer.personio.de/reference/delete_company-attendances-projects-id): deletes a project from the company account\n* [`PATCH /company/attendances/projects/{id}`](https://developer.personio.de/reference/patch_company-attendances-projects-id): updates a project with the given data\n\nAbsences\n\n* [`GET /company/time-off-types`](https://developer.personio.de/reference/get_company-time-off-types): get a list of available absences types\n* [`GET /company/time-offs`](https://developer.personio.de/reference/get_company-time-offs): fetch absence data for the company employees\n* [`POST /company/time-offs`](https://developer.personio.de/reference/post_company-time-offs): add absence data for the company employees\n* [`GET /company/time-offs/{id}`](https://developer.personio.de/reference/get_company-time-offs-id): get the absence entry with the specified ID\n* [`DELETE /company/time-offs/{id}`](https://developer.personio.de/reference/delete_company-time-offs-id): delete the absence entry with the specified ID\n\n### Not yet implemented\n\n* [`PATCH /company/employees/{id}`](https://developer.personio.de/reference/patch_company-employees-employee-id): update an existing employee entry\n* [`GET /company/employees/{employee_id}/absences/balance`](https://developer.personio.de/reference/get_company-employees-employee-id-absences-balance): retrieve the absence balance for a specific employee\n* [`GET /company/employees/custom-attributes`](https://developer.personio.de/reference/get_company-employees-custom-attributes): this endpoint is an alias for /company/employees/attributes\n* [`GET /company/employees/attributes`](https://developer.personio.de/reference/get_company-employees-attributes): lists all the allowed attributes per API credentials including custom (dynamic) attributes.\n* [`GET /company/absence-periods`](https://developer.personio.de/reference/get_company-absence-periods)\n* [`POST /company/absence-periods`](https://developer.personio.de/reference/post_company-absence-periods)\n* [`DELETE /company/absence-periods/{id}`](https://developer.personio.de/reference/delete_company-absence-periods-id)\n\n* [`GET /company/document-categories`](https://developer.personio.de/reference/get_company-document-categories): this endpoint is responsible for fetching all document categories of the company\n* [`POST /company/documents`](https://developer.personio.de/reference/post_company-documents): this endpoint is responsible for uploading documents for the company employees\n* [`GET /company/custom-reports/reports`](https://developer.personio.de/reference/listreports): this endpoint provides you with metadata about existing custom reports in your Personio account, such as report name, report type, report date / timeframe\n* [`GET /company/custom-reports/reports/{report_id}`](https://developer.personio.de/reference/listreportitems): this endpoint provides you with the data of an existing Custom Report\n* [`GET /company/custom-reports/columns`](https://developer.personio.de/reference/listcolumns): this endpoint provides human-readable labels for report table columns\n* all of the [recruiting API](https://developer.personio.de/reference/introduction-1)\n\n## Contact\n\nSebastian Straub (sebastian.straub [at] alexanderthamm.com)\n\nDeveloped with \u2764 at [Alexander Thamm GmbH](https://www.alexanderthamm.com/)\n\n## License\n\n Copyright 2020 Alexander Thamm GmbH\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License.\n\n\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "a lightweight Personio API client",
"version": "0.2.3",
"project_urls": {
"Documentation": "https://at-gmbh.github.io/personio-py/",
"Homepage": "https://github.com/at-gmbh/personio-py",
"Source": "https://github.com/at-gmbh/personio-py",
"Tracker": "https://github.com/at-gmbh/personio-py/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "164b277c3a6d42565a6d5939baeaf88b935db0adb8ac0d28dcb6307752575087",
"md5": "e0fb2b8228dd254100db774012cb60ee",
"sha256": "4218b6614d7c0af50d49390f018c99ae4a9ab49b933d85667fd428594c2b0b9b"
},
"downloads": -1,
"filename": "personio_py-0.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0fb2b8228dd254100db774012cb60ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 29452,
"upload_time": "2023-05-05T14:14:21",
"upload_time_iso_8601": "2023-05-05T14:14:21.259078Z",
"url": "https://files.pythonhosted.org/packages/16/4b/277c3a6d42565a6d5939baeaf88b935db0adb8ac0d28dcb6307752575087/personio_py-0.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "12f33c2d875128d3a4296a5e6a2817ce0c14ba9ab65af54de4e3dd7c5a1cc97b",
"md5": "7ecdefe2be642f09d3610153f0923b69",
"sha256": "e2a49101063703e5b65108b608710371fa62c596ce93cc14b1b52b683797e42f"
},
"downloads": -1,
"filename": "personio-py-0.2.3.tar.gz",
"has_sig": false,
"md5_digest": "7ecdefe2be642f09d3610153f0923b69",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 27444,
"upload_time": "2023-05-05T14:14:22",
"upload_time_iso_8601": "2023-05-05T14:14:22.559268Z",
"url": "https://files.pythonhosted.org/packages/12/f3/3c2d875128d3a4296a5e6a2817ce0c14ba9ab65af54de4e3dd7c5a1cc97b/personio-py-0.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-05 14:14:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "at-gmbh",
"github_project": "personio-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "personio-py"
}
JSON
