sofine 0.2.4.2

模板

所有插件都继承自超级类，sofine.plugins.plugin_base.PluginBase。您的插件 __init__ 方法必须调用超级类 __init__。

class ArchiveDotOrgSearchResults(plugin_base.PluginBase):
    def __init__(self):
        super(ArchiveDotOrgSearchResults, self).__init__()

您的插件最后一行应将模块作用域变量 plugin 赋值给您的插件类名称。例如

plugin = ArchiveDotOrgResults

插件属性

基类定义了四个属性

• self.name - string。插件的名称

• self.group - string。插件的插件组。这是插件目录中插件部署的子目录。

• self.schema - list of string。调用 get_data 时可以与传递给 get_data 的键关联的属性键集。

• self.adds_keys - boolean。表示插件是否向正在构建的数据集添加键，或者只是向现有键添加属性。

您必须始终定义 name 和 group。

self.schema = ['quote']

插件方法

插件还有四个方法。

def get_data(self, keys, args):
    """
    * `keys` - `list`. The list of keys to process.
    * `args` - `'list`. Empty for this plugin.
    Calls the Yahoo API to get all available fields for each ticker provided as a key in `keys`."""
    return {ticker : ystockquote.get_all(ticker) for ticker in keys}

{"trading::get_quotes::quote" : 47.65}

def parse_args(self, argv):
    """`[-p|--path]` - Path to the file listing the keys to load into this data source."""

    usage = "[-p|--path] - Path to the file listing the keys to load into this data source."
    parser = OptionParser(usage=usage)
    parser.add_option("-p", "--path",
                    action="store", dest="path",
                    help="Path to the file listing the keys to load into this data source. Required.")
    (opts, args) = parser.parse_args(argv)

    is_valid = True
    if not opts.path:
        print "Invalid argument error."
        print "Your args: path {0}".format(opts.path)
        print usage
        is_valid = False

    return is_valid, [opts.path]

完整的插件示例

与编写一次性脚本相比，这只是一点点开销，但投资回报率是能够知道您的插件在哪里，用标准语法调用它们，并以任何有用的组合将它们组合起来。

有多小？这里有一个与 sofine 一起分发的 Google 搜索 API 插件。

它从一个辅助函数开始，您必须编写任何一次性脚本来调用 API。

import urllib
import urllib2
import json

def query_google_search(k):
    url = 'https://ajax.googleapis.ac.cn/ajax/services/search/web?v=1.0&q={0}'.format(urllib.quote(k))
    ret = urllib2.urlopen(url)
    ret = ret.read()
    ret = json.loads(ret)

    if ret: 2
        ret = {'results' : ret['responseData']['results']}
    else:
        ret = {'results' : []}

    return ret

现在，这里有使您的插件在 sofine 中运行的 11 行附加代码。

from sofine.plugins import plugin_base as plugin_base

class GoogleSearchResults(plugin_base.PluginBase):

    def __init__(self):
        super(GoogleSearchResults, self).__init__()
        self.name = 'google_search_results'
        self.group = 'example'
        self.schema = ['results']
        self.adds_keys = False

    def get_data(self, keys, args):
        return {k : query_google_search(k) for k in keys}

plugin = GoogleSearchResults

仅为了好玩，这里是一个第二个示例。它显示了将现有的 Python API 包装器作为 sofine 插件包装是多么容易。

from sofine.plugins import plugin_base as plugin_base
import ystockquote

class YStockQuoteLib(plugin_base.PluginBase):

    def __init__(self):
        super(YStockQuoteLib, self).__init__()
        self.name = 'ystockquotelib'
        self.group = 'example'
        self.schema = ['fifty_two_week_low', 'market_cap', 'price', 'short_ratio',
                       'volume','dividend_yield', 'avg_daily_volume', 'ebitda',
                       'change', 'dividend_per_share', 'stock_exchange',
                       'two_hundred_day_moving_avg', 'fifty_two_week_high',
                       'price_sales_ratio', 'price_earnings_growth_ratio',
                       'fifty_day_moving_avg', 'price_book_ratio', 'earnings_per_share',
                       'price_earnings_ratio', 'book_value']
        self.adds_keys = False

    def get_data(self, keys, args):
        return {ticker : ystockquote.get_all(ticker) for ticker in keys}

