User

This part of the documentation covers:

None of these objects should ever be instantiated by the user (developer).

When listing users, GitHub only sends a handful of the object’s attributes. To retrieve all of the object’s attributes, you must call the refresh() method. This unfortunately requires another call to the API, so use it sparingly if you have a low limit

User Modules

class github3.users.User(json, session)

Object for the full representation of a User.

GitHub’s API returns different amounts of information about users based upon how that information is retrieved. This object exists to represent the full amount of information returned for a specific user. For example, you would receive this class when calling user(). To provide a clear distinction between the types of users, github3.py uses different classes with different sets of attributes.

This object no longer contains information about the currently authenticated user (e.g., me()).

Changed in version 1.0.0.

This object contains all of the attributes available on ShortUser as well as the following:

bio

The markdown formatted User’s biography

blog

The URL of the user’s blog

company

The name or GitHub handle of the user’s company

created_at

A parsed datetime object representing the date the user was created

email

The email address the user has on their public profile page

followers_count

The number of followers of this user

following_count

The number of users this user follows

hireable

Whether or not the user has opted into GitHub jobs advertising

location

The location specified by the user on their public profile

name

The name specified by their user on their public profile

public_gists_count

The number of public gists owned by this user

updated_at

A parsed datetime object representing the date the user was last updated

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())
Returns:this object’s attributes serialized to a dictionary
Return type:dict
as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())
Returns:this object’s attributes as a JSON string
Return type:str
delete()

Delete the user.

Per GitHub API documentation, it is often preferable to suspend the user.

Note

This is only available for admins of a GitHub Enterprise instance.

Returns:bool – True if successful, False otherwise
demote()

Demote a site administrator to simple user.

You can demote any user account except your own.

This is only available for admins of a GitHub Enterprise instance.

Returns:bool – True if successful, False otherwise
events(public=False, number=-1, etag=None)

Iterate over events performed by this user.

Parameters:
  • public (bool) – (optional), only list public events for the authenticated user
  • number (int) – (optional), number of events to return. Default: -1 returns all available events.
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Events

followers(number=-1, etag=None)

Iterate over the followers of this user.

Parameters:
  • number (int) – (optional), number of followers to return. Default: -1 returns all available
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Users

following(number=-1, etag=None)

Iterate over the users being followed by this user.

Parameters:
  • number (int) – (optional), number of users to return. Default: -1 returns all available users
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Users

from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

impersonate(scopes=None)

Obtain an impersonation token for the user.

The retrieved token will allow impersonation of the user. This is only available for admins of a GitHub Enterprise instance.

Parameters:scopes (list) – (optional), areas you want this token to apply to, i.e., ‘gist’, ‘user’
Returns:Authorization
is_assignee_on(username, repository)

Check if this user can be assigned to issues on username/repository.

Parameters:
  • username (str) – owner’s username of the repository
  • repository (str) – name of the repository
Returns:

True if the use can be assigned, False otherwise

Return type:

bool

is_following(username)

Check if this user is following username.

Parameters:username (str) – (required)
Returns:bool
keys(number=-1, etag=None)

Iterate over the public keys of this user.

New in version 0.5.

Parameters:
  • number (int) – (optional), number of keys to return. Default: -1 returns all available keys
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Keys

new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
organization_events(org, number=-1, etag=None)

Iterate over events from the user’s organization dashboard.

Note

You must be authenticated to view this.

Parameters:
  • org (str) – (required), name of the organization
  • number (int) – (optional), number of events to return. Default: -1 returns all available events
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Events

organizations(number=-1, etag=None)

Iterate over organizations the user is member of.

Parameters:
  • number (int) – (optional), number of organizations to return. Default: -1 returns all available organization
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of ShortOrganizations

promote()

Promote a user to site administrator.

This is only available for admins of a GitHub Enterprise instance.

Returns:bool – True if successful, False otherwise
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
received_events(public=False, number=-1, etag=None)

Iterate over events that the user has received.

If the user is the authenticated user, you will see private and public events, otherwise you will only see public events.

Parameters:
  • public (bool) – (optional), determines if the authenticated user sees both private and public or just public
  • number (int) – (optional), number of events to return. Default: -1 returns all events available
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Events

refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:self
rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterprise instance.

Parameters:login (str) – (required), new name of the user
Returns:bool
revoke_impersonation()

Revoke all impersonation tokens for the current user.

This is only available for admins of a GitHub Enterprise instance.

Returns:bool – True if successful, False otherwise
starred_repositories(sort=None, direction=None, number=-1, etag=None)

Iterate over repositories starred by this user.

Changed in version 0.5: Added sort and direction parameters (optional) as per the change in GitHub’s API.

Parameters:
  • number (int) – (optional), number of starred repos to return. Default: -1, returns all available repos
  • sort (str) – (optional), either ‘created’ (when the star was created) or ‘updated’ (when the repository was last pushed to)
  • direction (str) – (optional), either ‘asc’ or ‘desc’. Default: ‘desc’
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of StarredRepository

subscriptions(number=-1, etag=None)

Iterate over repositories subscribed to by this user.

Parameters:
  • number (int) – (optional), number of subscriptions to return. Default: -1, returns all available
  • etag (str) – (optional), ETag from a previous request to the same endpoint
Returns:

generator of Repository

suspend()

Suspend the user.

This is only available for admins of a GitHub Enterprise instance.

This API is disabled if you use LDAP, check the GitHub API dos for more information.

Returns:bool – True if successful, False otherwise
unsuspend()

Unsuspend the user.

This is only available for admins of a GitHub Enterprise instance.

This API is disabled if you use LDAP, check the GitHub API dos for more information.

Returns:bool – True if successful, False otherwise

class github3.users.Key(json, session)

The object representing a user’s SSH key.

Please see GitHub’s Key Documentation for more information.

Changed in version 1.0.0: Removed title attribute

key

A string containing the actual text of the SSH Key

id

GitHub’s unique ID for this key

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())
Returns:this object’s attributes serialized to a dictionary
Return type:dict
as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())
Returns:this object’s attributes as a JSON string
Return type:str
delete()

Delete this key.

from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:self
update(title, key)

Update this key.

Warning

As of 20 June 2014, the API considers keys to be immutable. This will soon begin to return MethodNotAllowed errors.

Parameters:
  • title (str) – (required), title of the key
  • key (str) – (required), text of the key file
Returns:

bool


class github3.users.Plan(json, session)

The Plan object.

Please see GitHub’s Authenticated User documentation for more details.

collaborators_count

Changed in version 1.0.0.

The number of collaborators allowed on this plan

name

The name of the plan on GitHub

private_repos_count

Changed in version 1.0.0.

The number of allowed private repositories

space

The amount of space allotted by this plan

as_dict()

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())
Returns:this object’s attributes serialized to a dictionary
Return type:dict
as_json()

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())
Returns:this object’s attributes as a JSON string
Return type:str
from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

from_json(json, session)

Return an instance of this class formed from json.

is_free()

Check if this is a free plan.

Returns:bool
new_session()

Generate a new session.

Returns:A brand new session
Return type:GitHubSession
ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:int
refresh(conditional=False)

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos = [r.refresh() for r in g.repositories_by('kennethreitz')]

Without the return value, that would be an array of None’s and you would otherwise have to do:

repos = [r for i in g.repositories_by('kennethreitz')]
[r.refresh() for r in repos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs
Returns:self