Wrapperクラスにdownload, execute_http_get関数を用意 (#456)

* 公開

* versionup

* update wrapper

annofabapi/__version__.py

@@ -1 +1 @@
-__version__ = "0.58.0"
+__version__ = "0.59.0"

annofabapi/api.py

@@ -447,7 +447,7 @@ def _execute_http_request(
                 **kwargs,
             )
 
-        # リトライすべき場合はExceptionをスローする
+        # リトライが必要な場合は、backoffがリトライできるようにするため、Exceptionをスローする
         if raise_for_status or _should_retry_with_status(response.status_code):
             _log_error_response(logger, response)
             _raise_for_status(response)

annofabapi/wrapper.py

@@ -77,13 +77,6 @@ def _first_true(iterable, default=None, pred=None):
     return next(filter(pred, iterable), default)
 
 
-def _hour_to_millisecond(hour: Optional[float]) -> Optional[int]:
-    return int(hour * 3600_000) if hour is not None else None
-
-
-_ORGANIZATION_ID_FOR_AVAILABILITY = "___plannedWorktime___"
-"""予定稼働時間用の組織ID"""
-
 _JOB_CONCURRENCY_LIMIT = {
     ProjectJobType.COPY_PROJECT: {
         ProjectJobType.GEN_INPUTS,
@@ -205,16 +198,49 @@ def _get_all_objects(func_get_list: Callable, limit: int, **kwargs_for_func_get_
 
         return all_objects
 
-    def _download(self, url: str, dest_path: Union[str, Path]) -> requests.Response:
+    def execute_http_get(self, url: str) -> requests.Response:
+        """
+        指定したURLに対してHTTP GETを実行します。
+
+        塗りつぶし画像など外部リソースのURLを指定することを想定しています。
+
+        Args:
+            url: HTTP GETでアクセスするURL
+
+        Returns:
+            URLにアクセスしたときの ``requests.Response`` 情報
+
+        Note:
+            ``requests.get`` でアクセスすることとの違いは以下の通りです。
+
+             * ``requests.Session`` 情報を使ってTCPコネクションを再利用しているため、``requests.get`` を使ってダウンロードするよりも、パフォーマンスが向上する可能性があります。
+             * 必要に応じてリトライします
+             * HTTPステータスコードが4XX,5XXならば、HTTPErrorがスローされます
+
+
+        """
+        return self.api._execute_http_request(http_method="get", url=url)
+
+    def download(self, url: str, dest_path: Union[str, Path]) -> requests.Response:
         """
         指定したURLからファイルをダウンロードします。
 
+        ``getAnnotation`` などダウンロード用のURLを指定することを想定しています。
+
+
         Args:
             url: ダウンロード対象のURL
             dest_path: 保存先ファイルのパス
 
         Returns:
-            URLにアクセスしたときのResponse情報
+            URLにアクセスしたときの ``requests.Response`` 情報
+
+        Note:
+            ``requests.get`` でアクセスすることとの違いは以下の通りです。
+
+             * ``requests.Session`` 情報を使ってTCPコネクションを再利用しているため、``requests.get`` を使ってダウンロードするよりも、パフォーマンスが向上する可能性があります。
+             * 必要に応じてリトライします
+             * HTTPステータスコードが4XX,5XXならば、HTTPErrorがスローされます
 
         """
         response = self.api._execute_http_request(http_method="get", url=url)
@@ -269,7 +295,7 @@ def download_annotation_archive(self, project_id: str, dest_path: Union[str, Pat
         # 2022/01時点でレスポンスのcontent-typeが"text/plain"なので、contentの型がdictにならない。したがって、Locationヘッダを参照する。
         _, response = self.api.get_annotation_archive(project_id)
         url = response.headers["Location"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "SimpleアノテーションZIPファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -300,7 +326,7 @@ def download_full_annotation_archive(self, project_id: str, dest_path: Union[str
         # 2022/01時点でレスポンスのcontent-typeが"text/plain"なので、contentの型がdictにならない。したがって、Locationヘッダを参照する。
         _, response = self.api.get_archive_full_with_pro_id(project_id)
         url = response.headers["Location"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "FullアノテーションZIPファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -1578,7 +1604,7 @@ def download_project_inputs_url(self, project_id: str, dest_path: Union[str, Pat
         """
         content, _ = self.api.get_project_inputs_url(project_id)
         url = content["url"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "入力データ全件ファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -1603,7 +1629,7 @@ def download_project_tasks_url(self, project_id: str, dest_path: Union[str, Path
 
         content, _ = self.api.get_project_tasks_url(project_id)
         url = content["url"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "タスク全件ファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -1635,7 +1661,7 @@ def download_project_inspections_url(self, project_id: str, dest_path: Union[str
 
         content, _ = self.api.get_project_inspections_url(project_id)
         url = content["url"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "検査コメント全件ファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -1659,7 +1685,7 @@ def download_project_comments_url(self, project_id: str, dest_path: Union[str, P
 
         content, _ = self.api.get_project_comments_url(project_id)
         url = content["url"]
-        response = self._download(url, dest_path)
+        response = self.download(url, dest_path)
         logger.info(
             "コメント全件ファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -1684,7 +1710,7 @@ def download_project_task_history_events_url(self, project_id: str, dest_path: U
 
         content, _ = self.api.get_project_task_history_events_url(project_id)
         url = content["url"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "タスク履歴イベント全件ファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,
@@ -1709,7 +1735,7 @@ def download_project_task_histories_url(self, project_id: str, dest_path: Union[
 
         content, _ = self.api.get_project_task_histories_url(project_id)
         url = content["url"]
-        response2 = self._download(url, dest_path)
+        response2 = self.download(url, dest_path)
         logger.info(
             "タスク履歴全件ファイルをダウンロードしました。 :: project_id='%s', Last-Modified='%s', file='%s'",
             project_id,

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "annofabapi"
-version = "0.58.0"
+version = "0.59.0"
 description = "Python Clinet Library of AnnoFab WebAPI (https://annofab.com/docs/api/)"
 authors = ["yuji38kwmt"]
 license = "MIT"