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

samsara/equipment/stats/client.py

@@ -3,13 +3,14 @@
 import typing
 
 from ...core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ...core.pagination import AsyncPager, SyncPager
 from ...core.request_options import RequestOptions
-from ...types.equipment_stats_list_response import EquipmentStatsListResponse
-from ...types.equipment_stats_response import EquipmentStatsResponse
+from ...types.equipment_stats_list_response_data import EquipmentStatsListResponseData
+from ...types.equipment_stats_response_data import EquipmentStatsResponseData
 from .raw_client import AsyncRawStatsClient, RawStatsClient
 from .types.stats_feed_request_types_item import StatsFeedRequestTypesItem
-from .types.stats_get_request_types_item import StatsGetRequestTypesItem
 from .types.stats_history_request_types_item import StatsHistoryRequestTypesItem
+from .types.stats_list_request_types_item import StatsListRequestTypesItem
 
 
 class StatsClient:
@@ -27,7 +28,7 @@ class StatsClient:
         """
         return self._raw_client
 
-    def get(
+    def list(
         self,
         *,
         after: typing.Optional[str] = None,
@@ -35,10 +36,10 @@ class StatsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         types: typing.Optional[
-            typing.Union[StatsGetRequestTypesItem, typing.Sequence[StatsGetRequestTypesItem]]
+            typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentStatsResponse:
+    ) -> SyncPager[EquipmentStatsResponseData]:
         """
         Returns the last known stats for all equipment. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -62,12 +63,12 @@ class StatsClient:
         equipment_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
             A filter on the data based on this comma-separated list of equipment IDs. Example: `equipmentIds=1234,5678`
 
-        types : typing.Optional[typing.Union[StatsGetRequestTypesItem, typing.Sequence[StatsGetRequestTypesItem]]]
-            The types of equipment stats you want to query. Currently, you may submit up to 3 types.
+        types : typing.Optional[typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]]
+            The types of equipment stats you want to query. Currently, you may submit up to 4 types.
 
             - `engineRpm`: The revolutions per minute of the engine.
             - `fuelPercents`: The percent of fuel in the unit of equipment.
-            - `obdEngineSeconds`: The number of seconds the engine has been running since it was new. This value is provided directly from on-board diagnostics.
+            - `obdEngineSeconds`: The number of seconds the engine has been running as reported directly from on-board diagnostics. This is supported with the following hardware configurations: AG24/AG26 + AOPEN/A9PIN/ACT9/ACT14.
             - `gatewayEngineSeconds`: An approximation of the number of seconds the engine has been running since it was new, based on the amount of time the asset gateway has been receiving power with an offset provided manually through the Samsara cloud dashboard. This is supported with the following hardware configurations:
               - AG24/AG26/AG46P + APWR cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required)
               - AG52 + BPWR/BEQP cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required).
@@ -83,7 +84,7 @@ class StatsClient:
 
         Returns
         -------
-        EquipmentStatsResponse
+        SyncPager[EquipmentStatsResponseData]
             The most recent equipment stats and pagination information
 
         Examples
