Better configuration setting, documentation

cricalix · cricalix · commit 36e222047440 · 2023-05-26T07:52:52.000+01:00
This is v0.1.2 of the plugin. It addresses some deficiencies in the documentation, and deals with configuration pass-through from the language server more correctly.

* Adds docs/Configuration.md to detail what configuration options are supported
* Updates docs/kate.md to detail how to pass settings from Kate's LSP config structure
* Updates README.md with more precise details about the configuration
* Updates README.md with more links, reflowed text, reorganised text
* Updates the plugin to default the configuration as "enabled, but don't create pyre config"
* Updates the plugin to log when the pyre config option is somehow missing
* Moves the pyre config file creation out of the `initialize` hook and into the point before running Pyre
* Decorates error messages with the plugin name
diff --git a/README.md b/README.md
@@ -1,10 +1,8 @@
 # python-lsp-pyre
 
-Implements support for calling Meta's [Pyre type checker](https://github.com/facebook/pyre-check) via a subprocess.
-
 This is a plugin for the [Python LSP Server](https://github.com/python-lsp/python-lsp-server).
 
-It was written to scratch an itch, so may not be quite what you're looking for.
+It implements support for calling Meta's [Pyre type checker](https://github.com/facebook/pyre-check) via a subprocess.
 
 ## Installation
 
@@ -20,16 +18,17 @@ or to make it a development requirement in Poetry
 poetry add -G dev python-lsp-pyre
 ```
 
-Then run `python-lsp-server` as usual, the plugin will be auto-discovered by
-`python-lsp-server` if you've installed it to the right environment. Refer to
-`python-lsp-server` and your IDE/text editor documentation on how to setup
-`python-lsp-server`. An example is provided for KDE's [Kate editor](/docs/kate.md).
+Then run `python-lsp-server` as usual, the plugin will be auto-discovered by `python-lsp-server` if you've installed it to the right environment. Refer to `python-lsp-server` and your IDE/text editor documentation on how to setup `python-lsp-server`. The plugin's default `enabled` status is `True`.
+
+## Editor integration
+
+* An example is provided for KDE's [Kate editor](/docs/kate.md)
 
 ## Configuration
 
 Meta's Pyre uses `.pyre_configuration` files in your project to set up lint controls. It does not read `pyproject.toml`.
 
-On first run of this plugin, it will detect a missing `.pyre_configuration`, and write out one for you. It relies on the workspace root passed to the language server for this write. This file is not immutable, and the [reference documentation](https://pyre-check.org/docs/configuration/) may be useful.
+On first run of this plugin, it will detect a missing `.pyre_configuration` and write out one for you if the `create-pyre-config` [configuration](docs/Configuration.md) option is enabled. It relies on the workspace root passed to the language server for this write. This file is not immutable, and the [reference documentation](https://pyre-check.org/docs/configuration/) may be useful.
 
 You can also use `pyre init` instead to set up the configuration.
 
@@ -50,9 +49,11 @@ The configuration written by this plugin is:
 
 The noteable difference from `pyre init` is the change to the search strategy (pep561 to all).
 
+If the file is not present, the LSP error log, LSP output, and your editor's LSP messages will display an ABEND message containing the error from Pyre as it fails to run.
+
 ## Features
 
-This plugin adds the following features to `pylsp`:
+This plugin adds the following features to `python-lsp-server`:
 
 - Type linting via Meta's Pyre (pyre-check)
 
@@ -67,8 +68,17 @@ pip install -e '.[dev]'
 ```
 
 Alterately, if you use Poetry,
-```
+
+```bash
+git clone https://github.com/cricalix/python-lsp-pyre python-lsp-pyre
+cd python-lsp-pyre
 poetry install
 ```
 
 will set up a virtualenv if necessary, install all dependencies, and then install this project in editable/development mode.
+
+## Contributing
+
+This plugin was written to scratch an itch. If you find it useful, great!
+
+If something about it annoys you, or you think there's a better way to do something, you're welcome to send a PR.
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -0,0 +1,11 @@
+# Configuration
+
+Like other Python Language Server plugins, configuration of the plugin is achieved by sending settings to the server from the client via `workplace/didChangeConfiguration`.
+
+This plugin recognises the following configuration options.
+
+| Key | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `pylsp.plugins.pyre.enabled` | `boolean` | True | Enable or disable this plugin. |
+| `pylsp.plugins.pyre.create-pyre-config` | `boolean` | False | Whether to create a default .pyre_configuration file |
+
diff --git a/docs/kate.md b/docs/kate.md
@@ -8,14 +8,25 @@ In Settings > LSP Client > User Server Settings (normally found at `$USER/.confi
 
 ```json
 {
-    "servers": {
-        "python": {
-            "command": ["poetry", "run", "pylsp", "--check-parent-process" ],
-            "rootIndicationFileNames": ["poetry.lock", "pyproject.toml"],
-            "url": "https://github.com/python-lsp/python-lsp-server",
-            "highlightingModeRegex": "^Python$"
-        }
+  "servers": {
+    "python": {
+      "command": [
+        "poetry",
+        "run",
+        "pylsp",
+        "--check-parent-process",
+        "--verbose",
+        "--log-file",
+        "/tmp/pylsp"
+      ],
+      "rootIndicationFileNames": [
+        "poetry.lock",
+        "pyproject.toml"
+      ],
+      "url": "https://github.com/python-lsp/python-lsp-server",
+      "highlightingModeRegex": "^Python$"
     }
+  }
 }
 ```
 
@@ -28,3 +39,26 @@ If you wish to have a log file then add `, "--log-file", "/tmp/pylsp"` after `--
 The Python Language Server documentation supercedes the above instructions.
 
 The **rootIndicationFileNames** entry is used to ensure that the correct root directory is passed to the language server on requests for linting etcetera, assuming that the project has a **pyproject.toml** file.
+
+To pass [configuration options](Configuration.md) to the server, use the `settings` sub-key, splitting out each component of the key on the dot to make it a JSON structure key.
+
+For example, `pylsp.plugins.pyre.create-pyre-config` would be converted to:
+
+```json
+{
+  "servers": {
+    "python": {
+      "command": ["..."],
+      "settings": {
+        "pylsp": {
+          "plugins": {
+            "pyre": {
+              "create-pyre-config": true
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
diff --git a/pylsp_pyre/plugin.py b/pylsp_pyre/plugin.py
@@ -6,68 +6,44 @@
 
 import lsprotocol.converters as lsp_con
 import lsprotocol.types as lsp_types
+import pylsp.config.config as pylsp_conf
 import pylsp.lsp as pylsp_lsp
 import pylsp.workspace as pylsp_ws
 import pyre_check.client.language_server.protocol as pyre_proto
 from pylsp import hookimpl
-from pylsp.config.config import Config
 
 logger: logging.Logger = logging.getLogger(__name__)
+# A logging prefix.
+PLUGIN: str = "[python-lsp-pyre]"
 
 
 @hookimpl
-def pylsp_settings() -> Dict[str, Dict[str, Dict[str, bool]]]:
+def pylsp_settings(config: pylsp_conf.Config) -> Dict[str, Dict[str, Dict[str, bool]]]:
+    """
+    Default configuration for the plugin. Ensures all keys are set.
+    """
     return {
         "plugins": {
             "pyre": {
                 "enabled": True,
-                "auto-config": True,
+                "create-pyre-config": False,
             }
         }
     }
 
 
-@hookimpl
-def pylsp_initialize(config: Config, workspace: pylsp_ws.Workspace) -> None:
-    """
-    Checks for a Pyre configuration existence.
-
-    Runs on plugin init, relies on the workspace document root to know where to look for
-    the config file.
-    """
-    default_config = json.loads(
-        """
-        {
-      "site_package_search_strategy": "all",
-      "source_directories": [
-        "."
-      ],
-      "exclude": [
-        "\/setup.py",
-        ".*\/build\/.*"
-      ]
-    }
-    """
-    )
-    settings = config.plugin_settings("pyre")
-    if settings["auto-config"]:
-        docroot = workspace.root_path
-        path = Path(docroot).joinpath(".pyre_configuration")
-        if not path.exists():
-            logger.info(f"Initializing {path}")
-            with path.open(mode="w") as f:
-                f.write(json.dumps(default_config, indent=4))
-                f.write("\n")
-
-
 @hookimpl
 def pylsp_lint(
-    config: Config, workspace: pylsp_ws.Workspace, document: pylsp_ws.Document, is_saved: bool
+    config: pylsp_conf.Config,
+    workspace: pylsp_ws.Workspace,
+    document: pylsp_ws.Document,
+    is_saved: bool,
 ) -> List[Dict[str, Any]]:
     """
     Lints files (saved, not in-progress) and returns found problems.
     """
     logger.debug(f"Working with {document.path}, {is_saved=}")
+    maybe_create_pyre_config(config=config, workspace=workspace)
     if is_saved:
         with workspace.report_progress("lint: pyre check", "running"):
             settings = config.plugin_settings("pyre")
@@ -86,8 +62,10 @@ def abend(message: str, workspace: pylsp_ws.Workspace) -> Dict[str, Any]:
     Basically, make it visible in as many ways as possible - logging, workspace messaging, and
     actual lint results.
     """
-    logger.exception(message)
-    workspace.show_message(message=message, msg_type=pylsp_lsp.MessageType.Error)
+    logger.exception(f"{PLUGIN} {message}")
+    workspace.show_message(
+        message=f"{PLUGIN} {message}", msg_type=pylsp_lsp.MessageType.Error
+    )
     return {
         "source": "pyre",
         "severity": lsp_types.DiagnosticSeverity.Error,
@@ -156,3 +134,42 @@ def really_run_pyre(root_path: str) -> bytes:
         if e.returncode in (0, 1):
             return e.output
         raise
+
+
+def maybe_create_pyre_config(
+    config: pylsp_conf.Config, workspace: pylsp_ws.Workspace
+) -> None:
+    """
+    Initializes a .pyre_configuration file if `create-pyre-config` setting is enabled.
+
+    Only initializes if the file is missing.
+    """
+    default_config = json.loads(
+        """
+        {
+      "site_package_search_strategy": "all",
+      "source_directories": [
+        "."
+      ],
+      "exclude": [
+        "\/setup.py",
+        ".*\/build\/.*"
+      ]
+    }
+    """
+    )
+    settings = config.plugin_settings("pyre")
+    try:
+        if settings["create-pyre-config"]:
+            docroot = workspace.root_path
+            path = Path(docroot).joinpath(".pyre_configuration")
+            if not path.exists():
+                logger.info(f"Initializing {path}")
+                with path.open(mode="w") as f:
+                    f.write(json.dumps(default_config, indent=4))
+                    f.write("\n")
+
+    except KeyError:
+        message = f"{PLUGIN} create-pyre-config setting not found in dictionary"
+        logger.exception(message)
+        workspace.show_message(message=message, msg_type=pylsp_lsp.MessageType.Warning)
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-lsp-pyre"
-version = "0.1.1"
+version = "0.1.2"
 description = "Pyre linting plugin for pylsp"
 authors = ["Duncan Hill <python.projects@cricalix.net>"]
 license = "MIT"
