ServiceAPI, a base class for APIs which talk to a service, typically a web service via HTTP.
Project description
ServiceAPI, a base class for APIs which talk to a service, typically a web service via HTTP.
Latest release 20241007: HTTPServiceAPI.suburl: support interruption by RunState.cancel.
An instance of a ServiceAPI
embodies some basic features
that feel common to web based services:
- a notion of a login
- local state, an
SQLTags
for data about entities of the service - downloads, if that is a thing, with
FSTags
for file annotations
Class HTTPServiceAPI(ServiceAPI)
HTTPServiceAPI
base class for other APIs talking to HTTP services.
Subclasses must define:
API_BASE
: the base URL of API calls. For example, thePlayOnAPI
defines this asf'https://{API_HOSTNAME}/v3/'
.
HTTPServiceAPI.json(self, suburl, _response_encoding=None, **kw)
:
Request suburl
from the service, by default using a GET
.
Return the result decoded as JSON.
Parameters are as for HTTPServiceAPI.suburl
.
HTTPServiceAPI.suburl(self, suburl, *, _base_url=None, _method='GET', _no_raise_for_status=False, cookies=None, headers=None, runstate: Optional[cs.resources.RunState] = <function uses_runstate.<locals>.<lambda> at 0x10f9202c0>, upd, **rqkw)
:
Request suburl
from the service, by default using a GET
.
The suburl
must be a URL subpath not commencing with '/'
.
Keyword parameters:
_base_url
: the base request domain, default fromself.API_BASE
_method
: the request method, default'GET'
_no_raise_for_status
: do not raise an HTTP error if the response status is not 200, defaultFalse
(raise if not 200)cookies
: optional cookie jar, default fromself.cookies
Other keyword parameters are passed to the requests method.
Class RequestsNoAuth(requests.auth.AuthBase)
This is a special purpose subclass of requests.auth.AuthBase
to apply no authorisation at all.
This is for services with their own special purpose authorisation
and avoids things like automatic netrc based auth.
Class ServiceAPI(cs.resources.MultiOpenMixin)
SewrviceAPI
base class for other APIs talking to services.
ServiceAPI.available(self) -> Set[cs.sqltags.SQLTagSet]
:
Return a set of the SQLTagSet
instances representing available
items at the service, for example purchased books
available to your login.
ServiceAPI.get_login_state(self, do_refresh=False) -> cs.sqltags.SQLTagSet
:
The login state, a mapping. Performs a login if necessary
or if do_refresh
is true (default False
).
ServiceAPI.login(self) -> Mapping
:
Do a login: authenticate to the service, return a mapping of related information.
Not all services require this and we expect such subclasses to avoid use of login-based methods.
ServiceAPI.login_expiry
:
Expiry UNIX time for the login state.
This implementation returns None
.
ServiceAPI.login_state
:
The login state, a mapping. Performs a login if necessary.
ServiceAPI.startup_shutdown(self)
:
Open/close the FSTags and SQLTags.
Release Log
Release 20241007: HTTPServiceAPI.suburl: support interruption by RunState.cancel.
Release 20240723: ServiceAPI: acquire the fstags automatically at init.
Release 20230703: Retry logic for requests.
Release 20230217: Initial release.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for cs.service_api-20241007-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 81f8f84dc3afd6a68e3aa07f03ffe5d2db27f56c86b16acb283d07110201d0a3 |
|
MD5 | 9291bffcb5c2618a8b2c37cf1069966e |
|
BLAKE2b-256 | 38180557fad5ffab895e1b6f8f54d3ddabd1b0bbaea8c338bcb2d21e5066c088 |