tf.app.flags

tf.app.flags

解析命令行参数。

1. /usr/local/lib/python2.7/dist-packages/tensorflow/python/platform/flags.py

"""Implementation of the flags interface."""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

import argparse as _argparse

from tensorflow.python.platform import tf_logging as _logging
from tensorflow.python.util.all_util import remove_undocumented

_global_parser = _argparse.ArgumentParser()

......

文件中 import argparse，使用 argparse 需要创建一个解析器对象，告诉它将会有些什么参数。当程序运行时，解析器可以用于处理命令行参数。argparse 中的解析器类是 ArgumentParser。

_global_parser = _argparse.ArgumentParser()


# pylint: disable=invalid-name


class _FlagValues(object):
  """Global container and accessor for flags and their values."""

  def __init__(self):
    self.__dict__['__flags'] = {}
    self.__dict__['__parsed'] = False
    self.__dict__['__required_flags'] = set()

  def _parse_flags(self, args=None):
    result, unparsed = _global_parser.parse_known_args(args=args)
    for flag_name, val in vars(result).items():
      self.__dict__['__flags'][flag_name] = val
    self.__dict__['__parsed'] = True
    self._assert_all_required()
    return unparsed

  def __getattr__(self, name):
    """Retrieves the 'value' attribute of the flag --name."""
    try:
      parsed = self.__dict__['__parsed']
    except KeyError:
      # May happen during pickle.load or copy.copy
      raise AttributeError(name)
    if not parsed:
      self._parse_flags()
    if name not in self.__dict__['__flags']:
      raise AttributeError(name)
    return self.__dict__['__flags'][name]

  def __setattr__(self, name, value):
    """Sets the 'value' attribute of the flag --name."""
    if not self.__dict__['__parsed']:
      self._parse_flags()
    self.__dict__['__flags'][name] = value
    self._assert_required(name)

  def _add_required_flag(self, item):
    self.__dict__['__required_flags'].add(item)

  def _assert_required(self, flag_name):
    if (flag_name not in self.__dict__['__flags'] or
        self.__dict__['__flags'][flag_name] is None):
      raise AttributeError('Flag --%s must be specified.' % flag_name)

  def _assert_all_required(self):
    for flag_name in self.__dict__['__required_flags']:
      self._assert_required(flag_name)


def _define_helper(flag_name, default_value, docstring, flagtype):
  """Registers 'flag_name' with 'default_value' and 'docstring'."""
  _global_parser.add_argument('--' + flag_name,
                              default=default_value,
                              help=docstring,
                              type=flagtype)


# Provides the global object that can be used to access flags.
FLAGS = _FlagValues()

定义全局对象解析器类 _global_parser，定义 class _FlagValues(object) 类解析命令行，result, unparsed = _global_parser.parse_known_args(args=args) 返回一个有用的 result 和一个无用的 unparsed。parse_known_args 函数在接受到多余的命令行参数时不会报错，会原封不动的以一个 list 形式将其返回。函数返回的 result 是参数解析完的数据，而 unparsed 是那些未被解析的参数 list。

将命令行传入的命令和数据解析出来以字典的形式放到 self.__dict__['__flags'] 字典中，这样当要访问命令行输入的命令时，就能使用 tf.app.flag.Flags 这样的命令了。在 tensorflow 中是通过 tf.app.flag.Flags 来实现实例化这个类，然后再调用里面解析得到的参数即可。

setattr / getattr 方法是一些设置和获得解析的命令行参数的方法。在获得参数的时候 (getattr)，首先要通过解析字典中的 parsed = self.__dict__['__parsed'] 来检验参数是否已经被解析过，因为在 _parse_flags 方法中，只要解析过参数 (也即是运行过该函数)，那么 self.__dict__['__parsed'] 就会为 True (表明解析过参数)。因为这里是获取参数，所以除了要判断参数是否在字典里的基本要求外，还要判断有没有解析过参数，没有就运行 self._parse_flags() 解析参数。

