Communication Layer for Python Package and VSCode Extension - DevOps-MBSE/AaC GitHub Wiki

What's the point?

To support visualizing AaC definitions using Visual Studio Code's CustomEditor or CustomTextEditor (see here) we need to have a way for the editor to interact with the AaC Python package so that it can perform CRUD operations on the definition from the editor.

Along these lines, we have a couple options when it comes to allowing the chosen editor to interact with the AaC Python package:

  1. A standard REST API
  2. A WebAssemly API

It goes without saying that each of these options have their benefits and drawbacks which (we will discuss below) so the primary criteria we will use to evaluate these options will be as follows:

Criteria Question to answer Scale
Documentation What is the availability of technical documentation available for the specified approach? What is the quality of that documentation? 1-10
Flexibility How much flexibility does the option allow for making changes and adapting to new information when we get feedback from users, etc.? 1-10
Maturity How long has the project been in development? Will we run into issues that arise as a result of the project not having seen much use? 1-10
Complexity How involved will it be to set up something simple (i.e. a "hello world" style application)? Will a junior developer be able to hit the ground running, or will they have to spend days/weeks getting up to speed before being able to be productive? H/M/L

The criteria will be evaluated on a scale from 1 to 10 where 1 means the the approach does not lend itself to that criteria, 5 means the approach is neutral, and 10 means that criteria is met abundantly.

A quick example, for documentation of a REST API the score could reasonably come in around an 8 or 9 when considering documentation because there are numerous examples and resources of REST APIs. If there are examples of using REST APIs with VSCode extensions, that would further increase the score.

VSCode CustomEditor or CustomTextEditor API

The CustomTextEditor API

  • Uses VSCode's standard TextDocument as the underlying data model.
  • Used for text-based file types.
  • Easier to implement because VSCode already knows how to do many operations for text-based files.

The CustomEditor API

  • Uses a custom data model to represent the document.
  • Used for binary file formats (e.g. images, audio, etc).
  • More complexity when implementing since we need custom implementation for certain operations (e.g. saving, backing up, etc).
    • Complexity can be reduced if data model is read-only.

Which one to actually use

Given AaC definitions are represented using YAML - it would make sense to use a CustomTextEditor for our custom editor implementation so we can take advantage of the functionality already provided by VSCode and so we don't have to come up with a new data model for the VSCode representation.

Documentation Flexibility Maturity Complexity
8 8 9 M

  1. Resources

How to use it

  1. Register the custom editor using the customEditors contribution point (see here) in the extension's package.json.
  2. Register the custom editor provider with the expected view type when activating the extension (see here for the API call).
  3. Populate a provided WebviewPanel with HTML in the callback for resolveCustomTextEdtior (see here).
    • This happens every time a custom editor is opened.
  4. Provide clean-up operations for the onDidDispose event (on the WebviewPanel) when a view is closed.

Standard REST API

Documentation Flexibility Maturity Complexity
9 10 10 L

REST APIs are ubiquitous in software engineering and possibly the most common approach used when implementing a client-server application. It's clear, then, why implementing a REST API might be an attractive option. To implement a REST API with Python, we can use a variety of tools but in this article we will consider Flask, FastAPI, and the Django Rest Framework.

Flask

  • Microframework:
    • Leaves many design choices to developers
    • Increased flexibility
    • Fewer dependencies
  • Handle HTTP requests and route them to the appropriate function.
  • Large extension ecosystem
  • Mature (first PyPI release 2010-04-16)

  1. Resources

FastAPI

  • Framework optimized for building APIs.
  • Python type hints
  • Built-in support for asynchronous operations
  • Code looks similar to Flask
  • Uses Pydantic to represent and validate data (with structure)
  • New (first PyPI release 2018-12-08)

  1. Resources

Django Rest Framework

  • Requires an existing Django project
  • Lots of infrastructure to provide a simple
  • SQLite database is required

  1. Resources

General Resources

WebAssembly API

Documentation Flexibility Maturity Complexity
5 8 3 H

CPython

  1. Resources

Pyodide

  • Port of CPython to WebAssembly/Emscripten
  • Supports installing/running pure python packages in PyPI
  • Supports some packages that make use of C extensions
  • FFI for Python <-> JavaScript interaction
  • Full access to web APIs when used in a browser
  • Cannot install aac due to the following error: ValueError: Couldn't find a pure Python 3 wheel for: 'coverage>=6.0', 'iteration-utilities>=0.11'
  • Relatively new (first GitHub release 2018-11-07)
    • Pyodide is not available on PyPI
    • Pyodide can come from a CDN: see here

  1. Resources

General Resources