Update doc for the filenode module (closes gh-244)

ANNOUNCE.txt.in

@@ -34,6 +34,9 @@ A short summary of main new features:
   pre-allocated array to store data.
 - Added support for the floating point data types with extended precision
   (Float96, Float128, Complex192 and Complex256).
+- Complete rewrite of the `nodes.filenode` module. Now it is fully
+  compliant with the interfaces defined in the standard `io` module.
+  Only non-buffered binary I/O is supported currently.
 
 Please refer to the RELEASE_NOTES document for a more detailed list of
 changes in this release.

RELEASE_NOTES.txt

@@ -49,6 +49,11 @@ New features
   available if numpy_ provides it as well.
   Closes :issue:`51` and :issue:`214`.  Many thanks to Andrea Bedini.
 
+- Complete rewrite of the :mod:`nodes.filenode` module. Now it is fully
+  compliant with the interfaces defined in the standard :mod:`io` module.
+  Only non-buffered binary I/O is supported currently.
+  See also the `API changes`_ section.  Closes :issue:`244`.
+
 - New :program:`pt2to3` tool is provided to help users to port their
   applications to the new API (see `API changes`_ section).
 
@@ -118,7 +123,7 @@ so the old API is still usable even if it is now deprecated (see the
 Deprecations_ section).
 
 The only important exception is represented by names function/methods
-arguments.  Al uses of keyword arguments should be checked and fixed to use
+arguments.  All uses of keyword arguments should be checked and fixed to use
 the new naming convention.
 
 The new :program:`pt2to3` tool can be used to port PyTables based applications
@@ -144,6 +149,20 @@ Many deprecated features and support for obsolete modules has been dropped:
 
 Moreover:
 
+- The :mod:`nodes.filenode` has been completely rewritten to be fully
+  compliant with the interfaces defined in the :mod:`io` module.
+
+  The FileNode classes currently implemented are intended for binary I/O.
+
+  Main changes:
+
+  * the FileNode base class is no more available,
+  * the new version of :class:`nodes.filenode.ROFileNode` and
+    :class:`nodes.filenode.RAFileNode` objects no more expose the *offset*
+    attribute (the *seek* and *tell* methods can be used instead),
+  * the *lineSeparator* property is no more available end the ``\n``
+    character is always used as line separator.
+
 - The `__version__` module constants has been removed from almost all the
   modules (it was no more used after the switch to Git).
   Of course the package level constant (:data:`tables.__version__`) still

doc/source/usersguide/filenode.rst

@@ -277,8 +277,10 @@ This is a list of known current limitations:
 #. Node files can only be opened for read-only or read and append mode. This
    should be enhanced in the future.
 #. Near future?
-#. There is no universal newline support yet. This is likely to be
-   implemented in a near future.
+#. Only binary I/O is supported currently (read/write strings of bytes)
+#. There is no universal newline support yet. The only new-line character
+   used at the moment is ``\n``. This is likely to be improved in a near
+   future.
 #. Sparse files (files with lots of zeros) are not treated specially; if you
    want them to take less space, you should be better off using compression.
 

doc/source/usersguide/libref/filenode_classes.rst

@@ -7,38 +7,61 @@ Filenode Module
 
 .. automodule:: tables.nodes.filenode
 
+
 Module constants
 ----------------
+
 .. autodata:: NodeType
 
 .. autodata:: NodeTypeVersions
 
 
 Module functions
 ----------------
+
 .. autofunction:: new_node
 
 .. autofunction:: open_node
 
-The FileNode abstract class
----------------------------
 
-.. autoclass:: FileNode
+The RawPyTablesIO base class
+----------------------------
+
+.. autoclass:: RawPyTablesIO
+
+
+RawPyTablesIO attributes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoattribute:: RawPyTablesIO.mode
+
+
+RawPyTablesIO methods
+~~~~~~~~~~~~~~~~~~~~~
 
-FileNode attributes
-~~~~~~~~~~~~~~~~~~~
+.. automethod:: RawPyTablesIO.tell
 
-.. autoattribute:: FileNode.attrs
+.. automethod:: RawPyTablesIO.seek
 
+.. automethod:: RawPyTablesIO.seekable
 
-FileNode methods
-~~~~~~~~~~~~~~~~
+.. automethod:: RawPyTablesIO.fileno
 
-.. automethod:: FileNode.close
+.. automethod:: RawPyTablesIO.close
 
-.. automethod:: FileNode.seek
+.. automethod:: RawPyTablesIO.flush
 
-.. automethod:: FileNode.tell
+.. automethod:: RawPyTablesIO.truncate
+
+.. automethod:: RawPyTablesIO.readable
+
+.. automethod:: RawPyTablesIO.writable
+
+.. automethod:: RawPyTablesIO.readinto
+
+.. automethod:: RawPyTablesIO.readline
+
+.. automethod:: RawPyTablesIO.write
 
 
 The ROFileNode class
@@ -47,52 +70,78 @@ The ROFileNode class
 .. autoclass:: ROFileNode
 
 
