diamondback.commons package — diamondback documentation

# diamondback.commons package

## Submodules

## diamondback.commons.Log module

Description

> A log instance formats and writes log entries with a specified level and stream using the loguru package. Log entries contain an ISO-8601 datetime and level. Dynamic stream redirection and level specification are supported.

> Log uses lazy initialization to coexist with loguru, and removes or creates loguru handlers only on explicit stream assignment or write. In lazy initialization an existing default loguru handler, with an identity equal to 0, and a stream assignment of sys.stdout is removed, and a new loguru handler with a stream assignment of sys.stdout and a level of ‘INFO’ is created.

> In stream assignments subsequent to initialization, only loguru handlers previously created by Log will be removed, as the design pattern does not support multicast. The ability to create and modify externally defined loguru handlers, multicast, and utilize any native loguru functionality is supported.

> Levels defined by loguru are supported, including custom definitions, which may have an associated numerical value greater than or equal to zero. The level may be dynamically modified without creating, deleting, or modifying a loguru handler.

> Singleton.

> Thread safe.

Example

>     from diamondback import Log
>     import io
>     import numpy
>     import sys

>     try :

>         # Set Log level to 'INFO', the default level.

>         Log.level( 'INFO' )

>         Log.write( 'INFO', 'Test Log write.' )

>         # Set Log stream to sys.stdout.

>         Log.stream( sys.stdout )

>         Log.write( 'INFO', f'Valid = {True}' )

>         # Set Log stream to a memory stream.

>         stream = io.StringIO( )

>         Log.stream( stream )

>         x = numpy.random.rand( 2, 2 )

>         Log.write( 'INFO', f'X = {x}' )

>         # Read and reset memory stream.

>         value = stream.getvalue( )

>         _, _ = stream.truncate( 0 ), stream.seek( 0 )

>         # Set Log stream to a file.

>         with open( 'log.000.txt', 'w' ) as fout :

>             Log.stream( fout )

>             x = numpy.random.rand( 2, 2 )

>             Log.write( 'WARNING', f'X = {x}' )

>     except Exception as ex :

>         Log.write( 'ERROR', ex )

License

> BSD-3C.

> © 2018 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

> Larry Turner, Schneider Electric, Analytics & AI, 2018-03-22.

Definition

class `diamondback.commons.Log.` `Log`

  Bases: `object`

  Log.

  classmethod `level`(level: str) → None

    Level.

    Arguments :

    > level : str - in ( ‘CRITICAL’, ‘ERROR’, ‘WARNING’, ‘SUCCESS’, ‘INFO’, ‘DEBUG’, ‘TRACE’, … < custom > ).

  classmethod `stream`(stream: Any) → None

    Stream.

    Arguments :

    > stream : typing.Any, hasattr( ‘write’ ) - in ( sys.stderr, sys.stdout, open( < path >, ‘w’ or ‘a’ ) ).

  classmethod `write`(level: str, entry: Union[str, Exception]) → None

    Formats and writes log entries using the loguru package with a specified level and stream. Log entries contain an ISO-8601 datetime and level.

    Arguments :

    > level : str - in ( ‘CRITICAL’, ‘ERROR’, ‘WARNING’, ‘SUCCESS’, ‘INFO’, ‘DEBUG’, ‘TRACE’, … < custom > ).

    > entry : typing.Union[ str, Exception ].

## diamondback.commons.RestClient module

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
>     import numpy
>     import typing

>     class TestClient( RestClient ) :

>         def __init__( self ) -> None :

>             super( ).__init__( )

>             self.proxy = { 'http' : '', 'https' : '' }

>         def add( self, json : typing.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( { 'x' : numpy.random.rand( 3 ), 'y' : numpy.random.rand( 3 ) } )

License

> BSD-3C.

> © 2018 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

> Larry Turner, Schneider Electric, Analytics & AI, 2020-10-22.

Definition

class `diamondback.commons.RestClient.` `RestClient`

  Bases: `diamondback.interfaces.ILive.ILive`, `diamondback.interfaces.IProxy.IProxy`, `diamondback.interfaces.ITimeOut.ITimeOut`, `diamondback.interfaces.IUrl.IUrl`

  REST client.

  Initialize.

  property `live`

    bool.

    Type

      live

  `request`(method: str, api: str, item: Optional[Dict[str, str]] = None, data: Optional[Any] = None, json: Optional[Any] = None) → requests.models.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 : typing.Dict[ str, str ].

    > data : typing.Any.

    > json : typing.Any.

    Returns :

    > value : requests.Response.

## diamondback.commons.Serial module

Description

> A serial instance encodes and decodes an instance or collection in BSON or JSON, and generates SHA3-256 codes, using the jsonpickle package.

> BSON, Base-85 encoded gzip JSON, embeds a datetime context, and code will not be consistent or useful for validation.

> An instance may be an object or a collection, referenced by abstract or concrete types, and the instance will be correctly encoded and decoded, without custom encoding definitions. BSON binary format is selected by electing to compress. Encoding may be specified if an alternative to UTF-8 is required.

> Comments may be filtered from JSON by electing to clean. Python style docstring and line comments are supported, though line comments must be terminated by a new line.

> Singleton.

> Thread safe.

Example

>     from diamondback import Serial
>     import numpy
>     import pandas

>     # Encode and decode a dictionary instance in JSON.

>     x = { 'a' : numpy.random.rand( count ), 'b' : list( numpy.random.rand( count ) ) }

>     z = Serial.decode( Serial.encode( x ) )

>     # Encode and decode a dictionary instance in BSON.

>     y = Serial.encode( x, compress = True )

>     z = Serial.decode( y, compress = True )

>     # Encode and decode a pandas data frame in BSON.

>     model = pandas.DataFrame( { 'fruit' : [ 'orange', 'apple', 'kiwi' ], 'Cost' : [ 1.25, 1.5, 0.30 ] } )

>     y = Serial.encode( model )

>     # Generate SHA3-256 code for an encoded model.

>     code = Serial.code( y )

>     z = Serial.decode( y )

>     # Decode a dictionary instance from JSON.

>     z = Serial.decode( '{ "a" : 1.0, "b" : 2.0, "c" : 3.14159 }' )

License

> BSD-3C.

> © 2018 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

> Larry Turner, Schneider Electric, Analytics & AI, 2018-07-13.

Definition

class `diamondback.commons.Serial.` `Serial`

  Bases: `object`

  Serial.

  static `code`(state: str, encoding: str = 'utf_8') → str

    Code generation. SHA3-256 hash.

    Arguments :

    > state : str.

    > encoding : str.

    Returns :

    > code : str.

  static `decode`(state: str, compress: bool = False, encoding: str = 'utf_8', clean: bool = False) → Any

    Decodes an instance or collection from a BSON or JSON state. Encoding may be specified if an alternative to UTF-8 is required. Python style docstring and line comments may be cleaned, though line comments must be terminated by a new line.

    Arguments :

    > state : str.

    > compress : bool.

    > encoding : str.

    > clean : bool - clean comments.

    Returns :

    > instance : typing.Any.

  static `encode`(instance: Any, compress: bool = False, encoding: str = 'utf_8') → str

    Encodes BSON or JSON. Encoding may be specified if an alternative to UTF-8 is required.

    Arguments :

    > instance : typing.Any.

    > compress : bool.

    > encoding : str.

    Returns :

    > state : str.

## Module contents

Description

> Initialize imports.

License

> BSD-3C.

> © 2018 - 2021 Larry Turner, Schneider Electric Industries SAS. All rights reserved.

Author

> Larry Turner, Schneider Electric, Analytics & AI, 2018-03-22.

Definition