Python-facing wrapper around the native Blackboard. More...

#include <blackboard_pywrapper.hpp>

Collaboration diagram for yasmin::BlackboardPyWrapper:

Public Member Functions
	BlackboardPyWrapper ()
	Construct a wrapper with a newly created native Blackboard.
	BlackboardPyWrapper (Blackboard &&other)
	Construct a wrapper by moving an existing native Blackboard.
	BlackboardPyWrapper (Blackboard::SharedPtr bb_ptr)
	Construct a wrapper from an existing shared native Blackboard.
void	set (const std::string &key, py::object value)
	Store a Python object in the blackboard.
py::object	get (const std::string &key) const
	Retrieve a Python object from the blackboard.
void	remove (const std::string &key)
	Remove a value from the blackboard.
bool	contains (const std::string &key) const
	Check whether a key exists in the blackboard.
int	size () const
	Get the number of entries in the blackboard.
std::vector< std::string >	keys () const
	Get the keys visible in the current remapping scope.
py::list	values () const
	Get the values visible in the current remapping scope.
py::list	items () const
	Get the key-value pairs visible in the current remapping scope.
std::string	to_string () const
	Get a string representation of the blackboard contents.
void	set_remappings (const Remappings &remappings)
	Set key remappings on the underlying blackboard.
const Remappings &	get_remappings () const
	Get the current key remappings.
Blackboard::SharedPtr	get_cpp_blackboard () const
	Access the underlying native blackboard.

Private Types
using	StringVector = std::vector<std::string>
	Alias for a typed vector of strings.
using	IntVector = std::vector<std::int64_t>
	Alias for a typed vector of integers.
using	FloatVector = std::vector<double>
	Alias for a typed vector of floating point values.
using	BoolVector = std::vector<bool>
	Alias for a typed vector of booleans.
using	StringDict = std::unordered_map<std::string, std::string>
	Alias for a typed dictionary with string values.
using	IntDict = std::unordered_map<std::string, std::int64_t>
	Alias for a typed dictionary with integer values.
using	FloatDict = std::unordered_map<std::string, double>
	Alias for a typed dictionary with floating point values.
using	BoolDict = std::unordered_map<std::string, bool>
	Alias for a typed dictionary with boolean values.

Static Private Member Functions
static std::vector< uint8_t >	py_buffer_to_vector (const py::handle &value)
	Convert a Python bytes-like object into a byte vector.
template<typename ByteT>
static py::bytes	byte_vector_to_py_bytes (const std::vector< ByteT > &value)
	Convert a C++ byte-like vector into Python bytes.
static bool	is_python_bytes_like (const py::handle &value)
	Check whether a Python object is bytes-like.
static bool	is_python_int_like (const py::handle &value)
	Check whether a Python object is an integer but not a boolean.
static bool	is_python_float_like (const py::handle &value)
	Check whether a Python object is a floating point value.
static bool	is_python_number_like (const py::handle &value)
	Check whether a Python object is a numeric value.
static bool	is_python_sequence_like (const py::handle &value)
	Check whether a Python object should be treated as a sequence.
template<typename Predicate>
static bool	sequence_matches (const py::sequence &seq, Predicate pred)
	Check whether all elements of a Python sequence satisfy a predicate.
template<typename T>
static std::vector< T >	sequence_to_vector (const py::sequence &seq)
	Convert a Python sequence into a typed C++ vector.
static bool	dict_has_only_string_keys (const py::dict &dict)
	Check whether all keys in a Python dict are strings.
template<typename Predicate>
static bool	dict_values_match (const py::dict &dict, Predicate pred)
	Check whether all values of a Python dict satisfy a predicate.
template<typename T>
static std::unordered_map< std::string, T >	dict_to_unordered_map (const py::dict &dict)
	Convert a Python dict with string keys into a typed unordered_map.
template<typename T>
static bool	is_exact_cpp_type (const std::string &type)
	Compare a stored type string against an exact C++ type.

Private Attributes
Blackboard::SharedPtr	blackboard
	Shared pointer to the underlying native blackboard.

