bagof-magic

Classes that build themselves from your type hints.

Fields are written as annotations, and Magic generates __init__, __repr__, __eq__ and the other methods from them.

from bagof.magic import Magic

class Point(Magic, frozen=True):
    x: float
    y: float

>>> Point(1.0, 2.0)
Point(x=1.0, y=2.0)
>>> Point(1.0, 2.0) == Point(1.0, 2.0)
True
>>> Point(1.0, 2.0).x = 3.0
Traceback (most recent call last):
AttributeError: Cannot set frozen field 'x'

The same class can also be written with the magic decorator:

=== "Base class"

```python
from bagof.magic import Magic

class Point(Magic, frozen=True):
    x: float
    y: float
```

=== "Decorator"

```python
from bagof.magic import magic

@magic(frozen=True)
class Point:
    x: float
    y: float
```

What sets it apart

• Settings are class keyword arguments, and subclasses inherit them. A base class sets frozen=True once, every subclass keeps it, and a subclass overrides only the settings it needs to change. See Settings.
• Per-field behaviour lives in the annotation, not in a field() call: tags: Factory[list], token: NoRepr[str] = "". See Field annotations.
• Conversion and validation come from the type hint, and are turned on per class or per field. Config("localhost", "9000") stores port=9000 because the hint says int. See Conversion and validation.
• A class can build one of its own subclasses, chosen from the arguments it is called with. See Building the right subclass.
• A field can accept several input names, and can be read through forwarding properties under other names. See Input aliases and forwarding properties.
• A required field can follow one with a default, so a subclass can add a required field to a base whose fields all have defaults. See Field annotations.
• A subclass can forget a field it inherits by writing x: Forget, which frees the name for a field of its own. See Field annotations.
• A subclass can change part of an inherited field and keep the rest: x: ... = Inherit(frozen=True) freezes the inherited x without losing its default or its aliases, and _x: ... = Inherit("x") stores the inherited x under a private name while it is still read and passed as x. See Field annotations.
• The Extras page covers the rest: dict-like instances, replace, asdict and astuple, mutable defaults that are not shared, hooks around construction, generic classes, and docstrings generated from the fields.

How it compares

magic is close to attrs in spirit. Like pydantic, it does real work with the type hints, and like pydantic it uses inheritance where dataclasses and attrs use decorators.

The comparison page sets the four side by side in more detail.

Settings

class Thing(Magic, frozen=True, kw_only=True, slots=True):
    ...

Most of the settings that generate a method also accept a string in place of True. The generated method is then bound under that name, so that a hand-written method can call it.

The Settings page explains how settings are inherited and how a subclass overrides them.

Install

pip install git+https://github.com/bagofseeds/bagof-magic.git

Python 3.8 and later.

Status

The package is at an early stage. The API is still settling, and parts of it may change. Issues and ideas are welcome at bagofseeds/bagof-magic.