phable-cli 0.1.1__tar.gz → 0.1.3__tar.gz

{phable_cli-0.1.1 → phable_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: phable-cli
-Version: 0.1.1
+Version: 0.1.3
 Summary: Manage Phabricator tasks from the comfort of your terminal
 License: MIT
 Author: Balthazar Rouberol
@@ -44,14 +44,16 @@ Usage: phable [OPTIONS] COMMAND [ARGS]...
   Manage Phabricator tasks from the comfort of your terminal
 
 Options:
-  --help  Show this message and exit.
+  --version  Show the version and exit.
+  --help     Show this message and exit.
 
 Commands:
-  assign   Assign one or multiple task ids to a username
-  comment  Add a comment to a task
-  create   Create a new task
-  move     Move one or several task on their current project board
-  show     Show task details
+  assign     Assign one or multiple task ids to a username
+  comment    Add a comment to a task
+  create     Create a new task
+  move       Move one or several task on their current project board
+  show       Show task details
+  subscribe  Subscribe to one or multiple task ids
 ```
 
 ## Setup
@@ -59,7 +61,7 @@ Commands:
 For `phable` to work, you need to define the following environment variables:
 
 - `PHABRICATOR_URL`: URL to your phabricator instance. Ex: `PHABRICATOR_URL=https://phabricator.wikimedia.org`
-- `PHABRICATOR_API_TOKEN`: Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
+- `PHABRICATOR_TOKEN`: Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
 - `PHABRICATOR_DEFAULT_PROJECT_PHID`: id for the Phabricator project to be used by default when creating tasks.
 
 Note: to get `PHABRICATOR_DEFAULT_PROJECT_PHID`, define the first 2 environment variables, and run the following command, where T123456 is a task id belonging to your project.

{phable_cli-0.1.1 → phable_cli-0.1.3}/README.md

@@ -25,14 +25,16 @@ Usage: phable [OPTIONS] COMMAND [ARGS]...
   Manage Phabricator tasks from the comfort of your terminal
 
 Options:
-  --help  Show this message and exit.
+  --version  Show the version and exit.
+  --help     Show this message and exit.
 
 Commands:
-  assign   Assign one or multiple task ids to a username
-  comment  Add a comment to a task
-  create   Create a new task
-  move     Move one or several task on their current project board
-  show     Show task details
+  assign     Assign one or multiple task ids to a username
+  comment    Add a comment to a task
+  create     Create a new task
+  move       Move one or several task on their current project board
+  show       Show task details
+  subscribe  Subscribe to one or multiple task ids
 ```
 
 ## Setup
@@ -40,7 +42,7 @@ Commands:
 For `phable` to work, you need to define the following environment variables:
 
 - `PHABRICATOR_URL`: URL to your phabricator instance. Ex: `PHABRICATOR_URL=https://phabricator.wikimedia.org`
-- `PHABRICATOR_API_TOKEN`: Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
+- `PHABRICATOR_TOKEN`: Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
 - `PHABRICATOR_DEFAULT_PROJECT_PHID`: id for the Phabricator project to be used by default when creating tasks.
 
 Note: to get `PHABRICATOR_DEFAULT_PROJECT_PHID`, define the first 2 environment variables, and run the following command, where T123456 is a task id belonging to your project.

phable_cli-0.1.3/phable_cli/cache.py

@@ -0,0 +1,89 @@
+import inspect
+import json
+import os
+import sys
+import time
+from datetime import datetime
+from functools import wraps
+from pathlib import Path
+
+CACHE_HOME_PER_PLATFORM = {
+    "darwin": Path.home() / "Library" / "Caches",
+    "linux": Path(os.getenv("XDG_CACHE_HOME", f"{Path.home()}/.config")),
+    "windows": Path("c:/", "Users", os.getlogin(), "AppData", "Local", "Temp"),
+}
+
+
+class Cache:
+    """A persistent cache for long-lived data, such as user or project"""
+
+    def __init__(self):
+        self.cache_dir = CACHE_HOME_PER_PLATFORM[sys.platform] / "phind"
+        if not self.cache_dir.exists():
+            self.cache_dir.mkdir()
+        self.cache_filepath = self.cache_dir / "cache.json"
+        if self.cache_filepath.exists():
+            self.data = json.load(open(self.cache_filepath))
+        else:
+            self.data = {}
+
+    def dump(self):
+        json.dump(self.data, open(self.cache_filepath, "w"), indent=2)
+
+    def __setitem__(self, key, value):
+        self.data[key] = value
+
+    def __getitem__(self, key):
+        return self.data[key]
+
+    def __contains__(self, key):
+        return key in self.data
+
+
+cache = Cache()
+
+
+def cached(*cached_args, **cached_kwargs):
+    """Cache the return value of the decorated function in memory.
+
+    If a `ttl` keyword argment (of type typedelta) is passed to the decorator,
+    the cached value will only be valid for the provided duration.
+
+    """
+
+    def decorator(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            # Check if the decorated function takes a `self` parameter, which is then omitted
+            # from the cache key, as we just care about the other arguments, not the class itself.
+            if list(inspect.signature(f).parameters.keys())[0] == "self":
+                cache_args = args[1:]
+            else:
+                cache_args = args
+            cache_key = "__".join(map(str, cache_args))
+            cache_key += "__".join([f"{k}={v}" for k, v in kwargs.items()])
+            section = f.__name__
+            if section not in cache:
+                cache[section] = {}
+            if cache_hit := cache[section].get(cache_key):
+                if (
+                    cache_hit["valid_until"] is None
+                    or cache_hit["valid_until"] > time.time()
+                ):
+                    return cache_hit["data"]
+            data = f(*args, **kwargs)
+            cache[section][cache_key] = {
+                "data": data,
+                "valid_until": (
+                    (datetime.now() + cached_kwargs["ttl"]).timestamp()
+                    if cached_kwargs.get("ttl")
+                    else None
+                ),
+            }
+            return data
+
+        return wrapper
+
+    if cached_args and callable(cached_args[0]):
+        return decorator(cached_args[0])
+    return decorator

{phable_cli-0.1.1 → phable_cli-0.1.3}/phable_cli/cli.py

@@ -1,15 +1,24 @@
-import os
+import atexit
 import json
+import re
+from typing import Optional
 
 import click
+from click import Context
 
+from .cache import cache
+from .config import config
 from .phabricator import PhabricatorClient
 from .utils import text_from_cli_arg_or_fs_or_editor
 
 VARIADIC = -1  # Used for click variadic arguments
 
+# Dump the in-memory cache to disk when existing the CLI
+atexit.register(cache.dump)
+
 
 @click.group()
+@click.version_option()
 def cli():
     """Manage Phabricator tasks from the comfort of your terminal"""
     pass
@@ -110,41 +119,91 @@ def show_task(task_id: int, format: str = "plain"):
     default="normal",
 )
 @click.option("--parent-id", type=Task.from_str, help="ID of parent task")
+@click.option("--tags", multiple=True, help="Tags to associate to the task")
+@click.option("--owner", help="The username of the task owner")
 @click.pass_context
 def create_task(
     ctx,
     title: str,
-    description: str,
+    description: Optional[str],
     priority: str,
-    parent_id: str | None,
+    parent_id: Optional[str],
+    tags: list[str],
+    owner: Optional[str],
 ):
     """Create a new task
 
     \b
     Examples:
+    \b
+    # Create a task with a long description by writing it in your favorite text editor
+    $ phable create --title 'A task'
+    \b
+    # Create a task with a long description by pointing it to a description file
+    $ phable create --title 'A task' --description path/to/description.txt
+    \b
     # Create a task with associated title, priority and desription
     $ phable create --title 'Do the thing!' --priority high --description 'Address the thing right now'
     \b
     # Create a task with a given parent
     $ phable create --title 'A subtask' --description 'Subtask description' --parent-id T123456
     \b
-    # Create a task with a long description by pointing it to a description file
-    $ phable create --title 'A task' --description path/to/description.txt
+    # Create a task with an associated top-level project tag
+    $ phable create --title 'A task' --tags 'Data-Platform-SRE'
     \b
-    # Create a task with a long description by writing it in your favorite text editor
-    $ phable create --title 'A task'
+    # Create a task with an associated sub-project tag
+    $ phable create --title 'A task' --tags 'Data-Platform-SRE (2025.03.22 - 2025.04.11)
+    \b
+    # Create a task with an associated owner
+    $ phable create --title 'A task' --owner brouberol
+
     """
     client = PhabricatorClient()
     description = text_from_cli_arg_or_fs_or_editor(description)
     task_params = {
         "title": title,
         "description": description,
-        "projects.add": [os.environ["PHABRICATOR_DEFAULT_PROJECT_PHID"]],
+        "projects.add": [config.phabricator_default_project_phid],
         "priority": priority,
     }
+
+    tag_projects_phids = []
+    for tag in tags:
+        # The tag name can be a simple string, or "parent name (subproject name)"
+        # In the case of the latter, we need to fetch details for both projects
+        if match := re.match(
+            r"(?P<parent>[\w\s\.-]+) \((?P<subproject>[\w\s+\.-]+)\)", tag
+        ):
+            parent_title = match.group("parent").strip()
+            if parent_project := client.find_project_by_title(title=parent_title):
+                parent_project_phid = parent_project["phid"]
+            else:
+                ctx.fail(f"Project {parent_project} not found")
+            project_title = match.group("subproject").strip()
+            if project := client.find_project_by_title(
+                title=project_title, parent_phid=parent_project_phid
+            ):
+                tag_projects_phids.append(project["phid"])
+            else:
+                ctx.fail(f"Project {project_title} not found")
+        # Simple project name with no subproject
+        elif project := client.find_project_by_title(title=tag):
+            tag_projects_phids.append(project["phid"])
+        else:
+            ctx.fail(f"Project {tag} not found")
+
+    if tag_projects_phids:
+        task_params["projects.add"] = tag_projects_phids
+
+    if owner:
+        if owner_user := client.find_user_by_username(username=owner):
+            task_params["owner"] = owner_user["phid"]
+        else:
+            ctx.fail(f"User {owner} not found")
+
     if parent_id:
         parent = client.show_task(parent_id)
-        task_params["parents.add"] = [parent["phid"]]
+        task_params["parents.set"] = [parent["phid"]]
 
     task = client.create_or_edit_task(task_params)
     ctx.invoke(show_task, task_id=task["result"]["object"]["id"])
@@ -158,7 +217,7 @@ def create_task(
 )
 @click.argument("task-ids", type=Task.from_str, nargs=VARIADIC)
 @click.pass_context
-def assign_task(ctx, task_ids: list[int], username: str | None):
+def assign_task(ctx, task_ids: list[int], username: Optional[str]):
     """Assign one or multiple task ids to a username
 
     \b
@@ -185,9 +244,19 @@ def assign_task(ctx, task_ids: list[int], username: str | None):
     required=True,
     help="Name of destination column on the current project board",
 )
+@click.option(
+    "--milestone/--no-milestone",
+    default=False,
+    help=(
+        "If --milestone is passed, the task will be moved onto the current project's associated "
+        "milestone board, instead of the project board itself"
+    ),
+)
 @click.argument("task-ids", type=Task.from_str, nargs=VARIADIC)
 @click.pass_context
-def move_task(ctx, task_ids: list[int], column: str | None):
+def move_task(
+    ctx: Context, task_ids: list[int], column: Optional[str], milestone: bool
+) -> None:
     """Move one or several task on their current project board
 
     If the task is moved to a 'Done' column, it will be automatically
@@ -199,28 +268,19 @@ def move_task(ctx, task_ids: list[int], column: str | None):
     $ phable move T123456 T234567 --column 'Done'
 
     """
-    client = PhabricatorClient()
-    if not (
-        current_milestone := client.get_project_current_milestone(
-            project_phid=os.environ["PHABRICATOR_DEFAULT_PROJECT_PHID"]
-        )
-    ):
-        ctx.fail("Current milestone not found")
-    current_milestone_columns = client.list_project_columns(
-        project_phid=current_milestone["fields"]["proxyPHID"]
-    )
-    for col in current_milestone_columns:
-        if col["fields"]["name"].lower() == column.lower():
-            column_phid = col["phid"]
-            break
-    else:
-        ctx.fail(
-            f"Column {column} not found in milestone {current_milestone['fields']['name']}"
+    try:
+        client = PhabricatorClient()
+        target_project_phid = client.get_main_project_or_milestone(
+            milestone, config.phabricator_default_project_phid
         )
-    for task_id in task_ids:
-        client.move_task_to_column(task_id=task_id, column_phid=column_phid)
-        if column.lower() == "done":
-            client.mark_task_as_resolved(task_id)
+        target_column_phid = client.find_column_in_project(target_project_phid, column)
+
+        for task_id in task_ids:
+            client.move_task_to_column(task_id=task_id, column_phid=target_column_phid)
+            if column.lower() == "done":
+                client.mark_task_as_resolved(task_id)
+    except ValueError as ve:
+        ctx.fail(ve)
 
 
 @cli.command(name="comment")
@@ -230,7 +290,7 @@ def move_task(ctx, task_ids: list[int], column: str | None):
     help="Comment text or path to a text file containing the comment body. If not provided, an editor will be opened.",
 )
 @click.argument("task-id", type=Task.from_str)
-def comment_on_task(task_id: int, comment: str | None):
+def comment_on_task(task_id: int, comment: Optional[str]):
     """Add a comment to a task
 
     \b
@@ -238,11 +298,32 @@ def comment_on_task(task_id: int, comment: str | None):
     $ phable comment T123456 --comment 'hello'              # set comment body from the cli itself
     $ phable comment T123456 --comment path/to/comment.txt  # set comment body from a text file
     $ phable comment T123456                                # set comment body from your own text editor
+
     """
     client = PhabricatorClient()
     comment = text_from_cli_arg_or_fs_or_editor(comment)
     client.create_or_edit_task(task_id=task_id, params={"comment": comment})
 
 
+@cli.command(name="subscribe")
+@click.argument("task-ids", type=Task.from_str, nargs=VARIADIC)
+@click.pass_context
+def subscribe_to_task(ctx, task_ids: list[int]):
+    """Subscribe to one or multiple task ids
+
+    \b
+    Examples:
+    $ phable subscribe T123456
+    $ phable subscribe T123456 T234567
+
+    """
+    client = PhabricatorClient()
+    user = client.current_user()
+    if not user:
+        ctx.fail("Current user was not found")
+    for task_id in task_ids:
+        client.add_user_to_task_subscribers(task_id=task_id, user_phid=user["phid"])
+
+
 if __name__ == "__main__":
     cli()

phable_cli-0.1.3/phable_cli/config.py

@@ -0,0 +1,28 @@
+import os
+import sys
+from dataclasses import dataclass, field
+from functools import partial
+
+
+def os_getenv_or_raise(env_var_name: str):
+    if val := os.getenv(env_var_name):
+        return val
+    sys.stderr.write(f"{env_var_name} is not set and is required\n")
+    sys.stderr.flush()
+    sys.exit(1)
+
+
+def field_with_default_from_env(env_var_name):
+    return field(default_factory=partial(os_getenv_or_raise, env_var_name))
+
+
+@dataclass(frozen=True)
+class Config:
+    phabricator_url: str = field_with_default_from_env("PHABRICATOR_URL")
+    phabricator_token: str = field_with_default_from_env("PHABRICATOR_TOKEN")
+    phabricator_default_project_phid: str = field_with_default_from_env(
+        "PHABRICATOR_DEFAULT_PROJECT_PHID"
+    )
+
+
+config = Config()

{phable_cli-0.1.1 → phable_cli-0.1.3}/phable_cli/phabricator.py

@@ -1,9 +1,9 @@
-import os
+from typing import Any, Optional, TypeVar
+from datetime import timedelta
 import requests
 
-from typing import Any, TypeVar
-from functools import cache
-
+from .cache import cached
+from .config import config
 
 T = TypeVar("T")
 
@@ -16,16 +16,11 @@ class PhabricatorClient:
     """
 
     def __init__(self):
-        self.base_url = os.environ["PHABRICATOR_URL"].rstrip("/")
-        self.token = os.environ["PHABRICATOR_TOKEN"]
+        self.base_url = config.phabricator_url.rstrip("/")
+        self.token = config.phabricator_token
         self.session = requests.Session()
         self.timeout = 5
 
-        if not self.base_url or not self.token:
-            raise ValueError(
-                "PHABRICATOR_URL and PHABRICATOR_TOKEN must be set in your envionment"
-            )
-
     def _first(self, result_set: list[T]) -> T:
         if result_set:
             return result_set[0]
@@ -64,7 +59,7 @@ class PhabricatorClient:
             raise Exception(f"API request failed: {str(e)}")
 
     def create_or_edit_task(
-        self, params: dict[str, Any], task_id: int | None = None
+        self, params: dict[str, Any], task_id: Optional[int] = None
     ) -> dict[str, Any]:
         """Create or edit (if a task_id is provided) a Maniphest task."""
         raw_params = {}
@@ -97,7 +92,8 @@ class PhabricatorClient:
             "maniphest.search", params={"constraints[parentIDs][0]": parent_id}
         )["result"]["data"]
 