类外定义的方法，要调用就只能通过 tf.app.flags.XXX 来实现了。

def _define_helper(flag_name, default_value, docstring, flagtype):
  """Registers 'flag_name' with 'default_value' and 'docstring'."""
  _global_parser.add_argument('--' + flag_name,
                              default=default_value,
                              help=docstring,
                              type=flagtype)

_define_helper 函数中调用了 _global_parser.add_argument 完成对命令行 optional argument 的添加，_global_parser 就是前面参数解析器的一个实例。真正完成对命令行参数添加是在 _define_helper 中的 _global_parser.add_argument 函数。第一个参数时 '--' + flag_name 表示我们定义的命令行参数使用时必须以 -- 开头。第二个参数是命令行的默认值，没有赋给命令行参数值时使用默认值。第三个参数 help 保存帮助信息，第四个参数表示限定了赋予命令行参数数据的类型。
_define_helper() 最后一个 type 参数是 str。

# Provides the global object that can be used to access flags.
FLAGS = _FlagValues()

定义了 _FlagValues 这个类的一个实例，这样的这样当要访问命令行输入的命令时，就能使用像 tf.app.flag.Flags 这样的操作。

def mark_flag_as_required(flag_name):
  """Ensures that flag is not None during program execution.
  
  It is recommended to call this method like this:
  
    if __name__ == '__main__':
      tf.flags.mark_flag_as_required('your_flag_name')
      tf.app.run()
  
  Args:
    flag_name: string, name of the flag to mark as required.
 
  Raises:
    AttributeError: if flag_name is not registered as a valid flag name.
      NOTE: The exception raised will change in the future. 
  """
  if _global_parser.get_default(flag_name) is not None:
    _logging.warn(
        'Flag %s has a non-None default value; therefore, '
        'mark_flag_as_required will pass even if flag is not specified in the '
        'command line!' % flag_name)
  FLAGS._add_required_flag(flag_name)


def mark_flags_as_required(flag_names):
  """Ensures that flags are not None during program execution.
  
  Recommended usage:
  
    if __name__ == '__main__':
      tf.flags.mark_flags_as_required(['flag1', 'flag2', 'flag3'])
      tf.app.run()
  
  Args:
    flag_names: a list/tuple of flag names to mark as required.

  Raises:
    AttributeError: If any of flag name has not already been defined as a flag.
      NOTE: The exception raised will change in the future.
  """
  for flag_name in flag_names:
    mark_flag_as_required(flag_name)

在程序运行前先将某些命令行参数加入到 必备参数 __required_flags 的字典中，以判断解析完的参数是否满足这些必备要求。因为 mark_flags_as_required(flag_names) 方法会调用 mark_flag_as_required(flag_name) 方法，将当前传入的参数加入到 __required_flags 字典中 (FLAGS._add_required_flag(flag_name) 方法)，在最上面解析参数的方法 _parse_flags 中，解析完参数会通过 _assert_all_required 方法判断解析到的参数是否都在 _required_flags 字典中。

_allowed_symbols = [
    # We rely on gflags documentation.
    'DEFINE_bool',
    'DEFINE_boolean',
    'DEFINE_float',
    'DEFINE_integer',
    'DEFINE_string',
    'FLAGS',
    'mark_flag_as_required',
    'mark_flags_as_required',
]

第一个是参数名称，第二个是参数默认值，第三个是参数描述，如果不想描述可以直接用 ""。

def DEFINE_string(flag_name, default_value, docstring):
  """Defines a flag of type 'string'.

  Args:
    flag_name: The name of the flag as a string.
    default_value: The default value the flag should take as a string.
    docstring: A helpful message explaining the use of the flag.
  """
  _define_helper(flag_name, default_value, docstring, str)


def DEFINE_integer(flag_name, default_value, docstring):
  """Defines a flag of type 'int'.

  Args:
    flag_name: The name of the flag as a string.
    default_value: The default value the flag should take as an int.
    docstring: A helpful message explaining the use of the flag.
  """
  _define_helper(flag_name, default_value, docstring, int)

