fedfind

Fedora Finder查找Fedora。它提供了一个命令行界面和Python模块，用于查找并提供有关Fedora镜像和发布树的识别信息。试试看

fedfind images --release 35
fedfind images --release 36 --milestone Beta
fedfind images --release 36 --milestone Beta --compose 1 --respin 1
fedfind images --dist Fedora-Container --release 33 --compose 20211123 --respin 0
fedfind images --compose 20211210
fedfind images --composeid Fedora-Rawhide-20211210.n.0
fedfind images --release 34 --label Beta-1.1
fedfind images --release 5 --arch x86_64,ppc
fedfind images --release 15 --search desk

Fedora有稳定发布版、存档发布版、非常旧的存档发布版、"里程碑"发布版（Alpha / Beta）、发布验证“候选”组合、不稳定夜间组合和发布后夜间组合，所有这些都在不同的地方，具有几个不同的布局。没有关于所有各种组合/发布的地点和内容的规范数据库。我们在Fedora QA发现我们有几个工具需要知道如何从各种不同类型的发布中找到各种图像，以及关于各种发布/组合的地点和布局的点滴知识已经添加到不同的工具中。fedfind是为了将所有这些晦涩的知识整合到一个具有一致界面的单个代码库中而编写的。

fedfind允许您使用五个值指定发布/组合：'dist'、'release'、'milestone'、'compose'和'respin'。然后它可以找到该组合的位置，告诉您它是否存在，并给出所有包含在该发布中的图像的位置以及每个图像实际上包含的内容。作为此版本概念的一种替代方案，您也可以通过Pungi 4 / productmd '组合ID'或'组合标签'（见上面示例）查找发布。

fedfind在Python 2.7及更高版本（包括3.x）上运行。

安装和使用

fedfind 包含在官方 Fedora 和 EPEL 存储库中：要在 Fedora 上安装，请运行 dnf install fedfind，在启用 EPEL 的 RHEL / CentOS 上运行 yum install fedfind。您可能需要启用 updates-testing 存储库以获取最新版本。

您可以在 Pagure 上的 fedfind 项目页面 上访问，并使用 git clone https://pagure.io/fedora-qa/fedfind.git 进行克隆。Tarball 通过 PyPI 发布。

您可以从 tarball 中使用 fedfind CLI 而无需安装，例如从 tarball 根目录运行 ./fedfindlocal.py（您需要 productmd 和 six，以及 Python < 3.8 的 cached_property）。当然，您可以将 Python 模块复制到任何您喜欢的位置并就地使用。要全局安装 CLI 和模块，请运行 python setup.py install。

错误、pull 请求等。

您可以在 Pagure 上提交问题和 pull 请求。pull 请求必须经签名确认（使用 git 的 -s 参数）。通过签署您的 pull 请求，您同意 开发者来源证书

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

版本识别

fedfind 的一些用法依赖于对 'dist'、'release'、'milestone'、'compose'、'respin' 版本概念的了解，因此这里有一个快速入门指南。请注意，如果您打算仅使用现代 Pungi 4 生成的 compose 的 compose ID 或 URL 使用 fedfind，那么这一节对您可能不太感兴趣，您可能可以跳过。

在本节中，我们将使用 (release, milestone, compose, respin, dist) 的格式编写 release、milestone、compose、dist 五元组，其中 '' 表示省略的值，例如 (22, Beta, TC3, '', 'Fedora') 或 (22, '', '', '', 'Fedora')。请注意，'dist' 通常为 'Fedora'，这是其默认值，当未明确指定时使用。在概念上，'dist' 应该位于前面，但实际上 fedfind 函数接受这些值的顺序通常放在其他值之后，这是由于历史原因（在 fedfind 的版本方案创建时它还不存在）。

