update from Atlas with major reorg

attic/descriptors/doc_descriptor.py

@@ -0,0 +1,60 @@
+
+"""
+
+>>> f = Foo()
+>>> f.bar = 77
+>>> f.bar
+77
+>>> Foo.bar.__doc__
+'The "bar" attribute'
+>>> import pydoc
+>>> pydoc.getdoc(Foo.bazz)
+'The "bazz" attribute'
+
+"""
+
+
+def doc_descriptor_wrapper_factory(descriptor):
+    wrapper_cls_name = 'DocDescriptorWrapper'
+    wrapper_cls_attrs = descriptor.__dict__.copy()
+    wrapper_cls_attrs['__slots__'] = ['_wrapped']
+
+    def wrapped_getter(self):
+        "the wrapped descriptor instance"
+        return self._wrapped
+
+    def wrapper_repr(self):
+        return '<{} {!r}>'.format(wrapper_cls_name, self.__doc__)
+
+    wrapper_cls_attrs['wrapped'] = property(wrapped_getter)
+    wrapper_cls_attrs['__repr__'] = wrapper_repr
+    wrapper_cls = type(wrapper_cls_name, (), wrapper_cls_attrs)
+    wrapper = wrapper_cls()
+    wrapper._wrapped = descriptor
+    return wrapper
+
+
+class DocDescriptor:
+    """A documented descriptor"""
+
+    def __init__(self, documentation):
+        self.__doc__ = documentation
+        cls_name = self.__class__.__name__
+        self.storage_name = '_{}_{:x}'.format(cls_name, id(self))
+
+    def __get__(self, instance, owner):
+        """The __get__ method"""
+        if instance is None:
+            return doc_descriptor_wrapper_factory(self)
+        else:
+            return getattr(instance, self.storage_name)
+
+    def __set__(self, instance, value):
+        setattr(instance, self.storage_name, value)
+
+
+class Foo:
+    """The "Foo" class"""
+
+    bar = DocDescriptor('The "bar" attribute')
+    bazz = DocDescriptor('The "bazz" attribute')