lsdisk 0.1.1__py3-none-any.whl

lsdisk/__init__.py

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

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/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())

lsdisk/collectors/block_devices.py

@@ -0,0 +1,123 @@
+"""Discover Linux block devices through sysfs."""
+
+from pathlib import Path
+
+from lsdisk.models import BlockDevice
+
+
+SYSFS_BLOCK_PATH = Path("/sys/class/block")
+SECTOR_SIZE_BYTES = 512
+
+
+def _read_text(path: Path) -> str | None:
+    """Read a sysfs value, returning None when it is unavailable."""
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (OSError, UnicodeError):
+        return None
+
+
+def _detect_transport(device_path: Path) -> str | None:
+    """Infer the transport from available sysfs information."""
+    transport = _read_text(device_path / "device" / "transport")
+    if transport:
+        return transport
+
+    resolved = str(device_path.resolve()).lower()
+
+    indicators = (
+        ("nvme", "nvme"),
+        ("ata", "sata"),
+        ("usb", "usb"),
+        ("virtio", "virtio"),
+        ("mmc", "mmc"),
+        ("iscsi", "iscsi"),
+        ("sas", "sas"),
+    )
+
+    for indicator, transport_name in indicators:
+        if indicator in resolved:
+            return transport_name
+
+    return None
+
+
+def _build_device(entry: Path) -> BlockDevice | None:
+    """Build a device model from a sysfs block-device entry."""
+    try:
+        resolved = entry.resolve(strict=True)
+    except OSError:
+        return None
+
+    raw_size = _read_text(entry / "size")
+    if raw_size is None:
+        return None
+
+    try:
+        size_bytes = int(raw_size) * SECTOR_SIZE_BYTES
+    except ValueError:
+        return None
+
+    is_partition = (entry / "partition").exists()
+    device_type = "part" if is_partition else "disk"
+
+    scsi_type = _read_text(entry / "device" / "type")
+    if not is_partition and scsi_type == "5":
+        device_type = "rom"
+
+    parent_name = resolved.parent.name if is_partition else None
+
+    model = _read_text(entry / "device" / "model")
+    rotational_value = _read_text(entry / "queue" / "rotational")
+
+    rotational = None
+    if rotational_value in {"0", "1"}:
+        rotational = rotational_value == "1"
+
+    is_virtual = "/devices/virtual/" in str(resolved)
+    has_device_link = (entry / "device").exists()
+
+    physical = (
+        device_type == "disk"
+        and not is_virtual
+        and has_device_link
+    )
+
+    return BlockDevice(
+        name=entry.name,
+        path=f"/dev/{entry.name}",
+        device_type=device_type,
+        size_bytes=size_bytes,
+        physical=physical,
+        parent_name=parent_name,
+        model=model,
+        transport=_detect_transport(entry),
+        rotational=rotational,
+    )
+
+
+def collect_block_devices(
+    sysfs_path: Path = SYSFS_BLOCK_PATH,
+) -> list[BlockDevice]:
+    """Discover block devices and return a hierarchy of devices and partitions."""
+    if not sysfs_path.is_dir():
+        return []
+
+    discovered: dict[str, BlockDevice] = {}
+
+    for entry in sorted(sysfs_path.iterdir(), key=lambda item: item.name):
+        device = _build_device(entry)
+        if device is not None:
+            discovered[device.name] = device
+
+    roots: list[BlockDevice] = []
+
+    for device in discovered.values():
+        parent = discovered.get(device.parent_name or "")
+
+        if parent is None:
+            roots.append(device)
+        else:
+            parent.children.append(device)
+
+    return roots

lsdisk/collectors/filesystems.py

