Metadata-Version: 2.1
Name: jsserialize
Version: 0.5
Summary: 1-step serialization to/from json: handles user classes and circular refs
Home-page: https://alcramer@bitbucket.org/alcramer/jsserialize.git
Author: Al Cramer
Author-email: ac2.71828@gmail.com
License: UNKNOWN
Keywords: json,serialize,serialization
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown

## jsserialize.py: serialize python data structures as json strings

This module defines the functions "encode" and "decode",
which encode/decode data to and from json strings.
Unlike the functions in the standard "json" package,
these can automatically handle user-defined classes and circular references.

		jsserialize functions:

		encode(data,custom_encode=None):
			Encode "data" to a json string. 
			Use "custom_encode" to override the default encoding of objects.
			Returns: json string encoding of "data"

		decode(jsonstr,custom_decode=None):
			Recreate data from a json string ("jsonstr").  
			Use "custom_decode" to override the default decoding of objects.
			Returns: the recreated data

Custom encode/decode:

When we encode an object, we create a dictionary of 
name/value pairs giving the object's attributes. This contains 
the info needed to rebuild the object at decode time. The default 
handling requires that the object's class have a default 
constructor (ie., a constructor that doesn't accept arguments, "MyClass()").
If that's not possible, you can pass a custom encoder to "encode" 
(and custom decoder to "decode").

The custom encoder accepts an object and returns a dictionary.
Returning "None" means the object wasn't encoded, and we should
use the default handling. The custom decoder accepts a class name
and dictionary and returns an object. Returning "None" means
it wasn't decoded, and we should use the default handling.
Here's an example: we encode/decode a date from
the python datetime module.

		def custom_encode(obj):
    		if obj.__class__.__name__ == 'date':
        		# 'obj.isoformat()' returns a str
        		return {'isoformat': obj.isoformat()}
    		return None

		def custom_decode(classname,dct):
    		if classname == 'datetime.date':
        		# "fromisoformat" is class method that creates
        		# a date object from an isoformat string
        		return datetime.date.fromisoformat(dct['isoformat'])
    		return None

Note: in "custom_decode", "classname" is the full classname 
(module name, followed by the name in the class definition).

### Requirements and Installation
Requires Python 3.  Install with pip:

		pip install jsserialize

### Dev Notes
This repository contains "jsserialize.py". Additonal files ("setup.py",
"setup.cfg", and "hwoto_pypi.txt") are for uploading the module to pypi.

### Sample Code

		import jsserialize
		
		# We need some data to encode. We'll use a tree built from Nodes.
		# The base class None has a "parent" attribute and a list "kids"
		# containing child nodes. From the base class we define 2 subclasses,
		# "A" and "B". The A class has a "color" attribute whose value is a string.
		# The B class has a "date" attribute whose value is an object of class
		# "date", from the standard python "datetime" module.
		
		import datetime
		nodeid = 0
		class Node():
    		def __init__(self):
        		global nodeid
        		self.id = str(nodeid)
        		nodeid += 1
        		self.parent = None
        		self.kids = []
		
    		def add_kid(self,kid):
        		self.kids.append(kid)
        		kid.parent = self
		
    		def attrs_to_str(self):
        		# child classes override this to return a string giving
        		# attribute name/values.
        		return ''
		
    		def printme(self,indent=''):
        		pid = "None" if self.parent is None else self.parent.id
        		print('%s%s %s parent:%s %s' %
            		(indent,self.__class__.__name__,
            		self.id,pid,self.attrs_to_str()))
        		indent += '  '
        		for k in self.kids:
            		k.printme(indent)
		
		class A(Node):
    		def __init__(self,color='red'):
        		super().__init__()
        		self.color = color
		
    		def attrs_to_str(self):
        		return 'color:%s' % self.color
		
		class B(Node):
    		def __init__(self,date=None):
        		super().__init__()
        		self.date = date
		
    		def attrs_to_str(self):
        		return 'date:%s' % (
            		'None' if self.date is None else self.date.isoformat())
		
		# make the data we'll encode/decode: a tree built from A and B nodes.
		def make_data():
    		root = A()
    		kid1 = A('yellow')
    		kid2 = B(datetime.date.fromordinal(1))
    		root.add_kid(kid1)
    		root.add_kid(kid2)
    		kid2.add_kid( A('blue') )
    		kid2.add_kid( B(datetime.date.today()) )
    		return root
		
		# Here are the custom encode/decode functions. We need them
		# because our data includes objects of class "date"
		# from the python standard "datetime" module, and jsserialize
		# doesn't know how to encode/decode objects of that class.
		# Note that these encode/decode functions only need to handle
		# "date" objects -- our data also includes objects of class "A"
		# and "B", but jsserialize can handle them without our help. (For this
		# to work, we have to make sure our user-defined classes have
		# default constructors).
		
		def custom_encode(obj):
    		if obj.__class__.__name__ == 'date':
        		# 'obj.isoformat()' returns a str
        		return {'isoformat': obj.isoformat()}
    		# returning None tells jsserialize: we didn't encode the
    		# object, you do it.
    		return None
		
		def custom_decode(classname,dct):
    		# Notice that classname is the "full" name for the class:
    		# module name, followed the name that appeared in the
    		# class definition.
    		if classname == 'datetime.date':
        		# "fromisoformat" is class method that creates
        		# a date object from an isoformat string
        		return datetime.date.fromisoformat(dct['isoformat'])
    		# returning None tells jsserialize: we didn't decode the
    		# object, you do it.
    		return None
		
		def test():
    		# create data to be encoded: a tree built from nodes
    		data = make_data()
    		print("data to be encoded:")
    		data.printme()
		
    		# get the json string encoding
    		json_str = jsserialize.encode(data,custom_encode=custom_encode)
		
    		# decode the json_str, recreating the data
    		data2 = jsserialize.decode(json_str, custom_decode=custom_decode)
    		print("\ndecoded data:")
    		data2.printme()
		
    		# print the json string
    		print("\njson string:")
    		print(json_str)
		
		if __name__=='__main__':
    		test()

### Who do I talk to? ###

Al Cramer (ac2.7@1828@gmail.com)

Copyright Al Cramer 2022


