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

samsara/readings/client.py

@@ -0,0 +1,524 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.pagination import AsyncPager, SyncPager
+from ..core.request_options import RequestOptions
+from ..types.reading_definition_response_body import ReadingDefinitionResponseBody
+from ..types.reading_history_response_body import ReadingHistoryResponseBody
+from ..types.reading_snapshot_response_body import ReadingSnapshotResponseBody
+from .raw_client import AsyncRawReadingsClient, RawReadingsClient
+
+
+class ReadingsClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._raw_client = RawReadingsClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> RawReadingsClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        RawReadingsClient
+        """
+        return self._raw_client
+
+    def definitions(
+        self,
+        *,
+        after: typing.Optional[str] = None,
+        ids: typing.Optional[str] = None,
+        entity_types: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SyncPager[ReadingDefinitionResponseBody]:
+        """
+        An introspection endpoint for discovering the set of readings including their name, description, data type, unit, and other metadata.
+
+         <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Readings** under the Closed Beta 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>
+
+
+         **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.
+
+        Parameters
+        ----------
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        ids : typing.Optional[str]
+            A String of comma separated reading IDs. Include up to 50 readings IDs. If not set, all readings are returned.
+
+        entity_types : typing.Optional[str]
+            A list of entity type to return readings for.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SyncPager[ReadingDefinitionResponseBody]
+            OK response.
+
+        Examples
+        --------
+        from samsara import Samsara
+
+        client = Samsara(
+            token="YOUR_TOKEN",
+        )
+        response = client.readings.definitions()
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
+        """
+        return self._raw_client.definitions(
+            after=after, ids=ids, entity_types=entity_types, request_options=request_options
+        )
+
+    def history(
+        self,
+        *,
+        reading_id: str,
+        entity_type: str,
+        after: typing.Optional[str] = None,
+        entity_ids: typing.Optional[str] = None,
+        external_ids: typing.Optional[str] = None,
+        start_time: typing.Optional[str] = None,
+        end_time: typing.Optional[str] = None,
+        feed: typing.Optional[bool] = None,
+        include_external_ids: typing.Optional[bool] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SyncPager[ReadingHistoryResponseBody]:
+        """
+        Get the values of a reading for a set of entities within the specified time range. Returns a paginated response with data for the specified resource IDs where startTime <= happenedAtTime < endTime. End time of null implies endTime is infinite and all known readings are returned.
+
+         <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Readings** under the Closed Beta 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>
+
+
+         **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.
+
+        Parameters
+        ----------
+        reading_id : str
+            The reading ID to retrieve data for. Use /readings/definitions endpoint to get a list of valid reading IDs.
+
+        entity_type : str
+            A entity type of the entityIds or externalIds to fetch readings for. Use /readings/definitions endpoint to get a list of valid entity types.
+
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        entity_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of entity IDs or external IDs.
+
+        external_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of external IDs.
+
+        start_time : typing.Optional[str]
+            A filter on the data that returns the last known data points with timestamps greater than or equal to this value. Must be a string in RFC 3339 format. Millisecond precision and timezones are supported.
+
+        end_time : typing.Optional[str]
+            A filter on the data that returns the last known data points with timestamps less than or equal to this value. If not set, the time of the request is considered the endTime. Must be a string in RFC 3339 format. Millisecond precision and timezones are supported.
+
+        feed : typing.Optional[bool]
+            Set to true to enable feed mode for continuous reading updates. When enabled, the API always includes an endCursor in the response. If hasNextPage is false, it indicates that no new data is currently available — wait at least 5 seconds before making the next request to avoid unnecessary polling.
+
+        include_external_ids : typing.Optional[bool]
+            Optional boolean indicating whether to return external IDs on supported entities
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SyncPager[ReadingHistoryResponseBody]
+            OK response.
+
+        Examples
+        --------
+        from samsara import Samsara
+
+        client = Samsara(
+            token="YOUR_TOKEN",
+        )
+        response = client.readings.history(
+            reading_id="readingId",
+            entity_type="entityType",
+        )
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
+        """
+        return self._raw_client.history(
+            reading_id=reading_id,
+            entity_type=entity_type,
+            after=after,
+            entity_ids=entity_ids,
+            external_ids=external_ids,
+            start_time=start_time,
+            end_time=end_time,
+            feed=feed,
+            include_external_ids=include_external_ids,
+            request_options=request_options,
+        )
+
+    def latest(
+        self,
+        *,
+        reading_ids: str,
+        entity_type: str,
+        after: typing.Optional[str] = None,
+        entity_ids: typing.Optional[str] = None,
+        external_ids: typing.Optional[str] = None,
+        as_of_time: typing.Optional[str] = None,
+        include_external_ids: typing.Optional[bool] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SyncPager[ReadingSnapshotResponseBody]:
+        """
+        An endpoint to get the last value of a reading for a set of entities at the specified time.
+
+         <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Readings** under the Closed Beta 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>
+
+
+         **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.
+
+        Parameters
+        ----------
+        reading_ids : str
+            A collection of comma separated reading IDs. Include up to 3 readings IDs. Use /readings/definitions endpoint to get a list of valid reading IDs.
+
+        entity_type : str
+            A entity type of the entityIds or externalIds to fetch readings for. Use /readings/definitions endpoint to get a list of valid entity types.
+
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        entity_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of entity IDs or external IDs.
+
+        external_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of external IDs.
+
+        as_of_time : typing.Optional[str]
+            A filter on the data that returns the last known data points with timestamps less than or equal to this value. Defaults to now if not provided. Must be a string in RFC 3339 format. Millisecond precision and timezones are supported.
+
+        include_external_ids : typing.Optional[bool]
+            Optional boolean indicating whether to return external IDs on supported entities
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SyncPager[ReadingSnapshotResponseBody]
+            OK response.
+
+        Examples
+        --------
+        from samsara import Samsara
+
+        client = Samsara(
+            token="YOUR_TOKEN",
+        )
+        response = client.readings.latest(
+            reading_ids="readingIds",
+            entity_type="entityType",
+        )
+        for item in response:
+            yield item
+        # alternatively, you can paginate page-by-page
+        for page in response.iter_pages():
+            yield page
+        """
+        return self._raw_client.latest(
+            reading_ids=reading_ids,
+            entity_type=entity_type,
+            after=after,
+            entity_ids=entity_ids,
+            external_ids=external_ids,
+            as_of_time=as_of_time,
+            include_external_ids=include_external_ids,
+            request_options=request_options,
+        )
+
+
+class AsyncReadingsClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._raw_client = AsyncRawReadingsClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> AsyncRawReadingsClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        AsyncRawReadingsClient
+        """
+        return self._raw_client
+
+    async def definitions(
+        self,
+        *,
+        after: typing.Optional[str] = None,
+        ids: typing.Optional[str] = None,
+        entity_types: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncPager[ReadingDefinitionResponseBody]:
+        """
+        An introspection endpoint for discovering the set of readings including their name, description, data type, unit, and other metadata.
+
+         <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Readings** under the Closed Beta 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>
+
+
+         **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.
+
+        Parameters
+        ----------
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        ids : typing.Optional[str]
+            A String of comma separated reading IDs. Include up to 50 readings IDs. If not set, all readings are returned.
+
+        entity_types : typing.Optional[str]
+            A list of entity type to return readings for.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncPager[ReadingDefinitionResponseBody]
+            OK response.
+
+        Examples
+        --------
+        import asyncio
+
+        from samsara import AsyncSamsara
+
+        client = AsyncSamsara(
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            response = await client.readings.definitions()
+            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())
+        """
+        return await self._raw_client.definitions(
+            after=after, ids=ids, entity_types=entity_types, request_options=request_options
+        )
+
+    async def history(
+        self,
+        *,
+        reading_id: str,
+        entity_type: str,
+        after: typing.Optional[str] = None,
+        entity_ids: typing.Optional[str] = None,
+        external_ids: typing.Optional[str] = None,
+        start_time: typing.Optional[str] = None,
+        end_time: typing.Optional[str] = None,
+        feed: typing.Optional[bool] = None,
+        include_external_ids: typing.Optional[bool] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncPager[ReadingHistoryResponseBody]:
+        """
+        Get the values of a reading for a set of entities within the specified time range. Returns a paginated response with data for the specified resource IDs where startTime <= happenedAtTime < endTime. End time of null implies endTime is infinite and all known readings are returned.
+
+         <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Readings** under the Closed Beta 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>
+
+
+         **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.
+
+        Parameters
+        ----------
+        reading_id : str
+            The reading ID to retrieve data for. Use /readings/definitions endpoint to get a list of valid reading IDs.
+
+        entity_type : str
+            A entity type of the entityIds or externalIds to fetch readings for. Use /readings/definitions endpoint to get a list of valid entity types.
+
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        entity_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of entity IDs or external IDs.
+
+        external_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of external IDs.
+
+        start_time : typing.Optional[str]
+            A filter on the data that returns the last known data points with timestamps greater than or equal to this value. Must be a string in RFC 3339 format. Millisecond precision and timezones are supported.
+
+        end_time : typing.Optional[str]
+            A filter on the data that returns the last known data points with timestamps less than or equal to this value. If not set, the time of the request is considered the endTime. Must be a string in RFC 3339 format. Millisecond precision and timezones are supported.
+
+        feed : typing.Optional[bool]
+            Set to true to enable feed mode for continuous reading updates. When enabled, the API always includes an endCursor in the response. If hasNextPage is false, it indicates that no new data is currently available — wait at least 5 seconds before making the next request to avoid unnecessary polling.
+
+        include_external_ids : typing.Optional[bool]
+            Optional boolean indicating whether to return external IDs on supported entities
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncPager[ReadingHistoryResponseBody]
+            OK response.
+
+        Examples
+        --------
+        import asyncio
+
+        from samsara import AsyncSamsara
+
+        client = AsyncSamsara(
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            response = await client.readings.history(
+                reading_id="readingId",
+                entity_type="entityType",
+            )
+            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())
+        """
+        return await self._raw_client.history(
+            reading_id=reading_id,
+            entity_type=entity_type,
+            after=after,
+            entity_ids=entity_ids,
+            external_ids=external_ids,
+            start_time=start_time,
+            end_time=end_time,
+            feed=feed,
+            include_external_ids=include_external_ids,
+            request_options=request_options,
+        )
+
+    async def latest(
+        self,
+        *,
+        reading_ids: str,
+        entity_type: str,
+        after: typing.Optional[str] = None,
+        entity_ids: typing.Optional[str] = None,
+        external_ids: typing.Optional[str] = None,
+        as_of_time: typing.Optional[str] = None,
+        include_external_ids: typing.Optional[bool] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncPager[ReadingSnapshotResponseBody]:
+        """
+        An endpoint to get the last value of a reading for a set of entities at the specified time.
+
+         <b>Rate limit:</b> 10 requests/sec (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).
+
+        To use this endpoint, select **Read Readings** under the Closed Beta 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>
+
+
+         **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.
+
+        Parameters
+        ----------
+        reading_ids : str
+            A collection of comma separated reading IDs. Include up to 3 readings IDs. Use /readings/definitions endpoint to get a list of valid reading IDs.
+
+        entity_type : str
+            A entity type of the entityIds or externalIds to fetch readings for. Use /readings/definitions endpoint to get a list of valid entity types.
+
+        after : typing.Optional[str]
+             If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
+
+        entity_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of entity IDs or external IDs.
+
+        external_ids : typing.Optional[str]
+            A filter on the data based on this comma-separated list of external IDs.
+
+        as_of_time : typing.Optional[str]
+            A filter on the data that returns the last known data points with timestamps less than or equal to this value. Defaults to now if not provided. Must be a string in RFC 3339 format. Millisecond precision and timezones are supported.
+
+        include_external_ids : typing.Optional[bool]
+            Optional boolean indicating whether to return external IDs on supported entities
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncPager[ReadingSnapshotResponseBody]
+            OK response.
+
+        Examples
+        --------
+        import asyncio
+
+        from samsara import AsyncSamsara
+
+        client = AsyncSamsara(
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            response = await client.readings.latest(
+                reading_ids="readingIds",
+                entity_type="entityType",
+            )
+            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())
+        """
+        return await self._raw_client.latest(
+            reading_ids=reading_ids,
+            entity_type=entity_type,
+            after=after,
+            entity_ids=entity_ids,
+            external_ids=external_ids,
+            as_of_time=as_of_time,
+            include_external_ids=include_external_ids,
+            request_options=request_options,
+        )