pytrap module¶

TRAP extension for python3 (pytrap).

This module can be used to write NEMEA module. It consists of two main classes: TrapCtx and UnirecTemplate. TrapCtx contains communication interface, actually, it is a wrapper for libtrap. UnirecTemplate can be used for data access and manipulation. It uses UniRec macros and functions in order to retrieve value of a field and to store value into data message.

Simple example to receive and send one message:

Example

>>> import pytrap
>>> c = pytrap.TrapCtx()
>>> c.init(["-i", "u:socket1,u:socket2"], 1, 1)
>>> fmttype = pytrap.FMT_UNIREC
>>> fmtspec = "ipaddr SRC_IP"
>>> c.setRequiredFmt(0, fmttype, fmtspec)
>>> rec = pytrap.UnirecTemplate(fmtspec)
>>> try:
...     data = c.recv()
>>> except pytrap.FormatChanged as e:
...     fmttype, fmtspec = c.getDataFmt(0)
...     rec = pytrap.UnirecTemplate(fmtspec)
...     data = e.data
>>> if len(data) <= 1:
...     # empty message - do not process it!!!
...     pass
>>> else:
...     c.setDataFmt(0, fmttype, fmtspec)
...     rec.setData(data)
...     print(rec.strRecord())
>>> # send the message that was received:
>>> c.send(data)
>>> c.finalize()

Simple example for data access using rec - UnirecTemplate instance:

Example

>>> print(rec.SRC_IP)
>>> rec.SRC_IP = pytrap.UnirecIPAddr("127.0.0.1")
>>> print(getattr(rec, "SRC_IP"))
>>> rec.TIME_FIRST = pytrap.UnirecTime(12345678)
>>> print(rec.TIME_FIRST)
>>> print(rec.TIME_FIRST.toDatetime())

Simple example for creation of new message of UnirecTemplate: .. rubric:: Example

>>> # createMessage() expects the maximal total size of fields with variable length as an argument,
>>> # here it is 100, i.e., size of all variable length data (sum of sizes) MUST be <= 100 bytes
>>> data = rec.createMessage(100)
>>> rec.DST_PORT = 80

createMessage() should be called just at the beginning of program or when format change is needed.

It is possible to set JSON format and send JSON documents via TRAP interface. Example (send):

>>> import pytrap
>>> import json
>>> c = pytrap.TrapCtx()
>>> c.init(["-i", "f:/tmp/jsondata.trapcap:w"], 0, 1)
>>> c.setDataFmt(0, pytrap.FMT_JSON, "JSON")
>>>
>>> a = json.dumps({"a": 123, "b": "aaa"})
>>>
>>> c.send(bytearray(a, "utf-8"))
>>>
>>> c.finalize()

Example (receive):

>>> import pytrap
>>> import json
>>> c = pytrap.TrapCtx()
>>> c.init(["-i", "f:/tmp/jsondata.trapcap"], 1)
>>> c.setRequiredFmt(0, pytrap.FMT_JSON, "JSON")
>>>
>>> data = c.recv()
>>> print(json.loads(data.decode("utf-8")))
>>>
>>> c.finalize()

There are complete example modules, see: https://github.com/CESNET/Nemea-Framework/tree/master/examples/python

For more details, see the generated documentation: https://nemea.liberouter.org/doc/pytrap/.

pytrap.pytrap.getTrapVersion()¶

Get the version of libtrap.

Returns: libtrap version, git version.
Return type: tuple(str, str)

exception pytrap.FormatChanged¶: Bases: pytrap.TrapError

exception pytrap.FormatMismatch¶: Bases: pytrap.TrapError

exception pytrap.Terminated¶: Bases: pytrap.TrapError

exception pytrap.TimeoutError¶: Bases: pytrap.TrapError

class pytrap.TrapCtx¶

Bases: object

Class represents libtrap context. It must be initialized using init() and finalized and the end of usage finalize(). To terminate blocking libtrap functions use terminate().

finalize()¶: Free allocated memory.

getDataFmt()¶

Get data format that was negotiated via input IFC.

Parameters: ifcidx (Optional[int]) – Index of IFC (default: 0).
Returns: Type of format and specifier (see setRequiredFmt()).
Return type: Tuple(int, string)

getInIFCState()¶

Get the state of input IFC.

