3. Developer Guides¶
Contents:
- 3.1. Exception Handling in Data Lab Services
- 3.2. Documenting Python APIs with Docstrings
- 3.2.1. Basic Format of Docstrings
- 3.2.1.1. Docstrings MUST be delimited by triple double quotes
- 3.2.1.2. Docstrings SHOULD begin with
"""
and terminate with"""
on its own line - 3.2.1.3. Docstrings of methods and functions SHOULD NOT be preceded or followed by a blank line
- 3.2.1.4. Docstrings of classes SHOULD be followed, but not preceded, by a blank line
- 3.2.1.5. Docstring content MUST be indented with the code’s scope
- 3.2.2. ReStructuredText in Docstrings
- 3.2.3. Numpydoc Sections in Docstrings
- 3.2.4. Documenting Modules
- 3.2.5. Documenting Classes
- 3.2.6. Documenting Methods and Functions
- 3.2.7. Documenting Constants and Class Attributes
- 3.2.8. Documenting Class Properties
- 3.2.9. Complete Example Module
- 3.2.10. Acknowledgements
- 3.2.1. Basic Format of Docstrings
- 3.3. Python Performance Profiling
- 3.4. Data Lab Python Style Guide
- 3.4.1. Introduction
- 3.4.2. 0. Python Version
- 3.4.3. 1. PEP 8 is the Baseline Coding Style
- 3.4.4. 2. Layout
- 3.4.4.1. Service Configuration Information MUST be stored externally
- 3.4.4.2. Client-side Configuration Information
- 3.4.4.3. Packages SHOULD import only what is necessary
- 3.4.4.4. Exportable Python packages MUST contain a standard license file
- 3.4.4.5. Docstring and comment line length MUST be less than or equal to 79 columns
- 3.4.5. 3. Whitespace
- 3.4.6. 4. Comments
- 3.4.7. 5. Documentation Strings (docstrings)
- 3.4.8. 6. Naming Conventions
- 3.4.8.1. Modules which contain class definitions SHOULD be named after the class name
- 3.4.8.2. User-defined names SHOULD NOT shadow python built-in functions
- 3.4.8.3. Names l (lowercase: el), O (uppercase: oh), I (uppercase: eye) MUST be avoided
- 3.4.8.4. Always use
cls
for the first argument to metaclass instance methods
- 3.4.9. 7. Source Files & Modules
- 3.4.10. 8. Classes
- 3.4.11. 9. Comparisons
- 3.4.12. 10. Idiomatic Python
- 3.4.12.1. A mutable object MUST NOT be used as a keyword argument default
- 3.4.12.2. Context managers (
with
) SHOULD be used for resource allocation - 3.4.12.3. Avoid
dict.keys()
when iterating over keys or checking membership - 3.4.12.4. The
subprocess
module SHOULD be used to spawn processes - 3.4.12.5.
lambda
SHOULD NOT be used - 3.4.12.6. The
set
type SHOULD be used for unordered collections - 3.4.12.7. Iterators and generators SHOULD be used to iterate over large data sets efficiently
- 3.4.12.8.
if False:
andif True:
SHOULD NOT be used - 3.4.12.9. Python exceptions SHOULD be raised and checked in Python code
- 3.5. Python Unit Testing
- 3.6. ReStructuredText Sample
- 3.7. ReStructuredText Style Guide
- 3.7.1. Sample
- 3.7.2. Inline Text Styling
- 3.7.3. Lists
- 3.7.4. Sections
- 3.7.5. Linking
- 3.7.6. Tables
- 3.7.7. Images and Figures
- 3.7.8. Math
- 3.7.9. Source code
- 3.7.10. Command line prompts
- 3.7.11. Footnotes
- 3.7.12. Citations
- 3.7.13. Comments in ReStructuredText
- 3.7.14. RestructuredText Formatting Conventions
- 3.8. Page Title Example