User¶
This part of the documentation covers:
None of these objects should ever be instantiated by the user (developer).
When listing users, GitHub only sends a handful of the object’s attributes. To retrieve all of the object’s attributes, you must call the refresh() method. This unfortunately requires another call to the API, so use it sparingly if you have a low limit
User Modules¶
-
class
github3.users.
User
(json, session)¶ Object for the full representation of a User.
GitHub’s API returns different amounts of information about users based upon how that information is retrieved. This object exists to represent the full amount of information returned for a specific user. For example, you would receive this class when calling
user()
. To provide a clear distinction between the types of users, github3.py uses different classes with different sets of attributes.This object no longer contains information about the currently authenticated user (e.g.,
me()
).Changed in version 1.0.0.
This object contains all of the attributes available on
ShortUser
as well as the following:-
bio
¶ The markdown formatted User’s biography
-
blog
¶ The URL of the user’s blog
-
company
¶ The name or GitHub handle of the user’s company
-
created_at
¶ A parsed
datetime
object representing the date the user was created
-
email
¶ The email address the user has on their public profile page
-
followers_count
¶ The number of followers of this user
-
following_count
¶ The number of users this user follows
-
hireable
¶ Whether or not the user has opted into GitHub jobs advertising
-
location
¶ The location specified by the user on their public profile
-
name
¶ The name specified by their user on their public profile
-
public_gists_count
¶ The number of public gists owned by this user
-
updated_at
¶ A parsed
datetime
object representing the date the user was last updated
-
as_dict
()¶ Return the attributes for this object as a dictionary.
This is equivalent to calling:
json.loads(obj.as_json())
Returns: this object’s attributes serialized to a dictionary Return type: dict
-
as_json
()¶ Return the json data for this object.
This is equivalent to calling:
json.dumps(obj.as_dict())
Returns: this object’s attributes as a JSON string Return type: str
-
delete
()¶ Delete the user.
Per GitHub API documentation, it is often preferable to suspend the user.
Note
This is only available for admins of a GitHub Enterprise instance.
Returns: bool – True if successful, False otherwise
-
demote
()¶ Demote a site administrator to simple user.
You can demote any user account except your own.
This is only available for admins of a GitHub Enterprise instance.
Returns: bool – True if successful, False otherwise
-
events
(public=False, number=-1, etag=None)¶ Iterate over events performed by this user.
Parameters: - public (bool) – (optional), only list public events for the authenticated user
- number (int) – (optional), number of events to return. Default: -1 returns all available events.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
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
-
from_dict
(json_dict, session)¶ Return an instance of this class formed from
json_dict
.
-
from_json
(json, session)¶ Return an instance of this class formed from
json
.
-
impersonate
(scopes=None)¶ Obtain an impersonation token for the user.
The retrieved token will allow impersonation of the user. This is only available for admins of a GitHub Enterprise instance.
Parameters: scopes (list) – (optional), areas you want this token to apply to, i.e., ‘gist’, ‘user’ Returns: Authorization
-
is_assignee_on
(username, repository)¶ Check if this user can be assigned to issues on username/repository.
Parameters: - username (str) – owner’s username of the repository
- repository (str) – name of the repository
Returns: True if the use can be assigned, False otherwise
Return type: bool
-
is_following
(username)¶ Check if this user is following
username
.Parameters: username (str) – (required) Returns: bool
-
keys
(number=-1, etag=None)¶ Iterate over the public keys of this user.
New in version 0.5.
Parameters: - number (int) – (optional), number of keys to return. Default: -1 returns all available keys
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of
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.
Key
(json, session)¶ The object representing a user’s SSH key.
Please see GitHub’s Key Documentation for more information.
Changed in version 1.0.0: Removed
title
attribute-
key
¶ A string containing the actual text of the SSH Key
-
id
¶ GitHub’s unique ID for this key
-
as_dict
()¶ Return the attributes for this object as a dictionary.
This is equivalent to calling:
json.loads(obj.as_json())
Returns: this object’s attributes serialized to a dictionary Return type: dict
-
as_json
()¶ Return the json data for this object.
This is equivalent to calling:
json.dumps(obj.as_dict())
Returns: this object’s attributes as a JSON string Return type: str
-
delete
()¶ Delete this key.
-
from_dict
(json_dict, session)¶ Return an instance of this class formed from
json_dict
.
-
from_json
(json, session)¶ Return an instance of this class formed from
json
.
-
new_session
()¶ Generate a new session.
Returns: A brand new session Return type: GitHubSession
-
ratelimit_remaining
¶ Number of requests before GitHub imposes a ratelimit.
Returns: int
-
refresh
(conditional=False)¶ Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() for r in g.repositories_by('kennethreitz')]
Without the return value, that would be an array of
None
’s and you would otherwise have to do:repos = [r for i in g.repositories_by('kennethreitz')] [r.refresh() for r in repos]
Which is really an anti-pattern.
Changed in version 0.5.
Parameters: conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs Returns: self
-
update
(title, key)¶ Update this key.
Warning
As of 20 June 2014, the API considers keys to be immutable. This will soon begin to return MethodNotAllowed errors.
Parameters: - title (str) – (required), title of the key
- key (str) – (required), text of the key file
Returns: bool
-
-
class
github3.users.
Plan
(json, session)¶ The
Plan
object.Please see GitHub’s Authenticated User documentation for more details.
-
collaborators_count
¶ Changed in version 1.0.0.
The number of collaborators allowed on this plan
-
name
¶ The name of the plan on GitHub
-
private_repos_count
¶ Changed in version 1.0.0.
The number of allowed private repositories
-
space
¶ The amount of space allotted by this plan
-
as_dict
()¶ Return the attributes for this object as a dictionary.
This is equivalent to calling:
json.loads(obj.as_json())
Returns: this object’s attributes serialized to a dictionary Return type: dict
-
as_json
()¶ Return the json data for this object.
This is equivalent to calling:
json.dumps(obj.as_dict())
Returns: this object’s attributes as a JSON string Return type: str
-
from_dict
(json_dict, session)¶ Return an instance of this class formed from
json_dict
.
-
from_json
(json, session)¶ Return an instance of this class formed from
json
.
-
is_free
()¶ Check if this is a free plan.
Returns: bool
-
new_session
()¶ Generate a new session.
Returns: A brand new session Return type: GitHubSession
-
ratelimit_remaining
¶ Number of requests before GitHub imposes a ratelimit.
Returns: int
-
refresh
(conditional=False)¶ Re-retrieve the information for this object.
The reasoning for the return value is the following example:
repos = [r.refresh() for r in g.repositories_by('kennethreitz')]
Without the return value, that would be an array of
None
’s and you would otherwise have to do:repos = [r for i in g.repositories_by('kennethreitz')] [r.refresh() for r in repos]
Which is really an anti-pattern.
Changed in version 0.5.
Parameters: conditional (bool) – If True, then we will search for a stored header (‘Last-Modified’, or ‘ETag’) on the object and send that as described in the Conditional Requests section of the docs Returns: self
-