Package: opendigger_pycli
OpenDigger CLI 文档OpenDigger CLI 文档🗺️Big Picture🪛安装基本环境从源码安装从PyPI安装🕹️基本用法开启自动补全获取Github Personal Access Token获取OpenAI keyconfig 命令repo 命令user 命令query 命令按类型筛选指标按时间筛选指标数据对某一指标进行时间筛选正向筛选指标反向筛选指标display 命令表格格式图表格式json格式保存输出结果export 命令数据报告原始Json数据组合使用👀异常处理缺失数据自动反馈仓库不存在用户不存在🔌插件开发query的返回数据插件示例示例插件使用📄筛选条件表达式详解End🗺️Big Picture🪛安装基本环境Python >= 3.8从源码安装python3-mpipinstallflit

gitclonehttps://github.com/CoderChen01/opendigger-pycli.git

flitinstall# 详见：https://github.com/pypa/flit从PyPI安装pip3installopendigger_pycli🕹️基本用法开启自动补全zsh:eval"$(_OPENDIGGER_COMPLETE=zsh_sourceopendigger)"bash:eval"$(_FOO_BAR_COMPLETE=bash_sourceopendigger)"获取Github Personal Access TokenGithub Personal Access Token用于访问Github API，获取Github API的权限。通过Github API我们可以获取到Github上的仓库和用户的基本信息和自动反馈缺失数据。点击这里获取。具体步骤：1.点击Fine-grained tokens> 点击Generate new token2.设置Token name和Token Expiration3.选择仓库权限4.设置issue的读写权限注意metadata权限也必须同时设置只读权限获取OpenAI keyOpenAI key用于访问OpenAI API，获取OpenAI API的权限。通过OpenAI API我们可以对指标数据进行分析和生成洞察报告。点击这里获取。config 命令config命令用于配置工具所使用到的第三方API密钥和基本的用户信息。目前工具使用到了Github API和OpenAI API。两者本别用来查询仓库和用户的基本信息，和用来对指标数据进行分析和生成洞察报告。该命令只有一个参数：-s / --set：用于设置配置项（该参数可以多次使用）具体使用如下：# 配置Github API密钥opendiggerconfig--setapp_keys.github_pat<your_pat># 配置OpenAI API密钥opendiggerconfig-sapp_keys.openai_key<your_key># 同时配置用户姓名和邮箱opendiggerconfig-suser_info.name<your_name>-suser_info.email<your_email>演示录屏repo 命令repo命令用于查看仓库的指标数据。该命令有一个参数：-r / --repo：用于指定仓库名称。（该参数可以多次使用）如果多次指定将会查询多个仓库的指标数据。该命令单独使用时，将会查询仓库的基本信息。基本信息包括仓库主页链接、仓库Owner主页链接、仓库是否是Fork的和仓库的创建时间与最近更新时间。通过这些信息可以帮助用户快速了解仓库的基本情况。具体使用如下：# 查询单个仓库的基本信息opendiggerrepo-rX-lab2017/open-digger# 查询多个仓库的基本信息opendiggerrepo-rX-lab2017/open-digger-rmicrosoft/vscode结果截图演示录屏user 命令user命令用于查看用户的指标数据。该命令有一个参数：-u / --username：用于指定用户名。（该参数可以多次使用）如果多次指定将会查询多个用户的指标数据。该命令单独使用时，将会查询用户的基本信息。基本信息包括用户名、用户昵称、用户邮箱、用户主页链接、用户创建时间和用户最近更新时间。通过这些信息可以帮助用户快速了解用户的基本情况。具体使用如下：# 查询单个用户的基本信息opendiggeruser-uCoderChen01# 查询多个用户的基本信息opendiggeruser-uCoderChen01-uX-lab2017结果截图query 命令query命令是repo和user的子命令(⚠️query命令只能够在repo和user命令之后使用。)，用于对仓库或用户的指标数据进行筛选。当前支持的筛选条件有：按类型筛选指标按时间筛选指标数据对某一指标进行筛选正向筛选指标反向筛选指标query命令的所有参数如下：-i, --index                     Select indicators whose type is INDEX.
-m, --metric                    Select indicators whose type is METRIC.
-n, --network                   Select indicators whose type is NETWORK.
-x, --x-lab                     Select indicators whose introducer is X-lab.
-c, --chaoss                    Select indicators whose introducer is
                                CHAOSS.
