Skip to content

Commit d42df65

Browse files
yashk2810tensorflower-gardener
yashk2810
authored and
tensorflower-gardener
committed
Add utilities so as to generate pages on tf.org for type aliases. The sys.version_info guard will make sure it works with all versions of python that TF supports. The API docs will be generated in kokoro in python 3.7.
PiperOrigin-RevId: 321266183 Change-Id: I90178f93227e932ff0dc464a4293c399a99d0b9f
1 parent bfeba4d commit d42df65

3 files changed

Lines changed: 76 additions & 22 deletions

File tree

‎tensorflow/python/types/BUILD‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,20 @@ py_strict_library(
3232
"//tensorflow:types_whitelist",
3333
],
3434
deps = [
35+
":doc_typealias",
3536
"//tensorflow/python:tf_export",
3637
"//third_party/py/numpy",
3738
],
3839
)
40+
41+
py_strict_library(
42+
name = "doc_typealias",
43+
srcs = [
44+
"doc_typealias.py",
45+
],
46+
srcs_version = "PY2AND3",
47+
visibility = [
48+
"//tensorflow:__subpackages__",
49+
],
50+
deps = [],
51+
)

‎tensorflow/python/types/core.py‎

Lines changed: 28 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,12 @@
1818
from __future__ import division
1919
from __future__ import print_function
2020

21+
import textwrap
22+
2123
from typing import Union
2224
import numpy as np
2325

26+
from tensorflow.python.types import doc_typealias
2427
from tensorflow.python.util.tf_export import tf_export
2528

2629
# TODO(mdan): Consider adding ABC once the dependence on isinstance is reduced.
@@ -64,29 +67,32 @@ def numpy(self):
6467
pass
6568

6669

67-
# TODO(rahulkamat): Add missing types that are convertible to tensor
68-
# A `Union` type which can be used to denote "Tensor or other values that
69-
# TensorFlow implicitly converts to Tensor". For example, it includes
70-
# `list` and `ndarray`.
71-
#
72-
# This union will contain `tf.Tensor` and all types which can be successfully
73-
# converted to a `tf.Tensor` by `tf.convert_to_tensor`.
74-
#
75-
# This definition may be used in user code. Additional types may be added in the
76-
# future as more input types are supported.
77-
#
78-
# Example:
79-
#
80-
# def foo(tensor_like: TensorLike):
81-
# pass
82-
#
83-
# This definition passes static type verification for:
84-
#
85-
# foo(tf.constant([1, 2, 3]))
86-
# foo([1, 2, 3])
87-
# foo(np.array([1, 2, 3]))
88-
#
70+
# TODO(rahulkamat): Add missing types that are convertible to Tensor.
8971
TensorLike = Union[Tensor, int, float, bool, str, complex, tuple, list,
9072
np.ndarray]
73+
doc_typealias.document(
74+
obj=TensorLike,
75+
doc=textwrap.dedent("""\
76+
Union of all types that can be converted to a `tf.Tensor` by `tf.convert_to_tensor`.
77+
78+
This definition may be used in user code. Additional types may be added
79+
in the future as more input types are supported.
80+
81+
# Example:
82+
83+
```
84+
def foo(x: TensorLike):
85+
pass
86+
```
87+
88+
This definition passes static type verification for:
89+
90+
```
91+
foo(tf.constant([1, 2, 3]))
92+
foo([1, 2, 3])
93+
foo(np.array([1, 2, 3]))
94+
```
95+
"""),
96+
)
9197
tf_export("types.experimental.TensorLike").export_constant(
9298
__name__, "TensorLike")

‎tensorflow/python/types/doc_typealias.py‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Copyright 2020 The TensorFlow Authors. All Rights Reserved.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
# ==============================================================================
15+
"""Helper functions to add documentation to type aliases."""
16+
17+
from __future__ import absolute_import
18+
from __future__ import division
19+
from __future__ import print_function
20+
21+
import sys
22+
23+
24+
def document(obj, doc):
25+
"""Adds a docstring to typealias by overriding the `__doc__` attribute.
26+
27+
Note: Overriding `__doc__` is only possible after python 3.7.
28+
29+
Args:
30+
obj: Typealias object that needs to be documented.
31+
doc: Docstring of the typealias. It should follow the standard pystyle
32+
docstring rules.
33+
"""
34+
if sys.version_info >= (3, 7):
35+
obj.__doc__ = doc

0 commit comments

Comments
 (0)