modal 1.5.1.dev7__tar.gz → 1.5.1.dev8__tar.gz

{modal-1.5.1.dev7 → modal-1.5.1.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.5.1.dev7
+Version: 1.5.1.dev8
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

modal-1.5.1.dev8/modal/_billing.py

@@ -0,0 +1,155 @@
+# Copyright Modal Labs 2025
+from dataclasses import FrozenInstanceError, dataclass
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import Any, Iterable, TypedDict
+
+from modal_proto import api_pb2
+
+from ._utils.deprecation import deprecation_warning
+from .client import _Client
+
+BILLING_DOCSTRING = """
+            The `start` and `end` parameters are required to either have a UTC timezone or to be
+            timezone-naive (which will be interpreted as UTC times). The timestamps in the result will
+            be in UTC. Cost will be reported for full intervals, even if the provided `start` or `end`
+            parameters are partial: `start` will be rounded to the beginning of its interval, while
+            partial `end` intervals will be excluded.
+
+            Additional user-provided metadata can be included in the report if the objects have tags
+            and `tag_names` (i.e., keys) are specified in the request. Alternatively, pass `tag_names=["*"]`
+            to include all tags in the report. Note that tags will be attributed to the entire interval even
+            if they were added or removed at some point within it. If the tag name was not in use during an
+            interval, it will be absent from the tags dictionary in that output row.
+
+            In most cases, billing data will be available in the database that this API queries within
+            minutes, although there may be collection delays. If completeness is important for your use
+            case, we recommend leaving a buffer after the end of the query interval.
+"""
+
+
+class WorkspaceBillingReportItem(TypedDict):
+    object_id: str
+    description: str
+    environment_name: str
+    interval_start: datetime
+    cost: Decimal
+    tags: dict[str, str]
+
+
+@dataclass(slots=True, frozen=True)
+class BillingReportItem:
+    object_id: str
+    description: str
+    environment_name: str
+    interval_start: datetime
+    cost: Decimal
+    cost_by_resource: dict[str, Decimal]
+    tags: dict[str, str]
+
+    def __getitem__(self, key: str) -> Any:
+        """mdmd:ignore"""
+        if key not in self.__slots__:
+            raise KeyError(key)
+
+        return getattr(self, key)
+
+    def __setitem__(self, key: str, _: Any):
+        """mdmd:ignore"""
+        raise FrozenInstanceError(f"cannot assign to field {key!r}")
+
+    def keys(self) -> Iterable[str]:
+        """mdmd:ignore"""
+        yield from self.__slots__
+
+    def values(self) -> Iterable[Any]:
+        """mdmd:ignore"""
+        for k in self.__slots__:
+            yield getattr(self, k)
+
+    def items(self) -> Iterable[tuple[str, Any]]:
+        """mdmd:ignore"""
+        for k in self.__slots__:
+            yield k, getattr(self, k)
+
+    @classmethod
+    def _from_proto(cls, pb_item: api_pb2.WorkspaceBillingReportItem) -> "BillingReportItem":
+        return cls(
+            object_id=pb_item.object_id,
+            description=pb_item.description,
+            environment_name=pb_item.environment_name,
+            interval_start=pb_item.interval.ToDatetime().replace(tzinfo=timezone.utc),
+            cost=Decimal(pb_item.cost),
+            cost_by_resource={k: Decimal(str(v)) for k, v in pb_item.cost_by_resource.items()},
+            tags=dict(pb_item.tags),
+        )
+
+
+async def _workspace_billing_report(
+    *,
+    start: datetime,  # Start of the report, inclusive
+    end: datetime | None = None,  # End of the report, exclusive
+    resolution: str = "d",  # Resolution, e.g. "d" for daily or "h" for hourly
+    tag_names: list[str] | None = None,  # Optional additional metadata to include
+    client: _Client | None = None,
+) -> list[WorkspaceBillingReportItem]:
+    """Generate a tabular report of workspace usage by object and time.
+
+    The result will be a list of dictionaries for each interval (determined by `resolution`)
+    between the `start` and `end` limits. The dictionary represents a single Modal object
+    that billing can be attributed to (e.g., an App) along with metadata (including user-defined
+    tags) for identifying that object. The dictionary also contains a breakdown of the cost value
+    attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
+    etc.). The specific resource types included in the breakdown are subject to change as
+    Modal's billing model evolves.
+
+    The `start` and `end` parameters are required to either have a UTC timezone or to be
+    timezone-naive (which will be interpreted as UTC times). The timestamps in the result will
+    be in UTC. Cost will be reported for full intervals, even if the provided `start` or `end`
+    parameters are partial: `start` will be rounded to the beginning of its interval, while
+    partial `end` intervals will be excluded.
+
+    Additional user-provided metadata can be included in the report if the objects have tags
+    and `tag_names` (i.e., keys) are specified in the request. Alternatively, pass `tag_names=["*"]`
+    to include all tags in the report. Note that tags will be attributed to the entire interval even
+    if they were added or removed at some point within it. If the tag name was not in use during an
+    interval, it will be absent from the tags dictionary in that output row.
+
+    In most cases, billing data will be available in the database that this API queries within
+    minutes, although there may be collection delays. If completeness is important for your use
+    case, we recommend leaving a buffer after the end of the query interval.
+
+    It's also possible to generate reports using the
+    [`modal billing report`](https://modal.com/docs/reference/cli/billing) CLI command. The CLI
+    has a few convenience features for generating reports across relative time ranges.
+
+    """
+
+    deprecation_warning(
+        (2026, 6, 18),
+        "`workspace_billing_report()` is deprecated. Use `Workspace.billing.report()` instead.",
+    )
+
+    from ._workspace import _Workspace
+
+    data = await _Workspace.from_context(client=client).billing.report(
+        start=start,
+        end=end,
+        resolution=resolution,
+        tag_names=tag_names,
+    )
+
+    res: list[WorkspaceBillingReportItem] = []
+    for datum in data:
+        item: WorkspaceBillingReportItem = {
+            "object_id": datum.object_id,
+            "description": datum.description,
+            "environment_name": datum.environment_name,
+            "interval_start": datum.interval_start,
+            "cost": Decimal(datum.cost),
+            "tags": dict(datum.tags),
+        }
+
+        res.append(item)
+
+    return res

{modal-1.5.1.dev7 → modal-1.5.1.dev8}/modal/_environments.py

@@ -3,6 +3,7 @@ import asyncio
 import builtins
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from typing import Literal
 
 from google.protobuf.empty_pb2 import Empty
@@ -12,6 +13,7 @@ from synchronicity import classproperty
 
 from modal_proto import api_pb2
 
+from ._billing import BILLING_DOCSTRING, BillingReportItem
 from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
@@ -318,7 +320,7 @@ class _Environment(_Object, type_prefix="en"):
     # def settings(self) -> EnvironmentSettings:
     #     return self._settings
 
-    def _hydrate_metadata(self, metadata: Message):
+    def _hydrate_metadata(self, metadata: Message | None):
         # Overridden concrete implementation of base class method
         assert metadata and isinstance(metadata, api_pb2.EnvironmentMetadata)
         self._name = metadata.name or None
@@ -392,6 +394,79 @@ class _Environment(_Object, type_prefix="en"):
             client=client,
         )
 