-s, --select INDICATOR_QUERY    The indicator to select.
-o, --only-select / -N, --no-only-select
                                Only query selected indicators.
-I, --ignore IGNORED_INDICATOR_NAMES
                                The indicators to ignore.
-f, --fileter INDICATOR_QUERY   The query applying to all indicatorsquery 命令有两个子命令：display: 用于将筛选出来的数据以表格、图表或json格式在终端输出。export: 用于将筛选出来的数据经过GPT分析后导出数据报告或直接导出原始json数据。⚠️ 特别说明query命令可以理解为是一个数据下载器，它可以根据用户所传参数从opendigger的数据仓库中下载指定的数据。
但是query命令并不会对数据进行处理，它只是将数据下载到本地。
如果用户需要对数据进行处理，可以使用query命令的display子命令和export子命令。如果用户没有在query后使用display或export子命令，那么query命令将不会对数据进行任何处理，而是只输出筛选指标的基本信息。
用户也可以通过我们提供的接口获取query命令下载并筛选后的数据，开发自定义的命令。具体见🔌插件开发。按类型筛选指标query命令在不带任何参数的情况下，可以输出当前支持的所有指标的基本信息。基本信息包括指标名称、指标类型、指标引入者和指标数据示例链接。具体演示如下：# 查看仓库指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery演示录屏如果我们需要查看某一类型的指标的基本信息，可以使用-i、-m和-n参数。如果我们需要查看某一引入者的指标的基本信息，可以使用-x和-c参数。同时这些指标可以组合使用，例如：# 查看指标类型为index的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-i# 或者opendiggerrepo-rX-lab2017/open-diggerquery--index# 查看指标类型为metric的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-m# 查看指标类型为network的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-n# 查看指标引入者为X-lab的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-x# 查看指标引入者为CHAOSS的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-c# 查看指标类型为metric且引入者为X-lab的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-m-x# 或者opendiggerrepo-rX-lab2017/open-diggerquery-m--x-lab# 或者opendiggerrepo-rX-lab2017/open-diggerquery-xm# 或者opendiggerrepo-rX-lab2017/open-diggerquery--metric--x-lab# 查看指标类型为metric且引入者为CHAOSS的指标的基本信息opendiggerrepo-rX-lab2017/open-diggerquery-m-c如上所示，我们可以通过组合使用-i、-m、-n、-x和-c参数来查看我们想要的指标的基本信息。这些参数都不接受值，只需要指定即可。按时间筛选指标数据通过上述参数我们可以筛选出我们关注的指标类型，然后我们可以通过-f参数对筛选出的指标类型的数据进行时间上的筛选。-f参数接受一个指标筛选条件表达式，详细筛选条件表达式见下方：📄筛选条件表达式详解。下面是一些例子（这里为了便于演示将使用display子命令将筛选出来的数据在终端以表格形式输出）：# 查看仓库X-lab2017/open-digger在2023年的index类型的指标数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-f2023display-ftable# 查看仓库X-lab2017/open-digger在2021~2023年的index类型的指标数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-f2021~2023display-ftable# 查看仓库X-lab2017/open-digger在2021年3月~2023年3月的index类型的指标数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-f2021-03~2023-03display-ftable# 查看仓库X-lab2017/open-digger过去年份3月到8月的index类型的指标数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-f3~8display-ftable# 查看仓库X-lab2017/open-digger过去年份3月的index类型的指标数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-f3display-ftable演示录屏query对某一指标进行时间筛选基于-f参数我们可以对筛选出的指标进行时间上的过滤，但是如果我们需要针对某一个指标进行筛选该怎么办呢？我们可以通过-s参数来对某一个指标指定筛选条件。-s参数接受一个指标查询表达式，该表达式由指标名称和筛选条件表达式组成。指标名称和筛选条件表达式之间用:分隔。下面是一些例子（这里为了便于演示将使用display子命令将筛选出来的数据在终端以表格形式输出）：# 查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看2023年的数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:2023display-ftable# 查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看2021~2022年的数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:2021~2022display-ftable# 查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看2021年3月~2022年3月的数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:2021-03~2022-03display-ftable# 查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看过去年份3月到8月的数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:3~8display-ftable# 查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看过去年份8月的数据，并以表格形式在终端打印opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:8display-ftable演示录屏：查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看2023年的数据，并以表格形式在终端打印查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看2021~2022年的数据，并以表格形式在终端打印查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看2021年3月~2022年3月的数据，并以表格形式在终端打印查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看过去年份3月到8月的数据，并以表格形式在终端打印查看仓库X-lab2017/open-digger的index类型的指标数据，并对openrank指标进行筛选，只查看过去年份8月的数据，并以表格形式在终端打印正向筛选指标我们已经可以对指标通过类型、时间进行筛选并将其在终端以表格形式输出了，并且我们还能针对某一个指标进行时间上的筛选。但是，query命令默认查询所有的指标，即使我们使用了-i,-m,-n,-x和-c筛选出特定的指标，通过-f和-s筛选出特定的指标数据，但是我们仍然会得到大量的指标数据，这些指标数据中可能有我们不关心的指标数据。我们可以通过-o / --only-select参数与-s参数配合使用，只查询我们关心的指标数据。比如我们只查询仓库X-lab2017/open-digger的index类型的指标数据，并且只查询openrank指标的数据，我们可以这样做：# 只查看过往年份3~8月的openrank指标数据opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:3~8-odisplay-ftable# 或者opendiggerrepo-rX-lab2017/open-diggerquery-i-sopenrank:3~8--only-selectdisplay-ftable# 或者opendiggerrepo-rX-lab2017/open-diggerquery-i-osopenrank:3~8display-ftable演示录屏我们还可以查询多个指标的数据，比如我们还想查看openrank和issue_age指标的数据，我们可以这样做：# 只查看过往年份3~8月的openrank和过往5~8月的issue_age指标数据opendiggerrepo-rX-lab2017/open-diggerquery-sopenrank:3~8-sissue_age:5~8-odisplay-ftable反向筛选指标我们还可以通过-I / --ignore参数来反向筛选指标，即我们可以通过-I / --ignore参数来忽略某些指标。比如我们只查询仓库X-lab2017/open-digger的index类型的指标数据，并且忽略openrank指标的数据，我们可以这样做：opendiggerrepo-rX-lab2017/open-diggerquery-i-Iopenrankdisplay-ftabledisplay 命令display命令是query命令的子命令，用于将筛选出来的数据以表格、图表或json格式在终端输出。该命令在上文演示中已经使用过，不过该命令还支持除了table格式的其他格式。具体支持参数如下：-f, --format [table|graph|json]
                                Display format  [required]
