attrs integration example in docs fails with forward reference error

[krave1986]

The attrs integration example in the documentation fails to run due to a forward reference issue. Using List["Address"] in the User class still results in a NameError.

You can find the code here. Just copy, paste and run the code. The error will jump out.

Error message:

Exception has occurred: NameError
Could not de-stringify annotation 'Address'
File "", line 1, in
NameError: name 'Address' is not defined

Environment

SQLAlchemy 2.0.39
attrs 25.3.0

[zzzeek]

hmm yup

so that example was made for the 1.4 version of SQLAlchemy and it's been broken for the entirety of the 2.0 series when we started parsing Mapped[] annotations. Nobody has noticed for about 18 months. That is a datapoint for how popular this use case might be (i.e. nobody is using this).

There's no workaround for this that I can think of right now, unless we established some new flag that entirely turns off declarative's parsing of annotations.

So unfortunately I'm going to just remove this example from the docs right now, since this is not really usable. We continue to have full support for mapping to existing dataclasses. But because we have no continuous testing for attrs integration, this feature simply broke and nobody noticed, therefore it's not appropriate to be documented since we are clearly not supporting it.

[zzzeek]

cc @CaselIT

[zzzeek]

OK attrs still works with imperative mappings. so there's a path

[zzzeek]

I will update the docs to remove "attrs with declarative" since this has not worked for all of 2.0. imperative mappings can still be used.

[krave1986]

Thanks for the quick response and clarification, Michael! I appreciate you taking the time to explain the situation.

[CaselIT]

it seems that attrs support dataclasses, so maybe we can just document that?

[zzzeek]

maybe, but I think we can't be responsible for the whole python object model world at the same time