You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A Pony library for interacting with the GitHub REST API. Provides typed models, HTTP request infrastructure, and Promise-based async results.
Contributing with an AI assistant
This is a Pony project. The ponylang org maintains a set of LLM coding skills. Get set up with them before contributing:
Not set up yet? Install them once:
git clone https://github.com/ponylang/llm-skills.git
cd llm-skills
python install.py
Already set up? Make sure you're on the latest. If you installed with the script above, git pull in the directory where you cloned llm-skills and the symlinked skills update automatically — if you set them up another way, refresh them however that setup expects.
make ssl=3.0.x # build + run unit tests + build examples
make unit-tests ssl=3.0.x # unit tests only
make test-one t=TestName ssl=3.0.x # run a single test by name
make examples ssl=3.0.x # build examples only
make clean # clean build artifacts + corral deps
make config=debug ssl=3.0.x # debug build
SSL version is required for all build/test targets. This machine has OpenSSL 3.x, so use ssl=3.0.x.
Uses corral for dependency management. make automatically runs corral fetch before compiling.
github.com/ponylang/web_link.git -- RFC 8288 Link header parsing
github.com/ponylang/uri.git -- RFC 6570 URI template expansion
Source Layout
assets/ -- Test certificates (self-signed cert.pem + key.pem from lori)
github_rest_api/
github.pony -- GitHub class (entry point, has get_repo, get_org_repos, gist operations)
repository.pony -- Repository model + GetRepository, GetRepositoryLabels
issue.pony -- Issue model + GetIssue, GetRepositoryIssues, IssueSort, SortDirection
issue_pull_request.pony -- IssuePullRequest model (PR metadata on issues)
pull_request.pony -- PullRequest model + GetPullRequest
pull_request_base.pony -- PullRequestBase model (head/base refs)
pull_request_file.pony -- PullRequestFile model + GetPullRequestFiles
commit.pony -- Commit model + GetCommit
commit_file.pony -- CommitFile model (sha, status, filename)
git_commit.pony -- GitCommit model (author, committer, message)
git_person.pony -- GitPerson model (name, email)
release.pony -- Release model + CreateRelease
asset.pony -- Asset model (release assets)
label.pony -- Label model + CreateLabel, DeleteLabel
issue_comment.pony -- IssueComment model + CreateIssueComment, GetIssueComments
gist.pony -- Gist model + 15 gist operations (CRUD, lists, forks, commits, star)
gist_file.pony -- GistFile model (file within a gist)
gist_file_update.pony -- GistFileEdit, GistFileRename, GistFileDelete for update operations
gist_commit.pony -- GistCommit + GistChangeStatus models
gist_comment.pony -- GistComment model + 5 comment operations (CRUD + list)
search.pony -- SearchIssues + SearchResults generic
user.pony -- User model
license.pony -- License model
json_nav_util.pony -- JsonNavUtil (string_or_none for nullable JSON fields)
paginated_list.pony -- PaginatedList[A] with prev/next page navigation, LinkedJsonRequester, LinkedResultReceiver
_extract_pagination_links.pony -- Extracts prev/next URLs from Link headers (via web_link)
_test_json_converters.pony -- Property-based tests for JSON converter primitives
_test_result_receivers.pony -- Async tests for result receiver actors
_test_mock_http_server.pony -- Mock HTTPS server infrastructure for request actor tests
_test_request_actors.pony -- Integration tests for all four request actor types
_test_search_and_pagination.pony -- Converter unit tests + mock HTTP pagination behavior tests
request/ -- HTTP request infrastructure (temporary home, intended to be extracted to its own library)
credentials.pony -- Credentials (lori.TCPConnectAuth + token + optional ssl_ctx), ResultReceiver
_ssl.pony -- SSLContextFactory (shared SSL context creation, fallback when Credentials.ssl_ctx is None)
json_requester.pony -- JsonRequester actor (GET/POST/PATCH with JSON response)
no_content_requester.pony -- NoContentRequester actor (DELETE/PUT expecting 204)
check_requester.pony -- CheckRequester actor (GET returning Bool: 204=true, 404=false)
request_error.pony -- RequestError (status, response_body, message)
json.pony -- JsonConverter interface, JsonTypeString utility
query_params.pony -- QueryParams (URL query string builder with percent-encoding)
_test.pony -- QueryParams tests (example + property-based)
_test.pony -- Test runner (pagination link extraction + delegates to subpackage tests)
Architecture
Request/Response Pattern
All API operations return Promise[(T | RequestError)]. The flow is:
Operation primitive (e.g., GetRepository) creates a Promise
Creates a ResultReceiver[T] actor with the promise and a JsonConverter[T]
Builds URL using ponylang/uri RFC 6570 template expansion for path parameters
Creates a short-lived request actor (JsonRequester / NoContentRequester / CheckRequester / LinkedJsonRequester) that owns an HTTPClientConnection from ponylang/courier
On success, JSON is parsed and converted to model via JsonConverter
Promise is fulfilled with either the model or a RequestError
OO Convenience API
Models have methods that chain to further API calls:
PaginatedList[A] wraps an array of results with prev_page() / next_page() methods that return (Promise | None). Pagination links are extracted from HTTP Link headers using the ponylang/web_link library (via _ExtractPaginationLinks). Used by GetRepositoryLabels, GetOrganizationRepositories, GetRepositoryIssues, SearchIssues, GetUserGists, GetPublicGists, GetStarredGists, GetUsernameGists, GetGistForks, GetGistCommits, and GetGistComments.
Auth
Credentials holds a lori.TCPConnectAuth, an optional token string, and an optional SSLContext val. When ssl_ctx is provided, request actors use it instead of the default SSLContextFactory. Each request actor sets User-Agent, Accept: application/vnd.github.v3+json, and Authorization: Bearer <token> headers.
Conventions
All models are class val (immutable, shareable)
JSON converters are primitives implementing JsonConverter[T] interface
Type aliases for result unions: RepositoryOrError, IssueOrError, etc.
Keep CLAUDE.md in sync when adding or changing features — update the source layout, OO convenience API, pagination section, and coverage table as part of the PR that introduces the change
Known TODOs in Code
None currently tracked.
GitHub REST API Coverage Comparison
What this library currently implements vs what GitHub's REST API offers.
Scope is limited to the API categories the library already touches plus
commonly-used categories that a GitHub API library would typically need.