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

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 `Event`s

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 `User`s

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 `User`s

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.

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 `Key`s

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 `Event`s

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 `ShortOrganization`s

promote()¶

Promote a user to site administrator.

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

Returns:	bool – True if successful, False otherwise

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

received_events(public=False, number=-1, etag=None)¶

Iterate over events that the user has received.

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

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

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

rename(login)¶

Rename the user.

Note

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

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

revoke_impersonation()¶

Revoke all impersonation tokens for the current user.

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

Returns:	bool – True if successful, False otherwise

starred_repositories(sort=None, direction=None, number=-1, etag=None)¶

Iterate over repositories starred by this user.

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

Parameters:

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

Returns:

generator of StarredRepository

subscriptions(number=-1, etag=None)¶

Iterate over repositories subscribed to by this user.

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

suspend()¶

Suspend the user.

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

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

Returns:	bool – True if successful, False otherwise

unsuspend()¶

Unsuspend the user.

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

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

Returns:	bool – True if successful, False otherwise

class github3.users.User(json, session)¶

Object for the full representation of a User.

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

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

Changed in version 1.0.0.

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

bio¶: The markdown formatted User’s biography

blog¶: The URL of the user’s blog

company¶: The name or GitHub handle of the user’s company

created_at¶: A parsed datetime object representing the date the user was created

email¶: The email address the user has on their public profile page

followers_count¶: The number of followers of this user

following_count¶: The number of users this user follows

hireable¶: Whether or not the user has opted into GitHub jobs advertising

location¶: The location specified by the user on their public profile

name¶: The name specified by their user on their public profile

public_gists_count¶: The number of public gists owned by this user

updated_at¶: A parsed datetime object representing the date the user was last updated

as_dict()¶

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:	this object’s attributes serialized to a dictionary
Return type:	dict

as_json()¶

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:	this object’s attributes as a JSON string
Return type:	str

delete()¶

Delete the user.

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

Note

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

Returns:	bool – True if successful, False otherwise

demote()¶

Demote a site administrator to simple user.

You can demote any user account except your own.

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

Returns:	bool – True if successful, False otherwise

events(public=False, number=-1, etag=None)¶

Iterate over events performed by this user.

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

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 `User`s

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 `User`s

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.

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 `Key`s

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 `Event`s

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 `ShortOrganization`s

promote()¶

Promote a user to site administrator.

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

Returns:	bool – True if successful, False otherwise

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

received_events(public=False, number=-1, etag=None)¶

Iterate over events that the user has received.

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

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

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

rename(login)¶

Rename the user.

Note

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

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

revoke_impersonation()¶

Revoke all impersonation tokens for the current user.

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

Returns:	bool – True if successful, False otherwise

starred_repositories(sort=None, direction=None, number=-1, etag=None)¶

Iterate over repositories starred by this user.

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

Parameters:

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

Returns:

generator of StarredRepository

subscriptions(number=-1, etag=None)¶

Iterate over repositories subscribed to by this user.

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

suspend()¶

Suspend the user.

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

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

Returns:	bool – True if successful, False otherwise

unsuspend()¶

Unsuspend the user.

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

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

Returns:	bool – True if successful, False otherwise

class github3.users.AuthenticatedUser(json, session)¶

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 `Event`s

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 `User`s

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 `User`s

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.

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 `Key`s

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 `Event`s

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 `ShortOrganization`s

promote()¶

Promote a user to site administrator.

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

Returns:	bool – True if successful, False otherwise

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

received_events(public=False, number=-1, etag=None)¶

Iterate over events that the user has received.

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

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

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

rename(login)¶

Rename the user.

Note

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

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

revoke_impersonation()¶

Revoke all impersonation tokens for the current user.

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

Returns:	bool – True if successful, False otherwise

starred_repositories(sort=None, direction=None, number=-1, etag=None)¶

Iterate over repositories starred by this user.

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

Parameters:

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

Returns:

generator of StarredRepository

subscriptions(number=-1, etag=None)¶

Iterate over repositories subscribed to by this user.

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

suspend()¶

Suspend the user.

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

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

