|
| 1 | +# Docstrings and Type Hints |
| 2 | + |
| 3 | +All public methods should have docstrings to document the parameters, keywords, exceptions raised, and return types for each method. Models and clients should also document properties, instance variables, and class variables. |
| 4 | + |
| 5 | +* [Docstrings](#docstrings) |
| 6 | + * [Method Docstrings](#method_docstrings) |
| 7 | + * [Model and Client Docstrings](#Model_and_Client_Docstrings) |
| 8 | +* [Type Hints](#type_hints) |
| 9 | + * [Type Hints for Python 2.7 and 3.5+](#type_hints_for_python_2.7_and_3.5+) |
| 10 | + * [Type Hints for Python 3.5+](#type_hints_for_python_3.5+) |
| 11 | + |
| 12 | +## Docstrings |
| 13 | + |
| 14 | +Docstrings are noted by the Python long-string `"""<docstring>"""`. When adding docstrings the `~` can be optionally added to the front of a custom model, this will only display the actual model name in the documentation. For example a type that looks like `azure.data.tables.TableEntity` will display the entire path in the documentation, but `~azure.data.tables.TableEntity` will only display `TableEntity` in the documentation. Additionally, adding the wrapper `` :class:`~azure.data.tables.TableEntity` `` will display only `TableEntity` formatted in monospace font. These documentation methods will also create direct links to the type documentation. Both of these capabilities are optional and can only be used in the two-line format described below. |
| 15 | + |
| 16 | +### Method Docstrings |
| 17 | + |
| 18 | +A method docstring is annotated by the Python long-string `"""<docstring>"""` right after the method definition. The convention is a short line ending with a period, two new lines, followed by a longer description. Below is an example of a full docstring from `azure-ai-formrecognizer`: |
| 19 | +```python |
| 20 | + @distributed_trace |
| 21 | + def begin_training(self, training_files_url, use_training_labels, **kwargs): |
| 22 | + # type: (str, bool, Any) -> LROPoller[CustomFormModel] |
| 23 | + """Create and train a custom model. |
| 24 | +
|
| 25 | + The request must include a `training_files_url` parameter that is an |
| 26 | + externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that |
| 27 | + a container URI (without SAS) is accepted only when the container is public. |
| 28 | + Models are trained using documents that are of the following content type - 'application/pdf', |
| 29 | + 'image/jpeg', 'image/png', 'image/tiff', or 'image/bmp'. Other types of content in the container is ignored. |
| 30 | +
|
| 31 | + :param str training_files_url: An Azure Storage blob container's SAS URI. A container URI (without SAS) |
| 32 | + can be used if the container is public. For more information on setting up a training data set, see: |
| 33 | + https://docs.microsoft.com/azure/cognitive-services/form-recognizer/build-training-data-set |
| 34 | + :param bool use_training_labels: Whether to train with labels or not. Corresponding labeled files must |
| 35 | + exist in the blob container if set to `True`. |
| 36 | + :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for |
| 37 | + training. For example, when using a Azure storage blob URI, use the prefix to restrict sub |
| 38 | + folders for training. |
| 39 | + :keyword include_subfolders: A flag to indicate if subfolders within the set of prefix folders |
| 40 | + will also need to be included when searching for content to be preprocessed. Not supported if |
| 41 | + training with labels. |
| 42 | + :paramtype include_subfolders: bool |
| 43 | + :keyword str model_name: An optional, user-defined name to associate with your model. |
| 44 | + :keyword continuation_token: A continuation token to restart a poller from a saved state. |
| 45 | + :paramtype continuation_token: str |
| 46 | + :return: An instance of an LROPoller. Call `result()` on the poller |
| 47 | + object to return a :class:`~azure.ai.formrecognizer.CustomFormModel`. |
| 48 | + :rtype: ~azure.core.polling.LROPoller[~azure.ai.formrecognizer.CustomFormModel] |
| 49 | + :raises ~azure.core.exceptions.HttpResponseError: |
| 50 | + Note that if the training fails, the exception is raised, but a model with an |
| 51 | + "invalid" status is still created. You can delete this model by calling :func:`~delete_model()` |
| 52 | +
|
| 53 | + .. versionadded:: v2.1 |
| 54 | + The *model_name* keyword argument |
| 55 | +
|
| 56 | + .. admonition:: Example: |
| 57 | +
|
| 58 | + .. literalinclude:: ../samples/sample_train_model_without_labels.py |
| 59 | + :start-after: [START training] |
| 60 | + :end-before: [END training] |
| 61 | + :language: python |
| 62 | + :dedent: 8 |
| 63 | + :caption: Training a model (without labels) with your custom forms. |
| 64 | + """ |
| 65 | + ... |
| 66 | +``` |
| 67 | + |
| 68 | +The first portion of this docstring is a general description of what the method does. Following the general description of the method is a **required new line** and then documentation for each of the parameters, optional keyword arguments, returned objects, and potentially raised errors. |
| 69 | + |
| 70 | +Positional parameters can be documented in one-line or two-lines. Both options can be used in a single docstring for documenting different parameters without issue. |
| 71 | +1. This option works best for parameters that are one of the basic types (`str`, `int`, `bool`, `bytes`, `float`, etc.) |
| 72 | +```python |
| 73 | +:param <type> <param_name>: <Description of the parameter> |
| 74 | +``` |
| 75 | +2. This option works best for parameters that use custom models or have many different options |
| 76 | +```python |
| 77 | +:param <param_name>: <Description of the parameter> |
| 78 | +:type <param_name>: <param_type> |
| 79 | +``` |
| 80 | + |
| 81 | +Optional keyword arguments can be documented in one-line or two-lines. Both options can be used in a single docstring for documenting different keywords without issue. Keywords includes kwargs and in Python 3 code only, parameters after `*` character. |
| 82 | +1. This option works best for keyword args that are one of the basic types (`str`, `int`, `bool`, `bytes`, `float`, etc.) |
| 83 | +```python |
| 84 | +:keyword <type> <keyword_name>: <Description of the keyword> |
| 85 | +``` |
| 86 | +2. This option works best for keyword that use custom models or have many different options |
| 87 | +```python |
| 88 | +:keyword <keyword_name>: <Description of the keyword> |
| 89 | +:paramtype <keyword_name>: <keyword_type> |
| 90 | +``` |
| 91 | + |
| 92 | +The returned object is documented on two lines, the first describing what the returned object is and the second describing what the returned type is. |
| 93 | +```python |
| 94 | +""" |
| 95 | +:return: <Description of the returned object> |
| 96 | +:rtype: <Type of the returned object> |
| 97 | +""" |
| 98 | +``` |
| 99 | + |
| 100 | +Finally, describe the possible errors raised by a method: |
| 101 | +```python |
| 102 | +:raises <error1>, <error2>, or <error3>: <description> |
| 103 | +``` |
| 104 | + |
| 105 | +All of the above information needs to be added for each public method and there **needs to be a newline after the above docstrings**. There are additional options for including examples and version specific additions. |
| 106 | + |
| 107 | +For adding a version specific change use the `versionadded` docstring: |
| 108 | +``` |
| 109 | +.. versionadded:: <version_number> |
| 110 | +
|
| 111 | +``` |
| 112 | + |
| 113 | +Additional sphinx directives are documented [here](https://review.docs.microsoft.com/help/onboard/admin/reference/python/documenting-api?branch=master#supported-sphinx-directives) |
| 114 | + |
| 115 | +### Model and Client Docstrings |
| 116 | + |
| 117 | +For documenting the properties of a model or client, include a docstring right after the `__init__` method or immediately after the class declaration |
| 118 | + |
| 119 | +Here is an example in `azure-ai-textanalytics`: |
| 120 | +```python |
| 121 | +class DetectedLanguage(DictMixin): |
| 122 | + """DetectedLanguage contains the predicted language found in text, |
| 123 | + its confidence score, and its ISO 639-1 representation. |
| 124 | +
|
| 125 | + :ivar name: Long name of a detected language (e.g. English, |
| 126 | + French). |
| 127 | + :vartype name: str |
| 128 | + :ivar iso6391_name: A two letter representation of the detected |
| 129 | + language according to the ISO 639-1 standard (e.g. en, fr). |
| 130 | + :vartype iso6391_name: str |
| 131 | + :ivar confidence_score: A confidence score between 0 and 1. Scores close |
| 132 | + to 1 indicate 100% certainty that the identified language is true. |
| 133 | + :vartype confidence_score: float |
| 134 | + """ |
| 135 | +``` |
| 136 | + |
| 137 | +The properties of a model should be documented with the `ivar` docstring: |
| 138 | +``` |
| 139 | +:ivar <property_name>: <description> |
| 140 | +:vartype <property_name>: <type> |
| 141 | +``` |
| 142 | + |
| 143 | +Models that are used as a positional or keyword argument for methods that make service calls should have docstrings that expand past `ivars`. Below is an example of a model from `azure-ai-translation-document` that has positional and keyword argument parameters documented. |
| 144 | + |
| 145 | +```python |
| 146 | +class DocumentTranslationInput(object): # pylint: disable=useless-object-inheritance |
| 147 | + # pylint: disable=C0301 |
| 148 | + """Input for translation. This requires that you have your source document or |
| 149 | + documents in an Azure Blob Storage container. Provide a SAS URL to the source file or |
| 150 | + source container containing the documents for translation. The source document(s) are |
| 151 | + translated and written to the location provided by the TranslationTargets. |
| 152 | +
|
| 153 | + :param str source_url: Required. Location of the folder / container or single file with your |
| 154 | + documents. |
| 155 | + :param targets: Required. Location of the destination for the output. This is a list of |
| 156 | + TranslationTargets. Note that a TranslationTarget is required for each language code specified. |
| 157 | + :type targets: list[~azure.ai.translation.document.TranslationTarget] |
| 158 | + :keyword str source_language_code: Language code for the source documents. |
| 159 | + If none is specified, the source language will be auto-detected for each document. |
| 160 | + :keyword str prefix: A case-sensitive prefix string to filter documents in the source path for |
| 161 | + translation. For example, when using a Azure storage blob Uri, use the prefix to restrict |
| 162 | + sub folders for translation. |
| 163 | + :keyword str suffix: A case-sensitive suffix string to filter documents in the source path for |
| 164 | + translation. This is most often use for file extensions. |
| 165 | + :keyword storage_type: Storage type of the input documents source string. Possible values |
| 166 | + include: "Folder", "File". |
| 167 | + :paramtype storage_type: str or ~azure.ai.translation.document.StorageInputType |
| 168 | + :keyword str storage_source: Storage Source. Default value: "AzureBlob". |
| 169 | + Currently only "AzureBlob" is supported. |
| 170 | +
|
| 171 | + :ivar str source_url: Required. Location of the folder / container or single file with your |
| 172 | + documents. |
| 173 | + :ivar targets: Required. Location of the destination for the output. This is a list of |
| 174 | + TranslationTargets. Note that a TranslationTarget is required for each language code specified. |
| 175 | + :vartype targets: list[~azure.ai.translation.document.TranslationTarget] |
| 176 | + :ivar str source_language_code: Language code for the source documents. |
| 177 | + If none is specified, the source language will be auto-detected for each document. |
| 178 | + :ivar str prefix: A case-sensitive prefix string to filter documents in the source path for |
| 179 | + translation. For example, when using a Azure storage blob Uri, use the prefix to restrict |
| 180 | + sub folders for translation. |
| 181 | + :ivar str suffix: A case-sensitive suffix string to filter documents in the source path for |
| 182 | + translation. This is most often use for file extensions. |
| 183 | + :ivar storage_type: Storage type of the input documents source string. Possible values |
| 184 | + include: "Folder", "File". |
| 185 | + :vartype storage_type: str or ~azure.ai.translation.document.StorageInputType |
| 186 | + :ivar str storage_source: Storage Source. Default value: "AzureBlob". |
| 187 | + Currently only "AzureBlob" is supported. |
| 188 | + """ |
| 189 | +``` |
| 190 | + |
| 191 | +Positional parameters and keyword arguments are documented in the exact same way as a client method would be, using the `param` and `keyword` descriptors. Although not required, a new line between `param` and `keyword` descriptors helps to separate the docstring into logically separated groups. |
| 192 | + |
| 193 | + |
| 194 | +## Type Hints |
| 195 | + |
| 196 | +### Type Hints for Python 2.7 and 3.5+ |
| 197 | + |
| 198 | +Python 2.7 does not support in-line type hints, the type hints for all sync code will have to adhere to type-hints in comments only. On all public methods include a type-hint by using the `# type: (...) -> (...)` format: |
| 199 | +```python |
| 200 | +def add(num1, num2): |
| 201 | + # type: (int, int) -> int |
| 202 | + return num1 + num2 |
| 203 | +``` |
| 204 | +The spacing in type hints is important, there must be a space between "#" and "type", after the semicolon, and before and after the "->". If the type hint is not properly formatted API View will not recognize them. |
| 205 | + |
| 206 | +Here is a more complex example from `azure-ai-textanalytics` |
| 207 | +```python |
| 208 | +from typing import List, Dict, Union, TYPE_CHECKING |
| 209 | + |
| 210 | +if TYPE_CHECKING: |
| 211 | + from ._models import TextDocumentInput, RecognizeEntitiesResult |
| 212 | + |
| 213 | +def recognize_entities( |
| 214 | + self, |
| 215 | + documents, # type: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]] |
| 216 | + **kwargs # type: Any |
| 217 | +): |
| 218 | + # type: (...) -> List[Union[RecognizeEntitiesResult, DocumentError]] |
| 219 | +``` |
| 220 | + |
| 221 | +If a parameter can be one of many types use the `Union` type to describe all possible options. Types such as dict, list, and tuple have to be imported from the `typing` module as demonstrated at the top of the snippet. For the complex types (Dict, List, Tuple), the inner type has to be declared as well. For example, a list of strings is `List[str]`, a dictionary mapping strings to many different types of objects can be described as `Dict[str, object]`. Custom types have to be imported under a type checking conditional, importing `TYPE_CHECKING` from the `typing` module and only importing the custom models within this `if` statement. |
| 222 | + |
| 223 | +### Type Hints for Python 3.5+ |
| 224 | + |
| 225 | +The async models and clients are only valid in Python 3.5+ which allows for the use of in-line type hints. A simple example follows: |
| 226 | +```python |
| 227 | +def add(num1: int, num2: int) -> int: |
| 228 | + return num1 + num2 |
| 229 | +``` |
| 230 | + |
| 231 | +Here is a more complex example from `azure-ai-textanalytics` |
| 232 | +```python |
| 233 | +from typing import List, Dict, Union |
| 234 | +from ._models import TextDocumentInput, RecognizeEntitiesResult |
| 235 | + |
| 236 | +def recognize_entities( |
| 237 | + self, |
| 238 | + documents: Union[List[str], List[TextDocumentInput], List[Dict[str, str]]], |
| 239 | + **kwargs: Any |
| 240 | +) -> List[Union[RecognizeEntitiesResult, DocumentError]]: |
| 241 | +``` |
| 242 | +Note that in the in-line type hints the custom models do not to be guarded by an `if TYPE_CHECKING` conditional. These custom models must be included in imports or the program will fail on the type not being found. Do not use `dict[str,list[str]]`, always use the upper case version from the `typing` module, instead do `Dict[str, List[str]]`. |
0 commit comments