rispy - Python的RIS文件解析器/编写器

RIS参考文献文件的Python 3.8+ 读写器。

发音 - rispee - 类似于 "crispy"，但没有 c。

用法

解析

>>> import rispy
>>> filepath = 'tests/data/example_full.ris'
>>> with open(filepath, 'r') as bibliography_file:
...     entries = rispy.load(bibliography_file)
...     for entry in entries:
...         print(entry['id'])
...         print(entry['first_authors'])
12345
['Marx, Karl', 'Lindgren, Astrid']
12345
['Marxus, Karlus', 'Lindgren, Astrid']

也可以使用文件路径来读取RIS文件。如果在 load 中未指定编码，则将使用默认的系统编码。

>>> from pathlib import Path
>>> import rispy
>>> p = Path('tests', 'data', 'example_utf_chars.ris')
>>> entries = rispy.load(p, encoding='utf-8')
>>> for entry in entries:
...     print(entry['authors'][0])
Dobrokhotova, Yu E.

编写

>>> import rispy
>>> entries = [
... {'type_of_reference': 'JOUR',
...  'id': '42',
...  'primary_title': 'The title of the reference',
...  'first_authors': ['Marxus, Karlus', 'Lindgren, Astrid']
...  },{
... 'type_of_reference': 'JOUR',
...  'id': '43',
...  'primary_title': 'Reference 43',
...  'abstract': 'Lorem ipsum'
...  }]
>>> filepath = 'export.ris'
>>> with open(filepath, 'w') as bibliography_file:
...     rispy.dump(entries, bibliography_file)

示例RIS条目

   1.
   TY  - JOUR
   ID  - 12345
   T1  - Title of reference
   A1  - Marx, Karl
   A1  - Lindgren, Astrid
   A2  - Glattauer, Daniel
   Y1  - 2014//
   N2  - BACKGROUND: Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.  RESULTS: Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. CONCLUSIONS: Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium.
   KW  - Pippi
   KW  - Nordwind
   KW  - Piraten
   JF  - Lorem
   JA  - lorem
   VL  - 9
   IS  - 3
   SP  - e0815
   CY  - United States
   PB  - Fun Factory
   PB  - Fun Factory USA
   SN  - 1932-6208
   M1  - 1008150341
   L2  - http://example.com
   ER  -

TAG_KEY_MAPPING

大多数字段包含字符串值，但一些如first_authors (A1) 被解析为列表。默认映射是从网络上的规范创建的，但据我们所知，没有单一来源的RIS真相，因此可能需要根据特定的导出系统进行修改

• 维基百科
• ResearcherId
• Refman
• Refman (RIS格式)
• Zotero

完整ListType标签列表

>>> from rispy import LIST_TYPE_TAGS
>>> print(LIST_TYPE_TAGS)
['A1', 'A2', 'A3', 'A4', 'AU', 'KW', 'N1', 'UR']

完整默认映射

>>> from rispy import TAG_KEY_MAPPING
>>> from pprint import pprint
>>> pprint(TAG_KEY_MAPPING)
{'A1': 'first_authors',
 'A2': 'secondary_authors',
 'A3': 'tertiary_authors',
 'A4': 'subsidiary_authors',
 'AB': 'abstract',
 'AD': 'author_address',
 'AN': 'accession_number',
 'AU': 'authors',
 'C1': 'custom1',
 'C2': 'custom2',
 'C3': 'custom3',
 'C4': 'custom4',
 'C5': 'custom5',
 'C6': 'custom6',
 'C7': 'custom7',
 'C8': 'custom8',
 'CA': 'caption',
 'CN': 'call_number',
 'CY': 'place_published',
 'DA': 'date',
 'DB': 'name_of_database',
 'DO': 'doi',
 'DP': 'database_provider',
 'EP': 'end_page',
 'ER': 'end_of_reference',
 'ET': 'edition',
 'ID': 'id',
 'IS': 'number',
 'J2': 'alternate_title1',
 'JA': 'alternate_title2',
 'JF': 'alternate_title3',
 'JO': 'journal_name',
 'KW': 'keywords',
 'L1': 'file_attachments1',
 'L2': 'file_attachments2',
 'L4': 'figure',
 'LA': 'language',
 'LB': 'label',
 'M1': 'note',
 'M3': 'type_of_work',
 'N1': 'notes',
 'N2': 'notes_abstract',
 'NV': 'number_of_volumes',
 'OP': 'original_publication',
 'PB': 'publisher',
 'PY': 'year',
 'RI': 'reviewed_item',
 'RN': 'research_notes',
 'RP': 'reprint_edition',
 'SE': 'section',
 'SN': 'issn',
 'SP': 'start_page',
 'ST': 'short_title',
 'T1': 'primary_title',
 'T2': 'secondary_title',
 'T3': 'tertiary_title',
 'TA': 'translated_author',
 'TI': 'title',
 'TT': 'translated_title',
 'TY': 'type_of_reference',
 'UK': 'unknown_tag',
 'UR': 'urls',
 'VL': 'volume',
 'Y1': 'publication_year',
 'Y2': 'access_date'}

