API Reference

cwtch.cwtch

is_cwtch_model(cls) -> bool

Check if class is a cwtch model.

Source code in cwtch/cwtch.py

def is_cwtch_model(cls) -> bool:
    """Check if class is a cwtch model."""

    return bool(getattr(cls, "__cwtch_model__", None) and not getattr(cls, "__cwtch_view__", None))

is_cwtch_view(cls) -> bool

Check if class is a cwtch view.

Source code in cwtch/cwtch.py

def is_cwtch_view(cls) -> bool:
    """Check if class is a cwtch view."""

    return bool(getattr(cls, "__cwtch_model__", None) and getattr(cls, "__cwtch_view__", None))

field(default: Any = _MISSING, *, default_factory: _Missing[Callable] = _MISSING, init: bool = True, init_alias: Unset[str] = UNSET, repr: Unset[Literal[False]] = UNSET, compare: Unset[bool] = UNSET, property: Unset[Literal[True]] = UNSET, validate: Unset[bool] = UNSET, metadata: Unset[dict] = UNSET, kw_only: Unset[dict] = UNSET) -> Any

Return an object to identify dataclass fields.

Parameters:

Name	Type	Description	Default
default	Any	The default value of the field.	_MISSING
default_factory	_Missing[Callable]	A 0-argument function called to initialize a field's value.	_MISSING
init	bool	If init is true, the field will be a parameter to the class's __init__() function.	True
repr	Unset[Literal[False]]	If repr is true, the field will be included in the object's repr().	UNSET
compare	Unset[bool]	If compare is true, the field will be used in comparison functions.	UNSET
property	Unset[Literal[True]]		UNSET
validate	Unset[bool]		UNSET
metadata	Unset[dict]	If specified, must be a mapping which is stored but not otherwise examined by dataclass.	UNSET
kw_only	Unset[dict]	If kw_only true, the field will become a keyword-only parameter to __init__().	UNSET

It is an error to specify both default and default_factory.

Source code in cwtch/cwtch.py

def field(
    default: Any = _MISSING,
    *,
    default_factory: _Missing[Callable] = _MISSING,
    init: bool = True,
    init_alias: Unset[str] = UNSET,
    repr: Unset[Literal[False]] = UNSET,
    compare: Unset[bool] = UNSET,
    property: Unset[Literal[True]] = UNSET,
    validate: Unset[bool] = UNSET,
    metadata: Unset[dict] = UNSET,
    kw_only: Unset[dict] = UNSET,
) -> Any:
    """
    Return an object to identify dataclass fields.

    Args:
        default: The default value of the field.
        default_factory: A 0-argument function called to initialize a field's value.
        init: If init is true, the field will be a parameter to the class's `__init__()` function.
        repr: If repr is true, the field will be included in the object's repr().
        compare: If compare is true, the field will be used in comparison functions.
        property:
        validate:
        metadata: If specified, must be a mapping which is stored but not otherwise examined by dataclass.
        kw_only: If kw_only true, the field will become a keyword-only parameter to `__init__()`.

    It is an error to specify both default and default_factory.
    """
    return Field(
        default=default,
        default_factory=default_factory,
        init=init,
        init_alias=init_alias,
        repr=repr,
        compare=compare,
        property=property,
        validate=validate,
        metadata=metadata,
        kw_only=kw_only,
    )

dataclass(cls=None, *, slots: Unset[bool] = UNSET, kw_only: Unset[bool] = UNSET, env_prefix: Unset[str | Sequence[str]] = UNSET, env_source: Unset[Callable] = UNSET, validate: Unset[bool] = UNSET, add_disable_validation_to_init: Unset[bool] = UNSET, show_input_value_on_error: Unset[bool] = UNSET, extra: Unset[Literal['ignore', 'forbid']] = UNSET, repr: Unset[bool] = UNSET, eq: Unset[bool] = UNSET, recursive: Unset[bool | Sequence[str]] = UNSET, handle_circular_refs: Unset[bool] = UNSET) -> Callable[[Type[T]], Type[T]]

Parameters:

