CodingStandards/KeywordArguments

#!wiki caution
'''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:

#!highlight python
def create(self, context, instance_type,
           image_id, kernel_id=None, ramdisk_id=None,
           min_count=1, max_count=1,
           display_name='', display_description='',
           key_name=None, key_data=None, security_group='default',
           availability_zone=None, user_data=None):
    """Create the number of instances requested if quota and
    other arguments check out ok."""

Might be rewritten as:

#!highlight python
def create(self, context, instance_type, image_id, **kwargs):
    """
    Attempt to create one or more virtual machine instances using the
    given context, instance_type, image_id, and a list of parameter which
    are passed in as keyword arguments. 

    `quota.QuotaError` will be raised by this function if the minimum number
    of instances cannot be created due to quota violations.

    @param context: `nova.context.RequestContext` compatible object
    @param instance_type: string identifying the instance type
    @param image_id: integer identifying the image to use
    @kwarg kernel_id: integer identifying the kernel to use
    @kwarg ramdisk_id: integer identifying the ramdisk to use
    @kwarg min_count: minimum instances to create, defaults to 1
    @kwarg max_count: maximum instances to create, defaults to 1
    @kwarg display_name: string name to give created instances
    @kwarg display_description: string description to give instances
    @kwarg key_name: string name of key pair to use
    @kwarg key_data: public key to use for created instances
    @kwarg security_group: list or string containing names of groups
    @kwarg availability_zone: string identifying availability zone
    @kwarg user_data: string of data to attach to created instances
    """
    kernel_id = kwargs.get("kernel_id", None)
    ramdisk_id = kwargs.get("ramdisk_id", None)
    min_count = kwargs.get("min_count", 1)
    max_count = kwargs.get("max_count", 1)
    display_name = kwargs.get("display_name", "")
    display_description = kwargs.get("display_description", "")
    key_name = kwargs.get("key_name", None)
    security_group = kwargs.get("security_group", "default")
    availability_zone = kwargs.get("availability_zone", None)
    user_data = kwargs.get("user_data", None)

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:

#!highlight python
 kernel_id = kwargs.get("kernel_id", None)
 

...might become...

#!highlight python
 kernel_id = kwargs.get("kernel_id", config.default_kernel_id)