lsdisk 0.1.1__tar.gz

lsdisk-0.1.1/LICENSE

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

lsdisk-0.1.1/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: lsdisk
+Version: 0.1.1
+Summary: Cross-distro Linux Storage Explorer
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Dynamic: license-file
+
+<div align="center">
+
+  <img src="img/lsdisk.png" alt="lsdisk — Linux Storage Explorer" width="760">
+
+  <p><strong>Cross-distro Linux Storage Explorer</strong></p>
+  <p>Understand your disks, partitions, and filesystems — clearly, safely, and from the terminal.</p>
+
+</div>
+
+<div align="center">
+
+  <p>
+    <a href="https://github.com/SammMartins/lsdisk/releases/latest"><img src="https://img.shields.io/github/v/release/SammMartins/lsdisk?color=blue" alt="Latest Release"></a>
+    <a href="https://github.com/SammMartins/lsdisk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/SammMartins/lsdisk?color=green" alt="License"></a>
+    <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.8%2B-blue?logo=python&logoColor=white" alt="Python"></a>
+    <a href="https://www.kernel.org/"><img src="https://img.shields.io/badge/platform-linux-lightgrey?logo=linux&logoColor=white" alt="Platform"></a>
+    <a href="https://github.com/SammMartins/lsdisk/stargazers"><img src="https://img.shields.io/github/stars/SammMartins/lsdisk?color=yellow" alt="GitHub Stars"></a>
+  </p>
+
+</div>
+
+---
+
+## About lsdisk
+
+**lsdisk** is a Linux storage inspection tool designed to make information about HDDs, SSDs, partitions, and filesystems easier to understand.
+
+It brings storage topology and filesystem capacity information together in a structured terminal interface. lsdisk is read-only: it inspects storage and does not format, partition, mount, or modify filesystems.
+
+<br>
+
+![lsdisk Demo](./img/lsdisk_0_1_1.gif)
+
+<p><sub><em>Live demonstration of lsdisk v0.1.1 inspecting Linux storage devices in the terminal.</em></sub></p>
+
+## Features
+
+- **Physical storage inventory** — show detected disks and their child partitions in a hierarchical view.
+- **Device details** — display device names, capacity, model, physical/virtual classification, and HDD or SSD/Flash indicators when the system provides enough information.
+- **Filesystem capacity** — report total, used, free, and user-available capacity for accessible mounted filesystems.
+- **Mountpoint visibility** — associate filesystem information with mountpoints where the relationship can be established.
+- **Filesystem grouping** — group related filesystem records to avoid repeating capacity for multiple mountpoints, including supported Btrfs subvolume cases.
+- **Utilization bars** — display a compact visual usage bar and percentage in the terminal. The filled bar and percentage use utilization colors: green below 70%, yellow from 70% to below 90%, and red at 90% or above.
+- **Multiple output modes** — provide a compact default view, expanded output, table output, and JSON output.
+- **Graceful handling of missing data** — distinguish unavailable information from a confirmed zero value.
+
+Capacity values depend on the information available from the running Linux system. Physical disk capacity and mounted filesystem capacity describe different layers and should not be treated as interchangeable.
+
+## Design principles
+
+| Principle | What it means |
+|---|---|
+| **Read-only inspection** | Do not modify disks, partitions, or filesystems. |
+| **Modular architecture** | Keep data collection, analysis, serialization, and presentation separated. |
+| **Portability** | Avoid unnecessary dependencies on a specific Linux distribution. |
+| **Transparency** | Distinguish confirmed values from estimates or unavailable data. |
+| **Testability** | Validate calculations and behavior with automated tests. |
+
+## Technology
+
+- **Python** — application logic.
+- **Rich** — terminal presentation and colored utilization bars.
+- **Python standard library** — core APIs and supporting functionality.
+- **Linux interfaces**, including `/sys` and `/proc`, where appropriate.
+- **`os.statvfs()`** — mounted filesystem capacity statistics.
+- **`unittest`** — automated testing.
+
+## Requirements
+
+- Linux
+- Python 3.11 or newer
+- `curl` and `tar` for the shell installer
+
+The installer creates an isolated Python virtual environment and installs the Python dependencies. Some storage information may depend on available system interfaces, permissions, and the storage configuration.
+
+## Installation
+
+The installation script downloads lsdisk, creates an isolated Python virtual environment, and installs the `lsdisk` command for the current user:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/SammMartins/lsdisk/main/install.sh | bash
+```
+
+The installer does not require `sudo` and refuses to run as root. By default, it stores application data in `~/.local/share/lsdisk` and the executable in `~/.local/bin`. If `~/.local/bin` is not in your `PATH`, follow the instruction printed by the installer.
+
+Run lsdisk:
+
+```bash
+lsdisk
+```
+
+Show available options:
+
+```bash
+lsdisk --help
+```
+
+To install from a different branch, set `LSDISK_BRANCH` before running the installer:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/SammMartins/lsdisk/main/install.sh | LSDISK_BRANCH=main bash
+```
+
+## Uninstallation
+
+If `uninstall.sh` is available locally, run it as your regular user, without `sudo`:
+
+```bash
+bash uninstall.sh
+```
+
+The uninstaller removes the per-user launcher and application data directory. It does not delete the local Git repository or project source files.
+
+## Usage
+
+```bash
+lsdisk
+lsdisk --all
+lsdisk --table-mode
+lsdisk --json
+lsdisk --help
+```
+
+- `lsdisk` displays the default compact storage view.
+- `lsdisk --all` displays expanded inventory details, including additional devices and mount information.
+- `lsdisk --table-mode` selects table output.
+- `lsdisk --json` emits machine-readable JSON without terminal UI formatting.
+- `lsdisk --help` lists the options supported by the installed version.
+
+Use the output of `lsdisk --help` as the source of truth for the options available in a specific release.
+
+## Development status
+
+**lsdisk is in early development.** Features and interfaces may change as the project evolves. The current implementation focuses on block-device topology and capacity information for mounted filesystems.
+
+### Roadmap
+
+- [ ] Identify filesystem types on unmounted partitions without mounting them.
+- [ ] Collect filesystem labels and UUIDs more completely.
+- [ ] Improve identification of partitions whose filesystem information is unavailable.
+- [ ] Expand validated handling of Btrfs, LVM, RAID, LUKS, and other storage layers.
+
+These items are planned improvements, not guarantees of the current implementation.
+
+## Project documentation
+
+- [Architecture](docs/ARCHITECTURE.md)
+- [Development guide](docs/DEVELOPMENT.md)
+- [Changelog](CHANGELOG.md)
+
+## Safety scope
+
+lsdisk is intended for **storage inspection only**. Formatting, partitioning, filesystem modification, and automatic mounting are outside the project's scope.
+
+## License
+
+lsdisk is distributed under the [MIT License](LICENSE).
+
+---
+
+<div align="center">
+  <sub>lsdisk — making Linux storage easier to explore.</sub>
+</div>

