Users and their Associated Objects

This section of the documentation covers the representations of various objects related to the Users API.

User Objects

class github3.users.ShortUser(json, session: github3.session.GitHubSession)

Object for the shortened representation of a User.

GitHub’s API returns different amounts of information about users based upon how that information is retrieved. Often times, when iterating over several users, GitHub will return less information. To provide a clear distinction between the types of users, github3.py uses different classes with 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 from uritemplate that can be used to generate an events URL

followers_url

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

following_urlt

A URITemplate object from uritemplate that can be used to generate the URL to check if this user is following other_user

gists_urlt

A URITemplate object from uritemplate that can be used to generate the 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 to which a user belongs

received_events_url

A string representing the resource to retrieve the events a user received

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 of GitHub’s staff

starred_urlt

A URITemplate object from uritemplate that can be used to generate a 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 cases should 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 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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

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 same endpoint

Returns

generator of GPGKeys

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

property 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: bool = False) → github3.models.GitHubCore

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.Stargazer(json, session: github3.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 on ShortUser as well as the following:

starred_at

The time and date that the user starred the repository this was queried 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 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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

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 same endpoint

Returns

generator of GPGKeys

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

property 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: bool = False) → github3.models.GitHubCore

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.User(json, session: github3.session.GitHubSession)

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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

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 same endpoint

Returns

generator of GPGKeys

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

property 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: bool = False) → github3.models.GitHubCore

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.AuthenticatedUser(json, session: github3.session.GitHubSession)

Object to represent the currently authenticated user.

This is returned by me(). It contains the extra informtation that is not returned for other users such as the currently authenticated user’s plan and private email information.

New in version 1.0.0.

Changed in version 1.0.0: The total_private_gists attribute is no longer returned by GitHub’s API and so is removed.

This object has all of the same attribute as the ShortUser and User objects as 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, this attribute will not be returned. To handle these situations sensitively, the attribute will be set to None. Repositories may still have a license associated with them in 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 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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

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 same endpoint

Returns

generator of GPGKeys

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

property 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: bool = False) → github3.models.GitHubCore

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.Collaborator(json, session: github3.session.GitHubSession)

Object for the representation of a collaborator.

New in version 1.1.0.

When retrieving a repository’s contributors, GitHub returns the same information as a ShortUser with an additional attribute:

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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

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 same endpoint

Returns

generator of GPGKeys

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

property 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: bool = False) → github3.models.GitHubCore

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.Contributor(json, session: github3.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 a User.

The attribute contributions was renamed to contributions_count, the documentation already declared it as contributions_count, it was the implementation now reflects this as well.

When retrieving a repository’s contributors, GitHub returns the same information as a ShortUser with an additional attribute:

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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod from_json(json, session)

Return an instance of this class formed from json.

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 same endpoint

Returns

generator of GPGKeys

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

property 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: bool = False) → github3.models.GitHubCore

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

AuthenticatedUser Peripherals

class github3.users.Key(json, session: github3.session.GitHubSession)

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.

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod 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

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → github3.models.GitHubCore

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: github3.session.GitHubSession)

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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod 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

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → github3.models.GitHubCore

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

class github3.users.Email(json, session: github3.session.GitHubSession)

The object used to represent an AuthenticatedUser’s email.

Please see GitHub’s Emails documentation for more information.

This object has all of the attributes of ShortEmail as well as the following attributes:

primary

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

visibility

A string value representing whether an authenticated user can view the email address. Use public 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

classmethod from_dict(json_dict, session)

Return an instance of this class formed from json_dict.

classmethod 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

property ratelimit_remaining

Number of requests before GitHub imposes a ratelimit.

Returns

int

refresh(conditional: bool = False) → github3.models.GitHubCore

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