otf-api 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

otf_api/cli/__init__.py

@@ -0,0 +1,4 @@
+from otf_api.cli.app import base_app
+from otf_api.cli.bookings import bookings_app, classes_app
+
+__all__ = ["base_app", "bookings_app", "classes_app"]

otf_api/cli/_utilities.py

@@ -0,0 +1,60 @@
+import functools
+import inspect
+import traceback
+from collections.abc import Awaitable, Callable
+from typing import Any, NoReturn, ParamSpec, TypeGuard, TypeVar
+
+import typer
+from click.exceptions import ClickException
+
+T = TypeVar("T")
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def is_async_fn(func: Callable[P, R] | Callable[P, Awaitable[R]]) -> TypeGuard[Callable[P, Awaitable[R]]]:
+    """
+    Returns `True` if a function returns a coroutine.
+
+    See https://github.com/microsoft/pyright/issues/2142 for an example use
+    """
+    while hasattr(func, "__wrapped__"):
+        func = func.__wrapped__
+
+    return inspect.iscoroutinefunction(func)
+
+
+def exit_with_error(message: Any, code: int = 1, **kwargs: Any) -> NoReturn:
+    """
+    Utility to print a stylized error message and exit with a non-zero code
+    """
+    from otf_api.cli.app import base_app
+
+    kwargs.setdefault("style", "red")
+    base_app.console.print(message, **kwargs)
+    raise typer.Exit(code)
+
+
+def exit_with_success(message: Any, **kwargs: Any) -> NoReturn:
+    """
+    Utility to print a stylized success message and exit with a zero code
+    """
+    from otf_api.cli.app import base_app
+
+    kwargs.setdefault("style", "green")
+    base_app.console.print(message, **kwargs)
+    raise typer.Exit(0)
+
+
+def with_cli_exception_handling(fn: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any | None:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort, ClickException):
+            raise  # Do not capture click or typer exceptions
+        except Exception:
+            traceback.print_exc()
+            exit_with_error("An exception occurred.")
+
+    return wrapper

otf_api/cli/app.py

