canvas 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

canvas_cli/apps/plugin/plugin.py

@@ -0,0 +1,286 @@
+import json
+import tarfile
+import tempfile
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urljoin
+
+import requests
+import typer
+from cookiecutter.exceptions import OutputDirExistsException
+from cookiecutter.main import cookiecutter
+
+from canvas_cli.apps.auth.utils import get_default_host, get_or_request_api_token
+from canvas_cli.utils.context import context
+from canvas_cli.utils.print import print
+from canvas_cli.utils.validators import validate_manifest_file
+
+
+def plugin_url(host: str, *paths: str) -> str:
+    """Generates the plugin url for managing plugins in a Canvas instance."""
+    join = "/".join(["plugin-io/plugins", "/".join(paths or [])])
+    join = join if join.endswith("/") else join + "/"
+
+    return urljoin(host, join)
+
+
+def validate_package(package: Path) -> Path:
+    """Validate if `package` Path exists and it is a file."""
+    if not package.exists():
+        raise typer.BadParameter(f"Package {package} does not exist")
+
+    if not package.is_file():
+        raise typer.BadParameter(f"Package {package} isn't a file")
+
+    if not package.name.endswith("tar.gz") and not package.name.endswith("whl"):
+        raise typer.BadParameter(f"Package {package} needs to be a tar.gz or a whl")
+
+    return package
+
+
+def _build_package(package: Path) -> Path:
+    """Runs `poetry build` on `package` and returns the built archive."""
+    if not package.exists() or not package.is_dir():
+        raise typer.BadParameter(f"Couldn't build {package}, not a dir")
+
+    with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as file:
+        with tarfile.open(file.name, "w:gz") as tar:
+            tar.add(package, arcname=".")
+
+        return Path(file.name)
+
+
+def _get_name_from_metadata(host: str, token: str, package: Path) -> Optional[str]:
+    """Extract metadata from a provided package and return the package name if it exists in the metadata."""
+    try:
+        metadata_response = requests.post(
+            plugin_url(host, "extract-metadata"),
+            headers={"Authorization": f"Bearer {token}"},
+            files={"package": open(package, "rb")},
+        )
+    except requests.exceptions.RequestException:
+        print.json(f"Failed to connect to {host}", success=False)
+        raise typer.Exit(1)
+
+    if metadata_response.status_code != requests.codes.ok:
+        print.response(metadata_response, success=False)
+        raise typer.Exit(1)
+
+    metadata = metadata_response.json()
+    return metadata.get("name")
+
+
+def get_base_plugin_template_path() -> Path:
+    """Return context's base_plugin_template_path, so it can be used as a Typer default."""
+    return context.plugin_template_dir / context.default_plugin_template_name
+
+
+def init() -> None:
+    """Create a new plugin."""
+    template = get_base_plugin_template_path()
+    try:
+        project_dir = cookiecutter(str(template))
+    except OutputDirExistsException:
+        raise typer.BadParameter(f"The supplied directory already exists")
+
+    print.json(f"Project created in {project_dir}", project_dir=project_dir)
+
+
+def install(
+    plugin_name: Path = typer.Argument(..., help="Path to plugin to install"),
+    host: Optional[str] = typer.Option(
+        callback=get_default_host,
+        help="Canvas instance to connect to",
+        default=None,
+    ),
+) -> None:
+    """Install a plugin into a Canvas 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)
+
+    if not plugin_name.exists():
+        raise typer.BadParameter(f"Plugin '{plugin_name}' does not exist")
+
+    if plugin_name.is_dir():
+        validate_manifest(plugin_name)
+        built_package_path = _build_package(plugin_name)
+    else:
+        raise typer.BadParameter(f"Plugin '{plugin_name}' needs to be a valid directory")
+
+    print.verbose(f"Installing plugin: {built_package_path} into {host}")
+
+    url = plugin_url(host)
+
+    print.verbose(f"Posting {built_package_path.absolute()} to {url}")
+
+    try:
+        r = requests.post(
+            url,
+            data={"is_enabled": True},
+            files={"package": open(built_package_path, "rb")},
+            headers={"Authorization": f"Bearer {token}"},
+        )
+    except requests.exceptions.RequestException:
+        print.json(f"Failed to connect to {host}", success=False)
+        raise typer.Exit(1)
+
+    if r.status_code == requests.codes.created:
+        print.response(r)
+
+    # If we got a bad_request, means there's a duplicate plugin and install can't handle that.
+    # So we need to get the plugin-name from the package and call `update` directly
+    elif r.status_code == requests.codes.bad_request:
+        plugin_name = _get_name_from_metadata(host, token, built_package_path)
+        update(plugin_name, built_package_path, is_enabled=True, host=host)
+    else:
+        print.response(r, success=False)
+        raise typer.Exit(1)
+
+
+def uninstall(
+    name: str = typer.Argument(..., help="Plugin name to uninstall"),
+    host: Optional[str] = typer.Option(
+        callback=get_default_host,
+        help="Canvas instance to connect to",
+        default=None,
+    ),
+) -> None:
+    """Uninstall a plugin from a Canvas instance."""
+    if not host:
+        raise typer.BadParameter("Please specify a host or or add one to the configuration file")
+
+    url = plugin_url(host, name)
+
+    print.verbose(f"Uninstalling {name} using {url}")
+
+    token = get_or_request_api_token(host)
+
+    try:
+        r = requests.delete(
+            url,
+            headers={
+                "Authorization": f"Bearer {token}",
+            },
+        )
+    except requests.exceptions.RequestException:
+        print.json(f"Failed to connect to {host}", success=False)
+        raise typer.Exit(1)
+
+    if r.status_code == requests.codes.no_content:
+        print.response(r)
+    else:
+        print.response(r, success=False)
+        raise typer.Exit(1)
+
+
+def list(
+    host: Optional[str] = typer.Option(
+        callback=get_default_host,
+        help="Canvas instance to connect to",
+        default=None,
+    )
+) -> None:
+    """List all plugins from a Canvas instance."""
+    if not host:
+        raise typer.BadParameter("Please specify a host or add one to the configuration file")
+
+    url = plugin_url(host)
+
+    token = get_or_request_api_token(host)
+
+    try:
+        r = requests.get(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+    except requests.exceptions.RequestException:
+        print.json(f"Failed to connect to {host}", success=False)
+        raise typer.Exit(1)
+
+    if r.status_code == requests.codes.ok:
+        print.response(r)
+    else:
+        print.response(r, success=False)
+        raise typer.Exit(1)
+
+
+def validate_manifest(
+    plugin_name: Path = typer.Argument(..., help="Path to plugin to validate"),
+) -> None:
+    """Validate the Canvas Manifest json file."""
+    if not plugin_name.exists():
+        raise typer.BadParameter(f"Plugin '{plugin_name}' does not exist")
+
+    if not plugin_name.is_dir():
+        raise typer.BadParameter(f"Plugin '{plugin_name}' is not a directory, nothing to validate")
+
+    manifest = plugin_name / "CANVAS_MANIFEST.json"
+
+    if not manifest.exists():
+        raise typer.BadParameter(
+            f"Plugin '{plugin_name}' does not have a CANVAS_MANIFEST.json file to validate"
+        )
+
+    try:
+        manifest_json = json.loads(manifest.read_text())
+    except json.JSONDecodeError:
+        print.json(
+            "There was a problem loading the manifest file, please ensure it's valid JSON",
+            success=False,
+            path=str(plugin_name),
+        )
+        raise typer.Abort()
+
+    validate_manifest_file(manifest_json)
+
+    print.json(f"Plugin '{plugin_name}' has a valid CANVAS_MANIFEST.json file")
+
+
+def update(
+    name: str = typer.Argument(..., help="Plugin name to update"),
+    package: Optional[Path] = typer.Option(
+        help="Path to a wheel or sdist file containing the python package to install",
+        default=None,
+    ),
+    is_enabled: Optional[bool] = typer.Option(
+        None, "--enable/--disable", show_default=False, help="Enable/disable the plugin"
+    ),
+    host: Optional[str] = typer.Option(
+        callback=get_default_host,
+        help="Canvas instance to connect to",
+        default=None,
+    ),
+) -> None:
+    """Updates a plugin from an instance."""
+    if not host:
+        raise typer.BadParameter("Please specify a host or set a default via the `auth` command")
+
+    if package:
+        validate_package(package)
+
+    token = get_or_request_api_token(host)
+
+    print.verbose(f"Updating plugin {name} from {host} with {is_enabled=}, {package=}")
+
+    binary_package = {"package": open(package, "rb")} if package else None
+
+    url = plugin_url(host, name)
+
+    try:
+        r = requests.patch(
+            url,
+            data={"is_enabled": is_enabled} if is_enabled is not None else {},
+            files=binary_package,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+    except requests.exceptions.RequestException:
+        print.json(f"Failed to connect to {host}", success=False)
+        raise typer.Exit(1)
+
+    if r.status_code == requests.codes.ok:
+        print.response(r)
+    else:
+        print.response(r, success=False)
+        raise typer.Exit(1)

canvas_cli/apps/plugin/tests.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import pytest
+import typer
+from typer.testing import CliRunner
+
+from .plugin import validate_package
+
+runner = CliRunner()
+
+
+def test_validate_package_unexistant_path() -> None:
+    """Tests the validate_package callback with an invalid folder."""
+    with pytest.raises(typer.BadParameter):
+        validate_package(Path("/a_random_url_that_will_not_exist_or_so_I_hope"))
+
+
+def test_validate_package_wrong_file_type(tmp_path: Path) -> None:
+    """Tests the validate_package callback with an invalid file type."""
+    invalid_file = tmp_path / "tmp_file.zip"
+    invalid_file.write_text("definitely not a python package")
+
+    with pytest.raises(typer.BadParameter):
+        validate_package(invalid_file)
+
+
+def test_validate_package_valid_file(tmp_path: Path) -> None:
+    """Tests the validate_package callback with a valid file type."""
+    package_path = tmp_path / "test-package.whl"
+    package_path.write_text("something")
+    result = validate_package(package_path)
+    assert result == package_path

canvas_cli/conftest.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+import pytest
+
+import canvas_cli.main
+from canvas_cli.utils.context import context
+
+
+@pytest.fixture(autouse=True)
+def monkeypatch_app_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Monkeypatch `get_app_dir` in order to return a temp dir when testing, so we don't overwrite our config file."""
+
+    def app_dir() -> str:
+        return str(tmp_path)
+
+    monkeypatch.setattr(canvas_cli.main, "get_app_dir", app_dir)
+
+
+@pytest.fixture(autouse=True)
+def reset_context_variables() -> None:
+    """Reset the context properties to their default value.
+    This is needed because we cannot build a `reset` method in the CLIContext class,
+    because `load_from_file` loads properties dynamically.
+    Also since this is a CLI, it's not expected to keep the global context in memory for more than a run,
+    which definitely happens with tests run
+    """
+    context._default_host = None
+    context._verbose = False

