{"id":21295670,"url":"https://github.com/hgromer/pymarshaler","last_synced_at":"2025-07-11T17:30:30.524Z","repository":{"id":43783718,"uuid":"308922219","full_name":"hgromer/pymarshaler","owner":"hgromer","description":"Marshall python objects to and from JSON","archived":false,"fork":false,"pushed_at":"2023-01-31T03:46:07.000Z","size":58,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-06T18:08:32.736Z","etag":null,"topics":["marshalling","python","serialization"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hgromer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-10-31T16:19:25.000Z","updated_at":"2023-08-05T15:15:13.000Z","dependencies_parsed_at":"2023-02-16T15:31:36.693Z","dependency_job_id":null,"html_url":"https://github.com/hgromer/pymarshaler","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgromer%2Fpymarshaler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgromer%2Fpymarshaler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgromer%2Fpymarshaler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hgromer%2Fpymarshaler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hgromer","download_url":"https://codeload.github.com/hgromer/pymarshaler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225741005,"owners_count":17516896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["marshalling","python","serialization"],"created_at":"2024-11-21T14:06:10.266Z","updated_at":"2024-11-21T14:06:10.895Z","avatar_url":"https://github.com/hgromer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pymarshaler - Marshal and Unmarshal Python Objects\n\n## Disclaimer\nThis tool is in no way production ready\n\n## About\nPymarshaler allows you to marshal and unmarshal any python object directly to and from a JSON formatted string. \n\nPymarshaler takes advantage of python's new [typing support](https://docs.python.org/3/library/typing.html). By reading class init param types, we are able to walk down nested JSON structures and assign appropriate values.\n\n## Basic Usage\n\n### Declare a class with typing information \n\nNote, we can use regular old classes as long as their init methods are annotated properly, but it's preferable to use dataclasses whenever possible\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Test:\n    \n    name: str\n```\n\nThat's it! We can now marshal, and more importantly, unmarshal this object to and from JSON.\n\n```python\nfrom pymarshaler.marshal import Marshal\nimport json\n\ntest_instance = Test('foo')\nblob = Marshal.marshal(test_instance)\nprint(blob.decode())\n\u003e\u003e\u003e '{name: foo}'\n\nmarshal = Marshal()\nresult = marshal.unmarshal(Test, json.loads(blob))\nprint(result.name)\n\u003e\u003e\u003e 'foo'\n```\n\nWe also use `marshal.unmarshal_str(cls, str)` if we want to unmarshal directly from the blob source.\n\nThis is a pretty trivial example, lets add in a nested class\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass StoresTest:\n    \n    test: Test\n\n    \nstores_test = StoresTest(Test('foo'))\nblob = marshal.marshal(stores_test)\nprint(blob)\n\u003e\u003e\u003e '{test: {name: foo}}'\n\nresult = marshal.unmarshal(StoresTest, json.loads(blob))\nprint(result.test.name)\n\u003e\u003e\u003e 'foo'\n```\n\nAs you can see, adding a nested class is as simple as as adding a basic structure.\n\nPymarshaler will fail when encountering an unknown field by default, however you can configure it to ignore unknown fields\n\n```python\nfrom pymarshaler.marshal import Marshal \nfrom pymarshaler.arg_delegates import ArgBuilderFactory\n\nmarshal = Marshal()\nblob = {'test': 'foo', 'unused_field': 'blah'}\nresult = marshal.unmarshal(Test, blob)\n\u003e\u003e\u003e 'Found unknown field (unused_field: blah). If you would like to skip unknown fields create a Marshal object who can skip ignore_unknown_fields'\n\nmarhsal = Marshal(ignore_unknown_fields=True)\nresult = marshal.unmarshal(Test, blob)\nprint(result.name)\n\u003e\u003e\u003e 'foo'\n```\n\n## Advanced Usage\n\nWe can use pymarshaler to handle containers as well. Again we take advantage of python's robust typing system\n\n```python\nfrom dataclasses import dataclass\nfrom pymarshaler.marshal import Marshal\nfrom typing import Set\nimport json\n\n@dataclass\nclass TestContainer:\n \n    container: Set[str]\n    \n\nmarshal = Marshal()\ncontainer_instance = TestContainer({'foo', 'bar'})        \nblob = marshal.marshal(container_instance)\nprint(blob.decode())\n\u003e\u003e\u003e '{container: [\"foo\", \"bar\"]}'\n\nresult = marshal.unmarshal(TestContainer,json.loads(blob))\nprint(result.container)\n\u003e\u003e\u003e '{foo, bar}'\n```\n\nPymarshaler can also handle containers that store user defined types. The `Set[str]` could easily have been `Set[UserDefinedType]`\n\nPymarshaler also supports default values, and will use any default values supplied in the `__init__` if those values aren't present in the JSON data.\n\n```python\nfrom dataclasses import dataclass\nfrom pymarshaler.marshal import Marshal\n\n@dataclass\nclass TestWithDefault:\n    \n    name: str = 'foo'\n\n\nmarshal = Marshal()\nresult = marshal.unmarshal(TestWithDefault, {})\nprint(result.name)\n\u003e\u003e\u003e 'foo'\n```\nPymarshaler will raise an error if any non-default attributes aren't given\n\nPymarshaler also supports a validate method on creation of the python object. This method will be called before being returned to the user.\n\n```python\nfrom dataclasses import dataclass\nfrom pymarshaler.marshal import Marshal\n\n\n@dataclass\nclass TestWithValidate:\n    \n    name: str\n\n    def validate(self):\n        print(f'My name is {self.name}!')\n\n\nmarshal = Marshal()\nresult = marshal.unmarshal(TestWithValidate, {'name': 'foo'})\n\u003e\u003e\u003e 'My name is foo!'\n```\n\nThis can be used to validate the python object right at construction, potentially raising an error if any of the fields have invalid values\n\nIt's also possible to register your own custom unmarshaler for specific user defined classes by passing in a function pointer that will \"resolve\" the raw data\n\n```python\nfrom dataclasses import dataclass\n\nfrom pymarshaler.marshal import Marshal\n\n\n@dataclass\nclass ClassWithMessage:\n    message: str\n\n\nclass ClassWithCustomDelegate:\n\n    def __init__(self, message_obj: ClassWithMessage):\n        self.message_obj = message_obj\n\n\ndef custom_delegate(data):\n    return ClassWithCustomDelegate(ClassWithMessage(data['message']))\n\n\nmarshal = Marshal()\nmarshal.register_delegate(ClassWithCustomDelegate, custom_delegate)\nresult = marshal.unmarshal(ClassWithCustomDelegate, {'message': 'Hello from the custom delegate!'})\nprint(result.message_obj)\n\u003e\u003e\u003e 'Hello from the custom delegate!'\n```\n\nThe result from any delegate should be the initialized resulting class instance\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhgromer%2Fpymarshaler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhgromer%2Fpymarshaler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhgromer%2Fpymarshaler/lists"}