Workflow Service Protocol - Fat or thin functions? - For example, creating a virtual environment could be: - Fat: creation and installation in one call, returning details - Thin: - Creation - Installation - Details # Discovery Apps could install a `_wsp_*` command for easy discoverability of what's available. Having something called just `_wsp` could set the default tool to use unless a specific tool is requested/specified. ## App details - Returns - name - version For error messages, debugging, etc. ## Capabilities - Returns - Collection of strings listing all the supported features List the capabilities of the tool for self-discovery. # Environments This could either done in a generic fashion (where arguments are flexible and you specify the kind of environment you want) or be specific to the kind of environment. ## Generic example ### List - Arguments - cwd - Returns - kind - key - name - location (? Or have a separate info/details call?) ### Create - Arguments - cwd - name - kind - options (e.g., for virtual environments would have extras, dependency groups, etc.) - Returns - key - location ## Virtual environments example ### List - Arguments - cwd - Returns - key - name - Python version - file location (if available) Should be a cheap lookup. ### Create - Arguments - cwd - name - Requirement - Environment marker or specific interpreter and version? - Requirement handles interpreter type and interpreter version together, but requires a bit more work on the workflow tool to tease apart what to do - with pip? - Could leave that up to the workflow tool to decide - Returns - key - Python version (is supporting specifying by requirement) - file location (if available) ### Delete - Arguments - key ### Install❓ - Support only what's available from pyproject.toml and pylock.toml or also support individual package installs? - Do you leave it up to the workflow tools to figure out where to find pyproject.toml and pylock.toml? Or have the path to the file be specified? - Considered passing the actual contents, but since the files will have to live _somewhere_, it seemed unnecessary ### Installed packages - Arguments - key - Returns - Collection of details about each project - Specific metadata like name and version? - The core metadata (including file name to be forwards-compatible with metadata.json) so the user can have a more complete picture? - Do we care about entry points? - Returning the core metadata would take care of that implicitly. - Can look at [importlib.metadata](https://docs.python.org/3/library/importlib.metadata.html) for inspiration. ### Execute #### Execute - Arguments - key - command - Only support commands for `python` or entry points? Or any command on the machine? - cwd? - env - encoding/text? - No good way to send binary data over JSON without base64. - Returns - ID #### Poll - Arguments - ID - Returns - None or return code #### Wait - Arguments - ID - timeout - Returns - return code #### Communicate - Arguments - ID - input - timeout - Returns - stdout - stderr #### Signal - Arguments - ID - signal #### Terminate - Arguments - ID - kill # Install Python ## List - Returns - List of interpreters - Interpreter type - Interpreter version - Interpreter key to use in other APIs? Only list what's installed? Or include what's available to install? ## Install❓ - How to specify - All details? - Interpreter type - Interpreter version - Environment marker? # Performance ## Daemon A signal to the workflow tool that the process will be left running for some time, so it can do things that have a bit of upfront cost (compared to being a single call and then exiting). # Open issues❓ - Need to be able to run scripts with inline script metadata - Would the caller handle it? - Would need to support the ability to [[#Create]] temporary virtual environments - `requires-python` would let creating a virtual environment appropriately - Manually install or a call to install dependencies as read from the script - [[#Execute]] - API? - Some "run" call that mirrored the [[#Execute]] API, but that takes the path to a script instead of `python`/entry point - Provide a flag to allow for installing Python as necessary? - `pipx run` support? - Inline script metadata gets you practically there - Might be stretching too far