Merge pull request #228 from frictionlessdata/readme-review-and-minor…

…-improvements

README review and minor improvements

.gitignore

@@ -36,6 +36,7 @@ pip-delete-this-directory.txt
 # Unit test / coverage reports
 htmlcov/
 .tox/
+.pytest_cache/
 .coverage
 .coverage.*
 .cache
@@ -74,3 +75,4 @@ tmp
 
 # Extra
 datapackage
+.#*

Makefile

@@ -14,7 +14,6 @@ list:
 	@grep '^\.PHONY' Makefile | cut -d' ' -f2- | tr ' ' '\n'
 
 test:
-	pylama $(PACKAGE)
 	tox
 
 version:

setup.py

@@ -48,7 +48,6 @@ def read(*paths):
     'lxml>=3.0,<4.0',
 ]
 TESTS_REQUIRE = [
-    'pylama',
     'tox',
 ]
 README = read('README.md')

tabulator/cli.py

@@ -20,8 +20,6 @@
 @click.option('--limit', type=click.INT)
 @click.version_option(tabulator.__version__, message='%(version)s')
 def cli(source, limit, **options):
-    """https://github.com/frictionlessdata/tabulator-py#cli
-    """
     options = {key: value for key, value in options.items() if value is not None}
     with tabulator.Stream(source, **options) as stream:
         cast = str
@@ -30,7 +28,7 @@ def cli(source, limit, **options):
         if stream.headers:
             click.echo(click.style(', '.join(map(cast, stream.headers)), bold=True))
         for count, row in enumerate(stream, start=1):
-            click.echo(', '.join(map(cast, row)))
+            click.echo(','.join(map(cast, row)))
             if count == limit:
                 break
 

tabulator/exceptions.py

@@ -8,44 +8,34 @@
 # Module API
 
 class TabulatorException(Exception):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
+    '''Base class for all tabulator exceptions.'''
     pass
 
 
 class IOError(TabulatorException):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
     pass
 
 
-class HTTPError(TabulatorException):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
+class HTTPError(IOError):
     pass
 
 
 class SourceError(TabulatorException):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
+    '''The source file could not be parsed correctly.'''
     pass
 
 
 class SchemeError(TabulatorException):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
+    '''The file scheme is not supported.'''
     pass
 
 
 class FormatError(TabulatorException):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
+    '''The file format is unsupported or invalid.'''
     pass
 
 
 class EncodingError(TabulatorException):
-    """https://github.com/frictionlessdata/tabulator-py#exceptions
-    """
     pass
 
 

tabulator/loader.py

@@ -12,18 +12,37 @@
 
 @add_metaclass(ABCMeta)
 class Loader(object):
+    '''Abstract class implemented by the data loaders
+
+    The loaders inherit and implement this class' methods to add support for a
+    new scheme (e.g. ssh).
+
+    Args:
+        bytes_sample_size (int): Sample size in bytes
+        **options (dict): Loader options
+
+    Returns:
+        Loader: Loader instance.
+    '''
 
     # Public
 
     options = []
 
     def __init__(self, bytes_sample_size, **options):
-        """https://github.com/frictionlessdata/tabulator-py#custom-loaders
-        """
         pass
 
     @abstractmethod
     def load(self, source, mode='t', encoding=None):
-        """https://github.com/frictionlessdata/tabulator-py#custom-loaders
-        """
+        '''Load source file.
+
+        Args:
+            source (str): Path to tabular source file.
+            mode (str, optional): Text stream mode, `t` (text) or `b` (binary).
+                Defaults to `t`.
+            encoding (str, optional): Source encoding. Auto-detect by default.
+
+        Returns:
+            Union[TextIO, BinaryIO]: I/O stream opened either as text or binary.
+        '''
         pass

tabulator/parser.py

@@ -12,51 +12,88 @@
 
 @add_metaclass(ABCMeta)
 class Parser(object):
+    '''Abstract class implemented by the data parsers.
+
+    The parsers inherit and implement this class' methods to add support for a
+    new file type.
+
+    Args:
+        loader (tabulator.Loader): Loader instance to read the file.
+        force_parse (bool): When `True`, the parser yields an empty extended
+            row tuple `(row_number, None, [])` when there is an error parsing a
+            row. Otherwise, it stops the iteration by raising the exception
+            `tabulator.exceptions.SourceError`.
+        **options (dict): Loader options
+
+    Returns:
+        Parser: Parser instance.
+    '''
 
     # Public
 
     options = []
 
     def __init__(self, loader, force_parse, **options):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
         pass
 
     @property
     @abstractmethod
     def closed(self):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
+        '''Flag telling if the parser is closed.'''
         pass  # pragma: no cover
 
     @abstractmethod
     def open(self, source, encoding=None):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
+        '''Open underlying file stream in the beginning of the file.
+
+        The parser gets a byte or text stream from the `tabulator.Loader`
+        instance and start emitting items.
+
+        Args:
+            source (str): Path to source table.
+            encoding (str, optional): Source encoding. Auto-detect by default.
+
+        Returns:
+            None
+        '''
         pass  # pragma: no cover
 
     @abstractmethod
     def close(self):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
+        '''Closes underlying file stream.'''
         pass  # pragma: no cover
 
     @abstractmethod
     def reset(self):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
+        '''Resets underlying stream and current items list.
+
+        After `reset()` is called, iterating over the items will start from the
+        beginning.
+        '''
         pass  # pragma: no cover
 
     @property
     @abstractmethod
     def encoding(self):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
         pass  # pragma: no cover
 
     @property
     @abstractmethod
     def extended_rows(self):
-        """https://github.com/frictionlessdata/tabulator-py#custom-parsers
-        """
+        '''Returns extended rows iterator.
+
+        The extended rows are tuples containing `(row_number, headers, row)`,
+
+        Yields:
+            Tuple[int, List[str], List[Any]]: Extended rows containing
+                `(row_number, headers, row)`, where `headers` is a list of the
+                header names (can be `None`), and `row` is a list of row
+                values.
+
+        Raises:
+            `tabulator.exceptions.SourceError`: If `force_parse` is `False` and
+                a row can't be parsed, this exception will be raised.
+                Otherwise, an empty extended row is returned (i.e.
+                `(row_number, None, [])`).
+        '''
         pass  # pragma: no cover