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 : 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 : 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
from typing import Dict
import numpy

class TestClient( RestClient ) :

    def __init__( self ) -> None :

        super( ).__init__( )

        self.proxy = { '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( { '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 : Dict[ str, str ].

data : Any.

json : 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 : 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 : Any.

compress : bool.

encoding : str.

Returns :

state : str.

Module contents

Description

Initialize.

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