From 95bc52ebd8c8264bd78e29e0ff12099d044e22c9 Mon Sep 17 00:00:00 2001
From: Blallo <blallo@autistici.org>
Date: Fri, 27 Nov 2020 19:41:09 +0100
Subject: [PATCH] Add docs and clarify

---
 src/phi/async_ldap/mixins.py | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/src/phi/async_ldap/mixins.py b/src/phi/async_ldap/mixins.py
index ee4ab2d..458570b 100644
--- a/src/phi/async_ldap/mixins.py
+++ b/src/phi/async_ldap/mixins.py
@@ -124,6 +124,13 @@ class Entry(object):
 
 
 class OrganizationalUnit(object):
+    """
+    Mixin that represents an OrganizationalUnit. It provides the methods to interact
+    with the LDAP db _and_ to supervise its `Member`s.
+    To properly use it, one must specify the `ou` and `child_class` class attributes
+    when inheriting.
+    """
+
     object_class = ["organizationalUnit", "top"]
 
     def __init__(self, client, **kwargs):
@@ -190,7 +197,17 @@ class OrganizationalUnit(object):
             raise PhiCannotExecute("Cannot delete an OU and delete_cascade is not set")
 
 
-def hydrate(obj, data):
+def _hydrate(obj, data):
+    """
+    Iterate over the structure of the given `data`. Using the key name, filtering
+    only on the values that the given `obj` accepts (`obj.ldap_attributes`),
+    appropriately set the corresponding value in the given `obj`. In particular:
+      - append to lists
+      - handle password setting
+      - set scalars
+    This is called `_hydrate` because its aim is to fill a structure (the `obj`)
+    with substance.
+    """
     for k, v in data.items():
         if k in obj.ldap_attributes:
             if isinstance(v, list) and not isinstance(v, LDAPValueList):
@@ -204,13 +221,20 @@ def hydrate(obj, data):
 
 
 class Member(object):
+    """
+    Mixin that represents a generic member of an `OrganizationalUnit`.
+    It provides the methods to interact with the LDAP db.
+    To properly use, `ou`, `object_class` and `ldap_attributes` class attributes must
+    be specified when inheriting.
+    """
+
     def __init__(self, client, name, **kwargs):
         self.client = client
         self.base_dn = client.base_dn
         self.name = name
         self._entry = LDAPEntry(self.dn)
         if kwargs:
-            hydrate(self, kwargs)
+            _hydrate(self, kwargs)
 
     def __eq__(self, other):
         if isinstance(other, type(self)):
@@ -254,5 +278,5 @@ class Member(object):
 
     async def sync(self):
         res = await self._get()
-        hydrate(self, res)
+        _hydrate(self, res)
         return self