Merge pull request #351 from atopile/mawildoer/pipx-looks-brilliant

Use `pipx` + extension auto-resolves the python interpreter

.vscode/tasks.json

@@ -15,6 +15,9 @@
             "group": {
                 "kind": "build",
                 "isDefault": true
+            },
+            "options": {
+                "cwd": "${workspaceFolder}/src/vscode-atopile"
             }
         },
         {
@@ -26,7 +29,10 @@
                 "reveal": "never",
                 "group": "watchers"
             },
-            "group": "build"
+            "group": "build",
+            "options": {
+                "cwd": "${workspaceFolder}/src/vscode-atopile"
+            }
         },
         {
             "label": "tasks: watch-tests",

docs/getting-started.md

@@ -29,35 +29,18 @@ The `.ato` files are human readable and can be version controlled, so you can co
 
 To run atopile, you will need the atopile compiler, the VSCode extension for syntax highlighting and git credential manager.
 
-### atopile compiler - with pip <small>recommended</small>
+### atopile compiler - with `pipx` <small>recommended</small>
 
 atopile is published as a [python package](https://pypi.org/project/atopile/) on pypi. You can install it using `pip` from your command line. We recommend setting up a virtual environment for atopile so that atopile's dependencies don't clash with the rest of your system.
 
-Start by making sure you have `python@3.11` or later installed on your machine.
-
-??? question "How to install python 3.11 or later"
-
-    To install python 3.11 or later, you can use [brew](https://brew.sh)
-
-    `brew install python@3.11`
-
-    once you create your venv, make sure to run:
-
-    `python3.11 -m venv venv`
-
-Setup the venv:
-``` sh
-python3.11 -m venv venv
-```
-Activate the venv:
+It's dead simple with [`pipx`](https://pipx.pypa.io/stable/)
 ``` sh
-source venv/bin/activate
+pipx install atopile
 ```
 
-Now you can install atopile:
-``` sh
-pip install atopile
-```
+??? question "How do I install `pipx`?"
+    `pipx` has some dead simple installation instructions here: https://pipx.pypa.io/stable/installation/#installing-pipx
+
 
 atopile should be installed. You can verify that it worked with the following command which should give you the current version of atopile.
 ``` sh
@@ -73,10 +56,31 @@ __[Getting started with atopile - get setup and build your first project from sc
 
 ---
 
-### atopile compiler - with git
+### atopile compiler - for development
 
 atopile can be directly installed from [GitHub](https://github.com/atopile/atopile) by cloning the repository into a subfolder of your project root. This could be useful if you want to use the latest version of atopile:
 
+Start by making sure you have `python@3.11` or later installed on your machine.
+
+??? question "How to install python 3.11 or later"
+
+    To install python 3.11 or later, you can use [brew](https://brew.sh)
+
+    `brew install python@3.11`
+
+    once you create your venv, make sure to run:
+
+    `python3.11 -m venv venv`
+
+Setup the venv:
+``` sh
+python3.11 -m venv venv
+```
+Activate the venv:
+``` sh
+source venv/bin/activate
+```
+
 ```
 git clone https://github.com/atopile/atopile.git
 ```
@@ -94,20 +98,24 @@ From VSCode, navigate to the VSCode extensions and install atopile.
 
 ![](assets/images/ato_extension.png)
 
-#### Configuration
+The extension needs to know where your ato compiler's python interpreter is located. There are two ways to do this:
+
+#### 1. - Easy
 
-There's a small amount of one-time configuration required to get type-hints from the extension.
+If `ato` is in your PATH, the extension will find it automatically.
 
-1. Get the path to your python interpreter that has ato installed. This is usually in a virtual environment.
-   - You can find this by running `which python` while your venv is activated.
-2. Configure VSCode to use it!
-   - `Cmd + Shift + P` (or `Ctrl + Shift + P` on Windows) to open the command palette
-   - Type "Python: Select Interpreter" and select it
-   - If your venv isn't there, you can add it by selecting "Enter interpreter path" and pasting the path to your venv's python binary.
 
-All together now!
+#### 2. - Harder
+
+If not, you can set the `atopile.interpreter` setting in your vscode settings to the path of the `ato` executable.
+eg. in your `settings.json` ():
+```json
+{
+    "atopile.interpreter": ["/path/to/the/python/interpreter/used/for/ato"]
+}
+```
 
-![](/docs/assets/images/extension-python-setup.gif)
+You can find `/path/to/the/python/interpreter/used/for/ato` by running `ato --python-path` in your terminal, where `ato` is available.
 
 
 ## Making a simple circuit

src/atopile/cli/cli.py

@@ -1,4 +1,5 @@
 import logging
+import sys
 
 import click
 from rich.logging import RichHandler
@@ -22,12 +23,21 @@
 )
 
 
+def python_interpreter_path(ctx, param, value):
+    """Print the current python interpreter path."""
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(sys.executable)
+    ctx.exit()
+
+
 # cli root
 @click.version_option()
 @click.group()
 @click.option("--non-interactive", is_flag=True, envvar="ATO_NON_INTERACTIVE")
 @click.option("--debug", is_flag=True)
 @click.option("-v", "--verbose", count=True)
+@click.option("--python-path", is_flag=True, callback=python_interpreter_path, expose_value=False)
 @click.pass_context  # This decorator makes the context available to the command.
 def cli(ctx, non_interactive: bool, debug: bool, verbose: int):
     """Base CLI group."""

src/vscode-atopile/README.md

@@ -6,17 +6,26 @@ This extension provides syntax highlighting, auto-completion and goto definition
 
 ## Installation
 
-Instructions from the docs: https://atopile.io/getting-started/#vscode-extension-extension-store
+Install it from your favourite extension store!
 
-There's a small amount of one-time configuration required to get type-hints from the extension.
 
-1. Get the path to your python interpreter that has ato installed. This is usually in a virtual environment.
-   - You can find this by running `which python` while your venv is activated.
-2. Configure VSCode to use it!
-   - `Cmd + Shift + P` (or `Ctrl + Shift + P` on Windows) to open the command palette
-   - Type "Python: Select Interpreter" and select it
-   - If your venv isn't there, you can add it by selecting "Enter interpreter path" and pasting the path to your venv's python binary.
+## Configuration
 
-All together now!
+### 1. - Easy
 
-![](/docs/assets/images/extension-python-setup.gif)
+If `ato` is in your PATH, the extension will find it automatically.
+
+
+### 2. - Harder
+
+If not, you can set the `atopile.interpreter` setting in your vscode settings to the path of the `ato` executable.
+eg. in your `settings.json` ():
+```json
+{
+    "atopile.interpreter": ["/path/to/the/python/interpreter/used/for/ato"]
+}
+```
+
+You can find `/path/to/the/python/interpreter/used/for/ato` by running `ato --python-path` in your terminal, where `ato` is available.
+
+These instructions are also in the docs: https://atopile.io/getting-started/#vscode-extension-extension-store

src/vscode-atopile/src/common/settings.ts

@@ -4,6 +4,11 @@
 import { ConfigurationChangeEvent, ConfigurationScope, WorkspaceConfiguration, WorkspaceFolder } from 'vscode';
 import { getInterpreterDetails } from './python';
 import { getConfiguration, getWorkspaceFolders } from './vscodeapi';
+import { promisify } from 'util';
+import { exec } from 'node:child_process';
+import { traceError, traceLog } from './log/logging';
+
+const async_exec = promisify(exec);
 
 export interface ISettings {
     cwd: string;
@@ -56,8 +61,19 @@ export async function getWorkspaceSettings(
     let interpreter: string[] = [];
     if (includeInterpreter) {
         interpreter = getInterpreterFromSetting(namespace, workspace) ?? [];
+
+        // If no interpreter is set, try to get it from the ato command
         if (interpreter.length === 0) {
-            interpreter = (await getInterpreterDetails(workspace.uri)).path ?? [];
+            try {
+                const { stdout, stderr } = await async_exec('ato --python-path');
+                interpreter = [stdout.trim()];
+            } catch (error) {
+                traceError('Error getting interpreter from ato --python-path: ', error);
+                throw error;
+            }
+            traceLog(`Using interpreter from ato --python-path: ${interpreter.join(' ')}`);
+        } else {
+            traceLog(`Using interpreter from ${namespace}.interpreter: ${interpreter.join(' ')}`);
         }
     }