def DEFINE_float(flag_name, default_value, docstring):
  """Defines a flag of type 'float'.

  Args:
    flag_name: The name of the flag as a string.
    default_value: The default value the flag should take as a float.
    docstring: A helpful message explaining the use of the flag.
  """
  _define_helper(flag_name, default_value, docstring, float)

通过 tf.app.flags 来调用这个 flags.py 文件，用 flags.DEFINE_string/interger/float() 来添加命令行参数，而 FLAGS=flags.FLAGS 可以实例化这个解析参数的类，进而从对应的命令行参数取出参数。

2. 使用示例

2.0 example 0

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# yongqiang cheng

import tensorflow as tf

flags = tf.app.flags
FLAGS = flags.FLAGS  # FLAGS = tf.app.flags.FLAGS - instantiation

# training parameters.
flags.DEFINE_float('base_learning_rate', .0001, 'The base learning rate for model training.')
flags.DEFINE_integer('learning_rate_decay_step', 2000, 'Decay the base learning rate at a fixed step.')
flags.DEFINE_integer('train_batch_size', 12, 'The number of images in each batch during training.')
flags.DEFINE_boolean('upsample_logits', True, 'Upsample logits during training.')
flags.DEFINE_string('dataset', 'dataset_name', 'Name of the test dataset.')

print(FLAGS.base_learning_rate)
print(FLAGS.learning_rate_decay_step)
print(FLAGS.train_batch_size)
print(FLAGS.upsample_logits)
print(FLAGS.dataset)

/home/yongqiang/miniconda3/envs/tf_cpu_1.4.1/bin/python /home/yongqiang/pycharm_work/yongqiang.py
0.0001
2000
12
True
dataset_name

Process finished with exit code 0

2.1 example 1

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# yongqiang cheng

import tensorflow as tf

flags = tf.app.flags
FLAGS = flags.FLAGS

# training parameters.
flags.DEFINE_float('base_learning_rate', .0001, 'The base learning rate for model training.')
flags.DEFINE_integer('learning_rate_decay_step', 2000, 'Decay the base learning rate at a fixed step.')
flags.DEFINE_integer('train_batch_size', 12, 'The number of images in each batch during training.')
flags.DEFINE_boolean('upsample_logits', True, 'Upsample logits during training.')
flags.DEFINE_string('dataset', 'dataset_name', 'Name of the test dataset.')


def main(_):
    print(FLAGS.base_learning_rate)
    print(FLAGS.learning_rate_decay_step)
    print(FLAGS.train_batch_size)
    print(FLAGS.upsample_logits)
    print(FLAGS.dataset)


if __name__ == '__main__':
    tf.app.run()

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py 
0.0001
2000
12
True
dataset_name
strong@foreverstrong:~/git_workspace/MonoGRNet$

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py -h
usage: test.py [-h] [--base_learning_rate BASE_LEARNING_RATE]
               [--learning_rate_decay_step LEARNING_RATE_DECAY_STEP]
               [--train_batch_size TRAIN_BATCH_SIZE]
               [--upsample_logits [UPSAMPLE_LOGITS]] [--noupsample_logits]
               [--dataset DATASET]

optional arguments:
  -h, --help            show this help message and exit
  --base_learning_rate BASE_LEARNING_RATE
                        The base learning rate for model training.
  --learning_rate_decay_step LEARNING_RATE_DECAY_STEP
                        Decay the base learning rate at a fixed step.
  --train_batch_size TRAIN_BATCH_SIZE
                        The number of images in each batch during training.
  --upsample_logits [UPSAMPLE_LOGITS]
                        Upsample logits during training.
  --noupsample_logits
  --dataset DATASET     Name of the test dataset.
strong@foreverstrong:~/git_workspace/MonoGRNet$

FLAGS = flags.FLAGS 可以实例化解析参数的类，进而从对应的命令行参数取出参数。

2.2 example 2

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import tensorflow as tf

