草图语法资源管理器

• 草图语法资源管理器
  • 介绍
  • 设置
  • 进行 API 调用
    • 保存结果
    • 输入文件
  • 特征
  • 笔记
  • 关于
  • 引文

介绍

Sketch Grammar Explorer (SGEX) 是一个用于使用Sketch Engine API的 Python 包。目标是使用 Sketch Engine 和NoSketch Engine为任何类型的编程工作开发一个灵活的脚手架。

设置

使用 Python 3.10 构建。（不再测试与 3.7 的兼容性。）

安装

• 获取Sketch Engine API 密钥（如果使用他们的服务器）

使用 pip 安装 SGEX：

• pip install sgex

或手动：

• 克隆这个仓库
• 安装依赖：
  • 当前版本pip install -r requirements.txt
  • 必需的pip install requests pyyaml
  • 可选的pip install keyring pandas openpyxl lxml

API 凭据

要配置 SGEX，请运行以下代码或手动将示例配置文件复制到您的项目目录。

import sgex
sgex.Call(sgex.call_examples)

配置文件包含 API 凭据和服务器的其他设置。在调用服务器之前，请设置您的凭据：

• 如果服务器需要凭据，请添加用户名和 API 密钥
• API 密钥也可以通过keyring包 进行管理
  • 添加条目：keyring.set_password("<server>","<username>","<api_key>")
  • 在配置文件中，包括用户名，但保留 API 密钥为null

默认配置文件包括两个服务器：用于 Sketch Engine 和本地 NoSketch Engine 安装。根据需要添加更多。

进行 API 调用

要开始调用，请生成示例输入文件并执行作业：

import sgex

sgex.parse(sgex.call_examples, "examples.yml")
sgex.Call("examples.yml", loglevel="info")

SGEX 解析来自输入文件的调用，向服务器发出请求，并将结果存储在data/sgex.db. 接下来，制作您自己的输入文件并尝试其他功能。

选项

input包含 API 调用的 YAML/JSON 文件的字典或路径

output保存到 sqlite（默认sgex.db）或文件：json, csv, xlsx, xml,txt

dry_run( False)

skipTrue当 sqlite ( )中已存在相同参数的哈希时跳过调用

clear在调用之前删除现有数据（sqlite 或data/raw/）（False）

server从config.yml( "ske")中选择服务器

threads用于异步调用（None默认情况下，否则为整数 <= 32）

halt( True) 在 HTTP 响应错误时中止调用

loglevel( "warning") 输出到.sgex.log

保存结果

检索到的 API 数据存储在 .sqlite 数据库中data/。默认数据库是sgex.db; 提供其他文件名时会创建新数据库（始终使用.db扩展名）。

API 响应也可以使用等保存到data/raw/支持的文件类型（JSON、CSV、XLSX、TXT、XML）中output="csv"。这将覆盖预先存在的数据。

对输出格式的支持取决于调用类型：例如，view需要 JSON 并freqs接受所有文件类型。JSON 是唯一适用于所有呼叫类型的格式。NoSketch Engine 服务器可能与某些格式和调用类型不兼容（参见此比较）。

输入文件

SGEX 调用结构

一个或多个调用可以通过创建一个 SGEX 可读的输入文件来执行，该文件包含参数字典形式的 API 调用。

• 每个调用的键作为一个 id ( "call0")
• 呼叫类型（频率、一致性等）定义为"type"
• 每个调用都有一个 API 参数字典"call"
• 调用可以选择包含自定义元数据"meta"
• "keep"可用于仅保存部分响应数据（仅限 JSON）

下面的调用查询EcoLexicon 英语语料库中的词条“rock”，并通过几种文本类型检索频率。

YAML

YAML 文件保留 CQL 格式并且不需要额外的字符转义：

call0:
  type: freqs
  meta:
    category1: tag1
  call:
    q:
    - alemma,"rock"
    corpname: preloaded/ecolexicon_en
    freq_sort: freq
    fcrit:
    - doc.domains 0
    - doc.genre 0
    - doc.editor 0

JSON

JSON 需要一致地使用双引号和转义字符：

• 内部双引号转义"alemma,\"rock\""，"aword,\"it's\""
• 特殊字符的双重转义："atag,1:\"N.*\" [word=\",|\\(\"]

