doc for base plugin

4 files changed, 111 insertions, 57 deletions

diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst
index 4ffe2e457..e3c72994b 100644
--- a/docs/plugins/base_plugin.rst
+++ b/docs/plugins/base_plugin.rst
@@ -3,22 +3,106 @@
 Base Plugin - And here it begins...
 ===================================
 
+A Plugin in pyLoad is a python file located at one of the subfolders in :file:`module/plugins/`.
+All different plugin types inherit from :class:`Base <module.plugins.Base.Base>`, which defines basic methods
+and meta data. You should read this section carefully, because it's the base for all plugin development.
+After that it is a good idea to look at several already existing plugin to get a more detailed idea of how
+they have to look like and whats possible with them.
 
 Meta Data
 ---------
 
+All important data which must be known by pyLoad is set using class attributes pre- and suffixed with ``__``.
+An overview of acceptible values can be found in :class:`Base <module.plugins.Base.Base>` source code.
+Non needed attributes can be left out, except ``__version__``. Nevertheless please fill out most information
+as you can, when you want to submit your plugin to the public repo.
+
+You don't need to subclass :class:`Base <module.plugins.Base.Base>` directly, but the
+intermediate type according to your plugin. As example we choose an Hoster plugin, but the same is true for all
+plugin types.
+
+For localization pyLoad supports gettext [1]_, to mark strings for translation surround them with ``_("...")``.
+
+How basic hoster plugin header could look like::
+
+        from module.plugin.Hoster import Hoster
+
+        class MyFileHoster(Hoster):
+                __version__ = "0.1"
+                __description__ = _("Short description of the plugin")
+                __long_description = _("""A even longer description
+                is not needed for hoster plugin,
+                but hook plugin should have it so the user knows what they doing.""")
 
 Config Entries
 --------------
 
+Every plugin is allowed to add entries to the config. These are defined via ``__config__`` and consists
+of a list with tuples in the format of ``(name, type, verbose_name, default_value)`` or
+``(name, type, verbose_name, short_description, default_value)``.
+
+Example from Youtube plugin::
+
+        class YoutubeCom:
+            __config__ = [("quality", "sd;hd;fullhd", _("Quality Setting"), "hd"),
+                          ("fmt", "int", _("FMT Number 0-45"), _("Desired FMT number, look them up at wikipedia"), 0),
+                          (".mp4", "bool", _("Allow .mp4"), True)]
+
+
+At runtime the desired config values can be retrieved with ``self.getConfig(name)`` and setted with
+``self.setConfig(name, value)``.
 
 Tagging Guidelines
 ------------------
 
+To categorize a plugin, a list of keywords can be assigned via ``__tags__`` attribute. You may add arbitrary
+tags as you like, but please look at this table first to choose your tags. With standardised keywords we can generate
+a better overview of the plugins and provide some search criteria.
+
+=============== ===========================================================
+Keyword         Meaning
+=============== ===========================================================
+image           Anything related to image(hoster)
+video           Anything related to video(hoster)
+captcha         A plugin that needs captcha decrypting
+interaction     A plugin that makes uses of interaction with user
+free            A hoster without any premium service
+premium_only    A hoster only useable with account
+ip_check        A hoster that checks ip, that can be avoided with reconnect
+=============== ===========================================================
 
 Basic Methods
 -------------
 
+All methods can be looked up at :class:`Base <module.plugins.Base.Base>`. To note some important ones:
+
+The pyload core instance is accessible at ``self.core`` attribute
+and the :class:`Api <module.Api.Api>` at ``self.core.api``
+
+With ``self.load(...)`` you can load any url and get the result. This method is only available to Hoster and Crypter.
+For other plugins use ``getURL(...)`` or ``getRequest()``.
+
+Use ``self.store(...)`` and ``self.retrieve(...)`` to store data persistantly into the database.
+
+Make use of ``logInfo, logError, logWarning, logDebug`` for logging purposes.
+
 Debugging
 ---------
 
+One of the most important aspects in software programming is debugging. It is especially important
+for plugins which heavily rely on external input, which is true for all hoster and crypter plugins.
+To enable debugging functionality start pyLoad with ``-d`` option or enable it in the config.
+
+You should use ``self.logDebug(msg)`` when ever it is reasonable. It is a good pratice to log server output
+or the calculation of results and then check in the log if it really it what you are expecting.
+
+For further debugging you can install ipython [2]_, and set breakpoints with ``self.core.breakpoint()``.
+It will open the python debugger [3]_ and pause the plugin thread.
+To open a ipython shell in the running programm use ``self.shell()``.
+These methods are usefull to gain access to the code flow at runtime and check or modify variables.
+
+
+.. rubric:: Footnotes
+.. [1] http://docs.python.org/library/gettext.html
+.. [2] http://ipython.org/
+.. [3] http://docs.python.org/library/pdb.html
\ No newline at end of file
diff --git a/docs/plugins/crypter_plugin.rst b/docs/plugins/crypter_plugin.rst
index d910ec412..639d58abf 100644
--- a/docs/plugins/crypter_plugin.rst
+++ b/docs/plugins/crypter_plugin.rst
@@ -3,3 +3,23 @@
 Crypter - Extract links from pages
 ==================================
 
