Package: restsession
restsessionHTTP Session package for RESTful API consumption. This project is a wrapper for the Python "requests" library that incorporates features that normally must be added for each project such a automatic Retry support, Base URL sessions, and non-standard authorization header removal on cross-domain redirects. Configuration for each feature is performed by modifying object attributes for the RestSession instance.Two classes are provided for use:RestSessionandRestSessionSingleton.RestSessionis the class that you will likely use most often, and instantiation is identical to therequests_toolbelt.sessions.BaseURLSessionclass.You might find theRestSessionSingletonclass useful if you have modules in a larger project that must make REST API requests to an endpoint using common attributes, such as authentication. Instantiating and configuring a RestSessionSingleton instance in your project allows you to access the single instance, in any module, and perform requests without re-defining the same attributes.This project exists because I frequently create projects that userequestsin the same manner, and I got tired of repeating myself :smiley:UsageInstances can be created explicitly or using a context manager. All methods from the requests library should be available for use.Explicit implementation example:fromrestsessionimportRestSessionsession=RestSession()result=session.get("https://example.local/path/to/resource")ifresult.ok:# Do something on successOr, for a Singleton session:fromrestsessionimportRestSessionSingletonsession=RestSessionSingleton()result=session.get("https://example.local/path/to/resource")ifresult.ok:# Do something on successBase URL SessionFor projects intended to interact with a single endpoint (for example, RESTCONF on a single network device), Base URL sessions are supported. Base URL sessions allow you to instantiate the class with a common path, and all subsequent requests are made to a path relative to the Base URL. Example:# Example RESTCONF usagefromrestsessionimportRestSessionsession=RestSession(base_url="https://network.device/restconf/data/Cisco-IOS-XE-native:native/")session.auth=("username","password")session.headers.update({"Content-Type":"application/yang-data+json","Accept":"application/yang-data+json"})result=session.get("interface/GigabitEthernet=1")print(result.json())Note the trailing slash (/) on the Base URL and the lack of leading slash in the target URL!This is due to the behavior ofurllib.parse.urljoin, used to generate the final URL. This behavior can be overridden using thealways_relative_urloption (see Attributes, below).Attributes and DefaultsRequest behaviors (commonly modified):All attributes are OPTIONAL. Defaults are set, but can be overridden by modifying the attribute value.base_url(string): Any valid URL to be used as the base URL for subsequent requests. URLs specified for individual requests should be supplied relative to the base URL, when defined.Default: Nonealways_relative_url(bool): Override theurllib.parse.urljoindefault behavior and assume that any path is relative to the base URL, if one has been defined. This is to reduce headaches which occur from trying to figure out why a path isn't being retrieved because of a missing trailing slash / present leading slash.Default: Trueauth(tuple | requests.auth.AuthBase): If provided as a tuple(username, password), specify Basic Authorization for the session. Alternately accepts a custom auth class of typerequests.auth.AuthBase.Default: Noneremove_headers_on_redirect(list): List of custom auth headers to be removed on cross-domain redirect.Default: Nonebackoff_factor(float): Exponential backoff factor for retries when a Retry-After header was not returned by the server.Default: 0.3headers(dict): Headers to include with the request.Note: useheaders.update()to leave existing headers intact; explicitly setting headers will override any previously defined or default headers.Default: Content-Type and Accept set to application/json. User-Agent and Keepalive are set.max_reauth(int): Maximum number of times to attempt to reauthenticate and retry an unauthorized request before an Exception is raised.Default: 3max_redirects(int): Maximum number of redirects to follow before an Exception is raised.Default: 16respect_retry_headers(bool): If a Retry-After header is sent by the server, whether to honor the value. If False, immediately retry the request.Default: Trueretries(int): Maximum number of retries to perform before an Exception is raised.Default: 3timeout(float | tuple[float,float]): Request timeout, in seconds. If provided as a tuple, the first value is the connection timeout and the second value is the read timeout (amount of time to wait for data to be returned by the server). A single value uses the same timeout for connect and read.Default: 3verify(bool): Whether to perform TLS certificate chain validation.Security risk! Only set to False for development purposes, or if you know the risks of disabling TLS validation!Default: TrueAdditional attributes (most users can ignore these):request_exception_hook(Callable): Callable to handle (and raise) exceptions when request errors are encountered.Default: see "Exceptions", below.response_hooks(Callable):[Advanced usage]Callable to be invoked after a response is received from the server.Default: Noneretry_method_list(list[str]): List of HTTP methods for which retries should be attempted when a status matchingretry_status_code_listis received.Default: HEAD, GET, PUT, POST, PATCH, DELETE, OPTIONS, TRACEretry_status_code_list(list[int]): List of HTTP status codes that will trigger an automatic retry of the request.Default: 408 (Request timeout), 413 (Payload too large), 429 (Too many requests), 503 (Service unavailable)safe_arguments(current unused) (bool): If an invalid value is supplied for an attribute, ignore and use the last good value instead of raising an Exception.Default: TrueExceptionsProject specific:The following project-specific exceptions have been defined and can be imported to your code from the restsession.exceptions module:RestSessionErroris the base exception class from which other exceptions are derived.InvalidParameterErrorwill be raised if an invalid value or data type is provided for an attribute.InitializationErrorwill be raised on initial class instantiation if there is a error validating supplied parameters. Currently, the only parameter accepted isbase_url, so verify that a valid URL has been supplied if this exception is raised.Request exceptions:By default, exceptions raised by therequestslibrary will be caught and re-raised. See therequests.exceptions documentationfor more information.