Merge pull request #10 from ocf/docstrings-and-subnet

More useful docstrings, add subnet constants

ocflib/constants.py

@@ -8,6 +8,10 @@
 
 OCF_KRB_REALM = 'OCF.BERKELEY.EDU'
 
+# TODO: provide ip_network objects from ipaddress after we're on Python 3.4
+OCF_SUBNET_V4 = '169.229.226.0/24'
+OCF_SUBNET_V6 = '2607:f140:8801::/64'
+
 OCF_MAIL_HOST = 'anthrax.ocf.berkeley.edu'
 OCF_MAIL_PORT = 25
 
@@ -36,7 +40,7 @@
 MAIL_FROM = 'Open Computing Facility <help@ocf.berkeley.edu>'
 
 MAIL_SIGNATURE = """Thanks for flying OCF,
-The friendly staff of 171 MLK
+The friendly staff of 171 MLK Student Union
 
 =========
 The Open Computing Facility is an all-volunteer, student-run service

ocflib/infra/ldap.py

@@ -1,7 +1,7 @@
+import string
 from base64 import b64encode
 from contextlib import contextmanager
 from itertools import chain
-from string import ascii_letters
 from textwrap import dedent
 
 import ldap3
@@ -13,16 +13,42 @@
 
 @contextmanager
 def ldap_connection(host):
+    """Context manager that provides an ldap3 Connection.
+
+    Example usage:
+
+       with ldap_connection('ldap.ocf.berkeley.edu') as c:
+            c.search(OCF_LDAP_PEOPLE, '(uid=ckuehl)', attributes=['uidNumber'])
+
+    You might find it more convenient to use the ldap_ocf or ldap_ucb functions
+    also defined.
+
+    :param host: server hostname
+    """
     server = ldap3.Server(host, use_ssl=True)
     with ldap3.Connection(server) as connection:
         yield connection
 
 
 def ldap_ocf():
+    """Context manager that provides an ldap3 Connection to OCF's LDAP server.
+
+    Example usage:
+
+       with ldap_ocf() as c:
+            c.search(OCF_LDAP_PEOPLE, '(uid=ckuehl)', attributes=['uidNumber'])
+    """
     return ldap_connection(constants.OCF_LDAP)
 
 
 def ldap_ucb():
+    """Context manager that provides an ldap3 Connection to the campus LDAP.
+
+    Example usage:
+
+       with ldap_ucb() as c:
+            c.search(UCB_LDAP_PEOPLE, '(uid=ckuehl)', attributes=['uidNumber'])
+    """
     return ldap_connection(constants.UCB_LDAP)
 
 
@@ -48,7 +74,7 @@ def create_ldap_entry_with_keytab(
     def format_attr(key, values):
         # might be possible to have non-ASCII letters in keys, but don't think
         # it will happen to us. we can fix this if it ever does.
-        assert all(c in ascii_letters for c in key), 'Key is ASCII letters.'
+        assert all(c in string.ascii_letters for c in key), 'key is not ASCII letters'
 
         # rather than try to carefully escape values, we just base64 encode
         return (