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

Question

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?

Asked By: Abhijit

||

Source

Answer 1

php.net describes the parameters for functions that are part of the PHP language and its standard libraries.

The library you’re asking about, requests, is a third-party library and not part of the Python language or its standard libraries. You’ll find that the standard libraries like urllib are in fact very well documented, like urllib.request here: https://docs.python.org/3/library/urllib.request.html#module-urllib.request

However, some third party libraries are far more user-friendly and requests is a popular example of that. The documentation is up to the developers though, so you should try and contact them about it. Don’t blame the language, unless you want to blame it for not having nice enough standard libraries (and then there’s some reasons there).

As indicated in the comments to your question, the source code for requests is freely available, so you can find out what **kwargs are expected and how they are used there: https://docs.python-requests.org/en/latest/_modules/requests/cookies/#RequestsCookieJar.set

Note that domain and path are explicitly used, and the rest is passed on as **kwargs to create_cookie() if no Morsel was passed as a value.

Answered By: Grismar

Answer 2

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.

Answered By: Antonio Gonzalez

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

Question:

Answers: