CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-niquests

Niquests is a simple, yet elegant, HTTP library that is a drop-in replacement for Requests, which is under feature freeze.

—

Pending
Overview
Eval results
Files

sync-requests.mddocs/

Synchronous HTTP Requests

Core HTTP methods for making synchronous requests. These functions provide a simple interface for HTTP communication without requiring explicit session management. Each request creates a new connection that is automatically closed after completion.

Capabilities

Generic Request Function

The fundamental request function that all other HTTP methods build upon. Supports all HTTP methods and provides complete control over request parameters.

def request(
    method: HttpMethodType,
    url: str,
    *,
    params: QueryParameterType | None = None,
    data: BodyType | None = None,
    json: Any | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
) -> Response:
    """
    Constructs and sends a Request with the specified HTTP method.
    
    Args:
        method: HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
        url: Target URL for the request
        params: Query parameters to append to URL
        data: Request body data (dict, list, bytes, or file-like object)
        json: JSON serializable object to send in request body
        headers: HTTP headers to include in request
        cookies: Cookies to send with request
        files: Files for multipart upload
        auth: Authentication credentials
        timeout: Request timeout in seconds
        allow_redirects: Whether to follow HTTP redirects
        proxies: Proxy configuration
        verify: SSL certificate verification (bool or CA bundle path)
        stream: Whether to download response immediately
        cert: Client SSL certificate
        hooks: Request/response lifecycle hooks
        retries: Retry configuration
        
    Returns:
        Response object containing server response
    """

GET Requests

Retrieves data from the specified URL. Commonly used for fetching web pages, API responses, and downloadable content.

def get(
    url: str,
    params: QueryParameterType | None = None,
    *,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
    **kwargs: Any,
) -> Response:
    """
    Sends a GET request to retrieve data from the specified URL.
    
    Args:
        url: Target URL
        params: Query parameters to append to URL
        headers: HTTP headers
        cookies: Cookies to send
        auth: Authentication credentials
        timeout: Request timeout (defaults to read timeout)
        allow_redirects: Follow redirects (default: True)
        proxies: Proxy configuration
        verify: SSL verification
        stream: Stream response content
        cert: Client certificate
        hooks: Request hooks
        retries: Retry configuration
        **kwargs: Additional arguments
        
    Returns:
        Response object
    """

Usage example:

# Simple GET request
response = niquests.get('https://api.example.com/data')

# GET with query parameters
params = {'q': 'search term', 'limit': 10}
response = niquests.get('https://api.example.com/search', params=params)

# GET with custom headers
headers = {'User-Agent': 'MyApp/1.0', 'Accept': 'application/json'}
response = niquests.get('https://api.example.com/data', headers=headers)

POST Requests

Sends data to the server for processing. Commonly used for form submissions, API data creation, and file uploads.

def post(
    url: str,
    data: BodyType | None = None,
    json: Any | None = None,
    *,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
) -> Response:
    """
    Sends a POST request with optional data payload.
    
    Args:
        url: Target URL
        data: Request body data
        json: JSON data to serialize and send
        params: Query parameters
        headers: HTTP headers
        cookies: Cookies
        files: Files for multipart upload
        auth: Authentication
        timeout: Request timeout (defaults to write timeout)
        allow_redirects: Follow redirects
        proxies: Proxy configuration
        verify: SSL verification
        stream: Stream response
        cert: Client certificate
        hooks: Request hooks
        retries: Retry configuration
        
    Returns:
        Response object
    """

Usage example:

# POST with JSON data
data = {'name': 'John Doe', 'email': 'john@example.com'}
response = niquests.post('https://api.example.com/users', json=data)

# POST with form data
form_data = {'username': 'john', 'password': 'secret'}
response = niquests.post('https://example.com/login', data=form_data)

# POST with file upload
files = {'upload': open('document.pdf', 'rb')}
response = niquests.post('https://api.example.com/upload', files=files)

PUT Requests

Updates or replaces a resource on the server. Typically used for full resource updates in REST APIs.

