Skip to main content
Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Consider using release 6.1.1 instead.
Reason given by maintainers: pydal 20261107 is too unstable

TypeDAL

PyPI - Version PyPI - Python Version
Ruff License: MIT
checks

Typing support for PyDAL. This package aims to improve the typing support for PyDAL. By using classes instead of the define_table method, type hinting the result of queries can improve the experience while developing. In the background, the queries are still generated and executed by pydal itself, this package only provides some logic to properly pass calls from class methods to the underlying db.define_table pydal Tables.

  • TypeDAL is the replacement class for DAL that manages the code on top of DAL.
  • TypedTable must be the parent class of any custom Tables you define (e.g. class SomeTable(TypedTable))
  • TypedField can be used instead of Python native types when extra settings (such as default) are required ( e.g. name = TypedField(str, default="John Doe")). It can also be used in an annotation (name: TypedField[str]) to improve editor support over only annotating with str.
  • TypedRows: can be used as the return type annotation of pydal's .select() and subscribed with the actual table class, so e.g. rows: TypedRows[SomeTable] = db(...).select(). When using the QueryBuilder, a TypedRows instance is returned by .collect().

Version 2.0 also introduces more ORM-like functionality. Most notably, a Typed Query Builder that sees your table classes as models with relationships to each other. See 3. Building Queries for more details.

Quickstart

uv pip install typedal
# alternative:
pip install typedal
from typedal import TypeDAL, TypedTable

db = TypeDAL("sqlite:memory")
# Alternatives:
# db = TypeDAL("sqlite://storage.sqlite")
# db = TypeDAL("postgres://user:password@localhost:5432/mydb")
# db = TypeDAL("mysql://user:password@localhost:3306/mydb")
# ...


@db.define()
class User(TypedTable):
    name: str
    age: int | None


User.insert(name="Alice", age=30)
adults = User.where(User.age >= 18).collect()
print(adults.column("name"))  # ['Alice']

If you are new to TypeDAL, start with:

  1. Getting Started
  2. Defining Tables
  3. Building Queries
  4. Relationships

CLI

The TypeDAL CLI provides a convenient interface for generating SQL migrations for edwh-migrate from PyDAL or TypeDAL configurations using pydal2sql. It offers various commands to streamline database management tasks.

Usage

typedal --help

Options

  • --show-config: Toggle to show configuration details. Default is no-show-config.
  • --version: Toggle to display version information. Default is no-version.
  • --install-completion: Install completion for the current shell.
  • --show-completion: Show completion for the current shell, for copying or customization.
  • --help: Display help message and exit.

Commands

  • cache.clear: Clear expired items from the cache.
  • cache.stats: Show caching statistics.
  • migrations.fake: Mark one or more migrations as completed in the database without executing the SQL code.
  • migrations.generate: Run pydal2sql based on the TypeDAL configuration.
  • migrations.run: Run edwh-migrate based on the TypeDAL configuration.
  • typescript.generate: Generate TypeScript interfaces from TypeDAL models.
  • setup: Interactively setup a [tool.typedal] entry in the local pyproject.toml.

Configuration

TypeDAL and its CLI can be configured via pyproject.toml.
See 6. Migrations for more information about configuration.

TypeDAL for PyDAL users - Quick Overview

Below you'll find a quick overview of translation from pydal to TypeDAL.
For more info, see the docs.


Translations from pydal to typedal

Description pydal typedal typedal alternative(s) ...
Setup
from pydal import DAL, Field

db = DAL(...)
from typedal import TypeDAL, TypedTable, TypedField

db = TypeDAL(...)
Table Definitions
db.define_table(
    "table_name",
    Field("fieldname", "string", required=True),
    Field("otherfield", "float"),
    Field("yet_another", "text", default="Something"),
)
@db.define
class TableName(TypedTable):
    fieldname: str
    otherfield: float | None
    yet_another = TypedField(str, type="text", default="something", required=False)
import typing


