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

samsara/hos/client.py

@@ -3,11 +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.hos_clocks_response import HosClocksResponse
+from ..types.hos_daily_logs_object_response_body import HosDailyLogsObjectResponseBody
 from ..types.hos_logs_response import HosLogsResponse
-from ..types.hos_violations_get_hos_violations_response_body import HosViolationsGetHosViolationsResponseBody
+from ..types.hos_violations_object_response_body import HosViolationsObjectResponseBody
 from .raw_client import AsyncRawHosClient, RawHosClient
+from .types.hos_daily_logs_request_driver_activation_status import HosDailyLogsRequestDriverActivationStatus
 
 
 class HosClient:
@@ -86,6 +89,99 @@ class HosClient:
         )
         return _response.data
 
+    def daily_logs(
+        self,
+        *,
+        driver_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        start_date: typing.Optional[str] = None,
+        end_date: typing.Optional[str] = None,
+        tag_ids: typing.Optional[str] = None,
+        parent_tag_ids: typing.Optional[str] = None,
+        driver_activation_status: typing.Optional[HosDailyLogsRequestDriverActivationStatus] = None,
+        after: typing.Optional[str] = None,
+        expand: typing.Optional[typing.Literal["vehicle"]] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SyncPager[HosDailyLogsObjectResponseBody]:
+        """
+        Get summarized daily Hours of Service charts for the specified drivers.
+
+        The time range for a log is defined by the `driver`'s `eldDayStartHour`. This value is configurable per driver.
+
+        The `startDate` and `endDate` parameters indicate the date range you'd like to retrieve daily logs for. A daily log will be returned if its `startTime` is on any of the days within in this date range (inclusive of `startDate` and `endDate`).
+
+        **Note:** If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.
+
+        If you are using the legacy version of this endpoint and looking for its documentation, you can find it [here](https://www.samsara.com/api-legacy#operation/getFleetDriversHosDailyLogs).
+
+         <b>Rate limit:</b> 5 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 ELD Compliance Settings (US)** under the Compliance 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
+        ----------
+        driver_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+             A filter on the data based on this comma-separated list of driver IDs and externalIds. Example: `driverIds=1234,5678,payroll:4841`
+
+        start_date : typing.Optional[str]
+             A start date in YYYY-MM-DD. This is a date only without an associated time. Example: `2019-06-13`. This is a required field
+
+        end_date : typing.Optional[str]
+             An end date in YYYY-MM-DD. This is a date only without an associated time. Must be greater than or equal to the start date. Example: `2019-07-21`. This is a required field
+
+        tag_ids : typing.Optional[str]
+             A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`
+
+        parent_tag_ids : typing.Optional[str]
+             A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`
+
+        driver_activation_status : typing.Optional[HosDailyLogsRequestDriverActivationStatus]
+            If value is `deactivated`, only drivers that are deactivated will appear in the response. This parameter will default to `active` if not provided (fetching only active drivers).  Valid values: `active`, `deactivated`
+
+        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.
+
+        expand : typing.Optional[typing.Literal["vehicle"]]
+            Expands the specified value(s) in the response object. Expansion populates additional fields in an object, if supported. Unsupported fields are ignored. To expand multiple fields, input a comma-separated list.
+
+            Valid value: `vehicle`  Valid values: `vehicle`
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SyncPager[HosDailyLogsObjectResponseBody]
+            OK response.
+
+        Examples
+        --------
+        from samsara import Samsara
+
+        client = Samsara(
+            token="YOUR_TOKEN",
+        )
+        response = client.hos.daily_logs()
+        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.daily_logs(
+            driver_ids=driver_ids,
+            start_date=start_date,
+            end_date=end_date,
+            tag_ids=tag_ids,
+            parent_tag_ids=parent_tag_ids,
+            driver_activation_status=driver_activation_status,
+            after=after,
+            expand=expand,
+            request_options=request_options,
+        )
+
     def logs(
         self,
         *,
@@ -167,7 +263,7 @@ class HosClient:
         types: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         after: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> HosViolationsGetHosViolationsResponseBody:
+    ) -> SyncPager[HosViolationsObjectResponseBody]:
         """
         Get active Hours of Service violations for the specified drivers.
 
@@ -212,7 +308,7 @@ class HosClient:
 
         Returns
         -------
-        HosViolationsGetHosViolationsResponseBody
+        SyncPager[HosViolationsObjectResponseBody]
             OK response.
 
         Examples
@@ -222,9 +318,14 @@ class HosClient:
         client = Samsara(
             token="YOUR_TOKEN",
         )
-        client.hos.violations()
+        response = client.hos.violations()
+        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.violations(
+        return self._raw_client.violations(
             driver_ids=driver_ids,
             start_time=start_time,
             end_time=end_time,
@@ -234,7 +335,6 @@ class HosClient:
             after=after,
             request_options=request_options,
         )
-        return _response.data
 
 
 class AsyncHosClient:
@@ -321,6 +421,108 @@ class AsyncHosClient:
         )
         return _response.data
 
+    async def daily_logs(
+        self,
+        *,
+        driver_ids: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
+        start_date: typing.Optional[str] = None,
+        end_date: typing.Optional[str] = None,
+        tag_ids: typing.Optional[str] = None,
+        parent_tag_ids: typing.Optional[str] = None,
+        driver_activation_status: typing.Optional[HosDailyLogsRequestDriverActivationStatus] = None,
+        after: typing.Optional[str] = None,
+        expand: typing.Optional[typing.Literal["vehicle"]] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> AsyncPager[HosDailyLogsObjectResponseBody]:
+        """
+        Get summarized daily Hours of Service charts for the specified drivers.
+
+        The time range for a log is defined by the `driver`'s `eldDayStartHour`. This value is configurable per driver.
+
+        The `startDate` and `endDate` parameters indicate the date range you'd like to retrieve daily logs for. A daily log will be returned if its `startTime` is on any of the days within in this date range (inclusive of `startDate` and `endDate`).
+
+        **Note:** If data is still being uploaded from the Samsara Driver App, it may not be completely reflected in the response from this endpoint. The best practice is to wait a couple of days before querying this endpoint to make sure that all data from the Samsara Driver App has been uploaded.
+
+        If you are using the legacy version of this endpoint and looking for its documentation, you can find it [here](https://www.samsara.com/api-legacy#operation/getFleetDriversHosDailyLogs).
+
+         <b>Rate limit:</b> 5 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 ELD Compliance Settings (US)** under the Compliance 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
+        ----------
+        driver_ids : typing.Optional[typing.Union[str, typing.Sequence[str]]]
+             A filter on the data based on this comma-separated list of driver IDs and externalIds. Example: `driverIds=1234,5678,payroll:4841`
+
+        start_date : typing.Optional[str]
+             A start date in YYYY-MM-DD. This is a date only without an associated time. Example: `2019-06-13`. This is a required field
+
+        end_date : typing.Optional[str]
+             An end date in YYYY-MM-DD. This is a date only without an associated time. Must be greater than or equal to the start date. Example: `2019-07-21`. This is a required field
+
+        tag_ids : typing.Optional[str]
+             A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`
+
+        parent_tag_ids : typing.Optional[str]
+             A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`
+
+        driver_activation_status : typing.Optional[HosDailyLogsRequestDriverActivationStatus]
+            If value is `deactivated`, only drivers that are deactivated will appear in the response. This parameter will default to `active` if not provided (fetching only active drivers).  Valid values: `active`, `deactivated`
+
+        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.
+
+        expand : typing.Optional[typing.Literal["vehicle"]]
+            Expands the specified value(s) in the response object. Expansion populates additional fields in an object, if supported. Unsupported fields are ignored. To expand multiple fields, input a comma-separated list.
+
+            Valid value: `vehicle`  Valid values: `vehicle`
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        AsyncPager[HosDailyLogsObjectResponseBody]
+            OK response.
+
+        Examples
+        --------
+        import asyncio
+
+        from samsara import AsyncSamsara
+
+        client = AsyncSamsara(
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            response = await client.hos.daily_logs()
+            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.daily_logs(
+            driver_ids=driver_ids,
+            start_date=start_date,
+            end_date=end_date,
+            tag_ids=tag_ids,
+            parent_tag_ids=parent_tag_ids,
+            driver_activation_status=driver_activation_status,
+            after=after,
+            expand=expand,
+            request_options=request_options,
+        )
+
     async def logs(
         self,
         *,
@@ -410,7 +612,7 @@ class AsyncHosClient:
         types: typing.Optional[typing.Union[str, typing.Sequence[str]]] = None,
         after: typing.Optional[str] = None,
         request_options: typing.Optional[RequestOptions] = None,
-    ) -> HosViolationsGetHosViolationsResponseBody:
+    ) -> AsyncPager[HosViolationsObjectResponseBody]:
         """
         Get active Hours of Service violations for the specified drivers.
 
@@ -455,7 +657,7 @@ class AsyncHosClient:
 
         Returns
         -------
-        HosViolationsGetHosViolationsResponseBody
+        AsyncPager[HosViolationsObjectResponseBody]
             OK response.
 
         Examples
@@ -470,12 +672,18 @@ class AsyncHosClient:
 
 
         async def main() -> None:
-            await client.hos.violations()
+            response = await client.hos.violations()
+            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.violations(
+        return await self._raw_client.violations(
             driver_ids=driver_ids,
             start_time=start_time,
             end_time=end_time,
@@ -485,4 +693,3 @@ class AsyncHosClient:
             after=after,
             request_options=request_options,
         )
-        return _response.data