The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Async-Github-0.013
River stage zero No dependents
++
/ Net::Async::Github

NAME

Net::Async::Github - support for the https://github.com REST API with IO::Async

SYNOPSIS

 use IO::Async::Loop;
 use Net::Async::Github;
 my $loop = IO::Async::Loop->new;
 $loop->add(
  my $gh = Net::Async::Github->new(
   token => '...',
  )
 );
 # Give 'secret_team' pull access to all private repos
 $gh->repos(visibility => 'private')
    ->grant_team(secret_team => 'pull')
    ->await;

DESCRIPTION

This is a basic wrapper for Github's API.

METHODS

current_user

Returns information about the current user.

 my $user = $gh->current_user->get;
 printf "User [%s] has %d public repos and was last updated on %s%s\n",
  $user->login, $user->public_repos, $user->updated_at->to_string

Resolves to a Net::Async::Github::User instance.

configure

Accepts the following optional named parameters:

  • token - the Github API token

  • endpoints - hashref of RFC6570-compliant URL mappings

  • http - an HTTP client compatible with the Net::Async::HTTP API

  • mime_type - the MIME type to use as the Accept header for requests

  • page_cache_size - number of GET responses to cache. Defaults to 1000, set to 0 to disable.

  • timeout - How long in seconds to wait before giving up on a request. Defaults to 60. If set to 0, then no timeout will take place.

You probably just want token, defaults should be fine for the other settings.

If you're creating a large number of instances, you can avoid some disk access overhead by passing endpoints from an existing instance to the constructor for a new instance.

reopen

Reopens the given PR.

Expects the following named parameters:

  • owner - which user or organisation owns this PR

  • repo - which repo it's for

  • id - the pull request ID

Resolves to the current status.

pull_request

Returns information about the given PR.

Expects the following named parameters:

  • owner - which user or organisation owns this PR

  • repo - which repo it's for

  • id - the pull request ID

Resolves to the current status.

pull_requests

Returns information of all PRs of given repository.

Expects the following named parameters:

  • owner - which user or organisation owns this PR

  • repo - the repository this pull request is for

Returns a Ryu::Source instance, this will emit a Net::Async::Github::PullRequest instance for each found repository.

create_branch

Creates a new branch.

Takes the following named parameters:

  • owner - which organisation owns the target repository

  • repo - the repository to raise the PR against

  • branch - new branch name that will be created

  • sha - the SHA1 value for this branch

update_ref

Update a reference to a new commit

Takes the following named parameters:

  • owner - which organisation owns the target repository

  • repo - the repository to raise the PR against

  • ref - ref name that we are updating.

  • sha - the SHA1 value of comment that the ref will point to

  • force - force update ref even if it is not fast-forward if it is true.

create_pr

Creates a new pull request.

Takes the following named parameters:

  • owner - which organisation owns the target repository

  • repo - the repository to raise the PR against

  • head - head commit starting point, typically the latest commit on your fork's branch

  • base - base commit this PR applies changes to typically you'd want the target repo master

create_commit

Creates an empty commit. Can be used to simulate git commit --allow-empty or to create a merge commit from multiple heads.

Takes the following named parameters:

  • owner - which organisation owns the target repository

  • repo - the repository to raise the PR against

  • message - The commit message

  • tree - The SHA of tree object that commit will point to

  • parents - Arrayref that include the parents of the commit

user

Returns information about the given user.

users

Iterates through all users. This is a good way to exhaust your 5000-query ratelimiting quota.

Identifies the head version for this branch.

Requires the following named parameters:

  • owner - which organisation or person owns the repo

  • repo - the repository name

  • branch - which branch to check

update

core_rate_limit

Returns a Net::Async::Github::RateLimit::Core instance which can track rate limits.

rate_limit

METHODS - Internal

The following methods are used internally. They're not expected to be useful for external callers.

api_key

token

endpoints

Returns an accessor for the endpoints data. This is a hashref containing URI templates, used by "endpoint".

endpoint

Expands the selected URI via URI::Template. Each item is defined in our endpoints.json file.

Returns a URI instance.

http

Accessor for the HTTP client object. Will load and instantiate a Net::Async::HTTP instance if necessary.

Actual HTTP implementation is not guaranteed, and the default is likely to change in future.

timeout

The parameter that will be used when create Net::Async::HTTP object. If it is undef, then a default value 60 seconds will be used. If it is 0, then Net::Async::HTTP will never timeout.

auth_info

Returns authentication information used in the HTTP request.

mime_type

Returns the MIME type used for requests. Currently defined by github in https://developer.github.com/v3/media/ as application/vnd.github.v3+json.

base_uri

The URI for requests. Defaults to https://api.github.com.

http_get

Performs an HTTP GET request.

pending_requests

A list of all pending requests.

validate_branch_name

Applies validation rules from git-check-ref-format for a branch name.

Will raise an exception on invalid input.

validate_owner_name

Applies github rules for user/organisation name.

Will raise an exception on invalid input.

validate_repo_name

Applies github rules for repository name.

Will raise an exception on invalid input.

validate_args

Convenience method to apply validation on common parameters.

page_cache_size

Returns the total number of GET responses we'll cache. Default is probably 1000.

page_cache

The page cache instance, likely to be provided by Cache::LRU.

ryu

Our Ryu::Async instance, used for instantiating Ryu::Source instances.

INHERITED METHODS

IO::Async::Notifier

add_child, adopt_future, adopted_futures, can_event, children, configure_unknown, debug_printf, get_loop, invoke_error, invoke_event, loop, make_event_cb, maybe_invoke_event, maybe_make_event_cb, new, notifier_name, parent, remove_child, remove_from_parent

AUTHOR

Tom Molesworth <TEAM@cpan.org>, with contributions from @chylli-binary.

LICENSE

Copyright Tom Molesworth 2014-2021. Licensed under the same terms as Perl itself.