Skip to content

Commit 5f56d32

Browse files
Type hints overhaul (#352)
This PR provides numerous improvements and one bugfix regarding type hints. This is my follow-up to our discussion here @evertlammerts: #341 (comment) All changes are only in the type stubs, which means that there's no impact whatsoever on any runtime logic. ## Changes 1) New `_expression.pyi` file to separate the `Expression` class, and allow circular imports and references. Leans-up a bit the `__init__` file, which is nice. 2) Two new `Protocol` for numpy array and types. Allow to type check those without emitting errors if the user doesn't have the library installed. Array is useful for `Expression` conversions, Dtype for `DuckDBPyType` conversions. 3) Refactored and expanded the `_ExpressionLike` type alias. Renamed it to `IntoExpr`, and added various new type aliases covering as much situations as possible for `Expression` conversions. 4) Added a few Literals to cover the ids and `str` conversions to `DuckDBPyType`, providing a nice autocompletion for arguments, and a nice interaction with pattern matching when checking the id value. Also, provide `JSON` and `BIGNUM` convenient instanciation as an added bonus (ATM they are absent from sqltypes constants). 5) Added various new type aliases, to cover all paths for `DuckDBPyType` conversions: as python/numpy static type hints, as `dict` instances, or as `Literal | str`. This significantly improve the types hints regarding datatypes arguments, who were very often only accepting str or `DuckDBTypes` in the signatures. 6) Added various new `Literal` for files methods/functions argument options. 7) Centralized type aliases, Literals, and Protocols in a `_typing.pyi` file, to avoid bloating the `__init__`. 8) Added a new `CppEnum` class to reduce code duplication for enum-like classes, and centralized them in a new `_enum.pyi` file. 9) Fixed the `StatementType` class who had incorrect values (no `_STATEMENT` at the end of the member names) ## Notes - I tried to document this as best as I could with docstrings for users and "private" comments. I left a few observations, but what I would add is that one thing is clear, the runtime accepted types are all over the place (sometimes Mapping is ok, sometimes only dict is ok, etc...). As I said in #341 , prioritizing `collections.abc` as much as possible would be the best way to go in the future. - Centralizing the type aliases and using them as much as possible make sense IMO, especially with an API that have repeated signatures (connexion methods vs module level function for example). - The next step would be to move the type definition in a concrete **.py** file, allowing user to import those if they want to annotate custom functions or do runtime type introspection. Note that this can be done if you import them from `_duckdb` (not intuitive), but only in a `TYPE_CHECKING` block (will crash otherwise), and your LSP will most likely say that they can't resolve the import.
2 parents 03ac23b + 8a94680 commit 5f56d32

File tree

6 files changed

+564
-417
lines changed

6 files changed

+564
-417
lines changed

0 commit comments

Comments
 (0)