Where can I find Python requests library functions **kwargs parameters documented?

For example, from https://docs.python-requests.org/en/latest/api/#requests.cookies.RequestsCookieJar.set:

set(name, value, **kwargs)
Dict-like set() that also supports optional domain and path 
args in order to resolve naming collisions from using one cookie jar over multiple domains.

Where can I find information about what other arguments the function takes as **kwargs?

I mean these arguments, domain, path, expires, max_age, secure, httponly. It is not documented there!

All other functions are like this, I got confused what to pass as parameters.

In php.net they describe all parameters properly.

Where can I find all parameters that are hidden behind **kwargs?

>Solution :

In my experience reading the source code for many open source libraries solves this problem.

For the example you posted the source code is the following:

def set(self, name, value, **kwargs):
        """Dict-like set() that also supports optional domain and path args in
        order to resolve naming collisions from using one cookie jar over
        multiple domains.
        """
        # support client code that unsets cookies by assignment of a None value:
        if value is None:
            remove_cookie_by_name(
                self, name, domain=kwargs.get("domain"), path=kwargs.get("path")
            )
            return

        if isinstance(value, Morsel):
            c = morsel_to_cookie(value)
        else:
            c = create_cookie(name, value, **kwargs)
        self.set_cookie(c)
        return c

For python kwargs are viewed as a dictionary (that’s what ** does). In this case the set function uses the "domain" and "path" directly. However, there is another function that takes **kwargs. This is the main purpose of using kwargs instead of fixing the arguments.

If we dive into the source code of create_cookie we can see which keyword arguments are valid.

def create_cookie(name, value, **kwargs):
    """Make a cookie from underspecified parameters.

    By default, the pair of `name` and `value` will be set for the domain ''
    and sent on every request (this is sometimes called a "supercookie").
    """
    result = {
        "version": 0,
        "name": name,
        "value": value,
        "port": None,
        "domain": "",
        "path": "/",
        "secure": False,
        "expires": None,
        "discard": True,
        "comment": None,
        "comment_url": None,
        "rest": {"HttpOnly": None},
        "rfc2109": False,
    }

    badargs = set(kwargs) - set(result)
    if badargs:
        raise TypeError(
            f"create_cookie() got unexpected keyword arguments: {list(badargs)}"
        )

    result.update(kwargs)
    result["port_specified"] = bool(result["port"])
    result["domain_specified"] = bool(result["domain"])
    result["domain_initial_dot"] = result["domain"].startswith(".")
    result["path_specified"] = bool(result["path"])

    return cookielib.Cookie(**result)

In this case the only allowed keywords are the ones described in the results dictionary.

Leave a Reply