Skip to content

Improve docstrings #954

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 2, 2021
Merged

Improve docstrings #954

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 23 additions & 23 deletions pymysql/connections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,18 +99,18 @@ class Connection:
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 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 unix_socket: Use a unix socket rather than TCP/IP.
:param read_timeout: The timeout for reading from the connection in seconds (default: None - no timeout)
:param write_timeout: The timeout for writing to the connection in seconds (default: None - no timeout)
:param charset: Charset you want to use.
:param charset: Charset 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.
Expand All @@ -124,16 +124,15 @@ class Connection:
: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.
:param connect_timeout: The timeout for connecting to the database in seconds.
(default: 10, min: 1, max: 31536000)
:param ssl:
A dict of arguments similar to mysql_ssl_set()'s parameters.
:param ssl_ca: Path to the file that contains a PEM-formatted CA certificate
:param ssl_cert: Path to the file that contains a PEM-formatted client certificate
:param ssl_disabled: A boolean value that disables usage of TLS
:param ssl_key: Path to the file that contains a PEM-formatted private key for the client certificate
:param ssl_verify_cert: Set to true to check the validity of server certificates
:param ssl_verify_identity: Set to true to check the server's identity
:param ssl: A dict of arguments similar to mysql_ssl_set()'s parameters.
:param ssl_ca: Path to the file that contains a PEM-formatted CA certificate.
:param ssl_cert: Path to the file that contains a PEM-formatted client certificate.
:param ssl_disabled: A boolean value that disables usage of TLS.
:param ssl_key: Path to the file that contains a PEM-formatted private key for the client certificate.
:param ssl_verify_cert: Set to true to check the server certificate's validity.
:param ssl_verify_identity: Set to true to check the server's identity.
:param read_default_group: Group to read from in the configuration file.
: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)
Expand All @@ -148,8 +147,8 @@ class Connection:
(if no authenticate method) for returning a string from the user. (experimental)
:param server_public_key: SHA256 authentication plugin public key value. (default: None)
:param binary_prefix: Add _binary prefix on bytes and bytearray. (default: False)
:param compress: Not supported
:param named_pipe: Not supported
:param compress: Not supported.
:param named_pipe: Not supported.
:param db: **DEPRECATED** Alias for database.
:param passwd: **DEPRECATED** Alias for password.

Expand Down Expand Up @@ -415,11 +414,11 @@ def close(self):

@property
def open(self):
"""Return True if the connection is open"""
"""Return True if the connection is open."""
return self._sock is not None

def _force_close(self):
"""Close connection without QUIT message"""
"""Close connection without QUIT message."""
if self._sock:
try:
self._sock.close()
Expand Down Expand Up @@ -448,7 +447,7 @@ def _read_ok_packet(self):
return ok

def _send_autocommit_mode(self):
"""Set whether or not to commit after every execute()"""
"""Set whether or not to commit after every execute()."""
self._execute_command(
COMMAND.COM_QUERY, "SET AUTOCOMMIT = %s" % self.escape(self.autocommit_mode)
)
Expand Down Expand Up @@ -496,7 +495,7 @@ def select_db(self, db):
self._read_ok_packet()

def escape(self, obj, mapping=None):
"""Escape whatever value you pass to it.
"""Escape whatever value is passed.

Non-standard, for internal use; do not use this in your applications.
"""
Expand All @@ -510,7 +509,7 @@ def escape(self, obj, mapping=None):
return converters.escape_item(obj, self.charset, mapping=mapping)

def literal(self, obj):
"""Alias for escape()
"""Alias for escape().

Non-standard, for internal use; do not use this in your applications.
"""
Expand All @@ -530,9 +529,8 @@ def cursor(self, cursor=None):
"""
Create a new cursor to execute queries with.

:param cursor: The type of cursor to create; one of :py:class:`Cursor`,
:py:class:`SSCursor`, :py:class:`DictCursor`, or :py:class:`SSDictCursor`.
None means use Cursor.
:param cursor: The type of cursor to create. None means use Cursor.
:type cursor: :py:class:`Cursor`, :py:class:`SSCursor`, :py:class:`DictCursor`, or :py:class:`SSDictCursor`.
"""
if cursor:
return cursor(self)
Expand Down Expand Up @@ -565,6 +563,8 @@ def ping(self, reconnect=True):
Check if the server is alive.