• Dist 是 fedfind 使用的术语，pungi 和 productmd 称其为 shortname；当 fedfind 创建时，这实际上并不存在，但现在 Fedora 项目生产的 composes 比以前多得多，其中一些具有不同的 dists / shortnames。在具有 compose ID 'Fedora-Rawhide-20160301.n.0' 的 compose 中，dist / shortname 是 Fedora；在具有 compose ID 'Fedora-Container-33-20211123.0' 的 compose 中，dist / shortname 是 Fedora-Container。《Fedora》是所有主线 composes 的 dist，这是默认值。《Fedora-Container》是夜间容器图像 composes 的 dist，每天为当前稳定版本生成一次，目前在发布工程输出的初始位置可以找到，而不是在镜像位置。同样，《Fedora-Cloud》和《Fedora-IoT》是当前稳定版本的夜间云和 IoT composes 的 dist。例如，(35, '', 20211210, 0, 'Fedora-Cloud') 将找到 Fedora 35 的第一个 2021-12-10 夜间云 compose。《FedoraRespin》是 live-respins 目录中当前发布后 live respin compose 的 dist；一次只有一个这样的（注意，这些只是半官方构建，由志愿者作为便利提供，它们没有官方 composes 的状态）。任何带有 dist 《FedoraRespin》的 release 或 compose 都用作 检查：如果 live-respins 目录中的现有内容与预期的发布（编号）或 compose（日期）不匹配，fedfind 将引发异常而不是返回 RespinRelease 实例。

• 发布版本通常是一个Fedora版本号，例如27、15或1。唯一被接受的非整数值是'Rawhide'，用于Rawhide的每日构建，以及'ELN'，用于ELN构建。从严格意义上讲，它们没有与它们相关联的明确发布版本：它们是永续滚动树。Rawhide每日构建的规范版本为（Rawhide，'', YYYYMMDD，N）（其中N是重制版本号）。请注意，python-wikitcms几乎使用与fedfind相同的版本概念，但Wikitcms为Rawhide每日构建的'验证事件'确实有发布版本：这是验证事件的属性，而不是构建的属性。因此，可能存在一个Wikitcms的验证事件（24，Rawhide，20151012，1，'Fedora'）对应于fedfind的构建（Rawhide，'', 20151012，1）。fedfind和python-wikitcms都认可这种情况，并将尝试转换彼此的值以方便起见。

• 里程碑表示里程碑或每日构建的类型。当前发布的有效里程碑是Beta、RC（或最终版，意思相同）、分支和生产。Alpha里程碑存在到Fedora 25，但Fedora 26及以后的发布版本没有Alpha；已找不到Alpha发布，因为Fedora 25及以前的Alpha现在已被移除。fedfind接受Rawhide作为里程碑，并将其转换为发布版本 - 因此（'', Rawhide，YYYYMMDD，N，'Fedora'）并不完全有效，但将被CLI和get_release函数处理，并转换为（Rawhide，'', YYYYMMDD，N，'Fedora'）。稳定发布版本没有里程碑；（23，RC，'', '', 'Fedora'）将被get_release和CLI接受，但在内部处理为（23，'', '', '', 'Fedora'）。生产里程碑表示所谓的'生产'构建，这通常也将是一个Alpha、Beta或最终'候选'构建 - 你可能能在两个不同的地方找到相同的构建，例如，带有生产里程碑和基于日期的构建和重制，或者带有Alpha、Beta或最终版里程碑和基于数字的构建和重制。这大约相当于通过构建ID搜索生产构建和通过构建标签搜索生产构建之间的差异。更多内容请参见下文的fedfind / Wikitcms 与 Pungi / productmd 版本化部分。目前，里程碑值对于除了Fedora之外的其他dists没有意义。

为了向后兼容，接受Cloud和Respin值；它们将被转换为Fedora-Cloud或FedoraRespin的dist值，以及一个空白的里程碑值。fedfind 4.0之前的版本将里程碑概念过度使用来处理这些dist值，而不是正确地处理它们作为dist值。此功能可能在未来的主要版本中删除。

