phable-cli 0.1.7__tar.gz → 0.1.9__tar.gz

{phable_cli-0.1.7 → phable_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: phable-cli
-Version: 0.1.7
+Version: 0.1.9
 Summary: Manage Phabricator tasks from the comfort of your terminal
 License: MIT
 Author: Balthazar Rouberol
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: click (>=8.1.8,<9.0.0)
+Requires-Dist: pytest (>=8.3.5,<9.0.0)
 Requires-Dist: requests (>=2.32.3,<3.0.0)
 Description-Content-Type: text/markdown
 
@@ -58,20 +59,45 @@ Commands:
 
 ## Setup
 
-For `phable` to work, you need to define the following environment variables:
+For `phable` to work, you need to define the follwoing configuration, by running `$EDITOR $(phable config show)`:
 
-- `PHABRICATOR_URL`: URL to your phabricator instance. Ex: `PHABRICATOR_URL=https://phabricator.wikimedia.org`
-- `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.
+```ini
+[phabricator]
+url = # URL to your phabricator instance. Ex: `url = https://phabricator.wikimedia.org`
+token = # API token. Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
+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.
+To get `default_project_phid`, define the first 2 configurations, and run the following command, where `T123456` is a task id belonging to your project.
 
 ```console
 $ phable show T123456 --format=json | jq -r '.attachments.projects.projectPHIDs[]'
 ```
 
+Note: you can also expose these confriguration through the following environment variables, for backwards compatibility:
+- `PHABRICATOR_URL`
+- `PHABRICATOR_TOKEN`
+- `PHABRICATOR_DEFAULT_PROJECT_PHID`
+
 ## Tips and tricks
 
+### Setting up aliases
+You can define command aliases. For example, instead of typing `phable move --column 'Done' --milestone T123456`, you might want to type `phable done T123456`. To do this, open the phable configuration file, with `$EDITOR $(phable config show)` and define an alias:
+
+```ini
+[aliases]
+done = move --column 'Done' --milestone
+```
+
+I personally currently have the following aliases:
+```console
+$ phable config aliases list
+done = move --column 'Done' --milestone
+review = move --column 'Needs Review' --milestone
+wip = move --column 'In Progress' --milestone
+```
+
+### Phabricator task IDs as clickable links in iTerm2
 If you're using iTerm2, you can turn the task IDs into clickable links, by going to iTerm2 > Settings > Profiles > Advanced > Smart Selection > Edit > [+]:
 - Title: Phabricator Task Id
 - Action: Open URL

{phable_cli-0.1.7 → phable_cli-0.1.9}/README.md

@@ -39,20 +39,45 @@ Commands:
 
 ## Setup
 
-For `phable` to work, you need to define the following environment variables:
+For `phable` to work, you need to define the follwoing configuration, by running `$EDITOR $(phable config show)`:
 
-- `PHABRICATOR_URL`: URL to your phabricator instance. Ex: `PHABRICATOR_URL=https://phabricator.wikimedia.org`
-- `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.
+```ini
+[phabricator]
+url = # URL to your phabricator instance. Ex: `url = https://phabricator.wikimedia.org`
+token = # API token. Generate a token from ${PHABRICATOR_URL}/settings/user/${YOUR_USERNAME}/page/apitokens/
+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.
+To get `default_project_phid`, define the first 2 configurations, and run the following command, where `T123456` is a task id belonging to your project.
 
 ```console
 $ phable show T123456 --format=json | jq -r '.attachments.projects.projectPHIDs[]'
 ```
 
+Note: you can also expose these confriguration through the following environment variables, for backwards compatibility:
+- `PHABRICATOR_URL`
+- `PHABRICATOR_TOKEN`
+- `PHABRICATOR_DEFAULT_PROJECT_PHID`
+
 ## Tips and tricks
 
+### Setting up aliases
+You can define command aliases. For example, instead of typing `phable move --column 'Done' --milestone T123456`, you might want to type `phable done T123456`. To do this, open the phable configuration file, with `$EDITOR $(phable config show)` and define an alias:
+
+```ini
+[aliases]
+done = move --column 'Done' --milestone
+```
+
+I personally currently have the following aliases:
+```console
+$ phable config aliases list
+done = move --column 'Done' --milestone
+review = move --column 'Needs Review' --milestone
+wip = move --column 'In Progress' --milestone
+```
+
+### Phabricator task IDs as clickable links in iTerm2
 If you're using iTerm2, you can turn the task IDs into clickable links, by going to iTerm2 > Settings > Profiles > Advanced > Smart Selection > Edit > [+]:
 - Title: Phabricator Task Id
 - Action: Open URL

{phable_cli-0.1.7/phable_cli → phable_cli-0.1.9/phable}/cache.py

@@ -2,23 +2,30 @@ import inspect
 import json
 import os
 import sys
+import tempfile
 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()}/.cache")),
