Zapros

Appearance

Query Parameters ​

Pass query parameters as a dictionary to the params argument. Zapros URL-encodes the values and appends them to the URL before sending the request.

python
from zapros import AsyncClient

async with AsyncClient() as client:
    response = await client.request(
        "GET",
        "https://httpbin.org/get",
        params={
            "q": "hello world",
            "page": "1",
        },
    )
    # Sends: GET /get?q=hello+world&page=1
python
from zapros import Client

with Client() as client:
    response = client.request(
        "GET",
        "https://httpbin.org/get",
        params={
            "q": "hello world",
            "page": "1",
        },
    )
    # Sends: GET /get?q=hello+world&page=1

Special characters and spaces are percent-encoded automatically — you never need to escape values yourself.

Repeated parameters ​

Pass a list as a value to send the same key multiple times:

python
response = await client.request(
    "GET",
    "https://api.example.com/items",
    params={
        "status": ["active", "pending"],
        "page": "1",
    },
)
# Sends: GET /items?status=active&status=pending&page=1
python
response = client.request(
    "GET",
    "https://api.example.com/items",
    params={
        "status": ["active", "pending"],
        "page": "1",
    },
)
# Sends: GET /items?status=active&status=pending&page=1

Parameter Priority ​

When query parameters come from multiple sources, they are merged in this order (lowest to highest priority):

  1. default_params set on the client
  2. Query parameters in the URL string passed to url=
  3. Parameters in the params= argument

Duplicate keys are overwritten by higher priority sources:

python
async with AsyncClient(
    default_params={"version": "1"}
) as client:
    response = await client.request(
        "GET",
        "https://api.example.com/search?lang=en",
        params={"q": "zapros"},
    )
# Sends: GET /search?version=1&lang=en&q=zapros
python
with Client(default_params={"version": "1"}) as client:
    response = client.request(
        "GET",
        "https://api.example.com/search?lang=en",
        params={"q": "zapros"},
    )
# Sends: GET /search?version=1&lang=en&q=zapros

When the same key appears in multiple sources, the highest priority value wins:

python
response = await client.request(
    "GET",
    "https://api.example.com/items?tag=python",
    params={"tag": "http"},
)
# Sends: GET /items?tag=http
python
response = client.request(
    "GET",
    "https://api.example.com/items?tag=python",
    params={"tag": "http"},
)
# Sends: GET /items?tag=http

Using URL Objects ​

Zapros uses the URL class from pywhatwgurl. You can build URLs with query parameters:

python
from zapros import URL

url = URL("https://api.example.com/search")
url.search_params["q"] = "zapros"
url.search_params["limit"] = "10"

print(url)

Pass URL objects to requests by converting them to strings:

python
from zapros import AsyncClient, URL

url = URL("https://api.example.com/users")
url.search_params["page"] = "2"

async with AsyncClient() as client:
    response = await client.request("GET", url)
python
from zapros import Client, URL

url = URL("https://api.example.com/users")
url.search_params["page"] = "2"

with Client() as client:
    response = client.request("GET", url)