Issue 2953 (and issue 2745) Revise Track Documentation

.github/workflows/ci-workflow.yml

@@ -66,7 +66,7 @@ jobs:
       run: pip install dataclasses
 
     - name: Install pytest
-      run: pip install pytest~=6.2.5
+      run: pip install pytest~=7.0.1
 
     - name: Check exercises
       run: |

bin/data.py

@@ -4,7 +4,7 @@
 from itertools import chain
 import json
 from pathlib import Path
-import toml
+import tomli
 from typing import List, Any, Dict, Type
 
 
@@ -354,8 +354,8 @@ class TestsTOML:
 
     @classmethod
     def load(cls, toml_path: Path):
-        with toml_path.open() as f:
-            data = toml.load(f)
+        with toml_path.open("rb") as f:
+            data = tomli.load(f)
         return cls({uuid: TestCaseTOML(uuid, *opts) for
                     uuid, opts in
                     data.items() if

bin/generate_tests.py

@@ -34,7 +34,7 @@
 from itertools import repeat
 from string import punctuation, whitespace
 from subprocess import check_call
-import toml
+import tomli
 from tempfile import NamedTemporaryFile
 from textwrap import wrap
 from typing import Any, Dict, List, NoReturn, Union

docs/INSTALLATION.md

@@ -1,9 +1,35 @@
 # Installing Python
 
-If Python isn't already available on your system,  detailed instructions by platform can be found in the [Python Setup and Usage][using python] section of the official documentation.
-Real Python also offers a [very helpful guide][helpful guide] to installation on various platforms, including iOS and Android.
+If Python isn't already available on your system, detailed instructions by platform can be found in the [Python Setup and Usage][using python] section of the official documentation.
+Real Python also offers a [nice guide][helpful guide] to installation on various platforms, including iOS and Android.
 
-Exercism tests and tooling currently supports `Python 3.8` (tests) and `Python 3.9` (tooling).
+Finally, these posts by Brett Cannon [A quick-and-dirty guide][quick-and-dirty] and [Why you should use `python -m pip`][python-m-pip], give very helpful advice on how to manage Python installations and packages.
 
+**Note for MacOS users:**  prior to MacOS Monterey (12.3), `Python 2.7` came pre-installed with the operating system.
+Using `Python 2.7` with exercsim or most other programs is not recommended.
+You should instead install Python 3 via one of the methods detailed below.
+As of MacOS Monterey (12.3), no version of Python will be pre-installed via MacOS.
+
+Some quick links into the documentation by operating system:
+
+-  [Windows][windows] Additionally, this Microsoft article on [installing Python on windows][python-on-windows] is helpful.
+-  [Unix & Linux Systems][unix-and-linux] (_these largely work for MacOS as well_)
+-  [MacOS][macos] : **This is outdated.**
+   We recommend reviewing some of the methods outlined in the Real Python article [Installing Python][installing-python] or the articles by Brett Cannon linked above.
+
+
+Exercism tests and tooling currently support `Python 3.8` (_tests_) and `Python 3.9` (_tooling_).
+This means that the [newest features of Python `3.10`][310-new-features] are **not** currently supported.
+Please refer to the [Python 3.9.x documentation][3.9 docs] for what is currently supported.
+
+[3.9 docs]: https://docs.python.org/3.9/
+[310-new-features]: https://docs.python.org/3/whatsnew/3.10.html
 [helpful guide]: https://realpython.com/installing-python/
+[installing-python]: https://realpython.com/installing-python/#what-your-options-are_1
+[macos]: https://docs.python.org/3/using/mac.html
+[python-m-pip]: https://snarky.ca/why-you-should-use-python-m-pip/
+[python-on-windows]: https://docs.microsoft.com/en-us/windows/python/beginners
+[quick-and-dirty]: https://snarky.ca/a-quick-and-dirty-guide-on-how-to-install-packages-for-python/
+[unix-and-linux]: https://docs.python.org/3/using/unix.html
 [using python]: https://docs.python.org/3/using/index.html
+[windows]: https://docs.python.org/3/using/windows.html

docs/LEARNING.md

@@ -1,7 +1,7 @@
 # Learning
 
 ## Learning Python From Scratch
-Python is (_as Wikipedia says_), a powerful *general-purpose and high-level programming language*.
+Python is (_as [Wikipedia says][wikipython]_), a *general-purpose and high-level programming language*.
  It can be used to write a wide variety of different kinds of software, from video games to HTTP servers to command-line tools - and a whole lot else.
  It is especially good at 'gluing' different systems and programs together.
 
@@ -12,23 +12,32 @@ And we think the best way to lean is to _play_ and to _practice_ with coding pro
 Below you will find some additional jumping-off places to start your learning journey, recommended by our community.
 
 
-## Resources
-
 - [Python Documentation Tutorial][Python Documentation Tutorial]
-- [Automate the Boring Stuff with Python (Book)][automate the boring stuff]
+- [Automate the Boring Stuff with Python (_book_)][automate the boring stuff]
+- [Automate the Boring Stuff Videos (_covers first 15 book chapters_)][automate the videos]
 - [Learn X in Y minutes (where X = Python3)][Learn X in Y minutes]
-- [Python3 Beginner Tutorial (video)][Python3 Beginner Tutorial]
-- [Practical Python Programming from David Beazley][Practical Python]
-- [Official Python3 Documentation and Reference][python docs]
-- [PyCharm EDU **IDE** and **Courses**][pycharm edu]
 - [Python at Free Code Camp][python at free code camp]
+- [Intro to Python (_python-course.eu_)][python-course.eu]
+- [Think Python][Think Python]
+- [Python for Non-Programmers][python-for-non-programmers]
+- [Python 4 Everyone][python4everyone]
+- [Introduction to Computer Science and Programming in Python (MIT)][mitocw600]
+- [Googles Python Class][googles python class]
+- [Microsoft's Python Learning Path][MS Python]
+- [PyCharm EDU **IDE** and **Courses**][pycharm edu] (_paid_)
 
 
 [Learn X in Y minutes]: https://learnxinyminutes.com/docs/python3/
-[Practical Python]: https://dabeaz-course.github.io/practical-python/
+[MS Python]: https://docs.microsoft.com/en-us/learn/paths/python-language/
 [Python Documentation Tutorial]: https://docs.python.org/3/tutorial/index.html
 [Python at Free Code Camp]: https://www.freecodecamp.org/learn/scientific-computing-with-python/
-[Python3 Beginner Tutorial]: https://www.youtube.com/playlist?list=PL1A2CSdiySGJd0LJRRSwQZbPZaDP0q67j
-[automate the boring stuff]: https://automatetheboringstuff.com/
+[Think Python]: http://www.greenteapress.com/thinkpython/html/index.html
+[automate the boring stuff]: https://automatetheboringstuff.com/2e/
+[automate the videos]: https://www.youtube.com/watch?v=1F_OgqRuSdI&list=PL0-84-yl1fUnRuXGFe_F7qSH1LEnn9LkW
+[googles python class]: https://developers.google.com/edu/python/introduction
+[mitocw600]: https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-0001-introduction-to-computer-science-and-programming-in-python-fall-2016/
 [pycharm edu]: https://www.jetbrains.com/pycharm-edu/
-[python docs]: https://docs.python.org/3/
+[python-course.eu]: https://python-course.eu/python-tutorial/
+[python-for-non-programmers]: https://store.lerner.co.il/python-for-non-programmers-live
+[python4everyone]: https://www.py4e.com/
+[wikipython]: https://en.wikipedia.org/wiki/Python_(programming_language)

docs/RESOURCES.md

@@ -1,22 +1,28 @@
-# Recommended learning resources
+# Additional Resources for Python
 
-* [The Python Tutorial][The Python Tutorial]
-* [The Python Library Reference][The Python Library Reference]
-* [The Python Docs][python docs]
-* [Practical Python][practical python]
-* [Think Python][think python]
-* [PyMOTW-3][pymotw-3]
-* [automate the boring stuff][automate the boring stuff]
-* [Googles Python Class][Googles Python Class]
-* [pycharm edu][pycharm edu]
+- [Official Python 3 Documentation and Reference][python docs]
+- [The Python Library Reference][The Python Library Reference]
+- [The Docs on pip][pip]
+- [Tall, Snarky Canadian (_The Blog of Core Python Developer Brett Cannon_)][Tall, Snarky Canadian]
+- [Practical Python][practical python]
+- [Python 3 Module of the Week (PyMOTW-3)][pymotw-3]
+- [Beyond the Basic Stuff with Python][Beyond the Basic Stuff with Python]
+- [The Big Book of Small Python Projects][The Big Book of Small Python Projects]
+- [Data Structures and Information Retrieval in Python][Data Structures and Information Retrieval in Python]
+- [python practice projects][python practice projects]
+- [Python Courses eu][python-course.eu main]
+- [Fluent Python Notebooks][fluent-notebooks]
 
 
+[Beyond the Basic Stuff with Python]: https://inventwithpython.com/beyond/
+[Data Structures and Information Retrieval in Python]: https://allendowney.github.io/DSIRP/
 [Practical Python]: https://dabeaz-course.github.io/practical-python/
-[The Python Tutorial]: https://docs.python.org/3/tutorial/index.html
+[Tall, Snarky Canadian]: https://snarky.ca/
+[The Big Book of Small Python Projects]: http://inventwithpython.com/bigbookpython/
 [The Python Library Reference]: https://docs.python.org/3/library/index.html
-[Googles Python Class]: https://developers.google.com/edu/python
-[Think Python]: http://www.greenteapress.com/thinkpython/html/index.html
-[automate the boring stuff]: https://automatetheboringstuff.com/
-[pycharm edu]: https://www.jetbrains.com/pycharm-edu/
-[python docs]: https://docs.python.org/3/
+[fluent-notebooks]: https://github.com/AllenDowney/fluent-python-notebooks
+[pip]: https://pip.pypa.io/en/stable/user_guide/
 [pymotw-3]: https://pymotw.com/3/
+[python docs]: https://docs.python.org/3/
+[python practice projects]: http://pythonpracticeprojects.com/
+[python-course.eu main]: https://python-course.eu/