common_db.builder.inference
inference.py — per-source dtype -> SQLAlchemy type tables (pure functions).
The anti-pattern this replaces: ONE pandas dtype map guessing for every world (the old client’s int64->Numeric, unmapped->Text). Here every source family gets its own faithful table, and unmapped types REFUSE loudly (strict) or land as Text WITH a counted heal (never silent).
Type-name vocabulary (the builder’s string shorthand — what a human types): text · numeric · float · int · bigint · smallint · bool · date · time · timestamp · timestamptz · jsonb · bytea · uuid
Functions
columns_from_arrow
def columns_from_arrow(schema: Any) -> dict[str, Any]columns_from_pandas
def columns_from_pandas(df: Any) -> dict[str, Any]Pandas dtypes -> sa types. Object columns are resolved by ALL non-null values agreeing (the old first-value-sampling bug is the reason).
columns_from_polars
def columns_from_polars(df: Any) -> dict[str, Any]compatibility
def compatibility(incoming: Any, declared: Any) -> str‘exact’ | ‘coercible’ | ‘incompatible’ for one column pair.
type_from_kinds
def type_from_kinds(kinds: set[type]) -> AnyA SET of python value kinds -> the narrowest sa type that fits ALL of them — the widening lattice (int+float -> Numeric, anything+str -> Text). Sample rows and pandas object columns both vote through here, so neither can regress to first-value sampling (the legacy bug).
type_from_polars
def type_from_polars(dtype: Any) -> AnyOne polars dtype -> sa type (faithful, refuses unknowns).
type_from_python
def type_from_python(annotation: Any) -> tuple[Any, bool]A python/pydantic annotation -> (sa type, nullable). Optional unwraps; unknown annotations refuse loudly.
type_from_str
def type_from_str(name: str) -> Any‘numeric’ -> sa.Numeric() — the shorthand resolver (refuses unknowns).