doc: Added basic docstrings.

pykube/__init__.py

@@ -0,0 +1,3 @@
+"""
+Python client for Kubernetes
+"""

pykube/config.py

@@ -1,3 +1,7 @@
+"""
+Configuration code.
+"""
+
 import base64
 import copy
 import tempfile
@@ -6,25 +10,47 @@
 
 
 class KubeConfig(object):
+    """
+    Main configuration class.
+    """
 
     def __init__(self, filename):
+        """
+        Creates an instance of the KubeConfig class.
+
+        :Parameters:
+           - `filename`: The full path to the configuration file
+        """
         self.filename = filename
         self.doc = None
         self.current_context = None
 
     def parse(self):
+        """
+        Parses the configuration file.
+        """
         if self.doc is not None:
+            # TODO: Warn if there is nothing to parse?
             return
         with open(self.filename) as f:
             self.doc = yaml.load(f.read())
         if "current-context" in self.doc and self.doc["current-context"]:
             self.set_current_context(self.doc["current-context"])
 
     def set_current_context(self, value):
+        """
+        Sets the context to the provided value.
+
+        :Parameters:
+           - `value`: The value for the current context
+        """
         self.current_context = value
 
     @property
     def clusters(self):
+        """
+        Returns known clusters by exposing as a read-only property.
+        """
         if not hasattr(self, "_clusters"):
             self.parse()
             cs = {}
@@ -38,6 +64,9 @@ def clusters(self):
 
     @property
     def users(self):
+        """
+        Returns known users by exposing as a read-only property.
+        """
         if not hasattr(self, "_users"):
             self.parse()
             us = {}
@@ -50,6 +79,9 @@ def users(self):
 
     @property
     def contexts(self):
+        """
+        Returns known contexts by exposing as a read-only property.
+        """
         if not hasattr(self, "_contexts"):
             self.parse()
             cs = {}
@@ -60,20 +92,30 @@ def contexts(self):
 
     @property
     def cluster(self):
+        """
+        Returns the current selected cluster by exposing as a
+        read-only property.
+        """
         self.parse()
         if self.current_context is None:
             raise Exception("current context not set; call set_current_context")
         return self.clusters[self.contexts[self.current_context]["cluster"]]
 
     @property
     def user(self):
+        """
+        Returns the current user by exposing as a read-only property.
+        """
         self.parse()
         if self.current_context is None:
             raise Exception("current context not set; call set_current_context")
         return self.users[self.contexts[self.current_context]["user"]]
 
 
 class BytesOrFile(object):
+    """
+    Implements the same interface for files and byte input.
+    """
 
     @classmethod
     def maybe_set(cls, d, key):
@@ -86,6 +128,12 @@ def maybe_set(cls, d, key):
             d[file_key] = cls(d[file_key])
 
     def __init__(self, data):
+        """
+        Creates a new instance of BytesOrFile.
+
+        :Parameters:
+           - `data`: A full path to a file or base64 encoded bytes
+        """
         self._filename = None
         self._bytes = None
         if data.startswith("/"):
@@ -94,13 +142,19 @@ def __init__(self, data):
             self._bytes = base64.b64decode(data)
 
     def bytes(self):
+        """
+        Returns the provided data as bytes.
+        """
         if self._filename:
             with open(self._filename, "rb") as f:
                 return f.read()
         else:
             return self._bytes
 
     def filename(self):
+        """
+        Returns the provided data as a file location.
+        """
         if self._filename:
             return self._filename
         else:

pykube/exceptions.py

@@ -1,2 +1,10 @@
+"""
+Exceptions.
+"""
+
+
 class KubernetesError(Exception):
+    """
+    Base exception for all Kubernetes errors.
+    """
     pass

pykube/http.py

@@ -1,17 +1,34 @@
+"""
+HTTP request related code.
+"""
+
 import posixpath
 
 import requests
 
 
 class HTTPClient(object):
+    """
+    Client for interfacing with the Kubernetes API.
+    """
 
     def __init__(self, config, version="v1"):
+        """
+        Creates a new instance of the HTTPClient.
+
+        :Parameters:
+           - `config`: The configuration instance
+           - `version`: The version of the API to use
+        """
         self.config = config
         self.url = self.config.cluster["server"]
         self.version = version
         self.session = self.build_session()
 
     def build_session(self):
+        """
+        Creates a new session for the client.
+        """
         s = requests.Session()
         if "certificate-authority" in self.config.cluster:
             s.verify = self.config.cluster["certificate-authority"].filename()
@@ -25,6 +42,12 @@ def build_session(self):
         return s
 
     def get_kwargs(self, **kwargs):
+        """
+        Creates a full URL to request based on arguments.
+
+        :Parametes:
+           - `kwargs`: All keyword arguments to build a kubernetes API endpoint
+        """
         bits = [
             "/api",
             self.version,
@@ -42,25 +65,81 @@ def get_kwargs(self, **kwargs):
         return kwargs
 
     def request(self, *args, **kwargs):
+        """
+        Makes an API request based on arguments.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.request(*args, **self.get_kwargs(**kwargs))
 
     def get(self, *args, **kwargs):
+        """
+        Executes an HTTP GET.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.get(*args, **self.get_kwargs(**kwargs))
 
     def options(self, *args, **kwargs):
+        """
+        Executes an HTTP OPTIONS.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.options(*args, **self.get_kwargs(**kwargs))
 
     def head(self, *args, **kwargs):
+        """
+        Executes an HTTP HEAD.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.head(*args, **self.get_kwargs(**kwargs))
 
     def post(self, *args, **kwargs):
+        """
+        Executes an HTTP POST.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.post(*args, **self.get_kwargs(**kwargs))
 
     def put(self, *args, **kwargs):
+        """
+        Executes an HTTP PUT.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.put(*args, **self.get_kwargs(**kwargs))
 
     def patch(self, *args, **kwargs):
+        """
+        Executes an HTTP PATCH.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.patch(*args, **self.get_kwargs(**kwargs))
 
     def delete(self, *args, **kwargs):
+        """
+        Executes an HTTP DELETE.
+
+        :Parameters:
+           - `args`: Non-keyword arguments
+           - `kwargs`: Keyword arguments
+        """
         return self.session.delete(*args, **self.get_kwargs(**kwargs))