Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorflow/python/framework/tensor_conversion.py: 83%

1# Copyright 2023 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"""Tensor conversion functions.""" 

16from tensorflow.python.framework import tensor_conversion_registry 

17from tensorflow.python.util import deprecation 

18from tensorflow.python.util import dispatch 

19from tensorflow.python.util import tf_export 

20 

21 

22def convert_to_tensor_v1( 

23 value, dtype=None, name=None, preferred_dtype=None, dtype_hint=None 

24): 

25 """Converts the given `value` to a `Tensor` (with the TF1 API).""" 

26 preferred_dtype = deprecation.deprecated_argument_lookup( 

27 "dtype_hint", dtype_hint, "preferred_dtype", preferred_dtype 

28 ) 

29 return convert_to_tensor_v2(value, dtype, preferred_dtype, name) 

30 

31 

32@tf_export.tf_export(v1=["convert_to_tensor"]) 

33@dispatch.add_dispatch_support 

34def convert_to_tensor_v1_with_dispatch( 

35 value, dtype=None, name=None, preferred_dtype=None, dtype_hint=None 

36): 

37 """Converts the given `value` to a `Tensor`. 

38 

39 This function converts Python objects of various types to `Tensor` 

40 objects. It accepts `Tensor` objects, numpy arrays, Python lists, 

41 and Python scalars. For example: 

42 

43 ```python 

44 import numpy as np 

45 

46 def my_func(arg): 

47 arg = tf.convert_to_tensor(arg, dtype=tf.float32) 

48 return tf.matmul(arg, arg) + arg 

49 

50 # The following calls are equivalent. 

51 value_1 = my_func(tf.constant([[1.0, 2.0], [3.0, 4.0]])) 

52 value_2 = my_func([[1.0, 2.0], [3.0, 4.0]]) 

53 value_3 = my_func(np.array([[1.0, 2.0], [3.0, 4.0]], dtype=np.float32)) 

54 ``` 

55 

56 This function can be useful when composing a new operation in Python 

57 (such as `my_func` in the example above). All standard Python op 

58 constructors apply this function to each of their Tensor-valued 

59 inputs, which allows those ops to accept numpy arrays, Python lists, 

60 and scalars in addition to `Tensor` objects. 

61 

62 Note: This function diverges from default Numpy behavior for `float` and 

63 `string` types when `None` is present in a Python list or scalar. Rather 

64 than silently converting `None` values, an error will be thrown. 

65 

66 Args: 

67 value: An object whose type has a registered `Tensor` conversion function. 

68 dtype: Optional element type for the returned tensor. If missing, the type 

69 is inferred from the type of `value`. 

70 name: Optional name to use if a new `Tensor` is created. 

71 preferred_dtype: Optional element type for the returned tensor, used when 

72 dtype is None. In some cases, a caller may not have a dtype in mind when 

73 converting to a tensor, so preferred_dtype can be used as a soft 

74 preference. If the conversion to `preferred_dtype` is not possible, this 

75 argument has no effect. 

76 dtype_hint: same meaning as preferred_dtype, and overrides it. 

77 

78 Returns: 

79 A `Tensor` based on `value`. 

80 

81 Raises: 

82 TypeError: If no conversion function is registered for `value` to `dtype`. 

83 RuntimeError: If a registered conversion function returns an invalid value. 

84 ValueError: If the `value` is a tensor not of given `dtype` in graph mode. 

85 """ 

86 return convert_to_tensor_v1( 

87 value, 

88 dtype=dtype, 

89 name=name, 

90 preferred_dtype=preferred_dtype, 

91 dtype_hint=dtype_hint, 

92 ) 

93 

94 

95@tf_export.tf_export("convert_to_tensor", v1=[]) 

96@dispatch.add_dispatch_support 

97def convert_to_tensor_v2_with_dispatch( 

98 value, dtype=None, dtype_hint=None, name=None 

99): 

100 """Converts the given `value` to a `Tensor`. 

101 

102 This function converts Python objects of various types to `Tensor` 

103 objects. It accepts `Tensor` objects, numpy arrays, Python lists, 

104 and Python scalars. 

105 

106 For example: 

107 

108 >>> import numpy as np 

109 >>> def my_func(arg): 

110 ... arg = tf.convert_to_tensor(arg, dtype=tf.float32) 

111 ... return arg 

112 

113 >>> # The following calls are equivalent. 

114 ... 

115 >>> value_1 = my_func(tf.constant([[1.0, 2.0], [3.0, 4.0]])) 

116 >>> print(value_1) 

117 tf.Tensor( 

118 [[1. 2.] 

119 [3. 4.]], shape=(2, 2), dtype=float32) 

120 >>> value_2 = my_func([[1.0, 2.0], [3.0, 4.0]]) 

121 >>> print(value_2) 

122 tf.Tensor( 

123 [[1. 2.] 

124 [3. 4.]], shape=(2, 2), dtype=float32) 

125 >>> value_3 = my_func(np.array([[1.0, 2.0], [3.0, 4.0]], dtype=np.float32)) 

126 >>> print(value_3) 

127 tf.Tensor( 

128 [[1. 2.] 

129 [3. 4.]], shape=(2, 2), dtype=float32) 

130 

131 This function can be useful when composing a new operation in Python 

132 (such as `my_func` in the example above). All standard Python op 

133 constructors apply this function to each of their Tensor-valued 

134 inputs, which allows those ops to accept numpy arrays, Python lists, 

135 and scalars in addition to `Tensor` objects. 

136 

137 Note: This function diverges from default Numpy behavior for `float` and 

138 `string` types when `None` is present in a Python list or scalar. Rather 

139 than silently converting `None` values, an error will be thrown. 

140 

141 Args: 

142 value: An object whose type has a registered `Tensor` conversion function. 

143 dtype: Optional element type for the returned tensor. If missing, the type 

144 is inferred from the type of `value`. 

145 dtype_hint: Optional element type for the returned tensor, used when dtype 

146 is None. In some cases, a caller may not have a dtype in mind when 

147 converting to a tensor, so dtype_hint can be used as a soft preference. If 

148 the conversion to `dtype_hint` is not possible, this argument has no 

149 effect. 

150 name: Optional name to use if a new `Tensor` is created. 

151 

152 Returns: 

153 A `Tensor` based on `value`. 

154 

155 Raises: 

156 TypeError: If no conversion function is registered for `value` to `dtype`. 

157 RuntimeError: If a registered conversion function returns an invalid value. 

158 ValueError: If the `value` is a tensor not of given `dtype` in graph mode. 

159 """ 

160 return convert_to_tensor_v2( 

161 value, dtype=dtype, dtype_hint=dtype_hint, name=name 

162 ) 

163 

164 

165def convert_to_tensor_v2(value, dtype=None, dtype_hint=None, name=None): 

166 """Converts the given `value` to a `Tensor`.""" 

167 # preferred_dtype = preferred_dtype or dtype_hint 

168 return tensor_conversion_registry.convert( 

169 value, dtype, name, preferred_dtype=dtype_hint 

170 )