diff options
| -rw-r--r-- | docs/api/json_api.rst | 36 | ||||
| -rw-r--r-- | docs/api/overview.rst | 2 | ||||
| -rw-r--r-- | docs/api/thrift_api.rst | 6 | ||||
| -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 |
8 files changed, 69 insertions, 68 deletions
diff --git a/docs/api/json_api.rst b/docs/api/json_api.rst index 3df006c49..6d55b13b4 100644 --- a/docs/api/json_api.rst +++ b/docs/api/json_api.rst @@ -4,35 +4,35 @@ JSON API ======== -JSON [1]_ is a lightweight object notation and wrapper exists for nearly every programming language. Every +JSON [1]_ is a lightweight object notation and wrappers exist for nearly every programming language. Every modern browser is able to load JSON objects with JavaScript. Unlike to thrift you don't need to generate or precompile -any stub methods, the JSON :class:`Api <module.Api.Api>` is ready to use for most language. The libary is really lightweight (at least in python) -and you can build very lightweight scripts with it. Because of the builtin support JSON is the first choice for all browser +any stub methods, the JSON :class:`Api <module.Api.Api>` is ready to be used in most languages. The library is really lightweight (at least in python) +and you can build very lightweight scripts with it. Because of the builtin support, JSON is the first choice for all browser applications. In our case JSON is just the output format, you have exactly the same methods available as with the thrift backend. The only -difference is the used protocol. +difference is the underlying protocol. -So are there still reasons to choose the original :doc:`thrift <thrift_api>` backend in favor to JSON? Yes, since it +Are there still reasons to choose the original :doc:`thrift <thrift_api>` backend in favor to JSON? Yes, since it uses a binary protocol the performance will be better (when generating the objects), traffic will be smaller and therefore the transfer faster. In most IDEs you will get code completion, because of the pre-generated classes, which can make work much easier. If you intend to write a full client you should prefer thrift if the language is supported, for lightweight scripts and -in browser environment JSON wil be the better choice. +in browser environments JSON will be the better choice. Login ----- -First you need to authenticate, if you using this within the webinterface and the user is logged the API is also accessible, +First you need to authenticate, if you are using this within the web interface and the user is logged in, the API is also accessible, since they share the same cookie/session. -However, if you are building a external client and want to authenticate manually +However, if you are building an external client and want to authenticate manually you have to send your credentials ``username`` and ``password`` as POST parameter to ``http://pyload-core/api/login``. The result will be your session id. If you are using cookies, it will be set and you can use the API now. -In case you dont't have cookies enabled you can pass the session id as ``session`` POST parameter +In case you don't have cookies enabled you can pass the session id as ``session`` POST parameter so pyLoad can authenticate you. @@ -40,19 +40,19 @@ Calling Methods --------------- In general you can use any method listed at the :class:`Api <module.Api.Api>` documentation, which is also available to -the thriftbackend. +the thrift backend. Access works simply via ``http://pyload-core/api/methodName``, where ``pyload-core`` is the ip address -or hostname including the webinterface port. By default on local access this would be `localhost:8000`. +or hostname including the web interface port. By default on local access this would be `localhost:8000`. -The return value will be formatted in JSON, complex data types as dictionaries. Definition for datatypes can be found +The return value will be formatted in JSON, complex data types as dictionaries. Definition for data types can be found :doc:`here <datatypes>` Passing parameters ------------------ -To pass arguments you have two choices. -Either use positional arguments, eg ``http://pyload-core/api/getFileData/1``, where 1 is the FileID, or use keyword +To pass arguments you have two choices: +Either use positional arguments, e.g.: ``http://pyload-core/api/getFileData/1``, where 1 is the FileID, or use keyword arguments supplied via GET or POST ``http://pyload-core/api/getFileData?fid=1``. You can find the argument names in the :class:`Api <module.Api.Api>` documentation. @@ -60,11 +60,11 @@ It is important that *all* arguments are in JSON format. So ``http://pyload-core 1 represents an integer in json format. On the other hand if the method is expecting strings, this would be correct: ``http://pyload-core/api/getUserData/"username"/"password"``. -Strings are wrapped in double qoutes, because `"username"` represents a string in json format. It's not limited to -strings and intergers, every container type like lists and dicts are possible. You usually don't have to convert them. -Just use a json encoder before using them in the HTTP request. +Strings are wrapped in double qoutes, because `"username"` represents a string in JSON format. It's not limited to +strings and integers, every container type like lists and dicts are possible. You usually don't have to convert them. +Just use a JSON encoder before using them in the HTTP request. -Please note that the data have to be urlencoded at last. (Most libaries will do that automatically) +Please note that the data has to be urlencoded at last. (Most libraries will do that automatically) .. rubric:: Footnotes diff --git a/docs/api/overview.rst b/docs/api/overview.rst index 47fe1be82..37aa8a526 100644 --- a/docs/api/overview.rst +++ b/docs/api/overview.rst @@ -16,7 +16,7 @@ The idea of the centralized pyLoad :class:`Api <module.Api.Api>` is to give unif and plugins in pyLoad, and furthermore to other clients, written in arbitrary programming languages. Most of the :class:`Api <module.Api.Api>` functionality is exposed via RPC [2]_ and accessible via thrift [3]_ or simple JSON objects [4]_. In conclusion the :class:`Api <module.Api.Api>` is accessible via many programming language, -over network from remote maschines and over browser with javascript. +over network from remote machines and over browser with javascript. .. rubric:: Contents diff --git a/docs/api/thrift_api.rst b/docs/api/thrift_api.rst index a4987a797..cd1d2f23c 100644 --- a/docs/api/thrift_api.rst +++ b/docs/api/thrift_api.rst @@ -5,8 +5,8 @@ Thrift API ========== Thrift [1]_ was first developed in-house at facebook, but later published to public domain and developed at Apache Incubator. -It includes a binary protocol for remote calls, which is much more performant than other data formats like XML, additionally -it is available for numerous languages and therefore we choosed it as primary backend for our API. +It includes a binary protocol for remote calls, which has a much better performance than other data formats like XML, additionally +it is available for numerous languages and therefore we choose it as primary backend for our API. First of all, you need to know what you can do with our API. It lets you do all common task like retrieving download status, manage queue, manage accounts, modify config and so on. @@ -15,7 +15,7 @@ This document is not intended to explain every function in detail, for a complet see :class:`Api <module.Api.Api>`. Of course its possible to access the ``core.api`` attribute in plugins and hooks, but much more -interesting is the possibillity to call function from different programs written in many different languages. +interesting is the possibility to call function from different programs written in many different languages. pyLoad uses thrift as backend and provides its :class:`Api <module.Api.Api>` as service. More information about thrift can be found in their wiki [2]_. 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 |