samsara-api 0.0.1__py3-none-any.whl → 0.0.2__py3-none-any.whl

samsara/vehicles/stats/client.py

@@ -3,9 +3,10 @@
 import typing
 
 from ...core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ...core.pagination import AsyncPager, SyncPager
 from ...core.request_options import RequestOptions
-from ...types.vehicle_stats_list_response import VehicleStatsListResponse
-from ...types.vehicle_stats_response import VehicleStatsResponse
+from ...types.vehicle_stats_list_response_data import VehicleStatsListResponseData
+from ...types.vehicle_stats_response_data import VehicleStatsResponseData
 from .raw_client import AsyncRawStatsClient, RawStatsClient
 from .types.stats_feed_request_decorations_item import StatsFeedRequestDecorationsItem
 from .types.stats_feed_request_types_item import StatsFeedRequestTypesItem
@@ -41,7 +42,7 @@ class StatsClient:
             typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VehicleStatsResponse:
+    ) -> SyncPager[VehicleStatsResponseData]:
         """
         Returns the last known stats of all vehicles at the given `time`. If no `time` is specified, the current time is used.
 
@@ -71,7 +72,7 @@ class StatsClient:
         types : typing.Optional[typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]]
             The stat types you want this endpoint to return information on. See also the <a href="/docs/telematics#query-parameters" target="_blank">Telematics</a> guide for more details.
 
-            You may list ***up to 3*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
+            You may list ***up to 4*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
 
             *Note:* `auxInput3`-`auxInput10` count as a single type against the limit of 3. For example, you could list `types=engineStates,obdOdometerMeters,auxInput3,auxInput4` because `auxInput3` and `auxInput4` count as a single stat type. `auxInput1` and `auxInput2` still count as their own individual types.
 
@@ -128,7 +129,7 @@ class StatsClient:
 
         Returns
         -------
-        VehicleStatsResponse
+        SyncPager[VehicleStatsResponseData]
             Vehicle stats snapshot
 
         Examples
@@ -138,9 +139,14 @@ class StatsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.vehicles.stats.list()
+        response = client.vehicles.stats.list()
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
         """
