Added docstrings for symbol/series_store modules + removed QwtAbstractSeriesStore

Author: PierreRaybaut

doc/images/symbol_path_example.png

@@ -7,7 +7,6 @@ Contents:
     :maxdepth: 2
 
     overview
-    limitations
     installation
     examples/index
     reference/index

doc/index.rst

@@ -26,19 +26,23 @@ only plot items needed by `guiqwt`): `QwtPlotItem` (base class),
 `QwtPlotCurve`.
 
 The `HistogramItem` object implemented in PyQwt's HistogramDemo.py is not 
-available here as a similar item is already implemented in `guiqwt`. As a 
+available here (a similar item is already implemented in `guiqwt`). As a 
 consequence, the following classes are not implemented: `QwtPlotHistogram`, 
 `QwtIntervalSeriesData`, `QwtIntervalSample`.
 
-The following data structure objects are not implemented as they seemed not 
-relevant with Python and NumPy: `QwtCPointerData` (As a consequence, method 
+The following data structure objects are not implemented as they seemed 
+irrelevant with Python and NumPy: `QwtCPointerData` (as a consequence, method 
 `QwtPlot.setRawSamples` is not implemented), `QwtSyntheticPointData`.
 
 The following sample data type objects are not implemented as they seemed 
 quite specific: `QwtSetSample`, `QwtOHLCSample`. For similar reasons, the 
 `QwtPointPolar` class and the following sample iterator objects are not 
-implemented: `QwtSetSeriesData`, `QwtTradingChartData`, 
-`QwtPoint3DSeriesData`, `QwtArraySeriesData`, `QwtPointSeriesData`.
+implemented: `QwtSetSeriesData`, `QwtTradingChartData` and 
+`QwtPoint3DSeriesData`.
+
+The following classes are not implemented because they seem inappropriate in 
+the Python/NumPy context: `QwtArraySeriesData`, `QwtPointSeriesData`, 
+`QwtAbstractSeriesStore`.
 
 Threads:
 

doc/overview.rst

@@ -26,4 +26,6 @@ Main `python-qwt` classes:
     scale_engine
     scale_widget
     series_data
+    series_store
+    symbol
     toqimage

doc/reference/index.rst

@@ -0,0 +1,2 @@
+.. automodule:: qwt.series_store
+   :members:

doc/reference/series_store.rst

@@ -0,0 +1,2 @@
+.. automodule:: qwt.symbol
+   :members:

doc/reference/symbol.rst

@@ -374,7 +374,7 @@ def symbol(self):
 
     def setPen(self, *args):
         """
-        Build and/or assigna a pen, depending on the arguments.
+        Build and/or assign a pen, depending on the arguments.
         
         .. py:method:: setPen(color, width, style)
         

qwt/plot_curve.py

@@ -15,7 +15,6 @@
 
 from qwt.plot import QwtPlotItem, QwtPlotItem_PrivateData
 from qwt.text import QwtText
-from qwt.series_store import QwtAbstractSeriesStore
 
 from qwt.qt.QtCore import Qt, QRectF
 
@@ -26,12 +25,11 @@ def __init__(self):
         self.orientation = Qt.Vertical
 
 
-class QwtPlotSeriesItem(QwtPlotItem, QwtAbstractSeriesStore):
+class QwtPlotSeriesItem(QwtPlotItem):
     """
     Base class for plot items representing a series of samples
     """
     def __init__(self, title):
-        QwtAbstractSeriesStore.__init__(self)
         if not isinstance(title, QwtText):
             title = QwtText(title)
         QwtPlotItem.__init__(self, title)

qwt/plot_seriesitem.py

@@ -621,9 +621,8 @@ class QwtLogScaleEngine(QwtScaleEngine):
     """
     A scale engine for logarithmic scales
 
-    The step size is measured in *decades*
-    and the major step size will be adjusted to fit the pattern
-    \f$\left\{ 1,2,3,5\right\} \cdot 10^{n}\f$, where n is a natural number
+    The step size is measured in *decades* and the major step size will be 
+    adjusted to fit the pattern {1,2,3,5}.10**n, where n is a natural number
     including zero.
 
     .. warning::

qwt/scale_engine.py

@@ -5,57 +5,103 @@
 # Copyright (c) 2015 Pierre Raybaut, for the Python translation/optimization
 # (see LICENSE file for more details)
 
-from qwt.qt.QtCore import QRectF
+"""
+QwtSeriesStore
+--------------
 
+.. autoclass:: QwtSeriesStore
+   :members:
+"""
 
-class QwtAbstractSeriesStore(object):
-    def dataChanged(self):
-        raise NotImplementedError
-    
-    def dataSize(self):
-        raise NotImplementedError
-    
-    def dataRect(self):
-        raise NotImplementedError
-    
-    def setRectOfInterest(self, rect):
-        raise NotImplementedError
+from qwt.qt.QtCore import QRectF
 
 
-class QwtSeriesStore(QwtAbstractSeriesStore):
+class QwtSeriesStore(object):
+    """
+    Class storing a `QwtSeriesData` object
+
+    `QwtSeriesStore` and `QwtPlotSeriesItem` are intended as base classes for 
+    all plot items iterating over a series of samples.
+    """
     def __init__(self):
         self.__series = None
 
+    def setData(self, series):
+        """
+        Assign a series of samples
+
+        :param qwt.series_data.QwtSeriesData series: Data
+
+        .. warning::
+        
+            The item takes ownership of the data object, deleting it 
+            when its not used anymore.
+        """
+        if self.__series != series:
+            self.__series = series
+            self.dataChanged()
+    
     def data(self):
+        """
+        :return: the series data
+        """
         return self.__series
 
     def sample(self, index):
+        """
+        :param int index: Index
+        :return: Sample at position index
+        """
         if self.__series:
             return self.__series.sample(index)
         else:
-            #TODO: not implemented!
             return
 
-    def setData(self, series):
-        if self.__series != series:
-            self.__series = series
-            self.dataChanged()
-    
     def dataSize(self):
+        """
+        :return: Number of samples of the series
+        
+        .. seealso::
+        
+            :py:meth:`setData()`, 
+            :py:meth:`qwt.series_data.QwtSeriesData.size()`
+        """
         if self.__series is None:
             return 0
         return self.__series.size()
 
     def dataRect(self):
+        """
+        :return: Bounding rectangle of the series or an invalid rectangle, when no series is stored
+        
+        .. seealso::
+        
+            :py:meth:`qwt.series_data.QwtSeriesData.boundingRect()`
+        """
         if self.__series is None or self.dataSize() == 0:
             return QRectF(1.0, 1.0, -2.0, -2.0)
         return self.__series.boundingRect()
 
     def setRectOfInterest(self, rect):
+        """
+        Set a the "rect of interest" for the series
+        
+        :param QRectF rect: Rectangle of interest
+        
+        .. seealso::
+        
+            :py:meth:`qwt.series_data.QwtSeriesData.setRectOfInterest()`
+        """
         if self.__series:
             self.__series.setRectOfInterest(rect)
 
     def swapData(self, series):
+        """
+        Replace a series without deleting the previous one
+        
+        :param qwt.series_data.QwtSeriesData series: New series
+        :return: Previously assigned series
+        """
         swappedSeries = self.__series
         self.__series = series
         return swappedSeries