User Objects

classgithub3.users.ShortUser(json,session:GitHubSession)

Object for the shortened representation of a User.

GitHub’s API returns different amounts of information about users basedupon how that information is retrieved. Often times, when iterating overseveral users, GitHub will return less information. To provide a cleardistinction between the types of users, github3.py uses different classeswith different sets of attributes.

New in version 1.0.0.

avatar_url

The URL of the avatar (possibly from Gravatar)

events_urlt

A URITemplate object fromuritemplate that can be used to generatean events URL

followers_url

A string representing the resource to retrieve a User’s followers

following_urlt

A URITemplate object fromuritemplate that can be used to generatethe URL to check if this user is followingother_user

gists_urlt

A URITemplate object fromuritemplate that can be used to generatethe URL to retrieve a Gist by its id

gravatar_id

The identifier for the user’s gravatar

html_url

The URL of the user’s publicly visible profile. For example,https://github.com/sigmavirus24

id

The unique ID of the account

login

The username of the user, e.g.,sigmavirus24

organizations_url

A string representing the resource to retrieve the organizations towhich a user belongs

received_events_url

A string representing the resource to retrieve the events a userreceived

repos_url

A string representing the resource to list a user’s repositories

site_admin

A boolean attribute indicating whether the user is a member ofGitHub’s staff

starred_urlt

A URITemplate object fromuritemplate that can be used to generatea URL to retrieve whether the user has starred a repository.

subscriptions_url

A string representing the resource to list a user’s subscriptions

type

A string representing the type of User account this. In all casesshould be “User”

url

A string of this exact resource retrievable from GitHub’s API

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 theuser.

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 theauthenticated user

• number (int) – (optional), number of events to return. Default: -1returns all available events.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofUsers

following(number=-1,etag=None)

Iterate over the users being followed by this user.

Parameters:

• number (int) – (optional), number of users to return. Default: -1returns all available users

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofUsers

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

gpg_keys(number=-1,etag=None)

Iterate over the GPG keys of this user.

New in version 1.2.0.

Parameters:

• number (int) – (optional), number of GPG keys to return. Default:-1 returns all available GPG keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofGPGKeys

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 followingusername.

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: -1returns all available keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofKeys

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: -1returns all available events

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofShortOrganizations

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

propertyratelimit_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 publicevents, otherwise you will only see public events.

Parameters:

• public (bool) – (optional), determines if the authenticated usersees both private and public or just public

• number (int) – (optional), number of events to return. Default: -1returns all events available

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterpriseinstance.

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 inGitHub’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 wascreated) 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 sameendpoint

Returns:

generator ofStarredRepository

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 sameendpoint

Returns:

generator ofRepository

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 moreinformation.

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 moreinformation.

Returns:

bool – True if successful, False otherwise

classgithub3.users.Stargazer(json,session:GitHubSession)

Object representing a user that has starred a repository.

New in version 3.0.0.

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

starred_at

The time and date that the user starred the repository this wasqueried from.

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 theuser.

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 theauthenticated user

• number (int) – (optional), number of events to return. Default: -1returns all available events.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofUsers

following(number=-1,etag=None)

Iterate over the users being followed by this user.

Parameters:

• number (int) – (optional), number of users to return. Default: -1returns all available users

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofUsers

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

gpg_keys(number=-1,etag=None)

Iterate over the GPG keys of this user.

New in version 1.2.0.

Parameters:

• number (int) – (optional), number of GPG keys to return. Default:-1 returns all available GPG keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofGPGKeys

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 followingusername.

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: -1returns all available keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofKeys

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: -1returns all available events

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofShortOrganizations

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

propertyratelimit_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 publicevents, otherwise you will only see public events.

Parameters:

• public (bool) – (optional), determines if the authenticated usersees both private and public or just public

• number (int) – (optional), number of events to return. Default: -1returns all events available

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterpriseinstance.

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 inGitHub’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 wascreated) 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 sameendpoint

