prfiesta 0.2.1b228__tar.gz

prfiesta-0.2.1b228/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.3
+Name: prfiesta
+Version: 0.2.1b228
+Summary: Collect and Analyze Individual Contributor Pull Requests
+Keywords: pull-request,pull-request-review,performance-review
+Author: kiran94
+License: MIT
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Dist: pygithub>=1.58.1,<2.0.0
+Requires-Dist: click>=8.1.3,<9.0.0
+Requires-Dist: cloup>=2.1.0,<3.0.0
+Requires-Dist: pandas>=2.0.1,<3.0.0
+Requires-Dist: pyarrow>=18.1.0,<19.0.0
+Requires-Dist: rich>=13.3.5,<14.0.0
+Requires-Dist: seaborn>=0.12.2,<0.13.0
+Requires-Dist: matplotlib>=3.7.1,<4.0.0
+Requires-Dist: natural>=0.2.0,<0.3.0
+Requires-Dist: urllib3<2
+Requires-Dist: duckdb>=1.1.3,<2.0.0
+Requires-Dist: numpy<2
+Requires-Python: >=3.9
+Project-URL: Homepage, https://pypi.org/project/prfiesta/
+Project-URL: Repository, https://github.com/kiran94/prfiesta/pull/67
+Project-URL: Documentation, https://github.com/kiran94/prfiesta/blob/main/README.md
+Description-Content-Type: text/markdown
+
+# prfiesta 🦜🥳
+
+[![main](https://github.com/kiran94/prfiesta/actions/workflows/main.yml/badge.svg)](https://github.com/kiran94/prfiesta/actions/workflows/main.yml) ![GitHub](https://img.shields.io/github/license/kiran94/prfiesta) [![PyPI](https://img.shields.io/pypi/v/prfiesta)](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.
+
+[![asciicast](https://asciinema.org/a/587987.svg)](https://asciinema.org/a/587987)
+
+## Install
+
+```bash
+python -m pip install prfiesta
+```
+
+> [!TIP]
+> If you are using [`uvx`](https://docs.astral.sh/uv/guides/tools/) then you can also just run this:
+> ```bash
+> uvx prfiesta --help
+> ```
+
+Dependencies:
+
+- Python 3.9+
+
+## 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. Must have the `repo` scope. |                          |
+| `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
+uv sync
+uv build
+```
+
+This should leave you in a state where all dependencies are installed and `prfiesta` is available through `uv run`.
+
+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)

prfiesta-0.2.1b228/README.md

@@ -0,0 +1,233 @@
+# prfiesta 🦜🥳
+
+[![main](https://github.com/kiran94/prfiesta/actions/workflows/main.yml/badge.svg)](https://github.com/kiran94/prfiesta/actions/workflows/main.yml) ![GitHub](https://img.shields.io/github/license/kiran94/prfiesta) [![PyPI](https://img.shields.io/pypi/v/prfiesta)](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.
+
+[![asciicast](https://asciinema.org/a/587987.svg)](https://asciinema.org/a/587987)
+
+## Install
+
+```bash
+python -m pip install prfiesta
+```
+
+> [!TIP]
+> If you are using [`uvx`](https://docs.astral.sh/uv/guides/tools/) then you can also just run this:
+> ```bash
+> uvx prfiesta --help
+> ```
+
+Dependencies:
+
+- Python 3.9+
+
+## 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. Must have the `repo` scope. |                          |
+| `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
+uv sync
+uv build
+```
+
+This should leave you in a state where all dependencies are installed and `prfiesta` is available through `uv run`.
+
+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)

prfiesta-0.2.1b228/prfiesta/__init__.py

@@ -0,0 +1,17 @@
+import importlib.metadata
+import logging
+import os
+
+from rich.logging import RichHandler
+
+__version__ = importlib.metadata.version(__name__)
+
+LOGGING_LEVEL = os.environ.get("LOGGING_LEVEL", logging.INFO)
+LOGGING_FORMAT = os.environ.get("LOGGING_FORMAT", "%(message)s")
+SPINNER_STYLE = os.environ.get("SPINNER_STYLE", "blue")
+
+logging.basicConfig(
+    level=LOGGING_LEVEL,
+    format=LOGGING_FORMAT,
+    handlers=[RichHandler(markup=True, show_path=False, show_time=False, show_level=True)],
+)

prfiesta-0.2.1b228/prfiesta/__main__.py

@@ -0,0 +1,100 @@
+import logging
+from datetime import datetime
+
+import click
+import cloup
+from rich.live import Live
+from rich.spinner import Spinner
+from rich.text import Text
+
+from prfiesta import SPINNER_STYLE, __version__
+from prfiesta.collectors.github import GitHubCollector
+from prfiesta.environment import GitHubEnvironment
+from prfiesta.output import output_frame
+
+logger = logging.getLogger(__name__)
+
+github_environment = GitHubEnvironment()
+
+
+@cloup.command()
+@cloup.option_group(
+    "general options",
+    cloup.option("-u", "--users", multiple=True, help="The GitHub Users to search for. Can be multiple"),
+    cloup.option("--reference", help="A external ticket reference to search for e.g. JIRA-1234"),
+)
+@cloup.option_group(
+    "date filter options",
+    cloup.option("-a", "--after", type=click.DateTime(formats=["%Y-%m-%d"]), help="Only search for pull requests after this date e.g 2023-01-01"),
+    cloup.option("-b", "--before", type=click.DateTime(formats=["%Y-%m-%d"]), help="Only search for pull requests before this date e.g 2023-04-30"),
+    cloup.option("-d", "--use-updated", is_flag=True, default=False, help="filter on when the pr was last updated rather then created"),
+)
+@cloup.option_group(
+    "user filter options",
+    cloup.option("-i", "--use-involves", is_flag=True, default=False, help="collect prs where the users are the author or assignee or mentioned or commented"),
+    cloup.option("-r", "--use-reviewed-by", is_flag=True, default=False, help="collect prs where the users reviewed them"),
+    cloup.option("-rr", "--use-review-requested", is_flag=True, default=False, help="collect prs where the users were requested a review"),
+    constraint=cloup.constraints.mutually_exclusive,
+    help="Collect alternative details for the users. If omitted then just collect the prs that a user has authored.",
+)
+@cloup.option_group(
+    "output options",
+    cloup.option("-o", "--output", default=None, help="The output location"),
+    cloup.option(
+        "-ot",
+        "--output-type",
+        type=click.Choice(["csv", "parquet", "duckdb"]),
+        default="csv",
+        show_default=True,
+        show_choices=True,
+        help="The output format",
+    ),
+    cloup.option("-dc", "--drop-columns", multiple=True, help="Drop columns from the output dataframe"),
+)
+@cloup.option_group(
+    "authentication options",
+    cloup.option("-x", "--url", help="The URL of the Git provider to use"),
+    cloup.option("-t", "--token", help="The Authentication token to use"),
+)
+@cloup.version_option(__version__)
+def main(**kwargs) -> None:
+    users: tuple[str] = kwargs.get("users")
+    token: str = kwargs.get("token") or github_environment.get_token()
+    url: str = kwargs.get("url") or github_environment.get_url()
+    output: str = kwargs.get("output")
+    output_type: str = kwargs.get("output_type")
+    before: datetime = kwargs.get("before")
+    after: datetime = kwargs.get("after")
+    drop_columns: list[str] = list(kwargs.get("drop_columns"))
+    use_updated: bool = kwargs.get("use_updated")
+    use_involves: bool = kwargs.get("use_involves")
+    use_reviewed_by: bool = kwargs.get("use_reviewed_by")
+    use_review_requested: bool = kwargs.get("use_review_requested")
+    reference: str = kwargs.get("reference")
+
+    logger.info("[bold green]PR Fiesta 🦜🥳")
+
+    spinner = Spinner("dots", text=Text("Loading", style=SPINNER_STYLE))
+
+    with Live(spinner, refresh_per_second=20, transient=True):
+        collector = GitHubCollector(token=token, url=url, spinner=spinner, drop_columns=drop_columns)
+        pr_frame = collector.collect(
+            *users,
+            after=after,
+            before=before,
+            use_updated=use_updated,
+            use_involves=use_involves,
+            use_reviewed_by=use_reviewed_by,
+            use_review_requested=use_review_requested,
+            reference=reference,
+        )
+
+        if not pr_frame.empty:
+            logger.info("Found [bold green]%s[/bold green] pull requests!", pr_frame.shape[0])
+
+            output_frame(pr_frame, output_type, spinner=spinner, output_name=output)
+            logger.info("Time to analyze 🔎 See https://github.com/kiran94/prfiesta/blob/main/docs/analysis.md for some inspiration!")
+
+
+if __name__ == "__main__":  # pragma: nocover
+    main()

prfiesta-0.2.1b228/prfiesta/analysis/plot.py

@@ -0,0 +1,128 @@
+import calendar
+import logging
+from typing import Optional, Union
+
+import matplotlib.pyplot as plt
+import pandas as pd
+import seaborn as sns
+from matplotlib.axes import Axes
+
+logger = logging.getLogger(__name__)
+
+_months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
+
+
+def plot_state_distribution(data: pd.DataFrame, **kwargs) -> Union[plt.Figure, plt.Axes, pd.DataFrame]:
+    ax: Optional[Axes] = kwargs.get("ax")
+    palette: Optional[str] = kwargs.get("palette")
+    title: Optional[str] = kwargs.get("title", "State Distribution")
+    hue: Optional[str] = kwargs.get("hue", "repository_name")
+
+    if ax:
+        ax.set_title(title)
+
+    return sns.histplot(data, x="state", hue=hue, ax=ax, palette=palette)
+
+
+def plot_overall_timeline(data: pd.DataFrame, **kwargs) -> Union[plt.Figure, plt.Axes, pd.DataFrame]:
+    ax: Optional[Axes] = kwargs.get("ax")
+    palette: Optional[str] = kwargs.get("palette")
+    title: Optional[str] = kwargs.get("title", "Overall Contributions")
+    hue: Optional[str] = kwargs.get("hue", "month")
+
+    temp = data.copy()
+
+    temp["month"] = temp["created_at"].dt.month_name()
+    temp["year"] = temp["created_at"].dt.year.astype(str)
+
+    temp = temp.groupby(["month", "year"])["id"].count()
+    temp = temp.reset_index()
+
+    # X Axis Ordering (Year)
+    x_order = temp["year"].unique().tolist()
+    x_order = [int(x) for x in x_order]
+    x_order.sort()
+    x_order = [str(x) for x in x_order]
+
+    # Hue Ordering (Months)
+    sorted_months = sorted(_months, key=lambda x: list(calendar.month_name).index(x))
+
+    p = sns.barplot(temp, x="year", y="id", hue=hue, ax=ax, order=x_order, hue_order=sorted_months, palette=palette)
+
+    if ax:
+        ax.set_title(title)
+        ax.legend(loc="upper left")
+
+    return p
+
+
+def plot_author_associations(data: pd.DataFrame, **kwargs) -> Union[plt.Figure, plt.Axes, pd.DataFrame]:
+    ax: Optional[Axes] = kwargs.get("ax")
+    palette: Optional[str] = kwargs.get("palette")
+    title: Optional[str] = kwargs.get("title", "Author Associations")
+
+    temp = data.groupby("author_association")["id"].count()
+    temp.name = "count"
+
+    return temp.plot.pie(ax=ax, title=title, legend=True, colormap=palette)
+
+
+def plot_conventional_commit_breakdown(data: pd.DataFrame, **kwargs) -> Union[plt.Figure, plt.Axes, pd.DataFrame]:
+    ax: Optional[Axes] = kwargs.get("ax")
+    palette: Optional[str] = kwargs.get("palette")
+    title: Optional[str] = kwargs.get("title", "Conventional Commit Breakdown")
+    hue: Optional[str] = kwargs.get("hue", "type")
+
+    conventional_commit_frame = (
+        data["title"].str.extract(r"^(?P<type>feat|fix|docs|style|refactor|test|chore|build|ci|perf)(\((?P<scope>[A-Za-z-]+)\))?: (?P<subject>[^\n]+)$").copy()
+    )
+
+    conventional_commit_frame = conventional_commit_frame.drop(columns=[1, "subject"])
+    conventional_commit_frame = pd.concat([conventional_commit_frame, data["repository_name"]], axis=1)
+    conventional_commit_frame = conventional_commit_frame.dropna(subset=["type"])
+
+    if conventional_commit_frame.empty:
+        logger.warning("passed data did not seem to have any conventional commits")
+        return None
+
+    type_count = conventional_commit_frame.groupby(["type", "repository_name"]).count().reset_index()
+    type_count = type_count[type_count["scope"] != 0]
+    type_count = type_count.sort_values(by="scope", ascending=False)
+    type_count = type_count.rename(columns={"scope": "count"})
+
+    p = sns.barplot(type_count, y="repository_name", x="count", hue=hue, ax=ax, palette=palette)
+
+    if ax:
+        ax.set_title(title)
+        ax.legend(loc="upper right")
+
+    return p
+
+
+def plot_reactions(data: pd.DataFrame, **kwargs) -> Union[plt.Figure, plt.Axes, pd.DataFrame]:
+    ax: Optional[Axes] = kwargs.get("ax")
+    palette: Optional[str] = kwargs.get("palette")
+    title: Optional[str] = kwargs.get("title", "Reactions")
+    hue: Optional[str] = kwargs.get("hue")
+    threshold: Optional[int] = kwargs.get("threshold")
+
+    reaction_columns = [x for x in data.columns.tolist() if x.startswith("reactions.") and x not in ["reactions.url"]]
+
+    reaction_df = data[reaction_columns]
+    reaction_df = reaction_df[reaction_df["reactions.total_count"] > 0]
+    reaction_df = reaction_df.drop(columns=["reactions.total_count"])
+
+    if reaction_df.empty:
+        logger.warning("passed data did not seem to have any reactions 🙁")
+        return None
+
+    if threshold:
+        reaction_df = reaction_df[reaction_df < threshold]
+
+    p = sns.scatterplot(reaction_df, ax=ax, palette=palette, hue=hue)
+
+    if ax:
+        ax.set_title(title)
+        ax.legend(loc="upper right")
+
+    return p

prfiesta-0.2.1b228/prfiesta/analysis/view.py

@@ -0,0 +1,34 @@
+from datetime import datetime, timezone
+
+import pandas as pd
+from IPython.display import HTML, DisplayObject
+from natural.date import duration
+
+
+def _enrich_pr_link(data: pd.DataFrame) -> pd.DataFrame:
+    def make_link(row: pd.Series) -> str:
+        return f'<a href="{row["html_url"]}">{row["title"]}</a>'
+
+    data["title"] = data.apply(make_link, axis=1)
+    return data.drop(columns="html_url")
+
+
+def view_pull_requests(data: pd.DataFrame, **kwargs) -> DisplayObject:
+    as_frame: bool = kwargs.get("as_frame", False)
+    relative_dates: bool = kwargs.get("relative_dates", True)
+    head: int = kwargs.get("head")
+
+    temp = data[["number", "title", "repository_name", "updated_at", "html_url"]].copy()
+    temp = _enrich_pr_link(temp)
+
+    if relative_dates:
+        temp["updated_at"] = pd.to_datetime(temp["updated_at"])
+        temp["updated_at"] = temp["updated_at"].apply(duration, now=datetime.now(timezone.utc))
+
+    if head:
+        temp = temp.head(head)
+
+    if as_frame:
+        return temp
+
+    return HTML(temp.to_html(escape=False, index=False))

prfiesta-0.2.1b228/prfiesta/collectors/github.py

@@ -0,0 +1,169 @@
+import logging
+from datetime import datetime
+from typing import List, Optional, Tuple
+
+import pandas as pd
+from github import Github
+from github.GithubException import RateLimitExceededException
+from rich.spinner import Spinner
+
+from prfiesta.environment import GitHubEnvironment
+from prfiesta.spinner import update_spinner
+
+logger = logging.getLogger(__name__)
+
+
+class GitHubCollector:
+    def __init__(self, **kwargs) -> None:
+        environment = GitHubEnvironment()
+        token = kwargs.get("token") or environment.get_token()
+        self._url = kwargs.get("url") or environment.get_url()
+
+        self._github = Github(token, base_url=self._url)
+        self._spinner: Spinner = kwargs.get("spinner")
+
+        self._sort_column = ["updated_at"]
+        self._drop_columns = kwargs.get("drop_columns") or ["node_id", "performed_via_github_app"]
+
+        self._move_to_end_columns = [
+            "url",
+            "repository_url",
+            "html_url",
+            "timeline_url",
+            "labels_url",
+            "comments_url",
+            "events_url",
+        ]
+        self._datetime_columns = [
+            "created_at",
+            "updated_at",
+            "closed_at",
+        ]
+
+    def collect(
+        self,
+        *users: Optional[Tuple[str]],
+        after: Optional[datetime] = None,
+        before: Optional[datetime] = None,
+        use_updated: Optional[bool] = False,
+        use_involves: Optional[bool] = False,
+        use_reviewed_by: Optional[bool] = False,
+        use_review_requested: Optional[bool] = False,
+        reference: Optional[str] = None,
+    ) -> pd.DataFrame:
+        query = self._construct_query(users, after, before, use_updated, use_involves, use_reviewed_by, use_review_requested, reference)
+
+        update_spinner(f"Searching {self._url} with[bold blue] {query}", self._spinner, logger)
+
+        pull_request_data = None
+        try:
+            pulls = self._github.search_issues(query=query)
+
+            pull_request_data: list[dict] = []
+            for pr in pulls:
+                pull_request_data.append(pr.__dict__["_rawData"])
+
+        except RateLimitExceededException as e:
+            logger.warning("🙇 You were rate limited by the GitHub API, try requesting less data.")
+            logger.debug(e)
+            return pd.DataFrame()
+
+        if not pull_request_data:
+            logger.warning("Did not find any results for this search criteria!")
+            return pd.DataFrame()
+
+        update_spinner("Post Processing", self._spinner, logger)
+        pr_frame = pd.json_normalize(pull_request_data)
+
+        pr_frame = pr_frame.drop(columns=self._drop_columns, errors="ignore")
+        pr_frame = pr_frame.sort_values(by=self._sort_column, ascending=False)
+        pr_frame = self._parse_datetime_columns(pr_frame)
+        pr_frame["repository_name"] = pr_frame["repository_url"].str.extract(r"(.*)\/repos\/(?P<repository_name>(.*))")["repository_name"]
+        pr_frame = self._move_column_to_end(pr_frame)
+
+        return pr_frame
+
+    @staticmethod
+    def _construct_query(
+        users: Optional[List[str]],
+        after: Optional[datetime] = None,
+        before: Optional[datetime] = None,
+        use_updated: Optional[bool] = False,
+        use_involves: Optional[bool] = False,
+        use_reviewed_by: Optional[bool] = False,
+        use_review_requested: Optional[bool] = False,
+        reference: Optional[str] = None,
+    ) -> str:
+        """
+        Constructs a GitHub Search Query
+        that returns pull requests made by the passed users and options.
+
+        Examples
+        --------
+            type:pr author:user1
+            type:pr author:user2 created:<=2021-01-01
+            type:pr author:user1 author:user2 created:2021-01-01..2021-03-01
+            type:pr author:user2 updated:>=2021-01-01
+            type:pr involves:user2
+            type:pr reviewed-by:user1
+            type:pr review-requested:user1
+            type:pr in:title,body "PA-12765"
+
+        All dates are inclusive.
+        See GitHub Docs for full options https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests
+        """
+        query: List[str] = []
+        query.append("type:pr")
+
+        author_filter = "author"
+        if use_involves:
+            author_filter = "involves"
+        elif use_reviewed_by:
+            author_filter = "reviewed-by"
+        elif use_review_requested:
+            author_filter = "review-requested"
+
+        logger.debug("using author filter %s", author_filter)
+
+        for u in users:
+            query.append(f"{author_filter}:{u}")
+
+        time_filter = "created"
+        if use_updated:
+            time_filter = "updated"
+
+        logger.debug("using time filter %s", time_filter)
+
+        if before and after:
+            query.append(f"{time_filter}:{after.strftime('%Y-%m-%d')}..{before.strftime('%Y-%m-%d')}")
+        elif before:
+            query.append(f"{time_filter}:<={before.strftime('%Y-%m-%d')}")
+        elif after:
+            query.append(f"{time_filter}:>={after.strftime('%Y-%m-%d')}")
+
+        if reference:
+            query.append(f'in:title,body "{reference}"')
+
+        return " ".join(query)
+
+    def _move_column_to_end(self, df: pd.DataFrame) -> pd.DataFrame:
+        for col in self._move_to_end_columns:
+            try:
+                df.insert(len(df.columns) - 1, col, df.pop(col))
+                df.drop(columns=col)
+            except KeyError:
+                # This can happen if the user provides a custom _drop_columns which
+                # removes the column before we can move it to the end
+                logger.debug("Attempted to move column %s but it did not exist", col)
+
+        return df
+
+    def _parse_datetime_columns(self, df: pd.DataFrame) -> pd.DataFrame:
+        for col in self._datetime_columns:
+            df[col] = pd.to_datetime(df[col], errors="coerce")
+        return df
+
+
+if __name__ == "__main__":  # pragma: nocover
+    g = GitHubCollector()
+    logger.info(g._construct_query(["kiran94", "hello"], datetime(2021, 1, 1), datetime(2021, 3, 1)))

prfiesta-0.2.1b228/prfiesta/environment.py

@@ -0,0 +1,17 @@
+import os
+
+from github.Consts import DEFAULT_BASE_URL as GITHUB_DEFAULT_BASE_URL
+
+
+class GitHubEnvironment:
+    def get_token(self) -> str:
+        """Gets the authentication token for this environment."""
+        token = os.environ.get("GITHUB_ENTERPRISE_TOKEN", os.environ.get("GITHUB_TOKEN"))
+        if not token:
+            raise ValueError("GITHUB_ENTERPRISE_TOKEN or GITHUB_TOKEN must be set")
+
+        return token
+
+    def get_url(self) -> str:
+        """Gets the URL for the git provider."""
+        return os.environ.get("GH_HOST", GITHUB_DEFAULT_BASE_URL)

prfiesta-0.2.1b228/prfiesta/output.py

@@ -0,0 +1,57 @@
+import logging
+import os
+import re
+from datetime import datetime
+from typing import Literal, Optional
+
+import duckdb
+import pandas as pd
+from rich.spinner import Spinner
+
+from prfiesta.spinner import update_spinner
+
+logger = logging.getLogger(__name__)
+
+OUTPUT_TYPE = Literal["csv", "parquet", "duckdb"]
+WIN_ILLEGAL_FILENAME = r"[:\/\\\*\?\"\<\>\|]"
+
+
+def output_frame(
+    frame: pd.DataFrame,
+    output_type: OUTPUT_TYPE,
+    spinner: Spinner,
+    output_name: Optional[str] = None,
+    timestamp: Optional[datetime] = None,
+) -> None:
+    if not timestamp:
+        timestamp = datetime.now()
+
+    if not output_name:
+        output_name = f"export.{timestamp.strftime('%Y%m%d%H%M%S')}.{output_type}"
+
+    if os.name == "nt" and re.search(WIN_ILLEGAL_FILENAME, output_name):
+        msg = f"{output_name} is an invalid filename on windows"
+        raise ValueError(msg)
+
+    update_spinner(f"Writing export to {output_name}", spinner, logger)
+
+    if output_type == "csv":
+        frame.to_csv(output_name, index=False)
+
+    elif output_type == "parquet":
+        frame.to_parquet(output_name, index=False)
+
+    elif output_type == "duckdb":
+        duckdb_table = f"prfiesta_{timestamp.strftime('%Y%m%d_%H%M%S')}"
+
+        update_spinner(f"connecting to duckdb {output_name}", spinner, logger)
+        conn = duckdb.connect(output_name)
+
+        update_spinner(f"exporting to duckdb table {duckdb_table}", spinner, logger)
+        conn.execute(f"CREATE TABLE {duckdb_table} AS SELECT * FROM frame")  # noqa: S608 duckdb_table is always constructed internally
+
+        conn.close()
+    else:
+        raise ValueError("unknown output_type %s", output_type)
+
+    logger.info("Exported to %s!", output_name)

prfiesta-0.2.1b228/prfiesta/spinner.py

@@ -0,0 +1,11 @@
+from logging import Logger
+
+from rich.spinner import Spinner
+
+from prfiesta import SPINNER_STYLE
+
+
+def update_spinner(message: str, spinner: Spinner, logger: Logger) -> None:
+    logger.debug(message)
+    if spinner:
+        spinner.update(text=message, style=SPINNER_STYLE)

prfiesta-0.2.1b228/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "prfiesta"
+version = "0.2.1b228"
+description = "Collect and Analyze Individual Contributor Pull Requests"
+authors = [{ name = "kiran94" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.9"
+keywords = [ "pull-request", "pull-request-review", "performance-review" ]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Version Control :: Git"
+]
+dependencies = [
+    "pygithub>=1.58.1,<2.0.0",
+    "click>=8.1.3,<9.0.0",
+    "cloup>=2.1.0,<3.0.0",
+    "pandas>=2.0.1,<3.0.0",
+    "pyarrow>=18.1.0,<19.0.0",
+    "rich>=13.3.5,<14.0.0",
+    "seaborn>=0.12.2,<0.13.0",
+    "matplotlib>=3.7.1,<4.0.0",
+    "natural>=0.2.0,<0.3.0",
+    "urllib3<2",
+    "duckdb>=1.1.3,<2.0.0",
+    "numpy<2",
+]
+
+[project.urls]
+Homepage = "https://pypi.org/project/prfiesta/"
+Repository = "https://github.com/kiran94/prfiesta/pull/67"
+Documentation = "https://github.com/kiran94/prfiesta/blob/main/README.md"
+
+[project.scripts]
+prfiesta = "prfiesta.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=7.3.1,<8.0.0",
+    "pytest-cov>=4.0.0,<5.0.0",
+    "pytest-github-actions-annotate-failures>=0.2.0,<0.3.0",
+    "jupyterlab-widgets>=3.0.7,<4.0.0",
+    "jupyter-black>=0.3.4,<0.4.0",
+    "ipywidgets>=8.0.6,<9.0.0",
+    "pre-commit>=3.3.2,<4.0.0",
+    "ruff>=0.1.0,<0.2.0",
+    "jupyterlab>=4.3.4,<5.0.0",
+    "papermill>=2.6.0,<3.0.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "prfiesta"
+
+[tool.ruff]
+line-length = 160
+target-version = "py38"
+
+# All Rules: https://beta.ruff.rs/docs/rules/
+select = [
+    "F",     # pyflakes
+    "E",     # pycodestyle
+    "C90",   # macabe complexity
+    "I",     # isort
+    "W",     # warning
+    "N",     # pep8-naming
+    "UP",    # pyupgrade
+    "YTT",   # flake8-2020
+    "ANN",   # flake8-annotations
+    "S",     # flake8-bandit
+    "BLE",   # flake8-blind-except
+    "B",     # flake8-bugbear
+    "A",     # flake8-builtins
+    "COM",   # flake8-commas
+    "C4",    # flake8-comprehensions
+    # "DTZ", # flake8-datetimez
+    "T10",   # flake8-debugger
+    "DJ",    # flake8-django
+    "EM",    # flake8-errmsg
+    "EXE",   # flake8-executable
+    "ISC",   # flake8-implicit-str-concat
+    "ICN",   # flake8-import-conventions
+    "G",     # flake8-logging-format
+    "INP",   # flake8-no-pep420
+    "PIE",   # flake8-pie
+    "T20",   # flake8-print
+    "PYI",   # flake8-pyi
+    "PT",    # flake8-pytest-style
+    "Q",     # flake8-quotes
+    "RSE",   # flake8-raise
+    "RET",   # flake8-return
+    # "SLF", # flake8-self
+    "SIM",   # flake8-simplify
+    "TID",   # flake8-tidy-imports
+    "INT",   # flake8-gettext
+    "ARG",   # flake8-unused-arguments
+    # "PTH", # flake8-use-pathlib
+    "ERA",   # eradicate
+    "PD",    # pandas-vet
+    "PGH",   # pygrep-hooks
+    "PL",    # pylint
+    "PLE",   # error
+    "PLR",   # refactor
+    "PLW",   # warning
+    "NPY",   # numpy-specific-rules
+    "RUF",   # ruff-specific-rules
+]
+
+ignore = [
+    "S101",    # asserts are used in unit tests
+    "EM101",   # not a big deal if the error message is duplicated in the traceback
+    "ANN101",  # ignore missing type annotation on self
+    "ANN003",  # ignore missing type annotations on **kwargs
+    "PLR0913", # ignore for test cases with high level of paramtatization
+    "COM812",  # disable to avoid conflict with formatter
+    "ISC001",  # disable to avoid conflict with formatter
+    "RET504",  # sometimes decreases code readability
+]