tf.app.flags.DEFINE_string('str_name', 'yongqiang', "description1")
tf.app.flags.DEFINE_integer('int_name', 10, "description2")
tf.app.flags.DEFINE_boolean('bool_name', False, "description3")

FLAGS = tf.app.flags.FLAGS


def main(_):
    print(FLAGS.str_name)
    print(FLAGS.int_name)
    print(FLAGS.bool_name)


if __name__ == '__main__':
    tf.app.run()

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py 
yongqiang
10
False
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --str_name foreverstrong --int_name 19 --bool_name True
foreverstrong
19
True
strong@foreverstrong:~/git_workspace/MonoGRNet$

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py -h
usage: test.py [-h] [--str_name STR_NAME] [--int_name INT_NAME]
               [--bool_name [BOOL_NAME]] [--nobool_name]

optional arguments:
  -h, --help            show this help message and exit
  --str_name STR_NAME   description1
  --int_name INT_NAME   description2
  --bool_name [BOOL_NAME]
                        description3
  --nobool_name
strong@foreverstrong:~/git_workspace/MonoGRNet$

tf.app.flags.DEFINE_xxx() 添加命令行的 optional argument (可选参数)，而 tf.app.flags.FLAGS 可以从对应的命令行参数取出参数。

在命令行运行程序时，不带参数运行，程序使用默认值。使用命令行赋初值时，就会调用使用命令行设置的值。

命令行输入 flag_name + parameter，例如 --learning_rate 0.01。两个短横杠 + 参数名字 + 空格 + 赋给参数的值，多个参数时，用空格隔开。

如果需要修改默认参数的值，则在命令行传入自定义参数值即可，若全部使用默认参数值，则可直接在命令行运行 Python 文件。

在命令行中输入 python test.py -h 可以查看帮助信息。

2.3 example 3

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import tensorflow as tf

flags = tf.app.flags
FLAGS = flags.FLAGS

tf.app.flags.DEFINE_integer('train_batch_size', 12, 'The number of images in each batch during training.')
tf.app.flags.DEFINE_boolean("is_train", True, "")


def main():
    print("{}".format(FLAGS.train_batch_size))
    print("{}".format(FLAGS.is_train))


if __name__ == '__main__':
    tf.app.run()

main() 函数是需要传参数，否则会出现如下报错信息。
注意 def main(): 括号中没有下划线。

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py -h
usage: test.py [-h] [--train_batch_size TRAIN_BATCH_SIZE]
               [--is_train [IS_TRAIN]] [--nois_train]

optional arguments:
  -h, --help            show this help message and exit
  --train_batch_size TRAIN_BATCH_SIZE
                        The number of images in each batch during training.
  --is_train [IS_TRAIN]
  --nois_train
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py
Traceback (most recent call last):
  File "test.py", line 19, in <module>
    tf.app.run()
  File "/usr/local/lib/python2.7/dist-packages/tensorflow/python/platform/app.py", line 48, in run
    _sys.exit(main(_sys.argv[:1] + flags_passthrough))
TypeError: main() takes no arguments (1 given)
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64
Traceback (most recent call last):
  File "test.py", line 19, in <module>
    tf.app.run()
  File "/usr/local/lib/python2.7/dist-packages/tensorflow/python/platform/app.py", line 48, in run
    _sys.exit(main(_sys.argv[:1] + flags_passthrough))
TypeError: main() takes no arguments (1 given)
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64 --is_train False
Traceback (most recent call last):
  File "test.py", line 19, in <module>
    tf.app.run()
  File "/usr/local/lib/python2.7/dist-packages/tensorflow/python/platform/app.py", line 48, in run
    _sys.exit(main(_sys.argv[:1] + flags_passthrough))
TypeError: main() takes no arguments (1 given)
strong@foreverstrong:~/git_workspace/MonoGRNet$

def main(): 括号中添加下划线 def main(_):。

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import tensorflow as tf

flags = tf.app.flags
FLAGS = flags.FLAGS

tf.app.flags.DEFINE_integer('train_batch_size', 12, 'The number of images in each batch during training.')
tf.app.flags.DEFINE_boolean("is_train", True, "")