-    def find_parent_task(self, subtask_id: int) -> dict[str, Any] | None:
+    @cached
+    def find_parent_task(self, subtask_id: int) -> Optional[dict[str, Any]]:
         """Return details of the parent Maniphest task for the provided task id"""
         return self._first(
             self._make_request(
@@ -111,16 +107,25 @@ class PhabricatorClient:
 
     def mark_task_as_resolved(self, task_id: int) -> dict[str, Any]:
         """Set the status of the argument task to Resolved"""
-        return self.create_or_edit_task(task_id=task_id, params={"status": "Resolved"})
+        return self.create_or_edit_task(task_id=task_id, params={"status": "resolved"})
+
+    def add_user_to_task_subscribers(
+        self, task_id: int, user_phid: str
+    ) -> dict[str, Any]:
+        """Add the user to the list of the task subscribers"""
+        return self.create_or_edit_task(
+            task_id=task_id, params={"subscribers.add": [user_phid]}
+        )
 
-    @cache
-    def show_user(self, phid: str) -> dict[str, Any] | None:
+    @cached
+    def show_user(self, phid: str) -> Optional[dict[str, Any]]:
         """Show details of a Maniphest user"""
         user = self._make_request(
             "user.search", params={"constraints[phids][0]": phid}
         )["result"]["data"]
         return self._first(user)
 
+    @cached
     def show_projects(self, phids: list[str]) -> dict[str, Any]:
         """Show details of the provided Maniphest projects"""
         params = {}
@@ -128,11 +133,13 @@ class PhabricatorClient:
             params[f"constraints[phids][{i}]"] = phid
         return self._make_request("project.search", params=params)["result"]["data"]
 
+    @cached
     def current_user(self) -> dict[str, Any]:
         """Return details of the user associated with the phabricator API token"""
         return self._make_request("user.whoami")["result"]
 
-    def find_user_by_username(self, username: str) -> dict[str, Any] | None:
+    @cached
+    def find_user_by_username(self, username: str) -> Optional[dict[str, Any]]:
         """Return user details of the user with the provided username"""
         user = self._make_request(
             "user.search", params={"constraints[usernames][0]": username}
@@ -143,6 +150,7 @@ class PhabricatorClient:
         """Set the owner of the argument task to the argument user id"""
         return self.create_or_edit_task(task_id=task_id, params={"owner": user_phid})
 
+    @cached(ttl=timedelta(days=1))
     def list_project_columns(
         self,
         project_phid: str,
@@ -152,13 +160,58 @@ class PhabricatorClient:
             "project.column.search", params={"constraints[projects][0]": project_phid}
         )["result"]["data"]
 
-    def get_project_current_milestone(self, project_phid: str) -> dict[str, Any] | None:
-        """Return the first non hidden column associated with a subproject.
-
-        We assume it to be associated with the current milestone.
+    @cached(ttl=timedelta(days=1))
+    def get_project_current_milestone_phid(self, project_phid: str) -> Optional[str]:
+        """Return the PHID of the current milestone associated with the given project.
 
+        We assume that the current milestone is displayed on the project's
+        board as the first non-hidden column.
         """
         columns = self.list_project_columns(project_phid)
         for column in columns:
             if column["fields"]["proxyPHID"] and not column["fields"]["isHidden"]:
-                return column
+                return column["fields"]["proxyPHID"]
+
+    def get_main_project_or_milestone(self, milestone: bool, project_phid: str) -> str:
+        """Returns either the given project, or the current milestone of the given project."""
+        if not milestone:
+            return project_phid
+
+        target_project_phid = self.get_project_current_milestone_phid(
+            project_phid=(project_phid)
+        )
+
+        if not target_project_phid:
+            raise ValueError(f"Could not find a milestone in {project_phid}")
+
+        return target_project_phid
+
+    @cached
+    def find_column_in_project(self, project_phid: str, column_name: str) -> str:
+        """Finds a column in a project.
+
+        :raises ValueError if the column isn't found"""
+        potential_target_columns = self.list_project_columns(project_phid=project_phid)
+
+        for col in potential_target_columns:
+            if col["fields"]["name"].lower() == column_name.lower():
+                column_phid = col["phid"]
+                break
+        else:
+            raise ValueError(
+                f"Column {column_name} not found in milestone {project_phid}"
+            )
+        return column_phid
+
+    @cached
+    def find_project_by_title(
+        self, title: str, parent_phid: Optional[str] = None
+    ) -> Optional[dict[str, Any]]:
+        params = {"constraints[query]": f'title:"{title}"'}
+        if parent_phid:
+            params["constraints[parents][0]"] = parent_phid
+        else:
+            params["constraints[maxDepth]"] = "0"  # search for top-level project
+        return self._first(
+            self._make_request("project.search", params=params)["result"]["data"]
+        )

{phable_cli-0.1.1 → phable_cli-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "phable-cli"
-version = "0.1.1"
+version = "0.1.3"
 description = "Manage Phabricator tasks from the comfort of your terminal"
 authors = ["Balthazar Rouberol <br@imap.cc>"]
 license = "MIT"