Returns:	bool – True if successful, False otherwise

unsuspend()¶

Unsuspend the user.

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

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

Returns:	bool – True if successful, False otherwise

class github3.users.Collaborator(json, session)¶

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 `Event`s

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 `User`s

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 `User`s

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.

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 `Key`s

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 `Event`s

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 `ShortOrganization`s

promote()¶

Promote a user to site administrator.

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

Returns:	bool – True if successful, False otherwise

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

received_events(public=False, number=-1, etag=None)¶

Iterate over events that the user has received.

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

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

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

rename(login)¶

Rename the user.

Note

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

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

revoke_impersonation()¶

Revoke all impersonation tokens for the current user.

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

Returns:	bool – True if successful, False otherwise

starred_repositories(sort=None, direction=None, number=-1, etag=None)¶

Iterate over repositories starred by this user.

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

Parameters:

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

Returns:

generator of StarredRepository

subscriptions(number=-1, etag=None)¶

Iterate over repositories subscribed to by this user.

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

suspend()¶

Suspend the user.

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

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

Returns:	bool – True if successful, False otherwise

unsuspend()¶

Unsuspend the user.

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

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

Returns:	bool – True if successful, False otherwise

class github3.users.Contributor(json, session)¶

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 `Event`s

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 `User`s

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 `User`s

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.

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 `Key`s

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 `Event`s

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 `ShortOrganization`s

promote()¶

Promote a user to site administrator.

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

Returns:	bool – True if successful, False otherwise

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

received_events(public=False, number=-1, etag=None)¶

Iterate over events that the user has received.

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

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

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

rename(login)¶

Rename the user.

Note

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

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

revoke_impersonation()¶

Revoke all impersonation tokens for the current user.

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

Returns:	bool – True if successful, False otherwise

starred_repositories(sort=None, direction=None, number=-1, etag=None)¶

Iterate over repositories starred by this user.

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

Parameters:

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

Returns:

generator of StarredRepository

subscriptions(number=-1, etag=None)¶

Iterate over repositories subscribed to by this user.

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

suspend()¶

Suspend the user.

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

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

Returns:	bool – True if successful, False otherwise

unsuspend()¶

Unsuspend the user.

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

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

Returns:	bool – True if successful, False otherwise

AuthenticatedUser Peripherals¶

class github3.users.Key(json, session)¶

The object representing a user’s SSH key.

Please see GitHub’s Key Documentation for more information.

Changed in version 1.0.0: Removed title attribute

key¶: A string containing the actual text of the SSH Key

id¶: GitHub’s unique ID for this key

as_dict()¶

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:	this object’s attributes serialized to a dictionary
Return type:	dict

as_json()¶

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:	this object’s attributes as a JSON string
Return type:	str

delete()¶: Delete this key.

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`

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

update(title, key)¶

Update this key.

Warning

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

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

class github3.users.Plan(json, session)¶

The Plan object.

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

collaborators_count¶: Changed in version 1.0.0.

The number of collaborators allowed on this plan

name¶: The name of the plan on GitHub

private_repos_count¶: Changed in version 1.0.0.

The number of allowed private repositories

space¶: The amount of space allotted by this plan

as_dict()¶

Return the attributes for this object as a dictionary.

This is equivalent to calling:

json.loads(obj.as_json())

Returns:	this object’s attributes serialized to a dictionary
Return type:	dict

as_json()¶

Return the json data for this object.

This is equivalent to calling:

json.dumps(obj.as_dict())

Returns:	this object’s attributes as a JSON string
Return type:	str

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`

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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

class github3.users.Email(json, session)¶

The object used to represent an AuthenticatedUser’s email.

Please see GitHub’s Emails documentation for more information.

The attributes represented on this object include:

email¶: The email address as a string

verified¶: A boolean value representing whether the address has been verified or not

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

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`

ratelimit_remaining¶

Number of requests before GitHub imposes a ratelimit.

Returns:	int

refresh(conditional=False)¶

Re-retrieve the information for this object.

The reasoning for the return value is the following example:

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

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

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

Which is really an anti-pattern.

Changed in version 0.5.

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