1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
## Overview
You can attach simple Python scripts to requests inside the `Scripts` tab, and have Posting run them at various stages of the request lifecycle. This powerful feature allows you to:
- Perform setup before a request (e.g. setting variables, preparing data)
- Set or modify headers, query parameters, and other request properties
- Print logs and messages
- Set variables to be used in later requests (e.g. authentication tokens)
- Inspect request and response objects, and manipulate them
- Pretty much anything else you can think of doing with Python!
<img src="../../assets/scripts-tab.png" alt="Scripts tab" />
## Script types
Posting supports three types of scripts, which run at different points in the request/response lifecycle:
1. **Setup Scripts**: Runs before the request is constructed. This is useful for setting initial variables which may be substituted into the request.
2. **Pre-request Scripts**: Runs after the request has been constructed and variables have been substituted, but before the request is sent. You can directly modify the request object here.
3. **Post-response Scripts**: Runs after the response is received. This is useful for extracting data from the response, or for performing cleanup.
## Writing scripts
In the context of Posting, a "script" is a regular Python function.
By default, if you specify a path to a Python file, Posting will look for and execute the following functions at the appropriate times:
- `setup(posting: Posting) -> None`
- `on_request(request: RequestModel, posting: Posting) -> None`
- `on_response(response: httpx.Response, posting: Posting) -> None`
However, you can have Posting call any function you wish using the syntax `path/to/script.py:function_to_run`.
Note that relative paths are relative to the collection directory.
This ensures that if you place scripts inside your collection directory,
they're included when you share a collection with others.
Note that you do not need to specify all of the arguments when writing these functions. Posting will only pass the number of arguments that you've specified when it calls your function. For example, you could define a your `on_request` function as `def on_request(request: RequestModel) -> None` and Posting would call it with `on_request(request: RequestModel)` without passing the `posting` argument.
## Editing scripts
When you edit a script, it'll automatically be reloaded.
This means you can keep Posting open while editing it.
Posting also allows you to quickly jump to your editor (assuming you've set the `$EDITOR` or `$POSTING_EDITOR` environment variables) to edit a script.
Press ++ctrl+e++ while a script input field inside the `Scripts` tab is focused to open the path in your editor.
!!! warning
As of version 2.0.0, the script file must exist *before* pressing ++ctrl+e++. Posting will not create the file for you.
## Script logs
If your script writes to `stdout` or `stderr`, you'll see the output in the `Scripts` tab in the Response section.
This output is not persisted on disk.
### Example: Setup script
The **setup script** is run before the request is built.
You can set variables in the setup script that can be used in the request.
For example, you could use `httpx` to fetch an access token, then set the token as a variable so that it may be substituted into the request.
```python
def setup(posting: Posting) -> None:
# Set a variable which may be used in this request
# (or other requests to follow)
posting.set_variable("auth_token", "1234567890")
```
With this setup script attached to a request, you can then reference the `auth_token` variable in the request UI by typing `$auth_token`.
The `$auth_token` variable will remain for the duration of the session,
so you may wish to add a check to see if it has already been set in this session:
```python
def setup(posting: Posting) -> None:
if not posting.get_variable("auth_token"):
posting.set_variable("auth_token", "1234567890")
```
### Example: Pre-request script
The **pre-request script** is run after the request has been constructed and variables have been substituted, right before the request is sent.
You can directly modify the `RequestModel` object in this function, for example to set headers, query parameters, etc.
The code snippet below shows some of the API.
```python
from posting import Auth, Header, RequestModel, Posting
def on_request(request: RequestModel, posting: Posting) -> None:
# Add a custom header to the request.
request.headers.append(Header(name="X-Custom-Header", value="foo"))
# Set auth on the request.
request.auth = Auth.basic_auth("username", "password")
# request.auth = Auth.digest_auth("username", "password")
# request.auth = Auth.bearer_token_auth("token")
# This will be captured and written to the log.
print("Request is being sent!")
# Make a notification pop-up in the UI.
posting.notify("Request is being sent!")
```
### Example: Post-response script
The **post-response script** is run after the response is received.
You can use this to extract data from the response, for example a JWT token,
and set it as a variable to be used in later requests.
```python
from posting import Posting
def on_response(response: httpx.Response, posting: Posting) -> None:
# Print the status code of the response to the log.
print(response.status_code)
# Set a variable to be used in later requests.
# You can write '$auth_token' in the UI and it will be substituted with
# the value of the $auth_token variable.
posting.set_variable("auth_token", response.headers["Authorization"])
```
### The `Posting` object
The `Posting` object provides access to the application context and useful methods:
- `set_variable(name: str, value: object) -> None`: Set a session variable
- `get_variable(name: str, default: object | None = None) -> object | None`: Get a session variable
- `clear_variable(name: str) -> None`: Clear a specific session variable
- `clear_all_variables() -> None`: Clear all session variables
- `notify(message: str, title: str = "", severity: str = "information", timeout: float | None = None)`: Send a notification to the user
Note that variables are described as "session variables" because they persist for the duration of the session (until you close Posting).
### Execution environment
Scripts run in the same process and environment as Posting, so you should take care to avoid performing damaging global operations such as monkey-patching standard library modules.
#### Libraries
You can make use of any library that is available in the Python environment that Posting is running in. This means you can use all of the Python standard library as well as any of Posting's dependencies (such as `httpx`, `pyyaml`, `pydantic`, etc).
If you install Posting with `uv`, you can easily add extra dependencies which you can then use in your scripts:
```bash
uv tool install posting --with <library-name>
```
|
