Merge pull request #2 from lopezvoliver/run

Run GEE scripts in vscode! and performance improvement

CHANGELOG.md

@@ -8,4 +8,11 @@
         | Id | Type | Description | State | CreateTime | EndTime | BatchEECU |  
         | --- | --- | --- | --- | --- | --- | --- |  
 
-    - Provides "EE Tasks: update gcloud accounts list". Only required after using `gcloud` to authenticate additional users. This is done automatically the first time the extension is activated (if `gcloud` is available). 
+    - Provides "EE Tasks: update gcloud accounts list". Only required after using `gcloud` to authenticate additional users. This is done automatically the first time the extension is activated (if `gcloud` is available). 
+
+## v0.1.0
+
+- Major internal changes to improve performance
+- New feature: run a GEE script from vscode! see documentation [here](https://github.com/gee-community/eetasks/blob/main/docs/runGEEscripts.md)
+- Fixed a [bug](https://github.com/gee-community/eetasks/issues/1) that prevented the EndTime and BatchEECU columns to display. 
+- Renamed the `EE Tasks: update gcloud accounts list` command to `EE Tasks: update available accounts`. This reflects an implementation change that simplifies and groups all accounts (gcloud and "earthengine").  

README.md

@@ -4,43 +4,60 @@ An extension for monitoring Earth Engine tasks.
 
 ## Features
 
-![eetasks-readme](https://raw.githubusercontent.com/lopezvoliver/eetasks/main/eetasks-readme.gif)
+### EE Tasks: view tasks
+
+![eetasks-readme](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/eetasks-readme.gif)
 
 Open a table view of Earth Engine tasks for a user or service account. 
 
+### EE Tasks: run GEE script
+
+![eetasks-readme](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/geerunExample.gif)
+
+Run GEE code from within vscode! Learn more about what is [currently supported here](https://github.com/gee-community/eetasks/blob/main/docs/runGEEscripts.md). 
+
+### EE Tasks: update available accounts
+
+Use this command if you expect to use this extension for [multiple accounts](#multi-account-views). The command is run automatically upon first use of either the [view tasks](#ee-tasks-view) or [run gee script](#ee-tasks-run-gee-script) commands. 
+
 ## Requirements
 
 A [Google Earth Engine account](https://code.earthengine.google.com/register) is required to use the Earth Engine Tasks Manager extension. Additionally, either the [Earth Engine command line tool](https://developers.google.com/earth-engine/guides/command_line) (eecli) or the Earth Engine [python client library](https://developers.google.com/earth-engine/guides/python_install) must have been used to authenticate an account. If you are familiar with the [gcloud cli](https://cloud.google.com/sdk/docs/install) and have already [authenticated](https://cloud.google.com/sdk/gcloud/reference/auth/login) an earth engine account, you can also use `gcloud` to authenticate the Earth Engine library for this extension. 
 
 ### Multi-account views
 
-![eetasks-multi](https://raw.githubusercontent.com/lopezvoliver/eetasks/main/eetasks-multi.png)
-
-Multiple panels may be opened to view the tasks for different users.
+![eetasks-multi](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/eetasks-multi.png)
 
+Multiple panels may be opened to view the tasks for different accounts. 
 
 #### Interactive account selection
 
-![eetasks-users](https://raw.githubusercontent.com/lopezvoliver/eetasks/main/eetasks-users.png)
+The available user accounts are populated using the [EE Tasks: update available accounts](#ee-tasks-update-available-accounts) command at any time. This command is automatically called upon the first time you run either the [EE Tasks: view tasks](#ee-tasks-view-tasks) or the [EE Tasks: run GEE script](#ee-tasks-run-gee-script) commads.
 
-Use the `EE Tasks: view tasks` command to interactively select a user account. 
+![eetasks-users](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/eetasks-users.png)
 
-The `earthengine` account refers to the credentials stored and managed by the earthengine Python API. The EE tasks extensions will never modify these credentials. 
+The `earthengine` account refers to the credentials stored and managed by the earthengine Python API. The EE Tasks extension will not modify these credentials. 
 
-The other accounts shown (if any) are managed by the `gcloud cli` (as well as the earthengine cli through `gcloud`). You can use `gcloud auth login` to add an additional user, and `gcloud auth list` to display the accounts. The first time the EE tasks extension is activated, it will look for these accounts. If you have updated the credentialed accounts with `gcloud`, update them in the extension by using the `EE tasks: update gcloud accounts list`.
+The `application-default` account refers to the
+[application default credentials](https://cloud.google.com/sdk/gcloud/reference/auth/application-default) in `gcloud`.
+
+The other accounts shown (if any) are managed by the `gcloud cli` (as well as the earthengine cli through `gcloud`). You can use `gcloud auth login` to add an additional user, and `gcloud auth list` to display the accounts. If you update the credentialed accounts with `gcloud`, update them in the extension by using the [EE Tasks: update available accounts](#ee-tasks-update-available-accounts). 
 
 When selecting an account other than `earthengine`, you will also be prompted to specify a project to use. 
 
 #### Default account
 
-![eetasks-default](https://raw.githubusercontent.com/lopezvoliver/eetasks/main/eetasks-default.png)
+![eetasks-default](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/eetasks-default.png)
+
+You may also specify a default account and project to use with the `EE tasks: view tasks (default account)`. You may specify any of the available accounts. 
 
-You may also specify a default account and project to use with the `EE tasks: view tasks (defaut account)`. Set the default account to `earthengine` to use the credentials managed by the eecli or python library, in which case there is no need to specify a project. You may also specify `application-default` to use the [application default credentials](https://cloud.google.com/sdk/gcloud/reference/auth/application-default). If the project is left blank and the account is not `earthengine`, you will be prompted for it. If the account is blank, you will prompted for it. Specifying an account that is not any of `earthengine`, `application-default`, or in the `gcloud auth list` will result in an error. 
+If the project is left blank and the account is not `earthengine`, you will be prompted for it. If the account is blank, you will prompted for it. Specifying an account that is not any of the available accounts will not work. 
 
 #### Service account (advanced use)
 
-Use the `EE tasks: view tasks (service account)` to view the tasks associated to a [service account](https://developers.google.com/earth-engine/guides/service_account). You wil be prompted to select a `json` file ([see the animation](#features) above).
+Use the `EE Tasks: view tasks (service account)` to view the tasks associated to a [service account](https://developers.google.com/earth-engine/guides/service_account). You wil be prompted to select a `json` file ([see the animation](#features) above).
 
+There is also a variation of the [EE Tasks: run GEE script](#ee-tasks-run-gee-script) command to use a service account instead of a user account. 
 
 ## Extension Settings
 
@@ -55,6 +72,6 @@ This extension contributes the following settings:
 
 ## Known Issues
 
-- Tested in linux and windows.  
 - The tasks tables do not refresh automatically. However, you can use the refresh button (🔄) to update the table on demand. 
-- The gcloud accounts lists is retrieved automatically only the first time the extension is activated. However, you can use the `EE tasks: update gcloud accounts list` to update it. 
+- The intended use for the `EE Tasks: run GEE script` is lmited and currently experimental (recommended for experienced users only). [Learn more about it here](https://github.com/gee-community/eetasks/blob/main/docs/runGEEscripts.md).
+    - An unknown cause for an issue prevents the use of synchronous calls to some `ee` functions in Windows. Learn more about it [here](https://github.com/gee-community/eetasks/blob/main/docs/runGEEscripts.md#caveat-for-windows-users)

docs/runGEEscripts.md

@@ -0,0 +1,112 @@
+# Run GEE scripts from vscode!
+
+## Hello world
+
+Use the `EE Tasks: run GEE script` command to run the GEE script open in the Editor using a user account/project. For example:
+
+![hellogee](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/helloGEE.PNG)
+
+
+> The `EE Tasks: run GEE script (service account)` is also available to run scripts using a valid private key (JSON file). 
+
+upon picking an available account (and project, if required), the script is started. If successful, the output will open in a channel called "EE Tasks: GEE script runs":
+
+![hellogee-log](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/helloGEE-log.png)
+
+## GEE script definition
+
+For the purpose of this document, a "GEE script" is a `.js` file that is able to run in the [Earth Engine Code Editor](https://developers.google.com/earth-engine/guides/playground). 
+
+> ❗ Not all GEE scripts can be run here. More details will be given below. 
+
+How does the [hello-world](#hello-world) example above work? Evidently, running the same script directly in [node](https://nodejs.org/en/) will not work:
+
+```bash
+$ node helloGEE.js 
+C:\Users\lopezom\helloGEE.js:1
+ee.String("Hello world!")
+^
+
+ReferenceError: ee is not defined
+```
+
+Internally, the EE Tasks extension wraps your code in a function that handles the initialization of ee, as well as providing *some* of the extra features in the [Earth Engine Code Editor](https://developers.google.com/earth-engine/guides/playground), including [print](https://developers.google.com/earth-engine/apidocs/print) and `Export` (e.g. [Export.table.toDrive](https://developers.google.com/earth-engine/apidocs/export-table-todrive)). See more details of what features are [included](#features) and which ones are [excluded](#excluded-features). 
+
+
+## Use cases 
+
+Why would I want to run a GEE script in vscode? Short answer: [just because I can](https://i.kym-cdn.com/entries/icons/original/000/040/653/goldblum-quote.jpeg). Kidding aside, the goal here is to provide a quick way for developers to test short, simple code, and to submit Export tasks without leaving vscode. 
+
+> ❗ Use of `EE Tasks: run GEE script` is experimental and recommended for experienced GEE developers only. Not following [GEE coding best practices](https://developers.google.com/earth-engine/guides/best_practices) might lead to the extension crashing (e.g. the equivalent of [browser lock](https://developers.google.com/earth-engine/guides/debugging#browser-lock)). However, it's not the end of world, as a simple "Reload window" should get the extension running back to normal. 
+
+However, simple client-side errors will be catched:
+
+![hellogee-log](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/helloGEE-syntaxError.png)
+
+> ❗ See another [caveat for Windows users here](#caveat-for-windows-users).
+
+## Not recommended use cases
+
+Outside of the specific use-cases defined above, **it is not recommended to run GEE scripts using the EE Tasks extension**. The [Code Editor](https://code.earthengine.google.com) or [geemap](https://geemap.org) are definitely the right tools for exploratory analyses, debugging, etc. 
+
+## Features 
+
+### `print`
+
+`print` somewhat mirrors the functionality of [print](https://developers.google.com/earth-engine/apidocs/print) in the Code Editor:
+
+>  ⚠️ An important difference is that when objects that have a `getInfo` get printed, the operation is performed asynchronously, so the order is not guaranteed ❗
+
+![ExportTableSuccessFail](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/print.png)
+
+> ⚠️ In windows, do not use the `.getInfo` methods directly. [Here's why](#caveat-for-windows-users). In linux, this shouldn't be an issue.  
+
+### `Export`
+
+All `Export` features mirror the functionality from the [Code Editor](https://developers.google.com/earth-engine/guides/debugging#browser-lock) (in fact, they [wrap](https://github.com/gee-community/eetasks/blob/main/src/utilities/codeEditorUtils.js) the `ee.batch.Export*` methods). However, 
+
+> ⚠️ In contrast to the Code Editor, tasks will be automatically submitted.
+
+For example:
+
+![ExportTableSuccessFail](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/ExportTableSuccessAndFail.png)
+
+> ⚠️ Another contrast to the Code Editor can be seen in the example above. Some parameters such as `description`, `fileNamePrefix`, `assetId`, etc. are either given default values (e.g. "myExportTableTask") in the Code Editor, or are prompted from the user after clicking "Run". Here, the task fails to start if they are not provided explicitly.  
+
+We can then use the `EE Tasks: view` command to monitor the task:
+
+![ExportTableTaskCompleted](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/ExportTableTaskCompleted.png)
+
+We can see that the task completed, demonstrating task submission *and* monitoring from vscode!
+
+## Excluded features
+
+### `Map`, `Chart`, and `ui` 
+
+These are not supported here. However, lines of code using these features are silently ignored, so there is no need to exclude them:
+
+![silentlyIgnored](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/silentlyIgnored.png)
+
+Support for `Chart` and `Map` *may* be developed in the future. 
+
+### [require](https://developers.google.com/earth-engine/apicods/require)
+
+Importing a module directly from GEE (e.g. `require("users/homeFolder/repo:path/to/file)`) is not currently supported, and is unlikely to be developed soon. However, in some very *limited and specific* cases, one workaround is to (1) clone the git repository ([see how to here](https://gis.stackexchange.com/a/315134/67301)), and (2) change the line of code to use the absolute path to the local file instead. For example:
+
+![require](https://raw.githubusercontent.com/gee-community/eetasks/main/docs/assets/require.png)
+
+This silly example demonstrates the use of require with a local file. However, note that the `clonedGEErepo/test.js` file does not have access to `ee`, `print`, `Export`, etc.. so the script will fail if it attempts to access them. 
+
+The example above works because the function `addOne` does not use any of these, but it does allow using the methods within the objects passed as arguments (e.g. the `.add` method from the passed argument `ee.Number(1)`). A workaround would be to modify the functions to use within the module to require so that they allow passing `ee` (or other features to use) as arguments. 
+
+However.. if you are using `require` you are probably already doing something more complicated than the [recommended use cases](#use-cases) for `EE Tasks: run GEE script`. 
+
+## Caveat for windows users
+
+For some unknown reason, synchronous calls to some `ee` methods (e.g., most notably `getInfo`) do not work when running from vscode. Even stranger, this issue only occurs in windows. This is unlikely to be a bug with `ee` itself, as running the same code directly in `node` does work in Windows, so the issue is isolated to within vscode. 
+
+See more details in the [question](https://stackoverflow.com/questions/77436205/synchronous-function-call-to-external-library-within-vscode-freezes-only-in-wind) posted to StackOverflow, and if you have some insight please share it. 
+
+What happens when I use `getInfo` (or other method that accepts a callback function) synchronously through a GEE script in `EE Tasks: run GEE script` in windows? 
+
+Nothing really.. the error is not catched properly (there will be no message showing that the script run failed), but any other call to a `EE Tasks` extension will not work. A simple `Developer: Reload Window` will get the extension working back to normal. 

package.json

@@ -18,6 +18,14 @@
   "main": "./out/extension.js",
   "contributes": {
     "commands": [
+      {
+        "command": "eetasks.run",
+        "title": "EE Tasks: run GEE script"
+      },
+      {
+        "command": "eetasks.runAsServiceAccount",
+        "title": "EE Tasks: run GEE script (service account)"
+      },
       {
         "command": "eetasks.open",
         "title": "EE Tasks: view tasks"
@@ -31,8 +39,8 @@
         "title": "EE Tasks: view tasks (service account)"
       },
       {
-        "command": "eetasks.updateGcloudAccountsList",
-        "title": "EE Tasks: update gcloud accounts list"
+        "command": "eetasks.updateUserAccounts",
+        "title": "EE Tasks: update available accounts"
       }
     ],
     "configuration": {