CodingStandards/KeywordArguments

This is a coding standard suggestion.
 * 1) !wiki caution

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)