API Reference¶

Parsing¶

This is the parsing aspect of GitHub.com URLs and shorthands.

GitHub’s api schema for (supported) types are the following:

Issue: /{owner}/{repo}/issues/{issue_number}
Pull Request: /{owner}/{repo}/pull/{pr_number}
Branch/Tag/Commit: /{owner}/{repo}/tree/{ref}
Discussion: /{owner}/{repo}/discussions/{discussion_number}
Tag: /{owner}/{repo}/releases/tag/{tag}

In addition, issues, pull requests, and commits support comments:

Issue Comment: /{owner}/{repo}/issues/{issue_number}#issuecomment-{comment_id}
Pull Request Comment: /{owner}/{repo}/pull/{pr_number}#issuecomment-{comment_id}
Discussion Comment: /{owner}/{repo}/discussions/{discussion_number}#discussioncomment-{comment_id}
Commit Comment: /{owner}/{repo}/commit/{commit_sha}#commitcomment-{comment_id}

Issues and pull requests also support events:

Issue Event: /{owner}/{repo}/issues/{issue_number}#event-{event_id}
Pull Request Event: /{owner}/{repo}/pull/{pr_number}#event-{event_id}

Pull Requests support reviews and review comments:

Review: /{owner}/{repo}/pull/{pr_number}#pullrequestreview-3373902296
Review comments: /{owner}/{repo}/pull/{pr_number}#discussion_r2269233870

ghretos.parsing.parse_shorthand(shorthand: str, *, allow_optional_user: bool = False, settings: MatcherSettings = MatcherSettings(domains=['github.com', 'www.github.com'], issues=True, issue_comments=True, issue_events=True, pull_requests=True, pull_request_comments=True, pull_request_reviews=True, pull_request_review_comments=True, pull_request_events=True, discussions=True, discussion_comments=True, commits=True, commit_comments=True, releases=True, shorthand=True, short_repo=True, short_numberables=True, short_refs=True, short_bare_username=False, require_strict_type=True)) → GitHubResource | None¶

Parses a shorthand notation for a GitHub resource.

Examples of supported shorthand: - user/repo - user/repo#issue_number - user/repo@ref (can be sha, branch, or tag)

If the user is omitted, default_user is used if provided to enable the following shorthand: - repo#issue_number - repo@ref (can be sha, branch, or tag)

When allow_optional_user is False, the user must be provided. If allow_optional_user is True, returned repos will have an empty string in the User field.

No requests are made to GitHub; this is purely syntactic parsing. No validation is performed on the parsed values, they are simply returned as-is.

ghretos.parsing.parse_url(url: str | URL, *, settings: MatcherSettings = MatcherSettings(domains=['github.com', 'www.github.com'], issues=True, issue_comments=True, issue_events=True, pull_requests=True, pull_request_comments=True, pull_request_reviews=True, pull_request_review_comments=True, pull_request_events=True, discussions=True, discussion_comments=True, commits=True, commit_comments=True, releases=True, shorthand=True, short_repo=True, short_numberables=True, short_refs=True, short_bare_username=False, require_strict_type=True)) → GitHubResource | None¶

Parses a GitHub URL into its corresponding resource.

Please note that PullRequests are a type of Issue in GitHub’s data model, and are represented as such in the API. This method still distinguishes them for clarity.

Note

Unlike parse_shorthand, this method returns a separate PullRequest type for pull requests. However, since pull requests are represented as issues in GitHub’s data model and API, this distinction is primarily for clarity. In addition, unsanitized input URLs may lead to unexpected results. Do not assume a PullRequest actually refers to a pull request.

Args:: url: The URL to parse. settings: MatcherSettings for the URL matcher.
Returns:: A ParsedResource instance if the URL corresponds to a known GitHub resource, None otherwise.

Models¶

class ghretos.models.Commit(*, repo: Repo, sha: str)¶

Represents a GitHub commit.

repo: Repo¶: The repository the commit belongs to.

sha: str¶: The SHA of the commit.

class ghretos.models.CommitComment(*, repo: Repo, sha: str, comment_id: int)¶

Represents a comment on a GitHub commit.

comment_id: int¶: The ID of the comment.

repo: Repo¶: The repository the commit belongs to.

sha: str¶: The SHA of the commit.

class ghretos.models.Discussion(*, repo: Repo, number: int)¶

Represents a GitHub discussion.

number: int¶: The number of the discussion.

repo: Repo¶: The repository the discussion belongs to.

class ghretos.models.DiscussionComment(*, repo: Repo, number: int, comment_id: int)¶

Represents a comment on a GitHub discussion.

comment_id: int¶: The ID of the comment.

number: int¶: The number of the discussion.

repo: Repo¶: The repository the discussion belongs to.

class ghretos.models.GitHubResource¶: Base class for all GitHub resources.

class ghretos.models.Issue(*, repo: Repo, number: int)¶

Represents a GitHub issue.

number: int¶: The number of the issue.

repo: Repo¶: The repository the issue belongs to.

class ghretos.models.IssueComment(*, repo: ghretos.models.Repo, number: int, comment_id: int)¶

comment_id: int¶: The ID of the comment.

number: int¶: The number of the issue.

repo: Repo¶: The repository the issue belongs to.

class ghretos.models.IssueEvent(*, repo: ghretos.models.Repo, number: int, event_id: int)¶

event_id: int¶: The ID of the event.

number: int¶: The number of the issue.

repo: Repo¶: The repository the issue belongs to.

