diamondback.commons.RestClient — diamondback documentation

# 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

    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'

        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