# Spellframes and categories

<sub>**Beginner.** The organizing half of every address.</sub>

A `spellframe` is the **category** half of the Address Law. It is a plain
string when you just want grouping, or a `Protocol` when you want a *contract*.
Nothing else is a spellframe: a concrete class is refused at `bind()` with a
`TypeError` that names the two forms (pass `spellframe="Name"` to group under
its name, or declare the shape as a `typing.Protocol`).

```python
# strings — organize by role
book.bind(spell=UsersRepo, existence="unique",
          spellframe="storage", binding_name="users")
book.bind(spell=UsersApi,  existence="unique",
          spellframe="web",     binding_name="users")

repo = conduit.meld(spellframe="storage", binding_name="users")
api  = conduit.meld(spellframe="web",     binding_name="users")
```

This is an **excerpt**: define `UsersRepo` and `UsersApi`, bind them before
conjure, then resolve each full address. The result is a repository and an API
object in separate categories, even though both bindings are named `users`.

Same `binding_name`, two categories, **two distinct addresses** — names never
collide across spellframes. A string frame is only a label: it groups, it is
addressable, and it never makes its members providers of anything. A `Protocol`
frame is a label **and a contract**: `bind()` checks the spell against the
Protocol's own public members, records the Protocol on the binding, and a
parameter annotated with that Protocol resolves exactly its recorded
implementers — which is what collection DI gathers:

```python
book.bind(spell=EmailHandler, existence="unique",
          spellframe=Handler, binding_name="email")
```

## Runnable examples

- [Spellframe grouping](../examples/beginner/09-spellframe-grouping.md) — Beginner 09
- [Protocols as shapes](../examples/beginner/17-protocols-as-shapes.md) — Beginner 17
- [Frames as dict classification](../examples/beginner/25-frames-as-dict-classification.md) — Beginner 25
- [Meld a frame as dict](../examples/beginner/38-meld-a-frame-as-dict.md) — Beginner 38

[All beginner examples](../examples/beginner/index.md) · [Level contents](index.md) · [Full contents](../contents.md)

[Canonical page source](https://github.com/Synaptic724/melder/blob/0895ce795453cd87e35d70665957b4e89aad3317/README.md)