class ghretos.models.MatcherSettings(domains: list[str] = <factory>, issues: bool = True, issue_comments: bool = True, issue_events: bool = True, pull_requests: bool = True, pull_request_comments: bool = True, pull_request_reviews: bool = True, pull_request_review_comments: bool = True, pull_request_events: bool = True, discussions: bool = True, discussion_comments: bool = True, commits: bool = True, commit_comments: bool = True, releases: bool = True, shorthand: bool = True, short_repo: bool = True, short_numberables: bool = True, short_refs: bool = True, short_bare_username: bool = False, require_strict_type: bool = True)¶

Settings for matching GitHub URLs and shorthands.

Each of these settings are completely seperate: disabling one does not affect the others. For example, disabling issues will not disable issue_comments.

commit_comments: bool = True¶: Whether to match /owner/repo/commit/{sha}#commitcomment-{number} commit comment URLs.

commits: bool = True¶: Whether to match /owner/repo/commit/{sha} URLs.

discussion_comments: bool = True¶: Whether to match /owner/repo/discussions/{number}#discussioncomment-{number} discussion comment URLs.

discussions: bool = True¶: Whether to match /owner/repo/discussions/{number} URLs.

domains: list[str]¶: List of domains to consider as GitHub domains.

issue_comments: bool = True¶: Whether to match /owner/repo/issues/{number}#issuecomment-{number} issue comment URLs.

issue_events: bool = True¶: Whether to match /owner/repo/issues/{number}#event-{number} issue event URLs.

issues: bool = True¶: Whether to match /owner/repo/issues/{number} URLs.

classmethod none() → Self¶: Return a MatcherSettings instance with all resource types disabled.

pull_request_comments: bool = True¶: Whether to match /owner/repo/pull/{number}#issuecomment-{number} pull request comment URLs.

pull_request_events: bool = True¶: Whether to match /owner/repo/pull/{number}#event-{number} pull request event URLs.

pull_request_review_comments: bool = True¶: Whether to match /owner/repo/pull/{number}#pullrequestreviewcomment-{number} pull request review comment URLs.

pull_request_reviews: bool = True¶: Whether to match /owner/repo/pull/{number}#review-{number} pull request review URLs.

pull_requests: bool = True¶: Whether to match /owner/repo/pull/{number} URLs.

releases: bool = True¶: Whether to match /owner/repo/releases/tag/{tag} URLs.

require_strict_type: bool = True¶: Whether to support /issues/, /pulls/, and /discussions/ only for their respective types. If this is False, issues, pulls, and discussions will be ignored if the fragment indicates a type only supported by another resource.

short_bare_username: bool = False¶: Whether to support bare short username notation. e.g., username to refer to a user. This is disabled by default to prevent false positives.

short_numberables: bool = True¶: Whether to support shorthand notations such as owner/repo#number.

short_refs: bool = True¶: Whether to support shorthand notations such as owner/repo@ref.

short_repo: bool = True¶: Whether to support short repository names in shorthands (e.g., repo#number).

shorthand: bool = True¶: Whether to match shorthand notations like owner/repo#number. UNLIKE other setting, this is required to enable shorthand parsing.

class ghretos.models.NumberedResource(*, repo: Repo, number: int)¶

Special base class for resources with numbers.

This is used for shorthand parsing for numbered resources, where the specific type is not known.

This can represent either a Issue, PullRequest, or Discussion.

number: int¶: The number of the resource.

repo: Repo¶: The repository the resource belongs to.

class ghretos.models.PullRequest(*, repo: Repo, number: int)¶

Represents a GitHub pull request.

number: int¶: The number of the pull request.

repo: Repo¶: The repository the pull request belongs to.

class ghretos.models.PullRequestComment(*, repo: Repo, number: int, comment_id: int)¶

Represents a comment on a GitHub pull request.

comment_id: int¶: The ID of the comment.

number: int¶: The number of the pull request.

repo: Repo¶: The repository the pull request belongs to.

class ghretos.models.PullRequestEvent(*, repo: Repo, number: int, event_id: int)¶

Represents an event on a GitHub pull request.

event_id: int¶: The ID of the event.

number: int¶: The number of the pull request.

repo: Repo¶: The repository the pull request belongs to.

class ghretos.models.PullRequestReview(*, repo: Repo, number: int, review_id: int)¶

Represents a review on a GitHub pull request.

number: int¶: The number of the pull request.

repo: Repo¶: The repository the pull request belongs to.

review_id: int¶: The ID of the review.

class ghretos.models.PullRequestReviewComment(*, repo: Repo, number: int, comment_id: int, sha: str | None = None, commit_page: bool = False, files_page: bool = False)¶

Represents a review comment on a GitHub pull request.

comment_id: int¶: The ID of the review comment.

commit_page: bool = False¶: Whether the comment was found on a commit page.

files_page: bool = False¶: Whether the comment was found on the files page.

number: int¶: The number of the pull request.

repo: Repo¶: The repository the pull request belongs to.

sha: str | None = None¶: The SHA of the commit the comment is on, if applicable.

class ghretos.models.ReleaseTag(*, repo: Repo, tag: str)¶

Represents a GitHub release tag.

repo: Repo¶: The repository the release belongs to.

tag: str¶: The tag associated with this release.

class ghretos.models.Repo(*, name: str, owner: str)¶

property full_name: str¶: Return the full name of the repository in the format ‘owner/name’.

property html_url: str¶: Return the HTML URL of the repository. Note this only supports GitHub.com for now.

API Reference¶

Parsing¶

Models¶

ghretos

Navigation

Related Topics