diff options
Diffstat (limited to 'docs/plugins')
| -rw-r--r-- | docs/plugins/addon_plugin.rst | 33 | ||||
| -rw-r--r-- | docs/plugins/base_plugin.rst | 36 | ||||
| -rw-r--r-- | docs/plugins/crypter_plugin.rst | 8 | ||||
| -rw-r--r-- | docs/plugins/hoster_plugin.rst | 8 | ||||
| -rwxr-xr-x | docs/plugins/overview.rst | 8 |
5 files changed, 47 insertions, 46 deletions
diff --git a/docs/plugins/addon_plugin.rst b/docs/plugins/addon_plugin.rst index 57c7e4a96..c2258f2aa 100644 --- a/docs/plugins/addon_plugin.rst +++ b/docs/plugins/addon_plugin.rst @@ -6,15 +6,15 @@ Addon - Add new functionality A Hook is a python file which is located at :file:`module/plugins/hooks`. The :class:`HookManager <module.HookManager.HookManager>` will load it automatically on startup. Only one instance exists over the complete lifetime of pyload. Your hook can interact on various events called by the :class:`HookManager <module.HookManager.HookManager>`, -do something complete autonomic and has full access to the :class:`Api <module.Api.Api>` and every detail of pyLoad. -The UpdateManager, CaptchaTrader, UnRar and many more are realised as hooks. +do something completely autonomic and has full access to the :class:`Api <module.Api.Api>` and every detail of pyLoad. +The UpdateManager, CaptchaTrader, UnRar and many more are implemented as hooks. Hook header ----------- -Your hook needs to subclass :class:`Hook <module.plugins.Hook.Hook>` and will inherit all of its method, make sure to check its documentation! +Your hook needs to subclass :class:`Hook <module.plugins.Hook.Hook>` and will inherit all of its methods, so make sure to check it's documentation! -All Hooks should start with something like this: :: +All hooks should start with something like this: :: from module.plugins.Hook import Hook @@ -28,7 +28,7 @@ All Hooks should start with something like this: :: __author_mail__ = ("me@has-no-mail.com") All meta-data is defined in the header, you need at least one option at ``__config__`` so the user can toggle your -hook on and off. Dont't overwrite the ``init`` method if not neccesary, use ``setup`` instead. +hook on and off. Don't overwrite the ``init`` method if not necessary, use ``setup`` instead. Using the Config ---------------- @@ -41,16 +41,16 @@ When everything went right you can access the config values with ``self.getConfi Interacting on Events --------------------- -The next step is to think about where your Hook action takes places. +The next step is to think about where your Hook action takes place. The easiest way is to overwrite specific methods defined by the :class:`Hook <module.plugins.Hook.Hook>` base class. The name is indicating when the function gets called. See :class:`Hook <module.plugins.Hook.Hook>` page for a complete listing. -You should be aware of the arguments the Hooks are called with, whether its a :class:`PyFile <module.PyFile.PyFile>` -or :class:`PyPackage <module.PyPackage.PyPackage>` you should read its related documentation to know how to access her great power and manipulate them. +You should be aware of the arguments the hooks are called with, whether its a :class:`PyFile <module.PyFile.PyFile>` +or :class:`PyPackage <module.PyPackage.PyPackage>` you should read the relevant documentation to know how to access it's great power and manipulate them. -A basic excerpt would look like: :: +What a basic excerpt would look like: :: from module.plugins.Hook import Hook @@ -66,13 +66,13 @@ A basic excerpt would look like: :: print "A Download just finished." Another important feature to mention can be seen at the ``__threaded__`` parameter. Function names listed will be executed -in a thread, in order to not block the main thread. This should be used for all kind of longer processing tasks. +in a thread, in order to not block the main thread. This should be used for all kinds of long lived processing tasks. -Another and more flexible and powerful way is to use event listener. +Another and more flexible and powerful way is to use the event listener. All hook methods exists as event and very useful additional events are dispatched by the core. For a little overview look -at :class:`HookManager <module.HookManager.HookManager>`. Keep in mind that you can define own events and other people may listen on them. +at :class:`HookManager <module.HookManager.HookManager>`. Keep in mind that you can define your own events and other people may listen on them. -For your convenience it's possible to register listeners automatical via the ``event_map`` attribute. +For your convenience it's possible to register listeners automatically via the ``event_map`` attribute. It requires a `dict` that maps event names to function names or a `list` of function names. It's important that all names are strings :: from module.plugins.Hook import Hook @@ -99,14 +99,15 @@ Use `self.manager.addEvent("name", function)`, `self.manager.removeEvent("name", :class:`HookManager <module.HookManager.HookManager>`. Contrary to ``event_map``, ``function`` has to be a reference and **not** a `string`. -We introduced events because it scales better if there a a huge amount of events and hooks. So all future interaction will be exclusive +We introduced events because it scales better if there is a huge amount of events and hooks. So all future interactions will be exclusively available as event and not accessible through overwriting hook methods. However you can safely do this, it will not be removed and is easier to implement. -Providing RPC services +Providing + RPC services ---------------------- -You may noticed that pyLoad has an :class:`Api <module.Api.Api>`, which can be used internal or called by clients via RPC. +You may have noticed that pyLoad has an :class:`Api <module.Api.Api>`, which can be used internal or called by clients via RPC. So probably clients want to be able to interact with your hook to request it's state or invoke some action. Sounds complicated but is very easy to do. Just use the ``Expose`` decorator: :: 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 <module.plugins.Base.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 <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. +An overview of acceptable values can be found in :class:`Base <module.plugins.Base.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 <module.plugins.Crypter.Crypter>` and :class:`Crypter <module.plugins.Hoster.Hoster>` -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 <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 +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 <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. +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 diff --git a/docs/plugins/crypter_plugin.rst b/docs/plugins/crypter_plugin.rst index 4e7803808..8c54dccb1 100644 --- a/docs/plugins/crypter_plugin.rst +++ b/docs/plugins/crypter_plugin.rst @@ -4,7 +4,7 @@ Crypter - Extract links from pages ================================== We are starting with the simplest plugin, the :class:`Crypter <module.plugins.Crypter.Crypter>`. -It's job is it to take a url as input and generate new package or links, for example by filtering the urls or +It's job is to take an url as input and generate a new package or links, for example by filtering the urls or loading a page and extracting links from the html code. You need to define the ``__pattern__`` to match target urls and subclass from :class:`Crypter <module.plugins.Crypter.Crypter>`. :: @@ -36,11 +36,11 @@ create new Packages if needed by instantiating a :class:`Package` instance, whic html = self.load(url) - # .decrypt_from_content is only a example method here and will return a list of urls + # .decrypt_from_content is only an example method here and will return a list of urls urls = self.decrypt_from_content(html) return Package("my new package", urls) -And that's basically all you need to know. Just as little side-note if you want to use decrypter in +And that's basically all you need to know. Just as a little side-note if you want to use decrypter in your code you can use:: plugin = self.core.pluginManager.loadClass("crypter", "NameOfThePlugin") @@ -53,7 +53,7 @@ SimpleCrypter ------------- For simple crypter services there is the :class:`SimpleCrypter <module.plugins.internal.SimpleCrypter.SimpleCrypter>` class which handles most of the workflow. Only the regexp -pattern have to be defined. +pattern has to be defined. Exmaple:: diff --git a/docs/plugins/hoster_plugin.rst b/docs/plugins/hoster_plugin.rst index ee112b570..b7546a313 100644 --- a/docs/plugins/hoster_plugin.rst +++ b/docs/plugins/hoster_plugin.rst @@ -24,13 +24,13 @@ An example ``process`` function could look like this :: # download the file, destination is determined by pyLoad self.download(parsed_url) -You need to know about the :class:`PyFile <module.PyFile.PyFile>` class, since an instance of it is given as parameter to every pyfile. -Some tasks your plugin should handle: proof if file is online, get filename, wait if needed, download the file, etc.. +You need to know about the :class:`PyFile <module.PyFile.PyFile>` class, since an instance of it is given as a parameter to every pyfile. +Some tasks your plugin should handle: check if the 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 +Some hosters 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 @@ -54,4 +54,4 @@ Testing Examples -------- -Best examples are already existing plugins in :file:`module/plugins/`.
\ No newline at end of file +The best examples are the already existing plugins in :file:`module/plugins/`.
\ No newline at end of file diff --git a/docs/plugins/overview.rst b/docs/plugins/overview.rst index 70db5ac90..b3debb053 100755 --- a/docs/plugins/overview.rst +++ b/docs/plugins/overview.rst @@ -12,10 +12,10 @@ Extending pyLoad .. rubric:: Motivation -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 :doc:`Base <base_plugin>` part, since it contains basic functionality for all plugins types. -A class diagram visualizing the relationship can be find below [1]_ +pyLoad offers a comfortable and powerful plugin system to make extensions 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 overview about the +conceptual part. You should not leave out the :doc:`Base <base_plugin>` part, since it contains basic functionality for all plugin types. +A class diagram visualizing the relationship can be found below [1]_ .. rubric:: Contents |