@@ -0,0 +1,89 @@
+"""Discover mounted filesystems using Linux mountinfo and statvfs."""
+
+import os
+import re
+from pathlib import Path
+
+from lsdisk.models import FilesystemUsage
+
+
+MOUNTINFO_PATH = Path("/proc/self/mountinfo")
+_OCTAL_ESCAPE = re.compile(r"\\([0-7]{3})")
+
+
+def _unescape_mountinfo(value: str) -> str:
+    """Decode octal escapes used in mountinfo fields."""
+    return _OCTAL_ESCAPE.sub(
+        lambda match: chr(int(match.group(1), 8)),
+        value,
+    )
+
+
+def _parse_mountinfo_line(line: str) -> dict[str, str] | None:
+    """Parse one mountinfo line into normalized fields."""
+    try:
+        before_separator, after_separator = line.split(" - ", 1)
+        left = before_separator.split()
+        right = after_separator.split()
+
+        if len(left) < 6 or len(right) < 3:
+            return None
+
+        return {
+            "device_id": left[2],
+            "filesystem_root": _unescape_mountinfo(left[3]),
+            "mountpoint": _unescape_mountinfo(left[4]),
+            "filesystem_type": right[0],
+            "source": _unescape_mountinfo(right[1]),
+        }
+    except (ValueError, IndexError):
+        return None
+
+
+def collect_filesystems(
+    mountinfo_path: Path = MOUNTINFO_PATH,
+) -> list[FilesystemUsage]:
+    """Collect capacity statistics for accessible mounted filesystems."""
+    try:
+        lines = mountinfo_path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError):
+        return []
+
+    filesystems: list[FilesystemUsage] = []
+
+    for line in lines:
+        mount = _parse_mountinfo_line(line)
+        if mount is None:
+            continue
+
+        mountpoint = mount["mountpoint"]
+
+        try:
+            stats = os.statvfs(mountpoint)
+        except OSError:
+            # A mount can disappear between reading mountinfo and statvfs.
+            continue
+
+        fragment_size = stats.f_frsize or stats.f_bsize
+        total_bytes = stats.f_blocks * fragment_size
+        free_bytes = stats.f_bfree * fragment_size
+        available_bytes = stats.f_bavail * fragment_size
+
+        try:
+            usage = FilesystemUsage(
+                mountpoint=mountpoint,
+                source=mount["source"],
+                filesystem_type=mount["filesystem_type"],
+                total_bytes=total_bytes,
+                free_bytes=free_bytes,
+                available_bytes=available_bytes,
+                device_id=mount["device_id"],
+                filesystem_root=mount["filesystem_root"],
+            )
+        except ValueError:
+            # Ignore inconsistent statistics rather than reporting bad data.
+            continue
+
+        filesystems.append(usage)
+
+    return filesystems

lsdisk/inventory.py

