diff --git a/python/ql/src/Exceptions/CatchingBaseException.qhelp b/python/ql/src/Exceptions/CatchingBaseException.qhelp
index 725f9ce465ba..bde17418aa76 100644
--- a/python/ql/src/Exceptions/CatchingBaseException.qhelp
+++ b/python/ql/src/Exceptions/CatchingBaseException.qhelp
@@ -45,10 +45,10 @@ leaving KeyboardInterrupt
to propagate.
-Python Language Reference: The try statement,
-Exceptions.
+Python Language Reference: The try statement,
+Exceptions.
M. Lutz, Learning Python, Section 35.3: Exception Design Tips and Gotchas, O'Reilly Media, 2013.
-Python Tutorial: Errors and Exceptions.
+Python Tutorial: Errors and Exceptions.
diff --git a/python/ql/src/Exceptions/EmptyExcept.qhelp b/python/ql/src/Exceptions/EmptyExcept.qhelp
index 9b7ef09643fb..f968c65af196 100644
--- a/python/ql/src/Exceptions/EmptyExcept.qhelp
+++ b/python/ql/src/Exceptions/EmptyExcept.qhelp
@@ -7,7 +7,7 @@
The loss of information can lead to hard to debug errors and incomplete log files.
It is even possible that ignoring an exception can cause a security vulnerability.
An empty except
block may be an indication that the programmer intended to
-handle the exception but never wrote the code to do so.
+handle the exception, but never wrote the code to do so.
@@ -15,7 +15,7 @@ handle the exception but never wrote the code to do so.
-In this example the program keeps running with the same privileges if it fails to drop to lower
+
In this example, the program keeps running with the same privileges if it fails to drop to lower
privileges.
diff --git a/python/ql/src/Expressions/CallToSuperWrongClass.qhelp b/python/ql/src/Expressions/CallToSuperWrongClass.qhelp
index dc88b1bea88c..7a2516329f4a 100644
--- a/python/ql/src/Expressions/CallToSuperWrongClass.qhelp
+++ b/python/ql/src/Expressions/CallToSuperWrongClass.qhelp
@@ -24,7 +24,7 @@ However, this may result in incorrect object initialization if the enclosing cla
-In this example the call to super(Vehicle, self)
in Car.__init__
is incorrect as it
+In this example, the call to super(Vehicle, self)
in Car.__init__
is incorrect, as it
passes Vehicle
rather than Car
as the first argument to super
.
As a result, super(SportsCar, self).__init__()
in the SportsCar.__init__
method will not call
all __init__()
methods because the call to super(Vehicle, self).__init__()
@@ -37,7 +37,7 @@ skips StatusSymbol.__init__()
.
- Python Standard Library: super.
+ Python Standard Library: super.
Artima Developer: Things to Know About Python Super.
diff --git a/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.py b/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.py
index 14804d313005..ea051fcd1530 100644
--- a/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.py
+++ b/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.py
@@ -1,2 +1,2 @@
-dictionary = {1:"a", 2:"b", 2:"c"}
-print dictionary[2]
\ No newline at end of file
+dictionary = {1:"a", 2:"b", 2:"c"} # BAD: The `2` key is duplicated.
+print(dictionary[2])
\ No newline at end of file
diff --git a/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.qhelp b/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.qhelp
index 19c4df9a5581..3aeea4b954c3 100644
--- a/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.qhelp
+++ b/python/ql/src/Expressions/DuplicateKeyInDictionaryLiteral.qhelp
@@ -4,8 +4,8 @@
Dictionary literals are constructed in the order given in the source.
-This means that if a key is duplicated the second key-value pair will overwrite
-the first as a dictionary can only have one value per key.
+This means that if a key is duplicated, the second key-value pair will overwrite
+the first; as a dictionary can only have one value per key.
@@ -15,14 +15,14 @@ If they are then decide which value is wanted and delete the other one.
-This example will output "c" because the mapping between 2 and "b" is overwritten by the
-mapping from 2 to "c". The programmer may have meant to map 3 to "c" instead.
+The following example will output "c"
, because the mapping between 2 and "b"
is overwritten by the
+mapping from 2 to "c"
. The programmer may have meant to map 3 to "c"
instead.
- Python: Dictionary literals.
+ Python: Dictionary literals.
diff --git a/python/ql/src/Expressions/ExplicitCallToDel.qhelp b/python/ql/src/Expressions/ExplicitCallToDel.qhelp
index 9ec18b46918e..3e6b79c929f8 100644
--- a/python/ql/src/Expressions/ExplicitCallToDel.qhelp
+++ b/python/ql/src/Expressions/ExplicitCallToDel.qhelp
@@ -17,7 +17,7 @@ wrap the use of the object in a with
statement.
-In the first example, rather than close the zip file in a conventional manner the programmer has called __del__
.
+
In the first example, rather than close the zip file in a conventional manner, the programmer has called __del__
.
A safer alternative is shown in the second example.
diff --git a/python/ql/src/Expressions/IncorrectComparisonUsingIs.qhelp b/python/ql/src/Expressions/IncorrectComparisonUsingIs.qhelp
index b8c25fa04a24..b1df1e8b8b7c 100644
--- a/python/ql/src/Expressions/IncorrectComparisonUsingIs.qhelp
+++ b/python/ql/src/Expressions/IncorrectComparisonUsingIs.qhelp
@@ -37,7 +37,7 @@ either of the alternatives below.
- Python Standard Library: Comparisons.
+ Python Standard Library: Comparisons.
diff --git a/python/ql/src/Expressions/IncorrectComparisonUsingIs.ql b/python/ql/src/Expressions/IncorrectComparisonUsingIs.ql
index 6eda4abbde21..fa0ca14669f6 100644
--- a/python/ql/src/Expressions/IncorrectComparisonUsingIs.ql
+++ b/python/ql/src/Expressions/IncorrectComparisonUsingIs.ql
@@ -1,6 +1,6 @@
/**
* @name Comparison using is when operands support `__eq__`
- * @description Comparison using 'is' when equivalence is not the same as identity
+ * @description Comparison using `is` when equivalence is not the same as identity
* @kind problem
* @tags quality
* reliability
diff --git a/python/ql/src/Expressions/UnsupportedFormatCharacter.qhelp b/python/ql/src/Expressions/UnsupportedFormatCharacter.qhelp
index b22d59a209c5..ae2f30afcb38 100644
--- a/python/ql/src/Expressions/UnsupportedFormatCharacter.qhelp
+++ b/python/ql/src/Expressions/UnsupportedFormatCharacter.qhelp
@@ -3,18 +3,19 @@
"qhelp.dtd">
-A format string, that is the string on the left hand side of an expression like fmt % arguments
, must consist of legal conversion specifiers.
+
A printf-style format string (i.e. a string that is used as the left hand side of the %
operator, such as fmt % arguments
)
+must consist of valid conversion specifiers, such as %s
, %d
, etc.
Otherwise, a ValueError
will be raised.
-Choose a legal conversion specifier.
+Ensure a valid conversion specifier is used.
-In format_as_tuple_incorrect
, "t" is not a legal conversion specifier.
+
In the following example, format_as_tuple_incorrect
, %t
is not a valid conversion specifier.
@@ -22,7 +23,7 @@ Otherwise, a ValueError
will be raised.
- Python Library Reference: String Formatting.
+ Python Library Reference: printf-style String Formatting.
diff --git a/python/ql/src/Functions/ConsistentReturns.qhelp b/python/ql/src/Functions/ConsistentReturns.qhelp
index cd29062ada66..62162a2c1c48 100644
--- a/python/ql/src/Functions/ConsistentReturns.qhelp
+++ b/python/ql/src/Functions/ConsistentReturns.qhelp
@@ -6,7 +6,7 @@
When a function contains both explicit returns (return value
) and implicit returns
-(where code falls off the end of a function) this often indicates that a return
+(where code falls off the end of a function), this often indicates that a return
statement has been forgotten. It is best to return an explicit return value even when returning
None
because this makes it easier for other developers to read your code.
@@ -29,7 +29,7 @@ return value of None
as this equates to False
. However
-Python Language Reference: Function definitions.
+Python Language Reference: Function definitions.
diff --git a/python/ql/src/Functions/ConsistentReturns.ql b/python/ql/src/Functions/ConsistentReturns.ql
index a1b308514562..1bc7b5724b36 100644
--- a/python/ql/src/Functions/ConsistentReturns.ql
+++ b/python/ql/src/Functions/ConsistentReturns.ql
@@ -1,6 +1,6 @@
/**
* @name Explicit returns mixed with implicit (fall through) returns
- * @description Mixing implicit and explicit returns indicates a likely error as implicit returns always return 'None'.
+ * @description Mixing implicit and explicit returns indicates a likely error as implicit returns always return `None`.
* @kind problem
* @tags quality
* reliability
@@ -31,4 +31,4 @@ predicate has_implicit_return(Function func) {
from Function func
where explicitly_returns_non_none(func) and has_implicit_return(func)
select func,
- "Mixing implicit and explicit returns may indicate an error as implicit returns always return None."
+ "Mixing implicit and explicit returns may indicate an error, as implicit returns always return None."
diff --git a/python/ql/src/Functions/InitIsGenerator.qhelp b/python/ql/src/Functions/InitIsGenerator.qhelp
index 113e444d1f39..d1144815c7fc 100644
--- a/python/ql/src/Functions/InitIsGenerator.qhelp
+++ b/python/ql/src/Functions/InitIsGenerator.qhelp
@@ -22,7 +22,7 @@ not logical in the context of an initializer.
- Python: The __init__ method.
+ Python: The __init__ method.
diff --git a/python/ql/src/Functions/ModificationOfParameterWithDefault.qhelp b/python/ql/src/Functions/ModificationOfParameterWithDefault.qhelp
index 39bb484f8917..12714a68364d 100644
--- a/python/ql/src/Functions/ModificationOfParameterWithDefault.qhelp
+++ b/python/ql/src/Functions/ModificationOfParameterWithDefault.qhelp
@@ -37,7 +37,7 @@ function with a default of default=None
, check if the parameter is
Effbot: Default Parameter Values in Python.
- Python Language Reference: Function definitions.
+ Python Language Reference: Function definitions.
diff --git a/python/ql/test/query-tests/Functions/return_values/ConsistentReturns.expected b/python/ql/test/query-tests/Functions/return_values/ConsistentReturns.expected
index 1bb6a25860be..302a327a1444 100644
--- a/python/ql/test/query-tests/Functions/return_values/ConsistentReturns.expected
+++ b/python/ql/test/query-tests/Functions/return_values/ConsistentReturns.expected
@@ -1,4 +1,4 @@
-| functions_test.py:18:1:18:11 | Function cr1 | Mixing implicit and explicit returns may indicate an error as implicit returns always return None. |
-| functions_test.py:22:1:22:11 | Function cr2 | Mixing implicit and explicit returns may indicate an error as implicit returns always return None. |
-| functions_test.py:336:1:336:16 | Function ok_match | Mixing implicit and explicit returns may indicate an error as implicit returns always return None. |
-| functions_test.py:344:1:344:17 | Function ok_match2 | Mixing implicit and explicit returns may indicate an error as implicit returns always return None. |
+| functions_test.py:18:1:18:11 | Function cr1 | Mixing implicit and explicit returns may indicate an error, as implicit returns always return None. |
+| functions_test.py:22:1:22:11 | Function cr2 | Mixing implicit and explicit returns may indicate an error, as implicit returns always return None. |
+| functions_test.py:336:1:336:16 | Function ok_match | Mixing implicit and explicit returns may indicate an error, as implicit returns always return None. |
+| functions_test.py:344:1:344:17 | Function ok_match2 | Mixing implicit and explicit returns may indicate an error, as implicit returns always return None. |