Merge pull request #25 from twindb/doc-fixes

Documentation update

HISTORY.rst

@@ -2,6 +2,13 @@
 History
 =======
 
+3.0.2 (2020-09-13)
+------------------
+
+* Python 3 support
+* Command line tool renamed to twindb-table-compare
+
+
 0.1.0 (2016-08-29)
 ------------------
 

README.rst

@@ -2,27 +2,18 @@
 TwinDB Table Compare
 ====================
 
-.. image:: https://badges.gitter.im/twindb/twindb_table_compare.svg
-   :alt: Join the chat at https://gitter.im/twindb/twindb_table_compare
-   :target: https://gitter.im/twindb/twindb_table_compare?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
-
-
 .. image:: https://img.shields.io/pypi/v/twindb_table_compare.svg
         :target: https://pypi.python.org/pypi/twindb_table_compare
 
-.. image:: https://img.shields.io/travis/twindb/twindb_table_compare.svg
-        :target: https://travis-ci.org/twindb/twindb_table_compare
-
-.. image:: https://img.shields.io/codecov/c/github/twindb/twindb_table_compare.svg
-        :target: https://codecov.io/gh/twindb/twindb_table_compare
-        :alt: Code test coverage
+.. image:: https://img.shields.io/travis/twindb/twindb-table-compare.svg
+        :target: https://travis-ci.org/twindb/twindb-table-compare
 
 .. image:: https://readthedocs.org/projects/twindb-table-compare/badge/?version=master
         :target: https://twindb-table-compare.readthedocs.io/en/master/?badge=master
         :alt: Documentation Status
 
-.. image:: https://pyup.io/repos/github/twindb/twindb_table_compare/shield.svg
-     :target: https://pyup.io/repos/github/twindb/twindb_table_compare/
+.. image:: https://pyup.io/repos/github/twindb/twindb-table-compare/shield.svg
+     :target: https://pyup.io/repos/github/twindb/twindb-table-compare/
      :alt: Updates
 
 .. image:: https://img.shields.io/pypi/dd/Django.svg?maxAge=2592000

docs/index.rst

@@ -15,6 +15,7 @@ Contents:
    installation
    usage
    modules
+   history
    contributing
    authors
 

docs/installation.rst

@@ -5,14 +5,19 @@ Installation
 ============
 
 
+Supported Python versions
+-------------------------
+
+* Python 3.6, 3.7, and 3.8 are supported.
+
 Stable release
 --------------
 
 To install TwinDB Table Compare, run this command in your terminal:
 
 .. code-block:: console
 
-    $ pip install twindb_table_compare
+    $ pip install twindb-table-compare
 
 This is the preferred method to install TwinDB Table Compare, as it will always install the most recent stable release.
 
@@ -32,13 +37,13 @@ You can either clone the public repository:
 
 .. code-block:: console
 
-    $ git clone git://github.com/twindb/twindb_table_compare
+    $ git clone https://github.com/twindb/twindb-table-compare.git
 
 Or download the `tarball`_:
 
 .. code-block:: console
 
-    $ curl  -OL https://github.com/twindb/twindb_table_compare/tarball/master
+    $ curl  -OL https://github.com/twindb/twindb-table-compare/tarball/master
 
 Once you have a copy of the source, you can install it with:
 
@@ -47,5 +52,5 @@ Once you have a copy of the source, you can install it with:
     $ python setup.py install
 
 
-.. _Github repo: https://github.com/twindb/twindb_table_compare
-.. _tarball: https://github.com/twindb/twindb_table_compare/tarball/master
+.. _Github repo: https://github.com/twindb/twindb-table-compare
+.. _tarball: https://github.com/twindb/twindb-table-compare/tarball/master

docs/modules.rst

@@ -0,0 +1,7 @@
+twindb_table_compare
+====================
+
+.. toctree::
+   :maxdepth: 4
+
+   twindb_table_compare

docs/twindb_table_compare.rst

@@ -0,0 +1,30 @@
+twindb\_table\_compare package
+==============================
+
+Submodules
+----------
+
+twindb\_table\_compare.cli module
+---------------------------------
+
+.. automodule:: twindb_table_compare.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+twindb\_table\_compare.compare module
+-------------------------------------
+
+.. automodule:: twindb_table_compare.compare
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: twindb_table_compare
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/usage.rst

@@ -3,16 +3,29 @@ Usage
 
 TwinDB Table Compare should be used in the command line.
 
-This will show differences in data between *slave* and its master.
 