• 构建是精确的构建标识符（在需要时）。对于候选构建，它始终为1。对于每日构建，它是一个YYYYMMDD格式的日期。稳定发布版本和里程碑发布版本没有构建。

• 重制是一个整数，每次重复一个本应具有相同版本的构建时都会增加。这个概念来自Pungi。例如，如果我们尝试在2016-03-01构建两个Rawhide每日构建，在fedfind的版本化中，它们是（Rawhide，'', 20160301，0）和（Rawhide，'', 20160301，1）。相应的Pungi / productmd '构建ID'样式版本化是Fedora-Rawhide-20160301.n.0和Fedora-Rawhide-20160301.n.1。

请注意，为了方便起见，fedfind将尝试检测'构建'值实际上是一个组合构建和重制，并将其拆分 - 因此你可以指定构建为1.7（对于构建1，重制7）或20160330.0或20160330.n.0（这两者都将被处理为构建20160330，重制0）。

一些示例

• 稳定版本： (23, '', '', '', 'Fedora')
• 测试版本： (24, Beta, '', '', 'Fedora')
• 候选版本： (24, Beta, 1, 7, 'Fedora')
• 分支夜间版本： (24, Branched, 20160330, 0, 'Fedora')
• 原野夜间版本： (Rawhide, '', 20160330, 1, 'Fedora')

测试套件包含许多对 get_release() 的测试，这些测试偶然间可以作为接受使用的进一步示例。fedfind CLI 和 get_release() 被设计用来猜测许多情况下省略的值，主要是为了辅助无人值守的使用，因此例如，脚本可以简单地指定 ('', Branched, '', '', 'Fedora') 以在指定日期的最新分支组合上运行，而无需知道当前的分支版本号。有关各种情况的更详细信息，可以在 get_release() 函数的 docstring 中找到。

fedfind / Wikitcms 与 Pungi / productmd 版本控制

在 Fedora 组合中使用 Pungi 4 之前，fedfind / Wikitcms 版本控制系统就已经开发出来了。当时为了使系统继续工作，非常仓促地将 Pungi / productmd 的 'respin' 概念塞入 fedfind / Wikitcms 版本控制概念中，并且还添加了 productmd 的 'short' 概念到 fedfind 中（通常称为 'dist'，这在 Fedora 的上下文中更准确地描述了其功能）。

目前，fedfind 尽量保持与其遗留版本控制方法尽可能兼容，同时支持使用 productmd 版本控制概念进行版本识别。例如，非 Pungi 4 组合有一个粗略伪造的 cid 属性，至少在解析为 '组合 ID' 时会生成正确的版本号，并且 get_release() 可以解析 大多数（我们力求 '全部'，但我们也是现实主义者！）组合 ID、组合 URL 和组合标签，并返回适当的发布实例。

Pungi 有几个类似版本的概念。对 fedfind 来说，最重要的是 '组合 ID' 和 '标签'。所有 Pungi 组合都有一个 '组合 ID'。并非所有都有标签——只有 '生产' 组合才有（不是 '夜间' 或 '测试' 组合）。

组合 ID 看起来像 Fedora-24-20160301.n.0（夜间），或 Fedora-Rawhide-20160302.t.1（测试），或 Fedora-24-20160303.0（生产）。发布号、日期和组合类型总会以某种方式指示出来。对于 Fedora 来说，respin 值应该始终存在。没有类型的 '里程碑' 指示。

标签看起来像 Alpha-1.2，或 Beta-13.16。有一个支持里程碑的列表（包括 Fedora 的 Alpha 和 Beta，但不包括最终版本——productmd 使用 RC 代替）。第一个数字是公共发布号（与 Fedora 不同，RHEL 有编号的里程碑发布）；第二个是 respin 值，它被视为更私有的/内部属性。该方案设计周围的系统似乎是，会生产并测试多个 "Alpha 1" respin，最终一个是作为公共的 "Alpha 1" 发布——因此 'respins' 概念大致涵盖了 Fedora 以前使用的 "TC" 和 "RC" 组合的相同领域。

