The coverimage showcase a tutorial by Clear Code (YouTube, GitHub).

When you're a new programmer, much time and effort go into learning that first programming language. Once you gain enough familiarity with the ins and outs, you can start to invest time into building a development environment that will boost your productivity. Here follow my opinionated attempt to systematize some of the best practices for setting up a new Python development environment.

Table of Contents

• Windows Terminal
  • Execution policy
  • New profiles
• Pyenv
  • Pyenv installation
  • Pyenv maintenance
• Poetry
  • Poetry installation
  • Poetry maintenance
• Git & GitHUb
  • Git installation
  • Git maintenance
• Repository
  • Existing project
  • New project
  • Manage projects
  • Fast track new repos
• PyCharm
  • Open projects
  • Configure Python interpreter
  • Default project directory
  • Suggested Plugins
  • Install plugins
  • IDE integration
• Known issues

Windows Terminal

Developers spend enough time in terminals and shell programs, to deserve a better terminal. Windows Terminal is a customizable multi-tabbed terminal application that can run any shell program or terminal emulator. The new command-line front-end can be installed from the Microsoft Store.

Execution policy

In Windows 10, the execution policy is set to restricted by default. This means that Windows PowerShell cannot execute any script, but you can change this policy. Refer to the Microsoft Docs for more information.

1. Open Windows PowerShell and type the following to get a list of all the execution policies.

PS Get-ExecutionPolicy -List

>         Scope ExecutionPolicy
>         ----- ---------------
> MachinePolicy       Undefined
>    UserPolicy       Undefined
>       Process       Undefined
>   CurrentUser       Undefined
>  LocalMachine       Undefined

2. Set the execution policy in the CurrentUser scope.

PS Set-ExecutionPolicy RemoteSigned -scope CurrentUser

3. Verify that execution policy for the CurrentUser scope is set.

PS Get-ExecutionPolicy -scope CurrentUser

If you later want to remove the execution policy, type the following.

PS Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser

New profiles

If a command-line tool does not have a profile auto-generated for you, you can add it manually by editing the settings.json file. Follow these steps to add a profile for most command-line tools and shells. Refer to the Microsoft Docs for more information.

Python terminal

1. First you need to generate a guid value. These take the format of {00000000-0000-0000-0000-000000000000}. You can generate a guidin Windows PowerShell.

PS [guid]::NewGuid()

> 393188ce-14fa-4a3d-a556-21982206494a

2. Inspect the properties of the python terminal's shortcut, take note of the full path to the python executable, any command-line switches used, and the default starting directory.

3. You'll notice that the executable has an embedded icon, but Windows Terminal requires a separate icon or picture file. This step is optional, but if you like to add the icon to the new profile, you will have to extract it from the executable with a 3rd party tool. There are several free tools available, like Thumbico, IconsExtract, Quick Any2Ico and IconExplorer.

4. Press the Ctrl + , keyboard combination or open the drop-down menu and select Settings and then click on Open JSON file. to open the settings.json file in your favourite text editor.

5. Scroll down to find the "profiles": section to add the new profile. Remember that you can make use of environment variables such as %PROGRAMFILES% or %USERPROFILE% in any path depending on where the executable is located. Copy the following profile into your settings.json, but replace the contents of each property with the correct information.

            {
                "commandline": "%USERPROFILE%\\AppData\\Local\\Programs\\Python\\Python310\\python.exe",
                "guid": "{393188ce-14fa-4a3d-a556-21982206494a}",
                "hidden": false,
                "icon": "%USERPROFILE%\\AppData\\Local\\Programs\\Python\\Python310\\python.ico",
                "name": "Python 3.10 (64-bit)",
                "startingDirectory": "%USERPROFILE%\\AppData\\Local\\Programs\\Python\\Python310\\"
            }

Git Bash terminal

1. Similarly to the steps above, generate a guid value in Windows PowerShell.

PS [guid]::NewGuid()

> da73a63c-697d-4a3f-b7c6-b51996b66c91

2. Extract the icon from the executable.

3. Open the settings.json file in your favourite text editor, and add the new profile.

            {
                "commandline": "%PROGRAMFILES%\\Git\\bin\\bash.exe -li",
                "guid": "{da73a63c-697d-4a3f-b7c6-b51996b66c91}",
                "hidden": false,
                "icon": "%PROGRAMFILES%\\Git\\git.ico",
                "name": "Git Bash",
                "startingDirectory": "%USERPROFILE%"
            }

Git CMD terminal

