codetree-cli 0.2.2__tar.gz → 0.3.0__tar.gz

codetree_cli-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reza Mardani
+
+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.

codetree_cli-0.3.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: codetree-cli
+Version: 0.3.0
+Summary: See your codebase as a living, animated tree: lines of code, comments and languages per folder and file.
+Home-page: https://github.com/rezamardani01/codetree
+Author: Reza Mardani
+Author-email: mardanireza30@gmail.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Environment :: X11 Applications
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Topic :: Software Development
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+Dynamic: summary
+
+<div align="center">
+
+# 🌳 CodeTree
+
+**See your codebase as a living, animated tree.**
+
+Folders grow into branches, files bloom as leaves — sized by lines of code, colored by language.
+
+[![PyPI](https://img.shields.io/pypi/v/codetree-cli?color=3b9eff&label=PyPI)](https://pypi.org/project/codetree-cli/)
+[![Python](https://img.shields.io/badge/python-3.8%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-3fb950)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-8b949e)](#installation)
+[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](#why-codetree)
+
+<img src="https://raw.githubusercontent.com/rezamardani01/codetree/main/docs/screenshot.png" alt="CodeTree showing the Python standard library as a radial tree" width="900">
+
+</div>
+
+---
+
+## Why CodeTree?
+
+Line counters give you a table. CodeTree gives you a **map**: you instantly see which folders are heavy, which files dominate, and how comments, blank lines and code are balanced — and you can explore it by clicking, zooming and searching.
+
+- 🌱 **A tree, not a table** — an animated radial tree that grows from the trunk outward.
+- 🎨 **Language-aware** — 40+ languages detected, every line classified as *code*, *comment* or *blank*.
+- ⚡ **Fast** — scans thousands of files in a couple of seconds, in the background, with a live progress view.
+- 🧰 **Zero dependencies** — pure Python standard library (Tkinter for the GUI).
+- 🖥️ **GUI by default, terminal when you need it** — scriptable with JSON / CSV / Markdown export.
+
+## Installation
+
+```bash
+pip install codetree-cli
+```
+
+From source:
+
+```bash
+git clone https://github.com/rezamardani01/codetree.git
+cd codetree
+pip install .
+```
+
+> Requires Python 3.8+. The GUI uses Tkinter, which ships with the official Python installers
+> (on some Linux distributions install it with e.g. `sudo apt install python3-tk`).
+
+## Usage
+
+```bash
+codetree                  # open the GUI on the current folder
+codetree path/to/project  # open the GUI on a specific folder
+codetree-gui              # same, without a console window on Windows
+```
+
+### In the window
+
+| Action | What it does |
+|---|---|
+| **Click a folder** | Grow or fold its branch (animated) |
+| **Drag / mouse wheel** | Pan / zoom |
+| **Hover a node** | Highlights its path to the trunk and shows lines, code/comment/blank split, size and share of the project |
+| **Double-click a file** | Opens it in your default editor |
+| **Right-click** | Open, show in folder, copy path |
+| **Search box** | Prunes the tree to matching files and folders |
+| **Click a language** | Lights up all leaves written in it |
+| **Click a file in "Largest files"** | Flies the camera to that leaf |
+| **Expand all · Collapse · Fit view** | Overview controls |
+| **Theme · Export** | Dark/light theme, export JSON / CSV / Markdown |
+
+Shortcuts: `F5` rescan · `Ctrl+O` browse · `Ctrl+F` search · `Ctrl+E` export JSON · `Esc` clear search.
+
+### Reading the tree
+
+- **Trunk** (center) = the project root.
+- **Branches / green nodes** = folders. Thicker branch = more lines. The number on a folded node is how many items it hides.
+- **Leaves** = files, arranged in a sunflower pattern at the end of their branch. **Bigger leaf = more lines. Color = language.**
+
+### Terminal mode
+
+```bash
+codetree --cli                          # tree + language table + summary
+codetree --cli --depth 2 --sort lines   # limit depth, biggest first
+codetree --cli --top 10                 # also list the 10 largest files
+codetree -e py -e js -i "*.min.js"      # only these extensions, ignore a pattern
+codetree --json report.json             # write reports (use - for stdout)
+codetree --csv report.csv --md report.md
+```
+
+| Option | Description |
+|---|---|
+| `--cli` | Print to the terminal instead of opening the GUI |
+| `--json / --csv / --md FILE` | Export a report (implies `--cli`) |
+| `-i, --ignore PATTERN` | Glob to ignore, repeatable |
+| `-e, --ext EXT` | Only count these extensions, repeatable |
+| `--hidden` | Include hidden files and folders |
+| `--no-gitignore` | Do not read `.gitignore` |
+| `--no-default-ignores` | Do not skip `node_modules`, `venv`, `build`, … |
+| `--max-size MB` | Skip files larger than this (default 5) |
+| `--sort name\|lines\|code`, `--depth N`, `--top N` | Terminal tree options |
+| `--no-color` | Disable colors |
+| `-V, --version` | Show the version |
+
+If the GUI cannot start (for example over SSH without a display), CodeTree automatically falls back to terminal output.
+
+### Use it as a library
+
+```python
+from codetree.core import scan, ScanOptions
+
+result = scan(".", ScanOptions(extensions=["py"], ignore=["tests"]))
+print(result.total_files, result.total_lines)
+for lang in result.languages.values():
+    print(lang.name, lang.code, lang.comment, lang.blank)
+```
+
+## What gets counted
+
+- Hidden files and folders are skipped (enable with `--hidden` / the *Hidden files* checkbox).
+- `node_modules`, `venv`, `__pycache__`, `dist`, `build`, `.git`, lock files and similar noise are skipped by default.
+- Patterns in the project's root `.gitignore` are respected.
+- Binary files and files over 5 MB are skipped; everything else is read as UTF‑8 with a lenient fallback.
+
+## Development
+
+```bash
+git clone https://github.com/rezamardani01/codetree.git
+cd codetree
+python -m unittest discover -s tests -t .
+python -m codetree .          # run from source
+```
+
+Project layout:
+
+```
+codetree/
+├── core.py   # scanner, language table, line classification, exporters
+├── cli.py    # command line interface
+├── gui.py    # animated Tkinter tree
+└── tests/
+```
+
+## Contributing
+
+Contributions are welcome! Fork the repository, create a branch, add tests for your change and open a pull request. Ideas, bug reports and new language definitions are all appreciated — please open an issue first for larger changes.
+
+## License
+
+Released under the [MIT License](LICENSE) © Reza Mardani.

codetree_cli-0.3.0/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+
+# 🌳 CodeTree
+
+**See your codebase as a living, animated tree.**
+
+Folders grow into branches, files bloom as leaves — sized by lines of code, colored by language.
+
+[![PyPI](https://img.shields.io/pypi/v/codetree-cli?color=3b9eff&label=PyPI)](https://pypi.org/project/codetree-cli/)
+[![Python](https://img.shields.io/badge/python-3.8%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-3fb950)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-8b949e)](#installation)
+[![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)](#why-codetree)
+
+<img src="https://raw.githubusercontent.com/rezamardani01/codetree/main/docs/screenshot.png" alt="CodeTree showing the Python standard library as a radial tree" width="900">
+
+</div>
+
+---
+
+## Why CodeTree?
+
+Line counters give you a table. CodeTree gives you a **map**: you instantly see which folders are heavy, which files dominate, and how comments, blank lines and code are balanced — and you can explore it by clicking, zooming and searching.
+
+- 🌱 **A tree, not a table** — an animated radial tree that grows from the trunk outward.
+- 🎨 **Language-aware** — 40+ languages detected, every line classified as *code*, *comment* or *blank*.
+- ⚡ **Fast** — scans thousands of files in a couple of seconds, in the background, with a live progress view.
+- 🧰 **Zero dependencies** — pure Python standard library (Tkinter for the GUI).
+- 🖥️ **GUI by default, terminal when you need it** — scriptable with JSON / CSV / Markdown export.
+
+## Installation
+
+```bash
+pip install codetree-cli
+```
+
+From source:
+
+```bash
+git clone https://github.com/rezamardani01/codetree.git
+cd codetree
+pip install .
+```
+
+> Requires Python 3.8+. The GUI uses Tkinter, which ships with the official Python installers
+> (on some Linux distributions install it with e.g. `sudo apt install python3-tk`).
+
+## Usage
+
+```bash
+codetree                  # open the GUI on the current folder
+codetree path/to/project  # open the GUI on a specific folder
+codetree-gui              # same, without a console window on Windows
+```
+
+### In the window
+
+| Action | What it does |
+|---|---|
+| **Click a folder** | Grow or fold its branch (animated) |
+| **Drag / mouse wheel** | Pan / zoom |
+| **Hover a node** | Highlights its path to the trunk and shows lines, code/comment/blank split, size and share of the project |
+| **Double-click a file** | Opens it in your default editor |
+| **Right-click** | Open, show in folder, copy path |
+| **Search box** | Prunes the tree to matching files and folders |
+| **Click a language** | Lights up all leaves written in it |
+| **Click a file in "Largest files"** | Flies the camera to that leaf |
+| **Expand all · Collapse · Fit view** | Overview controls |
+| **Theme · Export** | Dark/light theme, export JSON / CSV / Markdown |
+
+Shortcuts: `F5` rescan · `Ctrl+O` browse · `Ctrl+F` search · `Ctrl+E` export JSON · `Esc` clear search.
+
+### Reading the tree
+
+- **Trunk** (center) = the project root.
+- **Branches / green nodes** = folders. Thicker branch = more lines. The number on a folded node is how many items it hides.
+- **Leaves** = files, arranged in a sunflower pattern at the end of their branch. **Bigger leaf = more lines. Color = language.**
+
+### Terminal mode
+
+```bash
+codetree --cli                          # tree + language table + summary
+codetree --cli --depth 2 --sort lines   # limit depth, biggest first
+codetree --cli --top 10                 # also list the 10 largest files
+codetree -e py -e js -i "*.min.js"      # only these extensions, ignore a pattern
+codetree --json report.json             # write reports (use - for stdout)
+codetree --csv report.csv --md report.md
+```
+
+| Option | Description |
+|---|---|
+| `--cli` | Print to the terminal instead of opening the GUI |
+| `--json / --csv / --md FILE` | Export a report (implies `--cli`) |
+| `-i, --ignore PATTERN` | Glob to ignore, repeatable |
+| `-e, --ext EXT` | Only count these extensions, repeatable |
+| `--hidden` | Include hidden files and folders |
+| `--no-gitignore` | Do not read `.gitignore` |
+| `--no-default-ignores` | Do not skip `node_modules`, `venv`, `build`, … |
+| `--max-size MB` | Skip files larger than this (default 5) |
+| `--sort name\|lines\|code`, `--depth N`, `--top N` | Terminal tree options |
+| `--no-color` | Disable colors |
+| `-V, --version` | Show the version |
+
+If the GUI cannot start (for example over SSH without a display), CodeTree automatically falls back to terminal output.
+
+### Use it as a library
+
+```python
+from codetree.core import scan, ScanOptions
+
+result = scan(".", ScanOptions(extensions=["py"], ignore=["tests"]))
+print(result.total_files, result.total_lines)
+for lang in result.languages.values():
+    print(lang.name, lang.code, lang.comment, lang.blank)
+```
+
+## What gets counted
+
+- Hidden files and folders are skipped (enable with `--hidden` / the *Hidden files* checkbox).
+- `node_modules`, `venv`, `__pycache__`, `dist`, `build`, `.git`, lock files and similar noise are skipped by default.
+- Patterns in the project's root `.gitignore` are respected.
+- Binary files and files over 5 MB are skipped; everything else is read as UTF‑8 with a lenient fallback.
+
+## Development
+
+```bash
+git clone https://github.com/rezamardani01/codetree.git
+cd codetree
+python -m unittest discover -s tests -t .
+python -m codetree .          # run from source
+```
+
+Project layout:
+
+```
+codetree/
+├── core.py   # scanner, language table, line classification, exporters
+├── cli.py    # command line interface
+├── gui.py    # animated Tkinter tree
+└── tests/
+```
+
+## Contributing
+
+Contributions are welcome! Fork the repository, create a branch, add tests for your change and open a pull request. Ideas, bug reports and new language definitions are all appreciated — please open an issue first for larger changes.
+
+## License
+
+Released under the [MIT License](LICENSE) © Reza Mardani.

codetree_cli-0.3.0/codetree/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

codetree_cli-0.3.0/codetree/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

codetree_cli-0.3.0/codetree/cli.py

@@ -0,0 +1,164 @@
+"""Command line entry point. Opens the GUI by default; ``--cli`` prints to the terminal."""
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .core import (DirNode, ScanOptions, ScanResult, format_size, scan, sorted_languages,
+                   to_csv, to_json, to_markdown)
+
+SORT_KEYS = {
+    "name": lambda n: n.name.lower(),
+    "lines": lambda n: -n.total,
+    "code": lambda n: -n.code,
+}
+
+
+class _Style:
+    def __init__(self, enabled: bool):
+        self.on = enabled
+
+    def __call__(self, text, code):
+        return f"\033[{code}m{text}\033[0m" if self.on else str(text)
+
+
+def _print_tree(node: DirNode, c: _Style, sort: str, depth: int, prefix: str = "", level: int = 0) -> None:
+    key = SORT_KEYS[sort]
+    items = [("d", d) for d in sorted(node.dirs, key=key)] + [("f", f) for f in sorted(node.files, key=key)]
+    for i, (kind, item) in enumerate(items):
+        last = i == len(items) - 1
+        branch = "└── " if last else "├── "
+        if kind == "d":
+            print(f"{prefix}{branch}{c(item.name + '/', '1;34')}  {c(f'{item.total:,} lines', '90')}")
+            if depth <= 0 or level + 1 < depth:
+                _print_tree(item, c, sort, depth, prefix + ("    " if last else "│   "), level + 1)
+        else:
+            print(f"{prefix}{branch}{item.name}  {c(f'{item.total:,} lines', '32')}"
+                  f" {c('(' + item.language + ')', '90')}")
+
+
+def _print_report(result: ScanResult, args, c: _Style) -> None:
+    print(c(f"\n{result.root.name}/", "1;36"))
+    _print_tree(result.root, c, args.sort, args.depth)
+
+    langs = sorted_languages(result)
+    if langs:
+        print(c("\nLanguages", "1"))
+        width = max(len(l.name) for l in langs)
+        total = result.total_lines or 1
+        print(f"  {'Language'.ljust(width)}  {'Files':>6} {'Code':>9} {'Comment':>9} {'Blank':>9} {'Share':>7}")
+        for l in langs:
+            bar = "█" * max(1, round(l.total / total * 20))
+            print(f"  {l.name.ljust(width)}  {l.files:>6} {l.code:>9,} {l.comment:>9,} {l.blank:>9,} "
+                  f"{l.total / total:>6.1%} {c(bar, '36')}")
+
+    if args.top:
+        print(c(f"\nTop {args.top} largest files", "1"))
+        for f in sorted(result.files, key=lambda f: f.total, reverse=True)[: args.top]:
+            print(f"  {f.total:>8,}  {os.path.relpath(f.path, result.root.path)}")
+
+    r = result.root
+    print(c("\nSummary", "1"))
+    print(f"  Files:    {r.file_count:,}")
+    print(f"  Folders:  {result.folder_count:,}")
+    print(f"  Lines:    {r.total:,}  (code {r.code:,} · comments {r.comment:,} · blank {r.blank:,})")
+    print(f"  Size:     {format_size(r.size)}")
+    print(f"  Time:     {result.elapsed:.2f}s")
+    if result.skipped_binary or result.skipped_large:
+        print(c(f"  Skipped:  {result.skipped_binary} binary, {result.skipped_large} too large", "90"))
+    for err in result.errors[:5]:
+        print(c(f"  ! {err}", "33"), file=sys.stderr)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="codetree",
+        description="Analyze a project's lines of code. Opens a graphical window by default.")
+    p.add_argument("path", nargs="?", default=".", help="project directory (default: current directory)")
+    p.add_argument("--cli", action="store_true", help="print the report in the terminal instead of opening the GUI")
+    p.add_argument("--json", metavar="FILE", help="write a JSON report ('-' for stdout); implies --cli")
+    p.add_argument("--csv", metavar="FILE", help="write a CSV report ('-' for stdout); implies --cli")
+    p.add_argument("--md", metavar="FILE", help="write a Markdown report ('-' for stdout); implies --cli")
+    p.add_argument("-i", "--ignore", action="append", default=[], metavar="PATTERN",
+                   help="glob pattern to ignore (repeatable), e.g. -i '*.min.js' -i tests")
+    p.add_argument("-e", "--ext", action="append", default=[], metavar="EXT",
+                   help="only count these extensions (repeatable), e.g. -e py -e js")
+    p.add_argument("--hidden", action="store_true", help="include hidden files and folders")
+    p.add_argument("--no-gitignore", action="store_true", help="do not read .gitignore")
+    p.add_argument("--no-default-ignores", action="store_true", help="do not skip node_modules, venv, build, ...")
+    p.add_argument("--max-size", type=float, default=5, metavar="MB", help="skip files larger than this (default 5)")
+    p.add_argument("--sort", choices=sorted(SORT_KEYS), default="name", help="tree sort order (CLI)")
+    p.add_argument("--depth", type=int, default=0, help="limit tree depth, 0 = unlimited (CLI)")
+    p.add_argument("--top", type=int, default=0, metavar="N", help="list the N largest files (CLI)")
+    p.add_argument("--no-color", action="store_true", help="disable colored output")
+    p.add_argument("-V", "--version", action="version", version=f"codetree {__version__}")
+    return p
+
+
+def _emit(target: str, text: str) -> None:
+    if target == "-":
+        sys.stdout.write(text)
+    else:
+        with open(target, "w", encoding="utf-8", newline="") as fh:
+            fh.write(text)
+        print(f"Saved {target}", file=sys.stderr)
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    path = os.path.abspath(args.path)
+    if not os.path.isdir(path):
+        print(f"codetree: '{args.path}' is not a directory.", file=sys.stderr)
+        return 2
+
+    options = ScanOptions(
+        include_hidden=args.hidden,
+        use_default_ignores=not args.no_default_ignores,
+        respect_gitignore=not args.no_gitignore,
+        ignore=args.ignore,
+        extensions=args.ext,
+        max_size=int(args.max_size * 1024 * 1024),
+    )
+
+    exports = [(args.json, to_json), (args.csv, to_csv), (args.md, to_markdown)]
+    wants_cli = args.cli or any(t for t, _ in exports)
+
+    if not wants_cli:
+        try:
+            from .gui import run_gui
+        except ImportError as e:
+            print(f"codetree: GUI unavailable ({e}); falling back to terminal output.", file=sys.stderr)
+        else:
+            try:
+                run_gui(path, options)
+                return 0
+            except Exception as e:  # e.g. no display
+                print(f"codetree: could not open the GUI ({e}); falling back to terminal output.", file=sys.stderr)
+
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    try:
+        result = scan(path, options)
+    except KeyboardInterrupt:
+        return 130
+    stdout_taken = any(t == "-" for t, _ in exports)
+    for target, fn in exports:
+        if target:
+            _emit(target, fn(result))
+    if not stdout_taken:
+        color = not args.no_color and sys.stdout.isatty() and "NO_COLOR" not in os.environ
+        if color and os.name == "nt":
+            os.system("")  # enable ANSI escapes on Windows consoles
+        _print_report(result, args, _Style(color))
+    return 0
+
+
+def main_gui() -> int:
+    """Entry point for the ``codetree-gui`` launcher (no console window on Windows)."""
+    return main(sys.argv[1:] if len(sys.argv) > 1 else ["."])
+
+
+if __name__ == "__main__":
+    sys.exit(main())