-
Notifications
You must be signed in to change notification settings - Fork 17
addons
Add-ons (or actions as todo.sh calls them) allow for developers and users to overwrite or add new commands to todo.py.
In version 0.3 which has no set date for release. It will be ready when it is ready. If you want to test add-ons, they exist in the development branch. Note: This branch is usually stable, but at times may not be stable. Only use this if you really want to start developing add-ons for others. (2012-05-23)
There is a proposal to support todo.sh's add-ons as well as those written in python. While it's open for comment, please contribute to the discussion.
There are two types of add-ons you can use with todo.py. The first are the
bash add-ons written for the original todo.sh project. There is a list of
available add-ons on that project's wiki. The second are add-ons written
specific to todo.py in python.
You can follow Gina Trapani's directions on how to install a todo.sh add-on.
Please be certain to set the TODO_ACTIONS_DIR variable in your
$TODO_DIR/config file if you will be using a directory other than
$TODO_DIR/actions/.
After downloading the add-on(s) you wish to use, place them in
$TODO_DIR/actions/, where $TODO_DIR is the directory you specified in
your config file to hold the todo related files. If you never specified such a
directory, the default (on linux) is /home/user/.todo/ so place the
actions directory inside of that directory and the add-on files inside of
that.
Edit your config file ($TODO_DIR/config) to include the line:
ACTIONS="list,of,file,names"
Where the file names exclude the .py extension, e.g. if you were to use the
mstave.py from sample_addons/, you would write:
ACTIONS="mstave"
After doing this, you can run todo.py help (or whatever you have it aliased
to) to see the commands and their description. Then just run those commands like
you would any other command.
-
mstave.pyis available in thesample_addonsdirectory at the moment.
Anyone with some knowledge of python should be able to develop their own custom actions for use with todo.py. The functionality for add-ons (a.k.a actions) can examined here. Sample addons are available in the repository.
Generally you can structure your add-on however you please. However, every
add-on requires one dictionary of commands and their associated functions. For
example, in mstave.py, there are three new commands, two of which have
aliases.
If you look at the function referenced above which does the loading of the add-ons, you can see that if no instance is found, it will print an error.
Please, follow PEPs 8, 20 and 257. For PEP-8 compliance, be sure to use this script_. You can use whatever new data structures you may like. Define classes, etc., whatever works for you is fine. I may even do an object-oriented version of this script just for laughs sometime soon.
Your add-on should not be included somewhere in sample_addons/. It should
preferably have its own repository or gist. When you want your add-on included
on this page, open an issue and be sure to use the Add-on submission label.
Your issue should follow these guidelines:
- The title should be the name of your add-on (whatever you so choose).
- You should follow this template: [1]
# Important information :Author: (Your name, not necessarily your real name) :Email: (optional) :Version: :License: (If any, it must be compatible with the GPL) :Copyright: (c) YYYY by (Author) :Python versions: (Which versions have you tested this on) :Dependencies: (List of modules your add-on depends on, optional) :Repository/Gist: (link-to-repository) ## Description Describe what the add-on does. Do not be technical and do not simply include the usage lines for help. ## Technical Details Why do you need those dependencies? etc.
- Your code should be well documented (comments, doc-strings, etc)
- Name your files in such a way as to avoid conflicts with other add-ons whilst not causing the user to have to type too much when adding it to their config file.
Note: If your add-on does not run on the specified versions, it will not be included until you fix the discrepancy.
| [1] | Put the escape quotes for syntax highlighting around the paragraph in the "Important Information" section and use ascii syntax highlighting. The wiki will not allow me to use this in the template above. |
Once your add-on is accepted for inclusion on this page, I (or someone else) will close the issue and in the comment include a reference to the commit in which the changes were added. If you would like, you may submit a reStructuredText formatted file for inclusion in this wiki. It should follow the rough format of the above issue description. A cheatsheet for reST is available on GitHub. Any updates to the wiki file should be made as comments on the original issue. A possible template for the wiki follows.
:Author: :Email: :Version: :License: :Copyright: :Python versions: :Dependencies: :Repository/Gist: :Original Submission: (link to original issue) Description ----------- Description of what your add-on does. You should include what you had in the original issue. Technical Details ----------------- Why do you require those dependencies? etc. Tips and Tricks --------------- What fun/cool things can you do with these commands (if anything)? Other sections you wish to include ---------------------------------- Spam
Just be aware that wiki updates may not be immediate. Including a link to the original submission then allows for others to check for updated wikis etc.