[wrapper] operateTask APIの処理を分割したメソッドを作成 (#240)

* update

* 作業ガイドを登録

* test project 作成

* [wrapper] operateTaskを分解したようなメソッドを追加

* [wrapper] operateTaskを分解したようなメソッドを追加

* format

* format

* version up

* update README

Author: yuji38kwmt

README_for_developer.md

@@ -2,60 +2,28 @@
 開発者用のドキュメントです。
 ソースコードの生成、テスト実行、リリース手順などを記載します。
 
-## Requirements
+# Requirements
 * Bash
 * Docker (OpenAPI Generatorを実行するのに必要)
 * python 3.6+
-    * poetry
 
-## Install
+# Install
 以下のコマンドを実行してください。開発に必要な環境が構築されます。
 
 ```bash
 $ make init
 ```
 
-## Source
+# Test
 
-### ソースコードの生成
-annofabapiのいくつかのファイルは、[AnnoFab Web APIのOpenAPI Spec](https://annofab.com/docs/api/swagger.yaml)から自動生成しています。
-以下のコマンドを実行すると、ソースコードが生成されます。詳細は[generate/README.md](generate/README.md)を参照してください。
-
-```
-# `generate/swagger/*.yaml`ファイルから、ソースコードを生成する
-$ generate/generate.sh
-
-# AnnoFab WebAPIのOpenAPI Spec を`generate/swagger/`にダウンロードしてから、ソースコードを生成する
-$ generate/generate.sh --download
-
-```
-
-### フォーマットを実行
-以下のコマンドを実行してください。
-
-```
-$ make format
-```
-
-### lintを実行
-以下のコマンドを実行してください。
-
-```
-$ make lint
-```
-
-## Test
-
-### テストの実行方法
+## テストの実行方法
 1. AnnoFabの認証情報を、`.netrc`ファイルまたは環境変数に設定する。
-2. `pytest.ini`に、テスト対象の`project_id`と`task_id`を指定する。
+2. 以下のコマンドを実行して、テスト用のプロジェクトとタスクを作成する。
+     * `poetry run python tests/create_test_project.py --organization ${MY_ORGANIZATION}`
+3. `pytest.ini`に、テスト対象の`project_id`と`task_id`を指定する。
     * `task_id`はプロジェクト`project_id`配下であること
     * **【注意】テストを実行すると、AnnoFabプロジェクトの内容が変更される**
-3. `$ make test`コマンドを実行する。
-
-#### タスクの前提条件
-* タスクの先頭画像にアノテーションが1個以上付与されている
-* タスクの先頭画像に検査コメントが1個以上付与されている
+4. `$ make test`コマンドを実行する。
 
 
 #### テストメソッドを指定してテストする方法
@@ -89,8 +57,17 @@ $ poetry run pytest --print_log_annofabapi tests
 * 「パスワード変更」など使用頻度が少なく、実行や確認がしづらいメソッド
 
 
+# Versioning
+annofabapiのバージョンはSemantic Versioning 2.0に従います。
+* メソッドが追加されたときは、マイナーバージョンを上げる。
+* annofabapiのバグ/ドキュメント修正などにより、annofabapiをリリースするときは、パッチバージョンを上げる。
+
+annofabapiのバージョンは以下のファイルで定義しています。
+* `annofabapi/__version__.py`
+* `pyproject.toml`
 
-## Release
+
+# PyPIへのリリース方法
 
 ## 事前作業
 
@@ -102,30 +79,12 @@ https://pypi.org/account/register/
 https://pypi.org/project/annofabapi/
 
 ## リリース方法
-
-### 1. annofabapiのバージョンを上げる
-以下のファイルに記載されているバージョンを上げてください。
-* `annofabapi/__version__.py`
-* `pyproject.toml`
-
-バージョンはSemantic Versioning 2.0に従います。
-* メソッドが追加されたときは、マイナーバージョンを上げる。
-* annofabapiのバグ/ドキュメント修正などにより、annofabapiをリリースするときは、パッチバージョンを上げる。
-
-
-### 2. PyPIに登録する
+以下のコマンドを実行してください。PyPIのユーザ名とパスワードの入力が求められます。
 
 ```
 $ make publish
 ```
 
-※ PyPIのユーザ名とパスワードの入力が求められます。
-
-
-
-### 3. GitHubのリリースページに追加
-GitHubのRelease機能を使って、リリース情報を記載します。
-
 
 ## Document
 ### ドキュメントの作成
@@ -143,3 +102,44 @@ ReadTheDocsのビルド結果は https://readthedocs.org/projects/annofab-api-py
 ## 開発フロー
 * masterブランチを元にしてブランチを作成して、プルリクを作成してください。masterブランチへの直接pushすることはGitHub上で禁止しています。
 * リリース時のソースはGitHubのRelease機能、またはPyPIからダウンロードしてください。
+
+
+
+
+-----------------
+# AnnoFab WebAPIの更新により、リリースする
+### 1.ソースコードの生成
+
+annofabapiのいくつかのファイルは、[AnnoFab Web APIのOpenAPI Spec](https://annofab.com/docs/api/swagger.yaml)から自動生成しています。
+以下のコマンドを実行すると、ソースコードが生成されます。詳細は[generate/README.md](generate/README.md)を参照してください。
+
+```
+# `generate/swagger/*.yaml`ファイルから、ソースコードを生成する
+$ generate/generate.sh
+
+# AnnoFab WebAPIのOpenAPI Spec を`generate/swagger/`にダウンロードしてから、ソースコードを生成する
+$ generate/generate.sh --download
+
+$ make format && make lint
+```
+
+### 2.テストの実施
+「テストの実行方法」を参照
+
+### 3.versionを上げる
+「Versioning」を参照
+
+### 4.プルリクを作ってマージする
+
+### 5.PyPIへパッケージをアップロードする
+「PyPIへのリリース方法」を参照
+
+### 6.GitHubのリリースページに追加
+GitHubのRelease機能を使って、リリース情報を記載します。
+
+
+
+
+
+
+

annofabapi/__version__.py

@@ -1 +1 @@
-__version__ = "0.40.1"
+__version__ = "0.40.2"

annofabapi/wrapper.py

@@ -39,6 +39,7 @@
     SimpleAnnotationDetail,
     SupplementaryData,
     Task,
+    TaskStatus,
 )
 from annofabapi.parser import SimpleAnnotationDirParser, SimpleAnnotationParser
 from annofabapi.utils import _download, _log_error_response, _raise_for_status, allow_404_error, str_now
@@ -1448,6 +1449,222 @@ def get_all_tasks(self, project_id: str, query_params: Optional[Dict[str, Any]]
         """
         return self._get_all_objects(self.api.get_tasks, limit=200, project_id=project_id, query_params=query_params)
 
+    def change_task_status_to_working(self, project_id: str, task_id: str) -> Task:
+        """
+        タスクのステータスを「作業中」に変更します。
+
+        Notes:
+            * 現在タスクを担当しているユーザーのみ、この操作を行うことができます。
+            * 現在の状態が未着手(not_started)、休憩中(break)、保留(on_hold)のいずれかであるタスクに対してのみ、この操作を行うことができます。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+
+        Returns:
+            変更後のタスク
+        """
+        task, _ = self.api.get_task(project_id, task_id)
+        request_body = {
+            "status": TaskStatus.WORKING.value,
+            "account_id": self.api.account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def change_task_status_to_break(self, project_id: str, task_id: str) -> Task:
+        """
+        タスクのステータスを「休憩中」に変更します。
+
+        Notes:
+            * 現在タスクを担当しているユーザーのみ、この操作を行うことができます。
+            * 現在の状態が作業中(working)のタスクに対してのみ、この操作を行うことができます。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+
+        Returns:
+            変更後のタスク
+        """
+        task, _ = self.api.get_task(project_id, task_id)
+        request_body = {
+            "status": TaskStatus.BREAK.value,
+            "account_id": self.api.account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def change_task_status_to_on_hold(self, project_id: str, task_id: str) -> Task:
+        """
+        タスクのステータスを「保留」に変更します。
+
+        Notes:
+            * 現在タスクを担当しているユーザーのみ、この操作を行うことができます。
+            * 現在の状態が作業中(working)のタスクに対してのみ、この操作を行うことができます。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+
+        Returns:
+            変更後のタスク
+        """
+        task, _ = self.api.get_task(project_id, task_id)
+        request_body = {
+            "status": TaskStatus.ON_HOLD.value,
+            "account_id": self.api.account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def complete_task(self, project_id: str, task_id: str) -> Task:
+        """
+        今のフェーズを完了させ、 次のフェーズに遷移させます。
+        教師付フェーズのときはタスクを提出します。
+        検査／受入フェーズのときは、タスクを合格にします。
+
+
+        Notes:
+            * 現在タスクを担当しているユーザーのみ、この操作を行うことができます。
+            * 現在の状態が作業中(working)のタスクに対してのみ、この操作を行うことができます。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+
+        Returns:
+            変更後のタスク
+        """
+        task, _ = self.api.get_task(project_id, task_id)
+        request_body = {
+            "status": TaskStatus.COMPLETE.value,
+            "account_id": self.api.account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def cancel_submitted_task(self, project_id: str, task_id: str) -> Task:
+        """
+        タスクの提出を取り消します。
+        「提出されたタスク」とは以下の状態になっています。
+         * 教師付フェーズで「提出」ボタンを押して、検査/受入フェーズへ遷移したタスク
+         * 検査フェーズから「合格」ボタンを押して、受入フェーズへ遷移したタスク
+
+        Notes:
+            * 現在タスクを担当しているユーザーのみ、この操作を行うことができます。
+            * タスク提出後に検査/受入(抜取含む)等の作業が一切行われていない場合のみ、この操作を行うことができます。
+            * 現在の状態が未着手(not_started)のタスクに対してのみ、この操作を行うことができます。
+            * 現在のフェーズが検査(inspection)、もしくは受入(acceptance)のタスクに対してのみ、この操作を行うことができます。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+
+        Returns:
+            変更後のタスク
+        """
+        task, _ = self.api.get_task(project_id, task_id)
+        request_body = {
+            "status": TaskStatus.CANCELLED.value,
+            "account_id": self.api.account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def cancel_completed_task(self, project_id: str, task_id: str, operator_account_id: Optional[str] = None) -> Task:
+        """
+        タスクの受入完了状態を取り消す。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+            operator_account_id: 受入完了状態を取り消した後の担当者のaccount_id
+
+        Returns:
+            変更後のタスク
+        """
+
+        task, _ = self.api.get_task(project_id, task_id)
+
+        request_body = {
+            "status": TaskStatus.NOT_STARTED.value,
+            "account_id": operator_account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def change_task_operator(
+        self, project_id: str, task_id: str, operator_account_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        タスクの担当者を変更します。
+
+        Notes:
+            * プロジェクトオーナー(owner)、もしくは受入担当者(accepter)のみ、この操作を行うことができます。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+            operator_account_id: 新しい担当者のaccount_id。Noneの場合は、担当者を「未割り当て」にします。
+
+        Returns:
+            変更後のタスク
+
+        """
+        task, _ = self.api.get_task(project_id, task_id)
+
+        request_body = {
+            "status": TaskStatus.NOT_STARTED.value,
+            "account_id": operator_account_id,
+            "last_updated_datetime": task["updated_datetime"],
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
+    def reject_task(self, project_id: str, task_id: str, force: bool = False) -> Dict[str, Any]:
+        """
+        タスクを差し戻します。
+        * 通常の差し戻しの場合、タスクの担当者は未割り当てになります。
+        * 強制差し戻しの場合、タスクの担当者は直前の教師付フェーズの担当者になります。
+
+        Notes:
+            * 通常の差し戻しの場合
+                * 現在タスクを担当しているユーザーのみ、この操作を行うことができます。
+                * 現在の状態が作業中(working)のタスクに対してのみ、この操作を行うことができます。
+                * 現在のフェーズが検査(inspection)、もしくは受入(acceptance)のタスクに対してのみ、この操作を行うことができます。
+            * 強制差し戻しの場合
+                * タスクの状態・フェーズを無視して、フェーズを教師付け(annotation)に、状態を未作業(not started)に変更します。
+                * タスクの担当者としては、直前の教師付け(annotation)フェーズの担当者を割り当てます。
+                * この差戻しは、抜取検査・抜取受入のスキップ判定に影響を及ぼしません。
+
+        Args:
+            project_id: プロジェクトID
+            task_id: タスクID
+            force: Trueなら強制差し戻し、Falseなら通常の差し戻しを実施する
+
+        Returns:
+            変更後のタスク
+
+        """
+
+        task, _ = self.api.get_task(project_id, task_id)
+
+        request_body = {
+            "status": TaskStatus.REJECTED.value,
+            "account_id": self.api.account_id,
+            "last_updated_datetime": task["updated_datetime"],
+            "force": force,
+        }
+        updated_task, _ = self.api.operate_task(project_id, task_id, request_body=request_body)
+        return updated_task
+
     #########################################
     # Public Method : Instruction
     #########################################