# prfiesta 🦜🥳
[](https://github.com/kiran94/prfiesta/actions/workflows/main.yml)  [](https://pypi.org/project/prfiesta/)
> Collect and Analyze Individual Contributor Pull Requests
`prfiesta` allows you to collect, analyze and celebrate pull requests made by an individual 🎉.
It can be used by engineers or managers to gain insights into all the great work the contributor has made over a specified period of time. A great use case of this tool is during a performance review process when you want to perform analysis on all the contributions made over the year.
[](https://asciinema.org/a/587987)
## Install
```bash
python -m pip install prfiesta
```
Dependencies:
- Python 3.8+
## Usage
```bash
# Authenticate yourself
export GITHUB_TOKEN=... # or GITHUB_ENTERPRISE_TOKEN
# Get all pull requests for a user
prfiesta -u kiran94
# Get all pull requests for a user created after a date
prfiesta -u kiran94 --after 2023-01-01
# Get all pull requests for a user created between two dates
prfiesta -u kiran94 --after 2023-01-01 --before 2023-06-01
# Get all pull requests for a user updated after a date
prfiesta -u kiran94 --after 2023-01-01 --use-updated
# Get all pull requests with a custom output file name
prfiesta -u kiran94 --output my_pull_requests.csv
# Get all pull requests in parquet format with a custom file name
prfiesta -u kiran94 --output-type parquet --output my_pull_requests.parquet
# Get all pull requests and export to a duckdb database
prfiesta -u kiran94 --output-type duckdb --output mydatabase.duckdb
# Get all pull requests for more then one user
prfiesta -u kiran94 -u user2
# Get all pull requests and drop specific columns from the output
prfiesta -u kiran94 -dc events_url -dc comments_url -dc node_id
# Get all pull requests where the user was involved (as opposed to just authored)
prfiesta -u kiran94 --use-involves
# Get all pull requests where the user reviewed it rather then being the author
prfiesta -u charliermarsh --after 2023-05-01 --use-reviewed-by
# Get all pull requests where the user was requested a review rather then being the author
prfiesta -u charliermarsh --after 2023-05-01 --use-review-requested
# Get all pull requests which contains a reference (e.g JIRA card reference) within the PR title or body
prfiesta --reference PA-12765
# Get help
prfiesta --help
# Show the current version
prfiesta --version
```
You can also leverage `prfiesta` directly in your own application:
```python
import pandas as pd
from datetime import datetime
from prfiesta.collectors.github import GitHubCollector
github = GitHubCollector()
frame: pd.DataFrame = github.collect('kiran94', 'user2', after=datetime(2023, 1, 1))
print(frame)
```
### Output
You can control the output type using the `--output-type` option. Supported options:
- `csv` (default)
- `parquet`
- [`duckdb`](https://duckdb.org/)
You can also customize the output file name using the `--output` option. When using `duckdb`, this argument is the duckdb database that we should export into. You can see an example of a duckdb workflow [here](https://github.com/kiran94/prfiesta/blob/main/notebooks/misc/duckdb_integration.ipynb).
### User Filter
By default, `prfiesta` will take the users provided in the `--user` option and search the Git provider for any pull requests that the user **authored**. Within more collaborative environments, this may not be what you want as you may want to also gain some visibility into all secondary contributions a user made (e.g commenting on others pull requests).
*The options listed here are mutually exclusive.*
#### User Involvement
`prfiesta` exposes the `--use-involves` flag which will search for pull requests that were:
- Created by a certain user
- Assigned to that user
- Mention that user
- commented on by that user
Learn more about `involves` [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-a-user-thats-involved-in-an-issue-or-pull-request).
#### User Reviewed
`prfiesta` exposes a `--use-reviewed-by` flag which will collect pull requests where the user *has reviewed* other's pull requests.
Learn more about searching review requests [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-pull-request-review-status-and-reviewer)
#### User Requested Review
`prfiesta` exposes a `--use-review-requested` flag which will collect pull requests where the user was *requested* a review from other collaborators.
Learn more about searching review requests [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-pull-request-review-status-and-reviewer)
### Date Filter
When using the `--after` and `--before` date filters, by default `prfiesta` will use the `created` date dimension with these filters on the Git provider (e.g GitHub). This may not fit your use case and you may want to filter on when a pull request was `updated` instead. To do this you can use the `--use-updated` flag.
Learn more about date filters [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-when-an-issue-or-pull-request-was-created-or-last-updated).
### Reference Search
You may come across a use case where you want to filter pull requests on a specific reference. For example, it may be a team practise to put a JIRA card reference within the pull request title or body.
For this you can use the `--reference` filter.
> [!NOTE]
> Results from reference search is entirely up to the GitHub Search API. On some ocassions, it may not provide inaccurate results.
## Analysis
`prfiesta` ships with built in plots to help analyze your pull request data. These serve as a starting point in your analysis. See more information on the build in plots and views [here](https://github.com/kiran94/prfiesta/blob/main/docs/analysis.md).
## Using GitHub Enterprise
If you trying to fetch data from a [GitHub Enterprise](https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin?apiVersion=2022-11-28) server, then much of the same functionality should work the same. You just need to make sure that:
- `GH_HOST` is set to your enterprise instance's API URL. Reach out to your internal GitHub team if you are not sure what this should be.
- `GITHUB_ENTERPRISE_TOKEN` a [personal access token](https://docs.github.com/en/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) generated on your GitHub Enterprise instance.
## GitHub Rate Limiting
Depending on your input parameters, you may end up in a situation where you are being [Rate Limited](https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limiting) by the GitHub API.
See this [Notebook](https://github.com/kiran94/prfiesta/blob/main/notebooks/misc/rate_limit.ipynb) on a way to handle this.
## Environment Variables
| Variable | Description | Default |
| --------------- | --------------- | ------ |
| `GITHUB_TOKEN` | The Github [`Token`](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to use | |
| `GITHUB_ENTERPRISE_TOKEN` | Takes precedence over `GITHUB_TOKEN` when set | |
| `GH_HOST` | The Github Host to communicate with (Override this with your company's GitHub Enterprise server if needed) | `https://api.github.com` |
| `LOGGING_LEVEL` | The [Logging Level](https://docs.python.org/3/library/logging.html#logging-levels) to use | `INFO` |
| `LOGGING_FORMAT` | The [Logging Format](https://docs.python.org/3/library/logging.html#logrecord-attributes) to use | `%(message)s` |
| `SPINNER_STYLE` | The [Spinner Style](https://rich.readthedocs.io/en/stable/reference/spinner.html) to use | `blue` |
## Developer Setup
Assuming you have cloned the repository and are at the root of the repository in your terminal.
```bash
poetry shell
poetry install
poetry build
```
This should leave you in a state where you have the virtual environment sourced, all dependencies are installed and `prfiesta` is installed locally.
You can then leverage the various commands in the [makefile](https://github.com/kiran94/prfiesta/blob/main/makefile) for development tasks:
```bash
# Run all unit tests
make test
# Produce code coverage reports
make coverage
# Code linting
make lint
```
Optionally you can also install [pre-commit](https://github.com/pre-commit/pre-commit) to run some sanity checks before your commits.
```bash
# Install it into your git hooks (one time setup)
# from this point onwards, any commits will run pre-commit checks
precommit_install
# If you want to run all checks on all files without comitting.
precommit_run
```
### Creating Prereleases
When you create a pull request on this repository, various CI checks are run, towards the end of those checks there is a `release` job.
Usually when running under `main`, this job is responsible for publishing new versions to pypi. However when running under a pull request, this will create a special prerelease package specific to that pull request.
The versioning of this package follows [PEP-440](https://peps.python.org/pep-0440/#pre-releases) and will look something like this:
```
0.8.1b125
```
Where
- `0.8.1` = The bumped version of what is currently within the `pyproject.toml` of that pull request. We don't attempt to do any analysis to figure out if we should be bumping with a higher serverity in this context.
- `b` = Beta; Indicates to pypi that this is a prerelease package.
- `125` = The `github.run_number` from [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context).
An example prerelease package looks like this: https://pypi.org/project/prfiesta/0.8.1b125/
Downstream users can then do a full end to end test with the prerelease package before the change is merged into `main`. This will automatically be posted into the pull request [example](https://github.com/kiran94/prfiesta/pull/36#issuecomment-1564909558).
You can find the full version history of package [here](https://pypi.org/project/prfiesta/#history)
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/prfiesta/",
"name": "prfiesta",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "pull-request,pull-request-review,performance-review",
"author": "kiran94",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/89/2d/d1891f62fc792cf8da6fda47ef404a7116767c602ecb394d357f772e3c4d/prfiesta-0.13.0.tar.gz",
"platform": null,
"description": "# prfiesta \ud83e\udd9c\ud83e\udd73\n\n[](https://github.com/kiran94/prfiesta/actions/workflows/main.yml)  [](https://pypi.org/project/prfiesta/)\n\n> Collect and Analyze Individual Contributor Pull Requests\n\n`prfiesta` allows you to collect, analyze and celebrate pull requests made by an individual \ud83c\udf89.\n\nIt can be used by engineers or managers to gain insights into all the great work the contributor has made over a specified period of time. A great use case of this tool is during a performance review process when you want to perform analysis on all the contributions made over the year.\n\n[](https://asciinema.org/a/587987)\n\n## Install\n\n```bash\npython -m pip install prfiesta\n```\n\nDependencies:\n\n- Python 3.8+\n\n## Usage\n\n```bash\n# Authenticate yourself\nexport GITHUB_TOKEN=... # or GITHUB_ENTERPRISE_TOKEN\n\n# Get all pull requests for a user\nprfiesta -u kiran94\n\n# Get all pull requests for a user created after a date\nprfiesta -u kiran94 --after 2023-01-01\n\n# Get all pull requests for a user created between two dates\nprfiesta -u kiran94 --after 2023-01-01 --before 2023-06-01\n\n# Get all pull requests for a user updated after a date\nprfiesta -u kiran94 --after 2023-01-01 --use-updated\n\n# Get all pull requests with a custom output file name\nprfiesta -u kiran94 --output my_pull_requests.csv\n\n# Get all pull requests in parquet format with a custom file name\nprfiesta -u kiran94 --output-type parquet --output my_pull_requests.parquet\n\n# Get all pull requests and export to a duckdb database\nprfiesta -u kiran94 --output-type duckdb --output mydatabase.duckdb\n\n# Get all pull requests for more then one user\nprfiesta -u kiran94 -u user2\n\n# Get all pull requests and drop specific columns from the output\nprfiesta -u kiran94 -dc events_url -dc comments_url -dc node_id\n\n# Get all pull requests where the user was involved (as opposed to just authored)\nprfiesta -u kiran94 --use-involves\n\n# Get all pull requests where the user reviewed it rather then being the author\nprfiesta -u charliermarsh --after 2023-05-01 --use-reviewed-by\n\n# Get all pull requests where the user was requested a review rather then being the author\nprfiesta -u charliermarsh --after 2023-05-01 --use-review-requested\n\n# Get all pull requests which contains a reference (e.g JIRA card reference) within the PR title or body\nprfiesta --reference PA-12765\n\n# Get help\nprfiesta --help\n\n# Show the current version\nprfiesta --version\n```\n\nYou can also leverage `prfiesta` directly in your own application:\n\n```python\nimport pandas as pd\n\nfrom datetime import datetime\nfrom prfiesta.collectors.github import GitHubCollector\n\ngithub = GitHubCollector()\nframe: pd.DataFrame = github.collect('kiran94', 'user2', after=datetime(2023, 1, 1))\n\nprint(frame)\n```\n\n### Output\n\nYou can control the output type using the `--output-type` option. Supported options:\n\n- `csv` (default)\n- `parquet`\n- [`duckdb`](https://duckdb.org/)\n\nYou can also customize the output file name using the `--output` option. When using `duckdb`, this argument is the duckdb database that we should export into. You can see an example of a duckdb workflow [here](https://github.com/kiran94/prfiesta/blob/main/notebooks/misc/duckdb_integration.ipynb).\n\n### User Filter\n\nBy default, `prfiesta` will take the users provided in the `--user` option and search the Git provider for any pull requests that the user **authored**. Within more collaborative environments, this may not be what you want as you may want to also gain some visibility into all secondary contributions a user made (e.g commenting on others pull requests).\n\n*The options listed here are mutually exclusive.*\n\n#### User Involvement\n\n`prfiesta` exposes the `--use-involves` flag which will search for pull requests that were:\n\n- Created by a certain user\n- Assigned to that user\n- Mention that user\n- commented on by that user\n\nLearn more about `involves` [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-a-user-thats-involved-in-an-issue-or-pull-request).\n\n#### User Reviewed\n\n`prfiesta` exposes a `--use-reviewed-by` flag which will collect pull requests where the user *has reviewed* other's pull requests.\n\nLearn more about searching review requests [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-pull-request-review-status-and-reviewer)\n\n#### User Requested Review\n\n`prfiesta` exposes a `--use-review-requested` flag which will collect pull requests where the user was *requested* a review from other collaborators.\n\nLearn more about searching review requests [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-pull-request-review-status-and-reviewer)\n\n### Date Filter\n\nWhen using the `--after` and `--before` date filters, by default `prfiesta` will use the `created` date dimension with these filters on the Git provider (e.g GitHub). This may not fit your use case and you may want to filter on when a pull request was `updated` instead. To do this you can use the `--use-updated` flag.\n\nLearn more about date filters [here](https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests#search-by-when-an-issue-or-pull-request-was-created-or-last-updated).\n\n### Reference Search\n\nYou may come across a use case where you want to filter pull requests on a specific reference. For example, it may be a team practise to put a JIRA card reference within the pull request title or body.\n\nFor this you can use the `--reference` filter.\n\n> [!NOTE]\n> Results from reference search is entirely up to the GitHub Search API. On some ocassions, it may not provide inaccurate results.\n\n## Analysis\n\n`prfiesta` ships with built in plots to help analyze your pull request data. These serve as a starting point in your analysis. See more information on the build in plots and views [here](https://github.com/kiran94/prfiesta/blob/main/docs/analysis.md).\n\n## Using GitHub Enterprise\n\nIf you trying to fetch data from a [GitHub Enterprise](https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin?apiVersion=2022-11-28) server, then much of the same functionality should work the same. You just need to make sure that:\n\n- `GH_HOST` is set to your enterprise instance's API URL. Reach out to your internal GitHub team if you are not sure what this should be.\n- `GITHUB_ENTERPRISE_TOKEN` a [personal access token](https://docs.github.com/en/enterprise-cloud@latest/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) generated on your GitHub Enterprise instance.\n\n## GitHub Rate Limiting\n\nDepending on your input parameters, you may end up in a situation where you are being [Rate Limited](https://docs.github.com/en/rest/overview/resources-in-the-rest-api?apiVersion=2022-11-28#rate-limiting) by the GitHub API.\n\nSee this [Notebook](https://github.com/kiran94/prfiesta/blob/main/notebooks/misc/rate_limit.ipynb) on a way to handle this.\n\n## Environment Variables\n\n| Variable | Description | Default |\n| --------------- | --------------- | ------ |\n| `GITHUB_TOKEN` | The Github [`Token`](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to use | |\n| `GITHUB_ENTERPRISE_TOKEN` | Takes precedence over `GITHUB_TOKEN` when set | |\n| `GH_HOST` | The Github Host to communicate with (Override this with your company's GitHub Enterprise server if needed) | `https://api.github.com` |\n| `LOGGING_LEVEL` | The [Logging Level](https://docs.python.org/3/library/logging.html#logging-levels) to use | `INFO` |\n| `LOGGING_FORMAT` | The [Logging Format](https://docs.python.org/3/library/logging.html#logrecord-attributes) to use | `%(message)s` |\n| `SPINNER_STYLE` | The [Spinner Style](https://rich.readthedocs.io/en/stable/reference/spinner.html) to use | `blue` |\n\n## Developer Setup\n\nAssuming you have cloned the repository and are at the root of the repository in your terminal.\n\n```bash\npoetry shell\npoetry install\npoetry build\n```\n\nThis should leave you in a state where you have the virtual environment sourced, all dependencies are installed and `prfiesta` is installed locally.\n\nYou can then leverage the various commands in the [makefile](https://github.com/kiran94/prfiesta/blob/main/makefile) for development tasks:\n\n```bash\n# Run all unit tests\nmake test\n\n# Produce code coverage reports\nmake coverage\n\n# Code linting\nmake lint\n```\n\nOptionally you can also install [pre-commit](https://github.com/pre-commit/pre-commit) to run some sanity checks before your commits.\n\n```bash\n# Install it into your git hooks (one time setup)\n# from this point onwards, any commits will run pre-commit checks\nprecommit_install\n\n# If you want to run all checks on all files without comitting.\nprecommit_run\n```\n\n### Creating Prereleases\n\nWhen you create a pull request on this repository, various CI checks are run, towards the end of those checks there is a `release` job.\n\nUsually when running under `main`, this job is responsible for publishing new versions to pypi. However when running under a pull request, this will create a special prerelease package specific to that pull request.\n\nThe versioning of this package follows [PEP-440](https://peps.python.org/pep-0440/#pre-releases) and will look something like this:\n\n```\n0.8.1b125\n```\n\nWhere\n- `0.8.1` = The bumped version of what is currently within the `pyproject.toml` of that pull request. We don't attempt to do any analysis to figure out if we should be bumping with a higher serverity in this context.\n- `b` = Beta; Indicates to pypi that this is a prerelease package.\n- `125` = The `github.run_number` from [GitHub Actions](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context).\n\nAn example prerelease package looks like this: https://pypi.org/project/prfiesta/0.8.1b125/\n\nDownstream users can then do a full end to end test with the prerelease package before the change is merged into `main`. This will automatically be posted into the pull request [example](https://github.com/kiran94/prfiesta/pull/36#issuecomment-1564909558).\n\nYou can find the full version history of package [here](https://pypi.org/project/prfiesta/#history)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Collect and Analyze Individual Contributor Pull Requests",
"version": "0.13.0",
"project_urls": {
"Documentation": "https://github.com/kiran94/prfiesta/blob/main/README.md",
"Homepage": "https://pypi.org/project/prfiesta/",
"Repository": "https://github.com/kiran94/prfiesta"
},
"split_keywords": [
"pull-request",
"pull-request-review",
"performance-review"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d3f9564a07351aeac92cb0f0b1fc2a909d6cc6c943351eb878f80be3d74e0158",
"md5": "385d43c1315eede07bd946ebf376aa2f",
"sha256": "785dd1aa6498ba0d1cd14ba1b2fa3c9c13c57375eddad59d6493394ac4d1e85b"
},
"downloads": -1,
"filename": "prfiesta-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "385d43c1315eede07bd946ebf376aa2f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 14361,
"upload_time": "2024-01-26T19:33:14",
"upload_time_iso_8601": "2024-01-26T19:33:14.516424Z",
"url": "https://files.pythonhosted.org/packages/d3/f9/564a07351aeac92cb0f0b1fc2a909d6cc6c943351eb878f80be3d74e0158/prfiesta-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "892dd1891f62fc792cf8da6fda47ef404a7116767c602ecb394d357f772e3c4d",
"md5": "d0eb641d5b1e958e974f407fcea7f362",
"sha256": "4b1da9519c2b9515e498f07cccee97485111ddc937f3444486c768c31d92140b"
},
"downloads": -1,
"filename": "prfiesta-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "d0eb641d5b1e958e974f407fcea7f362",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 15754,
"upload_time": "2024-01-26T19:33:16",
"upload_time_iso_8601": "2024-01-26T19:33:16.375497Z",
"url": "https://files.pythonhosted.org/packages/89/2d/d1891f62fc792cf8da6fda47ef404a7116767c602ecb394d357f772e3c4d/prfiesta-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-26 19:33:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiran94",
"github_project": "prfiesta",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "prfiesta"
}
JSON
