How to document an argument that takes several types

Question

In Python 2, is there a canonical way to document that a method can be more than one type?

Here is how I did it:

def __init__(self, work_order_number): """This message communicates that a job is being rerun. Olio will forget everything it knows about the job. Args: work_order_number (int or str): Work order number """ payload = { 'work_order_number': str(work_order_number), } self.content = json.dumps(payload) 

where I used the notation (int or str) to indicate that the argument can be integer or string.

As usual, Python 2 programs document that a method argument can have more than one type? Is there a standard or best practice?

Due to forces beyond my control, I cannot use Python 3 and therefore cannot use annotations

Answer 1

The way you did it is wonderful. There is no exact format that is needed; you just need to make the intent understandable with commas or "or". See, for example, various functions from matplotlib or pandas that take arguments documented with "str or None", "float, sequence or None", "list-like or integer", etc.