A versatile library for transforming and serializing data models into multiple formats.
Project description
Transmutate
Transmutate is a Python library designed to handle dataclass serialization and deserialization across various formats such as JSON, JSONB, and Protocol Buffers (Proto). The library supports both conversion to these formats and validation of dataclass fields.
Features
- JSON Serialization: Convert dataclasses to and from JSON format.
- JSONB Serialization: Convert dataclasses to and from JSONB format, a compact version of JSON.
- Protocol Buffers Serialization: Generate Proto definitions from dataclasses.
- Field Validation: Custom validation for dataclass fields using
validation_<field>
methods. - Service Definitions: Define gRPC services with customizable RPC methods.
- Proto Generator: Automatically generate Proto files including service and message definitions.
- Easy Integration: Built on top of Python's dataclasses, allowing seamless integration with existing codebases.
Installation
You can install Transmutate via Poetry by adding it to your pyproject.toml
file or by using the following command:
poetry add transmutate
Alternatively, if you're using pip, you can install it with:
pip install transmutate
Usage
Below are some examples demonstrating how to use Transmutate with simple dataclasses.
Defining a Dataclass
You can define your dataclasses using the BaseModel
from Transmutate, which provides built-in serialization and validation capabilities.
from dataclasses import dataclass, field
from typing import List, Optional
from transmutate.base_model import BaseModel
class Person(BaseModel):
name: str
age: int
email: Optional[str] = None
phone_numbers: List[str] = field(default_factory=list)
def validation_age(self):
if not (0 <= self.age <= 120):
raise ValueError("Age must be between 0 and 120.")
def validation_email(self):
if self.email and "@" not in self.email:
raise ValueError("Invalid email address.")
JSON Serialization
Convert a dataclass instance to JSON:
person = Person(name="John Doe", age=30, email="john.doe@example.com")
json_data = person.to_json()
print(json_data)
Output:
{
"name": "John Doe",
"age": 30,
"email": "john.doe@example.com",
"phone_numbers": []
}
Parse a JSON string back to a dataclass instance:
person_from_json = Person.from_json(json_data)
print(person_from_json)
JSONB Serialization
Convert a dataclass instance to JSONB:
jsonb_data = person.to_jsonb()
print(jsonb_data)
Output:
{"name":"John Doe","age":30,"email":"john.doe@example.com","phone_numbers":[]}
Parse a JSONB string back to a dataclass instance:
person_from_jsonb = Person.from_jsonb(jsonb_data)
print(person_from_jsonb)
Proto Serialization
Generate a Proto definition from a dataclass:
proto_definition = person.to_proto()
print(proto_definition)
Output:
syntax = "proto3";
message Person {
string name = 1;
int32 age = 2;
string email = 3;
repeated string phone_numbers = 4;
}
Custom Validation
You can define custom validation logic for fields in your dataclasses using validation_<field>
methods. These methods will automatically be called during initialization.
@dataclass
class Address(BaseModel):
street: str
city: str
zip_code: str
def validation_zip_code(self):
if not self.zip_code.isdigit() or len(self.zip_code) != 5:
raise ValueError("Zip code must be a 5-digit number.")
Defining a gRPC Service
The Service
class allows you to define gRPC services with various RPC types.
from transmutate.service import Service, RpcType
from typing import List
class TestMessage(BaseModel):
name: str
age: int
email: str
phone_numbers: List[str]
class AnotherMessage(BaseModel):
status: str
message: str
service = Service(
name="TestService",
types=[RpcType.UNARY, RpcType.SERVER_STREAMING],
method_names=["GetInfo", "StreamInfo"],
request_dataclass=TestMessage,
response_dataclass=AnotherMessage
)
Proto File Generation
Use ProtoGenerator
to automatically generate Proto files for services and messages.
from transmutate.proto_generator import ProtoGenerator
services = [
Service(
name="TestService",
types=[RpcType.UNARY, RpcType.SERVER_STREAMING],
method_names=["GetInfo", "StreamInfo"],
request_dataclass=TestMessage,
response_dataclass=AnotherMessage
)
]
proto_generator = ProtoGenerator(service_name="TestService", services=services)
proto_generator.generate_proto()
Output Proto file will be saved in the specified directory:
syntax = "proto3";
package testservice;
service TestService {
rpc GetInfo (TestMessage) returns (AnotherMessage);
rpc StreamInfo (TestMessage) returns (stream AnotherMessage);
}
message TestMessage {
string name = 1;
int32 age = 2;
string email = 3;
repeated string phone_numbers = 4;
}
message AnotherMessage {
string status = 1;
string message = 2;
}
Testing
Transmutate includes a suite of unit tests to ensure functionality. You can run the tests using unittest
or pytest
.
# Using unittest
poetry run python -m unittest discover tests
# Using pytest
poetry run pytest tests
Contributing
Contributions to Transmutate are welcome! Please feel free to open issues or submit pull requests on the GitHub repository.
License
Transmutate is open-source software licensed under the MIT License.
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 transmutate-0.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 661c73619a39dfb6ab41791231fda08d1f08c3316e9787c670b936e70c518e6b |
|
MD5 | 00317a93a57025d851604eec2fd85f24 |
|
BLAKE2b-256 | 7a9df9f0aa64b5603ac8d15d8b069ab40da1b2040a38c9b0b85f2017d62c9a5d |