+    @property
+    def billing(self) -> "_EnvironmentBillingManager":
+        return _EnvironmentBillingManager(self)
+
+
+class _EnvironmentBillingManager:
+    """mdmd:namespace
+    Namespace for Environment billing APIs
+    """
+
+    def __init__(self, environment: _Environment):
+        """mdmd:ignore"""
+        self._environment = environment
+
+    async def report(
+        self,
+        *,
+        start: datetime,  # Start of the report, inclusive
+        end: datetime | None = None,  # End of the report, exclusive
+        resolution: str = "d",  # Resolution, e.g. "d" for daily or "h" for hourly
+        tag_names: list[str] | None = None,  # Optional additional metadata to include
+    ) -> list[BillingReportItem]:
+        (
+            """Return a report of workspace usage by object and time, scoped to the calling Environment.
+
+            The result will be a list of dataclasses for each interval (determined by `resolution`)
+            between the `start` and `end` limits. Each item represents a single (Modal object, time interval)
+            pair that billing can be attributed to (e.g., an App) along with metadata (including user-defined
+            tags) to identify that object. The dataclass also contains a breakdown of the cost value
+            attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
+            etc.). The specific resource types included in the breakdown are subject to change as
+            Modal's billing model evolves.
+
+            It's also possible to generate reports using the
+            [`modal environment billing report`](https://modal.com/docs/reference/cli/environment) CLI command.
+            The CLI has a few convenience features for generating reports across relative time ranges.
+
+            """
+            + BILLING_DOCSTRING
+        )
+
+        if tag_names is None:
+            tag_names = []
+
+        if end is None:
+            end = datetime.now(timezone.utc)
+
+        if start.tzinfo is None:
+            start = start.replace(tzinfo=timezone.utc)
+        elif start.tzinfo != timezone.utc:
+            raise InvalidError("Timezone-aware 'start' parameter must be in UTC.")
+
+        if end.tzinfo is None:
+            end = end.replace(tzinfo=timezone.utc)
+        elif end.tzinfo != timezone.utc:
+            raise InvalidError("Timezone-aware 'end' parameter must be in UTC.")
+
+        if not self._environment.is_hydrated:
+            await self._environment.hydrate()
+
+        request = api_pb2.WorkspaceBillingReportRequest(
+            resolution=resolution,
+            tag_names=tag_names,
+            environment_ids=[self._environment.object_id],
+        )
+        request.start_timestamp.FromDatetime(start)
+        request.end_timestamp.FromDatetime(end)
+
+        return [
+            BillingReportItem._from_proto(pb_item)
+            async for pb_item in self._environment.client.stub.WorkspaceBillingReport.unary_stream(request)
+        ]
+
 
 ENVIRONMENT_CACHE: dict[str, _Environment] = {}
 