-s, --save DIRECTORY            Save output to file, you can use this option
                                get a simple report
-p, --paging / --no-paging      Page output like more/less command, you
                                CANNOT use this option and save to file at
                                the same time
-c, --pager-color / --no-pager-color
                                Enable color in pager, Only works when
                                paging is enabled可以通过-f参数指定输出格式，并且通过-s / --save参数可以将终端输出的内容保存到文件(一个简易版的数据报告)中，通过-p / --paging参数可以将终端输出的内容分页显示，通过-c / --pager-color参数可以在分页显示时启用颜色。表格格式表格格式在上文中已经提及，这里不再赘述。图表格式图表格式可以将筛选出来的数据以图表的形式在终端输出。目前支持的图表类型有：横向柱状图热力图具体使用如下：查看仓库X-lab2017/open-digger的index类型的openrank指标数据，只查看2023年的数据，并以图表形式在终端打印:opendiggerrepo-rX-lab2017/open-diggerquery-i-osopenrank:2023display-fgraph结果截图：从图中可以看出openrank 2023年每个月的数据变化。查看仓库X-lab2017/open-digger的metric类型的active_date_and_time指标数据，只查看2023年的数据，并以图表形式在终端打印:opendiggerrepo-rX-lab2017/open-diggerquery-m-osactive_date_and_time:2023display-fgraph结果截图：从图中可以看出2023年每个月的活跃时间段。热力图的横纵坐标标号的含义在图下方也会有相应的说明。查看仓库X-lab2017/open-digger的metric类型的summed_code_change_line指标数据，并以图表形式在终端打印:opendiggerrepo-rX-lab2017/open-diggerquery-m-ossummed_code_change_linedisplay-fgraph结果截图：从图中可以看出summed_code_change_line指标的数据变化。对于负值的数据，我们会将其转换为正值，然后在图表中以红色显示。json格式我们输出的json格式与原数据不一样，我们对原始数据进行了处理，将年月解析了出来并进行了排序，对于包含-raw的字段我们也进行了处理。这样用户直接复制打印出来的json数据为自己所用。具体使用如下：查看仓库X-lab2017/open-digger的metric类型的issue_age指标数据,并以json格式在终端打印:opendiggerrepo-rX-lab2017/open-diggerquery-mosissue_agedisplay-fjson演示录屏保存输出结果我们可以将终端输出的内容保存到文件中，这样我们可以得到一个简易版的数据报告。比如我们以图表形式输出仓库X-lab2017/open-digger的所有指标数据(除了project_openrank_network指标)，并将输出结果保存到文件中：opendiggerrepo-rX-lab2017/open-diggerquerydisplay-fgraph-s.演示录屏https://atomgit.com/opendigger-pycli/opendigger-pycli/raw/cjj_dev/docs/assets/demos/repo-query-dispaly-save.mp4export 命令export命令是query命令的子命令，用于将筛选出来的数据经过GPT分析后导出数据报告或直接导出原始json数据。具体支持参数如下：-f, --format [report|json]  Format to export  [required]
