postgresql_idx: add docstrings, remove extra doc lines (ansible#57670)

lib/ansible/modules/database/postgresql/postgresql_idx.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright: (c) 2018, Andrey Klychkov (@Andersson007) <[email protected]>
+# Copyright: (c) 2018-2019, Andrey Klychkov (@Andersson007) <[email protected]>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
@@ -114,20 +114,10 @@
 notes:
 - The index building process can affect database performance.
 - To avoid table locks on production databases, use I(concurrent=yes) (default behavior).
-- The default authentication assumes that you are either logging in as or
-  sudo'ing to the postgres account on the host.
-- This module uses psycopg2, a Python PostgreSQL database adapter. You must
-  ensure that psycopg2 is installed on the host before using this module.
-- If the remote host is the PostgreSQL server (which is the default case), then
-  PostgreSQL must also be installed on the remote host.
-- For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages
-  on the remote host before using this module.
-
-requirements:
-- psycopg2
 
 author:
 - Andrew Klychkov (@Andersson007)
+
 extends_documentation_fragment: postgres
 '''
 
@@ -250,6 +240,32 @@
 #
 
 class Index(object):
+
+    """Class for working with PostgreSQL indexes.
+
+    TODO:
+        1. Add possibility to change ownership
+        2. Add possibility to change tablespace
+        3. Add list called executed_queries (executed_query should be left too)
+        4. Use self.module instead of passing arguments to the methods whenever possible
+        5. Remove self.__exec_sql and use module_utils.postgres.exec_sql instead
+
+    Args:
+        module (AnsibleModule) -- object of AnsibleModule class
+        cursor (cursor) -- cursor object of psycopg2 library
+        schema (str) -- name of the index schema
+        name (str) -- name of the index
+
+    Attrs:
+        module (AnsibleModule) -- object of AnsibleModule class
+        cursor (cursor) -- cursor object of psycopg2 library
+        schema (str) -- name of the index schema
+        name (str) -- name of the index
+        exists (bool) -- flag the index exists in the DB or not
+        info (dict) -- dict that contents information about the index
+        executed_query (str) -- executed query
+    """
+
     def __init__(self, module, cursor, schema, name):
         self.name = name
         if schema:
@@ -272,16 +288,20 @@ def __init__(self, module, cursor, schema, name):
         self.executed_query = ''
 
     def get_info(self):
+        """Refresh index info.
+
+        Return self.info dict.
         """
-        Getter to refresh and return table info
-        """
+
         self.__exists_in_db()
         return self.info
 
     def __exists_in_db(self):
+        """Check index existence, collect info, add it to self.info dict.
+
+        Return True if the index exists, otherwise, return False.
         """
-        Check index and collect info
-        """
+
         query = ("SELECT i.schemaname, i.tablename, i.tablespace, "
                  "pi.indisvalid, c.reloptions "
                  "FROM pg_catalog.pg_indexes AS i "
@@ -310,11 +330,20 @@ def __exists_in_db(self):
             return False
 
     def create(self, tblname, idxtype, columns, cond, tblspace, storage_params, concurrent=True):
+        """Create PostgreSQL index.
+
+        Return True if success, otherwise, return False.
+
+        Args:
+            tblname (str) -- name of a table for the index
+            idxtype (str) -- type of the index like BTREE, BRIN, etc
+            columns (str) -- string of comma-separated columns that need to be covered by index
+            tblspace (str) -- tablespace for storing the index
+            storage_params (str) -- string of comma-separated storage parameters
+
+        Kwargs:
+            concurrent (bool) -- build index in concurrent mode, default True
         """
-        Create PostgreSQL index.
-        """
-        # To change existing index we should write
-        # 'postgresql_alter_table' standalone module.
 
         if self.exists:
             return False
@@ -354,8 +383,17 @@ def create(self, tblname, idxtype, columns, cond, tblspace, storage_params, conc
         return False
 
     def drop(self, schema, cascade=False, concurrent=True):
-        """
-        Drop PostgreSQL index.
+        """Drop PostgreSQL index.
+
+        Return True if success, otherwise, return False.
+
+        Args:
+            schema (str) -- name of the index schema
+
+        Kwargs:
+            cascade (bool) -- automatically drop objects that depend on the index,
+                default False
+            concurrent (bool) -- build index in concurrent mode, default True
         """
 
         changed = False