-    "windows": Path("c:/", "Users", os.getlogin(), "AppData", "Local", "Temp"),
-}
+if not os.getenv("GITHUB_ACTIONS"):
+    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"),
+    }
+else:
+    CACHE_HOME_PER_PLATFORM = {}
 
 
 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"
+        cache_parent_dir = CACHE_HOME_PER_PLATFORM.get(sys.platform) or Path(
+            tempfile.mkdtemp()
+        )
+        self.cache_dir = cache_parent_dir / "phind"
         if not self.cache_dir.exists():
             self.cache_dir.mkdir()
         self.cache_filepath = self.cache_dir / "cache.json"

phable_cli-0.1.9/phable/cli/assign.py

@@ -0,0 +1,39 @@
+import click
+from typing import Optional
+
+from phable.phabricator import PhabricatorClient
+from phable.utils import Task
+from phable.cli.utils import VARIADIC
+
+
+@click.command(name="assign")
+@click.option(
+    "--username",
+    required=False,
+    help="The username to assign the task to. Self-assign the task if not provided.",
+)
+@click.argument("task-ids", type=Task.from_str, nargs=VARIADIC, required=True)
+@click.pass_context
+@click.pass_obj
+def assign_task(
+    client: PhabricatorClient,
+    ctx: click.Context,
+    task_ids: list[int],
+    username: Optional[str],
+):
+    """Assign one or multiple task ids to a username
+
+    \b
+    Examples:
+    $ phable assign T123456             # self assign task
+    $ phable assign T123456  brouberol  # asign to username
+
+    """
+    if not username:
+        user = client.current_user()
+    else:
+        user = client.find_user_by_username(username)
+        if not user:
+            ctx.fail(f"User {username} was not found")
+    for task_id in task_ids:
+        client.assign_task_to_user(task_id=task_id, user_phid=user["phid"])

phable_cli-0.1.9/phable/cli/cache.py

@@ -0,0 +1,22 @@
+import click
+import atexit
+
+from phable.cache import cache
+
+
+@click.group(name="cache")
+def _cache():
+    """Manage internal cache"""
+
+
+@_cache.command(name="show")
+def show_cache():
+    """Display the location of the internal phable cache"""
+    click.echo(cache.cache_filepath)
+
+
+@_cache.command()
+def clear():
+    """Delete the phable internal cache file"""
+    cache.cache_filepath.unlink(missing_ok=True)
+    atexit.unregister(cache.dump)  # avoid re-dumping the in-memory cache back to disk

phable_cli-0.1.9/phable/cli/comment.py

@@ -0,0 +1,26 @@
+import click
+from typing import Optional
+from phable.utils import Task, text_from_cli_arg_or_fs_or_editor
+from phable.phabricator import PhabricatorClient
+
+
+@click.command(name="comment")
+@click.option(
+    "--comment",
+    type=str,
+    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)
+@click.pass_obj
+def comment_on_task(client: PhabricatorClient, task_id: int, comment: Optional[str]):
+    """Add a comment to a task
+
+    \b
+    Example:
+    $ 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
+
+    """
+    comment = text_from_cli_arg_or_fs_or_editor(comment)
+    client.create_or_edit_task(task_id=task_id, params={"comment": comment})

phable_cli-0.1.9/phable/cli/config.py

@@ -0,0 +1,25 @@
+import click
+from phable.config import config
+
+
+@click.group(name="config")
+def _config():
+    """Manage phable config"""
+
+
+@_config.command(name="show")
+def show_config():
+    """Display the location of the phable config"""
+    click.echo(config.filepath)
+
+
+@_config.group
+def aliases():
+    """Manage aliases"""
+
+
+@aliases.command()
+def list():
+    """List configured aliases"""
+    for name, alias in config.data.get("aliases", {}).items():
+        click.echo(f"{name} = {alias}")

phable_cli-0.1.9/phable/cli/create.py