class TableName(TypedTable):
    fieldname: TypedField[str]
    otherfield: TypedField[typing.Optional[float]]
    yet_another = TextField(default="something", required=False)


db.define(TableName)
Insert
db.table_name.insert(fieldname="value")
TableName.insert(fieldname="value")
# the old syntax is also still supported:
db.table_name.insert(fieldname="value")
(quick) Select
# all:
all_rows = db(db.table_name).select()  # -> Any (Rows)
# some:
rows = db((db.table_name.id > 5) & (db.table_name.id < 50)).select(db.table_name.id)
# one:
row = db.table_name(id=1)  # -> Any (Row)
# all:
all_rows = TableName.collect()  # or .all()
# some:
# order of select and where is interchangeable here
rows = TableName.select(Tablename.id).where(TableName.id > 5).where(TableName.id < 50).collect()
# one:
row = TableName(id=1)  # or .where(...).first()
# you can also still use the old syntax and type hint on top of it;
# all:
all_rows: TypedRows[TableName] = db(db.table_name).select()
# some:
rows: TypedRows[TableName] = db((db.table_name.id > 5) & (db.table_name.id < 50)).select(db.table_name.id)
# one:
row: TableName = db.table_name(id=1)

All Types

See 2. Defining Tables

Helpers

TypeDAL provides some utility functions to interact with the underlying pyDAL objects:

  • get_db(TableName):
    Retrieve the DAL instance associated with a given TypedTable or pyDAL Table.

  • get_table(TableName):
    Access the original PyDAL Table from a TypedTable instance (db.table_name).

  • get_field(TableName.fieldname):
    Get the pyDAL Field from a TypedField. This ensures compatibility when interacting directly with PyDAL.

These helpers are useful for scenarios where direct access to the PyDAL objects is needed while still using TypeDAL. An example of this is when you need to do a db.commit() but you can't import db directly:

from typedal.helpers import get_db  # , get_table, get_field

MyTable.insert(...)
db = get_db(MyTable)
db.commit()  # this is usually done automatically but sometimes you want to manually commit.

Caveats

  • Some editors (notably PyCharm) cannot always distinguish class-level and instance-level access on the same symbol. For example, Model.somefield is a field descriptor (query operations like .belongs()), while model.somefield is the runtime value (for example list[str]).
  • TypedField limitations; Since pydal implements some magic methods to perform queries, some features of typing will not work on a typed field: typing.Optional or a union (Field() | None) will result in errors. The only way to make a typedfield optional right now, would be to set required=False as an argument yourself. This is also a reason why typing.get_type_hints is not a complete solution.

Metadata

Release files for TypeDAL 6.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for TypeDAL 6.1.0
File Size Uploaded Provenance Actions
typedal-6.1.0.tar.gz 114.3 kB Without provenance Details for typedal-6.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for TypeDAL 6.1.0
File Interpreter ABI Platform Actions
typedal-6.1.0-py3-none-any.whl Python 3 none any Details for typedal-6.1.0-py3-none-any.whl

Total release size: 241.1 kB

Release files / typedal-6.1.0.tar.gz

Download URL typedal-6.1.0.tar.gz
Size 114.3 kB
Tags Source
SHA-256 checksum
How to use checksums
22b660324fec4844b7776f6824943e5509ff6189338bab21ab6b6614597a1e85
BLAKE2b-256 checksum
How to use checksums
88c06e95d7f2a516ab251139c4db5f5101fe271b64136d8b6241401e78774854
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / typedal-6.1.0-py3-none-any.whl

Download URL typedal-6.1.0-py3-none-any.whl
Size 126.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79a088bd6487e99b4a085a867f4aed84b430f1ee4c0b6fe606ef349d368a73ef
BLAKE2b-256 checksum
How to use checksums
9b01daa5b01e30f497b50cbe4b8054a6d1dab56c1a80b8ca2e2494d00811e4a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.26 {"installer":{"name":"uv","version":"0.11.26","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for TypeDAL 6.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

6.1.0 This release

2 release files No provenance

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