From 25fb5b9a026263831d7deffc33d6b6a2dadb6fa4 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 20 Jan 2010 23:41:05 -0200 Subject: [PATCH] Documented most of the stuff, but still need to make the Twitter (and others) appear in the index --- HACKING | 2 +- README | 73 +++++++++++++++++--------------- docs/docs.rst | 4 -- docs/index.rst | 2 + mitterlib/network/__init__.py | 19 ++++++++- mitterlib/network/networkbase.py | 23 ++++++---- mitterlib/network/twitter.py | 33 +++++++++++++++ mitterlib/ui/ui_pygtk.py | 48 +++++++++++++++++---- 8 files changed, 146 insertions(+), 58 deletions(-) delete mode 100644 docs/docs.rst diff --git a/HACKING b/HACKING index 089358e..f6b0ea7 100644 --- a/HACKING +++ b/HACKING @@ -3,7 +3,7 @@ Mitter Hacking Guidelines ========================= First of all, Mitter is a Python project and it tries to follow PEP8_ -as close as possible. Sometimes, we fail, but we try to adhere to it +as close as possible. Sometimes we fail, but we try to adhere to it as much as possible. The Google Guidelines_ for Python are a good summary about it, although we don't follow all their recommendations: diff --git a/README b/README index 81b3422..33ddc54 100644 --- a/README +++ b/README @@ -9,19 +9,20 @@ networks. Options ======= -To get a list of options Mitter support, you can call it with -``mitter --help``. Along with the default options, you'll get options -for each interface and network. +To get a list of options Mitter support, you can call it with ``mitter +--help``. Along with the default options, you'll get options for each +interface and network. Config file ----------- -Mitter saves its options in a config file in your home directory, -called ``.mitter.ini``. Some options, not displayed in the command -line options, are available there. Be careful when changing those -options or Mitter may stop working. +Mitter saves its options in a config file in your home directory, called +``.mitter.ini``. Some options, not displayed in the command line options, are +available there. Be careful when changing those options or Mitter may stop +working. Documentation about those options is available in the beginning of +the module and should be available with the generated documentation. -In any case, if things don't seem to be working, you can remove this -file and Mitter will ask the necessary options to work again. +In any case, if things don't seem to be working, you can remove this file and +Mitter will ask the necessary options to work again. Networks ======== @@ -29,50 +30,52 @@ As for version 1.0, Mitter supports Twitter. Interfaces ========== -As for version 1.0, Mitter have the following interfaces: PyGTK, TTY, -Cmd, Zork. +As for version 1.0, Mitter have the following interfaces: PyGTK, TTY, Cmd, +Zork. Choosing Interfaces ------------------- -If you want to chose a specific interface, you can use the ``-i`` -option, followed by the interface name. +If you want to chose a specific interface, you can use the ``-i`` option, +followed by the interface name. Once you have chose an interface, Mitter will +keep opening it every time it runs. To change to another interface, use the +``-i`` option again. PyGTK ----- -PyGTK is a graphical interface, which uses the GTK toolkit. To be -used, it requires that PyGTK is installed in your system. If you don't -have PyGTK, Mitter will switch to another interface that doesn't -require it. +PyGTK is a graphical interface, which uses the GTK toolkit. To be used, it +requires that the PyGTK module is installed in your system. If you don't have +PyGTK, Mitter will switch to another interface that doesn't require it. TTY --- -TTY is a text interface, used to display the updates. It does not -offer any interactivity. You can use it to do automated updates -without user intervention or to simply retrieve the current messages. +TTY is a text interface, used to display the updates. It does not offer any +interactivity. You can use it to do automated updates without user +intervention or to simply retrieve the current messages. Cmd --- -CMD is a text interface, with a command line. It offers some smart -behaviour, like retrieving new messages when there is no option and -starting an update when the command is not recognized. +CMD is a text interface, with a command line. It will display the messages in +a numbered list and most of options related to those messages will require the +message number. It also have some smart behaviour, like retrieving new +messages when there is no option and starting an update when the command is +not recognized. Zork ---- -Zork is another text interface, but works a little bit slowly than the -Cmd interface. Instead of displaying all the messages at once, Zork -displays message by message, requiring the user to jump to the next -message. It offers a fine-grained control to which message to reply, -at the expense of few commands. +Zork is another text interface, but works a little bit slowly than the Cmd +interface. Instead of displaying all the messages at once and requiring that +you select message by their numbers, Zork displays message by message, +requiring the user to jump to the next message. It offers a fine-grained +control to which message to reply, at the expense of few commands. How Mitter Finds Interfaces --------------------------- -Mitter uses Python default module loading to find interfaces. This -means: It will search modules starting with the current directory, -then the global system path. When installed via ``setup.py`` or -``easy_install``, interfaces will be installed in the global system -directory; if you don't want to install Mitter, you can run it in the -command line, just be sure to be in the main ``mitter`` directory -before call it. +Mitter uses Python default module loading to find interfaces. It works like +this: It will search modules starting with the current directory, then the +global system path. When installed via ``setup.py`` or ``easy_install``, +interfaces will be installed in the global system directory; if you don't want +to install Mitter, you can run it in the command line, just be sure to be in +the main ``mitter`` directory before call it. Suggestions? Bugs? ================== diff --git a/docs/docs.rst b/docs/docs.rst deleted file mode 100644 index 49c58b5..0000000 --- a/docs/docs.rst +++ /dev/null @@ -1,4 +0,0 @@ -Documentation -============= - - HACKING diff --git a/docs/index.rst b/docs/index.rst index 31f1ad4..3092d8e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,8 @@ User Documentation INSTALL HACKING + twitter + Developer Documentation: diff --git a/mitterlib/network/__init__.py b/mitterlib/network/__init__.py index 0b81f2a..785a3d1 100644 --- a/mitterlib/network/__init__.py +++ b/mitterlib/network/__init__.py @@ -28,6 +28,24 @@ _log = logging.getLogger('mitterlib.network.Networks') # List of files that are not networks SKIPPABLES = ('__init__.py', 'networkbase.py') +"""The network manager, besides managing the other networks and their options, +have the following options: + +*timeout* + Timeout for requests, in seconds. This value is (or should) be used to all + networks. Default value is '120'. + +*save_count* + Number of operations till the configuration file is saved again. Most + networks will save their status in the config file, but not request it to be + saved immediately (nor should they, 'cause they can save a weird state in + case the next network causes Mitter to crash or something related.) A value + of 0 means the Network Manager will save the config file after each round of + requests to all networks (failing or succeding); for devices that use flash + drives as storage, it's recommended some large value (since those devices + have a defined number of writes as lifetime.) Default is '5'. +""" + #-------------------------------------------------------------------- # Helper functions #-------------------------------------------------------------------- @@ -144,7 +162,6 @@ class Networks(object): return result def options(self): - """Request all networks to add their options.""" for shortcut in self.networks: conn = self.networks[shortcut] conn.options(self._options) diff --git a/mitterlib/network/networkbase.py b/mitterlib/network/networkbase.py index bc7baee..de15437 100644 --- a/mitterlib/network/networkbase.py +++ b/mitterlib/network/networkbase.py @@ -184,25 +184,32 @@ class NetworkBase(object): retrieve information from the network. It's a list of dictionaries, containing: - * *name*: Name of the option, used in ConfigOpt (for the name in the + *name* + Name of the option, used in ConfigOpt (for the name in the config file and to access it through the options variable); - * *flags*: The list of command line options for this option (as in + *flags* + The list of command line options for this option (as in OptParse); - * *prompt*: The prompt to be used by interfaces when requesting the + *prompt* + The prompt to be used by interfaces when requesting the variable; - * *help*: Description for the value; it's used by ConfigOpt to show the + *help* + Description for the value; it's used by ConfigOpt to show the description of the paramater in the command line options and can be used by interfaces to show tooltips about the field; - * *type*: The type of the option; valid values are: + *type* + The type of the option; valid values are: - * 'str': A string; + **str** + A string; - * 'passwd': Password; string, but interfaces should hide the information - if possible. + **passwd** + Password; string, but interfaces should hide the information + if possible. """ def is_setup(self): diff --git a/mitterlib/network/twitter.py b/mitterlib/network/twitter.py index 55a4022..a88dad2 100644 --- a/mitterlib/network/twitter.py +++ b/mitterlib/network/twitter.py @@ -43,6 +43,39 @@ except ImportError: # Fallback to SimpleJSON import simplejson as json +""" +The Twitter network layer have the following options: + +*last_tweet* + Last tweet seen in the home timeline request. It's used to not request the + whole timeline again. Usually, it should not be manually changed. Starts + with no value, meaning it will request only the first page; after that, it + will requests all tweets, no matter how many pages it is necessary, since + the last seen tweet. + +*last_reply* + Last reply seen in the replies timeline. Works exactly the same as + *last_tweet*, but with replies timeline. + +*server_url* + URL for the non-secure server. Can include any paths. Default value is + 'http://api.twitter.com/1'. + +*secure_server_url* + URL for the secure server. Can include any paths. Default value is + 'https://api.twitter.com/1'. + +*threshold* + Threshold for not requesting the next page. If the number of returned + elements is below this number, the module will not request the next page. + This is due the way Twitter uses its cache: In a normal operation, any page + that have less than the default 20 elements per page can be considered the + last page; due the caching policy Twitter uses, some pages will have less + than those 20 elements (it first retrieves the 20 elements, then checks if + there are any deleted elements -- if there are, those are removed but no new + elements are added to the result.) Default value is '16' (80% of a full + page.) +""" # ---------------------------------------------------------------------- # I18n bits # ---------------------------------------------------------------------- diff --git a/mitterlib/ui/ui_pygtk.py b/mitterlib/ui/ui_pygtk.py index 72ad22c..3a63d47 100644 --- a/mitterlib/ui/ui_pygtk.py +++ b/mitterlib/ui/ui_pygtk.py @@ -36,6 +36,35 @@ from mitterlib.ui.helpers.image_helpers import find_image from mitterlib.constants import gpl_3, version from mitterlib.ui.helpers import timesince +""" +PyGTK interface internal options: + +*width* + Width of the main window, in pixels. Default value is '450', but this value + is saved when Mitter is closed and reloaded when it's run again. + +*height* + Height of the main window, in pixels. Default value is '300' but it is saved + when Mitter is closed and reloaded when it's run again. + +*position_x* + X position of the main window. Default value is '5' but it is saved when + Mitter is closed and reloaded when it's run again. + +*position_y* + Y position of the main window. Default value is '5' but it is saved when + Mitter is closed and reloaded when it's run again. + +*link_colour* + Colour for displaying links. Default value is 'blue'. You can use valid X11 + colour names or hex-triplets (as used in HTML, e.g., #0000ff. -- you need to + include the hash in those cases.) + +*spell_check* + Boolean indicating if spell checker is enabled. Mitter will try to activate + it the first time it's run, but it requires Aspell and its Python bindings. +""" + # Constants _log = logging.getLogger('ui.pygtk') @@ -1482,15 +1511,16 @@ class Interface(object): default=5, conflict_group='interface', is_cmd_option=False) - options.add_option( - group=self.NAMESPACE, - option='max_status_display', - help='Maximum number of elements to keep internally', - type='int', - metavar='MESSAGES', - default=60, - conflict_group='interface', - is_cmd_option=False) # TODO: Should it be config only? + # TODO: Should we use this, anyway? + #options.add_option( + # group=self.NAMESPACE, + # option='max_status_display', + # help='Maximum number of elements to keep internally', + # type='int', + # metavar='MESSAGES', + # default=60, + # conflict_group='interface', + # is_cmd_option=False) # TODO: Should it be config only? options.add_option( group=self.NAMESPACE, option='link_colour',