feed-archiver 2.0.6

详细描述

安装

$ pip3 install --user feed-archiver

$ docker compose up

$ docker pull "registry.gitlab.com/rpatterson/feed-archiver"

$ docker run --rm -it "registry.gitlab.com/rpatterson/feed-archiver" ...

使用方法

在目录中创建一个./.feed-archiver.yml YAML文件，作为所有要存档的源根目录。该YAML文件必须有一个顶级defaults键，其值是一个定义默认或全局选项的对象。特别是，该部分中的base-url键，其值必须是一个字符串，它定义了客户端从该位置提供存档的外部基本URL，并用于在无法使用相对URL的位置组装绝对URL。该文件还必须有一个顶级feeds键，其值是一个定义在此目录中要存档的远程源的对象数组或列表。每个源对象必须包含一个remote-url键，其值是一个包含要存档的单独源URL的字符串。在最简单的情况下，这可以只是一个文件，如下所示

defaults:
  base-url: "https://feeds.example.com"
feeds:
  - title: "Garply Podcast Title"
    remote-url: "\
    https://foo-username:secret@grault.example.com\
    /feeds/garply.rss?bar=qux%2Fbaz#corge"
...

然后在那个目录中运行$ feed-archiver命令，以从当前版本的源更新存档，并编写一个包含指向存档源链接的HTML索引

$ cd "/var/www/html/feeds/"
$ feed-archiver
INFO:Retrieving feed URL: https://foo-username:secret@grault.example.com/feeds/garply.rss
...
INFO:Writing HTML index: /var/www/html/feeds/index.html

有关选项和参数的详细信息，请参阅命令行帮助

$ feed-archiver --help
usage: feed-archiver [-h] [--log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}]
                     [--archive-dir [ARCHIVE_DIR]]
                     {update,relink} ...

Archive RSS/Atom syndication feeds and their enclosures and assets.

positional arguments:
  {update,relink}       sub-command
    update              Request the URL of each feed in the archive and update contents accordingly.
    relink              Re-link enclosures to the correct locations for the current configuration.

options:
  -h, --help            show this help message and exit
  --log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,DEBUG,NOTSET}
                        Select logging verbosity. (default: INFO)
  --archive-dir [ARCHIVE_DIR], -a [ARCHIVE_DIR]
                        the archive root directory into which all feeds, their enclosures and assets
                        will be downloaded (default: .)

如果使用Docker容器镜像，也可以从命令行运行容器

$ docker compose run "feed-archiver" feed-archiver --help
usage: feed-archiver [-h]

要将投递项的附件链接到备用层次结构，例如媒体库中，请将一个名为“enclosures”的键添加到投递配置中，其值为一个对象列表/数组，每个对象定义一个链接到投递项附件的备用路径。顶级defaults键中定义的所有enclosures都将用于所有投递。跨多个enclosures配置共享的配置可以放在相应的defaults / plugins / enclosures / {plugin_name}对象中。附件的实际链接委托给插件。

当使用$ feed-archiver update子命令从远程投递URL更新存档时，新项的附件将按配置进行链接。如果enclosures配置更改或任何使用的插件引用可能更改的外部资源，例如当使用sonarr插件且Sonarr已升级或重命名相应的视频文件时，请使用$ feed-archiver relink命令更新所有现有链接。

插件

如何将投递项附件链接到媒体库是由插件或附加组件负责的。具体来说，enclosures配置中的plugin键必须是一个字符串，它是注册在feedarchiver.enclosures组中的Python入口点的名称。入口点对象引用必须指向一个接受以下参数的feedarchiver.enclosures.EnclosurePlugin子类

1. parent=dict

   如果插件在defaults中为所有投递配置，则为feedarchiver.archive.Archive；如果为特定投递定义，则为feedarchiver.feed.ArchiveFeed。

2. config=dict

   特定附件配置的序列化存档配置YAML的反序列化Python字典对象。

并且其实例必须是可调用的，并且在调用时必须接受以下参数

1. archive_feed=feedarchiver.feed.ArchiveFeed

   内部表示存档中单个投递的对象。

2. feed_elem=xml.etree.ElementTree.Element，item_elem=xml.etree.ElementTree.Element

   表示整个投递的Python XML元素对象，对于RSS，这是<channel>子元素，而对于Atom，这是根<feed>元素，以及表示特定投递项的类似对象。

