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?
- Currently programs like pydoc are throughly unhelpful when functions such as this one are encountered.
- Function definitions which might have an arbitrary number of keyword parameters can still be made to fit on a smaller number of lines.
- 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)