Job tags support

CHANGELOG.D/1393.feature

@@ -0,0 +1 @@
+Support job tags: `neuro run --tag=experiment-1`, `neuro ps --tag=experiment-1`.

README.md

@@ -423,6 +423,7 @@ Name | Description|
 |_--http PORT_|Enable HTTP port forwarding to container  \[default: 80]|
 |_\--http-auth / --no-http-auth_|Enable HTTP authentication for forwarded HTTP port  \[default: True]|
 |_\-n, --name NAME_|Optional job name|
+|_--tag TAG_|Optional job tag, multiple values allowed|
 |_\-d, --description DESC_|Optional job description in free format|
 |_\-q, --quiet_|Run command in quiet mode \(DEPRECATED)|
 |_\-v, --volume MOUNT_|Mounts directory from vault into container. Use multiple options to mount more than one volume. --volume=HOME is an alias for storage::/var/storage/home:rw and storage://neuromation/public:/var/storage/neuromation:ro|
@@ -480,6 +481,7 @@ Name | Description|
 |_\--http-auth / --no-http-auth_|Enable HTTP authentication for forwarded HTTP port  \[default: True]|
 |_\-p, --preemptible / -P, --non-preemptible_|Run job on a lower-cost preemptible instance  \[default: False]|
 |_\-n, --name NAME_|Optional job name|
+|_--tag TAG_|Optional job tag, multiple values allowed|
 |_\-d, --description DESC_|Optional job description in free format|
 |_\-q, --quiet_|Run command in quiet mode \(DEPRECATED)|
 |_\-v, --volume MOUNT_|Mounts directory from vault into container. Use multiple options to mount more than one volume. --volume=HOME is an alias for storage::/var/storage/home:rw and storage://neuromation/public:/var/storage/neuromation:ro|
@@ -516,6 +518,7 @@ neuro ps -a --owner=user-1 --owner=user-2
 neuro ps --name my-experiments-v1 -s failed -s succeeded
 neuro ps --description=my favourite job
 neuro ps -s failed -s succeeded -q
+neuro ps --tag tag1 -t tag2
 
 ```
 
@@ -527,6 +530,7 @@ Name | Description|
 |_\-o, --owner TEXT_|Filter out jobs by owner \(multiple option).|
 |_\-a, --all_|Show all jobs regardless the status \(equivalent to `\-s pending -s running -s succeeded -s failed`).|
 |_\-n, --name NAME_|Filter out jobs by name.|
+|_\-t, --tag TAG_|Filter out jobs by tag \(multiple option)|
 |_\-d, --description DESCRIPTION_|Filter out jobs by description \(exact match).|
 |_\-q, --quiet_|Run command in quiet mode \(DEPRECATED)|
 |_\-w, --wide_|Do not cut long lines for terminal width.|
@@ -1669,6 +1673,7 @@ Name | Description|
 |_--http PORT_|Enable HTTP port forwarding to container  \[default: 80]|
 |_\--http-auth / --no-http-auth_|Enable HTTP authentication for forwarded HTTP port  \[default: True]|
 |_\-n, --name NAME_|Optional job name|
+|_--tag TAG_|Optional job tag, multiple values allowed|
 |_\-d, --description DESC_|Optional job description in free format|
 |_\-q, --quiet_|Run command in quiet mode \(DEPRECATED)|
 |_\-v, --volume MOUNT_|Mounts directory from vault into container. Use multiple options to mount more than one volume. --volume=HOME is an alias for storage::/var/storage/home:rw and storage://neuromation/public:/var/storage/neuromation:ro|
@@ -1726,6 +1731,7 @@ Name | Description|
 |_\--http-auth / --no-http-auth_|Enable HTTP authentication for forwarded HTTP port  \[default: True]|
 |_\-p, --preemptible / -P, --non-preemptible_|Run job on a lower-cost preemptible instance  \[default: False]|
 |_\-n, --name NAME_|Optional job name|
+|_--tag TAG_|Optional job tag, multiple values allowed|
 |_\-d, --description DESC_|Optional job description in free format|
 |_\-q, --quiet_|Run command in quiet mode \(DEPRECATED)|
 |_\-v, --volume MOUNT_|Mounts directory from vault into container. Use multiple options to mount more than one volume. --volume=HOME is an alias for storage::/var/storage/home:rw and storage://neuromation/public:/var/storage/neuromation:ro|
@@ -1762,6 +1768,7 @@ neuro ps -a --owner=user-1 --owner=user-2
 neuro ps --name my-experiments-v1 -s failed -s succeeded
 neuro ps --description=my favourite job
 neuro ps -s failed -s succeeded -q
+neuro ps --tag tag1 -t tag2
 
 ```
 