def put(
    url: str,
    data: BodyType | None = None,
    *,
    json: Any | None = None,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
) -> Response:
    """
    Sends a PUT request to update or replace a resource.
    
    Args:
        url: Target URL
        data: Request body data
        json: JSON data to serialize and send
        params: Query parameters
        headers: HTTP headers
        cookies: Cookies
        files: Files for multipart upload
        auth: Authentication
        timeout: Request timeout
        allow_redirects: Follow redirects
        proxies: Proxy configuration
        verify: SSL verification
        stream: Stream response
        cert: Client certificate
        hooks: Request hooks
        retries: Retry configuration
        
    Returns:
        Response object
    """

PATCH Requests

Partially updates a resource on the server. Used for incremental updates in REST APIs.

def patch(
    url: str,
    data: BodyType | None = None,
    *,
    json: Any | None = None,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    files: MultiPartFilesType | MultiPartFilesAltType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
) -> Response:
    """
    Sends a PATCH request for partial resource updates.
    """

DELETE Requests

Removes a resource from the server. Used for resource deletion in REST APIs.

def delete(
    url: str,
    *,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = WRITE_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
    **kwargs: Any,
) -> Response:
    """
    Sends a DELETE request to remove a resource.
    """

HEAD Requests

Retrieves only the headers from a resource without downloading the body content. Useful for checking resource metadata, existence, or last-modified dates.

def head(
    url: str,
    *,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
    allow_redirects: bool = False,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
    **kwargs: Any,
) -> Response:
    """
    Sends a HEAD request to retrieve only response headers.
    
    Note: allow_redirects defaults to False for HEAD requests.
    """

OPTIONS Requests

Queries the server for supported HTTP methods and capabilities for a specific resource. Used for CORS preflight requests and API discovery.

def options(
    url: str,
    *,
    params: QueryParameterType | None = None,
    headers: HeadersType | None = None,
    cookies: CookiesType | None = None,
    auth: HttpAuthenticationType | None = None,
    timeout: TimeoutType | None = READ_DEFAULT_TIMEOUT,
    allow_redirects: bool = True,
    proxies: ProxyType | None = None,
    verify: TLSVerifyType = True,
    stream: bool = False,
    cert: TLSClientCertType | None = None,
    hooks: HookType[PreparedRequest | Response] | None = None,
    retries: RetryType = DEFAULT_RETRIES,
    **kwargs: Any,
) -> Response:
    """
    Sends an OPTIONS request to query server capabilities.
    """

Common Parameters

All synchronous HTTP methods support these common parameters:

Request Configuration

  • url: Target URL (required)
  • params: Query parameters (dict, list of tuples, or bytes)
  • headers: HTTP headers (dict)
  • cookies: Cookies (dict or CookieJar object)
  • auth: Authentication (tuple for Basic auth or custom Auth object)

Request Body (POST/PUT/PATCH)

  • data: Request body data (dict, list, bytes, or file-like object)
  • json: JSON-serializable object (automatically sets Content-Type)
  • files: Files for multipart upload (dict of name: file-like-object pairs)

Network Configuration

  • timeout: Request timeout (float, tuple, or TimeoutConfiguration)
  • allow_redirects: Follow HTTP redirects (boolean, defaults vary by method)
  • proxies: Proxy settings (dict mapping protocols to proxy URLs)
  • verify: SSL certificate verification (boolean or CA bundle path)
  • cert: Client SSL certificate (string path or tuple)

Advanced Options

  • stream: Download response content immediately (boolean)
  • hooks: Request/response lifecycle hooks (dict)
  • retries: Retry configuration (integer or RetryConfiguration object)

Type Definitions

HttpMethodType = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
QueryParameterType = Union[dict, list, bytes]
HeadersType = Union[dict, Headers]
CookiesType = Union[dict, RequestsCookieJar]
BodyType = Union[str, bytes, dict, list, IOBase]
TimeoutType = Union[float, Tuple[float, float], TimeoutConfiguration]
TLSVerifyType = Union[bool, str, bytes]
TLSClientCertType = Union[str, Tuple[str, str], Tuple[str, str, str]]
ProxyType = dict
RetryType = Union[int, RetryConfiguration]
HookType = dict

Install with Tessl CLI

npx tessl i tessl/pypi-niquests

docs

advanced-features.md

async-requests.md

exceptions.md

index.md

models.md

sessions.md

sync-requests.md

tile.json