@@ -0,0 +1,149 @@
+import click
+import re
+from typing import Optional
+from pathlib import Path
+from phable.phabricator import PhabricatorClient
+from phable.utils import text_from_cli_arg_or_fs_or_editor, Task
+from phable.config import config
+from phable.cli.show import show_task
+
+
+@click.command(name="create")
+@click.option("--title", required=True, help="Title of the task")
+@click.option(
+    "--description",
+    help="Task description or path to a file containing the description body. If not provided, an editor will be opened.",
+)
+@click.option(
+    "--template",
+    type=Path,
+    help=(
+        "Task description template file. If provided, the --description flag will be ignored "
+        "and an editor will be opened, pre-filled with the template file content"
+    ),
+)
+@click.option(
+    "--priority",
+    type=click.Choice(["unbreaknow", "high", "normal", "low", "needs-triage"]),
+    help="Priority level of the task",
+    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("--cc", multiple=True, help="Subscribers to associate to the task")
+@click.option("--owner", help="The username of the task owner")
+@click.pass_context
+@click.pass_obj
+def create_task(
+    client: PhabricatorClient,
+    ctx: click.Context,
+    title: str,
+    description: Optional[str],
+    template: Path,
+    priority: str,
+    parent_id: Optional[str],
+    tags: list[str],
+    cc: 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 associated description template
+    $ phable create --title 'Do the thing!' --template ./template.md
+    \b
+    # Create a task with a given parent
+    $ phable create --title 'A subtask' --description 'Subtask description' --parent-id T123456
+    \b
+    # Create a task with an associated top-level project tag
+    $ phable create --title 'A task' --tags 'Data-Platform-SRE'
+    \b
+    # 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
+    \b
+    # Create a task with an associated subscriber
+    $ phable create --title 'A task' --cc brouberol
+
+    """
+    if template:
+        if template.exists():
+            description = template
+            force_editor = True
+        else:
+            ctx.fail(f"Template file {template} does not exist")
+    else:
+        force_editor = False
+    description = text_from_cli_arg_or_fs_or_editor(
+        description, force_editor=force_editor
+    )
+
+    task_params = {
+        "title": title,
+        "description": description,
+        "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
+    else:
+        task_params["projects.add"] = [config.phabricator_default_project_phid]
+
+    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.set"] = [parent["phid"]]
+
+    cc_phids = []
+    for username in cc:
+        if user := client.find_user_by_username(username=username):
+            cc_phids.append(user["phid"])
+        else:
+            ctx.fail(f"User {owner} not found")
+    if cc_phids:
+        task_params["subscribers.set"] = cc_phids
+
+    task = client.create_or_edit_task(task_params)
+    ctx.invoke(show_task, task_id=task["result"]["object"]["id"])

phable_cli-0.1.9/phable/cli/list.py

@@ -0,0 +1,81 @@
+import click
+from typing import Optional
+
+from phable.phabricator import PhabricatorClient
+from phable.config import config
+from phable.display import display_tasks
+
+
+@click.command(name="list")
+@click.option(
+    "--column",
+    "columns",
+    required=False,
+    help="The columns the tasks should be located in",
+    multiple=True,
+)
+@click.option(
+    "--owner",
+    required=False,
+    help="The username the tasks should be assigned to",
+)
+@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.option(
+    "--format",
+    required=False,
+    type=click.Choice(("html", "plain", "json", "markdown")),
+    default="plain",
+    help="The output format of the task list",
+)
+@click.pass_context
+@click.pass_obj
+def list_tasks(
+    client: PhabricatorClient,
+    ctx: click.Context,
+    columns: list[str],
+    owner: Optional[str] = None,
+    milestone: bool = False,
+    format: str = "plain",
+):
+    """Lists and filter tasks
+
+    \b
+    Examples:
+    # List all tasks in the default board
+    $ phable list
+    \b
+    # List all tasks in the default board latest milestone
+    $ phable list --milestone
+    \b
+    # List all tasks owner by brouberol in the Done column of the default board latest milestone
+    $ phable list --milestone --owner brouberol --column Done
+
+    """
+    if owner:
+        owner_user = client.find_user_by_username(owner)["phid"]
+        if not owner_user:
+            ctx.fail(f"User {owner} was not found")
+    else:
+        owner_user = None
+    project_phid = client.get_main_project_or_milestone(
+        project_phid=config.phabricator_default_project_phid, milestone=milestone
+    )
+    if columns:
+        column_phids = [
+            client.find_column_in_project(project_phid=project_phid, column_name=column)
+            for column in columns
+        ]
+    else:
+        column_phids = None
+    tasks = client.find_tasks(
+        column_phids=column_phids, owner_phid=owner_user, project_phid=project_phid
+    )
+    tasks = [client.enrich_task(task) for task in tasks]
+    display_tasks(tasks=tasks, format=format, separator="")

phable_cli-0.1.9/phable/cli/main.py

@@ -0,0 +1,97 @@
+import atexit
+
+import click
+from click import Context
+
+
+from phable.cache import cache
+from phable.config import config
+from phable.phabricator import PhabricatorClient
+from phable.cli.assign import assign_task
+from phable.cli.cache import _cache
+from phable.cli.comment import comment_on_task
+from phable.cli.config import _config
+from phable.cli.create import create_task
+from phable.cli.move import move_task
+from phable.cli.report import report_done_tasks
+from phable.cli.show import show_task
+from phable.cli.subscribe import subscribe_to_task
+from phable.cli.list import list_tasks
+
+
+class AliasedCommandGroup(click.Group):
+    """Custom CLI group allowing the replaement of aliases commands on the fly
+
+    For example if we have the following configuraion:
+    [aliases]
+    done = move --column 'Done' --milestone
+
+    then calling `phable done T123456` will actually call
+    `phable move --column Done --milestone T123456` under the hood.
+
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._aliases = config.data.get("aliases", {})
+
+    def make_context(self, info_name, args, parent=None, **extra):
+        # First, let's parse the command and handle aliases
+        parsed_args = self.parse_command(info_name, args)
+
+        # Then create the context with the possibly modified args
+        ctx = super().make_context(
+            info_name=parsed_args[0], args=parsed_args[1:], parent=parent, **extra
+        )
+        return ctx
+
+    def parse_command(self, ctx_name, args):
+        """Parse command line arguments and handle aliases"""
+        if not args:
+            return [ctx_name]
+
+        # Check if the first argument is an alias
+        if args[0] in self._aliases:
+            pattern = self._aliases[args[0]]
+            # Split the pattern and combine with remaining args
+            pattern_parts = click.parser.split_arg_string(pattern)
+            # Replace the alias with the pattern parts
+            args = pattern_parts + args[1:]
+
+        return [ctx_name] + args
+
+    def get_command(self, ctx, cmd_name):
+        """Override to handle aliases in command lookup"""
+        if cmd_name in self._aliases:
+            return super().get_command(ctx, self._aliases[cmd_name].split()[0])
+        return super().get_command(ctx, cmd_name)
+
+
+@click.group(cls=AliasedCommandGroup)
+@click.version_option(package_name="phable-cli")
+@click.pass_context
+def cli(ctx: Context):
+    """Manage Phabricator tasks from the comfort of your terminal"""
+    ctx.obj = PhabricatorClient(config.phabricator_url, config.phabricator_token)
+
+
+cli.add_command(assign_task)
+cli.add_command(_cache)
+cli.add_command(comment_on_task)
+cli.add_command(_config)
+cli.add_command(create_task)
+cli.add_command(move_task)
+cli.add_command(report_done_tasks)
+cli.add_command(show_task)
+cli.add_command(subscribe_to_task)
+cli.add_command(list_tasks)
+
+
+def runcli():
+    # Dump the in-memory cache to disk when existing the CLI
+    atexit.register(cache.dump)
+    cli(max_content_width=120)
+
+
+if __name__ == "__main__":
+    runcli()

phable_cli-0.1.9/phable/cli/move.py

@@ -0,0 +1,58 @@
+import click
+from typing import Optional
+from phable.config import config
+from phable.cli.utils import VARIADIC
+from phable.phabricator import PhabricatorClient
+from phable.utils import Task
+
+
+@click.command(name="move")
+@click.option(
+    "--column",
+    type=str,
+    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, required=True)
+@click.pass_context
+@click.pass_obj
+def move_task(
+    client: PhabricatorClient,
+    ctx: click.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
+    marked as 'Resolved' as well.
+
+    \b
+    Example:
+    $ phable move T123456 --column 'In Progress'
+    $ phable move T123456 T234567 --column 'Done'
+
+    """
+    try:
+        target_project_phid = client.get_main_project_or_milestone(
+            milestone, config.phabricator_default_project_phid
+        )
+        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() in ("in progress", "needs review"):
+                client.mark_task_as_in_progress(task_id)
+            if column.lower() == "done":
+                client.mark_task_as_resolved(task_id)
+    except ValueError as ve:
+        ctx.fail(ve)