Development Notes

Environment Setup

Installation:

Upgrade pip:

which python3
#/opt/homebrew/Cellar/python@3.11/3.11.5/bin/python3
#anaconda3/bin/python 3.10
#/usr/bin/python3 3.9.6
which python
#python not found
#in you case could be opposite due to the fact that Windows Store reserved python3 name in PATH
python3 -m pip install --upgrade pip 

Basic requirements for project:

pip3 install pygame
pip3 install psutil
pip3 install tk 

#TODO add requirements.txt

Requirements:

Tested on:

• Python 3.9.6 - works but UI feels not good
• Python 3.10 - works
• Python 3.10 - works
• pygame==2.5.2
• psutil==5.9.0
• tk==8.6.12

python3 -m pip install --upgrade pip
python3 -m pip install pygame
python3 -m pip install psutil
python3 -m pip install tk 

but versions could be different.

TODO: check minimal versions

• black==23.7.0
• flake8==7.0.0
• mccabe==0.7.0
• mypy==1.5.1
• mypy-extensions==1.0.0
• pre-commit==3.6.2
• pyflakes==3.2.0
• ruff==0.0.284
• toml==0.10.2
• types-psutil==5.9.5.20240205
• typing_extensions==4.4.0
• virtualenv==20.25.0
• vulture==2.8

Development:

Tools:

• pylint
• flake8
• mypy
• vulture
• black
• pre-commit
• pylance

Get all tools required for developent:

Resolving for linting and code navigation:

pip install -r requirements.txt 

Type/symbol resolving for linting and code navigation:

python3 -m pip install types-psutil
mypy --install-types 

Linters:

pip3 install flake8
pip3 install mypy
pip3 install vulture
python3 -m pip install -U pydocstyle 

Install Pylance in VSCode for additional help.

Manual Linting:

Run mypy:

mypy DiskClick.pyw
# or just run mypy in project DiskClick/ 

Run Vulture:

vulture DiskClick.pyw 

Run flake8 with specific line length:

flake8 --max-line-length=150 DiskClick.pyw 

Formatter Installation:

pip3 install black 

Manual Formatting:

Run Black with line length 150:

black -l 150 DiskClick.pyw 

Automatic Linting with Pre-Commit:

pip3 install pre-commit
pre-commit install
pre-commit clean
pre-commit autoupdate
pre-commit run --all-files
pre-commit run --all-files --verbose 

Running the Program:

python3 DiskClick.pyw ./DiskClick.pyw 

Check untyped definitions with mypy:

mypy --check-untyped-defs DiskClick.pyw 

Run the program:

python3 DiskClick.pyw 

Code Quality Guidelines

Please let's try to make this and other tools greater (...again 8P) by following the guidelines below:

• Be consistent: We try to follow the same code style as the rest of the project.
• Be explicit: We try to make the code as explicit as possible.
• Be simple: We try to make the code as simple as possible.
• Be pragmatic: We try to make the code as pragmatic as possible.
• Be fast: We try to make the code as fast as possible.
• Be safe: We try to make the code as safe as possible.
• Be smart: We try to make the code as smart as possible.
• Be beautiful: We try to make the code as beautiful as possible.
• Be powerful: We try to make... at least we try to...

Static Type Checker: mypy

mypy is not a linter in the traditional sense; it is a static type checker for Python. It checks the type correctness of Python code when type hints are used.

mypy Standards:

tl;dr

• PEP 484: Introduced type hints to Python.
• PEP 526: Syntax for variable annotations.
• PEP 544: Protocols and structural subtyping.
• PEP 561: Distributing and packaging type information.
• PEP 563: Postponed evaluation of type annotations.
• PEP 585: Type hinting generics in standard collections.
• PEP 586: Literal types.
• PEP 589: TypedDict.
• PEP 591: Adding a final qualifier to type annotations.
• PEP 593: Flexible function and variable annotations.
• PEP 604: Union types as X | Y.
• PEP 612: Parameter Specification Variables.

but:

