{"id":15426151,"url":"https://github.com/cryptaliagy/octoviz","last_synced_at":"2025-04-04T16:41:43.686Z","repository":{"id":127565412,"uuid":"200070481","full_name":"cryptaliagy/OctoViz","owner":"cryptaliagy","description":null,"archived":false,"fork":false,"pushed_at":"2019-08-15T22:00:55.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-10T02:14:32.529Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cryptaliagy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-08-01T14:56:20.000Z","updated_at":"2019-08-27T21:02:18.000Z","dependencies_parsed_at":"2023-07-21T01:39:04.873Z","dependency_job_id":null,"html_url":"https://github.com/cryptaliagy/OctoViz","commit_stats":null,"previous_names":["cryptaliagy/octoviz"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2FOctoViz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2FOctoViz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2FOctoViz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptaliagy%2FOctoViz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cryptaliagy","download_url":"https://codeload.github.com/cryptaliagy/OctoViz/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247214146,"owners_count":20902729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T17:54:59.825Z","updated_at":"2025-04-04T16:41:43.660Z","avatar_url":"https://github.com/cryptaliagy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OctoViz\n\nA tool to visualize PR lifetime data from Github!\n\nBefore using, ensure you have a github OAuth token to use. Create profiles using `octoviz profile create` to specify the url to connect to (if in corporate environment) and the token to use.\n\nTo install, simply use `pip install .`. A virtual environment is strongly encouraged if developing, or if there is a concern for conflicting dependencies with your system.\n\nOctoViz comes with lots of information in the help menu. See `octoviz -h` for more details. All sub-commands also have their own help menu by passing the `-h` flag.\n\nCached files and generated HTML files are found in the home directory under the folder '.octoviz' in the home directory. Commands are included to flush the cache, the html files, or everything, as well as to create/delete/update profiles.\n\nWindows support is currently experimental but presumed to be complete.\n\n# Table of Contents\n1. [OctoViz Tour](#octoviz-tour)\n    1. [Installatiion](#installation)\n    2. [Creating a Profile](#creating-a-profile)\n    3. [Deleting OctoViz Profile](#deleting-octoviz-profile)\n    4. [Running the OctoViz – Simple](#running-the-OctoViz-–-simple)\n        1. [Basic Commands \u0026 Cache Management](#basic-commands-\u0026-cache-management)\n        2. [Rate Limiting](#rate-limiting)\n        3. [Saving \u0026 Customizing Your Graphs](#saving-\u0026-customizing-your-graphs)\n        4. [Putting It All Together – Combined Examples](#putting-it-all-together-–-combined-examples)\n2. [Quick Reference Guide](#quick-reference-guide)\n\n# *OctoViz Tour*\n\n## Installation\nTo install, simply clone this repository and install with `pip install .`\n\n\n## Creating a Profile\nIf you are trying to create a profile in OctoViz you will need to use a Github Personal Access token. You can find more information about it in [this link](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line).\n\nYour Github token will need to have (at minimum) access to Public Repositories (repo:public_repo), but if you want to get data for private repositories you might need to give full control of private repositories (repo) access.\n\nNow that you have your access token, you can create your profile by using the following command:\n\n```\noctoviz profile create -t your_token_from_github\n```\n\nIf you need to use multiple profiles – such as if multiple accounts with private repositories need to be analyzed or if connecting both to Github.com and your corporate's Github repository, you will need to name your profiles. If you only have one profile, you can omit the name; OctoViz will automatically name it 'default' for you.\n\nTo name an OctoViz profile, simply add the `-n` flag to your `profile create` call.\n\n```\noctoviz profile create -t your_token_from_github -n my_first_profile\n```\n\nIf you need to connect to a Github Enterprise server, make sure you also pass that to the OctoViz:\n\n```\noctoviz profile create -u https://link-to-company-github.com -t your_token_from_github -n work_profile\n```\n\\\nIf your token was valid, you should now have at least one profile active! Unless you need to update your API token, or the URL to connect to, this should be a one-time setup. You can update your profile by using `octoviz profile update [-t new_token] [-u new_url] NAME`\n\nYou can check your profiles by using `octoviz profile --list`.  \n\n## Deleting OctoViz Profile\n\nTo delete OctoViz profiles, simply run:\n\n```\noctoviz profile delete PROFILE_NAME [PROFILE_NAME ...]\n```\n\nYou may specify more than one profile name to delete multiple profiles with one command\n\n-------\n\n## Running the OctoViz – Simple\nOctoViz was designed to be as simple as possible to use, while still being flexible and powerful enough to provide more detailed usage when desired. The commands and flags shown below will give you a pretty good glimpse of what OctoViz can do!\n\n### *Basic Commands \u0026 Cache Management*\nWithout any flags, OctoViz will search for the specified repository in all profiles until it finds it or runs out of profiles to search in. This means that, if you specify multiple repositories from different servers that you have a profile for, you can effectively grab the data from all of them with no extra hassle.\n\nTo start, run the following:\n```bash\noctoviz run org_name/repo_name  # Replace org_name and repo_name with the appropriate info\n```\n\nThis will cause the OctoViz to connect to Github and pull data of closed pull requests in the repository. By default, it will fetch pull requests that were created within the last 12 months, but you may specify different amounts of time with flags that will be discussed later.\n\n\u003eExtra reading: The pull request data obtained by this method is the 'ShortPullRequest'. You can read more about the data it contains [here](https://github3py.readthedocs.io/en/master/api-reference/pulls.html)\n\nAfter fetching the data, it will group it by the week that the pull request was closed, and then render two graphs: One is a line chart of the 25th, 50th (median), and 90th percentile time taken to close a pull request in a given week, and the other will be the number of pull requests closed during that week.\n\nTo speed up the processing of the same data between OctoViz usages, a local cache will be created and can be found in your OctoViz directory under the folder `cache`. If you re-run the same command, you will see that the time it takes to re-create the graphs is a lot smaller than it took to gather them the first time.\n\n\u003e*Note*: OctoViz will always use cached data if it exists.\n\nIf you have previously cached data for a repository and want to re-cache the data, simply specify the flag `-b` or `--build-cache` as shown below:\n\n```bash\noctoviz run -b org_name/repo_name # Replace org_name and repo_name with appropriate info\n```\n\nThis will force OctoViz to poll Github for the newest PR data.\n\nIf you do not wish to build a cache at all, specify the `--no-cache` flag when executing the OctoViz as such:\n\n```bash\noctoviz run --no-cache org_name/repo_name\n```\n\nIf you want **all** cached data to be deleted after executing OctoViz, specify the `-c` or `--cleanup` flag as such:\n```bash\noctoviz run -c org_name/repo_name # Replace org_name and repo_name with appropriate info\n```\n\nThere are some cases in which you might want OctoViz to cache some data but not need it to immediately display any graphs. In this case, the `--no-render` flag can be specified to speed the process along by performing only the caching operations and none of the data processing ones. You can do so as such:\n\n```bash\noctoviz run --no-render org_name/repo_name\n```\n\n\u003e *Note*: OctoViz does not force the cache to be *re*built when --no-render is specified. If you want to ensure you're fetching the newest data, make sure you also pass the `-b` flag.\n\n\n\n### *Rate Limiting*\n\nThere may be times when the default settings for OctoViz do not poll enough data or poll too much data for your usage. In that case, you may use the rate limiting arguments to request more data or less data.\n\nThe two examples below outline a rate limit of 6 weeks and 6 months respectively:\n\n```\noctoviz run --limit-by-weeks 6 org_name/repo_name\noctoviz run --limit-by-months 6 org_name/repo_name\n```\n\n\u003e *Note*: When rate limiting cached data, OctoViz does not ensure that the data you have is complete. If you have less cached data than you would like to rate-limit, make sure to pass the `-b` flag, otherwise it might show an incomplete graph\n\nThere could also be need to see the entire history of a repository's data. In that case, you may specify the `--no-limit` flag when building the cache to grab the full history. Depending on the size of the repository and how active it is in terms of PRs, this could mean a many-year, multi-thousand-call endeavor. Expect this to take a long time, and be wary of possibly surpassing the Github API request limits\n\n```\noctoviz run --no-limit org_name/repo_name\n```\n\n\u003e *Note*: Github has a limit of 5000 requests per hour to its API. Ensure your calls stay below it.\n\n### *Saving \u0026 Customizing Your Graphs*\n\nYou may have need to create multiple HTML files for different types of graphs. Should that be the case, you may want to keep all rendered HTML files instead of overriding each one. To do so, make sure to specify a name for the output file with `-n`:\n\n```\noctoviz run -n my_repo_graph org_name/repo_name\n```\n\nThis will produce a file called `'my_repo_graph.html'` in your `'.octoviz/html'` folder. By default, any time OctoViz is run without the `-n` or the `--no-render` flag it will generate a file called `'octoviz.html'` in your `'.octoviz/html'` folder.\n\nWhen rendering graphs of time-aggregated data, if you would like to group by month instead of by week, it is possible to do so by specifying the `-m` flag as such:\n\n```\noctoviz run -m org_name/repo_name\n```\n\nIf instead of the week/month closed, you would like the data to be grouped by the week/month a PR was created, you may specify the `--group-by` argument as such:\n\n```\noctoviz run --group-by created org_name/repo_name\n```\n\nWhen the two graphs for each repository are rendered, you may notice that zooming in or panning the x-axis of one graph will cause the other to also change in an identical way on the x-axis. This allows for quick visual identification of both the current values of the line graph and the number of pull requests on the bar graph.\n\nFor two or more repositories, this behaviour is only shared between the graphs of the same repository by default. If you would like to have this behaviour shared between all graphs (so that all graphs are 'synced' to the same timeframe or line number count), specify the `-x` flag.\n\n```\noctoviz run -x org_name/repo_name-1 org_name/repo_name-2\n```\n\nYou may also have noticed that the y-axis scales tend to be different for graphs of different repositories. If you would like to ensure that y-axis panning, zooming, and scale are shared between all graphs in the same column, specify the `-y` flag.\n\n```\noctoviz run -y org_name/repo_name-1 org_name/repo_name-2\n```\n\nThis can be combined with the `-x` flag to always see graphs at the same scale and time in one document\n\nGiven that OctoViz collects the most recent data possible, you might notice that the current timeframe is also included in this. If you would like to only see 'complete' data (i.e. on time span that excludes the current one), specify the `--complete` flag.\n\n```\noctoviz run --complete org_name/repo_name\n```\n\nThis will create a graph that omits the most recent week (if aggregating by week) or month (if aggregating by month).\n\nBy default, OctoViz will provide you with a line graph showing the time it takes for the 25th, 50th, and 90th percentile PRs to be closed. This means that, respectively, it displays the amount of time at which 25%, 50%, and 90% of PRs at that span took to be closed. If these percentiles do not work for your team, you may specify your own with the `-p` argument. If you were wanting to include lines for the 20th, 40th, 60th, and 80th percentile PR, for example, you would do so as such:\n\n```\noctoviz run -p 20,40,60,80 org_name/repo_name\n```\n\nYou may include as many lines as are necessary for you and your team. Keep in mind as well that by clicking on the line in the legend, you will toggle the visibility for that line. This may be useful when wanting to hone in on one specific percentile without having to re-render the graph.\n\n\n### *Putting it all together – Combined Examples*\n\nSay you have an organization named my_org and repositories first_repo and second_repo and you wanted to:\n\nSee the data for PRs since the creation of first_repo, grouped by the month the PRs were opened, ignoring the current month, and save that to a file called 'first_repo_monthly_history.html'\n\n```\noctoviz run --no-limit -m --group-by created --complete -n first_repo_monthly_history my_org/first_repo\n```\n\nLook at the data for the last six months of first_repo and second_repo, without overriding the currently cached data, making sure that the graphs will always be showing the same time span\n\n```\noctoviz run --limit-by-months 6 --no-cache -x my_org/first_repo my_org/second_repo\n```\n\n\n\n\n------------------------\n\n\n# Quick Reference Guide\n\nCreate a profile\n```bash\noctoviz profile create -t your_token\n```\n\nEdit a profile\n```bash\noctoviz profile edit -t new_token profile_name\n```\n\nDelete a profile\n```bash\noctoviz profile delete profile_name\n```\n\nBasic command\n```bash\noctoviz run org_name/repo_name [org_name/repo_name ...] # 12 months of data, aggregated by week PR was closed in\n```\n\nForce-fetch data and build cache\n```\noctoviz run -b org_name/repo_name\n```\n\nForce-fetch data and do not build cache\n```\noctoviz run --no-cache org_name/repo_name\n```\n\nClean up all cached data after execution\n```\noctoviz run --cleanup org_name/repo_name\n```\n\nDo not render HTML file (fetches data if cache does not exist)\n```\noctoviz run --no-render org_name/repo_name\n```\n\nAggregate data by month instead of by week\n```\noctoviz run -m org_name/repo_name\n```\n\nGroup data by when the PR was created\n```\noctoviz run --group-by created org_name/repo_name\n```\n\nShow only data for complete time periods\n```\noctoviz run --complete org_name/repo_name\n```\n\nGive a custom name to the output file\n```\noctoviz run -n my_rendered_file org_name/repo_name\n```\n\nLink the x axes of all rendered graphs\n```\noctoviz run -x org_name/repo_name\n```\n\nLink the y axes of all rendered graphs of the same type\n```\noctoviz run -y org_name/repo_name\n```\n\nShow lines for the 10th, 30th, 60th and 95th percentile times\n```\noctoviz run -p 10,30,60,95 org_name/repo_name\n```\n\nLimit how much data to be polled from Github to only PRs created in the last 6 weeks\n```\noctoviz run --limit-by-weeks 6 org_name/repo_name\n```\n\nLimit how much data to be polled from Github to only PRs created in the last 6 months\n```\noctoviz run --limit-by-months 6 org_name/repo_name\n```\n\nPoll the data for a repository for all closed PRs\n```\noctoviz run --no-limit org_name/repo_name\n```\n\nPoll the full-form of the PR data\n```\noctoviz run --full org_name/repo_name\n```\n\n\u003e *NOTE*: All commands below require data to be polled or cached in full-form\n\nView pull request data by total number of lines changed in a pull request\n```\noctoviz run --analyze-by total org_name/repo_name\n```\n\nView data by total number of lines changed, comparing the last quarter with the one before it\n```\noctoviz run --analyze-by total --compare-last quarter org_name/repo_name\n```\n\nView data by total number of lines changed, comparing the current quarter with the one before it\n```\noctoviz run --analyze-by total --compare-current quarter org_name/repo_name\n```\n\nGroup PR line data size by spans of 40 instead of the default 20\n```\noctoviz run --analyze-by total --round-to 40 org_name/repo_name\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptaliagy%2Foctoviz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptaliagy%2Foctoviz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptaliagy%2Foctoviz/lists"}