[Analyzer Comments]: Changes for Upgrade to Python 3.13

analyzer-comments/python/general/general_recommendations.md

@@ -0,0 +1,32 @@
+1.  Get familiar with the conventions outlined in [PEP 8][pep-8].
+    While these are not "law", they are the standard used in the Python project itself and are a great baseline in most coding situations.
+2.  Read and think about the ideas outlined in [PEP 20 (aka "The Zen of Python")][pep-20].
+    Like PEP 8, these are not "laws", but they are solid guiding principles for better and clearer Python code.
+3.  Prefer clear and easy to follow code over comments. But DO comment where needed for clarity.
+4.  Consider using type hints to clarify your code.
+    Explore the type hint [documentation][type-hint-docs] and [why you might not want to type hint][type-hint-nos].
+5.  Try to follow the docstring guidelines laid out in [PEP 257][pep-257].
+    Good documentation matters.
+6.  Avoid [magic numbers][magic-numbers].
+7.  Prefer [`enumerate()`][enumerate-docs] over [`range(len())`][range-docs] in loops that need both an index and element.
+8.  Prefer [comprehensions][comprehensions] and [generator expressions][generators] over loops that append to a data structure.
+    But don't [overuse comprehensions][comprehension-overuse].
+9.  When joining more than few substrings or concatenating in a loop, prefer [`str.join()`][join] over other methods of string concatenation.
+10.  Get familiar with Python's rich set of [built-in functions][built-in-functions]  and the [Standard Library][standard-lib].
+     Go [here][standard-lib-overview] for a brief tour and some interesting highlights.
+
+[built-in-functions]: https://docs.python.org/3/library/functions.html
+[comprehension-overuse]: https://treyhunner.com/2019/03/abusing-and-overusing-list-comprehensions-in-python/
+[comprehensions]: https://treyhunner.com/2015/12/python-list-comprehensions-now-in-color/
+[enumerate-docs]: https://docs.python.org/3/library/functions.html#enumerate
+[generators]: https://www.pythonmorsels.com/how-write-generator-expression/
+[join]: https://docs.python.org/3/library/stdtypes.html#str.join
+[magic-numbers]: https://en.wikipedia.org/wiki/Magic_number_(programming)
+[pep-20]: https://peps.python.org/pep-0020/
+[pep-257]: https://peps.python.org/pep-0257/
+[pep-8]: https://peps.python.org/pep-0008/
+[range-docs]: https://docs.python.org/3/library/functions.html#func-range
+[standard-lib-overview]: https://docs.python.org/3/tutorial/stdlib.html
+[standard-lib]: https://docs.python.org/3/library/index.html
+[type-hint-docs]: https://typing.python.org/en/latest/index.html
+[type-hint-nos]: https://typing.python.org/en/latest/guides/typing_anti_pitch.html

analyzer-comments/python/pylint/convention.md

@@ -1,9 +1,15 @@
 # pylint convention
 
-**Line %{lineno}** [_%{code}_]  :  %{message} was reported by Pylint.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
 
-Which means this code doesn't follow general [code style][code style] conventions.
-While this type of issue generally doesn't affect the way code _executes_, it can hurt
-readability or the performance of automated tools such as documentation generators or test runners.
+%{message}.
 
-[code style]: https://www.python.org/dev/peps/pep-0008/
+This code doesn't follow general [Python code style][code style] conventions.
+While this type of issue generally doesn't affect the way code _executes_, it can hurt readability or the performance of automated tools such as documentation generators or test runners.
+
+%Q{Instead of:\n\n```python\n#{bad_code}\n```\n}
+%Q{Try:\n\n```python\n#{good_code}\n```\n\n}
+%Q{Additional information:\n #{related_info}\n}
+%{details}
+
+[code style]: https://www.python.org/dev/peps/pep-0008/

analyzer-comments/python/pylint/error.md

@@ -1,5 +1,13 @@
 # pylint informational
 
-**Line %{lineno}** [_%{code}_]  :  %{message} was reported by Pylint.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
+
+%{message}.
 
 This code has an error or problem that should be addressed.
+
+%Q{Instead of:\n\n```python\n#{bad_code}\n```\n}
+%Q{Try:\n\n```python\n#{good_code}\n```\n\n}
+%Q{Additional information:\n #{related_info}\n}
+%{details}
+

analyzer-comments/python/pylint/fatal.md

@@ -1,5 +1,8 @@
 # pylint fatal
 
-**Line %{lineno}** [_%{code}_]  :  %{message} was reported by Pylint.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
+
+%{message}.
+
 
 This is a fatal error. Something went wrong, and the code cannot be processed any further.

analyzer-comments/python/pylint/informatonal.md

@@ -1,7 +1,13 @@
 # pylint informational
 
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
 
-**Line %{lineno}** [_%{code}_]  :  %{message} was reported by Pylint.
+%{message}.
 
 There is `FIXME`/`TODO`/`XXX` style comment or other "informational" pattern or note in the code.
  These tags are often used to annotate places where code is stubbed out but needs work - or to highlight potential design flaws or bugs that need to be addressed in the future.
+
+%Q{Instead of:\n\n```python\n#{bad_code}\n```\n}
+%Q{Try:\n\n```python\n#{good_code}\n```\n\n}
+%Q{Additional information:\n #{related_info}\n}
+%{details}

analyzer-comments/python/pylint/refactor.md

@@ -1,11 +1,18 @@
 # pylint refactor
 
-**Line %{lineno}** [_%{code}_]  :  %{message} was reported by Pylint.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
+
+%{message}.
 
 This code is emitting a [code smell][code smell], and may be in need of
 a re-write or refactor.
- This doesn't mean the code is incorrect or buggy in a _technical sense_ -- only that it
+ This doesn't mean the code is incorrect or buggy in a _technical sense_, only that it
 appears to have one or more patterns that could lead to _future_ bugs or maintenance issues.
 Consider taking a closer look at it.
 
+%Q{Instead of:\n\n```python\n#{bad_code}\n```\n}
+%Q{Try:\n\n```python\n#{good_code}\n```\n\n}
+%Q{Additional information:\n #{related_info}\n}
+%{details}
+
 [code smell]: https://en.wikipedia.org/wiki/Code_smell

analyzer-comments/python/pylint/warning.md

@@ -1,8 +1,15 @@
 # pylint warning
 
-**Line %{lineno}** [_%{code}_]  :  %{message} was reported by Pylint.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
+
+%{message}.
 
 There is an issue in the code that could lead to a bug or error in the program.
 While this error might not be _severe_, it could lead to more severe issues in the future.
-It is recommend the problem be addressed before proceeding further.
+It is recommended the problem be addressed before proceeding further.
+
+%Q{Instead of:\n\n```python\n#{bad_code}\n```\n}
+%Q{Try:\n\n```python\n#{good_code}\n```\n\n}
+%Q{Additional information:\n #{related_info}\n}
+%{details}