canvas 0.1.4__tar.gz → 0.1.6__tar.gz

canvas-0.1.6/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.1
+Name: canvas
+Version: 0.1.6
+Summary: SDK to customize event-driven actions in your Canvas instance
+License: MIT
+Author: Canvas Team
+Author-email: engineering@canvasmedical.com
+Requires-Python: >=3.11,<3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: cookiecutter
+Requires-Dist: grpcio (>=1.60.1,<2.0.0)
+Requires-Dist: ipython (>=8.21.0,<9.0.0)
+Requires-Dist: jsonschema (>=4.21.1,<5.0.0)
+Requires-Dist: keyring
+Requires-Dist: pydantic (>=2.6.1,<3.0.0)
+Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
+Requires-Dist: redis (>=5.0.4,<6.0.0)
+Requires-Dist: requests
+Requires-Dist: restrictedpython (>=7.1,<8.0)
+Requires-Dist: statsd (>=4.0.1,<5.0.0)
+Requires-Dist: typer[all]
+Requires-Dist: websocket-client (>=1.7.0,<2.0.0)
+Description-Content-Type: text/markdown
+
+### Getting Started
+
+Create a file `~/.canvas/credentials.ini` and add the client_id and client_secret credentials for each of your Canvas instances. You can define your default host with `is_default=true`. If no default is explicitly defined, the Canvas CLI will use the first instance in the file as the default for each of the CLI commands.
+
+**Example:**
+
+```
+[my-canvas-instance]
+client_id=myclientid
+client_secret=myclientsecret
+
+[my-dev-canvas-instance]
+client_id=devclientid
+client_secret=devclientsecret
+is_default=true
+
+[localhost]
+client_id=localclientid
+client_secret=localclientsecret
+```
+
+Next, you're ready to install canvas.
+
+`pip install canvas`
+
+**Usage**:
+
+```console
+$ canvas [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+- `--no-ansi`: Disable colorized output
+- `--version`
+- `--verbose`: Show extra output
+- `--install-completion`: Install completion for the current shell.
+- `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+- `--help`: Show this message and exit.
+
+**Commands**:
+
+- `init`: Create a new plugin
+- `install`: Install a plugin into a Canvas instance
+- `uninstall`: Uninstall a plugin from a Canvas instance
+- `list`: List all plugins from a Canvas instance
+- `validate-manifest`: Validate the Canvas Manifest json file
+- `logs`: Listen and print log streams from a Canvas instance
+
+## `canvas init`
+
+Create a new plugin.
+
+**Usage**:
+
+```console
+$ canvas init [OPTIONS]
+```
+
+**Options**:
+
+- `--help`: Show this message and exit.
+
+## `canvas install`
+
+Install a plugin into a Canvas instance.
+
+**Usage**:
+
+```console
+$ canvas install [OPTIONS] PLUGIN_NAME
+```
+
+**Arguments**:
+
+- `PLUGIN_NAME`: Path to plugin to install [required]
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas uninstall`
+
+Uninstall a plugin from a Canvas instance..
+
+**Usage**:
+
+```console
+$ canvas uninstall [OPTIONS] NAME
+```
+
+**Arguments**:
+
+- `NAME`: Plugin name to delete [required]
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas list`
+
+List all plugins from a Canvas instance.
+
+**Usage**:
+
+```console
+$ canvas list [OPTIONS]
+```
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas validate-manifest`
+
+Validate the Canvas Manifest json file.
+
+**Usage**:
+
+```console
+$ canvas validate-manifest [OPTIONS] PACKAGE
+```
+
+**Arguments**:
+
+- `PLUGIN_NAME`: Path to plugin to install [required]
+
+**Options**:
+
+- `--help`: Show this message and exit.
+
+## `canvas logs`
+
+Listens and prints log streams from the instance.
+
+**Usage**:
+
+```console
+$ canvas logs [OPTIONS]
+```
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+

canvas-0.1.6/README.md

@@ -0,0 +1,148 @@
+### Getting Started
+
+Create a file `~/.canvas/credentials.ini` and add the client_id and client_secret credentials for each of your Canvas instances. You can define your default host with `is_default=true`. If no default is explicitly defined, the Canvas CLI will use the first instance in the file as the default for each of the CLI commands.
+
+**Example:**
+
+```
+[my-canvas-instance]
+client_id=myclientid
+client_secret=myclientsecret
+
+[my-dev-canvas-instance]
+client_id=devclientid
+client_secret=devclientsecret
+is_default=true
+
+[localhost]
+client_id=localclientid
+client_secret=localclientsecret
+```
+
+Next, you're ready to install canvas.
+
+`pip install canvas`
+
+**Usage**:
+
+```console
+$ canvas [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+- `--no-ansi`: Disable colorized output
+- `--version`
+- `--verbose`: Show extra output
+- `--install-completion`: Install completion for the current shell.
+- `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+- `--help`: Show this message and exit.
+
+**Commands**:
+
+- `init`: Create a new plugin
+- `install`: Install a plugin into a Canvas instance
+- `uninstall`: Uninstall a plugin from a Canvas instance
+- `list`: List all plugins from a Canvas instance
+- `validate-manifest`: Validate the Canvas Manifest json file
+- `logs`: Listen and print log streams from a Canvas instance
+
+## `canvas init`
+
+Create a new plugin.
+
+**Usage**:
+
+```console
+$ canvas init [OPTIONS]
+```
+
+**Options**:
+
+- `--help`: Show this message and exit.
+
+## `canvas install`
+
+Install a plugin into a Canvas instance.
+
+**Usage**:
+
+```console
+$ canvas install [OPTIONS] PLUGIN_NAME
+```
+
+**Arguments**:
+
+- `PLUGIN_NAME`: Path to plugin to install [required]
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas uninstall`
+
+Uninstall a plugin from a Canvas instance..
+
+**Usage**:
+
+```console
+$ canvas uninstall [OPTIONS] NAME
+```
+
+**Arguments**:
+
+- `NAME`: Plugin name to delete [required]
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas list`
+
+List all plugins from a Canvas instance.
+
+**Usage**:
+
+```console
+$ canvas list [OPTIONS]
+```
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.
+
+## `canvas validate-manifest`
+
+Validate the Canvas Manifest json file.
+
+**Usage**:
+
+```console
+$ canvas validate-manifest [OPTIONS] PACKAGE
+```
+
+**Arguments**:
+
+- `PLUGIN_NAME`: Path to plugin to install [required]
+
+**Options**:
+
+- `--help`: Show this message and exit.
+
+## `canvas logs`
+
+Listens and prints log streams from the instance.
+
+**Usage**:
+
+```console
+$ canvas logs [OPTIONS]
+```
+
+**Options**:
+
+- `--host TEXT`: Canvas instance to connect to
+- `--help`: Show this message and exit.

canvas-0.1.6/canvas_cli/apps/auth/__init__.py

@@ -0,0 +1,3 @@
+from canvas_cli.apps.auth.utils import get_or_request_api_token
+
+__all__ = ("get_or_request_api_token",)

canvas-0.1.6/canvas_cli/apps/auth/tests.py

@@ -0,0 +1,142 @@
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from canvas_cli.apps.auth import get_or_request_api_token
+
+
+@pytest.fixture
+def valid_token_response() -> Any:
+    class TokenResponse:
+        status_code = 200
+
+        def json(self) -> dict:
+            return {"access_token": "a-valid-api-token", "expires_in": 3600}
+
+    return TokenResponse()
+
+
+@pytest.fixture
+def error_token_response() -> Any:
+    class TokenResponse:
+        status_code = 500
+
+    return TokenResponse()
+
+
+@pytest.fixture
+def expired_token_response() -> Any:
+    class TokenResponse:
+        status_code = 200
+
+        def json(self) -> dict:
+            return {"access_token": "a-valid-api-token", "expires_in": -1}
+
+    return TokenResponse()
+
+
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.is_token_valid")
+def test_get_or_request_api_token_uses_stored_token(
+    mock_is_token_valid: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    valid_token_response: Any,
+) -> None:
+    mock_is_token_valid.return_value = True
+    mock_get_password.return_value = "a-stored-valid-token"
+    mock_post.return_value = valid_token_response
+
+    token = get_or_request_api_token("http://localhost:8000")
+
+    assert token == "a-stored-valid-token"
+    mock_post.assert_not_called()
+
+
+@patch("keyring.set_password")
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.get_api_client_credentials")
+def test_get_or_request_api_token_requests_token_if_none_stored(
+    mock_client_credentials: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    mock_set_password: MagicMock,
+    valid_token_response: Any,
+) -> None:
+    mock_client_credentials.return_value = "client_id=id&client_secret=secret"
+    mock_get_password.return_value = None
+    mock_post.return_value = valid_token_response
+
+    token = get_or_request_api_token("http://localhost:8000")
+
+    assert token == "a-valid-api-token"
+    mock_post.assert_called_once_with(
+        "http://localhost:8000/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        json=None,
+        data="grant_type=client_credentials&scope=system/Plugins.*&client_id=id&client_secret=secret",
+    )
+    mock_set_password.assert_called_with(
+        "canvas_cli.apps.auth.utils",
+        username="http://localhost:8000|token",
+        password="a-valid-api-token",
+    )
+
+
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.get_api_client_credentials")
+def test_get_or_request_api_token_raises_exception_if_error_token_response(
+    mock_client_credentials: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    error_token_response: Any,
+) -> None:
+    mock_client_credentials.return_value = "client_id=id&client_secret=secret"
+    mock_get_password.return_value = None
+    mock_post.return_value = error_token_response
+
+    with pytest.raises(Exception) as e:
+        get_or_request_api_token("http://localhost:8000")
+
+    assert "Unable to get a valid access token from the given host 'http://localhost:8000'" in repr(
+        e
+    )
+
+    mock_post.assert_called_once_with(
+        "http://localhost:8000/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        json=None,
+        data="grant_type=client_credentials&scope=system/Plugins.*&client_id=id&client_secret=secret",
+    )
+
+
+@patch("keyring.get_password")
+@patch("requests.Session.post")
+@patch("canvas_cli.apps.auth.utils.get_api_client_credentials")
+def test_get_or_request_api_token_raises_exception_if_expired_token(
+    mock_client_credentials: MagicMock,
+    mock_post: MagicMock,
+    mock_get_password: MagicMock,
+    expired_token_response: Any,
+) -> None:
+    mock_client_credentials.return_value = "client_id=id&client_secret=secret"
+    mock_get_password.return_value = None
+    mock_post.return_value = expired_token_response
+
+    with pytest.raises(Exception) as e:
+        get_or_request_api_token("http://localhost:8000")
+
+    assert (
+        "A valid token could not be acquired from the given host 'http://localhost:8000'" in repr(e)
+    )
+
+    mock_post.assert_called_once_with(
+        "http://localhost:8000/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        json=None,
+        data="grant_type=client_credentials&scope=system/Plugins.*&client_id=id&client_secret=secret",
+    )

canvas-0.1.6/canvas_cli/apps/auth/utils.py

@@ -0,0 +1,163 @@
+import configparser
+from datetime import datetime, timedelta
+from pathlib import Path
+from urllib.parse import urlparse
+
+import keyring
+import requests
+
+from canvas_sdk.utils import Http
+
+# Keyring namespace we'll use
+KEYRING_SERVICE = __name__
+
+CONFIG_PATH = Path.home() / ".canvas" / "credentials.ini"
+
+LOCALHOST = "http://localhost:8000"
+
+
+def get_password(username: str) -> str | None:
+    """Return the stored password for username, or None."""
+    return keyring.get_password(KEYRING_SERVICE, username)
+
+
+def set_password(username: str, password: str) -> None:
+    """Set the password for the given username."""
+    keyring.set_password(KEYRING_SERVICE, username=username, password=password)
+
+
+def delete_password(username: str) -> None:
+    """Delete the password for the given username."""
+    keyring.delete_password(KEYRING_SERVICE, username=username)
+
+
+def get_config() -> configparser.ConfigParser:
+    """Reads the config file and returns a ConfigParser object."""
+    config = configparser.ConfigParser()
+    if not config.read(CONFIG_PATH):
+        raise Exception(
+            f"""Please add your configuration file at '{CONFIG_PATH}' with the following format:
+
+            [my-canvas-subdomain]
+            client_id=myclientid
+            client_secret=myclientsecret
+
+            [my-dev-canvas-subdomain]
+            client_id=devclientid
+            client_secret=devclientsecret
+            is_default=true
+
+            [localhost]
+            client_id=localclientid
+            client_secret=localclientsecret
+            """
+        )
+    return config
+
+
+def read_config(host: str, property: str) -> str:
+    """Reads the config file and returns the property for a given section."""
+    config = get_config()
+    if host not in config:
+        raise Exception(f"'{host}' is not found in the configuration file at '{CONFIG_PATH}'")
+    return config.get(host, property)
+
+
+def get_api_client_credentials(host: str) -> str:
+    """Either return the given api_key, or fetch it from the keyring."""
+    hostname = urlparse(host).hostname
+
+    if not hostname:
+        raise ValueError("Could not parse hostname from URL")
+
+    instance = hostname.removesuffix(".canvasmedical.com")
+
+    client_id = read_config(instance, "client_id")
+    client_secret = read_config(instance, "client_secret")
+
+    return f"client_id={client_id}&client_secret={client_secret}"
+
+
+def get_default_host(host: str | None = None) -> str:
+    """Return the explicitly stated default host, or first if none is indicated."""
+    if host:
+        if "://" in host:
+            return host
+
+        if "localhost" in host:
+            return LOCALHOST
+
+        return f"https://{host}.canvasmedical.com"
+
+    config = get_config()
+    if not (hosts := config.sections()):
+        raise Exception(f"No hosts found in the configuration file at '{CONFIG_PATH}'")
+
+    first_default_host = next(
+        (host for host in hosts if config.getboolean(host, "is_default", fallback=False) is True),
+        hosts[0],
+    )
+    if first_default_host == "localhost":
+        return LOCALHOST
+
+    return f"https://{first_default_host}.canvasmedical.com"
+
+
+def request_api_token(host: str, api_client_credentials: str) -> dict:
+    """Request an api token using the provided client_id and client_secret."""
+    grant_type = "grant_type=client_credentials"
+    scope = "scope=system/Plugins.*"
+
+    http = Http()
+    token_response = http.post(
+        f"{host}/auth/token/",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        data=f"{grant_type}&{scope}&{api_client_credentials}",
+    )
+    if token_response.status_code != requests.codes.ok:
+        raise Exception(f"Unable to get a valid access token from the given host '{host}'")
+    return token_response.json()
+
+
+def is_token_valid(host_token_key: str, expiration_date: datetime | None = None) -> bool:
+    """True if the token has not expired yet."""
+    token_exp_date_key = f"{host_token_key}|exp_date"
+
+    if expiration_date:
+        if expiration_date <= datetime.now():
+            return False
+        set_password(token_exp_date_key, expiration_date.isoformat())
+        return True
+
+    stored_expiration_date = get_password(token_exp_date_key)
+    return (
+        stored_expiration_date is not None
+        and datetime.fromisoformat(stored_expiration_date) > datetime.now()
+    )
+
+
+def get_or_request_api_token(host: str | None = None) -> str:
+    """Returns an existing stored token if it has not expired, or requests a new one."""
+    if not (host := get_default_host(host)):
+        raise Exception(
+            f"Please specify a host or add one to the configuration file at '{CONFIG_PATH}'"
+        )
+
+    host_token_key = f"{host}|token"
+    token = get_password(host_token_key)
+
+    if token and is_token_valid(host_token_key):
+        return token
+
+    api_client_credentials = get_api_client_credentials(host)
+
+    if not (token_response := request_api_token(host, api_client_credentials)):
+        raise Exception(f"A token could not be acquired from the given host '{host}'")
+
+    token_expiration_date = datetime.now() + timedelta(seconds=token_response["expires_in"])
+    if not is_token_valid(host_token_key, token_expiration_date):
+        raise Exception(f"A valid token could not be acquired from the given host '{host}'")
+
+    new_token = token_response["access_token"]
+    set_password(host_token_key, new_token)
+    return new_token

canvas-0.1.6/canvas_cli/apps/logs/__init__.py

@@ -0,0 +1,3 @@
+from canvas_cli.apps.logs.logs import logs
+
+__all__ = ("logs",)

canvas-0.1.6/canvas_cli/apps/logs/logs.py

@@ -0,0 +1,59 @@
+from typing import Optional
+from urllib.parse import urlparse
+
+import typer
+import websocket
+
+from canvas_cli.apps.auth.utils import get_default_host, get_or_request_api_token
+from canvas_cli.utils.print import print
+
+
+def _on_message(ws: websocket.WebSocketApp, message: str) -> None:
+    print.json(message)
+
+
+def _on_error(ws: websocket.WebSocketApp, error: str) -> None:
+    print.json(f"Error: {error}", success=False)
+
+
+def _on_close(ws: websocket.WebSocketApp, close_status_code: str, close_msg: str) -> None:
+    print.json(f"Connection closed with status code {close_status_code}: {close_msg}")
+
+
+def _on_open(ws: websocket.WebSocketApp) -> None:
+    print.json("Connected to the logging service")
+
+
+def logs(
+    host: Optional[str] = typer.Option(
+        callback=get_default_host, help="Canvas instance to connect to", default=None
+    )
+) -> None:
+    """Listens and prints log streams from the instance."""
+    if not host:
+        raise typer.BadParameter("Please specify a host or add one to the configuration file")
+
+    token = get_or_request_api_token(host)
+
+    # Resolve the instance name from the Canvas host URL (e.g., extract
+    # 'example' from 'https://example.canvasmedical.com/')
+    hostname = urlparse(host).hostname
+    instance = hostname.removesuffix(".canvasmedical.com")
+
+    print.json(
+        f"Connecting to the log stream. Please be patient as there may be a delay before log messages appear."
+    )
+    websocket_uri = f"wss://logs.console.canvasmedical.com/{instance}?token={token}"
+
+    try:
+        ws = websocket.WebSocketApp(
+            websocket_uri,
+            on_message=_on_message,
+            on_error=_on_error,
+            on_close=_on_close,
+        )
+        ws.on_open = _on_open
+        ws.run_forever()
+
+    except KeyboardInterrupt:
+        raise typer.Exit(0)

canvas-0.1.6/canvas_cli/apps/plugin/__init__.py

@@ -0,0 +1,9 @@
+from canvas_cli.apps.plugin.plugin import (
+    init,
+    install,
+    list,
+    uninstall,
+    validate_manifest,
+)
+
+__all__ = ("uninstall", "init", "validate_manifest", "install", "list")