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

samsara/equipment/client.py

@@ -3,8 +3,9 @@
 import typing
 
 from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.pagination import AsyncPager, SyncPager
 from ..core.request_options import RequestOptions
-from ..types.equipment_list_response import EquipmentListResponse
+from ..types.equipment_object import EquipmentObject
 from ..types.equipment_response import EquipmentResponse
 from .locations.client import AsyncLocationsClient, LocationsClient
 from .raw_client import AsyncRawEquipmentClient, RawEquipmentClient
@@ -37,13 +38,9 @@ class EquipmentClient:
         parent_tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentListResponse:
+    ) -> SyncPager[EquipmentObject]:
         """
-        Returns a list of all equipment in an organization. Equipment objects represent powered assets connected to a [Samsara AG26](https://www.samsara.com/products/models/ag26) via an APWR, CAT, or J1939 cable. They are automatically created with a unique Samsara Equipment ID whenever an AG26 is activated in your organization.
-
-         **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.
-
-        To use this endpoint, select **Read Equipment** under the Equipment category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
+        Returns a list of all equipment in an organization.
 
         Parameters
         ----------
@@ -64,7 +61,7 @@ class EquipmentClient:
 
         Returns
         -------
-        EquipmentListResponse
+        SyncPager[EquipmentObject]
             List of all equipment objects, and pagination information
 
         Examples
@@ -74,12 +71,16 @@ class EquipmentClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.list()
+        response = client.equipment.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(
             limit=limit, after=after, parent_tag_ids=parent_tag_ids, tag_ids=tag_ids, request_options=request_options
         )
-        return _response.data
 
     def get(self, id: str, *, request_options: typing.Optional[RequestOptions] = None) -> EquipmentResponse:
         """
@@ -143,13 +144,9 @@ class AsyncEquipmentClient:
         parent_tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentListResponse:
+    ) -> AsyncPager[EquipmentObject]:
         """
-        Returns a list of all equipment in an organization. Equipment objects represent powered assets connected to a [Samsara AG26](https://www.samsara.com/products/models/ag26) via an APWR, CAT, or J1939 cable. They are automatically created with a unique Samsara Equipment ID whenever an AG26 is activated in your organization.
-
-         **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.
-
-        To use this endpoint, select **Read Equipment** under the Equipment category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
+        Returns a list of all equipment in an organization.
 
         Parameters
         ----------
@@ -170,7 +167,7 @@ class AsyncEquipmentClient:
 
         Returns
         -------
-        EquipmentListResponse
+        AsyncPager[EquipmentObject]
             List of all equipment objects, and pagination information
 
         Examples
@@ -185,15 +182,20 @@ class AsyncEquipmentClient:
 
 
         async def main() -> None:
-            await client.equipment.list()
+            response = await client.equipment.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(
             limit=limit, after=after, parent_tag_ids=parent_tag_ids, tag_ids=tag_ids, request_options=request_options
         )
-        return _response.data
 
     async def get(self, id: str, *, request_options: typing.Optional[RequestOptions] = None) -> EquipmentResponse:
         """

samsara/equipment/locations/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.equipment_locations_list_response import EquipmentLocationsListResponse
-from ...types.equipment_locations_response import EquipmentLocationsResponse
+from ...types.equipment_locations_list_response_data import EquipmentLocationsListResponseData
+from ...types.equipment_locations_response_data import EquipmentLocationsResponseData
 from .raw_client import AsyncRawLocationsClient, RawLocationsClient
 
 
@@ -32,7 +33,7 @@ class LocationsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentLocationsResponse:
+    ) -> SyncPager[EquipmentLocationsResponseData]:
         """
         Returns last known locations for all equipment. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -59,7 +60,7 @@ class LocationsClient:
 
         Returns
         -------
-        EquipmentLocationsResponse
+        SyncPager[EquipmentLocationsResponseData]
             The most recent equipment locations and pagination information
 
         Examples
@@ -69,16 +70,20 @@ class LocationsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.locations.list()
+        response = client.equipment.locations.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,
             parent_tag_ids=parent_tag_ids,
             tag_ids=tag_ids,
             equipment_ids=equipment_ids,
             request_options=request_options,
         )
-        return _response.data
 
     def feed(
         self,
@@ -88,9 +93,9 @@ class LocationsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentLocationsListResponse:
+    ) -> SyncPager[EquipmentLocationsListResponseData]:
         """
