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