plugin = YStockQuoteLib

HTTP插件路由

HTTP插件有四个路由，映射到Python插件中的方法。

get '/' + PLUGIN_NAME + '/' + PLUGIN_GROUP + '/get_data' do
  keys = params['keys'].split(',')
  ret = Hash[keys.map {|key| [key, query_google_search(key)]}]
  JSON.dump(ret)
end

127.0.0.1 - - [06/Oct/2014 23:55:16] "GET /google_search_results/example_http/get_data?keys=AAPL,MSFT&args= HTTP/1.1" 200 4648 0.1324

get '/' + PLUGIN_NAME + '/' + PLUGIN_GROUP + '/parse_args' do
  JSON.dump({"parsed_args" => params['args'], "is_valid" => true})
end

get '/' + PLUGIN_NAME + '/' + PLUGIN_GROUP + '/get_schema' do
  '{"schema" : ["results"]}'
end

get '/' + PLUGIN_NAME + '/' + PLUGIN_GROUP + '/get_schema' do
  '{"schema" : ["example_http::google_search_results::results"]}'
end

get '/' + PLUGIN_NAME + '/' + PLUGIN_GROUP + '/adds_keys' do
  '{"adds_keys" : false}'
end

包含数据格式插件的格式

{
 "AAPL":
    [
        {"avg_daily_volume": "59390100"},
        {"book_value": "20.193"},
        ...
    ]
}

AAPL, avg_daily_volume, 59390100, book_value, 20.193

<data>
    <row>
        <key>AAPL</key>
        <attributes>
            <attribute>
                <attribute_key>avg_daily_volume</attribute_key>
                <attribute_value>59390100</attribute_value>
            </attribute>
            <attribute>
                <attribute_key>book_value</attribute_key>
                <attribute_value>20.193</attribute_value>
            </attribute>
            ...
            ...
        </attributes>
    </row>
    ...
    ...
</data>

从命令行调用

当调用数据检索插件时，您可以可选地传递此参数来控制 sofine 期望的任何输入格式和返回数据集的数据格式。此参数在所有 sofine 数据检索调用之前传递一次，并将该格式应用于所有数据检索调用。

• [--SF-d|--SF-data-format] - 用于数据检索调用和返回数据集的数据格式。可选。默认为‘json’。

然后为每次数据检索调用传递这些参数

• [--SF-s|--SF-data-source] - 被调用的数据源名称。这是被调用的插件模块的名称。必需。

• [--SF-g|--SF-data-source-group] - 插件所在的插件组。这是插件模块部署的子目录。必需。

• [--SF-a|--SF-action] - 被调用的插件动作。如果动作是 get_data，则为可选。

调用 get_data 所需的任何其他参数应紧随 --SF-s 和 --SF-g 参数之后传递。

通过 REST 调用

sofine 配备了一个服务器，您可以在 python sofine/rest_runner.py 中启动它，通过 HTTP 调用插件。服务器默认在 localhost 的 10000 端口上运行。您可以通过设置环境变量 SOFINE_REST_PORT 来更改其运行的端口号。REST 调用使用与 CLI 调用相同的参数，但不带前导连字符。参数及其值交替形成资源路径。请参阅下一节中的示例。

get_data 示例

以下是调用 get_data 的示例

python $PYTHONPATH/sofine/runner.py '--SF-s fidelity --SF-g example -c <CUSTOMER_ID> -p <PIN> -a <ACCOUNT_ID> -e <EMAIL> | --SF-s ystockquotelib --SF-g example'

请注意，省略了 --SF-a，这意味着这是一个使用默认动作 get_data 的链式调用，首先是来自 fidelity 插件（因为它首先被调用，因为它添加了返回的键集合），然后是来自 ystockquotelib 插件（它向从 fidelity 收到的键添加属性）。