@@ -1773,6 +1780,7 @@ Name | Description|
 |_\-o, --owner TEXT_|Filter out jobs by owner \(multiple option).|
 |_\-a, --all_|Show all jobs regardless the status \(equivalent to `\-s pending -s running -s succeeded -s failed`).|
 |_\-n, --name NAME_|Filter out jobs by name.|
+|_\-t, --tag TAG_|Filter out jobs by tag \(multiple option)|
 |_\-d, --description DESCRIPTION_|Filter out jobs by description \(exact match).|
 |_\-q, --quiet_|Run command in quiet mode \(DEPRECATED)|
 |_\-w, --wide_|Do not cut long lines for terminal width.|

docs/jobs_reference.rst

@@ -45,6 +45,7 @@ Jobs
 
    .. comethod:: list(*, statuses: Iterable[JobStatus] = (), \
                       name: str = "" \
+                      tags: Sequence[str] = (), \
                       owners: Iterable[str] = (),
                  ) -> List[JobDescription]
 
@@ -69,6 +70,11 @@ Jobs
 
                        Empty string means that no filter is applied (default).
 
+      :param str name: Filter jobs by :attr:`~JobDescription.tags`. Retrieves all
+                       jobs submitted with at least one tag from the specified list.
+
+                       Empty list means that no filter is applied (default).
+
       :param ~typing.Iterable[str] owners: filter jobs by their owners.
 
                                            The parameter can be a set or list of owner
