Document C inline properties.

2 files changed, 32 insertions, 0 deletions

diff --git a/docs/examples/userguide/extension_types/c_property.pyx b/docs/examples/userguide/extension_types/c_property.pyx
new file mode 100644
index 000000000..a545398fe
--- /dev/null
+++ b/docs/examples/userguide/extension_types/c_property.pyx
@@ -0,0 +1,20 @@
+cdef extern from "complexobject.h":
+
+    struct Py_complex:
+        double real
+        double imag
+
+    ctypedef class __builtin__.complex [object PyComplexObject]:
+        cdef Py_complex cval
+
+        @property
+        cdef inline double real(self):
+            return self.cval.real
+
+        @property
+        cdef inline double imag(self):
+            return self.cval.imag
+
+
+def cprint(complex c):
+    print(f"{c.real}+{c.imag}j")  # uses C calls to the above property methods.
diff --git a/docs/src/userguide/extension_types.rst b/docs/src/userguide/extension_types.rst
index 5d1470f94..7b254a1d6 100644
--- a/docs/src/userguide/extension_types.rst
+++ b/docs/src/userguide/extension_types.rst
@@ -959,6 +959,18 @@ code. No changes to Python need be made to achieve significant speedups, even
 though the field names in Python and C are different. Of course, one should
 make sure the fields are equivalent.
 
+C inline properties
+-------------------
+
+Similar to Python property attributes, Cython provides a way to declare C-level
+properties on external extension types.  This is often used to shadow Python
+attributes through faster C level data access, but can also be used to add certain
+functionality to existing types when using them from Cython.
+
+For example, the above ``complex`` type could also be declared like this:
+
+.. literalinclude:: ../../examples/userguide/extension_types/c_property.pyx
+
 Implicit importing
 ------------------