API improvements

docs/guide/scripting.md

@@ -80,14 +80,20 @@ def setup(posting: Posting) -> None:
 
 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 `Request` object in this function, for example to set headers, query parameters, etc.
+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:
-    # Set a custom header on the request.
-    request.headers.append(
-        Header(name="X-Custom-Header", value="foo")
-    )
+    # 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")
 
     # This will be captured and written to the log.
     print("Request is being sent!")
@@ -103,6 +109,9 @@ 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)

src/posting/__init__.py

@@ -0,0 +1,26 @@
+from .collection import (
+    Auth,
+    Cookie,
+    Header,
+    QueryParam,
+    RequestBody,
+    RequestModel,
+    FormItem,
+    Options,
+    Scripts,
+)
+from .scripts import Posting
+
+
+__all__ = [
+    "Auth",
+    "Cookie",
+    "Header",
+    "QueryParam",
+    "RequestBody",
+    "RequestModel",
+    "FormItem",
+    "Options",
+    "Scripts",
+    "Posting",
+]

src/posting/collection.py

@@ -47,6 +47,16 @@ def to_httpx_auth(self) -> httpx.Auth | None:
             return httpx.DigestAuth(self.digest.username, self.digest.password)
         return None
 
+    @classmethod
+    def basic_auth(cls, username: str, password: str) -> Auth:
+        return cls(type="basic", basic=BasicAuth(username=username, password=password))
+
+    @classmethod
+    def digest_auth(cls, username: str, password: str) -> Auth:
+        return cls(
+            type="digest", digest=DigestAuth(username=username, password=password)
+        )
+
 
 class BasicAuth(BaseModel):
     username: str = Field(default="")
@@ -122,6 +132,11 @@ def request_sort_key(request: RequestModel) -> tuple[int, str]:
 
 
 class Scripts(BaseModel):
+    """The scripts associated with the request.
+
+    Paths are relative to the collection directory root.
+    """
+
     setup: str | None = Field(default=None)
     """A relative path to a script that will be run before the template is applied."""
 

tests/sample-collections/scripts/my_script.py

@@ -1,8 +1,7 @@
 import sys
 import httpx
 
-from posting.collection import Auth, BasicAuth, Header, RequestModel
-from posting.scripts import Posting
+from posting import Auth, Header, RequestModel, Posting
 
 
 def setup(posting: Posting) -> None:
@@ -17,7 +16,7 @@ def on_request(request: RequestModel, posting: Posting) -> None:
     request.headers.append(header)
     print(f"Set header:\n{header}!")
     # request.body.content = "asdf"
-    request.auth = Auth(type="basic", basic=BasicAuth(username="foo", password="bar"))
+    request.auth = Auth.basic_auth("username", "password")
     posting.notify(
         message="Hello from my_script.py!",
     )