Support docstrings on hybrid attributes

[David Baumgold]

Currently, it appears that there is no way to set a docstring on a hybrid attribute: even if there is a docstring on the function, the @hybrid_property and @hybrid_method decorators don't copy it over to the objects they return. There should be way to set docstrings on hybrid attributes.

My ultimate goal is to get Sphinx's autodoc extension working properly with hybrid attributes, so that I can write RST-formatted docstrings for the hybrid attributes of my data models, and generate beautiful documentation from those docstrings.

I started putting together a fix for this bug in a GitHub pull request, but the problem turned out to be more complicated than I expected.

[Mike Bayer]

OK there's a lot more going on in the PR than is stated here. The tests in the PR are specifically asking for this:

class MyClass(Base):
     @hybrid_property
     def foo(self):
         """instance level docstring"""
         return self.bar

    @foo.expression
    def foo(cls):
        """Class level docstring"""
        return cls.some_bar

and that above, there would somehow be a system that gets at one docstring or the other. I'm not sure how that would look. We can make the docstring that's on "expression" just take over for the attribute but for one Python attribute to have multple docstrings in different contexts is odd.

[Mike Bayer]

the pr at https://github.com/zzzeek/sqlalchemy/pull/239/commits revises 238 and seems to have all the expected cases working. but this highly modifies how a hybrid behaves now and we need to evaluate the impact.

[Mike Bayer]

Honor hybrid property / method docstrings

The docstring specified on a hybrid property or method is now honored at the class level, allowing it to work with tools like Sphinx autodoc. The mechanics here necessarily involve some wrapping of expressions to occur for hybrid properties, which may cause them to appear differently using introspection.

Fixes: #3653 Change-Id: I02549977fe8b2a051802eed7b00cc532fbc214e3 Pull-request: https://github.com/zzzeek/sqlalchemy/pull/239

→ <<cset 243b222a232d>>

[Mike Bayer]

Propagate hybrid properties / info

Keystone and others depend on the .property attribute being "mirrored" when a @hybrid_property is linked directly to a mapped attribute. Restore this linkage and also create a defined behavior for the .info dictionary; it is that of the hybrid itself. Add this behavioral change to the migration notes.

Change-Id: I8ac34ef52039387230c648866c5ca15d381f7fee References: #3653

→ <<cset 6f6e2c48ba0b>>