[tor-commits] [nyx/master] Panel pydocs
atagar at torproject.org
atagar at torproject.org
Fri Jul 15 17:33:39 UTC 2016
commit a4ca8e7b00b7c249699e7388c4fb8711afe66638
Author: Damian Johnson <atagar at 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)
More information about the tor-commits
mailing list