Home | History | Annotate | Download | only in compatibility 
      1 # TensorFlow Python API Upgrade Utility
      2 
      3 This tool allows you to upgrade your existing TensorFlow Python scripts,
      4 specifically:
      5 * `tf_upgrade_v2.py`: Upgrade code from TensorFlow 1.x to TensorFlow 2.0 preview.
      6 * `tf_upgrade.py`: Upgrade code to TensorFlow 1.0 from TensorFlow 0.11.
      7 
      8 ## Running the script from pip package
      9 
     10 First, install TensorFlow pip package*. See
     11 https://www.tensorflow.org/install/pip.
     12 
     13 Upgrade script can be run on a single Python file:
     14 
     15 ```
     16 tf_upgrade_v2 --infile foo.py --outfile foo-upgraded.py
     17 ```
     18 
     19 It will print a list of errors it finds that it can't fix. You can also run
     20 it on a directory tree:
     21 
     22 ```
     23 # upgrade the .py files and copy all the other files to the outtree
     24 tf_upgrade_v2 --intree coolcode --outtree coolcode-upgraded
     25 
     26 # just upgrade the .py files
     27 tf_upgrade_v2 --intree coolcode --outtree coolcode-upgraded --copyotherfiles False
     28 ```
     29 
     30 *Note: `tf_upgrade_v2` is installed automatically as a script by the pip install 
     31 after TensorFlow 1.12.
     32 
     33 ## Report
     34 
     35 The script will also dump out a report e.g. which will detail changes
     36 e.g.:
     37 
     38 ```
     39 'tensorflow/tools/compatibility/testdata/test_file_v1_12.py' Line 65
     40 --------------------------------------------------------------------------------
     41 
     42 Added keyword 'input' to reordered function 'tf.argmax'
     43 Renamed keyword argument from 'dimension' to 'axis'
     44 
     45     Old:         tf.argmax([[1, 3, 2]], dimension=0))
     46                                         ~~~~~~~~~~
     47     New:         tf.argmax(input=[[1, 3, 2]], axis=0))
     48 
     49 ```
     50 
     51 ## Caveats
     52 
     53 - Don't update parts of your code manually before running this script. In
     54 particular, functions that have had reordered arguments like `tf.argmax`
     55 or `tf.batch_to_space` will cause the script to incorrectly add keyword
     56 arguments that mismap arguments.
     57 
     58 - This script wouldn't actually reorder arguments. Instead, the script will add
     59 keyword arguments to functions that had their arguments reordered.
     60 
     61 - The script assumes that `tensorflow` is imported using `import tensorflow as tf`.
     62 
     63 - Note for upgrading to 2.0: Check out [tf2up.ml](http://tf2up.ml) for a convenient tool to upgrade Jupiter
     64   notebooks and Python files in a github repository.
     65 
     66 - Note for upgrading to 1.0: There are some syntaxes that are not handleable with this script as this
     67 script was designed to use only standard python packages.
     68 If the script fails with "A necessary keyword argument failed to be inserted." or
     69 "Failed to find keyword lexicographically. Fix manually.", you can try
     70 [@machrisaa's fork of this script](https://github.com/machrisaa/tf0to1).
     71 [@machrisaa](https://github.com/machrisaa) has used the
     72 [RedBaron Python refactoring engine](https://redbaron.readthedocs.io/en/latest/)
     73 which is able to localize syntactic elements more reliably than the built-in
     74 `ast` module this script is based upon. Note that the alternative script is not
     75 available for TensorFlow 2.0 upgrade.
     76