A package that allows using yaml to define zserio objects.
Project description
zs-yaml
Your Easy Path to zserio Test Data
zs-yaml adds YAML as a text format to be used with zserio in order to improve the user experience when manually creating or analyzing test data for specific zserio schemas.
- YAML Format: Uses YAML's human-readable format instead of JSON as the primary format for editing, making data handling and transformation more intuitive and less cluttered.
- Metadata Inclusion: Automatically includes metadata in the YAML, eliminating the need for users to manually identify the correct type when importing JSON data, ensuring seamless (de-)serialization.
- Custom Transformations: Allows for hooking in custom transformations so that users can work with familiar formats (e.g., dates or coordinate representations) instead of thinking in unfamiliar formats.
Installation
Install zs-yaml
using pip:
python -m pip install --upgrade zs-yaml
Usage
The main entry point for the application is zs-yaml
. It accepts arguments for specifying the input and output file paths. You can run the application as follows:
zs-yaml input.yaml output.bin
zs-yaml input.bin output.yaml
Notes
- You have to use the exact same order of fields in the YAML as defined by the zserio schema, because zserio expects this.
- When converting from binary to YAML, the target YAML file must already exist and contain the necessary metadata.
- The minimal metadata content in the target YAML file should be:
_meta:
schema_module: <module_name>
schema_type: <type_name>
Initialization Arguments
Some Zserio types require additional arguments during initialization, either when deserializing from binary or when creating objects from JSON. To support these types, you can specify initialization arguments in the _meta
section of your YAML file:
_meta:
schema_module: <module_name>
schema_type: <type_name>
initialization_args:
- <arg1>
- <arg2>
# ... more arguments as needed
Hint: At the moment only plain values are supported, although zserio supports also compound values as args. Support for these may be added in the future.
These arguments will be passed to the appropriate Zserio functions:
zserio.deserialize_from_file()
when converting from binary to YAMLzserio.from_json_file()
when converting from YAML to binary
For example:
_meta:
schema_module: my_schema
schema_type: MyType
initialization_args:
- 0xAB
- 42
# ... rest of your YAML data
In this example, 0xAB
and 42
will be passed as additional arguments to the initialization functions.
This feature ensures that types requiring additional initialization parameters can be properly handled in both directions of conversion (YAML to binary and binary to YAML).
Example
Zserio Schema Module Creation
-
Create the Zserio schema:
-
Create a file named
person.zs
with the following content:package person; struct Person { string name; string birthdate; string birth_location; string current_job; int32 income; RoleExperience experience[]; }; struct RoleExperience { string role; int32 years; };
-
-
Compile the Zserio schema and generate Python APIs:
-
Run the following command to compile the schema and generate Python sources:
# Generated sources needs type infos so that 'json <-> bin' # conversion works, which is utilized by zs-yaml zserio person.zs -withTypeInfoCode -python zs_gen_api
-
-
Ensure that the schema modules are available in the Python environment:
-
Export the
PYTHONPATH
to include the directory containing the generated Python sources:export PYTHONPATH="zs_gen_api"
-
Use zs-yaml to create data
Using zs-yaml, you can define the same data in a more human-readable YAML format and include necessary metadata along with a custom transformation for the birthdate:
# 1) Metadata is used to specify the type needed for
# (de-)serialization and custom transform functions
# 2) Users are free to use their preferred date format
# for the birth data as the a normalization function
# (defined in the referenced `transformations.py`)
# get invoked.
# 3) Yaml allows avoiding clutter and adding comments
# like this one :)
_meta:
schema_module: person.api
schema_type: Person
transformation_module: "./transformations.py"
name: John Doe
birthdate:
_f: normalize_date
_a: "01/01/1990"
birth_location: Springfield, USA
current_job: Software Engineer
income: 75000
experience:
- role: Intern
years: 1
- role: Junior Developer
years: 2
- role: Senior Developer
years: 3
Example Transformation Module (transformations.py)
def normalize_date(date_str):
from datetime import datetime
for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%m/%d/%Y"):
try:
return datetime.strptime(date_str, fmt).strftime("%Y-%m-%d")
except ValueError:
pass
raise ValueError(f"Date {date_str} is not in a recognized format")
Creating the Binary Representation
After you have installed zs-yaml
, call zs-yaml
to convert your YAML file to a binary representation:
# Install zs-yaml if not already installed.
# Create the binary representation from the YAML file
zs-yaml person.yaml person.bin
Project Structure
setup.py
: Script for setting up the project and installing dependencies.zs_yaml/
: Directory containing the actualzs-yaml
implementation.
Reference
This project references the zserio serialization framework. For more information about zserio, visit the zserio GitHub project.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for zs_yaml-0.3.1a2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c25cc963ed14acbef31b7fb12c77183155d4a7fbda9b6d645a626038092f60d |
|
MD5 | 1f5eae3e18cf052a5b93840ad00c3dd7 |
|
BLAKE2b-256 | 82fabce86a2081617c2914054a3675c191986ed76a239c9a01f8a470572a2755 |