@@ -93,9 +94,14 @@ class StatsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.stats.get()
+        response = client.equipment.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.get(
+        return self._raw_client.list(
             after=after,
             parent_tag_ids=parent_tag_ids,
             tag_ids=tag_ids,
@@ -103,7 +109,6 @@ class StatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
     def feed(
         self,
@@ -116,9 +121,9 @@ class StatsClient:
             typing.Union[StatsFeedRequestTypesItem, typing.Sequence[StatsFeedRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentStatsListResponse:
+    ) -> SyncPager[EquipmentStatsListResponseData]:
         """
-        Follow a continuous feed of all equipment stats from Samsara AG26s.
+        Follow a continuous feed of all equipment stats.
 
         Your first call to this endpoint will provide you with the most recent stats for each unit of equipment and a `pagination` object that contains an `endCursor`.
 
@@ -147,11 +152,11 @@ class StatsClient:
             A filter on the data based on this comma-separated list of equipment IDs. Example: `equipmentIds=1234,5678`
 
         types : typing.Optional[typing.Union[StatsFeedRequestTypesItem, typing.Sequence[StatsFeedRequestTypesItem]]]
-            The types of equipment stats you want to query. Currently, you may submit up to 3 types.
+            The types of equipment stats you want to query. Currently, you may submit up to 4 types.
 
             - `engineRpm`: The revolutions per minute of the engine.
             - `fuelPercents`: The percent of fuel in the unit of equipment.
-            - `obdEngineSeconds`: The number of seconds the engine has been running since it was new. This value is provided directly from on-board diagnostics.
+            - `obdEngineSeconds`: The number of seconds the engine has been running as reported directly from on-board diagnostics. This is supported with the following hardware configurations: AG24/AG26 + AOPEN/A9PIN/ACT9/ACT14.
             - `gatewayEngineSeconds`: An approximation of the number of seconds the engine has been running since it was new, based on the amount of time the asset gateway has been receiving power with an offset provided manually through the Samsara cloud dashboard. This is supported with the following hardware configurations:
               - AG24/AG26/AG46P + APWR cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required)
               - AG52 + BPWR/BEQP cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required).
@@ -167,7 +172,7 @@ class StatsClient:
 
         Returns
         -------
-        EquipmentStatsListResponse
+        SyncPager[EquipmentStatsListResponseData]
             The feed of equipment stats and pagination information
 
         Examples
@@ -177,9 +182,14 @@ class StatsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.stats.feed()
+        response = client.equipment.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,
@@ -187,7 +197,6 @@ class StatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
     def history(
         self,
@@ -202,7 +211,7 @@ class StatsClient:
             typing.Union[StatsHistoryRequestTypesItem, typing.Sequence[StatsHistoryRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentStatsListResponse:
+    ) -> SyncPager[EquipmentStatsListResponseData]:
         """
         Returns historical equipment status during the given time range. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -233,11 +242,11 @@ class StatsClient:
             A filter on the data based on this comma-separated list of equipment IDs. Example: `equipmentIds=1234,5678`
 
         types : typing.Optional[typing.Union[StatsHistoryRequestTypesItem, typing.Sequence[StatsHistoryRequestTypesItem]]]
-            The types of equipment stats you want to query. Currently, you may submit up to 3 types.
+            The types of equipment stats you want to query. Currently, you may submit up to 4 types.
 
             - `engineRpm`: The revolutions per minute of the engine.
             - `fuelPercents`: The percent of fuel in the unit of equipment.
-            - `obdEngineSeconds`: The number of seconds the engine has been running since it was new. This value is provided directly from on-board diagnostics.
+            - `obdEngineSeconds`: The number of seconds the engine has been running as reported directly from on-board diagnostics. This is supported with the following hardware configurations: AG24/AG26 + AOPEN/A9PIN/ACT9/ACT14.
             - `gatewayEngineSeconds`: An approximation of the number of seconds the engine has been running since it was new, based on the amount of time the asset gateway has been receiving power with an offset provided manually through the Samsara cloud dashboard. This is supported with the following hardware configurations:
               - AG24/AG26/AG46P + APWR cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required)
               - AG52 + BPWR/BEQP cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required).
@@ -253,7 +262,7 @@ class StatsClient:
 
         Returns
         -------
-        EquipmentStatsListResponse
+        SyncPager[EquipmentStatsListResponseData]
             Historical equipment stats and pagination information
 
         Examples
@@ -263,12 +272,17 @@ class StatsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.stats.history(
+        response = client.equipment.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,
@@ -278,7 +292,6 @@ class StatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
 
 class AsyncStatsClient:
@@ -296,7 +309,7 @@ class AsyncStatsClient:
         """
         return self._raw_client
 
-    async def get(
+    async def list(
         self,
         *,
         after: typing.Optional[str] = None,
@@ -304,10 +317,10 @@ class AsyncStatsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         types: typing.Optional[
-            typing.Union[StatsGetRequestTypesItem, typing.Sequence[StatsGetRequestTypesItem]]
+            typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentStatsResponse:
+    ) -> AsyncPager[EquipmentStatsResponseData]:
         """
         Returns the last known stats for all equipment. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -331,12 +344,12 @@ class AsyncStatsClient:
         equipment_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
             A filter on the data based on this comma-separated list of equipment IDs. Example: `equipmentIds=1234,5678`
 
-        types : typing.Optional[typing.Union[StatsGetRequestTypesItem, typing.Sequence[StatsGetRequestTypesItem]]]
-            The types of equipment stats you want to query. Currently, you may submit up to 3 types.
+        types : typing.Optional[typing.Union[StatsListRequestTypesItem, typing.Sequence[StatsListRequestTypesItem]]]
+            The types of equipment stats you want to query. Currently, you may submit up to 4 types.
 
             - `engineRpm`: The revolutions per minute of the engine.
             - `fuelPercents`: The percent of fuel in the unit of equipment.
-            - `obdEngineSeconds`: The number of seconds the engine has been running since it was new. This value is provided directly from on-board diagnostics.
+            - `obdEngineSeconds`: The number of seconds the engine has been running as reported directly from on-board diagnostics. This is supported with the following hardware configurations: AG24/AG26 + AOPEN/A9PIN/ACT9/ACT14.
             - `gatewayEngineSeconds`: An approximation of the number of seconds the engine has been running since it was new, based on the amount of time the asset gateway has been receiving power with an offset provided manually through the Samsara cloud dashboard. This is supported with the following hardware configurations:
               - AG24/AG26/AG46P + APWR cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required)
               - AG52 + BPWR/BEQP cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required).
@@ -352,7 +365,7 @@ class AsyncStatsClient:
 
         Returns
         -------
-        EquipmentStatsResponse
+        AsyncPager[EquipmentStatsResponseData]
             The most recent equipment stats and pagination information
 
         Examples
@@ -367,12 +380,18 @@ class AsyncStatsClient:
 
 
         async def main() -> None:
-            await client.equipment.stats.get()
+            response = await client.equipment.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.get(
+        return await self._raw_client.list(
             after=after,
             parent_tag_ids=parent_tag_ids,
             tag_ids=tag_ids,
@@ -380,7 +399,6 @@ class AsyncStatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
     async def feed(
         self,
@@ -393,9 +411,9 @@ class AsyncStatsClient:
             typing.Union[StatsFeedRequestTypesItem, typing.Sequence[StatsFeedRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentStatsListResponse:
+    ) -> AsyncPager[EquipmentStatsListResponseData]:
         """
-        Follow a continuous feed of all equipment stats from Samsara AG26s.
+        Follow a continuous feed of all equipment stats.
 
         Your first call to this endpoint will provide you with the most recent stats for each unit of equipment and a `pagination` object that contains an `endCursor`.
 
@@ -424,11 +442,11 @@ class AsyncStatsClient:
             A filter on the data based on this comma-separated list of equipment IDs. Example: `equipmentIds=1234,5678`
 
         types : typing.Optional[typing.Union[StatsFeedRequestTypesItem, typing.Sequence[StatsFeedRequestTypesItem]]]
-            The types of equipment stats you want to query. Currently, you may submit up to 3 types.
+            The types of equipment stats you want to query. Currently, you may submit up to 4 types.
 
             - `engineRpm`: The revolutions per minute of the engine.
             - `fuelPercents`: The percent of fuel in the unit of equipment.
-            - `obdEngineSeconds`: The number of seconds the engine has been running since it was new. This value is provided directly from on-board diagnostics.
+            - `obdEngineSeconds`: The number of seconds the engine has been running as reported directly from on-board diagnostics. This is supported with the following hardware configurations: AG24/AG26 + AOPEN/A9PIN/ACT9/ACT14.
             - `gatewayEngineSeconds`: An approximation of the number of seconds the engine has been running since it was new, based on the amount of time the asset gateway has been receiving power with an offset provided manually through the Samsara cloud dashboard. This is supported with the following hardware configurations:
               - AG24/AG26/AG46P + APWR cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required)
               - AG52 + BPWR/BEQP cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required).
@@ -444,7 +462,7 @@ class AsyncStatsClient:
 
         Returns
         -------
-        EquipmentStatsListResponse
+        AsyncPager[EquipmentStatsListResponseData]
             The feed of equipment stats and pagination information
 
         Examples
@@ -459,12 +477,18 @@ class AsyncStatsClient:
 
 
         async def main() -> None:
-            await client.equipment.stats.feed()
+            response = await client.equipment.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,
@@ -472,7 +496,6 @@ class AsyncStatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data
 
     async def history(
         self,
@@ -487,7 +510,7 @@ class AsyncStatsClient:
             typing.Union[StatsHistoryRequestTypesItem, typing.Sequence[StatsHistoryRequestTypesItem]]
         ] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentStatsListResponse:
+    ) -> AsyncPager[EquipmentStatsListResponseData]:
         """
         Returns historical equipment status during the given time range. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -518,11 +541,11 @@ class AsyncStatsClient:
             A filter on the data based on this comma-separated list of equipment IDs. Example: `equipmentIds=1234,5678`
 
         types : typing.Optional[typing.Union[StatsHistoryRequestTypesItem, typing.Sequence[StatsHistoryRequestTypesItem]]]
-            The types of equipment stats you want to query. Currently, you may submit up to 3 types.
+            The types of equipment stats you want to query. Currently, you may submit up to 4 types.
 
             - `engineRpm`: The revolutions per minute of the engine.
             - `fuelPercents`: The percent of fuel in the unit of equipment.
-            - `obdEngineSeconds`: The number of seconds the engine has been running since it was new. This value is provided directly from on-board diagnostics.
+            - `obdEngineSeconds`: The number of seconds the engine has been running as reported directly from on-board diagnostics. This is supported with the following hardware configurations: AG24/AG26 + AOPEN/A9PIN/ACT9/ACT14.
             - `gatewayEngineSeconds`: An approximation of the number of seconds the engine has been running since it was new, based on the amount of time the asset gateway has been receiving power with an offset provided manually through the Samsara cloud dashboard. This is supported with the following hardware configurations:
               - AG24/AG26/AG46P + APWR cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required)
               - AG52 + BPWR/BEQP cable ([Auxiliary engine configuration](https://kb.samsara.com/hc/en-us/articles/360043040512-Auxiliary-Inputs#UUID-d514abff-d10a-efaf-35d9-e10fa6c4888d) required).
@@ -538,7 +561,7 @@ class AsyncStatsClient:
 
         Returns
         -------
-        EquipmentStatsListResponse
+        AsyncPager[EquipmentStatsListResponseData]
             Historical equipment stats and pagination information
 
         Examples
@@ -553,15 +576,21 @@ class AsyncStatsClient:
 
 
         async def main() -> None:
-            await client.equipment.stats.history(
+            response = await client.equipment.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,
@@ -571,4 +600,3 @@ class AsyncStatsClient:
             types=types,
             request_options=request_options,
         )
-        return _response.data