Detailed Description

Python-facing wrapper around the native Blackboard.

The underlying Blackboard stores strongly typed C++ values. This wrapper translates common Python types into matching C++ types on write and converts them back into Python objects on read.

Supported scalar mappings:

bool <-> bool
int <-> std::int64_t
float <-> double
str <-> std::string
bytes / bytearray <-> std::vector<uint8_t>

Supported homogeneous container mappings:

list[str] / tuple[str, ...] <-> std::vector<std::string>
list[int] / tuple[int, ...] <-> std::vector<std::int64_t>
list[float] / tuple[float, ...] <-> std::vector<double>
list[bool] / tuple[bool, ...] <-> std::vector<bool>
dict[str, str] <-> std::unordered_map<std::string, std::string>
dict[str, int] <-> std::unordered_map<std::string, std::int64_t>
dict[str, float] <-> std::unordered_map<std::string, double>
dict[str, bool] <-> std::unordered_map<std::string, bool>

Mixed containers, nested containers, and empty containers are stored as py::object because no unique native C++ element type can be inferred safely.

Member Typedef Documentation

◆ BoolDict

using yasmin::BlackboardPyWrapper::BoolDict = std::unordered_map<std::string, bool>

private

Alias for a typed dictionary with boolean values.

◆ BoolVector

using yasmin::BlackboardPyWrapper::BoolVector = std::vector<bool>

private

Alias for a typed vector of booleans.

◆ FloatDict

using yasmin::BlackboardPyWrapper::FloatDict = std::unordered_map<std::string, double>

private

Alias for a typed dictionary with floating point values.

◆ FloatVector

using yasmin::BlackboardPyWrapper::FloatVector = std::vector<double>

private

Alias for a typed vector of floating point values.

◆ IntDict

using yasmin::BlackboardPyWrapper::IntDict = std::unordered_map<std::string, std::int64_t>

private

Alias for a typed dictionary with integer values.

◆ IntVector

using yasmin::BlackboardPyWrapper::IntVector = std::vector<std::int64_t>

private

Alias for a typed vector of integers.

◆ StringDict

using yasmin::BlackboardPyWrapper::StringDict = std::unordered_map<std::string, std::string>

private

Alias for a typed dictionary with string values.

◆ StringVector

using yasmin::BlackboardPyWrapper::StringVector = std::vector<std::string>

private

Alias for a typed vector of strings.

Constructor & Destructor Documentation

◆ BlackboardPyWrapper() [1/3]

yasmin::BlackboardPyWrapper::BlackboardPyWrapper ( )

inline

Construct a wrapper with a newly created native Blackboard.

◆ BlackboardPyWrapper() [2/3]

yasmin::BlackboardPyWrapper::BlackboardPyWrapper ( Blackboard && other )

inline

Construct a wrapper by moving an existing native Blackboard.

Parameters

other Native blackboard instance to move into shared ownership.

◆ BlackboardPyWrapper() [3/3]

yasmin::BlackboardPyWrapper::BlackboardPyWrapper ( Blackboard::SharedPtr bb_ptr )

inlineexplicit

Construct a wrapper from an existing shared native Blackboard.

Parameters

bb_ptr Shared pointer to a native Blackboard.

Member Function Documentation

◆ byte_vector_to_py_bytes()

template<typename ByteT>

py::bytes yasmin::BlackboardPyWrapper::byte_vector_to_py_bytes ( const std::vector< ByteT > & value )

inlinestaticprivate

Convert a C++ byte-like vector into Python bytes.

Template Parameters

ByteT Element type of the input vector.

Parameters

value Native byte buffer.

Returns: Python bytes object with identical raw contents.

◆ contains()

bool yasmin::BlackboardPyWrapper::contains ( const std::string & key ) const

inline

Check whether a key exists in the blackboard.

Parameters

key	Blackboard key to test.

Returns: True if the key exists.

◆ dict_has_only_string_keys()

bool yasmin::BlackboardPyWrapper::dict_has_only_string_keys ( const py::dict & dict )

