DEV Community

Cover image for Setting up a Python development environment
Blikoor
Blikoor

Posted on • Updated on

Setting up a Python development environment

#python #beginners #programming

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

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
Enter fullscreen mode Exit fullscreen mode 
>         Scope ExecutionPolicy
>         ----- ---------------
> MachinePolicy       Undefined
>    UserPolicy       Undefined
>       Process       Undefined
>   CurrentUser       Undefined
>  LocalMachine       Undefined
Enter fullscreen mode Exit fullscreen mode

2. Set the execution policy in the CurrentUser scope.

PS Set-ExecutionPolicy RemoteSigned -scope CurrentUser
Enter fullscreen mode Exit fullscreen mode

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

PS Get-ExecutionPolicy -scope CurrentUser
Enter fullscreen mode Exit fullscreen mode

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

PS Set-ExecutionPolicy -ExecutionPolicy Undefined -Scope CurrentUser
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode 
> 393188ce-14fa-4a3d-a556-21982206494a
Enter fullscreen mode Exit fullscreen mode

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.
Image description

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.
Image description

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\\"
            }
Enter fullscreen mode Exit fullscreen mode

Git Bash terminal

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

PS [guid]::NewGuid()
Enter fullscreen mode Exit fullscreen mode 
> da73a63c-697d-4a3f-b7c6-b51996b66c91
Enter fullscreen mode Exit fullscreen mode

2. Extract the icon from the executable.
Image description

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%"
            }
Enter fullscreen mode Exit fullscreen mode

Git CMD terminal

1. Generate a guid value in Windows PowerShell.

PS [guid]::NewGuid()
Enter fullscreen mode Exit fullscreen mode 
> b8fc6eae-eb19-4e9e-8564-a2221b1ab55e
Enter fullscreen mode Exit fullscreen mode

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

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%"
            }
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

OR

PS pip install pyenv-win --target $env:USERPROFILE\.pyenv
Enter fullscreen mode Exit fullscreen mode

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")
Enter fullscreen mode Exit fullscreen mode

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")
Enter fullscreen mode Exit fullscreen mode

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

PS pyenv --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

7. Update the Python cached version database.

PS pyenv update
Enter fullscreen mode Exit fullscreen mode

8. List all the Python versions available to install.

PS pyenv install --list
Enter fullscreen mode Exit fullscreen mode

9. Install the latest stable Python version.

PS pyenv install 3.10.0
Enter fullscreen mode Exit fullscreen mode

10. Verify that the Python version was installed.

PS pyenv versions
Enter fullscreen mode Exit fullscreen mode

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

PS pyenv global 3.10.0
Enter fullscreen mode Exit fullscreen mode

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

PS pyenv rehash
Enter fullscreen mode Exit fullscreen mode

back to top

Pyenv maintenance

To uninstall a Python version.

PS pyenv uninstall 3.10.0
Enter fullscreen mode Exit fullscreen mode

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

PS pyenv rehash
Enter fullscreen mode Exit fullscreen mode

To update pyenv-win to the latest stable version.

PS pip install --upgrade pyenv-win
Enter fullscreen mode Exit fullscreen mode

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 -
Enter fullscreen mode Exit fullscreen mode

2. Verify that Poetry is working.

PS poetry --version
Enter fullscreen mode Exit fullscreen mode

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")
Enter fullscreen mode Exit fullscreen mode

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

PS poetry --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS pip uninstall poetry
Enter fullscreen mode Exit fullscreen mode

OR

PS python install-poetry.py --uninstall
Enter fullscreen mode Exit fullscreen mode

To update Poetry to the latest stable version.

PS poetry self update
Enter fullscreen mode Exit fullscreen mode

To list the current configuration of Poetry.

PS poetry config --list
Enter fullscreen mode Exit fullscreen mode

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

PS poetry config virtualenvs.in-project true
Enter fullscreen mode Exit fullscreen mode

To create the Virtualenv in the default directory.

PS poetry config virtualenvs.in-project None
Enter fullscreen mode Exit fullscreen mode

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.

GitHub logo GitCredentialManager / git-credential-manager

Secure, cross-platform Git credential storage with authentication to GitHub, Azure Repos, and other popular Git hosting services.

Git Credential Manager

Build Status

Git Credential Manager (GCM) is a secure Git credential helper built on .NET that runs on Windows, macOS, and Linux.

Compared to Git's built-in credential helpers (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for Azure DevOps, Azure DevOps Server (formerly Team Foundation Server), GitHub, and Bitbucket.

Git Credential Manager (GCM) replaces the .NET Framework-based Git Credential Manager for Windows (GCM), and the Java-based Git Credential Manager for Mac and Linux (Java GCM), providing a consistent authentication experience across all platforms.

Current status

Git Credential Manager is currently available for Windows, macOS, and Linux. GCM only works with HTTP(S) remotes; you can still use Git with SSH:

Feature Windows macOS Linux
Installer/uninstaller ✓ ✓ ✓*
Secure platform credential storage ✓
(see more) 		✓
(see more)
…
View on GitHub

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.

GitHub logo PowerShell / openssh-portable

Portable OpenSSH, all Win32-OpenSSH releases and wiki are managed at https://github.com/powershell/Win32-OpenSSH

Portable OpenSSH

Fuzzing Status

OpenSSH is a complete implementation of the SSH protocol (version 2) for secure remote login, command execution and file transfer. It includes a client ssh and server sshd, file transfer utilities scp and sftp as well as tools for key generation (ssh-keygen), run-time key storage (ssh-agent) and a number of supporting programs.