{modal-1.5.1.dev7 → modal-1.5.1.dev8}/modal/_grpc_client.py

@@ -1,6 +1,6 @@
 # Copyright Modal Labs 2025
 from collections.abc import Collection, Mapping
-from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, overload
+from typing import TYPE_CHECKING, Any, AsyncGenerator, Generic, Literal, TypeVar, overload
 
 import grpclib.client
 from google.protobuf.message import Message
@@ -178,9 +178,9 @@ class UnaryStreamWrapper(Generic[RequestType, ResponseType]):
 
     async def unary_stream(
         self,
-        request,
+        request: RequestType,
         metadata: Any | None = None,
-    ):
+    ) -> AsyncGenerator[ResponseType, None]:
         from .client import _Client
 
         if self.client._snapshotted:

{modal-1.5.1.dev7 → modal-1.5.1.dev8}/modal/_utils/time_utils.py

@@ -256,3 +256,26 @@ def timestamp_to_localized_str(ts: float, isotz: bool = True) -> str | None:
             return f"{dt:%Y-%m-%d %H:%M %Z}"
     else:
         return None
+
+
+def format_interval(
+    dt: datetime,
+    *,
+    tz: tzinfo | None = None,
+    isoformat: bool = False,
+    show_date_only: bool = False,
+) -> str:
+    if tz is not None:
+        dt = dt.astimezone(tz)
+    else:
+        # Strip UTC tzinfo so isoformat() doesn't append +00:00
+        dt = dt.replace(tzinfo=None)
+    if isoformat:
+        # Full ISO format for machine-readable output
+        return dt.isoformat()
+    elif show_date_only:
+        # Just the date for daily resolution
+        return dt.strftime("%Y-%m-%d")
+    else:
+        # Date and time without seconds for hourly resolution
+        return dt.strftime("%Y-%m-%dT%H:%M")

{modal-1.5.1.dev7 → modal-1.5.1.dev8}/modal/_workspace.py

@@ -1,13 +1,15 @@
 # Copyright Modal Labs 2025
 import builtins
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Literal, Optional
 
 from google.protobuf.empty_pb2 import Empty
 
+from modal.exception import InvalidError
 from modal_proto import api_pb2
 
+from ._billing import BILLING_DOCSTRING, BillingReportItem
 from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
@@ -114,3 +116,75 @@ class _Workspace(_Object, type_prefix="ac"):
             hydrate_lazily=True,
             load_context_overrides=LoadContext(client=client),
         )