@@ -0,0 +1,177 @@
+import asyncio
+import functools
+import sys
+import typing
+from collections.abc import Callable
+from enum import Enum
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.theme import Theme
+
+import otf_api
+from otf_api.cli._utilities import is_async_fn, with_cli_exception_handling
+from otf_api.models.auth import User
+
+if typing.TYPE_CHECKING:
+    from otf_api.api import Api
+
+
+class OutputType(str, Enum):
+    json = "json"
+    table = "table"
+    interactive = "interactive"
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        print(otf_api.__version__)
+        raise typer.Exit()
+
+
+OPT_USERNAME: str = typer.Option(None, envvar=["OTF_EMAIL", "OTF_USERNAME"], help="Username for the OTF API")
+OPT_PASSWORD: str = typer.Option(envvar="OTF_PASSWORD", help="Password for the OTF API", hide_input=True)
+OPT_OUTPUT: OutputType = typer.Option(None, envvar="OTF_OUTPUT", show_default=False, help="Output format")
+OPT_LOG_LEVEL: str = typer.Option("CRITICAL", help="Log level", envvar="OTF_LOG_LEVEL")
+OPT_VERSION: bool = typer.Option(
+    None, "--version", callback=version_callback, help="Display the current version.", is_eager=True
+)
+
+
+def register_main_callback(app: "AsyncTyper") -> None:
+    @app.callback()  # type: ignore
+    @with_cli_exception_handling
+    def main_callback(
+        ctx: typer.Context,  # noqa
+        version: bool = OPT_VERSION,  # noqa
+        username: str = OPT_USERNAME,
+        password: str = OPT_PASSWORD,
+        output: OutputType = OPT_OUTPUT,
+        log_level: str = OPT_LOG_LEVEL,
+    ) -> None:
+        app.setup_console()
+        app.set_username(username)
+        app.password = password
+        app.output = output or OutputType.table
+        app.set_log_level(log_level)
+
+        # When running on Windows we need to ensure that the correct event loop policy is
+        # in place or we will not be able to spawn subprocesses. Sometimes this policy is
+        # changed by other libraries, but here in our CLI we should have ownership of the
+        # process and be able to safely force it to be the correct policy.
+        # https://github.com/PrefectHQ/prefect/issues/8206
+        if sys.platform == "win32":
+            asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
+
+
+class AsyncTyper(typer.Typer):
+    """
+    Wraps commands created by `Typer` to support async functions and handle errors.
+    """
+
+    console: Console
+
+    def __init__(self, *args: typing.Any, **kwargs: typing.Any):
+        super().__init__(*args, **kwargs)
+
+        theme = Theme({"prompt.choices": "bold blue"})
+        self.console = Console(highlight=False, theme=theme, color_system="auto")
+
+        # TODO: clean these up later, just don't want warnings everywhere that these could be None
+        self.api: Api = None  # type: ignore
+        self.username: str = None  # type: ignore
+        self.password: str = None  # type: ignore
+        self.output: OutputType = None  # type: ignore
+        self.logger = logger
+        self.log_level = "CRITICAL"
+
+    def set_username(self, username: str | None = None) -> None:
+        if username:
+            self.username = username
+            return
+
+        if User.cache_file_exists():
+            self.username = User.username_from_disk()
+            return
+
+        raise ValueError("Username not provided and not found in cache")
+
+    def set_log_level(self, level: str) -> None:
+        self.log_level = level
+        logger.remove()
+        logger.add(sys.stderr, level=self.log_level.upper())
+
+    def print(self, *args: typing.Any, **kwargs: typing.Any) -> None:
+        if self.output == "json":
+            self.console.print_json(*args, **kwargs)
+        else:
+            self.console.print(*args, **kwargs)
+
+    def add_typer(
+        self, typer_instance: "AsyncTyper", *args: typing.Any, aliases: list[str] | None = None, **kwargs: typing.Any
+    ) -> typing.Any:
+        aliases = aliases or []
+        for alias in aliases:
+            super().add_typer(typer_instance, *args, name=alias, no_args_is_help=True, hidden=True, **kwargs)
+
+        return super().add_typer(typer_instance, *args, no_args_is_help=True, **kwargs)
+
+    def command(
+        self, name: str | None = None, *args: typing.Any, aliases: list[str] | None = None, **kwargs: typing.Any
+    ) -> Callable[[typing.Any], typing.Any]:
+        """
+        Create a new command. If aliases are provided, the same command function
+        will be registered with multiple names.
+        """
+
+        aliases = aliases or []
+
+        def wrapper(fn: Callable[[typing.Any], typing.Any]) -> Callable[[typing.Any], typing.Any]:
+            # click doesn't support async functions, so we wrap them in
+            # asyncio.run(). This has the advantage of keeping the function in
+            # the main thread, which means signal handling works for e.g. the
+            # server and workers. However, it means that async CLI commands can
+            # not directly call other async CLI commands (because asyncio.run()
+            # can not be called nested). In that (rare) circumstance, refactor
+            # the CLI command so its business logic can be invoked separately
+            # from its entrypoint.
+            if is_async_fn(fn):
+                _fn = fn
+
+                @functools.wraps(fn)
+                def fn(*args: typing.Any, **kwargs: typing.Any) -> typing.Any:
+                    return asyncio.run(_fn(*args, **kwargs))  # type: ignore
+
+                fn.aio = _fn  # type: ignore
+
+            fn = with_cli_exception_handling(fn)
+
+            # register fn with its original name
+            command_decorator = super(AsyncTyper, self).command(name=name, *args, **kwargs)
+            original_command = command_decorator(fn)
+
+            # register fn for each alias, e.g. @marvin_app.command(aliases=["r"])
+            for alias in aliases:
+                super(AsyncTyper, self).command(
+                    name=alias,
+                    *args,
+                    **{k: v for k, v in kwargs.items() if k != "aliases"},
+                )(fn)
+
+            return typing.cast(Callable[[typing.Any], typing.Any], original_command)
+
+        return wrapper
+
+    def setup_console(self, soft_wrap: bool = True, prompt: bool = True) -> None:
+        self.console = Console(
+            highlight=False,
+            color_system="auto",
+            theme=Theme({"prompt.choices": "bold blue"}),
+            soft_wrap=not soft_wrap,
+            force_interactive=prompt,
+        )
+
+
+base_app = AsyncTyper(add_completion=True, no_args_is_help=True)
+register_main_callback(base_app)

