Organization¶
This section of the documentation covers:
Organization Objects¶
-
class
github3.orgs.
Organization
(json, session)¶ Object for the full representation of a Organization.
GitHub’s API returns different amounts of information about orgs based upon how that information is retrieved. This object exists to represent the full amount of information returned for a specific org. For example, you would receive this class when calling
organization()
. To provide a clear distinction between the types of orgs, github3.py uses different classes with different sets of attributes.Changed in version 1.0.0.
This object includes all attributes on
ShortOrganization
as well as the following:-
blog
¶ If set, the URL of this organization’s blog.
-
company
¶ The name of the company that is associated with this organization.
-
created_at
¶ A
datetime
instance representing the time and date when this organization was created.
-
email
¶ The email address associated with this organization.
-
followers_count
¶ The number of users following this organization. Organizations no longer have followers so this number will always be 0.
-
following_count
¶ The number of users this organization follows. Organizations no longer follow users so this number will always be 0.
-
html_url
¶ The URL used to view this organization in a browser.
-
location
¶ The location of this organization, e.g., New York, NY.
-
name
¶ The display name of this organization.
-
public_repos_count
¶ The number of public repositories owned by thi sorganization.
-
add_member
(username, team_id)¶ Add
username
toteam
and thereby to this organization.Warning
This method is no longer valid. To add a member to a team, you must now retrieve the team directly, and use the
invite
method.Warning
This method is no longer valid. To add a member to a team, you must now retrieve the team directly, and use the
invite
method.Any user that is to be added to an organization, must be added to a team as per the GitHub api.
Changed in version 1.0: The second parameter used to be
team
but has been changed toteam_id
. This parameter is now required to be an integer to improve performance of this method.Parameters: - username (str) – (required), login name of the user to be added
- team_id (int) – (required), team id
Returns: True if successful, False otherwise
Return type: bool
-
add_repository
(repository, team_id)¶ Add
repository
toteam
.Changed in version 1.0: The second parameter used to be
team
but has been changed toteam_id
. This parameter is now required to be an integer to improve performance of this method.Parameters: - repository (str) – (required), form: ‘user/repo’
- team_id (int) – (required), team id
Returns: True if successful, False otherwise
Return type: bool
-
all_events
(username, number=-1, etag=None)¶ Iterate over all org events visible to the authenticated user.
Parameters: - username (str) – (required), the username of the currently authenticated user.
- number (int) – (optional), number of events to return. Default: -1 iterates over all events available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of events
Return type:
-
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
-
conceal_member
(username)¶ Conceal
username
’s membership in this organization.Parameters: username (str) – username of the organization member to conceal Returns: True if successful, False otherwise Return type: bool
-
create_project
(name, body=u'')¶ Create a project for this organization.
If the client is authenticated and a member of the organization, this will create a new project in the organization.
Parameters: - name (str) – (required), name of the project
- body (str) – (optional), the body of the project
Returns: the new project
Return type: Project
-
create_repository
(name, description=u'', homepage=u'', private=False, has_issues=True, has_wiki=True, team_id=0, auto_init=False, gitignore_template=u'', license_template=u'')¶ Create a repository for this organization.
If the client is authenticated and a member of the organization, this will create a new repository in the organization.
name
should be no longer than 100 charactersParameters: - name (str) –
(required), name of the repository
Warning
this should be no longer than 100 characters
- description (str) – (optional)
- homepage (str) – (optional)
- private (bool) – (optional), If
True
, create a private repository. API default:False
- has_issues (bool) – (optional), If
True
, enable issues for this repository. API default:True
- has_wiki (bool) – (optional), If
True
, enable the wiki for this repository. API default:True
- team_id (int) – (optional), id of the team that will be granted access to this repository
- auto_init (bool) – (optional), auto initialize the repository.
- gitignore_template (str) – (optional), name of the template; this is ignored if auto_int is False.
- license_template (str) – (optional), name of the license; this is ignored if auto_int is False.
Returns: the created repository
Return type: Repository
- name (str) –
-
create_team
(name, repo_names=[], permission=u'pull')¶ Create a new team and return it.
This only works if the authenticated user owns this organization.
Parameters: - name (str) – (required), name to be given to the team
- repo_names (list) – (optional) repositories, e.g. [‘github/dotfiles’]
- permission (str) –
(optional), options:
pull
– (default) members can not push or administer- repositories accessible by this team
push
– members can push and pull but not administer- repositories accessible by this team
admin
– members can push, pull and administer- repositories accessible by this team
Returns: the created team
Return type:
-
edit
(billing_email=None, company=None, email=None, location=None, name=None)¶ Edit this organization.
Parameters: - billing_email (str) – (optional) Billing email address (private)
- company (str) – (optional)
- email (str) – (optional) Public email address
- location (str) – (optional)
- name (str) – (optional)
Returns: True if successful, False otherwise
Return type: bool
-
events
(number=-1, etag=None)¶ Iterate over public events for this org (deprecated).
Deprecated since version 1.0.0: Use
public_events()
instead.Parameters: - number (int) – (optional), number of events to return. Default: -1 iterates over all events available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of events
Return type:
-
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_member
(username)¶ Check if the user named
username
is a member.Parameters: username (str) – name of the user you’d like to check Returns: True if successful, False otherwise Return type: bool
-
is_public_member
(username)¶ Check if the user named
username
is a public member.Parameters: username (str) – name of the user you’d like to check Returns: True if the user is a public member, False otherwise Return type: bool
-
members
(filter=None, role=None, number=-1, etag=None)¶ Iterate over members of this organization.
Parameters: - filter (str) – (optional), filter members returned by this method. Can be one of:
"2fa_disabled"
,"all",
. Default:"all"
. Filtering by"2fa_disabled"
is only available for organization owners with private repositories. - role (str) – (optional), filter members returned by their role. Can be one of:
"all"
,"admin"
,"member"
. Default:"all"
. - number (int) – (optional), number of members to return. Default: -1 will return all available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of members of this organization
Return type: ShortUser
- filter (str) – (optional), filter members returned by this method. Can be one of:
-
new_session
()¶ Generate a new session.
Returns: A brand new session Return type: GitHubSession
-
project
(id, etag=None)¶ Return the organization project with the given ID.
Parameters: id (int) – (required), ID number of the project Returns: requested project Return type: Project
-
projects
(number=-1, etag=None)¶ Iterate over projects for this organization.
Parameters: - number (int) – (optional), number of members to return. Default: -1 will return all available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of organization projects
Return type: Project
-
public_events
(number=-1, etag=None)¶ Iterate over public events for this org.
Parameters: - number (int) – (optional), number of events to return. Default: -1 iterates over all events available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of public events
Return type:
-
public_members
(number=-1, etag=None)¶ Iterate over public members of this organization.
Parameters: - number (int) – (optional), number of members to return. Default: -1 will return all available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of public members
Return type: ShortUser
-
publicize_member
(username)¶ Make
username
’s membership in this organization public.Parameters: username (str) – the name of the user whose membership you wish to publicize Returns: True if successful, False otherwise Return type: bool
-
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
-
remove_member
(username)¶ Remove the user named
username
from this organization.Parameters: username (str) – name of the user to remove from the org Returns: True if successful, False otherwise Return type: bool
-
remove_repository
(repository, team_id)¶ Remove
repository
from the team withteam_id
.Parameters: - repository (str) – (required), form: ‘user/repo’
- team_id (int) – (required), the unique identifier of the team
Returns: True if successful, False otherwise
Return type: bool
-
repositories
(type=u'', number=-1, etag=None)¶ Iterate over repos for this organization.
Parameters: - type (str) – (optional), accepted values: (‘all’, ‘public’, ‘member’, ‘private’, ‘forks’, ‘sources’), API default: ‘all’
- number (int) – (optional), number of members to return. Default: -1 will return all available.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of repositories in this organization
Return type: Repository
-
team
(team_id)¶ Return the team specified by
team_id
.Parameters: team_id (int) – (required), unique id for the team Returns: the team identified by the id in this organization Return type: Team
-
teams
(number=-1, etag=None)¶ Iterate over teams that are part of this organization.
Parameters: - number (int) – (optional), number of teams to return. Default: -1 returns all available teams.
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of this organization’s teams
Return type: ShortTeam
-
-
class
github3.orgs.
Team
(json, session)¶ Object representing a team in the GitHub API.
In addition to the attributes on a
ShortTeam
a Team has the following attribute:-
created_at
¶ A
datetime
instance representing the time and date when this team was created.
-
members_count
¶ The number of members in this team.
-
organization
¶ A
ShortOrganization
representing the organization this team belongs to.
-
repos_count
¶ The number of repositories this team can access.
-
updated_at
¶ A
datetime
instance representing the time and date when this team was updated.
Please see GitHub’s Team Documentation for more information.
-
add_member
(username)¶ Add
username
to this team.Parameters: username (str) – the username of the user you would like to add to this team. Returns: True if successfully added, False otherwise Return type: bool
-
add_repository
(repository, permission=u'')¶ Add
repository
to this team.If a permission is not provided, the team’s default permission will be assigned, by GitHub.
Parameters: - repository (str) – (required), form: ‘user/repo’
- permission (str) – (optional), (‘pull’, ‘push’, ‘admin’)
Returns: True if successful, False otherwise
Return type: bool
-
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 team.
Returns: True if successful, False otherwise Return type: bool
-
edit
(name, permission=u'')¶ Edit this team.
Parameters: - name (str) – (required), the new name of this team
- permission (str) – (optional), one of (‘pull’, ‘push’, ‘admin’)
Returns: True if successful, False otherwise
Return type: bool
-
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
.
-
has_repository
(repository)¶ Check if this team has access to
repository
.Parameters: repository (str) – (required), form: ‘user/repo’ Returns: True if the team can access the repository, False otherwise Return type: bool
-
invite
(username)¶ Invite the user to join this team.
This returns a dictionary like so:
{'state': 'pending', 'url': 'https://api.github.com/teams/...'}
Parameters: username (str) – (required), login of user to invite to join this team. Returns: dictionary of the invitation response Return type: dict
-
is_member
(username)¶ Check if
login
is a member of this team.Parameters: username (str) – (required), username name of the user Returns: True if the user is a member, False otherwise Return type: bool
-
members
(role=None, number=-1, etag=None)¶ Iterate over the members of this team.
Parameters: - role (str) – (optional), filter members returned by their role in the team.
Can be one of:
"member"
,"maintainer"
,"all"
. Default:"all"
. - number (int) – (optional), number of users to iterate over. Default: -1 iterates over all values
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of the members of this team
Return type: ShortUser
- role (str) – (optional), filter members returned by their role in the team.
Can be one of:
-
membership_for
(username)¶ Retrieve the membership information for the user.
Parameters: username (str) – (required), name of the user Returns: dictionary with the membership Return type: dict
-
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
-
remove_member
(username)¶ Remove
username
from this team.Parameters: username (str) – (required), username of the member to remove Returns: True if successful, False otherwise Return type: bool
-
remove_repository
(repository)¶ Remove
repository
from this team.Parameters: repository (str) – (required), form: ‘user/repo’ Returns: True if successful, False otherwise Return type: bool
-
repositories
(number=-1, etag=None)¶ Iterate over the repositories this team has access to.
Parameters: - number (int) – (optional), number of repos to iterate over. Default: -1 iterates over all values
- etag (str) – (optional), ETag from a previous request to the same endpoint
Returns: generator of repositories this team has access to
Return type: ShortRepository
-
revoke_membership
(username)¶ Revoke this user’s team membership.
Parameters: username (str) – (required), name of the team member Returns: True if successful, False otherwise Return type: bool
-