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: 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 followingother_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
.
- 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
GPGKey
s
- 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
- 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
- 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
Event
s
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
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
.
- 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
GPGKey
s
- 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
- 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
- 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
Event
s
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
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
.
- 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
GPGKey
s
- 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
- 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
- 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
Event
s
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
andUser
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
.
- 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
GPGKey
s
- 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
- 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
- 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
Event
s
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
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
.
- 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
GPGKey
s
- 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
- 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
- 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
Event
s
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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 tocontributions_count
, the documentation already declared it ascontributions_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
.
- 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
GPGKey
s
- 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
- 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
- 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
Event
s
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
- property ratelimit_remaining¶
Number of requests before GitHub imposes a ratelimit.
- Returns
int
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
- property ratelimit_remaining¶
Number of requests before GitHub imposes a ratelimit.
- Returns
int
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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: 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
- property ratelimit_remaining¶
Number of requests before GitHub imposes a ratelimit.
- Returns
int
- refresh(conditional: bool = False) GitHubCore ¶
Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() 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