+- Python Forum (https://python-forum.io)
+-- Forum: General (https://python-forum.io/forum-1.html)
+--- Forum: News and Discussions (https://python-forum.io/forum-31.html)
+--- Thread: say 1st or 2nd? (/thread-32735.html)
say 1st or 2nd? - Skaperen - Mar-02-2021
suppose my function returns a 2-list or 2-tuple to the caller. documenting this function needs to refer to the item that would be accessed with [1]. should the text in this documentation refer to this as the "2nd" item or the "1st" item or the "[1]" item?
RE: say 1st or 2nd? - ndc85430 - Mar-02-2021
Is it not possible to avoid that problem altogether, by using a named tuple, dict or a class so that you can refer to the items by meaningful names? It sounds like the data is structured in some way, rather than merely being a collection of items. Modelling that structure enhances the expressiveness of the code.
RE: say 1st or 2nd? - Skaperen - Mar-02-2021
which of those would you suggest if keeping the efforts of who is coding the caller as simple as possible and 2nd importance is my effort coding and documenting the function?
RE: say 1st or 2nd? - ndc85430 - Mar-02-2021
I think all 3 are pretty easy to write and for a caller to use. Personally, I prefer named tuples or classes over dicts because they allow you to name the structure itself (as opposed to just the fields). That's clearly good for documentation, too. I don't know whether named tuples already implement
__eq__ and __hash__ should you need them.
RE: say 1st or 2nd? - DeaD_EyE - Mar-02-2021
Quote:suppose my function returns a 2-list or 2-tuple to the caller. documenting this function needs to refer to the item that would be accessed with [1]. should the text in this documentation refer to this as the "2nd" item or the "1st" item or the "[1]" item?
Yes, this was a problem before typehints were invented.
Now we can document code, giving the IDE better context and static type checking with mypy.
Often document strings hold too much information about types of arguments. Using instead typehints will prevent the information bloat in the docstring.
from typing import NamedTuple
class Result(NamedTuple):
"""
This instance is a result ...
"""
a: int
b: str
def some_function(iterations: int, name: str) -> Result:
"""
This function does nothing useful
"""
return Result(42, 23)
if __name__ == "__main__":
res = some_function(None, None)
a, b = some_function(1, "foo")
b = some_function(1, "foo")If you put this code in your IDE, the IDE should detect the errors in the code.For example Result expects one int and one str, but in the function call it's called with two integers.
I named this example epl_test.py. Don't ask why..
Output:andre@andre-GP70-2PE:~$ python epl_test.py
andre@andre-GP70-2PE:~$Output:andre@andre-GP70-2PE:~$ mypy epl_test.py
epl_test.py:16: error: Argument 2 to "Result" has incompatible type "int"; expected "str"
epl_test.py:20: error: Argument 1 to "some_function" has incompatible type "None"; expected "int"
epl_test.py:20: error: Argument 2 to "some_function" has incompatible type "None"; expected "str"
epl_test.py:22: error: Incompatible types in assignment (expression has type "Result", variable has type "str")
Found 4 errors in 1 file (checked 1 source file)
andre@andre-GP70-2PE:~$ from typing import NamedTuple
class Result(NamedTuple):
"""
This instance is a result ...
"""
a: int
b: str
def some_function(iterations: int, name: str) -> Result:
"""
This function does nothing useful
"""
return Result(42, "23")
if __name__ == "__main__":
a, b = some_function(1, "foo")Output:andre@andre-GP70-2PE:~$ python epl_test2.py
andre@andre-GP70-2PE:~$ mypy epl_test2.py
Success: no issues found in 1 source fileWe all know this situation. The comment or doctstring says a function will return
True and in reality the function returns False. 
RE: say 1st or 2nd? - Skaperen - Mar-02-2021
i have some more complex (complicated?) "type" checking. a valid value could be a list or tuple where every item is a list or tuple where every item at the 2nd level is a str or bytes that is not an empty string. this represents a POSIX shell pipeline of commands like this useless command example:
pipeline = [[b'ls',b'-l'],('tail','-n'+str(count)),some_command,['cut','-c','12-']][other, less complex, cases include making sure the type of 2 arguments is the same.