From 1bb6ebf544b43cacf7c0755c5a8608b79b95e2d6 Mon Sep 17 00:00:00 2001 From: RaNaN Date: Sat, 7 Jan 2012 20:11:16 +0100 Subject: MultiHoster plugin type, some fixes, new documentation structure --- docs/plugins/base_plugin.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 docs/plugins/base_plugin.rst (limited to 'docs/plugins/base_plugin.rst') diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst new file mode 100644 index 000000000..62ab248ef --- /dev/null +++ b/docs/plugins/base_plugin.rst @@ -0,0 +1,5 @@ +.. _base_plugin: + +Base Plugin - And here it begins... +=================================== + -- cgit v1.2.3 From c654f31efc548957f10e3f4c1a5060dcea1dcdec Mon Sep 17 00:00:00 2001 From: RaNaN Date: Tue, 10 Jan 2012 00:04:24 +0100 Subject: changed HEAD request --- docs/plugins/base_plugin.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) (limited to 'docs/plugins/base_plugin.rst') diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst index 62ab248ef..4ffe2e457 100644 --- a/docs/plugins/base_plugin.rst +++ b/docs/plugins/base_plugin.rst @@ -3,3 +3,22 @@ Base Plugin - And here it begins... =================================== + +Meta Data +--------- + + +Config Entries +-------------- + + +Tagging Guidelines +------------------ + + +Basic Methods +------------- + +Debugging +--------- + -- cgit v1.2.3 From 180a9ee57a6f4eaa5f4bdd7a272057231f6a5c88 Mon Sep 17 00:00:00 2001 From: RaNaN Date: Sun, 29 Jan 2012 20:09:11 +0100 Subject: doc for base plugin --- docs/plugins/base_plugin.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) (limited to 'docs/plugins/base_plugin.rst') 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 `, 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 ` 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 ` 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 `. To note some important ones: + +The pyload core instance is accessible at ``self.core`` attribute +and the :class:`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 -- cgit v1.2.3 From 7df4718276a12b7f19a73d3b789c791d57bf4342 Mon Sep 17 00:00:00 2001 From: RaNaN Date: Sun, 29 Jan 2012 22:57:41 +0100 Subject: doc for crypter plugin --- docs/plugins/base_plugin.rst | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) (limited to 'docs/plugins/base_plugin.rst') diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst index e3c72994b..1849f3986 100644 --- a/docs/plugins/base_plugin.rst +++ b/docs/plugins/base_plugin.rst @@ -17,11 +17,15 @@ An overview of acceptible values can be found in :class:`Base ` and :class:`Crypter ` +needs to have a specific regexp [1]_ ``__pattern__``. This will be matched against input urls and if a suited +plugin is found it is selected to handle the url. + You don't need to subclass :class:`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 ``_("...")``. +For localization pyLoad supports gettext [2]_, to mark strings for translation surround them with ``_("...")``. How basic hoster plugin header could look like:: @@ -34,6 +38,8 @@ How basic hoster plugin header could look like:: is not needed for hoster plugin, but hook plugin should have it so the user knows what they doing.""") +In future examples the meta data will be left out, but remember it's required in every plugin! + Config Entries -------------- @@ -96,13 +102,14 @@ To enable debugging functionality start pyLoad with ``-d`` option or enable it i 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. +For further debugging you can install ipython [3]_, and set breakpoints with ``self.core.breakpoint()``. +It will open the python debugger [4]_ 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 +.. [1] http://docs.python.org/library/re.html +.. [2] http://docs.python.org/library/gettext.html +.. [3] http://ipython.org/ +.. [4] http://docs.python.org/library/pdb.html \ No newline at end of file -- cgit v1.2.3 From da4cf026ad116518fefc3429b74a8cd94aeef73f Mon Sep 17 00:00:00 2001 From: RaNaN Date: Sun, 5 Feb 2012 17:27:13 +0100 Subject: updated documentation + diagrams --- docs/plugins/base_plugin.rst | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) (limited to 'docs/plugins/base_plugin.rst') diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst index 1849f3986..911f5d429 100644 --- a/docs/plugins/base_plugin.rst +++ b/docs/plugins/base_plugin.rst @@ -5,8 +5,9 @@ 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 `, 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 +and meta data. You should read this section carefully, because it's the base for all plugin development. It +is also a good idea to look at the class diagram [1]_ for all plugin types to get an overview. +At last you should 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 @@ -18,15 +19,15 @@ Non needed attributes can be left out, except ``__version__``. Nevertheless plea as you can, when you want to submit your plugin to the public repo. Additionally :class:`Crypter ` and :class:`Crypter ` -needs to have a specific regexp [1]_ ``__pattern__``. This will be matched against input urls and if a suited +needs to have a specific regexp [2]_ ``__pattern__``. This will be matched against input urls and if a suited plugin is found it is selected to handle the url. +For localization pyLoad supports gettext [3]_, to mark strings for translation surround them with ``_("...")``. + You don't need to subclass :class:`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 [2]_, to mark strings for translation surround them with ``_("...")``. - How basic hoster plugin header could look like:: from module.plugin.Hoster import Hoster @@ -102,14 +103,15 @@ To enable debugging functionality start pyLoad with ``-d`` option or enable it i 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 [3]_, and set breakpoints with ``self.core.breakpoint()``. -It will open the python debugger [4]_ and pause the plugin thread. +For further debugging you can install ipython [4]_, and set breakpoints with ``self.core.breakpoint()``. +It will open the python debugger [5]_ 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/re.html -.. [2] http://docs.python.org/library/gettext.html -.. [3] http://ipython.org/ -.. [4] http://docs.python.org/library/pdb.html \ No newline at end of file +.. [1] :ref:`plugin_hierarchy` +.. [2] http://docs.python.org/library/re.html +.. [3] http://docs.python.org/library/gettext.html +.. [4] http://ipython.org/ +.. [5] http://docs.python.org/library/pdb.html \ No newline at end of file -- cgit v1.2.3 From 5a7f415a25d8e036a37851fcd5e9be81caae2804 Mon Sep 17 00:00:00 2001 From: X3n0m0rph59 Date: Sun, 22 Apr 2012 16:54:06 +0200 Subject: Fixed spelling in the documentation --- docs/plugins/base_plugin.rst | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) (limited to 'docs/plugins/base_plugin.rst') diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst index 911f5d429..91a6eef44 100644 --- a/docs/plugins/base_plugin.rst +++ b/docs/plugins/base_plugin.rst @@ -8,43 +8,43 @@ All different plugin types inherit from :class:`Base ` and meta data. You should read this section carefully, because it's the base for all plugin development. It is also a good idea to look at the class diagram [1]_ for all plugin types to get an overview. At last you should look at several already existing plugin to get a more detailed idea of how -they have to look like and whats possible with them. +they have to look like and what is 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 ` 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. +An overview of acceptable values can be found in :class:`Base ` source code. +Unneeded 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 repository. Additionally :class:`Crypter ` and :class:`Crypter ` -needs to have a specific regexp [2]_ ``__pattern__``. This will be matched against input urls and if a suited +needs to have a specific regexp [2]_ ``__pattern__``. This will be matched against input url's and if a suited plugin is found it is selected to handle the url. For localization pyLoad supports gettext [3]_, to mark strings for translation surround them with ``_("...")``. You don't need to subclass :class:`Base ` directly, but the -intermediate type according to your plugin. As example we choose an Hoster plugin, but the same is true for all +intermediate type according to your plugin. As an example we choose a hoster plugin, but the same is true for all plugin types. -How basic hoster plugin header could look like:: +How a 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.""") + __long_description = _("""An even longer description + is not needed for hoster plugins, + but the hook plugin should have it, so the users know what they are doing.""") In future examples the meta data will be left out, but remember it's required in every plugin! Config Entries -------------- -Every plugin is allowed to add entries to the config. These are defined via ``__config__`` and consists +Every plugin is allowed to add entries to the configuration. These are defined via ``__config__`` and consist of a list with tuples in the format of ``(name, type, verbose_name, default_value)`` or ``(name, type, verbose_name, short_description, default_value)``. @@ -56,7 +56,7 @@ Example from Youtube plugin:: (".mp4", "bool", _("Allow .mp4"), True)] -At runtime the desired config values can be retrieved with ``self.getConfig(name)`` and setted with +At runtime the desired config values can be retrieved with ``self.getConfig(name)`` and set with ``self.setConfig(name, value)``. Tagging Guidelines @@ -72,9 +72,9 @@ 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 +interaction A plugin that makes use of interaction with the user free A hoster without any premium service -premium_only A hoster only useable with account +premium_only A hoster only usable with account ip_check A hoster that checks ip, that can be avoided with reconnect =============== =========================================================== @@ -89,7 +89,7 @@ and the :class:`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. +Use ``self.store(...)`` and ``self.retrieve(...)`` to store data persistently into the database. Make use of ``logInfo, logError, logWarning, logDebug`` for logging purposes. @@ -98,15 +98,15 @@ 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. +To enable debugging functionality start pyLoad with the ``-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. +or the calculation of results and then check in the log if it really is what you are expecting. For further debugging you can install ipython [4]_, and set breakpoints with ``self.core.breakpoint()``. It will open the python debugger [5]_ 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. +These methods are useful to gain access to the code flow at runtime and check or modify variables. .. rubric:: Footnotes -- cgit v1.2.3 From e8eaa91da9e1236d8009df0d79bebe023de8933f Mon Sep 17 00:00:00 2001 From: RaNaN Date: Sun, 6 May 2012 13:04:15 +0200 Subject: little documentation update --- docs/plugins/base_plugin.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/plugins/base_plugin.rst') diff --git a/docs/plugins/base_plugin.rst b/docs/plugins/base_plugin.rst index 91a6eef44..f6813cf40 100644 --- a/docs/plugins/base_plugin.rst +++ b/docs/plugins/base_plugin.rst @@ -66,9 +66,9 @@ To categorize a plugin, a list of keywords can be assigned via ``__tags__`` attr 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 @@ -76,7 +76,7 @@ interaction A plugin that makes use of interaction with the user free A hoster without any premium service premium_only A hoster only usable with account ip_check A hoster that checks ip, that can be avoided with reconnect -=============== =========================================================== +=============== ================================================================= Basic Methods ------------- -- cgit v1.2.3