cloudcosting 0.1.0__py3-none-any.whl

cloudcosting/__init__.py

@@ -0,0 +1,8 @@
+"""Multi-cloud infrastructure cost estimation tool."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cloudcosting")
+except PackageNotFoundError:
+    __version__ = "dev"

cloudcosting/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m cloudcosting."""
+
+from cloudcosting.cli import main
+
+if __name__ == "__main__":
+    main()

cloudcosting/cache.py

@@ -0,0 +1,110 @@
+"""File-based Price Cache with TTL.
+
+Provider-agnostic cache that stores keyed pricing data as JSON files.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from cloudcosting.domain import CacheError
+
+DEFAULT_CACHE_DIR = Path.home() / ".cloudcosting" / "cache"
+DEFAULT_TTL_SECONDS = 86400  # 24 hours
+
+
+@dataclass(frozen=True)
+class CacheResult:
+    """Result of a cache retrieval."""
+
+    data: dict | None
+    status: str  # "fresh", "stale", "miss"
+    age_seconds: float | None = None
+
+
+class PriceCache:
+    """File-based key-value cache with TTL and provider-scoped refresh."""
+
+    def __init__(
+        self,
+        cache_dir: Path = DEFAULT_CACHE_DIR,
+        ttl_seconds: int = DEFAULT_TTL_SECONDS,
+    ):
+        self._cache_dir = cache_dir
+        self._ttl_seconds = ttl_seconds
+
+    def store(self, provider: str, key: tuple, data: dict) -> None:
+        """Store pricing data with a cache key."""
+        try:
+            self._cache_dir.mkdir(parents=True, exist_ok=True)
+            entry = {
+                "provider": provider,
+                "key": str(key),
+                "data": data,
+                "timestamp": time.time(),
+                "ttl_seconds": self._ttl_seconds,
+            }
+            filepath = self._key_to_path(key)
+            filepath.write_text(json.dumps(entry, indent=2))
+        except OSError as e:
+            raise CacheError(f"Failed to write cache: {e}") from e
+
+    def retrieve(self, key: tuple, allow_stale: bool = False) -> CacheResult:
+        """Retrieve cached data. Returns fresh, stale, or miss."""
+        filepath = self._key_to_path(key)
+        if not filepath.exists():
+            return CacheResult(data=None, status="miss")
+
+        try:
+            entry = json.loads(filepath.read_text())
+        except (OSError, json.JSONDecodeError) as e:
+            raise CacheError(f"Failed to read cache: {e}") from e
+
+        age = time.time() - entry["timestamp"]
+        is_expired = age > entry.get("ttl_seconds", self._ttl_seconds)
+
+        if not is_expired:
+            return CacheResult(data=entry["data"], status="fresh", age_seconds=age)
+
+        if allow_stale:
+            return CacheResult(data=entry["data"], status="stale", age_seconds=age)
+
+        return CacheResult(data=None, status="miss", age_seconds=age)
+
+    def refresh_provider(self, provider: str) -> int:
+        """Delete all cached entries for a provider. Returns count deleted."""
+        if not self._cache_dir.exists():
+            return 0
+        count = 0
+        for filepath in self._cache_dir.glob("*.json"):
+            try:
+                entry = json.loads(filepath.read_text())
+                if entry.get("provider") == provider:
+                    filepath.unlink()
+                    count += 1
+            except (OSError, json.JSONDecodeError):
+                continue
+        return count
+
+    def refresh_all(self) -> int:
+        """Delete all cached entries. Returns count deleted."""
+        if not self._cache_dir.exists():
+            return 0
+        count = 0
+        for filepath in self._cache_dir.glob("*.json"):
+            try:
+                filepath.unlink()
+                count += 1
+            except OSError:
+                continue
+        return count
+
+    def _key_to_path(self, key: tuple) -> Path:
+        """Deterministic hash of cache key to file path."""
+        key_str = json.dumps(key, sort_keys=True, default=str)
+        key_hash = hashlib.sha256(key_str.encode()).hexdigest()[:16]
+        return self._cache_dir / f"{key_hash}.json"

cloudcosting/cli.py

@@ -0,0 +1,155 @@
+"""CLI entry point for cloudcosting."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import yaml
+
+from cloudcosting import __version__
+from cloudcosting.cache import PriceCache
+from cloudcosting.domain import CloudCostError
+
+
+def main():
+    """Main CLI entry point."""
+    args = sys.argv[1:]
+
+    if not args or args[0] in ("-h", "--help"):
+        _print_help()
+        sys.exit(0)
+
+    if args[0] in ("-v", "--version"):
+        print(f"cloudcosting {__version__}")
+        sys.exit(0)
+
+    command = args[0]
+
+    if command == "estimate":
+        _cmd_estimate(args[1:])
+    elif command == "cache":
+        _cmd_cache(args[1:])
+    else:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        _print_help()
+        sys.exit(1)
+
+
+def _cmd_estimate(args: list[str]):
+    """Run cost estimation from a config file."""
+    if not args:
+        print(
+            "Usage: cloudcosting estimate <config.yaml> [--format yaml|json] [-o output]",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    config_path = Path(args[0])
+    output_format = "yaml"
+    output_path = None
+
+    i = 1
+    while i < len(args):
+        if args[i] == "--format" and i + 1 < len(args):
+            output_format = args[i + 1]
+            i += 2
+        elif args[i] == "-o" and i + 1 < len(args):
+            output_path = Path(args[i + 1])
+            i += 2
+        else:
+            print(f"Unknown option: {args[i]}", file=sys.stderr)
+            sys.exit(1)
+
+    try:
+        from cloudcosting.estimator import run_estimation
+
+        estimate = run_estimation(config_path)
+        result = estimate.to_dict()
+
+        if output_format == "json":
+            output = json.dumps(result, indent=2)
+        else:
+            output = yaml.dump(result, default_flow_style=False, sort_keys=False)
+
+        if output_path:
+            output_path.write_text(output)
+            print(f"Estimate written to {output_path}", file=sys.stderr)
+        else:
+            print(output)
+
+        # Print summary to stderr
+        totals = result["estimate"]["totals"]
+        status = result["estimate"]["status"]
+        n_resources = sum(len(p["resources"]) for p in result["estimate"]["providers"])
+        n_errors = len(result["estimate"]["errors"]) + sum(
+            len(p.get("errors", [])) for p in result["estimate"]["providers"]
+        )
+
+        print("\n--- Summary ---", file=sys.stderr)
+        print(f"Status: {status}", file=sys.stderr)
+        print(f"Resources estimated: {n_resources}", file=sys.stderr)
+        if n_errors > 0:
+            print(f"Errors: {n_errors}", file=sys.stderr)
+        print(f"Monthly total: ${totals['monthly']:,.2f}", file=sys.stderr)
+        print(f"Annual total:  ${totals['annual']:,.2f}", file=sys.stderr)
+
+        sys.exit(0 if status == "complete" else 1)
+
+    except CloudCostError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _cmd_cache(args: list[str]):
+    """Cache management commands."""
+    if not args:
+        print("Usage: cloudcosting cache <refresh|status>", file=sys.stderr)
+        sys.exit(1)
+
+    subcommand = args[0]
+    cache = PriceCache()
+
+    if subcommand == "refresh":
+        provider = args[1] if len(args) > 1 else None
+        if provider:
+            count = cache.refresh_provider(provider)
+            print(f"Deleted {count} cached entries for provider '{provider}'")
+        else:
+            count = cache.refresh_all()
+            print(f"Deleted {count} cached entries")
+    elif subcommand == "status":
+        cache_dir = cache._cache_dir
+        if cache_dir.exists():
+            files = list(cache_dir.glob("*.json"))
+            print(f"Cache directory: {cache_dir}")
+            print(f"Cached entries: {len(files)}")
+        else:
+            print(f"Cache directory: {cache_dir} (does not exist)")
+            print("Cached entries: 0")
+    else:
+        print(f"Unknown cache command: {subcommand}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _print_help():
+    print(f"""cloudcosting {__version__} - Multi-cloud infrastructure cost estimation
+
+Usage:
+  cloudcosting estimate <config.yaml> [--format yaml|json] [-o output_file]
+  cloudcosting cache refresh [provider]
+  cloudcosting cache status
+  cloudcosting --version
+  cloudcosting --help
+
+Commands:
+  estimate    Run cost estimation from a YAML configuration file
+  cache       Manage the pricing data cache
+
+Examples:
+  cloudcosting estimate infrastructure.yaml
+  cloudcosting estimate infrastructure.yaml --format json
+  cloudcosting estimate infrastructure.yaml -o costs.yaml
+  cloudcosting cache refresh aws
+  cloudcosting cache status""")

cloudcosting/config.py

@@ -0,0 +1,112 @@
+"""Config Loader: reads YAML, validates structure, returns EstimationConfig.
+
+Validates structural requirements only. Provider-specific fields pass through.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from cloudcosting.domain import ConfigError, EstimationConfig, ResourceSpec
+
+REQUIRED_RESOURCE_FIELDS = ("provider", "region", "type")
+
+
+def load_config(
+    path: Path,
+    known_providers: set[str] | None = None,
+) -> EstimationConfig:
+    """Load and validate a YAML configuration file.
+
+    Args:
+        path: Path to YAML config file.
+        known_providers: If provided, validate provider IDs against this set.
+
+    Returns:
+        EstimationConfig with validated resource specs.
+
+    Raises:
+        ConfigError: On any structural validation failure.
+    """
+    try:
+        raw = yaml.safe_load(path.read_text())
+    except FileNotFoundError:
+        raise ConfigError(f"Configuration file not found: {path}") from None
+    except yaml.YAMLError as e:
+        raise ConfigError(f"Invalid YAML in {path}: {e}") from e
+
+    if not isinstance(raw, dict):
+        raise ConfigError(
+            f"Configuration must be a YAML mapping, got {type(raw).__name__}"
+        )
+
+    # Extract top-level defaults
+    defaults = {}
+    if "provider" in raw:
+        defaults["provider"] = str(raw["provider"])
+    if "region" in raw:
+        defaults["region"] = str(raw["region"])
+
+    # Resources list is required
+    if "resources" not in raw:
+        raise ConfigError("Configuration must contain a 'resources' key")
+
+    raw_resources = raw["resources"]
+    if not isinstance(raw_resources, list):
+        raise ConfigError("'resources' must be a list")
+
+    if len(raw_resources) == 0:
+        raise ConfigError("'resources' list must not be empty")
+
+    resources = []
+    for i, res in enumerate(raw_resources):
+        if not isinstance(res, dict):
+            raise ConfigError(
+                f"Resource {i}: must be a mapping, got {type(res).__name__}"
+            )
+
+        # Apply defaults for missing fields
+        effective = {**defaults, **res}
+
+        # Check required fields
+        for field in REQUIRED_RESOURCE_FIELDS:
+            if field not in effective:
+                raise ConfigError(f"Resource {i}: missing required field '{field}'")
+            if not isinstance(effective[field], str):
+                raise ConfigError(
+                    f"Resource {i}: '{field}' must be a string, "
+                    f"got {type(effective[field]).__name__}"
+                )
+
+        provider = effective["provider"]
+        region = effective["region"]
+        resource_type = effective["type"]
+
+        # Validate provider ID if registry is available
+        if known_providers is not None and provider not in known_providers:
+            raise ConfigError(
+                f"Resource {i}: unknown provider '{provider}'. "
+                f"Known providers: {sorted(known_providers)}"
+            )
+
+        # Extract label, pass everything else as params
+        label = str(effective.get("label", ""))
+        params = {
+            k: v
+            for k, v in effective.items()
+            if k not in ("provider", "region", "type", "label")
+        }
+
+        resources.append(
+            ResourceSpec(
+                provider=provider,
+                region=region,
+                type=resource_type,
+                params=params,
+                label=label,
+            )
+        )
+
+    return EstimationConfig(resources=tuple(resources), defaults=defaults)

cloudcosting/domain.py

@@ -0,0 +1,159 @@
+"""Domain objects and exceptions for cloudcosting.
+
+All data flowing through the system is represented here.
+No component defines its own ad-hoc dictionaries for passing data.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# -- Exceptions --
+
+
+class CloudCostError(Exception):
+    """Base exception for all cloudcosting errors."""
+
+
+class ConfigError(CloudCostError):
+    """Configuration file is malformed or missing required fields."""
+
+
+class ProviderError(CloudCostError):
+    """Provider-specific validation failure."""
+
+
+class PricingError(CloudCostError):
+    """Unable to fetch or parse pricing data."""
+
+
+class CacheError(CloudCostError):
+    """Cache read/write failure (filesystem issues)."""
+
+
+# -- Input domain --
+
+
+@dataclass(frozen=True)
+class ResourceSpec:
+    """A single resource specification from the configuration."""
+
+    provider: str
+    region: str
+    type: str
+    params: dict = field(default_factory=dict)
+    label: str = ""
+
+
+@dataclass(frozen=True)
+class EstimationConfig:
+    """Full parsed configuration: resources plus global defaults."""
+
+    resources: tuple[ResourceSpec, ...]
+    defaults: dict = field(default_factory=dict)
+
+
+# -- Output domain --
+
+
+@dataclass(frozen=True)
+class CostLineItem:
+    """One cost component (e.g., instance, storage, backup)."""
+
+    name: str
+    monthly: float
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "monthly": round(self.monthly, 2)}
+
+
+@dataclass(frozen=True)
+class ResourceCost:
+    """Full cost breakdown for one successfully estimated resource."""
+
+    label: str
+    type: str
+    monthly: float
+    annual: float
+    line_items: tuple[CostLineItem, ...]
+    notes: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict:
+        result = {
+            "label": self.label,
+            "type": self.type,
+            "monthly": round(self.monthly, 2),
+            "annual": round(self.annual, 2),
+            "line_items": [item.to_dict() for item in self.line_items],
+        }
+        if self.notes:
+            result["notes"] = list(self.notes)
+        return result
+
+
+@dataclass(frozen=True)
+class ResourceError:
+    """A failed resource with reason."""
+
+    label: str
+    type: str
+    reason: str
+
+    def to_dict(self) -> dict:
+        return {"label": self.label, "type": self.type, "reason": self.reason}
+
+
+@dataclass(frozen=True)
+class ProviderEstimate:
+    """Results for one provider: metadata + resource breakdowns + errors."""
+
+    provider: str
+    region: str
+    pricing_date: str
+    currency: str
+    cache_status: str
+    resources: tuple[ResourceCost, ...]
+    errors: tuple[ResourceError, ...] = ()
+
+    def to_dict(self) -> dict:
+        result = {
+            "provider": self.provider,
+            "region": self.region,
+            "pricing_date": self.pricing_date,
+            "currency": self.currency,
+            "cache_status": self.cache_status,
+            "resources": [r.to_dict() for r in self.resources],
+        }
+        if self.errors:
+            result["errors"] = [e.to_dict() for e in self.errors]
+        return result
+
+
+@dataclass(frozen=True)
+class Estimate:
+    """Top-level output: everything the CLI needs to serialize."""
+
+    version: str
+    timestamp: str
+    status: str  # "complete" or "partial"
+    providers: tuple[ProviderEstimate, ...]
+    totals: dict  # {"monthly": float, "annual": float}
+    errors: tuple[ResourceError, ...] = ()
+    warnings: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict:
+        result: dict = {
+            "estimate": {
+                "version": self.version,
+                "timestamp": self.timestamp,
+                "status": self.status,
+                "providers": [p.to_dict() for p in self.providers],
+                "totals": {
+                    "monthly": round(self.totals.get("monthly", 0.0), 2),
+                    "annual": round(self.totals.get("annual", 0.0), 2),
+                },
+                "errors": [e.to_dict() for e in self.errors],
+                "warnings": list(self.warnings),
+            }
+        }
+        return result

cloudcosting/estimator.py

@@ -0,0 +1,104 @@
+"""Estimator: Transaction script that orchestrates the full estimation workflow.
+
+Load config -> group resources by provider/region -> estimate -> aggregate -> return Estimate.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import UTC, datetime
+from pathlib import Path
+
+from cloudcosting import __version__
+from cloudcosting.cache import PriceCache
+from cloudcosting.config import load_config
+from cloudcosting.domain import (
+    Estimate,
+    EstimationConfig,
+    ProviderEstimate,
+    ResourceError,
+    ResourceSpec,
+)
+from cloudcosting.providers.registry import ProviderRegistry
+
+
+def run_estimation(
+    config_path: Path,
+    cache: PriceCache | None = None,
+) -> Estimate:
+    """Full estimation workflow: config -> providers -> aggregate.
+
+    This is the main entry point for the estimation pipeline.
+    """
+    if cache is None:
+        cache = PriceCache()
+
+    registry = ProviderRegistry(cache=cache)
+
+    # Load and validate config
+    config = load_config(config_path, known_providers=registry.known_ids)
+
+    return estimate_from_config(config, registry)
+
+
+def estimate_from_config(
+    config: EstimationConfig,
+    registry: ProviderRegistry,
+) -> Estimate:
+    """Estimate costs from an already-loaded config."""
+    # Group resources by (provider, region)
+    groups: dict[tuple[str, str], list[ResourceSpec]] = defaultdict(list)
+    global_errors: list[ResourceError] = []
+
+    for spec in config.resources:
+        provider = registry.get(spec.provider)
+        if provider is None:
+            global_errors.append(
+                ResourceError(
+                    label=spec.label or spec.type,
+                    type=spec.type,
+                    reason=f"No provider registered for '{spec.provider}'",
+                )
+            )
+            continue
+        groups[(spec.provider, spec.region)].append(spec)
+
+    # Run estimation per provider/region group
+    provider_estimates: list[ProviderEstimate] = []
+    for (provider_id, region), specs in groups.items():
+        provider = registry.get(provider_id)
+        pe = provider.estimate_resources(specs, region)
+        provider_estimates.append(pe)
+
+    # Aggregate totals
+    total_monthly = sum(rc.monthly for pe in provider_estimates for rc in pe.resources)
+    total_annual = total_monthly * 12
+
+    # Determine status
+    all_errors = list(global_errors)
+    for pe in provider_estimates:
+        all_errors.extend(pe.errors)
+
+    has_results = any(pe.resources for pe in provider_estimates)
+    if all_errors and has_results:
+        status = "partial"
+    elif all_errors and not has_results:
+        status = "failed"
+    else:
+        status = "complete"
+
+    # Collect warnings
+    warnings = []
+    for pe in provider_estimates:
+        if pe.cache_status == "stale":
+            warnings.append(f"Using stale cached pricing for {pe.provider}/{pe.region}")
+
+    return Estimate(
+        version=__version__,
+        timestamp=datetime.now(UTC).isoformat(),
+        status=status,
+        providers=tuple(provider_estimates),
+        totals={"monthly": total_monthly, "annual": total_annual},
+        errors=tuple(global_errors),
+        warnings=tuple(warnings),
+    )