@@ -0,0 +1,79 @@
+"""Build a unified inventory of Linux storage."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from collections.abc import Iterator
+
+from lsdisk.analyzers.filesystems import (
+    FilesystemGroup,
+    group_filesystems,
+)
+from lsdisk.collectors.block_devices import collect_block_devices
+from lsdisk.collectors.filesystems import collect_filesystems
+from lsdisk.models import BlockDevice, FilesystemUsage
+
+
+@dataclass
+class StorageInventory:
+    """Store discovered devices and filesystem information."""
+
+    devices: list[BlockDevice]
+    filesystems: list[FilesystemUsage]
+    filesystem_groups: list[FilesystemGroup]
+
+
+def walk_devices(
+    devices: list[BlockDevice],
+) -> Iterator[BlockDevice]:
+    """Yield devices recursively, including partitions."""
+    for device in devices:
+        yield device
+        yield from walk_devices(device.children)
+
+
+def _canonical_device_path(path: str) -> str | None:
+    """Resolve a device path, including available symlink aliases."""
+    if not path.startswith("/dev/"):
+        return None
+
+    try:
+        return str(Path(path).resolve(strict=False))
+    except (OSError, RuntimeError):
+        return None
+
+
+def collect_storage_inventory() -> StorageInventory:
+    """Collect devices and filesystems and associate their mountpoints."""
+    devices = collect_block_devices()
+    filesystems = collect_filesystems()
+
+    devices_by_path: dict[str, BlockDevice] = {}
+
+    for device in walk_devices(devices):
+        devices_by_path[device.path] = device
+        canonical_path = _canonical_device_path(device.path)
+
+        if canonical_path:
+            devices_by_path[canonical_path] = device
+
+    for filesystem in filesystems:
+        device = devices_by_path.get(filesystem.source)
+
+        if device is None:
+            canonical_source = _canonical_device_path(filesystem.source)
+            if canonical_source:
+                device = devices_by_path.get(canonical_source)
+
+        if device is None:
+            continue
+
+        device.filesystem_type = filesystem.filesystem_type
+
+        if filesystem.mountpoint not in device.mountpoints:
+            device.mountpoints.append(filesystem.mountpoint)
+
+    return StorageInventory(
+        devices=devices,
+        filesystems=filesystems,
+        filesystem_groups=group_filesystems(filesystems),
+    )

lsdisk/main.py

@@ -0,0 +1,128 @@
+"""Command-line entry point for lsdisk."""
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from importlib.metadata import PackageNotFoundError, version
+
+from lsdisk import __version__
+from lsdisk.inventory import collect_storage_inventory
+from lsdisk.serialization import inventory_to_dict
+from lsdisk.ui.terminal import (
+    create_console,
+    render_all,
+    render_compact,
+    render_simple,
+)
+
+
+def _get_version() -> str:
+    """Return the installed package version when available."""
+    try:
+        return version("lsdisk")
+    except PackageNotFoundError:
+        return __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="lsdisk",
+        description="Explore Linux storage devices, partitions, and filesystems.",
+        epilog=(
+            "Examples:\n"
+            "  lsdisk\n"
+            "  lsdisk --all\n"
+            "  lsdisk -T\n"
+            "  lsdisk --all --json\n"
+            "  lsdisk --color never"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+
+    modes = parser.add_mutually_exclusive_group()
+    modes.add_argument(
+        "--simple",
+        action="store_true",
+        help="Show the simplified overview (default).",
+    )
+    modes.add_argument(
+        "-a",
+        "--all",
+        action="store_true",
+        help="Show all devices, mounts, and filesystem statistics.",
+    )
+
+    output_modes = parser.add_mutually_exclusive_group()
+    output_modes.add_argument(
+        "--json",
+        action="store_true",
+        help="Output machine-readable JSON instead of terminal views.",
+    )
+    output_modes.add_argument(
+        "-T",
+        "--table-mode",
+        action="store_true",
+        help="Use tabular terminal output instead of the compact layout.",
+    )
+
+    parser.add_argument(
+        "--color",
+        choices=("auto", "always", "never"),
+        default="auto",
+        help="Control terminal colors (default: auto).",
+    )
+    parser.add_argument(
+        "--no-color",
+        dest="color",
+        action="store_const",
+        const="never",
+        default=argparse.SUPPRESS,
+        help="Disable terminal colors.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {_get_version()}",
+        help="Show the installed version and exit.",
+    )
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run lsdisk."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        inventory = collect_storage_inventory()
+    except (OSError, RuntimeError, ValueError) as exc:
+        print(f"lsdisk: error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        data = inventory_to_dict(inventory, include_all=args.all)
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+        return 0
+
+    console = create_console(args.color)
+
+    if args.table_mode:
+        if args.all:
+            render_all(inventory, console)
+        else:
+            render_simple(inventory, console)
+    else:
+        render_compact(
+            inventory,
+            console,
+            include_all=args.all,
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lsdisk/models.py

@@ -0,0 +1,78 @@
+"""Core data models for lsdisk."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class BlockDevice:
+    """Represents a block device or partition discovered on Linux."""
+
+    name: str
+    path: str
+    device_type: str
+    size_bytes: int
+    physical: bool | None = None
+    parent_name: str | None = None
+    model: str | None = None
+    transport: str | None = None
+    rotational: bool | None = None
+    filesystem_type: str | None = None
+    filesystem_label: str | None = None
+    filesystem_uuid: str | None = None
+    mountpoints: list[str] = field(default_factory=list)
+    children: list["BlockDevice"] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.size_bytes < 0:
+            raise ValueError("Device size cannot be negative.")
+
+    @property
+    def is_physical_disk(self) -> bool:
+        """Return whether the collector identified this as a physical disk."""
+        return self.device_type == "disk" and self.physical is True
+
+    @property
+    def is_partition(self) -> bool:
+        """Return whether this represents a partition."""
+        return self.device_type == "part"
+
+
+@dataclass(frozen=True)
+class FilesystemUsage:
+    """Represents capacity statistics for a mounted filesystem."""
+
+    mountpoint: str
+    source: str
+    filesystem_type: str
+    total_bytes: int
+    free_bytes: int
+    available_bytes: int
+    device_id: str | None = None
+    filesystem_root: str = "/"
+
+    def __post_init__(self) -> None:
+        if min(
+            self.total_bytes,
+            self.free_bytes,
+            self.available_bytes,
+        ) < 0:
+            raise ValueError("Filesystem capacity values cannot be negative.")
+
+        if self.free_bytes > self.total_bytes:
+            raise ValueError("Free space cannot exceed total capacity.")
+
+        if self.available_bytes > self.free_bytes:
+            raise ValueError("Available space cannot exceed free space.")
+
+    @property
+    def used_bytes(self) -> int:
+        """Return used filesystem space in bytes."""
+        return self.total_bytes - self.free_bytes
+
+    @property
+    def used_percent(self) -> float:
+        """Return the percentage of filesystem space used."""
+        if self.total_bytes == 0:
+            return 0.0
+
+        return self.used_bytes / self.total_bytes * 100