Skip to main content

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 20240723: ServiceAPI: acquire the fstags automatically at init.

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, the PlayOnAPI defines this as f'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(*a, upd: Optional[cs.upd.Upd] = <function uses_upd.<locals>.<lambda> at 0x102fe7060>, **kw): 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 from self.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, default False (raise if not 200)
  • cookies: optional cookie jar, default from self.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 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

cs_service_api-20240723.tar.gz (4.9 kB view details)

Uploaded Source

Built Distribution

cs.service_api-20240723-py3-none-any.whl (5.5 kB view details)

Uploaded Python 3

File details

Details for the file cs_service_api-20240723.tar.gz.

File metadata

  • Download URL: cs_service_api-20240723.tar.gz
  • Upload date:
  • Size: 4.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.0

File hashes

Hashes for cs_service_api-20240723.tar.gz
Algorithm Hash digest
SHA256 5723d8caf1914d150ce36eb8187f67760d226c96f0bca860fb1e3c1602107484
MD5 ec2896f325d90565bb4d7c1c4ef982da
BLAKE2b-256 f7dffc591071cac6dd155159f57d67989233a4f1fec4938f18c2cbc963c739dc

See more details on using hashes here.

File details

Details for the file cs.service_api-20240723-py3-none-any.whl.

File metadata

File hashes

Hashes for cs.service_api-20240723-py3-none-any.whl
Algorithm Hash digest
SHA256 0b37516e40e34db5150ce93290b5477187eee7f7ac088dc24dbc2a97c5751b2a
MD5 951e51ff27873aea1894032c95e6c8d9
BLAKE2b-256 38ff058ab7ff98f5e8ea6a375d47ea3f33021180d8b89c68ba3585a21f35268a

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page