inlinestaticprivate

Check whether all keys in a Python dict are strings.

Parameters

dict	Python dictionary to inspect.

Returns: True if all keys are Python strings.

◆ dict_to_unordered_map()

template<typename T>

std::unordered_map< std::string, T > yasmin::BlackboardPyWrapper::dict_to_unordered_map ( const py::dict & dict )

inlinestaticprivate

Convert a Python dict with string keys into a typed unordered_map.

Template Parameters

T	Target mapped type.

Parameters

dict	Python dictionary to convert.

Returns: Native unordered_map with converted keys and values.

◆ dict_values_match()

template<typename Predicate>

bool yasmin::BlackboardPyWrapper::dict_values_match	(	const py::dict &	dict,
		Predicate	pred )

inlinestaticprivate

Check whether all values of a Python dict satisfy a predicate.

Template Parameters

Predicate Callable returning bool for each value.

Parameters

dict	Python dictionary to inspect.
pred	Predicate applied to every value.

Returns: True if all values satisfy the predicate.

◆ get()

py::object yasmin::BlackboardPyWrapper::get ( const std::string & key ) const

inline

Retrieve a Python object from the blackboard.

Parameters

key	Blackboard key.

Returns: Python object reconstructed from the stored native value.

The native blackboard stores the type name of each entry. This method uses that exact stored type information to select the matching conversion path.

◆ get_cpp_blackboard()

Blackboard::SharedPtr yasmin::BlackboardPyWrapper::get_cpp_blackboard ( ) const

inline

Access the underlying native blackboard.

Returns: Shared pointer to the native blackboard instance.

◆ get_remappings()

const Remappings & yasmin::BlackboardPyWrapper::get_remappings ( ) const

inline

Get the current key remappings.

Returns: Reference to the underlying remapping table.

◆ is_exact_cpp_type()

template<typename T>

bool yasmin::BlackboardPyWrapper::is_exact_cpp_type ( const std::string & type )

inlinestaticprivate

Compare a stored type string against an exact C++ type.

Template Parameters

T	Type to compare against.

Parameters

type	Demangled type name stored in the blackboard.

Returns: True if the stored type exactly matches T.

Exact matching avoids ambiguous substring checks such as "int" matching both "int" and "std::vector<int>".

◆ is_python_bytes_like()

bool yasmin::BlackboardPyWrapper::is_python_bytes_like ( const py::handle & value )

inlinestaticprivate

Check whether a Python object is bytes-like.

Parameters

value Python object to test.

Returns: True if the object is bytes or bytearray.

◆ is_python_float_like()

bool yasmin::BlackboardPyWrapper::is_python_float_like ( const py::handle & value )

inlinestaticprivate

Check whether a Python object is a floating point value.

Parameters

value Python object to test.

Returns: True if the object is a Python float.

◆ is_python_int_like()

bool yasmin::BlackboardPyWrapper::is_python_int_like ( const py::handle & value )

inlinestaticprivate

Check whether a Python object is an integer but not a boolean.

Parameters

value Python object to test.

Returns: True if the object is an int and not a bool.

Python bool is a subclass of int, therefore it must be filtered out explicitly to avoid storing True and False as integers.

◆ is_python_number_like()

bool yasmin::BlackboardPyWrapper::is_python_number_like ( const py::handle & value )

inlinestaticprivate

Check whether a Python object is a numeric value.

Parameters

value Python object to test.

Returns: True if the object is an int-like or float-like value.

◆ is_python_sequence_like()

bool yasmin::BlackboardPyWrapper::is_python_sequence_like ( const py::handle & value )

inlinestaticprivate

Check whether a Python object should be treated as a sequence.

Parameters

value Python object to test.

Returns: True if the object is a list or tuple.

◆ items()

py::list yasmin::BlackboardPyWrapper::items ( ) const

inline

Get the key-value pairs visible in the current remapping scope.

Returns: Python list of (key, value) tuples.

◆ keys()

std::vector< std::string > yasmin::BlackboardPyWrapper::keys ( ) const

