[Tooling & Documentation]: Upgrade to python 3.13.5 (#74)

* Added pylint examples of bad code for linting rules.

* Added pylint examples of good code for linting rules.

* Added pylint linting rules details files.

* Added generic pylint analyzer for exercises without any customized analysis.

* Added pylint linting rules related info files.

* Custom analyzer stub, ready for additional rules beyond the existing PyLint analyzers.

* Details comment file for unused-wildcard-import lint rule.

* Added exercise metadata and exemplar code to test exercises.

* Added exercise solution code to test exercises.

* Added exercise golden analysis.json for test exercises.

* Upgraded dockerfile to python:3.13.5-alpine3.22

* Required init files for test and lib.

* Updated readme with new docker-based instructions.

* Updated PyLint comment files with good code, bad code, refs, and details from PyLint docs.

* Removed unneeded pylint config file from exercise.

* Added 10 general recommendations for when the analyzer has no feedback.

* Cleaned up and formatted run scripts.

* Upgraded requirements for Python 3.13.5.

* Upgraded the general PyLint config file with the 4.4.0 version and enabled all extensions.

* Added new golden tests for slect exercises to better test Analyzer and Analyzer feedback.

* Modified analyzer to use new method now that epylint is depricated.  Added extended PyLint messaging for PyLint comments.  Added a generic analyzer for when no custom analyzer is found.

* Added exercise names file and modified exercise.py to read exercise names from file instead of using empty directories,

Author: BethanyG

Dockerfile

@@ -1,15 +1,12 @@
-FROM python:3.11.2-slim
+FROM python:3.13.5-alpine3.22
 
-RUN apt-get update \
- && apt-get install curl -y \
- && apt-get remove curl -y \
- && apt-get autoremove -y \
- && rm -rf /var/lib/apt/lists/*
+COPY requirements.txt /requirements.txt
+COPY dev-requirements.txt /dev-requirements.txt
+
+RUN pip install -r /requirements.txt -r /dev-requirements.txt
 
-RUN mkdir /opt/analyzer
 COPY . /opt/analyzer
-WORKDIR /opt/analyzer
 
-RUN pip install -r requirements.txt -r dev-requirements.txt
-ENTRYPOINT ["/opt/analyzer/bin/run.sh"]
+WORKDIR /opt/analyzer
 
+ENTRYPOINT ["sh", "/opt/analyzer/bin/run.sh"]

README.md

@@ -1,17 +1,24 @@
 # Exercism's Python Analyzer
 
-This is Exercism's automated analyzer for the Python track.
+This is Exercism's automated analyzer for the Python track exercises.
+It is based on and uses [PyLint][pylint-github].
 
-It is run with `./bin/run.sh $EXERCISM $PATH_TO_FILES $PATH_FOR_OUTPUT` and will read the source code from `$PATH_TO_FILES` and write a text file with an analysis to `$PATH_FOR_OUTPUT`.
+It is run from a docker container using `./bin/run-in-docker.sh $EXERCISM $PATH_TO_FILES $PATH_FOR_OUTPUT` and will read the source code from `$PATH_TO_FILES` and write a text file with an analysis to `$PATH_FOR_OUTPUT`.
 
 For example:
 
 ```bash
-./bin/run.sh two_fer ~/solution-238382y7sds7fsadfasj23j/ ~/solution-238382y7sds7fsadfasj23j/output/
+./bin/run-in-docker.sh two_fer ~/solution-238382y7sds7fsadfasj23j/ ~/solution-238382y7sds7fsadfasj23j/output/
 ```
 
-Unit tests can be run from this directory:
+Unit tests also require [docker][docker] and can be run locally or from within GitHub via [codespaces][codespaces]:
 
 ```bash
-pytest -x
+
+#run from the python-analyzer (project root) directory.
+./bin/run-tests-in-docker.sh
 ```
+
+[pylint-github]: https://github.com/pylint-dev/pylint
+[docker]: https://www.docker.com/
+[codespaces]: https://github.com/features/codespaces

bin/run-in-docker.sh

@@ -34,8 +34,10 @@ mkdir -p "$output_dir"
 
 # run image passing the arguments
 docker run \
+    --rm \
+    --network none \
+    --read-only \
     --mount type=bind,src=$PWD/$2,dst=/solution \
     --mount type=bind,src=$PWD/$output_dir,dst=/output \
-    python-analyzer $1 /solution/ /output/
-    
-
+    --mount type=tmpfs,destination=/tmp \
+    exercism/python-analyzer $1 /solution/ /output/

bin/run-tests-in-docker.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env sh
+
+# Synopsis:
+# Test the test runner Docker image by running it against a predefined set of
+# solutions with an expected output.
+# The test runner Docker image is built automatically.
+
+# Output:
+# Outputs the diff of the expected test results against the actual test results
+# generated by the test runner Docker image.
+
+# Example:
+# ./bin/run-tests-in-docker.sh
+
+# Stop executing when a command returns a non-zero return code
+set -e
+
+# Build the Docker image
+docker build --rm -t exercism/python-analyzer .
+
+# Run the Docker image using the settings mimicking the production environment
+docker run \
+    --rm \
+    --network none \
+    --read-only \
+    --mount type=bind,src="${PWD}/test",dst=/opt/analyzer/test \
+    --mount type=tmpfs,dst=/tmp \
+    --workdir /opt/analyzer \
+    --entrypoint pytest \
+    exercism/python-analyzer -vv  --disable-warnings

bin/run.py

@@ -3,6 +3,8 @@
 CLI for the auto-analyzer for the Python track on Exercism.org.
 ./bin/run.sh two_fer ~/solution-238382y7sds7fsadfasj23j/ ~/solution-238382y7sds7fsadfasj23j/output/
 """
+
+
 import argparse
 import importlib.util
 import sys

comments/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

comments/pylint/convention.md

@@ -1,9 +1,15 @@
 # pylint convention
 
-**Line %{lineno}** [ _%{code}_ ]  :  %{message}.
- Was reported.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
 
-Which means this code doesn't follow general [`code style`][PEP8] conventions.
+%{message}.
+
+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.
 
-[PEP8]: https://www.python.org/dev/peps/pep-0008/
+%{bad_code}
+%{good_code}
+%{related_info}
+%{details}
+
+[code style]: https://www.python.org/dev/peps/pep-0008/

comments/pylint/error.md

@@ -1,6 +1,12 @@
 # pylint informational
 
-**Line %{lineno}** [ _%{code}_ ]  :  %{message}.
- Was reported.
+**Line %{lineno} [_%{code}_]** was reported by Pylint:
+
+%{message}.
 
 This code has an error or problem that should be addressed.
+
+%{bad_code}
+%{good_code}
+%{related_info}
+%{details}

comments/pylint/fatal.md

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

comments/pylint/informatonal.md

@@ -1,8 +1,13 @@
 # pylint informational
 
-**Line %{lineno}** [ _%{code}_ ]  :  %{message}.
- Was reported.
+**Line %{lineno} [_%{code}_]** 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.
+ 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.
 
+%{bad_code}
+%{good_code}
+%{related_info}
+%{details}