Name	Type	Description	Default
slots	Unset[bool]	If true, __slots__ attribute will be generated and new class will be returned instead of the original one. If __slots__ is already defined in the class, then TypeError is raised.	UNSET
kw_only	Unset[bool]	If kw_only is true, then by default all fields are keyword-only.	UNSET
env_prefix	Unset[str | Sequence[str]]	Prefix(or list of prefixes) for environment variables.	UNSET
env_source	Unset[Callable]	Environment variables source factory. By default os.environ.	UNSET
validate	Unset[bool]	Validate or not fields.	UNSET
add_disable_validation_to_init	Unset[bool]	Add disable_validation keywoard argument to __init__() method to disable validation.	UNSET
extra	Unset[Literal['ignore', 'forbid']]	Ignore or forbid extra arguments passed to init.	UNSET
repr	Unset[bool]	If true, a __rich_repr__() method will be generated and rich.repr.auto decorator applied to the class.	UNSET
eq	Unset[bool]	If true, an __eq__() method will be generated. This method compares the class as if it were a tuple of its fields, in order. Both instances in the comparison must be of the identical type.	UNSET
recursive	Unset[bool | Sequence[str]]	...	UNSET
handle_circular_refs	Unset[bool]	Handle or not circular refs.	UNSET

Source code in cwtch/cwtch.py

@dataclass_transform(field_specifiers=(field,))
def dataclass(
    cls=None,
    *,
    slots: Unset[bool] = UNSET,
    kw_only: Unset[bool] = UNSET,
    env_prefix: Unset[str | Sequence[str]] = UNSET,
    env_source: Unset[Callable] = UNSET,
    validate: Unset[bool] = UNSET,
    add_disable_validation_to_init: Unset[bool] = UNSET,
    show_input_value_on_error: Unset[bool] = UNSET,
    extra: Unset[Literal["ignore", "forbid"]] = UNSET,
    repr: Unset[bool] = UNSET,
    eq: Unset[bool] = UNSET,
    recursive: Unset[bool | Sequence[str]] = UNSET,
    handle_circular_refs: Unset[bool] = UNSET,
) -> Callable[[Type[T]], Type[T]]:
    """
    Args:
        slots: If true, `__slots__` attribute will be generated
            and new class will be returned instead of the original one.
            If `__slots__` is already defined in the class, then TypeError is raised.
        kw_only: If kw_only is true, then by default all fields are keyword-only.
        env_prefix: Prefix(or list of prefixes) for environment variables.
        env_source: Environment variables source factory. By default os.environ.
        validate: Validate or not fields.
        add_disable_validation_to_init: Add disable_validation keywoard argument to `__init__()` method
            to disable validation.
        extra: Ignore or forbid extra arguments passed to init.
        repr: If true, a `__rich_repr__()` method will be generated and rich.repr.auto decorator applied to the class.
        eq: If true, an `__eq__()` method will be generated.
            This method compares the class as if it were a tuple of its fields, in order.
            Both instances in the comparison must be of the identical type.
        recursive: ...
        handle_circular_refs: Handle or not circular refs.
    """

    if slots is UNSET:
        slots = SLOTS
    if kw_only is UNSET:
        kw_only = KW_ONLY
    if validate is UNSET:
        validate = VALIDATE
    if add_disable_validation_to_init is UNSET:
        add_disable_validation_to_init = ADD_DISABLE_VALIDATION_TO_INIT
    if show_input_value_on_error is UNSET:
        show_input_value_on_error = SHOW_INPUT_VALUE_ON_ERROR
    if extra is UNSET:
        extra = EXTRA
    if repr is UNSET:
        repr = REPR
    if eq is UNSET:
        eq = EQ
    if recursive is UNSET:
        recursive = RECURSIVE
    if handle_circular_refs is UNSET:
        handle_circular_refs = HANDLE_CIRCULAR_REFS

    def wrapper(
        cls,
        slots=slots,
        kw_only=kw_only,
        env_prefix=env_prefix,
        env_source=env_source,
        validate=validate,
        add_disable_validation_to_init=add_disable_validation_to_init,
        extra=extra,
        repr=repr,
        eq=eq,
        recursive=recursive,
        handle_circular_refs=handle_circular_refs,
    ):
        return _build(
            cls,
            cast(bool, slots),
            cast(bool, kw_only),
            cast(
                Unset[Sequence[str]],
                env_prefix if env_prefix is UNSET or isinstance(env_prefix, (list, tuple, set)) else [env_prefix],
            ),
            env_source,
            cast(bool, validate),
            cast(bool, add_disable_validation_to_init),
            cast(Literal["ignore", "forbid"], extra),
            cast(bool, repr),
            cast(bool, eq),
            cast(bool, recursive),
            cast(bool, handle_circular_refs),
        )

    if cls is None:
        return wrapper

    return wrapper(cls)

