8000 Improve docstrings · PyMySQL/PyMySQL@d127079 · GitHub
[go: up one dir, main page]
Skip to content

Commit d127079

Browse files
author
Rene Scheibe
committed
Improve docstrings
- dot at the end of descriptions - 3rd instead of 2nd person - more type information - minor rephrasing
1 parent 5a11bab commit d127079

File tree

2 files changed

+59
-43
lines changed

2 files changed

+59
-43
lines changed

‎pymysql/connections.py

+23-23
Original file line numberDiff line numberDiff line change
@@ -99,18 +99,18 @@ class Connection:
9999
Establish a connection to the MySQL database. Accepts several
100100
arguments:
101101
102-
:param host: Host where the database server is located
103-
:param user: Username to log in as
102+
:param host: Host where the database server is located.
103+
:param user: Username to log in as.
104104
:param password: Password to use.
105105
:param database: Database to use, None to not use a particular one.
106106
:param port: MySQL port to use, default is usually OK. (default: 3306)
107107
:param bind_address: When the client has multiple network interfaces, specify
108108
the interface from which to connect to the host. Argument can be
109109
a hostname or an IP address.
110-
:param unix_socket: Optionally, you can use a unix socket rather than TCP/IP.
110+
:param unix_socket: Optionally, a unix socket rather than TCP/IP can be used.
111111
:param read_timeout: The timeout for reading from the connection in seconds (default: None - no timeout)
112112
:param write_timeout: The timeout for writing to the connection in seconds (default: None - no timeout)
113-
:param charset: Charset you want to use.
113+
:param charset: Charset to use.
114114
:param sql_mode: Default SQL_MODE to use.
115115
:param read_default_file:
116116
Specifies my.cnf file to read these parameters from under the [client] section.
@@ -124,16 +124,15 @@ class Connection:
124124
:param client_flag: Custom flags to send to MySQL. Find potential values in constants.CLIENT.
125125
:param cursorclass: Custom cursor class to use.
126126
:param init_command: Initial SQL statement to run when connection is established.
127-
:param connect_timeout: Timeout before throwing an exception when connecting.
127+
:param connect_timeout: The timeout for connecting to the database in seconds.
128128
(default: 10, min: 1, max: 31536000)
129-
:param ssl:
130-
A dict of arguments similar to mysql_ssl_set()'s parameters.
131-
:param ssl_ca: Path to the file that contains a PEM-formatted CA certificate
132-
:param ssl_cert: Path to the file that contains a PEM-formatted client certificate
133-
:param ssl_disabled: A boolean value that disables usage of TLS
134-
:param ssl_key: Path to the file that contains a PEM-formatted private key for the client certificate
135-
:param ssl_verify_cert: Set to true to check the validity of server certificates
136-
:param ssl_verify_identity: Set to true to check the server's identity
129+
:param ssl: A dict of arguments similar to mysql_ssl_set()'s parameters.
130+
:param ssl_ca: Path to the file that contains a PEM-formatted CA certificate.
131+
:param ssl_cert: Path to the file that contains a PEM-formatted client certificate.
132+
:param ssl_disabled: A boolean value that disables usage of TLS.
133+
:param ssl_key: Path to the file that contains a PEM-formatted private key for the client certificate.
134+
:param ssl_verify_cert: Set to true to check the server certificate's validity.
135+
:param ssl_verify_identity: Set to true to check the server's identity.
137136
:param read_default_group: Group to read from in the configuration file.
138137
:param autocommit: Autocommit mode. None means use server default. (default: False)
139138
:param local_infile: Boolean to enable the use of LOAD DATA LOCAL command. (default: False)
@@ -148,8 +147,8 @@ class Connection:
148147
(if no authenticate method) for returning a string from the user. (experimental)
149148
:param server_public_key: SHA256 authentication plugin public key value. (default: None)
150149
:param binary_prefix: Add _binary prefix on bytes and bytearray. (default: False)
151-
:param compress: Not supported
152-
:param named_pipe: Not supported
150+
:param compress: Not supported.
151+
:param named_pipe: Not supported.
153152
:param db: **DEPRECATED** Alias for database.
154153
:param passwd: **DEPRECATED** Alias for password.
155154
@@ -415,11 +414,11 @@ def close(self):
415414