主线 Fedora 夜间组合的构建就像你预期的那样：短名称是 'Fedora'，发布号是 'Rawhide' 或实际的发布号，类型是夜间，如果同一天运行多个组合，respin 值将增加（通常只有在第一个失败并希望在第二天之前修复它时才会这样做）。因此，Fedora 夜间组合 ID 看起来像 Fedora-Rawhide-20180119.n.0，例如。

对于里程碑发布，Fedora 构建 '生产' 组合，标签号始终设置为 1，每次运行组合时 respin 号码增加。因此，对于 Fedora 24 Alpha 验证测试，我们构建了 Alpha-1.1、Alpha-1.2、Alpha-1.3 等等，直到 Alpha-1.7 最终作为公共 Alpha 发布发布。每个组合也都有一个 Fedora-24-20160323.0 格式的组合 ID。

对于云、容器和物联网镜像的发布后夜间组合，其构建几乎就像你预期的那样，但类型是 '生产' 而不是 '夜间'。因此，它们的组合 ID 看起来像 Fedora-Cloud-27-20180119.0 或 Fedora-IoT-26-20171215.1。它们的标签总是 RC-(date).(respin)，例如 RC-20180119.0。

当前的fedfind应该能够在几乎所有情况下通过其组成ID或其标签找到任何可找到的Fedora组成。Fedora的'生产'组成最初在一个位置（在kojipkgs上，与夜间分支和Rawhide组成并行，目录名称基于组成ID）落地，然后镜像到另一个位置（在alt上，目录名称基于组成标签）。当您搜索某个特定的生产/候选组成时，您是否找到了它的kojipkgs位置或其alt位置，这在一定程度上取决于您如何搜索它。通过组成标签搜索，或者使用类似里程碑 Alpha、组成 1、respin 7的搜索，通常会找到它的alt位置（作为Compose类实例）。通过组成ID搜索，或者使用类似里程碑 生产、组成 20160323、respin 0的搜索，通常会找到它的kojipkgs位置（作为Production类实例）。然而，当您通过类似组成ID的值进行搜索时，可以将get_fedora_release参数的promote设置为True，fedfind将尝试找到Compose类（alt位置）。所有实际存在的Pungi 4组成的fedfind发布实例都应该具有组成ID作为它们的cid属性。如果组成有一个标签，它应该作为label属性可用。

CLI

fedfind CLI命令为您提供发布映像的URL。例如，fedfind images -r 25将打印所有Fedora 25映像的URL。您可以通过各种方式过滤结果。有关更多信息，请使用fedfind -h和fedfind images -h。

Python模块

Python模块提供了对所有fedfind功能的访问。

示例用法

import fedfind.release

comp = fedfind.release.get_release(release=27)
print comp.location
for img in comp.all_images:
    print(img['url'])

模块设计和API

fedfind的主要部分是位于fedfind.release的Release类。主要入口点是fedfind.release.get_release() - 在几乎所有情况下，您都会从获取一个发布开始，该函数接受标识发布的release、milestone、compose、respin和dist值作为其参数，并返回一个Release子类的实例。您也可以传递url（它应该是一个Pungi 4组成的/compose目录，或者作为一个特殊情况，对于位于那里的半官方发布后实时respin，是https://dl.fedoraproject.org/pub/alt/live-respins/），cid（一个Pungi 4组成ID）或label（一个Pungi 4组成标签）作为发布/里程碑/组成/respin的替代方案。如果您传递一个url或cid，fedfind将运行交叉检查以确保发现的组成的URL或CID实际上与您请求的一致，如果不一致，则引发异常。

