README.md
1 # TensorFlow Python API Upgrade Utility
2
3 This tool allows you to upgrade your existing TensorFlow Python scripts.
4 This script can be run on a single Python file:
5
6 ```
7 tf_upgrade.py --infile foo.py --outfile foo-upgraded.py
8 ```
9
10 It will print a list of errors it finds that it can't fix. You can also run
11 it on a directory tree:
12
13 ```
14 # just upgrade the .py files
15 tf_upgrade.py --intree coolcode --outtree coolcode-upgraded
16 # after upgrade the .py files, then copy all the other files to the outtree
17 tf_upgrade.py --intree coolcode --outtree coolcode-upgraded --copyotherfiles True
18 ```
19
20 In either case, it will also dump out a report e.g. which will detail changes
21 e.g.:
22
23 ```
24 third_party/tensorflow/tools/compatibility/test_file_v0.11.py Line 125
25
26 Renamed keyword argument from `dim` to `axis`
27 Renamed keyword argument from `squeeze_dims` to `axis`
28
29 Old: [[1, 2, 3]], dim=1), squeeze_dims=[1]).eval(),
30 ~~~~ ~~~~~~~~~~~~~
31 New: [[1, 2, 3]], axis=1), axis=[1]).eval(),
32 ~~~~~ ~~~~~
33 ```
34
35 ## Caveats
36
37 - Don't update parts of your code manually before running this script. In
38 particular, functions that have had reordered arguments like `tf.concat`
39 or `tf.split` will cause the script to incorrectly add keyword arguments that
40 mismap arguments.
41
42 - This script wouldn't actually reorder arguments. Instead, the script will add
43 keyword arguments to functions that had their arguments reordered.
44
45 - This script is not able to upgrade all functions. One notable example is
46 `tf.reverse()` which has been changed to take a list of indices rather than
47 a tensor of bools. If the script detects this, it will report this to stdout
48 (and in the report), and you can fix it manually. For example if you have
49 `tf.reverse(a, [False, True, True])` you will need to manually change it to
50 `tf.reverse(a, [1, 2])`.
51
52 - There are some syntaxes that are not handleable with this script as this
53 script was designed to use only standard python packages. If the script fails
54 with "A necessary keyword argument failed to be inserted." or
55 "Failed to find keyword lexicographically. Fix manually.", you can try
56 [@machrisaa's fork of this script](https://github.com/machrisaa/tf0to1).
57 [@machrisaa](https://github.com/machrisaa) has used the
58 [RedBaron Python refactoring engine](https://redbaron.readthedocs.io/en/latest/)
59 which is able to localize syntactic elements more reliably than the built-in
60 `ast` module this script is based upon.
61