From cb3dbf7e836fa2db53a778584c61cc04e94a4a4e Mon Sep 17 00:00:00 2001
From: Anna R <annarev@google.com>
Date: Mon, 3 Dec 2018 14:01:53 -0800
Subject: [PATCH] Update README.md doc for tf_upgrade_v2.py.
PiperOrigin-RevId: 223857830
---
tensorflow/tools/compatibility/BUILD | 10 +--
tensorflow/tools/compatibility/README.md | 63 ++++++++++++-------
...{test_file_v1_10.py => test_file_v1_12.py} | 0
3 files changed, 45 insertions(+), 28 deletions(-)
rename tensorflow/tools/compatibility/testdata/{test_file_v1_10.py => test_file_v1_12.py} (100%)
diff --git a/tensorflow/tools/compatibility/BUILD b/tensorflow/tools/compatibility/BUILD
index 152a79f5429..05d924c092c 100644
--- a/tensorflow/tools/compatibility/BUILD
+++ b/tensorflow/tools/compatibility/BUILD
@@ -126,22 +126,22 @@ py_test(
genrule(
name = "generate_upgraded_file_v2",
testonly = 1,
- srcs = ["testdata/test_file_v1_10.py"],
+ srcs = ["testdata/test_file_v1_12.py"],
outs = [
"test_file_v2_0.py",
"report_v2.txt",
],
cmd = ("$(location :tf_upgrade_v2)" +
- " --infile $(location testdata/test_file_v1_10.py)" +
+ " --infile $(location testdata/test_file_v1_12.py)" +
" --outfile $(location test_file_v2_0.py)" +
" --reportfile $(location report_v2.txt)"),
tools = [":tf_upgrade_v2"],
)
py_test(
- name = "test_file_v1_10",
+ name = "test_file_v1_12",
size = "small",
- srcs = ["testdata/test_file_v1_10.py"],
+ srcs = ["testdata/test_file_v1_12.py"],
srcs_version = "PY2AND3",
deps = [
"//tensorflow:tensorflow_py",
@@ -164,6 +164,6 @@ exports_files(
"tf_upgrade.py",
"renames_v2.py",
"testdata/test_file_v0_11.py",
- "testdata/test_file_v1_10.py",
+ "testdata/test_file_v1_12.py",
],
)
diff --git a/tensorflow/tools/compatibility/README.md b/tensorflow/tools/compatibility/README.md
index aabc7b253d6..6ff42b1fefe 100644
--- a/tensorflow/tools/compatibility/README.md
+++ b/tensorflow/tools/compatibility/README.md
@@ -1,60 +1,77 @@
# TensorFlow Python API Upgrade Utility
This tool allows you to upgrade your existing TensorFlow Python scripts.
-This script can be run on a single Python file:
+Specifically: \
+`tf_upgrade_v2.py`: upgrades code from TensorFlow 1.12 to TensorFlow 2.0 preview. \
+`tf_upgrade.py`: upgrades code to TensorFlow 1.0 from TensorFlow 0.11.
+
+## Running the script from pip package
+
+First, install TensorFlow pip package. See
+https://www.tensorflow.org/install/pip.
+
+Upgrade script can be run on a single Python file:
```
-tf_upgrade.py --infile foo.py --outfile foo-upgraded.py
+tf_upgrade_v2 --infile foo.py --outfile foo-upgraded.py
```
It will print a list of errors it finds that it can't fix. You can also run
it on a directory tree:
```
+# upgrade the .py files and copy all the other files to the outtree
+tf_upgrade_v2 --intree coolcode --outtree coolcode-upgraded
+
# just upgrade the .py files
-tf_upgrade.py --intree coolcode --outtree coolcode-upgraded
-# after upgrade the .py files, then copy all the other files to the outtree
-tf_upgrade.py --intree coolcode --outtree coolcode-upgraded --copyotherfiles True
+tf_upgrade_v2 --intree coolcode --outtree coolcode-upgraded --copyotherfiles False
```
-In either case, it will also dump out a report e.g. which will detail changes
+
+## Report
+
+The script will also dump out a report e.g. which will detail changes
e.g.:
```
-third_party/tensorflow/tools/compatibility/test_file_v0.11.py Line 125
+'tensorflow/tools/compatibility/testdata/test_file_v1_12.py' Line 65
+--------------------------------------------------------------------------------
-Renamed keyword argument from `dim` to `axis`
-Renamed keyword argument from `squeeze_dims` to `axis`
+Added keyword 'input' to reordered function 'tf.argmax'
+Renamed keyword argument from 'dimension' to 'axis'
+
+ Old: tf.argmax([[1, 3, 2]], dimension=0))
+ ~~~~~~~~~~
+ New: tf.argmax(input=[[1, 3, 2]], axis=0))
- Old: [[1, 2, 3]], dim=1), squeeze_dims=[1]).eval(),
- ~~~~ ~~~~~~~~~~~~~
- New: [[1, 2, 3]], axis=1), axis=[1]).eval(),
- ~~~~~ ~~~~~
```
## Caveats
- Don't update parts of your code manually before running this script. In
-particular, functions that have had reordered arguments like `tf.concat`
-or `tf.split` will cause the script to incorrectly add keyword arguments that
-mismap arguments.
+particular, functions that have had reordered arguments like `tf.argmax`
+or `tf.batch_to_space` will cause the script to incorrectly add keyword
+arguments that mismap arguments.
- This script wouldn't actually reorder arguments. Instead, the script will add
keyword arguments to functions that had their arguments reordered.
- This script is not able to upgrade all functions. One notable example is
-`tf.reverse()` which has been changed to take a list of indices rather than
-a tensor of bools. If the script detects this, it will report this to stdout
+`tf.nn.conv2d` that no longer takes `use_cudnn_on_gpu` argument.
+If the script detects this, it will report this to stdout
(and in the report), and you can fix it manually. For example if you have
-`tf.reverse(a, [False, True, True])` you will need to manually change it to
-`tf.reverse(a, [1, 2])`.
+`tf.nn.conv2d(inputs, filters, strides, padding, use_cudnn_on_gpu=True)`
+you will need to manually change it to
+`tf.nn.conv2d(input, filters, strides, padding)`.
- There are some syntaxes that are not handleable with this script as this
-script was designed to use only standard python packages. If the script fails
-with "A necessary keyword argument failed to be inserted." or
+script was designed to use only standard python packages.
+There is an alternative available for TensorFlow 0.* to 1.0 upgrade script.
+If the script fails with "A necessary keyword argument failed to be inserted." or
"Failed to find keyword lexicographically. Fix manually.", you can try
[@machrisaa's fork of this script](https://github.com/machrisaa/tf0to1).
[@machrisaa](https://github.com/machrisaa) has used the
[RedBaron Python refactoring engine](https://redbaron.readthedocs.io/en/latest/)
which is able to localize syntactic elements more reliably than the built-in
-`ast` module this script is based upon.
+`ast` module this script is based upon. Note that the alternative script is not
+available for TensorFlow 2.0 upgrade.
diff --git a/tensorflow/tools/compatibility/testdata/test_file_v1_10.py b/tensorflow/tools/compatibility/testdata/test_file_v1_12.py
similarity index 100%
rename from tensorflow/tools/compatibility/testdata/test_file_v1_10.py
rename to tensorflow/tools/compatibility/testdata/test_file_v1_12.py