-s, --save-dir DIRECTORY    Directory to save indicators  [required]
--split / --no-split        Save indicators in separate files, ONLY For JSON format可以通过-f参数指定输出格式，并且通过-s / --save-dir参数可以将数据保存到指定目录中，通过--split / --no-split参数可以将数据分别保存到不同的文件中(只对json格式有用)。数据报告数据报告是我们对筛选出来的数据进行GPT分析后生成的，该报告包含了筛选出来的数据的分析结果和数据的可视化结果。具体使用如下：查看仓库X-lab2017/open-digger的所有指标数据（除project_openrank_detail指标），并导出数据报告：opendiggerrepo-rX-lab2017/open-diggerqueryexport-freport-s.演示录屏https://atomgit.com/opendigger-pycli/opendigger-pycli/raw/cjj_dev/docs/assets/demos/repo-query-export-report.mp4查看仓库X-lab2017/open-digger的所有指标数据(其中查看2023年8月的project_openrank_detail指标，并导出数据报告：open-diggerrepo-rX-lab2017/open-diggerquery-sproject_openrank_detail:2023-08export-freport-s.原始Json数据我们可以将筛选出来的数据导出为原始的json数据，这样用户可以自行处理数据。具体使用如下：# 查看仓库X-lab2017/open-digger的所有指标数据(其中查看2023年8月的project_openrank_detail的指标)，并导出原始json数据open-diggerrepo-rX-lab2017/open-diggerquery-sproject_openrank_detail:2023-08export-fjson-s.组合使用query的所有子命令都可以组合使用，比如我们可以先使用query命令筛选出我们关心的指标数据，然后使用display命令将筛选出来的数据以表格、图表或json格式在终端输出，最后使用export命令将筛选出来的数据经过GPT分析后导出数据报告或直接导出原始json数据。如果用户开发了自定义的插件，也可以使用自定义的插件对筛选出来的数据进行处理。比如我们想要查看仓库X-lab2017/open-digger的index类型的openrank指标数据，并且只查看2023年的数据，并以表格形式在终端打印，最后将筛选出来的数据已json格式导出，我们可以这样做：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank:2023display-ftableexport-fjson-s.结果截图：👀异常处理缺失数据自动反馈open-digger官方仓库对于一些仓库的指标数据是缺失的。用户查询某个仓库的指标数据时，如果该仓库的指标数据缺失，我们会给出相应的提示，并且会使用用户配置的github personal access token调用Github API在opendigger-pycli的github上自动提交一个数据缺失的issue。issue信息如图所示：如果多个用户重复查询同一个仓库的指标数据，我们不会冗余的提交，而是在原有的issue上添加一个"👀"符号。这样open-digger开发者可以通过定期查看issue来了解用户关注哪些仓库/用户的哪些指标数据。如果关注人数较多，可以决策是否添加该仓库/用户的指标数据。仓库不存在如果用户输入的仓库/用户不存在，我们会给出相应的提示。比如我们输入了一个不存在的仓库X-lab2017/open-digger-404，我们会给出相应的提示：opendiggerrepo-rX-lab2017/open-digger-404用户不存在如果用户输入的仓库/用户不存在，我们会给出相应的提示。比如我们输入了一个不存在的用户CoderChen01-404，我们会给出相应的提示：opendiggeruser-uCoderChen01-404🔌插件开发插件是opendigger-pycli的一个重要特性，它可以帮助用户快速开发自定义的命令，对筛选出来的数据进行处理。最为重要的就是我们的query命令，它利用了click库提供的Mult Command Pipelines特性，可以将筛选出来的数据传递给它的子命令，子命令可以是display命令，也可以是用户自定义的命令。query的返回数据@dataclassclassBaseQueryResult:type:t.ClassVar[t.Literal["user","repo"]]dataloaders:t.List["DataloaderProto"]indicator_queries:t.List[t.Tuple[str,t.Optional["IndicatorQuery"]]]uniform_query:t.Optional["IndicatorQuery"]data:t.Dict[str,"DataloaderResult"]=field(default_factory=dict,init=False)queried_data:t.Dict[str,"DataloaderResult"]=field(default_factory=dict,init=False)failed_query:t.Dict[str,t.Union[t.Optional["IndicatorQuery"],t.Dict[str,t.Optional["IndicatorQuery"]],],]=field(default_factory=dict,init=False)@dataclassclassRepoQueryResult(BaseQueryResult):type:t.ClassVar[t.Literal["repo"]]="repo"repo:t.Tuple[str,str]org_name:str=field(init=False)repo_name:str=field(init=False)def__post_init__(self)->None:self.org_name,self.repo_name=self.reporun_dataloader(self)run_query(self)@dataclassclassUserQueryResult(BaseQueryResult):type:t.ClassVar[t.Literal["user"]]="user"username:strdef__post_init__(self)->None:run_dataloader(self)run_query(self)其中当我们使用repo的query命令时，query命令的返回数据类型为RepoQueryResult，当我们使用user的query命令时，query命令的返回数据类型为UserQueryResult。RepoQueryResult和UserQueryResult都继承自BaseQueryResult，BaseQueryResult中包含了query命令的一些基本信息。如下是关键属性的介绍（具体用法请见源码：opendigger_pycli/results/display.py）：dataloaders：query命令筛选出的指标的数据加载器。indicator_queries：-s参数指定的指标查询表达式。uniform_query：-f参数指定的指标筛选条件表达式。data：query命令下载的原始数据。queried_data：query命令筛选后的数据。failed_query：query命令筛选失败的指标查询表达式。插件示例该示例插件的功能是将筛选出来的数据基本信息打印到终端。示例插件命令代码：# plugin_example/print_result/print_result.pyfrom__future__importannotationsimporttypingastimportclickfromopendigger_pycli.consoleimportCONSOLEfromopendigger_pycli.utils.decoratorsimportprocessorift.TYPE_CHECKING:fromopendigger_pycli.results.queryimportQueryResults@click.command("print-result",help="[Plugin Demo] Print query result to terminal")@processordefprint_result(results:QueryResults):CONSOLE.print(results)yield fromresults# 这个yield from是必须的，它会将结果传递给其他子命令。模块的安装配置如下：# plugin_example/print_result/setup.pyfromsetuptoolsimportsetupsetup(name="opendigger_pycli_print_result",version="0.1",py_modules=["print_result"],install_requires=["click",],entry_points="""[opendigger_pycli.plugins]print-result=print_result:print_result""",)注意entry_points的写法，opendigger_pycli.plugins是固定的，print-result是插件的名称，print_result:print_result定位到插件的入口函数。具体配置见：click-plugins示例插件使用进入示例插件的目录，执行如下命令安装插件：cdplugin_example/print_result

python3setup.pyinstall我们运行如下命令：opendiggerrepo-rX-lab2017/open-diggerquery--help会发现query命令的--help中多了一个print-result子命令。我们运行如下命令：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank:2023print-result结果如下：📄筛选条件表达式详解筛洗条件表达式主要分为如下几种：年份查询月份查询年月查询年月范围查询年份范围查询年份月份范围查询我们使用~来表示范围，使用-来表示年月。通过如下几个示例来说明：查询2023年的数据：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank-f2023display-ftable查询2021年到2023年的数据：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank-f2021~2023display-ftable查询过往年份3月的数据：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank-f3display-ftable查询过往年份3月到8月的数据：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank-f3~8display-ftable查询2023年3月的数据：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank-f2023-03display-ftable查询2022年3月到2023年3月的数据：opendiggerrepo-rX-lab2017/open-diggerquery-iosopenrank-f2022-03~2023-03display-ftableEnd更多功能等待您的探索...