# Type Hooks

Note

If you want to customize serialization for specific fields (rather than a type everywhere it appears), see Serializer Hooks.

Type hooks let you extend Dataclass Wizard to support custom or unsupported types, by defining how a type is:

- loaded (parsed) from JSON/dicts into a Python object, and

- dumped (serialized) back into JSON-compatible data.

This is the recommended way to add support for types such as `ipaddress.IPv4Address`, `pathlib.Path`, custom IDs, and other domain types.

## When to use type hooks

Use type hooks when:

- a type is not supported out of the box and you want a clean, reusable solution

- you want consistent behavior for a type across many dataclasses

- you want to avoid sprinkling per-field logic throughout your models

If you only need special handling for a single field (or a small subset of fields), prefer Serializer Hooks.

## Quick start: register a type

The simplest approach is to register a type and rely on sensible defaults:

- load: `Type(value)`

- dump: `str(value)`

Example: ipaddress.IPv4Address

    from __future__ import annotations  # Remove if Python 3.10+

    from ipaddress import IPv4Address

    from dataclass_wizard import DataclassWizard

    class Foo(DataclassWizard):
        # DataclassWizard auto-applies @dataclass to subclasses
        c: IPv4Address | None = None

    Foo.register_type(IPv4Address)

    foo = Foo.from_dict({"c": "127.0.0.1"})
    assert foo.c == IPv4Address("127.0.0.1")
    assert foo.to_dict() == {"c": "127.0.0.1"}

If you omit the registration, you will get an error indicating the type is not supported (and it should indicate whether the failure occurred during load or dump).

## No Inheritance Needed

Type hooks also work without subclassing `DataclassWizard` or `JSONWizard`. This is useful when you prefer plain dataclasses and use the functional API (`fromdict`/`asdict`).

    from __future__ import annotations  # Remove if Python 3.10+

    from dataclasses import dataclass
    from ipaddress import IPv4Address

    from dataclass_wizard import LoadMeta, asdict, fromdict, register_type

    @dataclass
    class Foo:
        b: bytes = b""
        s: str | None = None
        c: IPv4Address | None = None

    LoadMeta(v1=True).bind_to(Foo)

    # Register IPv4Address with default hooks (load=IPv4Address, dump=str)
    register_type(Foo, IPv4Address)

    data = {"b": "AAAA", "c": "127.0.0.1", "s": "foobar"}

    foo = fromdict(Foo, data)
    assert asdict(foo) == data
    assert asdict(fromdict(Foo, asdict(foo))) == data

## Registering custom load and dump functions

You can override the defaults by providing custom functions. In general:

- The load function should return the target type (or object).

- The dump function must return a JSON-serializable value (`str`, `int`, `float`, `bool`, `None`, `list`, `dict`).

    from decimal import Decimal, ROUND_HALF_UP

    from dataclass_wizard import DataclassWizard

    def load_decimal(v):
        # Normalize all decimals to 2 decimal places on load
        return Decimal(v).quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)

    def dump_decimal(v: Decimal):
        # Serialize as string to preserve precision
        return str(v)

    class Invoice(DataclassWizard):
        total: Decimal

    # Override the built-in Decimal behavior
    Invoice.register_type(Decimal, load=load_decimal, dump=dump_decimal)

    invoice = Invoice.from_dict({'total': '1.235'})
    print(invoice)              # Invoice(total=Decimal('1.24'))
    print(invoice.to_dict())    # {'total': '1.24'}

## V1 code generation hooks (advanced)

If you have v1 enabled, you may choose to provide v1 codegen hooks. These hooks accept `(TypeInfo, Extras)` and return a string expression (or `TypeInfo`) used by the v1 compiler.

This is useful if you need to integrate directly with the v1 compilation pipeline.

Note

Most users should start with `register_type()` and only use codegen hooks when needed.

