commit a4ca8e7b00b7c249699e7388c4fb8711afe66638 Author: Damian Johnson atagar@torproject.org Date: Fri Jul 15 09:46:44 2016 -0700

Panel pydocs

Proper sphinx pydocs for the panel module. --- nyx/panel/__init__.py | 108 +++++++++++++++++++++++++++--------------------- nyx/panel/config.py | 2 +- nyx/panel/connection.py | 2 +- nyx/panel/graph.py | 2 +- nyx/panel/header.py | 2 +- nyx/panel/log.py | 2 +- nyx/panel/torrc.py | 2 +- test/panel/header.py | 2 +- test/panel/torrc.py | 8 ++-- 9 files changed, 72 insertions(+), 58 deletions(-)

diff --git a/nyx/panel/__init__.py b/nyx/panel/__init__.py index 96a39bd..bfc4e6c 100644 --- a/nyx/panel/__init__.py +++ b/nyx/panel/__init__.py @@ -3,6 +3,27 @@

""" Panels consisting the nyx interface. + +**Module Overview:** + +:: + + KeyHandler - keyboard input a panel accepts + +- handle - triggers the keyboard action + + Panel - panel within the interface + |- DaemonPanel - panel that triggers actions at a set rate + | |- run - starts triggering daemon actions + | +- stop - stops triggering daemon actions + | + |- get_top - top position we're rendered into on the screen + |- set_top - sets top position within the screen + |- get_height - height occupied by the panel + | + |- set_visible - toggles panel visiblity + |- key_handlers - keyboard input accepted by the panel + |- get_preferred_size - dimensions when rendered + +- redraw - renders the panel content """

import collections @@ -63,56 +84,64 @@ class KeyHandler(collections.namedtuple('Help', ['key', 'description', 'current'

class Panel(object): """ - Common parent for interface panels, providing the ability to pause and - configure dimensions. + Panel within the nyx interface. """

def __init__(self): - self._visible = False self._top = 0 - - def set_visible(self, is_visible): - """ - Toggles if the panel is visible or not. - - Arguments: - is_visible - panel is redrawn when requested if true, skipped otherwise - """ - - self._visible = is_visible + self._visible = False

def get_top(self): """ - Provides the top position used for subwindows. + Provides our top position in the overall screen. + + :returns: **int** with the top coordinate """

return self._top

def set_top(self, top): """ - Changes the position where subwindows are placed within its parent. + Changes the position where we're rendered in the screen.

- Arguments: - top - positioning of top within parent + :param int top: top position within the sceen """

- if self._top != top: - self._top = top + self._top = top

def get_height(self): """ - Provides the height used by this panel. + Provides the height occupied by this panel.

:returns: **int** for the height of the panel or **None** if unlimited """

return None

+ def set_visible(self, is_visible): + """ + Toggles if the panel is visible or not. + + :param bool is_visible: shows panel if **True**, hides otherwise + """ + + self._visible = is_visible + + def key_handlers(self): + """ + Provides keyboard input this panel supports. + + :returns: **tuple** of :class:`~nyx.panel.KeyHandler` instances + """ + + return () + def get_preferred_size(self): """ - Provides the dimensions the subwindow would use when next redrawn, given - that none of the properties of the panel or parent change before then. This - returns a tuple of (height, width). + Provides the dimensions the subwindow would use when next redrawn if none + of its properties change. + + :returns: **tuple** of the form **(height, width)** """

with nyx.curses.raw_screen() as stdscr: @@ -128,40 +157,25 @@ class Panel(object):

return (new_height, new_width)

- def key_handlers(self): - """ - Provides options this panel supports. This is a tuple of - :class:`~nyx.panel.KeyHandler` instances. - """ - - return () - - def draw(self, subwindow): - """ - Draws display's content. This is meant to be overwritten by - implementations and not called directly (use redraw() instead). The - dimensions provided are the drawable dimensions, which in terms of width is - a column less than the actual space. - - Arguments: - subwindow - window content is drawn into - """ - - pass - def redraw(self): """ - Clears display and redraws its content. This can skip redrawing content if - able (ie, the subwindow's unchanged), instead just refreshing the display. + Renders our panel's content to the screen. """

if not self._visible: return # not currently visible

- nyx.curses.draw(self.draw, top = self._top, height = self.get_height()) + nyx.curses.draw(self._draw, top = self._top, height = self.get_height()) + + def _draw(self, subwindow): + pass

class DaemonPanel(Panel, threading.Thread): + """ + Panel that triggers its _update() method at a set rate. + """ + def __init__(self, update_rate): Panel.__init__(self) threading.Thread.__init__(self) diff --git a/nyx/panel/config.py b/nyx/panel/config.py index cbbaa92..f5d9dd9 100644 --- a/nyx/panel/config.py +++ b/nyx/panel/config.py @@ -240,7 +240,7 @@ class ConfigPanel(nyx.panel.Panel): nyx.panel.KeyHandler('s', 'sort ordering', self.show_sort_dialog), )

- def draw(self, subwindow): + def _draw(self, subwindow): contents = self._get_config_options() selected, scroll = self._scroller.selection(contents, subwindow.height - DETAILS_HEIGHT) is_scrollbar_visible = len(contents) > subwindow.height - DETAILS_HEIGHT diff --git a/nyx/panel/connection.py b/nyx/panel/connection.py index bd78a9b..497df5c 100644 --- a/nyx/panel/connection.py +++ b/nyx/panel/connection.py @@ -400,7 +400,7 @@ class ConnectionPanel(nyx.panel.DaemonPanel):

return tuple(options)

- def draw(self, subwindow): + def _draw(self, subwindow): controller = tor_controller() nyx_controller = nyx.controller.get_controller() entries = self._entries diff --git a/nyx/panel/graph.py b/nyx/panel/graph.py index e5f9cc7..4a4e125 100644 --- a/nyx/panel/graph.py +++ b/nyx/panel/graph.py @@ -557,7 +557,7 @@ class GraphPanel(nyx.panel.Panel): self._accounting_stats_paused = copy.copy(self._accounting_stats) self._stats_paused = dict([(key, type(self._stats[key])(self._stats[key])) for key in self._stats])

- def draw(self, subwindow): + def _draw(self, subwindow): if not self.displayed_stat: return

diff --git a/nyx/panel/header.py b/nyx/panel/header.py index 5f33f4f..31f9970 100644 --- a/nyx/panel/header.py +++ b/nyx/panel/header.py @@ -141,7 +141,7 @@ class HeaderPanel(nyx.panel.DaemonPanel): nyx.panel.KeyHandler('r', action = _reconnect), )

- def draw(self, subwindow): + def _draw(self, subwindow): vals = self._vals # local reference to avoid concurrency concerns self._last_width = subwindow.width is_wide = self.is_wide() diff --git a/nyx/panel/log.py b/nyx/panel/log.py index 02cd7fe..2eac0b5 100644 --- a/nyx/panel/log.py +++ b/nyx/panel/log.py @@ -250,7 +250,7 @@ class LogPanel(nyx.panel.DaemonPanel): if is_pause: self._event_log_paused = self._event_log.clone()

- def draw(self, subwindow): + def _draw(self, subwindow): scroll = self._scroller.location(self._last_content_height, subwindow.height - 1)

nyx_controller = nyx.controller.get_controller() diff --git a/nyx/panel/torrc.py b/nyx/panel/torrc.py index 6927e0c..dfe331d 100644 --- a/nyx/panel/torrc.py +++ b/nyx/panel/torrc.py @@ -108,7 +108,7 @@ class TorrcPanel(panel.Panel): nyx.panel.KeyHandler('l', 'line numbering', _toggle_line_numbers, 'on' if self._show_line_numbers else 'off'), )