+What about Decrypter and Container plugins?
+Well, they work nearly the same, only that the function they have to provide is named ``decrypt``
+
+Example: ::
+
+    from module.plugin.Crypter import Crypter
+
+    class MyFileCrypter(Crypter):
+        """
+            plugin code
+        """
+        def decrypt(self, pyfile):
+
+            urls = ["http://get.pyload.org/src", "http://get.pyload.org/debian", "http://get.pyload.org/win"]
+
+            self.packages.append(("pyLoad packages", urls, "pyLoad packages")) # urls list of urls
+
+They can access all the methods from :class:`Plugin <module.plugins.Plugin.Plugin>`, but the important thing is they
+have to append all packages they parsed to the `self.packages` list. Simply append tuples with `(name, urls, folder)`,
+where urls is the list of urls contained in the packages. Thats all of your work, pyLoad will know what to do with them.
diff --git a/docs/plugins/hoster_plugin.rst b/docs/plugins/hoster_plugin.rst
index 59f35f5cb..e4575a001 100644
--- a/docs/plugins/hoster_plugin.rst
+++ b/docs/plugins/hoster_plugin.rst
@@ -3,39 +3,6 @@
 Hoster - Load files to disk
 ===========================
 
-A Plugin is a python file located at one of the subfolders in :file:`module/plugins/`. Either :file:`hoster`, :file:`crypter`
-or :file:`container`, depending of it's type.
-
-There are three kinds of different plugins: **Hoster**, **Crypter**, **Container**.
-All kind of plugins inherit from the base :class:`Plugin <module.plugins.Plugin.Plugin>`. You should know its
-convenient methods, they make your work easier ;-)
-
-Every plugin defines a ``__pattern__`` and when the user adds urls, every url is matched against the pattern defined in
-the plugin. In case the ``__pattern__`` matched on the url the plugin will be assigned to handle it and instanciated when
-pyLoad begins to download/decrypt the url.
-
-Plugin header
--------------
-
-How basic hoster plugin header could look like: ::
-
-        from module.plugin.Hoster import Hoster
-
-        class MyFileHoster(Hoster):
-                __version__ = "0.1"
-                __pattern__ = r"http://myfilehoster.example.com/file_id/[0-9]+"
-                __config__ = []
-
-You have to define these meta-data, ``__pattern__`` has to be a regexp that sucessfully compiles with
-``re.compile(__pattern__)``.
-
-Just like :ref:`write_hooks` you can add and use config values exatly the same way.
-If you want a Crypter or Container plugin, just replace the word Hoster with your desired plugin type.
-
-
-Hoster plugins
---------------
-
 We head to the next important section, the ``process`` method of your plugin.
 In fact the ``process`` method is the only functionality your plugin has to provide, but its always a good idea to split up tasks to not produce spaghetti code.
 An example ``process`` function could look like this ::
@@ -61,40 +28,23 @@ You need to know about the :class:`PyFile <module.PyFile.PyFile>` class, since a
 Some tasks your plugin should handle:  proof if file is online, get filename, wait if needed, download the file, etc..
 
 Wait times
-__________
+----------
 
 Some hoster require you to wait a specific time. Just set the time with ``self.setWait(seconds)`` or
 ``self.setWait(seconds, True)`` if you want pyLoad to perform a reconnect if needed.
 
 Captcha decrypting
-__________________
+------------------
 
 To handle captcha input just use ``self.decryptCaptcha(url, ...)``, it will be send to clients
 or handled by :class:`Hook <module.plugins.Hook.Hook>` plugins
 
-Crypter
--------
-
-What about Decrypter and Container plugins?
-Well, they work nearly the same, only that the function they have to provide is named ``decrypt``
+User interaction
+----------------
 
-Example: ::
-
-    from module.plugin.Crypter import Crypter
-
-    class MyFileCrypter(Crypter):
-        """
-            plugin code
-        """
-        def decrypt(self, pyfile):
-
-            urls = ["http://get.pyload.org/src", "http://get.pyload.org/debian", "http://get.pyload.org/win"]
-
-            self.packages.append(("pyLoad packages", urls, "pyLoad packages")) # urls list of urls
+Testing
+-------
 
-They can access all the methods from :class:`Plugin <module.plugins.Plugin.Plugin>`, but the important thing is they
-have to append all packages they parsed to the `self.packages` list. Simply append tuples with `(name, urls, folder)`,
-where urls is the list of urls contained in the packages. Thats all of your work, pyLoad will know what to do with them.
 
 Examples
 --------
diff --git a/docs/plugins/overview.rst b/docs/plugins/overview.rst
index 23913b787..68ad96dfd 100755
--- a/docs/plugins/overview.rst
+++ b/docs/plugins/overview.rst
@@ -14,7 +14,7 @@ Extending pyLoad
 
 pyLoad offers an comfortable and powerful plugin system to make extending possible. With it you only need to have some
 python knowledge and can just start right away writing your own plugins. This document gives you an overwiew about the
-conceptual part. You should not left out the `Base` part, since it contains basic functionality for all plugins types.
+conceptual part. You should not left out the :doc:`Base <base_plugin>` part, since it contains basic functionality for all plugins types.
 
 .. rubric:: Contents