如果您想通过 REST 调用此操作，它的外观几乎相同。链式调用语法通过将参数名称和值的序列转换为 REST 资源路径来表示。

curl -X POST -d '{}' --header "Content-Type:application/json" http://localhost:10000/SF-s/fidelity/SF-g/example/c/<CUSTOMER_ID>/p/<PIN>/a/<ACCOUNT_ID>/e/<EMAIL>/SF-s/ystockquotelib/SF-g/example

以下是相同的 Python 示例

import sofine.runner as runner

data = {}
data_sources = ['fidelity', 'ystockquotelib']
data_source_groups = ['example', 'example']
data_source_args = [[customer_id, pin, account_id, email], []]
data = runner.get_data_batch(data, data_sources, data_source_groups, data_source_args)

此调用返回上述形式的数据集。以下是 JSON 输出

{
    "key_1": [{"attribute_1": value_1}, {"attribute_2": value_2}, ...],
    "key_2": ...
}

使用数据格式插件进行 get_data 示例

这是相同的调用，但使用 CSV 而不是默认的 JSON 作为数据格式

python $PYTHONPATH/sofine/runner.py '--SF-d format_csv --SF-s fidelity --SF-g example -c <CUSTOMER_ID> -p <PIN> -a <ACCOUNT_ID> -e <EMAIL> | --SF-s ystockquotelib --SF-g example'

其他动作

最后，让我们讨论 get_data 之外的其他动作。请注意，这些动作中没有一个可以链式调用。

get_namespaced_data

与 get_data 的工作方式相同，但在 CLI 调用中必须包含 --SF-a 参数或在 REST 调用中包含 SF-a 参数。

python $PYTHONPATH/sofine/runner.py '--SF-s fidelity --SF-g example --SF-a get_namespaced_data -c <CUSTOMER_ID> -p <PIN> -a <ACCOUNT_ID> -e <EMAIL> | --SF-s ystockquotelib --SF-g example --SF-a get_namespaced_data'

curl -X POST -d '{}' --header "Content-Type:application/json" http://localhost:10000/SF-s/fidelity/SF-g/example/SF-a/get_namespaced_data/c/<CUSTOMER_ID>/p/<PIN>/a/<ACCOUNT_ID>/e/<EMAIL>/SF-s/ystockquotelib/SF-g/example/SF-a/get_namespaced_data

此调用返回上述形式的数据集。以下是 JSON 输出。

{
    "key_1": [{"plugin_group::plugin_name::attribute_1": value_1},
    i         {"plugin_group::plugin_name::attribute_2": value_2}, ...],
    "key_2": ...
}

get_data_batch

这是一个仅在 Python 中可用的辅助动作，用于支持将插件调用组合成一个批处理调用，该调用返回一个数据集，相当于在一个调用中链式调用命令行或 REST 插件。

import sofine.runner as runner

data = {}
data_sources = ['fidelity', 'ystockquotelib']
data_source_groups = ['example', 'example']
data_source_args = [[customer_id, pin, account_id, email], []]
data = runner.get_data_batch(data, data_sources, data_source_groups, data_source_args)

请注意，该函数接受一个插件名称列表、一个插件组列表和一个列表列表的参数。每个列表必须将相应的插件、组和参数按顺序放置。

parse_args

您很少需要直接调用插件 parse_args。一种用法是测试您计划传递给 get_data 的参数是否有效 - 例如，在执行长时间运行的 get_data 调用之前，您可能想这样做。

从 CLI

python $PYTHONPATH/sofine/runner.py '--SF-s file_source --SF-g standard --SF-a parse_args -p "./sofine/tests/fixtures/file_source_test_data.txt"'

从 REST

curl -X POST -d '{}' --header "Content-Type:application/json" http://localhost:10000/SF-s/file_source/SF-g/standard/SF-a/parse_args/p/.%2Fsofine%2Ftests%2Ffixtures%2Ffile_source_test_data.txt

从Python

