Merge pull request #2624 from mike-perdide/patch-1

Adding a warning discouraging use of __acl__ properties attributes

1 files changed, 7 insertions, 0 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 7cbea113c..842aad23f 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -290,6 +290,13 @@ properties of the instance.
        def __init__(self, owner):
            self.owner = owner
 
+.. warning::
+
+   Writing ``__acl__`` as properties is discouraged, as AttributeErrors
+   occuring in ``fget`` or ``fset`` will be silently dismissed (this is consistent
+   with Python ``getattr`` and ``hasattr`` behaviors). For dynamic ACLs, simply use
+   callables, as documented above.
+
 .. index::
    single: ACE
    single: access control entry