diff options
43 files changed, 189 insertions, 298 deletions
diff --git a/ranger/__init__.py b/ranger/__init__.py index 8dbd7fc6..da6b234c 100644 --- a/ranger/__init__.py +++ b/ranger/__init__.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -A console file manager with VI key bindings. +"""A console file manager with VI key bindings. It provides a minimalistic and nice curses interface with a view on the directory hierarchy. The secondary task of ranger is to figure out which @@ -37,8 +36,7 @@ CONFDIR = '~/.config/ranger' # Example usage in the code: # import ranger; ranger.log("hello world") def log(*objects, **keywords): - """ - Writes objects to a logfile (for the purpose of debugging only.) + """Writes objects to a logfile (for the purpose of debugging only.) Has the same arguments as print() in python3. """ from ranger import arg diff --git a/ranger/api/__init__.py b/ranger/api/__init__.py index 9fbf2418..a50f706f 100644 --- a/ranger/api/__init__.py +++ b/ranger/api/__init__.py @@ -1,11 +1,10 @@ -""" -Files in this module contain helper functions used in configuration files. -""" +"""Files in this module contain helper functions used in configuration files.""" # Hooks for use in plugins: def hook_init(fm): - """ + """A hook that is called when ranger starts up. + Parameters: fm = the file manager instance Return Value: @@ -17,7 +16,8 @@ def hook_init(fm): """ def hook_ready(fm): - """ + """A hook that is called after the ranger UI is initialized. + Parameters: fm = the file manager instance Return Value: diff --git a/ranger/colorschemes/__init__.py b/ranger/colorschemes/__init__.py index a442d9c7..fb52df0e 100644 --- a/ranger/colorschemes/__init__.py +++ b/ranger/colorschemes/__init__.py @@ -1,3 +1 @@ -""" -Colorschemes are required to be located here or in CONFDIR/colorschemes/ -""" +"""Colorschemes are required to be located here or in CONFDIR/colorschemes/""" diff --git a/ranger/config/commands.py b/ranger/config/commands.py index ba1b6646..280c0cd8 100644 --- a/ranger/config/commands.py +++ b/ranger/config/commands.py @@ -79,8 +79,7 @@ from ranger.api.commands import * class alias(Command): - """ - :alias <newcommand> <oldcommand> + """:alias <newcommand> <oldcommand> Copies the oldcommand as newcommand. """ @@ -95,8 +94,7 @@ class alias(Command): self.fm.commands.alias(self.arg(1), self.rest(2)) class cd(Command): - """ - :cd [-r] <dirname> + """:cd [-r] <dirname> The cd command changes the directory. The command 'cd -' is equivalent to typing ``. @@ -172,8 +170,8 @@ class cd(Command): class chain(Command): - """ - :chain <command1>; <command2>; ... + """:chain <command1>; <command2>; ... + Calls multiple commands at once, separated by semicolons. """ def execute(self): @@ -247,8 +245,7 @@ class open_with(Command): return self._tab_through_executables() def _get_app_flags_mode(self, string): - """ - Extracts the application, flags and mode from a string. + """Extracts the application, flags and mode from a string. examples: "mplayer f 1" => ("mplayer", "f", 1) @@ -331,8 +328,7 @@ class open_with(Command): class find(Command): - """ - :find <string> + """:find <string> The find command will attempt to find a partial, case insensitive match in the filenames of the current directory and execute the @@ -386,8 +382,7 @@ class find(Command): class set_(Command): - """ - :set <option name>=<python expression> + """:set <option name>=<python expression> Gives an option a new value. """ @@ -415,8 +410,7 @@ class set_(Command): class setlocal(set_): - """ - :setlocal path=<python string> <option name>=<python expression> + """:setlocal path=<python string> <option name>=<python expression> Gives an option a new value. """ @@ -439,8 +433,7 @@ class setlocal(set_): class quit(Command): - """ - :quit + """:quit Closes the current tab. If there is only one tab, quit the program. """ @@ -452,8 +445,7 @@ class quit(Command): class quitall(Command): - """ - :quitall + """:quitall Quits the program immediately. """ @@ -463,8 +455,7 @@ class quitall(Command): class quit_bang(quitall): - """ - :quit! + """:quit! Quits the program immediately. """ @@ -473,8 +464,7 @@ class quit_bang(quitall): class terminal(Command): - """ - :terminal + """:terminal Spawns an "x-terminal-emulator" starting in the current directory. """ @@ -490,8 +480,7 @@ class terminal(Command): class delete(Command): - """ - :delete + """:delete Tries to delete the selection. @@ -536,8 +525,7 @@ class delete(Command): class mark(Command): - """ - :mark <regexp> + """:mark <regexp> Mark all files matching a regular expression. """ @@ -559,8 +547,7 @@ class mark(Command): class mark_tag(Command): - """ - :mark_tag [<tags>] + """:mark_tag [<tags>] Mark all tags that are tagged with either of the given tags. When leaving out the tag argument, all tagged files are marked. @@ -584,8 +571,7 @@ class mark_tag(Command): class console(Command): - """ - :console <command> + """:console <command> Open the console with the given command. """ @@ -601,8 +587,7 @@ class console(Command): class load_copy_buffer(Command): - """ - :load_copy_buffer + """:load_copy_buffer Load the copy buffer from confdir/copy_buffer """ @@ -623,8 +608,7 @@ class load_copy_buffer(Command): class save_copy_buffer(Command): - """ - :save_copy_buffer + """:save_copy_buffer Save the copy buffer to confdir/copy_buffer """ @@ -642,8 +626,7 @@ class save_copy_buffer(Command): class unmark(mark): - """ - :unmark <regexp> + """:unmark <regexp> Unmark all files matching a regular expression. """ @@ -651,8 +634,7 @@ class unmark(mark): class unmark_tag(mark_tag): - """ - :unmark_tag [<tags>] + """:unmark_tag [<tags>] Unmark all tags that are tagged with either of the given tags. When leaving out the tag argument, all tagged files are unmarked. @@ -661,8 +643,7 @@ class unmark_tag(mark_tag): class mkdir(Command): - """ - :mkdir <dirname> + """:mkdir <dirname> Creates a directory with the name <dirname>. """ @@ -682,8 +663,7 @@ class mkdir(Command): class touch(Command): - """ - :touch <fname> + """:touch <fname> Creates a file with the name <fname>. """ @@ -702,8 +682,7 @@ class touch(Command): class edit(Command): - """ - :edit <filename> + """:edit <filename> Opens the specified file in vim """ @@ -719,8 +698,7 @@ class edit(Command): class eval_(Command): - """ - :eval [-q] <python code> + """:eval [-q] <python code> Evaluates the python code. `fm' is a reference to the FM instance. @@ -760,8 +738,7 @@ class eval_(Command): class rename(Command): - """ - :rename <newname> + """:rename <newname> Changes the name of the currently highlighted file to <newname> """ @@ -791,8 +768,7 @@ class rename(Command): class chmod(Command): - """ - :chmod <octal number> + """:chmod <octal number> Sets the permissions of the selection to the octal number. @@ -831,8 +807,7 @@ class chmod(Command): class bulkrename(Command): - """ - :bulkrename + """:bulkrename This command opens a list of selected files in an external editor. After you edit and save the file, it will generate a shell script @@ -886,8 +861,7 @@ class bulkrename(Command): class relink(Command): - """ - :relink <newpath> + """:relink <newpath> Changes the linked path of the currently highlighted symlink to <newpath> """ @@ -925,8 +899,7 @@ class relink(Command): class help_(Command): - """ - :help + """:help Display ranger's manual page. """ @@ -943,8 +916,8 @@ class help_(Command): class copymap(Command): - """ - :copymap <keys> <newkeys1> [<newkeys2>...] + """:copymap <keys> <newkeys1> [<newkeys2>...] + Copies a "browser" keybinding from <keys> to <newkeys> """ context = 'browser' @@ -958,32 +931,32 @@ class copymap(Command): class copypmap(copymap): - """ - :copypmap <keys> <newkeys1> [<newkeys2>...] + """:copypmap <keys> <newkeys1> [<newkeys2>...] + Copies a "pager" keybinding from <keys> to <newkeys> """ context = 'pager' class copycmap(copymap): - """ - :copycmap <keys> <newkeys1> [<newkeys2>...] + """:copycmap <keys> <newkeys1> [<newkeys2>...] + Copies a "console" keybinding from <keys> to <newkeys> """ context = 'console' class copytmap(copymap): - """ - :copycmap <keys> <newkeys1> [<newkeys2>...] + """:copycmap <keys> <newkeys1> [<newkeys2>...] + Copies a "taskview" keybinding from <keys> to <newkeys> """ context = 'taskview' class unmap(Command): - """ - :unmap <keys> [<keys2>, ...] + """:unmap <keys> [<keys2>, ...] + Remove the given "browser" mappings """ context = 'browser' @@ -994,32 +967,32 @@ class unmap(Command): class cunmap(unmap): - """ - :cunmap <keys> [<keys2>, ...] + """:cunmap <keys> [<keys2>, ...] + Remove the given "console" mappings """ context = 'browser' class punmap(unmap): - """ - :punmap <keys> [<keys2>, ...] + """:punmap <keys> [<keys2>, ...] + Remove the given "pager" mappings """ context = 'pager' class tunmap(unmap): - """ - :tunmap <keys> [<keys2>, ...] + """:tunmap <keys> [<keys2>, ...] + Remove the given "taskview" mappings """ context = 'taskview' class map_(Command): - """ - :map <keysequence> <command> + """:map <keysequence> <command> + Maps a command to a keysequence in the "browser" context. Example: @@ -1036,6 +1009,7 @@ class map_(Command): class cmap(map_): """:cmap <keysequence> <command> + Maps a command to a keysequence in the "console" context. Example: @@ -1047,6 +1021,7 @@ class cmap(map_): class tmap(map_): """:tmap <keysequence> <command> + Maps a command to a keysequence in the "taskview" context. """ context = 'taskview' @@ -1054,14 +1029,14 @@ class tmap(map_): class pmap(map_): """:pmap <keysequence> <command> + Maps a command to a keysequence in the "pager" context. """ context = 'pager' class travel(Command): - """ - :travel <string> + """:travel <string> Filters the current directory for files containing the letters in the string, possibly with other letters in between. The filter is applied as @@ -1123,8 +1098,7 @@ class travel(Command): class filter(Command): - """ - :filter <string> + """:filter <string> Displays only the files which contain <string> in their basename. """ @@ -1137,8 +1111,7 @@ class filter(Command): class grep(Command): - """ - :grep <string> + """:grep <string> Looks for a string in all marked files or directories """ diff --git a/ranger/container/__init__.py b/ranger/container/__init__.py index 62ddc67a..ebd3a0da 100644 --- a/ranger/container/__init__.py +++ b/ranger/container/__init__.py @@ -1,4 +1 @@ -""" -This package includes container-objects which are -used to manage stored data -""" +"""This package includes container-objects for managing stored data""" diff --git a/ranger/container/bookmarks.py b/ranger/container/bookmarks.py index fa4679b6..8fcda0b1 100644 --- a/ranger/container/bookmarks.py +++ b/ranger/container/bookmarks.py @@ -9,21 +9,23 @@ ALLOWED_KEYS = string.ascii_letters + string.digits + "`'" class Bookmarks(object): """Bookmarks is a container which associates keys with bookmarks. - A key is a string with: len(key) == 1 and key in ALLOWED_KEYS. + A key is a string with: len(key) == 1 and key in ALLOWED_KEYS. - A bookmark is an object with: bookmark == bookmarktype(str(instance)) - Which is true for str or FileSystemObject. This condition is required - so bookmark-objects can be saved to and loaded from a file. + A bookmark is an object with: bookmark == bookmarktype(str(instance)) + Which is true for str or FileSystemObject. This condition is required + so bookmark-objects can be saved to and loaded from a file. - Optionally, a bookmark.go() method is used for entering a bookmark. - """ + Optionally, a bookmark.go() method is used for entering a bookmark. + """ last_mtime = None autosave = True load_pattern = re.compile(r"^[\d\w']:.") def __init__(self, bookmarkfile, bookmarktype=str, autosave=False): - """<bookmarkfile> specifies the path to the file where + """Initializes Bookmarks. + + <bookmarkfile> specifies the path to the file where bookmarks are saved in. """ self.autosave = autosave @@ -50,6 +52,7 @@ class Bookmarks(object): def enter(self, key): """Enter the bookmark with the given key. + Requires the bookmark instance to have a go() method. """ @@ -81,6 +84,7 @@ class Bookmarks(object): def __setitem__(self, key, value): """Bookmark <value> to the key <key>. + key is expected to be a 1-character string and element of ALLOWED_KEYS. value is expected to be a filesystemobject. """ @@ -96,6 +100,7 @@ class Bookmarks(object): def update(self): """Update the bookmarks from the bookmark file. + Useful if two instances are running which define different bookmarks. """ @@ -135,6 +140,7 @@ class Bookmarks(object): def save(self): """Save the bookmarks to the bookmarkfile. + This is done automatically after every modification if autosave is True.""" self.update() if self.path is None: diff --git a/ranger/core/actions.py b/ranger/core/actions.py index 6b75c691..56c71cdb 100644 --- a/ranger/core/actions.py +++ b/ranger/core/actions.py @@ -299,6 +299,7 @@ class Actions(FileManagerAware, EnvironmentAware, SettingsAware): def execute_file(self, files, **kw): """Execute a file. + app is the name of a method in Applications, without the "app_" flags is a string consisting of runner.ALLOWED_FLAGS mode is a positive integer. @@ -340,8 +341,7 @@ class Actions(FileManagerAware, EnvironmentAware, SettingsAware): # -------------------------- def move(self, narg=None, **kw): - """ - A universal movement method. + """A universal movement method. Accepts these parameters: (int) down, (int) up, (int) left, (int) right, (int) to, @@ -536,8 +536,7 @@ class Actions(FileManagerAware, EnvironmentAware, SettingsAware): pass def mark_files(self, all=False, toggle=False, val=None, movedown=None, narg=1): - """ - A wrapper for the directory.mark_xyz functions. + """A wrapper for the directory.mark_xyz functions. Arguments: all - change all files of the current directory at once? diff --git a/ranger/core/fm.py b/ranger/core/fm.py index a217be95..9493b5ae 100644 --- a/ranger/core/fm.py +++ b/ranger/core/fm.py @@ -1,9 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The File Manager, putting the pieces together -""" +"""The File Manager, putting the pieces together""" from time import time from collections import deque @@ -239,8 +237,9 @@ class FM(Actions, SignalDispatcher): self.signal_garbage_collect() def loop(self): - """ - The main loop consists of: + """The main loop of ranger. + + It consists of: 1. reloading bookmarks if outdated 2. letting the loader work 3. drawing and finalizing ui diff --git a/ranger/core/loader.py b/ranger/core/loader.py index efcc0983..73b3fb5a 100644 --- a/ranger/core/loader.py +++ b/ranger/core/loader.py @@ -112,8 +112,7 @@ class CopyLoader(Loadable, FileManagerAware): class CommandLoader(Loadable, SignalDispatcher, FileManagerAware): - """ - Run an external command with the loader. + """Run an external command with the loader. Output from stderr will be reported. Ensure that the process doesn't ever ask for input, otherwise the loader will be blocked until this @@ -268,8 +267,8 @@ class Loader(FileManagerAware): self.status = self.throbber_chars[self.throbber_status] def add(self, obj): - """ - Add an object to the queue. + """Add an object to the queue. + It should have a load_generator method. """ while obj in self.queue: @@ -317,9 +316,7 @@ class Loader(FileManagerAware): self.fm.ui.status.request_redraw() def pause(self, state): - """ - Change the pause-state to 1 (pause), 0 (no pause) or -1 (toggle) - """ + """Change the pause-state to 1 (pause), 0 (no pause) or -1 (toggle)""" if state == -1: state = not self.paused elif state == self.paused: @@ -336,8 +333,8 @@ class Loader(FileManagerAware): self.queue[0].unpause() def work(self): - """ - Load items from the queue if there are any. + """Load items from the queue if there are any. + Stop after approximately self.seconds_of_work_time. """ if self.paused: diff --git a/ranger/core/main.py b/ranger/core/main.py index dc35b47e..7ad71e96 100644 --- a/ranger/core/main.py +++ b/ranger/core/main.py @@ -1,9 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The main function responsible to initialize the FM object and stuff. -""" +"""The main function responsible to initialize the FM object and stuff.""" import os.path import sys diff --git a/ranger/core/runner.py b/ranger/core/runner.py index 0e4138d7..769c0911 100644 --- a/ranger/core/runner.py +++ b/ranger/core/runner.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -This module is an abstract layer over subprocess.Popen +"""This module is an abstract layer over subprocess.Popen It gives you highlevel control about how processes are run. @@ -47,8 +46,7 @@ def press_enter(): class Context(object): - """ - A context object contains data on how to run a process. + """A context object contains data on how to run a process. The attributes are: action -- a string with a command or a list of arguments for @@ -113,8 +111,7 @@ class Runner(object): def __call__(self, action=None, try_app_first=False, app='default', files=None, mode=0, flags='', wait=True, **popen_kws): - """ - Run the application in the way specified by the options. + """Run the application in the way specified by the options. Returns False if nothing can be done, None if there was an error, otherwise the process object returned by Popen(). diff --git a/ranger/core/shared.py b/ranger/core/shared.py index 22203e0f..30eb9038 100644 --- a/ranger/core/shared.py +++ b/ranger/core/shared.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -"""Shared objects contain singleton variables which can be -inherited, essentially acting like global variables.""" +"""Shared objects contain singletons for shared use.""" from ranger.ext.lazy_property import lazy_property import os.path diff --git a/ranger/core/tab.py b/ranger/core/tab.py index 212d58ef..da6913f6 100644 --- a/ranger/core/tab.py +++ b/ranger/core/tab.py @@ -49,8 +49,8 @@ class Tab(FileManagerAware, SettingsAware): thisfile = property(_get_thisfile, _set_thisfile) def at_level(self, level): - """ - Returns the FileSystemObject at the given level. + """Returns the FileSystemObject at the given level. + level >0 => previews level 0 => current file/directory level <0 => parent directories diff --git a/ranger/ext/curses_interrupt_handler.py b/ranger/ext/curses_interrupt_handler.py index 91bbc3e4..2d453f4a 100644 --- a/ranger/ext/curses_interrupt_handler.py +++ b/ranger/ext/curses_interrupt_handler.py @@ -1,7 +1,8 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" +"""Interrupt Signal handler for curses + This module can catch interrupt signals which would otherwise rise a KeyboardInterrupt exception and handle it by pushing a Ctrl+C (ASCII value 3) to the curses getch stack. diff --git a/ranger/ext/direction.py b/ranger/ext/direction.py index 371b417c..6630ca63 100644 --- a/ranger/ext/direction.py +++ b/ranger/ext/direction.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -Directions provide convenient methods for movement operations. +"""This class provides convenient methods for movement operations. Direction objects are handled just like dicts but provide methods like up() and down() which give you the correct value @@ -96,8 +95,7 @@ class Direction(dict): def move(self, direction, override=None, minimum=0, maximum=9999, current=0, pagesize=1, offset=0): - """ - Calculates the new position in a given boundary. + """Calculates the new position in a given boundary. Example: >>> d = Direction(pages=True) diff --git a/ranger/ext/get_executables.py b/ranger/ext/get_executables.py index f9e3c021..76b5140e 100644 --- a/ranger/ext/get_executables.py +++ b/ranger/ext/get_executables.py @@ -10,9 +10,7 @@ _cached_executables = None def get_executables(): - """ - Return all executable files in $PATH. Cached version. - """ + """Return all executable files in $PATH. Cached version.""" global _cached_executables if _cached_executables is None: _cached_executables = get_executables_uncached() @@ -20,8 +18,7 @@ def get_executables(): def get_executables_uncached(*paths): - """ - Return all executable files in each of the given directories. + """Return all executable files in each of the given directories. Looks in $PATH by default. """ diff --git a/ranger/ext/human_readable.py b/ranger/ext/human_readable.py index f1c5b1f6..96f8bda4 100644 --- a/ranger/ext/human_readable.py +++ b/ranger/ext/human_readable.py @@ -2,8 +2,7 @@ # This software is distributed under the terms of the GNU GPL version 3. def human_readable(byte, separator=' '): - """ - Convert a large number of bytes to an easily readable format. + """Convert a large number of bytes to an easily readable format. >>> human_readable(54) '54 B' diff --git a/ranger/ext/img_display.py b/ranger/ext/img_display.py index 9dcd276b..75501f48 100644 --- a/ranger/ext/img_display.py +++ b/ranger/ext/img_display.py @@ -1,6 +1,7 @@ # This software is distributed under the terms of the GNU GPL version 3. -""" +"""Interface for w3mimgdisplay to draw images into the console + This module provides functions to draw images in the terminal using w3mimgdisplay, an utilitary program from w3m (a text-based web browser). w3mimgdisplay can display images either in virtual tty (using linux @@ -19,10 +20,8 @@ class ImgDisplayUnsupportedException(Exception): pass def _get_font_dimensions(): - """ - Get the height and width of a character displayed in the terminal in - pixels. - """ + # Get the height and width of a character displayed in the terminal in + # pixels. s = struct.pack("HHHH", 0, 0, 0, 0) fd_stdout = sys.stdout.fileno() x = fcntl.ioctl(fd_stdout, termios.TIOCGWINSZ, s) @@ -32,9 +31,7 @@ def _get_font_dimensions(): def _w3mimgdisplay(commands): - """ - Invoke w3mimgdisplay and send commands on its standard input. - """ + """Invoke w3mimgdisplay and send commands on its standard input.""" process = Popen([W3MIMGDISPLAY_PATH] + W3MIMGDISPLAY_OPTIONS, stdin=PIPE, stdout=PIPE, universal_newlines=True) @@ -44,8 +41,7 @@ def _w3mimgdisplay(commands): return output def generate_w3m_input(path, start_x, start_y, max_width, max_height): - """ - Prepare the input string for w3mimgpreview + """Prepare the input string for w3mimgpreview start_x, start_y, max_height and max_width specify the drawing area. They are expressed in number of characters. @@ -83,8 +79,7 @@ def generate_w3m_input(path, start_x, start_y, max_width, max_height): filename = path) def draw(path, start_x, start_y, max_width, max_height): - """ - Draw an image file in the terminal. + """Draw an image file in the terminal. start_x, start_y, max_height and max_width specify the drawing area. They are expressed in number of characters. @@ -92,9 +87,7 @@ def draw(path, start_x, start_y, max_width, max_height): _w3mimgdisplay(generate_w3m_input(path, start_x, start_y, max_width, max_height)) def clear(start_x, start_y, width, height): - """ - Clear a part of terminal display. - """ + """Clear a part of terminal display.""" fontw, fonth = _get_font_dimensions() cmd = "6;{x};{y};{w};{h}\n4;\n3;".format( diff --git a/ranger/ext/iter_tools.py b/ranger/ext/iter_tools.py index f962a37d..eef943fd 100644 --- a/ranger/ext/iter_tools.py +++ b/ranger/ext/iter_tools.py @@ -4,8 +4,7 @@ from collections import deque def flatten(lst): - """ - Flatten an iterable. + """Flatten an iterable. All contained tuples, lists, deques and sets are replaced by their elements and flattened as well. @@ -24,8 +23,7 @@ def flatten(lst): yield elem def unique(iterable): - """ - Return an iterable of the same type which contains unique items. + """Return an iterable of the same type which contains unique items. This function assumes that: type(iterable)(list(iterable)) == iterable diff --git a/ranger/ext/keybinding_parser.py b/ranger/ext/keybinding_parser.py index a8ae0cb8..8023759b 100644 --- a/ranger/ext/keybinding_parser.py +++ b/ranger/ext/keybinding_parser.py @@ -60,8 +60,7 @@ reversed_special_keys = dict((v, k) for k, v in special_keys.items()) def parse_keybinding(obj): - """ - Translate a keybinding to a sequence of integers + """Translate a keybinding to a sequence of integers Example: lol<CR> => (ord('l'), ord('o'), ord('l'), ord('\\n')) @@ -108,9 +107,7 @@ def parse_keybinding(obj): def construct_keybinding(iterable): - """ - Does the reverse of parse_keybinding - """ + """Does the reverse of parse_keybinding""" return ''.join(key_to_string(c) for c in iterable) diff --git a/ranger/ext/lazy_property.py b/ranger/ext/lazy_property.py index 60d3c802..9e3454b0 100644 --- a/ranger/ext/lazy_property.py +++ b/ranger/ext/lazy_property.py @@ -1,8 +1,7 @@ # From http://blog.pythonisito.com/2008/08/lazy-descriptors.html class lazy_property(object): - """ - A @property-like decorator with lazy evaluation + """A @property-like decorator with lazy evaluation >>> class Foo: ... @lazy_property diff --git a/ranger/ext/popen_forked.py b/ranger/ext/popen_forked.py index 8ecba331..3b13ec69 100644 --- a/ranger/ext/popen_forked.py +++ b/ranger/ext/popen_forked.py @@ -5,8 +5,7 @@ import os import subprocess def Popen_forked(*args, **kwargs): - """ - Forks process and runs Popen with the given args and kwargs. + """Forks process and runs Popen with the given args and kwargs. Returns True if forking succeeded, otherwise False. """ diff --git a/ranger/ext/rifle.py b/ranger/ext/rifle.py index e28c8bd6..fc3a7de6 100755 --- a/ranger/ext/rifle.py +++ b/ranger/ext/rifle.py @@ -2,8 +2,7 @@ # Copyright (C) 2012-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -rifle, the file executor/opener of ranger +"""rifle, the file executor/opener of ranger This can be used as a standalone program or can be embedded in python code. When used together with ranger, it doesn't have to be installed to $PATH. @@ -34,9 +33,7 @@ except ImportError: _cached_executables = None def get_executables(): - """ - Return all executable files in $PATH + Cache them. - """ + """Return all executable files in $PATH + Cache them.""" global _cached_executables if _cached_executables is not None: return _cached_executables @@ -72,9 +69,7 @@ try: from ranger.ext.popen_forked import Popen_forked except ImportError: def Popen_forked(*args, **kwargs): - """ - Forks process and runs Popen with the given args and kwargs. - """ + """Forks process and runs Popen with the given args and kwargs.""" try: pid = os.fork() except OSError: @@ -101,8 +96,7 @@ def _is_terminal(): def squash_flags(flags): - """ - Remove lowercase flags if the respective uppercase flag exists + """Remove lowercase flags if the respective uppercase flag exists >>> squash_flags('abc') 'abc' @@ -262,7 +256,8 @@ class Rifle(object): return "set -- '%s'; %s" % (filenames, action) def list_commands(self, files, mimetype=None): - """ + """List all commands that are applicable for the given files + Returns one 4-tuple for all currently applicable commands The 4-tuple contains (count, command, label, flags). count is the index, counted from 0 upwards, @@ -286,8 +281,7 @@ class Rifle(object): yield (count, cmd, self._app_label, self._app_flags) def execute(self, files, number=0, label=None, flags="", mimetype=None): - """ - Executes the given list of files. + """Executes the given list of files. By default, this executes the first command where all conditions apply, but by specifying number=N you can run the 1+Nth command. diff --git a/ranger/ext/run_forked.py b/ranger/ext/run_forked.py index 39d08e51..f8dd2642 100644 --- a/ranger/ext/run_forked.py +++ b/ranger/ext/run_forked.py @@ -5,8 +5,7 @@ import os import subprocess def Popen_forked(*args, **kwargs): - """ - Forks process and runs Popen with the given args and kwargs. + """Forks process and runs Popen with the given args and kwargs. If os.fork() is not supported, runs Popen without forking and returns the process object returned by Popen. diff --git a/ranger/ext/shell_escape.py b/ranger/ext/shell_escape.py index a4e5628d..eeb3adf1 100644 --- a/ranger/ext/shell_escape.py +++ b/ranger/ext/shell_escape.py @@ -1,9 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -Functions to escape metacharacters of arguments for shell commands. -""" +"""Functions to escape metacharacters of arguments for shell commands.""" META_CHARS = (' ', "'", '"', '`', '&', '|', ';', '$', '!', '(', ')', '[', ']', '<', '>', '\t') diff --git a/ranger/ext/shutil_generatorized.py b/ranger/ext/shutil_generatorized.py index 72b8dc26..38e506a2 100644 --- a/ranger/ext/shutil_generatorized.py +++ b/ranger/ext/shutil_generatorized.py @@ -3,7 +3,6 @@ """Utility functions for copying files and directory trees. XXX The functions here don't copy the resource fork or other metadata on Mac. - """ import os diff --git a/ranger/ext/signals.py b/ranger/ext/signals.py index 5ff467aa..7f9d9b21 100644 --- a/ranger/ext/signals.py +++ b/ranger/ext/signals.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -An efficient and minimalistic signaling/hook module. +"""An efficient and minimalistic signaling/hook module. To use this in a class, subclass SignalDispatcher and call SignalDispatcher.__init__(self) in the __init__ function. Now you can bind @@ -62,8 +61,7 @@ import weakref from types import MethodType class Signal(dict): - """ - Signals are passed to the bound functions as an argument. + """Signals are passed to the bound functions as an argument. They contain the attributes "origin", which is a reference to the signal dispatcher, and "name", the name of the signal that was emitted. @@ -83,8 +81,7 @@ class Signal(dict): class SignalHandler: - """ - Signal Handlers contain information about a signal binding. + """Signal Handlers contain information about a signal binding. They are returned by signal_bind() and have to be passed to signal_unbind() in order to remove the handler again. @@ -101,22 +98,19 @@ class SignalHandler: class SignalDispatcher(object): - """ - This abstract class handles the binding and emitting of signals. - """ + """This abstract class handles the binding and emitting of signals.""" def __init__(self): self._signals = dict() def signal_clear(self): - """ Remove all signals. """ + """Remove all signals.""" for handler_list in self._signals.values(): for handler in handler_list: handler._function = None self._signals = dict() def signal_bind(self, signal_name, function, priority=0.5, weak=False, autosort=True): - """ - Bind a function to the signal. + """Bind a function to the signal. signal_name: Any string to name the signal function: Any function with either one or zero arguments which will be @@ -155,8 +149,7 @@ class SignalDispatcher(object): return handler def signal_force_sort(self, signal_name=None): - """ - Forces a sorting of signal handlers by priority. + """Forces a sorting of signal handlers by priority. This is only necessary if you used signal_bind with autosort=False after finishing to bind many signals at once. @@ -170,8 +163,7 @@ class SignalDispatcher(object): return False def signal_unbind(self, signal_handler): - """ - Removes a signal binding. + """Removes a signal binding. This requires the SignalHandler that has been originally returned by signal_bind(). @@ -188,8 +180,7 @@ class SignalDispatcher(object): pass def signal_garbage_collect(self): - """ - Remove all handlers with deleted weak references. + """Remove all handlers with deleted weak references. Usually this is not needed; every time you emit a signal, its handlers are automatically checked in this way. However, if you can't be sure @@ -235,8 +226,7 @@ class SignalDispatcher(object): del handler_list[i] def signal_emit(self, signal_name, **kw): - """ - Emits a signal and call every function that was bound to that signal. + """Emits a signal and call every function that was bound to that signal. You can call this method with any key words. They will be turned into attributes of the Signal object that is passed to the functions. diff --git a/ranger/fsobject/__init__.py b/ranger/fsobject/__init__.py index f3de0fcf..8ef136f9 100644 --- a/ranger/fsobject/__init__.py +++ b/ranger/fsobject/__init__.py @@ -1,7 +1,4 @@ -""" -FileSystemObjects are representation of files and directories -with fast access to their properties through caching -""" +"""FileSystemObjects are representation of files and directories""" BAD_INFO = '?' diff --git a/ranger/fsobject/directory.py b/ranger/fsobject/directory.py index 3785abfc..43fdff65 100644 --- a/ranger/fsobject/directory.py +++ b/ranger/fsobject/directory.py @@ -164,7 +164,8 @@ class Directory(FileSystemObject, Accumulator, Loadable, SettingsAware): # XXX: Check for possible race conditions def load_bit_by_bit(self): - """ + """An iterator that loads a part on every next() call + Returns a generator which load a part of the directory in each iteration. """ @@ -287,9 +288,9 @@ class Directory(FileSystemObject, Accumulator, Loadable, SettingsAware): self.load_generator = None def load_content(self, schedule=None): - """ - Loads the contents of the directory. Use this sparingly since - it takes rather long. + """Loads the contents of the directory. + + Use this sparingly since it takes rather long. """ self.content_outdated = False @@ -474,10 +475,7 @@ class Directory(FileSystemObject, Accumulator, Loadable, SettingsAware): return False def load_content_if_outdated(self, *a, **k): - """ - Load the contents of the directory if it's - outdated or not done yet - """ + """Load the contents of the directory if outdated""" if self.load_content_once(*a, **k): return True diff --git a/ranger/fsobject/fsobject.py b/ranger/fsobject/fsobject.py index ca3613ff..b39ea40b 100644 --- a/ranger/fsobject/fsobject.py +++ b/ranger/fsobject/fsobject.py @@ -186,7 +186,8 @@ class FileSystemObject(FileManagerAware): return self.path def load(self): - """ + """Loads information about the directory itself. + reads useful information about the filesystem-object from the filesystem and caches it for later use """ @@ -272,10 +273,7 @@ class FileSystemObject(FileManagerAware): return self.permissions def load_if_outdated(self): - """ - Calls load() if the currently cached information is outdated - or nonexistant. - """ + """Calls load() if the currently cached information is outdated""" if not self.loaded: self.load() return True diff --git a/ranger/gui/ansi.py b/ranger/gui/ansi.py index ba6aa44d..d2616323 100644 --- a/ranger/gui/ansi.py +++ b/ranger/gui/ansi.py @@ -2,9 +2,7 @@ # Copyright (C) 2010-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -A library to help to convert ANSI codes to curses instructions. -""" +"""A library to help to convert ANSI codes to curses instructions.""" from ranger.gui import color import re @@ -96,8 +94,7 @@ def text_with_fg_bg_attr(ansi_text): yield chunk def char_len(ansi_text): - """ - Count the number of visible characters. + """Count the number of visible characters. >>> char_len("\x1b[0;30;40mX\x1b[0m") 1 @@ -113,8 +110,7 @@ def char_len(ansi_text): return len(ansi_re.sub('', ansi_text)) def char_slice(ansi_text, start, length): - """ - Slices a string with respect to ansi code sequences + """Slices a string with respect to ansi code sequences Acts as if the ansi codes aren't there, slices the text from the given start point to the given length and adds the codes back in. diff --git a/ranger/gui/color.py b/ranger/gui/color.py index 06f49147..eec70661 100644 --- a/ranger/gui/color.py +++ b/ranger/gui/color.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -Contains abbreviations to curses color/attribute constants. +"""Contains abbreviations to curses color/attribute constants. Multiple attributes can be combined with the | (or) operator, toggled with ^ (xor) and checked for with & (and). Examples: @@ -19,9 +18,7 @@ import curses COLOR_PAIRS = {10: 0} def get_color(fg, bg): - """ - Returns the curses color pair for the given fg/bg combination. - """ + """Returns the curses color pair for the given fg/bg combination.""" c = bg+2 + 9*(fg + 2) diff --git a/ranger/gui/colorscheme.py b/ranger/gui/colorscheme.py index b44eacd0..0d5efc2d 100644 --- a/ranger/gui/colorscheme.py +++ b/ranger/gui/colorscheme.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -Colorschemes define colors for specific contexts. +"""Colorschemes define colors for specific contexts. Generally, this works by passing a set of keywords (strings) to the colorscheme.get() method to receive the tuple (fg, bg, attr). @@ -37,8 +36,7 @@ from ranger.ext.cached_function import cached_function from ranger.ext.iter_tools import flatten class ColorScheme(object): - """ - This is the class that colorschemes must inherit from. + """This is the class that colorschemes must inherit from. it defines the get() method, which returns the color tuple which fits to the given keys. @@ -46,8 +44,7 @@ class ColorScheme(object): @cached_function def get(self, *keys): - """ - Returns the (fg, bg, attr) for the given keys. + """Returns the (fg, bg, attr) for the given keys. Using this function rather than use() will cache all colors for faster access. @@ -62,8 +59,7 @@ class ColorScheme(object): @cached_function def get_attr(self, *keys): - """ - Returns the curses attribute for the specified keys + """Returns the curses attribute for the specified keys Ready to use for curses.setattr() """ @@ -71,8 +67,7 @@ class ColorScheme(object): return attr | color_pair(get_color(fg, bg)) def use(self, context): - """ - Use the colorscheme to determine the (fg, bg, attr) tuple. + """Use the colorscheme to determine the (fg, bg, attr) tuple. Override this method in your own colorscheme. """ diff --git a/ranger/gui/curses_shortcuts.py b/ranger/gui/curses_shortcuts.py index 571824ba..3fce7fcd 100644 --- a/ranger/gui/curses_shortcuts.py +++ b/ranger/gui/curses_shortcuts.py @@ -13,8 +13,8 @@ def _fix_surrogates(args): .decode('utf-8', 'replace') or arg for arg in args] class CursesShortcuts(SettingsAware): - """ - This class defines shortcuts to faciliate operations with curses. + """This class defines shortcuts to faciliate operations with curses. + color(*keys) -- sets the color associated with the keys from the current colorscheme. color_at(y, x, wid, *keys) -- sets the color at the given position diff --git a/ranger/gui/displayable.py b/ranger/gui/displayable.py index 78bc0448..621ca9cc 100644 --- a/ranger/gui/displayable.py +++ b/ranger/gui/displayable.py @@ -5,8 +5,7 @@ from ranger.core.shared import FileManagerAware, EnvironmentAware from ranger.gui.curses_shortcuts import CursesShortcuts class Displayable(EnvironmentAware, FileManagerAware, CursesShortcuts): - """ - Displayables are objects which are displayed on the screen. + """Displayables are objects which are displayed on the screen. This is just the abstract class, defining basic operations such as resizing, printing, changing colors. @@ -73,8 +72,8 @@ class Displayable(EnvironmentAware, FileManagerAware, CursesShortcuts): __bool__ = __nonzero__ def __contains__(self, item): - """ - Is item inside the boundaries? + """Checks if item is inside the boundaries. + item can be an iterable like [y, x] or an object with x and y methods. """ try: @@ -88,36 +87,36 @@ class Displayable(EnvironmentAware, FileManagerAware, CursesShortcuts): return self.contains_point(y, x) def draw(self): - """ - Draw the object. Called on every main iteration if visible. - Containers should call draw() on their contained objects here. - Override this! + """Draw the oject. + + Called on every main iteration if visible. Containers should call + draw() on their contained objects here. Override this! """ def destroy(self): - """ - Called when the object is destroyed. + """Called when the object is destroyed. + Override this! """ def contains_point(self, y, x): - """ - Test whether the point (with absolute coordinates) lies - within the boundaries of this object. + """Test whether the point lies inside this object. + + x and y should be absolute coordinates. """ return (x >= self.x and x < self.x + self.wid) and \ (y >= self.y and y < self.y + self.hei) def click(self, event): - """ - Called when a mouse key is pressed and self.focused is True. + """Called when a mouse key is pressed and self.focused is True. + Override this! """ pass def press(self, key): - """ - Called when a key is pressed and self.focused is True. + """Called when a key is pressed and self.focused is True. + Override this! """ pass @@ -132,8 +131,8 @@ class Displayable(EnvironmentAware, FileManagerAware, CursesShortcuts): self.win.erase() def finalize(self): - """ - Called after every displayable is done drawing. + """Called after every displayable is done drawing. + Override this! """ pass @@ -202,8 +201,7 @@ class Displayable(EnvironmentAware, FileManagerAware, CursesShortcuts): return self.__class__.__name__ class DisplayableContainer(Displayable): - """ - DisplayableContainers are Displayables which contain other Displayables. + """DisplayableContainers are Displayables which contain other Displayables. This is also an abstract class. The methods draw, poke, finalize, click, press and destroy are extended here and will recursively diff --git a/ranger/gui/widgets/__init__.py b/ranger/gui/widgets/__init__.py index 2a930b6c..617663a6 100644 --- a/ranger/gui/widgets/__init__.py +++ b/ranger/gui/widgets/__init__.py @@ -1,7 +1,4 @@ from ranger.gui.displayable import Displayable class Widget(Displayable): - """ - The Widget class defines no methods and only exists for - classification of widgets. - """ + """A class for classification of widgets.""" diff --git a/ranger/gui/widgets/browsercolumn.py b/ranger/gui/widgets/browsercolumn.py index ca5710ac..34806b7f 100644 --- a/ranger/gui/widgets/browsercolumn.py +++ b/ranger/gui/widgets/browsercolumn.py @@ -3,6 +3,7 @@ # This software is distributed under the terms of the GNU GPL version 3. """The BrowserColumn widget displays the contents of a directory or file.""" + import curses import stat from time import time @@ -24,7 +25,8 @@ class BrowserColumn(Pager): old_thisfile = None def __init__(self, win, level): - """ + """Initializes a Browser Column Widget + win = the curses window object of the BrowserView level = what to display? @@ -88,8 +90,7 @@ class BrowserColumn(Pager): return True def execute_curses_batch(self, line, commands): - """ - Executes a list of "commands" which can be easily cached. + """Executes a list of "commands" which can be easily cached. "commands" is a list of lists. Each element contains a text and an attribute. First, the attribute will be diff --git a/ranger/gui/widgets/browserview.py b/ranger/gui/widgets/browserview.py index c3e264ad..39d57c5a 100644 --- a/ranger/gui/widgets/browserview.py +++ b/ranger/gui/widgets/browserview.py @@ -2,6 +2,7 @@ # This software is distributed under the terms of the GNU GPL version 3. """The BrowserView manages a set of BrowserColumns.""" + import curses, _curses from ranger.ext.signals import Signal from ranger.ext.keybinding_parser import key_to_string diff --git a/ranger/gui/widgets/console.py b/ranger/gui/widgets/console.py index c9271cac..1977993c 100644 --- a/ranger/gui/widgets/console.py +++ b/ranger/gui/widgets/console.py @@ -1,10 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The Console widget implements a vim-like console for entering -commands, searching and executing files. -""" +"""The Console widget implements a vim-like console""" import curses import re @@ -422,8 +419,7 @@ class Console(Widget): self.execute(cmd) def ask(self, text, callback, choices=['y', 'n']): - """ - Open a question prompt with predefined choices + """Open a question prompt with predefined choices The "text" is displayed as the question text and should include a list of possible keys that the user can type. The "callback" is a function diff --git a/ranger/gui/widgets/pager.py b/ranger/gui/widgets/pager.py index f5988e08..4a98e083 100644 --- a/ranger/gui/widgets/pager.py +++ b/ranger/gui/widgets/pager.py @@ -2,9 +2,8 @@ # Copyright (C) 2010 David Barnett <davidbarnett2@gmail.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The pager displays text and allows you to scroll inside it. -""" +"""The pager displays text and allows you to scroll inside it.""" + from . import Widget from ranger.core.loader import CommandLoader from ranger.gui import ansi diff --git a/ranger/gui/widgets/statusbar.py b/ranger/gui/widgets/statusbar.py index 61a00b5d..1ce7af11 100644 --- a/ranger/gui/widgets/statusbar.py +++ b/ranger/gui/widgets/statusbar.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The statusbar displays information about the current file and directory. +"""The statusbar displays information about the current file and directory. On the left side, there is a display similar to what "ls -l" would print for the current file. The right side shows directory information diff --git a/ranger/gui/widgets/taskview.py b/ranger/gui/widgets/taskview.py index ae69402a..9b5104ce 100644 --- a/ranger/gui/widgets/taskview.py +++ b/ranger/gui/widgets/taskview.py @@ -1,9 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The TaskView allows you to modify what the loader is doing. -""" +"""The TaskView allows you to modify what the loader is doing.""" from . import Widget from ranger.ext.accumulator import Accumulator diff --git a/ranger/gui/widgets/titlebar.py b/ranger/gui/widgets/titlebar.py index 2a17211f..aacf0be8 100644 --- a/ranger/gui/widgets/titlebar.py +++ b/ranger/gui/widgets/titlebar.py @@ -1,8 +1,7 @@ # Copyright (C) 2009-2013 Roman Zimbelmann <hut@lavabit.com> # This software is distributed under the terms of the GNU GPL version 3. -""" -The titlebar is the widget at the top, giving you broad overview. +"""The titlebar is the widget at the top, giving you broad overview. It displays the current path among other things. """ |