使用过fedfind 1.x的人可能会记得用于描述图像的Image类和用于搜索的Query类。这两个类都从fedfind 2.x中删除，以支持产品md风格的元数据。所有Release实例都有一个metadata字典，如果发布存在，它将包含一个images项，该项本身是一个字典，包含产品md images.json文件格式的图像元数据。对于Pungi 4发布，这直接从images.json中读取；对于Pungi 4之前的发布，fedfind以类似格式合成元数据。

您还可以使用all_images便利属性；这基本上是图像元数据的一种扁平化形式。它是一个图像字典列表，每个图像字典都以与产品md图像字典相同的基本形式存在，但增加了一个variant条目以指示其变体（在原始产品md布局中，图像字典按变体和体系结构分组，这对于许多用例来说有点麻烦）。请注意，由于从Fedora 9开始，从fedfind 3.1.0以来，boot.iso文件不包括在all_images（或更底层的all_paths）中。

自fedfind 3.3.0版本以来，图像字典也添加了url和direct_url条目，它们提供了图像文件的完整HTTPS URL（因此fedfind消费者不再需要担心通过组合发布location或alt_location和图像path来构造URL）。url可能会通过https://download.fedoraproject.org镜像重定向器，该重定向器尝试在镜像之间分配负载。direct_url始终是直接链接。如果图像在公共镜像系统中，它将使用https://dl.fedoraproject.org镜像。除非您有强烈的理由使用direct_url，否则请使用url，以避免对服务器造成过度负载。

您应根据您的用例生成相应的查询。fedfind 1.x有专门的查询接口的主要原因是为了通过尽可能避免Koji查询并对其定制来加快夜间构建的速度；由于fedfind不再需要执行缓慢的Koji查询来查找图像，因此不再需要Query类，您始终可以直接在metadata['images']或all_images中的数据上操作。请注意，图像subvariant属性对于识别图像非常有用；您还可能想使用productmd中的identify_image函数来实现此目的。

fedfind中的所有方法和函数都有直接的文档：请参阅文档字符串以了解它们的目的。属性只要有目的就不明显，就会用注释进行说明。

所有未以_开头的方法、函数、属性和属性都认为是“公共的”。公共方法、函数签名和所有公共数据类型仅在主要版本中更改。fedfind无法控制productmd元数据的形式或内容，因此何时以及如何更改超出了我们的控制范围；我将尽最大努力保持旧构建合成的合成元数据与当前Pungi产生的结果大致一致，尽管它现在并不完美，并且可能永远不会完美（它有点定制为我实际需要的信息）。

fedfind能做的事情

fedfind可以做一些有用的东西，不仅仅是查询发布中的图像

• Release.check_expected()检查发布中是否都存在“预期”的图像。
• Release.previous_release()尝试确定“前一个”发布是什么，尽管这可能很困难，并且可能不会总是按预期工作或返回您期望的结果。
• helpers.get_current_release()告诉您当前的Fedora版本。

它是如何工作的（大致上）

fedfind有关Fedora存储各种构建的信息。对于Pungi 4构建类型，查找构建就是fedfind需要做的全部工作；它从元数据中读取有关构建中包含哪些图像的所有信息，并公开这些信息。

对于非Pungi 4构建（旧稳定版本）和修改过且其元数据被剥离的Pungi 4构建（当前稳定和里程碑版本），fedfind使用dl.fedoraproject.org上存在的imagelist文件，这些文件包含整个树中每个图像文件的列表。它找到被查询的特定构建的图像，然后从结果中生成一个相对于镜像树顶部的相对路径。然后它可以将其与已知的前缀组合以生成HTTPS URL。

对于元数据，fedfind首先尝试查看构建是否最初是用Pungi 4制作的，并且其元数据可在kojipkgs上的元数据存档中找到。它尝试从图像文件名中猜测构建标签，然后从构建标签中猜测构建ID，然后在存档中查找该构建的元数据。如果成功，它尝试将imagelist文件中发现的每个图像与原始元数据中的图像字典进行匹配，并将两者结合起来，以便路径信息是正确的，但所有其他图像信息都来自原始元数据，而不是由fedfind合成。

