【量化交易】 下单、函数、API 【004】

本文是 量化交易零基础入门教程 中的一篇，点击蓝字链接可查看该系列详情。

---

摘要

• 函数与 API
• 函数使用方法
• 如何看 API 文档
• 自定义函数方法
• 常用的下单函数
• 自测与自学

---

• 我们继续以前文策略代码为例进行讲解，如下：

    def initialize (context):
        run_daily (period,time='every_bar')
        g.security = '000001.XSHE'
  
    def period (context):
        order (g.security, 100)
  

• 通过前文讲解，现在这段代码中就剩这句下单语句还没讲了。为了理解这条语句，需要学习下 python 中函数的知识。

    order (g.security, 100)
  

函数与 API

• 函数是封装好的，可重复使用的 ，用来实现专一功能的代码段。函数能使代码易于维护与交流，提高编写策略的效率。通俗的理解是，把一系列代码指令包起来就是一个函数，起个名字就是函数名，之后用这个函数名，就知道这个名字指代那被包起来的一系列代码指令了。

• Python 语言自带了许多内建函数，比如之前见过的 print ()、type () 都是 Python 自带的函数，可以直接用。你也可以自己创建函数自己用，这被叫做自定义函数。比如如下这段框架代码其实就是自定义了一个名为 period 的函数，该函数内包了一个聚宽系统自带的函数 order ()：

    def period (context):
        order (g.security, 100)
  

• order () 的准确称谓其实是 API（application programming interface，即应用程序编程接口），API 的含义与函数有所不同，解释起来略复杂。不过实际使用中跟函数几乎没有差别，可以理解成聚宽平台基于 python 封装而成的函数。在 聚宽的 API 文档 中你可以看到除 order () 外其他 API。

使用一个函数

• 在使用函数的时候，通常需要提供一些参数 (也有可能不需要)，函数根据提供的参数，执行一系列的函数作者设计好的操作，往往也会根据提供的参数返回结果（也可能返回为空，即不返回），如下：

    # 用法：函数名 (参数，参数，......)
    # 例子如下：
  
    # 提供了两个参数 g.security 和 100，执行了买入 g.security 中数据对应的股票 100 股的操作
    order (g.security, 100)
  
    # 提供了一个参数 "你好"，执行了打印 "你好" 的操作
    print ("你好")
  
    # 提供了一个参数 "1" 给 type () 函数，type 函数执行了识别 "1" 数据类型的操作，并返回了 "1" 数据类型为结果。
    # type 返回的结果被当做参数提供给了 print (),print 执行了打印 type 返回的结果的操作
    # type 与 print 的嵌套使用，实现了打印 "1" 数据类型的操作。
    print (type ("1"))
  

• 可见，函数的功能多种多样，需要参数、返回的结果亦不尽相同，所以具体怎么用需要看函数作者提供的说明文档，或者看函数内的设计代码自己推断。函数内的代码不见得看得到，看到不一定看得懂，想看懂也可能很辛苦。所以一般函数的用法要看函数作者提供的说明文档。

• 聚宽设计的函数 (如前文所说准确叫法是 API) 的用法都写在 API 文档里，位置在聚宽网站导航栏 - 帮助 - API 文档。
• 接下来以 order 为例讲下文档怎么看。在 API 文档中找到 order - 按股数下单 的说明，如下：
  

• 可以看到，order 可接受的参数有 5 个，分别是 security，amount，style，side，pindex，这五个参数的名字与含义是函数作者设计的。意思是你使用 order 提供参数的时候，被提供参数将 按提供的顺序依次对应 这 5 个参数。比如下面的写法就是错误的。

    # 函数会按顺序把 100 对应为 security，即股票代码，把 "000001.XSHE" 对应为 amount，即要交易的数量。所以就会错。
    order (100,"000001.XSHE")
  

• 不按顺序提供参数的正确写法如下：

    # 用等号表示对应关系，参数名写前，要当做参数的变量或数据写在后
    # 如下是把 100 当做 amount 参数，把 "000001.XSHE" 当做 security 参数。
    order (amount=100,security="000001.XSHE")
  

• 可以发现有些参数后面有等号，如 style=None，含义 style 参数不提供的话，会被默认是 None，其他的 side='long', pindex=0 也是一样的道理，如果不提供会被默认是等号后面的内容。所以前文 order () 只写了两个参数也不会错。注意，security 和 amount 后面没有等号，即没有默认值，则必须提供参数不能省略。

    # 以下两句含义相同
    order ("000001.XSHE",100)
    order ("000001.XSHE",100,None,'long',0)
  

• 细说下 order 的各个参数

  • security 标的代码，数据类型要求是字符串，想知道 基金、期货、指数的代码都是什么，可以在这里看 聚宽数据 , 比如聚宽数据 - 向下滚动页面 - 点击指数数据，可以看到各指数的代码。特别的是股票代码目前没有页面，但只需在平时使用的股票代码后面加后缀就好了， 深交所（深交所股票 0 开头）股票代码后缀为.XSHE, 如 000001.XSHE, 上交所股票代码（上交所股票 6 开头）后缀为.XSHG 如 600000.XSHG。
  • amount 交易数量，正数表示买入，负数表示卖出，没什么可说的。
  • style 参数决定下的订单是市价单还是限价单，默认是 None 代表市价单。目前就用默认吧，限价单以后讲。
  • side 参数决定是开空单还是多单，默认为多单，股票只能多单，股指期货等其他品类可以开空单。
  • pindex 参数是在多资金仓位时选择资金仓位的，股票一般用不到。
