Source code for diamondback.commons.RestClient

""" **Description**
        REST client instances define a client for simple REST service requests
        using the requests package.  An API and an elective dictionary of parameter
        strings are encoded to build a URL, elective binary or JSON data are
        defined in the body of a request, and a requests response containing JSON,
        text, or binary data is returned.

        Proxy, timeout, and URL definition are supported.

        Live makes a head request to a URL and detects a live service.

    **Example**
        
        ::
        
            from diamondback import RestClient
            from typing import Dict
            import numpy

            class TestClient( RestClient ) :

                def __init__( self ) -> None :
                    super( ).__init__( )
                    self.proxy = dict( http = '', https = '' )

                def add( self, json : Dict[ str, numpy.ndarray ] ) -> numpy.ndarray :
                    return self.request( 'get', 'test/add', json = json ).json( )

            client = TestClient( )
            client.url = 'http://127.0.0.1:8080'
            client.timeout = ( 10.0, 60.0 )  # connect, read
            value = client.add( dict( x = numpy.random.rand( 3 ), y = numpy.random.rand( 3 ) ) )

    **License**
        `BSD-3C.  <https://github.com/larryturner/diamondback/blob/master/license>`_
        © 2018 - 2022 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

    **Author**
        Larry Turner, Schneider Electric, Analytics & AI, 2020-10-22.
"""

from typing import Any, Dict
import requests

[docs]class RestClient( object ) : """ REST client. """ @property def live( self ) : """ live : bool. """ try : requests.request( method = 'head', url = self.url, proxies = self.proxy, timeout = self.timeout ) value = True except Exception : value = False return value @live.setter def live( self, live : bool ) : self._live = live @property def proxy( self ) : """ proxy : Dict[ str, str ]. """ return self._proxy @proxy.setter def proxy( self, proxy : Dict[ str, str ] ) : self._proxy = proxy @property def timeout( self ) : """ timeout : Any. """ return self._timeout @timeout.setter def timeout( self, timeout : Any ) : self._timeout = timeout @property def url( self ) : """ url : str. """ return self._url @url.setter def url( self, url : str ) : """ Url. """ if ( url ) : url = url.strip( '/' ) self._url = url def __init__( self ) -> None : """ Initialize. """ super( ).__init__( ) self._live = False self._proxy, self._timeout = { }, ( 10.0, 60.0 ) self._url = 'http://127.0.0.1:8080'
[docs] def request( self, method : str, api : str, item : Dict[ str, str ] = None, data : Any = None, json : Any = None ) -> requests.Response : """ Request client for simple REST service requests. An API and an elective dictionary of parameter strings are encoded to build a URL, elective binary or JSON data are defined in the body of a request, and a requests response containing JSON, text, or binary data is returned. Arguments : method : str - in ( 'delete', 'get', 'head', 'options', 'patch', 'post', 'put' ). api : str - relative to the URL. item : Dict[ str, str ]. data : Any. json : Any. Returns : value : requests.Response. """ if ( not method ) : raise ValueError( f'Method = {method}' ) method = method.lower( ) if ( method not in ( 'delete', 'get', 'head', 'options', 'patch', 'post', 'put' ) ) : raise ValueError( f'Method = {method}' ) if ( ( data ) and ( json ) ) : raise ValueError( f'Data = {data} JSON = {json}' ) api = api.strip( '/' ) url = self.url if ( api ) : url += '/' + api with requests.request( method = method, url = url, params = item, data = data, json = json, proxies = self.proxy, timeout = self.timeout ) as value : value.raise_for_status( ) return value