canvas_cli/main.py

@@ -0,0 +1,78 @@
+import importlib.metadata
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from canvas_cli.apps import plugin
+from canvas_cli.apps.logs import logs as logs_command
+from canvas_cli.utils.context import context
+from canvas_cli.utils.print import print
+
+APP_NAME = "canvas_cli"
+
+# The main app
+app = typer.Typer(no_args_is_help=True)
+
+# Commands
+app.command(short_help="Create a new plugin")(plugin.init)
+app.command(short_help="Install a plugin into a Canvas instance")(plugin.install)
+app.command(short_help="Uninstall a plugin from a Canvas instance")(plugin.uninstall)
+app.command(short_help="List all plugins from a Canvas instance")(plugin.list)
+app.command(short_help="Validate the Canvas Manifest json file")(plugin.validate_manifest)
+app.command(short_help="Listen and print log streams from a Canvas instance")(logs_command)
+
+# Our current version
+__version__ = importlib.metadata.version("canvas")
+
+
+def version_callback(value: bool) -> None:
+    """Method called when the `--version` flag is set. Prints the version and exits the CLI."""
+    if value:
+        print.json(f"{APP_NAME} Version: {__version__}", version=__version__)
+        raise typer.Exit()
+
+
+def get_app_dir() -> str:
+    """Return the app dir, where the config file will be saved.
+    This method is monkeypatched in conftest.py, for testing purposes.
+    """
+    return typer.get_app_dir(APP_NAME)
+
+
+def get_or_create_config_file() -> Path:
+    """Method called to get a Path to the existent JSON config file, or create one if it doesn't exist."""
+    app_dir = get_app_dir()
+    config_path: Path = Path(app_dir) / "config.json"
+    if not config_path.is_file():
+        Path(app_dir).mkdir(parents=True, exist_ok=True)
+        with open(config_path, "w+") as file:
+            file.write("{}")
+
+    return config_path
+
+
+@app.callback()
+def main(
+    no_ansi: bool = typer.Option(False, "--no-ansi", help="Disable colorized output"),
+    version: Optional[bool] = typer.Option(
+        None, "--version", callback=version_callback, is_eager=True
+    ),
+    verbose: bool = typer.Option(False, "--verbose", help="Show extra output"),
+) -> None:
+    """Canvas swiss army knife CLI tool."""
+    # Fetch the config file and load our context from it.
+    config_file = get_or_create_config_file()
+
+    context.load_from_file(config_file)
+
+    context.no_ansi = no_ansi
+
+    # Set the --verbose flag
+    if verbose:
+        context.verbose = verbose
+        print.verbose("Verbose mode enabled")
+
+
+if __name__ == "__main__":
+    app()