3. feed_parsed=feedparser.util.FeedParserDict，item_parsed=feedparser.util.FeedParserDict

   表示整个投递和特定投递项的feedparser对象。

4. url_result=lxml.etree._ElementUnicodeResult

   包含特定附件URL的lxml特殊字符串对象。可以用来访问特定的附件元素。

5. enclosure_path=pathlib.Path

   归档中封套的路径，作为Python pathlib.Path对象，最佳猜测的文件基本名（包括后缀或扩展名），适用于给定的封套。此后缀考虑了封套URL的后缀、对封套URL请求的响应的Content-Type头，以及封套元素XML中任何type属性的值。

6. match=re.Match

   如果match-pattern与match-string键中展开的Python格式字符串匹配，则为Python正则表达式匹配对象。特别有用的是在match-pattern中指定正则表达式分组，然后在template中使用匹配这些分组的match-string部分的格式。如果match-pattern不匹配，则不会链接封套。如果存在符号组名，例如模式中的(?P<foo_group_name>.*)，则在格式字符串中也可以通过名称访问，例如{foo_group_name.lower()}。如果没有提供match-string，则使用默认值，该值将源标题、项目标题和封套基本名（包括扩展名）组合起来

   {utils.quote_sep(feed_parsed.feed.title).strip()}/{utils.quote_sep(item_parsed.title).strip()}{enclosure_path.suffix}

如果插件返回值，则必须是字符串列表，并将用作链接封套的目标路径。相对路径相对于归档根进行解析。这些路径没有转义，因此如果需要转义，则必须是插件配置的一部分。如果没有插件链接给定的封套，则任何具有fallback键为true的插件都将应用。以下是一个示例enclosures定义

defaults:
  base-url: "https://feeds.example.com"
  plugins:
    enclosures:
      sonarr:
        url: "http://localhost:8989"
        api-key: "????????????????????????????????"
  enclosures:
    # Link all feed item enclosures into the media library under the podcasts
    # directory.  Link items into an album directory named by series title if
    # matching.
    - template: "\
      /media/Library/Music/Podcasts\
      /{utils.quote_sep(feed_parsed.feed.title).strip()}\
      /{series_title}\
      /{utils.quote_sep(item_parsed.title).strip()}{enclosure_path.suffix}"
      match-string: "{utils.quote_sep(item_parsed.title).strip()}"
      match-pattern: "\
      (?P<item_title>.+) \\((?P<series_title>.+) \
      (?P<season_number>[0-9])(?P<episode_numbers>[0-9]+[0-9Ee& -]*)\\)"
    # Otherwise link into "self-titled" album directories of the same name as the
    # feed.
    - template: "\
      /media/Library/Music/Podcasts\
      /{utils.quote_sep(feed_parsed.feed.title).strip()}\
      /{utils.quote_sep(feed_parsed.feed.title).strip()}\
      /{utils.quote_sep(item_parsed.title).strip()}{enclosure_path.suffix}"
      fallback: true
feeds:
  - remote-url: "\
    https://foo-username:secret@grault.example.com\
    /feeds/garply.rss?bar=qux%2Fbaz#corge"
    enclosures:
      # This particular feed is a podcast about a TV series/show.  Link enclosures
      # from feed items about an individual episode next to the episode video file as
      # an external audio track using a non-default plugin.
      - plugin: "sonarr"
        match-string: "{utils.quote_sep(item_parsed.title).strip()}"
        match-pattern: "\
        (?P<item_title>.+) \\((?P<series_title>.+) \
        (?P<season_number>[0-9])(?P<episode_numbers>[0-9]+[0-9Ee& -]*)\\)"
        stem-append: "-garply"
...

./Feeds/{utils.quote_sep(feed_parsed.feed.title).strip()}/{utils.quote_sep(item_parsed.title).strip()}{enclosure_path.suffix}

贡献

注意：[此项目托管在GitLab上]。GitHub上有[镜像]，但请使用GitLab来报告问题、提交PR/MR以及任何其他开发或维护活动。

有关如何开始开发的更多详细信息，请参阅./CONTRIBUTING.rst文件。