• PEP 484: The original proposal that introduced type hints to Python, which includes the syntax for type annotations, the concept of type comments, and the stub files with .pyi extension.
• PEP 526: Syntax for variable annotations, which expanded type hints to variable declarations.
• PEP 544: Protocols and structural subtyping, which introduced a way to define class-like structures that can be used as types.
• PEP 561: Distributing and packaging type information, which specifies how to include type information in Python packages.
• PEP 563: Postponed evaluation of type annotations, which changes how annotations are stored in Python, making them strings by default.
• PEP 585: Type hinting generics in standard collections, which allows for the use of standard collection types (list, dict, etc.) as generic types.
• PEP 586: Literal types, which allows for specifying exact values that some variables are allowed to take.
• PEP 589: TypedDict, which specifies dictionaries with a fixed set of keys, each associated with a specific type.
• PEP 591: Adding a final qualifier to type annotations, which allows marking classes and methods as final (meaning they cannot be subclassed or overridden, respectively).
• PEP 593: Flexible function and variable annotations, which introduces a way to extend the type information provided through annotations.
• PEP 604: Allow writing union types as X | Y, which simplifies the syntax for specifying types that can be one of multiple options.
• PEP 612: Parameter Specification Variables, which allows the specification of the types of parameters for callable objects. mypy checks that the type annotations provided in the code are consistent with these standards and will highlight any discrepancies or errors it finds. It's important to note that while mypy can be used to catch many types of errors, it's not a replacement for traditional linting tools like flake8 or pylint, which check for stylistic issues, code complexity, and potential errors that are not related to type checking. These tools can be used in conjunction with mypy to maintain code quality. mypy ensures type annotations are consistent with these standards and highlights discrepancies.

Linter: flake8

flake8 is a command-line utility for enforcing style consistency across Python projects.

Tools flake8 Wraps Around:

tl;dr

• PyFlakes: Checks for errors in code.
• pycodestyle: Checks for PEP 8 stylistic issues.
• McCabe: Checks code complexity.

flake8 can be extended with plugins for additional checks or behavior modifications.

Standards flake8 Addresses:

• PEP 8: The main style guide for Python code.
• PEP 257: Docstring conventions.
• PEP 20: The Zen of Python.
• PEP 484: Type hints syntax correctness.

flake8 is commonly used with mypy for code quality and type consistency.

full:

• PyFlakes: Checks for various errors in Python code, such as misspelled variable names, unused imports, undefined variables, and more.
• pycodestyle (formerly known as pep8): Checks for stylistic issues that are in violation of PEP 8, which is the style guide for Python code.
• McCabe: Checks the complexity of your code, specifically the Cyclomatic complexity, which is a quantitative measure of the number of linearly independent paths through a program's source code.

flake8 can be extended with various plugins to add additional checks or modify its behavior. These plugins can check for things like type hinting compliance (though not with the same depth as mypy), specific framework-related issues, security concerns, and more.

The standards flake8 checks against are mostly derived from PEP 8, which is the accepted style guide for Python code. PEP 8 covers things like indentation, whitespace, line length, imports ordering, comments, naming conventions, and much more.

Here are some of the PEP standards that flake8, through its underlying tools, typically addresses:

• PEP 8: The main style guide for Python code, which flake8 uses as a reference for most of its style-related checks.
• PEP 257: Docstring conventions, which flake8 can check for with the help of plugins like flake8-docstrings.
• PEP 20: The Zen of Python, which includes principles that good Python code should adhere to. While not enforceable through linting, it provides a philosophical backdrop to other PEPs.
• PEP 484: Type hints, which flake8 can partially check for syntax correctness with the help of plugins like flake8-mypy or flake8-pyi.

It's common for Python projects to use flake8 in conjunction with mypy to ensure both code quality (style, complexity, common errors) and type consistency.

Code Cleanup Tool: Vulture

tl;dr Vulture finds unused code, helping clean up codebases by detecting:

• Unused functions
• Unused variables
• Unused classes
• Unused methods
• Unused attributes
• Unused arguments

Vulture uses static analysis, so there may be false positives due to Python's dynamic nature. Verification by developers is necessary after Vulture's report.

full: Vulture is a Python tool that finds unused code in Python projects. It helps developers clean up their codebases by detecting unused and potentially dead code, such as:

• Unused functions
• Unused variables
• Unused classes
• Unused methods
• Unused attributes
• Unused arguments

Vulture works by statically analyzing the code without actually running it. It makes an educated guess about which parts of the code are unused. However, because Python is a dynamic language and Vulture uses static analysis, there is a possibility of false positives. This means that it might identify code as unused when, in fact, it is used indirectly or dynamically (e.g., via getattr() or through deserialization of objects).

Vulture's checks are not based on a specific PEP but rather on the general idea of cleaning up code by removing unused elements. It is considered good practice to remove code that is no longer used because it can lead to confusion, increase maintenance effort, and potentially hide bugs.

After Vulture identifies unused code, it's up to the developer to verify whether the code is truly unused and can be safely removed. Developers often need to cross-check Vulture's report with their test suite, version control history, and by performing a manual code review to ensure that removing the suggested parts of the code won't affect the program's functionality.

Vulture can be integrated into continuous integration pipelines to help maintain code quality over time. It can also be used in combination with other code quality tools such as flake8, mypy, and pylint to provide a more comprehensive approach to improving and maintaining the health of a codebase.