Parameters: ifcidx (int) – Index of IFC.
Returns: One of module’s constants (FMTS_WAITING, FMTS_OK, FMTS_MISMATCH, FMTS_CHANGED).
Return type: int
Raises: TrapError – Bad index is passed or TRAP is not initialized.

getVerboseLevel()¶

Get current verbose level.

Returns: Level of verbosity. See setVerboseLevel() for possible values.
Return type: int

ifcctl()¶

Change settings of TRAP IFC.

Parameters

ifcidx (int) – Index of IFC.
dir_in (bool) – If True, input IFC will be modified, output IFC otherwise.
request (int) – Type of request given by a module’s constant (CTL_AUTOFLUSH, CTL_BUFFERSWITCH, CTL_TIMEOUT).
value (int) – Parameter value of the chosen request.

init()¶

Initialization of TRAP.

Parameters

argv (list[str]) – Arguments of the process.
ifcin (Optional[int]) – ifcin is a number of input IFC (default: 1).
ifcout (Optional[int]) – ifcout is a number of output IFC (default: 0).
module_name (Optional[str]) – Set name of this module.
module_desc (Optional[str]) – Set description of this module.
service_ifcname (Optional[str]) – Set identifier of service IFC, PID is used when omitted, set to “” (empty string) to disable service IFC.

Raises

TrapError – Initialization failed.

recv()¶

Receive data via TRAP interface.

Parameters

ifcidx (Optional[int]) – Index of input IFC (default: 0).

Returns

Received data.

Return type

bytearray

Raises

TimeoutError – Receiving data failed due to elapsed timeout.
TrapError – Bad index given.
FormatChanged – Data format was changed, it is necessary to update template. The received data is in data attribute of the FormatChanged instance.
Terminated – The TRAP IFC was terminated.

recvBulk()¶

Receive sequence of records at once via TRAP interface.

Parameters

urtempl (UnirecTemplate) – Created UnirecTemplate with the template, it is updated internally when the format is changed.
time (int) – Timeout in seconds before interrupt of capture.
count (int) – Maximum number of messages to capture, infinite when -1 (Warning! This can consume much memory.).
ifcidx (Optional[int]) – Index of input IFC (default: 0).

Returns

Received data.

Return type

list(dict)

Raises

TrapError – Bad index given.

send()¶

Send data via TRAP interface.

Parameters

bytes (bytearray or bytes) – Data to send.
ifcidx (Optional[int]) – Index of output IFC (default: 0).

Raises

TimeoutError – Receiving data failed due to elapsed timeout.
TrapError – Bad size or bad index given.
Terminated – The TRAP IFC was terminated.

sendFlush()¶

Force sending buffer for IFC with ifcidx index.

Parameters: ifcidx (Optional[int]) – Index of IFC (default: 0).

setDataFmt()¶

Set data format for output IFC.

Parameters

ifcidx (int) – Index of IFC.
type (Optional[int]) – Type of format (FMT_RAW, FMT_UNIREC), (default: FMT_UNIREC).
spec (Optional[string]) – Specifier of data format (default: “”).

setRequiredFmt()¶

Set required data format for input IFC.

Parameters

ifcidx (int) – Index of IFC.
type (Optional[int]) – Type of format: FMT_RAW, FMT_UNIREC (default: FMT_UNIREC)
spec (Optional[string]) – Specifier of data format (UniRec specifier for FMT_UNIREC type) (default: “”).

setVerboseLevel()¶

Set the verbose level of TRAP.

Parameters: level (int) – Level of verbosity the higher value the more verbose. Possible values: VERB_ERRORS (-3), VERB_WARNINGS (-2), VERB_NOTICES (-1) = default, VERB_VERBOSE (0), VERB_VERBOSE2 (1), VERB_VERBOSE3 (2).

terminate()¶: Terminate TRAP.

exception pytrap.TrapError¶: Bases: Exception

exception pytrap.TrapHelp¶: Bases: Exception

class pytrap.UnirecIPAddr(ip)¶

Bases: object

Class for UniRec IP Address storage and base data access.

Parameters: ip (str) – text represented IPv4 or IPv6 address

dec()¶

Decrement IP address.

Returns: New decremented IPAddress.
Return type: UnirecIPAddr

inc()¶

Increment IP address.

Returns: New incremented IPAddress.
Return type: UnirecIPAddr

isIPv4()¶

Check if the address is IPv4.