1. Generate a guid value in Windows PowerShell.

PS [guid]::NewGuid()

> b8fc6eae-eb19-4e9e-8564-a2221b1ab55e

2. Inspect the properties of the Git CMD terminal's shortcut.

3. Open the settings.json file in your favourite text editor, and add the new profile.

            {
                "commandline": "%PROGRAMFILES%\\Git\\git-cmd.exe --cd-to-home",
                "guid": "{da73a63c-697d-4a3f-b7c6-b51996b66c91}",
                "hidden": false,
                "icon": "%PROGRAMFILES%\\Git\\git.ico",
                "name": "Git CMD",
                "startingDirectory": "%USERPROFILE%"
            }

back to top

pyenv

Meet pyenv, a simple Python version management tool. It lets you change the global Python version, install multiple Python versions, set directory-specific Python versions, and create/manage virtual python environments.

Pyenv installation

1. Install pyenv-win by following the instructions. You can download the zip file, or if you already have Python installed like me, you can use pip instead.

PS Expand-Archive -LiteralPath $env:USERPROFILE\Downloads\pyenv-win-master.zip -DestinationPath $env:USERPROFILE\.pyenv

OR

PS pip install pyenv-win --target $env:USERPROFILE\.pyenv

2. If you already had Python installed, you need to disable the Python launcher.

• Right-click on the Start button or press the Windows key + X keyboard combination.
• When the WinX menu opens, select "Apps and Features", then click on "App Execution Aliases".
• Turn off the App Installer aliases for Python.

3. Add new system environment variables for pyenv.

