0

I recently came across this when reading the Python official documentation for json.load:

json.load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])

May I know how should I comprehend this?

For example, if I want to set the parameter parse_float to be 3, how should I construct the argument?

Also, what does [, ....] mean? Why is there a comma preceding the formal parameters?

Jason Lee
  • 15
  • 1
  • 5

2 Answers2

1

The square brackets […] is a common metalanguage notation used to denote an optional component of a syntax in documentation and manuals. "Optional" here means you can either omit or keep everything inside the brackets (but not a subset of it). It is in some sense analogous to (…)? in regular expressions.

The usage predates Python: you can find it in various Unix manpages. It is not part of Python's syntax, though you will find it in many docs.

When the documentation says:

foo(x[, y])

Formally, it means that both of the following are acceptable:

foo(x)
foo(x,  y)

For your example:

json.load(fp[, encoding[, cls[, object_hook[, parse_float[, parse_int[, parse_constant[, object_pairs_hook[, **kw]]]]]]]])

Formally, it means any of the following are acceptable:

json.load(fp)
json.load(fp, encoding)
json.load(fp, encoding, cls)
json.load(fp, encoding, cls, object_hook)
json.load(fp, encoding, cls, object_hook, parse_float)
json.load(fp, encoding, cls, object_hook, parse_float, parse_int)
json.load(fp, encoding, cls, object_hook, parse_float, parse_int, parse_constant)
json.load(fp, encoding, cls, object_hook, parse_float, parse_int, parse_constant, object_pairs_hook)
json.load(fp, encoding, cls, object_hook, parse_float, parse_int, parse_constant, object_pairs_hook, **kw)

However, the documentation is not very precise with the notation: it's fine to use keyword arguments to skip any of the parameters that you don't care because of the way arguments in Python work, e.g.:

json.load(fp, parse_float=3)

In fact, if you look at the same documentation for Python 3 you see that they chose to use a much clearer notation:

json.loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw)

Rufflewind
  • 8,545
  • 2
  • 35
  • 55
  • What if I want to skip one parameter? If I want to set the parameter `parse_float` to be `3` without changing `object_hook`, how should I construct the argument? Thanks! – Jason Lee Dec 16 '14 at 07:36
  • @Jason: They are optional so they typically would have default values. So to set the values of the parameters you want, just use the regular keyword arguments syntax. You know what all the parameter names are since they're all listed right there. – Jeff Mercado Dec 16 '14 at 07:40
  • You mean `json.load(fp,parse_float = 3)` ? – Jason Lee Dec 16 '14 at 07:41
  • I've added the example. The documentation isn't very precise with the way they use the notation, so it's probably fine to specify a keyword argument directly. – Rufflewind Dec 16 '14 at 07:43
0

The parameters are keyword arguments. You can use them like this:

def my_parse_float(float_str):
    return float(float_str)

print json.loads('{"foo":1, "bar":1.234}', parse_float=my_parse_float)

Output:

{'bar': 1.234, 'foo': 1}

For parse_float, the value of 3 makes no sense. Read the documentation:

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to float(num_str).