pycamel 2.1.0

Headers

Every router starts with the Content-Type: application/json header. You can change it in three ways:

# 1. Set default headers once, when the router is created
admin_users = data_service_maker_v1.make_router(
    '/admin/users', default_headers={"X-Role": "admin"}
)

# 2. Replace all headers for the next request only
statistic_route.set_headers({"Accept": "application/xml"}).get()

# 3. Add/override a single header for the next request only
statistic_route.append_header("X-Request-Id", "abc-123").get()

set_headers/append_header only apply to the next request - the router resets back to its default headers right after the request is sent.

Filters and query params

# localhost/api/users?age=22&gender=male&name_in=Inna,Erich
statistic_route.set_filters({
    "age": 22,
    "gender": "male",
    "name_in": ["Inna", "Erich"]
}).get()

Anything the requests library accepts as a keyword argument works too, for example .get(params={"page": 1}), .post(json={...}), .post(data={...}), .get(timeout=5). The only kwargs you cannot pass directly are url and headers - use .add_to_path()/ .set_filters() and .set_headers()/.append_header() instead.

Validating a response against a pydantic schema

from typing import Optional
from pydantic import BaseModel

class User(BaseModel):
    user_id: int
    first_name: Optional[str] = None
    last_name: str

response = statistic_route.get()
response.validate(User)               # validates response.json() as is
response.validate(User, 'data')        # validates response.json()['data']
response.validate(User, 'data:user')   # validates response.json()['data']['user']

users = response.get_validated_objects()  # List[User]

If you pass a single key without : (like 'data' above), pycamel searches for that key at any nesting level of the response, so it does not matter how deep it is - you don’t need to know or repeat the full path. A :-separated path (like 'data:user') instead walks that exact path step by step. If most of your endpoints share the same response envelope (for example {"data": {...}}), set it once instead of repeating it on every .validate() call:

CamelConfig(host='https://localhost/', project_validation_key='data')

Asserting a specific parameter

assert_parameter looks up a key anywhere in the response body (same nested-key search as above) and compares every match against an expected value:

response.assert_parameter("status", "ACTIVE")                 # ==
response.assert_parameter("status", ["ACTIVE", "BLOCKED"], "_in")  # in
response.assert_parameter("age", 18, "_ge")                    # >=

Reading values without asserting

ids = response.get_items_by_key("id")   # List of every "id" value found
raw = response.get_response_json()      # Untouched response.json()

Authentication

Most real backends require an auth token, and that token usually expires during a long test run. auth_provider is a callable that pycamel calls again right before every single request, so it naturally supports refresh - just make the callable check/renew the token whenever it needs to.

import time
import requests

_token_cache = {"value": None, "expires_at": 0}

def get_auth_headers():
    if time.time() >= _token_cache["expires_at"]:
        resp = requests.post(
            "https://localhost/auth/login",
            json={"login": "qa", "password": "qa"}
        ).json()
        _token_cache["value"] = resp["access_token"]
        _token_cache["expires_at"] = time.time() + resp["expires_in"]
    return {"Authorization": f"Bearer {_token_cache['value']}"}

# Applied to every router in the project:
CamelConfig(host='https://localhost/', auth_provider=get_auth_headers)

# Or scoped to a single router/router maker:
admin_users = data_service_maker_v1.make_router(
    '/admin/users', auth_provider=get_auth_headers
)

Headers returned by auth_provider can still be overridden for a single request with .append_header/.set_headers, which always win.

Timeouts and retries

By default a router has no enforced timeout and does not retry failed requests, matching earlier versions. You can configure sane defaults for the whole project on CamelConfig, and override them for a specific router when needed.

from pycamel import CamelConfig, RouterMaker

CamelConfig(
    host='https://localhost/',
    default_timeout=10,     # seconds, applied to every request
    retries=3,               # retried only on 502/503/504 responses
    backoff_factor=0.5
)

data_service_maker_v1 = RouterMaker('/data-service/v1')
# overrides the project-wide defaults for this router only
cats_statistic = data_service_maker_v1.make_router(
    '/cats-statistic', timeout=5, retries=0
)

A request can still override the default timeout by passing timeout= explicitly, e.g. statistic_route.get(timeout=1). Requests made from the same router reuse a single requests.Session, so connections are pooled.

Each CamelConfig(...) call fully replaces the previously configured values - a parameter left out clears the matching setting rather than keeping whatever an earlier CamelConfig(...) call had set. Call CamelConfig.reset() to explicitly clear every setting (including auth_provider) without configuring a new one, which is mainly useful between test modules/services that each need a clean slate:

from pycamel import CamelConfig

CamelConfig.reset()

Response time assertion

response = statistic_route.get()
response.assert_response_time(2)  # fails if the response took over 2s

Handling errors

All exceptions below can be imported directly from pycamel.

• ForbiddenParameter - url/headers/a positional argument was passed to .get()/.post()/etc. instead of the dedicated .set_headers()/.append_header() methods.

• RequestException - the underlying requests call raised (timeout, connection error, exhausted retries, etc.).

• MissingConfigError - a router was built before CamelConfig(host=...) was called.

• AbsentValidationItems - .validate()/.assert_parameter() received nothing to work with (None, {} or []).

• IncorrectValidationPath - a :-separated validation key path does not match the response structure.

• IncorrectAssertParameter - an unknown filter (not one of _eq/ _in/_lt/_gt/_le/_ge) was passed to .assert_parameter().