Skip to main content

Collect information about dependencies between a github repo and other repositories. Results available in JSON, markdown and badges.

Project description

github-dependents-info

PyPI PyPI - Downloads GitHub stars Build status Python Version Dependencies Status

GitHub contributors Generated by github-dependents-info GitHub Sponsors MegaLinter License PRs Welcome

Collect information about dependencies between a github repo and other repositories.

See tutorial on youtube


🚀 Features

GitHub API does not allow to collect information about package usage (Used by on home, Dependents in insights section)

This package uses GitHub HTML to collect dependents information and can:

  • Automate all the actions below using a simple GitHub Action !
  • Output as text
  • Output as json (including shields.io markdown badges)
  • Generate summary markdown file
  • Update existing markdown by inserting Used by badge within tags
    • <!-- gh-dependents-info-used-by-start --> [![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=10&color=informational&logo=slickpic)](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->
  • Handle multiple repositories packages
  • Filter results using minimum stars

Badges example

JSON output
{
    "all_public_dependent_repos": [
        {
            "name": "CIT-SeniorDesign/CIT-SeniorDesign.github.io",
            "stars": 0
        },
        {
            "name": "Moaz-Adel/Jobsity-Challenge",
            "stars": 0
        },
        {
            "name": "Moaz-Adel/automation-exercise-cypress",
            "stars": 0
        },
        {
            "name": "RecuencoJones/vscode-groovy-lint-issue",
            "stars": 0
        },
        {
            "name": "aboe026/data-structures",
            "stars": 0
        },
        {
            "name": "aboe026/shields.io-badge-results",
            "stars": 0
        },
        {
            "name": "aboe026/software-update-checker",
            "stars": 2
        },
        {
            "name": "katalon-labs/katalon-recorder-extension",
            "stars": 0
        },
        {
            "name": "mashafrancis/sa-jenkins",
            "stars": 0
        },
        {
            "name": "nvuillam/vscode-groovy-lint",
            "stars": 52
        },
        {
            "name": "run2cmd/dotfiles",
            "stars": 2
        }
    ],
    "packages": [
        {
            "id": null,
            "name": "nvuillam/npm-groovy-lint",
            "url": "https://github.com/nvuillam/npm-groovy-lint/network/dependents",
            "public_dependent_stars": 56,
            "public_dependents": [
                {
                    "name": "CIT-SeniorDesign/CIT-SeniorDesign.github.io",
                    "stars": 0
                },
                {
                    "name": "Moaz-Adel/Jobsity-Challenge",
                    "stars": 0
                },
                {
                    "name": "Moaz-Adel/automation-exercise-cypress",
                    "stars": 0
                },
                {
                    "name": "RecuencoJones/vscode-groovy-lint-issue",
                    "stars": 0
                },
                {
                    "name": "aboe026/data-structures",
                    "stars": 0
                },
                {
                    "name": "aboe026/shields.io-badge-results",
                    "stars": 0
                },
                {
                    "name": "aboe026/software-update-checker",
                    "stars": 2
                },
                {
                    "name": "katalon-labs/katalon-recorder-extension",
                    "stars": 0
                },
                {
                    "name": "mashafrancis/sa-jenkins",
                    "stars": 0
                },
                {
                    "name": "nvuillam/vscode-groovy-lint",
                    "stars": 52
                },
                {
                    "name": "run2cmd/dotfiles",
                    "stars": 2
                }
            ],
            "public_dependents_number": 11,
            "private_dependents_number": 4,
            "total_dependents_number": 15,
            "badges": {
                "total": "[![](https://img.shields.io/static/v1?label=Used%20by&message=15&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
                "public": "[![](https://img.shields.io/static/v1?label=Used%20by%20(public)&message=11&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
                "private": "[![](https://img.shields.io/static/v1?label=Used%20by%20(private)&message=4&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
                "stars": "[![](https://img.shields.io/static/v1?label=Used%20by%20(stars)&message=56&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)"
            }
        }
    ],
    "total_dependents_number": 15,
    "public_dependents_number": 11,
    "private_dependents_number": 4,
    "public_dependents_stars": 56,
    "badges": {
        "total": "[![](https://img.shields.io/static/v1?label=Used%20by&message=15&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
        "public": "[![](https://img.shields.io/static/v1?label=Used%20by%20(public)&message=11&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
        "private": "[![](https://img.shields.io/static/v1?label=Used%20by%20(private)&message=4&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)",
        "stars": "[![](https://img.shields.io/static/v1?label=Used%20by%20(stars)&message=56&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)"
    }
}
Markdown output for single package
# Dependents stats for nvuillam/npm-groovy-lint

## Package nvuillam/npm-groovy-lint

[![](https://img.shields.io/static/v1?label=Used%20by&message=15&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
[![](https://img.shields.io/static/v1?label=Used%20by%20(public)&message=11&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
[![](https://img.shields.io/static/v1?label=Used%20by%20(private)&message=4&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)
[![](https://img.shields.io/static/v1?label=Used%20by%20(stars)&message=56&color=informational&logo=slickpic)](https://github.com/nvuillam/npm-groovy-lint/network/dependents)

| Repository                                                                                                    | Stars |
|:--------------------------------------------------------------------------------------------------------------|------:|
| [CIT-SeniorDesign/CIT-SeniorDesign.github.io](https://github.com/CIT-SeniorDesign/CIT-SeniorDesign.github.io) |     0 |
| [Moaz-Adel/Jobsity-Challenge](https://github.com/Moaz-Adel/Jobsity-Challenge)                                 |     0 |
| [Moaz-Adel/automation-exercise-cypress](https://github.com/Moaz-Adel/automation-exercise-cypress)             |     0 |
| [RecuencoJones/vscode-groovy-lint-issue](https://github.com/RecuencoJones/vscode-groovy-lint-issue)           |     0 |
| [aboe026/data-structures](https://github.com/aboe026/data-structures)                                         |     0 |
| [aboe026/shields.io-badge-results](https://github.com/aboe026/shields.io-badge-results)                       |     0 |
| [aboe026/software-update-checker](https://github.com/aboe026/software-update-checker)                         |     2 |
| [katalon-labs/katalon-recorder-extension](https://github.com/katalon-labs/katalon-recorder-extension)         |     0 |
| [mashafrancis/sa-jenkins](https://github.com/mashafrancis/sa-jenkins)                                         |     0 |
| [nvuillam/vscode-groovy-lint](https://github.com/nvuillam/vscode-groovy-lint)                                 |    52 |
| [run2cmd/dotfiles](https://github.com/run2cmd/dotfiles)                                                       |     2 |

_Generated by [github-dependents-info](https://github.com/nvuillam/github-dependents-info)_

Note: If your repository packages have millions of dependents, running github-dependent-infos could take hours, as it works by browsing and scraping HTML pages returned by GitHub. For example, angular/angular dependents did run during several hours !


⚙️ Installation

pip install -U github-dependents-info

or install with Poetry

poetry add github-dependents-info

🛠️ Usage

    github-dependents-info [OPTIONS]
Parameter Type Description
--repo String Repository. Example: oxsecurity/megalinter
-b
--badgemarkdownfile
String (optional) Path to markdown file where to insert/update Used by badge
(must contain tags `
Generated by github-dependents-info`)
-s
--sort
String (optional) Sort order: name (default) or stars
-x
--minstars
String (optional) If set, filters repositories to keep only those with more than X stars
-m
--markdownfile
String (optional) Output markdown file file
-d
--docurl
String (optional) Hyperlink to use when clicking on badge markdown file badge. (Default: link to markdown file)
-p
--mergepackages
String (optional) In case of multiple packages, merge their stats in a single one in markdown and json output
-j
--json
String (optional) Output in json format
-v
--version
Boolean (optional) Displays version of github-dependents-info
--verbose Boolean (optional) Verbose output

🧪 Examples

  • Text output

    github-dependents-info --repo nvuillam/npm-groovy-lint
    
  • JSON output

    github-dependents-info --repo nvuillam/npm-groovy-lint --json
    
  • Insert/Update Used by markdown badge within an existing markdown file containing tags <!-- gh-dependents-info-used-by-start --> [![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=10&color=informational&logo=slickpic)](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->

    github-dependents-info --repo nvuillam/npm-groovy-lint --badgemarkdownfile ./README.md
    
  • Build markdown file with dependent repos (single package), sorted by name

    github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --verbose
    
  • Build markdown file with dependent repos (single package), with minimum 10 stars

    github-dependents-info --repo nvuillam/npm-groovy-lint --markdownfile ./docs/package-usage.md --minstars 10 --verbose
    
  • Build markdown file with dependent repos (multiple package), sorted by stars

    github-dependents-info --repo oxsecurity/megalinter --markdownfile ./docs/package-usage.md --sort stars --verbose
    
  • Build markdown file with dependent repos (multiple package), with merged list of packages in output markdown

    github-dependents-info --repo oxsecurity/megalinter --markdownfile ./docs/package-usage.md --sort stars --mergepackages --verbose
    

Use as GitHub Action

Allow GitHub Actions to create Pull Requests in Settings > Actions > General

image

Create a file .github/workflows/github-dependents-info.yml in your repository with the following YAML content.

If will generate a new Pull Request (or replace the pending one) every time the usage stats will have changed :)

Don't forget to add tags <!-- gh-dependents-info-used-by-start --> [![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=10&color=informational&logo=slickpic)](https://github.com/nvuillam/github-dependents-info/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end --> in your README.md, at the end of another badge line if you want github-dependents-info to replace its content automatically.

# GitHub Dependents Info workflow
# More info at https://github.com/nvuillam/github-dependents-info/
name: GitHub Dependents Info

# Let by default
on:
  # On manual launch
  workflow_dispatch:
  # On every push on selected branches (usually just main)
  push:
    branches: [main,master,setup-gdi]
  # Scheduled interval: Use CRON format https://crontab.guru/
  schedule:
    - cron: "0 0 * * 0" # Every sunday at midnight

permissions: read-all

concurrency:
  group: ${{ github.ref }}-${{ github.workflow }}
  cancel-in-progress: true

jobs:
  build:
    name: GitHub Dependents Info
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      # Git Checkout
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN }}
          fetch-depth: 0

      # Collect data & generate markdown
      - name: GitHub Dependents Info
        uses: nvuillam/github-dependents-info@v1.5.1 # If you trust me enough you can replace version by "main" :)
        # See documentation for variables details: https://github.com/nvuillam/github-dependents-info?tab=readme-ov-file#%EF%B8%8F-usage
        with:
          repo: ${{ github.repository }}
          outputrepo: ${{ github.repository }}
          # markdownfile: docs/github-dependents-info.md
          # badgemarkdownfile: README.md
          # sort: stars
          # minstars: "0"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Workaround for git issues
      - name: Prepare commit
        run: sudo chown -R $USER:$USER .

      # Create pull request
      - name: Create Pull Request
        id: cpr
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.PAT || secrets.GITHUB_TOKEN  }}
          branch: github-dependents-info-auto-update
          commit-message: "[GitHub Dependents Info] Updated markdown file(s)"
          delete-branch: true
          title: "[GitHub Dependents Info] Updated markdown file"
          body: "_Generated with [github-dependents-info](https://github.com/nvuillam/github-dependents-info), by [Nicolas Vuillamy](https://github.com/nvuillam)_"
          labels: documentation
      - name: Create PR output
        run: |
          echo "Pull Request Number - ${{ steps.cpr.outputs.pull-request-number }}"
          echo "Pull Request URL - ${{ steps.cpr.outputs.pull-request-url }}"

🛡 License

License

This project is licensed under the terms of the MIT license. See LICENSE for more details.


Credits 🚀 Your next Python package needs a bleeding-edge project structure.

This package has been inspired by stackexchange post How to use GitHub API to get a repository's dependents information in GitHub?

This project was generated with python-package-template

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

github_dependents_info-1.6.3.tar.gz (18.8 kB view hashes)

Uploaded Source

Built Distribution

github_dependents_info-1.6.3-py3-none-any.whl (14.1 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page