-        _response = self._raw_client.list(
+        return self._raw_client.list(
             after=after,
             time=time,
             parent_tag_ids=parent_tag_ids,
@@ -149,7 +155,6 @@ class StatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
     def feed(
         self,
@@ -165,7 +170,7 @@ class StatsClient:
             typing.Union[StatsFeedRequestDecorationsItem, typing.Sequence[StatsFeedRequestDecorationsItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VehicleStatsListResponse:
+    ) -> SyncPager[VehicleStatsListResponseData]:
         """
         Follow a feed of vehicle stats.
 
@@ -198,7 +203,7 @@ class StatsClient:
         types : typing.Optional[typing.Union[StatsFeedRequestTypesItem, typing.Sequence[StatsFeedRequestTypesItem]]]
             The stat types you want this endpoint to return information on. See also the <a href="/docs/telematics#query-parameters" target="_blank">Telematics</a> guide for more details.
 
-            You may list ***up to 3*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
+            You may list ***up to 4*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
 
             *Note:* `auxInput3`-`auxInput10` count as a single type against the limit of 3. For example, you could list `types=engineStates,obdOdometerMeters,auxInput3,auxInput4` because `auxInput3` and `auxInput4` count as a single stat type. `auxInput1` and `auxInput2` still count as their own individual types.
 
@@ -308,7 +313,7 @@ class StatsClient:
 
         Returns
         -------
-        VehicleStatsListResponse
+        SyncPager[VehicleStatsListResponseData]
             List of stat events for the specified vehicles and stat types.
 
         Examples
@@ -318,9 +323,14 @@ class StatsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.vehicles.stats.feed()
+        response = client.vehicles.stats.feed()
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
         """
-        _response = self._raw_client.feed(
+        return self._raw_client.feed(
             after=after,
             parent_tag_ids=parent_tag_ids,
             tag_ids=tag_ids,
@@ -329,7 +339,6 @@ class StatsClient:
             decorations=decorations,
             request_options=request_options,
         )
-        return _response.data
 
     def history(
         self,
@@ -347,7 +356,7 @@ class StatsClient:
             typing.Union[StatsHistoryRequestDecorationsItem, typing.Sequence[StatsHistoryRequestDecorationsItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VehicleStatsListResponse:
+    ) -> SyncPager[VehicleStatsListResponseData]:
         """
         Returns vehicle stats during the given time range for all vehicles. This can be optionally filtered by tags or specific vehicle IDs.
 
@@ -380,7 +389,7 @@ class StatsClient:
         types : typing.Optional[typing.Union[StatsHistoryRequestTypesItem, typing.Sequence[StatsHistoryRequestTypesItem]]]
             The stat types you want this endpoint to return information on. See also the <a href="/docs/telematics#query-parameters" target="_blank">Telematics</a> guide for more details.
 
-            You may list ***up to 3*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
+            You may list ***up to 4*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
 
             *Note:* `auxInput3`-`auxInput10` count as a single type against the limit of 3. For example, you could list `types=engineStates,obdOdometerMeters,auxInput3,auxInput4` because `auxInput3` and `auxInput4` count as a single stat type. `auxInput1` and `auxInput2` still count as their own individual types.
 
@@ -490,7 +499,7 @@ class StatsClient:
 
         Returns
         -------
-        VehicleStatsListResponse
+        SyncPager[VehicleStatsListResponseData]
             List of vehicle stats for the specified vehicles, stat type, and time range.
 
         Examples
@@ -500,12 +509,17 @@ class StatsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.vehicles.stats.history(
+        response = client.vehicles.stats.history(
             start_time="startTime",
             end_time="endTime",
         )
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
         """
-        _response = self._raw_client.history(
+        return self._raw_client.history(
             start_time=start_time,
             end_time=end_time,
             after=after,
@@ -516,7 +530,6 @@ class StatsClient:
             decorations=decorations,
             request_options=request_options,
         )
-        return _response.data
 
 
 class AsyncStatsClient:
@@ -546,7 +559,7 @@ class AsyncStatsClient:
             typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VehicleStatsResponse:
+    ) -> AsyncPager[VehicleStatsResponseData]:
         """
         Returns the last known stats of all vehicles at the given `time`. If no `time` is specified, the current time is used.
 
@@ -576,7 +589,7 @@ class AsyncStatsClient:
         types : typing.Optional[typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]]
             The stat types you want this endpoint to return information on. See also the <a href="/docs/telematics#query-parameters" target="_blank">Telematics</a> guide for more details.
 
-            You may list ***up to 3*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
+            You may list ***up to 4*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
 
             *Note:* `auxInput3`-`auxInput10` count as a single type against the limit of 3. For example, you could list `types=engineStates,obdOdometerMeters,auxInput3,auxInput4` because `auxInput3` and `auxInput4` count as a single stat type. `auxInput1` and `auxInput2` still count as their own individual types.
 
@@ -633,7 +646,7 @@ class AsyncStatsClient:
 
         Returns
         -------
-        VehicleStatsResponse
+        AsyncPager[VehicleStatsResponseData]
             Vehicle stats snapshot
 
         Examples
@@ -648,12 +661,18 @@ class AsyncStatsClient:
 
 
         async def main() -> None:
-            await client.vehicles.stats.list()
+            response = await client.vehicles.stats.list()
+            async for item in response:
+                yield item
+
+            # alternatively, you can paginate page-by-page
+            async for page in response.iter_pages():
+                yield page
 
 
         asyncio.run(main())
         """
-        _response = await self._raw_client.list(
+        return await self._raw_client.list(
             after=after,
             time=time,
             parent_tag_ids=parent_tag_ids,
@@ -662,7 +681,6 @@ class AsyncStatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
     async def feed(
         self,
@@ -678,7 +696,7 @@ class AsyncStatsClient:
             typing.Union[StatsFeedRequestDecorationsItem, typing.Sequence[StatsFeedRequestDecorationsItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VehicleStatsListResponse:
+    ) -> AsyncPager[VehicleStatsListResponseData]:
         """
         Follow a feed of vehicle stats.
 
@@ -711,7 +729,7 @@ class AsyncStatsClient:
         types : typing.Optional[typing.Union[StatsFeedRequestTypesItem, typing.Sequence[StatsFeedRequestTypesItem]]]
             The stat types you want this endpoint to return information on. See also the <a href="/docs/telematics#query-parameters" target="_blank">Telematics</a> guide for more details.
 
-            You may list ***up to 3*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
+            You may list ***up to 4*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
 
             *Note:* `auxInput3`-`auxInput10` count as a single type against the limit of 3. For example, you could list `types=engineStates,obdOdometerMeters,auxInput3,auxInput4` because `auxInput3` and `auxInput4` count as a single stat type. `auxInput1` and `auxInput2` still count as their own individual types.
 
@@ -821,7 +839,7 @@ class AsyncStatsClient:
 
         Returns
         -------
-        VehicleStatsListResponse
+        AsyncPager[VehicleStatsListResponseData]
             List of stat events for the specified vehicles and stat types.
 
         Examples
@@ -836,12 +854,18 @@ class AsyncStatsClient:
 
 
         async def main() -> None:
-            await client.vehicles.stats.feed()
+            response = await client.vehicles.stats.feed()
+            async for item in response:
+                yield item
+
+            # alternatively, you can paginate page-by-page
+            async for page in response.iter_pages():
+                yield page
 
 
         asyncio.run(main())
         """
-        _response = await self._raw_client.feed(
+        return await self._raw_client.feed(
             after=after,
             parent_tag_ids=parent_tag_ids,
             tag_ids=tag_ids,
@@ -850,7 +874,6 @@ class AsyncStatsClient:
             decorations=decorations,
             request_options=request_options,
         )
-        return _response.data
 
     async def history(
         self,
@@ -868,7 +891,7 @@ class AsyncStatsClient:
             typing.Union[StatsHistoryRequestDecorationsItem, typing.Sequence[StatsHistoryRequestDecorationsItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> VehicleStatsListResponse:
+    ) -> AsyncPager[VehicleStatsListResponseData]:
         """
         Returns vehicle stats during the given time range for all vehicles. This can be optionally filtered by tags or specific vehicle IDs.
 
@@ -901,7 +924,7 @@ class AsyncStatsClient:
         types : typing.Optional[typing.Union[StatsHistoryRequestTypesItem, typing.Sequence[StatsHistoryRequestTypesItem]]]
             The stat types you want this endpoint to return information on. See also the <a href="/docs/telematics#query-parameters" target="_blank">Telematics</a> guide for more details.
 
-            You may list ***up to 3*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
+            You may list ***up to 4*** types using comma-separated format. For example: `types=gps,engineStates,obdOdometerMeters`.
 
             *Note:* `auxInput3`-`auxInput10` count as a single type against the limit of 3. For example, you could list `types=engineStates,obdOdometerMeters,auxInput3,auxInput4` because `auxInput3` and `auxInput4` count as a single stat type. `auxInput1` and `auxInput2` still count as their own individual types.
 
@@ -1011,7 +1034,7 @@ class AsyncStatsClient:
 
         Returns
         -------
-        VehicleStatsListResponse
+        AsyncPager[VehicleStatsListResponseData]
             List of vehicle stats for the specified vehicles, stat type, and time range.
 
         Examples
@@ -1026,15 +1049,21 @@ class AsyncStatsClient:
 
 
         async def main() -> None:
-            await client.vehicles.stats.history(
+            response = await client.vehicles.stats.history(
                 start_time="startTime",
                 end_time="endTime",
             )
+            async for item in response:
+                yield item
+
+            # alternatively, you can paginate page-by-page
+            async for page in response.iter_pages():
+                yield page
 
 
         asyncio.run(main())
         """
-        _response = await self._raw_client.history(
+        return await self._raw_client.history(
             start_time=start_time,
             end_time=end_time,
             after=after,
@@ -1045,4 +1074,3 @@ class AsyncStatsClient:
             decorations=decorations,
             request_options=request_options,
         )
-        return _response.data