otf_api/cli/bookings.py

@@ -0,0 +1,231 @@
+from enum import Enum
+
+import pendulum
+import typer
+from loguru import logger
+
+import otf_api
+from otf_api.cli.app import OPT_OUTPUT, AsyncTyper, OutputType, base_app
+from otf_api.cli.prompts import prompt_select_from_table
+from otf_api.models.responses.bookings import BookingStatus
+from otf_api.models.responses.classes import ClassType, ClassTypeCli, DoW
+
+flipped_status = {item.value: item.name for item in BookingStatus}
+FlippedEnum = Enum("CliBookingStatus", flipped_status)  # type: ignore
+
+
+bookings_app = AsyncTyper(name="bookings", help="Get bookings data")
+classes_app = AsyncTyper(name="classes", help="Get classes data")
+base_app.add_typer(bookings_app, aliases=["booking"])
+base_app.add_typer(classes_app, aliases=["class"])
+
+
+def today() -> str:
+    val: str = pendulum.yesterday().date().to_date_string()
+    return val
+
+
+def next_month() -> str:
+    val: str = pendulum.now().add(months=1).date().to_date_string()
+    return val
+
+
+@bookings_app.command(name="list")
+async def list_bookings(
+    start_date: str = typer.Option(default_factory=today, help="Start date for bookings"),
+    end_date: str = typer.Option(default_factory=next_month, help="End date for bookings"),
+    status: FlippedEnum = typer.Option(None, case_sensitive=False, help="Booking status"),
+    limit: int = typer.Option(None, help="Limit the number of bookings returned"),
+    exclude_cancelled: bool = typer.Option(
+        True, "--exclude-cancelled/--include-cancelled", help="Exclude cancelled bookings", show_default=True
+    ),
+    exclude_none: bool = typer.Option(
+        True, "--exclude-none/--allow-none", help="Exclude fields with a value of None", show_default=True
+    ),
+    output: OutputType = OPT_OUTPUT,
+) -> None:
+    """
+    List bookings data
+    """
+
+    logger.info("Listing bookings data")
+
+    if output:
+        base_app.output = output
+
+    bk_status = BookingStatus.get_from_key_insensitive(status.value) if status else None
+
+    if not base_app.api:
+        base_app.api = await otf_api.Api.create(base_app.username, base_app.password)
+    bookings = await base_app.api.get_bookings(start_date, end_date, bk_status, limit, exclude_cancelled)
+
+    if base_app.output == "json":
+        base_app.print(bookings.to_json(exclude_none=exclude_none))
+    elif base_app.output == "table":
+        base_app.print(bookings.to_table())
+    elif base_app.output == "interactive":
+        result = prompt_select_from_table(
+            console=base_app.console,
+            prompt="Select a booking",
+            columns=bookings.show_bookings_columns(),
+            data=bookings.bookings,
+        )
+        print(result)
+
+
+@bookings_app.command()
+async def book(class_uuid: str = typer.Option(help="Class UUID to cancel")) -> None:
+    """
+    Book a class
+    """
+
+    logger.info(f"Booking class {class_uuid}")
+
+    if not base_app.api:
+        base_app.api = await otf_api.Api.create(base_app.username, base_app.password)
+    booking = await base_app.api.book_class(class_uuid)
+
+    base_app.console.print(booking)
+
+
+@bookings_app.command()
+async def book_interactive(
+    studio_uuids: list[str] = typer.Option(None, help="Studio UUIDs to get classes for"),
+    include_home_studio: bool = typer.Option(True, help="Include the home studio in the classes"),
+    start_date: str = typer.Option(default_factory=today, help="Start date for classes"),
+    end_date: str = typer.Option(None, help="End date for classes"),
+    limit: int = typer.Option(None, help="Limit the number of classes returned"),
+    class_type: list[ClassTypeCli] = typer.Option(None, help="Class type to filter by"),
+    day_of_week: list[DoW] = typer.Option(None, help="Days of the week to filter by"),
+    exclude_cancelled: bool = typer.Option(
+        True, "--exclude-cancelled/--allow-cancelled", help="Exclude cancelled classes", show_default=True
+    ),
+    start_time: list[str] = typer.Option(None, help="Start time for classes"),
+) -> None:
+    """
+    Book a class interactively
+    """
+
+    logger.info("Booking class interactively")
+
+    with base_app.console.status("Getting classes...", spinner="arc"):
+        if class_type:
+            class_type_enums = [ClassType.get_from_key_insensitive(class_type.value) for class_type in class_type]
+        else:
+            class_type_enums = None
+
+        if not base_app.api:
+            base_app.api = await otf_api.Api.create(base_app.username, base_app.password)
+
+        classes = await base_app.api.get_classes(
+            studio_uuids,
+            include_home_studio,
+            start_date,
+            end_date,
+            limit,
+            class_type_enums,
+            exclude_cancelled,
+            day_of_week,
+            start_time,
+        )
+
+    result = prompt_select_from_table(
+        console=base_app.console,
+        prompt="Book a class, any class",
+        columns=classes.book_class_columns(),
+        data=classes.classes,
+    )
+
+    print(result["ot_class_uuid"])
+    booking = await base_app.api.book_class(result["ot_class_uuid"])
+
+    base_app.console.print(booking)
+
+
+@bookings_app.command()
+async def cancel_interactive() -> None:
+    """
+    Cancel a booking interactively
+    """
+
+    logger.info("Cancelling booking interactively")
+
+    with base_app.console.status("Getting bookings...", spinner="arc"):
+        if not base_app.api:
+            base_app.api = await otf_api.Api.create(base_app.username, base_app.password)
+        bookings = await base_app.api.get_bookings()
+
+    result = prompt_select_from_table(
+        console=base_app.console,
+        prompt="Cancel a booking, any booking",
+        columns=bookings.show_bookings_columns(),
+        data=bookings.bookings,
+    )
+
+    print(result["class_booking_uuid"])
+    booking = await base_app.api.cancel_booking(result["class_booking_uuid"])
+
+    base_app.console.print(booking)
+
+
+@bookings_app.command()
+async def cancel(booking_uuid: str = typer.Option(help="Booking UUID to cancel")) -> None:
+    """
+    Cancel a booking
+    """
+
+    logger.info(f"Cancelling booking {booking_uuid}")
+
+    if not base_app.api:
+        base_app.api = await otf_api.Api.create(base_app.username, base_app.password)
+    booking = await base_app.api.cancel_booking(booking_uuid)
+
+    base_app.console.print(booking)
+
+
+@classes_app.command(name="list")
+async def list_classes(
+    studio_uuids: list[str] = typer.Option(None, help="Studio UUIDs to get classes for"),
+    include_home_studio: bool = typer.Option(True, help="Include the home studio in the classes"),
+    start_date: str = typer.Option(default_factory=today, help="Start date for classes"),
+    end_date: str = typer.Option(default_factory=next_month, help="End date for classes"),
+    limit: int = typer.Option(None, help="Limit the number of classes returned"),
+    class_type: ClassTypeCli = typer.Option(None, help="Class type to filter by"),
+    exclude_cancelled: bool = typer.Option(
+        True, "--exclude-cancelled/--allow-cancelled", help="Exclude cancelled classes", show_default=True
+    ),
+    exclude_none: bool = typer.Option(
+        True, "--exclude-none/--allow-none", help="Exclude fields with a value of None", show_default=True
+    ),
+    output: OutputType = OPT_OUTPUT,
+) -> None:
+    """
+    List classes data
+    """
+
+    logger.info("Listing classes")
+
+    if output:
+        base_app.output = output
+
+    class_type_enum = ClassType.get_from_key_insensitive(class_type.value) if class_type else None
+
+    if not base_app.api:
+        base_app.api = await otf_api.Api.create(base_app.username, base_app.password)
+    classes = await base_app.api.get_classes(
+        studio_uuids, include_home_studio, start_date, end_date, limit, class_type_enum, exclude_cancelled
+    )
+
+    if base_app.output == "json":
+        base_app.print(classes.to_json(exclude_none=exclude_none))
+    elif base_app.output == "table":
+        base_app.print(classes.to_table())
+    else:
+        result = prompt_select_from_table(
+            console=base_app.console,
+            prompt="Book a class, any class",
+            columns=classes.book_class_columns(),
+            data=classes.classes,
+        )
+        print(type(result))
+        print(result)

