✏️🎚️✅ PyTypeGauge

PyTypeGauge is a Python library that provides comprehensive statistics and metrics for your typed functions and Python code. The primary goal is to encourage developers to achieve 100% type coverage in their codebases.

⚠️ Note: PyTypeGauge is a simple tool designed to encourage better type annotation in your Python code. It does not validate the correctness of the types you add. The concept is straightforward: it recursively scans all Python files in a repository, using regular expressions to identify function prototypes and check whether their arguments and return types are annotated. PyTypeGauge then calculates the proportion of fully typed functions and arguments, providing a summary of your type coverage. Additionally, you can generate a comprehensive report in markdown format, highlighting functions and files that may need refactoring or additional type annotations.

PyTypeGauge is intended to be used with pre-commit hooks and can update your README.md with your project's type coverage progress.

Example Output (current type coverage)

For more advanced type checking and validation, consider using other well-maintained libraries such as mypy or pyright.

🧩 Features

• Analyze the type coverage of your Python functions.
• Generate detailed reports on the use of type hints.
• Track the progress of type hint adoption in your codebase.

📥 Installation

To install PyTypeGauge, run:

pip install pytypegauge

How to Use typegauge

typegauge is a command-line tool designed to analyze the type annotations in your Python code. You can specify a directory or a Python file, and the tool will evaluate the type coverage of your code. Below is a guide on how to use typegauge and the various options available.

Basic Usage

To analyze a specific directory or Python file, simply run:

typegauge <input>

Replace <input> with the path to the directory or Python file you want to analyze.

⚙️ Options

• -h, --help: Show the help message and exit.

  typegauge -h
  

• -g, --git: Analyze only files tracked by git. This is useful if you want to exclude untracked or ignored files.

  typegauge -g <input>
  

• -p, --plot-output: Display a graph showing the distribution of typing coverage in your code.

  typegauge -p <input>
  

• -csv CSV_OUTPUT, --csv-output CSV_OUTPUT: Save the results to a CSV file. Provide the desired CSV file name.

  typegauge -csv results.csv <input>
  

• -md, --markdown-output: Output the results in a markdown format suitable for inclusion in a README.md on GitHub. This is useful for creating progress badges or reports in your repository.

  typegauge -md <input>
  

• -c, --clean-output: Only return the percentage of typed arguments, which is useful for scripts and continuous integration setups.

  typegauge -c <input>
  

• -f, --full-report: Generate a full report listing all functions that are not fully typed. This can help you identify areas in your code that need improvement.

  typegauge -f <input>
  

By using these options, you can tailor the output of typegauge to suit your needs, whether you want a quick summary, a detailed report, or integration with other tools.

🪝 Hooks

Pytypegauge can be used as a pre-commit hook. To do this, add the following configuration to your .pre-commit-config.yaml file:

-   repo: https://github.com/White-On/pytypegauge
    rev: [version]
    hooks:
    -   id: pytypegauge

The hooks will get all the python files in the repository and check the type coverage of the functions in the files. If there is a README.md file in the repository, the hook will update the file with the type coverage of the repository in a markdown format. you can place a [!typo_progress] and the hook will replace it with the type coverage of the repository.

Note:

• The hook will not update the README.md file if the file is not in the repository.
• The hook will not update the README.md file if the file does not contain the [!typo_progress] tag.
• The hook will take all python files, there is no method for now to exclude some files from the hook.

TODO:

• Add hooks for pre-commit
• Add a description of the project
• Add a list of the project's dependencies in setup.py
• Fix bugs in the project
• Add a Logger to the project for Debugging
• Type correctly the project
• Add the feature with matplotlib
• Translate the code in English
• Add the feature with pandas
• add tests for the project
• Clean the code
• Add to pypi
• Make the readme more informative
• Create the hooks to use this project as a template
• Add the feature to generate a badge
• Add the feature to generate a markdown file
• Add verbose mode
• Clean code and arguments setup