Substantial rewrite for efficiency and flexibilty; support for some new API calls

[strix-technica]

This is a substantial rewrite with two objectives in mind: to make as few back-end REST requests as possible (which is crucial in terms of avoiding sanctions against your account for abuse of Sure's infrastructure) and to make the API better-suited to programmatic applications.

A number of feature enhancements and additions have also been made. The principal contributions of this PR are:

• Performance and efficiency:
  • Introduce built-in disc-backed persistent caching with locking to complement pre-existing ETag if-none-match mechanism
  • Rate limiting (queries served from cache rather than block)
  • Reimplement pet timeline to avoid calls for data already held in the house timeline
  • House timeline now not required for other features (including pet status and curfew condition), so only update the timeline if you really need it.
  • Improved robustness:
  • Curfew lock condition now extracted directly from device status (which is now included in the REST response) rather than iterating over the house timeline which could result in unknown statuses, especially after the revised API or June 19 reduced the number of events returned per call.
  • Add pet location REST call rather than iterating over house timeline. For typical users, this means the same number of calls but with much smaller payload
  • The likelihood of an exception being thrown by the constructor is greatly reduced because it no longer invokes any network activity. This does mean that the API doesn't automatically update itself (see below) and also means that you can be selective about what you update to avoid unnecessary REST traffic.
  • Authorisation is automatically refreshed when required. It is not necessary to poll for the AuthToken.
  • Transient back-end errors (5xx) and not found errors (404) handled appropriately
  • Improved machine interface:
  • Exceptions thrown to deal with problems rather than returning results that could be construed as valid responses. This could be improved upon further, but there's better error-checking than there was.
  • Class is split into back-end component (SurePetFlapAPI) and separate query class (SurePetFlapMixin) query interface. SurePetFlap is the combination of the two, but users can create their own query mixins if they wish.
  • Use of enumerations better suited to machine clients rather than text strings for human consumption. These are turned into the same text strings as before by the query mixin.
  • Because credentials are cached along with pretty much everything else, the API can be instantiated with no constructor arguments at all once the cache has been initialised (which can be done with the CLI tool if convenient).
  • Added a simplistic but easily extensible CLI tool. Network activity is separated from queries, so the CLI can be invoked multiple times without generating any network activity.
  • Added support for multiple flaps per router (hub), multiple hubs per household and multiple households per account. To accommodate this change, a number of property methods (getters only) have been added to access the default household consistent with the interface as it stands before merge.
  • Add battery state call.
  • Add support for events: battery warning, unidentified animal movement, user added
  • Bug fixes, notably to print_timeline() method.

The code in this PR is not 100% backwards compatible. One or two methods have been renamed, but chances are not ones you may use directly.

The main change required by any user of this API is to enclose calls to any of the update methods inside with ...: context block. When the block exits, the cache is flushed back to disc. The cache is only locked for the duration of the context block, so you can query it as much as you like from as many instances as you like provided only one instance at any one time is performing an update. Example:

api = sure_petcare.SurePetFlap()
pet_id = # appropriate ID or code here
with api:
    # You are **strongly** encouraged to update only things you need to update.
    # `update_timeline()` is particularly expensive so, if you don't need it, don't call it.
    api.update_pet_status()
print( api.pets[pet_id]['name'], api.get_current_status api.get_current_status( pet_id ) )

[strix-technica]

@jmvedrine, you might be interested in this PR — especially if you plan to do any significant development of your own.

Thanks for the thumbs-up, @Timx85!

@rcastberg is a bit preoccupied with other stuff right now so I don't know when he might be able to deal with this PR. I don't know if it's possible to issue a PR against a different fork, but you each can manually merge these changes via the git command line if you want (ask if you need any pointers).

N/m, it is now merged so do update your forks. The REST API has changed a bit and I haven't updated the requests accordingly (yet), and if the old-style requests quit working you'll need to pull/merge to get the updates.

Good luck, and I hope this is of some use!