Hướng dẫn python docstring code snippet - đoạn mã chuỗi doc python
Tôi muốn cung cấp các đoạn mã để hiển thị trường hợp người ta có thể sử dụng một phương thức hoặc lớp cụ thể trong Python. Làm thế nào tôi có thể làm điều đó? provide code snippets to show-case how one could use a particular method or class in python. How can I do that? Show Trong Java, người ta có thể sử dụng def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)9 to do so. Doctest là cách duy nhất? Khi tôi nhìn vào các tài liệu hiện có cho các gói điển hình (ví dụ: gấu trúc, numpy, v.v.), tôi không bao giờ thấy bất cứ điều gì khác ngoài DocTest nhằm kiểm tra phương thức và không chỉ định dạng văn bản là mã python. Vì vậy, nếu DocTest là cách duy nhất, điều gì sẽ là cách thích hợp để định dạng một đoạn mã để trông giống như các phiên Python tương tác? Tôi không muốn viết mã của mình trong một phiên tương tác mỗi lần và sau đó c+p nó trong tài liệu của tôi. Nó dường như không đúng. As I look at the existing docstrings for typical packages (e.g., pandas, numpy, etc), I never see anything other than doctest which is intended to test the method and not just to format text as python code. So, if doctest is the only way, what would be the proper way of formatting a snippet of code to look like interactive python sessions? I don't want to write my code in an interactive session each time and then c+p it in my docstring. It doesn't seem to be right. Đã hỏi ngày 4 tháng 7 năm 2019 lúc 18:05Jul 4, 2019 at 18:05
Docstrings không phải là cách duy nhất. Nếu bạn đang sử dụng Sphinx để tạo tài liệu thì bạn nên đọc cái này. Thí dụ
Đã trả lời ngày 4 tháng 7 năm 2019 lúc 18:19Jul 4, 2019 at 18:19
Fizzybearfizzybearfizzybear 1.1677 Huy hiệu bạc22 Huy hiệu đồng7 silver badges22 bronze badges 2 Về tài liệu và tiêu chuẩn#DocString Python là một chuỗi được sử dụng để ghi lại mô -đun Python, lớp, chức năng hoặc phương thức, vì vậy các lập trình viên có thể hiểu những gì nó làm mà không cần phải đọc chi tiết về việc triển khai. Ngoài ra, đó là một thực tế phổ biến để tạo tài liệu trực tuyến (HTML) tự động từ các tài liệu. Sphinx phục vụ mục đích này. Ví dụ tiếp theo đưa ra một ý tưởng về một tài liệu trông như thế nào: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num2 Một số tiêu chuẩn liên quan đến các tài liệu tồn tại, giúp chúng dễ đọc hơn và cho phép chúng dễ dàng xuất sang các định dạng khác như HTML hoặc PDF. Các quy ước đầu tiên mà mỗi tài liệu Python nên tuân theo được xác định trong PEP-257. Vì PEP-257 khá rộng, các tiêu chuẩn cụ thể khác cũng tồn tại. Trong trường hợp của Pandas, Công ước DocString Numpy được tuân thủ. Các quy ước này được giải thích trong tài liệu này:
Numpydoc là một phần mở rộng nhân sư để hỗ trợ Công ước DocString Numpy. Tiêu chuẩn sử dụng tái cấu trúcText (REST). Tái cấu trúcText là một ngôn ngữ đánh dấu cho phép mã hóa các kiểu trong các tệp văn bản thuần túy. Tài liệu về tái cấu trúc có thể được tìm thấy trong:
Pandas có một số người trợ giúp để chia sẻ tài liệu giữa các lớp liên quan, xem chia sẻ tài liệu.Sharing docstrings. Phần còn lại của tài liệu này sẽ tóm tắt tất cả các hướng dẫn trên và sẽ cung cấp các quy ước bổ sung cụ thể cho dự án Pandas. Viết một tài liệu#Quy tắc chung#Docstrings phải được xác định với ba trích dẫn kép. Không nên để lại các dòng trống trước hoặc sau DocString. Văn bản bắt đầu trong dòng tiếp theo sau các trích dẫn mở. Các trích dẫn đóng có dòng riêng của chúng (có nghĩa là chúng không ở cuối câu cuối cùng). Trong những dịp hiếm hoi, các kiểu phần còn lại như văn bản in đậm hoặc in nghiêng sẽ được sử dụng trong các tài liệu, nhưng nó phổ biến là có mã nội tuyến, được trình bày giữa các backticks. Những điều sau đây được xem xét mã nội tuyến:
Ghi chú Để chỉ hiển thị thành phần cuối cùng của lớp, phương thức hoặc hàm được liên kết, hãy đặt tiền tố với def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar8. Ví dụ: def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar9 sẽ liên kết đến def astype(dtype): """ Cast Series type. This section will provide further details. """ pass0 nhưng chỉ hiển thị phần cuối cùng, def astype(dtype): """ Cast Series type. This section will provide further details. """ pass1 dưới dạng văn bản liên kết. Xem cú pháp tham khảo chéo Sphinx để biết chi tiết. Good: def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr) Bad: def func(): """Some function. With several mistakes in the docstring. It has a blank like after the signature ``def func():``. The text 'Some function' should go in the line after the opening quotes of the docstring, not in the same line. There is a blank line between the docstring and the first line of code ``foo = 1``. The closing quotes should be in the next line, not in this one.""" foo = 1 bar = 2 return foo + bar Phần 1: Tóm tắt ngắn#Tóm tắt ngắn là một câu duy nhất thể hiện những gì chức năng làm một cách ngắn gọn. Tóm tắt ngắn phải bắt đầu bằng một chữ cái viết hoa, kết thúc bằng một dấu chấm và vừa với một dòng. Nó cần thể hiện những gì đối tượng làm mà không cung cấp chi tiết. Đối với các chức năng và phương pháp, tóm tắt ngắn phải bắt đầu với một động từ nguyên bản. Good: def astype(dtype): """ Cast Series type. This section will provide further details. """ pass Bad: def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass def astype(dtype): """ Cast Series type Missing dot at the end. """ pass def astype(dtype): """ Cast Series type from its current type to the new type defined in the parameter dtype. Summary is too verbose and doesn't fit in a single line. """ pass Phần 2: Tóm tắt mở rộng#Tóm tắt mở rộng cung cấp chi tiết về những gì chức năng làm. Nó không nên đi vào các chi tiết của các tham số, hoặc thảo luận về các ghi chú thực hiện, trong các phần khác. Một dòng trống được để lại giữa bản tóm tắt ngắn và tóm tắt mở rộng. Mỗi đoạn trong bản tóm tắt mở rộng kết thúc bằng một dấu chấm. Tóm tắt mở rộng sẽ cung cấp chi tiết về lý do tại sao chức năng này hữu ích và các trường hợp sử dụng của chúng, nếu nó không quá chung chung. def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass Phần 3: Tham số#Các chi tiết của các tham số sẽ được thêm vào trong phần này. Phần này có tiêu đề Các tham số của người dùng, theo sau là một dòng có dấu gạch nối dưới mỗi chữ cái của từ tham số. Một dòng trống được để lại trước tiêu đề phần, nhưng không phải sau đó, chứ không phải giữa dòng với từ ngữ tham số, và phần có dấu gạch nối. Sau tiêu đề, mỗi tham số trong chữ ký phải được ghi lại, bao gồm def astype(dtype): """ Cast Series type. This section will provide further details. """ pass2 và def astype(dtype): """ Cast Series type. This section will provide further details. """ pass3, nhưng không phải def astype(dtype): """ Cast Series type. This section will provide further details. """ pass4. Các tham số được xác định bởi tên của chúng, theo sau là một không gian, dấu hai chấm, không gian khác và loại (hoặc loại). Lưu ý rằng không gian giữa tên và đại tràng là quan trọng. Các loại không được xác định cho def astype(dtype): """ Cast Series type. This section will provide further details. """ pass2 và def astype(dtype): """ Cast Series type. This section will provide further details. """ pass3, nhưng phải được xác định cho tất cả các tham số khác. Sau khi định nghĩa tham số, bắt buộc phải có một dòng với mô tả tham số, được thụt vào và có thể có nhiều dòng. Mô tả phải bắt đầu bằng một chữ cái viết hoa, và kết thúc với một dấu chấm. Đối với các đối số từ khóa có giá trị mặc định, mặc định sẽ được liệt kê sau dấu phẩy ở cuối loại. Hình thức chính xác của loại trong trường hợp này sẽ là Int Int, mặc định 0. Trong một số trường hợp, có thể hữu ích để giải thích ý nghĩa của đối số mặc định, có thể được thêm vào sau dấu phẩy Int Int, mặc định -1, có nghĩa là tất cả CPU. Trong trường hợp giá trị mặc định là def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7, có nghĩa là giá trị sẽ không được sử dụng. Thay vì def astype(dtype): """ Cast Series type. This section will provide further details. """ pass8, nó được ưa thích để viết def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9. Khi def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 là một giá trị đang được sử dụng, chúng tôi sẽ giữ biểu mẫu STR, mặc định không có gì. Ví dụ, trong def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass1, def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 không phải là một giá trị đang được sử dụng, nhưng có nghĩa là nén là tùy chọn và không có nén nào được sử dụng nếu không được cung cấp. Trong trường hợp này, chúng tôi sẽ sử dụng def astype(dtype): """ Cast Series type. This section will provide further details. """ pass9. Chỉ trong các trường hợp như def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass4 và def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 mới được sử dụng theo cách tương tự như def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass6 hoặc def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass7 mới được sử dụng, thì chúng tôi sẽ chỉ định STR, int hoặc không, mặc định không có gì. Good: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num20 Bad: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num21 Các loại tham số#Khi chỉ định các loại tham số, các loại dữ liệu tích hợp Python có thể được sử dụng trực tiếp (loại Python được ưu tiên hơn chuỗi dài dòng, Integer, Boolean, v.v.):
Đối với các loại phức tạp, xác định các phân nhóm. Đối với def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass8 và def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass9, vì có nhiều loại có mặt, chúng tôi sử dụng giá đỡ để giúp đọc loại (dấu ngoặc xoăn cho def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass8 và dấu ngoặc thông thường cho def astype(dtype): """ Casts Series type. Verb in third-person of the present simple, should be infinitive. """ pass9):
Trong trường hợp chỉ có một tập hợp các giá trị được phép, hãy liệt kê chúng trong các dấu ngoặc xoăn và được phân tách bằng dấu phẩy (tiếp theo là một không gian). Nếu các giá trị là thứ tự và chúng có một đơn đặt hàng, hãy liệt kê chúng theo thứ tự này. Nếu không, hãy liệt kê giá trị mặc định trước tiên, nếu có:
Nếu loại được xác định trong mô -đun Python, mô -đun phải được chỉ định:
Nếu loại nằm trong một gói, mô -đun cũng phải được chỉ định:
Nếu loại là loại gấu trúc, cũng chỉ định gấu trúc ngoại trừ loạt và dataFrame:
Nếu loại chính xác không liên quan, nhưng phải tương thích với một mảng numpy, giống như mảng có thể được chỉ định. Nếu bất kỳ loại nào có thể được lặp lại được chấp nhận, có thể sử dụng ITEBLE:
Nếu có nhiều loại được chấp nhận, hãy tách chúng ra bằng dấu phẩy, ngoại trừ hai loại cuối cùng, cần phải được phân tách bằng từ ‘hoặc Hồi::
Nếu def astype(dtype): """ Cast Series type. This section will provide further details. """ pass7 là một trong những giá trị được chấp nhận, thì nó luôn cần phải là người cuối cùng trong danh sách. Đối với trục, quy ước là sử dụng một cái gì đó như:
Phần 4: Trả về hoặc sản lượng#Nếu phương thức trả về một giá trị, nó sẽ được ghi lại trong phần này. Ngoài ra nếu phương thức mang lại đầu ra của nó. Tiêu đề của phần sẽ được xác định theo cách tương tự như các tham số của Google. Với các tên, trả về, hay, người khác đã tạo ra một dòng có nhiều dấu gạch ngang như các chữ cái trong từ trước. Tài liệu về lợi nhuận cũng tương tự như các tham số. Nhưng trong trường hợp này, sẽ không có tên nào được cung cấp, trừ khi phương thức trả về hoặc mang lại nhiều hơn một giá trị (một bộ giá trị). Các loại cho các loại trả về trên mạng và các sản phẩm của người khác, giống như các loại đối với các tham số của các tham số. Ngoài ra, mô tả phải kết thúc với một dấu chấm. Ví dụ: với một giá trị duy nhất: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num22 Với nhiều hơn một giá trị: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num23 Nếu phương thức mang lại giá trị của nó: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num24 Phần 5: Xem thêm#Phần này được sử dụng để cho người dùng biết về chức năng gấu trúc liên quan đến phần được ghi lại. Trong các trường hợp hiếm hoi, nếu không có phương pháp hoặc chức năng liên quan nào có thể được tìm thấy, phần này có thể được bỏ qua. Một ví dụ rõ ràng sẽ là các phương pháp def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass3 và def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass4. Vì def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass4 tương đương với def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass3 nhưng vào cuối def astype(dtype): """ Cast Series type. This section will provide further details. """ pass1 hoặc def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass8 thay vì lúc đầu, thật tốt khi cho người dùng biết về nó. Để đưa ra trực giác về những gì có thể được xem xét liên quan, ở đây có một số ví dụ:
Khi quyết định những gì có liên quan, bạn chủ yếu nên sử dụng ý thức chung của mình và suy nghĩ về những gì có thể hữu ích cho người dùng đọc tài liệu, đặc biệt là những người ít kinh nghiệm hơn. Khi liên quan đến các thư viện khác (chủ yếu là def astype(dtype): """ Cast Series type from its current type to the new type defined in the parameter dtype. Summary is too verbose and doesn't fit in a single line. """ pass8), hãy sử dụng tên của mô -đun trước (không phải là bí danh như def astype(dtype): """ Cast Series type from its current type to the new type defined in the parameter dtype. Summary is too verbose and doesn't fit in a single line. """ pass9). Nếu hàm nằm trong một mô -đun không phải là chính, như def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass0, hãy liệt kê mô -đun đầy đủ (ví dụ: def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass1). Phần này có một tiêu đề, còn xem thêm (lưu ý vốn S và A), theo sau là dòng có dấu gạch nối và đi trước một dòng trống. Sau khi tiêu đề, chúng tôi sẽ thêm một dòng cho từng phương pháp hoặc hàm liên quan, theo sau là một không gian, một dấu hai chấm, một không gian khác và một mô tả ngắn minh họa phương pháp hoặc chức năng này, tại sao nó có liên quan trong bối cảnh này và những gì Sự khác biệt chính là giữa hàm được ghi lại và một được tham chiếu. Mô tả cũng phải kết thúc bằng một dấu chấm. Lưu ý rằng trong các trò chơi trả về của người Hồi giáo và các sản phẩm của người khác, mô tả được đặt trên dòng sau loại. Tuy nhiên, trong phần này, nó nằm trên cùng một dòng, với một dấu hai chấm ở giữa. Nếu mô tả không phù hợp với cùng một dòng, nó có thể tiếp tục vào các dòng khác phải được thụt thêm. Ví dụ: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num25 Phần 6: Ghi chú#Đây là một phần tùy chọn được sử dụng cho các ghi chú về việc thực hiện thuật toán hoặc để ghi lại các khía cạnh kỹ thuật của hành vi chức năng. Hãy bỏ qua nó, trừ khi bạn quen thuộc với việc thực hiện thuật toán hoặc bạn khám phá một số hành vi phản trực quan trong khi viết các ví dụ cho hàm. Phần này theo định dạng giống như phần tóm tắt mở rộng. Phần 7: Ví dụ#Đây là một trong những phần quan trọng nhất của một tài liệu, mặc dù được đặt ở vị trí cuối cùng, vì thường mọi người hiểu các khái niệm tốt hơn bằng ví dụ hơn là thông qua các giải thích chính xác. Các ví dụ trong tài liệu, bên cạnh việc minh họa việc sử dụng hàm hoặc phương thức, phải là mã Python hợp lệ, trả về đầu ra đã cho theo cách xác định và có thể được sao chép và chạy bởi người dùng. Các ví dụ được trình bày như một phiên trong Terminal Python. def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass2 được sử dụng để hiện tại mã. def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass3 được sử dụng để mã tiếp tục từ dòng trước. Đầu ra được trình bày ngay sau dòng mã cuối cùng tạo ra đầu ra (không có dòng trống ở giữa). Nhận xét mô tả các ví dụ có thể được thêm vào với các dòng trống trước và sau chúng. Cách để trình bày các ví dụ như sau:
Một ví dụ đơn giản có thể là: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num26 Các ví dụ nên ngắn gọn nhất có thể. Trong trường hợp sự phức tạp của hàm yêu cầu các ví dụ dài, được khuyến nghị sử dụng các khối có tiêu đề in đậm. Sử dụng Double Star def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass6 để tạo văn bản đậm, như trong def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass7. Các quy ước cho các ví dụ#Mã trong các ví dụ được giả định luôn bắt đầu với hai dòng không được hiển thị: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num27 Bất kỳ mô -đun nào khác được sử dụng trong các ví dụ phải được nhập rõ ràng, một dòng trên mỗi dòng (như được khuyến nghị trong nhập khẩu PEP 8#) và tránh các bí danh. Tránh nhập khẩu quá mức, nhưng nếu cần, nhập từ thư viện tiêu chuẩn đi trước, tiếp theo là các thư viện của bên thứ ba (như matplotlib).PEP 8#imports) and avoiding aliases. Avoid excessive imports, but if needed, imports from the standard library go first, followed by third-party libraries (like matplotlib). Khi minh họa các ví dụ với một def astype(dtype): """ Cast Series type. This section will provide further details. """ pass1, hãy sử dụng tên def unstack(): """ Pivot a row index to columns. When using a MultiIndex, a level can be pivoted so each value in the index becomes a column. This is especially useful when a subindex is repeated for the main index, and data is easier to visualize as a pivot table. The index level will be automatically removed from the index when added as columns. """ pass9 và nếu minh họa với một def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass8, hãy sử dụng tên def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num201. Đối với các chỉ số, def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num202 là tên ưa thích. Một tập hợp đồng nhất def astype(dtype): """ Cast Series type. This section will provide further details. """ pass1 hoặc def astype(dtype): """ Method to cast Series type. Does not start with verb. """ pass8 được sử dụng, hãy đặt tên cho chúng def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num205, def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num206, ________ 107, hoặc def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num208, def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num209, ________ 110 và def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num212. Dữ liệu được sử dụng trong ví dụ phải nhỏ gọn nhất có thể. Số lượng hàng được khuyến nghị là khoảng 4, nhưng làm cho nó trở thành một số có ý nghĩa cho ví dụ cụ thể. Ví dụ: trong phương thức def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num213, nó yêu cầu cao hơn 5, để hiển thị ví dụ với các giá trị mặc định. Nếu thực hiện def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num214, chúng ta có thể sử dụng một cái gì đó như def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num215, vì vậy thật dễ dàng để thấy rằng giá trị được trả về là giá trị trung bình. Để biết các ví dụ phức tạp hơn (ví dụ nhóm), tránh sử dụng dữ liệu mà không cần diễn giải, như ma trận các số ngẫu nhiên có cột A, B, C, D, và thay vào đó sử dụng một ví dụ có ý nghĩa, giúp dễ hiểu khái niệm này dễ dàng hơn. Trừ khi được yêu cầu bởi ví dụ, sử dụng tên của động vật, để giữ cho các ví dụ nhất quán. Và tính chất số của chúng. Khi gọi phương thức, các từ khóa đối số def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num216 được ưu tiên cho các đối số vị trí def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num217. Good: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num28 Bad: def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num29 Mẹo để nhận các ví dụ của bạn vượt qua các tài liệu#Nhận các ví dụ vượt qua các tài liệu trong tập lệnh xác thực đôi khi có thể là khó khăn. Dưới đây là một số điểm chú ý:
Lô trong ví dụ#Có một số phương pháp trong các lô trở lại gấu trúc. Để hiển thị các sơ đồ được tạo bởi các ví dụ trong tài liệu, chỉ thị def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num222 tồn tại. Để sử dụng nó, hãy đặt mã tiếp theo sau tiêu đề của các ví dụ trên mạng như được hiển thị bên dưới. Cốt truyện sẽ được tạo tự động khi xây dựng tài liệu. def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)5 Chia sẻ tài liệu#Pandas có một hệ thống để chia sẻ các tài liệu, với các biến thể nhỏ, giữa các lớp. Điều này giúp chúng tôi giữ cho các tài liệu nhất quán, trong khi giữ cho mọi thứ rõ ràng cho người dùng đọc. Nó đến với chi phí của một số phức tạp khi viết. Mỗi tài liệu được chia sẻ sẽ có một mẫu cơ sở với các biến, như def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num223. Các biến được điền vào sau đó sử dụng bộ trang trí def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num224. Cuối cùng, Docstrings cũng có thể được thêm vào với người trang trí def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num224. Trong ví dụ này, chúng tôi sẽ tạo ra một tài liệu cha mẹ bình thường (điều này giống như def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num226. Sau đó, chúng tôi sẽ có hai con (như def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num227 và def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num228). Chúng tôi sẽ thay thế các tên lớp trong tài liệu này.
def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)6 Các tài liệu kết quả là def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)7 Notice:
Các tệp của chúng tôi thường sẽ chứa một cấp độ mô-đun def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num229 với một số giá trị thay thế phổ biến (những thứ như def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num230, def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num231, v.v.). Bạn có thể thay thế và nối thêm một phát bằng một cái gì đó như def add_values(arr): """ Add the values in ``arr``. This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`. Some sections are omitted here for simplicity. """ return sum(arr)8 trong đó def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num232 có thể đến từ một cấp độ mô-đun def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num233 Tên chức năng ánh xạ từ điển đến DocStrings. Bất cứ nơi nào có thể, chúng tôi thích sử dụng def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num224, vì các quy trình viết tài liệu gần với bình thường hơn một chút. Xem def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num235 cho một mẫu ví dụ và def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num236 và def add(num1, num2): """ Add up two integer numbers. This function simply wraps the ``+`` operator, and does not do anything interesting, except for illustrating what the docstring of a very simple function looks like. Parameters ---------- num1 : int First number to add. num2 : int Second number to add. Returns ------- int The sum of ``num1`` and ``num2``. See Also -------- subtract : Subtract one integer from another. Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num237 cho các phiên bản điền. |