416415
@property
417416
def open(self):
418-
"""Return True if the connection is open"""
417+
"""Return True if the connection is open."""
419418
return self._sock is not None
420419

421420
def _force_close(self):
422-
"""Close connection without QUIT message"""
421+
"""Close connection without QUIT message."""
423422
if self._sock:
424423
try:
425424
self._sock.close()
@@ -448,7 +447,7 @@ def _read_ok_packet(self):
448447
return ok
449448

450449
def _send_autocommit_mode(self):
451-
"""Set whether or not to commit after every execute()"""
450+
"""Set whether or not to commit after every execute()."""
452451
self._execute_command(
453452
COMMAND.COM_QUERY, "SET AUTOCOMMIT = %s" % self.escape(self.autocommit_mode)
454453
)
@@ -496,7 +495,7 @@ def select_db(self, db):
496495
self._read_ok_packet()
497496

498497
def escape(self, obj, mapping=None):
499-
"""Escape whatever value you pass to it.
498+
"""Escape whatever value is passed.
500499
501500
Non-standard, for internal use; do not use this in your applications.
502501
"""
@@ -510,7 +509,7 @@ def escape(self, obj, mapping=None):
510509
return converters.escape_item(obj, self.charset, mapping=mapping)
511510

512511
def literal(self, obj):
513-
"""Alias for escape()
512+
"""Alias for escape().
514513
515514
Non-standard, for internal use; do not use this in your applications.
516515
"""
@@ -530,9 +529,8 @@ def cursor(self, cursor=None):
530529
"""
531530
Create a new cursor to execute queries with.
532531
533-
:param cursor: The type of cursor to create; one of :py:class:`Cursor`,
534-
:py:class:`SSCursor`, :py:class:`DictCursor`, or :py:class:`SSDictCursor`.
535-
None means use Cursor.
532+
:param cursor: The type of cursor to create. None means use Cursor.
533+
:type cursor: :py:class:`Cursor`, :py:class:`SSCursor`, :py:class:`DictCursor`, or :py:class:`SSDictCursor`.
536534
"""
537535
if cursor:
538536
return cursor(self)
@@ -565,6 +563,8 @@ def ping(self, reconnect=True):
565563
Check if the server is alive.
566564
567565
:param reconnect: If the connection is closed, reconnect.
566+
:type reconnect: boolean
567+
568568
:raise Error: If the connection is closed and reconnect=False.
569569
"""
570570
if self._sock is None:

‎pymysql/cursors.py

+36-20
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515

1616
class Cursor:
1717
"""
18-
This is the object you use to interact with the database.
18+
This is the object used to interact with the database.
1919
2020
Do not create an instance of a Cursor yourself. Call
2121
connections.Connection.cursor().
@@ -79,7 +79,7 @@ def setoutputsizes(self, *args):
7979
"""Does nothing, required by DB API."""
8080

8181
def _nextset(self, unbuffered=False):
82-
"""Get the next query set"""
82+
"""Get the next query set."""
8383
conn = self._get_db()
8484
current_result = self._result
8585
if current_result is None or current_result is not conn._result:
@@ -114,9 +114,18 @@ def _escape_args(self, args, conn):
114114