+
+    @property
+    def billing(self) -> "_WorkspaceBillingManager":
+        return _WorkspaceBillingManager(self)
+
+
+class _WorkspaceBillingManager:
+    """mdmd:namespace
+    Namespace for Workspace billing APIs
+    """
+
+    def __init__(self, workspace: _Workspace):
+        """mdmd:hidden"""
+        self._workspace = workspace
+
+    async def report(
+        self,
+        *,
+        start: datetime,  # Start of the report, inclusive
+        end: datetime | None = None,  # End of the report, exclusive
+        resolution: str = "d",  # Resolution, e.g. "d" for daily or "h" for hourly
+        tag_names: list[str] | None = None,  # Optional additional metadata to include
+    ) -> list[BillingReportItem]:
+        (
+            """Return a report of workspace usage by object and time.
+
+            The result will be a list of dataclasses for each interval (determined by `resolution`)
+            between the `start` and `end` limits. Each item represents a single (Modal object, time interval)
+            pair that billing can be attributed to (e.g., an App) along with metadata (including user-defined
+            tags) to identify that object. The dataclass also contains a breakdown of the cost value
+            attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
+            etc.). The specific resource types included in the breakdown are subject to change as
+            Modal's billing model evolves.
+
+            It's also possible to generate reports using the
+            [`modal billing report`](https://modal.com/docs/reference/cli/billing) CLI command. The CLI
+            has a few convenience features for generating reports across relative time ranges.
+
+            """
+            + BILLING_DOCSTRING
+        )
+
+        if tag_names is None:
+            tag_names = []
+
+        if end is None:
+            end = datetime.now(timezone.utc)
+
+        if start.tzinfo is None:
+            start = start.replace(tzinfo=timezone.utc)
+        elif start.tzinfo != timezone.utc:
+            raise InvalidError("Timezone-aware 'start' parameter must be in UTC.")
+
+        if end.tzinfo is None:
+            end = end.replace(tzinfo=timezone.utc)
+        elif end.tzinfo != timezone.utc:
+            raise InvalidError("Timezone-aware 'end' parameter must be in UTC.")
+
+        if not self._workspace.is_hydrated:
+            await self._workspace.hydrate()
+
+        request = api_pb2.WorkspaceBillingReportRequest(
+            resolution=resolution,
+            tag_names=tag_names,
+        )
+        request.start_timestamp.FromDatetime(start)
+        request.end_timestamp.FromDatetime(end)
+
+        return [
+            BillingReportItem._from_proto(pb_item)
+            async for pb_item in self._workspace.client.stub.WorkspaceBillingReport.unary_stream(request)
+        ]

{modal-1.5.1.dev7 → modal-1.5.1.dev8}/modal/billing.py

@@ -1,10 +1,11 @@
 # Copyright Modal Labs 2025
-from ._billing import WorkspaceBillingReportItem, _workspace_billing_report
+from ._billing import BillingReportItem, WorkspaceBillingReportItem, _workspace_billing_report
 from ._utils.async_utils import synchronize_api
 
-workspace_billing_report = synchronize_api(_workspace_billing_report)
+workspace_billing_report = synchronize_api(_workspace_billing_report, target_module=__name__)
 
 __all__ = [
     "workspace_billing_report",
     "WorkspaceBillingReportItem",
+    "BillingReportItem",
 ]

modal-1.5.1.dev8/modal/billing.pyi

