diff --git a/.editorconfig b/.editorconfig index 5bf5b93..2f97bea 100644 --- a/.editorconfig +++ b/.editorconfig @@ -16,6 +16,7 @@ indent_style = tab [*.{md,rst}] trim_trailing_whitespace = false +indent_size = 3 [Makefile] indent_style = tab diff --git a/docs/additional/bug_reporting.md b/docs/additional/bug_reporting.md deleted file mode 100644 index 4f1fda9..0000000 --- a/docs/additional/bug_reporting.md +++ /dev/null @@ -1,10 +0,0 @@ -# 错误报告 - -如果您认为发现了错误，请先验证以下步骤： - -- 此 `issue` 是否已经提及并解决呢？ -- 这个错误是否发生在 `Scrapy` 中？如果是这样，问题可能出在你的代码上或者是 `Scrapy` 本身，而不是 `AyugeSpiderTools`； -- 您使用的是最新的版本吗？新版本一般包含已发现的错误修复，请升级到最新版本再次尝试； -- 如果您确定问题是由 `AyugeSpiderTools` 引起的，请随时提交新问题。提 `issue` 特别是 `Feature request` 或 `Bug report` 时，尽量按照 `issue` 模板来书写，可方便编写。非强制要求，能清晰地描述问题即可； - -注：并非存在以上的问题就不允许提 `issue`，它只是用于自我快速排查问题。 diff --git a/docs/additional/bug_reporting.rst b/docs/additional/bug_reporting.rst new file mode 100644 index 0000000..996225c --- /dev/null +++ b/docs/additional/bug_reporting.rst @@ -0,0 +1,15 @@ +.. _additional-bug_reporting: + +========== +错误报告 +========== + +如果您认为发现了错误，请先验证以下步骤： + +- 此 issue 是否已经提及并解决呢？ +- 这个错误是否发生在 Scrapy 中？如果是这样，问题可能出在你的代码上或者是 Scrapy 本身，而不是 AyugeSpiderTools； +- 您使用的是最新的版本吗？新版本一般包含已发现的错误修复，请升级到最新版本再次尝试； +- 如果您确定问题是由 AyugeSpiderTools 引起的，请随时提交新问题。提 issue 特别是 Feature request 或 \ + Bug report 时，尽量按照 issue 模板来书写，可方便编写。非强制要求，能清晰地描述问题即可； + +注：并非存在以上的问题就不允许提 issue，它只是用于自我快速排查问题。 diff --git a/docs/additional/contributing.md b/docs/additional/contributing.md deleted file mode 100644 index 21ad6bf..0000000 --- a/docs/additional/contributing.md +++ /dev/null @@ -1,75 +0,0 @@ -# 贡献 - -在编写和提交 `pull request` 前，建议先创建一个对应 `issues` 并在其中讨论相关详细信息。 - -## 前提准备 - -本指南假设您已拥有 `github` 账户，以及 `python3`，虚拟环境和 `git` 的安装配置。 -但不会限制你使用的工具，比如你可以使用 `virtualenv` 代替 `pyenv`。 - -1. [Fork](https://github.com/shengchenyang/AyugeSpiderTools/fork) AyugeSpiderTools - -2. Clone your forked repository - - ```shell - git clone https://github.com//AyugeSpiderTools - cd AyugeSpiderTools - ``` - -3. Create a virtual environment - - ```shell - pyenv virtualenv 3.9.20 venv - pyenv activate venv - pip install poetry - poetry install - pre-commit install - ``` - -4. Run a test - - ```shell - pytest tests/test_items.py - ``` - -## 开发工作流 - -本项目有两个分支，分别是 `master` 和 `feature`，`master` 为稳定分支，`feature` 分支活跃度较高，通常情况下新功能及 `bug` 修复等通过此分支测试后才会最终同步到 `master` 分支。所以，若您有 `pull request` 需求请推送至 `feature` 。若您不太了解 `pull request` 流程，我会在以下部分介绍，并给出参考文章。 - -注意：请完成以上前提准备，以下步骤皆在你的 `repo` 中操作。 - -1. Checkout the `feature` branch - - ```shell - git checkout feature - ``` - -2. Create and checkout a new branch - - > 通常情况下，都不推荐直接在当前分支下操作（会影响后续与原作者的同步操作），需要新建一个新分支，如果这个分支修复了某个 `issues`，那么新建分支的名称可以为 `issue#` - - 比如本项目中，有一个 [issue](https://github.com/shengchenyang/AyugeSpiderTools/issues/9) 标题为 `安装后运行报错：ModuleNotFoundError: No module named 'yaml'`，假设你的 `pull request` 修复了此问题，那么新建的分支名称就可以为 `issue#9`，或者为 `fix-ModuleNotFoundError-yaml`，这里只是给出建议，具体名称可自定义，通俗易懂即可。 - - ```shell - git checkout -b - ``` - - 以上两步也可以直接优化为一句命令 `git checkout -b feature` - -3. Make your changes - -4. Run tests - - 只测试与当前 `pull request` 相关的功能即可。由于执行全部测试的依赖过多，所以你可以自行本地打包测试通过即可，可不用补充相关测试代码。 - -5. Commit and push your work - - ```shell - git add . - git commit -m "Your commit message goes here" - git push -u origin - ``` - -6. [Create a pull request](https://help.github.com/articles/creating-a-pull-request/) - - 完成上一步后，在你 `fork` 的 `github` 项目页面上就会有创建 `pull request` 合并的按钮了， 记得要从你 `repo` 的 `` 分支 `pull request` 到我 `repo` 的 `feature` 中，到此已完成整个流程。 diff --git a/docs/additional/contributing.rst b/docs/additional/contributing.rst new file mode 100644 index 0000000..16f653a --- /dev/null +++ b/docs/additional/contributing.rst @@ -0,0 +1,98 @@ +.. _additional-contributing: + +====== +贡献 +====== + +在编写和提交 pull request 前，建议先创建一个对应 issues 并在其中讨论相关详细信息。 + +前提准备 +========== + +本指南假设您已拥有 github 账户，以及 python3，虚拟环境和 git 的安装配置。但不会限制你使用的工具，比如\ +你可以使用 virtualenv 代替 pyenv。 + +1. `Fork `_ AyugeSpiderTools + +2. Clone your forked repository + +.. code:: bash + + git clone https://github.com//AyugeSpiderTools + cd AyugeSpiderTools + +3. Create a virtual environment + +.. code:: bash + + pyenv virtualenv 3.9.20 venv + pyenv activate venv + pip install poetry + poetry install + pre-commit install + +4. Run a test + +.. code:: bash + + pytest tests/test_items.py + +开发工作流 +============ + +本项目有两个分支，分别是 master 和 feature，master 为稳定分支，feature 分支活跃度较高，通常情况下新\ +功能及 bug 修复等通过此分支测试后才会最终同步到 master 分支。所以，若您有 pull request 需求请推送至 \ +feature。若您不太了解 pull request 流程，我会在以下部分介绍，并给出参考文章。 + +注意：请完成以上前提准备，以下步骤皆在你的 repo 中操作。 + +1. Checkout the feature branch + +.. code:: bash + + git checkout feature + +2. Create and checkout a new branch + +.. note:: + + 通常情况下，都不推荐直接在当前分支下操作（会影响后续与原作者的同步操作），需要新建一个新分支，如果这个\ + 分支修复了某个 issues，那么新建分支的名称可以为 ``issue#``。比如本项目中，有一个 `issue`_ 标\ + 题为 ``安装后运行报错：ModuleNotFoundError: No module named 'yaml'``，假设你的 pull request \ + 修复了此问题，那么新建的分支名称就可以为 ``issue#9``，或者为 ``fix-ModuleNotFoundError-yaml``，\ + 这里只是给出建议，具体名称可自定义，通俗易懂即可。 + +.. code:: bash + + git checkout -b + +.. note:: + + 以上两步也可以直接优化为一句命令 git checkout -b feature + +3. Make your changes + +4. Run tests + +.. note:: + + 只测试与当前 pull request 相关的功能即可。由于执行全部测试的依赖过多，所以你可以自行本地打包测试通过\ + 即可，可不用补充相关测试代码。 + +5. Commit and push your work + +.. code:: bash + + git add . + git commit -m "Your commit message goes here" + git push -u origin + +6. `Create a pull request`_ + +.. warning:: + + 完成上一步后，在你 fork 的 github 项目页面上就会有创建 pull request 合并的按钮了， 记得要从你 repo \ + 的 ```` 分支 pull request 到我 repo 的 ``feature`` 中，到此已完成整个流程。 + +.. _issue: https://github.com/shengchenyang/AyugeSpiderTools/issues/9 +.. _Create a pull request: https://help.github.com/articles/creating-a-pull-request/ diff --git a/docs/additional/documentation.md b/docs/additional/documentation.md deleted file mode 100644 index 6ea05ce..0000000 --- a/docs/additional/documentation.md +++ /dev/null @@ -1,38 +0,0 @@ -# 文档 - -## 贡献方式 - -贡献的一种方式是完善此项目的文档。若您觉得文档中有需要改进的地方，可减少用户的理解成本，可通过以下方式反馈和 `pr`。 - -- 文档中每个页面顶部都有一个 `Edit on GitHub` 的链接。通过单击该链接，您可以创建包含更改的拉取请求。您需要一个 `Github` 帐户才能编辑页面。 -- 但我还是推荐按照 [Pull Requests](https://ayugespidertools.readthedocs.io/en/latest/additional/contributing.html) 的规则来修改和提交 `pr`。 - -同样地，在有完善文档的想法时请先提 `issue` 进行简要说明，主要是避免贡献浪费。 - -## 本地构建 - -在提交 `pr` 前，如何在本地查看修改后的效果呢？ - -1. Create a virtual environment - - ```shell - pyenv virtualenv 3.9.20 venv - pyenv activate venv - pip install poetry - poetry install - pre-commit install - ``` - -2. Make changes - - 在 `docs` 文件夹下修改您关心的部分。 - -3. Check the effect - ```shell - # 进入文档目录 - cd docs - - # 构建文档 - make html - ``` - 当构建完成时使用浏览器访问本项目中 `docs/_build/html/index.html` 即可查看修改后的效果。 diff --git a/docs/additional/documentation.rst b/docs/additional/documentation.rst new file mode 100644 index 0000000..49827a9 --- /dev/null +++ b/docs/additional/documentation.rst @@ -0,0 +1,54 @@ +.. _additional-documentation: + +===== +文档 +===== + +贡献方式 +========== + +贡献的一种方式是完善此项目的文档。若您觉得文档中有需要改进的地方，可减少用户的理解成本，可通过以下方式反馈\ +和 pr。 + +- 文档中每个页面顶部都有一个 ``Edit on GitHub`` 的链接。通过单击该链接，您可以创建包含更改的拉取请求。\ + 您需要一个 Github 帐户才能编辑页面。 +- 但我还是推荐按照 `Pull Requests`_ 的规则来修改和提交 pr。 + +.. warning:: + + 同样地，在有完善文档的想法时请先提 issue 进行简要说明，主要是避免贡献浪费。 + +本地构建 +========== + +在提交 pr 前，如何在本地查看修改后的效果呢？ + +1. Create a virtual environment + +.. code:: bash + + pyenv virtualenv 3.9.20 venv + pyenv activate venv + pip install poetry + poetry install + pre-commit install + + +2. Make changes + + 在 docs 文件夹下修改您关心的部分。 + +3. Check the effect +:: + + # 进入文档目录 + cd docs + + # 构建文档 + make html + +.. note:: + + 当构建完成时使用浏览器访问本项目中 ``docs/_build/html/index.html`` 即可查看修改后的效果。 + +.. _Pull Requests: https://ayugespidertools.readthedocs.io/en/latest/additional/contributing.html diff --git a/docs/additional/donating.md b/docs/additional/donating.md deleted file mode 100644 index 824765d..0000000 --- a/docs/additional/donating.md +++ /dev/null @@ -1,5 +0,0 @@ -# 微信赞赏 - -如果此项目对你有所帮助，可以选择打赏作者。 - -![微信赞赏码](https://github.com/shengchenyang/AyugeSpiderTools/raw/master/artwork/ayugespidertools-donating.jpg) diff --git a/docs/additional/donating.rst b/docs/additional/donating.rst new file mode 100644 index 0000000..4499fa6 --- /dev/null +++ b/docs/additional/donating.rst @@ -0,0 +1,11 @@ +.. _additional-donating: + +========= +微信赞赏 +========= + +如果此项目对你有所帮助，可以选择打赏作者。 + +.. image:: https://github.com/shengchenyang/AyugeSpiderTools/raw/master/artwork/ayugespidertools-donating.jpg + :alt: 微信赞赏码 + :width: 280 diff --git a/docs/additional/news.md b/docs/additional/news.md deleted file mode 100644 index ffd1e4a..0000000 --- a/docs/additional/news.md +++ /dev/null @@ -1,868 +0,0 @@ -# Release notes - -## AyugeSpiderTools 3.11.1 (Preview: TBD) - -此部分用于展示下一版本更新预览。 - -这是预发布版本，部分内容还处于待定状态，和最终正式版可能会有所不同（包括版本号），不建议在生产环境中使用，可自行打包来提前测试和体验。 - -打包参考教程请查看：[How-To-Build-Your-Own-Library](https://ayugespidertools.readthedocs.io/en/latest/diy/myself.html) - -当然也可以直接 `pip install git+https://github.com/shengchenyang/AyugeSpiderTools.git` 来安装预发布包。 - -## AyugeSpiderTools 3.11.0 - -### Deprecations - -- 移除对 `python3.8` 的支持。（[104a3fa](https://github.com/shengchenyang/AyugeSpiderTools/commit/104a3faa0877a72febd960d110d349ec9be22239)） -- 不再支持 `3.4` 及以下版本的 `mongodb` 的存储，（[2874aab](https://github.com/shengchenyang/AyugeSpiderTools/commit/2874aabadb5149cbc376aa78e78077555309084b)） - -### New features - -- `scrapy` 依赖更新为最新的 `2.12.0`。（[c3cf229](https://github.com/shengchenyang/AyugeSpiderTools/commit/c3cf229179e86fab4b7800bbd8dacfb408382f83)） -- 升级 `aiohttp` 依赖版本，解决升级后的兼容问题。（[9f6b68e](https://github.com/shengchenyang/AyugeSpiderTools/commit/9f6b68e77ffed45d6a2721678573b9fc9c63700e)，[62160a8](https://github.com/shengchenyang/AyugeSpiderTools/commit/62160a8e3b3eb355a429bbaedfc6d05e771368ab)） - -### Bug fixes - -- 解决 `psycopg` 相关依赖可能存在的冲突问题。（[a267c03](https://github.com/shengchenyang/AyugeSpiderTools/commit/a267c03aec55ed63a16926f90cf3d22e9ca20611)） - -### Code optimizations - -- 项目改为基于 `python 3.9` 开发，将涉及到的开发代码，`ci/cd`，测试等工具都改为 `3.9` 的特性。（[1e44c3f](https://github.com/shengchenyang/AyugeSpiderTools/commit/1e44c3f9f4fee29f305da929413b2aa1774e319b)） - -... ... - -## AyugeSpiderTools 3.10.1 (2024-10-19) - -### Deprecations - -- `mongodb` 场景统一存储相关的代码逻辑，且更新方式由之前 `update_many` 改为更正常的 `update_one` 的规则。（[8af915f](https://github.com/shengchenyang/AyugeSpiderTools/commit/8af915f65fa021a97b2eeaf9893167f511ce81b9)） - -注： -1. 虽然此版本为 `patch` 升级，但还请在虚拟环境中自行测试后再确认是否升级。 - -### New features - -- 无。 - -### Bug fixes - -- 解决 `macOS` 低版本的依赖兼容问题，优化依赖管理；解决 `mongodb` 存储在 `py3.11` 及以上场景时 `motor` 和 `pymongo` 的版本冲突造成的运行报错。（[a52755f](https://github.com/shengchenyang/AyugeSpiderTools/commit/a52755fc1e3b75728f09a04017b5907afa161624)） - -### Code optimizations - -- 整理代码风格。（[c080c3c](https://github.com/shengchenyang/AyugeSpiderTools/commit/c080c3ccf0e0796c728dc8e25562b2d90f79e72d), [2130092](https://github.com/shengchenyang/AyugeSpiderTools/commit/213009271ab66ce6ec846462db0db0afe0f068dd)） - -
- -## AyugeSpiderTools 3.10.0 (2024-10-01) - -### Deprecations - -- 将 `ayugespidertools.common.utils` 中 `ToolsForAyu` 修改为 `Tools`。（[73703a0](https://github.com/shengchenyang/AyugeSpiderTools/commit/73703a0cbf26e53813bb58db83e89fe55486a3e1)） -- 删除 `AiohttpFormRequest`，`AiohttpRequestArgs`，改为更简洁的 `AiohttpRequest` 且与 `aiohttp` 请求参数一致。（[1a7b100](https://github.com/shengchenyang/AyugeSpiderTools/commit/1a7b1000fe32abe249007533a65f891bd989aee9)） -- 整理并统一了 `ayugespidertools.common.multiplexing` 中 `ReuseOperation` 的函数参数名。（[1cad13a](https://github.com/shengchenyang/AyugeSpiderTools/commit/1cad13a94449dafa2f988fdd825fe282c2368dec)） - -注： -1. 以上变动比较影响用户的是 `AiohttpRequest` 的部分，为不兼容的重构部分。其它部分如果未在项目中使用则完全不影响库的正常运行。 -2. `AiohttpRequest` 新功能介绍文档请在 [ayugespidertools aiohttp](https://ayugespidertools.readthedocs.io/en/latest/topics/downloader-middleware.html#aiohttp) 中查看。 - -### New features - -- 升级 `ua` 数据为新版本，并且将其放入 `data` 中的 `browsers.json` 文件中，修改获取 `ua` 的方式。（[7d08f85](https://github.com/shengchenyang/AyugeSpiderTools/commit/7d08f853a7ca0ad9b860a8cc0e550c1b0b66e2f0)，[7a905a3](https://github.com/shengchenyang/AyugeSpiderTools/commit/7a905a3403801bb6ed0d453d6d87698eb0fd4ce4)） -- `oss` 上传文件资源场景支持列表类型，现在可通过 `mongodb` 存储场景将 `oss` 相关的 `AyuItem` 字段设置为列表类型，在 [demo_oss_super](https://github.com/shengchenyang/DemoSpider/blob/3.10.x/DemoSpider/spiders/demo_oss_super.py) 中查看示例。（[5946c54](https://github.com/shengchenyang/AyugeSpiderTools/commit/5946c54144f30503090d7f09ec6a88a0b66427f9), [e553152](https://github.com/shengchenyang/AyugeSpiderTools/commit/e553152773f9fe7aee1fdd118a9bb6327daf52ef)） -- 增加从 `VIT_DIR` 中 `.conf` 的 `ini` 配置解析方法 `get_cfg`，以方便配置统一存放管理和保护隐私，在 [demo_conf](https://github.com/shengchenyang/DemoSpider/blob/3.10.x/DemoSpider/spiders/demo_conf.py) 中查看示例。（[dd2485b](https://github.com/shengchenyang/AyugeSpiderTools/commit/dd2485bf28ddf4cc9a08b464f9baf7af39bf7587)） -- `aiohttp` 请求方式改为更人性化的，且与 `aiohttp` 请求参数保持一致的体验。以减少用户使用，理解和维护成本。（[1cad13a](https://github.com/shengchenyang/AyugeSpiderTools/commit/1cad13a94449dafa2f988fdd825fe282c2368dec)） - -注： -1. 其它存储场景的 `oss` 暂不支持列表形式，需自行实现，可自行按照示例添加自行打包。 - -### Bug fixes - -- 修复轨迹生成时关于抖动出错的问题。（[6ad6958](https://github.com/shengchenyang/AyugeSpiderTools/commit/6ad69583647fc3a4261f7a4ad4521c22580cc1ab)） -- 修复自使用的 `json` 解析方法的错误。（[a1d7aac](https://github.com/shengchenyang/AyugeSpiderTools/commit/a1d7aac2c826807c4838e4fbd31de6e637cab963)） - -注： -1. 这里的问题修复都是非框架主要功能，不影响 `scrapy` 的扩展功能使用。 - -### Code optimizations - -- 升级 `aiohttp` 依赖版本。（[5b448e5](https://github.com/shengchenyang/AyugeSpiderTools/commit/5b448e5991cd7e26b6702cdbd1bfcacc9b3ebcce)） -- `Makefile` 添加 `git` 相关的配置。（[6304b77](https://github.com/shengchenyang/AyugeSpiderTools/commit/6304b772b14daf0880b591e82ff182a66c77bd2e)） -- 解决文档 `Edit on GitHub` 出现的链接不对的问题。（[6a79f61](https://github.com/shengchenyang/AyugeSpiderTools/commit/6a79f617eb8d0e6834f673199d1ab08f68681df3)） -- 文档完善贡献部分。（[842300a](https://github.com/shengchenyang/AyugeSpiderTools/commit/842300ad38afd9169e70e2c839128d282a120508)） -- 优化 `get_items_except_keys` 方法，提升效率。（[d218144](https://github.com/shengchenyang/AyugeSpiderTools/commit/d2181444982995421f34c406e51ca0a053f9db1f)） - -
- -## AyugeSpiderTools 3.9.8 (2024-05-17) - -### Deprecations - -- 删除新建项目中 `pyproject.toml` 模板。（[bb0adf3](https://github.com/shengchenyang/AyugeSpiderTools/commit/bb0adf3083cfdbeace76ddb96c9ac35a6dc4f76d)） -- 删除新建项目中 `run.py`, `run.sh`, `README.md`, `requirements.txt` 模板的过度设计，不影响程序功能，按需自行添加。（[2a02faa](https://github.com/shengchenyang/AyugeSpiderTools/commit/2a02faa385069ac3a93194296c326dc31228c47b), [cb1393f](https://github.com/shengchenyang/AyugeSpiderTools/commit/cb1393f70f49e4f956adecc4be5126871a97c3df)） -- 更新 `spider` 模板内容，保证示例的稳定，为了通用性去除 `type hint`（请按需自行添加，`DemoSpider` 项目中有示例），并规避一些问题等。（[7dc45fd](https://github.com/shengchenyang/AyugeSpiderTools/commit/7dc45fda8af3270d713fc21d9feda3ca8d6ea739)） -- `EncryptOperation` 改名为 `Encrypt`，不影响库的使用。（[5e529ca](https://github.com/shengchenyang/AyugeSpiderTools/commit/5e529ca3eb625637894712a3972ba95a612c1526)） -- 删除库中未使用的 `get_files_from_path` 方法。（[e0d04d2](https://github.com/shengchenyang/AyugeSpiderTools/commit/e0d04d27a5b1a58eabe785485ed3402f0748c892)） - -补充： -此弃用和变动并不影响项目中的功能，只涉及一些自动生成的多余配置文件，运行文件等，这些为过度设计（不应替用户强行决定，且未做到完美适配）。 - -比较喜欢完整项目模版的开发者，则可选择通过 [LazyScraper](https://github.com/shengchenyang/LazyScraper) 项目来更方便地生成项目模版。 - -### New features - -- 同步更新 `scrapy` 依赖版本为 `2.11.2`。（[1618654](https://github.com/shengchenyang/AyugeSpiderTools/commit/1618654d4c2b9bd4032a52844e29abe17d2ee532)） - -### Bug fixes - -- 无。 - -### Code optimizations - -- `requests` 相关代码更换为 `urllib` 方式。（[f014030](https://github.com/shengchenyang/AyugeSpiderTools/commit/f01403012bcebce0e49c27840dff446aa7ef70fd)，[5cd28cc](https://github.com/shengchenyang/AyugeSpiderTools/commit/5cd28ccd6f38d1a37b2d57cf7bc1306c13173d1e)） -- `.conf` 模板格式整理，修改模板为英文，以解决中英文混编下的格式问题。（[f6f0e43](https://github.com/shengchenyang/AyugeSpiderTools/commit/f6f0e43bd5fcced5f724882606941fd033a56156)，[01d02a1](https://github.com/shengchenyang/AyugeSpiderTools/commit/01d02a19ee275fe80c52d696dee39500d35c9581)，[8ded926](https://github.com/shengchenyang/AyugeSpiderTools/commit/8ded926de0a04680ce91fd07bfde36d478bfda5e)） -- 添加 `.editorconfig` 配置。([d175c6e](https://github.com/shengchenyang/AyugeSpiderTools/commit/d175c6e0ddfaf3dcc105c62ada422c9f907388cb)) -- `poetry` 依赖更新。（[f783546](https://github.com/shengchenyang/AyugeSpiderTools/commit/f78354616c3e95d8e00238e8970fe332373a0273)） -- 文档更新。 -- `mongodb` 存储场景中 `pymongo` 依赖版本及应用场景的判定逻辑修改，由通过 `py` 版本来判定改为由 `pymongo` 依赖版本来判定。目前本库在 `py3.11` 及以上还是会安装 `^4.5.0` 版本的 `pymongo`，不影响旧项目功能。（[625ad1c](https://github.com/shengchenyang/AyugeSpiderTools/commit/625ad1cf3a16463aa77744b7ce4d46f94f056bab)） - -补充解释：若 `py 3.11` 及以上则使用 `^4.5.0` 版本的 `pymongo` 来支持 `3.6` 及以上版本的 `MongoDB` 来解决 `motor` 的异步存储问题；若 `py3.11` 以下则使用 `3.13.0` 的 `pymongo` 版本来与目前一致。 （[issue 11](https://github.com/shengchenyang/AyugeSpiderTools/issues/11)） - - -
- -## AyugeSpiderTools 3.9.7 (2024-03-08) - -### Deprecations - -- 无。 - -### New features - -- `oss` 场景添加是否保存完整链接的配置 `full_link_enable`，默认 `false`，不影响旧项目。([009ac20](https://github.com/shengchenyang/AyugeSpiderTools/commit/009ac20a4db55069c4b0cee5822834e42e21ba00)) -- `oss` 场景不再需要手动添加上传的字段是否为空的判断。([009ac20](https://github.com/shengchenyang/AyugeSpiderTools/commit/009ac20a4db55069c4b0cee5822834e42e21ba00)) - -### Bug fixes - -- 修复 `aiohttp` 场景下由于目标网站未遵守编码时可能会出现的编码问题。([d2772b5](https://github.com/shengchenyang/AyugeSpiderTools/commit/d2772b5960c972c4cc6ee6e6ce541fa00e34a7fb)) - -### Code optimizations - -- 添加 `aiohttp` 可支持的请求方式。([c7c247e](https://github.com/shengchenyang/AyugeSpiderTools/commit/c7c247e1badf411a149d9d6e1430230ec81e99a8)) -- 优化 `oss`, `file download` 场景的 `pipeline` 示例，减少复杂逻辑。([b0929d8](https://github.com/shengchenyang/AyugeSpiderTools/commit/b0929d8adba7c4d3ce2c7064a56656825d8802b7), [f0f1b2f](https://github.com/shengchenyang/AyugeSpiderTools/commit/f0f1b2f61e449e30812d7410e55652d4fcb42169)) -- 测试场景增加剔除无关代码块的规则。([3e0ce94](https://github.com/shengchenyang/AyugeSpiderTools/commit/3e0ce949340b8d27f95d86ecbcbd8bf04e85cccd)) -- 代码风格统一，补充缺失的 `type hint`，提升开发体验。 - -
- -## AyugeSpiderTools 3.9.6 (2024-02-18) - -### Deprecations - -- 无。 - -### New features - -- 无。 - -### Bug fixes - -- 修复 mysql 存储引擎 engine 参数未生效的问题。([1240e37](https://github.com/shengchenyang/AyugeSpiderTools/commit/1240e375dd4e1bc7c87ba876a3cc8faf34b8695f)) - -### Code optimizations - -- 更新 `aiohttp` 依赖库版本以解决破坏兼容性的问题，同步更新 `scrapy` 依赖版本。（[3f0dc5a](https://github.com/shengchenyang/AyugeSpiderTools/commit/3f0dc5ada3a9742eff54e8a77c03a4fb7906795d), [246c824](https://github.com/shengchenyang/AyugeSpiderTools/commit/246c824813b4ffdc844b0df26a9e944a467fb9ea)） -- 文档更新。 - -
- -## AyugeSpiderTools 3.9.5 (2024-01-30) - -### Deprecations - -- 无。 - -### New features - -- `mysql` 场景添加 `odku_enable` 配置来设置是否开启 `ON DUPLICATE KEY UPDATE` 功能。([25d71dd](https://github.com/shengchenyang/AyugeSpiderTools/commit/25d71ddb789c71f3f570f85576ff225aeaf58d7b)) -- 添加 `oss pipeline` 的示例，请在 `DemoSpider` 中 `demo_oss` 和 `demo_oss_sec` 查看具体使用方法。([issue 16](https://github.com/shengchenyang/AyugeSpiderTools/issues/16)) - -### Bug fixes - -- 解决文件下载不支持多字段下载的问题，请在 `DemoSpider` 中 `demo_file` 和 `demo_file_sec` 查看具体使用方法。([f836f02](https://github.com/shengchenyang/AyugeSpiderTools/commit/f836f02d3c15b57623851888c0451ea0bfe8c631), [f504c45](https://github.com/shengchenyang/AyugeSpiderTools/commit/f504c45b86f2e328e2a9bb9f61328b693a571b52)) -- 解决远程配置管理中缺失的 `mongodb:uri` 优先级设置。([51ea7da](https://github.com/shengchenyang/AyugeSpiderTools/commit/51ea7da83c81fe97ea5cd6a6500fdb7fc3fa233b)) - -### Code optimizations - -- `mq` 场景添加关闭链接处理。([ac54fd0](https://github.com/shengchenyang/AyugeSpiderTools/commit/ac54fd0a7611a8e63b46689da83718a9cebdb013)) -- 更新 `readthedocs` 中的教程指南，以方便快速上手。 -- 更新部分依赖库版本。 - -
- -## AyugeSpiderTools 3.9.4 (2024-01-10) - -### Deprecations - -- 无。 - -### New features - -- 添加 `elasticsearch` 支持，具体示例请在 `DemoSpider` 中 `demo_es` 和 `demo_es_async` 查看。([issue 15](https://github.com/shengchenyang/AyugeSpiderTools/issues/15), [c4d048e](https://github.com/shengchenyang/AyugeSpiderTools/commit/c4d048ee74c7246760e2ba91ef2844a5dd3540d7), [7651dd3](https://github.com/shengchenyang/AyugeSpiderTools/commit/7651dd32974f6362b9a2dbc8e7258a5528d98858)) - -### Bug fixes - -- 无。 - -### Code optimizations - -- mypy check。([`785e36a`](https://github.com/shengchenyang/AyugeSpiderTools/commit/785e36a5a85b141168ce24bfae9efe605ac05c36)) - -
- -## AyugeSpiderTools 3.9.3 (2023-12-30) - -### Deprecations - -- 无。 - -### New features - -- `无`。 - -### Bug fixes - -- 解决 `pip install ayugespidertools` 并执行简单场景时提示 `oracledb` 的依赖缺失问题。([`e363937`](https://github.com/shengchenyang/AyugeSpiderTools/commit/e363937f2de8cb5dd06938ca2eb470e1a5b08847)) - -注：出现此问题又是因为未重新新建环境来测试，且使用 `Pycharm ssh` 远程开发时不会自动索引环境依赖导致，所以未检视出项目依赖的问题。后续也会添加对 `DemoSpider` 场景的测试自动化来完善测试流程。 - -由于对用户体验影响较大，先修复此问题并发布。 - -### Code optimizations - -- 统一代码风格。([`ecb97e8`](https://github.com/shengchenyang/AyugeSpiderTools/commit/ecb97e803b36da5a5fd0bca14c98654a4b5d743b)) - -
- -## AyugeSpiderTools 3.9.2 (2023-12-28) - -### Deprecations - -- 无。 - -### New features - -- `mysql` 配置项支持自定义自动创建库表场景的 `engine` 和 `collate` 参数。([`e652666`](https://github.com/shengchenyang/AyugeSpiderTools/commit/e6526668b818ec0d442160e60a98b73bd45fb673)) - -### Bug fixes - -- 解决 `settings` 模板生成的 `LOG_FILE` 不是当前项目名的问题。([`93c19d6`](https://github.com/shengchenyang/AyugeSpiderTools/commit/93c19d6c6812a86f6ea1ece7618c98e0f8c63957)) - -### Code optimizations - -- 更新 `spider` 模板，模板中解析方式改为 `scrapy` 的形式，防止对开发者造成理解成本。([`91ad948`](https://github.com/shengchenyang/AyugeSpiderTools/commit/91ad948506495bee210a673cd08541329375d8c4)) -- 更新 `spider` 模板中的 `type hint`，优化了开发者使用体验。([`c2a0908`](https://github.com/shengchenyang/AyugeSpiderTools/commit/c2a09087f9b9fa1d20927d51f9e9f670c74d00f3)) -- 优化一些数据库连接处理和配置解析方法等。 - -
- -## AyugeSpiderTools 3.9.1 (2023-12-22) - -### Deprecations - -- 无。 - -### New features - -- 添加 `postgresql` 的 `asyncio` 的 `AsyncConnectionPool` 存储场景支持。([`341e768`](https://github.com/shengchenyang/AyugeSpiderTools/commit/341e7681931f796b5167696b948ea331e2b62dbb)) - -### Bug fixes - -- 解决 `asyncio` 协程场景下的 `spider` 的 `AyuItem` 写法风格不兼容的问题。([`66177e4`](https://github.com/shengchenyang/AyugeSpiderTools/commit/66177e402d0e9c15b559664bfc40c6de0e545735)) - -### Code optimizations - -- 更新 `spider` 模板示例。([`61e10b1`](https://github.com/shengchenyang/AyugeSpiderTools/commit/61e10b140e880c7b2348b35687c167b6fad99b99)) - -
- -## AyugeSpiderTools 3.9.0 (2023-12-18) - -### Deprecations - -- `AsyncMysqlPipeline` 改名为 `AyuAsyncMysqlPipeline`。 -- `AsyncMongoPipeline` 改名为 `AyuAsyncMongoPipeline`。 -- 删除 `oss` 的模块及依赖。 - -注：最新示例请在 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 中查看，以往旧版请切换对应分支查看。 - -### New features - -- 添加 `oracle` 的存储场景支持，目前有 `fty` 及 `twisted` 两种方式。 -- 添加 `mongodb:uri` 的配置方式。 - -### Bug fixes - -- 解决 `asyncio mysql` 协程场景下可能会出现的被垃圾回收而阻塞的问题。 -- 解决 `mysql` 或 `postgresql` 的错误处理场景下由于权限等问题造成的循环递归问题。 - -### Code optimizations - -- 优化 `.conf` 模板示例，配置更明确且更易管理。 -- `mypy check`. - -
- -## AyugeSpiderTools 3.8.0 (2023-12-03) - -### Deprecations - -- `MYSQL_ENGINE_ENABLED` 的配置项名改为 `DATABASE_ENGINE_ENABLED`，目前支持 `msyql` 和 `postgresql`。 -- 安装再添加 `database` 选项，可通过 `pip install ayugespidertools[database]` 安装所需的所有数据依赖及扩展。 - -**注意：此变更包含不兼容部分，需要着重注意的部分如下：** -- 删除了 `MYSQL_ENGINE_ENABLED` 配置项； -- 由于 `SQLAlchemy` 依赖升级到了 `2.0+` 新版本，与以往的去重使用有变化，具体请查看本库 `readthedocs` 文档。 - -### New features - -- 支持 `python3.12`。 -- 添加 `postgresql` 的存储场景支持，目前有 `fty` 及 `twisted` 两种方式。 -- `DATABASE_ENGINE_ENABLED` 的配置目前会激活对应场景中数据库的 `engine` 和 `engine_conn` 以供去重使用。 -- 将 `psycopg` 相关的数据库扩展依赖改为可选项，可通过 `pip install ayugespidertools[database]` 安装所需依赖。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 优化 `type hints`。 -- 更新生成脚本模板以匹配新版本，也可使用以往 `pandas` 去重方式。 -- 更明确的日志信息。 - -
- -## AyugeSpiderTools 3.7.0 (2023-11-23) - -### Deprecations - -- 获取 `nacos` 和 `consul` 中的配置时不再转小写，请按照 [readthedocs](https://ayugespidertools.readthedocs.io/en/latest/intro/examples.html) 示例填写。 -- 删除 `html2text` 相关依赖及代码，此场景更适合自行实现。 -- 安装不再包含非核心依赖，可通过 `pip install ayugespidertools[all]` 安装全部依赖。 -- 一些 `api`变动： - - | 更改前 | 更改后 | 受影响的部分 | 备注 | - | ---------------------------------------- | ------------------------------------------ | ------------------------------------------------------------ | ------------------------ | - | extract_html_to_md | 删除 | ayugespidertools.formatdata | | - | AliOssBase | 转移到 ayugespider.extras 中 | ayugespidertools.oss | | - | yidungap, imgoperation, verificationcode | 转移到 ayugespider.extras 中，并整理在一起 | ayugespidertools.imgoperation
ayugespidertools.verificationcode
ayugespidertools.common.yidungap | 在 extras 部分查看变化。 | - -- 以下是对 `extras` 相关模块所影响较大部分的介绍： - - | 更改前 | 更改后 | 受影响的部分 | 备注 | - | ---------------------- | ------------------------------ | --------------------------------- | ---- | - | YiDunGetGap.discern | CvnpilKit.discern_gap | ayugespidertools.common.yidungap | | - | Picture.identify_gap | CvnpilKit.identify_gap | ayugespidertools.imgoperation | | - | match_img_get_distance | CvnpilKit.match_gap | ayugespidertools.verificationcode | | - | get_normal_track | CvnpilKit.get_normal_track | ayugespidertools.verificationcode | | - | get_selenium_tracks | ToolsForAyu.get_selenium_track | ayugespidertools.verificationcode | | - -注意： - -- **此变更包含不兼容部分，如果你只使用其中 `scrapy` 扩展库部分，那么除了 `nacos`，`consul` 的 `yaml` 和 `hcl` 解析外对你无影响。** -- **再次提醒，使用时请做好依赖管理，以免不兼容部分对你的影响！** - -### New features - -- `mongo` 场景添加 `authMechanisem` 配置选项，为可选配置，默认为 `SCRAM-SHA-1`。 -- 将 `numpy`, `oss`, `pillow` 等非核心依赖改为可选项，可通过 `pip install ayugespidertools[all]` 安装所有依赖。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 优化 `aiohttp`, `cvnpil` 等测试用例，将图像相关功能整理并放入 `cvnpil` 模块中。 -- `ayuge version` 修改为从 `__version__` 获取信息的方式。 -- 更新模板，`mysql_engine` 的示例改为通过 `sqlalchemy` 的方式，减少依赖数且大部分场景运行效率更好。 -- 将可选装依赖的相关的功能代码统一放入 `extras` 中，更易管理。 - -
- -## AyugeSpiderTools 3.6.1 (2023-11-06) - -### New features - -- 无。 - -### Bug fixes - -- 解决 `mq` 推送场景时 `yield AyuItem` 时的错误，现可支持多种格式。 -- 解决 `VIT_DIR` 默认参数未存储至 `settings` 中的问题。 - -### Code optimizations - -- 文件下载场景添加 `FILES_STORE` 路径不存在时的自动创建处理。 -- `settings` 模板删除无关配置。 -- 项目添加 `question issues template`。 - -
- -## AyugeSpiderTools 3.6.0 (2023-10-31) - -### Deprecations - -- 一些 `api` 变动： - -| 更改前 | 更改后 | 受影响的部分 | 备注 | -| ------------------------------------------------------------ | ------------------------------------------------------------ | --------------------- | ---- | -| 删除 `LOGURU_CONFIG` 配置参数 | 现只需配置 `LOGURU_ENABLED` 即可 | `slog` 日志模块 | | -| 删除 `spider` 中 `settings_type` 参数 | 此为过度设计，若需要可自定义配置 | 项目配置信息 | | -| 删除 `spider` 中 `mysql_engine_enabled` 参数 | 转移到设置中，名称为 `MYSQL_ENGINE_ENABLED` | 配置模块，影响较大。 | | -| `AyuItem` 中 `_table` 参数类型修改
删除 `spider` 中 `custom_table_enum` 参数 | 修改为与普通字段一样的 `DataItem` 或 `str` 类型，删除 `demand_code` 字段。 | `spider`，`Item` 模块 | | -| 删除 `RECORD_LOG_TO_MYSQL` 配置参数 | 改为 `ayugespidertools.pipelines.AyuStatisticsMysqlPipeline` 方式调用。 | 配置模块 | | - -注意：**此变更包含不兼容内容，请修改不兼容部分并调试正常后再投入生产；本项目在有一些不兼容变更时，会发布 `Minor` 及以上的版本包，请做好依赖版本管理。** - -### New features - -- 无。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 设置 `VIT_DIR` 默认参数。 -- 去除冗余配置，统一配置风格。将一些过于复杂的模块拆分，便于管理。 - -
- -## AyugeSpiderTools 3.5.2 (2023-10-17) - -### New features - -- 添加从 `nacos` 中获取配置的方法，若 `.conf` 中同时存在 `consul` 和 `nacos` 配置则优先使用 `consul`；即优先级 `consul` > `nacos`。 - -### Bug fixes - -- 无 - -### Code optimizations - -- 删除 `.conf` 示例中的无用配置 `wxbot`。 -- 优化从本地 `.conf` 获取配置的逻辑，也提供更清晰明确的报错信息。 -- `tox` 重新添加了 `windows` 场景。 -- 更新 `CI` 工具版本。 - -
- -## AyugeSpiderTools 3.5.1 (2023-09-28) - -### Bug fixes - -- 修复在 `py 3.11` 及以上版本的 `mongo` 相关场景的报错。([issue 11](https://github.com/shengchenyang/AyugeSpiderTools/issues/11)) - -### Code optimizations - -- 优化 `AyuItem` 实现，增强可读性及用户输入体验，比如 `add_field` 增加 `IDE` 参数提示功能。 -- 更新文档中 `AyuItem` 的使用建议及对应测试。 -- 更新测试文件，比如 `test_crawl` 及 `spider` 相关方法。 - -
- -## AyugeSpiderTools 3.5.0 (2023-09-21) - -### Bug fixes - -- 无。 - -### Code optimizations - -- `scrapy` 依赖升级为 `2.11.0`。 -- 统一运行统计的方法，修改运行 `stats` 中有关时间的获取和计算方法。 -- 添加 `pre-commit` 工具和 `CI`，提升 `commit` 和 `pull request` 体验。 -- 更新 `readthedocs` 的新配置。 -- 优化 `test_crawl` 的测试方法。 - -
- -## AyugeSpiderTools 3.4.2 (2023-09-15) - -### Bug fixes - -- 修复 `crawl` 模板文件中 `TableEnum` 的导入问题。 -- 修改文档中 `kafka` 推送示例 `typo` 问题。 - -### Code optimizations - -- 优化文件下载本地的逻辑，处理当 `file_url` 不存在时的情况。 -- 优化 `items`，`typevar` 等模块的 `type hint`，并删除无用的类型内容。 -- 设置包源的优先级。 -- 增加测试用例。 -- 添加 `mypy` 工具。 - -
- -## AyugeSpiderTools 3.4.1 (2023-09-07) - -### Bug fixes - -- 解决 `Twisted` 版本更新到 `23.8.0` 不兼容的问题。([issue 10](https://github.com/shengchenyang/AyugeSpiderTools/issues/10)) - -### Code optimizations - -- `scrapy` 依赖版本更新为 `2.10.1`。 - -
- -## AyugeSpiderTools 3.4.0 (2023-08-10) - -### Deprecation removals - -- 无。 - -### Deprecations - -- 无。 - -### New features - -- 无。 - -### Bug fixes - -- `aiohttp` 超时参数由 `AIOHTTP_CONFIG` 中的 `timeout` 获取改为直接从 `DOWNLOAD_TIMEOUT` 中获取。解决在 `aiohttp` 超时参数值大于 `DOWNLOAD_TIMEOUT` 时，与程序整体超时设置冲突，考虑程序的整体性，而不去根据 `aiohttp` 的超时设置来更新项目的整体设置。 - -### Code optimizations - -- `aiohttp` 添加 `allow_redirects` 配置参数 ，优化对应文档示例。 -- 更新 `scrapy` 依赖版本为 `2.10.0`。 -- 解决部分 `typo` 及注解问题。 - -
- -## AyugeSpiderTools 3.3.3 (2023-08-03) - -### Deprecation removals - -- 无。 - -### Deprecations - -- 无。 - -### New features - -- 无。 - -### Bug fixes - -- 修复解析 `yaml` 格式数据依赖缺失的问题。（[issue 9](https://github.com/shengchenyang/AyugeSpiderTools/issues/9)） - -### Code optimizations - -- 本库中解决 `Mysql` 的 `Unknown column 'xx' in 'field list'` 部分代码变动，比如不再根据 `item` 字段是`crawl_time` 类型格式来给其默认字段格式 `DATE`，因为用户可能只是存储字段是这个名称，意义并不同，或者它存的是个时间戳等情况。这样需要考虑的问题太复杂了，且具有隐患，不如优先解决字段缺失问题，后续按需再手动调整表字段类型。 - -
- -## AyugeSpiderTools 3.3.2 (2023-07-26) - -### Deprecation removals - -- 无。 - -### Deprecations - -- 无。 - -### New features - -- 增加贝塞尔曲线生成轨迹的示例方法。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 将项目中有关文件的操作统一改为 `pathlib` 的方式。 -- 根据 `consul` 获取配置的方式添加缓存处理，不用每次运行都多次调用同样参数来获取配置。减少请求次数，提高运行效率。 -- 更新 `README.md` 内容，增加对应英文版本。 - -
- -## AyugeSpiderTools 3.3.1 (2023-06-29) - -### Deprecation removals - -- 无。 - -### Deprecations - -- 无。 - -### New features - -- 无。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 优化 `item` 使用体验，完善功能及对应文档内容，具体请查看 [readthedocs](https://ayugespidertools.readthedocs.io/en/latest/topics/items.html) `item` 部分。 - -
- -## AyugeSpiderTools 3.3.0 (2023-06-21) - -### Deprecation removals - -- 优化了 `Item` 体验，升级为 `AyuItem`，使用更方便，但注意与旧版本写法并不兼容： - - 删除了 `MysqlDataItem` 实现。 - - 删除了 `MongoDataItem` 实现。 - - 增加了 `AyuItem` 参数以方便开发和简化 `pipelines` 结构，新示例请查看 `DemoSpider` 项目或 `readthedocs` 文档对应内容。 - -### Deprecations - -- 无。 - -### New features - -- 添加文件下载的示例，具体内容及示例请查看 [readthedocs](https://ayugespidertools.readthedocs.io/en/latest/topics/pipelines.html#mq) 上对应内容，具体案例请查看 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 中的 `demo_file` 项目。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 升级依赖库中 `numpy` 和 `loguru` 版本，避免其漏洞警告提示。 -- 更新对应的模板生成示例，简化一些不常用的配置即注释等。 - -
- -## AyugeSpiderTools 3.2.0 (2023-06-07) - -### Deprecation removals - -- 去除数据表前缀和集合前缀的鸡肋功能： - - 删除了 `MYSQL_TABLE_PREFIX` 参数。 - - 删除了 `MONGODB_COLLECTION_PREFIX` 参数。 -- 删除其它的鸡肋功能： - - 移除 `runjs` 方便运行 `js` 方法的鸡肋封装。 - - 移除 `rpa` 管理自动化程序的方法。 -- 删除了使用 `requests` 作为 `scrapy` 请求库的功能，推荐使用本库中 `aiohttp` 的方式。 - -### Deprecations - -- 无。 - -### New features - -- 添加 `kafka` 推送的示例，具体内容及示例请查看 [readthedocs](https://ayugespidertools.readthedocs.io/en/latest/topics/pipelines.html#mq) 上对应内容，具体案例请查看 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 项目。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 增加 `RabbitMQ` 中 `heartbeat` 和 `socket_timeout` 参数可自定义的功能。 -- 整理依赖文件。 - -
- -## AyugeSpiderTools 3.1.0 (2023-05-30) - -### Deprecation removals - -- 无。 - -### Deprecations - -- 无。 - -### New features - -- 添加 `mq` 推送的示例，具体内容及示例请查看 [readthedocs](https://ayugespidertools.readthedocs.io/en/latest/topics/pipelines.html#mq) 上对应内容，具体案例请查看 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 项目。 - -### Bug fixes - -- 无。 - -### Code optimizations - -- 修复部分 `typo` 问题。 - -
- -## AyugeSpiderTools 3.0.1 (2023-05-17) - -这是一个 `major` 版本更新，含有 `bug` 修复、代码优化等。 - -### Deprecation removals - -- 删除 `ayugespidertools` 的 `cli` 名称 -> 改为 `ayuge` 来管理。 - -### Deprecations - -- 无。 - -### New features - -- 修改 `item` 实现方式，不再通过将字段都存入 `alldata` 中即可实现动态设置字段的功能，使用更清晰，且能更方便地使用 `ItemLoaders` 的功能，具体内容及示例请查看 [readthedocs](https://ayugespidertools.readthedocs.io/en/ayugespidertools-3.0.1/topics/items.html) 上对应内容，具体案例请查看 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 项目。 - -### Bug fixes - -- 修复不会创建表注释的问题。 - -### Code optimizations - -- 修改 `dict_keys_to_lower` 和 `dict_keys_to_upper` 的将字典 key 转为大写或小写的功能优化为嵌套字典中所有 key 都转为大写或小写。 -- 将模板中 `settings.py` 中的配置读取放入库中 `update_settings` 实现，简化 `settings.py` 文件内容。 -- 优化 `Makefile` 功能，简化清理 `__pycache__` 文件夹的功能。 -- 修改部分 `typo` 问题。 -- 更新 `readthedocs` 内容，更新测试文件。 - -
- -## AyugeSpiderTools 2.1.0 (2023-05-09) - -这是一个主要更改了 `scrapy` 依赖库为 `2.9.0` 版本，含有 `bug` 修复。 - -### Deprecation removals - -- `tox` 去除 `windows` 平台的测试场景。 - -### Deprecations - -- 下一大版本将删除 `ayugespidertools` 的 `cli` 名称 -> 改为 `ayuge` 来管理。 - -### New features - -- 本库依赖库 `scrapy` 版本升级为 `2.9.0`。 - -### Bug fixes - -- 修复使用 `ayuge` 及 `ayuge -h` 命令时，未显示当前库版本的问题。 - -### Code optimizations - -- 无。 - -
- -## AyugeSpiderTools 2.0.3 (2023-05-06) - -此版本为微小变动。 - -### Deprecation removals - -- 无 - -### Deprecations - -- 下一大版本将删除 `ayugespidertools` 的 `cli` 名称 -> 改为 `ayuge` 来管理。 - -### New features - -- 添加 `mongodb` 的 `asyncio` 的示例。 - -### Bug fixes - -- 无 - -### Code optimizations - -- `readthedocs` 的 `markdown` 解析由 `recommonmark` 改为 `myst-parser`，以支持更多的 `markdown` 语法。 - -
- -## AyugeSpiderTools 2.0.1 (2023-04-27) - -此版本为大版本更新，修改了项目结构以统一本库及与 `scrapy` 结合的代码风格，也有一些功能完善等。最新功能示例请在 [DemoSpider](https://github.com/shengchenyang/DemoSpider/) 或 [readthedocs](https://ayugespidertools.readthedocs.io/en/ayugespidertools-2.0.1/) 中查看。 - -### Deprecation removals - -- 一些 `api` 变动： - -| 更改前 | 更改后 | 备注 | -| ------------------------------------------------------------ | ------------------------------------------------------- | ----------- | -| from ayugespidertools.AyugeSpider import AyuSpider | from ayugespidertools.spiders import AyuSpider | | -| from ayugespidertools.AyuRequest import AioFormRequest | from ayugespidertools.request import AiohttpFormRequest | | -| from ayugespidertools.AyuRequest import AiohttpRequest | from ayugespidertools.request import AiohttpRequest | | -| from ayugespidertools.common.Utils import * | from ayugespidertools.common.utils import * | | -| from ayugespidertools.Items import * | from ayugespidertools.items import * | | -| from .common.DataEnum import TableEnum | from .items import TableEnum | | -| from ayugespidertools.AyugeCrawlSpider import AyuCrawlSpider | from ayugespidertools.spiders import AyuCrawlSpider | | -| ayugespidertools.Pipelines | ayugespidertools.pipelines | pipelines | -| ayugespidertools.Middlewares | ayugespidertools.middlewares | middlweares | - -- 一些参数配置变动： - -| 更改前 | 更改后 | 备注 | -| ----------- | ------ | --------------- | -| PROXY_URL | proxy | 代理 proxy 参数 | -| PROXY_INDEX | index | 代理配置等 | - -注：所有配置的 `key` 都统一改为小写 - -- 一些使用方法更改： - - 使用 `AiohttpRequest` 构造请求时，由之前的 `meta` 中的 `aiohttp_args` 配置参数，改为由 `args` 的新增参数取代，其参数类型同样为 `dict`，也可以为 `AiohttpRequestArgs` 类型，更容易输入。 - -### Deprecations - -- 下一大版本将删除 `ayugespidertools` 的 `cli` 名称 -> 改为 `ayuge` 来管理。 - -### New features - -- 丰富 `aiohttp` 请求场景，增加重试，代理，`ssl` 等功能。 - - -### Bug fixes - -- 无 - -### Code optimizations - -- 更新测试用例。 - -
- -## AyugeSpiderTools 1.1.9 (2023-04-20) - -这是一个维护版本，具有次要功能、错误修复和清理。 - -### Deprecation removals - -- 无 - -### Deprecations - -- 无 - -### New features - -- 增加 `ayuge startproject` 命令支持 `project_dir` 参数。 - - ```shell - # 这将在 project dir 目录下创建一个 Scrapy 项目。如果未指定 project dir，则 project dir 将与 myproject 相同。 - ayuge startproject myproject [project_dir] - ``` - -### Bug fixes - -- 修复模板中 `settings` 的 `CONSUL` 配置信息没有更新为 `v1.1.6` 版本推荐的使用方法的问题。([releases ayugespidertools-1.1.6](https://github.com/shengchenyang/AyugeSpiderTools/releases/tag/ayugespidertools-1.1.6)) -- 修复在 `startproject` 创建项目时生成的 `run.sh` 中的路径信息错误问题。 - -### Code optimizations - -- 添加测试用例。 -- 以后的版本发布说明都会在 [ayugespidertools readthedocs](https://ayugespidertools.readthedocs.io/en/latest/additional/news.html) 上展示。 diff --git a/docs/additional/news.rst b/docs/additional/news.rst new file mode 100644 index 0000000..e2a4a5f --- /dev/null +++ b/docs/additional/news.rst @@ -0,0 +1,1059 @@ +.. _additional-news: + +============= +Release notes +============= + +AyugeSpiderTools 3.11.1 (Preview: TBD) +====================================== + +此部分用于展示下一版本更新预览。 + +这是预发布版本，部分内容还处于待定状态，和最终正式版可能会有所不同（包括版本号），不建议在生产环境中使用，\ +可自行打包来提前测试和体验。 + +打包参考教程请查看：`How-To-Build-Your-Own-Library`_ + +.. _How-To-Build-Your-Own-Library: https://ayugespidertools.readthedocs.io/en/latest/diy/myself.html + +当然也可以直接 ``pip install git+https://github.com/shengchenyang/AyugeSpiderTools.git`` 来\ +安装预发布包。 + +... ... + +AyugeSpiderTools 3.11.0 (2024-11-29) +==================================== + +Deprecations +------------ + +- 移除对 python3.8 的支持。 + + (:commit:`104a3faa0877a72febd960d110d349ec9be22239`) +- 不再支持 3.4 及以下版本的 `mongodb` 的存储， + + (:commit:`2874aabadb5149cbc376aa78e78077555309084b`) + +New features +------------ + +- scrapy 依赖更新为最新的 2.12.0。 + + (:commit:`c3cf229179e86fab4b7800bbd8dacfb408382f83`) +- 升级 aiohttp 依赖版本，解决升级后的兼容问题。 + + (:commit:`9f6b68e77ffed45d6a2721678573b9fc9c63700e`) + + (:commit:`62160a8e3b3eb355a429bbaedfc6d05e771368ab`) + +Bug fixes +--------- + +- 解决 psycopg 相关依赖可能存在的冲突问题。 + + (:commit:`a267c03aec55ed63a16926f90cf3d22e9ca20611`) + +Code optimizations +------------------ + +- 项目改为基于 python 3.9 开发，将涉及到的开发代码，ci/cd，测试等工具都改为 3.9 的特性。 + + (:commit:`1e44c3f9f4fee29f305da929413b2aa1774e319b`) + +AyugeSpiderTools 3.10.1 (2024-10-19) +==================================== + +Deprecations +------------ + +- mongodb 场景统一存储相关的代码逻辑，且更新方式由之前 update_many 改为更正常的 update_one 的规则。 + + (:commit:`8af915f65fa021a97b2eeaf9893167f511ce81b9`) + +.. note:: + + - 虽然此版本为 patch 升级，但还请在虚拟环境中自行测试后再确认是否升级。 + +New features +------------ + +- 无。 + +Bug fixes +--------- + +- 解决 macOS 低版本的依赖兼容问题，优化依赖管理；解决 mongodb 存储在 py3.11 及以上场景时 motor 和 \ + pymongo 的版本冲突造成的运行报错。 + + (:commit:`a52755fc1e3b75728f09a04017b5907afa161624`) + +Code optimizations +------------------ + +- 整理代码风格。 + + (:commit:`c080c3ccf0e0796c728dc8e25562b2d90f79e72d`) + + (:commit:`213009271ab66ce6ec846462db0db0afe0f068dd`) + +
+ +AyugeSpiderTools 3.10.0 (2024-10-01) +==================================== + +Deprecations +------------ + +- 将 ``ayugespidertools.common.utils`` 中 ``ToolsForAyu`` 修改为 Tools。 + + (:commit:`73703a0cbf26e53813bb58db83e89fe55486a3e1`) + +- 删除 ``AiohttpFormRequest``，``AiohttpRequestArgs``，改为更简洁的 ``AiohttpRequest`` 且与 \ + aiohttp 请求参数一致。 + + (:commit:`1a7b1000fe32abe249007533a65f891bd989aee9`) + +- 整理并统一了 ``ayugespidertools.common.multiplexing`` 中 ReuseOperation 的函数参数名。 + + (:commit:`1cad13a94449dafa2f988fdd825fe282c2368dec`) + +.. note:: + + - 以上变动比较影响用户的是 AiohttpRequest 的部分，为不兼容的重构部分。其它部分如果未在项目中使用则\ + 完全不影响库的正常运行。 + - AiohttpRequest 新功能介绍文档请在 :ref:`ayugespidertools aiohttp ` 中查看。 + +New features +------------ + +- 升级 ua 数据为新版本，并且将其放入 data 中的 browsers.json 文件中，修改获取 ua 的方式。 + + (:commit:`7d08f853a7ca0ad9b860a8cc0e550c1b0b66e2f0`) + + (:commit:`7a905a3403801bb6ed0d453d6d87698eb0fd4ce4`) + +- oss 上传文件资源场景支持列表类型，现在可通过 mongodb 存储场景将 oss 相关的 AyuItem 字段设置为列表\ + 类型，在 `demo_oss_super `_ \ + 中查看示例。 + + (:commit:`5946c54144f30503090d7f09ec6a88a0b66427f9`) + + (:commit:`e553152773f9fe7aee1fdd118a9bb6327daf52ef`) + +- 增加从 VIT_DIR 中 .conf 的 ini 配置解析方法 get_cfg，以方便配置统一存放管理和保护隐私，在 \ + `demo_conf `_ \ + 中查看示例。 + + (:commit:`dd2485bf28ddf4cc9a08b464f9baf7af39bf7587`) + +- aiohttp 请求方式改为更人性化的，且与 aiohttp 请求参数保持一致的体验。以减少用户使用，理解和维护成本。 + + (:commit:`1cad13a94449dafa2f988fdd825fe282c2368dec`) + +.. note:: + + - 其它存储场景的 oss 暂不支持列表形式，需自行实现，可自行按照示例添加自行打包。 + +Bug fixes +--------- + +- 修复轨迹生成时关于抖动出错的问题。 + + (:commit:`6ad69583647fc3a4261f7a4ad4521c22580cc1ab`) + +- 修复自使用的 json 解析方法的错误。 + + (:commit:`a1d7aac2c826807c4838e4fbd31de6e637cab963`) + +.. note:: + + - 这里的问题修复都是非框架主要功能，不影响 scrapy 的扩展功能使用。 + +Code optimizations +------------------ + +- 升级 aiohttp 依赖版本。 + + (:commit:`5b448e5991cd7e26b6702cdbd1bfcacc9b3ebcce`) + +- Makefile 添加 git 相关的配置。 + + (:commit:`6304b772b14daf0880b591e82ff182a66c77bd2e`) + +- 解决文档 ``Edit on GitHub`` 出现的链接不对的问题。 + + (:commit:`6a79f617eb8d0e6834f673199d1ab08f68681df3`) + +- 文档完善贡献部分。 + + (:commit:`842300ad38afd9169e70e2c839128d282a120508`) + +- 优化 get_items_except_keys 方法，提升效率。 + + (:commit:`d2181444982995421f34c406e51ca0a053f9db1f`) + +
+ +AyugeSpiderTools 3.9.8 (2024-05-17) +=================================== + +Deprecations +------------ + +- 删除新建项目中 pyproject.toml 模板。 + + (:commit:`bb0adf3083cfdbeace76ddb96c9ac35a6dc4f76d`) + +- 删除新建项目中 run.py, run.sh, README.md, requirements.txt 模板的过度设计，不影响程序功能，按需\ + 自行添加。 + + (:commit:`2a02faa385069ac3a93194296c326dc31228c47b`) + + (:commit:`cb1393f70f49e4f956adecc4be5126871a97c3df`) + +- 更新 spider 模板内容，保证示例的稳定，为了通用性去除 type hint（请按需自行添加，DemoSpider 项目中\ + 有示例），并规避一些问题等。 + + (:commit:`7dc45fda8af3270d713fc21d9feda3ca8d6ea739`) + +- EncryptOperation 改名为 Encrypt，不影响库的使用。 + + (:commit:`5e529ca3eb625637894712a3972ba95a612c1526`) + +- 删除库中未使用的 get_files_from_path 方法。 + + (:commit:`e0d04d27a5b1a58eabe785485ed3402f0748c892`) + +.. note:: + + - 此弃用和变动并不影响项目中的功能，只涉及一些自动生成的多余配置文件，运行文件等，这些为过度设计（不应\ + 替用户强行决定，且未做到完美适配）。 + - 比较喜欢完整项目模版的开发者，则可选择通过 `LazyScraper `_ \ + 项目来更方便地生成项目模版。 + +New features +------------ + +- 同步更新 scrapy 依赖版本为 2.11.2。 + + (:commit:`1618654d4c2b9bd4032a52844e29abe17d2ee532`) + +Bug fixes +--------- + +- 无。 + +Code optimizations +------------------ + +- requests 相关代码更换为 urllib 方式。 + + (:commit:`f01403012bcebce0e49c27840dff446aa7ef70fd`) + + (:commit:`5cd28ccd6f38d1a37b2d57cf7bc1306c13173d1e`) + +- .conf 模板格式整理，修改模板为英文，以解决中英文混编下的格式问题。 + + (:commit:`f6f0e43bd5fcced5f724882606941fd033a56156`) + + (:commit:`01d02a19ee275fe80c52d696dee39500d35c9581`) + + (:commit:`8ded926de0a04680ce91fd07bfde36d478bfda5e`) + +- 添加 .editorconfig 配置。 + + (:commit:`d175c6e0ddfaf3dcc105c62ada422c9f907388cb`) + +- `poetry` 依赖更新。 + + (:commit:`f78354616c3e95d8e00238e8970fe332373a0273`) + +- 文档更新。 +- mongodb 存储场景中 pymongo 依赖版本及应用场景的判定逻辑修改，由通过 py 版本来判定改为由 pymongo 依\ + 赖版本来判定。目前本库在 py3.11 及以上还是会安装 ``^4.5.0`` 版本的 pymongo，不影响旧项目功能。 + + (:commit:`625ad1cf3a16463aa77744b7ce4d46f94f056bab`) + +.. note:: + + 补充解释：若 py 3.11 及以上则使用 ``^4.5.0`` 版本的 pymongo 来支持 3.6 及以上版本的 MongoDB 来\ + 解决 motor 的异步存储问题；若 py3.11 以下则使用 3.13.0 的 pymongo 版本来与目前一致。(:issue:`11`) + +
+ +AyugeSpiderTools 3.9.7 (2024-03-08) +=================================== + +Deprecations +------------ + +- 无。 + +New features +------------ + +- oss 场景添加是否保存完整链接的配置 full_link_enable，默认 false，不影响旧项目。 + + (:commit:`009ac20a4db55069c4b0cee5822834e42e21ba00`) + +- oss 场景不再需要手动添加上传的字段是否为空的判断。 + + (:commit:`009ac20a4db55069c4b0cee5822834e42e21ba00`) + +Bug fixes +--------- + +- 修复 `aiohttp` 场景下由于目标网站未遵守编码时可能会出现的编码问题。 + + (:commit:`d2772b5960c972c4cc6ee6e6ce541fa00e34a7fb`) + +Code optimizations +------------------ + +- 添加 aiohttp 可支持的请求方式。 + + (:commit:`c7c247e1badf411a149d9d6e1430230ec81e99a8`) + +- 优化 oss, file download 场景的 pipeline 示例，减少复杂逻辑。 + + (:commit:`b0929d8adba7c4d3ce2c7064a56656825d8802b7`) + + (:commit:`f0f1b2f61e449e30812d7410e55652d4fcb42169`) + +- 测试场景增加剔除无关代码块的规则。 + + (:commit:`3e0ce949340b8d27f95d86ecbcbd8bf04e85cccd`) + +- 代码风格统一，补充缺失的 type hint，提升开发体验。 + +
+ +AyugeSpiderTools 3.9.6 (2024-02-18) +=================================== + +Deprecations +------------ + +- 无。 + +New features +------------ + +- 无。 + +Bug fixes +--------- + +- 修复 mysql 存储引擎 engine 参数未生效的问题。 + + (:commit:`1240e375dd4e1bc7c87ba876a3cc8faf34b8695f`) + +Code optimizations +------------------ + +- 更新 aiohttp 依赖库版本以解决破坏兼容性的问题，同步更新 scrapy 依赖版本。 + + (:commit:`3f0dc5ada3a9742eff54e8a77c03a4fb7906795d`) + + (:commit:`246c824813b4ffdc844b0df26a9e944a467fb9ea`) + +- 文档更新。 + +
+ +AyugeSpiderTools 3.9.5 (2024-01-30) +=================================== + +Deprecations +------------ + +- 无。 + +New features +------------ + +- mysql 场景添加 odku_enable 配置来设置是否开启 ON DUPLICATE KEY UPDATE 功能。 + + (:commit:`25d71ddb789c71f3f570f85576ff225aeaf58d7b`) + +- 添加 oss pipeline 的示例，请在 DemoSpider 中 demo_oss 和 demo_oss_sec 查看具体使用方法。 + + (:issue:`16`) + +Bug fixes +--------- + +- 解决文件下载不支持多字段下载的问题，请在 DemoSpider 中 demo_file 和 demo_file_sec 查看具体使用方法。 + + (:commit:`f836f02d3c15b57623851888c0451ea0bfe8c631`) + + (:commit:`f504c45b86f2e328e2a9bb9f61328b693a571b52`) + +- 解决远程配置管理中缺失的 `mongodb:uri` 优先级设置。 + + (:commit:`51ea7da83c81fe97ea5cd6a6500fdb7fc3fa233b`) + +Code optimizations +------------------ + +- mq 场景添加关闭链接处理。 + + (:commit:`ac54fd0a7611a8e63b46689da83718a9cebdb013`) + +- 更新 readthedocs 中的教程指南，以方便快速上手。 +- 更新部分依赖库版本。 + +
+ +AyugeSpiderTools 3.9.4 (2024-01-10) +=================================== + +Deprecations +------------ + +- 无。 + +New features +------------ + +- 添加 `elasticsearch` 支持，具体示例请在 `DemoSpider` 中 `demo_es` 和 `demo_es_async` 查看。 + + (:issue:`15`) + + (:commit:`c4d048ee74c7246760e2ba91ef2844a5dd3540d7`) + + (:commit:`7651dd32974f6362b9a2dbc8e7258a5528d98858`) + +Bug fixes +--------- + +- 无。 + +Code optimizations +------------------ + +- mypy check。 + + (:commit:`785e36a5a85b141168ce24bfae9efe605ac05c36`) + +
+ +AyugeSpiderTools 3.9.3 (2023-12-30) +=================================== + +Bug fixes +--------- + +- 解决 ``pip install ayugespidertools`` 并执行简单场景时提示 oracledb 的依赖缺失问题。 + + (:commit:`e363937f2de8cb5dd06938ca2eb470e1a5b08847`) + +Code optimizations +------------------ + +- 统一代码风格。 + + (:commit:`ecb97e803b36da5a5fd0bca14c98654a4b5d743b`) + +
+ +AyugeSpiderTools 3.9.2 (2023-12-28) +=================================== + +New features +------------ + +- mysql 配置项支持自定义自动创建库表场景的 engine 和 collate 参数。 + + (:commit:`e6526668b818ec0d442160e60a98b73bd45fb673`) + +Bug fixes +--------- + +- 解决 `settings` 模板生成的 `LOG_FILE` 不是当前项目名的问题。 + + (:commit:`93c19d6c6812a86f6ea1ece7618c98e0f8c63957`) + +Code optimizations +------------------ + +- 更新 spider 模板，模板中解析方式改为 scrapy 的形式，防止对开发者造成理解成本。 + + (:commit:`91ad948506495bee210a673cd08541329375d8c4`) + +- 更新 `spider` 模板中的 `type hint`，优化了开发者使用体验。 + + (:commit:`c2a09087f9b9fa1d20927d51f9e9f670c74d00f3`) + +- 优化一些数据库连接处理和配置解析方法等。 + +
+ +AyugeSpiderTools 3.9.1 (2023-12-22) +=================================== + +New features +------------ + +- 添加 postgresql 的 asyncio 的 AsyncConnectionPool 存储场景支持。 + + (:commit:`341e7681931f796b5167696b948ea331e2b62dbb`) + +Bug fixes +--------- + +- 解决 asyncio 协程场景下的 spider 的 AyuItem 写法风格不兼容的问题。 + + (:commit:`66177e402d0e9c15b559664bfc40c6de0e545735`) + +Code optimizations +------------------ + +- 更新 spider 模板示例。 + + (:commit:`61e10b140e880c7b2348b35687c167b6fad99b99`) + +
+ +AyugeSpiderTools 3.9.0 (2023-12-18) +=================================== + +Deprecations +------------ + +- AsyncMysqlPipeline 改名为 AyuAsyncMysqlPipeline。 +- AsyncMongoPipeline 改名为 AyuAsyncMongoPipeline。 +- 删除 oss 的模块及依赖。 + +New features +------------ + +- 添加 oracle 的存储场景支持，目前有 fty 及 twisted 两种方式。 +- 添加 mongodb:uri 的配置方式。 + +Bug fixes +--------- + +- 解决 asyncio mysql 协程场景下可能会出现的被垃圾回收而阻塞的问题。 +- 解决 mysql 或 postgresql 的错误处理场景下由于权限等问题造成的循环递归问题。 + +Code optimizations +------------------ + +- 优化 .conf 模板示例，配置更明确且更易管理。 +- mypy check. + +
+ +AyugeSpiderTools 3.8.0 (2023-12-03) +=================================== + +Deprecations +------------ + +- MYSQL_ENGINE_ENABLED 的配置项名改为 DATABASE_ENGINE_ENABLED，目前支持 msyql 和 postgresql。 +- 安装再添加 database 选项，可通过 pip install ayugespidertools[database] 安装所需的所有数据依赖及扩展。 + +.. warning:: 注意：此变更包含不兼容部分，需要着重注意的部分如下： + + - 删除了 MYSQL_ENGINE_ENABLED 配置项； + - 由于 SQLAlchemy 依赖升级到了 2.0+ 新版本，与以往的去重使用有变化，具体请查看本库 readthedocs 文档。 + +New features +------------ + +- 支持 python3.12。 +- 添加 postgresql 的存储场景支持，目前有 fty 及 twisted 两种方式。 +- DATABASE_ENGINE_ENABLED 的配置目前会激活对应场景中数据库的 engine 和 engine_conn 以供去重使用。 +- 将 psycopg 相关的数据库扩展依赖改为可选项，可通过 pip install ayugespidertools[database] 安装所需依赖。 + +Code optimizations +------------------ + +- 优化 type hints。 +- 更新生成脚本模板以匹配新版本，也可使用以往 pandas 去重方式。 +- 更明确的日志信息。 + +
+ +AyugeSpiderTools 3.7.0 (2023-11-23) +=================================== + +Deprecations +------------ + +- 获取 nacos 和 consul 中的配置时不再转小写，请按照 readthedocs 示例填写。 +- 删除 html2text 相关依赖及代码，此场景更适合自行实现。 +- 安装不再包含非核心依赖，可通过 pip install ayugespidertools[all] 安装全部依赖。 +- 一些 api 变动： + +.. csv-table:: + :header: "更改前", "更改后", "受影响的部分" + :widths: 10, 15, 30 + + "extract_html_to_md", "删除", "ayugespidertools.formatdata" + "AliOssBase", "转移到 ayugespider.extras 中", "ayugespidertools.oss" + "yidungap, imgoperation, verificationcode", "转移到 ayugespider.extras 中，并整理在一起", "ayugespidertools.imgoperation; \ + ayugespidertools.verificationcode; ayugespidertools.common.yidungap" + +- 以下是对 extras 相关模块所影响较大部分的介绍： + +.. csv-table:: + :header: "更改前", "更改后", "受影响的部分" + :widths: 10, 15, 30 + + "YiDunGetGap.discern", "CvnpilKit.discern_gap", "ayugespidertools.common.yidungap" + "Picture.identify_gap", "CvnpilKit.identify_gap", "ayugespidertools.imgoperation" + "match_img_get_distance", "CvnpilKit.match_gap", "ayugespidertools.verificationcode" + "get_normal_track", "CvnpilKit.get_normal_track", "ayugespidertools.verificationcode" + "get_selenium_tracks", "ToolsForAyu.get_selenium_track", "ayugespidertools.verificationcode" + +.. warning:: + + - 此变更包含不兼容部分，如果你只使用其中 scrapy 扩展库部分，那么除了 nacos，consul 的 yaml 和 hcl \ + 解析外对你无影响。 + - 再次提醒，使用时请做好依赖管理，以免不兼容部分对你的影响！ + +New features +------------ + +- mongo 场景添加 authMechanisem 配置选项，为可选配置，默认为 SCRAM-SHA-1。 +- 将 numpy, oss, pillow 等非核心依赖改为可选项，可通过 pip install ayugespidertools[all] 安装所有依赖。 + +Code optimizations +------------------ + +- 优化 aiohttp, cvnpil 等测试用例，将图像相关功能整理并放入 cvnpil 模块中。 +- ayuge version 修改为从 __version__ 获取信息的方式。 +- 更新模板，mysql_engine 的示例改为通过 sqlalchemy 的方式，减少依赖数且大部分场景运行效率更好。 +- 将可选装依赖的相关的功能代码统一放入 extras 中，更易管理。 + +
+ +AyugeSpiderTools 3.6.1 (2023-11-06) +=================================== + +Bug fixes +--------- + +- 解决 mq 推送场景时 yield AyuItem 时的错误，现可支持多种格式。 +- 解决 VIT_DIR 默认参数未存储至 settings 中的问题。 + + +Code optimizations +------------------ + +- 文件下载场景添加 FILES_STORE 路径不存在时的自动创建处理。 +- settings 模板删除无关配置。 +- 项目添加 question issues template。 + +
+ +AyugeSpiderTools 3.6.0 (2023-10-31) +=================================== + +Deprecations +------------ + +- 一些 api 变动： + +.. csv-table:: + :header: "更改前", "更改后", "受影响的部分" + :widths: 10, 15, 30 + + "删除 LOGURU_CONFIG 配置参数", "现只需配置 `LOGURU_ENABLED` 即可", "slog 日志模块" + "删除 spider 中 settings_type 参数", "此为过度设计，若需要可自定义配置", "项目配置信息" + "删除 spider 中 mysql_engine_enabled 参数", "转移到设置中，名称为 MYSQL_ENGINE_ENABLED", "配置模块，影响较大" + "AyuItem 中 _table 参数类型修改", "修改为与普通字段一样的 DataItem 或 str 类型，删除 demand_code 字段", "spider，Item 模块" + "删除 spider 中 custom_table_enum 参数", "CvnpilKit", "同上" + "删除 RECORD_LOG_TO_MYSQL 配置参数", "改为 ayugespidertools.pipelines.AyuStatisticsMysqlPipeline 方式调用", "配置模块" + "YiDunGetGap", "CvnpilKit", "ayugespidertools" + "YiDunGetGap", "CvnpilKit", "ayugespidertools" + +.. warning:: + + 此变更包含不兼容内容，请修改不兼容部分并调试正常后再投入生产；本项目在有一些不兼容变更时，会发布 Minor \ + 及以上的版本包，请做好依赖版本管理 + +Code optimizations +------------------ + +- 设置 VIT_DIR 默认参数。 +- 去除冗余配置，统一配置风格。将一些过于复杂的模块拆分，便于管理。 + +
+ +AyugeSpiderTools 3.5.2 (2023-10-17) +=================================== + +New features +------------ + +- 添加从 nacos 中获取配置的方法，若 .conf 中同时存在 consul 和 nacos 配置则优先使用 consul；即优先\ + 级 consul > nacos。 + +Code optimizations +------------------ + +- 删除 .conf 示例中的无用配置 wxbot。 +- 优化从本地 .conf 获取配置的逻辑，也提供更清晰明确的报错信息。 +- tox 重新添加了 windows 场景。 +- 更新 CI 工具版本。 + +
+ +AyugeSpiderTools 3.5.1 (2023-09-28) +=================================== + +Bug fixes +--------- + +- 修复在 `py 3.11` 及以上版本的 `mongo` 相关场景的报错。(:issue:`11`) + +Code optimizations +------------------ + +- 优化 AyuItem 实现，增强可读性及用户输入体验，比如 add_field 增加 IDE 参数提示功能。 +- 更新文档中 AyuItem 的使用建议及对应测试。 +- 更新测试文件，比如 test_crawl 及 spider 相关方法。 + +
+ +AyugeSpiderTools 3.5.0 (2023-09-21) +=================================== + +Code optimizations +------------------ + +- scrapy 依赖升级为 2.11.0。 +- 统一运行统计的方法，修改运行 stats 中有关时间的获取和计算方法。 +- 添加 pre-commit 工具和 CI，提升 commit 和 pull request 体验。 +- 更新 readthedocs 的新配置。 +- 优化 test_crawl 的测试方法。 + +
+ +AyugeSpiderTools 3.4.2 (2023-09-15) +=================================== + +Bug fixes +--------- + +- 修复 crawl 模板文件中 TableEnum 的导入问题。 +- 修改文档中 kafka 推送示例 typo 问题。 + +Code optimizations +------------------ + +- 优化文件下载本地的逻辑，处理当 file_url 不存在时的情况。 +- 优化 items，typevar 等模块的 type hint，并删除无用的类型内容。 +- 设置包源的优先级。 +- 增加测试用例。 +- 添加 mypy 工具。 + +
+ +AyugeSpiderTools 3.4.1 (2023-09-07) +=================================== + +Bug fixes +--------- + +- 解决 Twisted 版本更新到 23.8.0 不兼容的问题。(:issue:`10`) + +Code optimizations +------------------ + +- scrapy 依赖版本更新为 2.10.1。 + +
+ +AyugeSpiderTools 3.4.0 (2023-08-10) +=================================== + +Bug fixes +--------- + +- aiohttp 超时参数由 AIOHTTP_CONFIG 中的 timeout 获取改为直接从 DOWNLOAD_TIMEOUT 中获取。解决在 \ + aiohttp 超时参数值大于 DOWNLOAD_TIMEOUT 时，与程序整体超时设置冲突，考虑程序的整体性，而不去根据 \ + aiohttp 的超时设置来更新项目的整体设置。 + +Code optimizations +------------------ + +- aiohttp 添加 allow_redirects 配置参数 ，优化对应文档示例。 +- 更新 scrapy 依赖版本为 2.10.0。 +- 解决部分 typo 及注解问题。 + +
+ +AyugeSpiderTools 3.3.3 (2023-08-03) +=================================== + +Bug fixes +--------- + +- 修复解析 yaml 格式数据依赖缺失的问题。(:issue:`9`) + +Code optimizations +------------------ + +- 本库中解决 Mysql 的 Unknown column 'xx' in 'field list' 部分代码变动，比如不再根据 item 字段\ + 是crawl_time 类型格式来给其默认字段格式 DATE，因为用户可能只是存储字段是这个名称，意义并不同，或者它\ + 存的是个时间戳等情况。这样需要考虑的问题太复杂了，且具有隐患，不如优先解决字段缺失问题，后续按需再手动\ + 调整表字段类型。 + +
+ +AyugeSpiderTools 3.3.2 (2023-07-26) +=================================== + +New features +------------ + +- 增加贝塞尔曲线生成轨迹的示例方法。 + +Code optimizations +------------------ + +- 将项目中有关文件的操作统一改为 pathlib 的方式。 +- 根据 consul 获取配置的方式添加缓存处理，不用每次运行都多次调用同样参数来获取配置。减少请求次数，提高\ + 运行效率。 +- 更新 README.md 内容，增加对应英文版本。 + +
+ +AyugeSpiderTools 3.3.1 (2023-06-29) +=================================== + +Code optimizations +------------------ + +- 优化 item 使用体验，完善功能及对应文档内容，具体请查看 readthedocs item 部分。 + +
+ +AyugeSpiderTools 3.3.0 (2023-06-21) +=================================== + +Deprecation removals +-------------------- + +- 优化了 `Item` 体验，升级为 `AyuItem`，使用更方便，但注意与旧版本写法并不兼容： + + - 删除了 `MysqlDataItem` 实现。 + - 删除了 `MongoDataItem` 实现。 + - 增加了 `AyuItem` 参数以方便开发和简化 `pipelines` 结构，新示例请查看 `DemoSpider` 项目或 `readthedocs` 文档对应内容。 + +New features +------------ + +- 添加文件下载的示例，具体案例请查看 DemoSpider 中的 demo_file 项目。 + +Code optimizations +------------------ + +- 升级依赖库中 numpy 和 loguru 版本，避免其漏洞警告提示。 +- 更新对应的模板生成示例，简化一些不常用的配置即注释等。 + +
+ +AyugeSpiderTools 3.2.0 (2023-06-07) +=================================== + +Deprecation removals +-------------------- + +- 去除数据表前缀和集合前缀的鸡肋功能： + + - 删除了 MYSQL_TABLE_PREFIX 参数。 + - 删除了 MONGODB_COLLECTION_PREFIX 参数。 +- 删除其它的鸡肋功能： + + - 移除 runjs 方便运行 js 方法的鸡肋封装。 + - 移除 rpa 管理自动化程序的方法。 +- 删除了使用 requests 作为 scrapy 请求库的功能，推荐使用本库中 aiohttp 的方式。 + +New features +------------ + +- 添加 kafka 推送的示例，具体案例请查看 DemoSpider 项目的 demo_kafka 部分。 + +Code optimizations +------------------ + +- 增加 RabbitMQ 中 heartbeat 和 socket_timeout 参数可自定义的功能。 +- 整理依赖文件。 + +
+ +AyugeSpiderTools 3.1.0 (2023-05-30) +=================================== + +New features +------------ + +- 添加 mq 推送的示例，具体案例请查看 DemoSpider 项目的 demo_mq 部分。 + +Code optimizations +------------------ + +- 修复部分 typo 问题。 + +
+ +AyugeSpiderTools 3.0.1 (2023-05-17) +=================================== + +这是一个 major 版本更新，含有 bug 修复、代码优化等。 + +Deprecation removals +-------------------- + +- 删除 ayugespidertools 的 cli 名称 -> 改为 ayuge 来管理。 + +New features +------------ + +- 修改 item 实现方式，不再通过将字段都存入 alldata 中即可实现动态设置字段的功能，使用更清晰，且能更方便、 + 地使用 ItemLoaders 的功能，具体案例请查看 DemoSpider 项目。 + +Bug fixes +--------- + +- 修复不会创建表注释的问题。 + +Code optimizations +------------------ + +- 修改 dict_keys_to_lower 和 dict_keys_to_upper 的将字典 key 转为大写或小写的功能优化为嵌套字典中\ + 所有 key 都转为大写或小写。 +- 将模板中 settings.py 中的配置读取放入库中 update_settings 实现，简化 settings.py 文件内容。 +- 优化 Makefile 功能，简化清理 __pycache__ 文件夹的功能。 +- 修改部分 typo 问题。 +- 更新 readthedocs 内容，更新测试文件。 + +
+ +AyugeSpiderTools 2.1.0 (2023-05-09) +=================================== + +这是一个主要更改了 scrapy 依赖库为 2.9.0 版本，含有 bug 修复。 + +Deprecation removals +-------------------- + +- tox 去除 windows 平台的测试场景。 + +Deprecations +------------ + +- 下一大版本将删除 ayugespidertools 的 cli 名称 -> 改为 ayuge 来管理。 + +New features +------------ + +- 本库依赖库 scrapy 版本升级为 2.9.0。 + +Bug fixes +--------- + +- 修复使用 ayuge 及 ayuge -h 命令时，未显示当前库版本的问题。 + +AyugeSpiderTools 2.0.3 (2023-05-06) +=================================== + +Deprecations +============ + +- 下一大版本将删除 ayugespidertools 的 cl` 名称 -> 改为 ayuge 来管理。 + +New features +------------ + +- 添加 mongodb 的 asyncio 的示例。 + +Code optimizations +------------------ + +- readthedocs 的 markdown 解析由 recommonmark 改为 myst-parser，以支持更多的 markdown 语法。 + +
+ +AyugeSpiderTools 2.0.1 (2023-04-27) +=================================== + +Deprecation removals +-------------------- + +- 一些 api 变动： + +.. csv-table:: + :header: "更改前", "更改后", "受影响的部分" + :widths: 15, 15, 25 + + "from ayugespidertools.AyugeSpider import AyuSpider", "from ayugespidertools.spiders import AyuSpider", "_" + "from ayugespidertools.AyuRequest import AioFormRequest", "from ayugespidertools.request import AiohttpFormRequest", "_" + "from ayugespidertools.AyuRequest import AiohttpRequest", "from ayugespidertools.request import AiohttpRequest", "_" + "from ayugespidertools.common.Utils import * ", "from ayugespidertools.common.utils import *", "_" + "from ayugespidertools.Items import * ", "from ayugespidertools.items import *", "_" + "from .common.DataEnum import TableEnum", "from .items import TableEnum", "_" + "from ayugespidertools.AyugeCrawlSpider import AyuCrawlSpider", "from ayugespidertools.spiders import AyuCrawlSpider", "_" + "ayugespidertools.Pipelines", "ayugespidertools.pipelines", "pipelines" + "ayugespidertools.Middlewares", "ayugespidertools.middlewares", "middlweares" + +- 一些参数配置变动： + +.. csv-table:: + :header: "更改前", "更改后", "备注" + :widths: 10, 15, 30 + + "PROXY_URL", "proxy", "代理 proxy 参数" + "PROXY_INDEX", "index", "代理配置等" + +- 一些使用方法更改： + + - 使用 AiohttpRequest 构造请求时，由之前的 meta 中的 aiohttp_args 配置参数，改为由 args 的新增\ + 参数取代，其参数类型同样为 dict，也可以为 AiohttpRequestArgs 类型，更容易输入。 + +Deprecations +------------ + +- 下一大版本将删除 ayugespidertools 的 cli 名称 -> 改为 ayuge 来管理。 + +New features +------------ + +- 丰富 aiohttp 请求场景，增加重试，代理，ssl 等功能。 + +Code optimizations +------------------ + +- 更新测试用例。 + +
+ +AyugeSpiderTools 1.1.9 (2023-04-20) +=================================== + +New features +------------ + +- 增加 ayuge startproject 命令支持 project_dir 参数。 + +.. code:: bash + + # 这将在 project dir 目录下创建一个 Scrapy 项目。如果未指定 project dir，则 project dir 将与 myproject 相同。 + ayuge startproject myproject [project_dir] + +Bug fixes +--------- + +- 修复模板中 settings 的 CONSUL 配置信息没有更新为 v1.1.6 版本推荐的使用方法的问题。 +- 修复在 startproject 创建项目时生成的 run.sh 中的路径信息错误问题。 + +Code optimizations +------------------ + +- 添加测试用例。 +- 以后的版本发布说明都会在 ayugespidertools readthedocs 上展示。 diff --git a/docs/conf.py b/docs/conf.py index f2ce0ea..1fd7da8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -40,6 +40,7 @@ "sphinx.ext.coverage", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", + "sphinx.ext.extlinks", ] templates_path = ["_templates"] @@ -64,11 +65,44 @@ html_static_path: list = [] -source_parsers = { - ".md": "sphinx_markdown_parser.parser.MySTParser", -} source_suffix = [".rst", ".md"] autodoc_mock_imports = ["ayugespidertools"] suppress_warnings = ["myst.xref_missing"] + +# Options for sphinx-hoverxref options +# ------------------------------------ + +hoverxref_auto_ref = True +hoverxref_role_types = { + "class": "tooltip", + "command": "tooltip", + "confval": "tooltip", + "hoverxref": "tooltip", + "mod": "tooltip", + "ref": "tooltip", + "reqmeta": "tooltip", + "setting": "tooltip", + "signal": "tooltip", +} +hoverxref_roles = ["command", "reqmeta", "setting", "signal"] + +extlinks = { + "commit": ( + "https://github.com/shengchenyang/AyugeSpiderTools/commit/%s", + "commit %s", + ), + "issue": ( + "https://github.com/shengchenyang/AyugeSpiderTools/issues/%s", + "issue %s", + ), + "raw": ( + "https://raw.githubusercontent.com/shengchenyang/AyugeSpiderTools/master/%s", + "raw %s", + ), + "blob": ( + "https://github.com/shengchenyang/AyugeSpiderTools/blob/master/%s", + "blob %s", + ), +} diff --git a/docs/diy/myself.md b/docs/diy/myself.md deleted file mode 100644 index be6504e..0000000 --- a/docs/diy/myself.md +++ /dev/null @@ -1,41 +0,0 @@ -# How-To-Build-Your-Own-Library - -本库由 `poetry` 包管理工具构建，任何修改本库后自定义打包等需求请以 [poetry](https://python-poetry.org/) 官方文档为准。 - -## 前言 - -本库是把 `Scrapy` 的一些常用功能（扩展功能和开发中常用方法）封装成了一个库，方便大家快速使用。 - -但在使用本库的过程中，你可能会遇到一些问题： - -- 比如模板中某些配置不符合你的项目需求； -- 不喜欢项目结构的设计； -- 依赖库的版本不适合你的需求。 - -像这些可能包含非常个性化的定制，无法适配所有人的喜好，也无法通过 `Pull Requests` 合并来优雅地解决此类问题，这时候你可能会想要修改一些东西，那么你可以参考本文档，来快速构建你自己的专属库。 - -## 构建方法 - -你可以 `clone` 源码后，修改任意方法，修改完成后 `poetry build` 或 `make build` 即可打包并内部使用。 - -> 以更新 `kafka-python` 版本为例： - -- Prepare: `clone` 项目并准备开发环境 - - 将项目克隆到本地，创建 `python` 虚拟环境并安装 `poetry`，然后在项目根目录下运行 `poetry install` 安装依赖即可。 - -- Make your changes: 自定义更改的内容 - - 修改你所关注的部分，比如你的项目场景下可能需要其它的日志配置默认值，或添加其它的项目结构模板，更改库名等。 - - 若需要更新本项目的 `kafka-python` 依赖库版本为 `x.x.x`，那只需 `poetry add kafka-python==x.x.x` 安装目标版本即可。 - -- Run tests & Rebuild: 测试功能并重打包 - - 修改完毕并测试可用后，即可通过 `poetry build` 或 `make` 工具的 `make build` 打包即可使用。 - -以上步骤可以简化为，先 `clone` 源码，然后做出改变（若构建 `preview` 包时则不需要变动），最后在虚拟环境中执行 `pip install poetry && poetry build` 即可打包。 - -## 补充 - -若你自定义的方法对大多数人都合适的话，可以尝试将此功能添加到本项目，但是在此之前请先提交相关的 `ISSUES` 确认可行后再开发和提交对应 `PULL REQUESTS`，以免浪费了你做出的贡献。 diff --git a/docs/diy/myself.rst b/docs/diy/myself.rst new file mode 100644 index 0000000..ab96a29 --- /dev/null +++ b/docs/diy/myself.rst @@ -0,0 +1,56 @@ +.. _diy-myself: + +============================= +How-To-Build-Your-Own-Library +============================= + +本库由 poetry 包管理工具构建，任何修改本库后自定义打包等需求请以 `poetry`_ 官方文档为准。 + +前言 +====== + +本库是把 Scrapy 的一些常用功能（扩展功能和开发中常用方法）封装成了一个库，方便大家快速使用。 + +但在使用本库的过程中，你可能会遇到一些问题： + +- 比如模板中某些配置不符合你的项目需求； +- 不喜欢项目结构的设计； +- 依赖库的版本不适合你的需求。 + +像这些可能包含非常个性化的定制，无法适配所有人的喜好，也无法通过 Pull Requests 合并来优雅地解\ +决此类问题，这时候你可能会想要修改一些东西，那么你可以参考本文档，来快速构建你自己的专属库。 + +构建方法 +========== + +你可以 clone 源码后，修改任意方法，修改完成后 poetry build 或 make build 即可打包并内部使用。 + +以更新 kafka-python 版本为例： + +- Prepare: clone 项目并准备开发环境 + + 将项目克隆到本地，创建 python 虚拟环境并安装 poetry，然后在项目根目录下运行 poetry instal\ + 安装依赖即可。 + +- Make your changes: 自定义更改的内容 + + 修改你所关注的部分，比如你的项目场景下可能需要其它的日志配置默认值，或添加其它的项目结构模板，\ + 更改库名等。 + + 若需要更新本项目的 kafka-python 依赖库版本为 x.x.x，那只需 poetry add kafka-python==x.x.x\ + 安装目标版本即可。 + +- Run tests & Rebuild: 测试功能并重打包 + + 修改完毕并测试可用后，即可通过 poetry build 或 make 工具的 make build 打包即可使用。 + +以上步骤可以简化为，先 clone 源码，然后做出改变（若构建 preview 包时则不需要变动），最后在虚拟环境中执行\ +pip install poetry && poetry build 即可打包。 + +补充 +======= + +若你自定义的方法对大多数人都合适的话，可以尝试将此功能添加到本项目，但是在此之前请先提交相关的 ISSUES 确\ +认可行后再开发和提交对应 PULL REQUESTS，以免浪费了你做出的贡献。 + +.. _poetry: https://python-poetry.org/ diff --git a/docs/diy/mytemplate.md b/docs/diy/mytemplate.md deleted file mode 100644 index a88e803..0000000 --- a/docs/diy/mytemplate.md +++ /dev/null @@ -1,29 +0,0 @@ -# How-To-Build-Your-Own-Template - -## 前言 - -在开发爬虫项目时，需要设置各种辅助开发工具的配置内容，比如一些代码类型检查，代码风格整理和一些常用操作等。 - -就比如 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 中的项目结构，会大大提升团队中的开发体验。 - -而且，各个项目中的这些配置也都大致一样，那么就可以通过 `cookiecutter` 来将一些变动的参数和常用的选项提取出来整理成一个工程项目模版以供团队使用。 - -那如何快速创建类似 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 的 `Scrapy` 工程项目结构呢？ - -## 构建方法 - -> 推荐查看 `cookiecutter` 官方文档，来自定义团队专属的项目模版。 - -这里提供一个 [LazyScraper](https://github.com/shengchenyang/LazyScraper) 的 `cookiecutter` 示例，使用方法如下： - -```shell -# 需要提前安装好 `cookiecutter` -pip install cookiecutter - -# 然后根据 repo 模版生成项目 -cookiecutter https://github.com/shengchenyang/LazyScraper.git -``` - -## 补充 - -示例风格并非完全符合每个人的喜好，所以可参考着修改和完善。 diff --git a/docs/diy/mytemplate.rst b/docs/diy/mytemplate.rst new file mode 100644 index 0000000..b1cbfcd --- /dev/null +++ b/docs/diy/mytemplate.rst @@ -0,0 +1,40 @@ +.. _diy-mytemplate: + +============================== +How-To-Build-Your-Own-Template +============================== + +前言 +====== + +在开发爬虫项目时，需要设置各种辅助开发工具的配置内容，比如一些代码类型检查，代码风格整理和一些常用操作等。 + +就比如 `DemoSpider`_ 中的项目结构，会大大提升团队中的开发体验。 + +而且，各个项目中的这些配置也都大致一样，那么就可以通过 cookiecutter 来将一些变动的参数和常用的选项提取\ +出来整理成一个工程项目模版以供团队使用。 + +那如何快速创建类似 `DemoSpider`_ 的 Scrapy 工程项目结构呢？ + +构建方法 +========== + + 推荐查看 cookiecutter 官方文档，来自定义团队专属的项目模版。 + +这里提供一个 `LazyScraper`_ 的 cookiecutter 示例，使用方法如下： + +.. code:: bash + + # 需要提前安装好 cookiecutter + pip install cookiecutter + + # 然后根据 repo 模版生成项目 + cookiecutter https://github.com/shengchenyang/LazyScraper.git + +补充 +====== + +示例风格并非完全符合每个人的喜好，所以可参考着修改和完善。 + +.. _DemoSpider: https://github.com/shengchenyang/DemoSpider +.. _LazyScraper: https://github.com/shengchenyang/LazyScraper diff --git a/docs/intro/examples.md b/docs/intro/examples.md deleted file mode 100644 index 27e28f0..0000000 --- a/docs/intro/examples.md +++ /dev/null @@ -1,137 +0,0 @@ -# 例子 - -本教程将引导您完成这些任务： - -- 快速熟悉 `ayugespidertools` 库的使用方法和支持场景 -- 编写爬虫来抓取站点并提取数据 - -## 1. 快速开始 - -> 你可以使用以下两种方式来快速开始： - -### 1.1. 方式一：ayugespidertools - -通过跑通本库 `Github` 中的 `GIF` 示例，具体请点击跳转至 [AyugeSpiderTools](https://github.com/shengchenyang/AyugeSpiderTools) 查看。若不是很熟悉 `Scrapy` 库，可选择先查看本文档中的示例教程。 - -### 1.2. 方式二：DemoSpider - -另一种较方便的方式是：通过演示项目 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 来快速复现某些场景及功能。 - -本库 `ayugespidertools` 的 [github README.md](https://github.com/shengchenyang/AyugeSpiderTools#readme) 中所有功能，都可以在 `DemoSpider` 中找到示例。 - -您可以在项目的自述文件中找到有关它的更多信息。 - -## 2. 应用场景介绍 - -根据 `DemoSpider` 中的各个 `spider` 对一些应用场景进行简要的补充介绍，总体的介绍为： - -```diff -+ 0).以下场景全支持从 nacos 或 consul 中获取配置，不一一举例。 - -# 数据存入 Mysql 的场景： -+ 1).demo_one: 从 .conf 中获取 mysql 配置 -+ 3).demo_three: 从 consul 中获取 mysql 配置 -+ 21).demo_mysql_nacos: 从 nacos 中获取 mysql 配置 -+ 5).demo_five: Twisted 异步存储示例 -+ 24).demo_aiomysql: 结合 aiomysql 实现的 asyncio 异步存储示例 -+ 13).demo_AyuTurboMysqlPipeline: mysql 同步连接池的示例 - -# 数据存入 MongoDB 的场景： -+ 2).demo_two: 从 .conf 中获取 mongodb 配置 -+ 4).demo_four: 从 consul 中获取 mongodb 配置 -+ 6).demo_six: Twisted 异步存储示例 -+ 17).demo_mongo_async: 结合 motor 实现的 asyncio 异步存储示例 - -# 数据存入 PostgreSQL 的场景(需要安装 ayugespidertools[database]) -+ 22).demo_nine: 从 .conf 中获取 postgresql 配置 -+ 23).demo_ten: Twisted 异步存储示例 -+ 27).demo_eleven: asyncio 异步存储示例 - -# 数据存入 ElasticSearch 的场景(需要安装 ayugespidertools[database]) -+ 28).demo_es: 普通同步存储示例 -+ 29).demo_es_async: asyncio 异步存储示例 - -# 数据存入 Oracle 的场景(需要安装 ayugespidertools[database]) -+ 25). demo_oracle: 普通同步存储示例 -+ 26). demo_oracle_twisted: Twisted 异步存储示例 - -- 7).demo_seven: 使用 requests 来请求的场景(已删除，更推荐 aiohttp 方式) -+ 8).demo_eight: 同时存入 Mysql 和 MongoDB 的场景 -+ 9).demo_aiohttp_example: 使用 aiohttp 来请求的场景 -+ 10).demo_aiohttp_test: scrapy aiohttp 在具体项目中的使用方法示例 - -+ 11).demo_proxy_one: 快代理动态隧道代理示例 -+ 12).demo_proxy_two: 测试快代理独享代理 -+ 14).demo_crawl: 支持 scrapy CrawlSpider 的示例 - -# 本库中给出支持 Item Loaders 特性的示例 -+ 15).demo_item_loader: 本库中使用 Item Loaders 的示例 -- 16).demo_item_loader_two: 已删除，可查看 demo_item_loader，可方便的使用 Item Loaders 了 - -+ 18).demo_mq: 数据存入 rabbitmq 的模板示例 -+ 19).demo_kafka: 数据存入 kafka 的模板示例 -+ 20).demo_file: 使用本库 pipeline 下载图片等文件到本地的示例 -+ 30).demo_file_sec: 自行实现的图片下载示例 -+ 31).demo_oss: 使用本库 pipeline 上传到 oss 的示例 -+ 32).demo_oss_sec: 自行实现的 oss 上传示例 -``` - -基本查看以上 `spider` 即可了解使用方法，但有些示例还是不够详细，对以上内容进行补充。 - -- 以上场景有需要 `consul` 或 `nacos` 上的相关配置的示例，与 `.conf` 中的配置内容一致，以下为 `json` 格式配置的示例： - - ```json - { - "mysql":{ - "host":"***", - "port":3306, - "user":"***", - "password":"***", - "database":"***", - "charset":"选填：默认 utf8mb4" - }, - "mongodb":{ - "host":"***", - "port":27017, - "user":"***", - "password":"***", - "database":"***", - "authsource":"***", - "authMechanism":"选填：默认 SCRAM-SHA-1" - }, - "postgresql": { - "host":"***", - "port":5432, - "user":"***", - "password":"***", - "database":"***", - "charset":"选填：默认 UTF8" - }, - "mq":{ - "host":"***", - "port":5672, - "username":"***", - "password":"***", - "virtualhost":"***", - "queue":"***", - "exchange":"***", - "routing_key":"***" - }, - "kafka":{ - "bootstrap_servers":"127.0.0.1:9092 #若多个用逗号分隔", - "topic":"***", - "key":"***" - }, - "kdl_dynamic_proxy":{ - "proxy":"o668.kdltps.com:15818", - "username":"***", - "password":"***" - }, - "kdl_exclusive_proxy":{ - "proxy":"http://kps.kdlapi.com/api/getkps?orderid=***&num=100&format=json", - "username":"***", - "password":"***", - "index":1 - } - } - ``` diff --git a/docs/intro/examples.rst b/docs/intro/examples.rst new file mode 100644 index 0000000..561c40e --- /dev/null +++ b/docs/intro/examples.rst @@ -0,0 +1,152 @@ +.. _intro-examples: + +====== +例子 +====== + +本教程将引导您完成这些任务： + +- 快速熟悉 ayugespidertools 库的使用方法和支持场景 +- 编写爬虫来抓取站点并提取数据 + +1. 快速开始 +============= + + 你可以使用以下两种方式来快速开始： + +1.1. 方式一：ayugespidertools +--------------------------------- + +通过跑通本库 Github 中的 GIF 示例，具体请点击跳转至 `AyugeSpiderTools`_ 查看。若不是很熟悉 Scrapy\ +库，可选择先查看本文档中的示例教程。 + +1.2. 方式二：DemoSpider +-------------------------- + +另一种较方便的方式是：通过演示项目 `DemoSpider`_ 来快速复现某些场景及功能。 + +本库 `ayugespidertools github README.md`_ 中所有功能，都可以在 `DemoSpider`_ 中找到示例。 + +您可以在项目的自述文件中找到有关它的更多信息。 + +2. 应用场景介绍 +================ + +根据 `DemoSpider`_ 中的各个 spider 对一些应用场景进行简要的补充介绍，总体的介绍为： +:: + + + 0).以下场景全支持从 nacos 或 consul 中获取配置，不一一举例。 + + # 数据存入 Mysql 的场景： + + 1).demo_one: 从 .conf 中获取 mysql 配置 + + 3).demo_three: 从 consul 中获取 mysql 配置 + + 21).demo_mysql_nacos: 从 nacos 中获取 mysql 配置 + + 5).demo_five: Twisted 异步存储示例 + + 24).demo_aiomysql: 结合 aiomysql 实现的 asyncio 异步存储示例 + + 13).demo_AyuTurboMysqlPipeline: mysql 同步连接池的示例 + + # 数据存入 MongoDB 的场景： + + 2).demo_two: 从 .conf 中获取 mongodb 配置 + + 4).demo_four: 从 consul 中获取 mongodb 配置 + + 6).demo_six: Twisted 异步存储示例 + + 17).demo_mongo_async: 结合 motor 实现的 asyncio 异步存储示例 + + # 数据存入 PostgreSQL 的场景(需要安装 ayugespidertools[database]) + + 22).demo_nine: 从 .conf 中获取 postgresql 配置 + + 23).demo_ten: Twisted 异步存储示例 + + 27).demo_eleven: asyncio 异步存储示例 + + # 数据存入 ElasticSearch 的场景(需要安装 ayugespidertools[database]) + + 28).demo_es: 普通同步存储示例 + + 29).demo_es_async: asyncio 异步存储示例 + + # 数据存入 Oracle 的场景(需要安装 ayugespidertools[database]) + + 25). demo_oracle: 普通同步存储示例 + + 26). demo_oracle_twisted: Twisted 异步存储示例 + + - 7).demo_seven: 使用 requests 来请求的场景(已删除，更推荐 aiohttp 方式) + + 8).demo_eight: 同时存入 Mysql 和 MongoDB 的场景 + + 9).demo_aiohttp_example: 使用 aiohttp 来请求的场景 + + 10).demo_aiohttp_test: scrapy aiohttp 在具体项目中的使用方法示例 + + + 11).demo_proxy_one: 快代理动态隧道代理示例 + + 12).demo_proxy_two: 测试快代理独享代理 + + 14).demo_crawl: 支持 scrapy CrawlSpider 的示例 + + # 本库中给出支持 Item Loaders 特性的示例 + + 15).demo_item_loader: 本库中使用 Item Loaders 的示例 + - 16).demo_item_loader_two: 已删除，可查看 demo_item_loader，可方便的使用 Item Loaders 了 + + + 18).demo_mq: 数据存入 rabbitmq 的模板示例 + + 19).demo_kafka: 数据存入 kafka 的模板示例 + + 20).demo_file: 使用本库 pipeline 下载图片等文件到本地的示例 + + 30).demo_file_sec: 自行实现的图片下载示例 + + 31).demo_oss: 使用本库 pipeline 上传到 oss 的示例 + + 32).demo_oss_sec: 自行实现的 oss 上传示例 + + 33).demo_oss_super: MongoDB 存储场景 oss 上传字段支持列表类型 + + 34).demo_conf: 支持从 .conf 中获取自定义配置 + +基本查看以上 spider 即可了解使用方法，但有些示例还是不够详细，对以上内容进行补充。 + +- 以上场景有需要 consul 或 nacos 上的相关配置的示例，与 .conf 中的配置内容一致，以下为 json\ + 格式配置的示例： + +.. code:: json + + { + "mysql":{ + "host":"***", + "port":3306, + "user":"***", + "password":"***", + "database":"***", + "charset":"选填：默认 utf8mb4" + }, + "mongodb":{ + "host":"***", + "port":27017, + "user":"***", + "password":"***", + "database":"***", + "authsource":"***", + "authMechanism":"选填：默认 SCRAM-SHA-1" + }, + "postgresql": { + "host":"***", + "port":5432, + "user":"***", + "password":"***", + "database":"***", + "charset":"选填：默认 UTF8" + }, + "mq":{ + "host":"***", + "port":5672, + "username":"***", + "password":"***", + "virtualhost":"***", + "queue":"***", + "exchange":"***", + "routing_key":"***" + }, + "kafka":{ + "bootstrap_servers":"127.0.0.1:9092 #若多个用逗号分隔", + "topic":"***", + "key":"***" + }, + "kdl_dynamic_proxy":{ + "proxy":"o668.kdltps.com:15818", + "username":"***", + "password":"***" + }, + "kdl_exclusive_proxy":{ + "proxy":"http://kps.kdlapi.com/api/getkps?orderid=***&num=100&format=json", + "username":"***", + "password":"***", + "index":1 + } + } + +.. _AyugeSpiderTools: https://github.com/shengchenyang/AyugeSpiderTools +.. _DemoSpider: https://github.com/shengchenyang/DemoSpider +.. _ayugespidertools github README.md: https://github.com/shengchenyang/AyugeSpiderTools#readme diff --git a/docs/intro/install.md b/docs/intro/install.md deleted file mode 100644 index fa277a4..0000000 --- a/docs/intro/install.md +++ /dev/null @@ -1,119 +0,0 @@ -# 安装指南 - -## 支持的 Python 版本 - -`AyugeSpiderTools` 需要 `Python 3.9+`，在 `AyugeSpiderTools 3.10.1` 之后的版本不再支持 `python 3.8`。 - -## 安装 AyugeSpiderTools - -> 可以使用以下命令安装 `ayugespidertools` 及其依赖项： - -1. 若你的数据库场景只需要 `mysql` 和 `mongodb`，且不需要本库 `extras` 中的扩展功能，那么直接简洁安装即可，命令如下： - -```shell -pip install ayugespidertools -``` - -2. 若你需要更多的数据库场景，且同样不需要本库 `extras` 中的扩展功能，那么安装数据库版本最好，命令如下： - -```shell -pip install ayugespidertools[database] -``` - -3. 安装全部依赖命令如下： - -```shell -pip install ayugespidertools[all] -``` - -注意：若你只需要 `scrapy` 扩展库的简单功能，那么默认的简洁依赖安装即可；一些可选择的开发功能（都会放在 `extras` 部分）若要使用，请使用完整安装。 - -强烈建议您将 `ayugespidertools` 安装在专用的 `virtualenv` 中，以避免与您的系统包发生冲突。 - -4. 安装预发布(开发)版本，通过源码安装： - -```shell -# 请注意，此源码方式安装的是开发版本，请勿在正式场景中使用！ -pip install git+https://github.com/shengchenyang/AyugeSpiderTools.git -``` - -### 可能遇到的问题 - -> 在安装时可能会遇到以下问题： - -- `zsh: no matches found: ayugespidertools[database]` - - ```shell - # zsh 中需要修改对应的命令 - pip install 'ayugespidertools[database]' - pip install 'ayugespidertools[all]' - ``` - -- 无法安装到最新版本 - - 这是国内源对第三方库同步(完整度和速度)的问题。 - - ```shell - # 1.首先查看 pypi 上的版本信息 - # 如果输出的 latest 版本信息非最新，说明你的 pip 的 pypi 源还未同步，可选择“科学上网”或手动安装。 - pip index versions ayugespidertools - - # 1.1. 若你可以科学访问，安装只需指定 pypi 官方源即可： - pip install ayugespidertools -i https://pypi.org/simple - - # 1.2. 若访问受限，则需要手动安装： - # 先到 https://pypi.org/project/AyugeSpiderTools/#files 或 https://github.com/shengchenyang/AyugeSpiderTools/releases 下载 whl 文件 - # 然后 pip 安装此 whl 即可 - pip install ayugespidertools-x.x.x-py3-none-any.whl[database] -i https://mirrors.aliyun.com/pypi/simple/ - # zsh 中的命令同样需要修改 - pip install 'ayugespidertools-x.x.x-py3-none-any.whl[database]' -i https://mirrors.aliyun.com/pypi/simple/ - ``` - -- 无法查找到 `ayugespidertools` - - 这也是国内源的完整度问题，推荐优先配置为阿里云源或者清华大学源即可，若还不行请切换到官方源。 - - 报错详情如下： - - ```shell - ERROR: Could not find a version that satisfies the requirement ayugespidertools (from versions: none) - ERROR: No matching distribution found for ayugespidertools - ``` - - 解决方法如下： - - ```shell - pip install ayugespidertools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com - # 或者使用官方源： - pip install ayugespidertools -i https://pypi.org/simple - ``` - -- 可能存在的兼容问题 - - 特别是 `Apple Silicon MacOS` 的较新系统场景，若遇到安装问题，可先尝试单独安装 `Scrapy`，若问题依然存在则可排除本库的问题。 - - 报错示例如下： - - ```shell - ImportError: dlopen(/Users/runner/work/AyugeSpiderTools/AyugeSpiderTools/.tox/py/lib/python3.8/site-packages/lxml/etree.cpython-38-darwin.so, 0x0002): symbol not found in flat namespace '_exsltDateXpathCtxtRegister' - /Users/runner/work/AyugeSpiderTools/AyugeSpiderTools/.tox/py/lib/python3.8/site-packages/coverage/control.py:887: CoverageWarning: No data was collected. (no-data-collected) - ``` - - 解决方法如下： - - 可能出现兼容问题的库有：`lxml`, `urllib3`, `twisted` 等，可通过手动安装未报错的依赖版本，或升级 `Python Patch` 版本来快速解决。 - - 如遇到此类问题，请提 `issue` 反馈，我会更新依赖库版本。 - -若遇到其它的各种问题，请提 [issues](https://github.com/shengchenyang/AyugeSpiderTools/issues/new/choose)。 - -### 值得知道的事情 - -- `ayugespidertools` 是依赖于 `Scrapy` 开发的，对其在爬虫开发中遇到的常用操作进行扩展。 -- 可以从最新源码中构建，构建方法请参考本文 [How-To-Build-Your-Own-Library](../diy/myself.md) 部分。 - -### 使用虚拟环境（推荐） - -建议在所有平台上的虚拟环境中安装此库。 - -有关如何创建虚拟环境的信息，请参阅[虚拟环境和包](https://docs.python.org/3/tutorial/venv.html#tut-venv)。 diff --git a/docs/intro/install.rst b/docs/intro/install.rst new file mode 100644 index 0000000..9e42022 --- /dev/null +++ b/docs/intro/install.rst @@ -0,0 +1,131 @@ +.. _intro-install: + +========== +安装指南 +========== + +支持的 Python 版本 +=================== + +AyugeSpiderTools 需要 Python 3.9+，在 AyugeSpiderTools 3.10.1 之后的版本不再支持 python 3.8。 + +安装 AyugeSpiderTools +======================= + + 可以使用以下命令安装 ayugespidertools 及其依赖项： + +1. 若你的数据库场景只需要 mysql 和 mongodb，且不需要本库 extras 中的扩展功能，那么直接简洁安装即可，\ +命令如下： + +.. code:: bash + + pip install ayugespidertools + +2. 若你需要更多的数据库场景，且同样不需要本库 extras 中的扩展功能，那么安装数据库版本最好，命令如下： + +.. code:: bash + + pip install ayugespidertools[database] + +3. 安装全部依赖命令如下： + +.. code:: bash + + pip install ayugespidertools[all] + +4. 安装预发布(开发)版本，通过源码安装： + +.. code:: bash + + # 请注意，此源码方式安装的是开发版本，请勿在正式场景中使用！ + pip install git+https://github.com/shengchenyang/AyugeSpiderTools.git + +注意：若你只需要 scrapy 扩展库的简单功能，那么默认的简洁依赖安装即可；一些可选择的开发功能（都会放在 extras\ +部分）若要使用，请使用完整安装。 + +强烈建议您将 ayugespidertools 安装在专用的 virtualenv 中，以避免与您的系统包发生冲突。 + +可能遇到的问题 +--------------- + + 在安装时可能会遇到以下问题： + +- zsh: no matches found: ayugespidertools[database] + +.. code:: bash + + # zsh 中需要修改对应的命令 + pip install 'ayugespidertools[database]' + pip install 'ayugespidertools[all]' + +- 无法安装到最新版本 + +这是国内源对第三方库同步(完整度和速度)的问题。 +:: + + # 1.首先查看 pypi 上的版本信息 + # 如果输出的 latest 版本信息非最新，说明你的 pip 的 pypi 源还未同步，可选择“科学上网”或手动安装。 + pip index versions ayugespidertools + + # 1.1. 若你可以科学访问，安装只需指定 pypi 官方源即可： + pip install ayugespidertools -i https://pypi.org/simple + + # 1.2. 若访问受限，则需要手动安装： + # 先到 https://pypi.org/project/AyugeSpiderTools/#files 或 + # https://github.com/shengchenyang/AyugeSpiderTools/releases 下载 whl 文件 + # 然后 pip 安装此 whl 即可 + pip install ayugespidertools-x.x.x-py3-none-any.whl[database] -i https://mirrors.aliyun.com/pypi/simple/ + # zsh 中的命令同样需要修改 + pip install 'ayugespidertools-x.x.x-py3-none-any.whl[database]' -i https://mirrors.aliyun.com/pypi/simple/ + +- 无法查找到 ayugespidertools + + 这也是国内源的完整度问题，推荐优先配置为阿里云源或者清华大学源即可，若还不行请切换到官方源。 + +报错详情如下： +:: + + ERROR: Could not find a version that satisfies the requirement ayugespidertools (from versions: none) + ERROR: No matching distribution found for ayugespidertools + +解决方法如下： +:: + + pip install ayugespidertools -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com + # 或者使用官方源： + pip install ayugespidertools -i https://pypi.org/simple + +- 可能存在的兼容问题 + + 特别是 Apple Silicon MacOS 的较新系统场景，若遇到安装问题，可先尝试单独安装 Scrapy，若问题依然存在\ + 则可排除本库的问题。 + +报错示例如下： +:: + + ImportError: dlopen(/Users/runner/work/AyugeSpiderTools/AyugeSpiderTools/.tox/py/lib/python3.8/site-packages/lxml/etree.cpython-38-darwin.so, 0x0002): symbol not found in flat namespace '_exsltDateXpathCtxtRegister' + /Users/runner/work/AyugeSpiderTools/AyugeSpiderTools/.tox/py/lib/python3.8/site-packages/coverage/control.py:887: CoverageWarning: No data was collected. (no-data-collected) + +解决方法如下： +:: + + 可能出现兼容问题的库有：lxml, urllib3, twisted 等，可通过手动安装未报错的依赖版本，或升级 Python\ + Patch 版本来快速解决。 + +若遇到其它的各种问题，请提 `issues`_ 反馈。 + +值得知道的事情 +---------------- + +- ayugespidertools 是依赖于 Scrapy 开发的，对其在爬虫开发中遇到的常用操作进行扩展。 +- 可以从最新源码中构建，构建方法请参考本文 :ref:`How-To-Build-Your-Own-Library ` 部分。 + +使用虚拟环境（推荐） +-------------------- + +建议在所有平台上的虚拟环境中安装此库。 + +有关如何创建虚拟环境的信息，请参阅 `虚拟环境和包`_ 部分。 + +.. _issues: https://github.com/shengchenyang/AyugeSpiderTools/issues/new/choose +.. _虚拟环境和包: https://docs.python.org/3/tutorial/venv.html#tut-venv diff --git a/docs/intro/overview.md b/docs/intro/overview.md deleted file mode 100644 index 65b3afb..0000000 --- a/docs/intro/overview.md +++ /dev/null @@ -1,175 +0,0 @@ -# AyugeSpiderTools 一目了然 - -[AyugeSpiderTools](https://github.com/shengchenyang/AyugeSpiderTools) 是 `Scrapy` 的功能扩展模块，对其 `spider`，`item`，`middleware`，`pipeline` 等模块中的常用功能进行模板化生成和配置。比如生成常见的 `spider` ，运行 `sh` 和 `settings` 配置等脚本和固定项目文件结构；也对其不同模块进行功能扩展，比如给 `spider` 挂上 `Mysql engine` 的单例句柄可用于 `yield` 入库前的去重方式之一，给 `pipeline` 添加自动生成 `Mysql` 存储场景下所依赖的数据库、数据表、数据字段及注释，也可以解决常见的（字段编码，`Data too long`，存储字段不存在等等）错误场景。还有很多功能，请在其 `Github` 上查看。 - -## 注意： - -**如果你觉得某些功能实现未达到你的期望，比如某些中间件或管道等的实现方法你有更好的方式，你完全可以自行修改和 `build`，让其成为你个人或小组中的专属库。你可以修改任何你觉得有必要的部分，包括库名在内，希望本库能给你在爬虫开发或 `scrapy` 扩展开发方面有所指引。** - -**当然，你也可以选择给此项目做出贡献，比如增加或优化某些功能等，但在此之前请提相关的 `ISSUES` 经确认后再开发和提交 `PULL REQUESTS`，以免不太符合本库场景或已废弃等原因造成你的贡献浪费，那就太可惜了！** - -## 示例蜘蛛的演练 - -为了向您展示 `ayugespidertools` 带来了什么，我们将带您通过一个 `Scrapy Spider` 示例，使用最简单的方式来运行蜘蛛。 - -> 先创建项目： - -```shell -# eg: 本示例使用的 project_name 为 DemoSpider - -ayuge startproject -``` - -> 创建爬虫脚本： - -```shell -进入项目根目录 -cd - -生成脚本 -ayuge genspider -``` - -下面是从 [ayugespidertools](https://ayugespidertools.readthedocs.io/en/latest/) 文档网页中抓取标题信息的蜘蛛代码： - -```python -from ayugespidertools.items import DataItem, AyuItem -from ayugespidertools.spiders import AyuSpider -from scrapy.http import Request -from sqlalchemy import text - - -class DemoOneSpider(AyuSpider): - name = "demo_one" - allowed_domains = ["readthedocs.io"] - start_urls = ["http://readthedocs.io/"] - custom_settings = { - # 数据库引擎开关，打开会有对应的 engine 和 engine_conn，可用于数据入库前去重判断 - "DATABASE_ENGINE_ENABLED": True, - "ITEM_PIPELINES": { - # 激活此项则数据会存储至 Mysql - "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, - # 开启记录项目相关运行统计信息 - "ayugespidertools.pipelines.AyuStatisticsMysqlPipeline": 301, - }, - } - - def start_requests(self): - yield Request( - url="https://ayugespidertools.readthedocs.io/en/latest/", - callback=self.parse_first, - ) - - def parse_first(self, response): - _save_table = "_octree_info" - - li_list = response.xpath('//div[@aria-label="Navigation menu"]/ul/li') - for curr_li in li_list: - octree_text = curr_li.xpath("a/text()").get() - octree_href = curr_li.xpath("a/@href").get() - - # NOTE: 数据存储方式 1，推荐此风格写法。 - octree_item = AyuItem( - octree_text=octree_text, - octree_href=octree_href, - _table=_save_table, - ) - - # NOTE: 数据存储方式 2，需要自动添加表字段注释时的写法。但不要风格混用。 - """ - octree_item = AyuItem( - # 这里也可以写为 octree_text = DataItem(octree_text)，但没有字段注释 - # 功能了，那不如使用 <数据存储方式 1> - octree_text=DataItem(octree_text, "标题"), - octree_href=DataItem(octree_href, "标题链接"), - _table=DataItem(_save_table, "项目列表信息"), - ) - """ - - # NOTE: 数据存储方式 3，当然也可以直接 yield dict - # 但 _table，_mongo_update_rule 等参数就没有 IDE 提示功能了 - """ - yield { - "octree_text": octree_text, - "octree_href": octree_href, - "_table": _save_table, - } - """ - self.slog.info(f"octree_item: {octree_item}") - - # 数据入库逻辑 -> 测试 mysql_engine / mysql_engine_conn 的去重功能。 - # 场景对应的 engine 和 engine_conn 也已经给你了，你可自行实现。以下给出示例： - - # 示例一：比如使用 sqlalchemy2 来实现查询如下： - if self.mysql_engine_conn: - try: - _sql = text( - f"select `id` from `{_save_table}` where `octree_text` = {octree_text!r} limit 1" - ) - result = self.mysql_engine_conn.execute(_sql).fetchone() - if not result: - self.mysql_engine_conn.rollback() - yield octree_item - else: - self.slog.debug(f'标题为 "{octree_text}" 的数据已存在') - except Exception: - self.mysql_engine_conn.rollback() - yield octree_item - else: - yield octree_item - - # 示例二：使用 pandas 来实现查询如下： - """ - try: - sql = f"select `id` from `{_save_table}` where `octree_text` = {octree_text!r} limit 1" - df = pandas.read_sql(sql, self.mysql_engine) - - # 如果为空，说明此数据不存在于数据库，则新增 - if df.empty: - yield octree_item - - # 如果已存在，1). 若需要更新，请自定义更新数据结构和更新逻辑；2). 若不用更新，则跳过即可。 - else: - self.slog.debug(f"标题为 ”{octree_text}“ 的数据已存在") - - except Exception as e: - if any(["1146" in str(e), "1054" in str(e), "doesn't exist" in str(e)]): - yield octree_item - else: - self.slog.error(f"请查看数据库链接或网络是否通畅！Error: {e}") - """ -``` - -### 刚刚发生了什么？ - -刚刚使用 `ayugespidertools` 创建了项目，并生成了具体的爬虫脚本示例。其爬虫脚本中的各种依赖（比如项目目录结构，配置信息等）在创建项目后就正常产生了，一般所需的配置信息（比如 `Mysql`，`MongoDB` 等）在项目的 `VIT` 目录下 `.conf` 文件中修改，不需要配置的不用理会它即可。 - -只要配置好 `.conf` 信息，就可以跑通以上示例。如果修改为新的项目，只需要修改上面示例中的 `spdider` 解析规则即可。 - -## 还有什么？ - -本库依赖 `Scrapy`，你可以使用 `Scrapy` 命令来管理你的项目，体会 `Scrapy` 的强大和方便。 - -`ayugespidertools` 根据 `scrapy` 的模板功能方便的创建示例脚本，比如： - -```shell -# 查看支持的脚本模板示例 -ayuge genspider -l - - -Available templates: - async - basic - crawl - csvfeed - xmlfeed - -# 使用具体的示例命令 -ayuge genspider -t - -eg: ayuge gendpier -t async demom_async baidu.com -``` - -## 下一步是什么？ - -接下来的步骤是[安装 AyugeSpiderTools](install.md)， 按照 [Scrapy 教程](https://docs.scrapy.org/en/latest/intro/tutorial.html#intro-tutorial)学习如何使用 `Scrapy` 并加入 [Scrapy 社区](https://scrapy.org/community/)。谢谢你的关注！ diff --git a/docs/intro/overview.rst b/docs/intro/overview.rst new file mode 100644 index 0000000..d872436 --- /dev/null +++ b/docs/intro/overview.rst @@ -0,0 +1,193 @@ +.. _intro-overview: + +=========================== +AyugeSpiderTools 一目了然 +=========================== + +`AyugeSpiderTools`_ 是 Scrapy 的功能扩展模块，对其 spider，item，middleware，pipeline 等模块中\ +的常用功能进行模板化生成和配置。比如生成常见的 spider，运行 sh 和 settings 配置等脚本和固定项目文件结\ +构；也对其不同模块进行功能扩展，比如给 spider 挂上 Mysql engine 的单例句柄可用于 yield 入库前的去重\ +方式之一，给 pipeline 添加自动生成 Mysql 存储场景下所依赖的数据库、数据表、数据字段及注释，也可以解决\ +常见的（字段编码，Data too long，存储字段不存在等的）错误场景。还有很多功能，请在其 Github 上查看。 + +**如果你觉得某些功能实现未达到你的期望，比如某些中间件或管道等的实现方法你有更好的方式，你完全可以自行修改\ +和 build，让其成为你个人或小组中的专属库。你可以修改任何你觉得有必要的部分，包括库名在内，希望本库能给你\ +在爬虫开发或 scrapy 扩展开发方面有所指引。** + +**当然，你也可以选择给此项目做出贡献，比如增加或优化某些功能等，但在此之前请提相关的 ISSUES 经确认后再开\ +发和提交 PULL REQUESTS，以免不太符合本库场景或已废弃等原因造成你的贡献浪费，那就太可惜了！** + +示例蜘蛛的演练 +=============== + +为了向您展示 ayugespidertools 带来了什么，我们将带您通过一个 Scrapy Spider 示例，使用最简单的方式来\ +运行蜘蛛。 + +先创建项目： +:: + + # eg: 本示例使用的 project_name 为 DemoSpider + ayuge startproject + +创建爬虫脚本： +:: + + 进入项目根目录 + cd + +生成脚本: +:: + + ayuge genspider + + +下面是从 `AyugeSpiderTools`_ 文档网页中抓取标题信息的蜘蛛代码： + +.. code-block:: python + + from ayugespidertools.items import DataItem, AyuItem + from ayugespidertools.spiders import AyuSpider + from scrapy.http import Request + from sqlalchemy import text + + + class DemoOneSpider(AyuSpider): + name = "demo_one" + allowed_domains = ["readthedocs.io"] + start_urls = ["http://readthedocs.io/"] + custom_settings = { + # 数据库引擎开关，打开会有对应的 engine 和 engine_conn，可用于数据入库前去重判断 + "DATABASE_ENGINE_ENABLED": True, + "ITEM_PIPELINES": { + # 激活此项则数据会存储至 Mysql + "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, + # 开启记录项目相关运行统计信息 + "ayugespidertools.pipelines.AyuStatisticsMysqlPipeline": 301, + }, + } + + def start_requests(self): + yield Request( + url="https://ayugespidertools.readthedocs.io/en/latest/", + callback=self.parse_first, + ) + + def parse_first(self, response): + _save_table = "_octree_info" + + li_list = response.xpath('//div[@aria-label="Navigation menu"]/ul/li') + for curr_li in li_list: + octree_text = curr_li.xpath("a/text()").get() + octree_href = curr_li.xpath("a/@href").get() + + # NOTE: 数据存储方式 1，推荐此风格写法。 + octree_item = AyuItem( + octree_text=octree_text, + octree_href=octree_href, + _table=_save_table, + ) + + # NOTE: 数据存储方式 2，需要自动添加表字段注释时的写法。但不要风格混用。 + """ + octree_item = AyuItem( + # 这里也可以写为 octree_text = DataItem(octree_text)，但没有字段注释 + # 功能了，那不如使用 <数据存储方式 1> + octree_text=DataItem(octree_text, "标题"), + octree_href=DataItem(octree_href, "标题链接"), + _table=DataItem(_save_table, "项目列表信息"), + ) + """ + + # NOTE: 数据存储方式 3，当然也可以直接 yield dict + # 但 _table，_mongo_update_rule 等参数就没有 IDE 提示功能了 + """ + yield { + "octree_text": octree_text, + "octree_href": octree_href, + "_table": _save_table, + } + """ + self.slog.info(f"octree_item: {octree_item}") + + # 数据入库逻辑 -> 测试 mysql_engine / mysql_engine_conn 的去重功能。 + # 场景对应的 engine 和 engine_conn 也已经给你了，你可自行实现。以下给出示例： + + # 示例一：比如使用 sqlalchemy2 来实现查询如下： + if self.mysql_engine_conn: + try: + _sql = text( + f"select `id` from `{_save_table}` where `octree_text` = {octree_text!r} limit 1" + ) + result = self.mysql_engine_conn.execute(_sql).fetchone() + if not result: + self.mysql_engine_conn.rollback() + yield octree_item + else: + self.slog.debug(f'标题为 "{octree_text}" 的数据已存在') + except Exception: + self.mysql_engine_conn.rollback() + yield octree_item + else: + yield octree_item + + # 示例二：使用 pandas 来实现查询如下： + """ + try: + sql = f"select `id` from `{_save_table}` where `octree_text` = {octree_text!r} limit 1" + df = pandas.read_sql(sql, self.mysql_engine) + + # 如果为空，说明此数据不存在于数据库，则新增 + if df.empty: + yield octree_item + + # 如果已存在，1). 若需要更新，请自定义更新数据结构和更新逻辑；2). 若不用更新，则跳过即可。 + else: + self.slog.debug(f"标题为 ”{octree_text}“ 的数据已存在") + + except Exception as e: + if any(["1146" in str(e), "1054" in str(e), "doesn't exist" in str(e)]): + yield octree_item + else: + self.slog.error(f"请查看数据库链接或网络是否通畅！Error: {e}") + """ + +刚刚发生了什么？ +---------------- + +刚刚使用 `ayugespidertools` 创建了项目，并生成了具体的爬虫脚本示例。其爬虫脚本中的各种依赖（比如项目目录结构，配置信息等）在创建项目后就正常产生了，一般所需的配置信息（比如 `Mysql`，`MongoDB` 等）在项目的 `VIT` 目录下 `.conf` 文件中修改，不需要配置的不用理会它即可。 + +只要配置好 `.conf` 信息，就可以跑通以上示例。如果修改为新的项目，只需要修改上面示例中的 `spdider` 解析规则即可。 + +还有什么？ +=========== + +本库依赖 Scrapy，你可以使用 Scrapy 命令来管理你的项目，体会 Scrapy 的强大和方便。 + +ayugespidertools 根据 scrapy 的模板功能方便的创建示例脚本，比如： +:: + + # 查看支持的脚本模板示例 + ayuge genspider -l + + + Available templates: + async + basic + crawl + csvfeed + xmlfeed + + # 使用具体的示例命令 + ayuge genspider -t + + eg: ayuge gendpier -t async demom_async baidu.com + +下一步是什么？ +============== + +接下来的步骤是 :ref:`安装 AyugeSpiderTools `， 按照 `Scrapy 教程`_ 学习如何使用 Scrapy 并加\ +入 `Scrapy 社区`_ 。谢谢你的关注！ + +.. _AyugeSpiderTools: https://github.com/shengchenyang/AyugeSpiderTools +.. _Scrapy 教程: https://docs.scrapy.org/en/latest/intro/tutorial.html#intro-tutorial +.. _Scrapy 社区: https://scrapy.org/community/ diff --git a/docs/intro/tutorial.md b/docs/intro/tutorial.md deleted file mode 100644 index c4d0620..0000000 --- a/docs/intro/tutorial.md +++ /dev/null @@ -1,119 +0,0 @@ -# AyugeSpiderTools 教程 - -在本教程中，我们假设您的系统上已经安装了 `ayugespidertools`。 - -> 我们要抓取 [ayugespidertools readthedocs](https://ayugespidertools.readthedocs.io/en/latest/) 的网页内容，这是本库的文档网站。 -> - -本教程将引导您完成这些任务： - -- 创建一个新的 `Scrapy` 项目 -- 编写爬虫来抓取站点并提取数据 -- 使用命令行导出抓取的数据 -- 更改蜘蛛以递归地跟踪链接 -- 使用蜘蛛参数 - -## 创建项目 - -在开始抓取之前，您必须设置一个新的 `ayugespidertools` 项目。输入您要存储代码的目录并运行： - -```shell -ayuge startproject DemoSpider -``` - -这将创建一个 `DemoSpider` 包含以下内容的目录： - -通常情况下，我们只需关心 `spider` 的编写和 `VIT` 中 `.conf` 的配置即可。 - -```ini -DemoSpider/ -|-- DemoSpider # project's Python module, you'll import your code from here -| |-- __init__.py -| |-- items.py # project items definition file -| |-- logs # 日志管理文件夹，可以自定义规则 -| | |-- DemoSpider.log # scrapy 输出日志，文件名称为项目名 -| | |-- error.log # loguru 日志 error 规则输出文件 -| |-- middlewares.py # project middlewares definition file -| |-- pipelines.py # project pipelines definition file -| |-- settings.py # project settings definition file -| |-- spiders # a directory where you'll later put your spiders -| | |-- __init__.py -| `-- VIT -| `-- .conf # 配置文件，用于设置 Mysql, MongoDB 等配置 -`-- scrapy.cfg # deploy configuration file -``` - -## 我们的第一个 Spider - -这是我们第一个 `Spider` 的代码 `demo_one.py` ，将其保存在项目目录下命名的文件 `DemoSpider/spiders`中： - -```python -from ayugespidertools.items import AyuItem -from ayugespidertools.spiders import AyuSpider -from scrapy.http import Request - - -class DemoOneSpider(AyuSpider): - name = "demo_one" - allowed_domains = ["readthedocs.io"] - start_urls = ["http://readthedocs.io/"] - custom_settings = { - # 打开 mysql 引擎开关，用于数据入库前更新逻辑判断 - "DATABASE_ENGINE_ENABLED": True, - "ITEM_PIPELINES": { - # 激活此项则数据会存储至 Mysql - "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, - # 激活此项则数据会存储至 MongoDB - "ayugespidertools.pipelines.AyuFtyMongoPipeline": 301, - }, - } - - def start_requests(self): - yield Request( - url="https://ayugespidertools.readthedocs.io/en/latest/", - callback=self.parse_first, - ) - - def parse_first(self, response): - _save_table = "_octree_info" - - li_list = response.xpath('//div[@aria-label="Navigation menu"]/ul/li') - for curr_li in li_list: - octree_text = curr_li.xpath("a/text()").get() - octree_href = curr_li.xpath("a/@href").get() - - octree_item = AyuItem( - octree_text=octree_text, - octree_href=octree_href, - _table=_save_table, - ) - self.slog.info(f"octree_item: {octree_item}") - yield octree_item -``` - -如您所见，`Spider` 子类化 `AyuSpider` 并定义了一些属性和方法： - -- `name`: 标识蜘蛛。在一个项目中必须是唯一的，即不能为不同的 `Spiders` 设置相同的名字。 -- `start_requests()`: 必须返回一个可迭代的请求（你可以返回一个请求列表或编写一个生成器函数），蜘蛛将从中开始爬行。后续请求将从这些初始请求中依次生成。 -- `parse_first()`：将被调用以处理为每个请求下载的响应的方法。`response` 参数是 `TextResponse` 的一个实例，它保存页面内容，并有进一步的有用方法来处理它。该 `parse_first()` 方法通常解析响应，将抓取的数据提取为字典，并找到要遵循的新 `URL` 并从中创建新请求 ( `Request`)。 - -另外，一些其它注意事项： - -- 示例中的一些配置和一些功能并不是每个项目中都必须要编写和配置的，只是用于展示一些功能； -- 据上条可知，可以写出很简洁的代码，删除你认为的无关配置和方法并将其配置成你自己的模板就更容易适配更多人的使用场景。 - - -### 如何运行我们的蜘蛛 - -要让我们的蜘蛛工作，请转到项目的顶级目录并运行： - -```shell -# 本身就是 scrapy 的项目，所以可以使用 scrapy 可以执行的任何形式即可 -scrapy crawl demo_one - -# 或者执行项目根目录下的 run.py(需要编辑自己需要执行的脚本) -python run.py - -# 或者执行项目根目录下的 run.sh，其实它也是通过调用 run.py 来执行的。只不过 shell 文件中包含了虚拟环境的 activate 了而已 -sh run.sh -``` diff --git a/docs/intro/tutorial.rst b/docs/intro/tutorial.rst new file mode 100644 index 0000000..4ee240b --- /dev/null +++ b/docs/intro/tutorial.rst @@ -0,0 +1,130 @@ +.. _intro-tutorial: + +======================= +AyugeSpiderTools 教程 +======================= + +在本教程中，我们假设您的系统上已经安装了 ayugespidertools。 + + 我们要抓取 `ayugespidertools readthedocs`_ 的网页内容，这是本库的文档网站。 + +本教程将引导您完成这些任务： + +- 创建一个新的 Scrapy 项目 +- 编写爬虫来抓取站点并提取数据 +- 使用命令行导出抓取的数据 +- 更改蜘蛛以递归地跟踪链接 +- 使用蜘蛛参数 + +创建项目 +========== + +在开始抓取之前，您必须设置一个新的 ayugespidertools 项目。输入您要存储代码的目录并运行： + +.. code:: bash + + ayuge startproject DemoSpider + +这将创建一个 DemoSpider 包含以下内容的目录： + +通常情况下，我们只需关心 spider 的编写和 VIT 中 .conf 的配置即可。 +:: + + DemoSpider/ + |-- DemoSpider # project's Python module, you'll import your code from here + | |-- __init__.py + | |-- items.py # project items definition file + | |-- logs # 日志管理文件夹，可以自定义规则 + | | |-- DemoSpider.log # scrapy 输出日志，文件名称为项目名 + | | |-- error.log # loguru 日志 error 规则输出文件 + | |-- middlewares.py # project middlewares definition file + | |-- pipelines.py # project pipelines definition file + | |-- settings.py # project settings definition file + | |-- spiders # a directory where you'll later put your spiders + | | |-- __init__.py + | `-- VIT + | `-- .conf # 配置文件，用于设置 Mysql, MongoDB 等配置 + `-- scrapy.cfg # deploy configuration file + +我们的第一个 Spider +=================== + +这是我们第一个 Spider 的代码 demo_one.py，将其保存在项目目录下命名的文件 DemoSpider/spiders 中： + +.. code-block:: python + + from ayugespidertools.items import AyuItem + from ayugespidertools.spiders import AyuSpider + from scrapy.http import Request + + + class DemoOneSpider(AyuSpider): + name = "demo_one" + allowed_domains = ["readthedocs.io"] + start_urls = ["http://readthedocs.io/"] + custom_settings = { + # 打开 mysql 引擎开关，用于数据入库前更新逻辑判断 + "DATABASE_ENGINE_ENABLED": True, + "ITEM_PIPELINES": { + # 激活此项则数据会存储至 Mysql + "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, + # 激活此项则数据会存储至 MongoDB + "ayugespidertools.pipelines.AyuFtyMongoPipeline": 301, + }, + } + + def start_requests(self): + yield Request( + url="https://ayugespidertools.readthedocs.io/en/latest/", + callback=self.parse_first, + ) + + def parse_first(self, response): + _save_table = "_octree_info" + + li_list = response.xpath('//div[@aria-label="Navigation menu"]/ul/li') + for curr_li in li_list: + octree_text = curr_li.xpath("a/text()").get() + octree_href = curr_li.xpath("a/@href").get() + + octree_item = AyuItem( + octree_text=octree_text, + octree_href=octree_href, + _table=_save_table, + ) + self.slog.info(f"octree_item: {octree_item}") + yield octree_item + +如您所见，Spider 子类化 AyuSpider 并定义了一些属性和方法： + +- name: 标识蜘蛛。在一个项目中必须是唯一的，即不能为不同的 Spiders 设置相同的名字。 +- start_requests(): 必须返回一个可迭代的请求（你可以返回一个请求列表或编写一个生成器函数），蜘蛛将从中\ + 开始爬行。后续请求将从这些初始请求中依次生成。 +- parse_first()：将被调用以处理为每个请求下载的响应的方法。response 参数是 TextResponse 的一个实例，\ + 它保存页面内容，并有进一步的有用方法来处理它。该 parse_first() 方法通常解析响应，将抓取的数据提取为字\ + 典，并找到要遵循的新 URL 并从中创建新请求 (Request)。 + +另外，一些其它注意事项： + +- 示例中的一些配置和一些功能并不是每个项目中都必须要编写和配置的，只是用于展示一些功能； +- 据上条可知，可以写出很简洁的代码，删除你认为的无关配置和方法并将其配置成你自己的模板就更容易适配更多人的\ + 使用场景。 + + +如何运行我们的蜘蛛 +------------------ + +要让我们的蜘蛛工作，请转到项目的顶级目录并运行： +:: + + # 本身就是 scrapy 的项目，所以可以使用 scrapy 可以执行的任何形式即可 + scrapy crawl demo_one + + # 或者执行项目根目录下的 run.py(需要编辑自己需要执行的脚本) + python run.py + + # 或者执行项目根目录下的 run.sh，其实它也是通过调用 run.py 来执行的。只不过 shell 文件中包含了虚拟 + # 环境的 activate 了而已 + sh run.sh + +.. _ayugespidertools readthedocs: https://ayugespidertools.readthedocs.io/en/latest/ diff --git a/docs/topics/commands.md b/docs/topics/commands.md deleted file mode 100644 index 1c92c38..0000000 --- a/docs/topics/commands.md +++ /dev/null @@ -1,161 +0,0 @@ -# 命令行工具 - -`AyugeSpiderTools` 是直接使用 `scrapy` 命令行工具来控制的，这里简称为 `AyugeSpiderTools工具`，以区别于我们简称为“命令”或“Scrapy命令”的子命令。 - -`AyugeSpiderTools` 工具只提供了常用的几个命令，用于多种用途，每个命令都接受一组不同的参数和选项。但是，其它缺失的命令你可以直接使用 `Scrapy` 的即可。 - -## 配置设置 - -未改变，也是在在标准位置的 `ini` 样式文件中查找配置参数`scrapy.cfg`： - -这些文件中的设置按列出的优先顺序合并：用户定义的值比系统范围的默认值具有更高的优先级，并且项目范围的设置将在定义时覆盖所有其他设置。 - -## AyugeSpiderTools 项目的默认结构 - -在深入研究命令行工具及其子命令之前，让我们先了解一下项目的目录结构。 - -虽然可以修改，但是所有的项目默认都有相同的文件结构，类似这样： - -```shell -|-- DemoSpider -| |-- __init__.py -| |-- items.py -| |-- logs -| | |-- DemoSpider.log -| | `-- error.log -| |-- middlewares.py -| |-- pipelines.py -| |-- settings.py -| |-- spiders -| | |-- __init__.py -| | `-- spider1.py -| `-- VIT -| `-- .conf -`-- scrapy.cfg -``` - -文件所在的目录 `scrapy.cfg` 称为*项目根目录*。该文件包含定义项目设置的 `python` 模块的名称。这是一个例子： - -```shell -[settings] -default = DemoSpider.settings -``` - -## 使用 AyugespiderTools 工具 - -您可以先运行不带参数的 `AyugeSpiderTools` 工具，它会打印一些使用帮助和可用的命令： - -命令如下： - -```shell -ayuge -h -``` - -输出示例如下： - -```shell -AyugeSpiderTools 3.0.1 - no active project - -Usage: - ayuge [options] [args] - -Available commands: - genspider Generate new spider using pre-defined templates - startproject Create new project - version Print AyugeSpiderTools version - - [ more ] More commands available when run from project directory - -Use "ayuge -h" to see more info about a command -``` - -### 创建项目 - -您通常使用该工具做的第一件事是创建您的项目： - -```shell -ayuge startproject myproject [project_dir] -``` - -这将在该目录下创建一个 `Scrapy` 项目 `project_dir`。如果 `project_dir` 未指定，则项目目录将与 `myproject` 相同。 - -接下来，进入新项目目录： - -```shell -cd project_dir -``` - -您已准备好使用该命令从那里管理和控制您的项目。 - -### 控制项目 - -您可以使用项目内部的工具来控制和管理它们。 - -例如，要创建一个新的蜘蛛： - -```shell -ayuge genspider mydomain mydomain.com -``` - -## 启动项目 - -- 句法：`ayuge startproject [project_dir]` -- 需要项目：*无* - -在 `project dir` 目录下创建一个名为 `project_name` 的新项目。如果未指定项目目录，则项目目录将与项目名称相同。 - -使用示例： - -```shell -ayuge startproject myproject -``` - -## 可用的工具命令 - -本节包含可用内置命令的列表以及说明和一些用法示例。请记住，您始终可以通过运行以下命令获取有关每个命令的更多信息： - -```shell -ayuge -h -``` - -您可以使用以下命令查看所有可用命令： - -```shell -ayuge -h -``` - -### 启动项目 - -- 句法：`ayuge startproject [project_dir]` -- 需要项目：*无* - -在 `project dir` 目录下创建一个名为 `project name` 的新项目。如果未指定项目目录，则项目目录将与项目名称相同。 - -使用示例： - -```shell -ayuge startproject myproject -``` - -### genspider - -- 句法：`ayuge genspider [-t template] ` -- 需要项目：*无* - -使用示例： - -```shell -$ ayuge genspider -l -Available templates: - async - basic - crawl - csvfeed - xmlfeed - -$ ayuge genspider example example.com -Created spider 'example' using template 'basic' - -$ ayuge genspider -t crawl scrapyorg scrapy.org -Created spider 'scrapyorg' using template 'crawl' -``` diff --git a/docs/topics/commands.rst b/docs/topics/commands.rst new file mode 100644 index 0000000..24865bd --- /dev/null +++ b/docs/topics/commands.rst @@ -0,0 +1,174 @@ +.. _topics-commands: + +=========== +命令行工具 +=========== + +AyugeSpiderTools 是直接使用 scrapy 命令行工具来控制的，这里简称为 AyugeSpiderTools 工具，以区别于\ +我们简称为“命令”或“Scrapy命令”的子命令。 + +AyugeSpiderTools 工具只提供了常用的几个命令，用于多种用途，每个命令都接受一组不同的参数和选项。但是，其\ +它缺失的命令你可以直接使用 Scrapy 的即可。 + +配置设置 +========== + +未改变，也是在在标准位置的 ini 样式文件中查找配置参数 scrapy.cfg： + +这些文件中的设置按列出的优先顺序合并：用户定义的值比系统范围的默认值具有更高的优先级，并且项目范围的设置将\ +在定义时覆盖所有其他设置。 + +AyugeSpiderTools 项目的默认结构 +================================ + +在深入研究命令行工具及其子命令之前，让我们先了解一下项目的目录结构。 + +虽然可以修改，但是所有的项目默认都有相同的文件结构，类似这样： +:: + + |-- DemoSpider + | |-- __init__.py + | |-- items.py + | |-- logs + | | |-- DemoSpider.log + | | `-- error.log + | |-- middlewares.py + | |-- pipelines.py + | |-- settings.py + | |-- spiders + | | |-- __init__.py + | | `-- spider1.py + | `-- VIT + | `-- .conf + `-- scrapy.cfg + +文件所在的目录 scrapy.cfg 称为项目根目录。该文件包含定义项目设置的 python 模块的名称。这是一个例子： + +.. code:: bash + + [settings] + default = DemoSpider.settings + +使用 AyugespiderTools 工具 +============================ + +您可以先运行不带参数的 AyugeSpiderTools 工具，它会打印一些使用帮助和可用的命令： + +命令如下： + +.. code:: bash + + ayuge -h + +输出示例如下： +:: + + AyugeSpiderTools 3.0.1 - no active project + + Usage: + ayuge [options] [args] + + Available commands: + genspider Generate new spider using pre-defined templates + startproject Create new project + version Print AyugeSpiderTools version + + [ more ] More commands available when run from project directory + + Use "ayuge -h" to see more info about a command + +创建项目 +------------ + +您通常使用该工具做的第一件事是创建您的项目： + +.. code:: bash + + ayuge startproject myproject [project_dir] + +这将在该目录下创建一个 Scrapy 项目 project_dir。如果 project_dir 未指定，则项目目录将与 myproject 相同。 + +接下来，进入新项目目录： + +.. code:: bash + + cd project_dir + +您已准备好使用该命令从那里管理和控制您的项目。 + +控制项目 +------------ + +您可以使用项目内部的工具来控制和管理它们。 + +例如，要创建一个新的蜘蛛： + +.. code:: bash + + ayuge genspider mydomain mydomain.com + +启动项目 +========== + +- 句法：ayuge startproject [project_dir] +- 需要项目：*无* + +在 project dir 目录下创建一个名为 project_name 的新项目。如果未指定项目目录，则项目目录将与项目名称相同。 + +使用示例： + +.. code:: bash + + ayuge startproject myproject + +可用的工具命令 +=============== + +本节包含可用内置命令的列表以及说明和一些用法示例。请记住，您始终可以通过运行以下命令获取有关每个命令的更多信息： + +.. code:: bash + + ayuge -h + +您可以使用以下命令查看所有可用命令： + +.. code:: bash + + ayuge -h + +启动项目 +------------ + +- 句法：ayuge startproject [project_dir] +- 需要项目：*无* + +在 project dir 目录下创建一个名为 project name 的新项目。如果未指定项目目录，则项目目录将与项目名称相同。 + +使用示例： + +.. code:: bash + + ayuge startproject myproject + +genspider +--------- + +- 句法：ayuge genspider [-t template] +- 需要项目：*无* + +使用示例： +:: + + $ ayuge genspider -l + Available templates: + async + basic + crawl + csvfeed + xmlfeed + + $ ayuge genspider example example.com + Created spider 'example' using template 'basic' + + $ ayuge genspider -t crawl scrapyorg scrapy.org + Created spider 'scrapyorg' using template 'crawl' diff --git a/docs/topics/configuration.md b/docs/topics/configuration.md deleted file mode 100644 index 504320f..0000000 --- a/docs/topics/configuration.md +++ /dev/null @@ -1,223 +0,0 @@ -# Configuration - -`AyugeSpiderTools` 将项目中所依赖的敏感配置信息放入了当前项目的 `VIT` 下的 `.conf` 文件中独立管理。 - -当然，你也可以在项目中自定义 `VIT_DIR` 参数来决定配置文件 `.conf` 的路径。 - -若你有很多的 `Scrapy` 项目需要统一管理，可以选择以下方式： - -- 如果是单机多项目的情况，你可以指定 `VIT_DIR` 参数为此机器上的统一地址即可。 - -- 如果是多机多项目的情况，更推荐使用本库的 `consul` 或 `nacos` 服务来远程配置和管理，灵活性更高。 - -下面来介绍 `.conf` 文件中的配置内容： - -## Introduction - -配置格式使用 `ini`。 - -## [nacos] - -[nacos](https://nacos.io) 可用于远程配置管理服务，可以更敏捷和容易地管理微服务平台。 - -| 参数名 | 参数备注 | 描述 | -| ------ | ------------------------ | ------------------------------------------------------------ | -| url | _ | nacos 服务对应的链接，若有鉴权参数请在 url 中构建。 | -| format | 参数可选 json, xml, yaml | nacos url 配置中对应的格式解析方法，支持 json，xml，yaml 解析。请优先使用 json 和 xml 来解析，yaml 解析需要安装 ayugespidertools[all] 依赖。 | - -## [consul] - -[consul](https://consul.io) 的配置管理功能同 `nacos`，是本库提供的另一选择。但请注意：`consul` 比 `nacos` 的优先级更高，如果两者都配置了会优先使用 `consul` 配置。 - -不同的是配置中的鉴权 `token` 参数独立了出来。 - -| 参数名 | 参数备注 | 描述 | -| ------ | ----------------------------- | ------------------------------------------------------------ | -| url | _ | consul 服务对应的链接。 | -| format | 参数可选 json, xml, yaml, hcl | consul url 配置中对应的格式解析方法，支持 json，xml，yaml，hcl 解析，推荐 json 解析格式。hcl 和 yaml 解析需要安装 ayugespidertools[all] 依赖。 | -| token | 可选，默认空 | consul token 参数。 | - -## [mysql] - -用于 `mysql` 存储相关场景中使用，比如创建对应的 `sqlalchemy` 的 `engine`，`engine_conn` 来用于去重，创建数据库连接来解决表格缺失，字段缺失等问题。 - -| 参数名 | 参数备注 | 描述 | -| ----------- | ----------------------------- | ------------------------------------------------------------ | -| user | _ | _ | -| password | _ | _ | -| database | _ | 链接的数据库名称，在非 aiomysql 场景下，当 database 不存在时会用当前 user 创建所需库表及字段等。 | -| host | 可选，默认 localhost | _ | -| port | 可选，默认 3306 | _ | -| engine | 可选，默认 InnoDB | 自动创建数据库和数据表时需要的参数 | -| collate | 可选，默认 utf8mb4_general_ci | 自动创建数据库和数据表时需要的参数 | -| charset | 可选，默认 utf8mb4 | 自动创建数据库和数据表时需要的参数 | -| odku_enable | 可选，默认 false | 是否开启 ON DUPLICATE KEY UPDATE 功能 | - -注： - -- `charset` 参数选择有 `utf8mb4`，`gbk`，`latin1`，`utf16`，`utf16le`，`cp1251`，`euckr`，`greek`，`charset` 要与 `collate` 参数匹配。 -- 其中 `engine`，`charset`，`collate` 为自动创建数据库和数据表时需要的参数，可随意配置或默认即可，也可提前手动创建好表，也可后续手动修改。 - -## [mongodb:uri] - -`mongodb` 链接的 `uri` 配置方式。 - -| 参数名 | 参数备注 | 描述 | -| ------ | -------- | ----------- | -| uri | _ | mongoDB uri | - -## [mongodb] - -`mongodb` 链接的普通方式，`[mongodb:uri]` 和 `[mongodb]` 按需选择一种即可。 若两种都设置了，会优先从 `mongodb:uri` 中获取配置。 - -| 参数名 | 参数备注 | 描述 | -| ------------- | ---------------------- | ---- | -| database | _ | _ | -| user | _ | _ | -| password | _ | _ | -| host | 可选，默认 localhost | _ | -| port | 可选，默认 27017 | _ | -| authsource | 可选，默认 admin | _ | -| authMechanism | 可选，默认 SCRAM-SHA-1 | _ | - -## [postgresql] - -用于 `postgresql` 存储相关场景中使用，比如创建对应的 `sqlalchemy` 的 `engine`，`engine_conn` 来用于去重，创建数据库连接来解决表格缺失，字段缺失等问题。 - -| 参数名 | 参数备注 | 描述 | -| -------- | -------------------- | ------------------------------------------------------------ | -| user | _ | _ | -| password | _ | _ | -| database | _ | _ | -| host | 可选，默认 localhost | _ | -| port | 可选，默认 5432 | _ | -| charset | 可选，默认 UTF8 | 同 mysql 一样，用于在表不存在而创建时需要，可随意配置，后续也可手动修改。 | - -## [elasticsearch] - -用于 `elasticsearch` 存储相关场景中使用，也具有对应的 `es_engine`，`es_engine_conn` 来用于存储前的去重(查询及更新等自定义)逻辑。 - -| 参数名 | 参数备注 | 描述 | -| ---------------------- | ----------------------------------------- | ------------------------------------------------------------ | -| hosts | _ | 若有多个，用逗号分隔，比如 https://x.x.x.x:9200,https://x.x.x.x:9201 | -| index_class | 默认 {"settings":{"number_of_shards": 2}} | es Document 中的配置 | -| user | 默认 elastic | _ | -| password | 默认 elastic | _ | -| init | 是否初始化 es Document，默认 false | 是否创建 es 索引，此设置一般只在第一次运行项目时打开，或者选择手动创建并配置此参数永远为 false。 | -| verify_certs | 默认 false | 证书验证，推荐开启 | -| ca_certs | 默认 None | ca_certs 路径 | -| client_cert | 默认 None | client_cert 路径 | -| client_key | 默认 None | client_key 路径 | -| ssl_assert_fingerprint | 默认 None | es 启动中的 HTTP CA certificate SHA-256 fingerprint 参数 | - -注： - -- `ca_certs`，`client_cert`，`client_key`，`ssl_assert_fingerprint` 中只用配置一个即可，若 `verify_certs` 设置为 `false` 则都不用配置以上参数，但推荐开启此参数。 -- `index_class` 配置中不建议包含 `name` 参数，而是通过 `AyuItem` 中的 `_table` 来设置，`AyuItem` 会覆盖 `index_class` 中的 `name` 配置。 - -## [mq] - -推送到 `RabbitMQ` 场景所需的参数。以下配置参数与 `pika` 中一致，这里放入 [pika 文档](https://pika.readthedocs.io/en/stable/)，请自行对照查看。 - -| 参数名 | 参数备注 | 描述 | -| ----------- | -------------------- | ---- | -| virtualhost | _ | _ | -| queue | _ | _ | -| exchange | _ | _ | -| routing_key | _ | _ | -| username | 可选，默认 guest | _ | -| password | 可选，默认 guest | _ | -| host | 可选，默认 localhost | _ | -| port | 可选，默认 5672 | _ | - -## [oracle] - -用于 `oracle` 存储相关场景中使用，比如创建对应的 `sqlalchemy` 的 `engine`，`engine_conn` 来用于去重，但不会处理数据库表及字段缺失等错误，请提前创建好，因为其部分报错不如 `mysql` 及 `postgresql` 那样清晰明了，虽然也能解决，但必要性不高。 - -| 参数名 | 参数备注 | 描述 | -| ------------- | -------------------- | ------------------------------------------- | -| user | _ | _ | -| password | _ | _ | -| service_name | _ | _ | -| host | 可选，默认 localhost | _ | -| port | 可选，默认 1521 | _ | -| encoding | 可选，默认 utf8 | oracledb 的链接参数。 | -| thick_lib_dir | 可选，默认 false | oracledb 的 thick_mode 所需参数，按需配置。 | - -## [kafka] - -推送到 `kafka` 场景所需的参数。以下配置参数与 `kafka-python` 中一致，这里放入 [kafka-python 文档](https://kafka-python.readthedocs.io/en/master/)，请自行对照查看。 - -| 参数名 | 参数备注 | 描述 | -| ----------------- | -------- | ---------------------------------------------------- | -| bootstrap_servers | _ | 若有多个，用逗号分隔。比如 x.x.x.x:9092,x.x.x.x:9093 | -| topic | _ | _ | -| key | _ | _ | - -## [kdl_dynamic_proxy] - -快代理动态代理配置参数。 - -| 参数名 | 参数备注 | 描述 | -| -------- | -------- | -------------------- | -| proxy | _ | 快代理动态代理 api。 | -| username | _ | _ | -| password | _ | _ | - -## [kdl_exclusive_proxy] - -快代理独享代理配置参数。 - -| 参数名 | 参数备注 | 描述 | -| -------- | ------------ | -------------------------- | -| proxy | _ | 快代理独享代理 api。 | -| username | _ | _ | -| password | _ | _ | -| index | 可选，默认 1 | 表示取其索引值对应的代理。 | - -## [oss:ali] - -上传到阿里云 oss 的配置参数。 - -| 参数名 | 参数备注 | 描述 | -| -------------------- | ---------------------------- | ------------------------------------------------------------ | -| access_key | _ | 阿里云 access_key_id | -| access_secret | _ | 阿里云账号对应的 access_key_secret | -| endpoint | _ | 填写 Bucket 所在地域对应的 Endpoint | -| bucket | - | Bucket | -| doc | - | 需要操作的文件夹目录，比如 file/img，为可选参数。 | -| upload_fields_suffix | 规则字段，默认为 _file_url | 上传到 oss 的字段规则，包含 upload_fields_suffix 后缀的字段会上传到 oss。 | -| oss_fields_prefix | 规则字段，默认为 _ | 上传到 oss 的字段生成的新字段规则，会在原字段添加 oss_fields_prefix 前缀。 | -| full_link_enable | 是否开启完整链接，默认 false | 为是否保存完整的 oss 文件链接。 | - -遵守规则时的 `oss` 上传逻辑时使用，更复杂的需求也可根据示例自行实现。具体请看 `demo_oss` 和 `demo_oss_sec` 的场景示例。请自行选择可接受的风格。 - -## [custom_section] - -用于自定义配置： - -一些 `scrapy` 第三方扩展需要在 `settings.py` 中设置一些配置，涉及到 `host`，密码等隐私配置，直接展示在 `settings.py` 里是不可接受的，这里提供一种方法来解决。 - -在 `settings.py` 或 `spider` 等脚本中赋值重要参数时，可以从 `VIT_DIR` 的 `.conf` 中获取自定义配置内容，来达到隐藏隐私内容和保持配置内容统一存放的目的； - -比如在 `.conf` 中自定义配置以下内容： - -```shell -[custom_section] -custom_option=custom_value -custom_int=1 -custom_bool=true -custom_float=3.1415926 -``` - -那么，可以在程序任意地方通过 `get_cfg` 来获取自定义部分： - -```python -from ayugespidertools.config import get_cfg - -_my_cfg = get_cfg() -custom_option = _my_cfg["custom_section"].get("custom_option", "no_custom_value") -custom_int = _my_cfg["custom_section"].getint("custom_int", 0) -custom_bool = _my_cfg["custom_section"].getboolean("custom_bool", False) -custom_float = _my_cfg["custom_section"].getfloat("custom_float", 3.14) -``` diff --git a/docs/topics/configuration.rst b/docs/topics/configuration.rst new file mode 100644 index 0000000..dd95e99 --- /dev/null +++ b/docs/topics/configuration.rst @@ -0,0 +1,288 @@ +.. _topics-configuration: + +============= +Configuration +============= + +AyugeSpiderTools 将项目中所依赖的敏感配置信息放入了当前项目的 VIT 下的 .conf 文件中独立管理。当然，你\ +也可以在项目中自定义 VIT_DIR 参数来决定配置文件 .conf 的路径。 + +若你有很多的 Scrapy 项目需要统一管理，可以选择以下方式： + +- 如果是单机多项目的情况，你可以指定 VIT_DIR 参数为此机器上的统一地址即可。 +- 如果是多机多项目的情况，更推荐使用本库的 consul 或 nacos 服务来远程配置和管理，灵活性更高。 + +下面来介绍 .conf 文件中的配置内容： + +Introduction +============ + +配置格式使用 ini。 + +[nacos] +======= + +`Nacos`_ 可用于远程配置管理服务，可以更敏捷和容易地管理微服务平台。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "url", "_", "nacos 服务对应的链接，若有鉴权参数请在 url 中构建。" + "format", "参数可选 json, xml, yaml", "nacos url 配置中对应的格式解析方法，支持 json， + xml，yaml 解析。请优先使用 json 和 xml 来解析，yaml 解析需要安装 ayugespidertools[all] 依赖。" + +[consul] +======== + +`Consul`_ 的配置管理功能同 nacos，是本库提供的另一选择。但请注意：consul 比 nacos 的优先级更高，如果\ +两者都配置了会优先使用 consul 配置。不同的是配置中的鉴权 token 参数独立了出来。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "url", "_", "consul 服务对应的链接。" + "format", "参数可选 json, xml, yaml, hcl", "consul url 配置中对应的格式解析方法，支持 json， + xml，yaml，hcl 解析，推荐 json 解析格式。hcl 和 yaml 解析需要安装 ayugespidertools[all] 依赖。" + "token", "可选，默认空", "consul token 参数。" + +[mysql] +======= + +用于 mysql 存储相关场景中使用，比如创建对应的 sqlalchemy 的 engine，engine_conn 来用于去重，创建数\ +据库连接来解决表格缺失，字段缺失等问题。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "user", "_", "_" + "password", "_", "_" + "database", "_", "链接的数据库名称，在非 aiomysql 场景下，当 database 不存在时会用当前 user 创 + 建所需库表及字段等。" + "host", "可选，默认 localhost", "_" + "port", "可选，默认 3306", "_" + "engine", "可选，默认 InnoDB", "自动创建数据库和数据表时需要的参数" + "collate", "可选，默认 utf8mb4_general_ci", "自动创建数据库和数据表时需要的参数" + "charset", "可选，默认 utf8mb4", "自动创建数据库和数据表时需要的参数" + "odku_enable", "可选，默认 false", "是否开启 ON DUPLICATE KEY UPDATE 功能" + +注： + +- charset 参数选择有 utf8mb4，gbk，latin1，utf16，utf16le，cp1251，euckr，greek，charset 要与\ + collate 参数匹配。 +- 其中 engine，charset，collate 为自动创建数据库和数据表时需要的参数，可随意配置或默认即可，也可提前手\ + 动创建好表，也可后续手动修改。 + +[mongodb:uri] +============= + +mongodb 链接的 uri 配置方式。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "uri", "_", "mongoDB uri" + +[mongodb] +========= + +mongodb 链接的普通方式，[mongodb:uri] 和 [mongodb] 按需选择一种即可。 若两种都设置了，会优先从 mongodb:uri \ +中获取配置。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "database", "_", "_" + "user", "_", "_" + "password", "_", "_" + "host", "可选，默认 localhost", "_" + "port", "可选，默认 27017", "_" + "authsource", "可选，默认 admin", "_" + "authMechanism", "可选，默认 SCRAM-SHA-1", "_" + +[postgresql] +============ + +用于 postgresql 存储相关场景中使用，比如创建对应的 sqlalchemy 的 engine，engine_conn 来用于去重，\ +创建数据库连接来解决表格缺失，字段缺失等问题。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "user", "_", "_" + "password", "_", "_" + "database", "_", "_" + "host", "可选，默认 localhost", "_" + "port", "可选，默认 5432", "_" + "charset", "可选，默认 UTF8", "同 mysql 一样，用于在表不存在而创建时需要，可随意配置，后续也可手动修改。" + +[elasticsearch] +=============== + +用于 elasticsearch 存储相关场景中使用，也具有对应的 es_engine，es_engine_conn 来用于存储前的去重\ +(查询及更新等自定义)逻辑。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "hosts", "_", "若有多个，用逗号分隔，比如 https://x.x.x.x:9200,https://x.x.x.x:9201" + "index_class", "默认 {'settings':{'number_of_shards': 2}}", "es Document 中的配置" + "user", "默认 elastic", "_" + "password", "默认 elastic", "_" + "init", "是否初始化 es Document，默认 false", "是否创建 es 索引，此设置一般只在第一次运行项目时 + 打开，或者选择手动创建并配置此参数永远为 false。" + "verify_certs", "默认 false", "证书验证，推荐开启" + "ca_certs", "默认 None", "ca_certs 路径" + "client_cert", "默认 None", "client_cert 路径" + "client_key", "默认 None", "client_key 路径" + "ssl_assert_fingerprint", "默认 None", "es 启动中的 HTTP CA certificate SHA-256 fingerprint 参数" + +注： + +- ca_certs，client_cert，client_key，ssl_assert_fingerprint 中只用配置一个即可，若 verify_certs \ + 设置为 false 则都不用配置以上参数，但推荐开启此参数。 +- index_class 配置中不建议包含 name 参数，而是通过 AyuItem 中的 _table 来设置，AyuItem 会覆盖 \ + index_class 中的 name 配置。 + +[mq] +==== + +推送到 RabbitMQ 场景所需的参数。以下配置参数与 `pika`_ 中一致，请自行对照查看。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "virtualhost", "_", "_" + "queue", "_", "_" + "exchange", "_", "_" + "routing_key", "_", "_" + "username", "可选，默认 guest", "_" + "password", "可选，默认 guest", "_" + "host", "可选，默认 localhost", "_" + "port", "可选，默认 5672", "_" + +[oracle] +======== + +用于 oracle 存储相关场景中使用，比如创建对应的 sqlalchemy 的 engine，engine_conn 来用于去重，但不会\ +处理数据库表及字段缺失等错误，请提前创建好，因为其部分报错不如 mysql 及 postgresql 那样清晰明了，虽然也\ +能解决，但必要性不高。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "user", "_", "_" + "password", "_", "_" + "service_name", "_", "_" + "host", "可选，默认 localhost", "_" + "port", "可选，默认 1521", "_" + "encoding", "可选，默认 utf8", "oracledb 的链接参数。" + "thick_lib_dir", "可选，默认 false", "oracledb 的 thick_mode 所需参数，按需配置。" + +[kafka] +======= + +推送到 kafka 场景所需的参数。以下配置参数与 `kafka-python`_ 中一致，请自行对照查看。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "bootstrap_servers", "若有多个，用逗号分隔。比如 x.x.x.x:9092,x.x.x.x:9093", "" + "topic", "_", "_" + "key", "_", "_" + +[kdl_dynamic_proxy] +=================== + +快代理动态代理配置参数。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "proxy", "_", "快代理动态代理 api。" + "username", "_", "_" + "password", "_", "_" + +[kdl_exclusive_proxy] +===================== + +快代理独享代理配置参数。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "proxy", "_", "快代理独享代理 api。" + "username", "_", "_" + "password", "_", "_" + "index", "可选，默认 1", "表示取其索引值对应的代理。" + +[oss:ali] +========= + +上传到阿里云 oss 的配置参数。 + +.. csv-table:: + :header: "参数名", "参数备注", "描述" + :widths: 10, 15, 30 + + "access_key", "_", "阿里云 access_key_id" + "access_secret", "_", "阿里云账号对应的 access_key_secret" + "endpoint", "_", "填写 Bucket 所在地域对应的 Endpoint" + "bucket", "_", "Bucket" + "doc", "_", "需要操作的文件夹目录，比如 file/img，为可选参数。" + "upload_fields_suffix", "规则字段，默认为 _file_url", "上传到 oss 的字段规则，包含 + upload_fields_suffix 后缀的字段会上传到 oss。" + "oss_fields_prefix", "规则字段，默认为 _ ", "上传到 oss 的字段生成的新字段规则，会在原字段添加 + oss_fields_prefix 前缀。" + "full_link_enable", "是否开启完整链接，默认 false", "为是否保存完整的 oss 文件链接。" + + +遵守规则时的 oss 上传逻辑时使用，更复杂的需求也可根据示例自行实现。具体请看 demo_oss 和 demo_oss_sec \ +的场景示例。请自行选择可接受的风格。 + +[custom_section] +================ + +用于自定义配置： + +一些 scrapy 第三方扩展需要在 settings.py 中设置一些配置，涉及到 host，密码等隐私配置，直接展示在 \ +settings.py 里是不可接受的，这里提供一种方法来解决。 + +在 settings.py 或 spider 等脚本中赋值重要参数时，可以从 VIT_DIR 的 .conf 中获取自定义配置内容，来达\ +到隐藏隐私内容和保持配置内容统一存放的目的；比如在 .conf 中自定义配置以下内容： + +.. code:: ini + + [custom_section] + custom_option=custom_value + custom_int=1 + custom_bool=true + custom_float=3.1415926 + +那么，可以在程序任意地方通过 get_cfg 来获取自定义部分： + +.. code-block:: python + + from ayugespidertools.config import get_cfg + + _my_cfg = get_cfg() + custom_option = _my_cfg["custom_section"].get("custom_option", "no_custom_value") + custom_int = _my_cfg["custom_section"].getint("custom_int", 0) + custom_bool = _my_cfg["custom_section"].getboolean("custom_bool", False) + custom_float = _my_cfg["custom_section"].getfloat("custom_float", 3.14) + +.. _Nacos: https://nacos.io +.. _Consul: https://consul.io +.. _pika: https://pika.readthedocs.io/en/stable/ +.. _kafka-python: https://kafka-python.readthedocs.io/en/master/ diff --git a/docs/topics/downloader-middleware.md b/docs/topics/downloader-middleware.md deleted file mode 100644 index 766dac1..0000000 --- a/docs/topics/downloader-middleware.md +++ /dev/null @@ -1,189 +0,0 @@ -# downloader-middleware - -> 介绍本库中自带的常用 `DOWNLOADER_MIDDLEWARES` 中间件。 - -需要使用本库中的配置，需要在 `spider` 中修改如下，此为前提： - -```python -from ayugespidertools.spiders import AyuSpider - - -# 当前 spider 要继承 AyuSpider -class DemoOneSpider(AyuSpider): ... -``` - -## 1. 随机UA - -> 使用 `fake_useragent` 库中的 `ua` 信息，在每次发送请求时将随机取 `ua` 信息，将比较常用的 `ua` 标识的权重设置高一点，这里是根据 `fake_useragent` 库中的打印信息来规划权重的，即类型最多的 `ua` 其权重也就越高。 - -### 1.1. 使用方法 - -只需激活 `DOWNLOADER_MIDDLEWARES` 对应的配置即可。 - -```python -custom_settings = { - "DOWNLOADER_MIDDLEWARES": { - # 随机请求头 - "ayugespidertools.middlewares.RandomRequestUaMiddleware": 400, - }, -} -``` - -若想查看是否正常运行，只需查看其 `scrapy` 的 `debug` 日志，或在 `spider` 中打印 `response` 信息然后查看其信息即可。 - -## 2. 代理 - -### 2.1. 动态隧道代理 - -> 本库以快代理为例，其各个代理种类的使用方法大致相同 - -#### 2.1.1. 使用方法 - -激活 `DOWNLOADER_MIDDLEWARES` 中的动态代理配置。 - -```python -custom_settings = { - "DOWNLOADER_MIDDLEWARES": { - # 动态隧道代理激活 - "ayugespidertools.middlewares.DynamicProxyDownloaderMiddleware": 125, - }, -} -``` - -需要修改此项目中的 `VIT` 文件夹下的 `.conf` 对应的配置信息。 - -```ini -[KDL_DYNAMIC_PROXY] -PROXY=o668.kdltps.com:15818 -USERNAME=*** -PASSWORD=*** -``` - -然后即可正常运行。 - -### 2.2. 独享代理 - -#### 2.2.1. 使用方法 - -激活 `DOWNLOADER_MIDDLEWARES` 中的独享代理配置。 - -```python -custom_settings = { - "DOWNLOADER_MIDDLEWARES": { - # 独享代理激活 - "ayugespidertools.middlewares.ExclusiveProxyDownloaderMiddleware": 125, - }, -} -``` - -需要修改此项目中的 `VIT` 文件夹下的 `.conf` 对应的配置信息。 - -```ini -[kdl_exclusive_proxy] -proxy=http://kps.kdlapi.com/api/getkps?orderid=***&num=100&format=json -username=*** -password=*** -index=1 -``` - -注：`index` 为在有多个独享代理时取的代理对应的索引值。 - -## 3. 发送请求方式改为 aiohttp - -### 3.1. 使用方法 - -激活 `DOWNLOADER_MIDDLEWARES` 中的对应配置。 - -```python -custom_settings = { - "TWISTED_REACTOR": "twisted.internet.asyncioreactor.AsyncioSelectorReactor", - "DOWNLOADER_MIDDLEWARES": { - # 将 scrapy Request 替换为 aiohttp 方式 - "ayugespidertools.middlewares.AiohttpDownloaderMiddleware": 543, - }, - # aiohttp.TCPConnector 的配置项，非必需项，按需配置 - "AIOHTTP_CONFIG": { - "sleep": 1, - # 同时连接的总数 - "limit": 100, - # 同时连接到一台主机的数量 - "limit_per_host": 0, - "retry_times": 3, - "verify_ssl": False, - "allow_redirects": False, - }, - # aiohttp 的超时时间也用这个配置 - "DOWNLOAD_TIMEOUT": 25, -} -``` - -注： - -- `TWISTED_REACTOR` 的配置在本库的 `settings` 中就默认打开的，这里配置是为了演示，不用再次配置的； -- 这里的 `scrapy DOWNLOAD_TIMEOUT` 同样也是 `aiohttp` 请求的超时设置参数； -- `AIOHTTP_CONFIG` 为 `aiohttp` 的全局配置，是构建 `aiohttp.ClientSession` 的 `connector` 时所需的参数； - -`AIOHTTP_CONFIG` 可配置的参数如下(其实就是 `aiohttp.TCPConnector` 中的参数): - -```python -AIOHTTP_CONFIG = { - # 设置 aiohttp.TCPConnector 中的配置 - "verify_ssl": None, - "fingerprint": None, - "use_dns_cache": None, - "ttl_dns_cache": None, - "family": None, - "ssl_context": None, - "ssl": None, - "local_addr": None, - "resolver": None, - "keepalive_timeout": None, - "force_close": None, - "limit": None, - "limit_per_host": None, - "enable_cleanup_closed": None, - "loop": None, - "timeout_ceil_threshold": None, - # 设置一些自定义的全局参数 - "sleep": None, - "retry_times": None, -} -``` - -目前版本简化了 `aiohttp` 在 `yield AiohttpRequest` 的操作，也删除了 `AiohttpFormRequest` 来简化流程，示例如下： - -```python -from ayugespidertools.request import AiohttpRequest -from scrapy.http.request import NO_CALLBACK - -_ar_headers_ck = "headers_ck_key=ck; headers_ck_key2=ck" -_ar_ck = {"ck_key": "ck"} - - -def request_example(): - # 发送 get 请求示例： - yield AiohttpRequest( - url="http://httpbin.org/get?get_args=1", - callback=NO_CALLBACK, - headers={"Cookie": _ar_headers_ck}, - cookies=_ar_ck, - cb_kwargs={"request_name": 1}, - ) - - # 发送 post 请求示例： - post_data = {"post_key1": "post_value1", "post_key2": "post_value2"} - yield AiohttpRequest( - url="http://httpbin.org/post", - method="POST", - callback=NO_CALLBACK, - headers={"Cookie": _ar_headers_ck}, - data=post_data, - cookies=_ar_ck, - cb_kwargs={"request_name": 2}, - dont_filter=True, - ) - - -# 其中 AiohttpRequest 中的 params，json，data，proxy，ssl，timeout 等参数可按需求自定义设置。 -``` -由于改成通过 `yield AiohttpRequest` 的统一接口发送请求，且此方法参数与 `aiohttp` 的请求参数一致，极大地减少用户使用成本和避免维护地狱。 diff --git a/docs/topics/downloader-middleware.rst b/docs/topics/downloader-middleware.rst new file mode 100644 index 0000000..67e0d59 --- /dev/null +++ b/docs/topics/downloader-middleware.rst @@ -0,0 +1,209 @@ +.. _topics-downloader-middleware: + +===================== +downloader-middleware +===================== + +介绍本库中自带的常用 DOWNLOADER_MIDDLEWARES 中间件。若需要使用本库中的配置，需要在 spider 中修改如下，\ +此为前提： + +.. code-block:: python + + from ayugespidertools.spiders import AyuSpider + + + # 当前 spider 要继承 AyuSpider + class DemoOneSpider(AyuSpider): ... + +1. 随机UA +============ + +使用 fake_useragent 库中的 ua 信息，在每次发送请求时将随机取 ua 信息，将比较常用的 ua 标识的权重设置\ +高一点，这里是根据 fake_useragent 库中的打印信息来规划权重的，即类型最多的 ua 其权重也就越高。 + +1.1. 使用方法 +----------------- + +只需激活 DOWNLOADER_MIDDLEWARES 对应的配置即可。 + +.. code-block:: python + + custom_settings = { + "DOWNLOADER_MIDDLEWARES": { + # 随机请求头 + "ayugespidertools.middlewares.RandomRequestUaMiddleware": 400, + }, + } + +若想查看是否正常运行，只需查看其 scrapy 的 debug 日志，或在 spider 中打印 response 信息然后查看其信\ +息即可。 + +2. 代理 +========== + +2.1. 动态隧道代理 +--------------------- + +本库以快代理为例，其各个代理种类的使用方法大致相同 + +2.1.1. 使用方法 +^^^^^^^^^^^^^^^^^^^ + +激活 DOWNLOADER_MIDDLEWARES 中的动态代理配置。 + +.. code-block:: python + + custom_settings = { + "DOWNLOADER_MIDDLEWARES": { + # 动态隧道代理激活 + "ayugespidertools.middlewares.DynamicProxyDownloaderMiddleware": 125, + }, + } + +需要修改此项目中的 VIT 文件夹下的 .conf 对应的配置信息。 + +.. code:: ini + + [KDL_DYNAMIC_PROXY] + PROXY=o668.kdltps.com:15818 + USERNAME=*** + PASSWORD=*** + +然后即可正常运行。 + +2.2. 独享代理 +----------------- + +2.2.1. 使用方法 +^^^^^^^^^^^^^^^^^^^ + +激活 DOWNLOADER_MIDDLEWARES 中的独享代理配置。 + +.. code-block:: python + + custom_settings = { + "DOWNLOADER_MIDDLEWARES": { + # 独享代理激活 + "ayugespidertools.middlewares.ExclusiveProxyDownloaderMiddleware": 125, + }, + } + + +需要修改此项目中的 VIT 文件夹下的 .conf 对应的配置信息。 + +.. code:: ini + + [kdl_exclusive_proxy] + proxy=http://kps.kdlapi.com/api/getkps?orderid=***&num=100&format=json + username=*** + password=*** + index=1 + +注：index 为在有多个独享代理时取的代理对应的索引值。 + +.. _topics-downloader-middleware-aiohttp: + +3. 发送请求方式改为 aiohttp +============================ + +3.1. 使用方法 +----------------- + +激活 DOWNLOADER_MIDDLEWARES 中的对应配置。 + +.. code-block:: python + + custom_settings = { + "TWISTED_REACTOR": "twisted.internet.asyncioreactor.AsyncioSelectorReactor", + "DOWNLOADER_MIDDLEWARES": { + # 将 scrapy Request 替换为 aiohttp 方式 + "ayugespidertools.middlewares.AiohttpDownloaderMiddleware": 543, + }, + # aiohttp.TCPConnector 的配置项，非必需项，按需配置 + "AIOHTTP_CONFIG": { + "sleep": 1, + # 同时连接的总数 + "limit": 100, + # 同时连接到一台主机的数量 + "limit_per_host": 0, + "retry_times": 3, + "verify_ssl": False, + "allow_redirects": False, + }, + # aiohttp 的超时时间也用这个配置 + "DOWNLOAD_TIMEOUT": 25, + } + +注： + +- TWISTED_REACTOR 的配置在本库的 settings 中就默认打开的，这里配置是为了演示，不用再次配置的； +- 这里的 scrapy DOWNLOAD_TIMEOUT 同样也是 aiohttp 请求的超时设置参数； +- AIOHTTP_CONFIG 为 aiohttp 的全局配置，是构建 aiohttp.ClientSession 的 connector 时所需的参数； + +AIOHTTP_CONFIG 可配置的参数如下(其实就是 aiohttp.TCPConnector 中的参数): + +.. code-block:: python + + AIOHTTP_CONFIG = { + # 设置 aiohttp.TCPConnector 中的配置 + "verify_ssl": None, + "fingerprint": None, + "use_dns_cache": None, + "ttl_dns_cache": None, + "family": None, + "ssl_context": None, + "ssl": None, + "local_addr": None, + "resolver": None, + "keepalive_timeout": None, + "force_close": None, + "limit": None, + "limit_per_host": None, + "enable_cleanup_closed": None, + "loop": None, + "timeout_ceil_threshold": None, + # 设置一些自定义的全局参数 + "sleep": None, + "retry_times": None, + } + +目前版本简化了 aiohttp 在 yield AiohttpRequest 的操作，也删除了 AiohttpFormRequest 来简化流程，\ +示例如下： + +.. code-block:: python + + from ayugespidertools.request import AiohttpRequest + from scrapy.http.request import NO_CALLBACK + + _ar_headers_ck = "headers_ck_key=ck; headers_ck_key2=ck" + _ar_ck = {"ck_key": "ck"} + + + def request_example(): + # 发送 get 请求示例： + yield AiohttpRequest( + url="http://httpbin.org/get?get_args=1", + callback=NO_CALLBACK, + headers={"Cookie": _ar_headers_ck}, + cookies=_ar_ck, + cb_kwargs={"request_name": 1}, + ) + + # 发送 post 请求示例： + post_data = {"post_key1": "post_value1", "post_key2": "post_value2"} + yield AiohttpRequest( + url="http://httpbin.org/post", + method="POST", + callback=NO_CALLBACK, + headers={"Cookie": _ar_headers_ck}, + data=post_data, + cookies=_ar_ck, + cb_kwargs={"request_name": 2}, + dont_filter=True, + ) + + + # 其中 AiohttpRequest 中的 params，json，data，proxy，ssl，timeout 等参数可按需求自定义设置。 + +由于改成通过 yield AiohttpRequest 的统一接口发送请求，且此方法参数与 aiohttp 的请求参数一致，极大地\ +减少用户使用成本和避免维护地狱。 diff --git a/docs/topics/items.md b/docs/topics/items.md deleted file mode 100644 index fd62a1e..0000000 --- a/docs/topics/items.md +++ /dev/null @@ -1,311 +0,0 @@ -# Item - -> 演示在使用本库场景下 `Item` 的使用方法。 - -本教程将引导您完成这些任务： - -- 演示本库推荐的 `AyuItem` 适配方式 -- 补充适配 `add_value`, `add_xpath`, `add_css` 等方法的示例 - -## 快速开始 - -`scrapy` 中 `Item` 对应本库的 `AyuItem`，`AyuItem` 可用 `AyuItem(key=value)` 的形式直接动态赋值，其中 `value` 介绍如下： - -`value` 可选择的类型有： - -- 普通字段 - - ``` - from ayugespidertools.items import AyuItem - - _title = "article_title_value" - demo_item = AyuItem( - article_title=_title - ) - ``` - -- `DataItem` 字段 - - - 完整赋值 - - ``` - # `DataItem` 有 `key_value` 和 `notes` 两个参数，`key_value` 为存储的值； - # `notes` 在 `ElasticSearch` 存储场景中表示 `es document fields`，在其他(需要字段 - # 注释时，比如 `Mysql`，`postgresql` 存储)场景中表示为字段注释。 - - # 普通场景 - demo_item = AyuItem( - article_title=DataItem(_title, "文章标题"), - ) - - # es 场景 - from elasticsearch_dsl import Keyword - - demo_item = AyuItem( - article_title=DataItem(_title, Keyword()), - ) - - - 无 `notes` 赋值 - - ``` - # 即不需要字段注释，也不是 es 存储场景下，只赋值 key_value 参数 - - demo_item = AyuItem( - article_title=DataItem(_title), - ) - - # 不过，这种写法风格不如直接使用 【普通字段】的优雅赋值方式。 - ``` - -## 实现原理 - -> 以下为 `Mysql`， `MongoDB` 和 `ElasticSearch` 存储时的 `AyuItem` 示例，其它场景的用法也都一样： - -本库将所有需要存储的字段直接在对应的 `Item` (`AyuItem`) 中赋值即可，其中 `_table` 参数为必须参数，也可以使用 `add_field` 方法动态添加字段。 - -```python -_save_table = "_article_info_list" - - -def parse(self, response): - # 存储到 Mysql 场景时 Item 构建示例： - article_mysql_item = AyuItem( - article_detail_url=article_detail_url, - article_title=article_title, - comment_count=comment_count, - favor_count=favor_count, - nick_name=nick_name, - _table=_save_table, - ) - - # 存储到 MongoDB 场景时 Item 构建示例： - article_mongo_item = AyuItem( - article_detail_url=article_detail_url, - article_title=article_title, - comment_count=comment_count, - favor_count=favor_count, - nick_name=nick_name, - _table=_save_table, - # 可选参数，此示例表示以 article_detail_url 为去重规则，若存在则更新，不存在则新增 - _mongo_update_rule={"article_detail_url": article_detail_url}, - ) - - # 存储到 ElasticSearch 场景时 Item 构建示例： - # 同样地，为保持风格统一，es 存储场景中会把 es Document 中 fields 的声明 - # 放在 AyuItem 中 DataItem 的 notes 参数中。 - # 这个参数在其他(需要字段注释，比如 Mysql，postgresql)场景中表示为字段注释。 - from elasticsearch_dsl import Keyword, Search, Text - - book_info_item = AyuItem( - book_name=DataItem( - book_name, Text(analyzer="snowball", fields={"raw": Keyword()}) - ), - book_href=DataItem(book_href, Keyword()), - book_intro=DataItem(book_intro, Keyword()), - _table=DataItem(_save_table, "这里的索引注释可有可无，程序中不会使用。"), - ) - - -# 具体不同的场景示例，请在 DemoSpider 项目中查看； -# 如非场景需要，不推荐使用 DataItem 的方式构建 AyuItem，不太优雅。 -``` - -以上可知，目前可直接将需要的参数在对应 `Item` 中直接按 `key=value` 赋值即可，`key` 为存储至库中字段，`value` 为对应 `key` 所存储的值。 - -当然，目前也支持动态赋值，但我还是推荐直接创建好 `AyuItem` ，方便管理： - -```python -def parse(self, response): - mdi = AyuItem(_table="table0") - mdi.add_field("add_field1", "value1") - mdi.add_field("add_field2", DataItem(key_value="value2")) - mdi.add_field("add_field3", DataItem(key_value="value3", notes="add_field3值")) - # _table 修改可通过以下方式，同样不推荐使用 - mdi["_table"] = "table1" - - -# 不允许 AyuItem 中字段值的类型（str 和 DataItem）混用，这里是用于示例展示。 -``` -注：在使用 `AyuItem` 时，其中各字段值（除了 `_mongo_update_rule`）的类型都要统一，比如要么都使用 `str` 类型，要么都使用 `DataItem` 类型。 - -另外，本库的 `item` 提供类型转换，以方便后续的各种使用场景： - -```python -# 将本库 AyuItem 转为 dict 的方法 -item_dict = mdi.asdict() -# 将本库 AyuItem 转为 scrapy Item 的方法 -item = mdi.asitem() -``` - -## AyuItem 使用详解 - -> 详细介绍 `AyuItem` 支持的使用方法： - -创建 `AyuItem` 实例： - -```python -item = AyuItem(_table="ta") -``` - -获取字段： - -```shell ->>> item["_table"] -'ta' ->>> ->>> # 注意：虽然也可以通过 item._table 的形式获取，但是不建议这样，显得不明了。 -``` - -添加 / 修改字段（不存在则创建，存在则修改）： - -```shell ->>> item["_table"] = "tab" ->>> item["title"] = "tit" ->>> ->>> # 也可通过 add_field 添加字段，但不能重复添加相同字段 ->>> item.add_field("num", 10) ->>> ->>> [ item["_table"], item["title"], item["num"] ] -['tab', 'tit', 10] -``` - -类型转换： - -```shell ->>> # 内置转为 dict 和 scrapy Item 的方法 ->>> ->>> item.asdict() -{'title': 'tit', '_table': 'tab', 'num': 10} ->>> ->>> type(item.asitem()) - -``` - -删除字段： - -```shell ->>> # 删除字段： ->>> item.pop("num") -10 ->>> del item["title"] ->>> item -{'_table': 'tab'} -``` - -## 使用示例 - -> 只需要在 `yield item` 时，按需提前导入 `AyuItem`，将所有的存储字段和场景补充字段全部添加完整即可。 - -`AyuItem` 在 `spider` 中常用的基础使用方法示例，以本库模板中的 `basic.tmpl` 为例来作解释： - -```python -from ayugespidertools.items import AyuItem -from ayugespidertools.spiders import AyuSpider -from scrapy.http import Request -from sqlalchemy import text - - -class DemoOneSpider(AyuSpider): - name = "demo_one" - allowed_domains = ["readthedocs.io"] - start_urls = ["http://readthedocs.io/"] - custom_settings = { - # 数据库引擎开关，打开会有对应的 engine 和 engine_conn，可用于数据入库前去重判断 - "DATABASE_ENGINE_ENABLED": True, - "ITEM_PIPELINES": { - # 激活此项则数据会存储至 Mysql - "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, - # 激活此项则数据会存储至 MongoDB - "ayugespidertools.pipelines.AyuFtyMongoPipeline": 301, - }, - } - - def start_requests(self): - yield Request( - url="https://ayugespidertools.readthedocs.io/en/latest/", - callback=self.parse_first, - ) - - def parse_first(self, response): - _save_table = "_octree_info" - - # 你可以自定义解析规则，使用 lxml 还是 response.css response.xpath 等等都可以。 - li_list = response.xpath('//div[@aria-label="Navigation menu"]/ul/li') - for curr_li in li_list: - octree_text = curr_li.xpath("a/text()").get() - octree_href = curr_li.xpath("a/@href").get() - - octree_item = AyuItem( - octree_text=octree_text, - octree_href=octree_href, - _table=_save_table, - # 可选参数：这里表示 MongoDB 存储场景以 octree_text 为去重规则，若存在则更新，不存在则新增 - _mongo_update_rule={"octree_text": octree_text}, - ) - # 日志使用 scrapy 的 self.logger 或本库的 self.slog - self.slog.info(f"octree_item: {octree_item}") - - # 注意：同时存储至 mysql 和 mongodb 时，不建议使用以下去重方法，会互相影响。 - # 此时更适合： - # 1.mysql 添加唯一索引去重（结合 odku_enable 配置，本库会根据 on duplicate key update 更新）， - # mongoDB 场景下设置 _mongo_update_rule 参数即可； - # 2.或者添加爬取时间字段并每次新增的场景，即不去重，请根据使用场景自行选择; - # 3.同时存储多个数据库场景更推荐使用第三方去重来统一管理，比如 scrapy-redis，布隆过滤等。 - # 这里只是为了介绍使用 mysql_engine_conn 来对 mysql 去重的方法。 - if self.mysql_engine_conn: - try: - _sql = text( - f"select `id` from `{_save_table}` where `octree_text` = {octree_text!r} limit 1" - ) - result = self.mysql_engine_conn.execute(_sql).fetchone() - if not result: - self.mysql_engine_conn.rollback() - yield octree_item - else: - self.slog.debug(f'标题为 "{octree_text}" 的数据已存在') - except Exception as e: - self.mysql_engine_conn.rollback() - yield octree_item - else: - yield octree_item -``` - -> 由上可知，本库中的 `Item` 使用方法还是很方便的。 -> - -**对以上 `Item` 相关信息解释：** - -- 先导入所需 `Item`: `AyuItem` -- 构建对应场景的 `Item` - - `Mysql` 存储场景需要配置 `_table` 参数 - - `MongoDB` 存储场景可能会需要 `_mongo_update_rule` 来设置去重的更新条件 -- 最后 `yield` 对应 `item` 即可 - -补充：其中 `AyuItem` 也可以改成 `DataItem` 的赋值方式，那么 `mysql` 场景下在表字段不存在时会添加字段注释，`mongodb` 则没有影响。推荐直接赋值的方式，更明了。 - -## yield item - -> 这里解释下 `item` 的格式问题，虽说也是支持直接 `yield dict` ，`scrapy` 的 `item` 格式(即本库中的 `ScrapyItem`)，还有就是本库推荐的 `AyuItem` 的形式。 - -这里介绍下 `item` 字段及其注释，以上所有 `item` 都有参数提示： - -| item 字段 | 类型 | 注释 | -| ---------------------- | ------------- | ------------------------------------------------------------ | -| **自定义字段** | DataItem，Any | `item` 所有需要存储的字段，若有多个，请按规则自定义添加即可。 | -| **_table** | DataItem, str | 存储至数据表或集合的名称。 | -| **_mongo_update-rule** | dict | `MongoDB item` 场景下的查重规则。 | - -一些规则： - -| item 字段规则 | 类型 | 注释 | -| ----------------------------- | ------------- | ------------------------------------------------------------ | -| 后缀包含 _file_url | str, DataItem | 文件下载 pipeline 中使用，当包含此规则的字段会下载此字段资源到本地。生成的对应新字段会在原字段添加 _local 后缀。 | -| 前缀包含 upload_fields_suffix | str | oss 管道中使用，upload_fields_suffix 在 [oss:ali] 中配置，会上传此规则字段的资源到 oss。对应的新字段会在前缀添加 oss_fields_prefix。 | - -注，对以上表格中内容进行扩充解释： - -- 一般不推荐使用规则的方式来使用 `AyuItem`，推荐自行构建 `Ayuitem` 的逻辑更清晰更易维护，这里只是给出代码示例。 - -## 自定义 Item 字段和实现 Item Loaders - -具体请在下一章浏览。 diff --git a/docs/topics/items.rst b/docs/topics/items.rst new file mode 100644 index 0000000..a9de1e6 --- /dev/null +++ b/docs/topics/items.rst @@ -0,0 +1,334 @@ +.. _topics-items: + +==== +Item +==== + +演示在使用本库场景下 Item 的使用方法。 + +本教程将引导您完成这些任务： + +- 演示本库推荐的 AyuItem 适配方式 +- 补充适配 add_value, add_xpath, add_css 等方法的示例 + +快速开始 +========== + +scrapy 中 Item 对应本库的 AyuItem，AyuItem 可用 ``AyuItem(key=value)`` 的形式直接动态赋值，其中 \ +value 介绍如下： + +value 可选择的类型有： + +- 普通字段 + +.. code-block:: python + + from ayugespidertools.items import AyuItem + + _title = "article_title_value" + demo_item = AyuItem(article_title=_title) + +- ``DataItem`` 字段 + + - 完整赋值 + +.. code-block:: python + + # `DataItem` 有 `key_value` 和 `notes` 两个参数，`key_value` 为存储的值； + # `notes` 在 `ElasticSearch` 存储场景中表示 `es document fields`，在其他(需要字段 + # 注释时，比如 `Mysql`，`postgresql` 存储)场景中表示为字段注释。 + + # 普通场景 + demo_item = AyuItem( + article_title=DataItem(_title, "文章标题"), + ) + + # es 场景 + from elasticsearch_dsl import Keyword + + demo_item = AyuItem( + article_title=DataItem(_title, Keyword()), + ) + +--------------------------------------------------- + + - 无 ``notes`` 赋值 + +.. code-block:: python + + # 即不需要字段注释，也不是 es 存储场景下，只赋值 key_value 参数 + + demo_item = AyuItem( + article_title=DataItem(_title), + ) + + # 不过，这种写法风格不如直接使用 【普通字段】的优雅赋值方式。 + +实现原理 +========== + +以下为 Mysql， MongoDB 和 ElasticSearch 存储时的 AyuItem 示例，其它场景的用法也都一样： + +本库将所有需要存储的字段直接在对应的 Item (AyuItem) 中赋值即可，其中 ``_table`` 参数为必须参数，也可\ +以使用 ``add_field`` 方法动态添加字段。 + +.. code-block:: python + + _save_table = "_article_info_list" + + + def parse(self, response): + # 存储到 Mysql 场景时 Item 构建示例： + article_mysql_item = AyuItem( + article_detail_url=article_detail_url, + article_title=article_title, + comment_count=comment_count, + favor_count=favor_count, + nick_name=nick_name, + _table=_save_table, + ) + + # 存储到 MongoDB 场景时 Item 构建示例： + article_mongo_item = AyuItem( + article_detail_url=article_detail_url, + article_title=article_title, + comment_count=comment_count, + favor_count=favor_count, + nick_name=nick_name, + _table=_save_table, + # 可选参数，此示例表示以 article_detail_url 为去重规则，若存在则更新，不存在则新增 + _mongo_update_rule={"article_detail_url": article_detail_url}, + ) + + # 存储到 ElasticSearch 场景时 Item 构建示例： + # 同样地，为保持风格统一，es 存储场景中会把 es Document 中 fields 的声明 + # 放在 AyuItem 中 DataItem 的 notes 参数中。 + # 这个参数在其他(需要字段注释，比如 Mysql，postgresql)场景中表示为字段注释。 + from elasticsearch_dsl import Keyword, Search, Text + + book_info_item = AyuItem( + book_name=DataItem( + book_name, Text(analyzer="snowball", fields={"raw": Keyword()}) + ), + book_href=DataItem(book_href, Keyword()), + book_intro=DataItem(book_intro, Keyword()), + _table=DataItem(_save_table, "这里的索引注释可有可无，程序中不会使用。"), + ) + + + # 具体不同的场景示例，请在 DemoSpider 项目中查看； + # 如非场景需要，不推荐使用 DataItem 的方式构建 AyuItem，不太优雅。 + +以上可知，目前可直接将需要的参数在对应 Item 中直接按 ``key=value`` 赋值即可，key 为存储至库中字段，\ +value 为对应 key 所存储的值。 + +当然，目前也支持动态赋值，但我还是推荐直接创建好 AyuItem ，方便管理： + +.. code-block:: python + + def parse(self, response): + mdi = AyuItem(_table="table0") + mdi.add_field("add_field1", "value1") + mdi.add_field("add_field2", DataItem(key_value="value2")) + mdi.add_field("add_field3", DataItem(key_value="value3", notes="add_field3值")) + # _table 修改可通过以下方式，同样不推荐使用 + mdi["_table"] = "table1" + + + # 不允许 AyuItem 中字段值的类型（str 和 DataItem）混用，这里是用于示例展示。 + +注：在使用 AyuItem 时，其中各字段值（除了 ``_mongo_update_rule``）的类型都要统一，比如要么都使用 str \ +类型，要么都使用 ``DataItem`` 类型。 + +另外，本库的 item 提供类型转换，以方便后续的各种使用场景： + +.. code-block:: python + + # 将本库 AyuItem 转为 dict 的方法 + item_dict = mdi.asdict() + # 将本库 AyuItem 转为 scrapy Item 的方法 + item = mdi.asitem() + +AyuItem 使用详解 +================== + +详细介绍 AyuItem 支持的使用方法： + +创建 AyuItem 实例： + +.. code-block:: python + + item = AyuItem(_table="ta") + +获取字段： + +.. code:: bash + + >>> item["_table"] + 'ta' + >>> + >>> # 注意：虽然也可以通过 item._table 的形式获取，但是不建议这样，显得不明了。 + +添加 / 修改字段（不存在则创建，存在则修改）： + +.. code:: bash + + >>> item["_table"] = "tab" + >>> item["title"] = "tit" + >>> + >>> # 也可通过 add_field 添加字段，但不能重复添加相同字段 + >>> item.add_field("num", 10) + >>> + >>> [ item["_table"], item["title"], item["num"] ] + ['tab', 'tit', 10] + +类型转换： + +.. code:: bash + + >>> # 内置转为 dict 和 scrapy Item 的方法 + >>> + >>> item.asdict() + {'title': 'tit', '_table': 'tab', 'num': 10} + >>> + >>> type(item.asitem()) + + +删除字段： + +.. code:: bash + + >>> # 删除字段： + >>> item.pop("num") + 10 + >>> del item["title"] + >>> item + {'_table': 'tab'} + +使用示例 +========== + +只需要在 ``yield item`` 时，按需提前导入 AyuItem，将所有的存储字段和场景补充字段全部添加完整即可。 + +AyuItem 在 spider 中常用的基础使用方法示例，以本库模板中的 ``basic.tmpl`` 为例来作解释： + +.. code-block:: python + + from ayugespidertools.items import AyuItem + from ayugespidertools.spiders import AyuSpider + from scrapy.http import Request + from sqlalchemy import text + + + class DemoOneSpider(AyuSpider): + name = "demo_one" + allowed_domains = ["readthedocs.io"] + start_urls = ["http://readthedocs.io/"] + custom_settings = { + # 数据库引擎开关，打开会有对应的 engine 和 engine_conn，可用于数据入库前去重判断 + "DATABASE_ENGINE_ENABLED": True, + "ITEM_PIPELINES": { + # 激活此项则数据会存储至 Mysql + "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, + # 激活此项则数据会存储至 MongoDB + "ayugespidertools.pipelines.AyuFtyMongoPipeline": 301, + }, + } + + def start_requests(self): + yield Request( + url="https://ayugespidertools.readthedocs.io/en/latest/", + callback=self.parse_first, + ) + + def parse_first(self, response): + _save_table = "_octree_info" + + # 你可以自定义解析规则，使用 lxml 还是 response.css response.xpath 等等都可以。 + li_list = response.xpath('//div[@aria-label="Navigation menu"]/ul/li') + for curr_li in li_list: + octree_text = curr_li.xpath("a/text()").get() + octree_href = curr_li.xpath("a/@href").get() + + octree_item = AyuItem( + octree_text=octree_text, + octree_href=octree_href, + _table=_save_table, + # 可选参数：这里表示 MongoDB 存储场景以 octree_text 为去重规则，若存在则更新，不存在则新增 + _mongo_update_rule={"octree_text": octree_text}, + ) + # 日志使用 scrapy 的 self.logger 或本库的 self.slog + self.slog.info(f"octree_item: {octree_item}") + + # 注意：同时存储至 mysql 和 mongodb 时，不建议使用以下去重方法，会互相影响。 + # 此时更适合： + # 1.mysql 添加唯一索引去重（结合 odku_enable 配置，本库会根据 on duplicate key update 更新）， + # mongoDB 场景下设置 _mongo_update_rule 参数即可； + # 2.或者添加爬取时间字段并每次新增的场景，即不去重，请根据使用场景自行选择; + # 3.同时存储多个数据库场景更推荐使用第三方去重来统一管理，比如 scrapy-redis，布隆过滤等。 + # 这里只是为了介绍使用 mysql_engine_conn 来对 mysql 去重的方法。 + if self.mysql_engine_conn: + try: + _sql = text( + f"select `id` from `{_save_table}` where `octree_text` = {octree_text!r} limit 1" + ) + result = self.mysql_engine_conn.execute(_sql).fetchone() + if not result: + self.mysql_engine_conn.rollback() + yield octree_item + else: + self.slog.debug(f'标题为 "{octree_text}" 的数据已存在') + except Exception as e: + self.mysql_engine_conn.rollback() + yield octree_item + else: + yield octree_item + +由上可知，本库中的 Item 使用方法还是很方便的。 + +**对以上 Item 相关信息解释：** + +- 先导入所需 Item: ``AyuItem`` +- 构建对应场景的 ``Item`` + - ``Mysql`` 存储场景需要配置 ``_table`` 参数 + - ``MongoDB`` 存储场景可能会需要 ``_mongo_update_rule`` 来设置去重的更新条件 +- 最后 ``yield`` 对应 ``item`` 即可 + +补充：其中 AyuItem 也可以改成 DataItem 的赋值方式，那么 mysql 场景下在表字段不存在时会添加字段注释，\ +mongodb 则没有影响。推荐直接赋值的方式，更明了。 + +yield item +========== + +这里解释下 item 的格式问题，虽说也是支持直接 ``yield dict`` ，scrapy 的 item 格式(即本库中的 \ +``ScrapyItem``)，还有就是本库推荐的 AyuItem 的形式。 + +这里介绍下 item 字段及其注释，以上所有 item 都有参数提示： + +.. csv-table:: + :header: "item 字段", "类型", "注释" + :widths: 10, 15, 30 + + "自定义字段", "DataItem，Any", "item 所有需要存储的字段，若有多个，请按规则自定义添加即可。" + "_table", "DataItem, str", "存储至数据表或集合的名称。" + "_mongo_update-rule", "dict", "MongoDB item 场景下的查重规则。" + +一些规则： + +.. csv-table:: + :header: "item 字段规则", "类型", "注释" + :widths: 10, 15, 30 + + "后缀包含 _file_url", "str, DataItem", "文件下载 pipeline 中使用，当包含此规则的字段会下载此 + 字段资源到本地。生成的对应新字段会在原字段添加 _local 后缀。" + "前缀包含 upload_fields_suffix", "str", "oss 管道中使用，upload_fields_suffix 在 [oss:ali] + 中配置，会上传此规则字段的资源到 oss。对应的新字段会在前缀添加 oss_fields_prefix。" + +注，对以上表格中内容进行扩充解释： + +- 一般不推荐使用规则的方式来使用 AyuItem，推荐自行构建 Ayuitem 的逻辑更清晰更易维护，这里只是给出代码示例。 + +自定义 Item 字段和实现 Item Loaders +==================================== + +具体请在下一章浏览。 diff --git a/docs/topics/loaders.md b/docs/topics/loaders.md deleted file mode 100644 index cfa1242..0000000 --- a/docs/topics/loaders.md +++ /dev/null @@ -1,99 +0,0 @@ -# Item Loaders - -`Item Loaders` 提供了一种方便的机制来填充已抓取的 `ITEM`。尽管项目可以直接填充，项目加载器提供了一个更方便的 `API` 来从抓取过程中填充它们，通过自动化一些常见的任务，比如在分配它之前解析原始提取的数据。 - -换句话说，`ITEM` 提供了抓取数据的容器，而项目加载器提供了**填充**该容器的机制。 - -`Item Loaders` 旨在提供一种灵活、高效和简单的机制来扩展和覆盖不同的字段解析规则，无论是通过蜘蛛，还是通过源格式（`HTML`、`XML` 等），而不会成为维护的噩梦。 - -具体请查看 `scrapy` 中对应的 [Item Loaders](https://docs.scrapy.org/en/latest/topics/loaders.html) 的文档。 - -由文档可知，如果使用 `Item Loaders` 需要先声明 `Item` 子类，并固定 `Field` 字段。即以下内容示例： - -```python -import scrapy - - -class Product(scrapy.Item): - book_name = scrapy.Field() - book_href = scrapy.Field() - book_intro = scrapy.Field() -``` - -但是本库不固定 `Item field` 的内容，这样丧失了解放双手的目的。 - -虽然，`scrapy` 也可以通过使用如下方法来新增字段，但总归 `scrapy` 是不推荐这样的写法且不太方便： - -```python -Product.fields["add_field1"] = scrapy.Field() -``` - -那本库如何实现使用项目加载器填充项目的效果呢，本库是通过 `Item` 的 `asitem` 方法实现。具体使用方法请看文章后半段。 - -## 使用项目加载器填充项目 - -这是 `Spider` 中典型的 `Item Loader` 用法： - -```python -from scrapy.loader import ItemLoader -from myproject.items import Product -from ayugespidertools.items import AyuItem - - -# 这是 scrapy 中的实现示例： -def parse(self, response): - l = ItemLoader(item=Product(), response=response) - l.add_xpath("name", '//div[@class="product_name"]') - l.add_xpath("name", '//div[@class="product_title"]') - l.add_xpath("price", '//p[@id="price"]') - l.add_css("stock", "p#stock") - l.add_value("last_updated", "today") # you can also use literal values - yield l.load_item() - - -# 这是本库中的实现示例： -def parse(self, response): - # 先定义所需字段 - my_product = AyuItem( - book_name=None, - book_href=None, - book_intro=None, - _table="table_name", - ) - # 然后可根据 asitem 来使用常规的 ItemLoader 功能 - mine_item = ItemLoader(item=my_product.asitem(), selector=None) - mine_item.default_output_processor = TakeFirst() - mine_item.add_value("book_name", book_name) - mine_item.add_xpath("book_href", '//div[@class="product_title"]') - mine_item.add_css("book_intro", "p#stock") - item = mine_item.load_item() - yield item -``` - -## 使用数据类项 - -那本库的方式在使用 `ItemLoader` 时有没有缺点呢？ - -是的，有缺点，本库虽然支持动态添加 `Item` 字段，但是其实不太好实现 `dataclass items` 的字段类型约束和参数 `default` 的相关设置。本库是不推荐固定 `Item` 字段（比如 `ayugespidertools` `v3.0.0` 之前的版本中，会把数据都存入 `alldata` 的固定字段中），也不推荐 `spider` 中若存在不同 `Item` 数据类型就需要定义其对应的 `Item class` 的。其实各有优缺点，只是本库选择了牺牲此部分。 - -## 输入和输出处理器 - -那么，在本库中的使用方法如下： - -`Item Loader` 包含一个输入处理器和一个用于每个 `item` 字段的输出处理器。输入处理器在收到数据后立即处理提取的数据（通过[`add_xpath()`](https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.add_xpath),[`add_css()`](https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.add_css)或 [`add_value()`](https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.add_value)方法），输入处理器的结果被收集并保存在 `ItemLoader` 中。收集完所有数据后， [`ItemLoader.load_item()`](https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.load_item)调用该方法填充并获取填充的 [项对象](https://docs.scrapy.org/en/latest/topics/items.html#topics-items)。那是使用先前收集的数据（并使用输入处理器处理）调用输出处理器的时候。输出处理器的结果是分配给项目的最终值。 - -让我们看一个示例来说明如何为特定字段调用输入和输出处理器（这同样适用于任何其他字段）： - -```python -l = ItemLoader(my_product.asitem(), some_selector) -l.default_output_processor = TakeFirst() -l.add_xpath("name", xpath1) # (1) -l.add_xpath("name", xpath2) # (2) -l.add_css("name", css) # (3) -l.add_value("name", "test") # (4) -return l.load_item() # (5) -``` - -然后就可以使用 [使用项目加载器填充项目](# 使用项目加载器填充项目) 中的代码了 - -本库主推便捷，不太推荐使用以上代码自定义增加 `Item` 字段来适配 `Item Loaders` 的特性，除非某些场景下使用 `Item Loaders` 能够极大方便开发时，才推荐使用下。 diff --git a/docs/topics/loaders.rst b/docs/topics/loaders.rst new file mode 100644 index 0000000..1ddfd53 --- /dev/null +++ b/docs/topics/loaders.rst @@ -0,0 +1,122 @@ +.. _topics-loaders: + +============ +Item Loaders +============ + +``Item Loaders`` 提供了一种方便的机制来填充已抓取的 ITEM。尽管项目可以直接填充，项目加载器提供了一个更\ +方便的 API 来从抓取过程中填充它们，通过自动化一些常见的任务，比如在分配它之前解析原始提取的数据。 + +换句话说，ITEM 提供了抓取数据的容器，而项目加载器提供了填充该容器的机制。 + +Item Loaders 旨在提供一种灵活、高效和简单的机制来扩展和覆盖不同的字段解析规则，无论是通过蜘蛛，还是通过\ +源格式（``HTML``、``XML`` 等），而不会成为维护的噩梦。 + +具体请查看 `scrapy` 中对应的 `Item Loaders`_ 的文档。 + +由文档可知，如果使用 Item Loaders 需要先声明 Item 子类，并固定 Field 字段。即以下内容示例： + +.. code-block:: python + + import scrapy + + + class Product(scrapy.Item): + book_name = scrapy.Field() + book_href = scrapy.Field() + book_intro = scrapy.Field() + +但是本库不固定 Item field 的内容，这样丧失了解放双手的目的。 + +虽然，scrapy 也可以通过使用如下方法来新增字段，但总归 scrapy 是不推荐这样的写法且不太方便： + +.. code-block:: python + + Product.fields["add_field1"] = scrapy.Field() + +那本库如何实现使用项目加载器填充项目的效果呢，本库是通过 Item 的 asitem 方法实现。具体使用方法请看文章后半段。 + +使用项目加载器填充项目 +====================== + +这是 Spider 中典型的 Item Loader 用法： + +.. code-block:: python + + from scrapy.loader import ItemLoader + from myproject.items import Product + from ayugespidertools.items import AyuItem + + + # 这是 scrapy 中的实现示例： + def parse(self, response): + l = ItemLoader(item=Product(), response=response) + l.add_xpath("name", '//div[@class="product_name"]') + l.add_xpath("name", '//div[@class="product_title"]') + l.add_xpath("price", '//p[@id="price"]') + l.add_css("stock", "p#stock") + l.add_value("last_updated", "today") # you can also use literal values + yield l.load_item() + + + # 这是本库中的实现示例： + def parse(self, response): + # 先定义所需字段 + my_product = AyuItem( + book_name=None, + book_href=None, + book_intro=None, + _table="table_name", + ) + # 然后可根据 asitem 来使用常规的 ItemLoader 功能 + mine_item = ItemLoader(item=my_product.asitem(), selector=None) + mine_item.default_output_processor = TakeFirst() + mine_item.add_value("book_name", book_name) + mine_item.add_xpath("book_href", '//div[@class="product_title"]') + mine_item.add_css("book_intro", "p#stock") + item = mine_item.load_item() + yield item + +使用数据类项 +============== + +那本库的方式在使用 ItemLoader 时有没有缺点呢？ + +是的，有缺点，本库虽然支持动态添加 Item 字段，但是其实不太好实现 ``dataclass items`` 的字段类型约束和 +参数 ``default`` 的相关设置。本库是不推荐固定 Item 字段（比如 ayugespidertools v3.0.0 之前的版本中，\ +会把数据都存入 ``alldata`` 的固定字段中），也不推荐 spider 中若存在不同 Item 数据类型就需要定义其对应\ +的 ``Item class`` 的。其实各有优缺点，只是本库选择了牺牲此部分。 + +输入和输出处理器 +================= + +那么，在本库中的使用方法如下： + +Item Loader 包含一个输入处理器和一个用于每个 item 字段的输出处理器。输入处理器在收到数据后立即处理提取\ +的数据（通过 `add_xpath()`_,`add_css()`_ 或 `add_value()`_ 方法，输入处理器的结果被收集并保存在 \ +ItemLoader 中。收集完所有数据后， `ItemLoader.load_item()`_ 调用该方法填充并获取填充的 `项对象`_\ +。那是使用先前收集的数据（并使用输入处理器处理）调用输出处理器的时候。输出处理器的结果是分配给项目的最终值。 + +让我们看一个示例来说明如何为特定字段调用输入和输出处理器（这同样适用于任何其他字段）： + +.. code-block:: python + + l = ItemLoader(my_product.asitem(), some_selector) + l.default_output_processor = TakeFirst() + l.add_xpath("name", xpath1) # (1) + l.add_xpath("name", xpath2) # (2) + l.add_css("name", css) # (3) + l.add_value("name", "test") # (4) + return l.load_item() # (5) + +然后就可以使用 [使用项目加载器填充项目](# 使用项目加载器填充项目) 中的代码了 + +本库主推便捷，不太推荐使用以上代码自定义增加 Item 字段来适配 Item Loaders 的特性，除非某些场景下使用 \ +Item Loaders 能够极大方便开发时，才推荐使用下。 + +.. _Item Loaders: https://docs.scrapy.org/en/latest/topics/loaders.html +.. _add_xpath(): https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.add_xpath +.. _add_css(): https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.add_css +.. _add_value(): https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.add_value +.. _ItemLoader.load_item(): https://docs.scrapy.org/en/latest/topics/loaders.html#scrapy.loader.ItemLoader.load_item +.. _项对象: https://docs.scrapy.org/en/latest/topics/items.html#topics-items diff --git a/docs/topics/logging.md b/docs/topics/logging.md deleted file mode 100644 index adfd4be..0000000 --- a/docs/topics/logging.md +++ /dev/null @@ -1,82 +0,0 @@ -# Logging - -`Scrapy` 用 [`logging`](https://docs.python.org/3/library/logging.html#module-logging) 来记录日志，日志记录开箱即用，并且可以在某种程度上使用[日志设置](https://docs.scrapy.org/en/latest/topics/logging.html#topics-logging-settings)中列出的 `Scrapy` 设置进行配置。 - -本文不再介绍其详细配置及用法，请移步其官网文档中查看。`AyugeSpiderTools` 库会在 `settings` 中默认设置一个日志存储配置，默认放在项目的 `logs` 文件夹下，其名称为项目名称，如下所示： - -```python -# 日志管理 -LOG_FILE = "logs/DemoSpider.log" - -# 配置中 DemoSpider 是与 ayuge startproject 中的项目名称对应的 -``` - -## slog 日志 - -`ayugespidertools` 添加了 `loguru` 库来管理日志，可以很方便的查看不同日志等级的信息。可以在 `spider` 脚本中使用 `spider.slog` 或 `self.slog` 即可记录日志。同样，本库会在 `settings` 中也默认设置一个 `loguru` 的日志存储配置，也放在项目的 `logs` 文件夹下，如下所示： - -```python -# 本库只会持久化记录 error 级别的日志，但在调试时也可以方便地查看（包括其它等级的）控制台日志 -logger.add( - "logs/error.log", - level="ERROR", - rotation="1 week", - retention="7 days", - enqueue=True, -) -``` - -## 日志级别 - -`ayugespidertools` 中的 `loguru` 日志等级与 `Python` 的内置日志记录定义一致，大致分为 5 个不同的级别来指示给定日志消息的严重性。以下是标准的，按降序排列： - -1. `slog.CRITICAL`- 对于严重错误（最高严重性） -2. `slog.ERROR`- 对于常规错误 -3. `slog.WARNING`- 警告信息 -4. `slog.INFO`- 用于信息性消息 -5. `slog.DEBUG`- 用于调试消息（最低严重性） - -## 如何记录消息 - -至于如何使用 `scrapy logging` 来记录的示例就不再展示了，具体使用方法请看文档： [scrapy logging 使用说明](https://docs.scrapy.org/en/latest/topics/logging.html)，本库更推荐在调试阶段使用 `loguru` 来打印日志，会更快捷和明显地查看自己注意的部分。 - -`ayugespidertools` 会在 `startproject` 后默认再 `settings` 中添加一个日志配置，用于当前项目全局使用，可以在项目的各个目录文件中使用。 - -以下是如何使用`loguru` 的`WARNING` 级别记录消息的快速示例： - -```python -# project_name 为当前所在的 scrapy 项目名称 -from project_name.settings import logger - -logger.warning("This is a warning") -``` - -因为 `Loguru` 的理念是：**只有一个 [`logger`](https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger)**。将日志消息分派给已配置处理程序的对象。`Logger` 是 `loguru` 的核心对象，每个日志配置和使用都要通过对其中一个方法的调用。只有一个记录器，因此在使用之前不需要检索一个记录器。具体请查看文档：[loguru 使用说明](https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger) - -所以，你也可以直接使用如下方式，也会在全局中使用同一个 `loguru`。 - -```python -from loguru import logger - -logger.info("this is a info log") -``` - -## 从 spider 记录 - -以下是本库 `slog` 日志在 `spider` 中的使用示例： - -```python -import ayugespidertools - - -class MySpider(ayugespidertools.AyuSpider): - name = "myspider" - start_urls = ["https://scrapy.org"] - - def parse(self, response): - # 此条（error 级别以下的）日志默认下只会在控制台输出 - self.slog.info(f"info: Parse function called on {response.url}") - # 此条日志在默认下会持久化存储至 error.log 中 - self.slog.error(f"error: Parse function called on {response.url}") -``` -注：不影响 `scrapy` 自带的日志记录，可自行选择或同时使用。 diff --git a/docs/topics/logging.rst b/docs/topics/logging.rst new file mode 100644 index 0000000..4808532 --- /dev/null +++ b/docs/topics/logging.rst @@ -0,0 +1,106 @@ +.. _topics-logging: + +======= +Logging +======= + +Scrapy 用 `logging`_ 来记录日志，日志记录开箱即用，并且可以在某种程度上使用 `日志设置`_ 中列出的 \ +Scrapy 设置进行配置。 + +本文不再介绍其详细配置及用法，请移步其官网文档中查看。``AyugeSpiderTools`` 库会在 ``settings`` 中\ +默认设置一个日志存储配置，默认放在项目的 ``logs`` 文件夹下，其名称为项目名称，如下所示： + +.. code-block:: python + + # 日志管理 + LOG_FILE = "logs/DemoSpider.log" + + # 配置中 DemoSpider 是与 ayuge startproject 中的项目名称对应的 + +slog 日志 +============ + +ayugespidertools 添加了 ``loguru`` 库来管理日志，可以很方便的查看不同日志等级的信息。可以在 spider \ +脚本中使用 ``spider.slog`` 或 ``self.slog`` 即可记录日志。同样，本库会在 ``settings`` 中也默认设\ +置一个 loguru 的日志存储配置，也放在项目的 logs 文件夹下，如下所示： + +.. code-block:: python + + # 本库只会持久化记录 error 级别的日志，但在调试时也可以方便地查看（包括其它等级的）控制台日志 + logger.add( + "logs/error.log", + level="ERROR", + rotation="1 week", + retention="7 days", + enqueue=True, + ) + +日志级别 +========== + +ayugespidertools 中的 loguru 日志等级与 Python 的内置日志记录定义一致，大致分为 5 个不同的级别来指\ +示给定日志消息的严重性。以下是标准的，按降序排列： + +1. ``slog.CRITICAL``- 对于严重错误（最高严重性） +2. ``slog.ERROR``- 对于常规错误 +3. ``slog.WARNING``- 警告信息 +4. ``slog.INFO``- 用于信息性消息 +5. ``slog.DEBUG``- 用于调试消息（最低严重性） + +如何记录消息 +============= + +至于如何使用 `scrapy logging`_ 来记录的示例就不再展示了，本库更推荐在调试阶段使用 loguru 来打印日志，\ +会更快捷和明显地查看自己注意的部分。 + +ayugespidertools 会在 ``startproject`` 后默认在 settings 中添加一个日志配置，用于当前项目全局使用，\ +可以在项目的各个目录文件中使用。 + +以下是如何使用 loguru 的 WARNING 级别记录消息的快速示例： + +.. code-block:: python + + # project_name 为当前所在的 scrapy 项目名称 + from project_name.settings import logger + + logger.warning("This is a warning") + +因为 Loguru 的理念是：只有一个 `logger`_ 。将日志消息分派给已配置处理程序的对象。Logger 是 loguru 的\ +核心对象，每个日志配置和使用都要通过对其中一个方法的调用。只有一个记录器，因此在使用之前不需要检索一个记录\ +器。具体请查看文档：`loguru 使用说明`_ + +所以，你也可以直接使用如下方式，也会在全局中使用同一个 loguru。 + +.. code-block:: python + + from loguru import logger + + logger.info("this is a info log") + +从 spider 记录 +================ + +以下是本库 ``slog`` 日志在 ``spider`` 中的使用示例： + +.. code-block:: python + + import ayugespidertools + + + class MySpider(ayugespidertools.AyuSpider): + name = "myspider" + start_urls = ["https://scrapy.org"] + + def parse(self, response): + # 此条（error 级别以下的）日志默认下只会在控制台输出 + self.slog.info(f"info: Parse function called on {response.url}") + # 此条日志在默认下会持久化存储至 error.log 中 + self.slog.error(f"error: Parse function called on {response.url}") + +注：不影响 `scrapy` 自带的日志记录，可自行选择或同时使用。 + +.. _logging: https://docs.python.org/3/library/logging.html#module-logging +.. _日志设置: https://docs.scrapy.org/en/latest/topics/logging.html#topics-logging-settings +.. _scrapy logging: https://docs.scrapy.org/en/latest/topics/logging.html +.. _logger: https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger +.. _loguru 使用说明: https://loguru.readthedocs.io/en/stable/api/logger.html#loguru._logger.Logger diff --git a/docs/topics/pipelines.md b/docs/topics/pipelines.md deleted file mode 100644 index f905ab5..0000000 --- a/docs/topics/pipelines.md +++ /dev/null @@ -1,196 +0,0 @@ -# pipelines - -> 介绍本库中自带的常用 `pipelines` 管道。 - -需要使用本库中的 `pipelines` 的模板，需要在 `spider` 中修改如下： - -```python -from ayugespidertools.items import AyuItem -from ayugespidertools.spiders import AyuSpider - - -class DemoOneSpider(AyuSpider): # 第一处 - name = "demo_es" - custom_settings = { - "ITEM_PIPELINES": { - # 比如使用 Mysql 存储场景，激活此项则数据会存储至 Mysql - "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, # 第二处 - }, - } - ... - - def parse(self, response): - ... - yield AyuItem(...) # 第三处 -``` - -由上可知，使用还是比较简单的，记得其中三处的内容即可。以下内容不再对写法进行描述，都是相同的。 - -## 1. Mysql 存储 - -### 1.1. AyuFtyMysqlPipeline - -#### 1.1.1. 介绍 - -`AyuFtyMysqlPipeline` 为 `mysql` 同步存储的普通模式，具有自动创建所需数据库，数据表，自动动态管理 table 字段，表注释，也会自动处理常见（字段编码，`Data too long`，存储字段不存在等等）的存储问题。 - -属于经典的示例，也是网上教程能搜到最多的存储方式。 - -#### 1.1.2. 相关示例 - -可在 `DemoSpider` 中的 `demo_one`，`demo_three`，`demo_crawl`，`demo_eight`，`demo_file`，`demo_item_loader`，`demo_mysql_nacos` 中查看具体的代码示例。 - -### 1.2. AyuTwistedMysqlPipeline - -#### 1.2.1. 介绍 - -结合 `twisted` 实现 `Mysql` 存储场景下的异步操作。同样不用手动创建数据库表及字段。 - -比较推荐此方式方式，比较成熟。 - -#### 1.2.2. 相关示例 - -可在 `DemoSpdider` 项目中的 `demo_five` 中查看。 - -### 1.3. AyuAsyncMysqlPipeline - -#### 1.3.1. 介绍 - -结合 `aiomysql` 实现的 `async` 异步存储功能。目前需要手动创建数据库表及字段。 - -#### 1.3.2. 相关示例 - -可在 `DemoSpdider` 项目中的 `demo_aiomysql` 中查看示例。 - -## 2. MongoDB 存储 - -### 2.1. AyuFtyMongoPipeline - -`AyuFtyMysqlPipeline` 为 `mongodb` 同步存储的普通模式。 - -可在 `DemoSpider` 中的 `demo_two`，`demo_four`，`demo_eight` 中查看具体的代码示例。 - -### 2.2. AyuTwistedMongoPipeline - -结合 `twisted` 实现 `mongodb` 存储场景下的异步操作。 - -可在 `DemoSpdider` 项目中的 `demo_six` 中查看示例。 - -### 2.3. AyuAsyncMongoPipeline - -结合 `motor` 实现的 `async` 的异步存储功能。 - -可在 `DemoSpdider` 项目中的 `demo_mongo_async` 中查看示例。 - -## 3. PostgreSql 存储 - -就不再分别介绍了，命名规则一致，可通过对应的 `AyuFtyPostgresPipeline`，`AyuTwistedPostgresPipeline`，`AyuAsyncPostgresPipeline` 即可知其具体的场景及功能。其中 `asyncio` 场景下也暂不支持自动创建库表及字段。 - -## 4. Oracle 存储 - -同样地，具有的 `pipelines` 有 `AyuFtyOraclePipeline` 和 `AyuTwistedOraclePipeline`，但全都没有自动创建库表的功能，因为其相关报错没有其他库那么精准，虽也可实现但没有必要，请手动创建所需的库表及字段。 - -开发时候 `oracledb` 还不支持 `asyncio` 异步编程，目前 [v2.0.0](https://github.com/oracle/python-oracledb/releases/tag/v2.0.0) 已经支持，我也会在其稳定时添加其支持。 - -## 5. ElasticSearch 存储 - -同样地，具有的 `pipelines` 有 `AyuFtyESPipeline` 和 `AyuAsyncESPipeline`，没有结合 `twisted` 实现的异步方式。 - -可在 `DemoSpdider` 项目中的 `demo_es` 和 `demo_es_async` 中查看示例。 - -## 6. 消息推送服务 - -### 6.1. mq - -> 此场景下给出的是以 `pika` 实现的 `RabbitMQ` 的示例 - -对应的 `pipelines` 名称为 `AyuMQPipeline`，其中 `.conf` 中的所需配置如下： - -```ini -[mq] -host=*** -port=5672 -username=*** -password=*** -virtualhost=*** -queue=*** -exchange=*** -routing_key=*** - -# 一般只需配置以上参数即可，因为会有一些默认值，如果不需更改则不用配置，比如以下为非必须参数及其默认值： -durable=True -exclusive=False -auto_delete=False -content_type="text/plain" -delivery_mode=1 -mandatory=True -``` - -然后在 `spider` 中 `yield` 你所需结构的 `item` 即可（类型为 `dict`）。 - -### 6.2. kafka - -> 此场景给出的是以 `kafka-python` 实现的 `kafka` 推送示例 - -对应的 `pipelines` 名称为 `AyuKafkaPipeline`，其中 `.conf` 中的所需配置如下： - -```ini -[kafka] -bootstrap_servers=127.0.0.1:9092 #若多个用逗号分隔 -topic=*** -key=*** -``` - -然后在 `spider` 中 `yield` 你所需结构的 `item` 即可（类型为 `dict`）。 - -## 7. 文件下载 - -需要激活 `ITEM_PIPELINES` 对应的配置，然后在项目中配置相关参数。 - -`spider` 中的 `custom_settings` 所需配置如下： - -```python -"ITEM_PIPELINES": { - "ayugespidertools.pipelines.FilesDownloadPipeline": 300, - # 以下 AyuFtyMysqlPipeline 非必须，但只激活 FilesDownloadPipeline 时只会下载文件，但是 - # 并不会将信息与网页中的标题、描述等信息绑定，激活 AyuFtyMysqlPipeline 之类的选项后，可以自行 - # 添加其它可以描述文件的详细字段并存储对应场景的数据库中。 - "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 301, -} -``` - -`spider` 等其它项目配置中的所需详细设置示例如下： - -```ini -from pathlib import Path - -custom_settings = { - "ITEM_PIPELINES": { - "ayugespidertools.pipelines.FilesDownloadPipeline": 300, - "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 301, - }, - # 下载文件保存路径 - "FILES_STORE": Path(__file__).parent.parent / "docs", -} -``` - -具体示例请在 [DemoSpider](https://github.com/shengchenyang/DemoSpider) 项目中的 `demo_file` 和 `demo_file_sec` 查看。 - -## 8. oss 上传 - -> 此场景给出的是以 `oss2` 实现的 `oss` 上传示例 - -对应的 `pipelines` 名称为 `AyuAsyncOssPipeline`，其中 `.conf` 中的所需配置如下： - -具体的配置解释不再介绍了，请在 `item` 部分查看。 - -```ini -[oss:ali] -access_key= -access_secret= -endpoint= -bucket= -doc= -upload_fields_suffix=_file_url -oss_fields_prefix=_ -``` diff --git a/docs/topics/pipelines.rst b/docs/topics/pipelines.rst new file mode 100644 index 0000000..900c77a --- /dev/null +++ b/docs/topics/pipelines.rst @@ -0,0 +1,229 @@ +.. _topics-pipelines: + +========= +pipelines +========= + +介绍本库中自带的常用 ``pipelines`` 管道。 + +需要使用本库中的 pipelines 的模板，需要在 spider 中修改如下： + +.. code-block:: python + + from ayugespidertools.items import AyuItem + from ayugespidertools.spiders import AyuSpider + + + class DemoOneSpider(AyuSpider): # 第一处 + name = "demo_es" + custom_settings = { + "ITEM_PIPELINES": { + # 比如使用 Mysql 存储场景，激活此项则数据会存储至 Mysql + "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 300, # 第二处 + }, + } + ... + + def parse(self, response): + ... + yield AyuItem(...) # 第三处 + +由上可知，使用还是比较简单的，记得其中三处的内容即可。以下内容不再对写法进行描述，都是相同的。 + +1. Mysql 存储 +================ + +1.1. AyuFtyMysqlPipeline +----------------------------- + +1.1.1. 介绍 +^^^^^^^^^^^^^^^^ + +``AyuFtyMysqlPipeline`` 为 mysql 同步存储的普通模式，具有自动创建所需数据库，数据表，自动动态管理 \ +table 字段，表注释，也会自动处理常见（字段编码，``Data too long``，存储字段不存在等等）的存储问题。\ +属于经典的示例，也是网上教程能搜到最多的存储方式。 + +1.1.2. 相关示例 +^^^^^^^^^^^^^^^^^^^ + +可在 `DemoSpider`_ 中的 ``demo_one``，``demo_three``，``demo_crawl``，``demo_eight``，\ +``demo_file``，``demo_item_loader``，``demo_mysql_nacos`` 中查看具体的代码示例。 + +1.2. AyuTwistedMysqlPipeline +--------------------------------- + +1.2.1. 介绍 +^^^^^^^^^^^^^^^^ + +结合 ``twisted`` 实现 Mysql 存储场景下的异步操作。同样不用手动创建数据库表及字段。比较推荐此方式方式，\ +比较成熟。 + +1.2.2. 相关示例 +^^^^^^^^^^^^^^^^^^^ + +可在 DemoSpdider 项目中的 ``demo_five`` 中查看。 + +1.3. AyuAsyncMysqlPipeline +------------------------------ + +1.3.1. 介绍 +^^^^^^^^^^^^^^^^ + +结合 ``aiomysql`` 实现的 ``async`` 异步存储功能。目前需要手动创建数据库表及字段。 + +1.3.2. 相关示例 +^^^^^^^^^^^^^^^^^^^ + +可在 DemoSpdider 项目中的 ``demo_aiomysql`` 中查看示例。 + +2. MongoDB 存储 +================== + +2.1. AyuFtyMongoPipeline +----------------------------- + +``AyuFtyMysqlPipeline`` 为 ``mongodb`` 同步存储的普通模式。 + +可在 DemoSpider 中的 ``demo_two``，``demo_four``，``demo_eight`` 中查看具体的代码示例。 + +2.2. AyuTwistedMongoPipeline +--------------------------------- + +结合 ``twisted`` 实现 ``mongodb`` 存储场景下的异步操作。 + +可在 DemoSpdider 项目中的 ``demo_six`` 中查看示例。 + +2.3. AyuAsyncMongoPipeline +-------------------------------- + +结合 ``motor`` 实现的 ``async`` 的异步存储功能。 + +可在 DemoSpdider 项目中的 ``demo_mongo_async`` 中查看示例。 + +3. PostgreSql 存储 +===================== + +就不再分别介绍了，命名规则一致，可通过对应的 ``AyuFtyPostgresPipeline``，``AyuTwistedPostgresPipeline``，\ +``AyuAsyncPostgresPipeline`` 即可知其具体的场景及功能。其中 asyncio 场景下也暂不支持自动创建库表及字段。 + +4. Oracle 存储 +================= + +同样地，具有的 pipelines 有 ``AyuFtyOraclePipeline`` 和 ``AyuTwistedOraclePipeline``，但全都\ +没有自动创建库表的功能，因为其相关报错没有其他库那么精准，虽也可实现但没有必要，请手动创建所需的库表及字段。 + +开发时候 ``oracledb`` 还不支持 ``asyncio`` 异步编程，目前 `oracledb v2.0.0`_ 已经支持，我也会在\ +其稳定时添加其支持。 + +5. ElasticSearch 存储 +======================== + +同样地，具有的 pipelines 有 ``AyuFtyESPipeline`` 和 ``AyuAsyncESPipeline``，没有结合 ``twisted`` \ +实现的异步方式。 + +可在 DemoSpdider 项目中的 ``demo_es`` 和 ``demo_es_async`` 中查看示例。 + +6. 消息推送服务 +================= + +6.1. mq +------------ + +> 此场景下给出的是以 pika 实现的 ``RabbitMQ`` 的示例 + +对应的 pipelines 名称为 ``AyuMQPipeline``，其中 .conf 中的所需配置如下： + +.. code:: ini + + [mq] + host=*** + port=5672 + username=*** + password=*** + virtualhost=*** + queue=*** + exchange=*** + routing_key=*** + + # 一般只需配置以上参数即可，因为会有一些默认值，如果不需更改则不用配置，比如以下为非必须参数及其默认值： + durable=True + exclusive=False + auto_delete=False + content_type="text/plain" + delivery_mode=1 + mandatory=True + +然后在 spider 中 yield 你所需结构的 item 即可（类型为 ``dict``）。 + +6.2. kafka +-------------- + +此场景给出的是以 ``kafka-python`` 实现的 ``kafka`` 推送示例 + +对应的 pipelines 名称为 ``AyuKafkaPipeline``，其中 .conf 中的所需配置如下： + +.. code:: ini + + [kafka] + bootstrap_servers=127.0.0.1:9092 #若多个用逗号分隔 + topic=*** + key=*** + +然后在 spider 中 yield 你所需结构的 item 即可（类型为 ``dict``）。 + +7. 文件下载 +============== + +需要激活 ``ITEM_PIPELINES`` 对应的配置，然后在项目中配置相关参数。 + +spider 中的 ``custom_settings`` 所需配置如下： + +.. code-block:: python + + "ITEM_PIPELINES": { + "ayugespidertools.pipelines.FilesDownloadPipeline": 300, + # 以下 AyuFtyMysqlPipeline 非必须，但只激活 FilesDownloadPipeline 时只会下载文件，但是 + # 并不会将信息与网页中的标题、描述等信息绑定，激活 AyuFtyMysqlPipeline 之类的选项后，可以自行 + # 添加其它可以描述文件的详细字段并存储对应场景的数据库中。 + "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 301, + } + +spider 等其它项目配置中的所需详细设置示例如下： + +.. code:: ini + + from pathlib import Path + + custom_settings = { + "ITEM_PIPELINES": { + "ayugespidertools.pipelines.FilesDownloadPipeline": 300, + "ayugespidertools.pipelines.AyuFtyMysqlPipeline": 301, + }, + # 下载文件保存路径 + "FILES_STORE": Path(__file__).parent.parent / "docs", + } + +具体示例请在 `DemoSpider`_ 项目中的 ``demo_file`` 和 ``demo_file_sec`` 查看。 + +8. oss 上传 +============== + +此场景给出的是以 ``oss2`` 实现的 ``oss`` 上传示例 + +对应的 pipelines 名称为 ``AyuAsyncOssPipeline``，其中 .conf 中的所需配置如下： + +具体的配置解释不再介绍了，请在 item 部分查看。 + +.. code:: ini + + [oss:ali] + access_key= + access_secret= + endpoint= + bucket= + doc= + upload_fields_suffix=_file_url + oss_fields_prefix=_ + +.. _DemoSpider: https://github.com/shengchenyang/DemoSpider +.. _oracledb v2.0.0: https://github.com/oracle/python-oracledb/releases/tag/v2.0.0 diff --git a/docs/topics/settings.md b/docs/topics/settings.md deleted file mode 100644 index d4993e8..0000000 --- a/docs/topics/settings.md +++ /dev/null @@ -1,108 +0,0 @@ -# Settings - -`AyugeSpiderTools` 设置允许您自定义所有 `Scrapy` 及 `AyugeSpiderTools` 组件的行为，包括核心、扩展、管道和蜘蛛本身。 - -若您还不清楚 `Scrapy` 设置的知识，请跳转至 [Scrapy 文档](https://docs.scrapy.org/en/latest)查看教程。 - -以下内容主要介绍本库在具体场景下的配置示例： - -## VIT_DIR - -Default: `//VIT` - -项目运行配置 `.conf` 的路径，用于存放项目在不同场景下的配置，比如数据库链接配置。 - -## logger - -Default: `loguru.logger` - -用于日志记录，可按需设置。可与 `scrapy` 中的 `LOG_LEVEL` 和 `LOG_FILE`一同设置。 - -``` -logger.add( - "logs/error.log", - level="ERROR", - rotation="1 week", - retention="7 days", - enqueue=True, -) -``` - -## LOGURU_ENABLED - -Default: `True` - -是否开启 `loguru` 日志记录功能，开启时 `slog.("This is a log.")`。 -具体的说明请在 [logging](logging.md) 中查看。 - -## DATABASE_ENGINE_ENABLED - -旧配置名：`MYSQL_ENGINE_ENABLED`，已删除此配置名称 - -Default: `False` - -是否打开 `database` 引擎开关，用于数据入库前更新逻辑判断。 -如果是 `mysql` 场景，打开此项会激活 `mysql_engine` 和 `mysql_engine_conn`; -如果是 `postgresql` 场景，打开此项会激活 `postgres_engine` 和 `postgres_engine_conn`; - -## APP_CONF_MANAGE - -Default: `False` - -开启远程配置服务，支持 `consul` 和 `nacos` 工具，配合 `VIT_DIR` 中的 `.conf` 中的对应 `consul` 或 `nacos` 链接配置使用。 -如果两者都有，那优先取值 `consul`，即优先级 `consul` 大于 `nacos`。 - -## AIOHTTP_CONFIG - -Default: -``` -{ - # 设置 aiohttp.TCPConnector 中的配置 - "verify_ssl": None, - "fingerprint": None, - "use_dns_cache": None, - "ttl_dns_cache": None, - "family": None, - "ssl_context": None, - "ssl": None, - "local_addr": None, - "resolver": None, - "keepalive_timeout": None, - "force_close": None, - "limit": None, - "limit_per_host": None, - "enable_cleanup_closed": None, - "loop": None, - "timeout_ceil_threshold": None, - # 设置一些自定义的全局参数 - "sleep": None, - "retry_times": None, -} -``` - -这是使用 `aiohttp` 的 `yield AiohttpRequest` 来代替 `scrapy` 的 `yield Request` 和 `yield FormRequest` 来发送请求的功能； -其中的全局配置默配置全为 `None`，代表如果不配置其值或配置为 `None` 会使用 `aiohttp request` 的默认值，默认值示例如下： - -```shell -# 除了 sleep 和 retry_times，其它配置的字段及其默认值和 aiohttp 的 aiohttp.TCPConnector 保持一致。 -verify_ssl: bool = True, -fingerprint: Optional[bytes] = None, -use_dns_cache: bool = True, -ttl_dns_cache: Optional[int] = 10, -family: int = 0, -ssl_context: Optional[SSLContext] = None, -ssl: Union[bool, Fingerprint, SSLContext] = True, -local_addr: Optional[Tuple[str, int]] = None, -resolver: Optional[AbstractResolver] = None, -keepalive_timeout: Union[None, float, object] = sentinel, -force_close: bool = False, -limit: int = 100, -limit_per_host: int = 0, -enable_cleanup_closed: bool = False, -loop: Optional[asyncio.AbstractEventLoop] = None, -timeout_ceil_threshold: float = 5, -``` - -使用 `aiohttp` 来发送请求时，这个 `AIOHTTP_CONFIG` 及其子项不是必须参数，按需设置即可。现可使用统一的 `yield AiohttpRequest` 方式，且与 `aiohttp` 一样的请求参数来更方便地开发。 - -具体示例请查看 [downloader-middleware](downloader-middleware.md#3-发送请求方式改为-aiohttp) 的部分文档。 diff --git a/docs/topics/settings.rst b/docs/topics/settings.rst new file mode 100644 index 0000000..67c6c20 --- /dev/null +++ b/docs/topics/settings.rst @@ -0,0 +1,123 @@ +.. _topics-settings: + +======== +Settings +======== + +``AyugeSpiderTools`` 设置允许您自定义所有 Scrapy 及 AyugeSpiderTools 组件的行为，包括核心、扩展、\ +管道和蜘蛛本身。 + +若您还不清楚 Scrapy 设置的知识，请跳转至 `Scrapy`_ 文档查看教程。 + +以下内容主要介绍本库在具体场景下的配置示例： + +VIT_DIR +======= + +Default: ``//VIT`` + +项目运行配置 ``.conf`` 的路径，用于存放项目在不同场景下的配置，比如数据库链接配置。 + +logger +====== + +Default: ``loguru.logger`` + +用于日志记录，可按需设置。可与 scrapy 中的 ``LOG_LEVEL`` 和 ``LOG_FILE`` 一同设置。 + +.. code-block:: python + + logger.add( + "logs/error.log", + level="ERROR", + rotation="1 week", + retention="7 days", + enqueue=True, + ) + +LOGURU_ENABLED +============== + +Default: ``True`` + +是否开启 loguru 日志记录功能，开启时 ``slog.("This is a log.")``。 +具体的说明请在本文档的 :ref:`logging ` 部分查看。 + +DATABASE_ENGINE_ENABLED +======================= + +旧配置名：``MYSQL_ENGINE_ENABLED``，已删除此配置名称 + +Default: ``False`` + +是否打开 database 引擎开关，用于数据入库前更新逻辑判断。如果是 mysql 场景，打开此项会激活 \ +``mysql_engine`` 和 ``mysql_engine_conn``；如果是 ``postgresql`` 场景，打开此项会激活 \ +``postgres_engine`` 和 ``postgres_engine_conn``; + +APP_CONF_MANAGE +=============== + +Default: ``False`` + +开启远程配置服务，支持 ``consul`` 和 ``nacos`` 工具，配合 ``VIT_DIR`` 中的 ``.conf`` 中的对应 \ +consul 或 nacos 链接配置使用。如果两者都有，那优先取值 consul，即优先级 consul 大于 nacos。 + +AIOHTTP_CONFIG +============== + +Default: +:: + + { + # 设置 aiohttp.TCPConnector 中的配置 + "verify_ssl": None, + "fingerprint": None, + "use_dns_cache": None, + "ttl_dns_cache": None, + "family": None, + "ssl_context": None, + "ssl": None, + "local_addr": None, + "resolver": None, + "keepalive_timeout": None, + "force_close": None, + "limit": None, + "limit_per_host": None, + "enable_cleanup_closed": None, + "loop": None, + "timeout_ceil_threshold": None, + # 设置一些自定义的全局参数 + "sleep": None, + "retry_times": None, + } + +这是使用 ``aiohttp`` 的 ``yield AiohttpRequest`` 来代替 scrapy 的 ``yield Request`` 和 \ +``yield FormRequest`` 来发送请求的功能；其中的全局配置默配置全为 ``None``，代表如果不配置其值或配置\ +为 None 会使用 ``aiohttp request`` 的默认值，默认值示例如下： + +.. code:: bash + + # 除了 sleep 和 retry_times，其它配置的字段及其默认值和 aiohttp 的 aiohttp.TCPConnector 保持一致。 + verify_ssl: bool = True, + fingerprint: Optional[bytes] = None, + use_dns_cache: bool = True, + ttl_dns_cache: Optional[int] = 10, + family: int = 0, + ssl_context: Optional[SSLContext] = None, + ssl: Union[bool, Fingerprint, SSLContext] = True, + local_addr: Optional[Tuple[str, int]] = None, + resolver: Optional[AbstractResolver] = None, + keepalive_timeout: Union[None, float, object] = sentinel, + force_close: bool = False, + limit: int = 100, + limit_per_host: int = 0, + enable_cleanup_closed: bool = False, + loop: Optional[asyncio.AbstractEventLoop] = None, + timeout_ceil_threshold: float = 5, + +使用 aiohttp 来发送请求时，这个 ``AIOHTTP_CONFIG`` 及其子项不是必须参数，按需设置即可。现可使用统一\ +的 ``yield AiohttpRequest`` 方式，且与 aiohttp 一样的请求参数来更方便地开发。 + +具体示例请查看 :ref:`downloader-middleware ` 的部分文档。 + +.. _Scrapy: https://docs.scrapy.org/en/latest