view(base_cls, name: Unset[str] = UNSET, *, attach: Unset[bool] = UNSET, include: Unset[Sequence[str]] = UNSET, exclude: Unset[Sequence[str]] = UNSET, slots: Unset[bool] = UNSET, kw_only: Unset[bool] = UNSET, env_prefix: Unset[str | Sequence[str]] = UNSET, env_source: Unset[Callable] = UNSET, validate: Unset[bool] = UNSET, add_disable_validation_to_init: Unset[bool] = UNSET, extra: Unset[Literal['ignore', 'forbid']] = UNSET, repr: Unset[bool] = UNSET, eq: Unset[bool] = UNSET, recursive: Unset[bool | Sequence[str]] = UNSET, handle_circular_refs: Unset[bool] = UNSET) -> Callable[[Type[T]], Type[T]]

Parameters:

Name	Type	Description	Default
name	Unset[str]	View name.	UNSET
attach	Unset[bool]	If true, view will be attached to base cls.	UNSET
include	Unset[Sequence[str]]	List of fields to include in view.	UNSET
exclude	Unset[Sequence[str]]	List of fields to exclude from view.	UNSET
slots	Unset[bool]	If true, __slots__ attribute will be generated and new class will be returned instead of the original one. If __slots__ is already defined in the class, then TypeError is raised. If UNSET value from base view model will be used.	UNSET
kw_only	Unset[bool]	If kw_only is true, then by default all fields are keyword-only.	UNSET
env_prefix	Unset[str | Sequence[str]]	Prefix(or list of prefixes) for environment variables. If UNSET value from base view model will be used.	UNSET
env_source	Unset[Callable]	Environment variables source factory. If UNSET value from base view model will be used.	UNSET
validate	Unset[bool]	Validate or not fields. If UNSET value from base view model will be used.	UNSET
add_disable_validation_to_init	Unset[bool]	Add disable_validation keywoard argument to __init__() method to disable validation. If UNSET value from base view model will be used.	UNSET
extra	Unset[Literal['ignore', 'forbid']]	Ignore or forbid extra arguments passed to init. If UNSET value from base view model will be used.	UNSET
repr	Unset[bool]	If true, a __rich_repr__() method will be generated and rich.repr.auto decorator applied to the class. If UNSET value from base view model will be used.	UNSET
eq	Unset[bool]	If true, an __eq__() method will be generated. This method compares the class as if it were a tuple of its fields, in order. Both instances in the comparison must be of the identical type. If UNSET value from base view model will be used.	UNSET
recursive	Unset[bool | Sequence[str]]	...	UNSET
handle_circular_refs	Unset[bool]	Handle or not circular refs. If UNSET value from base view model will be used.	UNSET

Source code in cwtch/cwtch.py