@@ -0,0 +1,184 @@
+import datetime
+import decimal
+import modal._billing
+import modal.client
+import modal_proto.api_pb2
+import typing
+import typing_extensions
+
+class BillingReportItem:
+    """BillingReportItem(object_id: str, description: str, environment_name: str, interval_start: datetime.datetime, cost: decimal.Decimal, cost_by_resource: dict[str, decimal.Decimal], tags: dict[str, str])"""
+
+    object_id: str
+    description: str
+    environment_name: str
+    interval_start: datetime.datetime
+    cost: decimal.Decimal
+    cost_by_resource: dict[str, decimal.Decimal]
+    tags: dict[str, str]
+
+    def __getitem__(self, key: str) -> typing.Any:
+        """mdmd:ignore"""
+        ...
+
+    def __setitem__(self, key: str, _: typing.Any):
+        """mdmd:ignore"""
+        ...
+
+    def keys(self) -> typing.Iterable[str]:
+        """mdmd:ignore"""
+        ...
+
+    def values(self) -> typing.Iterable[typing.Any]:
+        """mdmd:ignore"""
+        ...
+
+    def items(self) -> typing.Iterable[tuple[str, typing.Any]]:
+        """mdmd:ignore"""
+        ...
+
+    @classmethod
+    def _from_proto(
+        cls, pb_item: modal_proto.api_pb2.WorkspaceBillingReportItem
+    ) -> modal._billing.BillingReportItem: ...
+    def __init__(
+        self,
+        object_id: str,
+        description: str,
+        environment_name: str,
+        interval_start: datetime.datetime,
+        cost: decimal.Decimal,
+        cost_by_resource: dict[str, decimal.Decimal],
+        tags: dict[str, str],
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+    def __setattr__(self, name, value):
+        """Implement setattr(self, name, value)."""
+        ...
+
+    def __delattr__(self, name):
+        """Implement delattr(self, name)."""
+        ...
+
+    def __hash__(self):
+        """Return hash(self)."""
+        ...
+
+    def __getstate__(self): ...
+    def __setstate__(self, state): ...
+
+class WorkspaceBillingReportItem(typing.TypedDict):
+    """dict() -> new empty dictionary
+    dict(mapping) -> new dictionary initialized from a mapping object's
+        (key, value) pairs
+    dict(iterable) -> new dictionary initialized as if via:
+        d = {}
+        for k, v in iterable:
+            d[k] = v
+    dict(**kwargs) -> new dictionary initialized with the name=value pairs
+        in the keyword argument list.  For example:  dict(one=1, two=2)
+    """
+
+    object_id: str
+    description: str
+    environment_name: str
+    interval_start: datetime.datetime
+    cost: decimal.Decimal
+    tags: dict[str, str]
+
+class __workspace_billing_report_spec(typing_extensions.Protocol):
+    def __call__(
+        self,
+        /,
+        *,
+        start: datetime.datetime,
+        end: typing.Optional[datetime.datetime] = None,
+        resolution: str = "d",
+        tag_names: typing.Optional[list[str]] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ) -> list[modal._billing.WorkspaceBillingReportItem]:
+        """Generate a tabular report of workspace usage by object and time.
+
+        The result will be a list of dictionaries for each interval (determined by `resolution`)
+        between the `start` and `end` limits. The dictionary represents a single Modal object
+        that billing can be attributed to (e.g., an App) along with metadata (including user-defined
+        tags) for identifying that object. The dictionary also contains a breakdown of the cost value
+        attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
+        etc.). The specific resource types included in the breakdown are subject to change as
+        Modal's billing model evolves.
+
+        The `start` and `end` parameters are required to either have a UTC timezone or to be
+        timezone-naive (which will be interpreted as UTC times). The timestamps in the result will
+        be in UTC. Cost will be reported for full intervals, even if the provided `start` or `end`
+        parameters are partial: `start` will be rounded to the beginning of its interval, while
+        partial `end` intervals will be excluded.
+
+        Additional user-provided metadata can be included in the report if the objects have tags
+        and `tag_names` (i.e., keys) are specified in the request. Alternatively, pass `tag_names=["*"]`
+        to include all tags in the report. Note that tags will be attributed to the entire interval even
+        if they were added or removed at some point within it. If the tag name was not in use during an
+        interval, it will be absent from the tags dictionary in that output row.
+
+        In most cases, billing data will be available in the database that this API queries within
+        minutes, although there may be collection delays. If completeness is important for your use
+        case, we recommend leaving a buffer after the end of the query interval.
+
+        It's also possible to generate reports using the
+        [`modal billing report`](https://modal.com/docs/reference/cli/billing) CLI command. The CLI
+        has a few convenience features for generating reports across relative time ranges.
+        """
+        ...
+
+    async def aio(
+        self,
+        /,
+        *,
+        start: datetime.datetime,
+        end: typing.Optional[datetime.datetime] = None,
+        resolution: str = "d",
+        tag_names: typing.Optional[list[str]] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ) -> list[modal._billing.WorkspaceBillingReportItem]:
+        """Generate a tabular report of workspace usage by object and time.
+
+        The result will be a list of dictionaries for each interval (determined by `resolution`)
+        between the `start` and `end` limits. The dictionary represents a single Modal object
+        that billing can be attributed to (e.g., an App) along with metadata (including user-defined
+        tags) for identifying that object. The dictionary also contains a breakdown of the cost value
+        attributed to individual resources (for an App, this can be CPU, Memory, specific GPU types,
+        etc.). The specific resource types included in the breakdown are subject to change as
+        Modal's billing model evolves.
+
+        The `start` and `end` parameters are required to either have a UTC timezone or to be
+        timezone-naive (which will be interpreted as UTC times). The timestamps in the result will
+        be in UTC. Cost will be reported for full intervals, even if the provided `start` or `end`
+        parameters are partial: `start` will be rounded to the beginning of its interval, while
+        partial `end` intervals will be excluded.
+
+        Additional user-provided metadata can be included in the report if the objects have tags
+        and `tag_names` (i.e., keys) are specified in the request. Alternatively, pass `tag_names=["*"]`
+        to include all tags in the report. Note that tags will be attributed to the entire interval even
+        if they were added or removed at some point within it. If the tag name was not in use during an
+        interval, it will be absent from the tags dictionary in that output row.
+
+        In most cases, billing data will be available in the database that this API queries within
+        minutes, although there may be collection delays. If completeness is important for your use
+        case, we recommend leaving a buffer after the end of the query interval.
+
+        It's also possible to generate reports using the
+        [`modal billing report`](https://modal.com/docs/reference/cli/billing) CLI command. The CLI
+        has a few convenience features for generating reports across relative time ranges.
+        """
+        ...
+
+workspace_billing_report: __workspace_billing_report_spec