Net::GitHub::V3(3pm)

✨ Net::GitHub::V3 — the Github API v3 glow-up ✨

okay bestie, sit DOWN. this is Net::GitHub::V3, a Perl module that talks to the Github API v3 and honestly? she's iconic. she's part of the Net::GitHub family (a User Contributed Perl Documentation situation, iykyk) and she is about to make your whole REST-calling life cute. 🎀

---

🌸 NAME 🌸

Net::GitHub::V3 — Github API v3. that's it, that's the name, short and slay. 💅

---

🦋 SYNOPSIS 🦋

okay so first things first: the docs literally say Prefer: this one, so like, listen to them:

use Net::GitHub;
my $gh = Net::GitHub->new(
    version => 3,
    login => 'fayland', pass => 'mypass',
    # or
    # access_token => $oauth_token
);

Or: if you're feeling direct, you can go straight to the module itself:

use Net::GitHub::V3;
my $gh = Net::GitHub::V3->new(
    login => 'fayland', pass => 'mypass',
    # or
    # access_token => $oauth_token
);

both are valid, no gatekeeping here 💖

---

🌈 DESCRIPTION 🌈

the whole vibe is documented over at <http://developer.github.com/v3/> — go peek, it's the source of truth. 👑

🫶 ATTRIBUTES 🫶

💜 Authentication

bestie, there are exactly two ways to authenticate through the 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} );

pick your fighter. either way you're in. ✨

💜 raw_response

my $gh = Net::GitHub->new(
    # login/pass or access_token
    raw_response => 1
);

this one hands you back a raw HTTP::Response object. like, the whole thing. unprocessed. raw. 🫣

💜 raw_string

my $gh = Net::GitHub->new(
    # login/pass or access_token
    raw_string => 1
);

and this one returns the HTTP::Response response content as a string. simple. clean. a vibe.

💜 api_throttle

my $gh = Net::GitHub->new(
    # login/pass or access_token
    api_throttle => 0
);

so the tea here: if your account is whitelisted and you wanna disable call rate limiting, you set api_throttle to 0. periodt. 🔥

💜 RaiseError

by default, error responses just get propagated to you as they arrive from the API — no drama, just vibes. but if you switch RaiseError on, those errors get turned into exceptions instead, which means you don't have to sit there checking for an error response after literally every single call. it's giving self-care, honestly. 💅

💜 Iterating over pages: next_url, last_url, prev_url, first_url, per_page

any method that returns multiple results may be paginated. after you run a query, you should check whether there are more results waiting for you. these attributes get reset for each query, so don't get attached. 🦋

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. and listen — it will be applied to GET urls no matter whether the url supports it or not. she does not ask permission. 😭

Github's own docs on this: <http://developer.github.com/v3/#pagination>

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

queries that 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 you pass to next_repos_issue are the exact same as for repos_issues, and this works for all the other interfaces that offer a next_xxx method too. all the available next_xxx methods are listed in the documentation of their corresponding modules — check the list further down. 👇

if you loop over the next_xxx interfaces, new API calls happen automatically, but only when needed to fetch more items. and an undefined return value means there are no more items. that's it, that's the end, bye. 👋

to start over from the first item, you need to close the iteration. every next_xxx method has a matching close_xxx method, and it must be called with exactly the same parameters as the next_xxx method for it to actually take effect:

$gh->issue->close_repos_issue(@args);

if you're using Net::GitHub::V3 in a command line program, you genuinely don't need to call the close_xxx methods at all. the moment the Net::GitHub::V3 object $gh goes out of scope, everything gets neatly cleaned up. she handles it. 🧚

However — and this is the important bit — if you have a long-lived Net::GitHub::V3 object, like in a persistent service process that provides its own interface to its users and talks to GitHub under the hood, then it's advisable to close the iterations when you're done with them. please. for her. 🥺

for brevity, and because they're usually not needed, the close_xxx methods are not listed with their modules. but it is guaranteed that every next_xxx method has a corresponding close_xxx method. no cap. 🫶

💜 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 with 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
} );

flexible, iconic, we love her. ✨

💜 ua

to set the proxy for ua, you can do something like this:

$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' ]);

this queries the API directly. no middleman, just you and the endpoint. 🔥

💖 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. easy, breezy. 🌸

💖 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 (bestie, your wrists deserve better 💜), there are two ways to call any method that 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 — another one, go look 👀

---

💀 AUTHOR & COPYRIGHT & LICENSE 💀

Refer Net::GitHub — that's where all the credit lives, bestie. 💖

---

and that's the whole page!! this doc shipped as perl v5.36.0, dated 2022-10-08, from the Net::GitHub::V3(3pm) manual page. go forth and query responsibly, you absolute main character. 🫶✨🎀