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>
Deserialization Arguments
Some zserio types require additional arguments during deserialization. To support these types, you can specify deserialization arguments in the _meta
section of your YAML file:
_meta:
schema_module: <module_name>
schema_type: <type_name>
deserialization_args:
- <arg1>
- <arg2>
# ... more arguments as needed
These arguments will be passed to the zserio.deserialize_from_file
function when converting from binary to YAML. For example:
_meta:
schema_module: my_schema
schema_type: MyType
deserialization_args:
- 0xAB
- 42
# ... rest of your YAML data
In this example, 0xAB
and 42
will be passed as additional arguments to the deserialization function.
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.1a1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cc2eeeef56c5d721e19d41160bac052fa3bb754a3459dcab77a2dc286421dc8d |
|
MD5 | 3abd9b95f7e22d651fc8a9fd6e5f2fc6 |
|
BLAKE2b-256 | d7c8b2c785861c9761309a77d7f846b6a0d993a0e8b485da2ce12bf08c0b37ac |