Upload 722 files

.gitattributes

@@ -0,0 +1,12 @@
+examples/characters/char4/background.png filter=lfs diff=lfs merge=lfs -text
+examples/characters/char4/original_img.png filter=lfs diff=lfs merge=lfs -text
+examples/drawings/garlic.png filter=lfs diff=lfs merge=lfs -text
+examples/garlic_out/image.png filter=lfs diff=lfs merge=lfs -text
+examples/garlic_out/video.gif filter=lfs diff=lfs merge=lfs -text
+media/background_example.gif filter=lfs diff=lfs merge=lfs -text
+media/different_bvh_skeleton_example.gif filter=lfs diff=lfs merge=lfs -text
+media/garlic.gif filter=lfs diff=lfs merge=lfs -text
+media/gif_export_video.gif filter=lfs diff=lfs merge=lfs -text
+media/interactive_window_example.gif filter=lfs diff=lfs merge=lfs -text
+media/mp4_export_video.gif filter=lfs diff=lfs merge=lfs -text
+media/multiple_characters_example.gif filter=lfs diff=lfs merge=lfs -text

animated_drawings/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.

animated_drawings/bin/Activate.ps1

@@ -0,0 +1,241 @@
+<#
+.Synopsis
+Activate a Python virtual environment for the current PowerShell session.
+
+.Description
+Pushes the python executable for a virtual environment to the front of the
+$Env:PATH environment variable and sets the prompt to signify that you are
+in a Python virtual environment. Makes use of the command line switches as
+well as the `pyvenv.cfg` file values present in the virtual environment.
+
+.Parameter VenvDir
+Path to the directory that contains the virtual environment to activate. The
+default value for this is the parent of the directory that the Activate.ps1
+script is located within.
+
+.Parameter Prompt
+The prompt prefix to display when this virtual environment is activated. By
+default, this prompt is the name of the virtual environment folder (VenvDir)
+surrounded by parentheses and followed by a single space (ie. '(.venv) ').
+
+.Example
+Activate.ps1
+Activates the Python virtual environment that contains the Activate.ps1 script.
+
+.Example
+Activate.ps1 -Verbose
+Activates the Python virtual environment that contains the Activate.ps1 script,
+and shows extra information about the activation as it executes.
+
+.Example
+Activate.ps1 -VenvDir C:\Users\MyUser\Common\.venv
+Activates the Python virtual environment located in the specified location.
+
+.Example
+Activate.ps1 -Prompt "MyPython"
+Activates the Python virtual environment that contains the Activate.ps1 script,
+and prefixes the current prompt with the specified string (surrounded in
+parentheses) while the virtual environment is active.
+
+.Notes
+On Windows, it may be required to enable this Activate.ps1 script by setting the
+execution policy for the user. You can do this by issuing the following PowerShell
+command:
+
+PS C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+For more information on Execution Policies: 
+https://go.microsoft.com/fwlink/?LinkID=135170
+
+#>
+Param(
+    [Parameter(Mandatory = $false)]
+    [String]
+    $VenvDir,
+    [Parameter(Mandatory = $false)]
+    [String]
+    $Prompt
+)
+
+<# Function declarations --------------------------------------------------- #>
+
+<#
+.Synopsis
+Remove all shell session elements added by the Activate script, including the
+addition of the virtual environment's Python executable from the beginning of
+the PATH variable.
+
+.Parameter NonDestructive
+If present, do not remove this function from the global namespace for the
+session.
+
+#>
+function global:deactivate ([switch]$NonDestructive) {
+    # Revert to original values
+
+    # The prior prompt:
+    if (Test-Path -Path Function:_OLD_VIRTUAL_PROMPT) {
+        Copy-Item -Path Function:_OLD_VIRTUAL_PROMPT -Destination Function:prompt
+        Remove-Item -Path Function:_OLD_VIRTUAL_PROMPT
+    }
+
+    # The prior PYTHONHOME:
+    if (Test-Path -Path Env:_OLD_VIRTUAL_PYTHONHOME) {
+        Copy-Item -Path Env:_OLD_VIRTUAL_PYTHONHOME -Destination Env:PYTHONHOME
+        Remove-Item -Path Env:_OLD_VIRTUAL_PYTHONHOME
+    }
+
+    # The prior PATH:
+    if (Test-Path -Path Env:_OLD_VIRTUAL_PATH) {
+        Copy-Item -Path Env:_OLD_VIRTUAL_PATH -Destination Env:PATH
+        Remove-Item -Path Env:_OLD_VIRTUAL_PATH
+    }
+
+    # Just remove the VIRTUAL_ENV altogether:
+    if (Test-Path -Path Env:VIRTUAL_ENV) {
+        Remove-Item -Path env:VIRTUAL_ENV
+    }
+
+    # Just remove the _PYTHON_VENV_PROMPT_PREFIX altogether:
+    if (Get-Variable -Name "_PYTHON_VENV_PROMPT_PREFIX" -ErrorAction SilentlyContinue) {
+        Remove-Variable -Name _PYTHON_VENV_PROMPT_PREFIX -Scope Global -Force
+    }
+
+    # Leave deactivate function in the global namespace if requested:
+    if (-not $NonDestructive) {
+        Remove-Item -Path function:deactivate
+    }
+}
+
+<#
+.Description
+Get-PyVenvConfig parses the values from the pyvenv.cfg file located in the
+given folder, and returns them in a map.
+
+For each line in the pyvenv.cfg file, if that line can be parsed into exactly
+two strings separated by `=` (with any amount of whitespace surrounding the =)
+then it is considered a `key = value` line. The left hand string is the key,
+the right hand is the value.
+
+If the value starts with a `'` or a `"` then the first and last character is
+stripped from the value before being captured.
+
+.Parameter ConfigDir
+Path to the directory that contains the `pyvenv.cfg` file.
+#>
+function Get-PyVenvConfig(
+    [String]
+    $ConfigDir
+) {
+    Write-Verbose "Given ConfigDir=$ConfigDir, obtain values in pyvenv.cfg"
+
+    # Ensure the file exists, and issue a warning if it doesn't (but still allow the function to continue).
+    $pyvenvConfigPath = Join-Path -Resolve -Path $ConfigDir -ChildPath 'pyvenv.cfg' -ErrorAction Continue
+
+    # An empty map will be returned if no config file is found.
+    $pyvenvConfig = @{ }
+
+    if ($pyvenvConfigPath) {
+
+        Write-Verbose "File exists, parse `key = value` lines"
+        $pyvenvConfigContent = Get-Content -Path $pyvenvConfigPath
+
+        $pyvenvConfigContent | ForEach-Object {
+            $keyval = $PSItem -split "\s*=\s*", 2
+            if ($keyval[0] -and $keyval[1]) {
+                $val = $keyval[1]
+
+                # Remove extraneous quotations around a string value.
+                if ("'""".Contains($val.Substring(0, 1))) {
+                    $val = $val.Substring(1, $val.Length - 2)
+                }
+
+                $pyvenvConfig[$keyval[0]] = $val
+                Write-Verbose "Adding Key: '$($keyval[0])'='$val'"
+            }
+        }
+    }
+    return $pyvenvConfig
+}
+
+
+<# Begin Activate script --------------------------------------------------- #>
+
+# Determine the containing directory of this script
+$VenvExecPath = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$VenvExecDir = Get-Item -Path $VenvExecPath
+
+Write-Verbose "Activation script is located in path: '$VenvExecPath'"
+Write-Verbose "VenvExecDir Fullname: '$($VenvExecDir.FullName)"
+Write-Verbose "VenvExecDir Name: '$($VenvExecDir.Name)"
+
+# Set values required in priority: CmdLine, ConfigFile, Default
+# First, get the location of the virtual environment, it might not be
+# VenvExecDir if specified on the command line.
+if ($VenvDir) {
+    Write-Verbose "VenvDir given as parameter, using '$VenvDir' to determine values"
+}
+else {
+    Write-Verbose "VenvDir not given as a parameter, using parent directory name as VenvDir."
+    $VenvDir = $VenvExecDir.Parent.FullName.TrimEnd("\\/")
+    Write-Verbose "VenvDir=$VenvDir"
+}
+
+# Next, read the `pyvenv.cfg` file to determine any required value such
+# as `prompt`.
+$pyvenvCfg = Get-PyVenvConfig -ConfigDir $VenvDir
+
+# Next, set the prompt from the command line, or the config file, or
+# just use the name of the virtual environment folder.
+if ($Prompt) {
+    Write-Verbose "Prompt specified as argument, using '$Prompt'"
+}
+else {
+    Write-Verbose "Prompt not specified as argument to script, checking pyvenv.cfg value"
+    if ($pyvenvCfg -and $pyvenvCfg['prompt']) {
+        Write-Verbose "  Setting based on value in pyvenv.cfg='$($pyvenvCfg['prompt'])'"
+        $Prompt = $pyvenvCfg['prompt'];
+    }
+    else {
+        Write-Verbose "  Setting prompt based on parent's directory's name. (Is the directory name passed to venv module when creating the virutal environment)"
+        Write-Verbose "  Got leaf-name of $VenvDir='$(Split-Path -Path $venvDir -Leaf)'"
+        $Prompt = Split-Path -Path $venvDir -Leaf
+    }
+}
+
+Write-Verbose "Prompt = '$Prompt'"
+Write-Verbose "VenvDir='$VenvDir'"
+
+# Deactivate any currently active virtual environment, but leave the
+# deactivate function in place.
+deactivate -nondestructive
+
+# Now set the environment variable VIRTUAL_ENV, used by many tools to determine
+# that there is an activated venv.
+$env:VIRTUAL_ENV = $VenvDir
+
+if (-not $Env:VIRTUAL_ENV_DISABLE_PROMPT) {
+
+    Write-Verbose "Setting prompt to '$Prompt'"
+
+    # Set the prompt to include the env name
+    # Make sure _OLD_VIRTUAL_PROMPT is global
+    function global:_OLD_VIRTUAL_PROMPT { "" }
+    Copy-Item -Path function:prompt -Destination function:_OLD_VIRTUAL_PROMPT
+    New-Variable -Name _PYTHON_VENV_PROMPT_PREFIX -Description "Python virtual environment prompt prefix" -Scope Global -Option ReadOnly -Visibility Public -Value $Prompt
+
+    function global:prompt {
+        Write-Host -NoNewline -ForegroundColor Green "($_PYTHON_VENV_PROMPT_PREFIX) "
+        _OLD_VIRTUAL_PROMPT
+    }
+}
+
+# Clear PYTHONHOME
+if (Test-Path -Path Env:PYTHONHOME) {
+    Copy-Item -Path Env:PYTHONHOME -Destination Env:_OLD_VIRTUAL_PYTHONHOME
+    Remove-Item -Path Env:PYTHONHOME
+}
+
+# Add the venv to the PATH
+Copy-Item -Path Env:PATH -Destination Env:_OLD_VIRTUAL_PATH
+$Env:PATH = "$VenvExecDir$([System.IO.Path]::PathSeparator)$Env:PATH"

animated_drawings/bin/activate

@@ -0,0 +1,66 @@
+# This file must be used with "source bin/activate" *from bash*
+# you cannot run it directly
+
+deactivate () {
+    # reset old environment variables
+    if [ -n "${_OLD_VIRTUAL_PATH:-}" ] ; then
+        PATH="${_OLD_VIRTUAL_PATH:-}"
+        export PATH
+        unset _OLD_VIRTUAL_PATH
+    fi
+    if [ -n "${_OLD_VIRTUAL_PYTHONHOME:-}" ] ; then
+        PYTHONHOME="${_OLD_VIRTUAL_PYTHONHOME:-}"
+        export PYTHONHOME
+        unset _OLD_VIRTUAL_PYTHONHOME
+    fi
+
+    # This should detect bash and zsh, which have a hash command that must
+    # be called to get it to forget past commands.  Without forgetting
+    # past commands the $PATH changes we made may not be respected
+    if [ -n "${BASH:-}" -o -n "${ZSH_VERSION:-}" ] ; then
+        hash -r 2> /dev/null
+    fi
+
+    if [ -n "${_OLD_VIRTUAL_PS1:-}" ] ; then
+        PS1="${_OLD_VIRTUAL_PS1:-}"
+        export PS1
+        unset _OLD_VIRTUAL_PS1
+    fi
+
+    unset VIRTUAL_ENV
+    if [ ! "${1:-}" = "nondestructive" ] ; then
+    # Self destruct!
+        unset -f deactivate
+    fi
+}
+
+# unset irrelevant variables
+deactivate nondestructive
+
+VIRTUAL_ENV="/Users/gauravyadav/AnimatedDrawings/animated_drawings"
+export VIRTUAL_ENV
+
+_OLD_VIRTUAL_PATH="$PATH"
+PATH="$VIRTUAL_ENV/bin:$PATH"
+export PATH
+
+# unset PYTHONHOME if set
+# this will fail if PYTHONHOME is set to the empty string (which is bad anyway)
+# could use `if (set -u; : $PYTHONHOME) ;` in bash
+if [ -n "${PYTHONHOME:-}" ] ; then
+    _OLD_VIRTUAL_PYTHONHOME="${PYTHONHOME:-}"
+    unset PYTHONHOME
+fi
+
+if [ -z "${VIRTUAL_ENV_DISABLE_PROMPT:-}" ] ; then
+    _OLD_VIRTUAL_PS1="${PS1:-}"
+    PS1="(animated_drawings) ${PS1:-}"
+    export PS1
+fi
+
+# This should detect bash and zsh, which have a hash command that must
+# be called to get it to forget past commands.  Without forgetting
+# past commands the $PATH changes we made may not be respected
+if [ -n "${BASH:-}" -o -n "${ZSH_VERSION:-}" ] ; then
+    hash -r 2> /dev/null
+fi

animated_drawings/bin/activate.csh

@@ -0,0 +1,25 @@
+# This file must be used with "source bin/activate.csh" *from csh*.
+# You cannot run it directly.
+# Created by Davide Di Blasi <davidedb@gmail.com>.
+# Ported to Python 3.3 venv by Andrew Svetlov <andrew.svetlov@gmail.com>
+
+alias deactivate 'test $?_OLD_VIRTUAL_PATH != 0 && setenv PATH "$_OLD_VIRTUAL_PATH" && unset _OLD_VIRTUAL_PATH; rehash; test $?_OLD_VIRTUAL_PROMPT != 0 && set prompt="$_OLD_VIRTUAL_PROMPT" && unset _OLD_VIRTUAL_PROMPT; unsetenv VIRTUAL_ENV; test "\!:*" != "nondestructive" && unalias deactivate'
+
+# Unset irrelevant variables.
+deactivate nondestructive
+
+setenv VIRTUAL_ENV "/Users/gauravyadav/AnimatedDrawings/animated_drawings"
+
+set _OLD_VIRTUAL_PATH="$PATH"
+setenv PATH "$VIRTUAL_ENV/bin:$PATH"
+
+
+set _OLD_VIRTUAL_PROMPT="$prompt"
+
+if (! "$?VIRTUAL_ENV_DISABLE_PROMPT") then
+    set prompt = "(animated_drawings) $prompt"
+endif
+
+alias pydoc python -m pydoc
+
+rehash

animated_drawings/bin/activate.fish

@@ -0,0 +1,64 @@
+# This file must be used with "source <venv>/bin/activate.fish" *from fish*
+# (https://fishshell.com/); you cannot run it directly.
+
+function deactivate  -d "Exit virtual environment and return to normal shell environment"
+    # reset old environment variables
+    if test -n "$_OLD_VIRTUAL_PATH"
+        set -gx PATH $_OLD_VIRTUAL_PATH
+        set -e _OLD_VIRTUAL_PATH
+    end
+    if test -n "$_OLD_VIRTUAL_PYTHONHOME"
+        set -gx PYTHONHOME $_OLD_VIRTUAL_PYTHONHOME
+        set -e _OLD_VIRTUAL_PYTHONHOME
+    end
+
+    if test -n "$_OLD_FISH_PROMPT_OVERRIDE"
+        functions -e fish_prompt
+        set -e _OLD_FISH_PROMPT_OVERRIDE
+        functions -c _old_fish_prompt fish_prompt
+        functions -e _old_fish_prompt
+    end
+
+    set -e VIRTUAL_ENV
+    if test "$argv[1]" != "nondestructive"
+        # Self-destruct!
+        functions -e deactivate
+    end
+end
+
+# Unset irrelevant variables.
+deactivate nondestructive
+
+set -gx VIRTUAL_ENV "/Users/gauravyadav/AnimatedDrawings/animated_drawings"
+
+set -gx _OLD_VIRTUAL_PATH $PATH
+set -gx PATH "$VIRTUAL_ENV/bin" $PATH
+
+# Unset PYTHONHOME if set.
+if set -q PYTHONHOME
+    set -gx _OLD_VIRTUAL_PYTHONHOME $PYTHONHOME
+    set -e PYTHONHOME
+end
+
+if test -z "$VIRTUAL_ENV_DISABLE_PROMPT"
+    # fish uses a function instead of an env var to generate the prompt.
+
+    # Save the current fish_prompt function as the function _old_fish_prompt.
+    functions -c fish_prompt _old_fish_prompt
+
+    # With the original prompt function renamed, we can override with our own.
+    function fish_prompt
+        # Save the return status of the last command.
+        set -l old_status $status
+
+        # Output the venv prompt; color taken from the blue of the Python logo.
+        printf "%s%s%s" (set_color 4B8BBE) "(animated_drawings) " (set_color normal)
+
+        # Restore the return status of the previous command.
+        echo "exit $old_status" | .
+        # Output the original/"old" prompt.
+        _old_fish_prompt
+    end
+
+    set -gx _OLD_FISH_PROMPT_OVERRIDE "$VIRTUAL_ENV"
+end

animated_drawings/bin/pip

@@ -0,0 +1,8 @@
+#!/Users/gauravyadav/AnimatedDrawings/animated_drawings/bin/python3
+# -*- coding: utf-8 -*-
+import re
+import sys
+from pip._internal.cli.main import main
+if __name__ == '__main__':
+    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
+    sys.exit(main())

animated_drawings/bin/pip3

@@ -0,0 +1,8 @@
+#!/Users/gauravyadav/AnimatedDrawings/animated_drawings/bin/python3
+# -*- coding: utf-8 -*-
+import re
+import sys
+from pip._internal.cli.main import main
+if __name__ == '__main__':
+    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
+    sys.exit(main())

animated_drawings/bin/pip3.9

@@ -0,0 +1,8 @@
+#!/Users/gauravyadav/AnimatedDrawings/animated_drawings/bin/python3
+# -*- coding: utf-8 -*-
+import re
+import sys
+from pip._internal.cli.main import main
+if __name__ == '__main__':
+    sys.argv[0] = re.sub(r'(-script\.pyw|\.exe)?$', '', sys.argv[0])
+    sys.exit(main())

animated_drawings/config.py

