Skip to content

Commit

Permalink
Add design considerations
Browse files Browse the repository at this point in the history
  • Loading branch information
lognaturel committed Apr 29, 2024
1 parent ca0bfa1 commit fafb189
Showing 1 changed file with 15 additions and 0 deletions.
15 changes: 15 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,21 @@ Error types raised by pyODK are found in `errors.py`, which currently is only th

Note that pyODK does not attempt to wrap every possible error condition, so if needed, broader exception handling should be included in your script / app.

## Design considerations
Our goal with pyODK is to support the most common Central API functionality in an easy-to-use, high-level way. Because we expose [HTTP verb methods](https://getodk.github.io/pyodk/http-methods/), we don't feel the need to add explicit support for the whole Central API.

Here are some points to think about when considering adding new methods to pyODK:

* Is it common enough to warrant a designed method or can we show examples using the HTTP methods if needed?
* For example, we currently consider manipulating form drafts directly out of scope but `client.forms.update` implicitly creates and publishes a draft
* Do people take this action independently or is it always part of reaching some broader goal?
* What pyODK class does it best fit in?
* For example, form versions are subresources on Central backend but in this library, methods that deal with form versions can be in the `forms` class directly since we’re not going to expose many of them
* How do people talk about the action that’s being performed? How do ODK docs and Central frontend talk about it?
* For example, documentation has the concept of "submission edits" so use `client.submissions.edit` rather than update
* Value expressiveness and consistency with ODK concepts over pyODK internal consistency
* What actually needs to be commonly configured? Starting by exposing a subset of parameters and naming/typing them carefully is ideal.

## Contribute

See issues for additions to `pyodk` that are under consideration. Please file new issues for any functionality you are missing.
Expand Down

0 comments on commit fafb189

Please sign in to comment.