First round of doc improvements

diff --git a/DEVELOPERS.md b/DEVELOPERS.md
index 132b9501f85d6fdcee4bb0870289af29a033b68b..a8eceb2f029eadde2d3639b72986df1ddb9edb68 100644 (file)
--- a/DEVELOPERS.md
+++ b/DEVELOPERS.md
@@ -1,16 +1,10 @@
-# How is datasette-pytables made?
+# How is datasette-pytables implemented?
 
-Datasette-PyTables is an external connector for [Datasette](https://github.com/simonw/datasette). Datasette publish data in SQLite files to the Internet with a JSON API, and this connector provides a way to do the same with PyTables files.
-
-Using a modified version of Datasette, [Datasette-Core](https://github.com/PyTables/datasette-core), we can load external connectors that allow us to access to any data container. For this, the connectors need a certain structure.
-
-Reviewing datasette-pytables code, you will see how to make other connectors for your needs.
+Datasette-PyTables is an external connector for [Datasette](https://github.com/simonw/datasette). Datasette publish data in SQLite files to the Internet with a JSON API, and this connector provides a way to do the same thing with PyTables files.  By using a fork of Datasette, [Datasette-Core](https://github.com/PyTables/datasette-core), we can load external connectors that allow us to access to any data container. For this, the connectors need the interface that is described here.  By following these interface, you will can make connectors for other data sources too.
 
 ## Tables inspection
 
-First of all, we need to export a special method called `inspect` that receives the path of the file as an argument and returns a tuple formed by a dictionary with tables info, a list with views name and a string identifying the connector.
-
-Each entry in the dictionary for tables info has the next structure:
+First of all, we need to implement a special method called `inspect` that receives the path of the file as an argument and returns a tuple formed by a dictionary with tables info, a list with views name and a string identifying the connector.  Each entry in the dictionary for tables info has the next structure:
 
     tables['table_name'] = {
         'name': 'table_name',
@@ -22,11 +16,11 @@ Each entry in the dictionary for tables info has the next structure:
         'fts_table': None,
         'foreign_keys': {'incoming': [], 'outgoing': []}
 
-This structure is used for PyTables. Maybe, in your case, you will need things like primary keys or foreign keys.
+This structure is used for PyTables. In your case, you may need additional entries like primary keys or foreign keys.
 
 ## Returning results
 
-Datasette runs through SQL queries, so your connector has to accept these queries and execute them. The next class and methods are needed:
+Datasette uses SQL for specifying the queries, so your connector has to accept SQL and execute it.  The next class and methods are needed:
 
     class Connection:
         def __init__(self, path):
@@ -35,7 +29,7 @@ Datasette runs through SQL queries, so your connector has to accept these querie
         def execute(self, sql, params=None, truncate=False, page_size=None, max_returned_rows=None):
             ...
 
-The `execute` method receives:
+The `Connection.execute()` method receives:
 
 * **sql**: the query
 * **params**: a dictionary with the params used in the query
@@ -43,13 +37,13 @@ The `execute` method receives:
 * **page_size**: the number of rows a page can contain
 * **max_returned_rows**: the maximum number of rows Datasette expects
 
-We need to parse the query because PyTables has its own style for queries, but other databases could work with the SQL queries without requiring any parsing.
+In our case, we need to parse the SQL query because PyTables has its own style for queries, but other databases could work with the SQL queries without requiring any parsing.
 
-Sometimes, Datasette make queries to `sqlite_master`; you need to keep it in mind.
+Note: Sometimes, Datasette make queries to `sqlite_master`; you need to keep it in mind.
 
-The `execute` method has to return a tuple with:
+The `Connection.execute()` method has to return a tuple with:
 
-* a list of rows (Datasette expects something like SQLite rows)
+* a list of rows (Datasette expects something similar to SQLite rows)
 * a boolean saying if the data is truncated, i.e., if we return all the rows or there are more rows than the maximum indicated in max_returned_rows
 * a tuple with the description of the columns in the form `(('c1',), ('c2',), ...)`
 
@@ -61,11 +55,11 @@ For example, if we have the next query:
 
     SELECT name FROM persons
 
-we need to return an object that allows to do things that:
+we need to return an object that allows to do things like:
 
     row[0] == 'Susan'
     row['name'] == 'Susan'
     [c for c in row] == ['Susan']
     json.dumps(row)
 
-We extend `list` class to get it, but if you respect the requirements for rows, you can develop your own implementation.
+In our case, we extend the `list` object to get it, but as long as you implement a similar interface, you can develop your own implementation too.

diff --git a/README.md b/README.md
index 0347a31f1ce42d18656fce566573a8f906af1e58..a447c04e834a0768199862ea71ec6c1de6664ec3 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,17 +1,15 @@
 # datasette-pytables
 
-Datasette-PyTables provides a web interface and a JSON API for [PyTables](https://github.com/PyTables/PyTables) files, allowing them to be accessible for Javascript programs, for example. It works in conjunction with [Datasette-Core](https://github.com/PyTables/datasette-core), a modified version of the original [Datasette](https://github.com/simonw/datasette), which provides a web interface for SQLite files.
-
-The modified version is able to work with SQLite files, like the original project, but can accept external connectors for any kind of database files, so you can develop your own connector for your favourite data container if you want (read [developers doc](https://github.com/PyTables/datasette-pytables/blob/master/DEVELOPERS.md))
+Datasette-PyTables provides a web interface and a JSON API for [PyTables](https://github.com/PyTables/PyTables) files, allowing them to be accessible for e.g. Javascript programs. It works in conjunction with [Datasette-Core](https://github.com/PyTables/datasette-core), a trivial fork of the original [Datasette](https://github.com/simonw/datasette), which provides a web interface for SQLite files.  This fork is able to work with SQLite files, like the original project, but can accept external connectors for any kind of database files, so you can develop your own connector for your favourite data container if you want (read [developers doc](https://github.com/PyTables/datasette-pytables/blob/master/DEVELOPERS.md))
 
 ## Installation
 
-Run `pip install datasette-pytables` to add the modified version of Datasette and the PyTables connector to your environment. Easy!
+Run `pip install datasette-pytables` to install both the forked version of Datasette and the PyTables connector. Easy as pie!
 
 ## How to serve PyTables files
 
     datasette serve path/to/data.h5
 
-This will start a web server on port 8001, so you can access to your data visiting [http://localhost:8001/](http://localhost:8001/)
+This will start a web server on port 8001; then you can access to your data visiting [http://localhost:8001/](http://localhost:8001/)
 
 Read the [Datasette documentation](http://datasette.readthedocs.io/en/latest/) for more advanced options.

diff --git a/datasette_pytables/__init__.py b/datasette_pytables/__init__.py
index 58fee10364d3fec5c83d5b011579555f8d492712..93f9b89cfa0577b9d4b10215cec6b191c595c3d3 100644 (file)
--- a/datasette_pytables/__init__.py
+++ b/datasette_pytables/__init__.py
@@ -251,6 +251,7 @@ class Connection:
         else:
             raise Exception("SQLite queries cannot be executed with this connector")
 
+
 class Row(list):
     def __init__(self, values=None):
         self.labels = []