-        Follow a continuous feed of all equipment locations from Samsara AG26s.
+        Follow a continuous feed of all equipment locations.
 
         Your first call to this endpoint will provide you with the most recent location for each unit of equipment and a `pagination` object that contains an `endCursor`.
 
@@ -121,7 +126,7 @@ class LocationsClient:
 
         Returns
         -------
-        EquipmentLocationsListResponse
+        SyncPager[EquipmentLocationsListResponseData]
             The feed of equipment locations and pagination information
 
         Examples
@@ -131,16 +136,20 @@ class LocationsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.locations.feed()
+        response = client.equipment.locations.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,
             equipment_ids=equipment_ids,
             request_options=request_options,
         )
-        return _response.data
 
     def history(
         self,
@@ -152,7 +161,7 @@ class LocationsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentLocationsListResponse:
+    ) -> SyncPager[EquipmentLocationsListResponseData]:
         """
         Returns historical equipment locations during the given time range. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -185,7 +194,7 @@ class LocationsClient:
 
         Returns
         -------
-        EquipmentLocationsListResponse
+        SyncPager[EquipmentLocationsListResponseData]
             Historical equipment locations and pagination information
 
         Examples
@@ -195,12 +204,17 @@ class LocationsClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.equipment.locations.history(
+        response = client.equipment.locations.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,
@@ -209,7 +223,6 @@ class LocationsClient:
             equipment_ids=equipment_ids,
             request_options=request_options,
         )
-        return _response.data
 
 
 class AsyncLocationsClient:
@@ -235,7 +248,7 @@ class AsyncLocationsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentLocationsResponse:
+    ) -> AsyncPager[EquipmentLocationsResponseData]:
         """
         Returns last known locations for all equipment. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -262,7 +275,7 @@ class AsyncLocationsClient:
 
         Returns
         -------
-        EquipmentLocationsResponse
+        AsyncPager[EquipmentLocationsResponseData]
             The most recent equipment locations and pagination information
 
         Examples
@@ -277,19 +290,24 @@ class AsyncLocationsClient:
 
 
         async def main() -> None:
-            await client.equipment.locations.list()
+            response = await client.equipment.locations.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,
             parent_tag_ids=parent_tag_ids,
             tag_ids=tag_ids,
             equipment_ids=equipment_ids,
             request_options=request_options,
         )
-        return _response.data
 
     async def feed(
         self,
@@ -299,9 +317,9 @@ class AsyncLocationsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentLocationsListResponse:
+    ) -> AsyncPager[EquipmentLocationsListResponseData]:
         """
-        Follow a continuous feed of all equipment locations from Samsara AG26s.
+        Follow a continuous feed of all equipment locations.
 
         Your first call to this endpoint will provide you with the most recent location for each unit of equipment and a `pagination` object that contains an `endCursor`.
 
@@ -332,7 +350,7 @@ class AsyncLocationsClient:
 
         Returns
         -------
-        EquipmentLocationsListResponse
+        AsyncPager[EquipmentLocationsListResponseData]
             The feed of equipment locations and pagination information
 
         Examples
@@ -347,19 +365,24 @@ class AsyncLocationsClient:
 
 
         async def main() -> None:
-            await client.equipment.locations.feed()
+            response = await client.equipment.locations.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,
             equipment_ids=equipment_ids,
             request_options=request_options,
         )
-        return _response.data
 
     async def history(
         self,
@@ -371,7 +394,7 @@ class AsyncLocationsClient:
         tag_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         equipment_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> EquipmentLocationsListResponse:
+    ) -> AsyncPager[EquipmentLocationsListResponseData]:
         """
         Returns historical equipment locations during the given time range. This can be optionally filtered by tags or specific equipment IDs.
 
@@ -404,7 +427,7 @@ class AsyncLocationsClient:
 
         Returns
         -------
-        EquipmentLocationsListResponse
+        AsyncPager[EquipmentLocationsListResponseData]
             Historical equipment locations and pagination information
 
         Examples
@@ -419,15 +442,21 @@ class AsyncLocationsClient:
 
 
         async def main() -> None:
-            await client.equipment.locations.history(
+            response = await client.equipment.locations.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,
@@ -436,4 +465,3 @@ class AsyncLocationsClient:
             equipment_ids=equipment_ids,
             request_options=request_options,
         )
-        return _response.data