Refactor: define CLI with click

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ default_install_hook_types:
 
 repos:
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v3.6.0
+    rev: v4.0.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]

compiler_admin/commands/info.py

@@ -1,17 +1,16 @@
-from compiler_admin import __version__ as version, RESULT_SUCCESS, RESULT_FAILURE
-from compiler_admin.services.google import CallGAMCommand, CallGYBCommand
+import click
 
+from compiler_admin import __version__ as version
+from compiler_admin.services.google import CallGAMCommand, CallGYBCommand
 
-def info(*args, **kwargs) -> int:
-    """Print information about this package and the GAM environment.
 
-    Returns:
-        A value indicating if the operation succeeded or failed.
+@click.command()
+def info():
     """
-    print(f"compiler-admin: {version}")
-
-    res = CallGAMCommand(("version",))
-    res += CallGAMCommand(("info", "domain"))
-    res += CallGYBCommand(("--version",))
+    Print information about the configured environment.
+    """
+    click.echo(f"compiler-admin, version {version}")
 
-    return RESULT_SUCCESS if res == RESULT_SUCCESS else RESULT_FAILURE
+    CallGAMCommand(("version",))
+    CallGAMCommand(("info", "domain"))
+    CallGYBCommand(("--version",))

compiler_admin/commands/init.py

@@ -1,10 +1,10 @@
-from argparse import Namespace
 import os
 from pathlib import Path
 from shutil import rmtree
 import subprocess
 
-from compiler_admin import RESULT_FAILURE, RESULT_SUCCESS
+import click
+
 from compiler_admin.services.google import USER_ARCHIVE, CallGAMCommand
 
 
@@ -22,48 +22,37 @@ def _clean_config_dir(config_dir: Path) -> None:
             rmtree(path)
 
 
-def init(args: Namespace, *extras) -> int:
-    """Initialize a new GAM project.
-
-    See https://github.com/taers232c/GAMADV-XTD3/wiki/How-to-Install-Advanced-GAM
-
-    Args:
-        username (str): The Compiler admin with which to initialize a new project.
-
-        gam (bool): If True, initialize a new GAM project.
+@click.command()
+@click.option("--gam", "init_gam", is_flag=True)
+@click.option("--gyb", "init_gyb", is_flag=True)
+@click.argument("username")
+def init(username: str, init_gam: bool = False, init_gyb: bool = False):
+    """Initialize a new GAM and/or GYB project.
 
-        gyb (bool): If True, initialize a new GYB project.
+    See:
 
-    Returns:
-        A value indicating if the operation succeeded or failed.
+    - https://github.com/taers232c/GAMADV-XTD3/wiki/How-to-Install-Advanced-GAM
+    - https://github.com/GAM-team/got-your-back/wiki
     """
-    if not hasattr(args, "username"):
-        raise ValueError("username is required")
-
-    admin_user = args.username
-    res = RESULT_SUCCESS
-
-    if getattr(args, "gam", False):
+    if init_gam:
         _clean_config_dir(GAM_CONFIG_PATH)
         # GAM is already installed via pyproject.toml
-        res += CallGAMCommand(("config", "drive_dir", str(GAM_CONFIG_PATH), "verify"))
-        res += CallGAMCommand(("create", "project"))
-        res += CallGAMCommand(("oauth", "create"))
-        res += CallGAMCommand(("user", admin_user, "check", "serviceaccount"))
+        CallGAMCommand(("config", "drive_dir", str(GAM_CONFIG_PATH), "verify"))
+        CallGAMCommand(("create", "project"))
+        CallGAMCommand(("oauth", "create"))
+        CallGAMCommand(("user", username, "check", "serviceaccount"))
 
-    if getattr(args, "gyb", False):
+    if init_gyb:
         _clean_config_dir(GYB_CONFIG_PATH)
         # download GYB installer to config directory
         gyb = GYB_CONFIG_PATH / "gyb-install.sh"
         with gyb.open("w+") as dest:
-            res += subprocess.call(("curl", "-s", "-S", "-L", "https://gyb-shortn.jaylee.us/gyb-install"), stdout=dest)
+            subprocess.call(("curl", "-s", "-S", "-L", "https://gyb-shortn.jaylee.us/gyb-install"), stdout=dest)
 
-        res += subprocess.call(("chmod", "+x", str(gyb.absolute())))
+        subprocess.call(("chmod", "+x", str(gyb.absolute())))
 
         # install, giving values to some options
         # https://github.com/GAM-team/got-your-back/blob/main/install-gyb.sh
         #
         # use GYB_CONFIG_PATH.parent for the install directory option, otherwise we get a .config/gyb/gyb directory structure
-        res += subprocess.call((gyb, "-u", admin_user, "-r", USER_ARCHIVE, "-d", str(GYB_CONFIG_PATH.parent)))
-
-    return RESULT_SUCCESS if res == RESULT_SUCCESS else RESULT_FAILURE
+        subprocess.call((gyb, "-u", username, "-r", USER_ARCHIVE, "-d", str(GYB_CONFIG_PATH.parent)))