Example: `IPv4Address` with v1 codegen hooks

    from dataclasses import dataclass
    from ipaddress import IPv4Address

    from dataclass_wizard import JSONWizard
    from dataclass_wizard.v1.models import TypeInfo, Extras

    def load_to_ipv4_address(tp: TypeInfo, extras: Extras) -> str:
        # Wrap the value expression using the type's constructor
        return tp.wrap(tp.v(), extras)

    def dump_from_ipv4_address(tp: TypeInfo, extras: Extras) -> str:
        # Dump an IPv4Address by converting to string
        return f"str({tp.v()})"

    @dataclass
    class Foo(JSONWizard):
        class Meta(JSONWizard.Meta):
            v1 = True
            v1_type_to_load_hook = {IPv4Address: load_to_ipv4_address}
            v1_type_to_dump_hook = {IPv4Address: dump_from_ipv4_address}

        c: IPv4Address | None = None

    foo = Foo.from_dict({"c": "127.0.0.1"})
    assert foo.to_dict() == {"c": "127.0.0.1"}

## Declaring hooks via Meta

If you prefer a declarative style, you can set hooks in `Meta`. This is especially useful for v1.

    from ipaddress import IPv4Address

    from dataclass_wizard import DataclassWizard

    # DataclassWizard sets `v1=True` and auto-applies @dataclass to subclasses
    class Foo(DataclassWizard):
        c: IPv4Address | None = None

    Foo.register_type(IPv4Address)

If you want to avoid method calls entirely, you can also register via `Meta`. (Exact configuration options may vary depending on the engine you use.)

    from __future__ import annotations  # Remove if Python 3.10+

    from dataclasses import dataclass
    from ipaddress import IPv4Address

    from dataclass_wizard import JSONWizard

    @dataclass
    class Foo(JSONWizard):
        class Meta(JSONWizard.Meta):
            v1 = True
            # Equivalent of Foo.register_type(IPv4Address)
            # Defaults: load=IPv4Address, dump=str
            v1_type_to_load_hook = {IPv4Address: IPv4Address}
            v1_type_to_dump_hook = {IPv4Address: str}

        c: IPv4Address | None = None

    assert Foo.from_dict({'c': '1.2.3.4'}).c == IPv4Address('1.2.3.4')  # True

## Enum example: load & dump by name

By default, enums are typically loaded and dumped using their `value`. If you prefer to load and dump enums by their name instead, you can override the default behavior using type hooks.

    from enum import Enum

    from dataclass_wizard import DataclassWizard

    class MyEnum(Enum):
        NAME_1 = 'one'
        NAME_2 = 'two'

    def load_enum_by_name(v):
        # Input example: 'NAME 1' -> MyEnum.NAME_1
        return MyEnum[v.replace(' ', '_')]

    def dump_enum_by_name(e: MyEnum):
        # Output example: MyEnum.NAME_1 -> 'NAME 1'
        return e.name.replace('_', ' ')

    class MyClass(DataclassWizard):
        my_str: str
        my_enum: MyEnum

    # Override the built-in Enum behavior
    MyClass.register_type(MyEnum, load=load_enum_by_name, dump=dump_enum_by_name)

    data = {'my_str': 'my string', 'my_enum': 'NAME 1'}

    c = MyClass.from_dict(data)
    assert c.my_enum is MyEnum.NAME_1
    assert c.to_dict() == data

## Runtime vs v1 codegen hooks

Dataclass Wizard supports two styles of hooks:

Runtime hooks

  Regular Python callables used at runtime.

  - load hook: `fn(value) -> object`

  - dump hook: `fn(object) -> json_value`

V1 codegen hooks

  Functions used by the v1 compiler.

  - hook: `fn(TypeInfo, Extras) -> str | TypeInfo`

If you provide a codegen hook, it must return a valid Python expression as a string, referencing any required types/functions that are in scope for the generated code.

## Errors and troubleshooting

Unsupported type errors

  If a type is unsupported, Dataclass Wizard will raise a parse/serialization error. The error should indicate:

  - the field name

  - whether the error occurred during load or dump

  - the unsupported type

  - a resolution hint (register a type hook)

If your dump hook returns a non-JSON value

  Ensure your dump hook returns JSON-compatible primitives (or nested structures composed of primitives).

If you see name errors in v1 generated code

  Your codegen hook must reference names that are in scope for the generated function. Prefer builtins (like `str`) or ensure the type/function is available to the compiler (via locals injection, if applicable).

## See also

- Serializer Hooks (field-level customization)

- Overview (supported types and general usage)