canvas_cli/templates/plugins/default/cookiecutter.json

@@ -0,0 +1,4 @@
+{
+    "project_name": "My Cool Plugin",
+    "__project_slug": "{{ cookiecutter.project_name.lower().replace(' ', '_') }}"
+}

canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/CANVAS_MANIFEST.json

@@ -0,0 +1,29 @@
+{
+    "sdk_version": "0.1.4",
+    "plugin_version": "0.0.1",
+    "name": "{{ cookiecutter.__project_slug }}",
+    "description": "Edit the description in CANVAS_MANIFEST.json",
+    "components": {
+        "protocols": [
+            {
+                "class": "{{ cookiecutter.__project_slug }}.protocols.my_protocol:Protocol",
+                "description": "A protocol that does xyz...",
+                "data_access": {
+                    "event": "",
+                    "read": [],
+                    "write": []
+                }
+            }
+        ],
+        "commands": [],
+        "content": [],
+        "effects": [],
+        "views": []
+    },
+    "secrets": [],
+    "tags": {},
+    "references": [],
+    "license": "",
+    "diagram": false,
+    "readme": "./README.md"
+}

canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/README.md

@@ -0,0 +1,12 @@
+{% for _ in cookiecutter.__project_slug %}={% endfor %}
+{{ cookiecutter.__project_slug }}
+{% for _ in cookiecutter.__project_slug %}={% endfor %}
+
+## Description
+
+A description of this plugin
+
+### Important Note!
+
+The CANVAS_MANIFEST.json is used when installing your plugin. Please ensure it
+gets updated if you add, remove, or rename protocols.

