# PyCodemark
---
## Overview
**PyCodemark** is a full-featured Python code review tool that automatically detects style issues, missing docstrings, and other code quality problems.
It supports **terminal, JSON, and SARIF output** for CI/CD integration and is extensible via plugins.
---
## Features
- Detect missing docstrings, PEP8 violations, clarity issues, type hints, and potential bugs
- AI-powered smart review using OpenAI GPT models
- Configurable checks via pycodemark.toml or environment variables
- Auto-fixable issues: line length, optional template docstrings
- Color-coded terminal output (green for no issues, yellow/red for warnings/errors)
- JSON and SARIF output for CI pipelines
- Plugin system for custom checks
- Pre-commit integration
- Works with Python 3.13+
---
## Installation
Clone the repository:
```bash
git clone https://github.com/roshanguptamca/pycodemark.git
cd pycodemark
```
Create a Python 3.13 virtual environment:
```bash
python3.13 -m venv venv
source venv/bin/activate
poetry install
```
Quick Start
# Quick Start with PyCodemark
PyCodemark is a **full-featured Python code review tool** that detects style issues, missing docstrings, and other code quality problems. It supports **terminal, JSON, and SARIF output** for CI integration.
## Installation
Install PyCodemark via pip:
```bash
pip install pycodemark
````
Or with Poetry:
```bash
poetry add pycodemark
poetry run pycodemark review src/
poetry run pycodemark review src/ --format json
poetry run pycodemark review src/ --format sarif
````
Run a basic code review:
```bash
pycodemark review src/
pycodemark review src/ --format json
pycodemark review src/ --format sarif
```
Environment Variables
PyCodemark requires an OpenAI API key to perform AI-powered smart code reviews. You can also optionally specify which OpenAI model to use.
## 1. OpenAI API Key
Set your API key as an environment variable:
```bash
export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"
```
This is required for the smart-review command.
The tool will use this key to authenticate with the OpenAI API.
You can obtain your key from OpenAI API Keys
## 2.Optional: Specify AI Model
By default, PyCodemark uses the gpt-5 model for smart reviews.
You can override it with the environment variable CODEMARK_MODEL:
```bash
export CODEMARK_MODEL="gpt-5"
```
If not set, gpt-5 will be used automatically.
You can specify any OpenAI chat-capable model available to your account.
Example models: gpt-5, gpt-5.1, gpt-4, gpt-4-32k.
# 3. Quick Example:
```bash
export OPENAI_API_KEY="sk-xxxx"
export CODEMARK_MODEL="gpt-5"
# Run AI-powered review
pycodemark smart-review src/
```
Any issues detected by the AI will appear in the terminal table, JSON, or SARIF output depending on the chosen --format.
If your quota is exceeded or the API fails, the tool will log the error in the report.
# 4. Security Tips
Do not commit your API key to version control.
Store keys securely in environment variables or secret managers.
You can also use .env files with tools like direnv or python-dotenv.
Plugins
Extend PyCodemark by adding custom checks under src/codemark/plugins/.
Each plugin must implement:
```python`
def run(file_path, config):
"""Return a list of issues detected in the file."""
return []
````
Pre-commit Integration
Add to your .pre-commit-config.yaml:
```yaml repos:
- repo: local
hooks:
- id: codemark
name: codemark-review
entry: codemark review --format terminal
language: system
types: [python]
```
Then run:
```bashpre-commit install
```pre-commit install
````
## CI/CD Integration (GitHub Actions)
You can integrate PyCodemark in CI pipelines with SARIF reporting.
Example workflow file: .github/workflows/codemark.yml
Runs PyCodemark on every push or pull request
Uploads SARIF results to GitHub for code scanning
Provides automated code quality checks
Configuration
Configure PyCodemark via pyproject.toml:
```toml
[tool.pycodemark]
max_line_length = 120
insert_docstrings = true
ignore_rules = ["LineLength"]
checks = { style = true, clarity = true, docstrings = true, type_hints = true, bugs = true, best_practices = true, ai_review = true }
exclude = ["tests/", "migrations/"]
```
- max_line_length: Maximum allowed characters per line
- insert_docstrings: Automatically insert template docstrings if missing
- ignore_rules: Disable specific rules
- checks: Enable or disable specific checks
- exclude: Ignore specific files or directories
# Makefile Commands:
- `make lint`: Run code linting
- make venv # Create virtual environment
- make install # Install dependencies via Poetry
- make build # Build package
- make test # Run tests
- make lint # Run linter
- make lint-fix # Automatically fix lint issues
- make review # Run terminal review
- make review-json # Run review with JSON output
- make review-sarif # Run review with SARIF output
- make publish # Publish to PyPI
```
- **NEW:** Auto-generate missing unit tests
- `pycodemark gen-tests src/` → scans your source code for functions without tests
- Creates or appends to files like `tests/test_<module>.py`
- Supports `--ai` for GPT-5-powered intelligent test generation
- Ideal for boosting test coverage quickly
## AI-Powered Unit Test Generation
Automatically generate tests for functions without coverage:
Command Description:
```bash
pycodemark gen-tests src/ # Generate basic pytest test stubs
pycodemark gen-tests src/ --ai # Generate AI-assisted realistic tests
pycodemark gen-tests src/ --overwrite # Replace existing test files
pycodemark gen-tests src/ --include-private # Include private functions in test generation
```
## Download Documentation:
PDF
HTML
License
MIT License © Roshan Gupta
Raw data
{
"_id": null,
"home_page": "https://github.com/roshanguptamca/pycodemark/",
"name": "pycodemark",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "python, code, review, linter, cli, static-analysis, quality",
"author": "Roshan",
"author_email": "roshanguptamca@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bd/ab/d505d54063628da5516416729ba5fe31d7d4feb82256bd7e51ed0fc5e5fe/pycodemark-0.5.1.tar.gz",
"platform": null,
"description": "# PyCodemark\n\n\n\n\n\n\n---\n\n## Overview\n\n**PyCodemark** is a full-featured Python code review tool that automatically detects style issues, missing docstrings, and other code quality problems. \nIt supports **terminal, JSON, and SARIF output** for CI/CD integration and is extensible via plugins.\n\n---\n\n## Features\n\n- Detect missing docstrings, PEP8 violations, clarity issues, type hints, and potential bugs\n- AI-powered smart review using OpenAI GPT models\n- Configurable checks via pycodemark.toml or environment variables\n- Auto-fixable issues: line length, optional template docstrings\n- Color-coded terminal output (green for no issues, yellow/red for warnings/errors)\n- JSON and SARIF output for CI pipelines\n- Plugin system for custom checks\n- Pre-commit integration\n- Works with Python 3.13+\n\n---\n\n## Installation\n\nClone the repository:\n\n```bash\ngit clone https://github.com/roshanguptamca/pycodemark.git\ncd pycodemark\n```\n\nCreate a Python 3.13 virtual environment:\n```bash\npython3.13 -m venv venv \nsource venv/bin/activate\npoetry install\n``` \nQuick Start\n# Quick Start with PyCodemark\n\nPyCodemark is a **full-featured Python code review tool** that detects style issues, missing docstrings, and other code quality problems. It supports **terminal, JSON, and SARIF output** for CI integration.\n\n## Installation\n\nInstall PyCodemark via pip:\n\n```bash\npip install pycodemark\n````\nOr with Poetry:\n```bash\npoetry add pycodemark \n\npoetry run pycodemark review src/\npoetry run pycodemark review src/ --format json\npoetry run pycodemark review src/ --format sarif \n````\nRun a basic code review:\n```bash\npycodemark review src/\npycodemark review src/ --format json\npycodemark review src/ --format sarif \n```\nEnvironment Variables\n\nPyCodemark requires an OpenAI API key to perform AI-powered smart code reviews. You can also optionally specify which OpenAI model to use.\n\n## 1. OpenAI API Key\n\nSet your API key as an environment variable:\n```bash\nexport OPENAI_API_KEY=\"sk-xxxxxxxxxxxxxxxxxxxxxxxx\" \n```\nThis is required for the smart-review command.\n\nThe tool will use this key to authenticate with the OpenAI API.\nYou can obtain your key from OpenAI API Keys\n\n## 2.Optional: Specify AI Model\n\nBy default, PyCodemark uses the gpt-5 model for smart reviews. \nYou can override it with the environment variable CODEMARK_MODEL:\n\n```bash\nexport CODEMARK_MODEL=\"gpt-5\" \n```\n\nIf not set, gpt-5 will be used automatically.\nYou can specify any OpenAI chat-capable model available to your account.\nExample models: gpt-5, gpt-5.1, gpt-4, gpt-4-32k.\n\n# 3. Quick Example:\n```bash\nexport OPENAI_API_KEY=\"sk-xxxx\"\nexport CODEMARK_MODEL=\"gpt-5\"\n\n# Run AI-powered review\npycodemark smart-review src/\n\n```\nAny issues detected by the AI will appear in the terminal table, JSON, or SARIF output depending on the chosen --format.\n\nIf your quota is exceeded or the API fails, the tool will log the error in the report.\n\n# 4. Security Tips\nDo not commit your API key to version control.\nStore keys securely in environment variables or secret managers.\nYou can also use .env files with tools like direnv or python-dotenv.\n\nPlugins\nExtend PyCodemark by adding custom checks under src/codemark/plugins/.\nEach plugin must implement:\n```python`\ndef run(file_path, config):\n \"\"\"Return a list of issues detected in the file.\"\"\"\n return []\n````\nPre-commit Integration\n\nAdd to your .pre-commit-config.yaml:\n```yaml repos:\n - repo: local\n hooks:\n - id: codemark\n name: codemark-review\n entry: codemark review --format terminal\n language: system\n types: [python] \n```\n\nThen run:\n```bashpre-commit install\n```pre-commit install\n````\n## CI/CD Integration (GitHub Actions)\n\nYou can integrate PyCodemark in CI pipelines with SARIF reporting.\nExample workflow file: .github/workflows/codemark.yml\n\nRuns PyCodemark on every push or pull request\n\nUploads SARIF results to GitHub for code scanning\n\nProvides automated code quality checks\n\nConfiguration\n\nConfigure PyCodemark via pyproject.toml:\n```toml\n[tool.pycodemark]\nmax_line_length = 120\ninsert_docstrings = true\nignore_rules = [\"LineLength\"]\nchecks = { style = true, clarity = true, docstrings = true, type_hints = true, bugs = true, best_practices = true, ai_review = true }\nexclude = [\"tests/\", \"migrations/\"]\n\n```\n- max_line_length: Maximum allowed characters per line\n- insert_docstrings: Automatically insert template docstrings if missing\n- ignore_rules: Disable specific rules\n- checks: Enable or disable specific checks\n- exclude: Ignore specific files or directories\n\n# Makefile Commands:\n- `make lint`: Run code linting\n- make venv # Create virtual environment\n- make install # Install dependencies via Poetry\n- make build # Build package\n- make test # Run tests\n- make lint # Run linter\n- make lint-fix # Automatically fix lint issues\n- make review # Run terminal review\n- make review-json # Run review with JSON output\n- make review-sarif # Run review with SARIF output\n- make publish # Publish to PyPI\n\n\n```\n- **NEW:** Auto-generate missing unit tests \n - `pycodemark gen-tests src/` \u2192 scans your source code for functions without tests \n - Creates or appends to files like `tests/test_<module>.py` \n - Supports `--ai` for GPT-5-powered intelligent test generation \n - Ideal for boosting test coverage quickly\n\n## AI-Powered Unit Test Generation\nAutomatically generate tests for functions without coverage:\nCommand\tDescription:\n```bash\npycodemark gen-tests src/\t# Generate basic pytest test stubs\npycodemark gen-tests src/ --ai\t# Generate AI-assisted realistic tests\npycodemark gen-tests src/ --overwrite\t# Replace existing test files\npycodemark gen-tests src/ --include-private\t# Include private functions in test generation\n```\n\n## Download Documentation:\nPDF\nHTML\n\nLicense\n\nMIT License \u00a9 Roshan Gupta",
"bugtrack_url": null,
"license": "MIT",
"summary": "PyCodemark \u2013 a full-featured code review tool for Python.",
"version": "0.5.1",
"project_urls": {
"Documentation": "https://github.com/roshanguptamca/pycodemark/blob/main/README.md",
"Homepage": "https://github.com/roshanguptamca/pycodemark/",
"Repository": "https://github.com/roshanguptamca/pycodemark/"
},
"split_keywords": [
"python",
" code",
" review",
" linter",
" cli",
" static-analysis",
" quality"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53467d98ca879649519b879623128cc1c305978dc196cb5f96b85007f49678cb",
"md5": "eb4afd4483a1ea5f44da1531b1f8b1f3",
"sha256": "144eb93c109125de2a3e1c4d840eb2bae3c4ec1a729dd775a78f2de1cc2df2fc"
},
"downloads": -1,
"filename": "pycodemark-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb4afd4483a1ea5f44da1531b1f8b1f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 17478,
"upload_time": "2025-10-25T22:19:00",
"upload_time_iso_8601": "2025-10-25T22:19:00.969306Z",
"url": "https://files.pythonhosted.org/packages/53/46/7d98ca879649519b879623128cc1c305978dc196cb5f96b85007f49678cb/pycodemark-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bdabd505d54063628da5516416729ba5fe31d7d4feb82256bd7e51ed0fc5e5fe",
"md5": "c9c8f294b89871758277d7b0657c9410",
"sha256": "75ffe185f5d4a0a0b5888796e5a0e8a7dd70df7161d2366a6f9252ca8e0393e8"
},
"downloads": -1,
"filename": "pycodemark-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "c9c8f294b89871758277d7b0657c9410",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 14218,
"upload_time": "2025-10-25T22:19:02",
"upload_time_iso_8601": "2025-10-25T22:19:02.164743Z",
"url": "https://files.pythonhosted.org/packages/bd/ab/d505d54063628da5516416729ba5fe31d7d4feb82256bd7e51ed0fc5e5fe/pycodemark-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-25 22:19:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "roshanguptamca",
"github_project": "pycodemark",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycodemark"
}
JSON
