startype23 1.0.0__tar.gz

startype23-1.0.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: startype23
+Version: 1.0.0
+Summary: A CLI tool that analyzes a directory and displays a colourful chart of file type distribution.
+Project-URL: Homepage, https://github.com/startype23/startype23
+Project-URL: Source, https://github.com/startype23/startype23
+Project-URL: Bug tracker, https://github.com/startype23/startype23/issues
+Author-email: StarType23 <charts@startype23.dev>
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# StarType23
+
+A CLI tool that walks a directory, counts files by extension, and renders a
+colourful file-type distribution chart in the terminal.
+
+## Features
+
+- Scans recursively and groups files by extension (count and disk size).
+- Renders a stacked proportion bar + a table with coloured mini bars.
+- Two modes: by **count** (`startype23`) or by **size** (`startype23 --size`).
+- Built-in lookup table of ~500 extensions with file-type category and
+  one-line description (`--explain .py`).
+- Column visibility toggles: `--filetype`, `--count`, `--percentage`,
+  `--distribution`.
+- Skips `.git`, `.venv`, `node_modules`, `__pycache__`, and similar by
+  default.
+- Flat-design pastel colour palette (no neon).
+
+## Usage
+
+```
+uv run startype23                         scan current directory
+uv run startype23 --size                  scan by disk size
+uv run startype23 --path /some/dir        scan a specific directory
+uv run startype23 --include-hidden        include dotfiles
+uv run startype23 --explain .py           look up an extension
+uv run startype23 --explain py            leading dot is optional
+uv run startype23 --exclude build         skip extra directories
+uv run startype23 --count --percentage    show only selected columns
+```
+
+| Flag                       | Description                                   |
+|----------------------------|-----------------------------------------------|
+| `--path`                   | Directory to scan (default: `.`)              |
+| `--exclude` / `-x`         | Extra directory names to skip (repeatable)    |
+| `--include-hidden`         | Include dotfiles in the scan                  |
+| `--no-include-hidden`      | Exclude dotfiles (default)                    |
+| `--explain` / `-e`         | Look up an extension and show its description |
+| `--size` / `-s`            | Size distribution instead of count            |
+| `--filetype` / `-ft`       | Show the File Type column                     |
+| `--count` / `-c`           | Show the Count column                         |
+| `--percentage` / `-p`      | Show the Percentage column                    |
+| `--distribution` / `-d`    | Show the Distribution bar column              |
+
+When no column flags are given, all columns show.  When one or more are
+given, only those (plus Extension) are shown.
+
+## Tools used to build this project
+
+- **Python 3.10+** -- language runtime.
+- **uv** -- package and project manager (install, build, publish).
+- **click** -- CLI framework (arguments, options, help).
+- **rich** -- terminal styling (tables, colours, text formatting).
+- **hatchling** -- build backend (PEP 517).
+- **Wikipedia's List of filename extensions** -- source for the ~500-entry
+  extension lookup table.
+
+## Publishing
+
+```bash
+uv build
+uv publish --token pypi-xxxxxxxx
+```

startype23-1.0.0/README.md

@@ -0,0 +1,63 @@
+# StarType23
+
+A CLI tool that walks a directory, counts files by extension, and renders a
+colourful file-type distribution chart in the terminal.
+
+## Features
+
+- Scans recursively and groups files by extension (count and disk size).
+- Renders a stacked proportion bar + a table with coloured mini bars.
+- Two modes: by **count** (`startype23`) or by **size** (`startype23 --size`).
+- Built-in lookup table of ~500 extensions with file-type category and
+  one-line description (`--explain .py`).
+- Column visibility toggles: `--filetype`, `--count`, `--percentage`,
+  `--distribution`.
+- Skips `.git`, `.venv`, `node_modules`, `__pycache__`, and similar by
+  default.
+- Flat-design pastel colour palette (no neon).
+
+## Usage
+
+```
+uv run startype23                         scan current directory
+uv run startype23 --size                  scan by disk size
+uv run startype23 --path /some/dir        scan a specific directory
+uv run startype23 --include-hidden        include dotfiles
+uv run startype23 --explain .py           look up an extension
+uv run startype23 --explain py            leading dot is optional
+uv run startype23 --exclude build         skip extra directories
+uv run startype23 --count --percentage    show only selected columns
+```
+
+| Flag                       | Description                                   |
+|----------------------------|-----------------------------------------------|
+| `--path`                   | Directory to scan (default: `.`)              |
+| `--exclude` / `-x`         | Extra directory names to skip (repeatable)    |
+| `--include-hidden`         | Include dotfiles in the scan                  |
+| `--no-include-hidden`      | Exclude dotfiles (default)                    |
+| `--explain` / `-e`         | Look up an extension and show its description |
+| `--size` / `-s`            | Size distribution instead of count            |
+| `--filetype` / `-ft`       | Show the File Type column                     |
+| `--count` / `-c`           | Show the Count column                         |
+| `--percentage` / `-p`      | Show the Percentage column                    |
+| `--distribution` / `-d`    | Show the Distribution bar column              |
+
+When no column flags are given, all columns show.  When one or more are
+given, only those (plus Extension) are shown.
+
+## Tools used to build this project
+
+- **Python 3.10+** -- language runtime.
+- **uv** -- package and project manager (install, build, publish).
+- **click** -- CLI framework (arguments, options, help).
+- **rich** -- terminal styling (tables, colours, text formatting).
+- **hatchling** -- build backend (PEP 517).
+- **Wikipedia's List of filename extensions** -- source for the ~500-entry
+  extension lookup table.
+
+## Publishing
+
+```bash
+uv build
+uv publish --token pypi-xxxxxxxx
+```

