ghrepo-stats


Nameghrepo-stats JSON
Version 0.5.4 PyPI version JSON
download
home_pagehttp://github.com/mrbean-bremen/ghrepo-stats
SummaryCommand line tools for GitHub repo statistics
upload_time2023-03-14 17:44:29
maintainer
docs_urlNone
authormrbean-bremen
requires_python
licenseMIT
keywords github python
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # ghrepo-stats [![PyPI version](https://badge.fury.io/py/ghrepo-stats.svg)](https://badge.fury.io/py/ghrepo-stats)

Have you ever wondered how the number of stargazers or the number of open
issues has changed over time for your or any public GitHub repository? I did, 
so I wrote this small command line tool that will show this data.

*ghrepo-stats* uses [pygithub](https://github.com/PyGithub/PyGithub) to 
collect some statistics from a specific repository using a command line tool
and show it using [matplotlib](https://github.com/matplotlib/matplotlib) or
write it to a csv file. 

Features
--------
The following sub-commands are supported:
- stars: shows the number of stargazers over time (caveat: stargazers that
  have removed their star are not shown, as the info is not available)
- issues: shows the number of currently open issues over time
- prs: shows the number of currently open pull requests over time
- commits: shows the number of commits over the last year
- codesize: shows the change of the code size over time measured by the 
  number of added and deleted lines
- issue-life: shows the average life time in days of issues over time
  (sampled once a week) 
- pr-life: shows the average life time in days of issues over time 
  (sampled once a week) 
- dependents: show which repositories and packages depend on your repository
  as a list sorted by the number of stargazers

Runtime
-------
Using sub-commands related to issues and PRs on repositories with many
(open or close) issues may take a lot of time due to API access
limitations the first time they are used on a given repository. 
Each subsequent call shall be much faster, as the results are cached in the file system
(as json files in the subdirectory `.ghrepo-stats` in the home directory of the current 
user).
Commands not related to issues/prs usually shall not take a long time, except for 
dependents - these are currently not cached and take a sufficient time 
(up to several minutes) if there are many of them (e.g. several thousands).

Installation
------------
If you want to try it, you can install it from PyPi:
```
pip install ghrepo-stats
```
Or you can install the current main branch from GitHub:
```
pip install git+https://github.com/mrbean-bremen/ghrepo-stats
```

Usage
-----
To use this, you need a GitHub account and a
[personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
able to read public repositories for your GitHub account. The user name and
token is expected to be found in the file `ghrepo-stats.ini`, either in the
repository root, or in your home path.

The contents should be in the form:
```
[auth]
username = my-github-username
token = 123456789abcdef0123456789abcdef012345678
```

To get usage information you can now type:
```
$ show-ghstats -h
usage: show-ghstats [-h] [--verbose] [--csv CSV] sub_command repo_name

Shows GitHub repo statistics

positional arguments:
  sub_command    The kind of statistics to show. Possible values: 'issues',
                 'prs', 'stars', 'commits', 'codesize', 'issue-life', 'pr-
                 life', 'dependents'.
  repo_name      Full repository name in the form <repo_owner>/<repo_name>.

optional arguments:
  -h, --help     show this help message and exit
  --verbose, -v  Outputs diagnostic information
  --csv CSV      Write the output into a csv file with the given file path
  --packages     Only for dependents: get dependent packages instead of repositories
  --min-stars MIN_STARS
                 Only for dependents: limits the output to dependents with at least 
                 the given number of stargazers.
```

So, for example, to get a star plot of a specific repository, you can write:
```
$ show-ghstats stars "my-github-username/my-repo"
```
If you want to have the numbers saved in a csv file instead to play around with
the numbers you can write: 
```
$ show-ghstats stars "my-github-username/my-repo" --csv=my_repo-issues
```
This will write a file `my_repo-issues.csv` with the numbers (date+time /
number of issues) in the current path.

Dependents
----------
Getting dependent repositories is a bit different from the other commands, as 
dependent repositories are not available via the GitHub API, and there is no 
statistics to show. Instead, the data is collected using web scraping, and output 
into a CSV file if given or as lines on the standard output.
There are also 2 specific parameters for this option (`--packages` and `--min-stars`)
as shown above. Sorting by the number of stargazers is done to show the most known 
repositories first.
No caching is done here (yet), so depending on the number of dependent repositories
the call may take a long time.

Examples
--------
Get some measure of popularity change by showing the number of stargazers over
time (note: stars that have been retracted are not counted):
```commandline
$ show-ghstats stars "pytest-dev/pyfakefs"
```
![stars](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/stars.png)

Check how issues are handled over time. There are two possibilities:
 - Show the number of open issues at any point in time:
```commandline
$ show-ghstats issues "svg-net/svg"
```
![issues](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/issues.png)

 - Show the average lifetime of an issue as it changes over time. An 
   increasing curve means ever more unresolved issues (also depends on the
   policies of the specific project - some projects leave issues open
   indefinitely, while others close outdated issues):
```commandline
$ show-ghstats issue-life "pytest-dev/pyfakefs"
```
![issue-lifetime](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/issuelife.png)

Get some measure of activity by checking how the code size changed over time 
(measured in code additions/deletions):
```commandline
$ show-ghstats codesize "pytest-dev/pytest"
```
![codesize](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/codesize.png)

Check which well-known packages depend on your repository: 
```commandline
$ show-ghstats dependents pydicom/pydicom --packages --min-stars=1000
```
```
fastai/fastai   23163
activeloopai/deeplake   5120
pypa/sampleproject      4500
openvinotoolkit/openvino        3890
Project-MONAI/MONAI     3675
Project-MONAI/MONAI     3675
microsoft/presidio      1906
Image-Py/imagepy        1209
```

            

Raw data

            {
    "_id": null,
    "home_page": "http://github.com/mrbean-bremen/ghrepo-stats",
    "name": "ghrepo-stats",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "github,python",
    "author": "mrbean-bremen",
    "author_email": "hansemrbean@googlemail.com",
    "download_url": "https://files.pythonhosted.org/packages/b0/3e/f87402d1580567e5fa51161bde2786e4bf076add61d8e462f1e55fe029b8/ghrepo-stats-0.5.4.tar.gz",
    "platform": null,
    "description": "# ghrepo-stats [![PyPI version](https://badge.fury.io/py/ghrepo-stats.svg)](https://badge.fury.io/py/ghrepo-stats)\n\nHave you ever wondered how the number of stargazers or the number of open\nissues has changed over time for your or any public GitHub repository? I did, \nso I wrote this small command line tool that will show this data.\n\n*ghrepo-stats* uses [pygithub](https://github.com/PyGithub/PyGithub) to \ncollect some statistics from a specific repository using a command line tool\nand show it using [matplotlib](https://github.com/matplotlib/matplotlib) or\nwrite it to a csv file. \n\nFeatures\n--------\nThe following sub-commands are supported:\n- stars: shows the number of stargazers over time (caveat: stargazers that\n  have removed their star are not shown, as the info is not available)\n- issues: shows the number of currently open issues over time\n- prs: shows the number of currently open pull requests over time\n- commits: shows the number of commits over the last year\n- codesize: shows the change of the code size over time measured by the \n  number of added and deleted lines\n- issue-life: shows the average life time in days of issues over time\n  (sampled once a week) \n- pr-life: shows the average life time in days of issues over time \n  (sampled once a week) \n- dependents: show which repositories and packages depend on your repository\n  as a list sorted by the number of stargazers\n\nRuntime\n-------\nUsing sub-commands related to issues and PRs on repositories with many\n(open or close) issues may take a lot of time due to API access\nlimitations the first time they are used on a given repository. \nEach subsequent call shall be much faster, as the results are cached in the file system\n(as json files in the subdirectory `.ghrepo-stats` in the home directory of the current \nuser).\nCommands not related to issues/prs usually shall not take a long time, except for \ndependents - these are currently not cached and take a sufficient time \n(up to several minutes) if there are many of them (e.g. several thousands).\n\nInstallation\n------------\nIf you want to try it, you can install it from PyPi:\n```\npip install ghrepo-stats\n```\nOr you can install the current main branch from GitHub:\n```\npip install git+https://github.com/mrbean-bremen/ghrepo-stats\n```\n\nUsage\n-----\nTo use this, you need a GitHub account and a\n[personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)\nable to read public repositories for your GitHub account. The user name and\ntoken is expected to be found in the file `ghrepo-stats.ini`, either in the\nrepository root, or in your home path.\n\nThe contents should be in the form:\n```\n[auth]\nusername = my-github-username\ntoken = 123456789abcdef0123456789abcdef012345678\n```\n\nTo get usage information you can now type:\n```\n$ show-ghstats -h\nusage: show-ghstats [-h] [--verbose] [--csv CSV] sub_command repo_name\n\nShows GitHub repo statistics\n\npositional arguments:\n  sub_command    The kind of statistics to show. Possible values: 'issues',\n                 'prs', 'stars', 'commits', 'codesize', 'issue-life', 'pr-\n                 life', 'dependents'.\n  repo_name      Full repository name in the form <repo_owner>/<repo_name>.\n\noptional arguments:\n  -h, --help     show this help message and exit\n  --verbose, -v  Outputs diagnostic information\n  --csv CSV      Write the output into a csv file with the given file path\n  --packages     Only for dependents: get dependent packages instead of repositories\n  --min-stars MIN_STARS\n                 Only for dependents: limits the output to dependents with at least \n                 the given number of stargazers.\n```\n\nSo, for example, to get a star plot of a specific repository, you can write:\n```\n$ show-ghstats stars \"my-github-username/my-repo\"\n```\nIf you want to have the numbers saved in a csv file instead to play around with\nthe numbers you can write: \n```\n$ show-ghstats stars \"my-github-username/my-repo\" --csv=my_repo-issues\n```\nThis will write a file `my_repo-issues.csv` with the numbers (date+time /\nnumber of issues) in the current path.\n\nDependents\n----------\nGetting dependent repositories is a bit different from the other commands, as \ndependent repositories are not available via the GitHub API, and there is no \nstatistics to show. Instead, the data is collected using web scraping, and output \ninto a CSV file if given or as lines on the standard output.\nThere are also 2 specific parameters for this option (`--packages` and `--min-stars`)\nas shown above. Sorting by the number of stargazers is done to show the most known \nrepositories first.\nNo caching is done here (yet), so depending on the number of dependent repositories\nthe call may take a long time.\n\nExamples\n--------\nGet some measure of popularity change by showing the number of stargazers over\ntime (note: stars that have been retracted are not counted):\n```commandline\n$ show-ghstats stars \"pytest-dev/pyfakefs\"\n```\n![stars](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/stars.png)\n\nCheck how issues are handled over time. There are two possibilities:\n - Show the number of open issues at any point in time:\n```commandline\n$ show-ghstats issues \"svg-net/svg\"\n```\n![issues](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/issues.png)\n\n - Show the average lifetime of an issue as it changes over time. An \n   increasing curve means ever more unresolved issues (also depends on the\n   policies of the specific project - some projects leave issues open\n   indefinitely, while others close outdated issues):\n```commandline\n$ show-ghstats issue-life \"pytest-dev/pyfakefs\"\n```\n![issue-lifetime](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/issuelife.png)\n\nGet some measure of activity by checking how the code size changed over time \n(measured in code additions/deletions):\n```commandline\n$ show-ghstats codesize \"pytest-dev/pytest\"\n```\n![codesize](https://github.com/mrbean-bremen/ghrepo-stats/raw/main/doc/images/codesize.png)\n\nCheck which well-known packages depend on your repository: \n```commandline\n$ show-ghstats dependents pydicom/pydicom --packages --min-stars=1000\n```\n```\nfastai/fastai   23163\nactiveloopai/deeplake   5120\npypa/sampleproject      4500\nopenvinotoolkit/openvino        3890\nProject-MONAI/MONAI     3675\nProject-MONAI/MONAI     3675\nmicrosoft/presidio      1906\nImage-Py/imagepy        1209\n```\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Command line tools for GitHub repo statistics",
    "version": "0.5.4",
    "split_keywords": [
        "github",
        "python"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "cb29733b5eaa76c99660112b5fe51f95ee5427ac5d4c95bd93b1ca54014bc88f",
                "md5": "9b9988be52ad68ba7cf72d94ba83e77a",
                "sha256": "1b48549342ea84d77fb9720971088643cfccf0232d69d99e136dae22999a26e3"
            },
            "downloads": -1,
            "filename": "ghrepo_stats-0.5.4-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9b9988be52ad68ba7cf72d94ba83e77a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 13934,
            "upload_time": "2023-03-14T17:44:28",
            "upload_time_iso_8601": "2023-03-14T17:44:28.297221Z",
            "url": "https://files.pythonhosted.org/packages/cb/29/733b5eaa76c99660112b5fe51f95ee5427ac5d4c95bd93b1ca54014bc88f/ghrepo_stats-0.5.4-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b03ef87402d1580567e5fa51161bde2786e4bf076add61d8e462f1e55fe029b8",
                "md5": "06895b6fb0bd6f1026f19413b730cd4d",
                "sha256": "d1db8796cc6d57a673a31a5424e73c2a31ab872e17f66359f3551671fbf01a1c"
            },
            "downloads": -1,
            "filename": "ghrepo-stats-0.5.4.tar.gz",
            "has_sig": false,
            "md5_digest": "06895b6fb0bd6f1026f19413b730cd4d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 13910,
            "upload_time": "2023-03-14T17:44:29",
            "upload_time_iso_8601": "2023-03-14T17:44:29.503935Z",
            "url": "https://files.pythonhosted.org/packages/b0/3e/f87402d1580567e5fa51161bde2786e4bf076add61d8e462f1e55fe029b8/ghrepo-stats-0.5.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-03-14 17:44:29",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "mrbean-bremen",
    "github_project": "ghrepo-stats",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "lcname": "ghrepo-stats"
}
        
Elapsed time: 0.04231s