Returns: True if the address is IPv4.
Return type: bool

isIPv6()¶

Check if the address is IPv6.

Returns: True if the address is IPv6.
Return type: bool

isNull()¶

Check if the address is null (IPv4 or IPv6), i.e. “0.0.0.0” or “::”.

Returns: True if the address is null.
Return type: bool

class pytrap.UnirecIPAddrRange(start[, end])¶

Bases: object

Class for UniRec IP Address Range storage and base data access.

Parameters

start (str) – text represented IPv4 address or prefix using /mask notation
end (Optional[str]) – text represented IPv4 address of end of the range
/mask) ((start must not contain) –

end¶: High IP address of range

isIn()¶

Check if the address is in IP range.

Parameters

ipaddr – UnirecIPAddr structReturns:
long – -1 if ipaddr < start of range, 0 if ipaddr is in interval, 1 if ipaddr > end of range .

isOverlap()¶

Check if 2 ranges sorted by start IP overlap.

Parameters

other – UnirecIPAddrRange, second interval to compareReturns:
bool – True if ranges are overlaps.

start¶: Low IP address of range

class pytrap.UnirecMACAddr(mac)¶

Bases: object

Class for UniRec MAC Address storage and base data access.

Parameters: mac (str) – text represented MAC address (e.g. “00:11:22:33:44:55”)

dec()¶

Decrement MAC address.

Returns: New decremented MAC address.
Return type: UnirecMACAddr

inc()¶

Increment MAC address.

Returns: New incremented MAC address.
Return type: UnirecMACAddr

isNull()¶

Check if the MAC address is null, i.e. “00:00:00:00:00:00”.

Returns: True if the address is null.
Return type: bool

class pytrap.UnirecMACAddrRange(start, end)¶

Bases: object

Class for UniRec MAC Address Range storage and base data access.

Parameters

start (UnirecMACAddr) – text represented MAC address or prefix using /mask notation
end (UnirecMACAddr) – text represented MAC address of end of the range
/mask) ((start must not contain) –

end¶: High MAC address of range

isIn()¶

Check if the address is in MAC range.

Parameters

macaddr – UnirecMACAddr structReturns:
long – -1 if macaddr < start of range, 0 if macaddr is in interval, 1 if macaddr > end of range .

isOverlap()¶

Check if 2 ranges sorted by start MAC overlap.

Parameters

other – UnirecMACAddrRange, second interval to compareReturns:
bool – True if ranges are overlaps.

start¶: Low MAC address of range

class pytrap.UnirecTemplate(spec)¶

Bases: object

Class for UniRec template storage and base data access.

Example

UnirecTemplate(“ipaddr SRC_IP,uint16 SRC_PORT,time START”) creates a template with tree fields.

Parameters: spec (str) – UniRec template specifier - list of field types and names

copy()¶

Create a new instance with the same format specifier without data.

Returns: New copy of object (not just reference).
Return type: UnirecTemplate

createMessage()¶

Create a message that can be filled in with values according to the template.

Parameters: dyn_size (Optional[int]) – Maximal size of variable data (in total) (default: 0).
Returns: Allocated memory that can be filled in using set().
Return type: bytearray

get()¶

Get value of the field from the UniRec message.

Parameters

data (bytearray or bytes) – Data - UniRec message.
field_name (str) – Field name.

Returns

Retrieved value of the field (depends on UniRec template).

Return type

(object)

Raises

TypeError – Data argument must be bytearray or bytes.
TrapError – Field name was not found.

getByID()¶

Get value of the field from the UniRec message.

Parameters

data (bytearray or bytes) – Data - UniRec message.
field_id (int) – Field ID (use getFieldsDict()).

Returns

Retrieved value of the field (depends on UniRec template).

Return type

(object)

Raises

TypeError – Data argument must be bytearray or bytes.

getData()¶

Get data that was already set using setData.

Returns: Data - UniRec message.
Return type: bytearray

getDict()¶

Get UniRec record as a dictionary.

Returns: Dictionary of field names and field values.
Return type: dict(str, object)

getFieldType()¶

Get type of given field.

Parameters: field_name (str) – Field name.
Returns: Type object (e.g. int, str or pytrap.UnirecIPAddr).
Return type: type

getFieldsDict()¶

Get set of fields of the template.

Returns: Dictionary of field_id with field name as a key.
Return type: Dict(str,int)

recFixlenSize()¶

Get size of fixed part of UniRec record.

This is the minimal size of a record with given template,i.e. the size with all variable-length fields empty. :returns: Size of fixed part of template in bytes :rtype: int

recSize()¶

Get size of UniRec record.

Return total size of valid record data, i.e. number of bytes occupied by all fields.This may be less than allocated size of ‘data’. :param data: Data of UniRec message (optional if previously set by setData)Returns: :type data: Optional[bytearray or bytes] :param int: Size of record data in bytes

recVarlenSize()¶

Get size of variable-length part of UniRec record.

Return total size of all variable-length fields. :param data: Data of UniRec message (optional if previously set by setData)Returns: :type data: Optional[bytearray or bytes] :param int: Total size of variable-length fields in bytes

set()¶

Set value of the field in the UniRec message.

Parameters

data (bytearray or bytes) – Data - UniRec message.
field_name (str) – Field name.
value (object) – New value of the field (depends on UniRec template).

Raises

TypeError – Bad object type of value was given.
TrapError – Field was not found.

setByID()¶

Set value of the field in the UniRec message.

Parameters

data (bytearray or bytes) – Data - UniRec message.
field_id (int) – Field ID.
value (object) – New value of the field (depends on UniRec template).

Raises

TypeError – Bad object type of value was given.
TrapError – Field was not found.

setData()¶

Set data for attribute access.

Parameters: data (bytearray or bytes) – Data - UniRec message.

strRecord()¶

Get values of record in readable format.

Returns: String in key=value format.
Return type: str

class pytrap.UnirecTime(int(seconds)[, int(miliseconds)])¶

class pytrap.UnirecTime(double(secs_and_msecs)) → None

class pytrap.UnirecTime(str("2019-03-18T12:11:10Z")) → None

Bases: object

Class for UniRec timestamp storage and base data access.

Parameters

str – datetime, e.g., “2019-03-18T12:11:10.123Z”
int (double or) – number of seconds
Optional[int] – number of miliseconds (when the first argument is int)

Raises

TypeError – unsupported type was provided or string is malformed.

format()¶

Get timestamp as a datetime object.

Parameters: format (Optional[str]) – Formatting string, same as for datetime.strftime (default: “%FT%TZ”).
Returns: Formatted timestamp as string.
Return type: (str)

static fromDatetime()¶

Get UnirecTime from a datetime object.

Returns: Retrieved timestamp.
Return type: (UnirecTime)

getMicroSeconds()¶

Get number of microseconds of timestamp.

Returns: Retrieved number of microseconds.
Return type: (long)

getMicroSecondsAsFloat()¶

Get number of microseconds of timestamp.

Returns: Retrieved number of microseconds.
Return type: (double)

getMiliSeconds()¶

Get number of seconds of timestamp.

Returns: Retrieved number of seconds.
Return type: (long)

getNanoSeconds()¶

Get number of nanoseconds of timestamp.

Returns: Retrieved number of nanoseconds.
Return type: (long)

getNanoSecondsAsFloat()¶

Get number of nanoseconds of timestamp.

Returns: Retrieved number of nanoseconds.
Return type: (double)

getSeconds()¶

Get number of seconds of timestamp.

Returns: Retrieved number of seconds.
Return type: (long)

getTimeAsFloat()¶

Get number of seconds of timestamp.

Returns: Retrieved timestamp as floating point number.
Return type: (double)

static now()¶

Get UnirecTime instance of current time.

Returns: Current date and time.
Return type: (UnirecTime)

toDatetime()¶

Get timestamp as a datetime object.

Returns: Retrieved timestamp as datetime.
Return type: (datetime)

pytrap.read_nemea(ifc_spec, nrows=- 1, array=False)[source]¶

Read nrows records from NEMEA TRAP interface given by ifc_spec and convert then into Pandas DataFrame.

Parameters

ifc_spec (str) – IFC specifier for TRAP input IFC, see https://nemea.liberouter.org/trap-ifcspec/
nrows (int) – Number of records, read until end of stream (zero size message) if -1.
array (bool) – Set output type to list of dictionary instead of pandas.DataFrame

Returns

DataFrame if array is False, otherwise, list of dictionary

Return type

pandas.DataFrame or list of dictionary

Raises

ModuleNotFoundError – When pandas is not installed.

pytrap module¶

Previous topic

Next topic

This Page