--- name: "Net::GitHub::V3" section: "3pm" platform: "linux" package: "libnet-github-perl" version: "1.05-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Net::GitHub::V3" --- # Net::GitHub::V3(3pm) Github API v3 ## NAME Net::GitHub::V3 - Github API v3 ## SYNOPSIS Prefer: ``` use Net::GitHub; my $gh = Net::GitHub->new( version => 3, login => 'fayland', pass => 'mypass', # or # access_token => $oauth_token ); ``` Or: ``` use Net::GitHub::V3; my $gh = Net::GitHub::V3->new( login => 'fayland', pass => 'mypass', # or # access_token => $oauth_token ); ``` ## DESCRIPTION \ ### ATTRIBUTES *Authentication* There are two ways to authenticate through GitHub API v3: - login/pass ``` my $gh = Net::GitHub::V3->new( login => $ENV{GITHUB_USER}, pass => $ENV{GITHUB_PASS} ); ``` - access\_token ``` my $gh = Net::GitHub->new( access_token => $ENV{GITHUB_ACCESS_TOKEN} ); ``` *raw\_response* ``` my $gh = Net::GitHub->new( # login/pass or access_token raw_response => 1 ); ``` return raw HTTP::Response object *raw\_string* ``` my $gh = Net::GitHub->new( # login/pass or access_token raw_string => 1 ); ``` return HTTP::Response response content as string *api\_throttle* ``` my $gh = Net::GitHub->new( # login/pass or access_token api_throttle => 0 ); ``` To disable call rate limiting (e.g. if your account is whitelisted), set **api\_throttle** to 0. *RaiseError* By default, error responses are propagated to the user as they are received from the API. By switching **RaiseError** on you can make the be turned into exceptions instead, so that you don't have to check for error response after every call. *Iterating over pages: next\_url, last\_url, prev\_url, first\_url, per\_page* Any methods which return multiple results *may* be paginated. After performing a query you should check to see if there are more results. These attributes will be reset for each query. The predicates to check these attributes are `"has_next_page"`, `"has_last_page"`, `"has_prev_page"` and `"has_first_page"`. `"per_page"` defaults to 100. It will be applied to GET urls no matter it supports or not. See Github's documentation: \ ``` my @issues = $gh->issue->repos_issues; while ($gh->issue->has_next_page) { push @issues, $gh->issue->query($gh->issue->next_url); ## OR ## push @issues, $gh->issue->next_page; } ``` *Iterating over individual items: next\_xxx and close\_xxx* The queries which can return paginated results can also be evaluated one by one, like this: ``` while (my $issue = $gh->issue->next_repos_issue( @args )) { # do something with $issue } ``` The arguments to next\_repos\_issue are the same as for repos\_issues, and is also applicable to all other interfaces which offer a next\_xxx method. All available next\_xxx methods are listed in the documentation of the corresponding modules, see the list below. If you loop over the next\_xxx interfaces, new API calls will be performed automatically, but only when needed to fetch more items. An undefined return value means there are no more items. To start over with the first item, you need to close the iteration. Every next\_xxx method has a corresponding close\_xxx method which must be called with exactly the same parameters as the next\_xxx method to take effect: ``` $gh->issue->close_repos_issue(@args); ``` If you use Net::GitHub::V3 in a command line program, there is no need to call the close\_xxx methods at all. As soon as the Net::GitHub::V3 object `$gh` goes out of scope, everything is neatly cleaned up. However, if you have a long-lived Net::GitHub::V3 object, e.g. in a persistent service process which provides an own interface to its users and talks to GitHub under the hood, then it is advisable to close the iterations when you're done with them. For brevity and because they usually are not needed, the close\_xxx methods are not listed with their modules. It is guaranteed that *every* next\_xxx method has a corresponding close\_xxx method. *Alternate iterator over individual items:* If next\_xxx and close\_xxx methods are not available for your pagination method you can use a generic iterator using the `"iterate"` helper. ``` $gh->issues->iterate( 'repos_issues', [ @args ], sub { my $issue = shift; ... # do something with $issue return 1; # if you want to continue iterating return; # when you want to interrupt the iteration process } ); ``` *ua* To set the proxy for ua, you can do something like following ``` $gh->ua->proxy('https', 'socks://127.0.0.1:9050'); ``` `$gh`-\>ua is an instance of LWP::UserAgent ### METHODS *query($method, $url, $data)* ``` my $data = $gh->query('/user'); $gh->query('PATCH', '/user', $data); $gh->query('DELETE', '/user/emails', [ 'myemail@somewhere.com' ]); ``` query API directly *next\_page* When the results have been paginated, `"next_page"` is sugar for the common case of iterating through all the pages in order. It simply calls `"query"` with the `"next_url"`. *set\_default\_user\_repo* ``` $gh->set_default_user_repo('fayland', 'perl-net-github'); # take effects for all $gh-> $gh->repos->set_default_user_repo('fayland', 'perl-net-github'); # take effects on $gh->repos ``` **To ease the keyboard, we provided two ways to call any method which starts with :user/:repo** 1\. SET user/repos before call methods below ``` $gh->set_default_user_repo('fayland', 'perl-net-github'); my @contributors = $gh->repos->contributors; ``` 2\. If it is just for once, we can pass :user, :repo before any arguments ``` my @contributors = $repos->contributors($user, $repo); ``` ### MODULES *user* ``` my $user = $gh->user->show('nothingmuch'); $gh->user->update( bio => 'Just Another Perl Programmer' ); ``` Net::GitHub::V3::Users *repos* ``` my @repos = $gh->repos->list; my $rp = $gh->repos->create( { "name" => "Hello-World", "description" => "This is your first repo", "homepage" => "https://github.com" } ); ``` Net::GitHub::V3::Repos *issue* ``` my @issues = $gh->issue->issues(); my $issue = $gh->issue->issue($issue_number); ``` Net::GitHub::V3::Issues *pull\_request* ``` my @pulls = $gh->pull_request->pulls(); ``` Net::GitHub::V3::PullRequests *org* ``` my @orgs = $gh->org->orgs; ``` Net::GitHub::V3::Orgs *git\_data* Net::GitHub::V3::GitData *gist* Net::GitHub::V3::Gists *oauth* Net::GitHub::V3::OAuth *event* Net::GitHub::V3::Events *search* Net::GitHub::V3::Search ## SEE ALSO Pithub ## AUTHOR & COPYRIGHT & LICENSE Refer Net::GitHub