otf_api/cli/prompts.py

@@ -0,0 +1,162 @@
+import os
+import typing
+
+import readchar
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
+
+from otf_api.cli._utilities import exit_with_error
+from otf_api.models.base import T
+
+if typing.TYPE_CHECKING:
+    from rich.console import Console
+
+
+def prompt(message, **kwargs):
+    """Utility to prompt the user for input with consistent styling"""
+    return Prompt.ask(f"[bold][green]?[/] {message}[/]", **kwargs)
+
+
+def confirm(message, **kwargs):
+    """Utility to prompt the user for confirmation with consistent styling"""
+    return Confirm.ask(f"[bold][green]?[/] {message}[/]", **kwargs)
+
+
+def prompt_select_from_table(
+    console: "Console",
+    prompt: str,
+    columns: list[str],
+    data: list[T],
+    table_kwargs: dict | None = None,
+) -> dict:
+    """
+    Given a list of columns and some data, display options to user in a table
+    and prompt them to select one.
+
+    Args:
+        prompt: A prompt to display to the user before the table.
+        columns: A list of strings that represent the attributes of the data to display.
+        data: A list of dicts with keys corresponding to the `key` values in
+            the `columns` argument.
+        table_kwargs: Additional kwargs to pass to the `rich.Table` constructor.
+    Returns:
+        dict: Data representation of the selected row
+    """
+    current_idx = 0
+    selected_row = None
+    table_kwargs = table_kwargs or {}
+    layout = Layout()
+
+    if not data:
+        exit_with_error("No data to display")
+
+    MODEL_TYPE = type(data[0])
+
+    TABLE_PANEL = Layout(name="left")
+    DATA_PANEL = Layout(name="right")
+
+    layout.split_row(TABLE_PANEL, DATA_PANEL)
+
+    TABLE_PANEL.ratio = 7
+    DATA_PANEL.ratio = 3
+    DATA_PANEL.minimum_size = 50
+
+    n_rows = os.get_terminal_size()[1] - 5
+
+    def build_table() -> Layout:
+        """
+        Generate a table of options. The `current_idx` will be highlighted.
+        """
+
+        table = initialize_table()
+        rows = data.copy()
+        rows, offset = paginate_rows(rows)
+        selected_item = add_rows_to_table(table, rows, offset)
+
+        finalize_table(table, prompt, selected_item)
+
+        return layout
+
+    def initialize_table() -> Table:
+        table_kwargs.setdefault("expand", True)
+        table = Table(**table_kwargs)
+        table.add_column()
+        for column in columns:
+            table.add_column(MODEL_TYPE.attr_to_column_header(column))
+        return table
+
+    def paginate_rows(rows: list[T]) -> tuple[list[T], int]:
+        if len(rows) > n_rows:
+            start = max(0, current_idx - n_rows + 1)
+            end = min(len(rows), start + n_rows)
+            rows = rows[start:end]
+            offset = start
+        else:
+            offset = 0
+        return rows, offset
+
+    def add_rows_to_table(table: Table, rows: list[T], offset: int) -> T:
+        selected_item: T = None
+        for i, item in enumerate(rows):
+            idx_with_offset = i + offset
+            is_selected_row = idx_with_offset == current_idx
+            if is_selected_row:
+                selected_item = item
+            table.add_row(*item.to_row(columns, is_selected_row))
+        return selected_item
+
+    def finalize_table(table: Table, prompt: str, selected_item: T) -> None:
+        if table.row_count < n_rows:
+            for _ in range(n_rows - table.row_count):
+                table.add_row()
+
+        TABLE_PANEL.update(Panel(table, title=prompt))
+        DATA_PANEL.update(Panel("", title="Selected Data"))
+        if not selected_item:
+            DATA_PANEL.visible = False
+        elif selected_item.sidebar_data is not None:
+            sidebar_data = selected_item.sidebar_data
+            DATA_PANEL.update(sidebar_data)
+            DATA_PANEL.visible = True
+
+    with Live(build_table(), console=console, transient=True) as live:
+        instructions_message = f"[bold][green]?[/] {prompt} [bright_blue][Use arrows to move; enter to select]"
+        live.console.print(instructions_message)
+        while selected_row is None:
+            key = readchar.readkey()
+
+            start_val = 0
+            offset = 0
+
+            match key:
+                case readchar.key.UP:
+                    offset = -1
+                    start_val = len(data) - 1 if current_idx < 0 else current_idx
+                case readchar.key.PAGE_UP:
+                    offset = -5
+                    start_val = len(data) - 1 if current_idx < 0 else current_idx
+                case readchar.key.DOWN:
+                    offset = 1
+                    start_val = 0 if current_idx >= len(data) else current_idx
+                case readchar.key.PAGE_DOWN:
+                    offset = 5
+                    start_val = 0 if current_idx >= len(data) else current_idx
+                case readchar.key.CTRL_C:
+                    # gracefully exit with no message
+                    exit_with_error("")
+                case readchar.key.ENTER | readchar.key.CR:
+                    selected_row = data[current_idx]
+
+            current_idx = start_val + offset
+
+            if current_idx < 0:
+                current_idx = len(data) - 1
+            elif current_idx >= len(data):
+                current_idx = 0
+
+            live.update(build_table(), refresh=True)
+
+        return selected_row

