api-interface-base (1.2.0)
Installation
pip install --index-url About this package
API Interface bases classes, implementations, type defs, etc
API Interface: Base classes, Implementations and Type Definitions
These are all the base clases on which other API implementations are based off
Install
This package should not be installed on its own, but the API Package for the Interface that is needed should be used.
Class ApiSettingsLoader
Interface to load settings from a settings.cfg file
Settings file layout
[Api:<Name>]
# type is either "screendragon" or "zac" at the moment
type=
# for the OAuth string
client_id=
client_secret=
# Only ZAC needs username and password too, they do not need to be set for Screendragon
username=
password=
# Acces URL is hostname + appname + api_apth: to this the final API url is added
# Hots name to connect to
hostname=
# app name
appname=
# api path
api_path=
# Optional: Proxy name "Proxy:<name>"
proxy=
[Proxy:<Name>]
# socks5 or socks5h only allowed
type=socks5
host=
port=
Api settings start wth "Api:" and proxy settings start with "Proxy:"
constants
- IDENT_SPLIT_CHARACTER: the split character for any string content key value splits
- ELEMENT_SPLIT_CHARACTER: entry value, for service name list in proxy argument
- PROXY_TYPES: the valid list of proxy types
- SCREENDRAGON: the string for the screendragon api type
- ZAC: the string for the zac api type
public methods
api_settings_loader
This must be called before proxy_settings_loader
def api_settings_loader(
self,
api_config_name: str,
interface_type: str,
) -> None:
- api_config_name: The config name to load, this is the part after "Api:"
- interface_type: either screndragon or zac, the constant ZAC and SCRENDRAGON can be used for this
The function will throw ValueError if it cannot load the settings
All settings are stored in the internal dictionary "settings"
proxy_settings_loader
This has to be called after api_settings_loader
def proxy_settings_loader(self, args_proxy_list: list[str] | None = None) -> None:
Load the proxy data, if not args proxy list is defined, it will only use set proxies in the api settings, if an argument string is given it has to be the following format:
<proxy name>:<proxy type>:<proxy host>:<proxy port>:<api service>
load_api_settings_and_proxy
Main loader function for settings and proxy information
def load_api_settings_and_proxy(
self,
api_config_name_interface_type_list: list[tuple[str, str]],
args_proxy_list: list[str] | None = None
) -> None:
Parameter api_config_name_interface_type_list is a list of tuples, where the first entry is the Api config setting block name in the ini file and the second is the settings type.
- first tuple entry: The config name to load, this is the part after "Api:"
- second tuple entry: either screndragon or zac, the constant ZAC and SCRENDRAGON can be used for this
Parameter args_proxy_list is list of strings from the argument parser for override proxy settings, will be skipped if set to None
The string is the in following format:
[OFF-]<proxy name>[[:<proxy type>]:<host>:<port>][:<service>]
- proxy name must be a valid alphanumeric string, if prefixed with "OFF-" then the proxy will be turned off
- proxy type is socks5 or socks5h, all others will be error
- host and port are the host name or host ip and the target port, if one is set the ohter must be set
- service is a API service block to attach this proxy too, if not set will be attached to all
If entries inbetween are not set the need to be left blank with the spacer character ":"
For exmaple to set a ini defined proxy to a service:
proxy_name::::service_name
Everything at the end that is not set can be left out
For example to set a proxy for all
proxy_name
The "OFF-" prefix will turn off the proxy setting
For example to not use an ini set proxy
OFF-proxy_name
get_api_settings_combined
Settings need to be loaded with load_api_settings_and_proxy first
def get_api_settings_combined(self, interface_type: str, debug: bool = False) -> 'ApiSettingsCombined':
Load and return a settings dictionary for an interface type, the debug flag can be set to turn on the debug flag for the Api intrface
interface_type can be screendragon or zac and the constants ZAC or SCREENDRAGON can be used
Development
There are unit tests that need to pass by running
uv run pytest
They cover only the api_settings_loader.py file
- Settings load
- Proxy override load
- Exceptions
Implementations
- ApiCallThrottleInterface
Can be used to implement throttling and waiting
Typed Definitions
ApiSettings
- client_id: str
- client_secret: str
- username: str | None
- password: str | None
- hostname: str; base host name
- appname: str; app name to attach to host name
- api_path: str; api path attached to the hostname and appname
Note that client_id, client_secret always have to be set. username and password are optional depending on the auth method requested
RequestsSettings
- use_proxy: bool; flag to use proxy, proxy_settings must be set
- proxy_settings: dict[str, str] | None; according to requests settings https://requests.readthedocs.io/en/latest/user/advanced/#proxies
- connection_timeout: int; how many seconds before a connection will time out
- verify: bool; Verify SSL certificates
- cafile: str | None; Set an override CA file to use
TokenData
- access_token: str
- refresh_token: str
- expires_in: float
- token_type: str
- status: str; SUCCESS or FAIL
- message: str
ArgsDebug
- skip_masking: bool; do not mask any passwords or secrets
- debug: bool; turn on debug output
- verbose: int; DEPRECATED, not used
ApiSettingsCombined
Combined set
- args: ArgDebugs
- auth: ApiSettings
- requests_settings: RquestsSettings
Base classes
Class ApiSettings
The master api settings call, uses the "ApiSettingsCombined" dictionary
init with "ApiSettings" dictionary and "Logger" class
provides public methods:
- get_base_url
- get_api_url
Class ApiAuthorize
must be implemented to run the authorization and any token requests
constants
- EXPIRE_DEFAULT: 5min
- TOKEN_TYPE_DEFAULT: Bearer
- FAILURE: string "FAIL"
- SUCCESS: string "SUCCESS"
provides public methods:
- get_token_status: returns True if the token status is SUCCESS
- get_auth_header
- authorize: runs the authorization process
- get_token_data
abstract protected method
- _process_authorize: returns "TokenData"; must be implemented for the authentication
Class WebRequets
The main interface wrapper for all possible web call types, this is the main part that will be used
init with "ApiSettings" dict, "ApiAuthorize" class, "ApiCallThrottle" class and "Logger" class and type name for internal tracking
provides public methods
- call: interface for all calls, passes them on to protected method _general_requests and passes the output through protected method _output_filter to return the content. Returns none on error
provides abtract methods to be implemented
- _general_request: for all calls: must be implemented
- the following calls below if implemented just need to be passed through "call"
- read_call (get)
- write_call (post)
- delete_call (delete)
- update_call (put)
- patch_call (patch)
provides protected methods
- _output_filter
- _get_api_call_url
- _prepare_api_uri
Build and deploy
increase the version number in pyproject.toml file, create a tag and push to git. then run the commands below.
Access to git.egplusww.jp server is necessary to deploy builds
uv build
uv publish --index opj-pypi --token <token>