覆盖键映射

解析器使用一个 TAG_KEY_MAPPING，可以通过调用带有 mapping 参数的 rispy.load() 来覆盖。

>>> from copy import deepcopy
>>> import rispy
>>> from pprint import pprint

>>> filepath = 'tests/data/example_full.ris'
>>> mapping = deepcopy(rispy.TAG_KEY_MAPPING)
>>> mapping["SP"] = "pages_this_is_my_fun"
>>> with open(filepath, 'r') as bibliography_file:
...     entries = rispy.load(bibliography_file, mapping=mapping)
...     pprint(sorted(entries[0].keys()))
['alternate_title2',
 'alternate_title3',
 'file_attachments2',
 'first_authors',
 'id',
 'issn',
 'keywords',
 'note',
 'notes_abstract',
 'number',
 'pages_this_is_my_fun',
 'place_published',
 'primary_title',
 'publication_year',
 'publisher',
 'secondary_authors',
 'type_of_reference',
 'urls',
 'volume']

可以通过传递列表到 list_tags 参数以相同的方式自定义列表标签。

更改rispy行为

有几种标志可以传递给 rispy.load() 和 rispy.dump()，以改变 rispy 处理标签的方式。例如，将 skip_unknown_tags 设置为 True 将导致 rispy 不读取或写入不在标签映射中的标签。更多内容可以在每个类的文档字符串中找到。如果需要更多自定义，可以创建自定义实现（见下一节）。

使用自定义实现

并非所有 RIS 文件都遵循相同的格式指南。存在一个用于创建自定义实现以读取和写入此类文件的接口。实现包含用于处理 RIS 文件的方法和参数，并应传递给 rispy.load() 或 rispy.dump()。

自定义实现

创建自定义实现涉及创建一个继承基类的类，并重写必要的变量和方法。也可以继承现有的解析器。如果只需要进行少量更改，则继承现有类是有益的。以下部分记录了可以重写的内容，以及一些示例。

解析

自定义解析器可以继承 RisParser（默认解析器）或 BaseParser。创建新解析器时可以重写各种参数和方法。这些在 BaseParser 的文档字符串中有记录。

示例

class WokParser(BaseParser):
      """Subclass of Base for reading Wok RIS files."""

      START_TAG = "PT"
      IGNORE = ["FN", "VR", "EF"]
      PATTERN = r"^[A-Z][A-Z0-9] |^ER\s?|^EF\s?"
      DEFAULT_MAPPING = WOK_TAG_KEY_MAPPING
      DEFAULT_LIST_TAGS = WOK_LIST_TYPE_TAGS

      def get_content(self, line):
         return line[2:].strip()

      def is_header(self, line):
         return True

编写

写入与解析非常相似。自定义写入类可以继承 BaseWriter 或其子类之一，如 RisWriter。

示例

class RisWriter(BaseWriter):
      """Subclass of BaseWriter for writing RIS files."""

      START_TAG = "TY"
      PATTERN = "{tag}  - {value}"
      DEFAULT_MAPPING = TAG_KEY_MAPPING
      DEFAULT_LIST_TAGS = LIST_TYPE_TAGS

      def set_header(self, count):
         return "{i}.".format(i=count)

其他功能

以下记录了 rispy 中包含的其他各种实用工具。

引用类型转换

有一个方法可以将常见的 RIS 引用类型转换为更易读的术语。它接受一个引用列表，并返回一个修改后的引用类型的列表副本。此转换的映射位于 config.py 中。

>>> from rispy.utils import convert_reference_types
>>> refs = [{"type_of_reference": "JOUR"}]
>>> print(convert_reference_types(refs))
[{'type_of_reference': 'Journal'}]

其他 RIS 类似格式的软件

某些 RIS 类似格式包含丰富的引用数据，例如列表和嵌套属性，这些 rispy 不支持。专注于这些格式的软件包括

• nbib - 解析 "PubMed" 或 "MEDLINE" 格式

开发者指南

提供的 Makefile 中包含常见的开发者命令；如果您没有安装 make，可以查看 make 命令并手动从命令行运行这些命令

# setup environment
python -m venv venv
source venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev]"

# check if code format changes are required
make lint

# reformat code
make format

# run tests
make test

当前已启用 Github Actions，以便在提交拉取请求时运行 lint 和 test。