作为库使用

Maigret 的 CLI 只是对一套异步 Python API 的薄包装。你完全可以将 Maigret 嵌入自己的工具、流水线和 OSINT 工作流中,无需通过 shell 调用。

本页介绍常见用法。底层函数的完整参数列表请参见源码中的 maigret.checking.maigret。

安装

pip install maigret

最小示例

一个可直接运行、面向访问量排名前 500 站点的端到端搜索示例:

import asyncio
import logging

from maigret import search as maigret_search
from maigret.sites import MaigretDatabase

# Load the bundled site database
db = MaigretDatabase().load_from_path(
    "maigret/resources/data.json"
)

# Pick which sites to scan (same filtering the CLI uses)
sites = db.ranked_sites_dict(top=500)

results = asyncio.run(
    maigret_search(
        username="soxoj",
        site_dict=sites,
        logger=logging.getLogger("maigret"),
        timeout=30,
        is_parsing_enabled=True,
    )
)

for site_name, result in results.items():
    if result["status"].is_found():
        print(site_name, result["url_user"])

关键点:

maigret_search 是一个 async 函数 —— 在脚本中用 asyncio.run(...) 包裹,或在你自己的事件循环中 await 调用即可。
is_parsing_enabled=True 会启用 socid_extractor,从而把个人主页中的字段(个人简介、关联账号、各类 uid 等)填充到 result["ids_data"]。
返回字典中的每一项都包含一个带有 is_found() 方法的 "status" 对象,以及 url_user、http_status、rank、ids_data 等字段。

站点过滤

ranked_sites_dict 支持的过滤参数与 CLI 完全一致:

# All sites tagged as coding, top 200 by rank
sites = db.ranked_sites_dict(top=200, tags=["coding"])

# Exclude NSFW and dating sites
sites = db.ranked_sites_dict(excluded_tags=["nsfw", "dating"])

# Only specific sites by name
sites = db.ranked_sites_dict(names=["GitHub", "Reddit", "VK"])

# Include disabled sites (useful for maintenance / self-check)
sites = db.ranked_sites_dict(disabled=True)

在已有事件循环中运行

如果你的应用本身就在运行一个 asyncio 事件循环(例如 FastAPI、aiohttp 服务、Discord 机器人等),请直接 await maigret_search,不要再调用 asyncio.run:

async def check_username(username: str) -> dict:
    results = await maigret_search(
        username=username,
        site_dict=sites,
        logger=logger,
        timeout=30,
    )
    return {
        name: r["url_user"]
        for name, r in results.items()
        if r["status"].is_found()
    }

通过代理转发

CLI 中暴露的代理 / Tor / I2P 选项,在库中就是普通的关键字参数:

results = await maigret_search(
    username="soxoj",
    site_dict=sites,
    logger=logger,
    proxy="socks5://127.0.0.1:1080",
    tor_proxy="socks5://127.0.0.1:9050",   # used for .onion sites
    i2p_proxy="http://127.0.0.1:4444",     # used for .i2p sites
    timeout=30,
)

完整函数签名

async def maigret(
    username: str,
    site_dict: Dict[str, MaigretSite],
    logger,
    query_notify=None,
    proxy=None,
    tor_proxy=None,
    i2p_proxy=None,
    timeout=30,
    is_parsing_enabled=False,
    id_type="username",
    debug=False,
    forced=False,
    max_connections=100,
    no_progressbar=False,
    cookies=None,
    retries=0,
    check_domains=False,
) -> QueryResultWrapper

每个选项的含义请参见命令行选项 —— 这些参数与 CLI 选项一一对应,语义完全相同。