From 6a609a3bd6b5050a12bf3d87b2170f20c16f4bee Mon Sep 17 00:00:00 2001 From: wookie184 Date: Wed, 2 Nov 2022 19:31:11 +0000 Subject: Move guides to a subdirectory --- .../guides/python-guides/common-windows-issues.md | 188 --------------------- .../creating-python-environment-windows.md | 72 -------- .../guides/python-guides/install-on-windows.md | 63 ------- .../guides/python-guides/microsoft-store.md | 36 ---- .../guides/python-guides/python-on-windows.md | 140 --------------- .../guides/python-guides/windows/_info.yml | 2 + .../python-guides/windows/common-windows-issues.md | 188 +++++++++++++++++++++ .../windows/creating-python-environment-windows.md | 72 ++++++++ .../python-guides/windows/install-on-windows.md | 63 +++++++ .../python-guides/windows/microsoft-store.md | 36 ++++ .../python-guides/windows/python-on-windows.md | 140 +++++++++++++++ 11 files changed, 501 insertions(+), 499 deletions(-) delete mode 100644 pydis_site/apps/content/resources/guides/python-guides/common-windows-issues.md delete mode 100644 pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md delete mode 100644 pydis_site/apps/content/resources/guides/python-guides/install-on-windows.md delete mode 100644 pydis_site/apps/content/resources/guides/python-guides/microsoft-store.md delete mode 100644 pydis_site/apps/content/resources/guides/python-guides/python-on-windows.md create mode 100644 pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml create mode 100644 pydis_site/apps/content/resources/guides/python-guides/windows/common-windows-issues.md create mode 100644 pydis_site/apps/content/resources/guides/python-guides/windows/creating-python-environment-windows.md create mode 100644 pydis_site/apps/content/resources/guides/python-guides/windows/install-on-windows.md create mode 100644 pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md create mode 100644 pydis_site/apps/content/resources/guides/python-guides/windows/python-on-windows.md (limited to 'pydis_site/apps/content/resources/guides') diff --git a/pydis_site/apps/content/resources/guides/python-guides/common-windows-issues.md b/pydis_site/apps/content/resources/guides/python-guides/common-windows-issues.md deleted file mode 100644 index 0bdb11ef..00000000 --- a/pydis_site/apps/content/resources/guides/python-guides/common-windows-issues.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Common issues using Python on Windows -description: This guide describes common issues you may run into when using Python on Windows and how to fix them. ---- - -### When I run `python` in the terminal I get no result, or the Windows Store opens! - -By default Windows has an alias for `python` in the terminal to guide you to -install it from the Microsoft Store. I would not recommend that you install -Python from the Microsoft Store, see why [here](../microsoft-store.md). -To disable this alias, search "App execution aliases" in windows search and -click on "Manage app execution aliases". In the list you should see two options -with title "App Installer" and descriptions `python.exe` and `python3.exe`. -Disable both of them. - -Note that if you are following instructions telling you to run a command -starting with `python3`, those instructions are intended for Unix/macOS systems. -Try just using `python` instead. - -If after doing this you have an issue with the Python command not being -detected, see the below question. - -### When I try and run my code with `python` in the terminal I get an error saying the command was not recognised - -If you have not installed Python, you will need to do that. Follow our guide [here](../install-on-windows.md). - -If you have installed python and are still having the issue, it is likely that -you forgot to add to PATH when doing so. See [our guide on adding Python to -PATH](../python-on-windows.md#changing-path) for how to fix this. -You can also use the `py` launcher instead of `python` by just replacing -`python` in your command with `py`. See -[this guide](../python-on-windows.md#the-py-launcher) for more information -on that. - -### I `pip` installed a package but when running my code get a `ModuleNotFoundError` - -* #### Are you actually getting a `ModuleNotFoundError`? - - If you are using a code editor such as VSCode or Pycharm you may get a - squiggly line under your import saying the module couldn't be found, it is - possible that this is just an mistake by the editor, so try actually running - your code with to ensure if it actually errors. - - If your code runs fine, you could try restarting your editor. If you have - newly installed a module it may just not have detected it yet. If that - doesn't help, you may need to configure your editor to ensure it is looking - for the module in the correct Python environment. See - [our guide on virtual environments](./python-on-windows.md#virtual-environments) - for more information. - -* #### Was the install successful? - - Look out for errors when installing the module you want. If you get an - error, that's probably why the import isn't working, so you should look - into it. Often a google search will help with this. - -* #### Did you use the correct module name? - - Double check that you haven't made a typo in the name you are importing, or - in what you installed from PyPI, you need to make sure you type the name - exactly as it should be. - - Also, **the name you should `import` may not be the same as the name you `pip - install`**. Check the module's documentation or PyPI page if you are unsure. - Examples of this are: - - * [**opencv-python**](https://pypi.org/project/opencv-python/): You need to - `pip install opencv-python`, but the import has to be `import cv2` - * [**discord.py**](https://pypi.org/project/discord.py/): You need to `pip - install discord.py`, but the import has to be `import discord` - * [**python-dotenv**](https://pypi.org/project/python-dotenv/): You need to - `pip install python-dotenv`, but the import has to be `import dotenv` - -* #### Are you installing to the same environment you're running your code from? - - This is a very common issue. When you install a module from PyPI, you will - install it into a single Python environment, the one that the `pip` you - invoked is part of. This could be different to the one you are running - the script from if it's using a different Python installation, - or a virtual environment. - - ###### I'm using Pycharm - - PyCharm creates a virtual environment for each project by default, so if - you're installing a module using Pycharm you need to make sure you also run - your code through PyCharm. This also applies the other way round, if you - want to use a module in PyCharm you need to install it through PyCharm. - - It's also possible to change PyCharm to use your system environment, see - [their guide on configuring your interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html) - for more information. - - ###### I installed the module using pip from the command line - - Run `pip -V` and look at the path returned it should be in the form - `\Lib\site-packages\pip`. - - Then put `import sys;print(sys.executable);sys.exit(0)` at the top - (above imports!) of your python file, and run it. The result should be - in the form `\python.exe`. - - Now compare that `PATH_TO_PYTHON` to the one from `pip -V`. If they're - different, this is the cause of the `ModuleNotFoundError`. Follow the - relevant "I'm running my code with ..." section below for how to fix - this. - - ###### I'm running my code with `python` from the terminal. - - If you are using a virtual environment, ensure you have activated it before - running `pip install`. You can test this by running `pip -V` and checking - the path is the one of your virtual environment. - - Alternatively, you can use the `py` command to specify the python version - you want to pip install into, e.g. `py -3.9 -m pip install numpy`, and to - specify the executable you want to run your code with, e.g. `py -3.9 - my_script.py`. - - If your `pip` and `python` commands are referring to different python - environments at the same time, it's possible your PATH is configured - incorrectly. See our - [guide for adding Python to PATH](../python-on-windows.md#adding-python-to-your-path) - for how to fix this. - - ###### I'm running my code with the button in VSCode - - To run your code from the same environment you installed Python to, set - the interpreter to the one at the path you found when running `pip -V` - by following - [this guide](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment). - The path should be in the form `PATH_TO_PYTHON\python.exe` - - Alternatively, you can pip install to the currently activated - environment. If you have configured VSCode to use a virtual environment, - it should automatically activate it when you open a new terminal, so - running the `pip install` command in the VSCode terminal should work. If - you are not using a virtual environment, you can use the `py` launcher - to specify the installation you want to install to. - -### I `pip` installed a command line program but it isn't recognised - -You pip installed a command line program like `PyInstaller` or `black` that is -intended to be run from the command line, but it does not work. Two common causes -for this are: - -* You are using Python from the Microsoft Store - - To check if this is the case, type `pip -V`. If the path output includes - something like - `PythonSoftwareFoundation.Python.3.10_3.10.2288.0_x64__qbz5n2kfra8p0`, you - are using Python from the Microsoft Store. To fix this you will either have - to use the full path to the scripts you want to use, or uninstall the - Microsoft Store Python and install Python properly with the online - installer. - -* You manually modified your PATH Environment Variable incorrectly - - If you added `Python` to PATH manually through environment variables, it is - possible that you only added the executable but not the `/Scripts` folder. - This would cause issues with `pip` and make command line tools not - accessible. Look at our [guide on adding Python to the - PATH](../python-on-windows.md#adding-python-to-your-path) for how to verify - and fix this. - -Projects that add a command line program usually work by adding an executable to -the `/Scripts` folder of your Python install. If you clicked "Add to PATH" when -installing Python this folder will have been added to PATH, so anything there -should be runnable directly from the command line. This should also be the case -when using a virtual environment, as long as it is properly activated. - -### I get a `SyntaxError` when trying to run `pip`,`python`, or another command. - -When you type `python` in the terminal you enter into the python REPL -(read-evaluate-print loop). This lets you run `Python` code line by line without -having to create a file. - -General commands like `pip` and `python` should be run in the terminal, not in -the Python REPL. To exit the REPL, type `exit()` and press enter. You should -then be able to run your commands normally. - -### I tried to uninstall Python by deleting the folder, now it doesn't work and I can't reinstall it! - -You should never uninstall your Python installation by deleting the folder it is -in. If you have, you may need to edit Registry Keys to fully remove the -installation. Doing this is dangerous and beyond the scope of this guide. - -To uninstall Python properly, run the installer for the version you want to -uninstall and select "uninstall". If you no longer have the installer, you can -re-download it first. diff --git a/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md b/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md deleted file mode 100644 index 635c384f..00000000 --- a/pydis_site/apps/content/resources/guides/python-guides/creating-python-environment-windows.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Creating a Unix-style Python Environment on Windows -description: How to setup Python for Windows. ---- - -Many programmers use Linux or macOS operating systems for their work, though newcomers to programming will likely want to get started on the computer they already own, which will often be running Windows. -This guide will help you install Python on Windows. - -Programmers also need to become comfortable using a command prompt (also known as a terminal), and many guides for both beginning and advanced programming will often tell you certain commands to run. -The Windows command prompt has different names for similar commands that are available on Linux and macOS. -This guide will also help you set up a command prompt called Git Bash, which will support many of the commands available on Linux and macOS. - -## Installing Python -Python can be downloaded from the Python website on the [downloads page](https://www.python.org/downloads/). -The website will automatically present you with a download button for the latest release of the Windows version when you access the site from a Windows machine. - -Once the download is complete, you can begin the installation. -Select "Customize Installation". -The default settings for "Optional Features" are sufficient and you can click "Next". - -The next step is to decide on a location where the Python executable can be stored on your computer. -This should be a location that's easy for you to remember. -One possibility is to create a folder called "Python" at the root of your hard drive. -Once you have selected a location, you can click "Install", as no other settings on this screen need to be adjusted. -This will complete the installation. - -## Installing a text editor -You will also need a text editor for writing Python programs, and for subsequent steps of this guide. -Powerful programs called integrated development environments (IDEs) like PyCharm and Visual Studio Code contain text editors, but they also contain many other features with uses that aren't immediately obvious to new programmers. - -[Notepad++](https://notepad-plus-plus.org/) is a popular text editor for both beginners and advanced users who prefer a simpler interface. -Other editors we recommend can be found [here](https://pythondiscord.com/resources/tools/#editors). - -## Installing Git Bash -Git is a command line program that helps you keep track of changes to your code, among other things. -Many developers use it, and while you may not need it right away, it is useful to install it because it comes with Git Bash. -On the "Select Components" screen, no settings need to be changed. -The next screen will ask what text editor you want to use with Git. Vim is the default choice, though Vim is widely considered difficult to learn, so you may choose to select Notepad++ or whichever text editor you may have installed previously. - -For all remaining screens in the installation, the default selections are fine. - -## Configuring .bashrc -`.bashrc` is a file where we tell Git Bash where the Python executable is. -First, open Git Bash, and as your first command, type `echo ~` and hit enter. -This will most likely print `c/Users/YourUsername` to the terminal. -Navigate to this location in your file explorer, though keep in mind that Windows will display `c/Users/YourUsername` as `C:\Users\YourUsername`. -In this folder, there will be a file called `.bashrc`; open it with your text editor of choice. - -For this step, you will need to remember where you installed Python earlier. -In whichever folder that was, there is a file called `python.exe`; this is the executable that will run your Python programs. -Copy the full path of this file, starting from `C:`. -If you used the example location given earlier, it will be located at `C:\Python\python.exe`. - -In the `.bashrc` file, add a line to the end of the file saying `alias python='C:\\Python\\python.exe`, where `C:\\Python\\python.exe` is the location of your `python.exe` file, but each folder is separated by two backslashes instead of one. -The two backslashes are because a single backslash is used as an [escape character](https://en.wikipedia.org/wiki/Escape_character). -Save the file, and then type `source ~/.bashrc` to activate the change you have made. - -Finally, enter `python -c 'import sys; print(sys.executable)'` into Git Bash. -(If you attempt to copy and paste this into the terminal using Ctrl+V, it might not work, though Shift+Insert will.) -If all the steps have been followed correctly, this will print the location of your `python.exe` file and demonstrate that your environment is set up correctly. -You can hereafter use the `python` command in Git Bash to run any Python program that you write. - -## Running a test program -At any location on your computer, create a file named `hello.py` and open it with your text editor. -The program need only be one line: `print('Hello world!')`. -Save this file. - -To run this program in Git Bash, navigate to where it is saved on your hard drive. -If you know the path to this location, you can use the `cd` command ("cd" stands for "change directory") to navigate to it. -If it's saved to your desktop, `cd /c/Users/YourUsername/Desktop` will take you there. -Otherwise if you have the directory open in your file explorer, you can right click anywhere in the white space of the file explorer window (not on top of a file) and select "Git Bash Here". -Once you're there, type `python hello.py`, and the program will run. diff --git a/pydis_site/apps/content/resources/guides/python-guides/install-on-windows.md b/pydis_site/apps/content/resources/guides/python-guides/install-on-windows.md deleted file mode 100644 index 2422e024..00000000 --- a/pydis_site/apps/content/resources/guides/python-guides/install-on-windows.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Installing Python on Windows -description: How to properly install python on windows ---- - -The recommended way to install Python on windows is directly from the -[Python website's Downloads page](https://www.python.org/downloads/windows/). -Installing Python from the Microsoft Store is not recommended as it can -[cause issues](../microsoft-store.md). - -## Selecting an Installer -There are many different installer options available from the downloads page. -You should usually select the "Windows installer" option instead of the "Windows -embeddable package". Some minor versions may not - -### Which version? -Current Python versions follow the form `3.major.minor`. Major releases happen -yearly and provide new features and breaking changes, whilst minor releases are -more common and only include bug/security fixes. - -Installing the latest major version will give you access to Python's newest -features. However, some modules may not support the newest versions straight -away, so installing the second latest will help you avoid those issues. If you -find you want some newer features or your module does not support your current -version, you can always install another version as well. - -You should generally always install the newest minor version, although some may -not provide an installer in which case you should find the newest that does. - -### 32-bit vs 64-bit? -Install 64-bit python unless you have reason not to. With 32 bit you may run -into memory limits if doing intensive operations (Python will be limited to -using 4GB of memory), and some installed modules may not offer prebuilt wheels -for 32 bit, potentially making installs slower or meaning you have to install -build dependencies. - -If you get an error when installing 64-bit Python, your computer may not support -it. To find out if this is the case, search "About your PC" in windows search -and open the settings page. Then look for the "System Type" option under "Device -Specifications". It should say "64-bit operating system, x64-based processor" if -you have support. You need a 64 bit processor and OS to install 64 bit programs. - -## Running the installer -When you run the installer you should see a screen like this: - -![python_installer_screen](https://user-images.githubusercontent.com/22353562/126144479-cfe6bd98-6d2e-47c3-b6b3-5de9f2656e9a.png) - -Make sure you tick "Add Python 3.x to Path". This allows you to use the `python` -and `pip` commands in your terminal to invoke Python. If you already have a -Python installation on your PATH and don't want this one to override it, don't -tick this. - -If you installed Python without adding to PATH and now want to add it, see -[our guide on adding Python to PATH](../python-on-windows.md#adding-python-to-your-path). - -Then simply click install, and wait for the install to finish! - -To test your installation, type "cmd" in the windows search bar and select -"Command Prompt" to open a terminal (make sure it's opened *after* installation -has finished) type `python -V`, and press enter. If it outputs your python -version, you've successfully installed Python. (if you didn't add to PATH, you -can use [the py launcher](../python-on-windows.md#the-py-launcher) to test -instead). diff --git a/pydis_site/apps/content/resources/guides/python-guides/microsoft-store.md b/pydis_site/apps/content/resources/guides/python-guides/microsoft-store.md deleted file mode 100644 index 8935163b..00000000 --- a/pydis_site/apps/content/resources/guides/python-guides/microsoft-store.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Why not to install Python from the Microsoft Store -description: This guide explains the issues with using Python installed from the Microsoft Store ---- - -Microsoft provides a Python app on the Microsoft Store as an alternative to -using the [Standard Installer](https://www.python.org/downloads/). We would -recommend that you use the standard installer instead wherever possible. - -Here are some common issues with using Python from the Microsoft Store: - -* ##### Command line tools won't work - Most command line tools, like `black` or `pyinstaller`, won't work directly - (without specifying the full path, or invoking them as a module if they allow - it). This happens because they work by adding an executable to the `Scripts/` directory, - which isn't added to PATH on the Microsoft Store version of Python. - -* ##### It can cause issues with permissions - Some modules and scripts wont work with it because of restricted permissions. - This is explained - [in the Python documentation](https://docs.python.org/3/using/windows.html#redirection-of-local-data-registry-and-temporary-paths) - -* ##### It uses PATH inconsistently - `python.exe` isn't added to PATH, but `pip.exe` is. This makes it easy to have - an inconsistent `pip` and `python`. The `pip` is under the - `C:\Users\username\AppData\Local\Microsoft\WindowsApps` entry, which wouldn't - obviously have anything Python related in it. If you add your normal Python - install path below this one, it's `pip` will be overridden by the `WindowsApps` - one but the `python` one wont as it's overwriting the app execution alias. - -* ##### Confusing App Execution Alias Behaviour - The usage of app execution aliases is confusing. If you use the online - installer and for get to tick the box to to add to path, when you try and use - `python`, you either get no output or the Microsoft Store opens. This hides the - command not found error which would have indicated that their install didn't - work as expected. diff --git a/pydis_site/apps/content/resources/guides/python-guides/python-on-windows.md b/pydis_site/apps/content/resources/guides/python-guides/python-on-windows.md deleted file mode 100644 index 62b006e5..00000000 --- a/pydis_site/apps/content/resources/guides/python-guides/python-on-windows.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Python on Windows -description: This guide explains how manage your Python installation(s) on Windows ---- - -## The py launcher -By default, Python installed on Windows using the online Python installer comes -with the "py launcher". It is a command line tool you invoke using the `py` -command, and helps you invoke a specific python version. - -It provides the `py -0p` command. This lists the python versions you have -installed, the output will look like this: - - C:\Users\username>py -0p - Installed Pythons found by py Launcher for Windows - -V:3.11 C:\Users\username\AppData\Local\Programs\Python\Python311\python.exe - -V:3.10 C:\Users\username\AppData\Local\Programs\Python\Python310\python.exe - -V:3.9 * C:\Users\username\AppData\Local\Programs\Python\Python39\python.exe - -The versions will be ordered from newest to oldest, and the `*` will indicate -which version running `py` will call by default. This depends on the following -requirements, and may not be the same version you get from running `python` (if -you get any): -```text -If an exact version is not given, using the latest version can be overridden by -any of the following, (in priority order): -• An active virtual environment -• A shebang line in the script (if present) -• With -2 or -3 flag a matching PY_PYTHON2 or PY_PYTHON3 Environment variable -• A PY_PYTHON Environment variable -• From [defaults] in py.ini in your %LOCALAPPDATA%\py.ini -• From [defaults] in py.ini beside py.exe (use `where py` to locate) -``` -You can override which version is called by specifying the major and minor -versions to used. For example, to invoke python 3.7, you could run `py -3.7`. -You can then pass any arguments to `python` on top of that, for example -`py -3.7 myscript.py` to run `myscript.py`, or `py -3.7 -m pip install numpy` -to invoke `pip` to install numpy into that version. - -You can use `py` instead of `python` and not have any python versions on PATH at -all. I would recommend having your "main" python version on path so you can -invoke it with `python` if you want to, and then use `py` whenever you want a -different version. The full documentation of the `py launcher` can be found -[here](https://docs.python.org/3/using/windows.html#python-launcher-for-windows) - -## Virtual Environments - -Virtual environments, (aka `venvs`), are a way of letting each of your projects -run in it's own python environment so different projects can have different -versions of the same dependencies. This means that a `pip install` to your main -Python will not affect a project where you're using a virtual environment. - -For information on how to create and activate a virtual environment check out -[this guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) - -If your editor/IDE has handling for venvs, it's worth looking into how it works. -Here's a [VSCode tutorial](https://code.visualstudio.com/docs/python/environments), and here's -[one for Pycharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html). -[Poetry](https://python-poetry.org/) and -[Pipenv](https://pipenv.pypa.io/en/latest/) are both popular tools for managing -dependencies and virtual environments. - -## Changing PATH -PATH is the system variable that Windows uses to locate executables needed on -the command line. Whenever you type a command name in your terminal, for example -`python` or `pip`, the terminal will look it up in the PATH to try and find out -what executable that command refers to, so it can be run. - -The Python installer provides an option to add `python` to your PATH, although it -is not checked by default so many people miss it. Don't worry if you forgot to select -this though, you can add it after installing: -### The safe method: through the installer - -The easiest and and safest way to add Python to PATH is by rerunning the installer. -Here is how to do that: - -1. Search for "Apps and features" in the Windows Search Bar. -2. In the "App list" search bar search for "Python": -3. Find the version you want to add to PATH, click the three dots next to the - name, and select "modify". This should open the installer window. -4. Select "Modify", and then click "next" on the "Optional Features" screen. -5. On the "Advanced Options" screen, tick the "Add Python to environment - variables" checkbox: - - ![NkeEczCt2U](https://user-images.githubusercontent.com/22353562/126303895-60155ea5-7189-4924-9aa7-de696ca02ae9.png) - -6. Click install. - -Python should now be on your PATH! You will need to restart any -terminals/editors you have open before they detect the change. - -### The advanced method: editing environment variables - -If you want more control over the entries in your PATH, you can edit the PATH -environment variables manually. - -First, search "environment variables" in Windows search and click on "Edit the -system environment variables". Then click the "Environment Variables" button -near the bottom of the window. - -Now there should be two boxes, one for user environment variables and one for -system environment variables. There should be a "Path" entry under both. If you -installed Python for your user account only (the default), double click the -"Path" entry under the "User variables for [username]" section. - -You should now see a list of paths. Each path represents a folder that will be -searched for executables when looking up a command name in the terminal. The -paths are searched from top to bottom, and the first executable found matching -the name will be used. The system PATH variable has priority over the user one. - -#### Adding Python to your PATH - -First you will need to find the location of your Python executable. You can find -this by running `py -0p` on the command line and selecting the path you want, or -by adding `import sys;print(sys.executable)` to your code and running that. - -For a standard Python install the file path should look something like -`C:\Users\username\AppData\Local\Programs\Python\Python3xx\python.exe`. To add -this two the path you should add two folders, the one containing `python.exe`, -and the `Scripts/` directory in that directory. In this case the two paths would -be: -- C:\Users\username\AppData\Local\Programs\Python\Python3xx\ -- C:\Users\username\AppData\Local\Programs\Python\Python3xx\Scripts - -It is important that both paths are added, otherwise `pip` and other commands -will not work correctly. - -To add a folder, click "Add New", and enter the folder name. You can then move -it up above any other Python versions you have installed if necessary. Watch out -for `C:\Users\username\AppData\Local\Microsoft\WindowsApps` as if you have Python -on the Windows Store it will be installed there. - -#### Verifying your changes - -You can check that `python` was added to PATH correctly by running -`python -c "import sys;print(sys.executable)"` and checking the executable -returned is the one you want. - -You can check that `pip` was added to PATH correctly by running `pip -V` -and checking the executable matches the one returned by `python` diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml b/pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml new file mode 100644 index 00000000..1bb00d29 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/_info.yml @@ -0,0 +1,2 @@ +title: Python on Windows +description: Guides related to installing, managing, and troubleshooting Python on Windows diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/common-windows-issues.md b/pydis_site/apps/content/resources/guides/python-guides/windows/common-windows-issues.md new file mode 100644 index 00000000..0bdb11ef --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/common-windows-issues.md @@ -0,0 +1,188 @@ +--- +title: Common issues using Python on Windows +description: This guide describes common issues you may run into when using Python on Windows and how to fix them. +--- + +### When I run `python` in the terminal I get no result, or the Windows Store opens! + +By default Windows has an alias for `python` in the terminal to guide you to +install it from the Microsoft Store. I would not recommend that you install +Python from the Microsoft Store, see why [here](../microsoft-store.md). +To disable this alias, search "App execution aliases" in windows search and +click on "Manage app execution aliases". In the list you should see two options +with title "App Installer" and descriptions `python.exe` and `python3.exe`. +Disable both of them. + +Note that if you are following instructions telling you to run a command +starting with `python3`, those instructions are intended for Unix/macOS systems. +Try just using `python` instead. + +If after doing this you have an issue with the Python command not being +detected, see the below question. + +### When I try and run my code with `python` in the terminal I get an error saying the command was not recognised + +If you have not installed Python, you will need to do that. Follow our guide [here](../install-on-windows.md). + +If you have installed python and are still having the issue, it is likely that +you forgot to add to PATH when doing so. See [our guide on adding Python to +PATH](../python-on-windows.md#changing-path) for how to fix this. +You can also use the `py` launcher instead of `python` by just replacing +`python` in your command with `py`. See +[this guide](../python-on-windows.md#the-py-launcher) for more information +on that. + +### I `pip` installed a package but when running my code get a `ModuleNotFoundError` + +* #### Are you actually getting a `ModuleNotFoundError`? + + If you are using a code editor such as VSCode or Pycharm you may get a + squiggly line under your import saying the module couldn't be found, it is + possible that this is just an mistake by the editor, so try actually running + your code with to ensure if it actually errors. + + If your code runs fine, you could try restarting your editor. If you have + newly installed a module it may just not have detected it yet. If that + doesn't help, you may need to configure your editor to ensure it is looking + for the module in the correct Python environment. See + [our guide on virtual environments](./python-on-windows.md#virtual-environments) + for more information. + +* #### Was the install successful? + + Look out for errors when installing the module you want. If you get an + error, that's probably why the import isn't working, so you should look + into it. Often a google search will help with this. + +* #### Did you use the correct module name? + + Double check that you haven't made a typo in the name you are importing, or + in what you installed from PyPI, you need to make sure you type the name + exactly as it should be. + + Also, **the name you should `import` may not be the same as the name you `pip + install`**. Check the module's documentation or PyPI page if you are unsure. + Examples of this are: + + * [**opencv-python**](https://pypi.org/project/opencv-python/): You need to + `pip install opencv-python`, but the import has to be `import cv2` + * [**discord.py**](https://pypi.org/project/discord.py/): You need to `pip + install discord.py`, but the import has to be `import discord` + * [**python-dotenv**](https://pypi.org/project/python-dotenv/): You need to + `pip install python-dotenv`, but the import has to be `import dotenv` + +* #### Are you installing to the same environment you're running your code from? + + This is a very common issue. When you install a module from PyPI, you will + install it into a single Python environment, the one that the `pip` you + invoked is part of. This could be different to the one you are running + the script from if it's using a different Python installation, + or a virtual environment. + + ###### I'm using Pycharm + + PyCharm creates a virtual environment for each project by default, so if + you're installing a module using Pycharm you need to make sure you also run + your code through PyCharm. This also applies the other way round, if you + want to use a module in PyCharm you need to install it through PyCharm. + + It's also possible to change PyCharm to use your system environment, see + [their guide on configuring your interpreter](https://www.jetbrains.com/help/pycharm/configuring-python-interpreter.html) + for more information. + + ###### I installed the module using pip from the command line + + Run `pip -V` and look at the path returned it should be in the form + `\Lib\site-packages\pip`. + + Then put `import sys;print(sys.executable);sys.exit(0)` at the top + (above imports!) of your python file, and run it. The result should be + in the form `\python.exe`. + + Now compare that `PATH_TO_PYTHON` to the one from `pip -V`. If they're + different, this is the cause of the `ModuleNotFoundError`. Follow the + relevant "I'm running my code with ..." section below for how to fix + this. + + ###### I'm running my code with `python` from the terminal. + + If you are using a virtual environment, ensure you have activated it before + running `pip install`. You can test this by running `pip -V` and checking + the path is the one of your virtual environment. + + Alternatively, you can use the `py` command to specify the python version + you want to pip install into, e.g. `py -3.9 -m pip install numpy`, and to + specify the executable you want to run your code with, e.g. `py -3.9 + my_script.py`. + + If your `pip` and `python` commands are referring to different python + environments at the same time, it's possible your PATH is configured + incorrectly. See our + [guide for adding Python to PATH](../python-on-windows.md#adding-python-to-your-path) + for how to fix this. + + ###### I'm running my code with the button in VSCode + + To run your code from the same environment you installed Python to, set + the interpreter to the one at the path you found when running `pip -V` + by following + [this guide](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment). + The path should be in the form `PATH_TO_PYTHON\python.exe` + + Alternatively, you can pip install to the currently activated + environment. If you have configured VSCode to use a virtual environment, + it should automatically activate it when you open a new terminal, so + running the `pip install` command in the VSCode terminal should work. If + you are not using a virtual environment, you can use the `py` launcher + to specify the installation you want to install to. + +### I `pip` installed a command line program but it isn't recognised + +You pip installed a command line program like `PyInstaller` or `black` that is +intended to be run from the command line, but it does not work. Two common causes +for this are: + +* You are using Python from the Microsoft Store + + To check if this is the case, type `pip -V`. If the path output includes + something like + `PythonSoftwareFoundation.Python.3.10_3.10.2288.0_x64__qbz5n2kfra8p0`, you + are using Python from the Microsoft Store. To fix this you will either have + to use the full path to the scripts you want to use, or uninstall the + Microsoft Store Python and install Python properly with the online + installer. + +* You manually modified your PATH Environment Variable incorrectly + + If you added `Python` to PATH manually through environment variables, it is + possible that you only added the executable but not the `/Scripts` folder. + This would cause issues with `pip` and make command line tools not + accessible. Look at our [guide on adding Python to the + PATH](../python-on-windows.md#adding-python-to-your-path) for how to verify + and fix this. + +Projects that add a command line program usually work by adding an executable to +the `/Scripts` folder of your Python install. If you clicked "Add to PATH" when +installing Python this folder will have been added to PATH, so anything there +should be runnable directly from the command line. This should also be the case +when using a virtual environment, as long as it is properly activated. + +### I get a `SyntaxError` when trying to run `pip`,`python`, or another command. + +When you type `python` in the terminal you enter into the python REPL +(read-evaluate-print loop). This lets you run `Python` code line by line without +having to create a file. + +General commands like `pip` and `python` should be run in the terminal, not in +the Python REPL. To exit the REPL, type `exit()` and press enter. You should +then be able to run your commands normally. + +### I tried to uninstall Python by deleting the folder, now it doesn't work and I can't reinstall it! + +You should never uninstall your Python installation by deleting the folder it is +in. If you have, you may need to edit Registry Keys to fully remove the +installation. Doing this is dangerous and beyond the scope of this guide. + +To uninstall Python properly, run the installer for the version you want to +uninstall and select "uninstall". If you no longer have the installer, you can +re-download it first. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/creating-python-environment-windows.md b/pydis_site/apps/content/resources/guides/python-guides/windows/creating-python-environment-windows.md new file mode 100644 index 00000000..635c384f --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/creating-python-environment-windows.md @@ -0,0 +1,72 @@ +--- +title: Creating a Unix-style Python Environment on Windows +description: How to setup Python for Windows. +--- + +Many programmers use Linux or macOS operating systems for their work, though newcomers to programming will likely want to get started on the computer they already own, which will often be running Windows. +This guide will help you install Python on Windows. + +Programmers also need to become comfortable using a command prompt (also known as a terminal), and many guides for both beginning and advanced programming will often tell you certain commands to run. +The Windows command prompt has different names for similar commands that are available on Linux and macOS. +This guide will also help you set up a command prompt called Git Bash, which will support many of the commands available on Linux and macOS. + +## Installing Python +Python can be downloaded from the Python website on the [downloads page](https://www.python.org/downloads/). +The website will automatically present you with a download button for the latest release of the Windows version when you access the site from a Windows machine. + +Once the download is complete, you can begin the installation. +Select "Customize Installation". +The default settings for "Optional Features" are sufficient and you can click "Next". + +The next step is to decide on a location where the Python executable can be stored on your computer. +This should be a location that's easy for you to remember. +One possibility is to create a folder called "Python" at the root of your hard drive. +Once you have selected a location, you can click "Install", as no other settings on this screen need to be adjusted. +This will complete the installation. + +## Installing a text editor +You will also need a text editor for writing Python programs, and for subsequent steps of this guide. +Powerful programs called integrated development environments (IDEs) like PyCharm and Visual Studio Code contain text editors, but they also contain many other features with uses that aren't immediately obvious to new programmers. + +[Notepad++](https://notepad-plus-plus.org/) is a popular text editor for both beginners and advanced users who prefer a simpler interface. +Other editors we recommend can be found [here](https://pythondiscord.com/resources/tools/#editors). + +## Installing Git Bash +Git is a command line program that helps you keep track of changes to your code, among other things. +Many developers use it, and while you may not need it right away, it is useful to install it because it comes with Git Bash. +On the "Select Components" screen, no settings need to be changed. +The next screen will ask what text editor you want to use with Git. Vim is the default choice, though Vim is widely considered difficult to learn, so you may choose to select Notepad++ or whichever text editor you may have installed previously. + +For all remaining screens in the installation, the default selections are fine. + +## Configuring .bashrc +`.bashrc` is a file where we tell Git Bash where the Python executable is. +First, open Git Bash, and as your first command, type `echo ~` and hit enter. +This will most likely print `c/Users/YourUsername` to the terminal. +Navigate to this location in your file explorer, though keep in mind that Windows will display `c/Users/YourUsername` as `C:\Users\YourUsername`. +In this folder, there will be a file called `.bashrc`; open it with your text editor of choice. + +For this step, you will need to remember where you installed Python earlier. +In whichever folder that was, there is a file called `python.exe`; this is the executable that will run your Python programs. +Copy the full path of this file, starting from `C:`. +If you used the example location given earlier, it will be located at `C:\Python\python.exe`. + +In the `.bashrc` file, add a line to the end of the file saying `alias python='C:\\Python\\python.exe`, where `C:\\Python\\python.exe` is the location of your `python.exe` file, but each folder is separated by two backslashes instead of one. +The two backslashes are because a single backslash is used as an [escape character](https://en.wikipedia.org/wiki/Escape_character). +Save the file, and then type `source ~/.bashrc` to activate the change you have made. + +Finally, enter `python -c 'import sys; print(sys.executable)'` into Git Bash. +(If you attempt to copy and paste this into the terminal using Ctrl+V, it might not work, though Shift+Insert will.) +If all the steps have been followed correctly, this will print the location of your `python.exe` file and demonstrate that your environment is set up correctly. +You can hereafter use the `python` command in Git Bash to run any Python program that you write. + +## Running a test program +At any location on your computer, create a file named `hello.py` and open it with your text editor. +The program need only be one line: `print('Hello world!')`. +Save this file. + +To run this program in Git Bash, navigate to where it is saved on your hard drive. +If you know the path to this location, you can use the `cd` command ("cd" stands for "change directory") to navigate to it. +If it's saved to your desktop, `cd /c/Users/YourUsername/Desktop` will take you there. +Otherwise if you have the directory open in your file explorer, you can right click anywhere in the white space of the file explorer window (not on top of a file) and select "Git Bash Here". +Once you're there, type `python hello.py`, and the program will run. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/install-on-windows.md b/pydis_site/apps/content/resources/guides/python-guides/windows/install-on-windows.md new file mode 100644 index 00000000..2422e024 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/install-on-windows.md @@ -0,0 +1,63 @@ +--- +title: Installing Python on Windows +description: How to properly install python on windows +--- + +The recommended way to install Python on windows is directly from the +[Python website's Downloads page](https://www.python.org/downloads/windows/). +Installing Python from the Microsoft Store is not recommended as it can +[cause issues](../microsoft-store.md). + +## Selecting an Installer +There are many different installer options available from the downloads page. +You should usually select the "Windows installer" option instead of the "Windows +embeddable package". Some minor versions may not + +### Which version? +Current Python versions follow the form `3.major.minor`. Major releases happen +yearly and provide new features and breaking changes, whilst minor releases are +more common and only include bug/security fixes. + +Installing the latest major version will give you access to Python's newest +features. However, some modules may not support the newest versions straight +away, so installing the second latest will help you avoid those issues. If you +find you want some newer features or your module does not support your current +version, you can always install another version as well. + +You should generally always install the newest minor version, although some may +not provide an installer in which case you should find the newest that does. + +### 32-bit vs 64-bit? +Install 64-bit python unless you have reason not to. With 32 bit you may run +into memory limits if doing intensive operations (Python will be limited to +using 4GB of memory), and some installed modules may not offer prebuilt wheels +for 32 bit, potentially making installs slower or meaning you have to install +build dependencies. + +If you get an error when installing 64-bit Python, your computer may not support +it. To find out if this is the case, search "About your PC" in windows search +and open the settings page. Then look for the "System Type" option under "Device +Specifications". It should say "64-bit operating system, x64-based processor" if +you have support. You need a 64 bit processor and OS to install 64 bit programs. + +## Running the installer +When you run the installer you should see a screen like this: + +![python_installer_screen](https://user-images.githubusercontent.com/22353562/126144479-cfe6bd98-6d2e-47c3-b6b3-5de9f2656e9a.png) + +Make sure you tick "Add Python 3.x to Path". This allows you to use the `python` +and `pip` commands in your terminal to invoke Python. If you already have a +Python installation on your PATH and don't want this one to override it, don't +tick this. + +If you installed Python without adding to PATH and now want to add it, see +[our guide on adding Python to PATH](../python-on-windows.md#adding-python-to-your-path). + +Then simply click install, and wait for the install to finish! + +To test your installation, type "cmd" in the windows search bar and select +"Command Prompt" to open a terminal (make sure it's opened *after* installation +has finished) type `python -V`, and press enter. If it outputs your python +version, you've successfully installed Python. (if you didn't add to PATH, you +can use [the py launcher](../python-on-windows.md#the-py-launcher) to test +instead). diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md b/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md new file mode 100644 index 00000000..8935163b --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/microsoft-store.md @@ -0,0 +1,36 @@ +--- +title: Why not to install Python from the Microsoft Store +description: This guide explains the issues with using Python installed from the Microsoft Store +--- + +Microsoft provides a Python app on the Microsoft Store as an alternative to +using the [Standard Installer](https://www.python.org/downloads/). We would +recommend that you use the standard installer instead wherever possible. + +Here are some common issues with using Python from the Microsoft Store: + +* ##### Command line tools won't work + Most command line tools, like `black` or `pyinstaller`, won't work directly + (without specifying the full path, or invoking them as a module if they allow + it). This happens because they work by adding an executable to the `Scripts/` directory, + which isn't added to PATH on the Microsoft Store version of Python. + +* ##### It can cause issues with permissions + Some modules and scripts wont work with it because of restricted permissions. + This is explained + [in the Python documentation](https://docs.python.org/3/using/windows.html#redirection-of-local-data-registry-and-temporary-paths) + +* ##### It uses PATH inconsistently + `python.exe` isn't added to PATH, but `pip.exe` is. This makes it easy to have + an inconsistent `pip` and `python`. The `pip` is under the + `C:\Users\username\AppData\Local\Microsoft\WindowsApps` entry, which wouldn't + obviously have anything Python related in it. If you add your normal Python + install path below this one, it's `pip` will be overridden by the `WindowsApps` + one but the `python` one wont as it's overwriting the app execution alias. + +* ##### Confusing App Execution Alias Behaviour + The usage of app execution aliases is confusing. If you use the online + installer and for get to tick the box to to add to path, when you try and use + `python`, you either get no output or the Microsoft Store opens. This hides the + command not found error which would have indicated that their install didn't + work as expected. diff --git a/pydis_site/apps/content/resources/guides/python-guides/windows/python-on-windows.md b/pydis_site/apps/content/resources/guides/python-guides/windows/python-on-windows.md new file mode 100644 index 00000000..62b006e5 --- /dev/null +++ b/pydis_site/apps/content/resources/guides/python-guides/windows/python-on-windows.md @@ -0,0 +1,140 @@ +--- +title: Python on Windows +description: This guide explains how manage your Python installation(s) on Windows +--- + +## The py launcher +By default, Python installed on Windows using the online Python installer comes +with the "py launcher". It is a command line tool you invoke using the `py` +command, and helps you invoke a specific python version. + +It provides the `py -0p` command. This lists the python versions you have +installed, the output will look like this: + + C:\Users\username>py -0p + Installed Pythons found by py Launcher for Windows + -V:3.11 C:\Users\username\AppData\Local\Programs\Python\Python311\python.exe + -V:3.10 C:\Users\username\AppData\Local\Programs\Python\Python310\python.exe + -V:3.9 * C:\Users\username\AppData\Local\Programs\Python\Python39\python.exe + +The versions will be ordered from newest to oldest, and the `*` will indicate +which version running `py` will call by default. This depends on the following +requirements, and may not be the same version you get from running `python` (if +you get any): +```text +If an exact version is not given, using the latest version can be overridden by +any of the following, (in priority order): +• An active virtual environment +• A shebang line in the script (if present) +• With -2 or -3 flag a matching PY_PYTHON2 or PY_PYTHON3 Environment variable +• A PY_PYTHON Environment variable +• From [defaults] in py.ini in your %LOCALAPPDATA%\py.ini +• From [defaults] in py.ini beside py.exe (use `where py` to locate) +``` +You can override which version is called by specifying the major and minor +versions to used. For example, to invoke python 3.7, you could run `py -3.7`. +You can then pass any arguments to `python` on top of that, for example +`py -3.7 myscript.py` to run `myscript.py`, or `py -3.7 -m pip install numpy` +to invoke `pip` to install numpy into that version. + +You can use `py` instead of `python` and not have any python versions on PATH at +all. I would recommend having your "main" python version on path so you can +invoke it with `python` if you want to, and then use `py` whenever you want a +different version. The full documentation of the `py launcher` can be found +[here](https://docs.python.org/3/using/windows.html#python-launcher-for-windows) + +## Virtual Environments + +Virtual environments, (aka `venvs`), are a way of letting each of your projects +run in it's own python environment so different projects can have different +versions of the same dependencies. This means that a `pip install` to your main +Python will not affect a project where you're using a virtual environment. + +For information on how to create and activate a virtual environment check out +[this guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment) + +If your editor/IDE has handling for venvs, it's worth looking into how it works. +Here's a [VSCode tutorial](https://code.visualstudio.com/docs/python/environments), and here's +[one for Pycharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html). +[Poetry](https://python-poetry.org/) and +[Pipenv](https://pipenv.pypa.io/en/latest/) are both popular tools for managing +dependencies and virtual environments. + +## Changing PATH +PATH is the system variable that Windows uses to locate executables needed on +the command line. Whenever you type a command name in your terminal, for example +`python` or `pip`, the terminal will look it up in the PATH to try and find out +what executable that command refers to, so it can be run. + +The Python installer provides an option to add `python` to your PATH, although it +is not checked by default so many people miss it. Don't worry if you forgot to select +this though, you can add it after installing: +### The safe method: through the installer + +The easiest and and safest way to add Python to PATH is by rerunning the installer. +Here is how to do that: + +1. Search for "Apps and features" in the Windows Search Bar. +2. In the "App list" search bar search for "Python": +3. Find the version you want to add to PATH, click the three dots next to the + name, and select "modify". This should open the installer window. +4. Select "Modify", and then click "next" on the "Optional Features" screen. +5. On the "Advanced Options" screen, tick the "Add Python to environment + variables" checkbox: + + ![NkeEczCt2U](https://user-images.githubusercontent.com/22353562/126303895-60155ea5-7189-4924-9aa7-de696ca02ae9.png) + +6. Click install. + +Python should now be on your PATH! You will need to restart any +terminals/editors you have open before they detect the change. + +### The advanced method: editing environment variables + +If you want more control over the entries in your PATH, you can edit the PATH +environment variables manually. + +First, search "environment variables" in Windows search and click on "Edit the +system environment variables". Then click the "Environment Variables" button +near the bottom of the window. + +Now there should be two boxes, one for user environment variables and one for +system environment variables. There should be a "Path" entry under both. If you +installed Python for your user account only (the default), double click the +"Path" entry under the "User variables for [username]" section. + +You should now see a list of paths. Each path represents a folder that will be +searched for executables when looking up a command name in the terminal. The +paths are searched from top to bottom, and the first executable found matching +the name will be used. The system PATH variable has priority over the user one. + +#### Adding Python to your PATH + +First you will need to find the location of your Python executable. You can find +this by running `py -0p` on the command line and selecting the path you want, or +by adding `import sys;print(sys.executable)` to your code and running that. + +For a standard Python install the file path should look something like +`C:\Users\username\AppData\Local\Programs\Python\Python3xx\python.exe`. To add +this two the path you should add two folders, the one containing `python.exe`, +and the `Scripts/` directory in that directory. In this case the two paths would +be: +- C:\Users\username\AppData\Local\Programs\Python\Python3xx\ +- C:\Users\username\AppData\Local\Programs\Python\Python3xx\Scripts + +It is important that both paths are added, otherwise `pip` and other commands +will not work correctly. + +To add a folder, click "Add New", and enter the folder name. You can then move +it up above any other Python versions you have installed if necessary. Watch out +for `C:\Users\username\AppData\Local\Microsoft\WindowsApps` as if you have Python +on the Windows Store it will be installed there. + +#### Verifying your changes + +You can check that `python` was added to PATH correctly by running +`python -c "import sys;print(sys.executable)"` and checking the executable +returned is the one you want. + +You can check that `pip` was added to PATH correctly by running `pip -V` +and checking the executable matches the one returned by `python` -- cgit v1.2.3