startype23-1.0.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "startype23"
+version = "1.0.0"
+description = "A CLI tool that analyzes a directory and displays a colourful chart of file type distribution."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "StarType23", email = "charts@startype23.dev" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Topic :: System :: Filesystems",
+]
+dependencies = [
+    "click>=8.1.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/startype23/startype23"
+Source = "https://github.com/startype23/startype23"
+"Bug tracker" = "https://github.com/startype23/startype23/issues"
+
+[project.scripts]
+startype23 = "startype23.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = []

startype23-1.0.0/src/startype23/__init__.py

@@ -0,0 +1,3 @@
+"""StarType23 -- A CLI tool for colourful file type distribution charts."""
+
+__version__ = "1.0.0"

startype23-1.0.0/src/startype23/analyzer.py

@@ -0,0 +1,131 @@
+"""Directory traversal and file extension aggregation."""
+
+import os
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+# Default directory names to skip during traversal.
+DEFAULT_EXCLUDE_DIRS: set[str] = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    "__pycache__",
+    "node_modules",
+    ".idea",
+    ".vscode",
+    ".DS_Store",
+}
+
+
+@dataclass
+class FileTypeInfo:
+    """Aggregated statistics for a single file extension."""
+
+    extension: str
+    count: int
+    total_size: int = 0
+    percentage: float = 0.0
+    size_percentage: float = 0.0
+
+
+def scan_directory(
+    path: str = ".",
+    exclude_dirs: set[str] | None = None,
+    include_hidden: bool = False,
+) -> list[FileTypeInfo]:
+    """Walk *path* and aggregate file counts by extension.
+
+    Parameters
+    ----------
+    path : str
+        Root directory to scan (defaults to current working directory).
+    exclude_dirs : set[str] or None
+        Directory names to skip.  When ``None``, the built-in
+        ``DEFAULT_EXCLUDE_DIRS`` set is used.
+    include_hidden : bool
+        If ``False``, files whose name starts with ``"."`` and directories
+        that have a leading dot are ignored.
+
+    Returns
+    -------
+    list[FileTypeInfo]
+        Sorted list (descending by count) of extension statistics.
+    """
+    root = Path(path).resolve()
+    if not root.is_dir():
+        raise NotADirectoryError(f"Not a directory: {root}")
+
+    if exclude_dirs is None:
+        exclude_dirs = DEFAULT_EXCLUDE_DIRS
+
+    counter: Counter[str] = Counter()
+    size_map: dict[str, int] = {}
+
+    for dirpath_str, dirnames, filenames in os.walk(root):
+        dirpath = Path(dirpath_str)
+
+        # Filter out directories we should skip.
+        dirnames[:] = [
+            d
+            for d in dirnames
+            if d not in exclude_dirs and (include_hidden or not d.startswith("."))
+        ]
+
+        for filename in filenames:
+            if not include_hidden and filename.startswith("."):
+                continue
+
+            ext = _extract_extension(filename)
+            counter[ext] += 1
+
+            try:
+                filepath = dirpath / filename
+                size_map[ext] = size_map.get(ext, 0) + filepath.stat().st_size
+            except OSError:
+                pass
+
+    total_files = sum(counter.values())
+    total_size_all = sum(size_map.values())
+
+    if total_files == 0:
+        return []
+
+    results: list[FileTypeInfo] = []
+    for ext, count in counter.most_common():
+        sz = size_map.get(ext, 0)
+        info = FileTypeInfo(
+            extension=ext,
+            count=count,
+            total_size=sz,
+            percentage=round((count / total_files) * 100, 1),
+            size_percentage=round((sz / total_size_all) * 100, 1)
+            if total_size_all
+            else 0.0,
+        )
+        results.append(info)
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_extension(filename: str) -> str:
+    """Return the lowercase file extension including the leading dot.
+
+    Files without an extension are grouped under the label ``"[no extension]"``.
+    Files consisting solely of an extension (e.g. ``".gitignore"``) are treated
+    as having no extension.
+    """
+    name, dot, ext = filename.rpartition(".")
+    if dot and name:
+        return f".{ext.lower()}"
+    return "[no extension]"