lsdisk-0.1.1/README.md

@@ -0,0 +1,163 @@
+<div align="center">
+
+  <img src="img/lsdisk.png" alt="lsdisk — Linux Storage Explorer" width="760">
+
+  <p><strong>Cross-distro Linux Storage Explorer</strong></p>
+  <p>Understand your disks, partitions, and filesystems — clearly, safely, and from the terminal.</p>
+
+</div>
+
+<div align="center">
+
+  <p>
+    <a href="https://github.com/SammMartins/lsdisk/releases/latest"><img src="https://img.shields.io/github/v/release/SammMartins/lsdisk?color=blue" alt="Latest Release"></a>
+    <a href="https://github.com/SammMartins/lsdisk/blob/main/LICENSE"><img src="https://img.shields.io/github/license/SammMartins/lsdisk?color=green" alt="License"></a>
+    <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.8%2B-blue?logo=python&logoColor=white" alt="Python"></a>
+    <a href="https://www.kernel.org/"><img src="https://img.shields.io/badge/platform-linux-lightgrey?logo=linux&logoColor=white" alt="Platform"></a>
+    <a href="https://github.com/SammMartins/lsdisk/stargazers"><img src="https://img.shields.io/github/stars/SammMartins/lsdisk?color=yellow" alt="GitHub Stars"></a>
+  </p>
+
+</div>
+
+---
+
+## About lsdisk
+
+**lsdisk** is a Linux storage inspection tool designed to make information about HDDs, SSDs, partitions, and filesystems easier to understand.
+
+It brings storage topology and filesystem capacity information together in a structured terminal interface. lsdisk is read-only: it inspects storage and does not format, partition, mount, or modify filesystems.
+
+<br>
+
+![lsdisk Demo](./img/lsdisk_0_1_1.gif)
+
+<p><sub><em>Live demonstration of lsdisk v0.1.1 inspecting Linux storage devices in the terminal.</em></sub></p>
+
+## Features
+
+- **Physical storage inventory** — show detected disks and their child partitions in a hierarchical view.
+- **Device details** — display device names, capacity, model, physical/virtual classification, and HDD or SSD/Flash indicators when the system provides enough information.
+- **Filesystem capacity** — report total, used, free, and user-available capacity for accessible mounted filesystems.
+- **Mountpoint visibility** — associate filesystem information with mountpoints where the relationship can be established.
+- **Filesystem grouping** — group related filesystem records to avoid repeating capacity for multiple mountpoints, including supported Btrfs subvolume cases.
+- **Utilization bars** — display a compact visual usage bar and percentage in the terminal. The filled bar and percentage use utilization colors: green below 70%, yellow from 70% to below 90%, and red at 90% or above.
+- **Multiple output modes** — provide a compact default view, expanded output, table output, and JSON output.
+- **Graceful handling of missing data** — distinguish unavailable information from a confirmed zero value.
+
+Capacity values depend on the information available from the running Linux system. Physical disk capacity and mounted filesystem capacity describe different layers and should not be treated as interchangeable.
+
+## Design principles
+
+| Principle | What it means |
+|---|---|
+| **Read-only inspection** | Do not modify disks, partitions, or filesystems. |
+| **Modular architecture** | Keep data collection, analysis, serialization, and presentation separated. |
+| **Portability** | Avoid unnecessary dependencies on a specific Linux distribution. |
+| **Transparency** | Distinguish confirmed values from estimates or unavailable data. |
+| **Testability** | Validate calculations and behavior with automated tests. |
+
+## Technology
+
+- **Python** — application logic.
+- **Rich** — terminal presentation and colored utilization bars.
+- **Python standard library** — core APIs and supporting functionality.
+- **Linux interfaces**, including `/sys` and `/proc`, where appropriate.
+- **`os.statvfs()`** — mounted filesystem capacity statistics.
+- **`unittest`** — automated testing.
+
+## Requirements
+
+- Linux
+- Python 3.11 or newer
+- `curl` and `tar` for the shell installer
+
+The installer creates an isolated Python virtual environment and installs the Python dependencies. Some storage information may depend on available system interfaces, permissions, and the storage configuration.
+
+## Installation
+
+The installation script downloads lsdisk, creates an isolated Python virtual environment, and installs the `lsdisk` command for the current user:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/SammMartins/lsdisk/main/install.sh | bash
+```
+
+The installer does not require `sudo` and refuses to run as root. By default, it stores application data in `~/.local/share/lsdisk` and the executable in `~/.local/bin`. If `~/.local/bin` is not in your `PATH`, follow the instruction printed by the installer.
+
+Run lsdisk:
+
+```bash
+lsdisk
+```
+
+Show available options:
+
+```bash
+lsdisk --help
+```
+
+To install from a different branch, set `LSDISK_BRANCH` before running the installer:
+
+```bash
+curl -sSL https://raw.githubusercontent.com/SammMartins/lsdisk/main/install.sh | LSDISK_BRANCH=main bash
+```
+
+## Uninstallation
+
+If `uninstall.sh` is available locally, run it as your regular user, without `sudo`:
+
+```bash
+bash uninstall.sh
+```
+
+The uninstaller removes the per-user launcher and application data directory. It does not delete the local Git repository or project source files.
+
+## Usage
+
+```bash
+lsdisk
+lsdisk --all
+lsdisk --table-mode
+lsdisk --json
+lsdisk --help
+```
+
+- `lsdisk` displays the default compact storage view.
+- `lsdisk --all` displays expanded inventory details, including additional devices and mount information.
+- `lsdisk --table-mode` selects table output.
+- `lsdisk --json` emits machine-readable JSON without terminal UI formatting.
+- `lsdisk --help` lists the options supported by the installed version.
+
+Use the output of `lsdisk --help` as the source of truth for the options available in a specific release.
+
+## Development status
+
+**lsdisk is in early development.** Features and interfaces may change as the project evolves. The current implementation focuses on block-device topology and capacity information for mounted filesystems.
+
+### Roadmap
+
+- [ ] Identify filesystem types on unmounted partitions without mounting them.
+- [ ] Collect filesystem labels and UUIDs more completely.
+- [ ] Improve identification of partitions whose filesystem information is unavailable.
+- [ ] Expand validated handling of Btrfs, LVM, RAID, LUKS, and other storage layers.
+
+These items are planned improvements, not guarantees of the current implementation.
+
+## Project documentation
+
+- [Architecture](docs/ARCHITECTURE.md)
+- [Development guide](docs/DEVELOPMENT.md)
+- [Changelog](CHANGELOG.md)
+
+## Safety scope
+
+lsdisk is intended for **storage inspection only**. Formatting, partitioning, filesystem modification, and automatic mounting are outside the project's scope.
+
+## License
+
+lsdisk is distributed under the [MIT License](LICENSE).
+
+---
+
+<div align="center">
+  <sub>lsdisk — making Linux storage easier to explore.</sub>
+</div>

lsdisk-0.1.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lsdisk"
+version = "0.1.1"
+description = "Cross-distro Linux Storage Explorer"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "rich>=13.0",
+]
+
+[project.scripts]
+lsdisk = "lsdisk.main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

lsdisk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lsdisk-0.1.1/src/lsdisk/__init__.py

@@ -0,0 +1,3 @@
+"""lsdisk: Cross-distro Linux Storage Explorer."""
+
+__version__ = "0.1.0"

lsdisk-0.1.1/src/lsdisk/analyzers/capacity.py

@@ -0,0 +1,64 @@
+"""Capacity calculations for lsdisk."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Capacity:
+    """Represent a capacity measurement in bytes."""
+
+    total_bytes: int
+    available_bytes: int
+
+    def __post_init__(self) -> None:
+        if self.total_bytes < 0:
+            raise ValueError("Total capacity cannot be negative.")
+
+        if self.available_bytes < 0:
+            raise ValueError("Available space cannot be negative.")
+
+        if self.available_bytes > self.total_bytes:
+            raise ValueError(
+                "Available space cannot exceed total capacity."
+            )
+
+    @property
+    def used_bytes(self) -> int:
+        """Calculate used space in bytes."""
+        return self.total_bytes - self.available_bytes
+
+    @property
+    def used_percent(self) -> float:
+        """Calculate the percentage used, from 0 to 100."""
+        if self.total_bytes == 0:
+            return 0.0
+
+        return self.used_bytes / self.total_bytes * 100
+
+    @property
+    def available_percent(self) -> float:
+        """Calculate the percentage available, from 0 to 100."""
+        if self.total_bytes == 0:
+            return 0.0
+
+        return self.available_bytes / self.total_bytes * 100
+
+
+def format_bytes(size_bytes: int) -> str:
+    """Format bytes using binary units (KiB, MiB, GiB, and TiB)."""
+    if size_bytes < 0:
+        raise ValueError("Size cannot be negative.")
+
+    value = float(size_bytes)
+    units = ("B", "KiB", "MiB", "GiB", "TiB", "PiB")
+
+    for unit in units:
+        if value < 1024 or unit == units[-1]:
+            if unit == "B":
+                return f"{int(value)} B"
+
+            return f"{value:.2f} {unit}"
+
+        value /= 1024
+
+    raise AssertionError("Size unit not found.")

lsdisk-0.1.1/src/lsdisk/analyzers/filesystems.py

@@ -0,0 +1,116 @@
+"""Classification and grouping of mounted filesystems."""
+
+from dataclasses import dataclass, field
+
+from lsdisk.models import FilesystemUsage
+
+
+VIRTUAL_FILESYSTEMS = {
+    "autofs",
+    "bpf",
+    "cgroup",
+    "cgroup2",
+    "configfs",
+    "debugfs",
+    "devpts",
+    "devtmpfs",
+    "efivarfs",
+    "fusectl",
+    "hugetlbfs",
+    "mqueue",
+    "proc",
+    "pstore",
+    "securityfs",
+    "sysfs",
+    "tmpfs",
+    "tracefs",
+}
+
+NETWORK_FILESYSTEMS = {
+    "9p",
+    "ceph",
+    "cifs",
+    "glusterfs",
+    "nfs",
+    "nfs4",
+    "smb3",
+    "sshfs",
+}
+
+PERSISTENT_FILESYSTEMS = {
+    "btrfs",
+    "exfat",
+    "ext2",
+    "ext3",
+    "ext4",
+    "f2fs",
+    "jfs",
+    "ntfs",
+    "ntfs3",
+    "reiserfs",
+    "udf",
+    "vfat",
+    "xfs",
+    "zfs",
+}
+
+
+@dataclass
+class FilesystemGroup:
+    """Represent one filesystem with its associated mountpoints."""
+
+    representative: FilesystemUsage
+    mountpoints: list[str] = field(default_factory=list)
+
+    @property
+    def total_bytes(self) -> int:
+        return self.representative.total_bytes
+
+    @property
+    def used_bytes(self) -> int:
+        return self.representative.used_bytes
+
+    @property
+    def available_bytes(self) -> int:
+        return self.representative.available_bytes
+
+
+def classify_filesystem(filesystem: FilesystemUsage) -> str:
+    """Classify a filesystem without hiding unrecognized types."""
+    filesystem_type = filesystem.filesystem_type.lower()
+
+    if filesystem_type in VIRTUAL_FILESYSTEMS:
+        return "virtual"
+
+    if filesystem_type in NETWORK_FILESYSTEMS:
+        return "network"
+
+    if filesystem_type in PERSISTENT_FILESYSTEMS:
+        return "persistent"
+
+    return "unknown"
+
+
+def group_filesystems(
+    filesystems: list[FilesystemUsage],
+) -> list[FilesystemGroup]:
+    """Group mounts that share the same filesystem identity."""
+    groups: dict[tuple[str, str, str], FilesystemGroup] = {}
+
+    for filesystem in filesystems:
+        identity = (
+            filesystem.device_id or filesystem.source,
+            filesystem.filesystem_type,
+            filesystem.source,
+        )
+
+        group = groups.get(identity)
+
+        if group is None:
+            group = FilesystemGroup(representative=filesystem)
+            groups[identity] = group
+
+        if filesystem.mountpoint not in group.mountpoints:
+            group.mountpoints.append(filesystem.mountpoint)
+
+    return list(groups.values())