Internal Auxiliary Functions

Auxiliary functions.

zlogging._aux.readline(file, separator=b'\t', maxsplit=-1, decode=False)

Wrapper for file.readline() function.

Parameters

  • file (_io.BufferedReader) – Log file object opened in binary mode.

  • separator (bytes) – Data separator.

  • maxsplit (int) – Maximum number of splits to do; see bytes.split() and str.split() for more information.

  • decode (bool) – If decide the buffered string with ascii encoding.

Returns

The splitted line as a list of bytes, or as str if decode if set to True.

Return type

List[AnyStr]

zlogging._aux.decimal_toascii(data, infinite=None)

Convert decimal.Decimal to ASCII.

Parameters

  • data (decimal.Decimal) – A decimal.Decimal object.

  • infinite (str) – The ASCII representation of infinite numbers (NaN and infinity).

Returns

The converted ASCII string.

Return type

str

Example

When converting a decimal.Decimal object, for example:

>>> d = decimal.Decimal('-123.123456789')

the function will preserve only 6 digits of its fractional part, i.e.:

>>> decimal_toascii(d)
'-123.123456'

Note

Infinite numbers, i.e. NaN and infinity (inf), will be converted as the value specified in infinite, in default the string representation of the number itself, i.e.:

  • NaN -> 'NaN'

  • Infinity -> 'Infinity'

zlogging._aux.float_toascii(data, infinite=None)

Convert float to ASCII.

Parameters

  • data (float) – A float number.

  • infinite (str) – The ASCII representation of infinite numbers (NaN and infinity).

Returns

The converted ASCII string.

Return type

str

Example

When converting a float number, for example:

>>> f = -123.123456789

the function will preserve only 6 digits of its fractional part, i.e.:

>>> float_toascii(f)
'-123.123456'

Note

Infinite numbers, i.e. NaN and infinity (inf), will be converted as the value specified in infinite, in default the string representation of the number itself, i.e.:

  • NaN -> 'nan'

  • Infinity -> 'inf'

zlogging._aux.unicode_escape(string)

Conterprocess of bytes.decode('unicode_escape')().

Parameters

string (bytes) – The bytestring to be escaped.

Returns

The escaped bytestring as an encoded string

Return type

str

Example

>>> b'\x09'.decode('unicode_escape')
'\t'
>>> unicode_escape(b'\t')
'\x09'
zlogging._aux.expand_typing(cls, exc=None)

Expand typing annotations.

Parameters

  • cls (Model or RecordType object) – a variadic class which supports PEP 484 style attribute typing annotations

  • exc (Optional[ValueError]) – (ValueError, optional): exception to be used in case of inconsistent values for unset_field, empty_field and set_separator

Returns

The returned dictionary contains the

following directives:

  • fields (OrderedDict mapping str and BaseType):

    a mapping proxy of field names and their corresponding data types, i.e. an instance of a BaseType subclass

  • record_fields (OrderedDict mapping str and RecordType):

    a mapping proxy for fields of record data type, i.e. an instance of RecordType

  • unset_fields (bytes): placeholder for unset field

  • empty_fields (bytes): placeholder for empty field

  • set_separator (bytes): separator for set/vector fields

Return type

Dict[str, Any]

Warns

BroDeprecationWarning – Use of bro_* prefixed typing annotations.

Raises

ValueError – In case of inconsistent values for unset_field, empty_field and set_separator.

Example

Define a custom log data model from Model using the prefines Bro/Zeek data types, or subclasses of BaseType:

class MyLog(Model):
    field_one = StringType()
    field_two = SetType(element_type=PortType)

Or you may use type annotations as PEP 484 introduced when declaring data models. All available type hints can be found in zlogging.typing:

class MyLog(Model):
    field_one: zeek_string
    field_two: zeek_set[zeek_port]

However, when mixing annotations and direct assignments, annotations will take proceedings, i.e. the function shall process first typing annotations then cls attribute assignments. Should there be any conflicts, the exc will be raised.

Note

Fields of zlogging.types.RecordType type will be expanded as plain fields of the cls, i.e. for the variadic class as below:

class MyLog(Model):
    record = RecrodType(one=StringType(),
                        two=VectorType(element_type=CountType()))

will have the following fields:

  • record.one -> string data type

  • record.two -> vector[count] data type