Add docstrings and use @property when needed.

radicale/__init__.py

@@ -18,6 +18,21 @@
 # You should have received a copy of the GNU General Public License
 # along with Radicale.  If not, see <http://www.gnu.org/licenses/>.
 
+"""
+Radicale Server module.
+
+This module offers 3 useful classes:
+
+- ``HTTPServer`` is a simple HTTP server;
+- ``HTTPSServer`` is a HTTPS server, wrapping the HTTP server in a socket
+  managing SSL connections;
+- ``CalendarHTTPHandler`` is a CalDAV request handler for HTTP(S) servers.
+
+To use this module, you should take a look at the file ``radicale.py`` that
+should have been included in this package.
+
+"""
+
 # TODO: Manage errors (see xmlutils)
 
 import socket
@@ -29,10 +44,14 @@ except ImportError:
 
 from radicale import config, support, xmlutils
 
-HTTPServer = server.HTTPServer
+class HTTPServer(server.HTTPServer):
+    """HTTP server."""
+    pass
 
 class HTTPSServer(HTTPServer):
+    """HTTPS server."""
     def __init__(self, address, handler):
+        """Create server by wrapping HTTP socket in an SSL socket."""
         # Fails with Python 2.5, import if needed
         import ssl
 
@@ -44,20 +63,23 @@ class HTTPSServer(HTTPServer):
             keyfile=config.get("server", "key"),
             ssl_version=ssl.PROTOCOL_SSLv23)
         self.server_bind()
-        self.server_activate()        
+        self.server_activate()
 
 class CalendarHTTPHandler(server.BaseHTTPRequestHandler):
     """HTTP requests handler for calendars."""
-    def _parse_path(self):
+    _encoding = config.get("encoding", "request")
+
+    @property
+    def calendar(self):
+        """The ``calendar.Calendar`` object corresponding to the given path."""
         path = self.path.strip("/").split("/")
         if len(path) >= 2:
             cal = "%s/%s" % (path[0], path[1])
-            self.calendar = calendar.Calendar("radicale", cal)
+            return calendar.Calendar("radicale", cal)
 
     def do_GET(self):
-        """Manage GET ``request``."""
-        self._parse_path()
-        answer = self.calendar.vcalendar().encode(config.get("encoding", "request"))
+        """Manage GET request."""
+        answer = self.calendar.vcalendar.encode(_encoding)
 
         self.send_response(client.OK)
         self.send_header("Content-Length", len(answer))
@@ -65,8 +87,7 @@ class CalendarHTTPHandler(server.BaseHTTPRequestHandler):
         self.wfile.write(answer)
 
     def do_DELETE(self):
-        """Manage DELETE ``request``."""
-        self._parse_path()
+        """Manage DELETE request."""
         obj = self.headers.get("if-match", None)
         answer = xmlutils.delete(obj, self.calendar, self.path)
 
@@ -76,15 +97,14 @@ class CalendarHTTPHandler(server.BaseHTTPRequestHandler):
         self.wfile.write(answer)
 
     def do_OPTIONS(self):
-        """Manage OPTIONS ``request``."""
+        """Manage OPTIONS request."""
         self.send_response(client.OK)
         self.send_header("Allow", "DELETE, GET, OPTIONS, PROPFIND, PUT, REPORT")
         self.send_header("DAV", "1, calendar-access")
         self.end_headers()
 
     def do_PROPFIND(self):
-        """Manage PROPFIND ``request``."""
-        self._parse_path()
+        """Manage PROPFIND request."""
         xml_request = self.rfile.read(int(self.headers["Content-Length"]))
         answer = xmlutils.propfind(xml_request, self.calendar, self.path)
 
@@ -95,14 +115,13 @@ class CalendarHTTPHandler(server.BaseHTTPRequestHandler):
         self.wfile.write(answer)
 
     def do_PUT(self):
-        """Manage PUT ``request``."""
+        """Manage PUT request."""
         # TODO: Improve charset detection
-        self._parse_path()
         contentType = self.headers["content-type"]
         if contentType and "charset=" in contentType:
             charset = contentType.split("charset=")[1].strip()
         else:
-            charset = config.get("encoding", "request")
+            charset = self._encoding
         ical_request = self.rfile.read(int(self.headers["Content-Length"])).decode(charset)
         obj = self.headers.get("if-match", None)
         xmlutils.put(ical_request, self.calendar, self.path, obj)
@@ -110,8 +129,7 @@ class CalendarHTTPHandler(server.BaseHTTPRequestHandler):
         self.send_response(client.CREATED)
 
     def do_REPORT(self):
-        """Manage REPORT ``request``."""
-        self._parse_path()
+        """Manage REPORT request."""
         xml_request = self.rfile.read(int(self.headers["Content-Length"]))
         answer = xmlutils.report(xml_request, self.calendar, self.path)