# PyPPMS
## PUMAPI - Python Interface
[Stratocore][3]'s *PPMS* booking system offers an API (the so-called *PUMAPI*, short for
PPMS Utility Management API) for fetching information from the booking system as well as
changing its state and properties.
This is a Python 3 package for talking to the *PUMAPI*.
## Usage Example
Fetch email addresses of all active users:
```Python
from pyppms import ppms
from credentials_ppms import PPMS_URL, PPMS_API_KEY
conn = ppms.PpmsConnection(PPMS_URL, PPMS_API_KEY)
print("Querying PPMS for emails of active users, can take minutes...")
emails = ppms.get_users_emails(active=True)
print(f"Got {len(emails)} email addresses from PPMS:")
print("\n".join(emails))
```
## Testing
Automated testing is described in the [`TESTING` document on github][2].
## Note
The PPMS API sometimes exposes a bit of a surprising behavior. During
development of the package, we came across several issues (this list is
certainly incomplete):
* HTTP status return code is always `200`, even on failed authentication.
* Results of queries are a mixture of CSV (with headers) and and text with
newlines (with no headers and therefore without structural information on
the data). JSON is implemented in some cases only.
* The CSV headers sometimes do contain spaces between the colons, sometimes
they don't.
* Some fields are quoted in the CSV output, some are not. Difficult to separate
the values since there are colons in the values too.
* Semantics of keys is not consistent. Sometimes `user` is the user id,
sometimes it refers to the user's full name.
* Using an invalid permission level (e.g. `Z`) with the `setright` action is
silently ignored by PUMAPI, the response is still `done` even though this
doesn't make any sense.
* There is no (obvious) robust way to derive the user id from the user's full
name that is returned e.g. by `getrunningsheet`, making it very hard to
cross-reference it with data from `getuser`.
* The result of the `getrunningsheet` query in general is not suited very well
for automated processing, it seems to be rather tailored for humans and
subject to (mis-) interpretation.
* Unfortunately `Username` and `Systemname` are not the unique id, they are
rather the full description. Therefore sometimes looping over all users and
systems is necessary.
* Some results have a very strange format - for example, the starting time of
the next booking is given as *minutes from now* instead of an absolute time.
* Official documentation is rather rudimentary, i.e. it contains almost no
information on what is returned in case wrong / invalid parameters are
supplied and similar situations.
## References
* [Imagopole PPMS Java client][1]
[1]: https://github.com/imagopole/ppms-http-client/blob/master/src/main/java/org/imagopole/ppms/api/PumapiRequest.java
[2]: https://github.com/imcf/pyppms/blob/master/TESTING.md
[3]: https://www.stratocore.com/
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/pyppms/",
"name": "pyppms",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "ppms,pumapi,booking-system,reservation-system",
"author": "Niko Ehrenfeuchter",
"author_email": "nikolaus.ehrenfeuchter@unibas.ch",
"download_url": "https://files.pythonhosted.org/packages/dd/dc/3f14079cdc83b7eff3f1b3ac509f7d3199bc86bc4224030ee36f450c280c/pyppms-3.2.1.tar.gz",
"platform": null,
"description": "# PyPPMS\n\n## PUMAPI - Python Interface\n\n[Stratocore][3]'s *PPMS* booking system offers an API (the so-called *PUMAPI*, short for\nPPMS Utility Management API) for fetching information from the booking system as well as\nchanging its state and properties.\n\nThis is a Python 3 package for talking to the *PUMAPI*.\n\n## Usage Example\n\nFetch email addresses of all active users:\n\n```Python\nfrom pyppms import ppms\nfrom credentials_ppms import PPMS_URL, PPMS_API_KEY\n\nconn = ppms.PpmsConnection(PPMS_URL, PPMS_API_KEY)\n\nprint(\"Querying PPMS for emails of active users, can take minutes...\")\nemails = ppms.get_users_emails(active=True)\nprint(f\"Got {len(emails)} email addresses from PPMS:\")\nprint(\"\\n\".join(emails))\n```\n\n## Testing\n\nAutomated testing is described in the [`TESTING` document on github][2].\n\n## Note\n\nThe PPMS API sometimes exposes a bit of a surprising behavior. During\ndevelopment of the package, we came across several issues (this list is\ncertainly incomplete):\n\n* HTTP status return code is always `200`, even on failed authentication.\n* Results of queries are a mixture of CSV (with headers) and and text with\n newlines (with no headers and therefore without structural information on\n the data). JSON is implemented in some cases only.\n* The CSV headers sometimes do contain spaces between the colons, sometimes\n they don't.\n* Some fields are quoted in the CSV output, some are not. Difficult to separate\n the values since there are colons in the values too.\n* Semantics of keys is not consistent. Sometimes `user` is the user id,\n sometimes it refers to the user's full name.\n* Using an invalid permission level (e.g. `Z`) with the `setright` action is\n silently ignored by PUMAPI, the response is still `done` even though this\n doesn't make any sense.\n* There is no (obvious) robust way to derive the user id from the user's full\n name that is returned e.g. by `getrunningsheet`, making it very hard to\n cross-reference it with data from `getuser`.\n* The result of the `getrunningsheet` query in general is not suited very well\n for automated processing, it seems to be rather tailored for humans and\n subject to (mis-) interpretation.\n* Unfortunately `Username` and `Systemname` are not the unique id, they are\n rather the full description. Therefore sometimes looping over all users and\n systems is necessary.\n* Some results have a very strange format - for example, the starting time of\n the next booking is given as *minutes from now* instead of an absolute time.\n* Official documentation is rather rudimentary, i.e. it contains almost no\n information on what is returned in case wrong / invalid parameters are\n supplied and similar situations.\n\n## References\n\n* [Imagopole PPMS Java client][1]\n\n[1]: https://github.com/imagopole/ppms-http-client/blob/master/src/main/java/org/imagopole/ppms/api/PumapiRequest.java\n[2]: https://github.com/imcf/pyppms/blob/master/TESTING.md\n[3]: https://www.stratocore.com/\n",
"bugtrack_url": null,
"license": "GPLv3",
"summary": "A Python package to communicate with Stratocore's PUMAPI.",
"version": "3.2.1",
"project_urls": {
"Documentation": "https://imcf.one/apidocs/pyppms/pyppms.html",
"Homepage": "https://pypi.org/project/pyppms/",
"Repository": "https://github.com/imcf/pyppms"
},
"split_keywords": [
"ppms",
"pumapi",
"booking-system",
"reservation-system"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "001718a8af741f49d3162066cb3622196c8da16b67fd58e5fadc9f4a7fd6aebd",
"md5": "5425a0384fe6ad8e5a5c18d700661f0b",
"sha256": "a7fc343923e452c37b0be61f8d57e9c65780d89fbc2d15964cc6d21c038163eb"
},
"downloads": -1,
"filename": "pyppms-3.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5425a0384fe6ad8e5a5c18d700661f0b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 21949,
"upload_time": "2023-06-30T08:33:16",
"upload_time_iso_8601": "2023-06-30T08:33:16.211582Z",
"url": "https://files.pythonhosted.org/packages/00/17/18a8af741f49d3162066cb3622196c8da16b67fd58e5fadc9f4a7fd6aebd/pyppms-3.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dddc3f14079cdc83b7eff3f1b3ac509f7d3199bc86bc4224030ee36f450c280c",
"md5": "8449b1abe8521ff2d5721e54c7a8f0c4",
"sha256": "1511362a34564161df0fc291d79dfdd57cabb03ddee4599a22f5ea4338c88dfd"
},
"downloads": -1,
"filename": "pyppms-3.2.1.tar.gz",
"has_sig": false,
"md5_digest": "8449b1abe8521ff2d5721e54c7a8f0c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 21125,
"upload_time": "2023-06-30T08:33:17",
"upload_time_iso_8601": "2023-06-30T08:33:17.454746Z",
"url": "https://files.pythonhosted.org/packages/dd/dc/3f14079cdc83b7eff3f1b3ac509f7d3199bc86bc4224030ee36f450c280c/pyppms-3.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-30 08:33:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "imcf",
"github_project": "pyppms",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyppms"
}
JSON