inline

Get the keys visible in the current remapping scope.

Returns: Sorted list of visible key names.

◆ py_buffer_to_vector()

std::vector< uint8_t > yasmin::BlackboardPyWrapper::py_buffer_to_vector ( const py::handle & value )

inlinestaticprivate

Convert a Python bytes-like object into a byte vector.

Parameters

value Python object expected to be bytes or bytearray.

Returns: Byte vector with the same raw contents.

Exceptions

std::runtime_error if the object is not bytes-like.

◆ remove()

void yasmin::BlackboardPyWrapper::remove ( const std::string & key )

inline

Remove a value from the blackboard.

Parameters

key	Blackboard key to remove.

◆ sequence_matches()

template<typename Predicate>

bool yasmin::BlackboardPyWrapper::sequence_matches	(	const py::sequence &	seq,
		Predicate	pred )

inlinestaticprivate

Check whether all elements of a Python sequence satisfy a predicate.

Template Parameters

Predicate Callable returning bool for each element.

Parameters

seq	Python sequence to inspect.
pred	Predicate applied to every element.

Returns: True if all elements satisfy the predicate.

◆ sequence_to_vector()

template<typename T>

std::vector< T > yasmin::BlackboardPyWrapper::sequence_to_vector ( const py::sequence & seq )

inlinestaticprivate

Convert a Python sequence into a typed C++ vector.

Template Parameters

T	Target element type.

Parameters

seq	Python sequence to convert.

Returns: Vector containing all converted elements.

◆ set()

void yasmin::BlackboardPyWrapper::set	(	const std::string &	key,
		py::object	value )

inline

Store a Python object in the blackboard.

Parameters

key	Blackboard key.
value	Python object to store.

The wrapper first tries to map the value to a native C++ type. If no safe native mapping exists, the value is stored as py::object.

◆ set_remappings()

void yasmin::BlackboardPyWrapper::set_remappings ( const Remappings & remappings )

inline

Set key remappings on the underlying blackboard.

Parameters

remappings Remapping table to apply.

◆ size()

int yasmin::BlackboardPyWrapper::size ( ) const

inline

Get the number of entries in the blackboard.

Returns: Number of stored key-value pairs.

◆ to_string()

std::string yasmin::BlackboardPyWrapper::to_string ( ) const

inline

Get a string representation of the blackboard contents.

Returns: Human-readable description of the stored keys and types.

◆ values()

py::list yasmin::BlackboardPyWrapper::values ( ) const

inline

Get the values visible in the current remapping scope.

Returns: Python list with the values in key order.

Member Data Documentation

◆ blackboard

Blackboard::SharedPtr yasmin::BlackboardPyWrapper::blackboard

private

Shared pointer to the underlying native blackboard.

The documentation for this class was generated from the following file:

yasmin/include/yasmin/blackboard_pywrapper.hpp

Public Member Functions

Private Types

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ BoolDict

◆ BoolVector

◆ FloatDict

◆ FloatVector

◆ IntDict

◆ IntVector

◆ StringDict

◆ StringVector

Constructor & Destructor Documentation

◆ BlackboardPyWrapper() [1/3]

◆ BlackboardPyWrapper() [2/3]

◆ BlackboardPyWrapper() [3/3]

Member Function Documentation

◆ byte_vector_to_py_bytes()

◆ contains()

◆ dict_has_only_string_keys()

◆ dict_to_unordered_map()

◆ dict_values_match()

◆ get()

◆ get_cpp_blackboard()

◆ get_remappings()

◆ is_exact_cpp_type()

◆ is_python_bytes_like()

◆ is_python_float_like()

◆ is_python_int_like()

◆ is_python_number_like()

◆ is_python_sequence_like()

◆ items()

◆ keys()

◆ py_buffer_to_vector()

◆ remove()

◆ sequence_matches()

◆ sequence_to_vector()

◆ set()

◆ set_remappings()

◆ size()

◆ to_string()

◆ values()

Member Data Documentation

◆ blackboard