# CodeClinic (codeclinic)
> Diagnose your Python project: import dependencies → maturity metrics (stub ratio) → Graphviz visualization.
## Install
```bash
pip install codeclinic
# or, from source (dev):
pip install -e .
```
> **Note:** Rendering SVG/PNG requires the Graphviz **system** tool (`dot`) in your PATH. macOS: `brew install graphviz`; Ubuntu: `sudo apt-get install graphviz`.
## Quick start
```bash
codeclinic --path ./src --out results
```
This prints a summary + adjacency list and writes:
- `results/analysis.json` (project analysis data)
- `results/stub_report.json` (detailed stub function report)
- `results/dependency_graph.dot` (DOT source)
- `results/dependency_graph.svg` (rendered visualization)
## Marking stubs
```python
from codeclinic import stub
@stub
def todo_api():
pass
```
`@stub` will (1) mark the function for static counting and (2) emit a `warnings.warn` when it’s actually called.
## Config
You can keep settings in `pyproject.toml` under `[tool.codeclinic]` or in a `codeclinic.toml` file:
```toml
[tool.codeclinic]
paths = ["src"]
include = ["**/*.py"]
exclude = ["**/tests/**", "**/.venv/**"]
aggregate = "package" # "module" | "package"
format = "svg" # svg | png | pdf | dot
output = "build/cc_graph"
count_private = false
```
CLI flags override config.
## Output Formats
### All-in-One (Default)
```bash
codeclinic --path ./src --out results
```
Generates complete analysis with all output files in a single directory.
### JSON Data Only
```bash
codeclinic --path ./src --out results --format json
```
Generates only JSON files (analysis + stub report) without visualization.
### Specific Visualization Formats
```bash
codeclinic --path ./src --out results --format svg # SVG visualization
codeclinic --path ./src --out results --format png # PNG visualization
codeclinic --path ./src --out results --format pdf # PDF visualization
```
## Stub Function Reports
The `stub_report.json` file contains detailed information about all `@stub` decorated functions:
```json
{
"metadata": {
"total_stub_functions": 5,
"modules_with_stubs": 3,
"function_stubs": 3,
"method_stubs": 2
},
"stub_functions": [
{
"module_name": "myproject.utils",
"file_path": "/path/to/utils.py",
"function_name": "incomplete_feature",
"full_name": "incomplete_feature",
"docstring": "This feature is not yet implemented.",
"is_method": false,
"class_name": null,
"graph_depth": 2
}
]
}
```
Each stub function includes:
- **File location** and module information
- **Function/method name** with full qualified name (e.g., `ClassName.method_name`)
- **Docstring** extracted from the function
- **Graph depth** - dependency level for implementation prioritization
- **Method classification** - whether it's a standalone function or class method
## CLI
```bash
codeclinic --path PATH [--out OUTPUT_DIR] [--format svg|png|pdf|dot|json] [--aggregate module|package]
```
## How it works
- Parses your code with `ast` (no import-time side effects).
- Builds an internal import graph (absolute & relative imports resolved).
- Counts public functions/methods and `@stub`-decorated ones to compute a stub ratio per node.
- Renders a Graphviz graph with node colors by ratio (green→yellow→red).
## Roadmap
- Smell detectors (circulars, forbidden deps, god packages, layer rules).
- HTML/PDF report with dashboards.
- Plugin entry points: `codeclinic.detector`.
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "codeclinic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "analysis, ast, dependency, graphviz, import, metrics, stub, visualization",
"author": null,
"author_email": "CodeClinic Team <codeclinic@example.com>",
"download_url": "https://files.pythonhosted.org/packages/91/33/354b91711ef3bab562946f79c523690339aba940e4383c0df284cd2c9e7b/codeclinic-0.1.2.tar.gz",
"platform": null,
"description": "# CodeClinic (codeclinic)\n\n> Diagnose your Python project: import dependencies \u2192 maturity metrics (stub ratio) \u2192 Graphviz visualization.\n\n## Install\n```bash\npip install codeclinic\n# or, from source (dev):\npip install -e .\n```\n> **Note:** Rendering SVG/PNG requires the Graphviz **system** tool (`dot`) in your PATH. macOS: `brew install graphviz`; Ubuntu: `sudo apt-get install graphviz`.\n\n## Quick start\n```bash\ncodeclinic --path ./src --out results\n```\nThis prints a summary + adjacency list and writes:\n- `results/analysis.json` (project analysis data)\n- `results/stub_report.json` (detailed stub function report)\n- `results/dependency_graph.dot` (DOT source)\n- `results/dependency_graph.svg` (rendered visualization)\n\n## Marking stubs\n```python\nfrom codeclinic import stub\n\n@stub\ndef todo_api():\n pass\n```\n`@stub` will (1) mark the function for static counting and (2) emit a `warnings.warn` when it\u2019s actually called.\n\n## Config\nYou can keep settings in `pyproject.toml` under `[tool.codeclinic]` or in a `codeclinic.toml` file:\n```toml\n[tool.codeclinic]\npaths = [\"src\"]\ninclude = [\"**/*.py\"]\nexclude = [\"**/tests/**\", \"**/.venv/**\"]\naggregate = \"package\" # \"module\" | \"package\"\nformat = \"svg\" # svg | png | pdf | dot\noutput = \"build/cc_graph\"\ncount_private = false\n```\nCLI flags override config.\n\n## Output Formats\n\n### All-in-One (Default)\n```bash\ncodeclinic --path ./src --out results\n```\nGenerates complete analysis with all output files in a single directory.\n\n### JSON Data Only\n```bash\ncodeclinic --path ./src --out results --format json\n```\nGenerates only JSON files (analysis + stub report) without visualization.\n\n### Specific Visualization Formats\n```bash\ncodeclinic --path ./src --out results --format svg # SVG visualization\ncodeclinic --path ./src --out results --format png # PNG visualization \ncodeclinic --path ./src --out results --format pdf # PDF visualization\n```\n\n## Stub Function Reports\n\nThe `stub_report.json` file contains detailed information about all `@stub` decorated functions:\n\n```json\n{\n \"metadata\": {\n \"total_stub_functions\": 5,\n \"modules_with_stubs\": 3,\n \"function_stubs\": 3,\n \"method_stubs\": 2\n },\n \"stub_functions\": [\n {\n \"module_name\": \"myproject.utils\",\n \"file_path\": \"/path/to/utils.py\", \n \"function_name\": \"incomplete_feature\",\n \"full_name\": \"incomplete_feature\",\n \"docstring\": \"This feature is not yet implemented.\",\n \"is_method\": false,\n \"class_name\": null,\n \"graph_depth\": 2\n }\n ]\n}\n```\n\nEach stub function includes:\n- **File location** and module information\n- **Function/method name** with full qualified name (e.g., `ClassName.method_name`)\n- **Docstring** extracted from the function\n- **Graph depth** - dependency level for implementation prioritization\n- **Method classification** - whether it's a standalone function or class method\n\n## CLI\n```bash\ncodeclinic --path PATH [--out OUTPUT_DIR] [--format svg|png|pdf|dot|json] [--aggregate module|package]\n```\n\n## How it works\n- Parses your code with `ast` (no import-time side effects).\n- Builds an internal import graph (absolute & relative imports resolved).\n- Counts public functions/methods and `@stub`-decorated ones to compute a stub ratio per node.\n- Renders a Graphviz graph with node colors by ratio (green\u2192yellow\u2192red).\n\n## Roadmap\n- Smell detectors (circulars, forbidden deps, god packages, layer rules).\n- HTML/PDF report with dashboards.\n- Plugin entry points: `codeclinic.detector`.\n\n## License\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "X-ray your Python project: import graph + stub maturity metrics + Graphviz viz + CLI",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://github.com/Scienith/code-clinic#readme",
"Homepage": "https://github.com/Scienith/code-clinic",
"Issues": "https://github.com/Scienith/code-clinic/issues",
"Repository": "https://github.com/Scienith/code-clinic"
},
"split_keywords": [
"analysis",
" ast",
" dependency",
" graphviz",
" import",
" metrics",
" stub",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c3e4f01f7fb38008ab7add13cc4bc15e14fdbc1fa7a15b39cddacc383c75b992",
"md5": "5278e938b9ebb5e5e53e17b66028f32f",
"sha256": "cbec64c78b5af3caf2aa380442c52c91a8bf384428fbdb977d15c55f49233413"
},
"downloads": -1,
"filename": "codeclinic-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5278e938b9ebb5e5e53e17b66028f32f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17234,
"upload_time": "2025-09-03T07:23:05",
"upload_time_iso_8601": "2025-09-03T07:23:05.844397Z",
"url": "https://files.pythonhosted.org/packages/c3/e4/f01f7fb38008ab7add13cc4bc15e14fdbc1fa7a15b39cddacc383c75b992/codeclinic-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9133354b91711ef3bab562946f79c523690339aba940e4383c0df284cd2c9e7b",
"md5": "a1774872111976818aebe4fcdb8f4d20",
"sha256": "14bdd166f65404e6e61bfce8a6a432c950fbe68dc32b7b4239f3babf4cef7f30"
},
"downloads": -1,
"filename": "codeclinic-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "a1774872111976818aebe4fcdb8f4d20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14027,
"upload_time": "2025-09-03T07:23:07",
"upload_time_iso_8601": "2025-09-03T07:23:07.035767Z",
"url": "https://files.pythonhosted.org/packages/91/33/354b91711ef3bab562946f79c523690339aba940e4383c0df284cd2c9e7b/codeclinic-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 07:23:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Scienith",
"github_project": "code-clinic#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "codeclinic"
}
JSON
