diff options
Diffstat (limited to 'docs/write_plugins.rst')
| -rw-r--r--[-rwxr-xr-x] | docs/write_plugins.rst | 133 |
1 files changed, 72 insertions, 61 deletions
diff --git a/docs/write_plugins.rst b/docs/write_plugins.rst index 0c581cdab..b513a5978 100755..100644 --- a/docs/write_plugins.rst +++ b/docs/write_plugins.rst @@ -1,92 +1,103 @@ -.. _write_plugins: +.. _write_plugins: -******************** -How to extend pyLoad -******************** - -This page should give you an basic idea, how to extend pyLoad with new features! - -Hooks ------ - -A Hook is a module which is located at :file:`module/plugin/hooks` and loaded with the startup. It inherits all methods from the base :class:`Hook <module.plugins.Hook.Hook>` module, make sure to check its documentation! - -All Hooks should start with something like this: :: - - from module.plugins.Hook import Hook - - class YourHook(Hook): - __name__ = "My own Hook" - __version__ = "0.1" - __description__ = "Does really cool stuff" - __config__ = [ ("activated" , "bool" , "Activated" , "True" ) ] - __threaded__ = ["downloadFinished"] - __author_name__ = ("Me") - __author_mail__ = ("me@has-no-mail.com") - - def setup(self): - #init hook and other stuff here - pass - -Take a closer look at the ``__config__`` parameter. You need at least this option indicating whether your Hook is activated or not. -You can add more config values as desired by adding tuples of the following format to the config list: ``("name", "type", "description", "default value")``. -When everything went right you can access your config values with ``self.getConfig(name)``. - -The next step is to think about where your Hook action takes places. -You can overwrite several methods of the base plugin, her name indicates when they 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.FileDatabase.PyFile>` or :class:`PyPackage <module.FileDatabase.PyPackage>` you should read its related documentation to know how to access her great power and manipulate them. - -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. - - Plugins -------- +======= -A Plugin in pyLoad sense is a module, that will be loaded and executed when its pattern match to a url that was been added to pyLoad. +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 ;-) +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 ;-) -We take a look how basis hoster plugin header could look like: :: +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): __name__ = "MyFileHoster" __version__ = "0.1" __pattern__ = r"http://myfilehoster.example.com/file_id/[0-9]+" __config__ = [] -Thats it, like above with :ref:`Hooks` you can add config values exatly the same way. +You have to define these meta-data, ``__pattern__`` has to be a regexp that sucessfully compiles with +``re.compile(__pattern__)``. -The ``__pattern__`` property is very important, it will be checked against every added url and if it matches your plugin will be choosed to do the grateful task of processing this download! In case you dont already spotted it, ``__pattern__`` has to be a regexp of course. +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 :: +An example ``process`` function could look like this :: - def process(self, pyfile): - html = self.load(pyfile.url) #load the content of the orginal pyfile.url to html + from module.plugin.Hoster import Hoster - pyfile.name = self.myFunctionToParseTheName(html) #parse the name from the site and write it to pyfile + class MyFileHoster(Hoster): + """ + plugin code + """ + + def process(self, pyfile): + html = self.load(pyfile.url) # load the content of the orginal pyfile.url to html + + # parse the name from the site and set attribute in pyfile + pyfile.name = self.myFunctionToParseTheName(html) parsed_url = self.myFunctionToParseUrl(html) - self.download(parsed_url) # download the file + # download the file, destination is determined by pyLoad + self.download(parsed_url) -You need to know about the :class:`PyFile <module.FileDatabase.PyFile>` class, since a instance of it is given as parameter to every pyfile. +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.. -There are also some functions to mention which are provided by the base Plugin: ``self.wait()``, ``self.decryptCaptcha()`` -Read about there functionality in the :class:`Plugin <module.plugins.Plugin.Plugin>` doc. +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`` -Example: :: +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. - def decrypt(self, pyfile): - self.packages.append((name, urls, folder)) # urls list of urls +Examples +-------- -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. +Best examples are already existing plugins in :file:`module/plugins/`.
\ No newline at end of file |