对于任何未找到匹配原始图像字典的已发现图像，以及没有可用原始元数据的合成，fedfind通过分析文件路径、猜测可以猜测的属性并省略其他属性来合成类似productmd风格的元数据。

在任何情况下，结果都是使元数据和派生属性（如all_images）尽可能相似，以便于不同类型的合成，这样fedfind消费者可以像使用Pungi 4合成那样与非Pungi 4合成进行交互（在元数据发现和合成实现的范围内，有些内容根本不被合成所覆盖）。

注意事项

速度和资源使用

使用小元数据文件（用于元数据合成）和仍然相当小的本地缓存的图像列表文件（用于非元数据合成），fedfind比以前快得多。不过，它仍然可能需要几秒钟来完成所有解析和分析。

当用作模块时，它将在发布实例的生命周期内缓存属性和图像列表。图像列表文件将根据来自服务器的'最后修改时间'进行缓存（在~/.cache/fedfind中）。对于每个新的发布实例，fedfind将访问服务器以检索最后修改时间头，但如果缓存的副本与该时间匹配，则不会重新下载文件。这些文件也相当小，所以在任何情况下下载都不会花很长时间。如果由于某种原因下载失败，但我们有必要的列表的缓存副本，fedfind将正常工作，但会记录一个警告，表明它正在使用可能过时的缓存数据。

如果~/.cache/fedfind对运行fedfind的用户不可写，我们将回退到使用仅对进程生命周期有效的临时缓存位置（并在退出时删除）。这至少确保了fedfind在这种情况下可以工作，但会导致它变慢，并且进行更多往返。

您可以将环境变量FEDFIND_NO_CACHE设置为任何值以禁用此缓存。文件列表仍然会写入到~/.cache/fedfind，但缓存的副本永远不会被使用，列表将在每次请求时重新下载。这是为受缓存影响的下游项目设计的（特别是，使用pyvcr的一个项目）。

它不应使用太多带宽（尽管我没有真正测量），但显然如果服务器被fedfind请求淹没，服务器管理员不会高兴，所以不要完全滥用它——如果您想做一些脚本化的事情，请至少使用模块并重用发布实例，以便查询被缓存。

找不到不存在的

除了稳定版本以外的所有发布版本都会消失。fedfind可以找到回溯到Fedora Core 1的稳定版本，但它不会找到Fedora 14 Alpha、Fedora 19 Beta TC3或2-3周前的夜间版本。这不是fedfind的错误——那些图像实际上已经不再公开可用。夜间版本只保留几周，特定里程碑的候选合成通常在我们前进到另两个里程碑之后就会消失，预发布版本（Alpha和Betas）通常在相关发布版本稳定后的一段时间内消失。fedfind只会找到实际上存在的。

请注意，fedfind也不是为了找到旧的非稳定版本的概念位置而设计的。由于它们的短暂性，它用于夜间构建和候选合成的模式仅反映了当前的做法，并且将在任何做法改变时进行更新。它没有大量关于我们旧合成确切命名约定的知识。如果您执行comp = fedfind.release.Compose(12, 'Final', 'TC4')并读取出comp.location或类似的内容，您得到的几乎肯定不是Fedora 12 Final TC4在它存在时实际存在的位置。

没有次要架构

目前，fedfind 并不处理任何二级架构。虽然如此，它将找到 PPC 版本的镜像用于 PPC 是主要架构的发布，以及 i686 版本的镜像用于 i686 是主要架构的发布。

致谢

这基本上都是我的责任。请注意，除了外部依赖之外，fedfind 的早期版本（1.1.2 及之前）包含由 Daniel Greenfield 在此处维护的 cached_property 实现的副本。自 1.1.3 版本起已删除该副本。

许可

Fedora Finder 在 GPL 3 或任何后续版本下可用。副本包含在 COPYING 文件中。