Organization

This section of the documentation covers:

Organization Objects

class github3.orgs.Organization(json, session=None)

The Organization object.

Two organization instances can be checked like so:

o1 == o2
o1 != o2

And is equivalent to:

o1.id == o2.id
o1.id != o2.id

See also: http://developer.github.com/v3/orgs/

add_member(username, team_id)

Add username to team 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 to team_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:

bool

add_repository(repository, team_id)

Add repository to team.

Changed in version 1.0: The second parameter used to be team but has been changed to team_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:

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

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:bool
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.

Parameters:
  • name (str) – (required), name of the repository
  • 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 = False.
  • license_template (str) – (optional), name of the license; this is ignored if auto_int = False.
Returns:

Repository

create_team(name, repo_names=[], permission=u'')

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:

Team

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:

bool

events(number=-1, etag=None)

Iterate over public events for this org (deprecated).

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

Deprecated: Use public_events instead.

from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

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

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 Events

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 Users

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: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:bool
remove_repository(repository, team_id)

Remove repository from the team with team_id.

Parameters:
  • repository (str) – (required), form: ‘user/repo’
  • team_id (int) – (required)
Returns:

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 Repository

team(team_id)

Return the team specified by team_id.

Parameters:team_id (int) – (required), unique id for the team
Returns: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 Teams


class github3.orgs.Team(json, session=None)

The Team object.

Two team instances can be checked like so:

t1 == t2
t1 != t2

And is equivalent to:

t1.id == t2.id
t1.id != t2.id

See also: http://developer.github.com/v3/orgs/teams/

add_member(username)

Add username to this team.

Parameters:username (str) – the username of the user you would like to add to the team.
Returns:bool
add_repository(repository, permission=u'')

Add repository to this team.

Parameters:
  • repository (str) – (required), form: ‘user/repo’
  • permission (str) – (optional), (‘pull’, ‘push’, ‘admin’)
Returns:

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:bool
edit(name, permission=u'')

Edit this team.

Parameters:
  • name (str) – (required)
  • permission (str) – (optional), (‘pull’, ‘push’, ‘admin’)
Returns:

bool

from_dict(json_dict)

Return an instance of this class formed from json_dict.

from_json(json)

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: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), user to invite to join this team.
Returns:dictionary
is_member(username)

Check if login is a member of this team.

Parameters:username (str) – (required), username name of the user
Returns: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 Users

membership_for(username)

Retrieve the membership information for the user.

Parameters:username (str) – (required), name of the user
Returns:dictionary
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:bool
remove_repository(repository)

Remove repository from this team.

Parameters:repository (str) – (required), form: ‘user/repo’
Returns: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 Repository objects

revoke_membership(username)

Revoke this user’s team membership.

Parameters:username (str) – (required), name of the team member
Returns:bool