wanting 0.5.0

A library for creating, and working with models that may have incomplete information.

Wanting is a library for creating, and working with models that may have incomplete information.

Motivation

Instances of domain models don’t always spring into existence fully formed. They may be partially constructed intially, then filled in over time. Making a model field optional that is not intially available, but eventually required is inaccurate because an optional field may always be optional, so it never has to be filled in. It would be better to make the field a required union of the type it wants, and a placholder type. The wanting types are such placeholders. They can include metadata, such as the source of the update with missing data, and even partial data from that source.

Usage

A domain model may look like this:

from typing import Literal

import wanting
import pydantic

class User(pydantic.BaseModel):
    name: str
    employee_id: str | wanting.Unavailable
    department_code: Literal["TECH", "FO", "BO", "HR"] | wanting.Unmapped

Then there is an onboarding system that creates a User. However, the employee_id is unavailable at this time because it will be generated later. The onboarding system sources the department code from some other system, which uses different values than those in the User model. The onboarding system knows how to map some of the codes from the other system to the User department codes, but not all of them. However, because employee_id, and department_code may also be wanting fields in the User model, the onboarding system can still create a fully valid model, while also indicating that some information is missing:

user = User(
    name="Charlotte",
    employee_id=wanting.Unavailable(source="onboarding"),
    department_code=wanting.Unmapped(source="onboarding", value="art"),
)

The model validates, and all the wanting fields serialize to valid JSON:

assert user.model_dump() == {
    "name": "Charlotte",
    "employee_id": {
        "kind": "unavailable",
        "source": "onboarding",
        "value": b"null",
    },
    "department_code": {
        "kind": "unmapped",
        "source": "onboarding",
        "value": b'"art"',
    },
}

This user can now be persisted, then queried, and updated later by other systems.