+ROFileNode attributes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoattribute:: ROFileNode.attrs
+
+
 ROFileNode methods
 ~~~~~~~~~~~~~~~~~~
 
 .. automethod:: ROFileNode.flush
 
-.. automethod:: ROFileNode.next
-
 .. automethod:: ROFileNode.read
 
 .. automethod:: ROFileNode.readline
 
 .. automethod:: ROFileNode.readlines
 
-.. automethod:: ROFileNode.xreadlines
+.. automethod:: ROFileNode.close
+
+.. automethod:: ROFileNode.seek
 
-.. automethod:: ROFileNode.truncate
+.. automethod:: ROFileNode.tell
 
-.. automethod:: ROFileNode.write
+.. automethod:: ROFileNode.readable
 
-.. automethod:: ROFileNode.writelines
+.. automethod:: ROFileNode.writable
 
+.. automethod:: ROFileNode.seekable
+
+.. automethod:: ROFileNode.fileno
 
 
 The RAFileNode class
 --------------------
 
 .. autoclass:: RAFileNode
 
+
+RAFileNode attributes
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoattribute:: RAFileNode.attrs
+
+
 RAFileNode methods
 ~~~~~~~~~~~~~~~~~~
 
 .. automethod:: RAFileNode.flush
 
-.. automethod:: RAFileNode.next
-
 .. automethod:: RAFileNode.read
 
 .. automethod:: RAFileNode.readline
 
 .. automethod:: RAFileNode.readlines
 
-.. automethod:: RAFileNode.xreadlines
-
 .. automethod:: RAFileNode.truncate
 
 .. automethod:: RAFileNode.write
 
 .. automethod:: RAFileNode.writelines
 
+.. automethod:: RAFileNode.close
+
+.. automethod:: RAFileNode.seek
+
+.. automethod:: RAFileNode.tell
+
+.. automethod:: RAFileNode.readable
+
+.. automethod:: RAFileNode.writable
+
+.. automethod:: RAFileNode.seekable
+
+.. automethod:: RAFileNode.fileno
+

tables/nodes/filenode.py

@@ -25,9 +25,8 @@
 See :ref:`filenode_usersguide` for instructions on use.
 
 .. versionchanged:: 3.0
-
-    In version 3.0 the module as been copletely rewritten do be fully
-    comliant with the :mod:`io` module interfeces.
+   In version 3.0 the module as been completely rewritten to be fully
+   compliant with the interfaces defined in the :mod:`io` module.
 
 """
 
@@ -79,6 +78,8 @@ def __init__(self, node, mode=None):
     # read only attribute
     @property
     def mode(self):
+        '''File mode'''
+
         return self._mode
 
     #def tell(self) -> int:
@@ -164,9 +165,9 @@ def close(self):
             self._node = None
 
     def flush(self):
-        """Flushes the file node.
+        """Flush write buffers, if applicable.
 
-        See file.flush.__doc__ for more information.
+        This is not implemented for read-only and non-blocking streams.
 
         """
 
@@ -263,7 +264,7 @@ def readline(self, limit=-1):
 
         If limit is specified, at most limit bytes will be read.
 
-        The line terminator is always b'\n' for binary files; for text
+        The line terminator is always ``\\n`` for binary files; for text
         files, the newlines argument to open can be used to select the line
         terminator(s) recognized.
 
@@ -530,16 +531,18 @@ class ROFileNode(FileNodeMixin, RawPyTablesIO):
     The constructor is not intended to be used directly.
     Use the open_node() function in read-only mode ('r') instead.
 
-    Version 1 implements the file storage as a UInt8 uni-dimensional EArray.
-    Version 2 uses an UInt8 N vector EArray.
+    :Version 1:
+        implements the file storage as a UInt8 uni-dimensional EArray.
+    :Version 2:
+        uses an UInt8 N vector EArray.
 
     .. versionchanged:: 3.0
+       The offset attribute is no more available, please use seek/tell
+       methods instead.
 
-        The offset attribute is no more available, please use seek/tell
-        methods instead.
-
-        Also the line_separator property is no more available.
-        The only line separator used for binary I/O is '\n'.
+    .. versionchanged:: 3.0
+       The line_separator property is no more available.
+       The only line separator used for binary I/O is ``\\n``.
 
     """
 
@@ -572,16 +575,18 @@ class RAFileNode(FileNodeMixin, RawPyTablesIO):
     The constructor is not intended to be used directly.
     Use the new_node() or open_node() functions instead.
 
-    Version 1 implements the file storage as a UInt8 uni-dimensional EArray.
-    Version 2 uses an UInt8 N vector EArray.
+    :Version 1:
+        implements the file storage as a UInt8 uni-dimensional EArray.
+    :Version 2:
+        uses an UInt8 N vector EArray.
 
     .. versionchanged:: 3.0
+       The offset attribute is no more available, please use seek/tell
+       methods instead.
 
-        The offset attribute is no more available, please use seek/tell
-        methods instead.
-
-        Also the line_separator property is no more available.
-        The only line separator used for binary I/O is '\n'.
+    .. versionchanged:: 3.0
+       The line_separator property is no more available.
+       The only line separator used for binary I/O is ``\\n``.
 
     """