- def draw(self, subwindow): + def _draw(self, subwindow): scroll = self._scroller.location(self._last_content_height - 1, subwindow.height - 1)

if self._torrc_content is None: diff --git a/test/panel/header.py b/test/panel/header.py index c14b404..2951747 100644 --- a/test/panel/header.py +++ b/test/panel/header.py @@ -79,7 +79,7 @@ class TestHeaderPanel(unittest.TestCase): sampling_mock.return_value = test_sampling()

panel = nyx.panel.header.HeaderPanel() - self.assertEqual(EXPECTED_PANEL, test.render(panel.draw).content) + self.assertEqual(EXPECTED_PANEL, test.render(panel._draw).content)

@patch('nyx.panel.header.tor_controller') @patch('nyx.tracker.get_resource_tracker') diff --git a/test/panel/torrc.py b/test/panel/torrc.py index 96d222c..732ec63 100644 --- a/test/panel/torrc.py +++ b/test/panel/torrc.py @@ -54,7 +54,7 @@ class TestGraphPanel(unittest.TestCase): @patch('nyx.panel.torrc.tor_controller', Mock()) def test_draw_with_content(self): panel = nyx.panel.torrc.TorrcPanel() - self.assertEqual(RENDERED_DEFAULT, test.render(panel.draw).content) + self.assertEqual(RENDERED_DEFAULT, test.render(panel._draw).content)

@require_curses @patch('nyx.panel.torrc._read_torrc', Mock(return_value = TORRC.splitlines())) @@ -63,7 +63,7 @@ class TestGraphPanel(unittest.TestCase): def test_draw_without_comments(self): panel = nyx.panel.torrc.TorrcPanel() panel._show_comments = False - self.assertEqual(RENDERED_WITHOUT_COMMENTS, test.render(panel.draw).content) + self.assertEqual(RENDERED_WITHOUT_COMMENTS, test.render(panel._draw).content)

@require_curses @patch('nyx.panel.torrc._read_torrc', Mock(return_value = TORRC.splitlines())) @@ -72,7 +72,7 @@ class TestGraphPanel(unittest.TestCase): def test_draw_without_line_numbers(self): panel = nyx.panel.torrc.TorrcPanel() panel._show_line_numbers = False - self.assertEqual(RENDERED_WITHOUT_LINE_NUMBERS, test.render(panel.draw).content) + self.assertEqual(RENDERED_WITHOUT_LINE_NUMBERS, test.render(panel._draw).content)

@require_curses @patch('nyx.panel.torrc._read_torrc', Mock(side_effect = IOError("[Errno 2] No such file or directory: '/path/to/torrc'"))) @@ -81,4 +81,4 @@ class TestGraphPanel(unittest.TestCase): def test_draw_with_error(self): panel = nyx.panel.torrc.TorrcPanel() panel._show_line_numbers = False - self.assertEqual(RENDERED_WITH_ERROR, test.render(panel.draw).content) + self.assertEqual(RENDERED_WITH_ERROR, test.render(panel._draw).content)