• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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(2022, 8, 22)
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://tensorflow.org/guide/version_compat#backward_forward).
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()
169