115115
def mogrify(self, query, args=None):
116116
"""
117-
Returns the exact string that is sent to the database by calling the
117+
Returns the exact string that would be sent to the database by calling the
118118
execute() method.
119119
120+
:param query: Query to mogrify.
121+
:type query: str
122+
123+
:param args: Parameters used with query. (optional)
124+
:type args: tuple, list or dict
125+
126+
:return: The query with argument binding applied.
127+
:rtype: str
128+
120129
This method follows the extension to the DB API 2.0 followed by Psycopg.
121130
"""
122131
conn = self._get_db()
@@ -127,14 +136,15 @@ def mogrify(self, query, args=None):
127136
return query
128137

129138
def execute(self, query, args=None):
130-
"""Execute a query
139+
"""Execute a query.
131140
132-
:param str query: Query to execute.
141+
:param query: Query to execute.
142+
:type query: str
133143
134-
:param args: parameters used with query. (optional)
144+
:param args: Parameters used with query. (optional)
135145
:type args: tuple, list or dict
136146
137-
:return: Number of affected rows
147+
:return: Number of affected rows.
138148
:rtype: int
139149
140150
If args is a list or tuple, %s can be used as a placeholder in the query.
@@ -150,12 +160,16 @@ def execute(self, query, args=None):
150160
return result
151161

152162
def executemany(self, query, args):
153-
# type: (str, list) -> int
154-
"""Run several data against one query
163+
"""Run several data against one query.
164+
165+
:param query: Query to execute.
166+
:type query: str
167+
168+
:param args: Sequence of sequences or mappings. It is used as parameter.
169+
:type args: tuple or list
155170
156-
:param query: query to execute on server
157-
:param args: Sequence of sequences or mappings. It is used as parameter.
158171
:return: Number of rows affected, if any.
172+
:rtype: int or None
159173
160174
This method improves performance on multiple-row INSERT and
161175
REPLACE. Otherwise it is equivalent to looping over args with
@@ -213,11 +227,13 @@ def _do_execute_many(
213227
return rows
214228

215229
def callproc(self, procname, args=()):
216-
"""Execute stored procedure procname with args
230+
"""Execute stored procedure procname with args.
217231
218-
procname -- string, name of procedure to execute on server
232+
:param procname: Name of procedure to execute on server.
233+
:type procname: str
219234
220-
args -- Sequence of parameters to use with procedure
235+
:param args: Sequence of parameters to use with procedure.
236+
:type args: tuple or list
221237
222238
Returns the original args.
223239
@@ -260,7 +276,7 @@ def callproc(self, procname, args=()):
260276
return args
261277

262278
def fetchone(self):
263-
"""Fetch the next row"""
279+
"""Fetch the next row."""
264280
self._check_executed()
265281
if self._rows is None or self.rownumber >= len(self._rows):
266282
return None
@@ -269,7 +285,7 @@ def fetchone(self):
269285
return result
270286

271287
def fetchmany(self, size=None):
272-
"""Fetch several rows"""
288+
"""Fetch several rows."""
273289
self._check_executed()
274290
if self._rows is None:
275291
return ()
@@ -279,7 +295,7 @@ def fetchmany(self, size=None):
279295
return result
280296

281297
def fetchall(self):
282-
"""Fetch all the rows"""
298+
"""Fetch all the rows."""
283299
self._check_executed()
284300
if self._rows is None:
285301
return ()
@@ -418,11 +434,11 @@ def nextset(self):
418434
return self._nextset(unbuffered=True)
419435

420436
def read_next(self):
421-
"""Read next row"""
437+
"""Read next row."""
422438
return self._conv_row(self._result._read_rowdata_packet_unbuffered())
423439

424440
def fetchone(self):
425-
"""Fetch next row"""
441+
"""Fetch next row."""
426442
self._check_executed()
427443
row = self.read_next()
428444
if row is None:
@@ -450,7 +466,7 @@ def __iter__(self):
450466
return self.fetchall_unbuffered()
451467

452468
def fetchmany(self, size=None):
453-
"""Fetch many"""
469+
"""Fetch many."""
454470
self._check_executed()
455471
if size is None:
456472
size = self.arraysize

0 commit comments

Comments
 (0)
0