Hướng dẫn python docstring kwargs
What is the conventional way to express in a docstring the expected types of keyword arguments? Show Or is this out of principle something I should not be doing at all? Google is suspiciously un-forthcoming on the subject. (I am interested in doing this because I find that keeping track of expected types of all variables is very helpful as I code. I use PyCharm, which warns me when arguments have unexpected types, or when custom class attributes may be unresolved etc.) However, I am finding that sometimes the list of possible keywrord arguments listed as
can become long and unreadable.. Consider the following code
I would like to use the docstring to state the expected types. And I would like PyCharm to warn me that sally's age has the wrong type. Of course, I don't know if PyCharm even has the capacity to 'understand' that level of detail in the docstring. Nevertheless I'd like to know what the conventional way to do it is. Other comments and suggestions about kwargs and docstrings also welcome. There is a doctstring example for Sphinx in their documentation. Specifically they show the following:
Though you asked about sphinx explicitly, I would also point to the Google Python Style Guide. Their docstring example seems to imply that they don't call out kwargs specifically. (other_silly_variable=None)
A-B-B has a question about the accepted answer of referencing the subprocess management documentation. If you import a module, you can quickly see the module docstrings via inspect.getsource. An example from the python interpreter using Silent Ghost's recommendation:
Of course you can also view the module documentation via help function. For example help(subprocess) I'm not personally a fan of the subprocess docstring for kwargs as an example, but like the Google example it doesn't list kwargs seperately as shown in the Sphinx documentation example.
I'm including this answer to A-B-B's question because it's worth noting that you can review any module's source or documentation this way for insights and inspiration for commenting your code.
Nội dung chính
Đối với ngôn ngữ lập trình Python, cú pháp đặc biệt *args trong phần định nghĩa hàm (function definitions) được sử dụng dể truyền một số lượng có thể thay đổi được các đối số cho một hàm. Nó được sử dụng để truyền vào cho hàm một danh sách đối số có số lượng đối số thay đổi được và các đối số đều là non-keyworded, tức là chúng đều chưa được định từ khóa. – Ý nghĩa: Cú pháp *args, ký hiệu * tức là nhận vào một số lượng có thể thay đổi được các args – viết tắt của argument (đối số truyền vào cho hàm). – *args cho phép hàm của bạn có thể nhận vào nhiều đối số hơn số lượng đối số chính thức đã được chỉ định trước đó. Với *args, bất kỳ số lượng đối số bổ sung nào cũng có thể được truyền vào hàm thông qua các tham số chính thức hiện tại của hàm (kể cả bạn không truyền thêm đối số bổ sung nào vào cũng được). – Ví dụ: Chúng ta muốn tạo ra một hàm thực hiện phép nhân, nhận vào số lượng đối số tùy ý và nhân chúng lại với nhau. Việc này có thể được thực hiện nhờ vào *args. – Sử dụng ký hiệu *, thì cái biến mà chúng ta gắn nó với ký hiệu * sẽ trở thành một kiểu dữ liệu iterable, nghĩa là lúc này bạn có thể thực hiện những việc như lặp/duyệt qua biến đó, hay sử dụng các hàm bậc cao hơn chẳng hạn như map và filter, v.v… để xử lý/thao tác nó. (giải thích thêm, trong Python, iterable có nghĩa là gì? iterable là bất kỳ đối tượng nào ở trong Python mà có khả năng trả về từng thành viên của nó, bản thân nó có thể được lặp/duyệt thông qua một vòng lặp for. Một số ví dụ quen thuộc về iterable thường gặp là list, tuple, và string – đây đều là các kiểu dữ liệu nối tiếp có thể được lặp thông qua một vòng lặp for). – Ví dụ sử dụng *arg trong Python: + Ví dụ 1:
Kết quả in ra là:
+ Ví dụ 2:
Kết quả in ra là:
2. **kwargs trong PythonĐối với ngôn ngữ lập trình Python, cú pháp đặc biệt **kwargs trong phần định nghĩa hàm (function definitions) được sử dụng dể truyền một số lượng có thể thay đổi được các đối số đã được keyworded – định từ khóa cho một hàm. **kwargs được tạo thành bởi kwargs đi kèm với hai dấu sao ở phía trước. Lý do phải sử dụng ** là bởi vì hai dấu sao cho phép chúng ta có thể truyền dữ liệu vào hàm thông qua các đối số từ khóa – keyword arguments, với số lượng tùy ý. – Một đối số từ khóa – keyword argument là nơi mà bạn cung cấp một cái tên cho biến mà bạn đang định truyền vào trong hàm. – Có thể tư duy theo cách sau: kwargs là một kiểu dictionary sẽ ánh xạ (maps) từng keyword (từ khóa) tới mỗi giá trị mà chúng ta truyền vào trong hàm. Đó là lý do vì sao khi chúng ta lặp qua kwargs và in ra các phần tử thì chúng được in ra không theo thứ tự nào cả. – Ví dụ 1. Sử dụng **kwargs để truyền các đối số từ khóa với số lượng tùy ý:
Kết quả in ra là:
– Ví dụ 2. Sử dụng **kwargs để truyền các đối số từ khóa với số lượng tùy ý, cùng với một đối số bổ sung nữa:
Kết quả in ra là:
3. Sử dụng *args và **kwargs để gọi đến một hàmVí dụ:
Kết quả in ra là:
4. Sử dụng *args và **kwargs trên cùng một dòng để gọi đến một hàmVí dụ:
Kết quả in ra là:
Nguồn và Tài liệu tiếng anh tham khảo:
Tài liệu từ cafedev:
Nếu bạn thấy hay và hữu ích, bạn có thể tham gia các kênh sau của cafedev để nhận được nhiều hơn nữa:
Chào thân ái và quyết thắng! Đăng ký kênh youtube để ủng hộ Cafedev nha các bạn, Thanks you! |