Metadata-Version: 2.4
Name: startype23
Version: 1.9.0
Summary: A CLI tool that analyzes a directory and displays a colourful chart of file type distribution.
Project-URL: Homepage, https://github.com/kifreya/startype23
Project-URL: Source, https://github.com/kifreya/startype23
Project-URL: Bug tracker, https://github.com/kifreya/startype23/issues
Author-email: StarType23 <charts@startype23.dev>
License: MIT
License-File: LICENSE
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

![StarType23 screenshot](src/media/powershell_screenshot.png)

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).
- Custom colour palette support via ``--colors`` (inline hex codes or file).

## Installation

```bash
uv tool install startype23
# or via pip:
pip install startype23
```

After installation, both `startype23` and `st23` are available globally.

## Usage

```
startype23 (or st23)                    scan current directory
startype23 --size                       scan by disk size
startype23 --path /some/dir             scan a specific directory
startype23 --include-hidden             include dotfiles
startype23 --explain .py                look up an extension
startype23 --explain py                 leading dot is optional
startype23 --exclude build              skip extra directories
startype23 --count --percentage         show only selected columns
startype23 --colors FF0000 --colors 00FF00   custom colours
startype23 --colors "#FF0000,#00FF00"       comma-separated in one string
startype23 --colors /path/to/colors.txt     load from file
startype23 --filter ".py,.md"              show only certain file types
startype23 --interactive                   build flags in a REPL
```

| 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              |
| `--colors`                 | Hex colour codes, one per flag, comma/space/semicolon/colon separated, or path to a colour file |
| `--borderless`             | Render tables without outer borders              |
| `--filter`                 | Show only matching extensions (comma, period, colon, semicolon, newline separated) |
| `--interactive`            | Launch interactive REPL mode for building flags  |

When no column flags are given, all columns show.  When one or more are
given, only those (plus Extension) are shown.

Custom colours can be provided inline or via a text file. The ``#`` prefix is
optional. If fewer colours are given than file types found, the tool falls
back to the built-in palette and prints a warning.  A default colour file at
``$HOME/.config/startype23/colors.txt`` is loaded automatically if no
``--colors`` flag is given.

### Interactive mode

``--interactive`` opens a REPL where flags are toggled one at a time, then
``run`` executes the scan.  Type ``help`` within the REPL for available
commands.

## 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.

