plone/plone.api — Issue #14: Call for votes: Method signatures
Author: wamdam
Created: 2012-02-27 15:35:44+00:00
State: open
Labels: question

We want the API to stay consistent for a long time. But we know that the method signatures (i.e. the amount, names, types or if they're optional) of parameters will change.

One example is the change from user_id to a possible user_email from plone3 to plone4 which affects most user method signatures. They all have to add user_email as a new (optional) parameter. More of these changes will come.

With that in mind, we have two choices:

1) Only Keyword Arguments with manual tests (see below *t1*)
2) Only Positional Arguments (see below *t2*)

```python
def t1(**kw):
""" Does something with an obj.

:param obj: [required] The object
:type obj: object
"""
if not kw.get('obj'):
raise ValueError("obj is required")

def t2(obj):
""" Does something with an obj.

:param obj: [required] The object
:type obj: object
"""
pass
```

The advantage with *t1* would be that we can add keyword arguments in future versions for BBB easily.
The advantage with *t2* is that code inspection can find the method signature (e.g. ipython) and displays the arguments nicely. Also it feels more pythonic.

The disadvantage with *t1* is that you have to read the docstring in order to know about the parameters. Code inspection will not help.
The disadvantage with *t2* is that people might start to use the method with positional arguments instead of keyword arguments which will make BBB more complicated. We'd have to make clear that people can expect BBB only if they use keyword arguments.