10

If one browses through the official Python docs, one can see function (or class) signatures of varying kinds.

For example

random.uniform(a, b)

is simple to understand: You pass it two objects a and b (that are floating point numbers and it returns a random number from the interval between them). Similarly simple to understand is the signature from

SSLSocket.getpeercert(binary_form=False)

where a default value for the argument is also specified, in case it's called without any argument.

But then there are also functions with really weird signatures like

min(iterable, *[, key, default])

or

readline.append_history_file(nelements[, filename])

or

csv.register_dialect(name[, dialect[, **fmtparams]])

What do these all mean? Is there some reference guide explaining how to read things like name[, dialect[, **fmtparams]]?

These example were just randomly taken from the official Python docs and don't cover all signature types I've come across. I need a general explanation how to read these signatures.

l7ll7
  • 1,309
  • 1
  • 10
  • 20

4 Answers4

4

The asterisk in the example below means that key and default are keyword only arguments:

min(iterable, *[, key, default])

Parameter in square brackets are optional, so below filename is optional:

readline.append_history_file(nelements[, filename])

Argument with a single asterisk mean that the function can have any number of positional arguments, for instance:

a_function(a, b, *args)

Argument with 2 asterisks mean that the function can have any number of keyword arguments, for instance:

class dict(mapping, **kwarg)

Everything is explained in the Python documentation: Function definitions

Laurent LAPORTE
  • 21,958
  • 6
  • 58
  • 103
  • It seems first always come mandatory arguments, then optional ones, and inside each of these two cases we first list the "normal" ones, then the positional arguments and then the keyword arguments. Is that correct? – l7ll7 Feb 06 '19 at 15:48
3

NB: I know this has been asked before but cannot find the dup so if someone does, please bip me and I'll delete my answer...

This is mainly a simplified EBNF notation. register_dialect(name[, dialect[, **fmtparams]]) means that the register_dialect functions takes a mandatory name argument, a facultative dialect argument and facultative arbitrary keyword arguments.

bruno desthuilliers
  • 75,974
  • 6
  • 88
  • 118
  • Would `register_dialect(name[, **fmtparams[, dialect ]])` have also been an acceptalbe signature, or is the order important in some way? – l7ll7 Feb 06 '19 at 15:46
  • The order is "important in some way" indeed (even if a bit less in Python3). `dialect` is a positional parameter (you don't need to name it, just to pass it as the nth - here second - argument). – bruno desthuilliers Feb 06 '19 at 15:50
2

Parameters in square bracket are optional. That means they have a default value which is used if you do not provide a value. If you read the function description, is usually explained.

When you have nested brackets, it means that the argument in the inner bracket cannot be provided if at least one of the arguments in the outer bracket is not provided. For example:

csv.register_dialect(name[, dialect[, **fmtparams]])

means that: csv.register_dialect(name) is valid, csv.register_dialect(name, dialect) is valid, csv.register_dialect(name, dialect, **fmtparams) is valid but csv.register_dialect(name, **fmtparams) is not valid.

* and ** are args and kwargs, here more reference on them.

Valentino
  • 7,291
  • 6
  • 18
  • 34
1

A common notation is that square brackets [] represent optional values. I'm not sure where this originates from, it might be BNF grammar.

* represents any number of positional arugments. ** represents any number of keyword arugments.

* and ** are legit python syntax. you can have a function signature looking like func(*args) for example. These are defined in the language reference. An easier reading might be the python tutorial.

Eric
  • 5,686
  • 2
  • 23
  • 36