add lots more docstrings

pykeepass/attachment.py

@@ -20,6 +20,7 @@ def __repr__(self):
 
     @property
     def id(self):
+        """str: get or set id of binary the attachment points to"""
         return int(self._element.find('Value').attrib['Ref'])
 
     @id.setter
@@ -28,6 +29,7 @@ def id(self, id):
 
     @property
     def filename(self):
+        """str: get or set filename attachment"""
         return self._element.find('Key').text
 
     @filename.setter
@@ -36,11 +38,13 @@ def filename(self, filename):
 
     @property
     def entry(self):
+        """Entry: get entry this attachment is associated with"""
         ancestor = self._element.getparent()
         return pykeepass.entry.Entry(element=ancestor, kp=self._kp)
 
     @property
     def binary(self):
+        """bytes: get binary this attachment points to"""
         try:
             return self._kp.binaries[self.id]
         except IndexError:
@@ -49,4 +53,5 @@ def binary(self):
     data = binary
 
     def delete(self):
+        """delete this attachment"""
         self._element.getparent().remove(self._element)

pykeepass/entry.py

@@ -124,6 +124,7 @@ def deref(self, attribute):
 
     @property
     def title(self):
+        """str: get or set entry title"""
         return self._get_string_field('Title')
 
     @title.setter
@@ -132,6 +133,7 @@ def title(self, value):
 
     @property
     def username(self):
+        """str: get or set entry username"""
         return self._get_string_field('UserName')
 
     @username.setter
@@ -140,6 +142,7 @@ def username(self, value):
 
     @property
     def password(self):
+        """str: get or set entry password"""
         return self._get_string_field('Password')
 
     @password.setter
@@ -148,6 +151,7 @@ def password(self, value):
 
     @property
     def url(self):
+        """str: get or set entry URL"""
         return self._get_string_field('URL')
 
     @url.setter
@@ -156,6 +160,7 @@ def url(self, value):
 
     @property
     def notes(self):
+        """str: get or set entry notes"""
         return self._get_string_field('Notes')
 
     @notes.setter
@@ -164,6 +169,7 @@ def notes(self, value):
 
     @property
     def icon(self):
+        """str: get or set entry icon. See icons.py"""
         return self._get_subelement_text('IconID')
 
     @icon.setter
@@ -172,6 +178,7 @@ def icon(self, value):
 
     @property
     def tags(self):
+        """str: get or set entry tags"""
         val = self._get_subelement_text('Tags')
         return val.split(';') if val else val
 
@@ -183,6 +190,7 @@ def tags(self, value):
 
     @property
     def otp(self):
+        """str: get or set entry OTP text. (defacto standard)"""
         return self._get_string_field('otp')
 
     @otp.setter
@@ -191,6 +199,7 @@ def otp(self, value):
 
     @property
     def history(self):
+        """:obj:`list` of :obj:`HistoryEntry`: get entry history"""
         if self._element.find('History') is not None:
             return [HistoryEntry(element=x, kp=self._kp) for x in self._element.find('History').findall('Entry')]
         else:
@@ -202,6 +211,7 @@ def history(self, value):
 
     @property
     def autotype_enabled(self):
+        """bool: get or set autotype enabled state.  Determines whether `autotype_sequence` should be used"""
         enabled = self._element.find('AutoType/Enabled')
         if enabled.text is not None:
             return enabled.text == 'True'
@@ -216,6 +226,7 @@ def autotype_enabled(self, value):
 
     @property
     def autotype_sequence(self):
+        """str: get or set [autotype string](https://keepass.info/help/base/autotype.html)"""
         sequence = self._element.find('AutoType/DefaultSequence')
         if sequence is None or sequence.text == '':
             return None
@@ -227,6 +238,7 @@ def autotype_sequence(self, value):
 
     @property
     def is_a_history_entry(self):
+        """bool: check if entry is History entry"""
         parent = self._element.getparent()
         if parent is not None:
             return parent.tag == 'History'
@@ -235,7 +247,7 @@ def is_a_history_entry(self):
     @property
     def path(self):
         """Path to element as list.  List contains all parent group names
-        ending with entry title.  List may contain strings or NoneTypes."""
+        ending with entry title.  List contains strings or NoneTypes."""
 
         # The root group is an orphan
         if self.parentgroup is None:
@@ -273,7 +285,16 @@ def custom_properties(self):
         return props
 
     def ref(self, attribute):
-        """Create reference to an attribute of this element."""
+        """Create reference to an attribute of this element.
+
+        Args:
+            attribute (str): one of 'title', 'username', 'password', 'url', 'notes', or 'uuid'
+
+        Returns:
+            str: [field reference][fieldref] to this field of this entry
+
+        [fieldref]: https://keepass.info/help/base/fieldrefs.html
+        """
         attribute_to_field = {
             'title': 'T',
             'username': 'U',

pykeepass/group.py

@@ -42,6 +42,7 @@ def __init__(self, name=None, element=None, icon=None, notes=None,
 
     @property
     def name(self):
+        """str: get or set group name"""
         return self._get_subelement_text('Name')
 
     @name.setter
@@ -50,6 +51,7 @@ def name(self, value):
 
     @property
     def notes(self):
+        """str: get or set group notes"""
         return self._get_subelement_text('Notes')
 
     @notes.setter
@@ -58,23 +60,22 @@ def notes(self, value):
 
     @property
     def entries(self):
-        # FIXME
-        # It may be better to keep a list of Entries as a (list) property
-        # ... but that may become out of sync and what is supposed to happen
-        # when an entry is updated?!
-        # On the other side this would make things like "e in g.entries" work
+        """:obj:`list` of :obj:`Entry`: get list of entries in this group"""
         return [pykeepass.entry.Entry(element=x, kp=self._kp) for x in self._element.findall('Entry')]
 
     @property
     def subgroups(self):
+        """:obj:`list` of :obj:`Group`: get list of groups in this group"""
         return [Group(element=x, kp=self._kp) for x in self._element.findall('Group')]
 
     @property
     def is_root_group(self):
+        """bool: return True if this is the database root"""
         return self._element.getparent().tag == 'Root'
 
     @property
     def path(self):
+        """:obj:`list` of (:obj:`str` or None): a list containing names of all parent groups, not including root"""
         # The root group is an orphan
         if self.is_root_group or self.parentgroup is None:
             return []
@@ -87,6 +88,11 @@ def path(self):
         return path
 
     def append(self, entries):
+        """Add copy of an entry to this group
+
+        Args:
+            entries (:obj:`Entry` or :obj:`list` of :obj:`Entry`)
+        """
         if type(entries) is list:
             for e in entries:
                 self._element.append(e._element)