Protocols are special cases of Bionic decorators; their effect is to specify the Serialization Protocol for the entity being defined. For example:
# This entity should only have values equal to "short" or "long".
@builder
@bn.protocol.enum('short', 'long')
def name_length(name):
if len(name) < 10:
return 'short'
else:
return 'long'
# This entity's value will always be a ``pandas.DataFrame``.
@builder
@bn.protocol.DataFrame
def raw_df():
from sklearn import datasets
dataset = datasets.load_breast_cancer()
df = pd.DataFrame(
data=dataset.data,
)
df['target'] = dataset.target
return df
Protocols are used to tell Bionic how to serialize, deserialize, and validate entity values. In most cases, Bionic's default protocol can figure out an appropriate way to handle each value, so explicit protocol decorators are usually not required. However, they can be useful for data types that need special handling, or just to add clarity, safety, or documentation to a entity definition.
Protocols can also be used when creating new entities with declare
or assign
:
builder.assign('name_length', 'short', bn.protocol.enum('short', 'long'))
builder.declare('raw_df', bn.protocol.DataFrame)
If you need to control how an entity is serialized, you can write your own custom protocol. (However, since Bionic is still at an early stage, future API changes may break your implementation.)
class MyProtocol(BaseProtocol):
def get_fixed_file_extension(self):
"""Returns the extension that persisted files should end with."""
raise NotImplementedError()
def write(self, value, path):
"""Write the contents of ``value`` to path object ``path``."""
raise NotImplementedError()
def read(self, path):
"""Read an object from path object ``path``, and return it."""
raise NotImplementedError()
bionic.protocol.dillable
bionic.protocol.enum
bionic.protocol.frame
bionic.protocol.image
bionic.protocol.numpy
bionic.protocol.picklable
bionic.protocol.type