Refine options

Author: jondy

pyarmor/docs/en/user/configuration.rst

@@ -1,6 +1,6 @@
-=======================
- Configuration Options
-=======================
+===============
+ Configuration
+===============
 
 .. contents:: Content
    :depth: 2
@@ -11,6 +11,8 @@
 
 Bool value is 0, 1
 
+Project configuration is stored in the :file:`.pyarmor/config`
+
 Project Domain
 ==============
 
@@ -85,8 +87,27 @@ Set option value. For example::
          joker:data
          :find.py
    * - recursive
-     - Bool
-     - Recursively search modules and packages in project src
+     - Enum
+     - How to search items in project src
+       - 0: no search
+       - 1: only search modules
+       - 2: search modules and packages
+       - 3: recursively search all modules and packages
+   * - pypaths
+     - List
+     - Extra Python paths to import module on demand::
+
+         path
+         path,path
+         modname::path,path
+
+       Used by wildcard import or outer base classes. For examle::
+
+         import a
+         from b import *
+
+         class C(a.T):
+             pass
 
 Section: rft
 ------------
@@ -132,7 +153,7 @@ Set option value. For example::
        - 1: only rename position-only arguments
        - 2: rename all the arguments except keyword-only arguments
        - 3: rename all the arguments
-   * - auto_export_mode
+   * - export_mode
      - Bool
      - 0
      - Export all the names list in the module attribute `__all__`
@@ -147,6 +168,8 @@ Set option value. For example::
 
           "inc"
           "dir*"
+          "modname::generic_visit"
+          "modname::Cls.visit_*"
 
        Note that arguments and local variables are always renamed
    * - exclude_funcs
@@ -163,6 +186,27 @@ Set option value. For example::
      - List
      -
      - Define how to rename unknown attributes
+
+       One rule one line. For example::
+
+         modname::scope:a.b.c
+         !modname::scope:a.b.c
+         modname::scope:a.b.c *.?.?
+
+      The first line will rename all attributes `b.c`, on the contrary the second form won't
+
+      The third form only renames attribute by action `?`
+   * - call_rules
+     - List
+     -
+     - Define keywords in which function call should be renamed::
+
+         foo
+         visit*
+         modname::foo
+         modname:::foo*
+         modname::Cls.meth:foo
+
    * - extra_builtins
      - List
      -
@@ -171,3 +215,7 @@ Set option value. For example::
      - List
      -
      - Classes aren't defined in the project
+   * - external_attrs
+     - List
+     -
+     - Outer attributes should not be renamed

pyarmor/docs/en/user/man.rst

