Relevant source:
|
def get_commit(self, sha: str) -> Commit: |
|
""" |
|
:calls: `GET /repos/{owner}/{repo}/commits/{ref} <https://docs.github.com/en/rest/reference/repos#commits>`_ |
|
:param sha: string |
|
:rtype: :class:`github.Commit.Commit` |
|
""" |
|
assert isinstance(sha, str), sha |
|
sha = urllib.parse.quote(sha, safe="") |
|
url = f"{self.url}/commits/{sha}" |
|
return github.Commit.Commit(self._requester, url=url) |
GitHub's API endpoint documentation uses ref, rather than sha, to reflect that the API accepts more than just commit shas (commits, branch names, and tags are all accepted), but PyGithub's method signature still uses sha.
This has caused me trouble with a service at work. A user provided my API a branch, rather than a commit sha, like the API endpoint expected. To my surprise, get_commit accepted the input (I expected a validation error due to the misleading naming). To be explicitly clear, the bug was in my application, not PyGithub, but the naming of this argument led me to believe the method would behave differently than it actually does.
Additionally (and this is a much more minor concern imo), the link to GitHub's API endpoint documentation doesn't work. I believe it should be updated to https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28#get-a-commit
A simple rename is technically backwards incompatible because users might be calling get_commit like get_commit(sha="deadbeef").
I'm interested in working on this, but would like guidance from the maintainers on what kind of a change/fix they'd be willing to accept before I dive into my editor. For example, is a backwards incompatible change (a simple rename of the argument) acceptable? If not, what about get_commit(self, ref: str="", *, sha: str="") with typing overloads (for type safety and improved IDE suggestions/autocomplete) and a runtime check that exactly one of ref/sha is provided? I'm open to other suggestions/ideas too.
Thanks!
Relevant source:
PyGithub/github/Repository.py
Lines 2396 to 2405 in 24305f6
GitHub's API endpoint documentation uses
ref, rather thansha, to reflect that the API accepts more than just commitshas (commits, branch names, and tags are all accepted), but PyGithub's method signature still usessha.This has caused me trouble with a service at work. A user provided my API a branch, rather than a commit sha, like the API endpoint expected. To my surprise,
get_commitaccepted the input (I expected a validation error due to the misleading naming). To be explicitly clear, the bug was in my application, notPyGithub, but the naming of this argument led me to believe the method would behave differently than it actually does.Additionally (and this is a much more minor concern imo), the link to GitHub's API endpoint documentation doesn't work. I believe it should be updated to https://docs.github.com/en/rest/commits/commits?apiVersion=2022-11-28#get-a-commit
A simple rename is technically backwards incompatible because users might be calling
get_commitlikeget_commit(sha="deadbeef").I'm interested in working on this, but would like guidance from the maintainers on what kind of a change/fix they'd be willing to accept before I dive into my editor. For example, is a backwards incompatible change (a simple rename of the argument) acceptable? If not, what about
get_commit(self, ref: str="", *, sha: str="")with typing overloads (for type safety and improved IDE suggestions/autocomplete) and a runtime check that exactly one of ref/sha is provided? I'm open to other suggestions/ideas too.Thanks!