@@ -0,0 +1,619 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+from __future__ import annotations
+import logging
+from collections import defaultdict
+from pathlib import Path
+from typing import Union, List, Tuple, Dict, TypedDict, Optional
+import yaml
+from pkg_resources import resource_filename
+from animated_drawings.utils import resolve_ad_filepath
+
+
+class Config():
+
+    def __init__(self, user_mvc_cfg_fn: str) -> None:
+        # get the base mvc config
+        with open(resource_filename(__name__, "mvc_base_cfg.yaml"), 'r') as f:
+            base_cfg = defaultdict(dict, yaml.load(f, Loader=yaml.FullLoader) or {})  # pyright: ignore[reportUnknownMemberType])
+
+        # search for the user-specified mvc config
+        user_mvc_cfg_p: Path = resolve_ad_filepath(user_mvc_cfg_fn, 'user mvc config')
+        logging.info(f'Using user-specified mvc config file located at {user_mvc_cfg_p.resolve()}')
+        with open(str(user_mvc_cfg_p), 'r') as f:
+            user_cfg = defaultdict(dict, yaml.load(f, Loader=yaml.FullLoader) or {})  # pyright: ignore[reportUnknownMemberType]
+
+        # overlay user specified mvc options onto base mvc, use to generate subconfig classes
+        self.view: ViewConfig = ViewConfig({**base_cfg['view'], **user_cfg['view']})
+        self.scene: SceneConfig = SceneConfig({**base_cfg['scene'], **user_cfg['scene']})
+        self.controller: ControllerConfig = ControllerConfig({**base_cfg['controller'], **user_cfg['controller']})
+
+        # cannot use an interactive controller with a headless mesa viewer
+        if self.controller.mode == 'interact':
+            try:
+                assert self.view.use_mesa is False, 'cannot use interactive controller when USE_MESA is True'
+            except AssertionError as e:
+                msg = f'Config error: {e}'
+                logging.critical(msg)
+                assert False, msg
+
+        # output video path must be set for render controller
+        if self.controller.mode == 'video_render':
+            try:
+                assert self.controller.output_video_path is not None, 'output_video_path must be set when using video_render controller'
+            except AssertionError as e:
+                msg = f'Config error: {e}'
+                logging.critical(msg)
+                assert False, msg
+
+        # output video codec must be set for render controller with .mp4 output filetype
+        if self.controller.mode == 'video_render' and self.controller.output_video_path is not None and self.controller.output_video_path.endswith('.mp4'):
+            try:
+                assert self.controller.output_video_codec is not None, 'output_video_codec must be set when using video_render controller'
+            except AssertionError as e:
+                msg = f'Config error: {e}'
+                logging.critical(msg)
+                assert False, msg
+
+
+class SceneConfig():
+
+    def __init__(self, scene_cfg: dict) -> None:
+
+        # show or hide the floor
+        try:
+            self.add_floor: bool = scene_cfg['ADD_FLOOR']
+            assert isinstance(self.add_floor, bool), 'is not bool'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in ADD_FLOOR config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # show or hide visualization of BVH motion driving characters
+        try:
+            self.add_ad_retarget_bvh: bool = scene_cfg['ADD_AD_RETARGET_BVH']
+            assert isinstance(self.add_ad_retarget_bvh, bool), 'is not bool'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in ADD_AD_RETARGET_BVH config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # config files for characters, driving motions, and retargeting
+        self.animated_characters: List[Tuple[CharacterConfig, RetargetConfig, MotionConfig]] = []
+
+        each: Dict[str, str]
+        for each in scene_cfg['ANIMATED_CHARACTERS']:
+            char_cfg_fn: str = each['character_cfg']
+            motion_cfg_fn: str = each['motion_cfg']
+            retarget_cfg_fn: str = each['retarget_cfg']
+            self.animated_characters.append((
+                CharacterConfig(char_cfg_fn),
+                RetargetConfig(retarget_cfg_fn),
+                MotionConfig(motion_cfg_fn)
+            ))
+
+
+class ViewConfig():
+
+    def __init__(self, view_cfg: dict) -> None:  # noqa: C901
+
+        # set color used to clear render buffer
+        try:
+            self.clear_color: list[Union[float, int]] = view_cfg["CLEAR_COLOR"]
+            assert len(self.clear_color) == 4, 'length not four'
+            for val in self.clear_color:
+                assert isinstance(val, (float, int)), f'{val} not float or int'
+                assert val <= 1.0, 'values must be <= 1.0'
+                assert val >= 0.0, 'values must be >= 0.0'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in CLEAR_COLOR config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set an image to use for the background, if desired
+        try:
+            self.background_image: Union[None, str] = view_cfg["BACKGROUND_IMAGE"]
+            assert isinstance(self.background_image, (NoneType, str)), 'type not NoneType or str'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in BACKGROUND_IMAGE config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set the dimensions of the window or output video
+        try:
+            self.window_dimensions: tuple[int, int] = view_cfg["WINDOW_DIMENSIONS"]
+            assert len(self.window_dimensions) == 2, 'length is not 2'
+            for val in self.window_dimensions:
+                assert val > 0, f'{val} must be > 0'
+                assert isinstance(val, int), 'type not int'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in WINDOW_DIMENSIONS config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set whether we want the character rigs to be visible
+        try:
+            self.draw_ad_rig: bool = view_cfg['DRAW_AD_RIG']
+            assert isinstance(self.draw_ad_rig, bool), 'value is not bool type'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in DRAW_AD_RIG config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set whether we want the character textures to be visible
+        try:
+            self.draw_ad_txtr: bool = view_cfg['DRAW_AD_TXTR']
+            assert isinstance(self.draw_ad_txtr, bool), 'value is not bool type'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in DRAW_AD_TXTR config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set whether we want the character triangle->bone assignment colors to be visible
+        try:
+            self.draw_ad_color: bool = view_cfg['DRAW_AD_COLOR']
+            assert isinstance(self.draw_ad_color, bool), 'value is not bool type'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in DRAW_AD_COLOR config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set whether we want the character mesh lines to be visible
+        try:
+            self.draw_ad_mesh_lines: bool = view_cfg['DRAW_AD_MESH_LINES']
+            assert isinstance(self.draw_ad_mesh_lines, bool), 'value is not bool type'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in DRAW_AD_MESH_LINES config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set whether we want to use mesa on the back end (necessary for headless rendering)
+        try:
+            self.use_mesa: bool = view_cfg['USE_MESA']
+            assert isinstance(self.use_mesa, bool), 'value is not bool type'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in USE_MESA config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set the position of the view camera
+        try:
+            self.camera_pos: list[Union[float, int]] = view_cfg['CAMERA_POS']
+            assert len(self.camera_pos) == 3, 'length != 3'
+            for val in self.camera_pos:
+                assert isinstance(val, (float, int)), f' {val} is not float or int'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in CAMERA_POS config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set the forward vector of the view camera (but it renders out of it's rear)
+        try:
+            self.camera_fwd: list[Union[float, int]] = view_cfg['CAMERA_FWD']
+            assert len(self.camera_fwd) == 3, 'length != 3'
+            for val in self.camera_fwd:
+                assert isinstance(val, (float, int)), f' {val} is not float or int'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in CAMERA_FWD config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+
+class ControllerConfig():
+
+    def __init__(self, controller_cfg: dict) -> None:
+
+        # set controller mode
+        try:
+            self.mode: str = controller_cfg["MODE"]
+            assert isinstance(self.mode, str), 'is not str'
+            assert self.mode in ('interactive', 'video_render'), 'mode not interactive or video_render'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in MODE config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set timestep for user interactions in interactive mode
+        try:
+            self.keyboard_timestep: Union[float, int] = controller_cfg["KEYBOARD_TIMESTEP"]
+            assert isinstance(self.keyboard_timestep, (float, int)), 'is not floar or int'
+            assert self.keyboard_timestep > 0, 'timestep val must be > 0'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in KEYBOARD_TIMESTEP config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set output video path (only use in video_render mode)
+        try:
+            self.output_video_path: Union[None, str] = controller_cfg['OUTPUT_VIDEO_PATH']
+            assert isinstance(self.output_video_path, (NoneType, str)), 'type is not None or str'
+            if isinstance(self.output_video_path, str):
+                assert Path(self.output_video_path).suffix in ('.gif', '.mp4'), 'output video extension not .gif or .mp4 '
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in OUTPUT_VIDEO_PATH config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # set output video codec (only use in video_render mode with .mp4)
+        try:
+            self.output_video_codec: Union[None, str] = controller_cfg['OUTPUT_VIDEO_CODEC']
+            assert isinstance(self.output_video_codec, (NoneType, str)), 'type is not None or str'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in OUTPUT_VIDEO_CODEC config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+
+class CharacterConfig():
+
+    class JointDict(TypedDict):
+        loc: List[float]
+        name: str
+        parent: Union[None, str]
+
+    def __init__(self, char_cfg_fn: str) -> None:  # noqa: C901
+        character_cfg_p = resolve_ad_filepath(char_cfg_fn, 'character cfg')
+        with open(str(character_cfg_p), 'r') as f:
+            char_cfg = yaml.load(f, Loader=yaml.FullLoader)
+
+        # validate image height
+        try:
+            self.img_height: int = char_cfg['height']
+            assert isinstance(self.img_height, int), 'type not int'
+            assert self.img_height > 0, 'must be > 0'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in character height config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate image width
+        try:
+            self.img_width: int = char_cfg['width']
+            assert isinstance(self.img_width, int), 'type not int'
+            assert self.img_width > 0, 'must be > 0'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in character width config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # based on height and width, determine what final img dimension will be (post padding)
+        self.img_dim: int = max(self.img_height, self.img_width)
+
+        # validate skeleton
+        try:
+            self.skeleton: List[CharacterConfig.JointDict] = []
+            for joint in char_cfg['skeleton']:
+
+                # ensure loc input is valid...
+                loc: List[int] = joint['loc']
+                assert len(loc) == 2, 'joint loc must be of length 2'
+                assert loc[0] >= 0, 'x val must be >= 0'
+                assert loc[0] < self.img_width, 'x val must be < image width'
+                assert loc[1] >= 0, 'y val must be >= 0'
+                assert loc[1] < self.img_height, 'y val must be < image height'
+
+                # ... then scale to between 0-1 based on img dim
+                loc_x: float = loc[0] / self.img_dim  # width
+                loc_y: float = loc[1] / self.img_dim + (1 - self.img_height / self.img_dim)  # height
+
+                # validate joint name
+                name: str = joint['name']
+                assert isinstance(name, str), 'name must be str'
+
+                # validate joint parent
+                parent: Union[None, str] = joint['parent']
+                assert isinstance(parent, (NoneType, str)), 'parent must be str or NoneType'
+
+                self.skeleton.append({'loc': [loc_x, loc_y], 'name': name, 'parent': parent})
+        except AssertionError as e:
+            msg = f'Error in character skeleton: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate skeleton joint parents
+        try:
+            names: List[str] = [joint['name'] for joint in self.skeleton]
+            for joint in self.skeleton:
+                assert isinstance(joint['parent'], NoneType) or joint['parent'] in names, f'joint.parent not None and not valid joint name: {joint}'
+        except AssertionError as e:
+            msg = f'Error in character skeleton: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate mask and texture files
+        try:
+            self.mask_p: Path = character_cfg_p.parent / 'mask.png'
+            self.txtr_p: Path = character_cfg_p.parent / 'texture.png'
+            assert self.mask_p.exists(), f'cannot find character mask: {self.mask_p}'
+            assert self.txtr_p.exists(), f'cannot find character texture: {self.txtr_p}'
+        except AssertionError as e:
+            msg = f'Error validating character files: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+
+class MotionConfig():
+
+    def __init__(self, motion_cfg_fn: str) -> None:  # noqa: C901
+        motion_cfg_p = resolve_ad_filepath(motion_cfg_fn, 'motion cfg')
+        with open(str(motion_cfg_p), 'r') as f:
+            motion_cfg = yaml.load(f, Loader=yaml.FullLoader)
+
+        # validate start_frame_idx
+        try:
+            self.start_frame_idx: int = motion_cfg.get('start_frame_idx', 0)
+            assert isinstance(self.start_frame_idx, int), 'type not int'
+            assert self.start_frame_idx >= 0, 'start_frame_idx must be > 0'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating start_frame_idx: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate end_frame_idx
+        try:
+            self.end_frame_idx: Optional[int] = motion_cfg.get('end_frame_idx', None)
+            assert isinstance(self.end_frame_idx, (NoneType, int)), 'type not NoneType or int'
+            if isinstance(self.end_frame_idx, int):
+                assert self.end_frame_idx >= self.start_frame_idx, 'end_frame_idx must be > start_frame_idx'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating end_frame_idx: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate frame time override
+        try:
+            self.frame_time: Optional[float] = motion_cfg.get('frame_time', None)
+            assert isinstance(self.frame_time, (NoneType, float)), 'is not None or float'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error in frame_time config parameter: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate groundplane joint
+        try:
+            self.groundplane_joint: str = motion_cfg['groundplane_joint']
+            assert isinstance(self.groundplane_joint, str), 'groundplane joint must be str'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating groundplane joint: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate forward_perp_joint_vectors
+        try:
+            self.forward_perp_joint_vectors: List[Tuple[str, str]] = motion_cfg['forward_perp_joint_vectors']
+            assert len(self.forward_perp_joint_vectors) > 0, 'forward_perp_joint_vectors len must be > 0'
+            for each in self.forward_perp_joint_vectors:
+                assert len(each) == 2, 'each list in forrward_perp_joint_vectors must have len = 2'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating forward_perp_joint_vectors: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate scale
+        try:
+            self.scale: float = motion_cfg['scale']
+            assert isinstance(self.scale, (int, float)), 'scale must be float or int'
+            assert self.scale > 0, 'scale must be > 0'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating scale: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate up
+        try:
+            self.up: str = motion_cfg['up']
+            assert self.up in ['+y', '+z'], 'up must be "+y" or "+z'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating up: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate bvh_p
+        try:
+            self.bvh_p: Path = resolve_ad_filepath(motion_cfg['filepath'], 'bvh filepath')
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating bvh_p: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+    def validate_bvh(self, bvh_joint_names: List[str]) -> None:
+        """ Performs all the validation steps that depend upon knowing the BVH joint names. This should be called once the BVH had been loaded."""
+        try:
+            for prox_joint_name, dist_joint_name in self.forward_perp_joint_vectors:
+                assert prox_joint_name in bvh_joint_names, f'invalid prox_joint name in motion_cfg.forward_perp_joint_vectors: {prox_joint_name}'
+                assert dist_joint_name in bvh_joint_names, f'invalid dist_joint name in motion_cfg.forward_perp_joint_vectors: {dist_joint_name}'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating forward_perp_joint_vector joints: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+
+class RetargetConfig():
+
+    class BvhProjectionBodypartGroup(TypedDict):
+        bvh_joint_names: List[str]
+        method: str
+        name: str
+
+    class CharBodypartGroup(TypedDict):
+        bvh_depth_drivers: List[str]
+        char_joints: List[str]
+
+    class CharBvhRootOffset(TypedDict):
+        bvh_projection_bodypart_group_for_offset: str
+        bvh_joints: List[List[str]]
+        char_joints: List[List[str]]
+
+    def __init__(self, retarget_cfg_fn: str) -> None:  # noqa: C901
+        retarget_cfg_p = resolve_ad_filepath(retarget_cfg_fn, 'retarget cfg')
+        with open(str(retarget_cfg_p), 'r') as f:
+            retarget_cfg = yaml.load(f, Loader=yaml.FullLoader)
+
+        # validate character starting location
+        try:
+            self.char_start_loc = retarget_cfg['char_starting_location']
+            assert len(self.char_start_loc) == 3, 'char start loc must be of len 3'
+            for val in self.char_start_loc:
+                assert isinstance(val, (float, int)), 'type must be float or int'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating char start location: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate bvh project bodypart groups
+        self.bvh_projection_bodypart_groups: List[RetargetConfig.BvhProjectionBodypartGroup]
+        try:
+            self.bvh_projection_bodypart_groups = retarget_cfg['bvh_projection_bodypart_groups']
+
+            for group in self.bvh_projection_bodypart_groups:
+                assert group['method'] in ['pca', 'sagittal', 'frontal'], 'group method must be "pca", "sagittal", or "frontal"'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating bvh_projection_bodypart_groups: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # Check that group names are unique
+        try:
+            group_names = [group['name'] for group in self.bvh_projection_bodypart_groups]
+            assert len(group_names) == len(set(group_names)), 'group names are not unique'
+        except AssertionError as e:
+            msg = f'Error validating bvh_projection_bodypart_groups: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char bodypart groups
+        self.char_bodypart_groups: List[RetargetConfig.CharBodypartGroup]
+        try:
+            self.char_bodypart_groups = retarget_cfg['char_bodypart_groups']
+            for group in self.char_bodypart_groups:
+                assert len(group['bvh_depth_drivers']) > 0, 'bvh_depth_drivers must have at least one joint specified'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating char_bodypart_groups: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char bvh root offset
+        self.char_bvh_root_offset: RetargetConfig.CharBvhRootOffset
+        try:
+            self.char_bvh_root_offset = retarget_cfg['char_bvh_root_offset']
+            assert len(self.char_bvh_root_offset['bvh_joints']) > 0, 'bvh_joints list must be greater than zero'
+            for each in self.char_bvh_root_offset['bvh_joints']:
+                assert len(each) > 0, 'each list in bvh_joints must have len > 0'
+
+            assert len(self.char_bvh_root_offset['char_joints']) > 0, 'char_joints list must be greater than zero'
+            for each in self.char_bvh_root_offset['char_joints']:
+                assert len(each) > 0, 'each list in char_joints must have len > 0'
+
+            assert isinstance(self.char_bvh_root_offset['bvh_projection_bodypart_group_for_offset'], str), 'bvh_projection_bodypart_group_for_offset must be str'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating char_bvh_root_offset: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char joint bvh joints mapping
+        self.char_joint_bvh_joints_mapping: Dict[str, Tuple[str, str]]
+        try:
+            self.char_joint_bvh_joints_mapping = retarget_cfg['char_joint_bvh_joints_mapping']
+            for key, val in self.char_joint_bvh_joints_mapping.items():
+                assert isinstance(key, str), 'key must be str'
+                assert isinstance(val, tuple), 'val must be tuple'
+                assert len(val) == 2, 'val must be of len 2'
+                assert isinstance(val[0], str) and isinstance(val[1], str), 'values must be str'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating char_bvh_root_offset: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char runtime checks
+        self.char_runtime_checks: List[str]
+        try:
+            self.char_runtime_checks = retarget_cfg['char_runtime_checks']
+            for check in self.char_runtime_checks:
+                assert check[0] in ['above'], 'currently only above check is supported'
+                if check[0] == 'above':
+                    assert len(check) == 4, 'above check needs 3 additional parameters'
+        except (AssertionError, ValueError) as e:
+            msg = f'Error validating char_runtime_checks: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+    def validate_char_and_bvh_joint_names(self, char_joint_names: List[str], bvh_joint_names: List[str]) -> None:  # noqa: C901
+
+        # validate bvh_projection_bodypart_groups
+        try:
+            for group in self.bvh_projection_bodypart_groups:
+                for bvh_joint_name in group['bvh_joint_names']:
+                    assert bvh_joint_name in bvh_joint_names, f'bvh_joint_name not valid: {bvh_joint_name}'
+        except AssertionError as e:
+            msg = f'Error validating bvh_projection_bodypart_groups: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char_bodypart_groups
+        try:
+            for group in self.char_bodypart_groups:
+                # check that bvh joint drivers are valid bvh joints
+                for bvh_joint_name in group['bvh_depth_drivers']:
+                    assert bvh_joint_name in bvh_joint_names, f'bvh_depth_driver joint name invalid: {bvh_joint_name}'
+
+                # check that all char_joints are valid character joints
+                for char_joint_name in group['char_joints']:
+                    assert char_joint_name in char_joint_names, f'char_joints joint name invalid: {char_joint_name}'
+        except AssertionError as e:
+            msg = f'Error validating char_bodypart_groups: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char_bvh_root_offset
+        try:
+            # check that bvh_projection_bodypart_group_for_offset matches a bvh_projection_bodypart_group name
+            group_names = [group['name'] for group in self.bvh_projection_bodypart_groups]
+            assert self.char_bvh_root_offset['bvh_projection_bodypart_group_for_offset'] in group_names, 'invalid bvh_projection_bodypart_group_for_offset'
+
+            # check bvh_joints contains valid joints
+            for bvh_joint_name_group in self.char_bvh_root_offset['bvh_joints']:
+                for joint_name in bvh_joint_name_group:
+                    assert joint_name in bvh_joint_names, f'invalid joint name in bvh_joints: {joint_name}'
+
+            # check char_joints are valid joints
+            for char_joint_name_group in self.char_bvh_root_offset['char_joints']:
+                for joint_name in char_joint_name_group:
+                    assert joint_name in char_joint_names, f'invalid joint name in char_joints: {joint_name}'
+        except AssertionError as e:
+            msg = f'Error validating char_bvh_root_offset: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char_joint_bvh_joints_mapping
+        try:
+            # check that dict keys correspond to valid character joints
+            for char_joint_name in self.char_joint_bvh_joints_mapping.keys():
+                assert char_joint_name in char_joint_names, f'invalid char_joint_name: {char_joint_name}'
+
+            # check that dict values correspond to valid bvh joints
+            for bvh_prox_joint_name, bvh_dist_joint_name in self.char_joint_bvh_joints_mapping.values():
+                assert bvh_prox_joint_name in bvh_joint_names, f'invalid bvh_prox_joint_name: {bvh_prox_joint_name}'
+                assert bvh_dist_joint_name in bvh_joint_names, f'invalid bvh_dist_joint_name: {bvh_dist_joint_name}'
+        except AssertionError as e:
+            msg = f'Error validating char_joint_bvh_joints_mapping: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+        # validate char runtime checks
+        try:
+            for check in self.char_runtime_checks:
+                if check[0] == 'above':
+                    # check that, if above test, following 3 params are valid character joint names
+                    _, target_joint_name, joint1_name, joint2_name = check
+                    assert target_joint_name in char_joint_names, f'above test target_joint_name invalid {target_joint_name}'
+                    assert joint1_name in char_joint_names, f'above test joint1_name invalid {joint1_name}'
+                    assert joint2_name in char_joint_names, f'above test joint2_name invalid {joint2_name}'
+        except AssertionError as e:
+            msg = f'Error validating char_runtime_checks: {e}'
+            logging.critical(msg)
+            assert False, msg
+
+
+NoneType = type(None)  # needed for type checking

animated_drawings/controller/controller.py

@@ -0,0 +1,104 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+""" Controller Abstract Base Class Module """
+
+from __future__ import annotations
+from typing import Optional
+from abc import abstractmethod
+import logging
+
+from animated_drawings.model.scene import Scene
+from animated_drawings.view.view import View
+from animated_drawings.config import ControllerConfig
+
+
+class Controller():
+    """
+    Base Controller class from which all other Controllers will be derived.
+    Controllers are responsible for:
+        - running the game loop.
+        - handling user input and forwarding it to the view or scene.
+        - triggering the scene's update method
+        - trigger the view's render method
+    """
+
+    def __init__(self, cfg: ControllerConfig, scene: Scene) -> None:
+        self.cfg: ControllerConfig = cfg
+        self.scene: Scene = scene
+        self.view: Optional[View] = None
+
+    def set_scene(self, scene: Scene) -> None:
+        """ Sets the scene attached to this controller."""
+        self.scene = scene
+
+    def set_view(self, view: View) -> None:
+        """ Sets the view attached to this controller."""
+        self.view = view
+
+    @abstractmethod
+    def _tick(self) -> None:
+        """Subclass and add logic is necessary to progress time"""
+
+    @abstractmethod
+    def _update(self) -> None:
+        """Subclass and add logic is necessary to update scene after progressing time"""
+
+    @abstractmethod
+    def _is_run_over(self) -> bool:
+        """Subclass and add logic is necessary to end the scene"""
+
+    @abstractmethod
+    def _start_run_loop_iteration(self) -> None:
+        """Subclass and add code to start run loop iteration"""
+
+    @abstractmethod
+    def _handle_user_input(self) -> None:
+        """Subclass and add code to handle user input"""
+
+    @abstractmethod
+    def _render(self) -> None:
+        """Subclass and add logic needed to have viewer render the scene"""
+
+    @abstractmethod
+    def _finish_run_loop_iteration(self) -> None:
+        """Subclass and add steps necessary before starting next iteration of run loop. """
+
+    @abstractmethod
+    def _prep_for_run_loop(self) -> None:
+        """Subclass and add anything necessary to do immediately prior to run loop. """
+
+    @abstractmethod
+    def _cleanup_after_run_loop(self) -> None:
+        """Subclass and add anything necessary to do after run loop has finished. """
+
+    def run(self) -> None:
+        """ The run loop. Subclassed controllers should overload and define functionality for each step in this function."""
+
+        self._prep_for_run_loop()
+        while not self._is_run_over():
+            self._start_run_loop_iteration()
+            self._update()
+            self._render()
+            self._tick()
+            self._handle_user_input()
+            self._finish_run_loop_iteration()
+
+        self._cleanup_after_run_loop()
+
+    @staticmethod
+    def create_controller(controller_cfg: ControllerConfig, scene: Scene, view: View) -> Controller:
+        """ Takes in a controller dictionary from mvc config file, scene, and view. Constructs and return appropriate controller."""
+        if controller_cfg.mode == 'video_render':
+            from animated_drawings.controller.video_render_controller import VideoRenderController
+            return VideoRenderController(controller_cfg, scene, view,)
+        elif controller_cfg.mode == 'interactive':
+            from animated_drawings.controller.interactive_controller import InteractiveController
+            from animated_drawings.view.window_view import WindowView
+            assert isinstance(view, WindowView)  # for static analysis. checks elsewhere ensure this always passes
+            return InteractiveController(controller_cfg, scene, view)
+        else:
+            msg = f'Unknown controller mode specified: {controller_cfg.mode}'
+            logging.critical(msg)
+            assert False, msg

animated_drawings/controller/interactive_controller.py

@@ -0,0 +1,117 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+""" Interactive Controller Class Module """
+
+import time
+from typing import Optional
+import glfw
+
+from animated_drawings.controller.controller import Controller
+from animated_drawings.model.scene import Scene
+from animated_drawings.view.window_view import WindowView
+from animated_drawings.config import ControllerConfig
+
+
+class InteractiveController(Controller):
+    """ Interactive Controller Class """
+
+    def __init__(self, cfg: ControllerConfig, scene: Scene, view: WindowView) -> None:
+        super().__init__(cfg, scene)
+
+        self.view: WindowView = view
+        self.prev_time: float = 0.0  # tracks real-world time passing between run loops
+        self.pause: bool = False     # tracks whether time progresses in the scene
+
+        glfw.init()
+        glfw.set_key_callback(self.view.win, self._on_key)
+
+    def _on_key(self, _win, key: int, _scancode, action, _mods) -> None:  # noqa: C901
+
+        if action not in (glfw.PRESS, glfw.REPEAT):
+            return
+
+        # close window
+        if key in (glfw.KEY_ESCAPE, glfw.KEY_Q):
+            glfw.set_window_should_close(self.view.win, True)
+
+        # move camera forward
+        elif key == glfw.KEY_W:
+            _, _, fwd = self.view.camera.get_right_up_fwd_vectors()
+            self.view.camera.offset(-0.1 * fwd)
+
+        # move camera back
+        elif key == glfw.KEY_S:
+            _, _, fwd = self.view.camera.get_right_up_fwd_vectors()
+            self.view.camera.offset(0.1 * fwd)
+
+        # move camera right
+        elif key == glfw.KEY_A:
+            right, _, _ = self.view.camera.get_right_up_fwd_vectors()
+            self.view.camera.offset(-0.1 * right)
+
+        # move camera left
+        elif key == glfw.KEY_D:
+            right, _, _ = self.view.camera.get_right_up_fwd_vectors()
+            self.view.camera.offset(0.1 * right)
+
+        # move camera up
+        elif key == glfw.KEY_E:
+            _, up, _ = self.view.camera.get_right_up_fwd_vectors()
+            self.view.camera.offset(0.1 * up)
+
+        # move camera down
+        elif key == glfw.KEY_R:
+            _, up, _ = self.view.camera.get_right_up_fwd_vectors()
+            self.view.camera.offset(-0.1 * up)
+
+        # toggle start/stop time
+        elif key == glfw.KEY_SPACE:
+            self.pause = not self.pause
+            self.prev_time = time.time()
+
+        # step forward in time
+        elif key == glfw.KEY_RIGHT:
+            self._tick(self.cfg.keyboard_timestep)
+
+        # step backward in time
+        elif key == glfw.KEY_LEFT:
+            self._tick(-self.cfg.keyboard_timestep)
+
+    def _is_run_over(self) -> None:
+        return glfw.window_should_close(self.view.win)
+
+    def _prep_for_run_loop(self) -> None:
+        self.prev_time = time.time()
+
+    def _start_run_loop_iteration(self) -> None:
+        self.view.clear_window()
+
+    def _tick(self, delta_t: Optional[float] = None) -> None:
+        # if passed a specific value to progress time by, do so
+        if delta_t:
+            self.scene.progress_time(delta_t)
+        # otherwise, if scene is paused, do nothing
+        elif self.pause:
+            pass
+        # otherwise, calculate real time passed since last call and progress scene by that amount
+        else:
+            cur_time = time.time()
+            self.scene.progress_time(cur_time - self.prev_time)
+            self.prev_time = cur_time
+
+    def _update(self) -> None:
+        self.scene.update_transforms()
+
+    def _handle_user_input(self) -> None:
+        glfw.poll_events()
+
+    def _render(self) -> None:
+        self.view.render(self.scene)
+
+    def _finish_run_loop_iteration(self) -> None:
+        self.view.swap_buffers()
+
+    def _cleanup_after_run_loop(self) -> None:
+        self.view.cleanup()

animated_drawings/controller/video_render_controller.py

@@ -0,0 +1,216 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+""" Video Render Controller Class Module """
+
+from __future__ import annotations
+import time
+import logging
+from typing import List
+from pathlib import Path
+from abc import abstractmethod
+import numpy as np
+import numpy.typing as npt
+import cv2
+from OpenGL import GL
+from tqdm import tqdm
+
+from animated_drawings.controller.controller import Controller
+from animated_drawings.model.scene import Scene
+from animated_drawings.model.animated_drawing import AnimatedDrawing
+from animated_drawings.view.view import View
+from animated_drawings.config import ControllerConfig
+
+NoneType = type(None)  # for type checking below
+
+
+class VideoRenderController(Controller):
+    """ Video Render Controller is used to non-interactively generate a video file """
+
+    def __init__(self, cfg: ControllerConfig, scene: Scene, view: View) -> None:
+        super().__init__(cfg, scene)
+
+        self.view: View = view
+
+        self.scene: Scene = scene
+
+        self.frames_left_to_render: int  # when this becomes zero, stop rendering
+        self.delta_t: float              # amount of time to progress scene between renders
+        self._set_frames_left_to_render_and_delta_t()
+
+        self.render_start_time: float  # track when we started to render frames (for performance stats)
+        self.frames_rendered: int = 0  # track how many frames we've rendered
+
+        self.video_width: int
+        self.video_height: int
+        self.video_width, self.video_height = self.view.get_framebuffer_size()
+
+        self.video_writer: VideoWriter = VideoWriter.create_video_writer(self)
+
+        self.frame_data = np.empty([self.video_height, self.video_width, 4], dtype='uint8')  # 4 for RGBA
+
+        self.progress_bar = tqdm(total=self.frames_left_to_render)
+
+    def _set_frames_left_to_render_and_delta_t(self) -> None:
+        """
+        Based upon the animated drawings within the scene, computes maximum number of frames in a BVH.
+        Checks that all frame times within BVHs are equal, logs a warning if not.
+        Uses results to determine number of frames and frame time for output video.
+        """
+
+        max_frames = 0
+        frame_time: List[float] = []
+        for child in self.scene.get_children():
+            if not isinstance(child, AnimatedDrawing):
+                continue
+            max_frames = max(max_frames, child.retargeter.bvh.frame_max_num)
+            frame_time.append(child.retargeter.bvh.frame_time)
+
+        if not all(x == frame_time[0] for x in frame_time):
+            msg = f'frame time of BVH files don\'t match. Using first value: {frame_time[0]}'
+            logging.warning(msg)
+
+        self.frames_left_to_render = max_frames
+        self.delta_t = frame_time[0]
+
+    def _prep_for_run_loop(self) -> None:
+        self.run_loop_start_time = time.time()
+
+    def _is_run_over(self) -> bool:
+        return self.frames_left_to_render == 0
+
+    def _start_run_loop_iteration(self) -> None:
+        self.view.clear_window()
+
+    def _update(self) -> None:
+        self.scene.update_transforms()
+
+    def _render(self) -> None:
+        self.view.render(self.scene)
+
+    def _tick(self) -> None:
+        self.scene.progress_time(self.delta_t)
+
+    def _handle_user_input(self) -> None:
+        """ ignore all user input when rendering video file """
+
+    def _finish_run_loop_iteration(self) -> None:
+        # get pixel values from the frame buffer, send them to the video writer
+        GL.glBindFramebuffer(GL.GL_READ_FRAMEBUFFER, 0)
+        GL.glReadPixels(0, 0, self.video_width, self.video_height, GL.GL_BGRA, GL.GL_UNSIGNED_BYTE, self.frame_data)
+        self.video_writer.process_frame(self.frame_data[::-1, :, :].copy())
+
+        # update our counts and progress_bar
+        self.frames_left_to_render -= 1
+        self.frames_rendered += 1
+        self.progress_bar.update(1)
+
+    def _cleanup_after_run_loop(self) -> None:
+        logging.info(f'Rendered {self.frames_rendered} frames in {time.time()-self.run_loop_start_time} seconds.')
+        self.view.cleanup()
+
+        _time = time.time()
+        self.video_writer.cleanup()
+        logging.info(f'Wrote video to file in in {time.time()-_time} seconds.')
+
+
+class VideoWriter():
+    """ Wrapper to abstract the different backends necessary for writing different video filetypes """
+
+    def __init__(self) -> None:
+        pass
+
+    @abstractmethod
+    def process_frame(self, frame: npt.NDArray[np.uint8]) -> None:
+        """ Subclass must specify how to handle each frame of data received. """
+        pass
+
+    @abstractmethod
+    def cleanup(self) -> None:
+        """ Subclass must specify how to finish up after all frames have been received. """
+        pass
+
+    @staticmethod
+    def create_video_writer(controller: VideoRenderController) -> VideoWriter:
+
+        assert isinstance(controller.cfg.output_video_path, str)  # for static analysis
+
+        output_p = Path(controller.cfg.output_video_path)
+        output_p.parent.mkdir(exist_ok=True, parents=True)
+
+        msg = f' Writing video to: {output_p.resolve()}'
+        logging.info(msg)
+        print(msg)
+
+        if output_p.suffix == '.gif':
+            return GIFWriter(controller)
+        elif output_p.suffix == '.mp4':
+            return MP4Writer(controller)
+        else:
+            msg = f'Unsupported output video file extension ({output_p.suffix}). Only .gif and .mp4 are supported.'
+            logging.critical(msg)
+            assert False, msg
+
+
+class GIFWriter(VideoWriter):
+    """ Video writer for creating transparent, animated GIFs with Pillow """
+
+    def __init__(self, controller: VideoRenderController) -> None:
+        assert isinstance(controller.cfg.output_video_path, str)  # for static analysis
+        self.output_p = Path(controller.cfg.output_video_path)
+
+        self.duration = int(controller.delta_t*1000)
+        if self.duration < 20:
+            msg = f'Specified duration of .gif is too low, replacing with 20: {self.duration}'
+            logging.warn(msg)
+            self.duration = 20
+
+        self.frames: List[npt.NDArray[np.uint8]] = []
+
+    def process_frame(self, frame: npt.NDArray[np.uint8]) -> None:
+        """ Reorder channels and save frames as they arrive"""
+        self.frames.append(cv2.cvtColor(frame, cv2.COLOR_BGRA2RGBA).astype(np.uint8))
+
+    def cleanup(self) -> None:
+        """ Write all frames to output path specified."""
+        from PIL import Image
+        self.output_p.parent.mkdir(exist_ok=True, parents=True)
+        logging.info(f'VideoWriter will write to {self.output_p.resolve()}')
+        ims = [Image.fromarray(a_frame) for a_frame in self.frames]
+        ims[0].save(self.output_p, save_all=True, append_images=ims[1:], duration=self.duration, disposal=2, loop=0)
+
+
+class MP4Writer(VideoWriter):
+    """ Video writer for creating mp4 videos with cv2.VideoWriter """
+    def __init__(self, controller: VideoRenderController) -> None:
+
+        # validate and prep output path
+        if isinstance(controller.cfg.output_video_path, NoneType):
+            msg = 'output video path not specified for mp4 video writer'
+            logging.critical(msg)
+            assert False, msg
+        output_p = Path(controller.cfg.output_video_path)
+        output_p.parent.mkdir(exist_ok=True, parents=True)
+        logging.info(f'VideoWriter will write to {output_p.resolve()}')
+
+        # validate and prep codec
+        if isinstance(controller.cfg.output_video_codec, NoneType):
+            msg = 'output video codec not specified for mp4 video writer'
+            logging.critical(msg)
+            assert False, msg
+        fourcc = cv2.VideoWriter_fourcc(*controller.cfg.output_video_codec)
+        logging.info(f'Using codec {controller.cfg.output_video_codec}')
+
+        # calculate video writer framerate
+        frame_rate = round(1/controller.delta_t)
+
+        # initialize the video writer
+        self.video_writer = cv2.VideoWriter(str(output_p), fourcc, frame_rate, (controller.video_width, controller.video_height))
+
+    def process_frame(self, frame: npt.NDArray[np.uint8]) -> None:
+        """ Remove the alpha channel and send to the video writer as it arrives. """
+        self.video_writer.write(frame[:, :, :3])
+
+    def cleanup(self) -> None:
+        self.video_writer.release()

animated_drawings/lib/python3.9/site-packages/_distutils_hack/__init__.py

@@ -0,0 +1,128 @@
+import sys
+import os
+import re
+import importlib
+import warnings
+
+
+is_pypy = '__pypy__' in sys.builtin_module_names
+
+
+warnings.filterwarnings('ignore',
+                        r'.+ distutils\b.+ deprecated',
+                        DeprecationWarning)
+
+
+def warn_distutils_present():
+    if 'distutils' not in sys.modules:
+        return
+    if is_pypy and sys.version_info < (3, 7):
+        # PyPy for 3.6 unconditionally imports distutils, so bypass the warning
+        # https://foss.heptapod.net/pypy/pypy/-/blob/be829135bc0d758997b3566062999ee8b23872b4/lib-python/3/site.py#L250
+        return
+    warnings.warn(
+        "Distutils was imported before Setuptools, but importing Setuptools "
+        "also replaces the `distutils` module in `sys.modules`. This may lead "
+        "to undesirable behaviors or errors. To avoid these issues, avoid "
+        "using distutils directly, ensure that setuptools is installed in the "
+        "traditional way (e.g. not an editable install), and/or make sure "
+        "that setuptools is always imported before distutils.")
+
+
+def clear_distutils():
+    if 'distutils' not in sys.modules:
+        return
+    warnings.warn("Setuptools is replacing distutils.")
+    mods = [name for name in sys.modules if re.match(r'distutils\b', name)]
+    for name in mods:
+        del sys.modules[name]
+
+
+def enabled():
+    """
+    Allow selection of distutils by environment variable.
+    """
+    which = os.environ.get('SETUPTOOLS_USE_DISTUTILS', 'stdlib')
+    return which == 'local'
+
+
+def ensure_local_distutils():
+    clear_distutils()
+    distutils = importlib.import_module('setuptools._distutils')
+    distutils.__name__ = 'distutils'
+    sys.modules['distutils'] = distutils
+
+    # sanity check that submodules load as expected
+    core = importlib.import_module('distutils.core')
+    assert '_distutils' in core.__file__, core.__file__
+
+
+def do_override():
+    """
+    Ensure that the local copy of distutils is preferred over stdlib.
+
+    See https://github.com/pypa/setuptools/issues/417#issuecomment-392298401
+    for more motivation.
+    """
+    if enabled():
+        warn_distutils_present()
+        ensure_local_distutils()
+
+
+class DistutilsMetaFinder:
+    def find_spec(self, fullname, path, target=None):
+        if path is not None:
+            return
+
+        method_name = 'spec_for_{fullname}'.format(**locals())
+        method = getattr(self, method_name, lambda: None)
+        return method()
+
+    def spec_for_distutils(self):
+        import importlib.abc
+        import importlib.util
+
+        class DistutilsLoader(importlib.abc.Loader):
+
+            def create_module(self, spec):
+                return importlib.import_module('setuptools._distutils')
+
+            def exec_module(self, module):
+                pass
+
+        return importlib.util.spec_from_loader('distutils', DistutilsLoader())
+
+    def spec_for_pip(self):
+        """
+        Ensure stdlib distutils when running under pip.
+        See pypa/pip#8761 for rationale.
+        """
+        if self.pip_imported_during_build():
+            return
+        clear_distutils()
+        self.spec_for_distutils = lambda: None
+
+    @staticmethod
+    def pip_imported_during_build():
+        """
+        Detect if pip is being imported in a build script. Ref #2355.
+        """
+        import traceback
+        return any(
+            frame.f_globals['__file__'].endswith('setup.py')
+            for frame, line in traceback.walk_stack(None)
+        )
+
+
+DISTUTILS_FINDER = DistutilsMetaFinder()
+
+
+def add_shim():
+    sys.meta_path.insert(0, DISTUTILS_FINDER)
+
+
+def remove_shim():
+    try:
+        sys.meta_path.remove(DISTUTILS_FINDER)
+    except ValueError:
+        pass

animated_drawings/lib/python3.9/site-packages/_distutils_hack/override.py

@@ -0,0 +1 @@
+__import__('_distutils_hack').do_override()

animated_drawings/lib/python3.9/site-packages/distutils-precedence.pth

@@ -0,0 +1 @@
+import os; var = 'SETUPTOOLS_USE_DISTUTILS'; enabled = os.environ.get(var, 'stdlib') == 'local'; enabled and __import__('_distutils_hack').add_shim(); 

animated_drawings/lib/python3.9/site-packages/pip-21.2.4.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

animated_drawings/lib/python3.9/site-packages/pip-21.2.4.dist-info/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2008-2021 The pip developers (see AUTHORS.txt file)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

animated_drawings/lib/python3.9/site-packages/pip-21.2.4.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.1
+Name: pip
+Version: 21.2.4
+Summary: The PyPA recommended tool for installing Python packages.
+Home-page: https://pip.pypa.io/
+Author: The pip developers
+Author-email: distutils-sig@python.org
+License: MIT
+Project-URL: Documentation, https://pip.pypa.io
+Project-URL: Source, https://github.com/pypa/pip
+Project-URL: Changelog, https://pip.pypa.io/en/stable/news/
+Platform: UNKNOWN
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.6
+License-File: LICENSE.txt
+
+pip - The Python Package Installer
+==================================
+
+.. image:: https://img.shields.io/pypi/v/pip.svg
+   :target: https://pypi.org/project/pip/
+
+.. image:: https://readthedocs.org/projects/pip/badge/?version=latest
+   :target: https://pip.pypa.io/en/latest
+
+pip is the `package installer`_ for Python. You can use pip to install packages from the `Python Package Index`_ and other indexes.
+
+Please take a look at our documentation for how to install and use pip:
+
+* `Installation`_
+* `Usage`_
+
+We release updates regularly, with a new version every 3 months. Find more details in our documentation:
+
+* `Release notes`_
+* `Release process`_
+
+In pip 20.3, we've `made a big improvement to the heart of pip`_; `learn more`_. We want your input, so `sign up for our user experience research studies`_ to help us do it right.
+
+**Note**: pip 21.0, in January 2021, removed Python 2 support, per pip's `Python 2 support policy`_. Please migrate to Python 3.
+
+If you find bugs, need help, or want to talk to the developers, please use our mailing lists or chat rooms:
+
+* `Issue tracking`_
+* `Discourse channel`_
+* `User IRC`_
+
+If you want to get involved head over to GitHub to get the source code, look at our development documentation and feel free to jump on the developer mailing lists and chat rooms:
+
+* `GitHub page`_
+* `Development documentation`_
+* `Development mailing list`_
+* `Development IRC`_
+
+Code of Conduct
+---------------
+
+Everyone interacting in the pip project's codebases, issue trackers, chat
+rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
+
+.. _package installer: https://packaging.python.org/guides/tool-recommendations/
+.. _Python Package Index: https://pypi.org
+.. _Installation: https://pip.pypa.io/en/stable/installation/
+.. _Usage: https://pip.pypa.io/en/stable/
+.. _Release notes: https://pip.pypa.io/en/stable/news.html
+.. _Release process: https://pip.pypa.io/en/latest/development/release-process/
+.. _GitHub page: https://github.com/pypa/pip
+.. _Development documentation: https://pip.pypa.io/en/latest/development
+.. _made a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/11/pip-20-3-new-resolver.html
+.. _learn more: https://pip.pypa.io/en/latest/user_guide/#changes-to-the-pip-dependency-resolver-in-20-3-2020
+.. _sign up for our user experience research studies: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
+.. _Python 2 support policy: https://pip.pypa.io/en/latest/development/release-process/#python-2-support
+.. _Issue tracking: https://github.com/pypa/pip/issues
+.. _Discourse channel: https://discuss.python.org/c/packaging
+.. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/
+.. _User IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa
+.. _Development IRC: https://kiwiirc.com/nextclient/#ircs://irc.libera.chat:+6697/pypa-dev
+.. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md
+
+

animated_drawings/lib/python3.9/site-packages/pip-21.2.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.36.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

animated_drawings/lib/python3.9/site-packages/pip-21.2.4.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+pip = pip._internal.cli.main:main
+pip3 = pip._internal.cli.main:main
+pip3.9 = pip._internal.cli.main:main
+

animated_drawings/lib/python3.9/site-packages/pip-21.2.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+pip

animated_drawings/lib/python3.9/site-packages/pip/__init__.py

@@ -0,0 +1,13 @@
+from typing import List, Optional
+
+__version__ = "21.2.4"
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    """This is an internal API only meant for use by pip's own console scripts.
+
+    For additional details, see https://github.com/pypa/pip/issues/7498.
+    """
+    from pip._internal.utils.entrypoints import _wrapper
+
+    return _wrapper(args)

animated_drawings/lib/python3.9/site-packages/pip/__main__.py

@@ -0,0 +1,31 @@
+import os
+import sys
+import warnings
+
+# Remove '' and current working directory from the first entry
+# of sys.path, if present to avoid using current directory
+# in pip commands check, freeze, install, list and show,
+# when invoked as python -m pip <command>
+if sys.path[0] in ("", os.getcwd()):
+    sys.path.pop(0)
+
+# If we are running from a wheel, add the wheel to sys.path
+# This allows the usage python pip-*.whl/pip install pip-*.whl
+if __package__ == "":
+    # __file__ is pip-*.whl/pip/__main__.py
+    # first dirname call strips of '/__main__.py', second strips off '/pip'
+    # Resulting path is the name of the wheel itself
+    # Add that to sys.path so we can import pip
+    path = os.path.dirname(os.path.dirname(__file__))
+    sys.path.insert(0, path)
+
+if __name__ == "__main__":
+    # Work around the error reported in #9540, pending a proper fix.
+    # Note: It is essential the warning filter is set *before* importing
+    #       pip, as the deprecation happens at import time, not runtime.
+    warnings.filterwarnings(
+        "ignore", category=DeprecationWarning, module=".*packaging\\.version"
+    )
+    from pip._internal.cli.main import main as _main
+
+    sys.exit(_main())

animated_drawings/lib/python3.9/site-packages/pip/_internal/__init__.py

@@ -0,0 +1,19 @@
+from typing import List, Optional
+
+import pip._internal.utils.inject_securetransport  # noqa
+from pip._internal.utils import _log
+
+# init_logging() must be called before any call to logging.getLogger()
+# which happens at import of most modules.
+_log.init_logging()
+
+
+def main(args: (Optional[List[str]]) = None) -> int:
+    """This is preserved for old console scripts that may still be referencing
+    it.
+
+    For additional details, see https://github.com/pypa/pip/issues/7498.
+    """
+    from pip._internal.utils.entrypoints import _wrapper
+
+    return _wrapper(args)

animated_drawings/lib/python3.9/site-packages/pip/_internal/build_env.py

@@ -0,0 +1,294 @@
+"""Build Environment used for isolation during sdist building
+"""
+
+import contextlib
+import logging
+import os
+import pathlib
+import sys
+import textwrap
+import zipfile
+from collections import OrderedDict
+from sysconfig import get_paths
+from types import TracebackType
+from typing import TYPE_CHECKING, Iterable, Iterator, List, Optional, Set, Tuple, Type
+
+from pip._vendor.certifi import where
+from pip._vendor.packaging.requirements import Requirement
+from pip._vendor.packaging.version import Version
+
+from pip import __file__ as pip_location
+from pip._internal.cli.spinners import open_spinner
+from pip._internal.locations import get_platlib, get_prefixed_libs, get_purelib
+from pip._internal.metadata import get_environment
+from pip._internal.utils.subprocess import call_subprocess
+from pip._internal.utils.temp_dir import TempDirectory, tempdir_kinds
+
+if TYPE_CHECKING:
+    from pip._internal.index.package_finder import PackageFinder
+
+logger = logging.getLogger(__name__)
+
+
+class _Prefix:
+
+    def __init__(self, path):
+        # type: (str) -> None
+        self.path = path
+        self.setup = False
+        self.bin_dir = get_paths(
+            'nt' if os.name == 'nt' else 'posix_prefix',
+            vars={'base': path, 'platbase': path}
+        )['scripts']
+        self.lib_dirs = get_prefixed_libs(path)
+
+
+@contextlib.contextmanager
+def _create_standalone_pip() -> Iterator[str]:
+    """Create a "standalone pip" zip file.
+
+    The zip file's content is identical to the currently-running pip.
+    It will be used to install requirements into the build environment.
+    """
+    source = pathlib.Path(pip_location).resolve().parent
+
+    # Return the current instance if `source` is not a directory. We can't build
+    # a zip from this, and it likely means the instance is already standalone.
+    if not source.is_dir():
+        yield str(source)
+        return
+
+    with TempDirectory(kind="standalone-pip") as tmp_dir:
+        pip_zip = os.path.join(tmp_dir.path, "__env_pip__.zip")
+        kwargs = {}
+        if sys.version_info >= (3, 8):
+            kwargs["strict_timestamps"] = False
+        with zipfile.ZipFile(pip_zip, "w", **kwargs) as zf:
+            for child in source.rglob("*"):
+                zf.write(child, child.relative_to(source.parent).as_posix())
+        yield os.path.join(pip_zip, "pip")
+
+
+class BuildEnvironment:
+    """Creates and manages an isolated environment to install build deps
+    """
+
+    def __init__(self):
+        # type: () -> None
+        temp_dir = TempDirectory(
+            kind=tempdir_kinds.BUILD_ENV, globally_managed=True
+        )
+
+        self._prefixes = OrderedDict(
+            (name, _Prefix(os.path.join(temp_dir.path, name)))
+            for name in ('normal', 'overlay')
+        )
+
+        self._bin_dirs = []  # type: List[str]
+        self._lib_dirs = []  # type: List[str]
+        for prefix in reversed(list(self._prefixes.values())):
+            self._bin_dirs.append(prefix.bin_dir)
+            self._lib_dirs.extend(prefix.lib_dirs)
+
+        # Customize site to:
+        # - ensure .pth files are honored
+        # - prevent access to system site packages
+        system_sites = {
+            os.path.normcase(site) for site in (get_purelib(), get_platlib())
+        }
+        self._site_dir = os.path.join(temp_dir.path, 'site')
+        if not os.path.exists(self._site_dir):
+            os.mkdir(self._site_dir)
+        with open(os.path.join(self._site_dir, 'sitecustomize.py'), 'w') as fp:
+            fp.write(textwrap.dedent(
+                '''
+                import os, site, sys
+
+                # First, drop system-sites related paths.
+                original_sys_path = sys.path[:]
+                known_paths = set()
+                for path in {system_sites!r}:
+                    site.addsitedir(path, known_paths=known_paths)
+                system_paths = set(
+                    os.path.normcase(path)
+                    for path in sys.path[len(original_sys_path):]
+                )
+                original_sys_path = [
+                    path for path in original_sys_path
+                    if os.path.normcase(path) not in system_paths
+                ]
+                sys.path = original_sys_path
+
+                # Second, add lib directories.
+                # ensuring .pth file are processed.
+                for path in {lib_dirs!r}:
+                    assert not path in sys.path
+                    site.addsitedir(path)
+                '''
+            ).format(system_sites=system_sites, lib_dirs=self._lib_dirs))
+
+    def __enter__(self):
+        # type: () -> None
+        self._save_env = {
+            name: os.environ.get(name, None)
+            for name in ('PATH', 'PYTHONNOUSERSITE', 'PYTHONPATH')
+        }
+
+        path = self._bin_dirs[:]
+        old_path = self._save_env['PATH']
+        if old_path:
+            path.extend(old_path.split(os.pathsep))
+
+        pythonpath = [self._site_dir]
+
+        os.environ.update({
+            'PATH': os.pathsep.join(path),
+            'PYTHONNOUSERSITE': '1',
+            'PYTHONPATH': os.pathsep.join(pythonpath),
+        })
+
+    def __exit__(
+        self,
+        exc_type,  # type: Optional[Type[BaseException]]
+        exc_val,  # type: Optional[BaseException]
+        exc_tb  # type: Optional[TracebackType]
+    ):
+        # type: (...) -> None
+        for varname, old_value in self._save_env.items():
+            if old_value is None:
+                os.environ.pop(varname, None)
+            else:
+                os.environ[varname] = old_value
+
+    def check_requirements(self, reqs):
+        # type: (Iterable[str]) -> Tuple[Set[Tuple[str, str]], Set[str]]
+        """Return 2 sets:
+            - conflicting requirements: set of (installed, wanted) reqs tuples
+            - missing requirements: set of reqs
+        """
+        missing = set()
+        conflicting = set()
+        if reqs:
+            env = get_environment(self._lib_dirs)
+            for req_str in reqs:
+                req = Requirement(req_str)
+                dist = env.get_distribution(req.name)
+                if not dist:
+                    missing.add(req_str)
+                    continue
+                if isinstance(dist.version, Version):
+                    installed_req_str = f"{req.name}=={dist.version}"
+                else:
+                    installed_req_str = f"{req.name}==={dist.version}"
+                if dist.version not in req.specifier:
+                    conflicting.add((installed_req_str, req_str))
+                # FIXME: Consider direct URL?
+        return conflicting, missing
+
+    def install_requirements(
+        self,
+        finder,  # type: PackageFinder
+        requirements,  # type: Iterable[str]
+        prefix_as_string,  # type: str
+        message  # type: str
+    ):
+        # type: (...) -> None
+        prefix = self._prefixes[prefix_as_string]
+        assert not prefix.setup
+        prefix.setup = True
+        if not requirements:
+            return
+        with contextlib.ExitStack() as ctx:
+            # TODO: Remove this block when dropping 3.6 support. Python 3.6
+            # lacks importlib.resources and pep517 has issues loading files in
+            # a zip, so we fallback to the "old" method by adding the current
+            # pip directory to the child process's sys.path.
+            if sys.version_info < (3, 7):
+                pip_runnable = os.path.dirname(pip_location)
+            else:
+                pip_runnable = ctx.enter_context(_create_standalone_pip())
+            self._install_requirements(
+                pip_runnable,
+                finder,
+                requirements,
+                prefix,
+                message,
+            )
+
+    @staticmethod
+    def _install_requirements(
+        pip_runnable: str,
+        finder: "PackageFinder",
+        requirements: Iterable[str],
+        prefix: _Prefix,
+        message: str,
+    ) -> None:
+        args = [
+            sys.executable, pip_runnable, 'install',
+            '--ignore-installed', '--no-user', '--prefix', prefix.path,
+            '--no-warn-script-location',
+        ]  # type: List[str]
+        if logger.getEffectiveLevel() <= logging.DEBUG:
+            args.append('-v')
+        for format_control in ('no_binary', 'only_binary'):
+            formats = getattr(finder.format_control, format_control)
+            args.extend(('--' + format_control.replace('_', '-'),
+                         ','.join(sorted(formats or {':none:'}))))
+
+        index_urls = finder.index_urls
+        if index_urls:
+            args.extend(['-i', index_urls[0]])
+            for extra_index in index_urls[1:]:
+                args.extend(['--extra-index-url', extra_index])
+        else:
+            args.append('--no-index')
+        for link in finder.find_links:
+            args.extend(['--find-links', link])
+
+        for host in finder.trusted_hosts:
+            args.extend(['--trusted-host', host])
+        if finder.allow_all_prereleases:
+            args.append('--pre')
+        if finder.prefer_binary:
+            args.append('--prefer-binary')
+        args.append('--')
+        args.extend(requirements)
+        extra_environ = {"_PIP_STANDALONE_CERT": where()}
+        with open_spinner(message) as spinner:
+            call_subprocess(args, spinner=spinner, extra_environ=extra_environ)
+
+
+class NoOpBuildEnvironment(BuildEnvironment):
+    """A no-op drop-in replacement for BuildEnvironment
+    """
+
+    def __init__(self):
+        # type: () -> None
+        pass
+
+    def __enter__(self):
+        # type: () -> None
+        pass
+
+    def __exit__(
+        self,
+        exc_type,  # type: Optional[Type[BaseException]]
+        exc_val,  # type: Optional[BaseException]
+        exc_tb  # type: Optional[TracebackType]
+    ):
+        # type: (...) -> None
+        pass
+
+    def cleanup(self):
+        # type: () -> None
+        pass
+
+    def install_requirements(
+        self,
+        finder,  # type: PackageFinder
+        requirements,  # type: Iterable[str]
+        prefix_as_string,  # type: str
+        message  # type: str
+    ):
+        # type: (...) -> None
+        raise NotImplementedError()

animated_drawings/lib/python3.9/site-packages/pip/_internal/cache.py

@@ -0,0 +1,287 @@
+"""Cache Management
+"""
+
+import hashlib
+import json
+import logging
+import os
+from typing import Any, Dict, List, Optional, Set
+
+from pip._vendor.packaging.tags import Tag, interpreter_name, interpreter_version
+from pip._vendor.packaging.utils import canonicalize_name
+
+from pip._internal.exceptions import InvalidWheelFilename
+from pip._internal.models.format_control import FormatControl
+from pip._internal.models.link import Link
+from pip._internal.models.wheel import Wheel
+from pip._internal.utils.temp_dir import TempDirectory, tempdir_kinds
+from pip._internal.utils.urls import path_to_url
+
+logger = logging.getLogger(__name__)
+
+
+def _hash_dict(d):
+    # type: (Dict[str, str]) -> str
+    """Return a stable sha224 of a dictionary."""
+    s = json.dumps(d, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return hashlib.sha224(s.encode("ascii")).hexdigest()
+
+
+class Cache:
+    """An abstract class - provides cache directories for data from links
+
+
+        :param cache_dir: The root of the cache.
+        :param format_control: An object of FormatControl class to limit
+            binaries being read from the cache.
+        :param allowed_formats: which formats of files the cache should store.
+            ('binary' and 'source' are the only allowed values)
+    """
+
+    def __init__(self, cache_dir, format_control, allowed_formats):
+        # type: (str, FormatControl, Set[str]) -> None
+        super().__init__()
+        assert not cache_dir or os.path.isabs(cache_dir)
+        self.cache_dir = cache_dir or None
+        self.format_control = format_control
+        self.allowed_formats = allowed_formats
+
+        _valid_formats = {"source", "binary"}
+        assert self.allowed_formats.union(_valid_formats) == _valid_formats
+
+    def _get_cache_path_parts(self, link):
+        # type: (Link) -> List[str]
+        """Get parts of part that must be os.path.joined with cache_dir
+        """
+
+        # We want to generate an url to use as our cache key, we don't want to
+        # just re-use the URL because it might have other items in the fragment
+        # and we don't care about those.
+        key_parts = {"url": link.url_without_fragment}
+        if link.hash_name is not None and link.hash is not None:
+            key_parts[link.hash_name] = link.hash
+        if link.subdirectory_fragment:
+            key_parts["subdirectory"] = link.subdirectory_fragment
+
+        # Include interpreter name, major and minor version in cache key
+        # to cope with ill-behaved sdists that build a different wheel
+        # depending on the python version their setup.py is being run on,
+        # and don't encode the difference in compatibility tags.
+        # https://github.com/pypa/pip/issues/7296
+        key_parts["interpreter_name"] = interpreter_name()
+        key_parts["interpreter_version"] = interpreter_version()
+
+        # Encode our key url with sha224, we'll use this because it has similar
+        # security properties to sha256, but with a shorter total output (and
+        # thus less secure). However the differences don't make a lot of
+        # difference for our use case here.
+        hashed = _hash_dict(key_parts)
+
+        # We want to nest the directories some to prevent having a ton of top
+        # level directories where we might run out of sub directories on some
+        # FS.
+        parts = [hashed[:2], hashed[2:4], hashed[4:6], hashed[6:]]
+
+        return parts
+
+    def _get_candidates(self, link, canonical_package_name):
+        # type: (Link, str) -> List[Any]
+        can_not_cache = (
+            not self.cache_dir or
+            not canonical_package_name or
+            not link
+        )
+        if can_not_cache:
+            return []
+
+        formats = self.format_control.get_allowed_formats(
+            canonical_package_name
+        )
+        if not self.allowed_formats.intersection(formats):
+            return []
+
+        candidates = []
+        path = self.get_path_for_link(link)
+        if os.path.isdir(path):
+            for candidate in os.listdir(path):
+                candidates.append((candidate, path))
+        return candidates
+
+    def get_path_for_link(self, link):
+        # type: (Link) -> str
+        """Return a directory to store cached items in for link.
+        """
+        raise NotImplementedError()
+
+    def get(
+        self,
+        link,            # type: Link
+        package_name,    # type: Optional[str]
+        supported_tags,  # type: List[Tag]
+    ):
+        # type: (...) -> Link
+        """Returns a link to a cached item if it exists, otherwise returns the
+        passed link.
+        """
+        raise NotImplementedError()
+
+
+class SimpleWheelCache(Cache):
+    """A cache of wheels for future installs.
+    """
+
+    def __init__(self, cache_dir, format_control):
+        # type: (str, FormatControl) -> None
+        super().__init__(cache_dir, format_control, {"binary"})
+
+    def get_path_for_link(self, link):
+        # type: (Link) -> str
+        """Return a directory to store cached wheels for link
+
+        Because there are M wheels for any one sdist, we provide a directory
+        to cache them in, and then consult that directory when looking up
+        cache hits.
+
+        We only insert things into the cache if they have plausible version
+        numbers, so that we don't contaminate the cache with things that were
+        not unique. E.g. ./package might have dozens of installs done for it
+        and build a version of 0.0...and if we built and cached a wheel, we'd
+        end up using the same wheel even if the source has been edited.
+
+        :param link: The link of the sdist for which this will cache wheels.
+        """
+        parts = self._get_cache_path_parts(link)
+        assert self.cache_dir
+        # Store wheels within the root cache_dir
+        return os.path.join(self.cache_dir, "wheels", *parts)
+
+    def get(
+        self,
+        link,            # type: Link
+        package_name,    # type: Optional[str]
+        supported_tags,  # type: List[Tag]
+    ):
+        # type: (...) -> Link
+        candidates = []
+
+        if not package_name:
+            return link
+
+        canonical_package_name = canonicalize_name(package_name)
+        for wheel_name, wheel_dir in self._get_candidates(
+            link, canonical_package_name
+        ):
+            try:
+                wheel = Wheel(wheel_name)
+            except InvalidWheelFilename:
+                continue
+            if canonicalize_name(wheel.name) != canonical_package_name:
+                logger.debug(
+                    "Ignoring cached wheel %s for %s as it "
+                    "does not match the expected distribution name %s.",
+                    wheel_name, link, package_name,
+                )
+                continue
+            if not wheel.supported(supported_tags):
+                # Built for a different python/arch/etc
+                continue
+            candidates.append(
+                (
+                    wheel.support_index_min(supported_tags),
+                    wheel_name,
+                    wheel_dir,
+                )
+            )
+
+        if not candidates:
+            return link
+
+        _, wheel_name, wheel_dir = min(candidates)
+        return Link(path_to_url(os.path.join(wheel_dir, wheel_name)))
+
+
+class EphemWheelCache(SimpleWheelCache):
+    """A SimpleWheelCache that creates it's own temporary cache directory
+    """
+
+    def __init__(self, format_control):
+        # type: (FormatControl) -> None
+        self._temp_dir = TempDirectory(
+            kind=tempdir_kinds.EPHEM_WHEEL_CACHE,
+            globally_managed=True,
+        )
+
+        super().__init__(self._temp_dir.path, format_control)
+
+
+class CacheEntry:
+    def __init__(
+        self,
+        link,  # type: Link
+        persistent,  # type: bool
+    ):
+        self.link = link
+        self.persistent = persistent
+
+
+class WheelCache(Cache):
+    """Wraps EphemWheelCache and SimpleWheelCache into a single Cache
+
+    This Cache allows for gracefully degradation, using the ephem wheel cache
+    when a certain link is not found in the simple wheel cache first.
+    """
+
+    def __init__(self, cache_dir, format_control):
+        # type: (str, FormatControl) -> None
+        super().__init__(cache_dir, format_control, {'binary'})
+        self._wheel_cache = SimpleWheelCache(cache_dir, format_control)
+        self._ephem_cache = EphemWheelCache(format_control)
+
+    def get_path_for_link(self, link):
+        # type: (Link) -> str
+        return self._wheel_cache.get_path_for_link(link)
+
+    def get_ephem_path_for_link(self, link):
+        # type: (Link) -> str
+        return self._ephem_cache.get_path_for_link(link)
+
+    def get(
+        self,
+        link,            # type: Link
+        package_name,    # type: Optional[str]
+        supported_tags,  # type: List[Tag]
+    ):
+        # type: (...) -> Link
+        cache_entry = self.get_cache_entry(link, package_name, supported_tags)
+        if cache_entry is None:
+            return link
+        return cache_entry.link
+
+    def get_cache_entry(
+        self,
+        link,            # type: Link
+        package_name,    # type: Optional[str]
+        supported_tags,  # type: List[Tag]
+    ):
+        # type: (...) -> Optional[CacheEntry]
+        """Returns a CacheEntry with a link to a cached item if it exists or
+        None. The cache entry indicates if the item was found in the persistent
+        or ephemeral cache.
+        """
+        retval = self._wheel_cache.get(
+            link=link,
+            package_name=package_name,
+            supported_tags=supported_tags,
+        )
+        if retval is not link:
+            return CacheEntry(retval, persistent=True)
+
+        retval = self._ephem_cache.get(
+            link=link,
+            package_name=package_name,
+            supported_tags=supported_tags,
+        )
+        if retval is not link:
+            return CacheEntry(retval, persistent=False)
+
+        return None

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/__init__.py

@@ -0,0 +1,4 @@
+"""Subpackage containing all of pip's command line interface related code
+"""
+
+# This file intentionally does not import submodules

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/autocompletion.py

@@ -0,0 +1,163 @@
+"""Logic that powers autocompletion installed by ``pip completion``.
+"""
+
+import optparse
+import os
+import sys
+from itertools import chain
+from typing import Any, Iterable, List, Optional
+
+from pip._internal.cli.main_parser import create_main_parser
+from pip._internal.commands import commands_dict, create_command
+from pip._internal.metadata import get_default_environment
+
+
+def autocomplete() -> None:
+    """Entry Point for completion of main and subcommand options."""
+    # Don't complete if user hasn't sourced bash_completion file.
+    if "PIP_AUTO_COMPLETE" not in os.environ:
+        return
+    cwords = os.environ["COMP_WORDS"].split()[1:]
+    cword = int(os.environ["COMP_CWORD"])
+    try:
+        current = cwords[cword - 1]
+    except IndexError:
+        current = ""
+
+    parser = create_main_parser()
+    subcommands = list(commands_dict)
+    options = []
+
+    # subcommand
+    subcommand_name: Optional[str] = None
+    for word in cwords:
+        if word in subcommands:
+            subcommand_name = word
+            break
+    # subcommand options
+    if subcommand_name is not None:
+        # special case: 'help' subcommand has no options
+        if subcommand_name == "help":
+            sys.exit(1)
+        # special case: list locally installed dists for show and uninstall
+        should_list_installed = not current.startswith("-") and subcommand_name in [
+            "show",
+            "uninstall",
+        ]
+        if should_list_installed:
+            env = get_default_environment()
+            lc = current.lower()
+            installed = [
+                dist.canonical_name
+                for dist in env.iter_installed_distributions(local_only=True)
+                if dist.canonical_name.startswith(lc)
+                and dist.canonical_name not in cwords[1:]
+            ]
+            # if there are no dists installed, fall back to option completion
+            if installed:
+                for dist in installed:
+                    print(dist)
+                sys.exit(1)
+
+        subcommand = create_command(subcommand_name)
+
+        for opt in subcommand.parser.option_list_all:
+            if opt.help != optparse.SUPPRESS_HELP:
+                for opt_str in opt._long_opts + opt._short_opts:
+                    options.append((opt_str, opt.nargs))
+
+        # filter out previously specified options from available options
+        prev_opts = [x.split("=")[0] for x in cwords[1 : cword - 1]]
+        options = [(x, v) for (x, v) in options if x not in prev_opts]
+        # filter options by current input
+        options = [(k, v) for k, v in options if k.startswith(current)]
+        # get completion type given cwords and available subcommand options
+        completion_type = get_path_completion_type(
+            cwords,
+            cword,
+            subcommand.parser.option_list_all,
+        )
+        # get completion files and directories if ``completion_type`` is
+        # ``<file>``, ``<dir>`` or ``<path>``
+        if completion_type:
+            paths = auto_complete_paths(current, completion_type)
+            options = [(path, 0) for path in paths]
+        for option in options:
+            opt_label = option[0]
+            # append '=' to options which require args
+            if option[1] and option[0][:2] == "--":
+                opt_label += "="
+            print(opt_label)
+    else:
+        # show main parser options only when necessary
+
+        opts = [i.option_list for i in parser.option_groups]
+        opts.append(parser.option_list)
+        flattened_opts = chain.from_iterable(opts)
+        if current.startswith("-"):
+            for opt in flattened_opts:
+                if opt.help != optparse.SUPPRESS_HELP:
+                    subcommands += opt._long_opts + opt._short_opts
+        else:
+            # get completion type given cwords and all available options
+            completion_type = get_path_completion_type(cwords, cword, flattened_opts)
+            if completion_type:
+                subcommands = list(auto_complete_paths(current, completion_type))
+
+        print(" ".join([x for x in subcommands if x.startswith(current)]))
+    sys.exit(1)
+
+
+def get_path_completion_type(
+    cwords: List[str], cword: int, opts: Iterable[Any]
+) -> Optional[str]:
+    """Get the type of path completion (``file``, ``dir``, ``path`` or None)
+
+    :param cwords: same as the environmental variable ``COMP_WORDS``
+    :param cword: same as the environmental variable ``COMP_CWORD``
+    :param opts: The available options to check
+    :return: path completion type (``file``, ``dir``, ``path`` or None)
+    """
+    if cword < 2 or not cwords[cword - 2].startswith("-"):
+        return None
+    for opt in opts:
+        if opt.help == optparse.SUPPRESS_HELP:
+            continue
+        for o in str(opt).split("/"):
+            if cwords[cword - 2].split("=")[0] == o:
+                if not opt.metavar or any(
+                    x in ("path", "file", "dir") for x in opt.metavar.split("/")
+                ):
+                    return opt.metavar
+    return None
+
+
+def auto_complete_paths(current: str, completion_type: str) -> Iterable[str]:
+    """If ``completion_type`` is ``file`` or ``path``, list all regular files
+    and directories starting with ``current``; otherwise only list directories
+    starting with ``current``.
+
+    :param current: The word to be completed
+    :param completion_type: path completion type(`file`, `path` or `dir`)i
+    :return: A generator of regular files and/or directories
+    """
+    directory, filename = os.path.split(current)
+    current_path = os.path.abspath(directory)
+    # Don't complete paths if they can't be accessed
+    if not os.access(current_path, os.R_OK):
+        return
+    filename = os.path.normcase(filename)
+    # list all files that start with ``filename``
+    file_list = (
+        x for x in os.listdir(current_path) if os.path.normcase(x).startswith(filename)
+    )
+    for f in file_list:
+        opt = os.path.join(current_path, f)
+        comp_file = os.path.normcase(os.path.join(directory, f))
+        # complete regular files when there is not ``<dir>`` after option
+        # complete directories when there is ``<file>``, ``<path>`` or
+        # ``<dir>``after option
+        if completion_type != "dir" and os.path.isfile(opt):
+            yield comp_file
+        elif os.path.isdir(opt):
+            yield os.path.join(comp_file, "")

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/base_command.py

@@ -0,0 +1,214 @@
+"""Base Command class, and related routines"""
+
+import logging
+import logging.config
+import optparse
+import os
+import sys
+import traceback
+from optparse import Values
+from typing import Any, List, Optional, Tuple
+
+from pip._internal.cli import cmdoptions
+from pip._internal.cli.command_context import CommandContextMixIn
+from pip._internal.cli.parser import ConfigOptionParser, UpdatingDefaultsHelpFormatter
+from pip._internal.cli.status_codes import (
+    ERROR,
+    PREVIOUS_BUILD_DIR_ERROR,
+    UNKNOWN_ERROR,
+    VIRTUALENV_NOT_FOUND,
+)
+from pip._internal.exceptions import (
+    BadCommand,
+    CommandError,
+    InstallationError,
+    NetworkConnectionError,
+    PreviousBuildDirError,
+    UninstallationError,
+)
+from pip._internal.utils.deprecation import deprecated
+from pip._internal.utils.filesystem import check_path_owner
+from pip._internal.utils.logging import BrokenStdoutLoggingError, setup_logging
+from pip._internal.utils.misc import get_prog, normalize_path
+from pip._internal.utils.temp_dir import TempDirectoryTypeRegistry as TempDirRegistry
+from pip._internal.utils.temp_dir import global_tempdir_manager, tempdir_registry
+from pip._internal.utils.virtualenv import running_under_virtualenv
+
+__all__ = ["Command"]
+
+logger = logging.getLogger(__name__)
+
+
+class Command(CommandContextMixIn):
+    usage: str = ""
+    ignore_require_venv: bool = False
+
+    def __init__(self, name: str, summary: str, isolated: bool = False) -> None:
+        super().__init__()
+
+        self.name = name
+        self.summary = summary
+        self.parser = ConfigOptionParser(
+            usage=self.usage,
+            prog=f"{get_prog()} {name}",
+            formatter=UpdatingDefaultsHelpFormatter(),
+            add_help_option=False,
+            name=name,
+            description=self.__doc__,
+            isolated=isolated,
+        )
+
+        self.tempdir_registry: Optional[TempDirRegistry] = None
+
+        # Commands should add options to this option group
+        optgroup_name = f"{self.name.capitalize()} Options"
+        self.cmd_opts = optparse.OptionGroup(self.parser, optgroup_name)
+
+        # Add the general options
+        gen_opts = cmdoptions.make_option_group(
+            cmdoptions.general_group,
+            self.parser,
+        )
+        self.parser.add_option_group(gen_opts)
+
+        self.add_options()
+
+    def add_options(self) -> None:
+        pass
+
+    def handle_pip_version_check(self, options: Values) -> None:
+        """
+        This is a no-op so that commands by default do not do the pip version
+        check.
+        """
+        # Make sure we do the pip version check if the index_group options
+        # are present.
+        assert not hasattr(options, "no_index")
+
+    def run(self, options: Values, args: List[Any]) -> int:
+        raise NotImplementedError
+
+    def parse_args(self, args: List[str]) -> Tuple[Any, Any]:
+        # factored out for testability
+        return self.parser.parse_args(args)
+
+    def main(self, args: List[str]) -> int:
+        try:
+            with self.main_context():
+                return self._main(args)
+        finally:
+            logging.shutdown()
+
+    def _main(self, args: List[str]) -> int:
+        # We must initialize this before the tempdir manager, otherwise the
+        # configuration would not be accessible by the time we clean up the
+        # tempdir manager.
+        self.tempdir_registry = self.enter_context(tempdir_registry())
+        # Intentionally set as early as possible so globally-managed temporary
+        # directories are available to the rest of the code.
+        self.enter_context(global_tempdir_manager())
+
+        options, args = self.parse_args(args)
+
+        # Set verbosity so that it can be used elsewhere.
+        self.verbosity = options.verbose - options.quiet
+
+        level_number = setup_logging(
+            verbosity=self.verbosity,
+            no_color=options.no_color,
+            user_log_file=options.log,
+        )
+
+        # TODO: Try to get these passing down from the command?
+        #       without resorting to os.environ to hold these.
+        #       This also affects isolated builds and it should.
+
+        if options.no_input:
+            os.environ["PIP_NO_INPUT"] = "1"
+
+        if options.exists_action:
+            os.environ["PIP_EXISTS_ACTION"] = " ".join(options.exists_action)
+
+        if options.require_venv and not self.ignore_require_venv:
+            # If a venv is required check if it can really be found
+            if not running_under_virtualenv():
+                logger.critical("Could not find an activated virtualenv (required).")
+                sys.exit(VIRTUALENV_NOT_FOUND)
+
+        if options.cache_dir:
+            options.cache_dir = normalize_path(options.cache_dir)
+            if not check_path_owner(options.cache_dir):
+                logger.warning(
+                    "The directory '%s' or its parent directory is not owned "
+                    "or is not writable by the current user. The cache "
+                    "has been disabled. Check the permissions and owner of "
+                    "that directory. If executing pip with sudo, you should "
+                    "use sudo's -H flag.",
+                    options.cache_dir,
+                )
+                options.cache_dir = None
+
+        if getattr(options, "build_dir", None):
+            deprecated(
+                reason=(
+                    "The -b/--build/--build-dir/--build-directory "
+                    "option is deprecated and has no effect anymore."
+                ),
+                replacement=(
+                    "use the TMPDIR/TEMP/TMP environment variable, "
+                    "possibly combined with --no-clean"
+                ),
+                gone_in="21.3",
+                issue=8333,
+            )
+
+        if "2020-resolver" in options.features_enabled:
+            logger.warning(
+                "--use-feature=2020-resolver no longer has any effect, "
+                "since it is now the default dependency resolver in pip. "
+                "This will become an error in pip 21.0."
+            )
+
+        try:
+            status = self.run(options, args)
+            assert isinstance(status, int)
+            return status
+        except PreviousBuildDirError as exc:
+            logger.critical(str(exc))
+            logger.debug("Exception information:", exc_info=True)
+
+            return PREVIOUS_BUILD_DIR_ERROR
+        except (
+            InstallationError,
+            UninstallationError,
+            BadCommand,
+            NetworkConnectionError,
+        ) as exc:
+            logger.critical(str(exc))
+            logger.debug("Exception information:", exc_info=True)
+
+            return ERROR
+        except CommandError as exc:
+            logger.critical("%s", exc)
+            logger.debug("Exception information:", exc_info=True)
+
+            return ERROR
+        except BrokenStdoutLoggingError:
+            # Bypass our logger and write any remaining messages to stderr
+            # because stdout no longer works.
+            print("ERROR: Pipe to stdout was broken", file=sys.stderr)
+            if level_number <= logging.DEBUG:
+                traceback.print_exc(file=sys.stderr)
+
+            return ERROR
+        except KeyboardInterrupt:
+            logger.critical("Operation cancelled by user")
+            logger.debug("Exception information:", exc_info=True)
+
+            return ERROR
+        except BaseException:
+            logger.critical("Exception:", exc_info=True)
+
+            return UNKNOWN_ERROR
+        finally:
+            self.handle_pip_version_check(options)

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/cmdoptions.py

@@ -0,0 +1,1009 @@
+"""
+shared options and groups
+
+The principle here is to define options once, but *not* instantiate them
+globally. One reason being that options with action='append' can carry state
+between parses. pip parses general options twice internally, and shouldn't
+pass on state. To be consistent, all options will follow this design.
+"""
+
+# The following comment should be removed at some point in the future.
+# mypy: strict-optional=False
+
+import os
+import textwrap
+import warnings
+from functools import partial
+from optparse import SUPPRESS_HELP, Option, OptionGroup, OptionParser, Values
+from textwrap import dedent
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from pip._vendor.packaging.utils import canonicalize_name
+
+from pip._internal.cli.parser import ConfigOptionParser
+from pip._internal.cli.progress_bars import BAR_TYPES
+from pip._internal.exceptions import CommandError
+from pip._internal.locations import USER_CACHE_DIR, get_src_prefix
+from pip._internal.models.format_control import FormatControl
+from pip._internal.models.index import PyPI
+from pip._internal.models.target_python import TargetPython
+from pip._internal.utils.hashes import STRONG_HASHES
+from pip._internal.utils.misc import strtobool
+
+
+def raise_option_error(parser: OptionParser, option: Option, msg: str) -> None:
+    """
+    Raise an option parsing error using parser.error().
+
+    Args:
+      parser: an OptionParser instance.
+      option: an Option instance.
+      msg: the error text.
+    """
+    msg = f"{option} error: {msg}"
+    msg = textwrap.fill(" ".join(msg.split()))
+    parser.error(msg)
+
+
+def make_option_group(group: Dict[str, Any], parser: ConfigOptionParser) -> OptionGroup:
+    """
+    Return an OptionGroup object
+    group  -- assumed to be dict with 'name' and 'options' keys
+    parser -- an optparse Parser
+    """
+    option_group = OptionGroup(parser, group["name"])
+    for option in group["options"]:
+        option_group.add_option(option())
+    return option_group
+
+
+def check_install_build_global(
+    options: Values, check_options: Optional[Values] = None
+) -> None:
+    """Disable wheels if per-setup.py call options are set.
+
+    :param options: The OptionParser options to update.
+    :param check_options: The options to check, if not supplied defaults to
+        options.
+    """
+    if check_options is None:
+        check_options = options
+
+    def getname(n: str) -> Optional[Any]:
+        return getattr(check_options, n, None)
+
+    names = ["build_options", "global_options", "install_options"]
+    if any(map(getname, names)):
+        control = options.format_control
+        control.disallow_binaries()
+        warnings.warn(
+            "Disabling all use of wheels due to the use of --build-option "
+            "/ --global-option / --install-option.",
+            stacklevel=2,
+        )
+
+
+def check_dist_restriction(options: Values, check_target: bool = False) -> None:
+    """Function for determining if custom platform options are allowed.
+
+    :param options: The OptionParser options.
+    :param check_target: Whether or not to check if --target is being used.
+    """
+    dist_restriction_set = any(
+        [
+            options.python_version,
+            options.platforms,
+            options.abis,
+            options.implementation,
+        ]
+    )
+
+    binary_only = FormatControl(set(), {":all:"})
+    sdist_dependencies_allowed = (
+        options.format_control != binary_only and not options.ignore_dependencies
+    )
+
+    # Installations or downloads using dist restrictions must not combine
+    # source distributions and dist-specific wheels, as they are not
+    # guaranteed to be locally compatible.
+    if dist_restriction_set and sdist_dependencies_allowed:
+        raise CommandError(
+            "When restricting platform and interpreter constraints using "
+            "--python-version, --platform, --abi, or --implementation, "
+            "either --no-deps must be set, or --only-binary=:all: must be "
+            "set and --no-binary must not be set (or must be set to "
+            ":none:)."
+        )
+
+    if check_target:
+        if dist_restriction_set and not options.target_dir:
+            raise CommandError(
+                "Can not use any platform or abi specific options unless "
+                "installing via '--target'"
+            )
+
+
+def _path_option_check(option: Option, opt: str, value: str) -> str:
+    return os.path.expanduser(value)
+
+
+def _package_name_option_check(option: Option, opt: str, value: str) -> str:
+    return canonicalize_name(value)
+
+
+class PipOption(Option):
+    TYPES = Option.TYPES + ("path", "package_name")
+    TYPE_CHECKER = Option.TYPE_CHECKER.copy()
+    TYPE_CHECKER["package_name"] = _package_name_option_check
+    TYPE_CHECKER["path"] = _path_option_check
+
+
+###########
+# options #
+###########
+
+help_: Callable[..., Option] = partial(
+    Option,
+    "-h",
+    "--help",
+    dest="help",
+    action="help",
+    help="Show help.",
+)
+
+isolated_mode: Callable[..., Option] = partial(
+    Option,
+    "--isolated",
+    dest="isolated_mode",
+    action="store_true",
+    default=False,
+    help=(
+        "Run pip in an isolated mode, ignoring environment variables and user "
+        "configuration."
+    ),
+)
+
+require_virtualenv: Callable[..., Option] = partial(
+    Option,
+    # Run only if inside a virtualenv, bail if not.
+    "--require-virtualenv",
+    "--require-venv",
+    dest="require_venv",
+    action="store_true",
+    default=False,
+    help=SUPPRESS_HELP,
+)
+
+verbose: Callable[..., Option] = partial(
+    Option,
+    "-v",
+    "--verbose",
+    dest="verbose",
+    action="count",
+    default=0,
+    help="Give more output. Option is additive, and can be used up to 3 times.",
+)
+
+no_color: Callable[..., Option] = partial(
+    Option,
+    "--no-color",
+    dest="no_color",
+    action="store_true",
+    default=False,
+    help="Suppress colored output.",
+)
+
+version: Callable[..., Option] = partial(
+    Option,
+    "-V",
+    "--version",
+    dest="version",
+    action="store_true",
+    help="Show version and exit.",
+)
+
+quiet: Callable[..., Option] = partial(
+    Option,
+    "-q",
+    "--quiet",
+    dest="quiet",
+    action="count",
+    default=0,
+    help=(
+        "Give less output. Option is additive, and can be used up to 3"
+        " times (corresponding to WARNING, ERROR, and CRITICAL logging"
+        " levels)."
+    ),
+)
+
+progress_bar: Callable[..., Option] = partial(
+    Option,
+    "--progress-bar",
+    dest="progress_bar",
+    type="choice",
+    choices=list(BAR_TYPES.keys()),
+    default="on",
+    help=(
+        "Specify type of progress to be displayed ["
+        + "|".join(BAR_TYPES.keys())
+        + "] (default: %default)"
+    ),
+)
+
+log: Callable[..., Option] = partial(
+    PipOption,
+    "--log",
+    "--log-file",
+    "--local-log",
+    dest="log",
+    metavar="path",
+    type="path",
+    help="Path to a verbose appending log.",
+)
+
+no_input: Callable[..., Option] = partial(
+    Option,
+    # Don't ask for input
+    "--no-input",
+    dest="no_input",
+    action="store_true",
+    default=False,
+    help="Disable prompting for input.",
+)
+
+proxy: Callable[..., Option] = partial(
+    Option,
+    "--proxy",
+    dest="proxy",
+    type="str",
+    default="",
+    help="Specify a proxy in the form [user:passwd@]proxy.server:port.",
+)
+
+retries: Callable[..., Option] = partial(
+    Option,
+    "--retries",
+    dest="retries",
+    type="int",
+    default=5,
+    help="Maximum number of retries each connection should attempt "
+    "(default %default times).",
+)
+
+timeout: Callable[..., Option] = partial(
+    Option,
+    "--timeout",
+    "--default-timeout",
+    metavar="sec",
+    dest="timeout",
+    type="float",
+    default=15,
+    help="Set the socket timeout (default %default seconds).",
+)
+
+
+def exists_action() -> Option:
+    return Option(
+        # Option when path already exist
+        "--exists-action",
+        dest="exists_action",
+        type="choice",
+        choices=["s", "i", "w", "b", "a"],
+        default=[],
+        action="append",
+        metavar="action",
+        help="Default action when a path already exists: "
+        "(s)witch, (i)gnore, (w)ipe, (b)ackup, (a)bort.",
+    )
+
+
+cert: Callable[..., Option] = partial(
+    PipOption,
+    "--cert",
+    dest="cert",
+    type="path",
+    metavar="path",
+    help=(
+        "Path to PEM-encoded CA certificate bundle. "
+        "If provided, overrides the default. "
+        "See 'SSL Certificate Verification' in pip documentation "
+        "for more information."
+    ),
+)
+
+client_cert: Callable[..., Option] = partial(
+    PipOption,
+    "--client-cert",
+    dest="client_cert",
+    type="path",
+    default=None,
+    metavar="path",
+    help="Path to SSL client certificate, a single file containing the "
+    "private key and the certificate in PEM format.",
+)
+
+index_url: Callable[..., Option] = partial(
+    Option,
+    "-i",
+    "--index-url",
+    "--pypi-url",
+    dest="index_url",
+    metavar="URL",
+    default=PyPI.simple_url,
+    help="Base URL of the Python Package Index (default %default). "
+    "This should point to a repository compliant with PEP 503 "
+    "(the simple repository API) or a local directory laid out "
+    "in the same format.",
+)
+
+
+def extra_index_url() -> Option:
+    return Option(
+        "--extra-index-url",
+        dest="extra_index_urls",
+        metavar="URL",
+        action="append",
+        default=[],
+        help="Extra URLs of package indexes to use in addition to "
+        "--index-url. Should follow the same rules as "
+        "--index-url.",
+    )
+
+
+no_index: Callable[..., Option] = partial(
+    Option,
+    "--no-index",
+    dest="no_index",
+    action="store_true",
+    default=False,
+    help="Ignore package index (only looking at --find-links URLs instead).",
+)
+
+
+def find_links() -> Option:
+    return Option(
+        "-f",
+        "--find-links",
+        dest="find_links",
+        action="append",
+        default=[],
+        metavar="url",
+        help="If a URL or path to an html file, then parse for links to "
+        "archives such as sdist (.tar.gz) or wheel (.whl) files. "
+        "If a local path or file:// URL that's a directory, "
+        "then look for archives in the directory listing. "
+        "Links to VCS project URLs are not supported.",
+    )
+
+
+def trusted_host() -> Option:
+    return Option(
+        "--trusted-host",
+        dest="trusted_hosts",
+        action="append",
+        metavar="HOSTNAME",
+        default=[],
+        help="Mark this host or host:port pair as trusted, even though it "
+        "does not have valid or any HTTPS.",
+    )
+
+
+def constraints() -> Option:
+    return Option(
+        "-c",
+        "--constraint",
+        dest="constraints",
+        action="append",
+        default=[],
+        metavar="file",
+        help="Constrain versions using the given constraints file. "
+        "This option can be used multiple times.",
+    )
+
+
+def requirements() -> Option:
+    return Option(
+        "-r",
+        "--requirement",
+        dest="requirements",
+        action="append",
+        default=[],
+        metavar="file",
+        help="Install from the given requirements file. "
+        "This option can be used multiple times.",
+    )
+
+
+def editable() -> Option:
+    return Option(
+        "-e",
+        "--editable",
+        dest="editables",
+        action="append",
+        default=[],
+        metavar="path/url",
+        help=(
+            "Install a project in editable mode (i.e. setuptools "
+            '"develop mode") from a local project path or a VCS url.'
+        ),
+    )
+
+
+def _handle_src(option: Option, opt_str: str, value: str, parser: OptionParser) -> None:
+    value = os.path.abspath(value)
+    setattr(parser.values, option.dest, value)
+
+
+src: Callable[..., Option] = partial(
+    PipOption,
+    "--src",
+    "--source",
+    "--source-dir",
+    "--source-directory",
+    dest="src_dir",
+    type="path",
+    metavar="dir",
+    default=get_src_prefix(),
+    action="callback",
+    callback=_handle_src,
+    help="Directory to check out editable projects into. "
+    'The default in a virtualenv is "<venv path>/src". '
+    'The default for global installs is "<current dir>/src".',
+)
+
+
+def _get_format_control(values: Values, option: Option) -> Any:
+    """Get a format_control object."""
+    return getattr(values, option.dest)
+
+
+def _handle_no_binary(
+    option: Option, opt_str: str, value: str, parser: OptionParser
+) -> None:
+    existing = _get_format_control(parser.values, option)
+    FormatControl.handle_mutual_excludes(
+        value,
+        existing.no_binary,
+        existing.only_binary,
+    )
+
+
+def _handle_only_binary(
+    option: Option, opt_str: str, value: str, parser: OptionParser
+) -> None:
+    existing = _get_format_control(parser.values, option)
+    FormatControl.handle_mutual_excludes(
+        value,
+        existing.only_binary,
+        existing.no_binary,
+    )
+
+
+def no_binary() -> Option:
+    format_control = FormatControl(set(), set())
+    return Option(
+        "--no-binary",
+        dest="format_control",
+        action="callback",
+        callback=_handle_no_binary,
+        type="str",
+        default=format_control,
+        help="Do not use binary packages. Can be supplied multiple times, and "
+        'each time adds to the existing value. Accepts either ":all:" to '
+        'disable all binary packages, ":none:" to empty the set (notice '
+        "the colons), or one or more package names with commas between "
+        "them (no colons). Note that some packages are tricky to compile "
+        "and may fail to install when this option is used on them.",
+    )
+
+
+def only_binary() -> Option:
+    format_control = FormatControl(set(), set())
+    return Option(
+        "--only-binary",
+        dest="format_control",
+        action="callback",
+        callback=_handle_only_binary,
+        type="str",
+        default=format_control,
+        help="Do not use source packages. Can be supplied multiple times, and "
+        'each time adds to the existing value. Accepts either ":all:" to '
+        'disable all source packages, ":none:" to empty the set, or one '
+        "or more package names with commas between them. Packages "
+        "without binary distributions will fail to install when this "
+        "option is used on them.",
+    )
+
+
+platforms: Callable[..., Option] = partial(
+    Option,
+    "--platform",
+    dest="platforms",
+    metavar="platform",
+    action="append",
+    default=None,
+    help=(
+        "Only use wheels compatible with <platform>. Defaults to the "
+        "platform of the running system. Use this option multiple times to "
+        "specify multiple platforms supported by the target interpreter."
+    ),
+)
+
+
+# This was made a separate function for unit-testing purposes.
+def _convert_python_version(value: str) -> Tuple[Tuple[int, ...], Optional[str]]:
+    """
+    Convert a version string like "3", "37", or "3.7.3" into a tuple of ints.
+
+    :return: A 2-tuple (version_info, error_msg), where `error_msg` is
+        non-None if and only if there was a parsing error.
+    """
+    if not value:
+        # The empty string is the same as not providing a value.
+        return (None, None)
+
+    parts = value.split(".")
+    if len(parts) > 3:
+        return ((), "at most three version parts are allowed")
+
+    if len(parts) == 1:
+        # Then we are in the case of "3" or "37".
+        value = parts[0]
+        if len(value) > 1:
+            parts = [value[0], value[1:]]
+
+    try:
+        version_info = tuple(int(part) for part in parts)
+    except ValueError:
+        return ((), "each version part must be an integer")
+
+    return (version_info, None)
+
+
+def _handle_python_version(
+    option: Option, opt_str: str, value: str, parser: OptionParser
+) -> None:
+    """
+    Handle a provided --python-version value.
+    """
+    version_info, error_msg = _convert_python_version(value)
+    if error_msg is not None:
+        msg = "invalid --python-version value: {!r}: {}".format(
+            value,
+            error_msg,
+        )
+        raise_option_error(parser, option=option, msg=msg)
+
+    parser.values.python_version = version_info
+
+
+python_version: Callable[..., Option] = partial(
+    Option,
+    "--python-version",
+    dest="python_version",
+    metavar="python_version",
+    action="callback",
+    callback=_handle_python_version,
+    type="str",
+    default=None,
+    help=dedent(
+        """\
+    The Python interpreter version to use for wheel and "Requires-Python"
+    compatibility checks. Defaults to a version derived from the running
+    interpreter. The version can be specified using up to three dot-separated
+    integers (e.g. "3" for 3.0.0, "3.7" for 3.7.0, or "3.7.3"). A major-minor
+    version can also be given as a string without dots (e.g. "37" for 3.7.0).
+    """
+    ),
+)
+
+
+implementation: Callable[..., Option] = partial(
+    Option,
+    "--implementation",
+    dest="implementation",
+    metavar="implementation",
+    default=None,
+    help=(
+        "Only use wheels compatible with Python "
+        "implementation <implementation>, e.g. 'pp', 'jy', 'cp', "
+        " or 'ip'. If not specified, then the current "
+        "interpreter implementation is used.  Use 'py' to force "
+        "implementation-agnostic wheels."
+    ),
+)
+
+
+abis: Callable[..., Option] = partial(
+    Option,
+    "--abi",
+    dest="abis",
+    metavar="abi",
+    action="append",
+    default=None,
+    help=(
+        "Only use wheels compatible with Python abi <abi>, e.g. 'pypy_41'. "
+        "If not specified, then the current interpreter abi tag is used. "
+        "Use this option multiple times to specify multiple abis supported "
+        "by the target interpreter. Generally you will need to specify "
+        "--implementation, --platform, and --python-version when using this "
+        "option."
+    ),
+)
+
+
+def add_target_python_options(cmd_opts: OptionGroup) -> None:
+    cmd_opts.add_option(platforms())
+    cmd_opts.add_option(python_version())
+    cmd_opts.add_option(implementation())
+    cmd_opts.add_option(abis())
+
+
+def make_target_python(options: Values) -> TargetPython:
+    target_python = TargetPython(
+        platforms=options.platforms,
+        py_version_info=options.python_version,
+        abis=options.abis,
+        implementation=options.implementation,
+    )
+
+    return target_python
+
+
+def prefer_binary() -> Option:
+    return Option(
+        "--prefer-binary",
+        dest="prefer_binary",
+        action="store_true",
+        default=False,
+        help="Prefer older binary packages over newer source packages.",
+    )
+
+
+cache_dir: Callable[..., Option] = partial(
+    PipOption,
+    "--cache-dir",
+    dest="cache_dir",
+    default=USER_CACHE_DIR,
+    metavar="dir",
+    type="path",
+    help="Store the cache data in <dir>.",
+)
+
+
+def _handle_no_cache_dir(
+    option: Option, opt: str, value: str, parser: OptionParser
+) -> None:
+    """
+    Process a value provided for the --no-cache-dir option.
+
+    This is an optparse.Option callback for the --no-cache-dir option.
+    """
+    # The value argument will be None if --no-cache-dir is passed via the
+    # command-line, since the option doesn't accept arguments.  However,
+    # the value can be non-None if the option is triggered e.g. by an
+    # environment variable, like PIP_NO_CACHE_DIR=true.
+    if value is not None:
+        # Then parse the string value to get argument error-checking.
+        try:
+            strtobool(value)
+        except ValueError as exc:
+            raise_option_error(parser, option=option, msg=str(exc))
+
+    # Originally, setting PIP_NO_CACHE_DIR to a value that strtobool()
+    # converted to 0 (like "false" or "no") caused cache_dir to be disabled
+    # rather than enabled (logic would say the latter).  Thus, we disable
+    # the cache directory not just on values that parse to True, but (for
+    # backwards compatibility reasons) also on values that parse to False.
+    # In other words, always set it to False if the option is provided in
+    # some (valid) form.
+    parser.values.cache_dir = False
+
+
+no_cache: Callable[..., Option] = partial(
+    Option,
+    "--no-cache-dir",
+    dest="cache_dir",
+    action="callback",
+    callback=_handle_no_cache_dir,
+    help="Disable the cache.",
+)
+
+no_deps: Callable[..., Option] = partial(
+    Option,
+    "--no-deps",
+    "--no-dependencies",
+    dest="ignore_dependencies",
+    action="store_true",
+    default=False,
+    help="Don't install package dependencies.",
+)
+
+build_dir: Callable[..., Option] = partial(
+    PipOption,
+    "-b",
+    "--build",
+    "--build-dir",
+    "--build-directory",
+    dest="build_dir",
+    type="path",
+    metavar="dir",
+    help=SUPPRESS_HELP,
+)
+
+ignore_requires_python: Callable[..., Option] = partial(
+    Option,
+    "--ignore-requires-python",
+    dest="ignore_requires_python",
+    action="store_true",
+    help="Ignore the Requires-Python information.",
+)
+
+no_build_isolation: Callable[..., Option] = partial(
+    Option,
+    "--no-build-isolation",
+    dest="build_isolation",
+    action="store_false",
+    default=True,
+    help="Disable isolation when building a modern source distribution. "
+    "Build dependencies specified by PEP 518 must be already installed "
+    "if this option is used.",
+)
+
+
+def _handle_no_use_pep517(
+    option: Option, opt: str, value: str, parser: OptionParser
+) -> None:
+    """
+    Process a value provided for the --no-use-pep517 option.
+
+    This is an optparse.Option callback for the no_use_pep517 option.
+    """
+    # Since --no-use-pep517 doesn't accept arguments, the value argument
+    # will be None if --no-use-pep517 is passed via the command-line.
+    # However, the value can be non-None if the option is triggered e.g.
+    # by an environment variable, for example "PIP_NO_USE_PEP517=true".
+    if value is not None:
+        msg = """A value was passed for --no-use-pep517,
+        probably using either the PIP_NO_USE_PEP517 environment variable
+        or the "no-use-pep517" config file option. Use an appropriate value
+        of the PIP_USE_PEP517 environment variable or the "use-pep517"
+        config file option instead.
+        """
+        raise_option_error(parser, option=option, msg=msg)
+
+    # Otherwise, --no-use-pep517 was passed via the command-line.
+    parser.values.use_pep517 = False
+
+
+use_pep517: Any = partial(
+    Option,
+    "--use-pep517",
+    dest="use_pep517",
+    action="store_true",
+    default=None,
+    help="Use PEP 517 for building source distributions "
+    "(use --no-use-pep517 to force legacy behaviour).",
+)
+
+no_use_pep517: Any = partial(
+    Option,
+    "--no-use-pep517",
+    dest="use_pep517",
+    action="callback",
+    callback=_handle_no_use_pep517,
+    default=None,
+    help=SUPPRESS_HELP,
+)
+
+install_options: Callable[..., Option] = partial(
+    Option,
+    "--install-option",
+    dest="install_options",
+    action="append",
+    metavar="options",
+    help="Extra arguments to be supplied to the setup.py install "
+    'command (use like --install-option="--install-scripts=/usr/local/'
+    'bin"). Use multiple --install-option options to pass multiple '
+    "options to setup.py install. If you are using an option with a "
+    "directory path, be sure to use absolute path.",
+)
+
+build_options: Callable[..., Option] = partial(
+    Option,
+    "--build-option",
+    dest="build_options",
+    metavar="options",
+    action="append",
+    help="Extra arguments to be supplied to 'setup.py bdist_wheel'.",
+)
+
+global_options: Callable[..., Option] = partial(
+    Option,
+    "--global-option",
+    dest="global_options",
+    action="append",
+    metavar="options",
+    help="Extra global options to be supplied to the setup.py "
+    "call before the install or bdist_wheel command.",
+)
+
+no_clean: Callable[..., Option] = partial(
+    Option,
+    "--no-clean",
+    action="store_true",
+    default=False,
+    help="Don't clean up build directories.",
+)
+
+pre: Callable[..., Option] = partial(
+    Option,
+    "--pre",
+    action="store_true",
+    default=False,
+    help="Include pre-release and development versions. By default, "
+    "pip only finds stable versions.",
+)
+
+disable_pip_version_check: Callable[..., Option] = partial(
+    Option,
+    "--disable-pip-version-check",
+    dest="disable_pip_version_check",
+    action="store_true",
+    default=False,
+    help="Don't periodically check PyPI to determine whether a new version "
+    "of pip is available for download. Implied with --no-index.",
+)
+
+
+def _handle_merge_hash(
+    option: Option, opt_str: str, value: str, parser: OptionParser
+) -> None:
+    """Given a value spelled "algo:digest", append the digest to a list
+    pointed to in a dict by the algo name."""
+    if not parser.values.hashes:
+        parser.values.hashes = {}
+    try:
+        algo, digest = value.split(":", 1)
+    except ValueError:
+        parser.error(
+            "Arguments to {} must be a hash name "  # noqa
+            "followed by a value, like --hash=sha256:"
+            "abcde...".format(opt_str)
+        )
+    if algo not in STRONG_HASHES:
+        parser.error(
+            "Allowed hash algorithms for {} are {}.".format(  # noqa
+                opt_str, ", ".join(STRONG_HASHES)
+            )
+        )
+    parser.values.hashes.setdefault(algo, []).append(digest)
+
+
+hash: Callable[..., Option] = partial(
+    Option,
+    "--hash",
+    # Hash values eventually end up in InstallRequirement.hashes due to
+    # __dict__ copying in process_line().
+    dest="hashes",
+    action="callback",
+    callback=_handle_merge_hash,
+    type="string",
+    help="Verify that the package's archive matches this "
+    "hash before installing. Example: --hash=sha256:abcdef...",
+)
+
+
+require_hashes: Callable[..., Option] = partial(
+    Option,
+    "--require-hashes",
+    dest="require_hashes",
+    action="store_true",
+    default=False,
+    help="Require a hash to check each requirement against, for "
+    "repeatable installs. This option is implied when any package in a "
+    "requirements file has a --hash option.",
+)
+
+
+list_path: Callable[..., Option] = partial(
+    PipOption,
+    "--path",
+    dest="path",
+    type="path",
+    action="append",
+    help="Restrict to the specified installation path for listing "
+    "packages (can be used multiple times).",
+)
+
+
+def check_list_path_option(options: Values) -> None:
+    if options.path and (options.user or options.local):
+        raise CommandError("Cannot combine '--path' with '--user' or '--local'")
+
+
+list_exclude: Callable[..., Option] = partial(
+    PipOption,
+    "--exclude",
+    dest="excludes",
+    action="append",
+    metavar="package",
+    type="package_name",
+    help="Exclude specified package from the output",
+)
+
+
+no_python_version_warning: Callable[..., Option] = partial(
+    Option,
+    "--no-python-version-warning",
+    dest="no_python_version_warning",
+    action="store_true",
+    default=False,
+    help="Silence deprecation warnings for upcoming unsupported Pythons.",
+)
+
+
+use_new_feature: Callable[..., Option] = partial(
+    Option,
+    "--use-feature",
+    dest="features_enabled",
+    metavar="feature",
+    action="append",
+    default=[],
+    choices=["2020-resolver", "fast-deps", "in-tree-build"],
+    help="Enable new functionality, that may be backward incompatible.",
+)
+
+use_deprecated_feature: Callable[..., Option] = partial(
+    Option,
+    "--use-deprecated",
+    dest="deprecated_features_enabled",
+    metavar="feature",
+    action="append",
+    default=[],
+    choices=["legacy-resolver"],
+    help=("Enable deprecated functionality, that will be removed in the future."),
+)
+
+
+##########
+# groups #
+##########
+
+general_group: Dict[str, Any] = {
+    "name": "General Options",
+    "options": [
+        help_,
+        isolated_mode,
+        require_virtualenv,
+        verbose,
+        version,
+        quiet,
+        log,
+        no_input,
+        proxy,
+        retries,
+        timeout,
+        exists_action,
+        trusted_host,
+        cert,
+        client_cert,
+        cache_dir,
+        no_cache,
+        disable_pip_version_check,
+        no_color,
+        no_python_version_warning,
+        use_new_feature,
+        use_deprecated_feature,
+    ],
+}
+
+index_group: Dict[str, Any] = {
+    "name": "Package Index Options",
+    "options": [
+        index_url,
+        extra_index_url,
+        no_index,
+        find_links,
+    ],
+}

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/command_context.py

@@ -0,0 +1,27 @@
+from contextlib import ExitStack, contextmanager
+from typing import ContextManager, Iterator, TypeVar
+
+_T = TypeVar("_T", covariant=True)
+
+
+class CommandContextMixIn:
+    def __init__(self) -> None:
+        super().__init__()
+        self._in_main_context = False
+        self._main_context = ExitStack()
+
+    @contextmanager
+    def main_context(self) -> Iterator[None]:
+        assert not self._in_main_context
+
+        self._in_main_context = True
+        try:
+            with self._main_context:
+                yield
+        finally:
+            self._in_main_context = False
+
+    def enter_context(self, context_provider: ContextManager[_T]) -> _T:
+        assert self._in_main_context
+
+        return self._main_context.enter_context(context_provider)

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/main.py

@@ -0,0 +1,70 @@
+"""Primary application entrypoint.
+"""
+import locale
+import logging
+import os
+import sys
+from typing import List, Optional
+
+from pip._internal.cli.autocompletion import autocomplete
+from pip._internal.cli.main_parser import parse_command
+from pip._internal.commands import create_command
+from pip._internal.exceptions import PipError
+from pip._internal.utils import deprecation
+
+logger = logging.getLogger(__name__)
+
+
+# Do not import and use main() directly! Using it directly is actively
+# discouraged by pip's maintainers. The name, location and behavior of
+# this function is subject to change, so calling it directly is not
+# portable across different pip versions.
+
+# In addition, running pip in-process is unsupported and unsafe. This is
+# elaborated in detail at
+# https://pip.pypa.io/en/stable/user_guide/#using-pip-from-your-program.
+# That document also provides suggestions that should work for nearly
+# all users that are considering importing and using main() directly.
+
+# However, we know that certain users will still want to invoke pip
+# in-process. If you understand and accept the implications of using pip
+# in an unsupported manner, the best approach is to use runpy to avoid
+# depending on the exact location of this entry point.
+
+# The following example shows how to use runpy to invoke pip in that
+# case:
+#
+#     sys.argv = ["pip", your, args, here]
+#     runpy.run_module("pip", run_name="__main__")
+#
+# Note that this will exit the process after running, unlike a direct
+# call to main. As it is not safe to do any processing after calling
+# main, this should not be an issue in practice.
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    if args is None:
+        args = sys.argv[1:]
+
+    # Configure our deprecation warnings to be sent through loggers
+    deprecation.install_warning_logger()
+
+    autocomplete()
+
+    try:
+        cmd_name, cmd_args = parse_command(args)
+    except PipError as exc:
+        sys.stderr.write(f"ERROR: {exc}")
+        sys.stderr.write(os.linesep)
+        sys.exit(1)
+
+    # Needed for locale.getpreferredencoding(False) to work
+    # in pip._internal.utils.encoding.auto_decode
+    try:
+        locale.setlocale(locale.LC_ALL, "")
+    except locale.Error as e:
+        # setlocale can apparently crash if locale are uninitialized
+        logger.debug("Ignoring error %s when setting locale", e)
+    command = create_command(cmd_name, isolated=("--isolated" in cmd_args))
+
+    return command.main(cmd_args)

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/main_parser.py

@@ -0,0 +1,87 @@
+"""A single place for constructing and exposing the main parser
+"""
+
+import os
+import sys
+from typing import List, Tuple
+
+from pip._internal.cli import cmdoptions
+from pip._internal.cli.parser import ConfigOptionParser, UpdatingDefaultsHelpFormatter
+from pip._internal.commands import commands_dict, get_similar_commands
+from pip._internal.exceptions import CommandError
+from pip._internal.utils.misc import get_pip_version, get_prog
+
+__all__ = ["create_main_parser", "parse_command"]
+
+
+def create_main_parser() -> ConfigOptionParser:
+    """Creates and returns the main parser for pip's CLI"""
+
+    parser = ConfigOptionParser(
+        usage="\n%prog <command> [options]",
+        add_help_option=False,
+        formatter=UpdatingDefaultsHelpFormatter(),
+        name="global",
+        prog=get_prog(),
+    )
+    parser.disable_interspersed_args()
+
+    parser.version = get_pip_version()
+
+    # add the general options
+    gen_opts = cmdoptions.make_option_group(cmdoptions.general_group, parser)
+    parser.add_option_group(gen_opts)
+
+    # so the help formatter knows
+    parser.main = True  # type: ignore
+
+    # create command listing for description
+    description = [""] + [
+        f"{name:27} {command_info.summary}"
+        for name, command_info in commands_dict.items()
+    ]
+    parser.description = "\n".join(description)
+
+    return parser
+
+
+def parse_command(args: List[str]) -> Tuple[str, List[str]]:
+    parser = create_main_parser()
+
+    # Note: parser calls disable_interspersed_args(), so the result of this
+    # call is to split the initial args into the general options before the
+    # subcommand and everything else.
+    # For example:
+    #  args: ['--timeout=5', 'install', '--user', 'INITools']
+    #  general_options: ['--timeout==5']
+    #  args_else: ['install', '--user', 'INITools']
+    general_options, args_else = parser.parse_args(args)
+
+    # --version
+    if general_options.version:
+        sys.stdout.write(parser.version)
+        sys.stdout.write(os.linesep)
+        sys.exit()
+
+    # pip || pip help -> print_help()
+    if not args_else or (args_else[0] == "help" and len(args_else) == 1):
+        parser.print_help()
+        sys.exit()
+
+    # the subcommand name
+    cmd_name = args_else[0]
+
+    if cmd_name not in commands_dict:
+        guess = get_similar_commands(cmd_name)
+
+        msg = [f'unknown command "{cmd_name}"']
+        if guess:
+            msg.append(f'maybe you meant "{guess}"')
+
+        raise CommandError(" - ".join(msg))
+
+    # all the args without the subcommand
+    cmd_args = args[:]
+    cmd_args.remove(cmd_name)
+
+    return cmd_name, cmd_args

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/parser.py

@@ -0,0 +1,292 @@
+"""Base option parser setup"""
+
+import logging
+import optparse
+import shutil
+import sys
+import textwrap
+from contextlib import suppress
+from typing import Any, Dict, Iterator, List, Tuple
+
+from pip._internal.cli.status_codes import UNKNOWN_ERROR
+from pip._internal.configuration import Configuration, ConfigurationError
+from pip._internal.utils.misc import redact_auth_from_url, strtobool
+
+logger = logging.getLogger(__name__)
+
+
+class PrettyHelpFormatter(optparse.IndentedHelpFormatter):
+    """A prettier/less verbose help formatter for optparse."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # help position must be aligned with __init__.parseopts.description
+        kwargs["max_help_position"] = 30
+        kwargs["indent_increment"] = 1
+        kwargs["width"] = shutil.get_terminal_size()[0] - 2
+        super().__init__(*args, **kwargs)
+
+    def format_option_strings(self, option: optparse.Option) -> str:
+        return self._format_option_strings(option)
+
+    def _format_option_strings(
+        self, option: optparse.Option, mvarfmt: str = " <{}>", optsep: str = ", "
+    ) -> str:
+        """
+        Return a comma-separated list of option strings and metavars.
+
+        :param option:  tuple of (short opt, long opt), e.g: ('-f', '--format')
+        :param mvarfmt: metavar format string
+        :param optsep:  separator
+        """
+        opts = []
+
+        if option._short_opts:
+            opts.append(option._short_opts[0])
+        if option._long_opts:
+            opts.append(option._long_opts[0])
+        if len(opts) > 1:
+            opts.insert(1, optsep)
+
+        if option.takes_value():
+            assert option.dest is not None
+            metavar = option.metavar or option.dest.lower()
+            opts.append(mvarfmt.format(metavar.lower()))
+
+        return "".join(opts)
+
+    def format_heading(self, heading: str) -> str:
+        if heading == "Options":
+            return ""
+        return heading + ":\n"
+
+    def format_usage(self, usage: str) -> str:
+        """
+        Ensure there is only one newline between usage and the first heading
+        if there is no description.
+        """
+        msg = "\nUsage: {}\n".format(self.indent_lines(textwrap.dedent(usage), "  "))
+        return msg
+
+    def format_description(self, description: str) -> str:
+        # leave full control over description to us
+        if description:
+            if hasattr(self.parser, "main"):
+                label = "Commands"
+            else:
+                label = "Description"
+            # some doc strings have initial newlines, some don't
+            description = description.lstrip("\n")
+            # some doc strings have final newlines and spaces, some don't
+            description = description.rstrip()
+            # dedent, then reindent
+            description = self.indent_lines(textwrap.dedent(description), "  ")
+            description = f"{label}:\n{description}\n"
+            return description
+        else:
+            return ""
+
+    def format_epilog(self, epilog: str) -> str:
+        # leave full control over epilog to us
+        if epilog:
+            return epilog
+        else:
+            return ""
+
+    def indent_lines(self, text: str, indent: str) -> str:
+        new_lines = [indent + line for line in text.split("\n")]
+        return "\n".join(new_lines)
+
+
+class UpdatingDefaultsHelpFormatter(PrettyHelpFormatter):
+    """Custom help formatter for use in ConfigOptionParser.
+
+    This is updates the defaults before expanding them, allowing
+    them to show up correctly in the help listing.
+
+    Also redact auth from url type options
+    """
+
+    def expand_default(self, option: optparse.Option) -> str:
+        default_values = None
+        if self.parser is not None:
+            assert isinstance(self.parser, ConfigOptionParser)
+            self.parser._update_defaults(self.parser.defaults)
+            assert option.dest is not None
+            default_values = self.parser.defaults.get(option.dest)
+        help_text = super().expand_default(option)
+
+        if default_values and option.metavar == "URL":
+            if isinstance(default_values, str):
+                default_values = [default_values]
+
+            # If its not a list, we should abort and just return the help text
+            if not isinstance(default_values, list):
+                default_values = []
+
+            for val in default_values:
+                help_text = help_text.replace(val, redact_auth_from_url(val))
+
+        return help_text
+
+
+class CustomOptionParser(optparse.OptionParser):
+    def insert_option_group(
+        self, idx: int, *args: Any, **kwargs: Any
+    ) -> optparse.OptionGroup:
+        """Insert an OptionGroup at a given position."""
+        group = self.add_option_group(*args, **kwargs)
+
+        self.option_groups.pop()
+        self.option_groups.insert(idx, group)
+
+        return group
+
+    @property
+    def option_list_all(self) -> List[optparse.Option]:
+        """Get a list of all options, including those in option groups."""
+        res = self.option_list[:]
+        for i in self.option_groups:
+            res.extend(i.option_list)
+
+        return res
+
+
+class ConfigOptionParser(CustomOptionParser):
+    """Custom option parser which updates its defaults by checking the
+    configuration files and environmental variables"""
+
+    def __init__(
+        self,
+        *args: Any,
+        name: str,
+        isolated: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        self.name = name
+        self.config = Configuration(isolated)
+
+        assert self.name
+        super().__init__(*args, **kwargs)
+
+    def check_default(self, option: optparse.Option, key: str, val: Any) -> Any:
+        try:
+            return option.check_value(key, val)
+        except optparse.OptionValueError as exc:
+            print(f"An error occurred during configuration: {exc}")
+            sys.exit(3)
+
+    def _get_ordered_configuration_items(self) -> Iterator[Tuple[str, Any]]:
+        # Configuration gives keys in an unordered manner. Order them.
+        override_order = ["global", self.name, ":env:"]
+
+        # Pool the options into different groups
+        section_items: Dict[str, List[Tuple[str, Any]]] = {
+            name: [] for name in override_order
+        }
+        for section_key, val in self.config.items():
+            # ignore empty values
+            if not val:
+                logger.debug(
+                    "Ignoring configuration key '%s' as it's value is empty.",
+                    section_key,
+                )
+                continue
+
+            section, key = section_key.split(".", 1)
+            if section in override_order:
+                section_items[section].append((key, val))
+
+        # Yield each group in their override order
+        for section in override_order:
+            for key, val in section_items[section]:
+                yield key, val
+
+    def _update_defaults(self, defaults: Dict[str, Any]) -> Dict[str, Any]:
+        """Updates the given defaults with values from the config files and
+        the environ. Does a little special handling for certain types of
+        options (lists)."""
+
+        # Accumulate complex default state.
+        self.values = optparse.Values(self.defaults)
+        late_eval = set()
+        # Then set the options with those values
+        for key, val in self._get_ordered_configuration_items():
+            # '--' because configuration supports only long names
+            option = self.get_option("--" + key)
+
+            # Ignore options not present in this parser. E.g. non-globals put
+            # in [global] by users that want them to apply to all applicable
+            # commands.
+            if option is None:
+                continue
+
+            assert option.dest is not None
+
+            if option.action in ("store_true", "store_false"):
+                try:
+                    val = strtobool(val)
+                except ValueError:
+                    self.error(
+                        "{} is not a valid value for {} option, "  # noqa
+                        "please specify a boolean value like yes/no, "
+                        "true/false or 1/0 instead.".format(val, key)
+                    )
+            elif option.action == "count":
+                with suppress(ValueError):
+                    val = strtobool(val)
+                with suppress(ValueError):
+                    val = int(val)
+                if not isinstance(val, int) or val < 0:
+                    self.error(
+                        "{} is not a valid value for {} option, "  # noqa
+                        "please instead specify either a non-negative integer "
+                        "or a boolean value like yes/no or false/true "
+                        "which is equivalent to 1/0.".format(val, key)
+                    )
+            elif option.action == "append":
+                val = val.split()
+                val = [self.check_default(option, key, v) for v in val]
+            elif option.action == "callback":
+                assert option.callback is not None
+                late_eval.add(option.dest)
+                opt_str = option.get_opt_string()
+                val = option.convert_value(opt_str, val)
+                # From take_action
+                args = option.callback_args or ()
+                kwargs = option.callback_kwargs or {}
+                option.callback(option, opt_str, val, self, *args, **kwargs)
+            else:
+                val = self.check_default(option, key, val)
+
+            defaults[option.dest] = val
+
+        for key in late_eval:
+            defaults[key] = getattr(self.values, key)
+        self.values = None
+        return defaults
+
+    def get_default_values(self) -> optparse.Values:
+        """Overriding to make updating the defaults after instantiation of
+        the option parser possible, _update_defaults() does the dirty work."""
+        if not self.process_default_values:
+            # Old, pre-Optik 1.5 behaviour.
+            return optparse.Values(self.defaults)
+
+        # Load the configuration, or error out in case of an error
+        try:
+            self.config.load()
+        except ConfigurationError as err:
+            self.exit(UNKNOWN_ERROR, str(err))
+
+        defaults = self._update_defaults(self.defaults.copy())  # ours
+        for option in self._get_all_options():
+            assert option.dest is not None
+            default = defaults.get(option.dest)
+            if isinstance(default, str):
+                opt_str = option.get_opt_string()
+                defaults[option.dest] = option.check_value(opt_str, default)
+        return optparse.Values(defaults)
+
+    def error(self, msg: str) -> None:
+        self.print_usage(sys.stderr)
+        self.exit(UNKNOWN_ERROR, f"{msg}\n")

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/progress_bars.py

@@ -0,0 +1,250 @@
+import itertools
+import sys
+from signal import SIGINT, default_int_handler, signal
+from typing import Any
+
+from pip._vendor.progress.bar import Bar, FillingCirclesBar, IncrementalBar
+from pip._vendor.progress.spinner import Spinner
+
+from pip._internal.utils.compat import WINDOWS
+from pip._internal.utils.logging import get_indentation
+from pip._internal.utils.misc import format_size
+
+try:
+    from pip._vendor import colorama
+# Lots of different errors can come from this, including SystemError and
+# ImportError.
+except Exception:
+    colorama = None
+
+
+def _select_progress_class(preferred: Bar, fallback: Bar) -> Bar:
+    encoding = getattr(preferred.file, "encoding", None)
+
+    # If we don't know what encoding this file is in, then we'll just assume
+    # that it doesn't support unicode and use the ASCII bar.
+    if not encoding:
+        return fallback
+
+    # Collect all of the possible characters we want to use with the preferred
+    # bar.
+    characters = [
+        getattr(preferred, "empty_fill", ""),
+        getattr(preferred, "fill", ""),
+    ]
+    characters += list(getattr(preferred, "phases", []))
+
+    # Try to decode the characters we're using for the bar using the encoding
+    # of the given file, if this works then we'll assume that we can use the
+    # fancier bar and if not we'll fall back to the plaintext bar.
+    try:
+        "".join(characters).encode(encoding)
+    except UnicodeEncodeError:
+        return fallback
+    else:
+        return preferred
+
+
+_BaseBar: Any = _select_progress_class(IncrementalBar, Bar)
+
+
+class InterruptibleMixin:
+    """
+    Helper to ensure that self.finish() gets called on keyboard interrupt.
+
+    This allows downloads to be interrupted without leaving temporary state
+    (like hidden cursors) behind.
+
+    This class is similar to the progress library's existing SigIntMixin
+    helper, but as of version 1.2, that helper has the following problems:
+
+    1. It calls sys.exit().
+    2. It discards the existing SIGINT handler completely.
+    3. It leaves its own handler in place even after an uninterrupted finish,
+       which will have unexpected delayed effects if the user triggers an
+       unrelated keyboard interrupt some time after a progress-displaying
+       download has already completed, for example.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Save the original SIGINT handler for later.
+        """
+        # https://github.com/python/mypy/issues/5887
+        super().__init__(*args, **kwargs)  # type: ignore
+
+        self.original_handler = signal(SIGINT, self.handle_sigint)
+
+        # If signal() returns None, the previous handler was not installed from
+        # Python, and we cannot restore it. This probably should not happen,
+        # but if it does, we must restore something sensible instead, at least.
+        # The least bad option should be Python's default SIGINT handler, which
+        # just raises KeyboardInterrupt.
+        if self.original_handler is None:
+            self.original_handler = default_int_handler
+
+    def finish(self) -> None:
+        """
+        Restore the original SIGINT handler after finishing.
+
+        This should happen regardless of whether the progress display finishes
+        normally, or gets interrupted.
+        """
+        super().finish()  # type: ignore
+        signal(SIGINT, self.original_handler)
+
+    def handle_sigint(self, signum, frame):  # type: ignore
+        """
+        Call self.finish() before delegating to the original SIGINT handler.
+
+        This handler should only be in place while the progress display is
+        active.
+        """
+        self.finish()
+        self.original_handler(signum, frame)
+
+
+class SilentBar(Bar):
+    def update(self) -> None:
+        pass
+
+
+class BlueEmojiBar(IncrementalBar):
+
+    suffix = "%(percent)d%%"
+    bar_prefix = " "
+    bar_suffix = " "
+    phases = ("\U0001F539", "\U0001F537", "\U0001F535")
+
+
+class DownloadProgressMixin:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # https://github.com/python/mypy/issues/5887
+        super().__init__(*args, **kwargs)  # type: ignore
+        self.message: str = (" " * (get_indentation() + 2)) + self.message
+
+    @property
+    def downloaded(self) -> str:
+        return format_size(self.index)  # type: ignore
+
+    @property
+    def download_speed(self) -> str:
+        # Avoid zero division errors...
+        if self.avg == 0.0:  # type: ignore
+            return "..."
+        return format_size(1 / self.avg) + "/s"  # type: ignore
+
+    @property
+    def pretty_eta(self) -> str:
+        if self.eta:  # type: ignore
+            return f"eta {self.eta_td}"  # type: ignore
+        return ""
+
+    def iter(self, it):  # type: ignore
+        for x in it:
+            yield x
+            # B305 is incorrectly raised here
+            # https://github.com/PyCQA/flake8-bugbear/issues/59
+            self.next(len(x))  # noqa: B305
+        self.finish()
+
+
+class WindowsMixin:
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        # The Windows terminal does not support the hide/show cursor ANSI codes
+        # even with colorama. So we'll ensure that hide_cursor is False on
+        # Windows.
+        # This call needs to go before the super() call, so that hide_cursor
+        # is set in time. The base progress bar class writes the "hide cursor"
+        # code to the terminal in its init, so if we don't set this soon
+        # enough, we get a "hide" with no corresponding "show"...
+        if WINDOWS and self.hide_cursor:  # type: ignore
+            self.hide_cursor = False
+
+        # https://github.com/python/mypy/issues/5887
+        super().__init__(*args, **kwargs)  # type: ignore
+
+        # Check if we are running on Windows and we have the colorama module,
+        # if we do then wrap our file with it.
+        if WINDOWS and colorama:
+            self.file = colorama.AnsiToWin32(self.file)  # type: ignore
+            # The progress code expects to be able to call self.file.isatty()
+            # but the colorama.AnsiToWin32() object doesn't have that, so we'll
+            # add it.
+            self.file.isatty = lambda: self.file.wrapped.isatty()
+            # The progress code expects to be able to call self.file.flush()
+            # but the colorama.AnsiToWin32() object doesn't have that, so we'll
+            # add it.
+            self.file.flush = lambda: self.file.wrapped.flush()
+
+
+class BaseDownloadProgressBar(WindowsMixin, InterruptibleMixin, DownloadProgressMixin):
+
+    file = sys.stdout
+    message = "%(percent)d%%"
+    suffix = "%(downloaded)s %(download_speed)s %(pretty_eta)s"
+
+
+class DefaultDownloadProgressBar(BaseDownloadProgressBar, _BaseBar):
+    pass
+
+
+class DownloadSilentBar(BaseDownloadProgressBar, SilentBar):
+    pass
+
+
+class DownloadBar(BaseDownloadProgressBar, Bar):
+    pass
+
+
+class DownloadFillingCirclesBar(BaseDownloadProgressBar, FillingCirclesBar):
+    pass
+
+
+class DownloadBlueEmojiProgressBar(BaseDownloadProgressBar, BlueEmojiBar):
+    pass
+
+
+class DownloadProgressSpinner(
+    WindowsMixin, InterruptibleMixin, DownloadProgressMixin, Spinner
+):
+
+    file = sys.stdout
+    suffix = "%(downloaded)s %(download_speed)s"
+
+    def next_phase(self) -> str:
+        if not hasattr(self, "_phaser"):
+            self._phaser = itertools.cycle(self.phases)
+        return next(self._phaser)
+
+    def update(self) -> None:
+        message = self.message % self
+        phase = self.next_phase()
+        suffix = self.suffix % self
+        line = "".join(
+            [
+                message,
+                " " if message else "",
+                phase,
+                " " if suffix else "",
+                suffix,
+            ]
+        )
+
+        self.writeln(line)
+
+
+BAR_TYPES = {
+    "off": (DownloadSilentBar, DownloadSilentBar),
+    "on": (DefaultDownloadProgressBar, DownloadProgressSpinner),
+    "ascii": (DownloadBar, DownloadProgressSpinner),
+    "pretty": (DownloadFillingCirclesBar, DownloadProgressSpinner),
+    "emoji": (DownloadBlueEmojiProgressBar, DownloadProgressSpinner),
+}
+
+
+def DownloadProgressProvider(progress_bar, max=None):  # type: ignore
+    if max is None or max == 0:
+        return BAR_TYPES[progress_bar][1]().iter
+    else:
+        return BAR_TYPES[progress_bar][0](max=max).iter

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/req_command.py

@@ -0,0 +1,453 @@
+"""Contains the Command base classes that depend on PipSession.
+
+The classes in this module are in a separate module so the commands not
+needing download / PackageFinder capability don't unnecessarily import the
+PackageFinder machinery and all its vendored dependencies, etc.
+"""
+
+import logging
+import os
+import sys
+from functools import partial
+from optparse import Values
+from typing import Any, List, Optional, Tuple
+
+from pip._internal.cache import WheelCache
+from pip._internal.cli import cmdoptions
+from pip._internal.cli.base_command import Command
+from pip._internal.cli.command_context import CommandContextMixIn
+from pip._internal.exceptions import CommandError, PreviousBuildDirError
+from pip._internal.index.collector import LinkCollector
+from pip._internal.index.package_finder import PackageFinder
+from pip._internal.models.selection_prefs import SelectionPreferences
+from pip._internal.models.target_python import TargetPython
+from pip._internal.network.session import PipSession
+from pip._internal.operations.prepare import RequirementPreparer
+from pip._internal.req.constructors import (
+    install_req_from_editable,
+    install_req_from_line,
+    install_req_from_parsed_requirement,
+    install_req_from_req_string,
+)
+from pip._internal.req.req_file import parse_requirements
+from pip._internal.req.req_install import InstallRequirement
+from pip._internal.req.req_tracker import RequirementTracker
+from pip._internal.resolution.base import BaseResolver
+from pip._internal.self_outdated_check import pip_self_version_check
+from pip._internal.utils.temp_dir import (
+    TempDirectory,
+    TempDirectoryTypeRegistry,
+    tempdir_kinds,
+)
+from pip._internal.utils.virtualenv import running_under_virtualenv
+
+logger = logging.getLogger(__name__)
+
+
+class SessionCommandMixin(CommandContextMixIn):
+
+    """
+    A class mixin for command classes needing _build_session().
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._session: Optional[PipSession] = None
+
+    @classmethod
+    def _get_index_urls(cls, options: Values) -> Optional[List[str]]:
+        """Return a list of index urls from user-provided options."""
+        index_urls = []
+        if not getattr(options, "no_index", False):
+            url = getattr(options, "index_url", None)
+            if url:
+                index_urls.append(url)
+        urls = getattr(options, "extra_index_urls", None)
+        if urls:
+            index_urls.extend(urls)
+        # Return None rather than an empty list
+        return index_urls or None
+
+    def get_default_session(self, options: Values) -> PipSession:
+        """Get a default-managed session."""
+        if self._session is None:
+            self._session = self.enter_context(self._build_session(options))
+            # there's no type annotation on requests.Session, so it's
+            # automatically ContextManager[Any] and self._session becomes Any,
+            # then https://github.com/python/mypy/issues/7696 kicks in
+            assert self._session is not None
+        return self._session
+
+    def _build_session(
+        self,
+        options: Values,
+        retries: Optional[int] = None,
+        timeout: Optional[int] = None,
+    ) -> PipSession:
+        assert not options.cache_dir or os.path.isabs(options.cache_dir)
+        session = PipSession(
+            cache=(
+                os.path.join(options.cache_dir, "http") if options.cache_dir else None
+            ),
+            retries=retries if retries is not None else options.retries,
+            trusted_hosts=options.trusted_hosts,
+            index_urls=self._get_index_urls(options),
+        )
+
+        # Handle custom ca-bundles from the user
+        if options.cert:
+            session.verify = options.cert
+
+        # Handle SSL client certificate
+        if options.client_cert:
+            session.cert = options.client_cert
+
+        # Handle timeouts
+        if options.timeout or timeout:
+            session.timeout = timeout if timeout is not None else options.timeout
+
+        # Handle configured proxies
+        if options.proxy:
+            session.proxies = {
+                "http": options.proxy,
+                "https": options.proxy,
+            }
+
+        # Determine if we can prompt the user for authentication or not
+        session.auth.prompting = not options.no_input
+
+        return session
+
+
+class IndexGroupCommand(Command, SessionCommandMixin):
+
+    """
+    Abstract base class for commands with the index_group options.
+
+    This also corresponds to the commands that permit the pip version check.
+    """
+
+    def handle_pip_version_check(self, options: Values) -> None:
+        """
+        Do the pip version check if not disabled.
+
+        This overrides the default behavior of not doing the check.
+        """
+        # Make sure the index_group options are present.
+        assert hasattr(options, "no_index")
+
+        if options.disable_pip_version_check or options.no_index:
+            return
+
+        # Otherwise, check if we're using the latest version of pip available.
+        session = self._build_session(
+            options, retries=0, timeout=min(5, options.timeout)
+        )
+        with session:
+            pip_self_version_check(session, options)
+
+
+KEEPABLE_TEMPDIR_TYPES = [
+    tempdir_kinds.BUILD_ENV,
+    tempdir_kinds.EPHEM_WHEEL_CACHE,
+    tempdir_kinds.REQ_BUILD,
+]
+
+
+def warn_if_run_as_root() -> None:
+    """Output a warning for sudo users on Unix.
+
+    In a virtual environment, sudo pip still writes to virtualenv.
+    On Windows, users may run pip as Administrator without issues.
+    This warning only applies to Unix root users outside of virtualenv.
+    """
+    if running_under_virtualenv():
+        return
+    if not hasattr(os, "getuid"):
+        return
+    # On Windows, there are no "system managed" Python packages. Installing as
+    # Administrator via pip is the correct way of updating system environments.
+    #
+    # We choose sys.platform over utils.compat.WINDOWS here to enable Mypy platform
+    # checks: https://mypy.readthedocs.io/en/stable/common_issues.html
+    if sys.platform == "win32" or sys.platform == "cygwin":
+        return
+    if sys.platform == "darwin" or sys.platform == "linux":
+        if os.getuid() != 0:
+            return
+    logger.warning(
+        "Running pip as the 'root' user can result in broken permissions and "
+        "conflicting behaviour with the system package manager. "
+        "It is recommended to use a virtual environment instead: "
+        "https://pip.pypa.io/warnings/venv"
+    )
+
+
+def with_cleanup(func: Any) -> Any:
+    """Decorator for common logic related to managing temporary
+    directories.
+    """
+
+    def configure_tempdir_registry(registry: TempDirectoryTypeRegistry) -> None:
+        for t in KEEPABLE_TEMPDIR_TYPES:
+            registry.set_delete(t, False)
+
+    def wrapper(
+        self: RequirementCommand, options: Values, args: List[Any]
+    ) -> Optional[int]:
+        assert self.tempdir_registry is not None
+        if options.no_clean:
+            configure_tempdir_registry(self.tempdir_registry)
+
+        try:
+            return func(self, options, args)
+        except PreviousBuildDirError:
+            # This kind of conflict can occur when the user passes an explicit
+            # build directory with a pre-existing folder. In that case we do
+            # not want to accidentally remove it.
+            configure_tempdir_registry(self.tempdir_registry)
+            raise
+
+    return wrapper
+
+
+class RequirementCommand(IndexGroupCommand):
+    def __init__(self, *args: Any, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+
+        self.cmd_opts.add_option(cmdoptions.no_clean())
+
+    @staticmethod
+    def determine_resolver_variant(options: Values) -> str:
+        """Determines which resolver should be used, based on the given options."""
+        if "legacy-resolver" in options.deprecated_features_enabled:
+            return "legacy"
+
+        return "2020-resolver"
+
+    @classmethod
+    def make_requirement_preparer(
+        cls,
+        temp_build_dir: TempDirectory,
+        options: Values,
+        req_tracker: RequirementTracker,
+        session: PipSession,
+        finder: PackageFinder,
+        use_user_site: bool,
+        download_dir: Optional[str] = None,
+    ) -> RequirementPreparer:
+        """
+        Create a RequirementPreparer instance for the given parameters.
+        """
+        temp_build_dir_path = temp_build_dir.path
+        assert temp_build_dir_path is not None
+
+        resolver_variant = cls.determine_resolver_variant(options)
+        if resolver_variant == "2020-resolver":
+            lazy_wheel = "fast-deps" in options.features_enabled
+            if lazy_wheel:
+                logger.warning(
+                    "pip is using lazily downloaded wheels using HTTP "
+                    "range requests to obtain dependency information. "
+                    "This experimental feature is enabled through "
+                    "--use-feature=fast-deps and it is not ready for "
+                    "production."
+                )
+        else:
+            lazy_wheel = False
+            if "fast-deps" in options.features_enabled:
+                logger.warning(
+                    "fast-deps has no effect when used with the legacy resolver."
+                )
+
+        return RequirementPreparer(
+            build_dir=temp_build_dir_path,
+            src_dir=options.src_dir,
+            download_dir=download_dir,
+            build_isolation=options.build_isolation,
+            req_tracker=req_tracker,
+            session=session,
+            progress_bar=options.progress_bar,
+            finder=finder,
+            require_hashes=options.require_hashes,
+            use_user_site=use_user_site,
+            lazy_wheel=lazy_wheel,
+            in_tree_build="in-tree-build" in options.features_enabled,
+        )
+
+    @classmethod
+    def make_resolver(
+        cls,
+        preparer: RequirementPreparer,
+        finder: PackageFinder,
+        options: Values,
+        wheel_cache: Optional[WheelCache] = None,
+        use_user_site: bool = False,
+        ignore_installed: bool = True,
+        ignore_requires_python: bool = False,
+        force_reinstall: bool = False,
+        upgrade_strategy: str = "to-satisfy-only",
+        use_pep517: Optional[bool] = None,
+        py_version_info: Optional[Tuple[int, ...]] = None,
+    ) -> BaseResolver:
+        """
+        Create a Resolver instance for the given parameters.
+        """
+        make_install_req = partial(
+            install_req_from_req_string,
+            isolated=options.isolated_mode,
+            use_pep517=use_pep517,
+        )
+        resolver_variant = cls.determine_resolver_variant(options)
+        # The long import name and duplicated invocation is needed to convince
+        # Mypy into correctly typechecking. Otherwise it would complain the
+        # "Resolver" class being redefined.
+        if resolver_variant == "2020-resolver":
+            import pip._internal.resolution.resolvelib.resolver
+
+            return pip._internal.resolution.resolvelib.resolver.Resolver(
+                preparer=preparer,
+                finder=finder,
+                wheel_cache=wheel_cache,
+                make_install_req=make_install_req,
+                use_user_site=use_user_site,
+                ignore_dependencies=options.ignore_dependencies,
+                ignore_installed=ignore_installed,
+                ignore_requires_python=ignore_requires_python,
+                force_reinstall=force_reinstall,
+                upgrade_strategy=upgrade_strategy,
+                py_version_info=py_version_info,
+            )
+        import pip._internal.resolution.legacy.resolver
+
+        return pip._internal.resolution.legacy.resolver.Resolver(
+            preparer=preparer,
+            finder=finder,
+            wheel_cache=wheel_cache,
+            make_install_req=make_install_req,
+            use_user_site=use_user_site,
+            ignore_dependencies=options.ignore_dependencies,
+            ignore_installed=ignore_installed,
+            ignore_requires_python=ignore_requires_python,
+            force_reinstall=force_reinstall,
+            upgrade_strategy=upgrade_strategy,
+            py_version_info=py_version_info,
+        )
+
+    def get_requirements(
+        self,
+        args: List[str],
+        options: Values,
+        finder: PackageFinder,
+        session: PipSession,
+    ) -> List[InstallRequirement]:
+        """
+        Parse command-line arguments into the corresponding requirements.
+        """
+        requirements: List[InstallRequirement] = []
+        for filename in options.constraints:
+            for parsed_req in parse_requirements(
+                filename,
+                constraint=True,
+                finder=finder,
+                options=options,
+                session=session,
+            ):
+                req_to_add = install_req_from_parsed_requirement(
+                    parsed_req,
+                    isolated=options.isolated_mode,
+                    user_supplied=False,
+                )
+                requirements.append(req_to_add)
+
+        for req in args:
+            req_to_add = install_req_from_line(
+                req,
+                None,
+                isolated=options.isolated_mode,
+                use_pep517=options.use_pep517,
+                user_supplied=True,
+            )
+            requirements.append(req_to_add)
+
+        for req in options.editables:
+            req_to_add = install_req_from_editable(
+                req,
+                user_supplied=True,
+                isolated=options.isolated_mode,
+                use_pep517=options.use_pep517,
+            )
+            requirements.append(req_to_add)
+
+        # NOTE: options.require_hashes may be set if --require-hashes is True
+        for filename in options.requirements:
+            for parsed_req in parse_requirements(
+                filename, finder=finder, options=options, session=session
+            ):
+                req_to_add = install_req_from_parsed_requirement(
+                    parsed_req,
+                    isolated=options.isolated_mode,
+                    use_pep517=options.use_pep517,
+                    user_supplied=True,
+                )
+                requirements.append(req_to_add)
+
+        # If any requirement has hash options, enable hash checking.
+        if any(req.has_hash_options for req in requirements):
+            options.require_hashes = True
+
+        if not (args or options.editables or options.requirements):
+            opts = {"name": self.name}
+            if options.find_links:
+                raise CommandError(
+                    "You must give at least one requirement to {name} "
+                    '(maybe you meant "pip {name} {links}"?)'.format(
+                        **dict(opts, links=" ".join(options.find_links))
+                    )
+                )
+            else:
+                raise CommandError(
+                    "You must give at least one requirement to {name} "
+                    '(see "pip help {name}")'.format(**opts)
+                )
+
+        return requirements
+
+    @staticmethod
+    def trace_basic_info(finder: PackageFinder) -> None:
+        """
+        Trace basic information about the provided objects.
+        """
+        # Display where finder is looking for packages
+        search_scope = finder.search_scope
+        locations = search_scope.get_formatted_locations()
+        if locations:
+            logger.info(locations)
+
+    def _build_package_finder(
+        self,
+        options: Values,
+        session: PipSession,
+        target_python: Optional[TargetPython] = None,
+        ignore_requires_python: Optional[bool] = None,
+    ) -> PackageFinder:
+        """
+        Create a package finder appropriate to this requirement command.
+
+        :param ignore_requires_python: Whether to ignore incompatible
+            "Requires-Python" values in links. Defaults to False.
+        """
+        link_collector = LinkCollector.create(session, options=options)
+        selection_prefs = SelectionPreferences(
+            allow_yanked=True,
+            format_control=options.format_control,
+            allow_all_prereleases=options.pre,
+            prefer_binary=options.prefer_binary,
+            ignore_requires_python=ignore_requires_python,
+        )
+
+        return PackageFinder.create(
+            link_collector=link_collector,
+            selection_prefs=selection_prefs,
+            target_python=target_python,
+        )

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/spinners.py

@@ -0,0 +1,157 @@
+import contextlib
+import itertools
+import logging
+import sys
+import time
+from typing import IO, Iterator
+
+from pip._vendor.progress import HIDE_CURSOR, SHOW_CURSOR
+
+from pip._internal.utils.compat import WINDOWS
+from pip._internal.utils.logging import get_indentation
+
+logger = logging.getLogger(__name__)
+
+
+class SpinnerInterface:
+    def spin(self) -> None:
+        raise NotImplementedError()
+
+    def finish(self, final_status: str) -> None:
+        raise NotImplementedError()
+
+
+class InteractiveSpinner(SpinnerInterface):
+    def __init__(
+        self,
+        message: str,
+        file: IO[str] = None,
+        spin_chars: str = "-\\|/",
+        # Empirically, 8 updates/second looks nice
+        min_update_interval_seconds: float = 0.125,
+    ):
+        self._message = message
+        if file is None:
+            file = sys.stdout
+        self._file = file
+        self._rate_limiter = RateLimiter(min_update_interval_seconds)
+        self._finished = False
+
+        self._spin_cycle = itertools.cycle(spin_chars)
+
+        self._file.write(" " * get_indentation() + self._message + " ... ")
+        self._width = 0
+
+    def _write(self, status: str) -> None:
+        assert not self._finished
+        # Erase what we wrote before by backspacing to the beginning, writing
+        # spaces to overwrite the old text, and then backspacing again
+        backup = "\b" * self._width
+        self._file.write(backup + " " * self._width + backup)
+        # Now we have a blank slate to add our status
+        self._file.write(status)
+        self._width = len(status)
+        self._file.flush()
+        self._rate_limiter.reset()
+
+    def spin(self) -> None:
+        if self._finished:
+            return
+        if not self._rate_limiter.ready():
+            return
+        self._write(next(self._spin_cycle))
+
+    def finish(self, final_status: str) -> None:
+        if self._finished:
+            return
+        self._write(final_status)
+        self._file.write("\n")
+        self._file.flush()
+        self._finished = True
+
+
+# Used for dumb terminals, non-interactive installs (no tty), etc.
+# We still print updates occasionally (once every 60 seconds by default) to
+# act as a keep-alive for systems like Travis-CI that take lack-of-output as
+# an indication that a task has frozen.
+class NonInteractiveSpinner(SpinnerInterface):
+    def __init__(self, message: str, min_update_interval_seconds: float = 60.0) -> None:
+        self._message = message
+        self._finished = False
+        self._rate_limiter = RateLimiter(min_update_interval_seconds)
+        self._update("started")
+
+    def _update(self, status: str) -> None:
+        assert not self._finished
+        self._rate_limiter.reset()
+        logger.info("%s: %s", self._message, status)
+
+    def spin(self) -> None:
+        if self._finished:
+            return
+        if not self._rate_limiter.ready():
+            return
+        self._update("still running...")
+
+    def finish(self, final_status: str) -> None:
+        if self._finished:
+            return
+        self._update(f"finished with status '{final_status}'")
+        self._finished = True
+
+
+class RateLimiter:
+    def __init__(self, min_update_interval_seconds: float) -> None:
+        self._min_update_interval_seconds = min_update_interval_seconds
+        self._last_update: float = 0
+
+    def ready(self) -> bool:
+        now = time.time()
+        delta = now - self._last_update
+        return delta >= self._min_update_interval_seconds
+
+    def reset(self) -> None:
+        self._last_update = time.time()
+
+
+@contextlib.contextmanager
+def open_spinner(message: str) -> Iterator[SpinnerInterface]:
+    # Interactive spinner goes directly to sys.stdout rather than being routed
+    # through the logging system, but it acts like it has level INFO,
+    # i.e. it's only displayed if we're at level INFO or better.
+    # Non-interactive spinner goes through the logging system, so it is always
+    # in sync with logging configuration.
+    if sys.stdout.isatty() and logger.getEffectiveLevel() <= logging.INFO:
+        spinner: SpinnerInterface = InteractiveSpinner(message)
+    else:
+        spinner = NonInteractiveSpinner(message)
+    try:
+        with hidden_cursor(sys.stdout):
+            yield spinner
+    except KeyboardInterrupt:
+        spinner.finish("canceled")
+        raise
+    except Exception:
+        spinner.finish("error")
+        raise
+    else:
+        spinner.finish("done")
+
+
+@contextlib.contextmanager
+def hidden_cursor(file: IO[str]) -> Iterator[None]:
+    # The Windows terminal does not support the hide/show cursor ANSI codes,
+    # even via colorama. So don't even try.
+    if WINDOWS:
+        yield
+    # We don't want to clutter the output with control characters if we're
+    # writing to a file, or if the user is running with --quiet.
+    # See https://github.com/pypa/pip/issues/3418
+    elif not file.isatty() or logger.getEffectiveLevel() > logging.INFO:
+        yield
+    else:
+        file.write(HIDE_CURSOR)
+        try:
+            yield
+        finally:
+            file.write(SHOW_CURSOR)

animated_drawings/lib/python3.9/site-packages/pip/_internal/cli/status_codes.py

@@ -0,0 +1,6 @@
+SUCCESS = 0
+ERROR = 1
+UNKNOWN_ERROR = 2
+VIRTUALENV_NOT_FOUND = 3
+PREVIOUS_BUILD_DIR_ERROR = 4
+NO_MATCHES_FOUND = 23

animated_drawings/lib/python3.9/site-packages/pip/_internal/commands/__init__.py

@@ -0,0 +1,112 @@
+"""
+Package containing all pip commands
+"""
+
+import importlib
+from collections import OrderedDict, namedtuple
+from typing import Any, Dict, Optional
+
+from pip._internal.cli.base_command import Command
+
+CommandInfo = namedtuple('CommandInfo', 'module_path, class_name, summary')
+
+# The ordering matters for help display.
+#    Also, even though the module path starts with the same
+# "pip._internal.commands" prefix in each case, we include the full path
+# because it makes testing easier (specifically when modifying commands_dict
+# in test setup / teardown by adding info for a FakeCommand class defined
+# in a test-related module).
+#    Finally, we need to pass an iterable of pairs here rather than a dict
+# so that the ordering won't be lost when using Python 2.7.
+commands_dict: Dict[str, CommandInfo] = OrderedDict([
+    ('install', CommandInfo(
+        'pip._internal.commands.install', 'InstallCommand',
+        'Install packages.',
+    )),
+    ('download', CommandInfo(
+        'pip._internal.commands.download', 'DownloadCommand',
+        'Download packages.',
+    )),
+    ('uninstall', CommandInfo(
+        'pip._internal.commands.uninstall', 'UninstallCommand',
+        'Uninstall packages.',
+    )),
+    ('freeze', CommandInfo(
+        'pip._internal.commands.freeze', 'FreezeCommand',
+        'Output installed packages in requirements format.',
+    )),
+    ('list', CommandInfo(
+        'pip._internal.commands.list', 'ListCommand',
+        'List installed packages.',
+    )),
+    ('show', CommandInfo(
+        'pip._internal.commands.show', 'ShowCommand',
+        'Show information about installed packages.',
+    )),
+    ('check', CommandInfo(
+        'pip._internal.commands.check', 'CheckCommand',
+        'Verify installed packages have compatible dependencies.',
+    )),
+    ('config', CommandInfo(
+        'pip._internal.commands.configuration', 'ConfigurationCommand',
+        'Manage local and global configuration.',
+    )),
+    ('search', CommandInfo(
+        'pip._internal.commands.search', 'SearchCommand',
+        'Search PyPI for packages.',
+    )),
+    ('cache', CommandInfo(
+        'pip._internal.commands.cache', 'CacheCommand',
+        "Inspect and manage pip's wheel cache.",
+    )),
+    ('index', CommandInfo(
+        'pip._internal.commands.index', 'IndexCommand',
+        "Inspect information available from package indexes.",
+    )),
+    ('wheel', CommandInfo(
+        'pip._internal.commands.wheel', 'WheelCommand',
+        'Build wheels from your requirements.',
+    )),
+    ('hash', CommandInfo(
+        'pip._internal.commands.hash', 'HashCommand',
+        'Compute hashes of package archives.',
+    )),
+    ('completion', CommandInfo(
+        'pip._internal.commands.completion', 'CompletionCommand',
+        'A helper command used for command completion.',
+    )),
+    ('debug', CommandInfo(
+        'pip._internal.commands.debug', 'DebugCommand',
+        'Show information useful for debugging.',
+    )),
+    ('help', CommandInfo(
+        'pip._internal.commands.help', 'HelpCommand',
+        'Show help for commands.',
+    )),
+])
+
+
+def create_command(name: str, **kwargs: Any) -> Command:
+    """
+    Create an instance of the Command class with the given name.
+    """
+    module_path, class_name, summary = commands_dict[name]
+    module = importlib.import_module(module_path)
+    command_class = getattr(module, class_name)
+    command = command_class(name=name, summary=summary, **kwargs)
+
+    return command
+
+
+def get_similar_commands(name: str) -> Optional[str]:
+    """Command name auto-correct."""
+    from difflib import get_close_matches
+
+    name = name.lower()
+
+    close_commands = get_close_matches(name, commands_dict.keys())
+
+    if close_commands:
+        return close_commands[0]
+    else:
+        return None

animated_drawings/lib/python3.9/site-packages/pip/_internal/commands/cache.py

@@ -0,0 +1,216 @@
+import os
+import textwrap
+from optparse import Values
+from typing import Any, List
+
+import pip._internal.utils.filesystem as filesystem
+from pip._internal.cli.base_command import Command
+from pip._internal.cli.status_codes import ERROR, SUCCESS
+from pip._internal.exceptions import CommandError, PipError
+from pip._internal.utils.logging import getLogger
+
+logger = getLogger(__name__)
+
+
+class CacheCommand(Command):
+    """
+    Inspect and manage pip's wheel cache.
+
+    Subcommands:
+
+    - dir: Show the cache directory.
+    - info: Show information about the cache.
+    - list: List filenames of packages stored in the cache.
+    - remove: Remove one or more package from the cache.
+    - purge: Remove all items from the cache.
+
+    ``<pattern>`` can be a glob expression or a package name.
+    """
+
+    ignore_require_venv = True
+    usage = """
+        %prog dir
+        %prog info
+        %prog list [<pattern>] [--format=[human, abspath]]
+        %prog remove <pattern>
+        %prog purge
+    """
+
+    def add_options(self) -> None:
+
+        self.cmd_opts.add_option(
+            '--format',
+            action='store',
+            dest='list_format',
+            default="human",
+            choices=('human', 'abspath'),
+            help="Select the output format among: human (default) or abspath"
+        )
+
+        self.parser.insert_option_group(0, self.cmd_opts)
+
+    def run(self, options: Values, args: List[Any]) -> int:
+        handlers = {
+            "dir": self.get_cache_dir,
+            "info": self.get_cache_info,
+            "list": self.list_cache_items,
+            "remove": self.remove_cache_items,
+            "purge": self.purge_cache,
+        }
+
+        if not options.cache_dir:
+            logger.error("pip cache commands can not "
+                         "function since cache is disabled.")
+            return ERROR
+
+        # Determine action
+        if not args or args[0] not in handlers:
+            logger.error(
+                "Need an action (%s) to perform.",
+                ", ".join(sorted(handlers)),
+            )
+            return ERROR
+
+        action = args[0]
+
+        # Error handling happens here, not in the action-handlers.
+        try:
+            handlers[action](options, args[1:])
+        except PipError as e:
+            logger.error(e.args[0])
+            return ERROR
+
+        return SUCCESS
+
+    def get_cache_dir(self, options: Values, args: List[Any]) -> None:
+        if args:
+            raise CommandError('Too many arguments')
+
+        logger.info(options.cache_dir)
+
+    def get_cache_info(self, options: Values, args: List[Any]) -> None:
+        if args:
+            raise CommandError('Too many arguments')
+
+        num_http_files = len(self._find_http_files(options))
+        num_packages = len(self._find_wheels(options, '*'))
+
+        http_cache_location = self._cache_dir(options, 'http')
+        wheels_cache_location = self._cache_dir(options, 'wheels')
+        http_cache_size = filesystem.format_directory_size(http_cache_location)
+        wheels_cache_size = filesystem.format_directory_size(
+            wheels_cache_location
+        )
+
+        message = textwrap.dedent("""
+            Package index page cache location: {http_cache_location}
+            Package index page cache size: {http_cache_size}
+            Number of HTTP files: {num_http_files}
+            Wheels location: {wheels_cache_location}
+            Wheels size: {wheels_cache_size}
+            Number of wheels: {package_count}
+        """).format(
+            http_cache_location=http_cache_location,
+            http_cache_size=http_cache_size,
+            num_http_files=num_http_files,
+            wheels_cache_location=wheels_cache_location,
+            package_count=num_packages,
+            wheels_cache_size=wheels_cache_size,
+        ).strip()
+
+        logger.info(message)
+
+    def list_cache_items(self, options: Values, args: List[Any]) -> None:
+        if len(args) > 1:
+            raise CommandError('Too many arguments')
+
+        if args:
+            pattern = args[0]
+        else:
+            pattern = '*'
+
+        files = self._find_wheels(options, pattern)
+        if options.list_format == 'human':
+            self.format_for_human(files)
+        else:
+            self.format_for_abspath(files)
+
+    def format_for_human(self, files: List[str]) -> None:
+        if not files:
+            logger.info('Nothing cached.')
+            return
+
+        results = []
+        for filename in files:
+            wheel = os.path.basename(filename)
+            size = filesystem.format_file_size(filename)
+            results.append(f' - {wheel} ({size})')
+        logger.info('Cache contents:\n')
+        logger.info('\n'.join(sorted(results)))
+
+    def format_for_abspath(self, files: List[str]) -> None:
+        if not files:
+            return
+
+        results = []
+        for filename in files:
+            results.append(filename)
+
+        logger.info('\n'.join(sorted(results)))
+
+    def remove_cache_items(self, options: Values, args: List[Any]) -> None:
+        if len(args) > 1:
+            raise CommandError('Too many arguments')
+
+        if not args:
+            raise CommandError('Please provide a pattern')
+
+        files = self._find_wheels(options, args[0])
+
+        # Only fetch http files if no specific pattern given
+        if args[0] == '*':
+            files += self._find_http_files(options)
+
+        if not files:
+            raise CommandError('No matching packages')
+
+        for filename in files:
+            os.unlink(filename)
+            logger.verbose("Removed %s", filename)
+        logger.info("Files removed: %s", len(files))
+
+    def purge_cache(self, options: Values, args: List[Any]) -> None:
+        if args:
+            raise CommandError('Too many arguments')
+
+        return self.remove_cache_items(options, ['*'])
+
+    def _cache_dir(self, options: Values, subdir: str) -> str:
+        return os.path.join(options.cache_dir, subdir)
+
+    def _find_http_files(self, options: Values) -> List[str]:
+        http_dir = self._cache_dir(options, 'http')
+        return filesystem.find_files(http_dir, '*')
+
+    def _find_wheels(self, options: Values, pattern: str) -> List[str]:
+        wheel_dir = self._cache_dir(options, 'wheels')
+
+        # The wheel filename format, as specified in PEP 427, is:
+        #     {distribution}-{version}(-{build})?-{python}-{abi}-{platform}.whl
+        #
+        # Additionally, non-alphanumeric values in the distribution are
+        # normalized to underscores (_), meaning hyphens can never occur
+        # before `-{version}`.
+        #
+        # Given that information:
+        # - If the pattern we're given contains a hyphen (-), the user is
+        #   providing at least the version. Thus, we can just append `*.whl`
+        #   to match the rest of it.
+        # - If the pattern we're given doesn't contain a hyphen (-), the
+        #   user is only providing the name. Thus, we append `-*.whl` to
+        #   match the hyphen before the version, followed by anything else.
+        #
+        # PEP 427: https://www.python.org/dev/peps/pep-0427/
+        pattern = pattern + ("*.whl" if "-" in pattern else "-*.whl")
+
+        return filesystem.find_files(wheel_dir, pattern)

animated_drawings/lib/python3.9/site-packages/pip/_internal/commands/check.py

@@ -0,0 +1,47 @@
+import logging
+from optparse import Values
+from typing import Any, List
+
+from pip._internal.cli.base_command import Command
+from pip._internal.cli.status_codes import ERROR, SUCCESS
+from pip._internal.operations.check import (
+    check_package_set,
+    create_package_set_from_installed,
+)
+from pip._internal.utils.misc import write_output
+
+logger = logging.getLogger(__name__)
+
+
+class CheckCommand(Command):
+    """Verify installed packages have compatible dependencies."""
+
+    usage = """
+      %prog [options]"""
+
+    def run(self, options: Values, args: List[Any]) -> int:
+
+        package_set, parsing_probs = create_package_set_from_installed()
+        missing, conflicting = check_package_set(package_set)
+
+        for project_name in missing:
+            version = package_set[project_name].version
+            for dependency in missing[project_name]:
+                write_output(
+                    "%s %s requires %s, which is not installed.",
+                    project_name, version, dependency[0],
+                )
+
+        for project_name in conflicting:
+            version = package_set[project_name].version
+            for dep_name, dep_version, req in conflicting[project_name]:
+                write_output(
+                    "%s %s has requirement %s, but you have %s %s.",
+                    project_name, version, req, dep_name, dep_version,
+                )
+
+        if missing or conflicting or parsing_probs:
+            return ERROR
+        else:
+            write_output("No broken requirements found.")
+            return SUCCESS