sqlalchemy / sqlalchemy/sqlalchemy

Type annotations are not preserved by `declared_attr`, `hybrid_property`, and potentially other decorators

Open
#5,999 7 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

awaiting info help wanted orm typing use case
Dominant language
Python
Stars
12.2k
Forks
1.8k
PR merge metrics
No merged PRs in 30d

Description

First of all, thanks a ton for SQLAlchemy -- it's been absolutely invaluable to my work.

Describe the bug

I'm using declared_attr and hybrid_property throughout one of my codebases. That codebase is automatically documented using Sphinx + sphinx-apidoc, which includes type annotations (via thing.__annotations__) when present.

This normally works just fine, but SQLAlchemy's various decorators don't preserve __annotations__. As such, various decorated APIs in my documentation lack type signatures.

Expected behavior

declared_attr and hybrid_property should preserve their underlying __annotations__ the way they currently do for __doc__.

To Reproduce

I don't have a simple test case yet, but I can try to produce one in a bit. In general, however:

  1. Take a SQLAlchemy codebase that uses hybrid_property or another decorator.
  2. Add type hints to the underlying (decorated) method
  3. Attempt to generate Sphinx docs for the containing module
  4. Check whether the generated docs include a type signature for the decorated method

Versions.

  • OS: Ubuntu 20.04
  • Python: CPython 3.8
  • SQLAlchemy: 1.3.12
  • Database: Postgres
  • DBAPI: psycopg2

I'm going to take a stab at fixing this, and will open a PR if my fixes work locally. Just figured I'd open an issue to track it as well 🙂

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the declared_attr and hybrid_property entry points, using an annotated underlying method and checking how the decorators currently expose doc. Verify the behavior through Sphinx and sphinx-apidoc; done means the decorated APIs retain their annotations and generated documentation includes their type signatures.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, sqlalchemy
Domain
database
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
56/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.