From b9d12bde663e5b1e12f58a1709e620a29655a65c Mon Sep 17 00:00:00 2001 From: Leo Chen Date: Fri, 11 Oct 2019 13:47:29 +0800 Subject: [PATCH] [cherry-pick] Polish en APIs of unique_name, test=release/1.6, test=document_fix (#20113) (#20455) --- paddle/fluid/API.spec | 6 +-- python/paddle/fluid/unique_name.py | 69 ++++++++++++++++++------------ 2 files changed, 45 insertions(+), 30 deletions(-) diff --git a/paddle/fluid/API.spec b/paddle/fluid/API.spec index 1ae3cd3213b..1fea11413cc 100644 --- a/paddle/fluid/API.spec +++ b/paddle/fluid/API.spec @@ -1125,9 +1125,9 @@ paddle.fluid.profiler.reset_profiler (ArgSpec(args=[], varargs=None, keywords=No paddle.fluid.profiler.profiler (ArgSpec(args=['state', 'sorted_key', 'profile_path'], varargs=None, keywords=None, defaults=(None, '/tmp/profile')), ('document', '8e8d777eb0127876d7bdb6c421db7f5c')) paddle.fluid.profiler.start_profiler (ArgSpec(args=['state'], varargs=None, keywords=None, defaults=None), ('document', '9494b48e79a0e07b49017ba5a97800b6')) paddle.fluid.profiler.stop_profiler (ArgSpec(args=['sorted_key', 'profile_path'], varargs=None, keywords=None, defaults=(None, '/tmp/profile')), ('document', '10406b144bd8b5e01ea44301219f7fef')) -paddle.fluid.unique_name.generate (ArgSpec(args=['key'], varargs=None, keywords=None, defaults=None), ('document', '4d68cde4c4df8f1b8018620b4dc19b42')) -paddle.fluid.unique_name.switch (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', '695a6e91afbcdbafac69a069038811be')) -paddle.fluid.unique_name.guard (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', 'ead717d6d440a1eb11971695cd1727f4')) +paddle.fluid.unique_name.generate (ArgSpec(args=['key'], varargs=None, keywords=None, defaults=None), ('document', '16bbac2df5f02c65cf5100741cd2aeb2')) +paddle.fluid.unique_name.switch (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', 'd7a9f8dd00c6337ea298623cb9d63c39')) +paddle.fluid.unique_name.guard (ArgSpec(args=['new_generator'], varargs=None, keywords=None, defaults=(None,)), ('document', 'b11ef0165c3f73d8dc73ec60dc988792')) paddle.fluid.Scope Scope() -> paddle.fluid.core_avx._Scope paddle.fluid.install_check.run_check (ArgSpec(args=[], varargs=None, keywords=None, defaults=None), ('document', '66b7c84a17ed32fec2df9628367be2b9')) paddle.fluid.save (ArgSpec(args=['program', 'model_path'], varargs=None, keywords=None, defaults=None), ('document', 'cef7d50c36b93c02b6d12bcea7d025ce')) diff --git a/python/paddle/fluid/unique_name.py b/python/paddle/fluid/unique_name.py index 9e3cd063092..550364a22fe 100644 --- a/python/paddle/fluid/unique_name.py +++ b/python/paddle/fluid/unique_name.py @@ -56,23 +56,24 @@ generator = UniqueNameGenerator() def generate(key): """ - Generate unique name with prefix key. + Generate unique name with prefix key. Currently, Paddle distinguishes the + names of the same key by numbering it from zero. For example, when key=fc, + it continuously generates fc_0, fc_1, fc_2, etc. - Args: - key(str): The generated name prefix. All generated name will be - started with this prefix. + Args: + key(str): The prefix of generated name. Returns: str: A unique string with the prefix key. - Examples: + Examples: + .. code-block:: python import paddle.fluid as fluid name1 = fluid.unique_name.generate('fc') name2 = fluid.unique_name.generate('fc') - # The result is fc_0, fc_1 - print name1, name2 + print(name1, name2) # fc_0, fc_1 """ return generator(key) @@ -102,27 +103,36 @@ def generate_with_ignorable_key(key): def switch(new_generator=None): """ - Switch the Global namespace to a new namespace. + Switch the namespace of in current context to a new namespace. Though + :code:`switch()` and :code:`guard()` can both change namespace, + :code:`guard()` is recommended since it can manage the context better + together with :code:`with` statement. - Args: - new_generator(None|UniqueNameGenerator): A new UniqueNameGenerator. + Args: + new_generator(UniqueNameGenerator, optional): A new UniqueNameGenerator, not + required normally. Default is None, which means switch to a new anonymous + namespace. Returns: UniqueNameGenerator: The previous UniqueNameGenerator. - Examples: + Examples: + .. code-block:: python import paddle.fluid as fluid name1 = fluid.unique_name.generate('fc') name2 = fluid.unique_name.generate('fc') - # The result is fc_0, fc_1 - print name1, name2 + print(name1, name2) # fc_0, fc_1 - fluid.unique_name.switch() + pre_generator = fluid.unique_name.switch() # switch to a new anonymous namespace. name2 = fluid.unique_name.generate('fc') - # The result is fc_0 - print name2 + print(name2) # fc_0 + + fluid.unique_name.switch(pre_generator) # switch back to pre_generator. + name3 = fluid.unique_name.generate('fc') + print(name3) # fc_2, since pre_generator has generated fc_0, fc_1. + """ global generator old = generator @@ -136,14 +146,21 @@ def switch(new_generator=None): @signature_safe_contextmanager def guard(new_generator=None): """ - Change the global namespace with `with` statement. + Change the namespace of unique name with :code:`with` statement. After calling it, + a new namespace in the context of :code:`with` will be created, and it will number + names from zero again when calling :code:`generate()` with same key. + + Args: + new_generator(str|bytes, optional): New name of global namespace. Note that str + in Python2 was spilted into str and bytes in Python3, so here are two + types. Default is None. If not None, new_generator will be added into + the prefix of unique name generated by :code:`generate()`. - Args: - new_generator(None|str|bytes): New name of global namespace. - Note that str in Python2 was spilted into str and bytes in Python3, - so here are two types. Default is None. + Returns: + None. + + Examples: - Examples: .. code-block:: python import paddle.fluid as fluid @@ -151,15 +168,13 @@ def guard(new_generator=None): name_1 = fluid.unique_name.generate('fc') with fluid.unique_name.guard(): name_2 = fluid.unique_name.generate('fc') - # The result is fc_0, fc_0 - print name_1, name_2 + print(name_1, name_2) # fc_0, fc_0 with fluid.unique_name.guard('A'): name_1 = fluid.unique_name.generate('fc') with fluid.unique_name.guard('B'): - name_2 = fluid.unique_name.generate('fc') - # The result is Afc_0, Bfc_0 - print name_1, name_2 + name_2 = fluid.unique_name.generate('fc') + print(name_1, name_2) # Afc_0, Bfc_0 """ if isinstance(new_generator, six.string_types): new_generator = UniqueNameGenerator(new_generator) -- GitLab