canvas_cli/templates/plugins/default/{{ cookiecutter.__project_slug }}/protocols/my_protocol.py

@@ -0,0 +1,55 @@
+from canvas_sdk.events import EventType
+from canvas_sdk.protocols import BaseProtocol
+from logger import log
+
+
+# Inherit from BaseProtocol to properly get registered for events
+class Protocol(BaseProtocol):
+    """
+    You should put a helpful description of this protocol's behavior here.
+    """
+
+    # Name the event type you wish to run in response to
+    RESPONDS_TO = EventType.Name(EventType.ASSESS_COMMAND__CONDITION_SELECTED)
+
+    NARRATIVE_STRING = "I was inserted from my plugin's protocol."
+
+    def compute(self):
+        """
+        This method gets called when an event of the type RESPONDS_TO is fired.
+        """
+        # This class is initialized with several pieces of information you can
+        # access.
+        #
+        # `self.event` is the event object that caused this method to be
+        # called.
+        #
+        # `self.target` is an identifier for the object that is the subject of
+        # the event. In this case, it would be the identifier of the assess
+        # command. If this was a patient create event, it would be the
+        # identifier of the patient. If this was a task update event, it would
+        # be the identifier of the task. Etc, etc.
+        #
+        # `self.context` is a python dictionary of additional data that was
+        # given with the event. The information given here depends on the
+        # event type.
+        #
+        # `self.secrets` is a python dictionary of the secrets you defined in
+        # your CANVAS_MANIFEST.json and set values for in the uploaded
+        # plugin's configuration page: <emr_base_url>/admin/plugin_io/plugin/<plugin_id>/change/
+        # Example: self.secrets['WEBHOOK_URL']
+
+        # You can log things and see them using the Canvas CLI's log streaming
+        # function.
+        log.info(self.NARRATIVE_STRING)
+
+        # Craft a payload to be returned with the effect(s).
+        payload = {
+            "note": {"uuid": self.context["note"]["uuid"]},
+            "data": {"narrative": self.NARRATIVE_STRING},
+        }
+
+        # Return zero, one, or many effects.
+        # Example:
+        # return [Effect(type=EffectType.ADD_PLAN_COMMAND, payload=json.dumps(payload))]
+        return []

canvas_cli/tests.py

@@ -0,0 +1,11 @@
+from typer.testing import CliRunner
+
+from .main import app
+
+runner = CliRunner()
+
+
+def test_version_callback_exits_successfully() -> None:
+    """Tests the CLI exits with 0 when calling with `--version`."""
+    result = runner.invoke(app, "--version")
+    assert result.exit_code == 0

canvas_cli/utils/context/__init__.py

@@ -0,0 +1,3 @@
+from canvas_cli.utils.context.context import CLIContext, context
+
+__all__ = ("context", "CLIContext")