Minor documentation and typo fixes caused by my insane love for PEP-3101 and pylint

radicale/__init__.py

@@ -103,13 +103,16 @@ class Application(object):
         if config.getboolean('logging', 'full_environment'):
             self.headers_log = lambda environ: environ
 
-    def headers_log(self, environ):
+    # This method is overriden in __init__ if full_environment is set
+    # pylint: disable=E0202
+    @staticmethod
+    def headers_log(environ):
+        """Remove environment variables from the headers for logging purpose."""
         request_environ = dict(environ)
         for shell_variable in os.environ:
-            #if shell_variable not in request_environ:
-            #    continue
             del request_environ[shell_variable]
         return request_environ
+    # pylint: enable=E0202
 
     def decode(self, text, environ):
         """Try to magically decode ``text`` according to given ``environ``."""
@@ -267,9 +270,9 @@ class Application(object):
         """Manage MKCALENDAR request."""
         calendar = calendars[0]
         props = xmlutils.props_from_request(content)
-        tz = props.get('C:calendar-timezone')
-        if tz:
-            calendar.replace('', tz)
+        timezone = props.get('C:calendar-timezone')
+        if timezone:
+            calendar.replace('', timezone)
             del props['C:calendar-timezone']
         with calendar.props as calendar_props:
             for key, value in props.items():

radicale/ical.py

@@ -192,10 +192,10 @@ class Calendar(object):
                 if include_container:
                     result.append(cls(path, principal=True))
                 try:
-                    for f in next(os.walk(abs_path))[2]:
-                        f_path = os.path.join(path, f)
-                        if cls.is_vcalendar(os.path.join(abs_path, f)):
-                            result.append(cls(f_path))
+                    for filename in next(os.walk(abs_path))[2]:
+                        file_path = os.path.join(path, filename)
+                        if cls.is_vcalendar(os.path.join(abs_path, filename)):
+                            result.append(cls(file_path))
                 except StopIteration:
                     # directory does not exist yet
                     pass
@@ -211,13 +211,13 @@ class Calendar(object):
 
     @staticmethod
     def is_vcalendar(path):
-        """Return `True` if there is a VCALENDAR file under `path`."""
-        with open(path) as f:
-            return 'BEGIN:VCALENDAR' == f.read(15)
+        """Return ``True`` if there is a VCALENDAR file under ``path``."""
+        with open(path) as stream:
+            return 'BEGIN:VCALENDAR' == stream.read(15)
 
     @staticmethod
     def _parse(text, item_types, name=None):
-        """Find items with type in ``item_types`` in ``text`` text.
+        """Find items with type in ``item_types`` in ``text``.
 
         If ``name`` is given, give this name to new items in ``text``.
 
@@ -388,20 +388,22 @@ class Calendar(object):
     @property
     @contextmanager
     def props(self):
+        """Get the calendar properties."""
         props_path = self.path + '.props'
-        # on enter
+        # On enter
         properties = {}
         if os.path.exists(props_path):
             with open(props_path) as prop_file:
                 properties.update(json.load(prop_file))
         yield properties
-        # on exit
+        # On exit
         self._create_dirs(props_path)
         with open(props_path, 'w') as prop_file:
             json.dump(properties, prop_file)
 
     @property
     def owner_url(self):
+        """Get the calendar URL according to its owner."""
         if self.owner:
             return '/{}/'.format(self.owner).replace('//', '/')
         else:
@@ -409,4 +411,5 @@ class Calendar(object):
 
     @property
     def url(self):
+        """Get the standard calendar URL."""
         return '/{}/'.format(self.local_path).replace('//', '/')

radicale/xmlutils.py

@@ -30,8 +30,8 @@ in them for XML requests (all but PUT).
 try:
     from collections import OrderedDict
 except ImportError:
-    # Python 2.6
-    OrderedDict = dict
+    # Python 2.6 has no OrderedDict, use a dict instead
+    OrderedDict = dict # pylint: disable=C0103
 import re
 import xml.etree.ElementTree as ET
 
@@ -56,7 +56,7 @@ for short, url in NAMESPACES.items():
         ET.register_namespace("" if short == "D" else short, url)
     else:
         # ... and badly with Python 2.6 and 3.1
-        ET._namespace_map[url] = short
+        ET._namespace_map[url] = short # pylint: disable=W0212
 
 
 CLARK_TAG_REGEX = re.compile(r"""
@@ -95,9 +95,11 @@ def _tag(short_name, local):
 
 
 def _tag_from_clark(name):
-    """For a given name using the XML Clark notation returns a human-readable
-    variant of the tag name for known namespaces. Otherwise returns the name
-    as is.
+    """Get a human-readable variant of the XML Clark notation tag ``name``.
+
+    For a given name using the XML Clark notation, return a human-readable
+    variant of the tag name for known namespaces. Otherwise, return the name as
+    is.
 
     """
     match = CLARK_TAG_REGEX.match(name)
@@ -122,8 +124,7 @@ def name_from_path(path, calendar):
 
 
 def props_from_request(root, actions=("set", "remove")):
-    """Returns a list of properties as a dictionary."""
-
+    """Return a list of properties as a dictionary."""
     result = OrderedDict()
     if not isinstance(root, ET.Element):
         root = ET.fromstring(root.encode("utf8"))
@@ -139,6 +140,7 @@ def props_from_request(root, actions=("set", "remove")):
     if prop_element is not None:
         for prop in prop_element:
             result[_tag_from_clark(prop.tag)] = prop.text
+
     return result
 
 
@@ -190,6 +192,7 @@ def propfind(path, xml_request, calendars, user=None):
 
 
 def _propfind_response(path, item, props, user):
+    """Build and return a PROPFIND response."""
     is_calendar = isinstance(item, ical.Calendar)
     if is_calendar:
         with item.props as cal_props:
@@ -278,7 +281,7 @@ def _propfind_response(path, item, props, user):
                     element.text = calendar_props[human_tag]
                 else:
                     is404 = True
-        # not for calendars
+        # Not for calendars
         elif tag == _tag("D", "getcontenttype"):
             element.text = \
                 "text/calendar; component={}".format(item.tag.lower())
@@ -304,8 +307,13 @@ def _propfind_response(path, item, props, user):
 
 
 def _add_propstat_to(element, tag, status_number):
-    """Adds a propstat structure to the given element for the
-    following `tag` with the given `status_number`."""
+    """Add a PROPSTAT response structure to an element.
+
+    The PROPSTAT answer structure is defined in rfc4918-9.1. It is added to the
+    given ``element``, for the following ``tag`` with the given
+    ``status_number``.
+
+    """
     propstat = ET.Element(_tag("D", "propstat"))
     element.append(propstat)