This is a coding standard suggestion.

Relevant blueprint: https://blueprints.launchpad.net/nova

Certain more nuanced aspects of programming in Python are not covered by PEP-0008. One of those nuances is the use of a keyword arguments helper when confronted with a large number of potential inputs to a function.

For example, a very important and key aspect of creating a virtual server: 

   1 def create(self, context, instance_type,
   2            image_id, kernel_id=None, ramdisk_id=None,
   3            min_count=1, max_count=1,
   4            display_name='', display_description='',
   5            key_name=None, key_data=None, security_group='default',
   6            availability_zone=None, user_data=None):
   7     """Create the number of instances requested if quota and
   8     other arguments check out ok."""
   9

Might be rewritten as: 

   1 def create(self, context, instance_type, image_id, **kwargs):
   2     """
   3     Attempt to create one or more virtual machine instances using the
   4     given context, instance_type, image_id, and a list of parameter which
   5     are passed in as keyword arguments. 
   6 
   7     `quota.QuotaError` will be raised by this function if the minimum number
   8     of instances cannot be created due to quota violations.
   9 
  10     @param context: `nova.context.RequestContext` compatible object
  11     @param instance_type: string identifying the instance type
  12     @param image_id: integer identifying the image to use
  13     @kwarg kernel_id: integer identifying the kernel to use
  14     @kwarg ramdisk_id: integer identifying the ramdisk to use
  15     @kwarg min_count: minimum instances to create, defaults to 1
  16     @kwarg max_count: maximum instances to create, defaults to 1
  17     @kwarg display_name: string name to give created instances
  18     @kwarg display_description: string description to give instances
  19     @kwarg key_name: string name of key pair to use
  20     @kwarg key_data: public key to use for created instances
  21     @kwarg security_group: list or string containing names of groups
  22     @kwarg availability_zone: string identifying availability zone
  23     @kwarg user_data: string of data to attach to created instances
  24     """
  25     kernel_id = kwargs.get("kernel_id", None)
  26     ramdisk_id = kwargs.get("ramdisk_id", None)
  27     min_count = kwargs.get("min_count", 1)
  28     max_count = kwargs.get("max_count", 1)
  29     display_name = kwargs.get("display_name", "")
  30     display_description = kwargs.get("display_description", "")
  31     key_name = kwargs.get("key_name", None)
  32     security_group = kwargs.get("security_group", "default")
  33     availability_zone = kwargs.get("availability_zone", None)
  34     user_data = kwargs.get("user_data", None)
  35

Why might we want to replace existing code (which works) with code which is over 4 times as long?

  1. Currently programs like pydoc are throughly unhelpful when functions such as this one are encountered.

  2. Function definitions which might have an arbitrary number of keyword parameters can still be made to fit on a smaller number of lines.
  3. Moving to the new form would allow more fined grained configuration for default values: 
       1  kernel_id = kwargs.get("kernel_id", None)
   2
  4. ..might become... 
       1  kernel_id = kwargs.get("kernel_id", config.default_kernel_id)
   2

Wiki: CodingStandards/KeywordArguments (last edited 2011-02-01 20:05:46 by Brian Lamar)