@@ -20,7 +20,7 @@ In current path create project, update project and show project information
 
    [#]_ pyarmor init -h
 
-   [#]_ pyarmor init [-C] [-s PATH] [-x PATTERN]
+   [#]_ pyarmor init [-C] [-s PATH] [-x PATTERN] [-r {0,1,2,3}]
 
    [#]_ pyarmor init [-e FILE] [-m FILE] [-p PATH]
 
@@ -37,11 +37,7 @@ In current path create project, update project and show project information
 
 .. option:: -s PATH, --src PATH
 
-   Project path, absolute path
-
-   If no :option:`-e`, :option:`-m`, :option:`-p`, all the modules and packages in this path will be added into this project
-
-   Otherwise, project only includes listed scripts, modules and packages
+   Specify project src, absolute path or relative path
 
 .. option:: -x PATTERN, --exclude PATTERN
 
@@ -95,6 +91,15 @@ In current path create project, update project and show project information
 
       $ pyarmor init -p lib/src@joker
 
+.. option:: -r, --recursive {0,1,2,3}
+
+   How to search items in project src
+
+   - 0: no search
+   - 1: only search modules
+   - 2: search modules and packages
+   - 3: recursively search all modules and packages
+
 .. option:: -C, --clean
 
    Remove all old project information before create new project
@@ -103,17 +108,11 @@ In current path create project, update project and show project information
 
    Create one project, add all scripts and packages in the current path to this project::
 
-      $ pyarmor init
-
-   This command is same as::
-
-    $ pyarmor init --src . -m "*.py" -p "*"
-
-   Quote wildcards in command line, otherwise may complain of syntax errors
+      $ pyarmor init -r 2
 
    If need exclude some files or paths::
 
-      $ pyarmor init --exclude venv --exclude "test*.py"
+      $ pyarmor init -r 2 --exclude venv --exclude "test*.py"
 
    If there has project in current path, this command could show project information::
 
@@ -137,19 +136,19 @@ All of these examples assume there is still no project in work path
 
 1. Create one project which include all the scripts and packages in current path::
 
-    $ pyarmor init
+    $ pyarmor init -r 3
 
 2. Same as above, but not include path `venv` and all scripts which start with `test`::
 
-    $ pyarmor init --exclude venv --exclude "test*.py"
+    $ pyarmor init -r 3 --exclude venv --exclude "test*.py"
 
 3. Update project src, :option:`-C` is required to clean old project::
 
-    $ pyarmor init -C --src another/src
+    $ pyarmor init -C --src another/src -r 3
 
 4. Create one project which src is not current path::
 
-    $ pyarmor init -s eke/src
+    $ pyarmor init -s eke/src -r 2
 
 5. Create one project with only one script::
 
@@ -421,7 +420,7 @@ Generate obfuscated scripts for project
 
    [#]_ pyarmor build [--mini | --rft | --mini-rft]
 
-   [#]_ pyarmor build [--autofix {0,1}]
+   [#]_ pyarmor build [--autofix {0,1,2,3}]
 
    [#]_ pyarmor build [--randname {0,1}]
 
@@ -450,19 +449,14 @@ Generate obfuscated scripts for project
 
      $ pyarmor build --mini-rft
 
-.. option:: --autofix {0,1}
+.. option:: --autofix {0,1,2,3}
 
    This option can simplifying the configuration for refactoring scripts.
 
    First enable auto-fix mode by this way::
 
      $ pyarmor build --autofix 1
 
-   When auto-fix mode is enabled
-
-   - Always `argument_mode = 1`
-   - Search all unknown attributes and add them to exclude table
-
    Then build the project::
 
      $ pyarmor build --rft

pyarmor/docs/en/user/tutorials.rst

@@ -155,9 +155,9 @@ First create one project with package `tomjson`::
 
 Because the package will be imported by outer scripts, the exported classes and functions can't be renamed
 
-In order to keep these names, one way is to enable option `auto_export_mode`::
+In order to keep these names, one way is to enable option `export_mode`::
 
-  $ pyarmor env -p set rft:auto_export_mode 1
+  $ pyarmor env -p set rft:export_mode 1
 
 Thus all the names list in the module attribute ``__all__`` aren't changed, and
 
@@ -175,9 +175,9 @@ Create Complex Project
 
 Let's create one comple project, include one script `jsontool.py` and package `tomjson`, but no `fibo.py` and path `venv`::
 
-  $ pyarmor init --clean --src . --exclude fibo.py --exclude venv
+  $ pyarmor init --clean --src . -r 2 --exclude fibo.py --exclude venv
 
-Because there is no :option:`--entry`, :option:`--module` and :option:`--package`, so pyarmor will search all the files and paths in the :option:`--src`, all of them except in the excludes will be added into the project.
+Pyarmor will search all the files and paths in the :option:`--src`, all of them except in the excludes will be added into the project.
 
 Check the project items::
 

pyarmor/docs/zh/user/configuration.rst

@@ -9,6 +9,8 @@
 
 .. highlight:: console
 
+配置选项存放在文件 `.pyarmor/config` 中
+
 布尔类型的值为 0, 1
 
 工程域
@@ -40,6 +42,8 @@
      - 文件列表
      - 工程的脚本，可以为空，也可以是一个或者多个文件
 
+       脚本一般是不会被工程中其他脚本和模块导入，是直接被执行的文件
+
        文件是相对于 src 的路径或者绝对路径，可以包含通配符，例如::
 
          foo.py
@@ -86,7 +90,26 @@
          :find.py
    * - recursive
      - 布尔
-     - 是否递归搜索工程源路径
+     - 搜索工程路径下的模块和包的模式
+       - 0 不搜索
+       - 1 只搜索工程目录下的模块
+       - 2 只搜索工程目录下的模块和包
+       - 3 递归搜索工程目录下面的所有的模块和包
+   * - pypaths
+     - 列表
+     - 指定动态导入模块时候的额外路径，支持的格式::
+
+         path
+         path,path
+         modname::path,path
+
+       主要用于重构的时候需要导入基类，以及获取 wildcard 导入的名称::
+
+         import a
+         from b import *
+
+         class C(a.T):
+             pass
 
 .. _rft-section:
 
@@ -134,7 +157,7 @@ rft
        - 1: 仅重命名 posonly 参数
        - 2: 仅保留 kwonly 的参数名称，其他都重命名
        - 3: 重命名所有函数的参数（默认值）
-   * - auto_export_mode
+   * - export_mode
      - 布尔
      - 0
      - 是否输出模块属性 `__all__` 中列出的名称
@@ -157,6 +180,8 @@ rft
 
           "inc"
           "dir*"
+          "modname::generic_visit"
+          "modname::Cls.visit_*"
 
        参数和局部变量总是会被重命名，这里列出的名称对参数和局部变量不起作用
    * - exclude_funcs
@@ -167,20 +192,59 @@ rft
           "func"
           "modname::func"
           "modname::cls.method"
-
    * - attr_rules
      - 模式列表
      -
      - 处理未知类型的属性的时候，自定义重命名规则
+
+       一个规则占一行，支持如下格式::
+
+         modname::scope:a.b.c
+         !modname::scope:a.b.c
+         modname::scope:a.b.c *.?.?
+
+      第一种格式所有的属性都重命名，第二种格式正好相反，所有的属性都不重命名
+
+      第三种格式是指定需要重命名的属性， `?` 对应的属性重命名
+   * - call_rules
+     - 模式列表
+     -
+     - 处理函数调用的时候，重命名匹配函数的关键字参数
+
+       支持的格式为函数名称，或者指定模块和范围，例如::
+
+         foo
+         visit*
+         modname::foo
+         modname:::foo*
+         modname::Cls.meth:foo
+
    * - extra_builtins
      - 名称列表
      -
      - 除了 builtins 模块之外，需要作为内置名称进行处理的额外名称
+
+       支持的格式为空格分开的名称，可以多行
    * - external_types
      - 外部类列表
      -
      - 处理未知类型的属性的时候，自动排除外部类的属性
 
+       支持的格式::
+         modname
+         modname::*
+         modname::Cls
+         modname::Cls*
+
+       只有模块名称则模块中所有的类的属性都会被排除
+   * - external_attrs
+     - 外部属性表
+     -
+     - 处理未知类型的属性的时候，自动排除这里列出的属性
+
+       支持的格式为空格分开的名称，可以多行，不支持通配符
+
+
 ..
    * - var_type_table
      - 列表