def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):

+accepts one :term:`positional argument` (``voltage``) and three
+:term:`keyword arguments <keyword argument>` (``state``, ``action``,
+and ``type``).  

This is simply false. An argument for voltage is required, the other three are optional. I suggest something like the followinga:

Calls to this function require 1 to 4 arguments. An argument for voltage is required; arguements for the other three parameters are optional because they have default arguments specified.

Arguments can be matched to parameters by either position or 'keyword', where the keyword is the name of a parameter. The two conditions are that each parameter is matched to at most one argument and that keyword matches follow positional matches. The following matches 4 argumnts to the corresponding parameters by position:
  parrot(100, 'loose', 'skid', 'American Red')
This matches the same arguments by keyword (parameter name):
  parrot(state='loose', voltage=100, type='American Red', action='loose') 
Any order is acceptable for such 'keyword arguments'.
A call can mix the two matching methods. This
parrot(100, action='loose')
passes one argument each way and lets 'state' and 'type' get their default values of 'a stiff' and 'Norwegian Blue'.

< add minimal set of bad calls >