{ "call0": {
    "type": "freqs",
    "meta": {
      "category1": "tag1"
    },
    "call":{
      "q": [
        "alemma,\"rock\""
      ],
      "corpname": "preloaded/ecolexicon_en",
      "freq_sort": "freq",
      "fcrit": [
        "doc.domains 0",
        "doc.genre 0",
        "doc.editor 0"]}}}

特征

回收参数

除非在每次调用中明确定义，否则参数将被重用。例如，下面的作业包含三个类似的调用。不是为每个参数写出每个参数，而是只完成第一次调用。后续调用仅包含要定义的新参数。

参数通过相同类型的调用顺序传递。如果type出现在新呼叫中，则不会重用任何内容。当参数是字典的一部分时，其项目将单独传递。字符串和其他数据类型只是被替换了。

call0:
  type: freqs
  call:
    q:
    - alemma,"rock"
    corpname: preloaded/ecolexicon_en
    freq_sort: freq
    fcrit:
    - doc.domains 0

call1:
  call:
    q:
    - alemma,"stone"

call2:
  call:
    q:
    - alemma,"pebble"

跳过重复

如果skip=True，当已经对 sqlite 数据库进行了相同的调用时，将不会重复调用。使用调用字典的散列来识别重复。如果内容"call"完全改变（甚至是一个字符），它们被认为是唯一的调用。作为 Python 字典，调用参数的顺序无关紧要。如果skip=False，则在新调用具有相同哈希时替换现有数据。元数据不影响散列或呼叫跳过。

异步调用

对于本地服务器，异步调用可以显着提高性能。asynchronous: True通过在 中添加服务器的详细信息来启用它config.yml。默认情况下，线程数会根据可用 CPU 的数量进行调整（请参阅max_workersconcurrent.futures ）。

丢弃不需要的 JSON 数据keep

SGEX 默认保存每个 API 调用的整个响应。相反，keep可用于指定要保存的 JSON 数据。例如，如果keep="concsize"为freqs调用设置了 ，则仅保留绝对频率，而丢弃其余响应。keep仅适用于顶级项目，不适用于嵌套数据。

服务器等待时间

服务器可能需要在呼叫之间等待。SGEX 使用其合理使用政策指南管理等待 Sketch Engine 服务器。如果自定义服务器需要等待，可以通过wait在配置文件中添加一个条目来启用，如下所示：

ske:         # server name
  wait:      # wait dictionary (measured in seconds)
  0: 1       # wait = 0 for 1 call
  2: 99      # wait = 2 for 2-99 calls
  5: 899     # wait = 5 for 100-899 calls
  45: null   # wait = 45 for 900 or more calls

笔记

处理不同的呼叫类型

每种调用类型freqs（频率）、view（索引）、wsketch（单词草图）等都有自己的参数和要求：参数在调用类型之间不可互换，但确实有相似之处。

请求过多

Sketch Engine 将阻止其 FUP 之外的 API 活动。在学习 API 的同时，有选择地、缓慢地测试调用，避免重复的相同调用。

API 使用情况

要了解有关 API 的更多信息，在使用 Sketch Engine 界面时检查网络活动会很有帮助。重要的是，Sketch Engine 有一些内部 API 方法，如果复制粘贴到 SGEX 调用中，这些方法将不起作用。

双重检查精度

在严重依赖 API 之前，最好练习在 Web 浏览器中和通过 API 尝试相同的查询，以确保结果相同。

保存和转换输入文件

parse()读取输入文件，但它也可以保存调用字典并使用dest="<filepath>".

日志记录和错误处理

• 一个糟糕的响应会立即停止工作，如果halt=True
• 使用 sqlite 时保存错误信息
• summary()Call从对象中获取作业详细信息

日志记录级别打印以下信息：

• critical- 没有什么
• error- 待定
• warning- 每个 API/响应错误及其调用 ID
• info- 进度和工作总结
• debug- 一切

关于

SGEX 的开发是为了满足格拉纳达大学（西班牙）笔译和口译系的研究需求。有关相关项目，请参阅LexiCon 研究小组。

该名称指的是草图语法，它们是 Sketch Engine 中的一系列广义语料库查询（参见他们的参考书目）。

欢迎提出问题、建议和支持。

引文

如果您使用 SGEX，请注明。