Module: Octokit::Client::Users

Included in:
Octokit::Client
Defined in:
lib/octokit/client/users.rb

Overview

Methods for the Users API

See Also:

Instance Method Summary collapse

Instance Method Details

#add_email(email, options = {}) ⇒ Array<String>

Add email address to user.

Requires authenticated client.

Examples:

@client.add_email('[email protected]')

Parameters:

  • email (String) —

    Email address to add to the user.

Returns:

  • (Array<String>) —

    Array of all email addresses of the user.

See Also:



321
322
323
324
 
# File 'lib/octokit/client/users.rb', line 321

def add_email(email, options = {})
  email = Array(email)
  post "user/emails", email
end

#add_key(title, key, options = {}) ⇒ Sawyer::Resource

Add public key to user account.

Requires authenticated client.

Examples:

@client.add_key('Personal projects key', 'ssh-rsa AAA...')

Parameters:

  • title (String) —

    Title to give reference to the public key.

  • key (String) —

    Public key.

Returns:

  • (Sawyer::Resource) —

    Hash representing the newly added public key.

See Also:



267
268
269
 
# File 'lib/octokit/client/users.rb', line 267

def add_key(title, key, options = {})
  post "user/keys", options.merge({:title => title, :key => key})
end

#all_users(options = {}) ⇒ Array<Sawyer::Resource>

List all GitHub users

This provides a dump of every user, in the order that they signed up for GitHub.

Parameters:

  • options (Hash) (defaults to: {}) —

    Optional options.

Options Hash (options):

  • :since (Integer) —

    The integer ID of the last User that you’ve seen.

Returns:

  • (Array<Sawyer::Resource>) —

    List of GitHub users.

See Also:



21
22
23
 
# File 'lib/octokit/client/users.rb', line 21

def all_users(options = {})
  paginate "users", options
end

#emails(options = {}) ⇒ Array<String>

List email addresses for a user.

Requires authenticated client.

Examples:

@client.emails

Returns:

  • (Array<String>) —

    Array of email addresses.

See Also:



308
309
310
 
# File 'lib/octokit/client/users.rb', line 308

def emails(options = {})
  paginate "user/emails", options
end

#exchange_code_for_token(code, app_id = client_id, app_secret = client_secret, options = {}) ⇒ Sawyer::Resource

Retrieve the access_token.

Examples:

Octokit.exchange_code_for_token('aaaa', 'xxxx', 'yyyy', {:accept => 'application/json'})

Parameters:

  • code (String) —

    Authorization code generated by GitHub.

  • app_id (String) (defaults to: client_id) —

    Client Id we received when our application was registered with GitHub.

  • app_secret (String) (defaults to: client_secret) —

    Client Secret we received when our application was registered with GitHub.

Returns:

  • (Sawyer::Resource) —

    Hash holding the access token.

See Also:



50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/octokit/client/users.rb', line 50

def exchange_code_for_token(code, app_id = client_id, app_secret = client_secret, options = {})
  options.merge!({
    :code => code,
    :client_id => app_id,
    :client_secret => app_secret,
    :headers => {
      :content_type => 'application/json',
      :accept       => 'application/json'
    }
  })
  post "#{web_endpoint}login/oauth/access_token", options
end

#follow(user, options = {}) ⇒ Boolean

Follow a user.

Requires authenticatied client.

Examples:

@client.follow('holman')

Parameters:

  • user (String) —

    Username of the user to follow.

Returns:

  • (Boolean) —

    True if follow was successful, false otherwise.

See Also:



152
153
154
 
# File 'lib/octokit/client/users.rb', line 152

def follow(user, options = {})
  boolean_from_response :put, "user/following/#{user}", options
end

#followers(user = login, options = {}) ⇒ Array<Sawyer::Resource>

Get a user’s followers.

Examples:

Octokit.followers('pengwynn')

Parameters:

  • user (String) (defaults to: login) —

    Username of the user whose list of followers you are getting.

Returns:

  • (Array<Sawyer::Resource>) —

    Array of hashes representing users followers.

See Also:



100
101
102
 
# File 'lib/octokit/client/users.rb', line 100

def followers(user=, options = {})
  paginate "users/#{user}/followers", options
end

#following(user = login, options = {}) ⇒ Array<Sawyer::Resource>

Get list of users a user is following.

Examples:

Octokit.following('pengwynn')

Parameters:

  • user (String) (defaults to: login) —

    Username of the user who you are getting the list of the people they follow.

Returns:

  • (Array<Sawyer::Resource>) —

    Array of hashes representing users a user is following.