This is a port of OpenBSD's OpenSSH to most Unix-like operating systems, including Linux, OS X and Cygwin. Portable OpenSSH polyfills OpenBSD APIs that are not available elsewhere, adds sshd sandboxing for more operating systems and includes support for OS-native authentication and auditing (e.g. using PAM).

Documentation

The official documentation for OpenSSH are the man pages for each tool:

Stable Releases

Stable release tarballs are available from a number of download mirrors. We recommend the use of a stable release for most…

View on GitHub

back to top

Git installation

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

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

PS git config --global user.name blikoor
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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/
Enter fullscreen mode Exit fullscreen mode

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

PS git config --global commit.template ~/.gitcommit_template
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
> manager-core
Enter fullscreen mode Exit fullscreen mode

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.
Animation of How to create tokens

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
Enter fullscreen mode Exit fullscreen mode

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

> Username: blikoor
> Password: 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
Enter fullscreen mode Exit fullscreen mode

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*'
Enter fullscreen mode Exit fullscreen mode 
> Name  : OpenSSH.Client~~~~0.0.1.0
> State : Installed
>
> Name  : OpenSSH.Server~~~~0.0.1.0
> State : NotPresent
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS get-service *ssh*
Enter fullscreen mode Exit fullscreen mode 
> Status   Name               DisplayName
> ------   ----               -----------
> Stopped  ssh-agent          OpenSSH Authentication Agent
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
> Source
> ------
> C:\Windows\System32\OpenSSH\ssh.exe
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

OR

PS ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
Enter fullscreen mode Exit fullscreen mode
  • 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]
Enter fullscreen mode Exit fullscreen mode
  • When prompted, type a secure passphrase. 
> Enter passphrase (empty for no passphrase): [Type passphrase]
> Enter same passphrase again: [Type passphrase again]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.
Animation of how to add keys to GitHub

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
Enter fullscreen mode Exit fullscreen mode 
> 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)?
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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.

blikoor

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

Blikoor ・ Nov 18 '21 ・ 2 min read

#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
Enter fullscreen mode Exit fullscreen mode

To set or change your default editor.

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

To list the global configuration variables.

$ git config --global -l
Enter fullscreen mode Exit fullscreen mode

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

$ git config --show-origin -l
Enter fullscreen mode Exit fullscreen mode

To list your configuration variables.

$ git config -l
Enter fullscreen mode Exit fullscreen mode

To list the local repository's configuration variables.

$ git config --local -l
Enter fullscreen mode Exit fullscreen mode

To list existing remotes of the local repository.

$ git remote -v
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

To rename an existing remote connection.

$ git remote rename origen origin
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

$ git --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

$ git config --global credential.helper manager-core
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

3. Verify the active Python version for this directory.

PS pyenv versions
Enter fullscreen mode Exit fullscreen mode 
PS python --version
Enter fullscreen mode Exit fullscreen mode

4. Make a virtual environment with Poetry and Virtualenv.

PS poetry env use python
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS poetry install
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

3. Verify the active Python version for this directory.

PS pyenv versions
Enter fullscreen mode Exit fullscreen mode 
PS python --version
Enter fullscreen mode Exit fullscreen mode

4. Make a virtual environment with Poetry and Virtualenv.

PS poetry env use python
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

6. Initialize the repository of your project.

PS git init
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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='    '
Enter fullscreen mode Exit fullscreen mode

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

PS pylint --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS black --version
Enter fullscreen mode Exit fullscreen mode

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

PS poetry add --dev mypy
Enter fullscreen mode Exit fullscreen mode

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

PS mypy --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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>]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS isort --version
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS pre-commit --version
Enter fullscreen mode Exit fullscreen mode

26. Create a pre-commit configuration file.

PS pre-commit sample-config > .pre-commit-config.yaml
Enter fullscreen mode Exit fullscreen mode

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

PS pre-commit install
Enter fullscreen mode Exit fullscreen mode 
> pre-commit installed at .git/hooks/pre-commit
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

29. Update the hooks to the latest version automatically.

PS pre-commit autoupdate
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS isort --show-files
Enter fullscreen mode Exit fullscreen mode

To get basic information about the currently activated virtual environment.

PS poetry env info
Enter fullscreen mode Exit fullscreen mode

To list environments associated with this project.

PS poetry env list
Enter fullscreen mode Exit fullscreen mode

To check the pyproject.toml file for errors.

PS poetry check
Enter fullscreen mode Exit fullscreen mode

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

PS poetry show
Enter fullscreen mode Exit fullscreen mode

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

PS poetry update
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

PS poetry remove <package-name>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode 
PS pyenv local 3.10.2
PS pyenv versions
PS poetry env use python
PS poetry install
Enter fullscreen mode Exit fullscreen mode

To delete existing virtual environments.

PS poetry env info
PS poetry env remove pygame-pong-hEbvnVPS-py3.10
Enter fullscreen mode Exit fullscreen mode

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

PS pyenv local --unset
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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='    '
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Install the project's dependencies with pip instead.

PS pip install -r requirements.txt
Enter fullscreen mode Exit fullscreen mode

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'"
Enter fullscreen mode Exit fullscreen mode

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\"
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

back to top

Top comments (0)

Read next

repiki profile image

Ruby Array Methods That Will Blow Your Mind, Pt. 3: Lord of the Slices

Repiki -

anmolbaranwal profile image

🚀 21 Tools to take your dev skills to the moon 🌝

Anmol Baranwal -

chabbasaad profile image

Tools & Extensions for Vue JS

Chabba Saad -

kigazon profile image

The Tale of Tailwind CSS and React

Josef Held -