Add docstrings

Author: jferard

sqliteondbf/__main__.py

@@ -24,6 +24,7 @@
 from executor import SQLiteExecutor as _SQLiteExecutor, connect, convert, export, view, dump
 
 def execute(script, logger=logging.getLogger("sqliteondbf")):
+ """execute a sqlite3 script on a DBF base"""
  _SQLiteExecutor(script, logger).execute()
 
 def _get_args():
@@ -38,6 +39,7 @@ def _get_args():
  return parser.parse_args()
 
 def main():
+ """sqliteondbf main function"""
  args = _get_args()
  if args.quiet:
  logging.basicConfig(level=logging.ERROR)

sqliteondbf/converter.py

@@ -24,11 +24,13 @@
 import dbfread
 
 class SQLiteConverter():
+ """A converter from dbf to sqlite3"""
  def __init__(self, connection = sqlite3.connect(":memory:"), logger=logging.getLogger("sqliteondbf")):
  self.__connection = connection
  self.__logger = logger
 
  def import_dbf(self, dbf_path, lowernames=True, encoding="cp850", char_decode_errors="strict"):
+ """Import a dbf database to the current sqlite connection"""
  cursor = self.__connection.cursor()
 
  for fpath in self.__dbf_files(dbf_path):
@@ -46,6 +48,7 @@ def __dbf_files(self, dbf_path):
  yield os.path.join(root, name)
 
 class SQLiteConverterWorker():
+ """The worker: converts a dbf table and add the table to the current connection"""
  __typemap = {
  'F': 'FLOAT',
  'L': 'BOOLEAN',
@@ -64,6 +67,7 @@ def __init__(self, logger, cursor, dbf_table):
  self.__dbf_table = dbf_table
 
  def import_dbf_file(self):
+ """Import the file"""
  try:
  self.__add_sqlite_table()
  except UnicodeDecodeError as err:

sqliteondbf/executor.py

@@ -23,10 +23,11 @@
 import csv
 import sys
 
-from splitter import SemicolonSplitter as _SemicolonSplitter
+from splitter import Splitter as _Splitter
 from converter import SQLiteConverter as _SQLiteConverter
 
 class SQLiteExecutor():
+ """A script executor: executes a sqlite script on a dbf database"""
  def __init__(self, script, logger):
  if type(script) == str:
  self.__script = script
@@ -45,7 +46,8 @@ def __init__(self, script, logger):
  }
 
  def execute(self):
- for e in _SemicolonSplitter().split(self.__script):
+ """Execute the script"""
+ for e in _Splitter().split(self.__script):
  e = e.strip()
  if not e:
  continue
@@ -146,15 +148,18 @@ def __get_args(self, e):
  return shlex.split(e)
 
 def connect(dbf_path, logger=logging.getLogger("sqliteondbf"), lowernames=True, encoding="cp850", char_decode_errors="strict"):
+ """take a dBase (= set of dbf files) directory and return a SQLite connection over the database"""
  return convert(dbf_path, ":memory:", logger=logger, lowernames=lowernames, encoding=encoding, char_decode_errors=char_decode_errors)
 
 def convert(dbf_path, sqlite_path, logger=logging.getLogger("sqliteondbf"), lowernames=True, encoding="cp850", char_decode_errors="strict"):
+ """convert a dBase (= set of dbf files) directory to a SQLite file and return a SQLite connection over the database"""
  logger.info("import {} to {}".format(dbf_path, sqlite_path))
  connection = sqlite3.connect(sqlite_path)
  _SQLiteConverter(connection, logger).import_dbf(dbf_path, encoding=encoding, lowernames=lowernames, char_decode_errors=char_decode_errors)
  return connection
 
 def export(cursor, csv_path, logger=logging.getLogger("sqliteondbf")):
+ """export the result of the last query to a csv file"""
  logger.info("export data to {}".format(csv_path))
  with open(csv_path, 'w', newline='', encoding='utf-8') as dest:
  writer = csv.writer(dest)
@@ -163,6 +168,7 @@ def export(cursor, csv_path, logger=logging.getLogger("sqliteondbf")):
  writer.writerow(row)
 
 def view(cursor, limit, logger=logging.getLogger("sqliteondbf"), file=sys.stdout):
+ """print the result of the last query"""
  logger.debug("display data on terminal")
  column_names = [description[0] for description in cursor.description]
  if limit >= 0:
