From 93af278d6170cb38eeb189fe8deb957b98d20876 Mon Sep 17 00:00:00 2001
From: Christopher Rosell <chrippa@tanuki.se>
Date: Fri, 24 Aug 2012 02:28:42 +0200
Subject: Add some docs.

---
 src/livestreamer/__init__.py         | 27 +++++++++++++++++++++++++++
 src/livestreamer/plugins/__init__.py | 14 ++++++++++++++
 src/livestreamer/stream.py           | 12 +++++++++++-
 3 files changed, 52 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/livestreamer/__init__.py b/src/livestreamer/__init__.py
index f554fb6..0f50dea 100644
--- a/src/livestreamer/__init__.py
+++ b/src/livestreamer/__init__.py
@@ -9,6 +9,11 @@ import pkgutil
 import imp
 
 class Livestreamer(object):
+    """
+        A Livestreamer session is used to keep track of plugins, options, log settings.
+
+    """
+
     def __init__(self):
         self.options = Options({
             "rtmpdump": None,
@@ -19,28 +24,44 @@ class Livestreamer(object):
         self.load_builtin_plugins()
 
     def set_option(self, key, value):
+        """Set option *key* to *value*."""
         self.options.set(key, value)
 
     def get_option(self, key):
+        """Return option *key*"""
         return self.options.get(key)
 
     def set_plugin_option(self, plugin, key, value):
+        """Set plugin option *key* to *value* for the plugin *plugin*."""
         if plugin in self.plugins:
             plugin = self.plugins[plugin]
             plugin.set_option(key, value)
 
     def get_plugin_option(self, plugin, key):
+        """Return plugin option *key* for the plugin *plugin*."""
         if plugin in self.plugins:
             plugin = self.plugins[plugin]
             return plugin.get_option(key)
 
     def set_loglevel(self, level):
+        """
+            Set the log level to *level*.
+            Valid levels are: none, error, warning, info, debug.
+        """
         self.logger.set_level(level)
 
     def set_logoutput(self, output):
+        """
+            Set the log output to *output*. Expects a file like
+            object with a write method.
+        """
         self.logger.set_output(output)
 
     def resolve_url(self, url):
+        """
+            Attempt to find the correct plugin for *url* and return it.
+            Raises :exc:`NoPluginError` on failure.
+        """
         parsed = urlparse(url)
 
         if len(parsed.scheme) == 0:
@@ -54,6 +75,9 @@ class Livestreamer(object):
         raise NoPluginError
 
     def get_plugins(self):
+        """
+            Returns the loaded plugins for the session.
+        """
         return self.plugins
 
     def load_builtin_plugins(self):
@@ -62,6 +86,9 @@ class Livestreamer(object):
             self.load_plugin(name, file, pathname, desc)
 
     def load_plugins(self, path):
+        """
+            Attempt to load plugins from the *path* directory.
+        """
         for loader, name, ispkg in pkgutil.iter_modules(path):
             file, pathname, desc = imp.find_module(name, path)
             self.load_plugin(name, file, pathname, desc)
diff --git a/src/livestreamer/plugins/__init__.py b/src/livestreamer/plugins/__init__.py
index 4c70fdc..ad96f6c 100644
--- a/src/livestreamer/plugins/__init__.py
+++ b/src/livestreamer/plugins/__init__.py
@@ -1,6 +1,10 @@
 from livestreamer.options import Options
 
 class Plugin(object):
+    """
+        A plugin can retrieve stream information from the *url* specified.
+    """
+
     options = Options()
 
     def __init__(self, url):
@@ -20,6 +24,16 @@ class Plugin(object):
         return cls.options.get(key)
 
     def get_streams(self):
+        """
+            Retrieves and returns a :class:`dict` containing the streams.
+
+            The key is the name of the stream, most commonly the quality.
+            The value is a :class:`Stream` object.
+
+            The stream with key *best* is a reference to the stream most likely
+            to be of highest quality.
+        """
+
         ranking = ["iphonelow", "iphonehigh", "240p", "320k", "360p", "850k",
                    "480p", "1400k", "720p", "2400k", "hd", "1080p", "live"]
         streams = self._get_streams()
diff --git a/src/livestreamer/stream.py b/src/livestreamer/stream.py
index 398bb6f..e71e3bc 100644
--- a/src/livestreamer/stream.py
+++ b/src/livestreamer/stream.py
@@ -10,11 +10,21 @@ class StreamError(Exception):
     pass
 
 class Stream(object):
+    """
+        This is a base class that should be inherited when implementing
+        different stream types. Should only be used directly from plugins.
+    """
+
     def __init__(self, session):
         self.session = session
 
     def open(self):
-       raise NotImplementedError
+        """
+            Opens a connection to the stream.
+            Returns a file-like object than can be used to read data.
+            Raises :exc:`StreamError` on failure.
+        """
+        raise NotImplementedError
 
 class StreamProcess(Stream):
     def __init__(self, session, params={}):
-- 
cgit v1.2.3