@dataclass_transform(field_specifiers=(field,))
def view(
    base_cls,
    name: Unset[str] = UNSET,
    *,
    attach: Unset[bool] = UNSET,
    include: Unset[Sequence[str]] = UNSET,
    exclude: Unset[Sequence[str]] = UNSET,
    slots: Unset[bool] = UNSET,
    kw_only: Unset[bool] = UNSET,
    env_prefix: Unset[str | Sequence[str]] = UNSET,
    env_source: Unset[Callable] = UNSET,
    validate: Unset[bool] = UNSET,
    add_disable_validation_to_init: Unset[bool] = UNSET,
    extra: Unset[Literal["ignore", "forbid"]] = UNSET,
    repr: Unset[bool] = UNSET,
    eq: Unset[bool] = UNSET,
    recursive: Unset[bool | Sequence[str]] = UNSET,
    handle_circular_refs: Unset[bool] = UNSET,
) -> Callable[[Type[T]], Type[T]]:
    """
    Args:
        name: View name.
        attach: If true, view will be attached to base cls.
        include: List of fields to include in view.
        exclude: List of fields to exclude from view.
        slots: If true, `__slots__` attribute will be generated
            and new class will be returned instead of the original one.
            If `__slots__` is already defined in the class, then TypeError is raised.
            If UNSET value from base view model will be used.
        kw_only: If kw_only is true, then by default all fields are keyword-only.
        env_prefix: Prefix(or list of prefixes) for environment variables.
            If UNSET value from base view model will be used.
        env_source: Environment variables source factory.
            If UNSET value from base view model will be used.
        validate: Validate or not fields.
            If UNSET value from base view model will be used.
        add_disable_validation_to_init: Add disable_validation keywoard argument to `__init__()` method
            to disable validation.
            If UNSET value from base view model will be used.
        extra: Ignore or forbid extra arguments passed to init.
            If UNSET value from base view model will be used.
        repr: If true, a `__rich_repr__()` method will be generated and rich.repr.auto decorator applied to the class.
            If UNSET value from base view model will be used.
        eq: If true, an `__eq__()` method will be generated.
            This method compares the class as if it were a tuple of its fields, in order.
            Both instances in the comparison must be of the identical type.
            If UNSET value from base view model will be used.
        recursive: ...
        handle_circular_refs: Handle or not circular refs.
            If UNSET value from base view model will be used.
    """

    if not (is_cwtch_model(base_cls) or is_cwtch_view(base_cls)):
        raise TypeError(f"{base_cls} is not a valid cwtch model or view")

    def wrapper(
        view_cls,
        *,
        base_cls=base_cls,
        name=name,
        attach=attach,
        include=include,
        exclude=exclude,
        slots=slots,
        kw_only=kw_only,
        env_prefix=env_prefix,
        env_source=env_source,
        validate=validate,
        add_disable_validation_to_init=add_disable_validation_to_init,
        extra=extra,
        repr=repr,
        eq=eq,
        recursive=recursive,
        handle_circular_refs=handle_circular_refs,
    ):
        if exclude and set(exclude) & view_cls.__annotations__.keys():  # type: ignore
            raise ValueError(f"unable to exclude fields {list(set(exclude) & view_cls.__annotations__.keys())}")  # type: ignore

        return _build_view(
            base_cls,
            view_cls,
            name,
            attach,
            include,
            exclude,
            slots,
            kw_only,
            cast(
                Unset[Sequence[str]],
                env_prefix if env_prefix is UNSET or isinstance(env_prefix, (list, tuple, str)) else [env_prefix],
            ),
            env_source,
            validate,
            add_disable_validation_to_init,
            extra,
            repr,
            eq,
            recursive,
            handle_circular_refs,
        )

    return wrapper

from_attributes(cls, obj: Any, data: dict | None = None, exclude: Sequence | None = None, suffix: str | None = None, reset_circular_refs: bool | None = None)

Build model from attributes of other object.

Parameters:

Name	Type	Description	Default
obj	Any	Object from which to build.	required
data	dict | None	Additional data to build.	None
exclude	Sequence | None	List of fields to exclude.	None
suffix	str | None	Fields suffix.	None
reset_circular_refs	bool | None	Reset circular references to None.	None

Source code in cwtch/cwtch.py

def from_attributes(
    cls,
    obj: Any,
    data: dict | None = None,
    exclude: Sequence | None = None,
    suffix: str | None = None,
    reset_circular_refs: bool | None = None,
):
    """
    Build model from attributes of other object.

    Args:
      obj: Object from which to build.
      data: Additional data to build.
      exclude: List of fields to exclude.
      suffix: Fields suffix.
      reset_circular_refs: Reset circular references to None.
    """

    kwds = {
        f.name: getattr(obj, f"{f_name}{suffix}" if suffix else f_name)
        for f_name, f in cls.__dataclass_fields__.items()
        if (not exclude or f_name not in exclude) and hasattr(obj, f"{f.name}{suffix}" if suffix else f_name)
    }
    if data:
        kwds.update(data)
    if exclude:
        kwds = {k: v for k, v in kwds.items() if k not in exclude}

    cache = _CACHE.get()
    cache["reset_circular_refs"] = reset_circular_refs
    try:
        return cls(__cwtch_cache_key=(cls, id(obj)), **kwds)
    finally:
        del cache["reset_circular_refs"]