PS [System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
PS [System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
PS [System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")

4. Add pyenv to your user Path variable.

PS [System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

5. Close, reopen the terminal, and type the following to verify pyenv is working.

PS pyenv --version

If you receive an error: "Command not found.", check if the environment variables are set properly.

• Press Windows key + R keyboard combination.
• When the Run application opens, type SystemPropertiesAdvanced.exe, and click the Ok button.

6. Run rehash from your home directory (i.e. %USERPROFILE%).

PS pyenv rehash

7. Update the Python cached version database.

PS pyenv update

8. List all the Python versions available to install.

PS pyenv install --list

9. Install the latest stable Python version.

PS pyenv install 3.10.0

10. Verify that the Python version was installed.

PS pyenv versions

11. Set the global interpreter to the newly installed Python, if there is no global interpreter.

PS pyenv global 3.10.0

12. Run rehash from your home directory (i.e. %USERPROFILE%).

PS pyenv rehash

back to top

Pyenv maintenance

To uninstall a Python version.

PS pyenv uninstall 3.10.0

To update Python version changes and maintain shims, rehash from your home directory.

PS pyenv rehash

To update pyenv-win to the latest stable version.

PS pip install --upgrade pyenv-win

back to top

Poetry

Poetry is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

Poetry installation

Install Poetry by following these instructions. Poetry provides a custom installer that will install Poetry isolated from the rest of your system.

1. Install Poetry by running the following script.

PS (Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -

2. Verify that Poetry is working.

PS poetry --version

3. If you receive an error: "Command not found.", add Poetry to your user Path variable.

PS [System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\AppData\Roaming\Python\Scripts;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")

4. Close, reopen the terminal, and type the following to verify that Poetry is working.

PS poetry --version

back to top

Poetry maintenance

To Spawn a shell, according to the $SHELL environment variable. A shell is required to use command line tools from within the virtual environment.

PS poetry shell

To uninstall Poetry run the installer again with the --uninstall option or use pip.

PS pip uninstall poetry

OR

PS python install-poetry.py --uninstall

To update Poetry to the latest stable version.

PS poetry self update

To list the current configuration of Poetry.

PS poetry config --list

To create the Virtualenv in the project's root directory.

PS poetry config virtualenvs.in-project true

To create the Virtualenv in the default directory.

PS poetry config virtualenvs.in-project None

back to top

Git & GitHub

Git is a distributed version control system. GitHub provides internet hosting for software development and version control using Git. You can access GitHub in various ways: in the browser, via a desktop application, with the API, or via the command line. Each way of accessing GitHub supports different modes of authentication. It should go without saying that these days everyone should protect their GitHub account with Two-factor authentication (2FA).

To use Git on the command line, you'll need to download, install, and configure Git or GitHub CLI. If you don't want to use the command line, you can instead download and install the free GitHub Desktop or Sourcetree clients.

When connecting to a GitHub repository from Git, you'll need to authenticate with GitHub using either HTTPS (recommended) or SSH. Although SSH-based authentication is considered the most secure, it can be more of a challenge to set up and manage. On the other hand, the less secure HTTPS-based authentication is much easier to use and provides the flexibility to authorize tokens for specific tasks.

It can be time-consuming and frustrating to enter credentials every time we interact with repositories. When connecting to a GitHub repository, every connection needs a username & password (PAT) when using the HTTPS protocol and an SSH key passphrase when using the SSH protocol. The Git credential system and ssh-agent can reduce this annoyance.

Git credentials system

The Git credential-helper can be configured in several modes: cache, store, osxkeychain, winstore, manager, and most notably manager-core.
In Windows, since Git v2.29.0.windows.1, Git comes with a bundled Git Credential Manager Core (GCM Core), which provides secure git credential storage. GCM Core is the default setting on Windows and called implicitly by Git. Git will initially request a username and PAT when interacting with a repository. On subsequent interactions, Git will re-use existing credentials or tokens that GCM Core stored as long as they're valid. Refer to the Pro Git Book, and man pages for Git for more information.

ssh-agent

The ssh-agent that is included with git, while technically a Windows executable, is configured for a pseudo-Linux environment. Thankfully, Windows 10 (version 1809 and later) now incorporate an SSH client to provide SSH authentication without using any third-party clients. Portable OpenSSH is the Microsoft fork of the OpenSSH open source project. Once the ssh-agent is running as a service that stores your various SSH keys, this can facilitate authentication without entering a passphrase each time. Refer to the Pro Git Book, OpenSSH Manual, and Microsoft Docs for more information.

Git installation

1. Download, run Git for Windows and follow the installation wizard steps. Refer to the Pro Git book for more information.

2. Open a terminal and type the following, to set your Git usename.

PS git config --global user.name blikoor

3. Set your email, if email privacy is enabled on remote, use the GitHub-provided noreply email address. Refere to GitHub Docs for more information.

PS git config --global user.email  60975288+blikoor@users.noreply.github.com

4. Create a ~/.gitcommit_template file. Using a custom commit template can help you to follow a structured outline and make better commit messages. A good starting point will be to read more about well-written commit messages and following the Conventional Commits specification. Copy everything below into your own file.

#Conventional Commits 1.0.0
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# Separate subject, body and footer(s) with a blank line.
# --------------------------------------------------------------------
# The commit message should be structured as follows:
# <type>[optional scope]: <description>
# |<----   Use a maximum of 50 characters   ---->|


# Why was this change made?
# [optional body]
# --------------------------------------------------------------------
# |<---   Try To Limit Each Line to a Maximum Of 70 Characters   --->|


# [optional footer(s)]
# Provide links or keys to any relevant tickets, articles, etc.
# Example: Github issue #23
# --------------------------------------------------------------------
# Types can be
#    feat       - introduces a new feature to the codebase
#    fix        - bug fix for your application
#    refactor   - refactoring production code
#    style      - formatting, corrections, etc; no code change
#    docs       - changes to documentation
#    test       - adding or refactoring tests; no code change
#    chore      - updating grunt tasks etc; no code change
# Use ! to draw attention to a breaking change
# --------------------------------------------------------------------
# For more information, visit:
# https://www.conventionalcommits.org/en/v1.0.0/
# https://chris.beams.io/posts/git-commit/

5. Set the default global commit template. Refer to the Pro Git Book for more information.

PS git config --global commit.template ~/.gitcommit_template

6. Choose between creating and using a personal access token (PAT) or a Secure Shell (SSH) public/private key pair for authentication.

Personal access token

6.1 Verify that your configuration setting for the Git credential-helper is set to manager-core. As mentioned earlier, if you installed the latest Git for Windows release, GCM Core should be the default setting. If this isn't the case for you, refer to Git maintenance for more information.

PS git config credential.helper

> manager-core

6.2 Create a personal access token on GitHub in your account settings, by following the visual instructions. Setting an expiration date on personal access tokens is recommended, tokens that expire can be regenerated. Refer to GitHub Docs for more information.

6.3 Once you have a token, you can enter it instead of your password when performing Git operations over HTTPS.

PS git clone https://github.com/blikoor/pygame-pong.git

6.4 When prompted, type your username and paste the PAT you copied.

> Username: blikoor
> Password: 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

SSH Public/Private key pair

The Windows OpenSSH client and server are optional features that might need to be installed.
6.1 Install OpenSSH through Windows Settings, follow the steps below.

• Right-click on the Start button or press the Windows key + X keyboard combination.
• When the WinX menu opens, select "Apps and Features", then click on "Optional features".
• Verify that the OpenSSH Client appear in the list of installed features.
• If not click on "Add a feature" to install it.
• Type 'ssh' in the search dialog box to find all the SSH features.
• Click the corresponding check box, and click the Install button.

OR

Install OpenSSH using Windows PowerShell, run PowerShell as an Administrator. Verify whether or not OpenSSH is already available.

PS Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*'

> Name  : OpenSSH.Client~~~~0.0.1.0
> State : Installed
>
> Name  : OpenSSH.Server~~~~0.0.1.0
> State : NotPresent

If not, install the OpenSSH client component. Refer to Microsoft Docs for more information.

PS Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0

6.2 After installing OpenSSH in Windows, verify the status of the SSH services.

PS get-service *ssh*

> Status   Name               DisplayName
> ------   ----               -----------
> Stopped  ssh-agent          OpenSSH Authentication Agent

6.3 The ssh-agent service needs to be started and can also be configured to start automatically with Windows. Run PowerShell as an Administrator.

PS Start-Service ssh-agent | Set-Service ssh-agent -StartupType Automatic

6.4 Verify that the path for the ssh-agent used by Git is properly configured and associated with OpenSSH in Windows. Validate that your output is similar. The ssh-agent executable should be in the System32 directory, not the Git for Windows program directory (C:\Program Files\Git\cmd\start-ssh-agent.cmd). If this isn't the case for you, refer to Known issues for solutions.

PS Get-Command ssh | Select-Object Source

> Source
> ------
> C:\Windows\System32\OpenSSH\ssh.exe

6.5 Check for existing SSH keys before generating a new key pair. The default filenames for public and private keys respectively look like the following: id_ed25519.pub, id_ed25519, id_rsa.pub, id_rsa. If you receive an error: "No such file or directory.", you do not have existing SSH key pairs in the default location.

PS Get-ChildItem $env:USERPROFILE\.ssh

6.6 Generate a new SSH key pair if you don't have a supported SSH key or don't wish to use any that are available. Only use the RSA algorithm when your system don't support Ed25519.

PS ssh-keygen -t ed25519 -C "your_email@example.com"

OR

PS ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

• When prompted to enter a file in which to save the key, press Enter. This accepts the default file and location.

> Enter a file in which to save the key:[Press enter]

• When prompted, type a secure passphrase.

> Enter passphrase (empty for no passphrase): [Type passphrase]
> Enter same passphrase again: [Type passphrase again]

6.7 Now that the keys are generated, add the private key to the ssh-agent and the public key to your GitHub account.

PS ssh-add $env:USERPROFILE\.ssh\id_ed25519

6.8 Add the public key to your GitHub account. Open the id_ed25519.pub file in a text editor. The contents of this file is your public key. Select and copy everything. Follow the visual instructions to add the key to GitHub account.

6.9 Only after generating SSH keys, adding them to the ssh-agent and your GitHub account, can you test the SSH connection.

PS ssh -T git@github.com

> The authenticity of host 'github.com (IP ADDRESS)' can't be established.
> RSA key fingerprint is SHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8.
> Are you sure you want to continue connecting (yes/no)?

Verify that the fingerprint in the message you see matches GitHub's RSA public key fingerprint. If it does, then type yes.

> Hi username! You've successfully authenticated, but GitHub does not
> provide shell access.

back to top

Git maintenance

It turned out to be quite challenging to manage SSH keys. I couldn't even figure out how to just list all keys, delete all keys, and delete individual keys stored by the ssh-agent.

How do I manage SSH keys stored in the ssh-agent (Portable OpenSSH)?

Blikoor ・ Nov 18 '21

#git #github #help #openssh

In contrast, the Credential Manager (GCM Core) not only allows you to save your credentials but also allows you to view, delete, add, backup, and restore credentials. There are two ways to open the Credential Manager in windows.
Open the Control Panel and click on User Accounts, Credential Manager, and Windows Credentials.

OR

Run the Credential Manager Command Line Utility.

PS rundll32.exe keymgr.dll, KRShowKeyMgr

To set or change your default editor.

PS git config --global core.editor ~/AppData/Local/atom/app-1.58.0/atom.exe --wait

To list the global configuration variables.

$ git config --global -l

To list all of your configuration variables and from where they are coming.

$ git config --show-origin -l

To list your configuration variables.

$ git config -l

To list the local repository's configuration variables.

$ git config --local -l

To list existing remotes of the local repository.

$ git remote -v

To add the remote connection that points to the original repository. This allows you to sync changes made in both repositories.

$ git remote add upstream https://github.com/blikoor/pygame-pong.git

To rename an existing remote connection.

$ git remote rename origen origin

To switch the remote connection from HTTPS to SSH, your URL might look like: git@github.com:USERNAME/REPOSITORY.git

$ git remote set-url origin git@github.com:blikoor/pygame-pong.git

To switch the remote connection from SSH to HTTPS, your URL might look like: https://github.com/USERNAME/REPOSITORY.git

$ git remote set-url origin https://github.com/blikoor/pygame-pong.git

To check the installed Git version. Make sure that Git v2.29.0.windows.1 or later is installed.

$ git --version

To check the installed GCM Core version. Make sure that GCM Core v2.0.252.766 or later is installed.

$ git credential-manager-core --version

To set the Git credential-helper to manager-core.

$ git config --global credential.helper manager-core

back to top

Repository

Local repositories reside on the developers' computers. In contrast, remote repositories are hosted on a server that is accessible for all team members.
back to top

Existing project

Open a terminal and change your current directory to the parent directory for the project (e.g., C:\repos).

1. Clone a repository from GitHub to your local computer.

PS PS cd /repos
PS git clone https://github.com/blikoor/pygame-pong.git

2. Change your current directory to the project directory (e.g., C:\repos\your-project), and set a Python version as the local version for this directory.

PS cd pygame-pong
PS pyenv local 3.10.0

3. Verify the active Python version for this directory.

PS pyenv versions

PS python --version

4. Make a virtual environment with Poetry and Virtualenv.

PS poetry env use python

5. Spawn a shell, according to the $SHELL environment variable. A shell is required to use command line tools from within the virtual environment.

PS poetry shell

3. Install the dependencies, as specified in the pyproject.toml and poetry.lock file.

PS poetry install

back to top

New project

Open a terminal and change your current directory to the parent directory for the project (e.g., C:\repos).

1. Create a directory structure for the project.

PS cd /repos
PS poetry new pygame-pong

2. Change your current directory to the project directory (e.g., C:\repos\your-project), and set a Python version as the local version for this directory.

PS cd pygame-pong
PS pyenv local 3.10.0

3. Verify the active Python version for this directory.

PS pyenv versions

PS python --version

4. Make a virtual environment with Poetry and Virtualenv.

PS poetry env use python

5. Spawn a shell, according to the $SHELL environment variable. A shell is required to use command line tools from within the virtual environment.

PS poetry shell

6. Initialize the repository of your project.

PS git init

7. Add the primary remote HTTPS or SSH connection for the repository.

# to add the remote HTTPS connection
PS git remote add origin https://github.com/blikoor/pygame-pong.git
# to add the remote SSH connection
PS git remote add origin git@github.com:blikoor/pygame-pong.git

8. Create a .gitignore file in your repository's root directory to tell Git which files and directories to ignore when you make a commit. The github/gitignore public repository has a comprehensive list of examples, and the gitignore.io website can generate a .gitignore file for you. For more information refer to the Pro Git book, man pages for Git, and GitHub Docs.

9. Create a .gitattributes file in your repository's root directory to keep certain files from displaying in diffs, or counting towards the repository language stats. The alexkaratarakis/gitattributes public repository has a comphensive list of examples. For more information refer to the Pro Git book, man pages for Git and GitHub Docs.

Production dependencies

Install the libraries or frameworks used to build the project.

10. Add pygame to the virtual environment. Pygame is a cross-platform set of Python modules designed for developing video games.

PS poetry add pygame

Development dependencies

Install packages to use during the development of the project.

11. Add pytest-cov to the virtual environment. The plugin pytest-cov provides some extra functionality for pytest, Poetry's default testing framework. Poetry already created the tests folder structure along with the rest of the project directory structure.

PS poetry add --dev pytest-cov

12. Add Pylint to the virtual environment. Pylint is a tool for finding bugs and style problems in Python source code.

PS poetry add --dev pylint

13. Pylint isn’t perfect, you need a configuration file to take full advantage of it. Download Google's pylintrc file and save it in the project's root directory. Another option is to generate a sample .pylintrc file with --generate-rcfile and configure it yourself.

PS pylint --generate-rcfile > .pylintrc

14. Since the Google internal style guide differ slightly from PEP 8, we need to customize their .pylintrc file to avoid conflicts between Pylint and Black (installed next). Open the .pylintrc file in a text editor and search for the indent-string setting. Copy and replace it with the following:

indent-string='    '

15. Verify that Pylint is working (shell required).

PS pylint --version

16. Add Black to the virtual environment. Black is a uncompromising Python code formatter. Black is still in beta at the time of writing, hence allowing pre-releases.

PS poetry add --dev black --allow-prereleases

17. Verify that Black is working (Shell required).

PS black --version

18. Add mypy to the virtual environment. mypy is a static type checker for Python.

PS poetry add --dev mypy

19. Verify that mypy is working (shell required).

PS mypy --version

20. mypy is the de facto static type checker for Python. However, its default configuration is too lenient. Custom configuration settings can be added to a mypy.ini file. Refer to the documentation or use the example below.

[mypy]
disallow_untyped_defs = True
disallow_any_unimported = True
no_implicit_optional = True
check_untyped_defs = True
warn_return_any = True
show_error_codes = True
warn_unused_ignores = True
warn_unused_configs = True

The best mypy configuration depends on the project. As a rule of thumb, make the configuration strict by default and loosen it per module if needed. A good practice when using an ignore comment is to ignore only the specific type of an error instead of silencing mypy completely for a line of code. In other words, use:

# type: ignore[<error-code>]

21. Add isort to the virtual environment. isort is a utility that sort imports alphabetically, and automatically separated into sections and by type.

PS poetry add --dev isort

22. Verify that isort is working (shell required).

PS isort --version

23. isort needs some configuration for compatibility with Black. The configuration settings can be added to a dedicated .isort.cfg file. Refer to the documentation or use the example below.

[settings]
profile = black
multi_line_output = 3
include_trailing_comma = True
force_grid_wrap = 0
use_parentheses = True
line_length = 88
skip_gitignore = True
ensure_newline_before_comments = True

24. Add pre-commit to the virtual environment. pre-commit is a framework for managing and maintaining multi-language pre-commit hooks.

PS poetry add --dev pre-commit

25. Verify that pre-commit is working (shell required).

PS pre-commit --version

26. Create a pre-commit configuration file.

PS pre-commit sample-config > .pre-commit-config.yaml

27. Install the Git hook scripts so that pre-commit run automatically on each commit.

PS pre-commit install

> pre-commit installed at .git/hooks/pre-commit

28. Add pre-commit plugin hooks to the .pre-commit-config.yaml file. Copy everything below and append it to your configuration file, but change the repository mappings of each hook to reflect the correct version. Refer to the documentation for more supported hooks.

-   repo: https://github.com/PyCQA/pylint
    rev: v2.12.2
    hooks:
    - id: pylint
-   repo: https://github.com/psf/black
    rev: 21.12b0
    hooks:
    - id: black
-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.930
    hooks:
    - id: mypy
-   repo: https://github.com/PyCQA/isort
    rev: 5.10.1
    hooks:
    - id: isort

29. Update the hooks to the latest version automatically.

PS pre-commit autoupdate

30. Run the hooks against all of the files after adding new hooks, usually pre-commit will only run on the changed files.

$ pre-commit run --all-files

back to top

Manage projects

It is best to manage the project in the project folder and from within a shell for the virtual environment.

To see isort's configuration, as well as sources of config options.

PS isort --show-config

To see the files isort will process with the current configuration.

PS isort --show-files

To get basic information about the currently activated virtual environment.

PS poetry env info

To list environments associated with this project.

PS poetry env list

To check the pyproject.toml file for errors.

PS poetry check

To show a breakdown of all the packages currently installed to the project, including dependencies of dependencies.

PS poetry show

To update dependencies specified in the pyproject.toml to their latest versions, and update the poetry.lock file accordingly.

PS poetry update

To export the poetry.lock file of the project to a requirements.txt file for some reason.

PS poetry export -f requirements.txt > requirements.txt

To remove dependencies from the virtual environment, updating the pyproject.toml and poetry.lock files accordingly.

PS poetry remove <package-name>

To update the project's Python version to the latest released version. Make sure to run the first set of commands from your home directory and the second set from the project root folder. Verify that the [tool.poetry.dependencies] section in the pyproject.toml file, reflect the new Python version. Remember to configure the new virtualenv for the project in the Pycharm IDE.

PS pyenv update
PS pyenv install 3.10.2
PS pyenv rehash

PS pyenv local 3.10.2
PS pyenv versions
PS poetry env use python
PS poetry install

To delete existing virtual environments.

PS poetry env info
PS poetry env remove pygame-pong-hEbvnVPS-py3.10

To unset a Python version as the local version for this directory.

PS pyenv local --unset

Fast track new repos

Here is how you can create a new project in a just a couple of minutes, assuming you have Pyenv and Poetry installed already.

1. Open a terminal and type the following:

PS cd /repos
PS poetry new your-project
PS cd your-project
PS pyenv local 3.10.0
PS poetry env use python
PS poetry shell
PS poetry add --dev pytest-cov pylint mypy isort pre-commit
PS poetry add --dev black --allow-prereleases
PS pre-commit sample-config > .pre-commit-config.yaml |
PS pre-commit install

2. Download Google's pylintrc file and save it in the project's root directory. Open the .pylintrc file in a text editor to replace the indent-string setting with the following:

indent-string='    '

3. Copy everything below and paste it into a mypy.ini file within the project's root directory.

[mypy]
disallow_untyped_defs = True
disallow_any_unimported = True
no_implicit_optional = True
check_untyped_defs = True
warn_return_any = True
show_error_codes = True
warn_unused_ignores = True
warn_unused_configs = True

4. Copy everything below and paste it into a .isort.cfg file within the project's root directory.

[settings]
profile = black
multi_line_output = 3
include_trailing_comma = True
force_grid_wrap = 0
use_parentheses = True
line_length = 88
skip_gitignore = True
ensure_newline_before_comments = True

5. Copy everything below and append it to your .pre-commit-config.yaml file, but change the repository mappings of each hook to reflect the correct version.

-   repo: https://github.com/PyCQA/pylint
    rev: v2.12.2
    hooks:
    - id: pylint
-   repo: https://github.com/psf/black
    rev: 21.12b0
    hooks:
    - id: black
-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.930
    hooks:
    - id: mypy
-   repo: https://github.com/PyCQA/isort
    rev: 5.10.1
    hooks:
    - id: isort

6. Copy everything from a template and paste it into a .gitignore file within the project's root directory.

7. Copy everything from a template and paste it into a .gitattributes file within the project's root directory.

8. Open a terminal and type the following:

$ git init
$ pre-commit autoupdate
$ pre-commit run --all-files

back to top

PyCharm

PyCharm Community Edition is a free, open-source, cross-platform IDE designed for pure Python development. Download, run the Standalone Installer, and follow the installation wizard steps. Refer to the Installation guide for more information.
back to top

Open projects

1. To open your project from disk, do one of the following:
On the Welcome Screen, click the Open button.

OR

From the main menu, select File | Open.

2. In the "Open File or Project" dialog that opens, find location of the project directory.

3. Click OK.
back to top

Configure Python interpreter

1. Press Crtl + Alt + S keyboard combination, to open the project settings.

2. Go to Project | Python Interpreter. Then click on the cog icon and select Add.

3. In the left-hand pane of the "Add Python Interpreter" dialog, select Poetry Environment.

4. Select the Existing environment option. Expand the Interpreter list and select any of the existing Poetry environments. Alternatively, find an interpreter and specify a path to it.
back to top

Default project directory

1. Press Crtl + Alt + S keyboard combination, to open the project settings.

2. Go to Apearance & Behaviour | System Settings. Then click on the folder icon to browse and select the default project folder for all projects (e.g., C:\repos).

3.\ Click the OK button.
back to top

Suggested plugins

Pycharm offers support for plugins to extend the core functionality of PyCharm and improve productivity. The following is only a short list of noteworthy community rated plugins, browse the Jet Brains Marketplace for more.

Free plugins

Pylint provides both real-time and on-demand scanning of Python files with Pylint from within the PyCharm IDE.

File Watchers allows the executing of tasks triggered by file modifications.

Rainbow Brackets colors nested parentheses, brackets or braces in your code.

AceJump allows you to quickly navigate the caret to any position visible in the editor.

String Manipulation provides case switching, sorting, filtering, incrementing, aligning to columns, grepping, escaping, encoding, and more.

Zero Width Characters Locator adds an inspection that prevents some hard to find bugs related to invisible zero width characters in source code and resources.

Grazie provides intelligent spelling and grammar checks for text that you write in the IDE.

IDE Features Trainer helps you learn basic shortcuts and essential features interactively - right inside the IDE.

Key Promoter X helps you to learn essential shortcuts while you are working.

Freemium plugins

Kite is an AI-powered coding assistant featuring code completion snippets, advanced function signatures, and instant documentation.

Tabnine is an AI coding assistant featuring code completion, AI-powered code completion, AI copilot, AI code snippets, code suggestion, code prediction, code hinting, or content assist.

WakaTime provides metrics, insights, and time tracking automatically generated from your programming activity.
back to top

Install plugins

1. Press Crtl + Alt + S keyboard combination, to open the IDE settings.

2. Go to Plugins. Then click on the Marketplace tab to browse and install plugins.

3. Find the plugin in the Marketplace and click install.
back to top

IDE integration

Black

1. Press Crtl + Alt + S keyboard combination, to open the IDE settings.

2. Go to Tools | External Tools. Then press Alt + Insert keyboard combination, to add a new tool.

3. Add a new external tool with the following values:
Name: Black
Description: Black is the uncompromising Python code formatter.
Program: $PyInterpreterDirectory$/black
Arguments: $FilePath$
Working directory: $ProjectFileDir$

4. Click OK button.

5. Format the currently opened file by selecting Tools | External Tools | Black from the menu.

OR

1. Make sure you have the File Watchers plugin installed.

2. Press Crtl + Alt + S keyboard combination, to open the IDE settings.

3. Go to Tools | File Watchers. Then press Alt + Insert keyboard combination, to add a new watcher.

4. Add a new watcher with the following values:
Name: Black
File type: Python
Scope: Project Files
Program: $PyInterpreterDirectory$/black
Arguments: $FilePath$
Output paths to refresh: $FilePath$
Working directory: $ProjectFileDir$

5. In advanced Options
Uncheck "Auto-save edited files to trigger the watcher"
Uncheck "Trigger the watcher on external changes"

6. Click OK button.

mypy

1. Press Crtl + Alt + S keyboard combination, to open the IDE settings.

2. Go to Tools | External Tools. Then press Alt + Insert keyboard combination, to add a new tool.

3. Add a new external tool with the following values:
Name: mypy
Description: mypy is the de facto static type checker for Python.
Program: $PyInterpreterDirectory$/mypy
Arguments: $FilePath$
Working directory: $ProjectFileDir$

4. Click OK button.

5. Format the currently opened file by selecting Tools | External Tools | Black from the menu.

OR

1. Make sure you have the File Watchers plugin installed.

2. Press Crtl + Alt + S keyboard combination, to open the IDE settings.

3. Go to Tools | File Watchers. Then press Alt + Insert keyboard combination, to add a new watcher.

4. Add a new watcher with the following values:
Name: mypy
File type: Python
Scope: Project Files
Program: $PyInterpreterDirectory$/mypy
Arguments: $FilePath$
Output paths to refresh: $FilePath$
Working directory: $ProjectFileDir$

5. In advanced Options
Uncheck "Auto-save edited files to trigger the watcher"
Uncheck "Trigger the watcher on external changes"

6. Click OK button.

isort

In short, there is no viable integration option available that I am aware of at the moment. The available isort plugin is outdated, and there are issues when trying to use either External Tools or the File Watchers plugin for this purpose.
back to top

Known issues

1. At the time of writing, I encountered an issue with Poetry's caching. When installing Poetry or dependencies you may encounter the following error: "ValueError, some whl file in the cache does not exist.". There are currently two accepted community workarounds:
Simply delete the AppData\Local\pypoetry\Cache\artifacts folder.

OR

Export a requirements.txt file with Poetry.

PS poetry export -f requirements.txt --output requirements.txt --without-hashes

Install the project's dependencies with pip instead.

PS pip install -r requirements.txt

2. If you installed the latest Git for Windows release, Git should automatically detect the existence of OpenSSH in Windows and should properly configure and associate with OpenSSH. This information is mostly here for completeness and in case someone does experience issues (referring to step 6.4 of Git).

The workaround for this is to change your Git global configuration to use the OpenSSH executable. Refer to the man pages for Git for more information. Run the following command in Windows PowerShell.

PS git config --global core.sshCommand "'C:\Windows\System32\OpenSSH\ssh.exe'"

OR

Append the following to the [core] section in your ~/.config file. Refer to the man pages for Git for more information.

[core]
    sshCommand = \"C:\\Windows\\System32\\OpenSSH\\ssh.exe\"

OR

If you still experience issues, you can override the Git auto-detection whether commands refer to OpenSSH by setting the GIT_SSH environment variable. Refer to the man pages for Git for more information.

PS [Environment]::SetEnvironmentVariable("GIT_SSH", "$((Get-Command ssh).Source)", [System.EnvironmentVariableTarget]::User)

back to top