Pre-releases v0.12.3rc1 (#274)

Author: wjsi

docs/source/base-functions.rst

@@ -8,8 +8,9 @@ ODPS用户可以编写自定义 `函数 <https://help.aliyun.com/document_detail
 基本操作
 ---------
 
-可以调用 ODPS 入口对象的 ``list_functions`` 来获取项目空间下的所有函数，``exist_function`` 能判断是否存在函数，
-``get_function`` 获取函数对象。
+可以调用 ODPS 入口对象的 :meth:`~odps.ODPS.list_functions` 来获取项目空间下的所有函数，
+:meth:`~odps.ODPS.exist_function` 能判断是否存在函数，\ :meth:`~odps.ODPS.get_function`
+获取函数对象。
 
 创建函数
 ---------

docs/source/base-instances.rst

@@ -9,8 +9,9 @@ Task如SQLTask是ODPS的基本计算单元，当一个Task在执行时会被实
 基本操作
 --------
 
-可以调用 ``list_instances`` 来获取项目空间下的所有instance， ``exist_instance`` 能判断是否存在某instance，
-``get_instance`` 能获取实例。
+可以调用 :meth:`~odps.ODPS.list_instances` 来获取项目空间下的所有 instance，\
+:meth:`~odps.ODPS.exist_instance` 能判断是否存在某instance，\
+:meth:`~odps.ODPS.get_instance` 能获取实例。
 
 .. code-block:: python
 
@@ -20,7 +21,8 @@ Task如SQLTask是ODPS的基本计算单元，当一个Task在执行时会被实
    >>>     print("Instance <my_instance_id> exists!")
 
 
-停止一个instance可以在odps入口使用 ``stop_instance``，或者对 instance 对象调用 ``stop`` 方法：
+停止一个instance可以在odps入口使用 :meth:`~odps.ODPS.stop_instance`\ ，或者对 :class:`~odps.models.Instance`
+对象调用 :meth:`~odps.models.Instance.stop` 方法：
 
 .. code-block:: python
 
@@ -35,7 +37,7 @@ Task如SQLTask是ODPS的基本计算单元，当一个Task在执行时会被实
 获取 LogView 地址
 ---------------
 
-对于 SQL 等任务，通过调用 ``get_logview_address`` 方法即可。
+对于 SQL 等任务，通过调用 :meth:`~odps.ODPS.get_logview_address` 方法即可。
 
 .. code-block:: python
 
@@ -58,9 +60,10 @@ Task如SQLTask是ODPS的基本计算单元，当一个Task在执行时会被实
 任务实例状态
 -------------
 
-一个instance的状态可以是 ``Running``、``Suspended`` 或者 ``Terminated``，用户可以通过 ``status`` 属性来获取状态。
-``is_terminated`` 方法返回当前instance是否已经执行完成，``is_successful`` 方法返回当前instance是否正确完成执行，
-任务处于运行中或者执行失败都会返回False。
+一个instance的状态可以是 ``Running``、``Suspended`` 或者 ``Terminated``，用户可以通过
+:meth:`~odps.models.Instance.status` 属性来获取状态。:meth:`~odps.models.Instance.is_terminated`
+方法返回当前instance是否已经执行完成，:meth:`~odps.models.Instance.is_successful`
+方法返回当前instance是否正确完成执行，任务处于运行中或者执行失败都会返回False。
 
 .. code-block:: python
 
@@ -74,23 +77,24 @@ Task如SQLTask是ODPS的基本计算单元，当一个Task在执行时会被实
    'Terminated'
 
 
-调用 ``wait_for_completion`` 方法会阻塞直到instance执行完成。 ``wait_for_success`` 方法同样会阻塞，不同的是，
+调用 :meth:`~odps.models.Instance.wait_for_completion` 方法会阻塞直到instance执行完成。\
+:meth:`~odps.models.Instance.wait_for_success` 方法同样会阻塞，不同的是，\
 如果最终任务执行失败，则会抛出相关异常。
 
 子任务操作
 -----------
 
 一个Instance真正运行时，可能包含一个或者多个子任务，我们称为Task，要注意这个Task不同于ODPS的计算单元。
 
-我们可以通过 ``get_task_names`` 来获取所有的Task任务，它返回一个所有子任务的名称列表。
+我们可以通过 :meth:`~odps.models.Instance.get_task_names` 来获取所有的Task任务，它返回一个所有子任务的名称列表。
 
 .. code-block:: python
 
    >>> instance.get_task_names()
    ['SQLDropTableTask']
 
-拿到Task的名称，我们就可以通过 ``get_task_result`` 来获取这个Task的执行结果。
-``get_task_results`` 以字典的形式返回每个Task的执行结果
+拿到Task的名称，我们就可以通过 :meth:`~odps.models.Instance.get_task_result` 来获取这个Task的执行结果。\
+:meth:`~odps.models.Instance.get_task_results` 以字典的形式返回每个Task的执行结果
 
 .. code-block:: python
 
@@ -103,7 +107,8 @@ Task如SQLTask是ODPS的基本计算单元，当一个Task在执行时会被实
    OrderedDict([('AnonymousSQLTask',
               '"sepallength","sepalwidth","petallength","petalwidth","name"\n5.1,3.5,1.4,0.2,"Iris-setosa"\n')])
 
-有时候我们需要在任务实例运行时显示所有子任务的运行进程。使用 ``get_task_progress`` 能获得Task当前的运行进度。
+有时候我们需要在任务实例运行时显示所有子任务的运行进程。使用 :meth:`~odps.models.Instance.get_task_progress`
+能获得Task当前的运行进度。
 
 .. code-block:: python
 

docs/source/base-models.rst

@@ -12,15 +12,15 @@ XFlow 是 ODPS 对算法包的封装，使用 PyODPS 可以执行 XFlow。对于
 
     PAI -name AlgoName -project algo_public -Dparam1=param_value1 -Dparam2=param_value2 ...
 
-可以使用如下方法调用：
+可以使用 :meth:`~odps.ODPS.run_xflow` 提交任务：
 
 .. code:: python
 
     >>> # 异步调用
     >>> inst = o.run_xflow('AlgoName', 'algo_public',
                            parameters={'param1': 'param_value1', 'param2': 'param_value2', ...})
 
-或者使用同步调用：
+或者使用 :meth:`~odps.ODPS.execute_xflow` 提交任务并等待执行完成：
 
 .. code:: python
 
@@ -30,18 +30,20 @@ XFlow 是 ODPS 对算法包的封装，使用 PyODPS 可以执行 XFlow。对于
 
 参数不应包含命令两端的引号（如果有），也不应该包含末尾的分号。
 
-这两个方法都会返回一个 Instance 对象。由于
+这两个方法都会返回一个 :class:`~odps.models.Instance` 对象。由于
 XFlow 的一个 Instance 包含若干个子 Instance，需要使用下面的方法来获得每个 Instance 的 LogView：
 
 .. code-block:: python
 
     >>> for sub_inst_name, sub_inst in o.get_xflow_sub_instances(inst).items():
     >>>     print('%s: %s' % (sub_inst_name, sub_inst.get_logview_address()))
 
-需要注意的是，``get_xflow_sub_instances`` 返回的是 Instance 当前的子 Instance，可能会随时间变化，因而可能需要定时查询。
-为简化这一步骤，可以使用 ``iter_xflow_sub_instances 方法``。该方法返回一个迭代器，会阻塞执行直至发现新的子 Instance
-或者主 Instance 结束。同时需要注意的是， ``iter_xflow_sub_instances`` 默认不会检查 Instance 是否报错，建议在循环结束时手动检查
-Instance 是否报错，以免遗漏可能的问题，或者增加 ``check=True`` 参数在 ``iter_xflow_sub_instances`` 退出时自动检查：
+需要注意的是，:meth:`~odps.ODPS.get_xflow_sub_instances` 返回的是 Instance 当前的子 Instance，\
+可能会随时间变化，因而可能需要定时查询。为简化这一步骤，可以使用 :meth:`~odps.ODPS.iter_xflow_sub_instances`
+方法。该方法返回一个迭代器，会阻塞执行直至发现新的子 Instance 或者主 Instance 结束。同时需要注意的是，
+:meth:`~odps.ODPS.iter_xflow_sub_instances` 默认不会检查 Instance 是否报错，建议在循环结束时手动检查
+Instance 是否报错，以免遗漏可能的问题，或者增加 ``check=True`` 参数在 :meth:`~odps.ODPS.iter_xflow_sub_instances`
+退出时自动检查：
 
 .. code-block:: python
 

docs/source/base-projects.rst

@@ -6,7 +6,7 @@
 `项目空间 <https://help.aliyun.com/document_detail/27818.html>`_ 是ODPS的基本组织单元，
 有点类似于Database的概念。
 
-我们通过 ODPS 入口对象的 ``get_project`` 来取到某个项目空间。
+我们通过 ODPS 入口对象的 :meth:`~odps.ODPS.get_project` 来取到某个项目空间。
 
 .. code-block:: python
 
@@ -15,4 +15,4 @@
 
 如果不提供参数，则取到默认项目空间。
 
-``exist_project`` 方法能检验某个项目空间是否存在。
+:meth:`~odps.ODPS.exist_project` 方法能检验某个项目空间是否存在。

docs/source/base-resources.rst

@@ -10,8 +10,8 @@
 基本操作
 -------
 
-列出所有资源还是可以使用 ``list_resources``，判断资源是否存在使用 ``exist_resource``。
-删除资源时，可以调用 ``delete_resource``，或者直接对于Resource对象调用 ``drop`` 方法。
+列出所有资源还是可以使用 :meth:`~odps.ODPS.list_resources`，判断资源是否存在使用 :meth:`~odps.ODPS.exist_resource`。\
+删除资源时，可以调用 :meth:`~odps.ODPS.delete_resource`，或者直接对于Resource对象调用 :meth:`~odps.models.Resource.drop` 方法。
 
 例如，要列举 Project 下的所有资源，可以使用下面的方法：
 
@@ -33,8 +33,8 @@
 
     o.exist_resource("resource_name.tar.gz")
 
-删除给定资源，可以使用 ODPS 入口对象的 ``delete_resource`` 方法，也可以使用 ``Resource``
-对象自己的 ``drop`` 方法。
+删除给定资源，可以使用 ODPS 入口对象的 :meth:`~odps.models.Resource.delete_resource` 方法，也可以使用
+:class:`~odps.models.Resource` 对象自己的 :meth:`~odps.models.Resource.drop` 方法。
 
 .. code-block:: python
 
@@ -109,7 +109,7 @@
 同时，PyODPS中，文件资源支持以二进制模式打开，打开如说一些压缩文件等等就需要以这种模式，
 因此 ``rb`` 就是指以二进制读模式打开文件，``r+b`` 是指以二进制读写模式打开。
 
-对于较大的文件资源，可以使用流式方式读写文件，使用方法为在调用 ``open_resource`` 时增加一个
+对于较大的文件资源，可以使用流式方式读写文件，使用方法为在调用 :meth:`~odps.ODPS.open_resource` 时增加一个
 ``stream=True`` 选项：
 
 .. code-block:: python

docs/source/base-schemas.rst

@@ -13,33 +13,33 @@ Schema
 
 Schema 基本操作
 ----------------
-你可以使用 ``exist_schema`` 判断 Schema 对象是否存在：
+你可以使用 :meth:`~odps.ODPS.exist_schema` 判断 Schema 对象是否存在：
 
 .. code-block:: python
 
     print(o.exist_schema("test_schema"))
 
-使用 ``create_schema`` 创建一个 Schema 对象：
+使用 :meth:`~odps.ODPS.create_schema` 创建一个 Schema 对象：
 
 .. code-block:: python
 
     schema = o.create_schema("test_schema")
     print(schema)
 
-使用 ``delete_schema`` 删除一个 Schema 对象：
+使用 :meth:`~odps.ODPS.delete_schema` 删除一个 Schema 对象：
 
 .. code-block:: python
 
     schema = o.delete_schema("test_schema")
 
-使用 ``get_schema`` 获得一个 Schema 对象并打印 Schema Owner：
+使用 :meth:`~odps.ODPS.get_schema` 获得一个 Schema 对象并打印 Schema Owner：
 
 .. code-block:: python
 
     schema = o.get_schema("test_schema")
     print(schema.owner)
 
-使用 ``list_schema`` 列举所有 Schema 对象并打印名称：
+使用 :meth:`~odps.ODPS.list_schema` 列举所有 Schema 对象并打印名称：
 
 .. code-block:: python
 

docs/source/base-sql.rst

@@ -3,30 +3,33 @@
 SQL
 =====
 
-PyODPS支持ODPS SQL的查询，并可以读取执行的结果。 ``execute_sql`` / ``execute_sql_interactive`` /
-``run_sql`` / ``run_sql_interactive`` 方法的返回值是 :ref:`运行实例 <instances>` 。
+PyODPS支持ODPS SQL的查询，并可以读取执行的结果。 :meth:`~odps.ODPS.execute_sql` /
+:meth:`~odps.ODPS.execute_sql_interactive` / :meth:`~odps.ODPS.run_sql` /
+:meth:`~odps.ODPS.run_sql_interactive` 方法的返回值是 :ref:`运行实例 <instances>` 。
 
 .. note::
 
     并非所有在 ODPS Console 中可以执行的命令都是 ODPS 可以接受的 SQL 语句。
     在调用非 DDL / DML 语句时，请使用其他方法，例如 GRANT / REVOKE 等语句请使用
-    ``run_security_query`` 方法，PAI 命令请使用 ``run_xflow`` 或 ``execute_xflow`` 方法。
+    :meth:`~odps.ODPS.run_security_query` 方法，PAI 命令请使用
+    :meth:`~odps.ODPS.run_xflow` 或 :meth:`~odps.ODPS.execute_xflow` 方法。
 
 .. _execute_sql:
 
 执行 SQL
 --------
 
-你可以使用 ``execute_sql`` 方法以同步方式执行 SQL。调用时，该方法会阻塞直至 SQL 执行完成，并返回一个
-Instance 实例。如果 SQL 执行报错，该方法会抛出以 ``odps.errors.ODPSError`` 为基类的错误。
+你可以使用 :meth:`~odps.ODPS.execute_sql` 方法以同步方式执行 SQL。调用时，该方法会阻塞直至 SQL 执行完成，并返回一个
+:class:`~odps.models.Instance` 实例。如果 SQL 执行报错，该方法会抛出以 ``odps.errors.ODPSError`` 为基类的错误。
 
 .. code-block:: python
 
    >>> o.execute_sql('select * from dual')  # 同步的方式执行，会阻塞直到SQL执行完成
 
 你也可以使用非阻塞方式异步执行 SQL。调用时，该方法在将 SQL 提交到 MaxCompute 后即返回 Instance
-实例。你需要使用 ``wait_for_success`` 方法等待该 SQL 执行完成。同样地，如果 instance 出现错误，
-``wait_for_success`` 会抛出以 ``odps.errors.ODPSError`` 为基类的错误。
+实例。你需要使用 :meth:`~odps.models.Instance.wait_for_success` 方法等待该 SQL 执行完成。\
+同样地，如果 instance 出现错误，:meth:`~odps.models.Instance.wait_for_success` 会抛出以
+``odps.errors.ODPSError`` 为基类的错误。
 
 .. code-block:: python
 
@@ -42,7 +45,7 @@ Instance 实例。如果 SQL 执行报错，该方法会抛出以 ``odps.errors.
 支持使用独立资源池对中小规模数据进行加速。PyODPS 从 0.11.4.1 开始支持以下列方式通过 MCQA 执行 SQL
 ，同时需要 MaxCompute 具备 MCQA 的支持。
 
-你可以使用 ``execute_sql_interactive`` 通过 MCQA 执行 SQL 并返回 MCQA Instance。如果
+你可以使用 :meth:`~odps.ODPS.execute_sql_interactive` 通过 MCQA 执行 SQL 并返回 MCQA Instance。如果
 MCQA 无法执行相应的 SQL ，会自动回退到传统模式。此时，函数返回的 Instance 为回退后的 Instance。
 
 .. code-block:: python
@@ -64,9 +67,9 @@ MCQA 无法执行相应的 SQL ，会自动回退到传统模式。此时，函
 
     >>> o.execute_sql_interactive('select * from dual', fallback="noresource,unsupported")
 
-你也可以使用 ``run_sql_interactive`` 通过 MCQA 异步执行 SQL。类似 ``run_sql``，该方法会在提交任务后即返回
-MCQA Instance，你需要自行等待 Instance 完成。需要注意的是，该方法不会自动回退。当执行失败时，你需要自行重试或执行
-``execute_sql``。
+你也可以使用 :meth:`~odps.ODPS.run_sql_interactive` 通过 MCQA 异步执行 SQL。类似 :meth:`~odps.ODPS.run_sql`，\
+该方法会在提交任务后即返回 MCQA Instance，你需要自行等待 Instance 完成。需要注意的是，该方法不会自动回退。当执行失败时，\
+你需要自行重试或执行 :meth:`~odps.ODPS.execute_sql`。
 
 .. code-block:: python
 
@@ -115,8 +118,9 @@ MCQA Instance，你需要自行等待 Instance 完成。需要注意的是，该
 设置运行参数
 ------------
 
-有时，我们在运行时，需要设置运行时参数，我们可以通过设置 ``hints`` 参数，参数类型是 dict。该参数对 ``execute_sql`` /
-``execute_sql_interactive`` / ``run_sql`` / ``run_sql_interactive`` 均有效。
+有时，我们在运行时，需要设置运行时参数，我们可以通过设置 ``hints`` 参数，参数类型是 dict。该参数对
+:meth:`~odps.ODPS.execute_sql` / :meth:`~odps.ODPS.execute_sql_interactive` /
+:meth:`~odps.ODPS.run_sql` / :meth:`~odps.ODPS.run_sql_interactive` 均有效。
 
 .. code-block:: python
 
@@ -139,7 +143,7 @@ MCQA Instance，你需要自行等待 Instance 完成。需要注意的是，该
 读取 SQL 执行结果
 ---------------
 
-运行 SQL 的 instance 能够直接执行 ``open_reader`` 的操作，一种情况是SQL返回了结构化的数据。
+运行 SQL 的 instance 能够直接执行 :meth:`~odps.models.Instance.open_reader` 的操作，一种情况是SQL返回了结构化的数据。
 
 .. code-block:: python
 
@@ -210,18 +214,18 @@ PyODPS 检测到读取 Instance 数据被限制，且 ``options.tunnel.limit_ins
     从 2024 年年末开始，MaxCompute 服务将支持离线 SQL 任务 ``open_reader`` 使用与表类似的 Arrow
     接口，MCQA 作业暂不支持。在此之前，使用 ``Instance.open_reader(arrow=True)`` 读取数据将报错。
 
-从 PyODPS 0.12.0 开始，你也可以直接调用 Instance 上的 ``to_pandas`` 方法直接将数据转换为 pandas。\
-你可以指定转换为 pandas 的起始行号和行数，若不指定则读取所有数据。该方法也支持 ``limit`` 参数，具体定义\
-与 ``open_reader`` 方法相同。该方法默认会使用 Arrow 格式读取，并转换为 pandas。如果 Arrow 格式不被\
-支持，将会回退到 Record 接口。
+从 PyODPS 0.12.0 开始，你也可以直接调用 Instance 上的 :meth:`~odps.models.Instance.to_pandas`
+方法直接将数据转换为 pandas。你可以指定转换为 pandas 的起始行号和行数，若不指定则读取所有数据。该方法也支持
+``limit`` 参数，具体定义与 ``open_reader`` 方法相同。该方法默认会使用 Arrow 格式读取，并转换为
+pandas。如果 Arrow 格式不被支持，将会回退到 Record 接口。
 
 .. code-block:: python
 
   >>> inst = o.execute_sql('select * from dual')
   >>> pd_df = inst.to_pandas(start=10, count=20)
 
-与表类似，从 PyODPS 0.12.0 开始，你也可以使用 Instance 上的 ``iter_pandas`` 方法按多个批次读取
-pandas DataFrame，参数与 ``Table.iter_pandas`` 类似。
+与表类似，从 PyODPS 0.12.0 开始，你也可以使用 Instance 上的 :meth:`~odps.models.Instance.iter_pandas`
+方法按多个批次读取 pandas DataFrame，参数与 ``Table.iter_pandas`` 类似。
 
 .. code-block:: python