See Also:



111
112
113
 
# File 'lib/octokit/client/users.rb', line 111

def following(user=, options = {})
  paginate "users/#{user}/following", options
end

#follows?(target) ⇒ Boolean #follows?(user, target) ⇒ Boolean

Check if you are following a user. Alternatively, check if a given user is following a target user.

Requries an authenticated client.

Examples:

@client.follows?('pengwynn')
@client.follows?('catsby', 'pengwynn')

Overloads:

  • #follows?(target) ⇒ Boolean

    Parameters:

    • target (String) —

      Username of the user that you want to check if you are following.

  • #follows?(user, target) ⇒ Boolean

    Parameters:

    • user (String) —

      Username of first user

    • target (String) —

      Username of the target user

Returns:

  • (Boolean) —

    True following target user, false otherwise.

See Also:



132
133
134
135
136
137
138
139
140
141
 
# File 'lib/octokit/client/users.rb', line 132

def follows?(*args)
  target = args.pop
  user = args.first
  if user.nil?
    url = "user/following/#{target}"
  else
    url = "users/#{user}/following/#{target}"
  end
  boolean_from_response :get, url
end

#key(key_id, options = {}) ⇒ Sawyer::Resource

Get a public key.

Note, when using dot notation to retrieve the values, ruby will return the hash key for the public keys value instead of the actual value, use symbol or key string to retrieve the value. See example.

Requires authenticated client.

Examples:

@client.key(1)

Retrieve public key contents

public_key = @client.key(1)
public_key.key
# => Error

public_key[:key]
# => "ssh-rsa AAA..."

public_key['key']
# => "ssh-rsa AAA..."

Parameters:

  • key_id (Integer) —

    Key to retreive.

Returns:

  • (Sawyer::Resource) —

    Hash representing the key.

See Also:



228
229
230
 
# File 'lib/octokit/client/users.rb', line 228

def key(key_id, options = {})
  get "user/keys/#{key_id}", options
end

#keys(options = {}) ⇒ Array<Sawyer::Resource>

Get list of public keys for user.

Requires authenticated client.

Examples:

@client.keys

Returns:

  • (Array<Sawyer::Resource>) —

    Array of hashes representing public keys.

See Also:



240
241
242
 
# File 'lib/octokit/client/users.rb', line 240

def keys(options = {})
  paginate "user/keys", options
end

#remove_email(email) ⇒ Array<String>

Remove email from user.

Requires authenticated client.

Examples:

@client.remove_email('[email protected]')

Parameters:

  • email (String) —

    Email address to remove.

Returns:

  • (Array<String>) —

    Array of all email addresses of the user.

See Also:



335
336
337
338
 
# File 'lib/octokit/client/users.rb', line 335

def remove_email(email)
  email = Array(email)
  boolean_from_response :delete, "user/emails", email
end

#remove_key(id, options = {}) ⇒ Boolean

Remove a public key from user account.

Requires authenticated client.

Examples:

@client.remove_key(1)

Parameters:

  • id (String) —

    Id of the public key to remove.

Returns:

  • (Boolean) —

    True if removal was successful, false otherwise.

See Also:



296
297
298
 
# File 'lib/octokit/client/users.rb', line 296

def remove_key(id, options = {})
  boolean_from_response :delete, "user/keys/#{id}", options
end

#starred(user = login, options = {}) ⇒ Array<Sawyer::Resource>

Get list of repos starred by a user.

Examples:

Octokit.starred('pengwynn')

Parameters:

  • user (String) (defaults to: login) —

    Username of the user to get the list of their starred repositories.

  • options (Hash) (defaults to: {}) —

    Optional options

Options Hash (options):

  • :sort (String) — default: created —

    Sort: created or updated.

  • :direction (String) — default: desc —

    Direction: asc or desc.

Returns:

  • (Array<Sawyer::Resource>) —

    Array of hashes representing repositories starred by user.

See Also:



179
180
181
182
 
# File 'lib/octokit/client/users.rb', line 179

def starred(user=, options = {})
  path = user_authenticated? ? "user/starred" : "users/#{user}/starred"
  paginate path, options
end

#starred?(*args) ⇒ Boolean

Check if you are starring a repo.

Requires authenticated client.

Examples:

@client.starred?('pengwynn/octokit')
@client.starred?('pengwynn', 'octokit') # deprecated

Parameters:

  • args (String, Hash, Repository) —

    A GitHub repository

Returns:

  • (Boolean) —

    True if you are following the repo, false otherwise.

See Also:



194
195
196
197
198
199
200
201
202
203
 
# File 'lib/octokit/client/users.rb', line 194

def starred?(*args)
  arguments = Octokit::Arguments.new(args)
  options = arguments.options
  name = name_with_owner = arguments.shift
  if repo = arguments.shift
    name_with_owner = "#{name}/#{repo}"
    warn "`.starred?('#{name}', '#{repo}')` is deprecated. Please use `.starred?('#{name_with_owner}')` instead."
  end
  boolean_from_response :get, "user/starred/#{Repository.new name_with_owner}", options
end

#subscriptions(user = login, options = {}) ⇒ Array<Sawyer::Resource> Also known as: watched

List repositories being watched by a user.

Examples:

@client.subscriptions("pengwynn")

Parameters:

  • user (String) (defaults to: login) —

    User’s GitHub username.

Returns:

  • (Array<Sawyer::Resource>) —

    Array of repositories.

See Also:



350
351
352
353
 
# File 'lib/octokit/client/users.rb', line 350

def subscriptions(user=, options = {})
  path = user_authenticated? ? "user/subscriptions" : "users/#{user}/subscriptions"
  paginate path, options
end

#unfollow(user, options = {}) ⇒ Boolean

Unfollow a user.

Requires authenticated client.

Examples:

@client.unfollow('holman')

Parameters:

  • user (String) —

    Username of the user to unfollow.

Returns:

  • (Boolean) —

    True if unfollow was successful, false otherwise.

See Also:



165
166
167
 
# File 'lib/octokit/client/users.rb', line 165

def unfollow(user, options = {})
  boolean_from_response :delete, "user/following/#{user}", options
end

#update_key(key_id, options = {}) ⇒ Sawyer::Resource

Update a public key

Requires authenticated client

Examples:

@client.update_key(1, :title => 'new title', :key => "ssh-rsa BBB")

Parameters:

  • key_id (Integer) —

    Id of key to update.

  • options (Hash) (defaults to: {}) —

    Hash containing attributes to update.

Options Hash (options):

  • :title (String)
  • :key (String)

Returns:

  • (Sawyer::Resource) —

    Hash representing the updated public key.

See Also:



283
284
285
 
# File 'lib/octokit/client/users.rb', line 283

def update_key(key_id, options = {})
  patch "user/keys/#{key_id}", options
end

#update_user(options) ⇒ Sawyer::Resource

Update the authenticated user

Examples:

Octokit.update_user(:name => "Erik Michaels-Ober", :email => "[email protected]", :company => "Code for America", :location => "San Francisco", :hireable => false)

Parameters:

  • options (Hash) —

    A customizable set of options.

Options Hash (options):

  • :name (String)
  • :email (String) —

    Publically visible email address.

  • :blog (String)
  • :company (String)
  • :location (String)
  • :hireable (Boolean)
  • :bio (String)

Returns:

  • (Sawyer::Resource)

See Also:



89
90
91
 
# File 'lib/octokit/client/users.rb', line 89

def update_user(options)
  patch "user", options
end

#user(user = nil, options = {}) ⇒ Sawyer::Resource

Get a single user

Examples:

Octokit.user("sferik")

Parameters:

  • user (String) (defaults to: nil) —

    A GitHub user name.

Returns:

  • (Sawyer::Resource)

See Also:



33
34
35
36
37
38
39
 
# File 'lib/octokit/client/users.rb', line 33

def user(user=nil, options = {})
  if user
    get "users/#{user}", options
  else
    get 'user', options
  end
end

#user_keys(user, options = {}) ⇒ Array<Sawyer::Resource>

Get list of public keys for user.

Requires authenticated client.

Examples:

@client.user_keys('pengwynn'

Returns:

  • (Array<Sawyer::Resource>) —

    Array of hashes representing public keys.

See Also:



252
253
254
255
 
# File 'lib/octokit/client/users.rb', line 252

def user_keys(user, options = {})
  # TODO: Roll this into .keys
  paginate "users/#{user}/keys", options
end

#validate_credentials(options = {}) ⇒ Boolean

Validate user username and password

Parameters:

  • options (Hash) (defaults to: {}) —

    User credentials

Options Hash (options):

  • :login (String) —

    GitHub login

  • :password (String) —

    GitHub password

Returns:

  • (Boolean) —

    True if credentials are valid



69
70
71
72
73
 
# File 'lib/octokit/client/users.rb', line 69

def validate_credentials(options = {})
  !self.class.new(options).user.nil?
rescue Octokit::Unauthorized
  false
end