compiler_admin/commands/time/__init__.py

@@ -1,16 +1,16 @@
-from argparse import Namespace
+import click
 
-from compiler_admin.commands.time.convert import convert  # noqa: F401
-from compiler_admin.commands.time.download import download  # noqa: F401
+from compiler_admin.commands.time.convert import convert
+from compiler_admin.commands.time.download import download
 
 
-def time(args: Namespace, *extra):
-    # try to call the subcommand function directly from global (module) symbols
-    # if the subcommand function was imported above, it should exist in globals()
-    global_env = globals()
+@click.group
+def time():
+    """
+    Work with Compiler time entries.
+    """
+    pass
 
-    if args.subcommand in global_env:
-        cmd_func = global_env[args.subcommand]
-        cmd_func(args, *extra)
-    else:
-        raise NotImplementedError(f"Unknown time subcommand: {args.subcommand}")
+
+time.add_command(convert)
+time.add_command(download)

compiler_admin/commands/time/convert.py

@@ -1,6 +1,9 @@
-from argparse import Namespace
+import os
+import sys
+from typing import TextIO
+
+import click
 
-from compiler_admin import RESULT_SUCCESS
 from compiler_admin.services.harvest import CONVERTERS as HARVEST_CONVERTERS
 from compiler_admin.services.toggl import CONVERTERS as TOGGL_CONVERTERS
 
@@ -21,9 +24,46 @@ def _get_source_converter(from_fmt: str, to_fmt: str):
         )
 
 
-def convert(args: Namespace, *extras):
-    converter = _get_source_converter(args.from_fmt, args.to_fmt)
+@click.command()
+@click.option(
+    "--input",
+    default=os.environ.get("TOGGL_DATA", sys.stdin),
+    help="The path to the source data for conversion. Defaults to $TOGGL_DATA or stdin.",
+)
+@click.option(
+    "--output",
+    default=os.environ.get("HARVEST_DATA", sys.stdout),
+    help="The path to the file where converted data should be written. Defaults to $HARVEST_DATA or stdout.",
+)
+@click.option(
+    "--from",
+    "from_fmt",
+    default="toggl",
+    help="The format of the source data.",
+    show_default=True,
+    type=click.Choice(sorted(CONVERTERS.keys()), case_sensitive=False),
+)
+@click.option(
+    "--to",
+    "to_fmt",
+    default="harvest",
+    help="The format of the converted data.",
+    show_default=True,
+    type=click.Choice(sorted([to_fmt for sub in CONVERTERS.values() for to_fmt in sub.keys()]), case_sensitive=False),
+)
+@click.option("--client", help="The name of the client to use in converted data.")
+def convert(
+    input: str | TextIO = os.environ.get("TOGGL_DATA", sys.stdin),
+    output: str | TextIO = os.environ.get("HARVEST_DATA", sys.stdout),
+    from_fmt="toggl",
+    to_fmt="harvest",
+    client="",
+):
+    """
+    Convert a time report from one format into another.
+    """
+    converter = _get_source_converter(from_fmt, to_fmt)
 
-    converter(source_path=args.input, output_path=args.output, client_name=args.client)
+    click.echo(f"Converting data from format: {from_fmt} to format: {to_fmt}")
 
-    return RESULT_SUCCESS
+    converter(source_path=input, output_path=output, client_name=client)

compiler_admin/commands/time/download.py

@@ -1,23 +1,125 @@
-from argparse import Namespace
+from datetime import datetime, timedelta
+import os
+from typing import List
+
+import click
+from pytz import timezone
 
-from compiler_admin import RESULT_SUCCESS
 from compiler_admin.services.toggl import TOGGL_COLUMNS, download_time_entries
 
 
-def download(args: Namespace, *extras):
-    params = dict(
-        start_date=args.start, end_date=args.end, output_path=args.output, output_cols=TOGGL_COLUMNS, billable=args.billable
-    )
+TZINFO = timezone(os.environ.get("TZ_NAME", "America/Los_Angeles"))
 
-    if args.client_ids:
-        params.update(dict(client_ids=args.client_ids))
-    if args.project_ids:
-        params.update(dict(project_ids=args.project_ids))
-    if args.task_ids:
-        params.update(dict(task_ids=args.task_ids))
-    if args.user_ids:
-        params.update(dict(user_ids=args.user_ids))
 
-    download_time_entries(**params)
+def local_now():
+    return datetime.now(tz=TZINFO)
+
+
+def prior_month_end():
+    now = local_now()
+    first = now.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+    return first - timedelta(days=1)
+
+
+def prior_month_start():
+    end = prior_month_end()
+    return end.replace(day=1)
 
