x-ray 0.3.3

x-ray 是一个 Python 库，用于查找 PDF 文档中的错误编辑。

为什么？

在 Free Law Project，我们收集了数百万份 PDF。一个持续存在的问题是人们无法正确编辑内容。他们没有以正确的方式进行操作，而是在黑色文本上绘制了一个黑色矩形或黑色高光，然后就结束了。好吧，当这种情况发生时，您只需选择矩形下方的文本，您就可以再次阅读它。不是很好。

在目睹了这个问题多年后，我们决定弄清楚它有多普遍，所以在一些帮助下，我们构建了这个简单的工具。您为工具提供 PDF 的路径。它会告诉你它是否有毫无价值的编辑。

接下来是什么？

现在，x-ray效果很好，我们正在使用它来分析我们集合中的文档。不过可能会更好。错误的编辑有多种形式。有关我们尚不支持的其他示例，请参阅问题选项卡。我们希望您能帮助解决一些更棘手的案件。

安装

用诗歌做：

poetry add x-ray

使用 pip，那就是：

pip install x-ray

用法

您可以在命令行上轻松使用它。安装后，只需：

% xray path/to/your/file.pdf
{
  "1": [
    {
      "bbox": [
        58.550079345703125,
        72.19873046875,
        75.65007781982422,
        739.3987426757812
      ],
      "text": "The Ring travels by way of Cirith Ungol"
    }
  ]
}

或者，如果您在某处的服务器上有 hte 文件，请给它一个 URL。如果它以 开头https://，它将被解释为要下载的 PDF：

% xray https://free.law/pdf/congressional-testimony-michael-lissner-free-law-project-hearing-on-ethics-and-transparency-2021-10-26.pdf
{}

您现在可以做的一个有趣的技巧是制作一个每行有一个 URL 的文件，将其命名为urls.txt. 然后你可以运行它来检查每个 URL：

xargs -n 1 xray  < urls.txt

不管你xray在命令行上运行什么，你都会得到 JSON 作为输出。当你拥有它时，你可以将它与jq. 格式如下：

• 这是一个字典。
• 键是页码。
• 每个页码都映射到一个字典列表。
• 这些字典中的每一个都映射到两个键。
• 第一个键是bbox。这是一个四元组，指示坏编辑的左上角和右下角的 x、y 位置。
• 第二个关键是text。这是坏矩形下的文本。

很简单。

如果您更喜欢长格式，也可以将其用作 Python 模块：

% pathon -m xray some-file.pdf

但这并不容易记住。

如果您想要更多，当然可以xray在 Python 中使用：

from pprint import pprint
import xray
bad_redactions = xray.inspect("some/path/to/your/file.pdf")  # Pathlib works too
pprint(bad_redactions)
{1: [{'bbox': (58.550079345703125,
               72.19873046875,
               75.65007781982422,
               739.3987426757812),
      'text': 'Aragorn is the one true king.'}]}

输出与上面相同，只是它是 Python 对象，而不是 JSON 对象。

如果您已经将文件内容作为bytes对象，那也可以：

some_bytes = requests.get("https://lotr-secrets.com/some-doc.pdf").content
bad_redactions = xray.inspect(some_bytes)

请注意，由于该inspect方法无论如何都使用相同的签名，因此您为其提供的对象的类型是必不可少的：

这意味着，如果您将磁盘上的文件名作为 bytes 对象而不是 a 提供str，它将无法正常工作。这将失败：

xray.inspect(b"some-file-path.pdf")

差不多就是这样。无需学习配置文件或其他变量。你给它一个文件名。如果其中有错误的编辑，您很快就会发现。

这个怎么运作

在幕后，xray使用高性能PyMuPDF 项目来解析 PDF。这是一个很棒的项目。

您可以阅读源代码以了解其工作原理，但总体思路是：

1. 在 PDF 中查找矩形。

2. 在同一位置查找字母

3. 渲染矩形

4. 检查矩形以查看它是否都是一种颜色

PDF 格式庞大而复杂，因此很难完美地做到这一切。我们尽力而为，但总是有更多工作要做，以使其变得更好。捐款和赞助的工作帮助。

贡献

请查看 Github 上的问题列表以了解我们需要的内容，或者如果您有任何问题，请开始对话。在您进行第一次贡献之前，我们需要签署一份贡献者许可协议。请参阅 repo 中的模板。

部署

发布通过 Github Actions 自动发生。要触发自动构建：

1. 更新 pyproject.toml 中的版本

2. 用“v0.0.0”之类的东西标记提交。

如果您希望手动创建新版本，过程是：

1. 更新版本信息pyproject.toml

2. 使用 Poetry配置您的 Pypi 凭据

3. 构建并发布版本：

poetry publish --build

执照

此存储库在许可 BSD 许可下可用，可以轻松安全地合并到您自己的库中。

欢迎拉取和功能请求。可以在 GitHub 中进行在线编辑（而且很简单！）。