-``twindb_table_compare`` *slave*
+.. note::
+
+    Before running TwinDB Table Compare tool, you should run ``pt-table-checksum`` first.
+    ``twindb-table-compare`` uses ``percona.checksums``. If you don't run ``pt-table-checksum``,
+    ``percona.checksums`` will be empty and thus ``twindb-table-compare`` won't show any differences.
+
+.. note::
+
+    ``twindb-table-compare`` should run agains the slave.
+
+This will show differences in data between a *slave* and its master.
+
+.. code-block:: shell
+
+    twindb-table-compare slave
 
 
 where *slave* is a hostname of a MySQL slave.
 
 ::
 
-    [root@master vagrant]# twindb_table_compare --user=dba --password=qwerty 192.168.35.251
+    # twindb-table-compare --user=dba --password=qwerty 192.168.35.251
     2016-09-03 22:48:01,732: INFO: twindb_table_compare.get_inconsistencies():127: Executing: SELECT chunk FROM `percona`.`checksums` WHERE (this_crc<>master_crc OR this_cnt<>master_cnt) AND db='mysql' AND tbl='proxies_priv'
     2016-09-03 22:48:01,734: INFO: twindb_table_compare.get_inconsistencies():138: Found 1 inconsistent chunk
     2016-09-03 22:48:01,734: INFO: twindb_table_compare.get_inconsistencies():141: # mysql.proxies_priv, chunk 1
@@ -48,4 +61,4 @@ where *slave* is a hostname of a MySQL slave.
      localhost dba *AA1420F182E88B9E5F874F6FBE7459291E8F4601 Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y 0 0 0 0mysql_native_password N
      % repl *809534247D21AC735802078139D8A854F45C31F3 N N N N N N N N N N N N N N N N N N N Y N N N N N N N N N 0 0 0 0 mysql_native_password N
 
-Run ``twindb_table_compare --help`` for other options.
+Run ``twindb-table-compare --help`` for other options.

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.0.2
+current_version = 3.0.3
 commit = True
 tag = False
 

setup.py

@@ -15,7 +15,7 @@
 
 setup(
     name="twindb_table_compare",
-    version="3.0.2",
+    version="3.0.3",
     description=(
         "TwinDB Table Compare reads percona.checksums from the master and slave "
         "and shows what records are difference if there are any inconsistencies."

twindb_table_compare/__init__.py

@@ -7,7 +7,7 @@
 
 __author__ = "Aleksandr Kuzminsky"
 __email__ = "[email protected]"
-__version__ = "3.0.2"
+__version__ = "3.0.3"
 
 LOG = logging.getLogger(__name__)
 

twindb_table_compare/compare.py

@@ -274,11 +274,11 @@ def primary_exists(conn, db, tbl):
 
 def get_boundary_clause(oper=">", index_fields=None, boundaries=None):
     """
-    Generate a clause for the WHERE statement based on field names and values
+    Generate a clause for the WHERE statement based on field names and values.
 
-    :param oper: Can be either ``<`` for the lower boundary or ``>``
-    for the upper boundary
-    :param index_fields: list of fields in the index
+    :param oper: Can be either ``<`` for the lower boundary
+        or ``>`` for the upper boundary.
+    :param index_fields: list of fields in the index.
     :type index_fields: list
     :param boundaries: list of values for a boundary.
     :type boundaries: list
@@ -317,15 +317,15 @@ def get_boundary_clause(oper=">", index_fields=None, boundaries=None):
 def get_where(lower_boundary, upper_boundary, index_fields):
     """
     Generate WHERE clause based on strings ``lower_boundary``,
-    ``upper_boundary`` from percona.checksums table and fields in the index
+    ``upper_boundary`` from ``percona.checksums`` table and fields in the index.
 
-    :param lower_boundary: values of lower boundary
+    :param lower_boundary: values of lower boundary.
     :type lower_boundary: str
-    :param upper_boundary: values of upper boundary
+    :param upper_boundary: values of upper boundary.
     :type upper_boundary: str
-    :param index_fields: list of fields in the index that was used
-    to access a chunk
-    :return: a WHERE clause to read a chunk
+    :param index_fields: list of fields in the index that was used.
+        to access a chunk.
+    :return: a WHERE clause to read a chunk.
     :rtype: str
     """
 
@@ -578,7 +578,7 @@ def get_inconsistent_tables(host, user, password, ch_db="percona", ch_tbl="check
     :param ch_db: Database where checksums are stored.
     :param ch_tbl: Table name where checksums are stored.
     :return: List of tuples with inconsistent tables.
-    Each tuple is database name, table name
+        Each tuple is database name, table name.
     :rtype: list
     """
     conn = connect(host=host, user=user, passwd=password)