From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 12 Sep 2018 15:44:57 +0000 (-0600)
Subject: Add explicit note about @hybrid_property mutators re: method name
X-Git-Tag: rel_1_3_0b1~82
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=92bccc796beaa47a537a2399fd67791045f810d2;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add explicit note about @hybrid_property mutators re: method name

Fixes: #4332
Change-Id: I7c52140d3a3055a71b192fea020c795a57356d90
---

diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst
index d70c6db52f..e2df229537 100644
--- a/doc/build/changelog/migration_12.rst
+++ b/doc/build/changelog/migration_12.rst
@@ -374,6 +374,33 @@ hybrid in-place, interfering with the definition on the superclass.
    :attr:`.hybrid_property.overrides` may be necessary to avoid name
    conflicts with :class:`.QueryableAttribute` in some cases.
 
+.. note:: This change in ``@hybrid_property`` implies that when adding setters and
+   other state to a ``@hybrid_property``, the **methods must retain the name
+   of the original hybrid**, else the new hybrid with the additional state will
+   be present on the class as the non-matching name.  This is the same behavior
+   as that of the ``@property`` construct that is part of standard Python::
+
+        class FirstNameOnly(Base):
+            @hybrid_property
+            def name(self):
+                return self.first_name
+
+            # WRONG - will raise AttributeError: can't set attribute when
+            # assigning to .name
+            @name.setter
+            def _set_name(self, value):
+                self.first_name = value
+
+        class FirstNameOnly(Base):
+            @hybrid_property
+            def name(self):
+                return self.first_name
+
+            # CORRECT - note regular Python @property works the same way
+            @name.setter
+            def name(self, value):
+                self.first_name = value
+
 :ticket:`3911`
 
 :ticket:`3912`