| Name | typecoverage JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | https://github.com/kairos-xx/typecoverage |
| Summary | A strict CLI + library API to report untyped variables, arguments, and function returns in Python code |
| upload_time | 2025-08-18 05:36:11 |
| maintainer | Joao Lopes |
| docs_url | None |
| author | Joao Lopes |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2024 Joao Lopes
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.
|
| keywords |
type-checking
static-analysis
type-annotations
code-quality
python-typing
ast-analysis
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
pytest
pytest
replit
black
flake8
build
requests
pyright
toml
pyyaml
isort
pyproject-flake8
zipfile38
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center">
<img src="https://i.postimg.cc/hPbkJZzB/icon-raster.png" alt="Typecoverage Logo" width="350"/>
<h1>🔍 Typecoverage - Python Type Annotation Analyzer</h1>
<p><em>A strict CLI + library API to report untyped variables, arguments, and function returns in Python code</em></p>
<p>
<img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+">
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
<img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code Style: Black">
</p>
</div>
## 🎯 What is Typecoverage?
Typecoverage is a comprehensive Python static analysis tool that identifies missing type annotations in your codebase. Unlike other type checkers that focus on type correctness, Typecoverage specifically targets **type annotation coverage** - ensuring your code has complete type hints for maintainability and clarity.
### ✨ Key Features
- 🔍 **Comprehensive Detection** - Finds missing annotations in functions, methods, variables, and returns
- 🎯 **Multiple Input Types** - Analyze files, directories, code strings, live Python objects, and more
- 📊 **Rich Output Formats** - Human-readable text with colors or machine-readable JSON
- ⚙️ **Flexible Filtering** - Smart defaults with configurable rules for different coding patterns
- 🚫 **Comment Suppression** - Standard `# type: ignore` and `# noqa` support
- 🚀 **High Performance** - Parallel processing for large codebases
- 🛠️ **CI/CD Ready** - Exit codes and JSON output for continuous integration
- 📝 **Detailed Context** - Source code snippets around issues for easy fixing
### 🚀 Quick Example
```python
from typecoverage import detect_untyped
# Analyze code string
code = """
def calculate_total(items, tax_rate):
subtotal = sum(item.price for item in items)
return subtotal * (1 + tax_rate)
"""
result = detect_untyped(code, statistics=True)
print(result)
```
**Output:**
```
Found 3 type annotation issues
📁 <string>
<string>:2:20 - Missing type annotation for argument "items"
1 │
► 2 │ def calculate_total(items, tax_rate):
3 │ subtotal = sum(item.price for item in items)
<string>:2:27 - Missing type annotation for argument "tax_rate"
1 │
► 2 │ def calculate_total(items, tax_rate):
3 │ subtotal = sum(item.price for item in items)
<string>:2:1 - Missing return type annotation "calculate_total"
1 │
► 2 │ def calculate_total(items, tax_rate):
3 │ subtotal = sum(item.price for item in items)
📊 Summary
Total issues: 3
🔴 Missing argument types: 2
🟡 Missing return types: 1
```
## 📦 Installation
### From Source (Current)
```bash
git clone <repository-url>
cd typecoverage-project
pip install -r requirements.txt
```
### Using the Package
```bash
# Install in development mode
pip install -e .
# Or install directly
python setup.py install
```
## 🏁 Quick Start
### Command Line Usage
```bash
# Using the module
python -m typecoverage myfile.py
# Using the installed command
typecoverage myfile.py
# Analyze entire project with statistics
typecoverage --recursive --statistics src/
# JSON output for CI/CD
typecoverage --format json --exit-nonzero-on-issues src/ > report.json
# Include context lines for easier fixing
typecoverage --context-lines 3 src/main.py
```
### Python API Usage
```python
from typecoverage import TypeCoverage, detect_untyped
# Simple analysis
result = detect_untyped("def func(x): return x", statistics=True)
print(result)
# Advanced analysis
checker = TypeCoverage()
issues, errors = checker.analyze_targets(
"src/",
recursive=True,
context_lines=2,
exclude=["__pycache__", "tests"],
)
stats = checker.compute_stats(issues)
print(f"Found {stats.total} issues across {len(set(i.file for i in issues))} files")
```
## 🎯 Supported Input Types
Typecoverage can analyze various types of targets:
| Input Type | Example | Description |
|------------|---------|-------------|
| **Files** | `main.py` | Individual Python files |
| **Directories** | `src/` | Directory trees (with `--recursive`) |
| **Glob Patterns** | `**/*.py` | Wildcard file matching |
| **Code Strings** | `"def func(x): pass"` | Direct Python code |
| **Live Functions** | `my_function` | Runtime function objects |
| **Classes** | `MyClass` | Class objects |
| **Modules** | `import mymodule; mymodule` | Module objects |
| **Paths** | `Path("src/main.py")` | pathlib.Path objects |
## ⚙️ Configuration
### Command Line Options
```bash
# Analysis options
--recursive # Recurse into subdirectories
--context-lines N # Show N lines of context around issues
--statistics # Include summary statistics
# Output options
--format json # JSON output instead of text
--output FILE # Write to file instead of stdout
--force-color # Force ANSI colors even when piped
# File filtering
--extensions .py,.pyx # File extensions to analyze
--exclude tests,docs # Exclude paths containing substrings
# Variable filtering (default: ignore these)
--no-ignore-underscore-vars # Include _private variables
--no-ignore-for-targets # Include for loop variables
--no-ignore-except-vars # Include exception variables
--no-ignore-context-vars # Include with statement variables
--no-ignore-comprehensions # Include list/dict comprehension vars
# Exit behavior
--exit-nonzero-on-issues # Exit 1 if any issues found
--fail-under N # Exit 1 if >= N issues found
```
### Configuration File
Create `pyproject.toml` configuration:
```toml
[tool.typecoverage]
recursive = true
statistics = true
context-lines = 2
exclude = ["tests", "__pycache__", "build"]
ignore-underscore-vars = true
exit-nonzero-on-issues = true
fail-under = 50
```
## 🚫 Issue Suppression
Use standard Python suppression comments:
```python
# Suppress all issues on this line
def my_function(x, y): # type: ignore
return x + y
# Suppress specific issue types
def another_function(x, y): # noqa: ANN001,ANN201
return x + y
# Suppress on previous line
# type: ignore
def third_function(x, y):
return x + y
```
**Supported patterns:**
- `# type: ignore` - Suppress all type checking issues
- `# type: ignore[code]` - Suppress specific error codes
- `# noqa` / `# noqa: code` - Flake8-style suppression
- `# mypy: ignore` / `# pyright: ignore` - Tool-specific suppression
## 📊 Understanding the Output
### Text Format
```
Found 5 type annotation issues
📁 src/calculator.py
src/calculator.py:15:8 - Missing type annotation for argument "value"
14 │ def process_value(self, value, multiplier=1):
► 15 │ result = value * multiplier
16 │ return result
📊 Summary
Total issues: 5
🔴 Missing argument types: 3
🟡 Missing return types: 1
🔵 Missing variable types: 1
```
### JSON Format
```json
{
"version": "0.1.8",
"issues": [
{
"file": "src/calculator.py",
"line": 15,
"column": 8,
"type": "untyped-argument",
"name": "value",
"context": [" def process_value(self, value, multiplier=1):", " result = value * multiplier"]
}
],
"statistics": {
"total": 5,
"untyped-argument": 3,
"untyped-return": 1,
"untyped-variable": 1
}
}
```
## 🔧 Advanced Usage
### Analyzing Live Objects
```python
from typecoverage import TypeCoverage
def my_function(x, y):
return x + y
class MyClass:
def method(self, value):
return value * 2
checker = TypeCoverage()
# Analyze function
issues, _ = checker.analyze_object(my_function, context_lines=1)
print(f"Function issues: {len(issues)}")
# Analyze class
issues, _ = checker.analyze_object(MyClass, context_lines=1)
print(f"Class issues: {len(issues)}")
```
### Batch Analysis
```python
from pathlib import Path
from typecoverage import analyze_targets
# Analyze multiple targets
issues, errors = analyze_targets(
"src/main.py", # Specific file
Path("lib/"), # Directory path
"utils/**/*.py", # Glob pattern
my_function, # Live object
recursive=True,
exclude=["test_", "__pycache__"],
context_lines=1,
)
print(f"Total issues: {len(issues)}")
print(f"Errors: {len(errors)}")
```
## 🏗️ CI/CD Integration
### GitHub Actions
```yaml
name: Type Annotation Coverage
on: [push, pull_request]
jobs:
typecoverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install dependencies
run: pip install -r requirements.txt
- name: Run typecoverage
run: |
typecoverage \
--format json \
--exit-nonzero-on-issues \
--recursive \
--output typecoverage-report.json \
src/
- name: Upload results
uses: actions/upload-artifact@v3
if: always()
with:
name: typecoverage-report
path: typecoverage-report.json
```
### Pre-commit Hook
```yaml
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: typecoverage
name: typecoverage
entry: typecoverage
language: system
args: [--exit-nonzero-on-issues, --recursive, src/]
files: \.py$
```
## 📚 Examples and Demos
### Basic Usage Demo
```bash
python demos/basic_usage.py
```
### Advanced Features Demo
```bash
python demos/advanced_usage.py
```
### CLI Examples
```bash
python demos/cli_examples.py
```
### Test the Library
```bash
# Run comprehensive test suite
pytest tests/ -v --cov=typecoverage --cov-report=term-missing
# Test specific functionality
pytest tests/test_core.py::TestTypeCoverage -v
```
## 🏗️ Project Structure
```
├── typecoverage/
│ ├── __init__.py # Public API exports
│ ├── __main__.py # CLI entry point
│ └── core.py # Main typecoverage implementation
├── src/
│ └── core.py # Development version
├── tests/
│ ├── test_core.py # Comprehensive test suite
│ └── test_suppressions.py # Suppression functionality tests
├── demos/
│ ├── basic_usage.py # Basic usage examples
│ ├── advanced_usage.py # Advanced features demo
│ └── cli_examples.py # CLI usage examples
├── docs/
│ └── wiki/ # Comprehensive documentation
│ ├── Home.md # Wiki home page
│ ├── Quick-Start.md # Getting started guide
│ ├── API-Reference.md# Complete API docs
│ └── CLI-Guide.md # Command-line reference
├── scripts/ # Development utilities
├── logs/ # Analysis logs
├── setup.py # Package setup
├── pyproject.toml # Project configuration
└── README.md # This file
```
## 🤝 Contributing
We welcome contributions! Here's how to get started:
1. **Fork the repository** and clone your fork
2. **Install development dependencies**: `pip install -r requirements.txt`
3. **Run tests**: `pytest tests/ -v`
4. **Check code style**: `ruff check . && black . --check`
5. **Make your changes** and add tests
6. **Run the full test suite**: `pytest tests/ --cov=typecoverage`
7. **Submit a pull request** with a clear description
### Development Workflow
```bash
# Set up development environment
pip install -r requirements.txt
# Run code formatting
black . --line-length 79
isort . -l 79 -m 1
ruff format . --line-length 79
# Run linting
ruff check .
pyright
# Run tests with coverage
pytest tests/ --cov=typecoverage --cov-report=term-missing
```
## 📈 Roadmap
- [x] **Core Analysis Engine** - AST-based type annotation detection
- [x] **CLI Interface** - Full command-line interface
- [x] **Python API** - Programmatic access
- [x] **Multiple Input Types** - Files, directories, code strings, live objects
- [x] **Output Formats** - Text and JSON with statistics
- [x] **Comment Suppression** - Standard suppression patterns
- [x] **Configuration Files** - pyproject.toml support
- [ ] **IDE Extensions** - VS Code, PyCharm plugin support
- [ ] **Type Hint Suggestions** - Automated type annotation suggestions
- [ ] **Incremental Analysis** - Only check changed files
- [ ] **Custom Rules** - User-defined annotation requirements
- [ ] **HTML Reports** - Rich web-based reporting
## ❓ FAQ
**Q: How does this differ from mypy or pyright?**
A: Mypy and pyright focus on type correctness (catching type errors). Typecoverage focuses on type **coverage** (ensuring annotations exist). Use them together for comprehensive type safety.
**Q: Can I use this with existing type checkers?**
A: Absolutely! Typecoverage complements mypy, pyright, and other type checkers. Run typecoverage first to ensure annotations exist, then use other tools to verify type correctness.
**Q: What about performance on large codebases?**
A: Typecoverage uses parallel processing and is optimized for speed. For very large projects, use `--exclude` to skip unnecessary directories and `--extensions` to limit file types.
**Q: How do I handle legacy code with many issues?**
A: Start with `--fail-under` set to your current issue count, then gradually reduce it. Use suppression comments for intentionally untyped code.
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with Python's `ast` module for accurate source code analysis
- Inspired by flake8, mypy, and other Python code quality tools
- Uses parallel processing for performance on large codebases
- Follows Google-style docstrings and modern Python practices
---
<div align="center">
<p>Made with ❤️ for the Python community</p>
<p>
<a href="docs/wiki/Home.md">📚 Documentation</a> •
<a href="demos/">🎯 Examples</a> •
<a href="https://github.com/yourusername/typecoverage/issues">🐛 Report Issues</a> •
<a href="https://github.com/yourusername/typecoverage/discussions">💬 Discussions</a>
</p>
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/kairos-xx/typecoverage",
"name": "typecoverage",
"maintainer": "Joao Lopes",
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Joao Lopes <joaslopes@gmail.com>",
"keywords": "type-checking, static-analysis, type-annotations, code-quality, python-typing, ast-analysis",
"author": "Joao Lopes",
"author_email": "Joao Lopes <joaslopes@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ab/74/35e69504a7f4d861e7cec0cc8d27949b32a4e9642a38b3f59bc5b05974ca/typecoverage-1.0.1.tar.gz",
"platform": "any",
"description": "\n<div align=\"center\">\n <img src=\"https://i.postimg.cc/hPbkJZzB/icon-raster.png\" alt=\"Typecoverage Logo\" width=\"350\"/>\n <h1>\ud83d\udd0d Typecoverage - Python Type Annotation Analyzer</h1>\n <p><em>A strict CLI + library API to report untyped variables, arguments, and function returns in Python code</em></p>\n\n <p>\n <img src=\"https://img.shields.io/badge/python-3.11+-blue.svg\" alt=\"Python 3.11+\">\n <img src=\"https://img.shields.io/badge/license-MIT-green.svg\" alt=\"MIT License\">\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code Style: Black\">\n </p>\n</div>\n\n## \ud83c\udfaf What is Typecoverage?\n\nTypecoverage is a comprehensive Python static analysis tool that identifies missing type annotations in your codebase. Unlike other type checkers that focus on type correctness, Typecoverage specifically targets **type annotation coverage** - ensuring your code has complete type hints for maintainability and clarity.\n\n### \u2728 Key Features\n\n- \ud83d\udd0d **Comprehensive Detection** - Finds missing annotations in functions, methods, variables, and returns\n- \ud83c\udfaf **Multiple Input Types** - Analyze files, directories, code strings, live Python objects, and more\n- \ud83d\udcca **Rich Output Formats** - Human-readable text with colors or machine-readable JSON\n- \u2699\ufe0f **Flexible Filtering** - Smart defaults with configurable rules for different coding patterns\n- \ud83d\udeab **Comment Suppression** - Standard `# type: ignore` and `# noqa` support\n- \ud83d\ude80 **High Performance** - Parallel processing for large codebases\n- \ud83d\udee0\ufe0f **CI/CD Ready** - Exit codes and JSON output for continuous integration\n- \ud83d\udcdd **Detailed Context** - Source code snippets around issues for easy fixing\n\n### \ud83d\ude80 Quick Example\n\n```python\nfrom typecoverage import detect_untyped\n\n# Analyze code string\ncode = \"\"\"\ndef calculate_total(items, tax_rate):\n subtotal = sum(item.price for item in items)\n return subtotal * (1 + tax_rate)\n\"\"\"\n\nresult = detect_untyped(code, statistics=True)\nprint(result)\n```\n\n**Output:**\n```\nFound 3 type annotation issues\n\n\ud83d\udcc1 <string>\n <string>:2:20 - Missing type annotation for argument \"items\"\n 1 \u2502 \n \u25ba 2 \u2502 def calculate_total(items, tax_rate):\n 3 \u2502 subtotal = sum(item.price for item in items)\n\n <string>:2:27 - Missing type annotation for argument \"tax_rate\"\n 1 \u2502 \n \u25ba 2 \u2502 def calculate_total(items, tax_rate):\n 3 \u2502 subtotal = sum(item.price for item in items)\n\n <string>:2:1 - Missing return type annotation \"calculate_total\"\n 1 \u2502 \n \u25ba 2 \u2502 def calculate_total(items, tax_rate):\n 3 \u2502 subtotal = sum(item.price for item in items)\n\n\ud83d\udcca Summary\n Total issues: 3\n \ud83d\udd34 Missing argument types: 2\n \ud83d\udfe1 Missing return types: 1\n```\n\n## \ud83d\udce6 Installation\n\n### From Source (Current)\n```bash\ngit clone <repository-url>\ncd typecoverage-project\npip install -r requirements.txt\n```\n\n### Using the Package\n```bash\n# Install in development mode\npip install -e .\n\n# Or install directly\npython setup.py install\n```\n\n## \ud83c\udfc1 Quick Start\n\n### Command Line Usage\n\n```bash\n# Using the module\npython -m typecoverage myfile.py\n\n# Using the installed command\ntypecoverage myfile.py\n\n# Analyze entire project with statistics\ntypecoverage --recursive --statistics src/\n\n# JSON output for CI/CD\ntypecoverage --format json --exit-nonzero-on-issues src/ > report.json\n\n# Include context lines for easier fixing\ntypecoverage --context-lines 3 src/main.py\n```\n\n### Python API Usage\n\n```python\nfrom typecoverage import TypeCoverage, detect_untyped\n\n# Simple analysis\nresult = detect_untyped(\"def func(x): return x\", statistics=True)\nprint(result)\n\n# Advanced analysis\nchecker = TypeCoverage()\nissues, errors = checker.analyze_targets(\n \"src/\",\n recursive=True,\n context_lines=2,\n exclude=[\"__pycache__\", \"tests\"],\n)\n\nstats = checker.compute_stats(issues)\nprint(f\"Found {stats.total} issues across {len(set(i.file for i in issues))} files\")\n```\n\n## \ud83c\udfaf Supported Input Types\n\nTypecoverage can analyze various types of targets:\n\n| Input Type | Example | Description |\n|------------|---------|-------------|\n| **Files** | `main.py` | Individual Python files |\n| **Directories** | `src/` | Directory trees (with `--recursive`) |\n| **Glob Patterns** | `**/*.py` | Wildcard file matching |\n| **Code Strings** | `\"def func(x): pass\"` | Direct Python code |\n| **Live Functions** | `my_function` | Runtime function objects |\n| **Classes** | `MyClass` | Class objects |\n| **Modules** | `import mymodule; mymodule` | Module objects |\n| **Paths** | `Path(\"src/main.py\")` | pathlib.Path objects |\n\n## \u2699\ufe0f Configuration\n\n### Command Line Options\n\n```bash\n# Analysis options\n--recursive # Recurse into subdirectories\n--context-lines N # Show N lines of context around issues\n--statistics # Include summary statistics\n\n# Output options \n--format json # JSON output instead of text\n--output FILE # Write to file instead of stdout\n--force-color # Force ANSI colors even when piped\n\n# File filtering\n--extensions .py,.pyx # File extensions to analyze\n--exclude tests,docs # Exclude paths containing substrings\n\n# Variable filtering (default: ignore these)\n--no-ignore-underscore-vars # Include _private variables\n--no-ignore-for-targets # Include for loop variables\n--no-ignore-except-vars # Include exception variables \n--no-ignore-context-vars # Include with statement variables\n--no-ignore-comprehensions # Include list/dict comprehension vars\n\n# Exit behavior\n--exit-nonzero-on-issues # Exit 1 if any issues found\n--fail-under N # Exit 1 if >= N issues found\n```\n\n### Configuration File\n\nCreate `pyproject.toml` configuration:\n\n```toml\n[tool.typecoverage]\nrecursive = true\nstatistics = true\ncontext-lines = 2\nexclude = [\"tests\", \"__pycache__\", \"build\"]\nignore-underscore-vars = true\nexit-nonzero-on-issues = true\nfail-under = 50\n```\n\n## \ud83d\udeab Issue Suppression\n\nUse standard Python suppression comments:\n\n```python\n# Suppress all issues on this line\ndef my_function(x, y): # type: ignore\n return x + y\n\n# Suppress specific issue types\ndef another_function(x, y): # noqa: ANN001,ANN201\n return x + y\n\n# Suppress on previous line\n# type: ignore\ndef third_function(x, y):\n return x + y\n```\n\n**Supported patterns:**\n- `# type: ignore` - Suppress all type checking issues\n- `# type: ignore[code]` - Suppress specific error codes\n- `# noqa` / `# noqa: code` - Flake8-style suppression\n- `# mypy: ignore` / `# pyright: ignore` - Tool-specific suppression\n\n## \ud83d\udcca Understanding the Output\n\n### Text Format\n\n```\nFound 5 type annotation issues\n\n\ud83d\udcc1 src/calculator.py\n src/calculator.py:15:8 - Missing type annotation for argument \"value\"\n 14 \u2502 def process_value(self, value, multiplier=1):\n \u25ba 15 \u2502 result = value * multiplier\n 16 \u2502 return result\n\n\ud83d\udcca Summary\n Total issues: 5\n \ud83d\udd34 Missing argument types: 3\n \ud83d\udfe1 Missing return types: 1 \n \ud83d\udd35 Missing variable types: 1\n```\n\n### JSON Format\n\n```json\n{\n \"version\": \"0.1.8\",\n \"issues\": [\n {\n \"file\": \"src/calculator.py\",\n \"line\": 15,\n \"column\": 8,\n \"type\": \"untyped-argument\", \n \"name\": \"value\",\n \"context\": [\" def process_value(self, value, multiplier=1):\", \" result = value * multiplier\"]\n }\n ],\n \"statistics\": {\n \"total\": 5,\n \"untyped-argument\": 3,\n \"untyped-return\": 1,\n \"untyped-variable\": 1\n }\n}\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Analyzing Live Objects\n\n```python\nfrom typecoverage import TypeCoverage\n\ndef my_function(x, y):\n return x + y\n\nclass MyClass:\n def method(self, value):\n return value * 2\n\nchecker = TypeCoverage()\n\n# Analyze function\nissues, _ = checker.analyze_object(my_function, context_lines=1)\nprint(f\"Function issues: {len(issues)}\")\n\n# Analyze class\nissues, _ = checker.analyze_object(MyClass, context_lines=1)\nprint(f\"Class issues: {len(issues)}\")\n```\n\n### Batch Analysis\n\n```python\nfrom pathlib import Path\nfrom typecoverage import analyze_targets\n\n# Analyze multiple targets\nissues, errors = analyze_targets(\n \"src/main.py\", # Specific file\n Path(\"lib/\"), # Directory path\n \"utils/**/*.py\", # Glob pattern\n my_function, # Live object\n recursive=True,\n exclude=[\"test_\", \"__pycache__\"],\n context_lines=1,\n)\n\nprint(f\"Total issues: {len(issues)}\")\nprint(f\"Errors: {len(errors)}\")\n```\n\n## \ud83c\udfd7\ufe0f CI/CD Integration\n\n### GitHub Actions\n\n```yaml\nname: Type Annotation Coverage\non: [push, pull_request]\n\njobs:\n typecoverage:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v3\n - name: Set up Python\n uses: actions/setup-python@v4\n with:\n python-version: '3.11'\n \n - name: Install dependencies\n run: pip install -r requirements.txt\n \n - name: Run typecoverage\n run: |\n typecoverage \\\n --format json \\\n --exit-nonzero-on-issues \\\n --recursive \\\n --output typecoverage-report.json \\\n src/\n \n - name: Upload results\n uses: actions/upload-artifact@v3\n if: always()\n with:\n name: typecoverage-report\n path: typecoverage-report.json\n```\n\n### Pre-commit Hook\n\n```yaml\n# .pre-commit-config.yaml\nrepos:\n - repo: local\n hooks:\n - id: typecoverage\n name: typecoverage\n entry: typecoverage\n language: system\n args: [--exit-nonzero-on-issues, --recursive, src/]\n files: \\.py$\n```\n\n## \ud83d\udcda Examples and Demos\n\n### Basic Usage Demo\n```bash\npython demos/basic_usage.py\n```\n\n### Advanced Features Demo\n```bash \npython demos/advanced_usage.py\n```\n\n### CLI Examples\n```bash\npython demos/cli_examples.py\n```\n\n### Test the Library\n```bash\n# Run comprehensive test suite\npytest tests/ -v --cov=typecoverage --cov-report=term-missing\n\n# Test specific functionality\npytest tests/test_core.py::TestTypeCoverage -v\n```\n\n## \ud83c\udfd7\ufe0f Project Structure\n\n```\n\u251c\u2500\u2500 typecoverage/\n\u2502 \u251c\u2500\u2500 __init__.py # Public API exports\n\u2502 \u251c\u2500\u2500 __main__.py # CLI entry point\n\u2502 \u2514\u2500\u2500 core.py # Main typecoverage implementation\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 core.py # Development version\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_core.py # Comprehensive test suite \n\u2502 \u2514\u2500\u2500 test_suppressions.py # Suppression functionality tests\n\u251c\u2500\u2500 demos/\n\u2502 \u251c\u2500\u2500 basic_usage.py # Basic usage examples\n\u2502 \u251c\u2500\u2500 advanced_usage.py # Advanced features demo\n\u2502 \u2514\u2500\u2500 cli_examples.py # CLI usage examples\n\u251c\u2500\u2500 docs/\n\u2502 \u2514\u2500\u2500 wiki/ # Comprehensive documentation\n\u2502 \u251c\u2500\u2500 Home.md # Wiki home page\n\u2502 \u251c\u2500\u2500 Quick-Start.md # Getting started guide\n\u2502 \u251c\u2500\u2500 API-Reference.md# Complete API docs\n\u2502 \u2514\u2500\u2500 CLI-Guide.md # Command-line reference\n\u251c\u2500\u2500 scripts/ # Development utilities\n\u251c\u2500\u2500 logs/ # Analysis logs\n\u251c\u2500\u2500 setup.py # Package setup\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u2514\u2500\u2500 README.md # This file\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository** and clone your fork\n2. **Install development dependencies**: `pip install -r requirements.txt`\n3. **Run tests**: `pytest tests/ -v`\n4. **Check code style**: `ruff check . && black . --check`\n5. **Make your changes** and add tests\n6. **Run the full test suite**: `pytest tests/ --cov=typecoverage`\n7. **Submit a pull request** with a clear description\n\n### Development Workflow\n\n```bash\n# Set up development environment\npip install -r requirements.txt\n\n# Run code formatting\nblack . --line-length 79\nisort . -l 79 -m 1\nruff format . --line-length 79\n\n# Run linting\nruff check .\npyright\n\n# Run tests with coverage\npytest tests/ --cov=typecoverage --cov-report=term-missing\n```\n\n## \ud83d\udcc8 Roadmap\n\n- [x] **Core Analysis Engine** - AST-based type annotation detection\n- [x] **CLI Interface** - Full command-line interface\n- [x] **Python API** - Programmatic access\n- [x] **Multiple Input Types** - Files, directories, code strings, live objects\n- [x] **Output Formats** - Text and JSON with statistics\n- [x] **Comment Suppression** - Standard suppression patterns\n- [x] **Configuration Files** - pyproject.toml support\n- [ ] **IDE Extensions** - VS Code, PyCharm plugin support \n- [ ] **Type Hint Suggestions** - Automated type annotation suggestions\n- [ ] **Incremental Analysis** - Only check changed files\n- [ ] **Custom Rules** - User-defined annotation requirements\n- [ ] **HTML Reports** - Rich web-based reporting\n\n## \u2753 FAQ\n\n**Q: How does this differ from mypy or pyright?**\nA: Mypy and pyright focus on type correctness (catching type errors). Typecoverage focuses on type **coverage** (ensuring annotations exist). Use them together for comprehensive type safety.\n\n**Q: Can I use this with existing type checkers?** \nA: Absolutely! Typecoverage complements mypy, pyright, and other type checkers. Run typecoverage first to ensure annotations exist, then use other tools to verify type correctness.\n\n**Q: What about performance on large codebases?**\nA: Typecoverage uses parallel processing and is optimized for speed. For very large projects, use `--exclude` to skip unnecessary directories and `--extensions` to limit file types.\n\n**Q: How do I handle legacy code with many issues?**\nA: Start with `--fail-under` set to your current issue count, then gradually reduce it. Use suppression comments for intentionally untyped code.\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with Python's `ast` module for accurate source code analysis\n- Inspired by flake8, mypy, and other Python code quality tools\n- Uses parallel processing for performance on large codebases\n- Follows Google-style docstrings and modern Python practices\n\n---\n\n<div align=\"center\">\n <p>Made with \u2764\ufe0f for the Python community</p>\n <p>\n <a href=\"docs/wiki/Home.md\">\ud83d\udcda Documentation</a> \u2022\n <a href=\"demos/\">\ud83c\udfaf Examples</a> \u2022\n <a href=\"https://github.com/yourusername/typecoverage/issues\">\ud83d\udc1b Report Issues</a> \u2022\n <a href=\"https://github.com/yourusername/typecoverage/discussions\">\ud83d\udcac Discussions</a>\n </p>\n</div>\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 Joao Lopes\n \n Permission is hereby granted, free of charge, to any person\n obtaining\n a copy of this software and associated documentation files (the\n \"Software\"), to deal in the Software without restriction, including\n without limitation the rights to use, copy, modify, merge, publish,\n distribute, sublicense, and/or sell copies of the Software, and to\n permit persons to whom the Software is furnished to do so,\n subject to\n the following conditions:\n \n The above copyright notice and this permission notice shall be\n included in all copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND,\n EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\n MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\n NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\n BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\n ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A strict CLI + library API to report untyped variables, arguments, and function returns in Python code",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/kairos-xx/typecoverage/releases",
"Documentation": "https://github.com/kairos-xx/typecoverage/docs",
"Homepage": "https://github.com/kairos-xx/typecoverage",
"Issues": "https://github.com/kairos-xx/typecoverage/issues",
"Repository": "https://github.com/kairos-xx/typecoverage"
},
"split_keywords": [
"type-checking",
" static-analysis",
" type-annotations",
" code-quality",
" python-typing",
" ast-analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8cbf51d924d317b8d568d440808c0b78efa4d6cd2caf9ea63c85d3f39c204870",
"md5": "a082cb586002e61b56338a33d42265aa",
"sha256": "1d87df4d681c694b6fcd73987a3d3857c3bc876fdc7eff1610c84b370b6c91d3"
},
"downloads": -1,
"filename": "typecoverage-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a082cb586002e61b56338a33d42265aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 26935,
"upload_time": "2025-08-18T05:36:09",
"upload_time_iso_8601": "2025-08-18T05:36:09.511647Z",
"url": "https://files.pythonhosted.org/packages/8c/bf/51d924d317b8d568d440808c0b78efa4d6cd2caf9ea63c85d3f39c204870/typecoverage-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ab7435e69504a7f4d861e7cec0cc8d27949b32a4e9642a38b3f59bc5b05974ca",
"md5": "8d2795a0fcb85438d609b796a4cabbe4",
"sha256": "5aaaf7157f4b3c34d149bf42cf53ae7623bcc133ab55af98b643188a91ed1d6a"
},
"downloads": -1,
"filename": "typecoverage-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8d2795a0fcb85438d609b796a4cabbe4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 47077,
"upload_time": "2025-08-18T05:36:11",
"upload_time_iso_8601": "2025-08-18T05:36:11.130543Z",
"url": "https://files.pythonhosted.org/packages/ab/74/35e69504a7f4d861e7cec0cc8d27949b32a4e9642a38b3f59bc5b05974ca/typecoverage-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 05:36:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kairos-xx",
"github_project": "typecoverage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pytest",
"specs": [
[
">=",
"7.0.0"
]
]
},
{
"name": "pytest",
"specs": []
},
{
"name": "replit",
"specs": [
[
"==",
"4.1.0"
]
]
},
{
"name": "black",
"specs": []
},
{
"name": "flake8",
"specs": []
},
{
"name": "build",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "pyright",
"specs": []
},
{
"name": "toml",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "isort",
"specs": []
},
{
"name": "pyproject-flake8",
"specs": []
},
{
"name": "zipfile38",
"specs": [
[
"==",
"0.0.3"
]
]
}
],
"lcname": "typecoverage"
}