asdict(inst, include: Sequence[str] | None = None, exclude: Sequence[str] | None = None, exclude_none: bool | None = None, exclude_unset: bool | None = None, context: dict | None = None) -> dict

Return cwtch model as dict.

Parameters:

Name	Type	Description	Default
inst		cwtch model.	required
include	Sequence[str] | None	List of field names to include.	None
exclude	Sequence[str] | None	List of field names to exclude.	None
exclude_none	bool | None	If true, fields with None value will be excluded.	None
exclude_unset	bool | None	If true, unset fields will be excluded.	None
context	dict | None	If specified, must be a mapping.	None

Source code in cwtch/cwtch.py

def asdict(
    inst,
    include: Sequence[str] | None = None,
    exclude: Sequence[str] | None = None,
    exclude_none: bool | None = None,
    exclude_unset: bool | None = None,
    context: dict | None = None,
) -> dict:
    """
    Return cwtch model as dict.

    Args:
        inst: cwtch model.
        include: List of field names to include.
        exclude: List of field names to exclude.
        exclude_none: If true, fields with None value will be excluded.
        exclude_unset: If true, unset fields will be excluded.
        context: If specified, must be a mapping.
    """

    return _asdict(
        inst,
        include_=include,
        exclude_=exclude,
        exclude_none=exclude_none,
        exclude_unset=exclude_unset,
        context=context,
    )

dumps_json(inst, encoder: Callable[[Any], Any] | None = None, context: dict | None = None)

Dump cwtch model to json.

Parameters:

Name	Type	Description	Default
encoder	Callable[[Any], Any] | None	Custom JSON encoder as callable.	None
context	dict | None	If specified, must be a mapping.	None

Source code in cwtch/cwtch.py

def dumps_json(inst, encoder: Callable[[Any], Any] | None = None, context: dict | None = None):
    """
    Dump cwtch model to json.

    Args:
        encoder: Custom JSON encoder as callable.
        context: If specified, must be a mapping.
    """

    return _dumps_json(inst, encoder, context)

validate_args(fn: Callable, args: tuple, kwds: dict) -> tuple[tuple, dict]

Helper to convert and validate function arguments.

Parameters:

Name	Type	Description	Default
args	tuple	function positional arguments.	required
kwds	dict	function keyword arguments.	required

Source code in cwtch/cwtch.py

def validate_args(fn: Callable, args: tuple, kwds: dict) -> tuple[tuple, dict]:
    """
    Helper to convert and validate function arguments.

    Args:
      args: function positional arguments.
      kwds: function keyword arguments.
    """

    annotations = {k: v.annotation for k, v in signature(fn).parameters.items()}

    validated_args = []
    for v, (arg_name, T) in zip(args, annotations.items()):
        if T != _empty:
            try:
                validated_args.append(validate_value(v, T))
            except ValidationError as e:
                raise TypeError(f"{fn.__name__}() expects {T} for argument {arg_name}") from e
        else:
            validated_args.append(v)

    validated_kwds = {}
    for arg_name, v in kwds.items():
        T = annotations[arg_name]
        if T != _empty:
            try:
                validated_kwds[arg_name] = validate_value(v, T)
            except ValidationError as e:
                raise TypeError(f"{fn.__name__}() expects {T} for argument {arg_name}") from e
        else:
            validated_kwds[arg_name] = v

    return tuple(validated_args), validated_kwds

validate_call(fn)

Decorator to convert and validate function arguments.

Source code in cwtch/cwtch.py

def validate_call(fn):
    """Decorator to convert and validate function arguments."""

    def wrapper(*args, **kwds):
        validate_args(fn, args, kwds)
        return fn(*args, **kwds)

    return wrapper