Merge pull request #114 from darrenburns/v2

V2

.github/workflows/test.yml

@@ -28,7 +28,7 @@ jobs:
         run: uv sync --all-extras --dev
       - name: Run Tests
         run: |
-            uv run make test
+            uv run make test-ci
       - name: Attach Code Coverage
         uses: py-cov-action/[email protected]
         with:

Makefile

@@ -9,8 +9,7 @@ test-snapshot-update:
 	$(run) pytest --cov=posting tests/ -n 16 -m "not serial" --snapshot-update $(ARGS)
 	$(run) pytest --cov-report term-missing --cov-append --cov=posting tests/ -m serial --snapshot-update $(ARGS)
 
-.PHONY: deploy
-deploy:
-	rye sync
-	rye build --clean
-	rye publish -y
+
+.PHONY: test-ci
+test-ci:
+	$(run) pytest --cov=posting tests/ --cov-report term-missing $(ARGS)

README.md

@@ -13,7 +13,9 @@ Some notable features include:
 - autocompletion
 - syntax highlighting using tree-sitter
 - Vim keys
+- customizable keybindings
 - user-defined themes
+- run Python code before and after requests
 - configuration
 - "open in $EDITOR"
 - a command palette for quickly accessing functionality
@@ -22,28 +24,27 @@ Visit the [website](https://posting.sh) for more information, the roadmap, and t
 
 ## Installation
 
-Posting can be installed via [`pipx`](https://pipx.pypa.io/stable/) or [Rye](https://rye-up.com/guide/installation) on MacOS, Linux, and Windows:
+Posting can be installed via [uv](https://docs.astral.sh/uv/getting-started/installation/) on MacOS, Linux, and Windows.
 
-```bash
-pipx install posting
-# or
-rye install posting
-```
-
-### Rye is recommended
+`uv` is a single Rust binary that you can use to install Python apps. It's significantly faster than alternative tools, and will get you up and running with Posting in seconds.
 
-Rye is recommended, as it is significantly faster than Homebrew and `pipx`, and can install Posting in under a second.
+You don't even need to worry about installing Python yourself - `uv` will manage everything for you.
 
 ```bash
 # quick install on MacOS/Linux
-curl -sSf https://rye.astral.sh/get | bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# install Posting
-rye install posting
+# install Posting (will also quickly install Python 3.12 if needed)
+uv tool install --python 3.12 posting
 ```
 
-Windows users should follow the guide [Rye](https://rye-up.com/guide/installation) to learn how to install Rye.
+`uv` can also be installed via Homebrew, Cargo, Winget, pipx, and more. See the [installation guide](https://docs.astral.sh/uv/getting-started/installation/) for more information.
+
+`uv` also makes it easy to install additional Python packages into your Posting environment, which you can then use in your pre-request/post-response scripts.
+
+### Prefer `pipx`?
 
+If you'd prefer to use `pipx`, that works too: `pipx install posting`.
 
 ## Learn More
 

docs/CHANGELOG.md

@@ -1,3 +1,38 @@
+## 2.0.0 [18th October 2024]
+
+### Added
+
+- **Scripting**: Run Python scripts before and after sending requests. Scripts can be used to perform setup, set variables, modify requests, and more.
+    - Define "setup", "pre-request" and "post-request" Python functions and attach them to requests.
+    - Posting will automatically reload these functions when they change, meaning you can edit them in an external editor while Posting is running.
+    - Scripts can be used to directly manipulate the request, set variables which are used in the request (e.g. set a `$token` variable which is used in the request URL).
+    - Output from scripts is captured and displayed in the "Scripts" tab.
+- **Keymaps**: Change the default keybindings for any of Posting's "global" actions (e.g. sending request, opening jump mode, etc.) by editing `keymap` section of your `config.yaml` file.
+- Added `heading.hostname` config to allow customisation of the hostname in the header. This field supports Rich markup. You may wish to use this to apply highlighting when `posting` is running on a production system vs a development environment, for example.
+- Added `focus.on_request_open` config to automatically shift focus when a request is opened via the collection browser. For example, you might prefer to have focus jump to the "Body" tab when a request is opened.
+- More detail and screenshots added to several sections of the guide.
+    - Much more detail added to the "Getting Started" section.
+    - Collections guide updated to explain more about the collection browser.
+    - Guide for Keymaps added.
+    - Guide for Scripting added.
+    - Guide for External Tools added (integrating with vim, less, fx, etc.)
+- `alt`+`enter` can now be used to send a request (in addition to the existing `ctrl+j` binding).
+- Tooltips added to more actions in the app footer. These appear on mouse hover.
+
+### Changed
+
+- Automatically apply `content-type` header based on the body type selected in the UI.
+- Updated to Textual 0.83.0
+- Various refinements to autocompletion, upgrading to textual-autocomplete 3.0.0a12.
+- Dependency specifications loosened on several dependencies.
+- Recommended installation method changed from rye to uv.
+
+### Fixed
+
+- Fixed double rendering in "jump mode" overlay.
+- Fixed sidebar not working on mobile on https://posting.sh
+- Fixed autocompletion appearing when on 1 item in the list and the "search string" is equal to that item.
+
 ## 1.13.0 [8th September 2024]
 
 ### Added

docs/guide/collections.md

@@ -7,10 +7,42 @@ It contains no "special files" or metadata -- it's just a directory.
 It could even be empty.
 "Collection" is simply the name we give to the directory which we've loaded into Posting.
 
+## The collection browser
+
+Posting displays the currently open collection in the sidebar.
+This is called the *collection browser*.
+
+![Posting collection tree](../assets/collection-tree.png){ height=300px }
+
+The name of the currently open collection is displayed in the bottom right corner of the collection browser.
+In the example above, the collection is named "sample-collection".
+
+You can navigate this sidebar using the keyboard or mouse.
+Open a request by clicking on it or pressing ++enter++ while it has focus,
+and it'll be loaded into the main body of the UI.
+A marker will also appear to the left of the request's title, indicating that the request is open.
+A save operation will overwrite the currently open request.
+
+!!! example "Keyboard shortcuts"
+
+    The collection browser supports various keyboard shortcuts for quick navigation. For example ++shift+j++ and ++shift+k++ can be used to jump through sub-collections.
+    Press ++f1++ while the browser has focus to view the full list of shortcuts.
+
+
+The collection browser can be moved to the left or right side of the screen by setting the `collection_browser.position` configuration option
+to either `"left"` or `"right"`.
+
 ## The default collection
 
-If you launch Posting without any arguments, it will load the *default collection*, which is stored in Posting's reserved data directory on your file system.
+If you launch Posting without a `--collection` argument, it will load the *default collection*, which is stored in Posting's reserved data directory on your file system.
+
+The default collection can be thought of as a *system wide collection*.
+It's a place to keep useful requests that you can easily access from anywhere, without having to manually specify a `--collection` argument.
+
 You can check where this is by running `posting locate collection`.
+The default collection is named "default", that name will be displayed in the bottom right corner of the collection browser.
+
+![Posting default collection](../assets/default-collection.png)
 
 This is useful to get started quickly, but you'll probably want to create your own collection directory and load it instead.
 This makes it easier to organize your requests and check them into version control.
@@ -19,6 +51,8 @@ This makes it easier to organize your requests and check them into version contr
 
 A collection is just a directory, so you can create a collection by simply creating an empty directory anywhere on your file system.
 
+With the directory created, it's time to load it into Posting...
+
 ## Loading a collection
 
 If you want to load a collection, you can do so by passing the path to the collection directory to Posting:
@@ -27,9 +61,7 @@ If you want to load a collection, you can do so by passing the path to the colle
 posting --collection path/to/collection
 ```
 
-## Example
-
-
+### Example
 
 To open a collection (a directory containing requests), use the `--collection` option:
 
@@ -39,4 +71,4 @@ posting --collection path/to/collection
 
 This will recursively find and display requests in the sidebar.
 If you don't supply a directory, Posting will use the default collection directory.
-You can check where this is by running `posting locate collection`.
+You can check where the default collection is by running `posting locate collection`.

docs/guide/command_palette.md

@@ -9,4 +9,3 @@ It can be used to switch themes, show/hide parts of the UI, and more.
 ### Using the command palette
 
 Press ++ctrl+p++ to open the command palette.
-

docs/guide/configuration.md

@@ -117,6 +117,7 @@ The table below lists all available configuration options and their environment
 | `heading.visible` (`POSTING_HEADING__VISIBLE`) | `true`, `false` (Default: `true`) | Show/hide the app header. |
 | `heading.show_host` (`POSTING_HEADING__SHOW_HOST`) | `true`, `false` (Default: `true`) | Show/hide the hostname in the app header. |
 | `heading.show_version` (`POSTING_HEADING__SHOW_VERSION`) | `true`, `false` (Default: `true`) | Show/hide the version in the app header. |
+| `heading.hostname` (`POSTING_HEADING__HOSTNAME`) | (Default: `unset`) | The hostname to display in the app header. You may use Rich markup here. If unset, the hostname provided via `socket.gethostname()` will be used. |
 | `url_bar.show_value_preview` (`POSTING_URL_BAR__SHOW_VALUE_PREVIEW`) | `true`, `false` (Default: `true`) | Show/hide the variable value preview below the URL bar. |
 | `collection_browser.position` (`POSTING_COLLECTION_BROWSER__POSITION`) | `"left"`, `"right"` (Default: `"left"`) | The position of the collection browser on screen. |
 | `collection_browser.show_on_startup` (`POSTING_COLLECTION_BROWSER__SHOW_ON_STARTUP`) | `true`, `false` (Default: `true`) | Show/hide the collection browser on startup. Can always be toggled using the command palette. |
@@ -129,6 +130,7 @@ The table below lists all available configuration options and their environment
 | `ssl.password` (`POSTING_SSL__PASSWORD`) | Password for the key file. (Default: `unset`) | Password to decrypt the key file if it's encrypted. |
 | `focus.on_startup` (`POSTING_FOCUS__ON_STARTUP`) | `"url"`, `"method", "collection"` (Default: `"url"`) | Automatically focus the URL bar, method, or collection browser when the app starts. |
 | `focus.on_response` (`POSTING_FOCUS__ON_RESPONSE`) | `"body"`, `"tabs"` (Default: `unset`)| Automatically focus the response tabs or response body text area when a response is received. |
+| `focus.on_request_open` (`POSTING_FOCUS__ON_REQUEST_OPEN`) | `"headers"`, `"body"`, `"query"`, `"info"`, `"url"`, `"method"` (Default: `unset`) | Automatically focus the specified target when a request is opened from the collection browser. |
 | `text_input.blinking_cursor` (`POSTING_TEXT_INPUT__BLINKING_CURSOR`) | `true`, `false` (Default: `true`) | If enabled, the cursor will blink in input widgets and text area widgets. |
 | `command_palette.theme_preview` (`POSTING_COMMAND_PALETTE__THEME_PREVIEW`) | `true`, `false` (Default: `false`) | If enabled, the command palette will display a preview of the selected theme when the cursor is over it. This will slow down cursor movement and so is disabled by default. |
 | `use_xresources` (`POSTING_USE_XRESOURCES`) | `true`, `false` (Default: `false`) | Try to create themes called `xresources-dark` and `xresources-light` (see the section below) |

docs/guide/external_tools.md

@@ -0,0 +1,65 @@
+## Overview
+
+You can quickly switch between Posting and external editors and pagers.
+
+For example, you could edit request bodies in `vim`, and then browse the JSON response body in `less` or `fx`.
+
+You can even configure a custom pager specifically for browsing JSON.
+
+## External Editors
+
+With a multi-line text area focused, press ++f4++ to open the file in your
+configured external editor.
+
+The configured external editor can be set as `editor` in your `config.yaml`
+file.
+For example:
+
+```yaml title="config.yaml"
+editor: vim
+```
+
+Alternatively, you can set the `POSTING_EDITOR` environment variable.
+
+```bash
+POSTING_EDITOR=vim
+```
+
+If neither is set, Posting will try to use the `EDITOR` environment variable.
+
+## External Pagers
+
+With a multi-line text area focused, press ++f3++ to open the file in your
+configured external pager.
+
+The configured external pager can be set as `pager` in your `config.yaml`
+file.
+For example:
+
+```yaml title="config.yaml"
+pager: less
+```
+
+Alternatively, you can set the `POSTING_PAGER` environment variable.
+
+```bash
+POSTING_PAGER=less
+```
+
+### JSON Pager
+
+You can use a custom pager for viewing JSON using the `pager_json` setting in
+your `config.yaml` file.
+For example:
+
+```yaml title="config.yaml"
+pager_json: jq
+```
+
+Alternatively, you can set the `POSTING_PAGER_JSON` environment variable.
+
+```bash
+POSTING_PAGER_JSON=jq
+```
+
+If neither is set, Posting will try to use the default pager lookup rules discussed earlier.