-    return RESULT_SUCCESS
+
+@click.command()
+@click.option(
+    "--start",
+    metavar="YYYY-MM-DD",
+    default=prior_month_start(),
+    callback=lambda ctx, param, val: datetime.strptime(val, "%Y-%m-%d %H:%M:%S%z"),
+    help="The start date of the reporting period. Defaults to the beginning of the prior month.",
+)
+@click.option(
+    "--end",
+    metavar="YYYY-MM-DD",
+    default=prior_month_end(),
+    callback=lambda ctx, param, val: datetime.strptime(val, "%Y-%m-%d %H:%M:%S%z"),
+    help="The end date of the reporting period. Defaults to the end of the prior month.",
+)
+@click.option(
+    "--output",
+    help="The path to the file where downloaded data should be written. Defaults to a path calculated from the date range.",
+)
+@click.option(
+    "--all",
+    "billable",
+    is_flag=True,
+    default=True,
+    help="Download all time entries. The default is to download only billable time entries.",
+)
+@click.option(
+    "-c",
+    "--client",
+    "client_ids",
+    envvar="TOGGL_CLIENT_ID",
+    help="An ID for a Toggl Client to filter for in reports. Can be supplied more than once.",
+    metavar="CLIENT_ID",
+    multiple=True,
+    type=int,
+)
+@click.option(
+    "-p",
+    "--project",
+    "project_ids",
+    help="An ID for a Toggl Project to filter for in reports. Can be supplied more than once.",
+    metavar="PROJECT_ID",
+    multiple=True,
+    type=int,
+)
+@click.option(
+    "-t",
+    "--task",
+    "task_ids",
+    help="An ID for a Toggl Project Task to filter for in reports. Can be supplied more than once.",
+    metavar="TASK_ID",
+    multiple=True,
+    type=int,
+)
+@click.option(
+    "-u",
+    "--user",
+    "user_ids",
+    help="An ID for a Toggl User to filter for in reports. Can be supplied more than once.",
+    metavar="USER_ID",
+    multiple=True,
+    type=int,
+)
+def download(
+    start: datetime,
+    end: datetime,
+    output: str = "",
+    billable: bool = True,
+    client_ids: List[int] = [],
+    project_ids: List[int] = [],
+    task_ids: List[int] = [],
+    user_ids: List[int] = [],
+):
+    """
+    Download a Toggl time report in CSV format.
+    """
+    if not output:
+        output = f"Toggl_time_entries_{start.strftime('%Y-%m-%d')}_{end.strftime('%Y-%m-%d')}.csv"
+
+    params = dict(start_date=start, end_date=end, output_path=output, output_cols=TOGGL_COLUMNS)
+
+    if billable:
+        params.update(dict(billable=billable))
+    if client_ids:
+        params.update(dict(client_ids=client_ids))
+    if project_ids:
+        params.update(dict(project_ids=project_ids))
+    if task_ids:
+        params.update(dict(task_ids=task_ids))
+    if user_ids:
+        params.update(dict(user_ids=user_ids))
+
+    click.echo("Downloading Toggl time entries with parameters:")
+    for k, v in params.items():
+        click.echo(f"  {k}: {v}")
+
+    download_time_entries(**params)

compiler_admin/commands/user/__init__.py

@@ -1,22 +1,28 @@
-from argparse import Namespace
+import click
 
-from compiler_admin.commands.user.alumni import alumni  # noqa: F401
-from compiler_admin.commands.user.create import create  # noqa: F401
-from compiler_admin.commands.user.convert import convert  # noqa: F401
-from compiler_admin.commands.user.delete import delete  # noqa: F401
-from compiler_admin.commands.user.offboard import offboard  # noqa: F401
-from compiler_admin.commands.user.reset import reset  # noqa: F401
-from compiler_admin.commands.user.restore import restore  # noqa: F401
-from compiler_admin.commands.user.signout import signout  # noqa: F401
+from compiler_admin.commands.user.alumni import alumni
+from compiler_admin.commands.user.convert import convert
+from compiler_admin.commands.user.create import create
+from compiler_admin.commands.user.delete import delete
+from compiler_admin.commands.user.offboard import offboard
+from compiler_admin.commands.user.reset import reset
+from compiler_admin.commands.user.restore import restore
+from compiler_admin.commands.user.signout import signout
 
 
-def user(args: Namespace, *extra):
-    # try to call the subcommand function directly from global (module) symbols
-    # if the subcommand function was imported above, it should exist in globals()
-    global_env = globals()
+@click.group
+def user():
+    """
+    Work with users in the Compiler org.
+    """
+    pass
 
-    if args.subcommand in global_env:
-        cmd_func = global_env[args.subcommand]
-        cmd_func(args, *extra)
-    else:
-        raise NotImplementedError(f"Unknown user subcommand: {args.subcommand}")
+
+user.add_command(alumni)
+user.add_command(convert)
+user.add_command(create)
+user.add_command(delete)
+user.add_command(offboard)
+user.add_command(reset)
+user.add_command(restore)
+user.add_command(signout)