• 根据说明文档，order 函数是有返回值的，如果创建订单成功，则返回 Order 对象，失败则返回 None。有返回值不一定要用，比如前文的例子都没用到这个返回值，实际上策略做的相当完备的时候才可能用到。一般用法是，根据返回值是否是 None，判断是否下单成功，成功时，根据返回值可以查询订单或取消订单等。不过具体实现方法、以及 Order 对象是什么，还需要学习很多的知识，后续可能会讲到。

自定义函数

• Python 定义函数使用 def 关键字，一般格式如下：

    def 函数名 (参数列表):
        函数体
  

• 函数名即为该函数起的名字，函数体即包在函数中的一系列操作的代码，参数列表即使用函数需要提供的参数，比如一个根据圆半径求周长的函数如下：

    # 根据圆半径 r 求周长 l
    def yuan (r):
        p=3.14
        l=2*p*r
        return l
  

• return 的含义是结束函数的运行并返回一个值，如上例子中就是返回了算好的周长 l。如果 return 后什么也不写就是返回 None 即空，如果不写 return，函数体运行完后，自动 return None。

• 至此，你应该意识到，函数内部是相对独立的，数据想进来要通过参数传进来，想出去要通过返回值传出去，函数从获得参数到返回值的过程中所产生的数据与变量中没通过返回值传出去的，在函数运行结束后（即返回值后）都将被计算机释放不再存储。如果想函数间通用某变量可以考虑用之前讲的全局变量。

• 如前文讲使用函数时看到的，可以用等号给参数附加默认值，而且可以用逗号分隔分隔多个参数，例子如下:

    # 根据圆半径 r 求周长 l 的 k 分之一
    def yuan (r,k=1):
        p=3.14
        l=2*p*r/k
        return l
  

• 在返回值的时候可以返回多个变量，例子如下:

    # 根据圆半径 r 求周长 l 与面积 s 的 k 分之一
    def yuan (r,k=1):
        p=3.14
        l=2*p*r/k
        s=p*r*r/k
        return l,s
  

• 使用自定义函数的方法跟前文讲的使用函数的方法一致，需要说明的是定义函数的代码放的位置，如下：

  

常用的下单函数

• 常用的下单函数有四个，使用方法和 order () 差不多，可能有人自己看 API 文档就能学会了。接下来我们分别介绍下基本用法，同样的不讲 style，side，pindex 这三个参数。

• order (security,amount)，刚刚细讲过，含义是买卖一定数量的（单位：股）股票。security 是股票代码，amount 是数量，amount 为负数时就是代表卖出了，需要知道的是，国内股票买入最小单位是 1 手即 100 股。例子如下：

    # 买入 100 股平安银行
    order ("000001.XSHE",100)
    # 卖出 100 股平安银行
    order ("000001.XSHE",-100)
  

• order_target (security,amount)，含义是通过买卖，将股票仓位调整至一定数量（单位：股）。security 是股票代码，amount 是数量。例子如下：

    # 调整平安银行的持股数量至 1000 股
    # 即，如果目前平安银行的持股数量低于 1000 股就买入，高于就是卖出，不高不低就不动。
    order_target ("000001.XSHE",1000)
  

• order_value (security,value)，含义是买卖一定价值量（单位：元）股票。security 是股票代码，value 是价值量。value 为负数时就是代表卖出了。例子如下：

    # 买入 10000 元的平安银行
    # 如果当前股票市价是 10 元，则代表买入 1000 股
    # 如果除不开系统会自动调整成相近的合理数量。卖出时也会。
    order_value ("000001.XSHE",10000)
    # 卖出 10000 元的平安银行
    # 如果当前股票市价是 100 元，则代表卖出 100 股
    order_value ("000001.XSHE",-10000)
  

• order_target_value (security,value)，通过买卖，将股票仓位调整至一定价值量（单位：元）。security 是股票代码，value 是价值量。例子如下：

    # 调整平安银行的持股价值量至 10000 元
    # 即，如果目前平安银行的持股价值量（按股票市价算）低于 10000 元就买入，高于就是卖出，不高不低就不动。
    order_target_value ("000001.XSHE",10000)
  

• 读者在尝试练习使用这些语句的时候，可以点击运行回测，通过查看回测结果页中的交易详情来看语句的执行效果，同时也可以看下日志。如下：

  
  

• 股票拆分合并和分红，交易的税费，下单导致成交价向不利的方向波动，这些因素系统都是默认考虑并仿真处理的了，具体的详情以及下的订单系统是如何模拟真实情况撮合成交的，可以看下 API 文档 订单处理。其实新手不用太关注 这些订单处理的细节，不核心，目前也不容易理解，可以等以后自己比较熟悉了再看。

自测与自学

• 实践下本文中的例子。
• 搜索了解下移动平均线（MA，均线）的计算方法。
• 搜索了解下市价单、限价单的含义。
• 自定义一个可计算包含若干数 list 中数的平均值的函数。即如果你定义的函数为 pjs ()，那么执行 pjs ([1,3,4,6]) 后，应该返回平均数 3.5。【提示：len () 可用来计算 list 的长度，用法如 len ([1,2,3,4])】。