orm-loader

Tests

A lightweight foundation for building and validating SQLAlchemy-based data models.

orm-loader sits below any particular schema or CDM. It gives you a small set of reusable pieces for defining tables, loading files through staging tables, and checking models against external specifications. It stays out of domain logic on purpose.

The library focuses on:

  • ORM table mixins and introspection
  • staged file loading
  • loader and validation infrastructure
  • operational helpers that work across supported backends

At the moment, the built-in backends are SQLite and PostgreSQL.

What this library provides

The package is deliberately small. Most downstream projects only need a couple of these pieces.

  1. A minimal ORM table base

ORMTableBase provides structural utilities for mapped tables without pulling domain rules into the base layer.

It supports:

  • mapper access and inspection
  • primary key discovery
  • required (non-nullable) column detection
  • consistent primary key handling across models
  • simple ID allocation helpers for sequence-less databases
from orm_loader.tables import ORMTableBase

class MyTable(ORMTableBase, Base):
    __tablename__ = "my_table"

You can inherit from it directly or pick it up through one of the higher-level mixins.

  1. CSV-based ingestion mixins

CSVLoadableTableInterface adds staged file loading to ORM tables. It can use pandas or PyArrow loaders, and on PostgreSQL it can use a fast COPY path when the input is clean enough.

Features include:

  • staging table creation and cleanup
  • chunked loading for large files
  • optional casting and deduplication before insert
  • backend-specific merge behaviour
  • PostgreSQL fast-path loading with ORM fallback
  • backend-aware index handling during merge
class MyTable(CSVLoadableTableInterface, ORMTableBase, Base):
    __tablename__ = "my_table"

The main extension points here are loader choice, column mapping, and the normal SQLAlchemy model definitions themselves. Most downstream projects do not need to override much beyond csv_columns() and the model schema.

  1. Structured serialisation and hashing

SerialisableTableInterface adds lightweight serialisation helpers for ORM rows.

It supports:

  • conversion to dictionaries
  • JSON serialisation
  • stable row-level fingerprints
  • iterator-style access to field/value pairs
row = session.get(MyTable, 1)
row.to_dict()
row.to_json()
row.fingerprint()

This is useful for:

  • debugging
  • auditing
  • reproducibility checks
  • downstream APIs or exports
  1. Model registry and validation scaffolding

The library includes validation infrastructure for comparing ORM models against external specifications.

This includes:

  • a model registry
  • table and field descriptors
  • validator contracts
  • a validation runner
  • structured validation reports Specifications can be loaded from CSV today, with support for other formats (e.g. LinkML) planned.
registry = ModelRegistry(model_version="1.0")
registry.load_table_specs(table_csv, field_csv)
registry.register_models([MyTable])

runner = ValidationRunner(validators=always_on_validators())
report = runner.run(registry)

Validation output is available as:

  • human-readable text
  • structured dictionaries
  • JSON (for CI/CD integration)
  • exit codes suitable for pipelines
  1. Database bootstrap helpers

The library provides lightweight helpers for schema creation and bootstrapping. It does not try to replace migrations.

from orm_loader.metadata import Base
from orm_loader.bootstrap import bootstrap

bootstrap(engine, create=True)
  1. Bulk-loading helpers

There are a few lower-level helpers for trusted bulk workflows, including backend-aware foreign key management and SQLite connection setup for heavy local loads.

Summary

This library is meant to be the boring layer underneath downstream models:

  • reusable ORM mixins
  • staged ingestion patterns
  • validation scaffolding
  • operational helpers

Domain rules, business logic, and schema semantics stay in the downstream project.

This makes it suitable as a shared foundation for:

  • clinical data models
  • research data marts
  • registry schemas
  • synthetic data pipelines

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.1.0)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for gkennos from gravatar.com gkennos Avatar for nicoloesch from gravatar.com nicoloesch

Credits

Author: gkennos

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache-2.0)

Requires

Python >=3.12

Provides Extra

dev postgres

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

orm_loader-1.0.1.tar.gz (140.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

orm_loader-1.0.1-py3-none-any.whl (61.0 kB view details)

Uploaded Python 3

File details

Details for the file orm_loader-1.0.1.tar.gz.

File metadata

  • Download URL: orm_loader-1.0.1.tar.gz
  • Upload date:
  • Size: 140.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for orm_loader-1.0.1.tar.gz
Algorithm Hash digest
SHA256 8ab3c3aa65cf07b02fb23505c04e5898ab339ceb155e8a697b8b0fab089a18b8
MD5 20d5bdfacafe3cefc426e2562c9ab0ae
BLAKE2b-256 f44cfe51c02e90710fc63b2a6cd9f563f48c0cc8bf2aad6bfb66e806e3c13fcf

See more details on using hashes here.

Provenance

The following attestation bundles were made for orm_loader-1.0.1.tar.gz:

Publisher: publish.yml on AustralianCancerDataNetwork/orm-loader

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file orm_loader-1.0.1-py3-none-any.whl.

File metadata

  • Download URL: orm_loader-1.0.1-py3-none-any.whl
  • Upload date:
  • Size: 61.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for orm_loader-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ebe7eb4644749086eeabb0cf6d5c8961622369bf72181dc2a0a4458136e75507
MD5 436fb6b86b2c36a7d83afe7e8f2b80d6
BLAKE2b-256 e8ccab60acffb180da5736c087586d93c71596929428815d5d8ef39567c06593

See more details on using hashes here.

Provenance

The following attestation bundles were made for orm_loader-1.0.1-py3-none-any.whl:

Publisher: publish.yml on AustralianCancerDataNetwork/orm-loader

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.1.0

2 files

This release

1.0.1 This release

2 files

1.0.0

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.27

2 files

0.3.26

2 files

0.3.25

2 files

0.3.24

2 files

0.3.23

2 files

0.3.22

2 files

0.3.21

2 files

0.3.20

2 files

0.3.19

2 files

0.3.18

2 files

0.3.17

2 files

0.3.16

2 files

0.3.15

2 files

0.3.14

2 files

0.3.13

2 files

0.3.12

2 files

0.3.11

2 files

0.3.10

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

Yanked

0.3.0

2 files

Yanked reason: typo

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.3

2 files

0.1.2

2 files

0.1.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page