diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index f9e9710e60..90b39b9f8c 100644 --- a/docs/INSTALLATION.md +++ b/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/ +[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 +[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/ \ No newline at end of file diff --git a/docs/LEARNING.md b/docs/LEARNING.md index 279c8d9ccc..15e4fd8021 100644 --- a/docs/LEARNING.md +++ b/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) diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md index 2e4a44ef45..ea8527592a 100644 --- a/docs/RESOURCES.md +++ b/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/ diff --git a/docs/TESTS.md b/docs/TESTS.md index 9b0825a680..09f9a0744b 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -1,45 +1,35 @@ # Tests -We use [pytest](http://pytest.org/en/latest/) as our website test runner. -You will need to install pytest on your development machine if you want to download and run exercise tests for the Python track locally. -We also recommend you install the following pytest plugins: +We use [pytest][Getting Started Guide] as our website test runner. +You will need to install `pytest` on your development machine if you want to download and run exercise tests for the Python track locally. +You should also install the following `pytest` plugins: -- [pytest-cache](http://pythonhosted.org/pytest-cache/) -- [pytest-subtests](https://github.com/pytest-dev/pytest-subtests) -- [pytest-pylint](https://github.com/carsongee/pytest-pylint) +- [pytest-cache][pytest-cache] +- [pytest-subtests][pytest-subtests] -The PyTest [Getting Started Guide](https://docs.pytest.org/en/latest/getting-started.html) has quick general instructions, although they do not cover installing the plugins. -Continue reading below for more detailed instructions. +We also recommend using the code linting program [pylint][pylint], as it is part of our automated feedback on the website and can be a very useful static code analysis tool. +For ease-of-use, the [pytest-pylint][pytest-pylint] plugin for `pytest` will allow you to run `pylint` via `pytest` on the command line. -We also recommend using [pylint](https://pylint.pycqa.org/en/latest/user_guide/), as it is part of our automated feedback on the website, and can be a very useful (but also noisy) code analysis tool. +Pylint configuration can be a bit much, so this [tutorial from pycqa.org][tutorial from pycqa.org] can be helpful for getting started, as can this overview of [Code Quality: Tools and Best Practices][Code Quality: Tools and Best Practices] from Real Python. -Pylint can be a bit much, so this [tutorial from pycqa.orgl](https://pylint.pycqa.org/en/latest/tutorial.html) can be helpful for getting started, as can this overview of [Code Quality: Tools and Best Practices](https://realpython.com/python-code-quality/) from Real Python. ---- +## Installing pytest -- [Pytest](#pytest) - - [Installing pytest](#installing-pytest) - - [Running the tests](#running-the-tests) - - [Extra arguments](#extra-arguments) -- [Extending your IDE](#extending-your-ide) -- [Additional information](#additional-information) +Pytest can be installed and updated using the built-in Python utility [`pip`][pip]. ---- +For additional tips, Brett Cannon has a nice [quick-and-dirty guide on how to install packages for python][quick-and-dirty], along with a great explanation on [why you should use `python -m pip`][python-m-pip]. +For more on Python's command line arguments, see [command line and environment][python command line] in the Python documentation. -## Pytest +**Note:** `Python3` and `py` may or may not be aliases for Python on your system. +Please adjust the install commands below accordingly. +To install `pytest` in a virtual environment, ensure the environment **is activated** prior to executing commands. +Otherwise, the `pytest` installation will be global. -_Official pytest documentation can be found on the [pytest Wiki](https://pytest.org/en/latest/) page._ - -Pytest lets you test your solutions using our provided tests, and is what we use to validate your solutions on the website. - -### Installing pytest - -Pytest can be installed and updated using the built-in Python utility `pip`. #### Windows ```powershell -PS C:\Users\foobar> python3 -m pip install pytest pytest-cache pytest-subtests pytest-pylint +PS C:\Users\foobar> py -m pip install pytest pytest-cache pytest-subtests pytest-pylint Successfully installed pytest-6.2.5 ... ``` @@ -51,49 +41,59 @@ Successfully installed pytest-6.2.5 ... ``` -To check if the installation was successful: + +To check if installation was successful: ```bash $ python3 -m pytest --version pytest 6.2.5 ``` -If you do not want to precede every command with `python3 -m` please refer to [adding to PATH](#adding-to-path) at the end of this document. +## Running the tests -#### Installing pytest within a virtual environment +To run the tests, go to the folder where the exercise is stored using `cd` in your terminal (_replace `{exercise-folder-location}` below with your path_). -_For more information about virtual environments please refer to the [tools](./tools) file._ +```bash +$ cd {exercise-folder-location} +``` -When installing pytest or any other module(s), make sure that you have [activated your environment](./tools#activating-your-virtual-environment). After which you can run: +The file you will want to run usually ends in `_test.py`. +This file contains the tests for the exercise solution, and are the same tests that run on the website when a solution is uploaded. +Next, run the following command in your terminal, replacing `{exercise_test.py}` with the location/name of the test file: ```bash -$ pip install pytest pytest-cache pytest-subtests pytest-pylint -Successfully installed pytest-6.2.5 ... +$ python3 -m pytest -o markers=task {exercise_test.py} +==================== 7 passed in 0.08s ==================== ``` -### Running the tests +### Fixing warnings -To run the tests, go to the folder where the exercise is stored using `cd` in your terminal (_replace `{exercise-folder-location}` below with the path_). +If you do not use the `pytest -o markers=task` in the command above, is possible that you will get `warnings` about "unknown markers" when running a test that uses our _new_ syntax. -```bash -$ cd {exercise-folder-location} -``` +To avoid typing `pytest -o markers=task` for every test you run, you can use a `pytest.ini` configuration file, which can be downloaded from the top level of the Python track directory: [pytest.ini][pytest.ini]. -The file you'll want always ends with `_test.py`. -This file contains the tests for your solution, and are the same tests which run on the website. -Now run the following command in your terminal, replacing `{exercise_test.py}` with the location/name of the test file: +You can also create your own `pytest.ini` file with the following content: -```bash -$ python3 -m pytest {exercise_test.py} -==================== 7 passed in 0.08s ==================== +```ini +[pytest] +markers = + task: A concept exercise task. ``` -#### Failures +Placing this file in the _root_ or _working_ directory for Exercism exercises will register the marks and stop the warnings. +More information on pytest marks can be found in the `pytest` documentation on [marking test functions][marking test functions with attributes] and the `pytest` documentation on [working with custom markers][working with custom markers]. + +_More information on customizing pytest configurations can be found in the pytest documentation on [configuration file formats][configuration file formats]_ + -When your code returns an incorrect or unexpected value, pytest returns all the failed tests and the returned and expected values of each. Look at the following failed test file: +### Test Failures + +When tests fail, `pytest` prints the text of each failed test, along with the expected and actual `return` values of each to the terminal. +Below is an generic example of a failed test: ```bash -$ python3 -m pytest {exercise_test.py} +$(my_venv) python3 -m pytest -o markers=task {exercise_test.py} + =================== FAILURES ==================== ______________ name_of_failed_test ______________ # Test code inside of {exercise_test.py} that failed. @@ -108,14 +108,49 @@ FAILED exercise_test.py::ExerciseTest::name_of_failed_test ### Extra arguments -If you really want to be specific about what pytest returns on your screen, here are some handy arguments that allows you to configure its behavior. +If you really want to be specific about what pytest returns on your screen, here are some handy command-line arguments that allows you to configure its behavior. + + +#### Return All Details [`-v`] + +Adding the `-v` (_verbose_) flag will return both environment information and a test summary in addition to test failures: + +```bash +$(my_venv) python3 -m pytest -o markers=task -v exercises// + +======================================== test session starts =========================================== +platform darwin -- Python 3.9.0, pytest-6.2.5, -- /usr/local/envs/my_env/bin/python3 +cachedir: .pytest_cache +metadata: {'Python': '3.9.0', 'Platform': 'macOS-10.14.6-x86_64-i386-64bit', 'Packages': {'pytest': '6.2.1'}, 'Plugins': {'subtests': '0.5.0', 'pylint': '0.18.0'} +rootdir: /Users//exercism/python, configfile: pytest.ini +plugins: subtests-0.5.0, pylint-0.18.0 + +collected 5 items + +exercises/exercise-name/exercise_file_test.py::ExerciseNameTest::test_one FAILED [ 20%] +exercises/exercise-name/exercise_file_test.py::ExerciseNameTest::test_two FAILED +exercises/exercise-name/exercise_file_test.py::ExerciseNameTest::test_three PASSED [ 40%] +exercises/concept/exercise-name/exercise_file_test.py::ExerciseNameTest::test_four FAILED +exercises/concept/exercise-name/exercise_file_test.py::ExerciseNameTest::test_five PASSED [ 60%] +exercises/concept/exercise-name/exercise_file_test.py::ExerciseNameTest::test_six FAILED +exercises/concept/exercise-name/exercise_file_test.py::ExerciseNameTest::test_seven PASSED [ 80%] +exercises/concept/exercise-name/exercise_file_test.py::ExerciseNameTest::test_eight FAILED +exercises/concept/exercise-name/exercise_file_test.py::ExerciseNameTest::test_nine PASSED [100%] + +================================================ FAILURES ====================================================== +# Failed tests are then individually printed out below + +....... +``` #### Stop After First Failure [`-x`] -Running the `pytest -x {exercise_test.py}` command, will run the tests like normal, but will stop the tests after the first failed test. This will help when you want to debug a single failure at a time. +Using the `-x` flag will run the tests as normal, but stop the test run upon the first test failure. +This helps when you want to debug a single task or test failure at a time: ```bash -$ python -m pytest -x example_test.py +$(my_venv) python3 -m pytest -o markers=task -x exercises// + =================== FAILURES ==================== _______________ example_test_foo ________________ ... @@ -128,64 +163,77 @@ FAILED example_test.py::ExampleTest::example_test_foo #### Failed Tests First [`--ff`] -`pytest-cache` remembers which tests failed last time you ran `pytest`, running `pytest --ff {exercise_test.py}` will run those previously failed tests first, then it will continue with the rest of the tests. This might speed up your testing if you are making a lot of smaller fixes. +The `pytest-cache` plugin remembers which tests failed last time you ran `pytest`, so using the flag `--ff` will tell `pytest` to run previously failed tests **first**, then continue with the remainder of the tests. +This might speed up your testing if you are making a lot of smaller fixes around one particular task or set of inputs. + ```bash -$ python -m pytest --ff bob_test.py +$(my_venv) python3 -m pytest -o markers=task --ff ==================== 7 passed in 503s ==================== ``` -#### Recommended Workflow +### Recommended Workflow We recommend using the following commands to make your debugging easier and (possibly) faster: First change your working directory to the directory of the exercise you want to test: ```bash -cd path/to/exercise +$(my_venv) cd path/to/exercise ``` Then, run the tests together with the previously explained arguments `-x` and`--ff`: ```bash -pytest -x -ff bob_test.py +$(my_venv) python3 -m pytest -o markers=task -x --ff ``` -This will test your solution. When `pytest` encounters a failed test, the program will stop and tell you which test failed. When you run the test again, `pytest` will first test that failed test, then continue with the rest. +This will test your solution. +When `pytest` encounters a failed test, the program will stop and tell you which test failed. +When you make fixes and run the test again, `pytest` will first run the previous test that failed, then continue with the remaining tests. + -#### Using PDB, the Python Debugger, with pytest +### Using PDB, the Python Debugger, with pytest -If you want to truly debug like a pro, use the `--pdb` argument after the `pytest` command. +If you want to "debug like a pro", you can use the `--pdb` argument after the `pytest` command, and drop into the built-in [Python debugger][pdb], `PDB`. ```bash -$ python3 -m pytest --pdb bob_test.py +$(my_venv) python3 -m pytest -o markers=task -x --ff --pdb =============== 4 passed in 0.15s =============== ``` -When a test fails, `PDB` allows you to look at variables and how your code responds. If you want to learn how to use the `PDB` module, have a look at the [Python Docs](https://docs.python.org/3/library/pdb.html#module-pdb) or [this](https://realpython.com/python-debugging-pdb/) Real Python article. +When a test fails, dropping into `PDB` will allow you to step through your code viewing the current scope, as well as checking the value of variables and the signature of different functions. +More details on the `PDB` module can be found in the [Python documentation on PDB][pdb]. +Additionally, the [pytest docs on PDB][pytest-pdb] and [this guide from Real Python](https://realpython.com/python-debugging-pdb/) are extremely helpful. + ## Extending your IDE -If you'd like to extend your IDE with some tools that will help you with testing and improving your code, check the [tools](./tools) page. We go into multiple IDEs, editors and some useful extensions. +If you'd like to extend your IDE with some tools that will help you with testing and improving your code, check the [tools](./tools) page. +We explore multiple IDEs, editors and some useful extensions for linting and debugging there. + ## Additional information -### Adding pytest to your PATH +### Adding python to your PATH -**Note:** If you are running a [virtual environment](./tools.md) you do not need to _add to path_ as it should work fine. +**Note:** If you have installed Python on Windows via the [PSF Installer][psf-installer], then the command will be `py` as opposed to `python3`. -Typing `python3 -m` every time you want to run a module can get a little annoying. You can add the `Scripts` folder of your Python installation to your path. If you do not know where you have installed Python, run the following command in your terminal: +Typing `python3 -m` every time you want to run a module can get a little annoying. +To avoid this, you can add the `Scripts` folder of your Python installation to your path. +If you do not know where you have installed Python, run the following command in your terminal: ```bash $ python3 -c "import os, sys; print(os.path.dirname(sys.executable))" {python_directory} ``` -The _returned_ directory is where your Python version is installed, in this tutorial it is referred to as `{python_directory}`. +The _returned_ directory is where your current active Python version is installed, in this section it is referred to as `{python_directory}`. #### Windows -Click the `Windows Start` button and lookup _Edit the system environment variables_ and press enter. Next press, `Environment Variables...`: +Click the `Windows Start` button and lookup _Edit the system environment variables_ and press enter. +Next press, `Environment Variables...`: ![Press the blue button, lol](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-SystemProperties.png) @@ -197,20 +245,32 @@ Then add a new line, as shown in the picture, replacing `{python_directory}` wit ![Add python to path](https://raw.githubusercontent.com/exercism/python/main/docs/img/Windows-AddPythonPath.png) -### Fixing warnings -It is possible that you will get `warnings` about "unknown markers" when running a test that uses our _new_ syntax. +#### MacOS/Linux -To resolve this issue, we use a `pytest.ini` file, which can be downloaded from the top level of the Python track directory: [pytest.ini](https://github.com/exercism/python/blob/main/pytest.ini). +The below should work for most Linux and MacOS flavors with a `bash` shell. +Commands may vary by Linux distro, and whether a `fish` or `zsh` shell is used. +Replace `{python_directory}` with the output of `python3 -c "import os, sys; print(os.path.dirname(sys.executable))"` -You can also create your own file with the following content: - -```ini -[pytest] -markers = - task: A concept exercise task. +```bash +export PATH=”$PATH:{python_directory}}” ``` -Whenever you run your tests, make sure that this file is in your _root_ or _working_ directory for Exercism exercises. - -_More information on customizing pytest can be found in the [PyTest docs](https://docs.pytest.org/en/6.2.x/customize.html#pytest-ini)_ +[pip]: https://pip.pypa.io/en/stable/getting-started/ +[python command line]: https://docs.python.org/3/using/cmdline.html +[pytest-cache]:http://pythonhosted.org/pytest-cache/ +[pytest-subtests]:https://github.com/pytest-dev/pytest-subtests +[pytest-pylint]:https://github.com/carsongee/pytest-pylint +[quick-and-dirty]: https://snarky.ca/a-quick-and-dirty-guide-on-how-to-install-packages-for-python/ +[Getting Started Guide]: https://docs.pytest.org/en/latest/getting-started.html +[pytest.ini]: https://github.com/exercism/python/blob/main/pytest.ini +[python-m-pip]: https://snarky.ca/why-you-should-use-python-m-pip/ +[tutorial from pycqa.org]: https://pylint.pycqa.org/en/latest/tutorial.html +[Code Quality: Tools and Best Practices]: https://realpython.com/python-code-quality/ +[pylint]: https://pylint.pycqa.org/en/latest/user_guide/ +[pdb]: https://docs.python.org/3.9/library/pdb.html +[pytest-pdb]: https://docs.pytest.org/en/6.2.x/usage.html#dropping-to-pdb-python-debugger-on-failures +[psf-installer]: https://www.python.org/downloads/ +[marking test functions with attributes]: https://docs.pytest.org/en/6.2.x/mark.html#raising-errors-on-unknown-marks +[working with custom markers]: https://docs.pytest.org/en/6.2.x/example/markers.html#working-with-custom-markers +[configuration file formats]: https://docs.pytest.org/en/6.2.x/customize.html#configuration-file-formats diff --git a/docs/TOOLS.md b/docs/TOOLS.md index a5673875b9..6023280d6b 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -1,189 +1,440 @@ # Tools -A list of tools, IDEs and editors that can help you write and debug your _Python_ code. +A list of tools, IDEs and editors that can help with writing and debugging Python code. -*Disclaimer: This is a collection of tools that are popular in our community. We do not have any financial affiliation with any of the tools listed below. We think these tools do their job and there are most certainly other tools that can do those jobs as well.* +**Disclaimer:** This is a collection of tools that are popular in our community. +It is not intended to be prescriptive nor exhaustive. +We think these tools do their job well, but there are most certainly other tools that are also good. +If you have an editor, IDE, tool, or plugin recommendation, we encourage you to add it to this document [on GitHub][python track on github]. +Exercism does not have any financial affiliation with any of the tools listed below. -Before you can start coding, make sure that you have the proper version of Python installed. Exercism currently supports `Python 3.8` and above. For more information, please refer to [Installing Python locally](https://exercism.org/docs/tracks/Python/installation). +Before you start, make sure that you have a recent version of Python installed. +The Exercism platform currently supports `Python 3.8` (_exercises and tests_) and `Python 3.9` (_tooling_). +For more information, please refer to [Installing Python locally][Installing Python locally]. ---- +
-- [Environments](#environments) - - [Venv](#venv) - - [Conda](#conda) -- [Editors and IDEs](#editors-and-ides) - - [Visual Studio Code](#visual-studio-code) - - [PyCharm](#pycharm) - - [Spyder IDE](#spyder-ide) - - [Sublime text](#sublime-text) - - [JupyterLab](#jupyterlab) +## Virtual Environments ---- +Python virtual environments offer lightweight runtime and package isolation. + They can help to organize your projects by keeping the Python packages you install bundled together inside a particular environment directory. +Different environments can hold different versions of the Python runtime together with any project or library dependencies. +This helps avoid bugs and incompatibilities caused by upgrading a library for one project that "breaks" a dependency in a different one. -## Environments +There are two major *virtual environment* tools in use today, the Python standard library [`venv`][venv] and the third-party [`conda env`][condaenv], using the [`conda`][conda] package manager and (_usually_) the Anaconda Python distribution. +Both of are straightforward to use and/or install. -Python environments are like separate Python installations: they can organize your workflow and projects by keeping the packages you install inside that project. This helps avoid bugs generated by something that you imported in another project. +Additionally, [`PyEnv`][pyenv] and [virtualenvwrapper][virtualenvwrapper] are tools that can help to manage multiple versions of Python and multiple Python environments on the same machine. -There are two major *virtual environments* in use today, `virtualenv` and `conda`. Both of are easy to install. +### Creating a virtual environment with `venv` -### Venv +To create a virtual environment using `venv`, `cd` to the directory you want to store your environments in. +This should be a directory **separate from** the code for your project, and one you will **not** be checking into source control. +Next, run the `venv` command with the name of a folder where you want to store this particular **environment**. +Common convention is to call that folder `_venv`: -Also known as `virtualenv`, *venv* is a light-weight solution to virtual environments. It creates a separate Python binary for every virtual environment and stores that inside your directory. +**Windows** -#### Creating your virtual environment +```powershell +PS C:\Users\foobar> py -m venv {name_of_virtualenv} +``` +To activate the virtual environment, run the following command: + +```powershell +PS> .\{name_of_virtual_env}\Scripts\activate.bat +(venv) PS> _ +``` + +
-To create a virtual environment, `cd` to the directory you want to store your environments in. Next, run the `venv` command with the name of a folder where you want to store this particular **environment**. Common convention is to call that folder `_venv`: +**Linux/MacOS** ```bash $ python3 -m venv {name_of_virtualenv} created virtual environment ... in 8568ms - -#### Activating your virtual environment - -To activate the virtual environment on Windows, run the following command: - -```powershell -PS> .\{name_of_virtual_env}\Scripts\activate -(venv) PS> _ ``` -To activate your virtual environment on Linux, or MacOS X, run the following command: +To activate the virtual environment, run the following command: ```bash $ source {name_of_virtual_env}/bin/activate (venv) $ _ ``` -From this terminal you can now run `pip` commands. All of the packages installed in the environment will be installed inside `{name_of_virtual_env}/Lib`. - -#### Virtual Environment wrapper - -Reference: [Wiki](https://virtualenvwrapper.readthedocs.io/en/latest/) - -The `virtualenvwrapper` module manages all your virtual environments in one place. You can create, copy, delete and switch between environments using the tools the module provides. It also allows you to add additional tools using extensions. You can create your own extension using the tutorial found [here](https://virtualenvwrapper.readthedocs.io/en/latest/plugins.html#plugins). +Once a `venv` is activated, you can run `pip` commands for package installation "inside" the environment. +Installed packages will be associated with the `venv`s version of Python, and located inside `{name_of_virtual_env}/Lib`. -### Conda +_Deactivating_ a virtual environment can be done by calling the `deactivate` script, located in the same directory as `activate`. -*Latest download can be found [here](https://www.anaconda.com/products/individual)* +
-Packaged with *Anaconda*, `conda` environments are similar to [venv environments](#venv) with the key difference being that `conda` can support the `R programming language`. Anaconda is most commonly used by researchers and data scientists because it contains a set of tools and programs tailored to them. The [Spyder IDE](#spider-ide) is one of the tools that comes with Anaconda. +### Creating a Virtual Environment using `conda` -To create a new `conda` environment, go to the *Anaconda Navigator*. Click on `environments` and then press the `Create` button. Fill in a name for your `conda` environment, select Python `3.8 or above` and click `Create`: +*The latest `conda` version can be installed via [miniconda][miniconda].* +This [`conda` cheatsheet][conda-cheatsheet] is very helpful, as are the [`conda` docs][conda-docs]. -![Creating New Conda Environment](https://raw.githubusercontent.com/exercism/Python/main/docs/img/Anaconda-Conda-New.png) +Originally created as a Python package manager for the popular [`Anaconda distribution`][anaconda] of "scientific Python", `conda` was later generalized and extended. +`conda` environments are similar to `venv`s, with the key difference being that `conda` can create virtual environments and install packages for many other programming languages in addition to Python. +Currently supported languages include `R`, `JavaScript`, `Ruby`, `Fortran`, `C/C++`, `Scala`, `Java`, and more. +For a comparison of `conda` commands vs `venv` commands, see the conda [command reference][conda command ref]. -#### Activating your conda environment -Activating your `conda` environment is easy, just click the `►` button next to your *environment*, then press `Open Terminal`. This should open a new terminal with an interface for your `conda` environment. +#### MacOS/Linux -From here you can run `conda` commands to install python packages from the Anaconda repository, or run regular `pip` commands to install python packages from PyPi inside your environment. All libraries will automatically be installed inside the `conda` environment. - ---- - -## Editors and IDEs - -### Visual Studio Code +To create a `conda` environment, type the following, replacing `{name of environment}` with your chosen name, and `python={version}` with your desired version of Python. +This can be followed by any additional packages you wish to install inside the environment: -Visual studio code (VS Code) is a code editor created by Microsoft. It is a general-purpose editor and not designed specifically for any one language. You can extend the editor using extensions; it comes with some great extensions already installed. +```bash +$ conda create --name {name of environment} python={version} "pytest>6.0" pylint +... + +## Package Plan ## + + environment location: /usr/local/anaconda3/envs/test_env + + added / updated specs: + - pylint + - pytest[version='>6'] + - python=3.10 + + +The following packages will be downloaded: + + package | build + ---------------------------|----------------- + astroid-2.11.1 | py310h2ec42d9_0 364 KB conda-forge + dill-0.3.4 | pyhd8ed1ab_0 62 KB conda-forge + lazy-object-proxy-1.7.1 | py310he24745e_0 32 KB conda-forge + libzlib-1.2.11 | h6c3fc93_1014 60 KB conda-forge + mccabe-0.7.0 | pyhd8ed1ab_0 11 KB conda-forge + openssl-3.0.2 | h6c3fc93_1 2.5 MB conda-forge + pip-22.0.4 | pyhd8ed1ab_0 1.5 MB conda-forge + platformdirs-2.5.1 | pyhd8ed1ab_0 15 KB conda-forge + pylint-2.13.1 | pyhd8ed1ab_0 284 KB conda-forge + pytest-7.1.1 | py310h2ec42d9_0 464 KB conda-forge + python-3.10.4 |h1cc4136_0_cpython 13.2 MB conda-forge + setuptools-61.1.1 | py310h2ec42d9_0 1.3 MB conda-forge + sqlite-3.37.1 | hb516253_0 1.8 MB conda-forge + tzdata-2022a | h191b570_0 121 KB conda-forge + wrapt-1.14.0 | py310h1961e1f_0 46 KB conda-forge + zlib-1.2.11 | h6c3fc93_1014 89 KB conda-forge + ------------------------------------------------------------ + Total: 21.8 MB + +Proceed ([y]/n)? y + +Preparing transaction: done +Verifying transaction: done +Executing transaction: done +# +# To activate this environment, use +# +# $ conda activate test_env +# +# To deactivate an active environment, use +# +# $ conda deactivate +``` -#### Python for VS Code +
-Extension: _Extension-id: ms-python.python_ +#### Windows -![Python Extension Header on VS Code](https://raw.githubusercontent.com/exercism/python/main/docs/img/VSCode-EXT-Python-Header.png) +Creating a `conda` environment on Windows uses the same general commands as above. +However, it is recommended that you use either the Anaconda `cmd` or `powershell` prompts over adding `conda` to your path: -The Python extension from Microsoft is extremely useful because of its range of features. Notably it supports testing and has a testing explorer! It has many other features that you can view on [its homepage](https://marketplace.visualstudio.com/items?itemName=ms-python.python). +```powershell +(base) PS C:\Users\foobar> conda create --name {name_of_environment} python={version} "pytest>6" pylint +... + +Collecting package metadata (current_repodata.json): done +Solving environment: done + +## Package Plan ## + + environment location: C:\ProgramData\Anaconda3\envs\test_env + + added / updated specs: + - pylint + - pytest[version='>6'] + - python=3.10 + + +The following packages will be downloaded: + + package | build + ---------------------------|----------------- + astroid-2.11.1 | py310h5588dad_0 364 KB conda-forge + attrs-21.4.0 | pyhd8ed1ab_0 49 KB conda-forge + bzip2-1.0.8 | h8ffe710_4 149 KB conda-forge + ca-certificates-2021.10.8 | h5b45459_0 176 KB conda-forge + dill-0.3.4 | pyhd8ed1ab_0 62 KB conda-forge + isort-5.10.1 | pyhd8ed1ab_0 79 KB conda-forge + lazy-object-proxy-1.7.1 | py310he2412df_0 34 KB conda-forge + libffi-3.4.2 | h8ffe710_5 41 KB conda-forge + libzlib-1.2.11 | h8ffe710_1014 64 KB conda-forge + mccabe-0.7.0 | pyhd8ed1ab_0 11 KB conda-forge + openssl-3.0.2 | h8ffe710_1 10.1 MB conda-forge + packaging-21.3 | pyhd8ed1ab_0 36 KB conda-forge + pip-22.0.4 | pyhd8ed1ab_0 1.5 MB conda-forge + platformdirs-2.5.1 | pyhd8ed1ab_0 15 KB conda-forge + pluggy-1.0.0 | py310h5588dad_2 26 KB conda-forge + py-1.11.0 | pyh6c4a22f_0 74 KB conda-forge + pylint-2.13.1 | pyhd8ed1ab_0 284 KB conda-forge + pyparsing-3.0.7 | pyhd8ed1ab_0 79 KB conda-forge + pytest-7.1.1 | py310h5588dad_0 483 KB conda-forge + python-3.10.4 |hcf16a7b_0_cpython 16.2 MB conda-forge + python_abi-3.10 | 2_cp310 4 KB conda-forge + setuptools-61.1.1 | py310h5588dad_0 1.3 MB conda-forge + sqlite-3.37.1 | h8ffe710_0 1.2 MB conda-forge + tk-8.6.12 | h8ffe710_0 3.5 MB conda-forge + tomli-2.0.1 | pyhd8ed1ab_0 16 KB conda-forge + typing-extensions-4.1.1 | hd8ed1ab_0 8 KB conda-forge + typing_extensions-4.1.1 | pyha770c72_0 29 KB conda-forge + tzdata-2022a | h191b570_0 121 KB conda-forge + vc-14.2 | hb210afc_6 13 KB conda-forge + vs2015_runtime-14.29.30037 | h902a5da_6 1.3 MB conda-forge + wheel-0.37.1 | pyhd8ed1ab_0 31 KB conda-forge + wrapt-1.14.0 | py310he2412df_0 49 KB conda-forge + xz-5.2.5 | h62dcd97_1 211 KB conda-forge + ------------------------------------------------------------ + Total: 37.5 MB + +Proceed ([y]/n)? y +... +Preparing transaction: done +Verifying transaction: done +Executing transaction: done +# +# To activate this environment, use +# +# $ conda activate test_env +# +# To deactivate an active environment, use +# +# $ conda deactivate +``` -##### Selecting the interpreter +
-The Python extensions supports the switching between multiple `interpreters`. This allows you to use different Python environments for different projects. This is also useful for when you are using `venv` or `conda`, which you can find more about in the [environments section](#environments). +### Virtual Environment wrapper -Click on the "Select interpreter" button in the lower left-hand of your window, another window should pop up where you can select the interpreter you want to use. +Documents and background: [virtualenvwrapper][virtualenvwrapper]. -![Interpreter selection PT2](https://raw.githubusercontent.com/exercism/python/main/docs/img/VSCode-EXT-Python-SelectInterpreter-2.png) +The `virtualenvwrapper` package works on top of `venv` to manage all your virtual environments in one place. + You can create, copy, delete and switch between environments with linux-like commands such as `lsvirtualenv` (_to list envs_) and `mkvirtualenv` (_to make an env_). + It also allows you to add additional management tools using extensions. + You can even create your own extensions to the tool using [this tutorial][venv wrapper tutorial]. -##### Other features -The Python plugin also comes with some other features that can help you debug and improve your Python code, here are some of those tools. +### PyEnv -[Test discovery tool](https://code.visualstudio.com/docs/python/testing#_configure-tests) - A tool that generates a tree containing all the *pytests* and *unittests* inside a directory. It will give you an easier and more readable interface for *pytest*. +`pyenv` is the Python fork of the popular `rbenv`/`ruby-build` tools modified for Python. +It is essentially a set of scripts and shims that allow for setting Python versions on both a global and user-specific basis. +It tries to adhere to the Unix tradition of a single-purpose, unobtrusive tool that does one thing well. -[Debugging tool](https://code.visualstudio.com/docs/python/testing#_configure-tests) - This tool will help you debug your code. You can set a `breakpoint` on a line. The debugging tool then allows you to view all *private* and *global* variables at that point in your program. +`pyenv` and the `pyenv` docs can be found on [GitHub][pyenv on github]. -[Linting](https://code.visualstudio.com/docs/python/testing#_configure-tests) - Linting looks out for simple mistakes in your code and notifies you when you write code which does not follow best practices according to PEP. Exercism currently focuses on following [PEP 8](https://www.python.org/dev/peps/pep-0008/). -[Formatting](https://code.visualstudio.com/docs/python/editing#_formatting) - This tool automatically formats your code to look a certain way. We recommend `autopep8` because it adheres to [PEP 8](https://www.python.org/dev/peps/pep-0008/). Other formatters are also supported. +
-[Config reference](https://code.visualstudio.com/docs/python/settings-reference) - If you want to configure your Python development on VS Code to behave exactly like you want it, view this reference guide. It explains options for the extensions which can really improve your coding experience. ---- +## Editors and IDEs -### PyCharm +### Visual Studio Code -PyCharm is an *Integrated Development Environment* built by JetBrains. It is specialized to work for Python and is commonly used among professionals. You can extend it with various paid and unpaid plugins, but out-of-the-box it comes with a load of features already available. +[Visual studio code (VS Code)][vscode] is a free code editor created by Microsoft. +It includes great support for both [virtual/conda environments][virtual environments in vscode], as well as [`docker`][docker in vscode] (_via the [docker plug-in][vs code docker plugin]_) and can be extended with many different plugins for [testing][python testing in vscode], [linting][linting python in vscode], [formatting][formatting python in vscode], and [web development][python web dev in vscode]. -#### Selecting the interpreter +#### Python for VS Code -Open your project, then navigate to `File` >> `Settings` >> `Project: ...` >> `Python Interpreter`. Click on the dropdown menu and select the environment you will be using. If the environment you would like to use is not in the list click on the `Show All...` button: +Extension: _Extension-id: ms-python.python_ -![Interpreter Selection Dropdown](https://raw.githubusercontent.com/exercism/python/main/docs/img/PyCharm-Config-InterpreterDropDown.png) +![Python Extension Header on VS Code](https://raw.githubusercontent.com/exercism/python/main/docs/img/VSCode-EXT-Python-Header.png) -From there click on the `+` button to add a new interpreter. Select the type of interpreter on the left. We suggest you either run a [conda](#conda) or [virtualenv](#venv) environment, but running the *system interpreter* works fine, too. Once you selected your interpreter, press the `Okay` button. +The [Python extension from Microsoft][MS Python extension] is the official Microsoft Python extension to VS Code, and a highly recommended installation. +It has a wide range of features, including environment management, test management, linting, and debugging. +As of the [latest release][vs code python latest release], installing the MS Python extension will also download [pylance][vs code pylance] (_a popular package for linting and validating Python code_), and [jupyter][vs code jupyter] (_for working with Jupyter Notebooks_). -![Add New Interpreter](https://raw.githubusercontent.com/exercism/python/main/docs/img/PyCharm-Config-InterpreterNew.png) +- A setup tutorial is available [here][python extension setup tutorial] and the [settings reference][vs code python settings reference] is very helpful. +- Information on setting up Python versions/working with virtual environments can be found [here][virtual environments in vscode]. +- Information on setting up and working with unittest and pytest in VS Code can be found [here][python testing in vscode]. -#### Other features +
-Below are some other features that we won't cover in this guide, but are really useful for development. +### PyCharm -[Running Tests](https://www.jetbrains.com/help/pycharm/pytest.html#run-pytest-test) - Running tests directly from a GUI in your window is really easy, but don't forget to look at the [pytest parameters](TESTS.md#extra-arguments) to set it up to your liking. +[PyCharm][pycharm download] is an `IDE` (_Integrated Development Environment_) built by [JetBrains][jetbrains]. + It is purpose-built for Python and is popular among professionals . + Like VS Code, it can be extended with various paid and unpaid plugins, themes, and formatters. + The paid version also supports [Django development][pycharm django dev], [Docker development][pycharm docker], and [Database integration][pycharm database tools]. -[Debug Tools](https://www.jetbrains.com/help/pycharm/debugging-code.html) - Debugging in PyCharm is a great way to take advantage of its tools. +- Information on setting up Python versions can be found in [configuring a Python Interpreter][pycharm interpreter config] and [configuring a virtual environment][pycharm config venv]. +- Steps for setting up pytest with pycharm can be found [here][pycharm pytest docs]. + - Pycharm defaults to using `unittest`, so you must have `pytest` installed into the environment you are using with pycharm (_see the interpreter and environment documents above_), and then point pycharm to it. + - [Running Tests][pycharm gui running tests] directly from the GUI is really easy, but don't forget to take a good look at the underlying [pytest parameters](TESTS.md#extra-arguments), so that it is set up to your liking. +- General documentation for running tests and debugging in pycharm can be found [here][pycharm run tests]. +- Additional debugging tools and guidance can be found [here][pycharm debugging tools]. + - **warning**: The `coverage` plugin for `pytest` will break pycharm's debugger. + See [run/debug configuration: pytest][pycharm debug configuration] for more information. ---- +
### Spyder IDE -Spyder is a Python IDE tailored for the scientific community. It packs some really good debugging utilities and it has an integrated *IPython terminal*. Out-of-the-box it does not come with support for *unittests* and *pytests*, but there is an official plugin available. +[Spyder][spyder-ide] is a cross-platform free and open source Python IDE tailored for the scientific community. +It is commonly included with the Anaconda distribution of Python, but can be [installed by itself][spyder standalone installers] and used with any version of Python. +We recommend a standalone installation to ensure maximum flexibility, and that there are no package conflicts. -#### Selecting the interpreter +Spyder fully supports `venv` and `conda` environments. +It includes an integrated [IPython][ipython] interactive terminal, an interactive debugger, and rich support for in-editor graphing and data exploration. +Additional code completion and linting are provided via [kite][kite]. +Integrations with [Jupyter Notebooks][spyder notebook plugin] and [testing tools][spyder unittest plugin] are provided via community-developed plugins. +You can also write [plugins of your own][writing spyder plugins], using the Spyder API. -To change the interpreter, go to `tools` >> `Preferences` >> `Python interpreter`. You can either select the global interpreter defined by Spyder or you can enter the path to your own Python environment. +- Setting Python [versions/virtual environments][spyder environments] in Spyder +- Setting up Spyder to run `unittest` and `pytest` tests via [spyder unittest plugin][spyder unittest plugin] +- Spyder [installation guide][spyder installation guide] + - [Standalone installers][spyder standalone installers] + - [Alternative installation methods][spyder alternate installation] + - [Notes on upgrading Spyder][spyder updating install] +- Spyder [quickstart guide][spyder quickstart guide] + - [First steps video][spyder first steps] + - [Running via Anaconda][spyder with Anaconda] + - [Creating a conda env just for Spyder][spyder conda env] +- Spyder [FAQ][spyder faq] +- Spyder [troubleshooting guide][spyder troubleshooting guide] +- Additional [spyder plugins][spyder plugins list] -![Spyder Python Interpreter Selection](https://raw.githubusercontent.com/exercism/python/main/docs/img/Spyder-Config-Interpreter.png) +
-Do not forget to click `Apply` once you selected your interpreter. +### Emacs -#### Other features +[Emacs][emacs] is a free, open source, and highly customizable text editor written in Lisp. +A great [installation and setup guide][emacs setup at real python] is available at Real Python. -[Spyder Unittest](https://github.com/spyder-ide/spyder-unittest/releases/latest) - This plugin gives you a built-in interface for running your tests. This link will bring you to the latest release on GitHub. +- The [Emacs Wiki][emacs wiki python programming] also has a good guide to Python programming with Emacs. +- [Full Stack Python][emacs at fullstack python] also collects some good information and links for getting started with Emacs. -[Code analyzer](https://docs.spyder-ide.org/current/panes/pylint.html#using-the-code-analyzer) - This tool can analyze your code, detecting bad practices, and catching bugs before you run your program. You can also configure it to only show [PEP 8](https://www.python.org/dev/peps/pep-0008/) violations. +
-[Debugging](https://docs.spyder-ide.org/current/panes/debugging.html) - This tool will help you debug your code, it allows you to set a `breakpoint` on a line. The debugging tool will then let you go through your Python code and quickly notice where it goes wrong. +### Vim -[Variable Explorer](https://docs.spyder-ide.org/current/panes/variableexplorer.html) - This tool is really useful in combination with the debugger. It allows you to view all the active variables in your code and it even allows you to edit of the values inside those variables. +[Vim][vimdotorg] is a free and "improved" version of the Unix standard `vi` text editor. +It is available on a wide variety of operating systems and Linux/Unix flavors. +A great [installation and setup guide][vim setup at real python] is available at Real Python, and handy cheat sheets are available at [vimsheet][vim cheat sheet], [glump][glump vim cheatsheet], and [rtorr][rtorr vim cheat sheet]. ---- -### Sublime text +Even if you decide editing Python code in `vim` is not for you, it is recommended that you familiarise with a basic set of commands. +`vim` or `vi` is often a "base" or "default" text editor in Linux and Unix distributions and is the default editor for `git` commit messages (_among other things_) on those systems. +Chances are good you will find yourself on a *nix system needing to edit a configuration file with only `vi` available, so knowing how to [quit vim][how do I quit vim] is (_at the very least_) good self defense. -Sublime text is text editor for coding, made by *Sublime HQ Pty Ltd*. It is similar to [VS Code](#visual-studio-code) in many regards. Sublime text is very customizable. It comes with an auto-complete engine and with Python syntax highlighting out-of-the-box. +
-#### Notable extensions +### Spacemacs -Sublime Text comes with a lot of tools already, but some of these tools could make your Python development easier. Make sure you have *package control* installed, go to `Tools` >> `Install Package Control...`. To install packages open your command pallet and type in `Package Control: Install Package`, here you can enter the name of the packages you'd like to install. +[Spacemacs][spacemacs] (_[github repo][spacemacs github repo]_) is a free community-driven distribution of Emacs that combines functionality from both Emacs and Vim. -[Terminus](https://packagecontrol.io/packages/Terminus) - A terminal for Sublime. Terminus is fully featured and has support for Windows operating systems. This package is a must-have for running `pytest` scripts. +- Official documentation can be found [here][spacemacs official docs] +- This [guide][opensource spacemacs guide] at opensource gives a quick rundown of installation and configuration options. +- The spacemacs [python layer][spacemacs python layer] adds functionality for testing, linting, environment management, and code formatting. -[SublimeLinter](https://packagecontrol.io/packages/SublimeLinter) - A linter for sublime. This tool notifies you about Python code that does not follow best practices. We recommend you set it up to use PEP-8. +
-### JupyterLab - -[Jupyter lab](https://jupyter.org/install) is an in-browser code editor that runs on your machine, combining the ability to write Markdown along side executable code and data. Jupyter supports multiple programming languages via `kernels` and can display graphs and tables as well as code and text. - -Jupyter comes pre-packaged with Anaconda. You can also install it in a **virtual environment** using `pip` or `conda`. Jupyter will use that environment and its Python version. Jupyter is most well-known for its code "notebooks". It is commonly used among data-scientists. - -#### Notable extensions +### Sublime text -The built-in tools for Jupyter Lab are sufficient for almost all exercises on Exercism. Most extensions to Jupyter focus more on data-science applications and not general-purpose programming. Explore extensions at your own pleasure. +[Sublime text][sublime text 4] is a paid text editor for coding, made by *Sublime HQ Pty Ltd*. +It is similar to [VS Code](#visual-studio-code) and [Atom][atom], with many [packages and plugins][sublime package control] for customization. +You can also [develop plugins][sublime plugin development] of your own for the editor using Python. + +- [Purchasing and installing][sublime purchasing and installing] Sublime +- Sublime [documentation][sublime official docs] and [support documentation][sublime support docs] +- Sublime [community documentation][sublime community docs] +- Full Stack Python has a great guide on [Sublime Text][sublime at fullstack python], with many links to tutorials. +- Real Python also offers a great guide to [setting up Sublime Text 3][sublime text at real python] +- The Chromium project also has [setup and usage][sublime chromium setup] instructions. + +[Installing Python locally]: https://exercism.org/docs/tracks/Python/installation +[MS Python extension]: https://marketplace.visualstudio.com/items?itemName=ms-python.python +[anaconda]: https://www.anaconda.com/products/individual +[atom]: https://atom.io/ +[conda command ref]: https://docs.conda.io/projects/conda/en/latest/commands.html#conda-vs-pip-vs-virtualenv-commands +[conda-cheatsheet]: https://docs.conda.io/projects/conda/en/latest/_downloads/843d9e0198f2a193a3484886fa28163c/conda-cheatsheet.pdf +[conda-docs]: https://docs.conda.io/projects/conda/en/latest/user-guide/index.html +[conda]: https://docs.conda.io/projects/conda/en/latest/index.html +[condaenv]: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html +[docker in vscode]: https://code.visualstudio.com/docs/containers/overview +[emacs at fullstack python]: https://www.fullstackpython.com/emacs.html +[emacs setup at real python]: https://realpython.com/emacs-the-best-python-editor +[emacs wiki python programming]: https://www.emacswiki.org/emacs/PythonProgrammingInEmacs#h5o-4 +[emacs]: https://www.gnu.org/software/emacs/ +[formatting python in vscode]: https://code.visualstudio.com/docs/python/editing#_formatting +[glump vim cheatsheet]: https://www.glump.net/_media/howto/desktop/vim-graphical-cheat-sheet-and-tutorial/vi-vim-cheat-sheet-and-tutorial.pdf +[how do I quit vim]: https://stackoverflow.com/questions/11828270/how-do-i-exit-the-vim-editor +[ipython]: https://ipython.org/ +[jetbrains]: https://www.jetbrains.com/ +[kite]: https://www.kite.com/ +[linting python in vscode]: https://code.visualstudio.com/docs/python/linting +[miniconda]: https://docs.conda.io/en/latest/miniconda.html +[opensource spacemacs guide]: https://opensource.com/article/19/12/spacemacs +[pycharm config venv]: https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html +[pycharm database tools]: https://www.jetbrains.com/help/pycharm/relational-databases.html +[pycharm debug configuration]: https://www.jetbrains.com/help/pycharm/run-debug-configuration-py-test.html +[pycharm debugging tools]: https://www.jetbrains.com/help/pycharm/debugging-code.html +[pycharm django dev]: https://www.jetbrains.com/help/pycharm/django-support7.html +[pycharm docker]: https://www.jetbrains.com/help/pycharm/docker.html +[pycharm download]: https://www.jetbrains.com/pycharm/download/ +[pycharm gui running tests]: https://www.jetbrains.com/help/pycharm/pytest.html#run-pytest-test +[pycharm interpreter config]: https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html +[pycharm pytest docs]: https://www.jetbrains.com/help/pycharm/pytest.html +[pycharm run tests]: https://www.jetbrains.com/help/pycharm/performing-tests.html +[pyenv on github]: https://github.com/pyenv/pyenv +[pyenv]: https://github.com/pyenv/pyenv +[python extension setup tutorial]: https://code.visualstudio.com/docs/python/python-tutorial +[python testing in vscode]: https://code.visualstudio.com/docs/python/testing +[python track on github]: https://github.com/exercism/python/blob/main/docs/TOOLS.md +[python web dev in vscode]: https://code.visualstudio.com/docs/python/tutorial-django +[rtorr vim cheat sheet]: https://vim.rtorr.com/ +[spacemacs github repo]: https://github.com/syl20bnr/spacemacs +[spacemacs official docs]: https://github.com/syl20bnr/spacemacs#documentation +[spacemacs python layer]: https://www.spacemacs.org/layers/+lang/python/README.html +[spacemacs]: https://www.spacemacs.org/ +[spyder alternate installation]: https://docs.spyder-ide.org/current/installation.html#alternative-methods +[spyder conda env]: https://docs.spyder-ide.org/current/installation.html#new-conda-environment +[spyder environments]: https://docs.spyder-ide.org/5/faq.html#using-existing-environment +[spyder faq]: https://docs.spyder-ide.org/5/faq.html +[spyder first steps]: https://docs.spyder-ide.org/current/videos/first-steps-with-spyder.html +[spyder installation guide]: https://docs.spyder-ide.org/current/installation.html +[spyder notebook plugin]: https://github.com/spyder-ide/spyder-notebook +[spyder plugins list]: https://docs.spyder-ide.org/5/faq.html#using-plugins +[spyder quickstart guide]: https://docs.spyder-ide.org/current/quickstart.html +[spyder standalone installers]: https://docs.spyder-ide.org/current/installation.html#standalone-installers +[spyder troubleshooting guide]: https://github.com/spyder-ide/spyder/wiki/Troubleshooting-Guide-and-FAQ +[spyder unittest plugin]: https://github.com/spyder-ide/spyder-unittest +[spyder updating install]: https://docs.spyder-ide.org/current/installation.html#updating-spyder +[spyder with Anaconda]: https://docs.spyder-ide.org/current/installation.html#anaconda +[spyder-ide]: https://www.spyder-ide.org/ +[sublime at fullstack python]: https://www.fullstackpython.com/sublime-text.html +[sublime chromium setup]: https://chromium.googlesource.com/chromium/src.git/+/HEAD/docs/sublime_ide.md +[sublime community docs]: https://docs.sublimetext.io/ +[sublime official docs]: https://www.sublimetext.com/docs/index.html +[sublime package control]: https://packagecontrol.io/ +[sublime plugin development]: https://docs.sublimetext.io/guide/extensibility/plugins/ +[sublime purchasing and installing]: https://www.sublimetext.com/download +[sublime support docs]: https://www.sublimetext.com/support +[sublime text 4]: https://www.sublimetext.com/ +[sublime text at real python]: https://realpython.com/setting-up-sublime-text-3-for-full-stack-python-development/ +[venv wrapper tutorial]: https://virtualenvwrapper.readthedocs.io/en/latest/plugins.html#plugins +[venv]: https://docs.python.org/3.9/tutorial/venv.html +[vim cheat sheet]: https://vimsheet.com/ +[vim setup at real python]: https://realpython.com/vim-and-python-a-match-made-in-heaven/ +[vimdotorg]: https://www.vim.org/ +[virtual environments in vscode]: https://code.visualstudio.com/docs/python/environments +[virtualenvwrapper]: https://virtualenvwrapper.readthedocs.io/en/latest/ +[vs code docker plugin]: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker +[vs code jupyter]: https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter +[vs code pylance]: https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance +[vs code python latest release]: https://marketplace.visualstudio.com/items?itemName=ms-python.python +[vs code python settings reference]: https://code.visualstudio.com/docs/python/settings-reference +[vscode]: https://code.visualstudio.com/ +[writing spyder plugins]: https://docs.spyder-ide.org/current/workshops/plugin-development.html diff --git a/exercises/shared/.docs/help.md b/exercises/shared/.docs/help.md index 9166baec49..0739a603ea 100644 --- a/exercises/shared/.docs/help.md +++ b/exercises/shared/.docs/help.md @@ -4,10 +4,12 @@ Below are some resources for getting help if you run into trouble: - [The PSF](https://www.python.org) hosts Python downloads, documentation, and community resources. - [Python Community on Discord](https://pythondiscord.com/) is a very helpful and active community. -- [#python on Libera.chat](https://www.python.org/community/irc/) this is where the cored developers for the language hang out and get work done. -- [Exercism on Gitter](https://gitter.im/exercism/home) join the Python room for Python-related questions or problems. - [/r/learnpython/](https://www.reddit.com/r/learnpython/) is a subreddit designed for Python learners. +- [#python on Libera.chat](https://www.python.org/community/irc/) this is where the core developers for the language hang out and get work done. +- [**Exercism on Gitter**](https://gitter.im/exercism/home) join the Python room for Python-related questions or problems. - [Python Community Forums](https://discuss.python.org/) +- [Free Code Camp Community Forums](https://forum.freecodecamp.org/) +- [CodeNewbie Community Help Tag](https://community.codenewbie.org/t/help) - [Pythontutor](http://pythontutor.com/) for stepping through small code snippets visually. diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md index e3905ce64d..196bf8c25b 100644 --- a/exercises/shared/.docs/tests.md +++ b/exercises/shared/.docs/tests.md @@ -1,19 +1,154 @@ # Tests -To run the included *tests*, run the test file using the `pytest` module, replacing `{exercise_name}`: +We use [pytest][pytest: Getting Started Guide] as our website test runner. +You will need to install `pytest` on your development machine if you want to download and run exercise tests for the Python track locally. +You should also install the following `pytest` plugins: + +- [pytest-cache][pytest-cache] +- [pytest-subtests][pytest-subtests] + +We also recommend using the code linting program [pylint][pylint], as it is part of our automated feedback on the website and can be a very useful static code analysis tool. +For ease-of-use, the [pytest-pylint][pytest-pylint] plugin for `pytest` will allow you to run `pylint` via `pytest` on the command line. + +Pylint configuration can be a bit much, so this [tutorial][tutorial from pycqa.org] from pycqa.org can be helpful for getting started, as can this overview of [Code Quality: Tools and Best Practices][Code Quality: Tools and Best Practices] from Real Python. + + +## Installing pytest + +Pytest can be installed and updated using the built-in Python utility [`pip`][pip]. + +For additional tips, Brett Cannon has a nice [quick-and-dirty guide on how to install packages for python][brett cannon: quick-and-dirty], along with a great explanation on [why you should use `python -m pip`][brett cannon: python-m-pip]. +For more on Python's command line arguments, see [command line and environment][python command line arguments] in the Python documentation. + +**Note:** `Python3` may or may not be an alias for Python on your system. +Please adjust the install commands below accordingly. +To install `pytest` in a virtual environment, ensure the environment **is activated** prior to executing commands. +Otherwise, the pytest installation will be global. + + +#### Windows + +```powershell +PS C:\Users\foobar> python3 -m pip install pytest pytest-cache pytest-subtests pytest-pylint +Successfully installed pytest-6.2.5 ... +``` + +#### Linux / MacOS ```bash -$ python3 -m pytest {exercise_name}_test.py +$ python3 -m pip install pytest pytest-cache pytest-subtests pytest-pylint +Successfully installed pytest-6.2.5 ... + ``` -Many IDE's and code editors have built-in support for using Pytest to run tests; check them out [here](https://github.com/exercism/python/blob/main/docs/TOOLS.md#editors-and-ides). -For more information about running tests using `pytest`, checkout our [Python testing guide](https://github.com/exercism/python/blob/main/docs/TESTS.md#pytest). +To check if installation was successful: + +```bash +$ python3 -m pytest --version +pytest 6.2.5 +``` + +## Running the tests + +To run the tests, go to the folder where the exercise is stored using `cd` in your terminal (_replace `{exercise-folder-location}` below with your path_). + +```bash +$ cd {exercise-folder-location} +``` + +The file you will want to run usually ends in `_test.py`. +This file contains the tests for the exercise solution, and are the same tests that run on the website when a solution is uploaded. +Next, run the following command in your terminal, replacing `{exercise_test.py}` with the location/name of the test file: + +```bash +$ python3 -m pytest -o markers=task {exercise_test.py} +==================== 7 passed in 0.08s ==================== +``` ### Common pytest options +- `-o` : override default `ini` (_you can use this to avoid marker warnings_) - `-v` : enable verbose output. - `-x` : stop running tests on first failure. - `--ff` : run failures from previous test before running other test cases. For other options, see `python3 -m pytest -h`. + + +### Fixing warnings + +If you do not use the `pytest -o markers=task` in the command above, is possible that you will get `warnings` about "unknown markers" when running a test that uses our _new_ syntax. + +To avoid typing `pytest -o markers=task` for every test you run, you can use a `pytest.ini` configuration file, which can be downloaded from the top level of the Python track directory: [pytest.ini][pytest.ini]. + +You can also create your own `pytest.ini` file with the following content: + +```ini +[pytest] +markers = + task: A concept exercise task. +``` + +Placing this file in the _root_ or _working_ directory for the Python track exercises will register the marks and stop the warnings. +More information on pytest marks can be found in the `pytest` documentation on [marking test functions][pytest: marking test functions with attributes] and the `pytest` documentation on [working with custom markers][pytest: working with custom markers]. + +_More information on customizing pytest configurations can be found in the pytest documentation on [configuration file formats][pytest: configuration file formats]_ + + +### Recommended Workflow + +We recommend using the following commands to make your debugging easier and (possibly) faster: + +First change your working directory to the directory of the exercise you want to test: + +```bash +$(my_venv) cd path/to/exercise +``` + +Then, run the tests together with the previously explained arguments `-x` and`--ff`: + +```bash +$(my_venv) python3 -m pytest -o markers=task -x --ff +``` + +This will test your solution. +When `pytest` encounters a failed test, the program will stop and tell you which test failed. +When you make fixes and run the test again, `pytest` will first run the previous test that failed, then continue with the remaining tests. + + +### Using PDB, the Python Debugger, with pytest + +You can use the `--pdb` argument after the `pytest` command and drop into the built-in [Python debugger][pdb], `PDB` on test failure: + +```bash +$(my_venv) python3 -m pytest -o markers=task -x --ff --pdb +=============== 4 passed in 0.15s =============== +``` + +Dropping into `PDB` will allow you to step through your code viewing the current scope, as well as checking the value of variables and the signature of different functions. +More details on the `PDB` module can be found in the [Python documentation on PDB][pdb]. +Additionally, the [pytest docs on PDB][pytest-pdb] and [this guide from Real Python](https://realpython.com/python-debugging-pdb/) are extremely helpful. + +## Extending your IDE + +If you'd like to extend your IDE with some tools that will help you with testing and improving your code, the Python track [tools page][Python track tools page] on exercism.org goes over some options. + +[Code Quality: Tools and Best Practices]: https://realpython.com/python-code-quality/ +[Pytest: Getting Started Guide]: https://docs.pytest.org/en/latest/getting-started.html +[Python track tools page]: https://exercism.org/docs/tracks/python/tools +[brett cannon: python-m-pip]: https://snarky.ca/why-you-should-use-python-m-pip/ +[brett cannon: quick-and-dirty]: https://snarky.ca/a-quick-and-dirty-guide-on-how-to-install-packages-for-python/ +[pdb]: https://docs.python.org/3.9/library/pdb.html +[pip]: https://pip.pypa.io/en/stable/getting-started/ +[pylint]: https://pylint.pycqa.org/en/latest/user_guide/ +[pytest-cache]:http://pythonhosted.org/pytest-cache/ +[pytest-pdb]: https://docs.pytest.org/en/6.2.x/usage.html#dropping-to-pdb-python-debugger-on-failures +[pytest-pylint]:https://github.com/carsongee/pytest-pylint +[pytest-subtests]:https://github.com/pytest-dev/pytest-subtests +[pytest.ini]: https://github.com/exercism/python/blob/main/pytest.ini +[pytest: configuration file formats]: https://docs.pytest.org/en/6.2.x/customize.html#configuration-file-formats +[pytest: marking test functions with attributes]: https://docs.pytest.org/en/6.2.x/mark.html#raising-errors-on-unknown-marks +[pytest: working with custom markers]: https://docs.pytest.org/en/6.2.x/example/markers.html#working-with-custom-markers +[python command line arguments]: https://docs.python.org/3/using/cmdline.html +[tutorial from pycqa.org]: https://pylint.pycqa.org/en/latest/tutorial.html