Bindings

Bindings

Python Bindings

The Python bindings for E2SAR are implemented with pybind11. You can find the source code in the 'src/pybind' directory.

Usage

The pybind11 module, named e2sar_py, is built alongside the C++ library and is named e2sar_py.cpython-<platform>.so based on the platform. To use the module, add its path to the Python environment:

# Add the path of the pybind module
import sys
sys.path.append('/path/to/e2sar_py.cpython-<platform>.so')

# Import the module
import e2sar_py
# Your Python code here

Examples

We provide Jupyter notebooks in the 'scripts/notebooks/pybind11_examples' directory to demonstrate Python usage.

• example_DataPlane.ipynb: Shows how to use the Python Segmenter and Reassembler classes to send and receive messages without a real FPGA control plane.
• example_EjfatURI.ipynb: Demonstrates how to create Python EjfatURI classes and handle cases where C++ functions return result<T> types.

Binding details

We list the C++ e2sar classes that are bound to Python and explain how their input, output, and return types are mapped to Python equivalents.

Bindings for the C++ e2sar::EjfatURI class

The C++ e2sar::EjfatURI class is mapped to the Python class e2sar_py.EjfatURI, with its public methods detailed in the table below. Their usage is further demonstrated in the Jupyter notebook examples.

Click to expand

Members	C++ `e2sar::EjfatURI` class	Python `e2sar_py.EjfatURI` class	Notes
Enum class	EjfatURI::TokenType::admin; EjfatURI::TokenType::instance; EjfatURI::TokenType::session;	EjfatURI.TokenType.admin EjfatURI.TokenType.instance EjfatURI.TokenType.session
Constructor	EjfatURI(const std::string &, TokenType, bool);	EjfatURI(uri: str, tt: e2sar_py.EjfatURI.TokenType)	C++ and Python functions use the same default parameter values.
Get/Set LB name	const std::string get_lbName(); void set_lbName(const std::string &);	EjfatURI.lb_name	The C++ get and set methods are mapped to the `lb_name` attribute of type string in the Python `EjfatURI` class.
Get/Set LB ID	const std::string get_lbId(); void set_lbId(const std::string &);	EjfatURI.lb_id	Similar as above.
Get/Set session ID	const std::string get_sessionId(); void set_sessionId(const std::string &);	EjfatURI.session_id	Similar as above.
Void functions: set tokens	void set_InstanceToken(const std::string &); void set_SessionToken(const std::string &);	EjfatURI.set_instance_token(token: str) -> None EjfatURI.set_session_token(token: str) -> None
Void functions: set IP v4/v6 addresses	void set_syncAddr(const std::pair<ip::address, u_int16_t> &); void set_dataAddr(const std::pair<ip::address, u_int16_t> &);	EjfatURI.set_sync_addr(ip_tuple: Tuple[e2sar_py.IPAddress, int]) -> None EjfatURI.set_data_addr(ip_tuple: Tuple[e2sar_py.IPAddress, int]) -> None	The C++ `std::pair` is mapped to a Python tuple, and the C++ `ip::address` class is mapped to the Python helper class `e2sar_py.IPAddress`. You can create `e2sar_py.IPAddress` Python objects using the method `e2sar_py.IPAddress.from_string(ip_str: str)`.
Functions return a bool value	bool get_useTls(); bool has_dataAddrv4(); bool has_dataAddrv6(); bool has_dataAddr(); bool has_syncAddr();	EjfatURI.get_useTls() -> bool EjfatURI.has_data_addr_v4() -> bool EjfatURI.has_data_addr_v6() -> bool EjfatURI.has_data_addr() -> bool EjfatURI.has_sync_addr() -> bool
Functions return a `result<std::string>` data type: get tokens	result<std::string> get_InstanceToken(); result<std::string> get_SessionToken(); result<std::string> get_AdminToken();	EjfatURI.get_instance_token() -> e2sar_py.E2SARResultString EjfatURI.get_session_token() -> e2sar_py.E2SARResultString EjfatURI.get_admin_token() -> e2sar_py.E2SARResultString	The Python functions return an `e2sar_py.E2SARResultString` object `rt_obj`. The actual values can be accessed using `rt_obj.value()`. The error information can be accessed using `rt_obj.value()`.
Functions return a `result<<std::pai<ip::address, u_int16_t>>` data type: get IP addresses	result<<std::pai<ip::address, u_int16_t>> get_cpAddr(); result<<std::pai<ip::address, u_int16_t>> get_dataAddrv4(); result<<std::pai<ip::address, u_int16_t>> get_dataAddrv6(); result<<std::pai<ip::address, u_int16_t>> get_syncAddr();	EjfatURI.get_cp_addr() -> e2sar_py.E2SARResultPairIP EjfatURI.get_data_addr_v4() -> e2sar_py.E2SARResultPairIP EjfatURI.get_data_addr_v6() -> e2sar_py.E2SARResultPairIP EjfatURI.get_sync_addr() -> e2sar_py.E2SARResultPairIP	The Python functions return an object whose `value` is a Python tuple, with the first element being an `e2sar_py.IPAddress` instance.
Get control plane hostname and port	result<<std::string, u_int16_t>> get_cpHost();	EjfatURI.get_cp_host() -> e2sar_py.E2SARResultPairString	The Python functions return an object whose `value` is a Python tuple, with the first element being a Python string.
Cast the `EjfatURI` object to a string	std::string to_string(TokenType);	EjfatURI.to_string() -> str
Initialize objects from environment variable. Returns a `result<EjfatURI>` data type	result<EjfatURI> getFromEnv(const std::string &, TokenType tt, bool);	EjfatURI.get_from_env(env_var: str, tt: e2sar_py.EjfatURI.TokenType, preferV6: bool) -> E2SARResultEjfatURI	The Python function returns an `E2SARResultEjfatURI` object, where the `value` attribute is an `EjfatURI` instance. C++ and Python functions use the same default parameter values.