otf_api/models/__init__.py

@@ -1,10 +1,9 @@
 from .auth import User
 from .responses import (
-    ALL_CLASS_STATUS,
-    ALL_HISTORY_CLASS_STATUS,
-    ALL_STUDIO_STATUS,
+    BookClass,
     BookingList,
     BookingStatus,
+    CancelBooking,
     ChallengeTrackerContent,
     ChallengeTrackerDetailList,
     ChallengeType,
@@ -22,7 +21,6 @@ from .responses import (
     StudioDetail,
     StudioDetailList,
     StudioServiceList,
-    StudioStatus,
     Telemetry,
     TelemetryHrHistory,
     TelemetryMaxHr,
@@ -36,7 +34,6 @@ __all__ = [
     "BookingStatus",
     "EquipmentType",
     "HistoryClassStatus",
-    "StudioStatus",
     "BookingList",
     "ChallengeTrackerContent",
     "ChallengeTrackerDetailList",
@@ -55,9 +52,8 @@ __all__ = [
     "TelemetryMaxHr",
     "StudioDetail",
     "StudioDetailList",
-    "ALL_CLASS_STATUS",
-    "ALL_HISTORY_CLASS_STATUS",
-    "ALL_STUDIO_STATUS",
     "PerformanceSummaryDetail",
     "PerformanceSummaryList",
+    "BookClass",
+    "CancelBooking",
 ]