:param reconnect: If the connection is closed, reconnect.
:type reconnect: boolean

:raise Error: If the connection is closed and reconnect=False.
"""
if self._sock is None:
Expand Down
56 changes: 36 additions & 20 deletions pymysql/cursors.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

class Cursor:
"""
This is the object you use to interact with the database.
This is the object used to interact with the database.

Do not create an instance of a Cursor yourself. Call
connections.Connection.cursor().
Expand Down Expand Up @@ -79,7 +79,7 @@ def setoutputsizes(self, *args):
"""Does nothing, required by DB API."""

def _nextset(self, unbuffered=False):
"""Get the next query set"""
"""Get the next query set."""
conn = self._get_db()
current_result = self._result
if current_result is None or current_result is not conn._result:
Expand Down Expand Up @@ -114,9 +114,18 @@ def _escape_args(self, args, conn):

def mogrify(self, query, args=None):
"""
Returns the exact string that is sent to the database by calling the
Returns the exact string that would be sent to the database by calling the
execute() method.

:param query: Query to mogrify.
:type query: str

:param args: Parameters used with query. (optional)
:type args: tuple, list or dict

:return: The query with argument binding applied.
:rtype: str

This method follows the extension to the DB API 2.0 followed by Psycopg.
"""
conn = self._get_db()
Expand All @@ -127,14 +136,15 @@ def mogrify(self, query, args=None):
return query

def execute(self, query, args=None):
"""Execute a query
"""Execute a query.

:param str query: Query to execute.
:param query: Query to execute.
:type query: str

:param args: parameters used with query. (optional)
:param args: Parameters used with query. (optional)
:type args: tuple, list or dict

:return: Number of affected rows
:return: Number of affected rows.
:rtype: int

If args is a list or tuple, %s can be used as a placeholder in the query.
Expand All @@ -150,12 +160,16 @@ def execute(self, query, args=None):
return result

def executemany(self, query, args):
# type: (str, list) -> int
"""Run several data against one query
"""Run several data against one query.

:param query: Query to execute.
:type query: str

:param args: Sequence of sequences or mappings. It is used as parameter.
:type args: tuple or list

:param query: query to execute on server
:param args: Sequence of sequences or mappings. It is used as parameter.
:return: Number of rows affected, if any.
:rtype: int or None

This method improves performance on multiple-row INSERT and
REPLACE. Otherwise it is equivalent to looping over args with
Expand Down Expand Up @@ -213,11 +227,13 @@ def _do_execute_many(
return rows

def callproc(self, procname, args=()):
"""Execute stored procedure procname with args
"""Execute stored procedure procname with args.

procname -- string, name of procedure to execute on server
:param procname: Name of procedure to execute on server.
:type procname: str

args -- Sequence of parameters to use with procedure
:param args: Sequence of parameters to use with procedure.
:type args: tuple or list

Returns the original args.

Expand Down Expand Up @@ -260,7 +276,7 @@ def callproc(self, procname, args=()):
return args

def fetchone(self):
"""Fetch the next row"""
"""Fetch the next row."""
self._check_executed()
if self._rows is None or self.rownumber >= len(self._rows):
return None
Expand All @@ -269,7 +285,7 @@ def fetchone(self):
return result

def fetchmany(self, size=None):
"""Fetch several rows"""
"""Fetch several rows."""
self._check_executed()
if self._rows is None:
return ()
Expand All @@ -279,7 +295,7 @@ def fetchmany(self, size=None):
return result

def fetchall(self):
"""Fetch all the rows"""
"""Fetch all the rows."""
self._check_executed()
if self._rows is None:
return ()
Expand Down Expand Up @@ -418,11 +434,11 @@ def nextset(self):
return self._nextset(unbuffered=True)

def read_next(self):
"""Read next row"""
"""Read next row."""
return self._conv_row(self._result._read_rowdata_packet_unbuffered())

def fetchone(self):
"""Fetch next row"""
"""Fetch next row."""
self._check_executed()
row = self.read_next()
if row is None:
Expand Down Expand Up @@ -450,7 +466,7 @@ def __iter__(self):
return self.fetchall_unbuffered()

def fetchmany(self, size=None):
"""Fetch many"""
"""Fetch many."""
self._check_executed()
if size is None:
size = self.arraysize
Expand Down