Package: colchian
ColchianIn Greek mythology, the Colchian Dragon guarded the Golden Fleece. Jason was sent on a quest to obtain the Golden Fleece, to prove himself worthy as king - but the Colchian Dragon was the final obstacle (after many others) stopping Jason from obtaining the fleece.Thecolchianpackage contains theColchianclass, which can be used to validate .json documents, or rather the Pythondictresulting from loading a .json file withjson.load().Colchian was developed with validation of .json configurations in mind, specifically those provided by the Conffu (https://pypi.org/project/conffu/) package, but will work for any reasonably sized .json or .yaml file (no testing was performed for large documents, nor has the code been optimised for performance).However, Colchian can be used to validate or correct any dictionary with mostly json-like structure and content.InstallationColchian is available from PyPI:pip install colchianUsageA very simple example:fromcolchianimportColchianfromjsonimportload,dumpstype_dict={"an integer":int,"some strings":[str]}withopen('my.json')asf:data=load(f)try:valid_data=Colchian.validated(data,type_dict)print(f'Valid:\n{dumps(valid_data)}')exceptColchian.ValidationErrorase:print(f'Something is wrong:{e}')A validmy.json:{"an integer":42,"some strings":["vastly","hugely","mind-bogglingly","big"]}To use Colchian:create a dictionary that defines the structure and types of a valid data dictionary (from a .json document);callColchian.validated()with the data and the type dictionary;the result will be the same data, with some data casted to the appropriate type, ifstrict=Falseis passed to the.validated()method;a Colchian.ValidationError exception will be raised if the data is not valid according top the type_dict.A few more tricks:use the Pythontypingmodule to use special types likeUnion,Any,ListorOptional;use wildcards (keys starting with*) to define elements that may appear with any name (and repeatedly);instead oftyping.Union, you can also use a tuple to indicate multiple options (for example(int, float)for a number field);assign a function as a type to perform custom validation or transformation on elements.These two type dictionaries function identically:type_dict1={'words':[str],'secret':(bool,None)}type_dict2={'words':List[str],'secret':Optional[bool]}When setting functions as a type, make sure they match this signature:deffunc(x:Any,*args,strict:bool,keys:List[str])->Any:passThat is, the function should expect the value to validate as the first positional parameter, followed by any extra parameters you may define in the type dict, with two required keyword parameters,strict(which will tell your function if the validation should be strict) andkeys(which will tell your function where the value sits in the .json document).To keep things easily organised, you should probably define such functions as methods on child of the Colchian class. For example:fromtypingimportListfromcolchianimportColchianclassMyColchian(Colchian):@staticmethoddeffizzbuzz(xs:List[int],fizz:str,buzz:str,strict:bool,keys:List[str]):return[fizz*(i%3==0)+buzz*(i%5==0)oriforiinxs]data={'xs':range(15)}type_dict={'xs':(MyColchian.fizzbuzz,'fizz','buzz')}print(MyColchian.validated(data,type_dict))You can pass extra parameters to your functions like this:type_dict={'xs':(MyColchian.dt_str,'%Y-%m-%d%H:%M')}The validation will interpret the rest of the tuple as positional parameters after the value, instead of type options.Note: this means that you can't pass two functions as the only options for a type:# causes problems:type_dict={'xs':(MyColchian.method1,MyColchian.method2)}This will cause values for key'xs'to be validated by callingMyColchian.method1(value, MyColchian.method2, strict, keys), instead of trying each function separately as you might expect. If you need this functionality, you can instead do this:# no problem:type_dict={'xs':((MyColchian.method1,),(MyColchian.method2,))}Similarly, if you want to validate an optional value against a function or method, you should use(None, function_name)instead of(function_name, None), as that would result in a call tofunction_name(value, None, strict, keys).An additional example is available intyped_configuration.py. Try that code and experiment with breakingexample_configuration.jsonin interesting ways.WildcardsIf you define wildcards in a type dictionary, elements that don't match required keys will be matched against them. If there are multiple wildcards, Colchian will try them all. For example:type_dict={'*:1':{'type':'car','wheels':4,'engine':float,'electric':typing.Optional[bool]},'*:2':{'type':'bicycle','wheels':2,'electric':bool}}Makes thisvehicles.jsona valid file:{"Peugeot 208":{"type":"car","wheels":4,"engine":1.4,"electric":false},"Batavus Socorro":{"type":"bicycle","wheels":2,"electric":false},"T-Ford":{"type":"car","wheels":4,"engine":2.9}}Note that you can't use the key'*'twice, which is why the wildcards are distinguished as'*:1'and'*:2'.Dictionary constructorWhen you callColchian.validate()with some dictionary, it constructs a new instance of that dictionary and all of its parts. If you pass it some subclass of a dictionary (as for example, a Conffu DictConfig), you may want to pass specific parameters to its constructor.fromcolchianimportColchianclassMyDict(dict):# your dict (class or instance) may have some attribute that's important to youimportant=Truedef__init__(self,*args,some_param=True,**kwargs):super().__init__(*args,**kwargs)# and possibly, you want it set as the object is constructedself.some_attribute=some_paramdefcreate_my_dict(md):# create a new object of the same type as md, passing parameters to its constructor matching those of mdresult=type(md)(some_param=md.some_param)# set other attributes to match the passed object mdresult.important=md.important# return the newly created objectreturnresult# create a MyDict with specific settingssome_dict=MyDict({'a':1},some_param=False)some_dict.important=False# tell colchian to use a factory function when creating new instances of MyDict, instead of just the constructorColchian.type_factories[MyDict]=create_my_dict# validated_dict will have settings matching some_dictvalidated_dict=Colchian.validated(some_dict,{'a':int})Note: this behaviour also means that Colchian will reconstruct lists - it does not checktype_factorieswhen doing so. It is assumed Colchian is primarily applied to dictionaries derived from .json documents, and only accounts for data types it would encounter in them.