Improve documentation

server/command.py

@@ -58,13 +58,28 @@ class AbstractCommand(ABC):
     @property
     @abstractmethod
     def _conditional_headers(self):
+        """
+        The conditional headers specific to this command instance.
+        """
         pass
 
     @abstractmethod
     def execute(self):
+        """
+        Execute the command
+        """
         pass
 
     def _build_message(self, status: int, content_type: str, body: bytes, extra_headers=None):
+        """
+        Build the response message.
+
+        @param status: The response status code
+        @param content_type: The response content-type header
+        @param body: The response body, may be empty.
+        @param extra_headers: Extra headers needed in the response message
+        @return: The encoded response message
+        """
 
         if extra_headers is None:
             extra_headers = {}
@@ -96,6 +111,13 @@ class AbstractCommand(ABC):
         return message
 
     def _get_path(self, check=True):
+        """
+        Returns the absolute file system path of the resource in the request.
+
+        @param check: If True, throws an error if the file doesn't exist
+        @raise NotFound: if `check` is True and the path doesn't exist
+        """
+
         norm_path = os.path.normpath(self.msg.target.path)
 
         if norm_path == "/":
@@ -109,6 +131,9 @@ class AbstractCommand(ABC):
         return path
 
     def _process_conditional_headers(self):
+        """
+        Processes the conditional headers for this command instance.
+        """
 
         for header in self._conditional_headers:
             tmp = self.msg.headers.get(header)
@@ -118,6 +143,13 @@ class AbstractCommand(ABC):
             self._conditional_headers[header]()
 
     def _if_modified_since(self):
+        """
+        Processes the if-modified-since header.
+        @return: True if the header is invalid, and thus shouldn't be taken into account, throws NotModified
+        if the content isn't modified since the given date.
+
+        @raise NotModified: If the date of if-modified-since greater than the modify date of the resource.
+        """
         date_val = self.msg.headers.get("if-modified-since")
         if not date_val:
             return True
@@ -133,6 +165,12 @@ class AbstractCommand(ABC):
         return True
 
     def get_mimetype(self, path):
+        """
+        Guess the type of file.
+        @param path: the path to the file to guess the type of
+        @return: The mimetype based on the extension, or if that fails, returns "text/plain" if the file is text,
+        otherwise returns "application/octet-stream"
+        """
         mime = mimetypes.guess_type(path)[0]
 
         if mime:
@@ -148,10 +186,16 @@ class AbstractCommand(ABC):
 
 
 class AbstractModifyCommand(AbstractCommand, ABC):
+    """
+    Base class for commands which modify a resource based on the request.
+    """
 
     @property
     @abstractmethod
     def _file_mode(self):
+        """
+        The mode to open the target resource with. (e.a. 'a' or 'w')
+        """
         pass
 
     @property
@@ -185,6 +229,10 @@ class AbstractModifyCommand(AbstractCommand, ABC):
 
 
 class HeadCommand(AbstractCommand):
+    """
+    A Command instance which represents an HEAD request
+    """
+
     @property
     def command(self):
         return "HEAD"
@@ -201,6 +249,10 @@ class HeadCommand(AbstractCommand):
 
 
 class GetCommand(AbstractCommand):
+    """
+    A Command instance which represents a GET request
+    """
+
     @property
     def command(self):
         return "GET"
@@ -221,6 +273,10 @@ class GetCommand(AbstractCommand):
 
 
 class PostCommand(AbstractModifyCommand):
+    """
+    A Command instance which represents a POST request
+    """
+
     @property
     def command(self):
         return "POST"
@@ -231,6 +287,10 @@ class PostCommand(AbstractModifyCommand):
 
 
 class PutCommand(AbstractModifyCommand):
+    """
+    A Command instance which represents a PUT request
+    """
+
     @property
     def command(self):
         return "PUT"