完善README、代码、workflows

- 完善README说明 - 完善代码注释 - 完善代码格式 - 完善插件log日志 - 完善插件说明 - 自动发布资产 - 自动生成发布说明 - 使得 GitHub Actions 工作流中的时间戳反映的是 UTC+8 时区 - 自动更新 tag_name 和 release_name
DoiiarX · Jan 4, 2024 · 0a7e3bd · 0a7e3bd
1 parent 4eb15f7
commit 0a7e3bd
Show file tree

Hide file tree

Showing 3 changed files with 177 additions and 14 deletions.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,61 @@
+name: Release Workflow
+
+on:
+  push:
+    branches: 
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    outputs:
+      timestamp: ${{ steps.get-timestamp.outputs.time }}
+    steps:
+    - name: Get build timestamp
+      id: get-timestamp
+      run: |
+        echo "time=$(TZ="Asia/Shanghai" /bin/date "+%Y-%m-%d-%H%M")" >> $GITHUB_OUTPUT
+
+    - name: Generate environmental variables
+      id: generate_env_vars
+      run: |
+        echo "tag_name=nlcisbn-${{ steps.get-timestamp.outputs.time }}" >> $GITHUB_OUTPUT
+        echo "release_name=NLCISBN Plugin Release ${{ steps.get-timestamp.outputs.time }}" >> $GITHUB_OUTPUT
+
+    - uses: actions/checkout@v2
+
+    # 创建ZIP压缩包
+    - name: Create ZIP Archive
+      run: |
+        zip NLCISBNPlugin.zip *.py README.md LICENSE
+
+    # 创建发布说明
+    - name: Generate Release Notes
+      id: generate_notes
+      run: |
+        RELEASE_NOTES=$(git log --format='%h %s' --reverse $(git describe --tags --abbrev=0 @^)..@)
+        echo "RELEASE_NOTES=$RELEASE_NOTES" >> $GITHUB_ENV
+  
+    # 创建发布
+    - name: Create Release
+      id: create_release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ steps.generate_env_vars.outputs.tag_name }}
+        release_name: ${{ steps.generate_env_vars.outputs.release_name }}
+        body: ${{ env.RELEASE_NOTES }}
+        draft: false
+        prerelease: true
+
+    # 上传ZIP文件作为发布资产
+    - name: Upload Release Asset
+      uses: actions/upload-release-asset@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        upload_url: ${{ steps.create_release.outputs.upload_url }}
+        asset_path: ./NLCISBNPlugin.zip
+        asset_name: NLCISBNPlugin.zip
+        asset_content_type: application/zip
diff --git a/README.md b/README.md
@@ -1,2 +1,93 @@
-# NLCISBNPlugin
-基于中国国家图书馆ISBN检索的calibre的source/metadata插件
+<p align="center">
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/stargazers" target="_blank"><img src="https://img.shields.io/github/stars/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/network/members" target="_blank"><img src="https://img.shields.io/github/forks/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/issues" target="_blank"><img src="https://img.shields.io/github/issues/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/issues?q=is%3Aissue+is%3Aclosed" target="_blank"><img src="https://img.shields.io/github/issues-closed/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/pulls" target="_blank"><img src="https://img.shields.io/github/issues-pr/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/pulls?q=is%3Apr+is%3Aclosed" target="_blank"><img src="https://img.shields.io/github/issues-pr-closed/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin" target="_blank"><img src="https://img.shields.io/github/last-commit/DoiiarX/NLCISBNPlugin.svg"></a>
+</p>
+<p align="center">
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin" target="_blank"><img src="https://visitor-badge.glitch.me/badge?page_id=d2-projects.d2-admin"></a>
+	<a href="https://github.com/DoiiarX/NLCISBNPlugin/releases" target="_blank"><img src="https://img.shields.io/github/release/DoiiarX/NLCISBNPlugin.svg"></a>
+	<a href="https://deepscan.io/dashboard#view=project&tid=22929&pid=26210&bid=830826"><img src="https://deepscan.io/api/teams/22929/projects/26210/branches/830826/badge/grade.svg" alt="DeepScan grade"></a>
+</p>
+
+# 中国国家图书馆ISBN Calibre Metadata 源插件
+
+该项目是一个用于 [Calibre](https://calibre-ebook.com/) 电子书管理软件的元数据源插件，旨在从[中国国家图书馆](http://opac.nlc.cn/F)获取图书信息，特别是基于ISBN。此插件允许用户轻松地将图书信息添加到其Calibre库中，包括书名、作者、出版日期等重要信息。
+
+## 功能特点
+
+- **自动元数据检索**：通过ISBN，自动从中国国家图书馆获取图书元数据。
+
+## 返回结果示例
+![image](https://github.com/DoiiarX/NLCISBNPlugin/assets/25550075/e6906459-0457-4c8c-a872-d7eda2d8beff)
+
+**返回项目包括：**
+- 书名
+- 标签
+- 作者
+- 简介
+- 出版社
+
+其中，标签由**分类**、**图书馆分类号**、**出版年份**组成
+
+## 待办事项
+
+以下是我们计划在未来添加到插件中的功能：
+
+- [ ] **更多定制选项**：增加用户可自定义的选项，以提供更多灵活性。
+- [ ] **更好的标题处理**：更好的标题处理。
+- [ ] **模糊搜索**：根据书名模糊搜索。根据isbn搜索isbn相同的多本书籍。
+
+## 安装
+
+1. 在 [Calibre官方网站](https://calibre-ebook.com/) 上下载并安装Calibre。
+
+2. 下载最新版本的 `NLCISBNPlugin` 插件文件。
+
+3. 打开Calibre软件，点击 "首选项" > "插件"。
+
+4. 在插件界面中，点击 "加载插件从文件中" 按钮，选择之前下载的插件zip文件。
+
+5. 安装完成后，启用该插件。
+
+## 使用
+
+1. 打开Calibre软件。
+
+2. 选择您想要更新元数据的电子书。
+
+3. 右键单击所选电子书，然后选择 "编辑元数据"。
+
+4. 在 "元数据编辑器" 窗口中，点击 "下载元数据"。
+
+5. 插件将自动从中国国家图书馆检索并填充图书信息。
+
+6. 确认信息无误后，点击 "确定" 保存更新的元数据。
+
+## 可能遇到的麻烦
+1. [无法安装插件。报错 It does not contain a top-level init.py file](https://github.com/DoiiarX/NLCISBNPlugin/issues/1)
+2. [当单一isbn对应多本书籍时，无法下载元数据](https://github.com/DoiiarX/NLCISBNPlugin/issues/4)
+## 贡献
+
+如果您发现任何问题或想要改进这个插件，欢迎贡献您的代码。请按照以下步骤进行：
+
+1. Fork 该仓库。
+
+2. 创建一个新的分支，以进行您的改进。
+
+3. 提交您的更改并创建一个拉取请求（Pull Request）。
+
+4. 我们将会审查您的代码并与您合作以将改进合并到主分支。
+
+## 许可证
+
+这个项目基于 [Apache 许可证 2.0](LICENSE) 开源，因此您可以自由使用、修改和分发它。
+
+---
+
+感谢您对中国国家图书馆ISBN Calibre Metadata 源插件的兴趣和支持！如果您有任何问题或建议，欢迎在 GitHub 上的问题部分提出。
+## Star 历史
+[![Stargazers over time](https://starchart.cc/DoiiarX/NLCISBNPlugin.svg)](https://starchart.cc/DoiiarX/NLCISBNPlugin)
diff --git a/__init__.py b/__init__.py
@@ -25,6 +25,8 @@
 def get_dynamic_url(log):
     '''
     从基础页面获取动态URL。
+    :param log: 日志记录器。
+    :return: 动态URL或None（获取失败时）。
     '''
     try:
         response = urllib.request.urlopen(urllib.request.Request(BASE_URL, headers=HEADERS), timeout=10)
@@ -40,9 +42,12 @@ def get_dynamic_url(log):
         log(f"获取动态URL时出错: {e}")
         return None
 
-def isbn2meta(isbn,log):
+def isbn2meta(isbn, log):
     '''
     将ISBN转换为元数据。
+    :param isbn: ISBN号码，作为字符串。
+    :param log: 日志记录器。
+    :return: 解析后的元数据或None（获取失败时）。
     '''
     if not isinstance(isbn, str):
         log("ISBN必须是字符串")
@@ -67,7 +72,7 @@ def isbn2meta(isbn,log):
         response = urllib.request.urlopen(urllib.request.Request(search_url, headers=HEADERS), timeout=10)
         response_text = response.read().decode('utf-8')
         soup = BeautifulSoup(response_text, "html.parser")
-        return parse_metadata(soup, isbn,log)
+        return parse_metadata(soup, isbn, log)
     except Exception as e:
         log(f"获取元数据时出错: {e}")
         return None
@@ -77,7 +82,8 @@ def parse_metadata(soup, isbn, log):
     从BeautifulSoup对象中解析元数据。
     :param soup: BeautifulSoup对象。
     :param isbn: ISBN号码，作为字符串。
-    :return: 解析后的元数据。
+    :param log: 日志记录器。
+    :return: 解析后的元数据或None（解析失败时）。
     '''
     data = {}
     prev_td1 = ''
@@ -106,7 +112,7 @@ def parse_metadata(soup, isbn, log):
             prev_td1 = td1.strip()
             prev_td2 = td2.strip()
 
-    # Use a regular expression to extract the 'pubdate' in [2019] format from '出版项'
+    # 从'出版项'中使用正则表达式提取格式为[2019]的'pubdate'
     pubdate_match = re.search(r',\s*(\d{4})', data.get("出版项", ""))
     pubdate = pubdate_match.group(1) if pubdate_match else ""
 
@@ -132,6 +138,13 @@ def parse_metadata(soup, isbn, log):
     return to_metadata(metadata, False, log)
 
 def to_metadata(book, add_translator_to_author, log):
+    '''
+    将书籍信息转换为元数据对象。
+    :param book: 书籍信息字典。
+    :param add_translator_to_author: 是否将翻译者添加到作者列表中。
+    :param log: 日志记录器。
+    :return: 元数据对象。
+    '''
     if book:
         authors = (book['authors'] + book['translators']
                    ) if add_translator_to_author and book.get('translators', None) else book['authors']
@@ -148,22 +161,20 @@ def to_metadata(book, add_translator_to_author, log):
                 elif re.compile('^\\d{4}-\\d+-\\d+$').match(pubdate):
                     mi.pubdate = datetime.strptime(pubdate, '%Y-%m-%d')
             except:
-                log.error('Failed to parse pubdate %r' % pubdate)
+                log.error('解析出版日期失败 %r' % pubdate)
         mi.comments = book['comments']
         mi.tags = book.get('tags', [])
-        # mi.rating = book['rating']
         mi.isbn = book.get('isbn', '')
-        # mi.series = book.get('series', [])
         mi.language = 'zh_CN'
         return mi
 
 class NLCISBNPlugin(Source):
-    name = 'National Library of China ISBN Plugin'
-    description = 'A Calibre plugin to fetch metadata from the National Library of China using ISBN.'
+    name = '国家图书馆ISBN插件'
+    description = '使用ISBN从中国国家图书馆获取元数据的Calibre插件。'
     supported_platforms = ['windows', 'osx', 'linux']
     version = (1, 0, 0)
     author = 'Doiiars'
-    capabilities = frozenset(['tags', 'identify','comments', 'pubdate'])
+    capabilities = frozenset(['tags', 'identify', 'comments', 'pubdate'])
 
     def get_book_url(self, identifiers):
         return None
@@ -173,8 +184,8 @@ def identify(self, log, result_queue, abort, title=None, authors=None, identifie
         if not isbn:
             return
 
-        metadata = isbn2meta(isbn,log)
-        log('Downloading metadata:', metadata)
+        metadata = isbn2meta(isbn, log)
+        log('下载元数据:', metadata)
         if metadata:
             result_queue.put(metadata)