# NetImport: Python Project Architecture Analyzer via Import Graphs
NetImport is a static analysis tool for Python projects that helps developers visualize and evaluate their codebase architecture by analyzing `import` statements. It builds a dependency graph between modules and packages, providing a clearer understanding of the project's structure, identifying potential issues with coupling and cohesion, and tracking complex or undesirable relationships.
## Core Features
* **Import Analysis:** Recursively scans the specified project directory for Python files and parses their `import` statements.
* **Dependency Graph Construction:** Creates a directed graph where nodes represent project modules/packages, as well as external and standard libraries. Edges depict the imports between them.
* **Graph Visualization:** Integrates with Matplotlib to generate visual representations of the dependency graph, facilitating easier analysis.
* **Flexible Configuration:** Allows customization of ignored directories and files via the command line, an `.netimport.toml` file, or `pyproject.toml`.
* **Dependency Type Identification:** Distinguishes imports of internal project modules, Python standard libraries, and external third-party dependencies.
## Why Use NetImport?
* **Understand Project Structure:** Gain a clear visual overview of how different parts of your application are interconnected. This is especially useful for new team members or when working with legacy code.
* **Assess Coupling:** Identify modules that are highly dependent on each other. High coupling can make code harder to change, test, and reuse.
* **Gauge Cohesion (Indirectly):** While directly calculating cohesion from imports alone is difficult, the graph can provide insights into how logically grouped functionalities are within a module by observing its dependencies.
* **Aid Refactoring:** Use the graph as a map during refactoring to understand which parts of the system will be affected by changes.
* **Architectural Oversight:** Helps in maintaining a clean and understandable architecture by making dependencies explicit.
## Installation
```bash
pip install netimport
```
or
```bash
poetry add netimport
```
## Usage
NetImport can be used from the command line and is suitable for integration into CI/CD pipelines.
### Command Line Interface
```bash
netimport [OPTIONS] <PROJECT_PATH>
```
### Key Options:
<PROJECT_PATH>: Path to the root directory of your Python project to be analyzed.
--output-graph FILENAME.PNG: Save the graph visualization to the specified file (e.g., dependencies.png).
--show-graph: Display the graph using Matplotlib (requires a GUI environment).
--config FILEPATH: Path to a custom configuration file (instead of .netimport.toml or pyproject.toml).
--ignored-dirs DIR1,DIR2: Comma-separated list of directories to ignore, overrides configuration files.
--ignored-files FILE1,FILE2: Comma-separated list of files to ignore.
--show-console-summary: Print a textual summary of the graph to the console.
--export-dot FILENAME.DOT: Export the graph in DOT format for use with Graphviz.
--export-mermaid FILENAME.MD: Export the graph in Mermaid syntax.
--layout ALGORITHM_NAME: Choose a graph layout algorithm for visualization (e.g., spring, kamada_kawai, circular; or dot, neato if Graphviz is used).
### Example:
```bash
netimport ./my_python_project --output-graph project_deps.png --layout spring
```
### Configuration
NetImport looks for configuration files in the following order of precedence:
- Command-line arguments.
- An .netimport.toml file in the project root.
- The [tool.netimport] section in a pyproject.toml file in the project root.
- Default values. (Maybe. I'm still thinking.)
Example .netimport.toml or pyproject.toml ([tool.netimport]):
```
ignored_dirs = ["venv", ".venv", "tests", "docs", "__pycache__", "node_modules", "migrations"]
ignored_files = ["setup.py", "manage.py"]
ignore_stdlib = true
ignore_external_lib = true
ignored_nodes = []
# Other planned or potential settings:
# default_layout_algorithm = "spring"
# exclude_std_lib_from_graph = false
# exclude_external_libs_from_graph = false
```
## Roadmap
- Architectural Metrics Calculation:
- Count of incoming/outgoing dependencies for each module (Afferent/Efferent Couplings).
- Calculation of Instability (I) metric.
- (Further research needed for A) Calculation of Abstractness (A) and Distance from Main Sequence (D) metrics, potentially with user-assisted annotation for abstract components.
- Defining Layers and Rule Checking: Ability to define architectural layers and validate rules between them (e.g., via a configuration file).
- Advanced Visualization:
- Interactive HTML reports (e.g., using pyvis or bokeh).
- Highlighting specific nodes or paths on the graph.
- Grouping nodes by package or defined layer.
- Plugin for popular IDEs (VSCode, PyCharm).
- CI/CD Integration: Output results in CI-friendly formats (e.g., JUnit XML), allow setting metric thresholds.
- Improved Import Resolution:
- Better handling of __all__ for more accurate analysis of from ... import *.
- More precise import resolution considering sys.path modifications and namespace packages.
## Contributing
Contributions are welcome to make NetImport better! If you'd like to help, please check out CONTRIBUTING.md for instructions on setting up your development environment, code style, and the process for submitting Pull Requests.
Key areas for contribution:
- Implementing new features from the Roadmap.
- Improving the existing codebase (refactoring, optimization).
- Writing tests.
- Enhancing documentation.
- Bug fixing.
Feel free to open Issues to discuss new ideas or problems.
License
This project is licensed under the MIT License (you'll need to create this file).
Crafted with ❤️ to help improve Python project architectures.
Raw data
{
"_id": null,
"home_page": "https://github.com/beilak/netimport",
"name": "netimport",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "python, architecture, linter, static analysis, import graph, dependencies, visualization, coupling, cohesion",
"author": "Beilak Aliev",
"author_email": "beilak.aliev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/84/43/c05cf923e549350161c459f294a03d5a772e4fcdf2eeb5d1a7cf87193f7d/netimport-0.0.5.tar.gz",
"platform": null,
"description": "# NetImport: Python Project Architecture Analyzer via Import Graphs\n\nNetImport is a static analysis tool for Python projects that helps developers visualize and evaluate their codebase architecture by analyzing `import` statements. It builds a dependency graph between modules and packages, providing a clearer understanding of the project's structure, identifying potential issues with coupling and cohesion, and tracking complex or undesirable relationships.\n\n## Core Features\n\n* **Import Analysis:** Recursively scans the specified project directory for Python files and parses their `import` statements.\n* **Dependency Graph Construction:** Creates a directed graph where nodes represent project modules/packages, as well as external and standard libraries. Edges depict the imports between them.\n* **Graph Visualization:** Integrates with Matplotlib to generate visual representations of the dependency graph, facilitating easier analysis.\n* **Flexible Configuration:** Allows customization of ignored directories and files via the command line, an `.netimport.toml` file, or `pyproject.toml`.\n* **Dependency Type Identification:** Distinguishes imports of internal project modules, Python standard libraries, and external third-party dependencies.\n\n## Why Use NetImport?\n\n* **Understand Project Structure:** Gain a clear visual overview of how different parts of your application are interconnected. This is especially useful for new team members or when working with legacy code.\n* **Assess Coupling:** Identify modules that are highly dependent on each other. High coupling can make code harder to change, test, and reuse.\n* **Gauge Cohesion (Indirectly):** While directly calculating cohesion from imports alone is difficult, the graph can provide insights into how logically grouped functionalities are within a module by observing its dependencies.\n* **Aid Refactoring:** Use the graph as a map during refactoring to understand which parts of the system will be affected by changes.\n* **Architectural Oversight:** Helps in maintaining a clean and understandable architecture by making dependencies explicit.\n\n## Installation\n\n```bash\npip install netimport\n```\nor \n```bash\npoetry add netimport\n```\n\n## Usage\n\nNetImport can be used from the command line and is suitable for integration into CI/CD pipelines.\n\n### Command Line Interface\n```bash\nnetimport [OPTIONS] <PROJECT_PATH>\n```\n\n\n### Key Options:\n\n<PROJECT_PATH>: Path to the root directory of your Python project to be analyzed.\n\n--output-graph FILENAME.PNG: Save the graph visualization to the specified file (e.g., dependencies.png).\n\n--show-graph: Display the graph using Matplotlib (requires a GUI environment).\n\n--config FILEPATH: Path to a custom configuration file (instead of .netimport.toml or pyproject.toml).\n\n--ignored-dirs DIR1,DIR2: Comma-separated list of directories to ignore, overrides configuration files.\n\n--ignored-files FILE1,FILE2: Comma-separated list of files to ignore.\n\n--show-console-summary: Print a textual summary of the graph to the console.\n\n--export-dot FILENAME.DOT: Export the graph in DOT format for use with Graphviz.\n\n--export-mermaid FILENAME.MD: Export the graph in Mermaid syntax.\n\n--layout ALGORITHM_NAME: Choose a graph layout algorithm for visualization (e.g., spring, kamada_kawai, circular; or dot, neato if Graphviz is used).\n\n\n### Example:\n\n```bash\nnetimport ./my_python_project --output-graph project_deps.png --layout spring\n```\n\n\n### Configuration\n\nNetImport looks for configuration files in the following order of precedence:\n\n- Command-line arguments.\n- An .netimport.toml file in the project root.\n- The [tool.netimport] section in a pyproject.toml file in the project root.\n- Default values. (Maybe. I'm still thinking.)\n\nExample .netimport.toml or pyproject.toml ([tool.netimport]):\n\n```\nignored_dirs = [\"venv\", \".venv\", \"tests\", \"docs\", \"__pycache__\", \"node_modules\", \"migrations\"]\nignored_files = [\"setup.py\", \"manage.py\"]\nignore_stdlib = true\nignore_external_lib = true\nignored_nodes = []\n# Other planned or potential settings:\n# default_layout_algorithm = \"spring\"\n# exclude_std_lib_from_graph = false\n# exclude_external_libs_from_graph = false\n```\n\n\n## Roadmap\n\n- Architectural Metrics Calculation:\n - Count of incoming/outgoing dependencies for each module (Afferent/Efferent Couplings).\n - Calculation of Instability (I) metric.\n - (Further research needed for A) Calculation of Abstractness (A) and Distance from Main Sequence (D) metrics, potentially with user-assisted annotation for abstract components.\n- Defining Layers and Rule Checking: Ability to define architectural layers and validate rules between them (e.g., via a configuration file).\n- Advanced Visualization:\n - Interactive HTML reports (e.g., using pyvis or bokeh).\n - Highlighting specific nodes or paths on the graph.\n - Grouping nodes by package or defined layer.\n- Plugin for popular IDEs (VSCode, PyCharm).\n- CI/CD Integration: Output results in CI-friendly formats (e.g., JUnit XML), allow setting metric thresholds.\n- Improved Import Resolution:\n - Better handling of __all__ for more accurate analysis of from ... import *.\n - More precise import resolution considering sys.path modifications and namespace packages.\n\n## Contributing\n\nContributions are welcome to make NetImport better! If you'd like to help, please check out CONTRIBUTING.md for instructions on setting up your development environment, code style, and the process for submitting Pull Requests.\n\nKey areas for contribution:\n\n- Implementing new features from the Roadmap.\n- Improving the existing codebase (refactoring, optimization).\n- Writing tests.\n- Enhancing documentation.\n- Bug fixing.\n\nFeel free to open Issues to discuss new ideas or problems.\n\nLicense\n\nThis project is licensed under the MIT License (you'll need to create this file).\n\nCrafted with \u2764\ufe0f to help improve Python project architectures.",
"bugtrack_url": null,
"license": "MIT",
"summary": "NetImport: Python Project Architecture Analyzer via Import Graphs",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/beilak/netimport",
"Repository": "https://github.com/beilak/netimport"
},
"split_keywords": [
"python",
" architecture",
" linter",
" static analysis",
" import graph",
" dependencies",
" visualization",
" coupling",
" cohesion"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7837a23391100b414d140fb7fff12e3b47676bb5e6592e66c0de3123df7ffe01",
"md5": "7705e6580fe1be2e4dfe3200c4ac1359",
"sha256": "26d9f538d091327e4c897e0df3378d6ddba7b4063af2be5f6996414e0f067991"
},
"downloads": -1,
"filename": "netimport-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7705e6580fe1be2e4dfe3200c4ac1359",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23890,
"upload_time": "2025-08-07T22:34:54",
"upload_time_iso_8601": "2025-08-07T22:34:54.304753Z",
"url": "https://files.pythonhosted.org/packages/78/37/a23391100b414d140fb7fff12e3b47676bb5e6592e66c0de3123df7ffe01/netimport-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8443c05cf923e549350161c459f294a03d5a772e4fcdf2eeb5d1a7cf87193f7d",
"md5": "7fcba73d6cce42c3771405ef1330999e",
"sha256": "711dfb2f1f8c83eadc04e9e23bdfa6bfd000ec02338e194a3f73626133a030f7"
},
"downloads": -1,
"filename": "netimport-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "7fcba73d6cce42c3771405ef1330999e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 20349,
"upload_time": "2025-08-07T22:34:55",
"upload_time_iso_8601": "2025-08-07T22:34:55.336784Z",
"url": "https://files.pythonhosted.org/packages/84/43/c05cf923e549350161c459f294a03d5a772e4fcdf2eeb5d1a7cf87193f7d/netimport-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 22:34:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "beilak",
"github_project": "netimport",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "netimport"
}
JSON
