Add status parameter to filter jobs

.github/CHANGELOG.md

@@ -40,6 +40,21 @@ This release contains contributions from (in alphabetical order):
 
 ### New features since last release
 
+* Job lists can now be filtered by status as well.
+  [(#30)](https://github.com/XanaduAI/xanadu-cloud-client/pull/30)
+
+  Using the CLI:
+
+  ```bash
+  xcc job list --status '<status>'
+  ```
+
+  Using the Python API:
+
+   ```python
+  xcc.Job.list(connection, status='<status>')
+  ```
+
 * The Connection class can now load a Connection from a Settings instance.
   [(#22)](https://github.com/XanaduAI/xanadu-cloud-client/pull/22)
 

docs/conf.py

@@ -59,9 +59,7 @@
 # Tell sphinx what the pygments highlight language should be.
 highlight_language = "py"
 
-mathjax_path = (
-    "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"
-)
+mathjax_path = "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML"
 nbsphinx_requirejs_path = ""
 
 # Add any paths that contain templates here, relative to this directory.
@@ -85,6 +83,7 @@
 #
 # The full version, including alpha/beta/rc tags.
 import xcc
+
 release = xcc.__version__
 
 # The short X.Y version.
@@ -253,22 +252,19 @@
 html_theme_options = {
     "navbar_name": "Xanadu Cloud Client",
     "navbar_logo_colour": "#78909c",
-
     "navbar_right_links": [
         {
             "name": "GitHub",
             "href": "https://github.com/XanaduAI/xanadu-cloud-client",
             "icon": "fab fa-github",
         }
     ],
-
     "border_colour": "#78909c",
     "prev_next_button_colour": "#607d8b",
     "prev_next_button_hover_colour": "#34515e",
     "toc_marker_colour": "#78909c",
     "table_header_background_colour": "#78909c",
     "text_accent_colour": "#78909c",
-
 }
 
 edit_on_github_project = "XanaduAI/xanadu-cloud-client"

docs/requirements.txt

@@ -2,5 +2,6 @@ docutils
 m2r2
 nbsphinx
 sphinx-copybutton
-sphinx>=3.1.0
+sphinx==4.5.0
 xanadu-sphinx-theme==0.1.0
+traitlets==5.2.0

tests/test_commands.py

@@ -47,7 +47,7 @@ class MockJob(xcc.Job):
     """
 
     @staticmethod
-    def list(connection, limit=10, ids=None):
+    def list(connection, limit=10, ids=None, status=None):
         connection = xcc.commands.load_connection()
         return [MockJob(id_, connection) for id_ in ("foo", "bar", "baz")][:limit]
 

tests/test_job.py

@@ -123,6 +123,92 @@ def test_list(self, connection, add_response, limit, ids, want_params, want_name
         have_params = responses.calls[0].request.params  # pyright: reportGeneralTypeIssues=false
         assert have_params == want_params
 
+    @pytest.mark.parametrize(
+        "limit, ids, status, want_params, want_names",
+        [
+            (
+                1,
+                None,
+                "queued",
+                {"size": "1", "status": "queued"},
+                ["foo"],
+            ),
+            (
+                2,
+                None,
+                None,
+                {"size": "2"},
+                ["foo", "bar"],
+            ),
+            (
+                2,
+                None,
+                "invalid",
+                {"size": "2", "status": "invalid"},
+                [],
+            ),
+            (
+                2,
+                [
+                    "00000000-0000-0000-0000-000000000001",
+                    "00000000-0000-0000-0000-000000000002",
+                    "00000000-0000-0000-0000-000000000003",
+                ],
+                "complete",
+                {
+                    "size": "3",
+                    "id": [
+                        "00000000-0000-0000-0000-000000000001",
+                        "00000000-0000-0000-0000-000000000002",
+                        "00000000-0000-0000-0000-000000000003",
+                    ],
+                    "status": "complete",
+                },
+                ["bar"],
+            ),
+        ],
+    )
+    @responses.activate
+    def test_list_status(
+        self, connection, add_response, limit, ids, status, want_params, want_names
+    ):
+        """Tests that the correct jobs are listed and that the correct query
+        parameters are encoded in the HTTP request to the Xanadu Cloud platform.
+        We ensure that the jobs are filtered by the given status.
+        """
+        data = [
+            {
+                "id": "00000000-0000-0000-0000-000000000001",
+                "name": "foo",
+                "status": "queued",
+                "target": "qpu",
+                "created_at": "2020-01-03T12:34:56.789012+00:00",
+            },
+            {
+                "id": "00000000-0000-0000-0000-000000000002",
+                "name": "bar",
+                "status": "complete",
+                "target": "qpu",
+                "created_at": "2020-01-03T12:34:56.789012+00:00",
+                "finished_at": "2020-01-03T12:34:56.789013+00:00",
+            },
+        ][:limit]
+
+        add_response(body={"data": data}, path="/jobs")
+        if status is not None:
+            have_names = [
+                job.name
+                for job in xcc.Job.list(connection, limit=limit, ids=ids, status=status)
+                if status is not None and job.status == status
+            ]
+        else:
+            have_names = [job.name for job in xcc.Job.list(connection, limit=limit, ids=ids)]
+
+        assert have_names == want_names
+
+        have_params = responses.calls[0].request.params  # pyright: reportGeneralTypeIssues=false
+        assert have_params == want_params
+
     @pytest.mark.parametrize("name", [None, "foo"])
     @responses.activate
     def test_submit(self, job_id, connection, name):
@@ -167,7 +253,13 @@ def test_result(self, connection, job):
         with io.BytesIO() as buffer:
             # The public savez() function does not allow pickling to be disabled.
             savez = numpy.lib.npyio._savez  # pylint: disable=protected-access
-            savez(file=buffer, args=output, kwds=metadata, compress=False, allow_pickle=False)
+            savez(
+                file=buffer,
+                args=output,
+                kwds=metadata,
+                compress=False,
+                allow_pickle=False,
+            )
 
             buffer.seek(0)
             body = buffer.read()

xcc/commands.py

@@ -257,18 +257,19 @@ def get_job(
 
 
 @beautify
-def list_jobs(limit: int = 5, ids: List[str] = None) -> Sequence[Mapping]:
+def list_jobs(limit: int = 5, ids: List[str] = None, status: str = None) -> Sequence[Mapping]:
     """Lists jobs submitted to the Xanadu Cloud.
 
     Args:
         limit (int): Maximum number of jobs to display.
         ids (List[str], optional): IDs of the jobs to display. If at least one
             ID is specified, the limit flag will be set to the number of IDs.
+        status (str): Status parameter used to filter returned jobs based on given status.
 
     Returns:
         Sequence[Mapping]: Overview of each job submitted to the Xanadu Cloud.
     """
-    jobs = Job.list(connection=load_connection(), limit=limit, ids=ids)
+    jobs = Job.list(connection=load_connection(), limit=limit, ids=ids, status=status)
     return [job.overview for job in jobs]
 
 

xcc/job.py

@@ -93,23 +93,32 @@ class Job:
 
     @staticmethod
     def list(
-        connection: Connection, limit: int = 5, ids: Optional[Collection[str]] = None
+        connection: Connection,
+        limit: int = 5,
+        ids: Optional[Collection[str]] = None,
+        status: str = None,
     ) -> Sequence[Job]:
         """Returns jobs submitted to the Xanadu Cloud.
 
+
         Args:
             connection (Connection): connection to the Xanadu Cloud
             limit (int): maximum number of jobs to retrieve
             ids (Collection[str], optional): IDs of the jobs to retrieve; if at
                 least one ID is specified, ``limit`` will be set to the length
                 of the ID collection
+            status (str, optional): status parameter used to filter the jobs list.
+                If status is empty, return all the jobs
 
         Returns:
             Sequence[Job]: jobs which were submitted on the Xanadu Cloud by the
             user associated with the Xanadu Cloud connection
         """
         size = len(ids) if ids else limit
-        response = connection.request("GET", "/jobs", params={"size": size, "id": ids})
+
+        response = connection.request(
+            "GET", "/jobs", params={"size": size, "id": ids, "status": status}
+        )
 
         jobs = []
 
@@ -122,7 +131,11 @@ def list(
 
     @staticmethod
     def submit(
-        connection: Connection, name: Optional[str], target: str, circuit: str, language: str
+        connection: Connection,
+        name: Optional[str],
+        target: str,
+        circuit: str,
+        language: str,
     ) -> Job:
         """Submits a job to the Xanadu Cloud.
 
@@ -136,7 +149,12 @@ def submit(
         Returns:
             Job: job submitted to the Xanadu Cloud
         """
-        payload = {"name": name, "target": target, "circuit": circuit, "language": language}
+        payload = {
+            "name": name,
+            "target": target,
+            "circuit": circuit,
+            "language": language,
+        }
         response = connection.request("POST", "/jobs", json=payload)
         details = response.json()