Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorflow/python/compat/compat.py: 73%

1# Copyright 2018 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"""Utilities for API compatibility between TensorFlow release versions. 

16 

17See [Version 

18Compatibility](https://tensorflow.org/guide/version_compat#backward_forward) 

19""" 

20 

21import datetime 

22import os 

23 

24from tensorflow.python.platform import tf_logging as logging 

25from tensorflow.python.util import tf_contextlib 

26from tensorflow.python.util.tf_export import tf_export 

27 

28 

29# This value changes every day with an automatic CL. It can be modified in code 

30# via `forward_compatibility_horizon()` or with the environment variable 

31# TF_FORWARD_COMPATIBILITY_DELTA_DAYS, which is added to the compatibility date. 

32_FORWARD_COMPATIBILITY_HORIZON = datetime.date(2023, 4, 30) 

33_FORWARD_COMPATIBILITY_DELTA_DAYS_VAR_NAME = "TF_FORWARD_COMPATIBILITY_DELTA_DAYS" 

34_FORWARD_COMPATIBILITY_DATE_NUMBER = None 

35 

36 

37def _date_to_date_number(year, month, day): 

38 return (year << 9) | (month << 5) | day 

39 

40 

41def _update_forward_compatibility_date_number(date_to_override=None): 

42 """Update the base date to compare in forward_compatible function.""" 

43 

44 global _FORWARD_COMPATIBILITY_DATE_NUMBER 

45 

46 if date_to_override: 

47 date = date_to_override 

48 else: 

49 date = _FORWARD_COMPATIBILITY_HORIZON 

50 delta_days = os.getenv(_FORWARD_COMPATIBILITY_DELTA_DAYS_VAR_NAME) 

51 if delta_days: 

52 date += datetime.timedelta(days=int(delta_days)) 

53 

54 if date < _FORWARD_COMPATIBILITY_HORIZON: 

55 logging.warning("Trying to set the forward compatibility date to the past" 

56 " date %s. This will be ignored by TensorFlow." % (date)) 

57 return 

58 _FORWARD_COMPATIBILITY_DATE_NUMBER = _date_to_date_number( 

59 date.year, date.month, date.day) 

60 

61 

62_update_forward_compatibility_date_number() 

63 

64 

65@tf_export("compat.forward_compatible") 

66def forward_compatible(year, month, day): 

67 """Return true if the forward compatibility window has expired. 

68 

69 See [Version 

70 compatibility](https://www.tensorflow.org/guide/versions#backward_and_partial_forward_compatibility). 

71 

72 Forward-compatibility refers to scenarios where the producer of a TensorFlow 

73 model (a GraphDef or SavedModel) is compiled against a version of the 

74 TensorFlow library newer than what the consumer was compiled against. The 

75 "producer" is typically a Python program that constructs and trains a model 

76 while the "consumer" is typically another program that loads and serves the 

77 model. 

78 

79 TensorFlow has been supporting a 3 week forward-compatibility window for 

80 programs compiled from source at HEAD. 

81 

82 For example, consider the case where a new operation `MyNewAwesomeAdd` is 

83 created with the intent of replacing the implementation of an existing Python 

84 wrapper - `tf.add`. The Python wrapper implementation should change from 

85 something like: 

86 

87 ```python 

88 def add(inputs, name=None): 

89 return gen_math_ops.add(inputs, name) 

90 ``` 

91 

92 to: 

93 

94 ```python 

95 from tensorflow.python.compat import compat 

96 

97 def add(inputs, name=None): 

98 if compat.forward_compatible(year, month, day): 

99 # Can use the awesome new implementation. 

100 return gen_math_ops.my_new_awesome_add(inputs, name) 

101 # To maintain forward compatibility, use the old implementation. 

102 return gen_math_ops.add(inputs, name) 

103 ``` 

104 

105 Where `year`, `month`, and `day` specify the date beyond which binaries 

106 that consume a model are expected to have been updated to include the 

107 new operations. This date is typically at least 3 weeks beyond the date 

108 the code that adds the new operation is committed. 

109 

110 Args: 

111 year: A year (e.g., 2018). Must be an `int`. 

112 month: A month (1 <= month <= 12) in year. Must be an `int`. 

113 day: A day (1 <= day <= 31, or 30, or 29, or 28) in month. Must be an 

114 `int`. 

115 

116 Returns: 

117 True if the caller can expect that serialized TensorFlow graphs produced 

118 can be consumed by programs that are compiled with the TensorFlow library 

119 source code after (year, month, day). 

120 """ 

121 return _FORWARD_COMPATIBILITY_DATE_NUMBER > _date_to_date_number( 

122 year, month, day) 

123 

124 

125@tf_export("compat.forward_compatibility_horizon") 

126@tf_contextlib.contextmanager 

127def forward_compatibility_horizon(year, month, day): 

128 """Context manager for testing forward compatibility of generated graphs. 

129 

130 See [Version 

131 compatibility](https://www.tensorflow.org/guide/versions#backward_and_partial_forward_compatibility). 

132 

133 To ensure forward compatibility of generated graphs (see `forward_compatible`) 

134 with older binaries, new features can be gated with: 

135 

136 ```python 

137 if compat.forward_compatible(year=2018, month=08, date=01): 

138 generate_graph_with_new_features() 

139 else: 

140 generate_graph_so_older_binaries_can_consume_it() 

141 ``` 

142 

143 However, when adding new features, one may want to unittest it before 

144 the forward compatibility window expires. This context manager enables 

145 such tests. For example: 

146 

147 ```python 

148 from tensorflow.python.compat import compat 

149 

150 def testMyNewFeature(self): 

151 with compat.forward_compatibility_horizon(2018, 08, 02): 

152 # Test that generate_graph_with_new_features() has an effect 

153 ``` 

154 

155 Args: 

156 year: A year (e.g., 2018). Must be an `int`. 

157 month: A month (1 <= month <= 12) in year. Must be an `int`. 

158 day: A day (1 <= day <= 31, or 30, or 29, or 28) in month. Must be an 

159 `int`. 

160 

161 Yields: 

162 Nothing. 

163 """ 

164 try: 

165 _update_forward_compatibility_date_number(datetime.date(year, month, day)) 

166 yield 

167 finally: 

168 _update_forward_compatibility_date_number()