def main(_):
    print("{}".format(FLAGS.train_batch_size))
    print("{}".format(FLAGS.is_train))


if __name__ == '__main__':
    tf.app.run()

如果不传入参数则按默认值处理，否则根据传入的值对变量进行更新。

bool 型变量需要注意，bool 只有 True 和 False，所以无论 bool 变量默认值为 True 还是 False，在变量面前加个 no 后都取 False，其他类型的没有这个特权。将 is_train 默认值设为 False，--nois_train 运行结果仍为 False。

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py -h
usage: test.py [-h] [--train_batch_size TRAIN_BATCH_SIZE]
               [--is_train [IS_TRAIN]] [--nois_train]

optional arguments:
  -h, --help            show this help message and exit
  --train_batch_size TRAIN_BATCH_SIZE
                        The number of images in each batch during training.
  --is_train [IS_TRAIN]
  --nois_train
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py
12
True
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64
64
True
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64 --is_train False
64
False
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --notrain_batch_size --nois_train
12
False
strong@foreverstrong:~/git_workspace/MonoGRNet$

2.4 example 4

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import tensorflow as tf

flags = tf.app.flags
FLAGS = flags.FLAGS

tf.app.flags.DEFINE_integer('train_batch_size', 12, 'The number of images in each batch during training.')
tf.app.flags.DEFINE_boolean("is_train", True, "")


def main(unused_argv):
    print("{}".format(FLAGS.train_batch_size))
    print("{}".format(FLAGS.is_train))
    print(unused_argv)


if __name__ == '__main__':
    tf.app.run()

main(unused_argv) 函数必须有参数，为无法解析出的 sys.argv。

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py -h
usage: test.py [-h] [--train_batch_size TRAIN_BATCH_SIZE]
               [--is_train [IS_TRAIN]] [--nois_train]

optional arguments:
  -h, --help            show this help message and exit
  --train_batch_size TRAIN_BATCH_SIZE
                        The number of images in each batch during training.
  --is_train [IS_TRAIN]
  --nois_train
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py
12
True
['test.py']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64
64
True
['test.py']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --notrain_batch_size --nois_train
12
False
['test.py', '--notrain_batch_size']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64 --is_train False
64
False
['test.py']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64 --is_train False --gpus 0
64
False
['test.py', '--gpus', '0']
strong@foreverstrong:~/git_workspace/MonoGRNet$

2.5 example 5

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import tensorflow as tf

flags = tf.app.flags
FLAGS = flags.FLAGS

tf.app.flags.DEFINE_integer('train_batch_size', 12, 'The number of images in each batch during training.')
tf.app.flags.DEFINE_boolean("is_train", True, "")


def main(_):
    print("{}".format(FLAGS.train_batch_size))
    print("{}".format(FLAGS.is_train))
    print(_)


if __name__ == '__main__':
    tf.app.run()

tf.app.run() 会自动调用 main(_) 函数，将文件名和未解析出的内容传到 main 函数的参数中。--gpus 0 未解析出，则放入 main 参数 _ 中。

strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py -h
usage: test.py [-h] [--train_batch_size TRAIN_BATCH_SIZE]
               [--is_train [IS_TRAIN]] [--nois_train]

optional arguments:
  -h, --help            show this help message and exit
  --train_batch_size TRAIN_BATCH_SIZE
                        The number of images in each batch during training.
  --is_train [IS_TRAIN]
  --nois_train
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py
12
True
['test.py']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64
64
True
['test.py']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64 --is_train False
64
False
['test.py']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --train_batch_size 64 --is_train False --gpus 0
64
False
['test.py', '--gpus', '0']
strong@foreverstrong:~/git_workspace/MonoGRNet$ 
strong@foreverstrong:~/git_workspace/MonoGRNet$ python test.py --notrain_batch_size --nois_train
12
False
['test.py', '--notrain_batch_size']
strong@foreverstrong:~/git_workspace/MonoGRNet$