lsum 0.1.0__tar.gz

lsum-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: lsum
+Version: 0.1.0
+Summary: Directory summary tool
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.3.2
+Requires-Dist: flit-core>=3.12.0
+Requires-Dist: pathspec>=0.12.1
+Requires-Dist: python-magic>=0.4.27
+Requires-Dist: rich>=15.0.0
+
+# 📂 lsum
+
+[![PyPI version](https://img.shields.io/pypi/v/lsum.svg?color=blue)](https://pypi.org/project/lsum/)
+[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+**lsum** (List Summary) is a high-performance, visually rich CLI directory analysis tool that transforms standard file listings into actionable intelligence.
+
+---
+
+### ⚡ TL;DR
+
+`lsum` is `ls` on steroids. It doesn't just list files; it **categorizes**, **counts**, and **visualizes** your directory's distribution by MIME types, extensions, and metadata—all while respecting your `.gitignore` rules.
+
+---
+
+### 🤔 Why lsum?
+
+Standard tools like `ls` or `tree` are great for finding files, but they fail to answer higher-level questions about your workspace. `lsum` was built to fill that gap:
+
+* **Audit Your Assets:** Instantly see how many gigabytes of images vs. text files you have.
+* **Visualize Structure:** Group files into elegant, color-coded panels based on their actual content (MIME) rather than just extensions.
+* **Clean Analysis:** Use the `--gitignore` flag to strip out `node_modules`, build artifacts, and logs, focusing only on the code that matters.
+* **Recursive Intelligence:** Understand the composition of entire project trees in a single, formatted view.
+
+---
+
+### 🚀 Installation
+
+#### 📦 From PyPI (Recommended)
+
+Install using [uv](https://github.com/astral-sh/uv) for the best experience:
+
+```bash
+uv tool install lsum
+```
+
+Or with standard pip:
+
+```bash
+pip install lsum
+```
+
+#### 🛠️ Building From Source
+
+Perfect for developers who want the latest features:
+
+```bash
+# Clone the repository
+git clone https://github.com/Debajyati/lsum.git
+cd lsum
+
+# Install dependencies and build
+uv pip install -e .
+```
+
+---
+
+### 🛠️ Usage Examples
+
+#### 1. Basic Listing
+
+A clean, tabular view of your current directory:
+
+```bash
+lsum
+```
+
+#### 2. Group by MIME Type (with Icons)
+
+See your files grouped by their actual content type (e.g., Image, Video, Text):
+
+```bash
+lsum --group
+```
+
+#### 3. Respect Gitignore
+
+Exclude build artifacts and ignored files for a "clean" summary:
+
+```bash
+lsum . --gitignore --count
+```
+
+#### 4. Recursive Extension Summary
+
+Analyze every file in your project tree, grouped by extension:
+
+```bash
+lsum . --recursive --group-extension
+```
+
+#### 5. Advanced Sorting & Filtering
+
+Find all `.txt` files and sort them by size:
+
+```bash
+lsum --filter-extension .txt --sort size
+```
+
+---
+
+### ⌨️ CLI Options
+
+| Option              | Shorthand | Description                                          |
+|:------------------- |:--------- |:---------------------------------------------------- |
+| `--count`           | `-c`      | Count files/directories in groups or total.          |
+| `--group`           | `-g`      | Group files by MIME type.                            |
+| `--group-extension` | `-ge`     | Group files by file extension.                       |
+| `--gitignore`       | `-gi`     | Respect `.gitignore` rules (excludes ignored files). |
+| `--recursive`       | `-r`      | Perform operations on all subdirectories.            |
+| `--sort`            | `-s`      | Sort by `name`, `size`, or `date`.                   |
+| `--filter`          | `-f`      | Filter by a specific MIME type (e.g., `image/jpeg`). |
+
+---
+
+### 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+*Built with ❤️ using Python and Rich.*
+

lsum-0.1.0/README.md

@@ -0,0 +1,124 @@
+# 📂 lsum
+
+[![PyPI version](https://img.shields.io/pypi/v/lsum.svg?color=blue)](https://pypi.org/project/lsum/)
+[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+**lsum** (List Summary) is a high-performance, visually rich CLI directory analysis tool that transforms standard file listings into actionable intelligence.
+
+---
+
+### ⚡ TL;DR
+
+`lsum` is `ls` on steroids. It doesn't just list files; it **categorizes**, **counts**, and **visualizes** your directory's distribution by MIME types, extensions, and metadata—all while respecting your `.gitignore` rules.
+
+---
+
+### 🤔 Why lsum?
+
+Standard tools like `ls` or `tree` are great for finding files, but they fail to answer higher-level questions about your workspace. `lsum` was built to fill that gap:
+
+* **Audit Your Assets:** Instantly see how many gigabytes of images vs. text files you have.
+* **Visualize Structure:** Group files into elegant, color-coded panels based on their actual content (MIME) rather than just extensions.
+* **Clean Analysis:** Use the `--gitignore` flag to strip out `node_modules`, build artifacts, and logs, focusing only on the code that matters.
+* **Recursive Intelligence:** Understand the composition of entire project trees in a single, formatted view.
+
+---
+
+### 🚀 Installation
+
+#### 📦 From PyPI (Recommended)
+
+Install using [uv](https://github.com/astral-sh/uv) for the best experience:
+
+```bash
+uv tool install lsum
+```
+
+Or with standard pip:
+
+```bash
+pip install lsum
+```
+
+#### 🛠️ Building From Source
+
+Perfect for developers who want the latest features:
+
+```bash
+# Clone the repository
+git clone https://github.com/Debajyati/lsum.git
+cd lsum
+
+# Install dependencies and build
+uv pip install -e .
+```
+
+---
+
+### 🛠️ Usage Examples
+
+#### 1. Basic Listing
+
+A clean, tabular view of your current directory:
+
+```bash
+lsum
+```
+
+#### 2. Group by MIME Type (with Icons)
+
+See your files grouped by their actual content type (e.g., Image, Video, Text):
+
+```bash
+lsum --group
+```
+
+#### 3. Respect Gitignore
+
+Exclude build artifacts and ignored files for a "clean" summary:
+
+```bash
+lsum . --gitignore --count
+```
+
+#### 4. Recursive Extension Summary
+
+Analyze every file in your project tree, grouped by extension:
+
+```bash
+lsum . --recursive --group-extension
+```
+
+#### 5. Advanced Sorting & Filtering
+
+Find all `.txt` files and sort them by size:
+
+```bash
+lsum --filter-extension .txt --sort size
+```
+
+---
+
+### ⌨️ CLI Options
+
+| Option              | Shorthand | Description                                          |
+|:------------------- |:--------- |:---------------------------------------------------- |
+| `--count`           | `-c`      | Count files/directories in groups or total.          |
+| `--group`           | `-g`      | Group files by MIME type.                            |
+| `--group-extension` | `-ge`     | Group files by file extension.                       |
+| `--gitignore`       | `-gi`     | Respect `.gitignore` rules (excludes ignored files). |
+| `--recursive`       | `-r`      | Perform operations on all subdirectories.            |
+| `--sort`            | `-s`      | Sort by `name`, `size`, or `date`.                   |
+| `--filter`          | `-f`      | Filter by a specific MIME type (e.g., `image/jpeg`). |
+
+---
+
+### 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+---
+
+*Built with ❤️ using Python and Rich.*

lsum-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "lsum"
+version = "0.1.0"
+description = "Directory summary tool"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "click>=8.3.2",
+    "flit-core>=3.12.0",
+    "pathspec>=0.12.1",
+    "python-magic>=0.4.27",
+    "rich>=15.0.0",
+]
+
+[project.scripts]
+lsum = "lsum.main:cli"
+
+[build-system]
+requires = ["flit_core<4"]
+build-backend = "flit_core.buildapi"
+

lsum-0.1.0/src/lsum/lib/constants.py

@@ -0,0 +1,39 @@
+colormap = {
+    "pdf": "red",
+    "ppt": "bright_red",
+    "pptx": "bright_red",
+    "vnd.openxmlformats-officedocument.presentationml.presentation": "bright_red",
+    "image": "green",
+    "doc": "blue",
+    "vnd.openxmlformats-officedocument.wordprocessingml.document": "blue",
+    "x-script.python": "bright_cyan",
+    "json": "yellow",
+    "javascript": "yellow",
+    "audio": "cyan",
+    "video": "magenta",
+    "plain": "white",
+    "csv": "bright_green",
+    "vnd.openxmlformats-officedocument.spreadsheetml.sheet": "green",
+    "zip": "bright_blue",
+    "exe": "bright_red",
+}
+
+MIME_TYPE_ICONS = {
+    "pdf": "📄",
+    "ppt": "📊",
+    "pptx": "📊",
+    "vnd.openxmlformats-officedocument.presentationml.presentation": "📊",
+    "image": "🖼️",
+    "doc": "📃",
+    "vnd.openxmlformats-officedocument.wordprocessingml.document": "📃",
+    "json": "🔧",
+    "audio": "🎵",
+    "video": "🎬",
+    "text": "📄",
+    "x-script.python": "🐍",
+    "javascript": "📜",
+    "csv": "📈",
+    "vnd.openxmlformats-officedocument.spreadsheetml.sheet": "📈",
+    "zip": "🗜️",
+    "exe": "⚙️",
+}

lsum-0.1.0/src/lsum/lib/ls.py

@@ -0,0 +1,620 @@
+import os
+from collections import Counter
+from .utils import assoclist, get_gitignore_matcher
+from rich import print
+from rich.table import Table
+from rich.panel import Panel
+from rich.columns import Columns
+from .mime import get_mime_type
+from .constants import MIME_TYPE_ICONS, colormap
+
+def count_files(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        dirs = 0
+        non_dirs = 0
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_dir():
+                    dirs += 1
+                else:
+                    non_dirs += 1
+        print(f"Directories: {dirs}")
+        print(f"Files: {non_dirs}")
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def list_files(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        dirs = []
+        non_dirs = []
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_dir():
+                    dirs.append(file.name)
+                else:
+                    non_dirs.append(file.name)
+        
+        dirlen = len(dirs)
+        non_dirlen = len(non_dirs)
+
+        if dirlen < non_dirlen:
+            dirs = dirs + [""] * (non_dirlen - dirlen)
+        elif non_dirlen < dirlen:
+            non_dirs = non_dirs + [""] * (dirlen - non_dirlen)
+
+        files_assoclist = assoclist(dirs, non_dirs)
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Listing",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="right")
+        table.add_column("Directories", style="bold blue underline", justify="left")
+        table.add_column("Files", style="bold green underline", justify="left")
+
+        index = 1
+        for first, second in files_assoclist.__iter__():
+            table.add_row(
+                str(index), f"{first}/" if len(first) else "", f"{second}"
+            )
+            index += 1
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def count_files_by_mime_type(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        mime_counts = Counter()
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file():
+                    mime_type = get_mime_type(file.path) or "Unknown MIME Type"
+                    mime_counts[mime_type] += 1
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} File Counts by MIME Type",
+            title_style="bold underline magenta",
+        )
+        table.add_column("MIME Type", style="bold red", justify="left")
+        table.add_column("Count", style="bold yellow", justify="right")
+
+        for mime, count in mime_counts.items():
+            table.add_row(mime, str(count))
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+# multibox layout with one box for each MIME type, and each box contains a list of files with that MIME type, and the box title is the MIME type and the count of files with that MIME type
+# use colormap and MIME_TYPE_ICONS to color the box title and add an icon to the box title based on the MIME type, if the MIME type is not in the colormap or MIME_TYPE_ICONS, use a default color and icon
+def group_files_by_mime_type(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        mime_groups = {}
+        with os.scandir(path) as entries:
+            for entry in entries:
+                if matcher and matcher.match_file(entry.name + ("/" if entry.is_dir() else "")):
+                    continue
+                if entry.is_file():
+                    mime_type = get_mime_type(entry.path) or "unknown/type"
+                    mime_groups.setdefault(mime_type, []).append(entry.name)
+
+        panels = []
+        for mime, files in mime_groups.items():
+            # Get the prefix (e.g., 'image' from 'image/jpeg')
+            prefix, suffix = mime.split("/")[0], mime.split("/")[1]
+            color = colormap.get(prefix, colormap.get(suffix, "white"))
+            icon = MIME_TYPE_ICONS.get(suffix, MIME_TYPE_ICONS.get(prefix, "📁"))
+
+            # 1. Join all files into one string first so they don't overwrite each other
+            file_list_str = "\n".join([f"[{color}]{f}[/{color}]" for f in files])
+
+            # 2. Create a Panel (the "Box") for this MIME type
+            box_title = f"{icon} {mime} ({len(files)})"
+            panels.append(Panel(file_list_str, title=box_title, border_style=color, expand=False))
+
+        # 3. Use Columns to display boxes side-by-side (or wrapped)
+        print(Columns(panels))
+
+    except FileNotFoundError:
+        print(f"[bold red]Error:[/bold red] Directory '{path}' not found.")
+    except PermissionError:
+        print(f"[bold red]Error:[/bold red] Permission denied for '{path}'.")
+
+def count_files_by_extension(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        extension_counts = Counter()
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file():
+                    ext = os.path.splitext(file.name)[1].lower() or "No Extension"
+                    extension_counts[ext] += 1
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} File Counts by Extension",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Extension", style="bold red", justify="left")
+        table.add_column("Count", style="bold yellow", justify="right")
+
+        for ext, count in extension_counts.items():
+            table.add_row(ext, str(count))
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def group_files_by_extension(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        extension_groups = {}
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file():
+                    ext = os.path.splitext(file.name)[1].lower() or "No Extension"
+                    extension_groups.setdefault(ext, []).append(file.path)
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Files Grouped by Extension",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="center")
+        table.add_column("Extension", style="bold red", justify="left")
+        table.add_column("Files", style="bold yellow", justify="left")
+
+        # when a new extension is encountered, print the first row with the extension with overline style, and subsequent rows with an empty extension column and no overline style
+        for ext, files in extension_groups.items():
+            first = True
+            index = 1
+            for file in files:
+                if first:
+                    table.add_row(f"{index}",ext, file)
+                    first = False
+                    index += 1
+                else:
+                    table.add_row(f"{index}","", file)
+                    index += 1
+            table.add_row("")  # add an empty row after each extension group for better readability
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def recursive_list_files(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Recursive Listing",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="right")
+        table.add_column("Path", style="bold cyan", justify="left")
+
+        index = 1
+        for root, dirs, files in os.walk(path):
+            if matcher:
+                rel_root = os.path.relpath(root, path)
+                if rel_root == ".":
+                    rel_root = ""
+                dirs[:] = [d for d in dirs if not matcher.match_file(os.path.join(rel_root, d) + "/")]
+                files = [f for f in files if not matcher.match_file(os.path.join(rel_root, f))]
+
+            for name in dirs + files:
+                full_path = os.path.join(root, name)
+                table.add_row(str(index), full_path)
+                index += 1
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def recursive_count_files(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        file_count = 0
+        dir_count = 0
+        for root, dirs, files in os.walk(path):
+            if matcher:
+                rel_root = os.path.relpath(root, path)
+                if rel_root == ".":
+                    rel_root = ""
+                dirs[:] = [d for d in dirs if not matcher.match_file(os.path.join(rel_root, d) + "/")]
+                files = [f for f in files if not matcher.match_file(os.path.join(rel_root, f))]
+
+            file_count += len(files)
+            dir_count += len(dirs)
+
+        print(f"Total Directories: {dir_count}")
+        print(f"Total Files: {file_count}")
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def recursive_count_files_by_mime_type(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        mime_counts = Counter()
+        for root, dirs, files in os.walk(path):
+            if matcher:
+                rel_root = os.path.relpath(root, path)
+                if rel_root == ".":
+                    rel_root = ""
+                dirs[:] = [d for d in dirs if not matcher.match_file(os.path.join(rel_root, d) + "/")]
+                files = [f for f in files if not matcher.match_file(os.path.join(rel_root, f))]
+
+            for file in files:
+                full_path = os.path.join(root, file)
+                mime_type = get_mime_type(full_path) or "Unknown MIME Type"
+                mime_counts[mime_type] += 1
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Recursive File Counts by MIME Type",
+            title_style="bold underline magenta",
+        )
+        table.add_column("MIME Type", style="bold red", justify="left")
+        table.add_column("Count", style="bold yellow", justify="right")
+
+        for mime, count in mime_counts.items():
+            table.add_row(mime, str(count))
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def recursive_group_files_by_mime_type(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        mime_groups = {}
+        for root, dirs, files in os.walk(path):
+            if matcher:
+                rel_root = os.path.relpath(root, path)
+                if rel_root == ".":
+                    rel_root = ""
+                dirs[:] = [d for d in dirs if not matcher.match_file(os.path.join(rel_root, d) + "/")]
+                files = [f for f in files if not matcher.match_file(os.path.join(rel_root, f))]
+
+            for file in files:
+                full_path = os.path.join(root, file)
+                mime_type = get_mime_type(full_path) or "unknown/type"
+                mime_groups.setdefault(mime_type, []).append(full_path)
+
+        panels = []
+        for mime, files in mime_groups.items():
+            prefix, suffix = mime.split("/")[0], mime.split("/")[1]
+            color = colormap.get(prefix, colormap.get(suffix, "white"))
+            icon = MIME_TYPE_ICONS.get(suffix, MIME_TYPE_ICONS.get(prefix, "📁"))
+            file_list_str = "\n".join([f"[{color}]{f}[/{color}]" for f in files])
+            box_title = f"{icon} {mime} ({len(files)})"
+            panels.append(Panel(file_list_str, title=box_title, border_style=color, expand=False))
+
+        print(Columns(panels))
+
+    except FileNotFoundError:
+        print(f"[bold red]Error:[/bold red] Directory '{path}' not found.")
+    except PermissionError:
+        print(f"[bold red]Error:[/bold red] Permission denied for '{path}'.")
+
+def recursive_count_files_by_extension(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        extension_counts = Counter()
+        for root, dirs, files in os.walk(path):
+            if matcher:
+                rel_root = os.path.relpath(root, path)
+                if rel_root == ".":
+                    rel_root = ""
+                dirs[:] = [d for d in dirs if not matcher.match_file(os.path.join(rel_root, d) + "/")]
+                files = [f for f in files if not matcher.match_file(os.path.join(rel_root, f))]
+
+            for file in files:
+                ext = os.path.splitext(file)[1].lower() or "No Extension"
+                extension_counts[ext] += 1
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Recursive File Counts by Extension",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Extension", style="bold red", justify="left")
+        table.add_column("Count", style="bold yellow", justify="right")
+
+        for ext, count in extension_counts.items():
+            table.add_row(ext, str(count))
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def recursive_group_files_by_extension(path=".", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        extension_groups = {}
+        for root, dirs, files in os.walk(path):
+            if matcher:
+                rel_root = os.path.relpath(root, path)
+                if rel_root == ".":
+                    rel_root = ""
+                dirs[:] = [d for d in dirs if not matcher.match_file(os.path.join(rel_root, d) + "/")]
+                files = [f for f in files if not matcher.match_file(os.path.join(rel_root, f))]
+
+            for file in files:
+                ext = os.path.splitext(file)[1].lower() or "No Extension"
+                full_path = os.path.join(root, file)
+                extension_groups.setdefault(ext, []).append(full_path)
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Recursive Files Grouped by Extension",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="center")
+        table.add_column("Extension", style="bold red", justify="left")
+        table.add_column("Files", style="bold yellow", justify="left")
+
+        for ext, files in extension_groups.items():
+            first = True
+            index = 1
+            for file in files:
+                if first:
+                    table.add_row(f"{index}",ext, file)
+                    first = False
+                    index += 1
+                else:
+                    table.add_row(f"{index}","", file)
+                    index += 1
+            table.add_row("")  # add an empty row after each extension group for better readability
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def filter_files_by_extension(path=".", extension=".txt", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Files with Extension '{extension}'",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="right")
+        table.add_column("File Name", style="bold green", justify="left")
+
+        index = 1
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file() and file.name.lower().endswith(extension.lower()):
+                    table.add_row(str(index), file.name)
+                    index += 1
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def filter_files_by_mime_type(path=".", mime_type="text/plain", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Files with MIME Type '{mime_type}'",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="right")
+        table.add_column("File Name", style="bold green", justify="left")
+
+        index = 1
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file():
+                    file_mime_type = get_mime_type(file.path)
+                    if file_mime_type == mime_type:
+                        table.add_row(str(index), file.name)
+                        index += 1
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def count_filter_files_by_mime_type(path=".", mime_type="text/plain", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        count = 0
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file():
+                    file_mime_type = get_mime_type(file.path)
+                    if file_mime_type == mime_type:
+                        count += 1
+
+        print(f"Number of files with MIME type '{mime_type}': {count}")
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def count_filter_files_by_extension(path=".", extension=".txt", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        count = 0
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file() and file.name.lower().endswith(extension.lower()):
+                    count += 1
+
+        print(f"Number of files with extension '{extension}': {count}")
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+
+def sort_files(path=".", sort_by="name", gitignore=False):
+    try:
+        matcher = get_gitignore_matcher(path) if gitignore else None
+        files_list = []
+        with os.scandir(path) as files:
+            for file in files:
+                if matcher and matcher.match_file(file.name + ("/" if file.is_dir() else "")):
+                    continue
+                if file.is_file():
+                    if sort_by == "name":
+                        files_list.append((file.name, file.path))
+                    elif sort_by == "size":
+                        files_list.append((file.stat().st_size, file.path))
+                    elif sort_by == "date":
+                        files_list.append((file.stat().st_mtime, file.path))
+
+        files_list.sort(key=lambda x: x[0])
+
+        table = Table(
+            show_header=True,
+            header_style="bold magenta",
+            title=f"{path if path != '.' else 'CWD'} Files Sorted by {sort_by.capitalize()}",
+            title_style="bold underline magenta",
+        )
+        table.add_column("Index", style="dim", width=6, justify="right")
+        table.add_column("File Name", style="bold green", justify="left")
+
+        index = 1
+        for _, file_path in files_list:
+            table.add_row(str(index), os.path.basename(file_path))
+            index += 1
+
+        print(table)
+
+    except FileNotFoundError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] The directory '{path}' does not exist."
+        )
+    except PermissionError:
+        print(
+            f"[bold yellow]Error:[/bold yellow] You do not have permission to access '{path}'."
+        )
+

lsum-0.1.0/src/lsum/lib/mime.py

@@ -0,0 +1,27 @@
+import os
+import mimetypes
+
+def get_mime_type(file_path:str):
+    """
+    Detects the MIME type of a file.
+    - First tries python-magic (content-based detection)
+    - Falls back to mimetypes (extension-based detection)
+    """
+    if not os.path.isfile(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Try python-magic if available
+    try:
+        import magic
+        mime = magic.Magic(mime=True)
+        mime_type = mime.from_file(file_path)
+        if mime_type:
+            return mime_type
+    except ImportError:
+        print("python-magic not installed. Falling back to mimetypes.")
+    except Exception as e:
+        print(f"python-magic failed: {e}. Falling back to mimetypes.")
+
+    # Fallback: mimetypes (based on file extension)
+    mime_type, _ = mimetypes.guess_type(file_path)
+    return mime_type or "Unknown"

lsum-0.1.0/src/lsum/lib/utils.py

@@ -0,0 +1,19 @@
+from typing import Any, Tuple, Optional
+import os
+import pathspec
+
+def assoclist(array1:list[Any], array2:list[Any]):
+    result:list[Tuple[Any,Any]] = []
+
+    length = min(len(array1),len(array2))
+    for i in range(length):
+        result.append((array1[i],array2[i]))
+    return result
+
+def get_gitignore_matcher(path: str) -> Optional[pathspec.PathSpec]:
+    gitignore_path = os.path.join(path, ".gitignore")
+    if os.path.exists(gitignore_path):
+        with open(gitignore_path, "r") as f:
+            spec = pathspec.PathSpec.from_lines("gitwildmatch", f)
+            return spec
+    return None

lsum-0.1.0/src/lsum/main.py

@@ -0,0 +1,146 @@
+#! /usr/bin/env python3
+from .lib.ls import (
+    count_files_by_extension,
+    count_files_by_mime_type,
+    group_files_by_mime_type,
+    list_files,
+    count_files,
+    group_files_by_extension,
+    recursive_count_files,
+    recursive_count_files_by_extension,
+    recursive_count_files_by_mime_type,
+    recursive_group_files_by_extension,
+    recursive_group_files_by_mime_type,
+    recursive_list_files,
+    filter_files_by_extension,
+    filter_files_by_mime_type,
+    count_filter_files_by_extension,
+    count_filter_files_by_mime_type,
+    sort_files,
+)
+import click
+
+
+@click.command()
+@click.argument("path", default=".", required=False)
+@click.option(
+    "--count",
+    "-c",
+    is_flag=True,
+    help="Count the number of files and directories in the specified path. Using it in conjunction with --group or --group-extension will count files within each group instead of the total count. Using it with --filter or --filter-extension will count only the files that match the specified filter criteria.",
+)
+@click.option("--group", "-g", is_flag=True, help="Group files by their MIME type.")
+@click.option(
+    "--group-extension",
+    "-ge",
+    is_flag=True,
+    help="Group files by their file extension.",
+)
+@click.option(
+    "--group-by",
+    "-gb",
+    type=click.Choice(["mime", "extension"], case_sensitive=False),
+    help="Group files by MIME type or file extension.",
+)
+@click.option(
+    "--filter",
+    "-f",
+    type=str,
+    help="Filter files by a specific MIME type (e.g., 'image/jpeg').",
+)
+@click.option(
+    "--filter-extension",
+    "-fe",
+    type=str,
+    help="Filter files by a specific file extension (e.g., '.txt').",
+)
+@click.option(
+    "--sort",
+    "-s",
+    type=click.Choice(["name", "size", "date"], case_sensitive=False),
+    help="Sort files by name, size, or date.",
+)
+@click.option(
+    "--recursive",
+    "-r",
+    is_flag=True,
+    help="Recursively perform the specified operations on all subdirectories within the given path. Must be used in conjunction with other options to specify the desired operations (e.g., counting, grouping). Note: currently, filtering or sorting files is not supported in recursive mode.",
+)
+@click.option(
+    "--gitignore",
+    "-gi",
+    is_flag=True,
+    help="Respect the .gitignore file if present in the specified directory and exclude those files and directories mentioned in the file from the search space.",
+)
+def cli(
+    path,
+    count,
+    group,
+    group_extension,
+    group_by,
+    filter,
+    filter_extension,
+    sort,
+    recursive,
+    gitignore,
+):
+    if recursive:
+        if count and group_by:
+            if group_by == "mime":
+                recursive_count_files_by_mime_type(path, gitignore=gitignore)
+            elif group_by == "extension":
+                recursive_count_files_by_extension(path, gitignore=gitignore)
+        elif count and not group_by and not group and not group_extension:
+            recursive_count_files(path, gitignore=gitignore)
+        elif count and group:
+            recursive_count_files_by_mime_type(path, gitignore=gitignore)
+        elif count and group_extension:
+            recursive_count_files_by_extension(path, gitignore=gitignore)
+        elif group_extension:
+            recursive_group_files_by_extension(path, gitignore=gitignore)
+        elif group:
+            recursive_group_files_by_mime_type(path, gitignore=gitignore)
+        elif group_by:
+            if group_by == "mime":
+                recursive_group_files_by_mime_type(path, gitignore=gitignore)
+            elif group_by == "extension":
+                recursive_group_files_by_extension(path, gitignore=gitignore)
+        else:
+            recursive_list_files(path, gitignore=gitignore)
+    else:
+        if count and group_by:
+            if group_by == "mime":
+                count_files_by_mime_type(path, gitignore=gitignore)
+            elif group_by == "extension":
+                count_files_by_extension(path, gitignore=gitignore)
+        elif count and not group_by and not group and not group_extension:
+            count_files(path, gitignore=gitignore)
+        elif count and group:
+            count_files_by_mime_type(path, gitignore=gitignore)
+        elif count and group_extension:
+            count_files_by_extension(path, gitignore=gitignore)
+        elif group_extension:
+            group_files_by_extension(path, gitignore=gitignore)
+        elif group:
+            group_files_by_mime_type(path, gitignore=gitignore)
+        elif group_by:
+            if group_by == "mime":
+                group_files_by_mime_type(path, gitignore=gitignore)
+            elif group_by == "extension":
+                group_files_by_extension(path, gitignore=gitignore)
+        elif count and filter:
+            count_filter_files_by_mime_type(path, filter, gitignore=gitignore)
+        elif count and filter_extension:
+            count_filter_files_by_extension(path, filter_extension, gitignore=gitignore)
+        elif filter_extension:
+            filter_files_by_extension(path, filter_extension, gitignore=gitignore)
+        elif filter:
+            filter_files_by_mime_type(path, filter, gitignore=gitignore)
+        elif sort:
+            sort_files(path, sort, gitignore=gitignore)
+        else:
+            list_files(path, gitignore=gitignore)
+
+
+if __name__ == "__main__":
+    cli()