@@ -113,6 +119,7 @@ Jobs
    .. comethod:: run(container: Container, \
                      *, \
                      name: Optional[str] = None, \
+                     tags: Sequence[str] = (), \
                      description: Optional[str] = None, \
                      is_preemptible: bool = False, \
                      schedule_timeout: Optional[float] = None, \
@@ -125,6 +132,8 @@ Jobs
 
       :param str name: optional container name.
 
+      :param str name: optional job tags.
+
       :param str desciption: optional container description.
 
       :param bool is_preemtible: a flag that specifies is the job is *preemptible* or
@@ -269,6 +278,11 @@ JobDescription
       Job name provided by user at creation time, :class:`str` or ``None`` if name is
       omitted.
 
+   .. attribute:: tags
+
+      List of job tags provided by user at creation time, :class:`Sequence[str]` or
+      ``()`` if tags omitted.
+
    .. attribute:: description
 
       Job description text provided by user at creation time, :class:`str` or ``None``

neuromation/api/jobs.py

@@ -109,6 +109,7 @@ class JobDescription:
     container: Container
     is_preemptible: bool
     name: Optional[str] = None
+    tags: Sequence[str] = ()
     description: Optional[str] = None
     http_url: URL = URL()
     ssh_server: URL = URL()
@@ -135,6 +136,7 @@ async def run(
         container: Container,
         *,
         name: Optional[str] = None,
+        tags: Sequence[str] = (),
         description: Optional[str] = None,
         is_preemptible: bool = False,
         schedule_timeout: Optional[float] = None,
@@ -147,6 +149,8 @@ async def run(
         }
         if name:
             payload["name"] = name
+        if tags:
+            payload["tags"] = tags
         if description:
             payload["description"] = description
         if schedule_timeout:
@@ -164,6 +168,7 @@ async def list(
         *,
         statuses: Iterable[JobStatus] = (),
         name: str = "",
+        tags: Iterable[str] = (),
         owners: Iterable[str] = (),
     ) -> List[JobDescription]:
         url = self._config.api_url / "jobs"
@@ -174,6 +179,8 @@ async def list(
             params.add("name", name)
         for owner in owners:
             params.add("owner", owner)
+        for tag in tags:
+            params.add("tag", tag)
         params["cluster_name"] = self._config.cluster_name
         auth = await self._config._api_auth()
         async with self._core.request("GET", url, params=params, auth=auth) as resp:
@@ -513,6 +520,7 @@ def _job_description_from_api(res: Dict[str, Any], parse: Parser) -> JobDescript
     owner = res["owner"]
     cluster_name = res["cluster_name"]
     name = res.get("name")
+    tags = res.get("tags", ())
     description = res.get("description")
     history = JobStatusHistory(
         status=JobStatus(res["history"].get("status", "unknown")),
@@ -536,6 +544,7 @@ def _job_description_from_api(res: Dict[str, Any], parse: Parser) -> JobDescript
         container=container,
         is_preemptible=res["is_preemptible"],
         name=name,
+        tags=tags,
         description=description,
         http_url=http_url_named or http_url,
         ssh_server=ssh_server,

neuromation/cli/job.py

@@ -201,6 +201,13 @@ def job() -> None:
     default=None,
     secure=True,
 )
+@option(
+    "--tag",
+    metavar="TAG",
+    type=str,
+    help="Optional job tag, multiple values allowed",
+    multiple=True,
+)
 @option(
     "-d",
     "--description",
@@ -298,6 +305,7 @@ async def submit(
     life_span: Optional[str],
     preemptible: bool,
     name: Optional[str],
+    tag: Sequence[str],
     description: Optional[str],
     wait_start: bool,
     pass_config: bool,
@@ -344,6 +352,7 @@ async def submit(
         life_span=life_span,
         preemptible=preemptible,
         name=name,
+        tags=tag,
         description=description,
         wait_start=wait_start,
         pass_config=pass_config,
@@ -516,6 +525,14 @@ async def _print_logs(root: Root, job: str) -> None:
     ),
 )
 @option("-n", "--name", metavar="NAME", help="Filter out jobs by name.", secure=True)
+@option(
+    "-t",
+    "--tag",
+    metavar="TAG",
+    type=str,
+    help="Filter out jobs by tag (multiple option)",
+    multiple=True,
+)
 @option(
     "-d",
     "--description",
@@ -542,6 +559,7 @@ async def ls(
     status: Sequence[str],
     all: bool,
     name: str,
+    tag: Sequence[str],
     owner: Sequence[str],
     description: str,
     wide: bool,
@@ -557,13 +575,17 @@ async def ls(
     neuro ps --name my-experiments-v1 -s failed -s succeeded
     neuro ps --description="my favourite job"
     neuro ps -s failed -s succeeded -q
+    neuro ps --tag tag1 -t tag2
     """
 
     format = await calc_columns(root.client, format)
 
     statuses = calc_statuses(status, all)
     owners = set(owner)
-    jobs = await root.client.jobs.list(statuses=statuses, name=name, owners=owners)
+    tags = set(tag)
+    jobs = await root.client.jobs.list(
+        statuses=statuses, name=name, owners=owners, tags=tags
+    )
 
     # client-side filtering
     if description:
@@ -750,6 +772,13 @@ def format_fail(job: str, reason: Exception) -> str:
     default=None,
     secure=True,
 )
+@option(
+    "--tag",
+    metavar="TAG",
+    type=str,
+    help="Optional job tag, multiple values allowed",
+    multiple=True,
+)
 @option(
     "-d",
     "--description",
@@ -843,6 +872,7 @@ async def run(
     life_span: Optional[str],
     preemptible: Optional[bool],
     name: Optional[str],
+    tag: Sequence[str],
     description: Optional[str],
     wait_start: bool,
     pass_config: bool,
@@ -897,6 +927,7 @@ async def run(
         life_span=life_span,
         preemptible=job_preset.is_preemptible,
         name=name,
+        tags=tag,
         description=description,
         wait_start=wait_start,
         pass_config=pass_config,
@@ -944,6 +975,7 @@ async def run_job(
     life_span: Optional[str],
     preemptible: bool,
     name: Optional[str],
+    tags: Sequence[str],
     description: Optional[str],
     wait_start: bool,
     pass_config: bool,
@@ -1021,6 +1053,7 @@ async def run_job(
         container,
         is_preemptible=preemptible,
         name=name,
+        tags=tags,
         description=description,
         life_span=job_life_span,
     )