def test_parse_args_file_source(self):
    data_source = 'file_source'
    data_source_group = 'standard'
    path = './sofine/tests/fixtures/file_source_test_data.txt'
    args = ['-p', path]
    actual = runner.parse_args(data_source, data_source_group, args)

    self.assertTrue(actual['is_valid'] and actual['parsed_args'] == [path])

该调用返回以下JSON，并且该调用只支持JSON输出。

{"is_valid": true|false, "parsed_args": [arg_1, arg_2, ...]}

get_schema

调用 get_schema 有几种用例，尤其是在 Python 中。例如，您可能希望从一起调用的一个或多个插件中检索属性键，以过滤或查询所有属性键的子集返回的数据。

命令行界面

python $PYTHONPATH/sofine/runner.py '--SF-s ystockquotelib --SF-g example --SF-a get_schema'

REST

curl -X POST -d '{}' --header "Content-Type:application/json" http://localhost:10000/SF-s/ystockquotelib/SF-g/example/SF-a/get_schema

Python

data_source = 'ystockquotelib'
data_source_group = 'example'
schema = runner.get_schema(data_source, data_source_group)

该调用返回以下JSON，并且该调用只支持JSON输出。

{"schema": [attribute_key_name_1, attribute_key_name_2, ...]}

get_namespaced_schema

与 get_schema 完全相同，但以命名空间形式返回模式字段。

命令行界面

python $PYTHONPATH/sofine/runner.py '--SF-s ystockquotelib --SF-g example --SF-a get_namespaced_schema'

REST

curl -X POST -d '{}' --header "Content-Type:application/json" http://localhost:10000/SF-s/ystockquotelib/SF-g/example/SF-a/get_namespaced_schema

Python

data_source = 'ystockquotelib'
data_source_group = 'example'
schema = runner.get_namespaced_schema(data_source, data_source_group)

该调用返回以下JSON，并且该调用只支持JSON输出。

{
    "schema": [plugin_group::plugin_name::attribute_key_name_1,
               plugin_group::plugin_name::attribute_key_name_2, ...]
}

添加键

adds_keys 动作允许您以编程方式询问插件是否向 sofine 构建的数据集添加键。假设您想了解在调用 sofine 插件的序列中哪些步骤添加键以及它们添加了哪些键。

for name, group in plugin_map:
    prev_keys = set(data.keys())
    data = runner.get_data(data, name, group, args_map[name])

    if runner.adds_keys(name, group):
        new_keys = set(data.keys()) - prev_keys
        logger.log(new_keys)

以下是调用 adds_keys 的示例

命令行界面

python $PYTHONPATH/sofine/runner.py '--SF-s ystockquotelib --SF-g example --SF-a adds_keys'

REST

curl -X POST -d '{}' --header "Content-Type:application/json" http://localhost:10000/SF-s/ystockquotelib/SF-g/example/SF-a/adds_keys

Python

data_source = 'ystockquotelib'
data_source_group = 'example'
adds_keys = runner.adds_keys(data_source, data_source_group)

该调用返回以下JSON，并且该调用只支持JSON输出。

{"adds_keys": true|false}

get_plugin

get_plugin 动作允许您在 Python 中获取插件对象的实例。这可以让您直接访问类范围方法或实例属性。

Python

data_source = 'google_search_results'
data_source_group = 'example'
plugin = runner.get_plugin(data_source, data_source_group)
schema = plugin.schema

get_plugin_module

get_plugin_module 动作允许您在 Python 中获取插件模块的实例。这可以让您直接访问模块范围方法或变量。例如，Google 搜索结果模块实现了一个名为 get_child_schema 的附加辅助程序，该辅助程序返回它为传递给它的每个键返回的 results JSON 对象中的属性列表。由于这是嵌套数据，更有趣的属性位于返回数据的下一级，辅助程序会告诉我们这些信息。

data_source = 'google_search_results'
data_source_group = 'example'
mod = runner.get_plugin_module(data_source, data_source_group)
# The google plugin implements an additional helper method in the module that returns
# the list of attributes in each 'results' object it returns mapped to each key
child_shema = mod.get_child_schema()