Returns:

generator ofStarredRepository

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 sameendpoint

Returns:

generator ofRepository

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 moreinformation.

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 moreinformation.

Returns:

bool – True if successful, False otherwise

classgithub3.users.User(json,session:GitHubSession)

Object for the full representation of a User.

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

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

Changed in version 1.0.0.

This object contains all of the attributes available onShortUser 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 parseddatetime object representing the date theuser 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 parseddatetime object representing the datethe 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 theuser.

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 theauthenticated user

• number (int) – (optional), number of events to return. Default: -1returns all available events.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofUsers

following(number=-1,etag=None)

Iterate over the users being followed by this user.

Parameters:

• number (int) – (optional), number of users to return. Default: -1returns all available users

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofUsers

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

gpg_keys(number=-1,etag=None)

Iterate over the GPG keys of this user.

New in version 1.2.0.

Parameters:

• number (int) – (optional), number of GPG keys to return. Default:-1 returns all available GPG keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofGPGKeys

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 followingusername.

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: -1returns all available keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofKeys

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: -1returns all available events

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofShortOrganizations

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

propertyratelimit_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 publicevents, otherwise you will only see public events.

Parameters:

• public (bool) – (optional), determines if the authenticated usersees both private and public or just public

• number (int) – (optional), number of events to return. Default: -1returns all events available

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterpriseinstance.

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 inGitHub’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 wascreated) 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 sameendpoint

Returns:

generator ofStarredRepository

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 sameendpoint

Returns:

generator ofRepository

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 moreinformation.

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 moreinformation.

Returns:

bool – True if successful, False otherwise

classgithub3.users.AuthenticatedUser(json,session:GitHubSession)

Object to represent the currently authenticated user.

This is returned byme(). It contains theextra informtation that is not returned for other users such as thecurrently authenticated user’s plan and private email information.

New in version 1.0.0.

Changed in version 1.0.0:Thetotal_private_gists attribute is no longer returned byGitHub’s API and so is removed.

This object has all of the same attribute as theShortUser andUser objectsas well as:

disk_usage

The amount of repository space that has been used by you, the user

owned_private_repos_count

The number of private repositories owned by you, the user

plan

Note

When used with a Github Enterprise instance <= 2.12.7, thisattribute will not be returned. To handle these situationssensitively, the attribute will be set toNone.Repositories may still have a license associated with themin these cases.

The name of the plan that you, the user, have purchased

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 theuser.

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 theauthenticated user

• number (int) – (optional), number of events to return. Default: -1returns all available events.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofUsers

following(number=-1,etag=None)

Iterate over the users being followed by this user.

Parameters:

• number (int) – (optional), number of users to return. Default: -1returns all available users

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofUsers

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

gpg_keys(number=-1,etag=None)

Iterate over the GPG keys of this user.

New in version 1.2.0.

Parameters:

• number (int) – (optional), number of GPG keys to return. Default:-1 returns all available GPG keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofGPGKeys

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 followingusername.

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: -1returns all available keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofKeys

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: -1returns all available events

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofShortOrganizations

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

propertyratelimit_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 publicevents, otherwise you will only see public events.

Parameters:

• public (bool) – (optional), determines if the authenticated usersees both private and public or just public

• number (int) – (optional), number of events to return. Default: -1returns all events available

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterpriseinstance.

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 inGitHub’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 wascreated) 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 sameendpoint

Returns:

generator ofStarredRepository

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 sameendpoint

Returns:

generator ofRepository

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 moreinformation.

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 moreinformation.

Returns:

bool – True if successful, False otherwise

classgithub3.users.Collaborator(json,session:GitHubSession)

Object for the representation of a collaborator.

New in version 1.1.0.

When retrieving a repository’s contributors, GitHub returns the sameinformation as aShortUser with an additionalattribute:

permissions

Admin, push, and pull permissions of a collaborator

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 theuser.

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 theauthenticated user

