Internal Auxiliary Functions

I/O Utilities

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

Wrapper for file.readline() function.

Parameters:

  • file (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.

Return type:

Union[list[str], list[bytes]]

Returns:

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

Value Conversion

zlogging._aux.decimal_toascii(data, infinite=None)[source]

Convert decimal.Decimal to ASCII.

Parameters:
Return type:

str

Returns:

The converted ASCII string.

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)[source]

Convert float to ASCII.

Parameters:

  • data (float) – A float number.

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

Return type:

str

Returns:

The converted ASCII string.

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)[source]

Conterprocess of bytes.decode('unicode_escape').

Parameters:

string (bytes) – The bytestring to be escaped.

Return type:

str

Returns:

The escaped bytestring as an encoded string

Example

>>> b'\x09'.decode('unicode_escape')
'\\t'
>>> unicode_escape(b'\t')
'\\x09'

Typing Inspection

zlogging._aux.expand_typing(cls, exc=None)[source]

Expand typing annotations.

Parameters:
Returns:

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

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

  • unset_fields: placeholder for unset field

  • empty_fields: placeholder for empty field

  • set_separator: separator for set/vector fields

Return type:

The returned dictionary contains the following directives

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