recipe_modules/disk_usage/api.py

# Copyright 2026 The Pigweed Authors
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may not
# use this file except in compliance with the License. You may obtain a copy of
# the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations under
# the License.
"""Provides disk usage statistics for the recipe start directory."""

from __future__ import annotations

import dataclasses

from recipe_engine import recipe_api


@dataclasses.dataclass(frozen=True)
class DiskUsageData:
    """Disk usage statistics in bytes."""

    total: int
    used: int
    free: int


class DiskUsageApi(recipe_api.RecipeApi):
    """Provides disk usage statistics for api.path.start_dir."""

    DiskUsageData = DiskUsageData

    def __call__(self, step_name: str = 'disk usage') -> DiskUsageData:
        """Returns disk usage statistics for api.path.start_dir."""
        cmd = [
            'python3',
            self.resource('disk_usage.py'),
            self.m.path.start_dir,
            self.m.json.output(),
        ]
        step_result = self.m.step(
            step_name,
            cmd,
            step_test_data=lambda: self.m.json.test_api.output(
                self.test_api.usage_dict()
            ),
        )
        res = step_result.json.output

        used_gb = res['used'] / (1024**3)
        total_gb = res['total'] / (1024**3)
        used_pct = (
            (res['used'] / res['total']) * 100 if res['total'] > 0 else 0.0
        )
        step_result.presentation.step_summary_text = (
            f'{used_gb:.2f}/{total_gb:.2f} GB used ({used_pct:.1f}%)'
        )

        return DiskUsageData(
            total=res['total'],
            used=res['used'],
            free=res['free'],
        )