• number (int) – (optional), number of events to return. Default: -1returns all available events.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofUsers

following(number=-1,etag=None)

Iterate over the users being followed by this user.

Parameters:

• number (int) – (optional), number of users to return. Default: -1returns all available users

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofUsers

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

gpg_keys(number=-1,etag=None)

Iterate over the GPG keys of this user.

New in version 1.2.0.

Parameters:

• number (int) – (optional), number of GPG keys to return. Default:-1 returns all available GPG keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofGPGKeys

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 followingusername.

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: -1returns all available keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofKeys

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: -1returns all available events

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofShortOrganizations

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

propertyratelimit_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 publicevents, otherwise you will only see public events.

Parameters:

• public (bool) – (optional), determines if the authenticated usersees both private and public or just public

• number (int) – (optional), number of events to return. Default: -1returns all events available

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterpriseinstance.

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 inGitHub’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 wascreated) 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 sameendpoint

Returns:

generator ofStarredRepository

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 sameendpoint

Returns:

generator ofRepository

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 moreinformation.

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 moreinformation.

Returns:

bool – True if successful, False otherwise

classgithub3.users.Contributor(json,session:GitHubSession)

Object for the specialized representation of a contributor.

New in version 1.0.0.

Changed in version 1.1.0:This class now refreshes to aUser.

The attributecontributions was renamed tocontributions_count,the documentation already declared it ascontributions_count, itwas the implementation now reflects this as well.

When retrieving a repository’s contributors, GitHub returns the sameinformation as aShortUser with an additionalattribute:

contributions_count

The number of contributions a contributor has made to the repository

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 theuser.

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 theauthenticated user

• number (int) – (optional), number of events to return. Default: -1returns all available events.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofUsers

following(number=-1,etag=None)

Iterate over the users being followed by this user.

Parameters:

• number (int) – (optional), number of users to return. Default: -1returns all available users

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofUsers

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

gpg_keys(number=-1,etag=None)

Iterate over the GPG keys of this user.

New in version 1.2.0.

Parameters:

• number (int) – (optional), number of GPG keys to return. Default:-1 returns all available GPG keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofGPGKeys

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 followingusername.

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: -1returns all available keys

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofKeys

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: -1returns all available events

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

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 sameendpoint

Returns:

generator ofShortOrganizations

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

propertyratelimit_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 publicevents, otherwise you will only see public events.

Parameters:

• public (bool) – (optional), determines if the authenticated usersees both private and public or just public

• number (int) – (optional), number of events to return. Default: -1returns all events available

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator ofEvents

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

rename(login)

Rename the user.

Note

This is only available for administrators of a GitHub Enterpriseinstance.

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 inGitHub’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 wascreated) 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 sameendpoint

Returns:

generator ofStarredRepository

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 sameendpoint

Returns:

generator ofRepository

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 moreinformation.

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 moreinformation.

Returns:

bool – True if successful, False otherwise

AuthenticatedUser Peripherals

classgithub3.users.Key(json,session:GitHubSession)

The object representing a user’s SSH key.

Please see GitHub’sKey Documentation for more information.

Changed in version 1.0.0:Removedtitle 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.

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

propertyratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:

int

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional 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

classgithub3.users.Plan(json,session:GitHubSession)

ThePlan object.

Please see GitHub’sAuthenticated 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

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

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

propertyratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:

int

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

classgithub3.users.Email(json,session:GitHubSession)

The object used to represent an AuthenticatedUser’s email.

Please see GitHub’sEmails documentation for more information.

This object has all of the attributes ofShortEmail as well asthe following attributes:

primary

A boolean value representing whether the address is the primaryaddress for the user or not

visibility

A string value representing whether an authenticated user can view theemail address. Usepublic to allow it,private to disallow it.

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

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

propertyratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns:

int

refresh(conditional:bool=False)→GitHubCore

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

repos=[r.refresh()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self