change polymorphic__proxy --> polymorphic_proxy and make it auto toggle on proxy

Author: bckohan

docs/changelog.rst

@@ -4,6 +4,7 @@ Changelog
 v4.3.0 (202X-XX-XX)
 -------------------
 
+* Implemented `Add polymorphic_proxy flag to enable polymorphic queries from proxy models. <https://github.com/jazzband/django-polymorphic/pull/676>`_
 * Fixed `Resolve primary key name correctly. <https://github.com/jazzband/django-polymorphic/pull/620>`_
 * Implemented `Include get_child_inlines() hook in stacked inline admin forms. <https://github.com/jazzband/django-polymorphic/pull/681>`_
 * Fixed `multi-database support in inheritance accessors. <https://github.com/jazzband/django-polymorphic/pull/550>`_

docs/index.rst

@@ -119,6 +119,7 @@ Advanced topics
    formsets
    migrating
    managers
+   proxy
    advanced
    changelog
    api/index

docs/proxy.rst

@@ -0,0 +1,66 @@
+Proxy Models
+============
+
+:pypi:`django-polymorphic` has supported :ref:`proxy models <django:proxy-models>` since they were
+introduced in Django but the default implementation is unintuitive. If a row is created from the
+proxy model the :class:`~django.contrib.contenttypes.models.ContentType` of the proxy class is
+recorded. This allows patterns that need to alter behavior based on which class was used to create
+the row.
+
+**By default the queryset on proxy models will filter on instance_of(ProxyModel) which will exclude
+any rows that were not created from the proxy.**
+
+.. code-block:: python
+
+    from polymorphic.models import PolymorphicModel
+
+    class MyModel(PolymorphicModel):
+        ...
+
+    class MyProxy(MyModel):
+        class Meta:
+            proxy = True
+
+    
+    MyModel.objects.create()
+    MyProxy.objects.create()
+
+    assert MyModel.objects.count() == 2
+    assert MyProxy.objects.count() == 1
+
+This behavior may be unexpected for typical uses of proxy models which involves creating from the
+concrete class then accessing from a proxy in the context where you need the modified proxy
+interface. There is a
+`discussion <https://github.com/jazzband/django-polymorphic/discussions/689>`_ if this should
+continue to be the default behavior in version 5+.
+
+Polymorphic Proxy Queries
+-------------------------
+
+.. versionadded:: 4.3
+
+If you wish for your proxy model querysets to behave polymorphically by default
+(include all rows created by the proxy and concrete models in the class's inheritance tree) then
+instead of (or in additon to) :attr:`~django.db.models.Options.proxy` set a
+:attr:`Meta.polymorphic_proxy` attribute to True:
+
+.. code-block:: python
+
+    from polymorphic.models import PolymorphicModel
+
+    class MyModel(PolymorphicModel):
+        ...
+
+    class MyProxy(MyModel):
+        class Meta:
+            polymorphc_proxy = True
+
+
+    MyModel.objects.create()
+    MyProxy.objects.create()
+
+    assert MyModel.objects.count() == 2
+    assert MyProxy.objects.count() == 2
+
+    for proxy in MyProxy.objects.all():
+        assert isinstance(proxy, MyProxy)  # 

src/polymorphic/base.py

@@ -55,9 +55,11 @@ class PolymorphicModelBase(ModelBase):
     def __new__(self, model_name, bases, attrs, **kwargs):
         polymorphic__proxy = None
         if "Meta" in attrs:
-            if hasattr(attrs["Meta"], "polymorphic__proxy"):
-                polymorphic__proxy = attrs["Meta"].polymorphic__proxy
-                del attrs["Meta"].polymorphic__proxy
+            if hasattr(attrs["Meta"], "polymorphic_proxy"):
+                polymorphic__proxy = attrs["Meta"].polymorphic_proxy
+                if polymorphic__proxy:
+                    attrs["Meta"].proxy = True
+                del attrs["Meta"].polymorphic_proxy
 
         # Workaround compatibility issue with six.with_metaclass() and custom Django model metaclasses:
         if not attrs and model_name == "NewBase":
@@ -84,9 +86,9 @@ def __new__(self, model_name, bases, attrs, **kwargs):
         new_class.polymorphic_super_sub_accessors_replaced = False
 
         if polymorphic__proxy is not None:
-            new_class._meta.polymorphic__proxy = polymorphic__proxy
+            new_class._meta.polymorphic_proxy = polymorphic__proxy
         else:
-            new_class._meta.polymorphic__proxy = not new_class._meta.proxy
+            new_class._meta.polymorphic_proxy = not new_class._meta.proxy
 
         # determine the name of the primary key field and store it into the class variable
         # polymorphic_primary_key_name (it is needed by query.py)

src/polymorphic/managers.py

@@ -28,7 +28,7 @@ def from_queryset(cls, queryset_class, class_name=None):
 
     def get_queryset(self):
         qs = self.queryset_class(self.model, using=self._db, hints=self._hints)
-        if not self.model._meta.polymorphic__proxy:
+        if not self.model._meta.polymorphic_proxy:
             qs = qs.instance_of(self.model)
         return qs
 

src/polymorphic/tests/models.py

@@ -385,15 +385,14 @@ class NonProxyChild(ProxyBase):
 # base(poly) -> proxy(poly) -> proxy(Traditional Django)
 class TradProxyOnProxyChild(ProxyChild):
     class Meta:
-        proxy = True
-        polymorphic__proxy = True
+        polymorphic_proxy = True
 
 
 # base(poly) -> proxy(Traditional Django)
 class TradProxyChild(ProxyBase):
     class Meta:
         proxy = True
-        polymorphic__proxy = True
+        polymorphic_proxy = True
 
 
 # base(poly) -> proxy(Traditional Django) -> proxy(poly)
@@ -404,7 +403,7 @@ class Meta:
 class AliasOfNonProxyChild(NonProxyChild):
     class Meta:
         proxy = True
-        polymorphic__proxy = True
+        polymorphic_proxy = True
 
 
 # base(poly) -> proxy(Traditional Django) -> proxy(poly)
@@ -416,15 +415,14 @@ class Meta:
 # base(poly) -> proxy(poly)
 class AliasProxyChild(ProxyBase):
     class Meta:
-        proxy = True
-        polymorphic__proxy = True
+        polymorphic_proxy = True
 
 
 # child(poly) -> proxy(poly)
 class NonAliasNonProxyChild(NonProxyChild):
     class Meta:
         proxy = True
-        polymorphic__proxy = False
+        polymorphic_proxy = False
 
 
 class ProxiedBase(ShowFieldTypeAndContent, PolymorphicModel):

src/polymorphic/tests/test_orm.py

@@ -927,7 +927,7 @@ def test_convert_back_to_django_style_from_polymorphic_stops_at_concrete(self):
         self.assertEqual(2, AliasOfNonProxyChild.objects.count())
 
     def test_revert_back_to_polymorphic_proxy(self):
-        self.assertFalse(ProxyChildAliasProxy._meta.polymorphic__proxy)
+        self.assertFalse(ProxyChildAliasProxy._meta.polymorphic_proxy)
 
     def test_proxy_get_real_instance_class(self):
         """