Update API docs (PyMySQL#573)

scchess · May 24, 2017 · 73c22c7 · 73c22c7
1 parent c364263
commit 73c22c7
Show file tree

Hide file tree

Showing 6 changed files with 78 additions and 60 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -18,7 +18,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../../'))
 
 # -- General configuration ------------------------------------------------
 

diff --git a/docs/source/modules/connections.rst b/docs/source/modules/connections.rst
@@ -1,6 +1,11 @@
-:mod:`pymysql.connections`
-==========================
+Connection Object
+=================
 
-.. automodule:: pymysql.connections
+.. module:: pymysql.connections
 
 .. autoclass:: Connection
+   :members:
+   :exclude-members: DataError, DatabaseError, Error, InterfaceError,
+                     IntegrityError, InternalError, NotSupportedError,
+                     OperationalError, ProgrammingError, Warning,
+                     escape, literal, write_packet
diff --git a/docs/source/modules/cursors.rst b/docs/source/modules/cursors.rst
@@ -1,7 +1,19 @@
-:mod:`pymysql.cursors`
-======================
+Cursor Objects
+==============
 
-.. automodule:: pymysql.cursors
+.. module:: pymysql.cursors
 
 .. autoclass:: Cursor
+   :members:
+   :exclude-members: DataError, DatabaseError, Error, InterfaceError,
+                     IntegrityError, InternalError, NotSupportedError,
+                     OperationalError, ProgrammingError, Warning
+
 .. autoclass:: SSCursor
+   :members:
+
+.. autoclass:: DictCursor
+   :members:
+
+.. autoclass:: SSDictCursor
+   :members:
diff --git a/docs/source/modules/index.rst b/docs/source/modules/index.rst
@@ -4,6 +4,9 @@ API Reference
 If you are looking for information on a specific function, class or
 method, this part of the documentation is for you.
 
+For more information, please read the `Python Database API specification
+<https://www.python.org/dev/peps/pep-0249>`_.
+
 .. toctree::
   :maxdepth: 2
 

diff --git a/pymysql/connections.py b/pymysql/connections.py
@@ -520,6 +520,54 @@ class Connection(object):
 
     The proper way to get an instance of this class is to call
     connect().
+
+    Establish a connection to the MySQL database. Accepts several
+    arguments:
+
+    :param host: Host where the database server is located
+    :param user: Username to log in as
+    :param password: Password to use.
+    :param database: Database to use, None to not use a particular one.
+    :param port: MySQL port to use, default is usually OK. (default: 3306)
+    :param bind_address: When the client has multiple network interfaces, specify
+        the interface from which to connect to the host. Argument can be
+        a hostname or an IP address.
+    :param unix_socket: Optionally, you can use a unix socket rather than TCP/IP.
+    :param charset: Charset you want to use.
+    :param sql_mode: Default SQL_MODE to use.
+    :param read_default_file:
+        Specifies  my.cnf file to read these parameters from under the [client] section.
+    :param conv:
+        Conversion dictionary to use instead of the default one.
+        This is used to provide custom marshalling and unmarshaling of types.
+        See converters.
+    :param use_unicode:
+        Whether or not to default to unicode strings.
+        This option defaults to true for Py3k.
+    :param client_flag: Custom flags to send to MySQL. Find potential values in constants.CLIENT.
+    :param cursorclass: Custom cursor class to use.
+    :param init_command: Initial SQL statement to run when connection is established.
+    :param connect_timeout: Timeout before throwing an exception when connecting.
+        (default: 10, min: 1, max: 31536000)
+    :param ssl:
+        A dict of arguments similar to mysql_ssl_set()'s parameters.
+        For now the capath and cipher arguments are not supported.
+    :param read_default_group: Group to read from in the configuration file.
+    :param compress: Not supported
+    :param named_pipe: Not supported
+    :param autocommit: Autocommit mode. None means use server default. (default: False)
+    :param local_infile: Boolean to enable the use of LOAD DATA LOCAL command. (default: False)
+    :param max_allowed_packet: Max size of packet sent to server in bytes. (default: 16MB)
+        Only used to limit size of "LOAD LOCAL INFILE" data packet smaller than default (16KB).
+    :param defer_connect: Don't explicitly connect on contruction - wait for connect call.
+        (default: False)
+    :param auth_plugin_map: A dict of plugin names to a class that processes that plugin.
+        The class will take the Connection object as the argument to the constructor.
+        The class needs an authenticate method taking an authentication packet as
+        an argument.  For the dialog plugin, a prompt(echo, prompt) method can be used
+        (if no authenticate method) for returning a string from the user. (experimental)
+    :param db: Alias for database. (for compatibility to MySQLdb)
+    :param passwd: Alias for password. (for compatibility to MySQLdb)
     """
 
     _sock = None
@@ -537,55 +585,6 @@ def __init__(self, host=None, user=None, password="",
                  max_allowed_packet=16*1024*1024, defer_connect=False,
                  auth_plugin_map={}, read_timeout=None, write_timeout=None,
                  bind_address=None):
-        """
-        Establish a connection to the MySQL database. Accepts several
-        arguments:
-
-        host: Host where the database server is located
-        user: Username to log in as
-        password: Password to use.
-        database: Database to use, None to not use a particular one.
-        port: MySQL port to use, default is usually OK. (default: 3306)
-        bind_address: When the client has multiple network interfaces, specify
-            the interface from which to connect to the host. Argument can be
-            a hostname or an IP address.
-        unix_socket: Optionally, you can use a unix socket rather than TCP/IP.
-        charset: Charset you want to use.
-        sql_mode: Default SQL_MODE to use.
-        read_default_file:
-            Specifies  my.cnf file to read these parameters from under the [client] section.
-        conv:
-            Conversion dictionary to use instead of the default one.
-            This is used to provide custom marshalling and unmarshaling of types.
-            See converters.
-        use_unicode:
-            Whether or not to default to unicode strings.
-            This option defaults to true for Py3k.
-        client_flag: Custom flags to send to MySQL. Find potential values in constants.CLIENT.
-        cursorclass: Custom cursor class to use.
-        init_command: Initial SQL statement to run when connection is established.
-        connect_timeout: Timeout before throwing an exception when connecting.
-            (default: 10, min: 1, max: 31536000)
-        ssl:
-            A dict of arguments similar to mysql_ssl_set()'s parameters.
-            For now the capath and cipher arguments are not supported.
-        read_default_group: Group to read from in the configuration file.
-        compress; Not supported
-        named_pipe: Not supported
-        autocommit: Autocommit mode. None means use server default. (default: False)
-        local_infile: Boolean to enable the use of LOAD DATA LOCAL command. (default: False)
-        max_allowed_packet: Max size of packet sent to server in bytes. (default: 16MB)
-            Only used to limit size of "LOAD LOCAL INFILE" data packet smaller than default (16KB).
-        defer_connect: Don't explicitly connect on contruction - wait for connect call.
-            (default: False)
-        auth_plugin_map: A dict of plugin names to a class that processes that plugin.
-            The class will take the Connection object as the argument to the constructor.
-            The class needs an authenticate method taking an authentication packet as
-            an argument.  For the dialog plugin, a prompt(echo, prompt) method can be used
-            (if no authenticate method) for returning a string from the user. (experimental)
-        db: Alias for database. (for compatibility to MySQLdb)
-        passwd: Alias for password. (for compatibility to MySQLdb)
-        """
         if no_delay is not None:
             warnings.warn("no_delay option is deprecated", DeprecationWarning)
 

diff --git a/pymysql/cursors.py b/pymysql/cursors.py
@@ -21,6 +21,9 @@
 class Cursor(object):
     """
     This is the object you use to interact with the database.
+
+    Do not create an instance of a Cursor yourself. Call
+    connections.Connection.cursor().
     """
 
     #: Max statement size which :meth:`executemany` generates.
@@ -32,10 +35,6 @@ class Cursor(object):
     _defer_warnings = False
 
     def __init__(self, connection):
-        """
-        Do not create an instance of a Cursor yourself. Call
-        connections.Connection.cursor().
-        """
         self.connection = connection
         self.description = None
         self.rownumber = 0