@@ -175,7 +181,8 @@ def view(cursor, limit, logger=logging.getLogger("sqliteondbf"), file=sys.stdout
  if cursor.fetchone():
  print ("...", file=file)
 
-def dump(dest, connection):
- with open(dest, 'w', encoding="utf-8", newline="\n") as f:
+def dump(sqlite_path, connection):
+ """dump the database to a SQLite file"""
+ with open(sqlite_path, 'w', encoding="utf-8", newline="\n") as f:
  for line in connection.iterdump():
  f.write(line+"\n")

sqliteondbf/splitter.py

@@ -14,7 +14,9 @@
  along with this program. If not, see <http://www.gnu.org/licenses/>.
  """
 
-class SemicolonSplitter():
+class Splitter():
+ """A splitter: splits a script into separate chunks. By default, the
+ separator is the semicolon. Ignores separators in comments or strings"""
  __NONE = 0
 
  __OPEN_BLOCK_COMMENT_C1 = 10
@@ -38,60 +40,60 @@ def __init__(self, block_comment=("/*", "*/"), line_comment="--", splitter=";"):
 
  def split(self, script):
  cur_chunk = []
- state = SemicolonSplitter.__NONE
+ state = Splitter.__NONE
  for c in script:
- if state == SemicolonSplitter.__NONE:
+ if state == Splitter.__NONE:
  if c == self.__block_comment[0][0]:
- state = SemicolonSplitter.__OPEN_BLOCK_COMMENT_C1
+ state = Splitter.__OPEN_BLOCK_COMMENT_C1
  elif c == self.__line_comment[0]:
- state = SemicolonSplitter.__OPEN_LINE_COMMENT_C1
+ state = Splitter.__OPEN_LINE_COMMENT_C1
  elif c == "\"":
- state = SemicolonSplitter.__DOUBLE_QUOTED
+ state = Splitter.__DOUBLE_QUOTED
  elif c == "'":
- state = SemicolonSplitter.__SINGLE_QUOTED
+ state = Splitter.__SINGLE_QUOTED
  elif c == self.__splitter:
  chunk = "".join(cur_chunk).strip()
  if chunk:
  yield chunk
  cur_chunk = []
  continue
- elif state == SemicolonSplitter.__OPEN_BLOCK_COMMENT_C1:
+ elif state == Splitter.__OPEN_BLOCK_COMMENT_C1:
  if c == self.__block_comment[0][1]:
- state = SemicolonSplitter.__BLOCK_COMMENT_OPENED
+ state = Splitter.__BLOCK_COMMENT_OPENED
  else:
- state = SemicolonSplitter.__NONE
- elif state == SemicolonSplitter.__BLOCK_COMMENT_OPENED:
+ state = Splitter.__NONE
+ elif state == Splitter.__BLOCK_COMMENT_OPENED:
  if c == self.__block_comment[1][0]:
- state = SemicolonSplitter.__BLOCK_COMMENT_OPENED_CLOSE_BLOCK_COMMENT_C1
- elif state == SemicolonSplitter.__BLOCK_COMMENT_OPENED_CLOSE_BLOCK_COMMENT_C1:
+ state = Splitter.__BLOCK_COMMENT_OPENED_CLOSE_BLOCK_COMMENT_C1
+ elif state == Splitter.__BLOCK_COMMENT_OPENED_CLOSE_BLOCK_COMMENT_C1:
  if c == self.__block_comment[1][1]:
  cur_chunk = []
- state = SemicolonSplitter.__NONE
+ state = Splitter.__NONE
  continue
- elif state == SemicolonSplitter.__OPEN_LINE_COMMENT_C1:
+ elif state == Splitter.__OPEN_LINE_COMMENT_C1:
  if c == self.__line_comment[1]:
- state = SemicolonSplitter.__LINE_COMMENT_OPENED
+ state = Splitter.__LINE_COMMENT_OPENED
  else:
- state = SemicolonSplitter.__NONE
- elif state == SemicolonSplitter.__LINE_COMMENT_OPENED:
+ state = Splitter.__NONE
+ elif state == Splitter.__LINE_COMMENT_OPENED:
  if c == "\n":
  cur_chunk = []
- state = SemicolonSplitter.__NONE
+ state = Splitter.__NONE
  continue
- elif state == SemicolonSplitter.__DOUBLE_QUOTED:
+ elif state == Splitter.__DOUBLE_QUOTED:
  if c == "\\":
- state = SemicolonSplitter.__DOUBLE_QUOTED_ESCAPE
+ state = Splitter.__DOUBLE_QUOTED_ESCAPE
  if c == "\"":
- state = SemicolonSplitter.__NONE
- elif state == SemicolonSplitter.__DOUBLE_QUOTED_ESCAPE:
- state = SemicolonSplitter.__DOUBLE_QUOTED;
- elif state == SemicolonSplitter.__SINGLE_QUOTED:
+ state = Splitter.__NONE
+ elif state == Splitter.__DOUBLE_QUOTED_ESCAPE:
+ state = Splitter.__DOUBLE_QUOTED;
+ elif state == Splitter.__SINGLE_QUOTED:
  if c == "\\":
- state = SemicolonSplitter.__SINGLE_QUOTED_ESCAPE
+ state = Splitter.__SINGLE_QUOTED_ESCAPE
  if c == "'":
- state = SemicolonSplitter.__NONE
- elif state == SemicolonSplitter.__SINGLE_QUOTED_ESCAPE:
- state = SemicolonSplitter.__SINGLE_QUOTED;
+ state = Splitter.__NONE
+ elif state == Splitter.__SINGLE_QUOTED_ESCAPE:
+ state = Splitter.__SINGLE_QUOTED;
 
  cur_chunk.append(c)
 

test/splitter_test.py

@@ -18,7 +18,7 @@
 import sqliteondbf.splitter as sp
 import unittest
 
-class SemicolonSplitterTest(unittest.TestCase):
+class SplitterTest(unittest.TestCase):
  def test(self):
  text="""
  a semicolon "in a double quoted (\\") string;" is not a separation
@@ -32,7 +32,7 @@ def test(self):
  this is one;
  """
 
- l = list(sp.SemicolonSplitter().split(text))
+ l = list(sp.Splitter().split(text))
  self.assertEquals(
  ['a semicolon "in a double quoted (\\") string;" is not a separation\n this is one',
  "a semicolon 'in a single quoted (\\') string;' is not a separation\n this is one",