Documentation for typic.register

[ahobsonsayers]

Description

In the documentation under the warning about handling unions it is specified that to handle unions we have to define a custom converter, however the link in the documentation goes nowhere.

Through browsing the issues I found out about the ability to define a coercer & type-checker which can then be registered with typic.register. I think i have mostly figured out how to use this, but it would be useful if there was some documentation about it and how it can be used.

I would be very willing to open a PR myself but I don't think I fully understand the API.

Also wanted to say i think typical is great, thanks for the wonderful library!

[seandstewart]

Hey @ahobsonsayers -

Thanks for the call out on this one, looks like the documentation was dropped when the library was migrated to hand-written docs instead of auto-generated. That being said, I've hoped to add a more wholistic way to define custom serializers at a part of #72, and ideally drop this function eventually.

As it is, the API is quite simple, you register your type by providing a callable which takes a type and checks whether it is your target type, and a deserializer which will be responsible for converting an input into your type.

A very contrived example:

import typic

from typing import Union

MyUnion = Union[str, int]

def check_my_union(t):
    return t == MyUnion

def convert_my_union(v):
    if isinstance(v, int):
        return v
    if isinstance(v, (str, bytes)) and v.isdigit():
        return int(v)
    return str(v)

typic.register(check_my_union, convert_my_union)

[ahobsonsayers]

Thanks for the reply and the extremely clear example, it has really helped me and hope it will help others in a similar situation. I saw #72 and it looks like a great idea!

Would you find it helpful if I opened a PR for documentation? I'm always glad to help.

Many thanks again

[ahobsonsayers]

Also, ive just noticed, in your above example

typic.register(check_my_union, convert_my_union)

should be

typic.register(convert_my_union, check_my_union)

According to your annotations:

(variable) register: (deserializer: DeserializerT, check: DeserializerT) -> None