From afcdd7bb34a867ba922eb24f8d165ef9a638ec92 Mon Sep 17 00:00:00 2001 From: Stephen Milner Date: Mon, 23 Nov 2015 13:35:48 -0500 Subject: [PATCH] doc: Added basic docstrings. --- pykube/__init__.py | 3 ++ pykube/config.py | 54 ++++++++++++++++++++++++++++++ pykube/exceptions.py | 8 +++++ pykube/http.py | 79 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 144 insertions(+) diff --git a/pykube/__init__.py b/pykube/__init__.py index e69de29..6f8319e 100644 --- a/pykube/__init__.py +++ b/pykube/__init__.py @@ -0,0 +1,3 @@ +""" +Python client for Kubernetes +""" diff --git a/pykube/config.py b/pykube/config.py index 26bd292..041b2c7 100644 --- a/pykube/config.py +++ b/pykube/config.py @@ -1,3 +1,7 @@ +""" +Configuration code. +""" + import base64 import copy import tempfile @@ -6,14 +10,27 @@ 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()) @@ -21,10 +38,19 @@ def parse(self): 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,6 +92,10 @@ 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") @@ -67,6 +103,9 @@ def cluster(self): @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") @@ -74,6 +113,9 @@ def user(self): 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,6 +142,9 @@ 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() @@ -101,6 +152,9 @@ def bytes(self): return self._bytes def filename(self): + """ + Returns the provided data as a file location. + """ if self._filename: return self._filename else: diff --git a/pykube/exceptions.py b/pykube/exceptions.py index abde7e5..c1b93f8 100644 --- a/pykube/exceptions.py +++ b/pykube/exceptions.py @@ -1,2 +1,10 @@ +""" +Exceptions. +""" + + class KubernetesError(Exception): + """ + Base exception for all Kubernetes errors. + """ pass diff --git a/pykube/http.py b/pykube/http.py index 2582d10..bc1bc8d 100644 --- a/pykube/http.py +++ b/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))