Team Objects

classgithub3.orgs.ShortTeam(json,session:GitHubSession)

Object representing a team in the GitHub API.

id

Unique identifier for this team across all of GitHub.

members_count

The number of members in this team.

members_urlt

AURITemplate instance to either retrieve allmembers in this team or to test if a user is a member.

name

The human-readable name provided to this team.

permission

The level of permissions this team has, e.g.,push,pull,oradmin.

privacy

The privacy level of this team inside the organization.

repos_count

The number of repositories this team can access.

repositories_url

The URL of the resource to enumerate all repositories this team canaccess.

slug

The handle for this team or the portion you would use in anat-mention after the/, e.g., in@myorg/myteam theslug ismyteam.

Please see GitHub’sTeam Documentation for more information.

add_or_update_membership(username,role='member')

Add or update the user’s membership in this team.

This returns a dictionary like so:

{'state':'pending','url':'https://api.github.com/teams/...','role':'member',}

Parameters:

• username (str) – (required), login of user whose membership is being modified

• role (str) – (optional), the role the user should have once their membershiphas been modified. Options: ‘member’, ‘maintainer’. Default:‘member’

Returns:

dictionary of the invitation response

Return type:

dict

add_repository(repository,permission='')

Addrepository to this team.

If a permission is not provided, the team’s default permissionwill 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:str,permission:str='',parent_team_id:int|None=None,privacy:str|None=None)

Edit this team.

Parameters:

• name (str) – (required), the new name of this team

• permission (str) –

  (optional), one of (‘pull’, ‘push’, ‘admin’).. deprecated:: 3.0.0

  This was deprecated by the GitHub API.

• parent_team_id (int) – (optional), id of the parent team for this team

• privacy (str) – (optional), one of “closed” or “secret”

Returns:

True if successful, False otherwise

Return type:

bool

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

has_repository(repository)

Check if this team has access torepository.

Parameters:

repository (str) – (required), form: ‘user/repo’

Returns:

True if the team can access the repository, 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 iteratesover 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

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

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

remove_repository(repository)

Removerepository 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 iteratesover 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:

ShortRepositoryWithPermissions

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

classgithub3.orgs.Team(json,session:GitHubSession)

Object representing a team in the GitHub API.

In addition to the attributes on aShortTeam a Teamhas the following attribute:

created_at

Adatetime instance representing the time and datewhen this team was created.

members_count

The number of members in this team.

organization

AShortOrganization representing theorganization this team belongs to.

repos_count

The number of repositories this team can access.

updated_at

Adatetime instance representing the time and datewhen this team was updated.

Please see GitHub’sTeam Documentation for more information.

add_or_update_membership(username,role='member')

Add or update the user’s membership in this team.

This returns a dictionary like so:

{'state':'pending','url':'https://api.github.com/teams/...','role':'member',}

Parameters:

• username (str) – (required), login of user whose membership is being modified

• role (str) – (optional), the role the user should have once their membershiphas been modified. Options: ‘member’, ‘maintainer’. Default:‘member’

Returns:

dictionary of the invitation response

Return type:

dict

add_repository(repository,permission='')

Addrepository to this team.

If a permission is not provided, the team’s default permissionwill 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:str,permission:str='',parent_team_id:int|None=None,privacy:str|None=None)

Edit this team.

Parameters:

• name (str) – (required), the new name of this team

• permission (str) –

  (optional), one of (‘pull’, ‘push’, ‘admin’).. deprecated:: 3.0.0

  This was deprecated by the GitHub API.

• parent_team_id (int) – (optional), id of the parent team for this team

• privacy (str) – (optional), one of “closed” or “secret”

Returns:

True if successful, False otherwise

Return type:

bool

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

has_repository(repository)

Check if this team has access torepository.

Parameters:

repository (str) – (required), form: ‘user/repo’

Returns:

True if the team can access the repository, 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 iteratesover 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

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

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

remove_repository(repository)

Removerepository 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 iteratesover 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:

ShortRepositoryWithPermissions

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

classgithub3.orgs.Membership(json,session:GitHubSession)

Object describing a user’s membership in teams and organizations.

organization

AShortOrganization instance representing theorganization this membership is part of.

organization_url

The URL of the organization resource in the API that this membershipis part of.

state

The state of this membership, e.g., active or pending.

active

Warning

This is a computed attribute, it is not returned by the API.

A boolean attribute equivalent toself.state.lower()=='active'.

pending

Warning

This is a computed attribute, it is not returned by the API.

A boolean attribute equivalent toself.state.lower()=='pending'.

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

edit(state)

Edit the user’s membership.

Parameters:

state (str) – (required), the state the membership should be in. Only accepts"active".

Returns:

True if successful, False otherwise

Return type:

bool

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

new_session()

Generate a new session.

Returns:

A brand new session

Return type:

GitHubSession

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

Organization Objects

classgithub3.orgs.ShortOrganization(json,session:GitHubSession)

Object for the shortened representation of an Organization.

GitHub’s API returns different amounts of information about orgs basedupon how that information is retrieved. Often times, when iterating overseveral orgs, GitHub will return less information. To provide a cleardistinction between the types of orgs, github3.py uses different classeswith different sets of attributes.

New in version 1.0.0.

avatar_url

The URL of the avatar image for this organization.

description

The user-provided description of this organization.

events_url

The URL to retrieve the events related to this organization.

hooks_url

The URL for the resource to manage organization hooks.

id

The unique identifier for this organization across GitHub.

issues_url

The URL to retrieve the issues across this organization’srepositories.

login

The unique username of the organization.

members_url

The URL to retrieve the members of this organization.

public_members_urlt

Auritemplate.URITemplate that can be expanded to either listthe public members of this organization or verify a user is a publicmember.

repos_url

The URL to retrieve the repositories in this organization.

url

The URL to retrieve this organization from the GitHub API.

type

Deprecated since version 1.0.0:This will be removed in a future release.

Previously returned by the API to indicate the type of the account.

add_or_update_membership(username,role='member')

Add a member or update their role.

Parameters:

• username (str) – (required), user to add or update.

• role (str) – (optional), role to give to the user. Options aremember,admin. Defaults tomember.

Returns:

the created or updated membership

Return type:

Membership

Raises:

ValueError if role is not a valid choice

add_repository(repository,team_id)

Addrepository toteam.

Changed in version 1.0:The second parameter used to beteam but has been changed toteam_id. This parameter is now required to be an integer toimprove 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 overall events available.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of events

Return type:

Event

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

block(username:ShortUser|User|AuthenticatedUser|Collaborator|Contributor|str)→bool

Block a specific user from an organization.

New in version 2.1.0.

Parameters:

username (str) – Name (or user-like instance) of the user to block.

Returns:

True if successful, Fales otherwise

Return type:

bool

blocked_users(number:int=-1,etag:str|None=None)→Iterator[ShortUser]

Iterate over the users blocked by this organization.

New in version 2.1.0.

Parameters:

• number (int) – (optional), number of users to iterate over. Default: -1 iteratesover 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

cancel_invite(invitee_id)

Cancel the invitation usinginvitee_idof the user from the organization.

Parameters:

invitee_id (int) – the identifier for the user being invited, to cancel its invitation

Returns:

bool

conceal_member(username)

Concealusername’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_hook(name,config,events=['push'],active=True)

Create a hook on this organization.

Parameters:

• name (str) – (required), name of the hook

• config (dict) – (required), key-value pairs which act as settings for this hook

• events (list) – (optional), events the hook is triggered for

• active (bool) – (optional), whether the hook is actually triggered

Returns:

the created hook

Return type:

OrganizationHook

create_project(name,body='')

Create a project for this organization.

If the client is authenticated and a member of the organization, thiswill 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='',homepage='',private=False,has_issues=True,has_wiki=True,team_id=0,auto_init=False,gitignore_template='',license_template='',has_projects=True)

Create a repository for this organization.

If the client is authenticated and a member of the organization, thiswill create a new repository in the organization.

name should be no longer than 100 characters

Parameters:

• 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), IfTrue, create a private repository. API default:False

• has_issues (bool) – (optional), IfTrue, enable issues for this repository. APIdefault:True

• has_wiki (bool) – (optional), IfTrue, enable the wiki for this repository. APIdefault:True

• team_id (int) – (optional), id of the team that will be granted access to thisrepository

• auto_init (bool) – (optional), auto initialize the repository.

• gitignore_template (str) – (optional), name of the template; this is ignored if auto_int isFalse.

• license_template (str) – (optional), name of the license; this is ignored if auto_int isFalse.

• has_projects (bool) – (optional), IfTrue, enable projects for this repository. APIdefault:True

Returns:

the created repository

Return type:

Repository

create_team(name:str,repo_names:Sequence[str]|None=[],maintainers:Sequence[str]|Sequence[_users._User]|None=[],permission:str='pull',parent_team_id:int|None=None,privacy:str='secret')

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’]

• maintainers (list) – (optional) list of usernames who will be maintainers

• 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

• parent_team_id (int) – (optional), the ID of a team to set as the parent team.

• privacy (str) –

  (optional), options:

  • secret – (default) only visible to organization

    owners and members of this team

  • closed – visible to all members of this organization

Returns:

the created team

Return type:

Team

edit(billing_email=None,company=None,email=None,location=None,name=None,description=None,has_organization_projects=None,has_repository_projects=None,default_repository_permission=None,members_can_create_repositories=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)

• description (str) – (optional) The description of the company.

• has_organization_projects (bool) – (optional) Toggles whether organization projects are enabled forthe organization.

• has_repository_projects (bool) – (optional) Toggles whether repository projects are enabled forrepositories that belong to the organization.

• default_repository_permission (string) –

  (optional) Default permission level members have for organizationrepositories:

  • read – (default) can pull, but not push to or administer

    this repository.

  • write – can pull and push, but not administer this

    repository.

  • admin – can pull, push, and administer this repository.

  • none – no permissions granted by default.

• members_can_create_repositories (bool) –

  (optional) Toggles ability of non-admin organization members tocreate repositories:

  • True – (default) all organization members can create

    repositories.

  • False – only admin members can create repositories.

Returns:

True if successful, False otherwise

Return type:

bool

failed_invitations()

List failed organization invitations.

Returns:

bool

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

hook(hook_id)

Get a single hook.

Parameters:

hook_id (int) – (required), id of the hook

Returns:

the hook

Return type:

OrganizationHook

hooks(number=-1,etag=None)

Iterate over hooks registered on this organization.

Parameters:

• number (int) – (optional), number of hoks to return. Default: -1returns all hooks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of hooks

Return type:

OrganizationHook

invitations(number=-1,etag=None)

Iterate over outstanding invitations to this organization.

Returns:

generator of invitation objects

Return type:

Invitation

invite(team_ids,invitee_id=None,email=None,role='direct_member')

Invite the user to join this organization.

Parameters:

• team_ids (list[int]) – (required), list of team identifiers to invite the user to

• invitee_id (int) – (required if email is not specified), the identifier for the userbeing invited

• email (str) – (required if invitee_id is not specified), the email address ofthe user being invited

• role (str) – (optional) role to provide to the invited user. Must be one of

Returns:

the created invitation

Return type:

Invitation

is_blocking(username:ShortUser|User|AuthenticatedUser|Collaborator|Contributor|str)→bool

Check if this organization is blocking a specific user.

New in version 2.1.0.

Parameters:

username (str) – Name (or user-like instance) of the user to unblock.

Returns:

True if successful, Fales otherwise

Return type:

bool

is_member(username)

Check if the user namedusername 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 namedusername 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 withprivate 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 returnall available.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of members of this organization

Return type:

ShortUser

membership_for(username)

Obtain the membership status ofusername.

Implementshttps://developer.github.com/v3/orgs/members/#get-organization-membership

Parameters:

username (str) – (required), username name of the user

Returns:

the membership information

Return type:

Membership

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 returnall 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 overall events available.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator of public events

Return type:

Event

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 returnall available.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of public members

Return type:

ShortUser

publicize_member(username:str)→bool

Makeusername’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

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

remove_member(username:str)→bool

Remove the user namedusername from this organization.

Note

Only a user may publicize their own membership. See also:https://developer.github.com/v3/orgs/members/#publicize-a-users-membership

Parameters:

username (str) – name of the user to remove from the org

Returns:

True if successful, False otherwise

Return type:

bool

remove_membership(username)

Removeusername from this organization.

Unlikeremove_member, this will cancel a pending invitation.

Parameters:

username (str) – (required), username of the member to remove

Returns:

bool

remove_repository(repository:Repository|ShortRepository|str,team_id:int)

Removerepository 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='',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 returnall 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:int)→Team|None

Return the team specified byteam_id.

Parameters:

team_id (int) – (required), unique id for the team

Returns:

the team identified by the id in this organization

Return type:

Team

team_by_name(team_slug:str)→Team|None

Return the team specified byteam_slug.

Parameters:

team_slug (str) – (required), slug for the team

Returns:

the team identified by the slug 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 allavailable teams.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of this organization’s teams

Return type:

ShortTeam

unblock(username:ShortUser|User|AuthenticatedUser|Collaborator|Contributor|str)→bool

Unblock a specific user from an organization.

New in version 2.1.0.

Parameters:

username (str) – Name (or user-like instance) of the user to unblock.

Returns:

True if successful, Fales otherwise

Return type:

bool

classgithub3.orgs.Organization(json,session:GitHubSession)

Object for the full representation of a Organization.

GitHub’s API returns different amounts of information about orgs basedupon how that information is retrieved. This object exists to representthe full amount of information returned for a specific org. For example,you would receive this class when callingorganization(). To provide a cleardistinction between the types of orgs, github3.py uses different classeswith different sets of attributes.

Changed in version 1.0.0.

This object includes all attributes onShortOrganization 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

Adatetime instance representing the time and datewhen this organization was created.

email

The email address associated with this organization.

followers_count

The number of users following this organization. Organizations nolonger have followers so this number will always be 0.

following_count

The number of users this organization follows. Organizations nolonger 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_or_update_membership(username,role='member')

Add a member or update their role.

Parameters:

• username (str) – (required), user to add or update.

• role (str) – (optional), role to give to the user. Options aremember,admin. Defaults tomember.

Returns:

the created or updated membership

Return type:

Membership

Raises:

ValueError if role is not a valid choice

add_repository(repository,team_id)

Addrepository toteam.

Changed in version 1.0:The second parameter used to beteam but has been changed toteam_id. This parameter is now required to be an integer toimprove 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 overall events available.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of events

Return type:

Event

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

block(username:ShortUser|User|AuthenticatedUser|Collaborator|Contributor|str)→bool

Block a specific user from an organization.

New in version 2.1.0.

Parameters:

username (str) – Name (or user-like instance) of the user to block.

Returns:

True if successful, Fales otherwise

Return type:

bool

blocked_users(number:int=-1,etag:str|None=None)→Iterator[ShortUser]

Iterate over the users blocked by this organization.

New in version 2.1.0.

Parameters:

• number (int) – (optional), number of users to iterate over. Default: -1 iteratesover 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

cancel_invite(invitee_id)

Cancel the invitation usinginvitee_idof the user from the organization.

Parameters:

invitee_id (int) – the identifier for the user being invited, to cancel its invitation

Returns:

bool

conceal_member(username)

Concealusername’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_hook(name,config,events=['push'],active=True)

Create a hook on this organization.

Parameters:

• name (str) – (required), name of the hook

• config (dict) – (required), key-value pairs which act as settings for this hook

• events (list) – (optional), events the hook is triggered for

• active (bool) – (optional), whether the hook is actually triggered

Returns:

the created hook

Return type:

OrganizationHook

create_project(name,body='')

Create a project for this organization.

If the client is authenticated and a member of the organization, thiswill 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='',homepage='',private=False,has_issues=True,has_wiki=True,team_id=0,auto_init=False,gitignore_template='',license_template='',has_projects=True)

Create a repository for this organization.

If the client is authenticated and a member of the organization, thiswill create a new repository in the organization.

name should be no longer than 100 characters

Parameters:

• 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), IfTrue, create a private repository. API default:False

• has_issues (bool) – (optional), IfTrue, enable issues for this repository. APIdefault:True

• has_wiki (bool) – (optional), IfTrue, enable the wiki for this repository. APIdefault:True

• team_id (int) – (optional), id of the team that will be granted access to thisrepository

• auto_init (bool) – (optional), auto initialize the repository.

• gitignore_template (str) – (optional), name of the template; this is ignored if auto_int isFalse.

• license_template (str) – (optional), name of the license; this is ignored if auto_int isFalse.

• has_projects (bool) – (optional), IfTrue, enable projects for this repository. APIdefault:True

Returns:

the created repository

Return type:

Repository

create_team(name:str,repo_names:Sequence[str]|None=[],maintainers:Sequence[str]|Sequence[_users._User]|None=[],permission:str='pull',parent_team_id:int|None=None,privacy:str='secret')

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’]

• maintainers (list) – (optional) list of usernames who will be maintainers

• 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

• parent_team_id (int) – (optional), the ID of a team to set as the parent team.

• privacy (str) –

  (optional), options:

  • secret – (default) only visible to organization

    owners and members of this team

  • closed – visible to all members of this organization

Returns:

the created team

Return type:

Team

edit(billing_email=None,company=None,email=None,location=None,name=None,description=None,has_organization_projects=None,has_repository_projects=None,default_repository_permission=None,members_can_create_repositories=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)

• description (str) – (optional) The description of the company.

• has_organization_projects (bool) – (optional) Toggles whether organization projects are enabled forthe organization.

• has_repository_projects (bool) – (optional) Toggles whether repository projects are enabled forrepositories that belong to the organization.

• default_repository_permission (string) –

  (optional) Default permission level members have for organizationrepositories:

  • read – (default) can pull, but not push to or administer

    this repository.

  • write – can pull and push, but not administer this

    repository.

  • admin – can pull, push, and administer this repository.

  • none – no permissions granted by default.

• members_can_create_repositories (bool) –

  (optional) Toggles ability of non-admin organization members tocreate repositories:

  • True – (default) all organization members can create

    repositories.

  • False – only admin members can create repositories.

Returns:

True if successful, False otherwise

Return type:

bool

failed_invitations()

List failed organization invitations.

Returns:

bool

classmethodfrom_dict(json_dict,session)

Return an instance of this class formed fromjson_dict.

classmethodfrom_json(json,session)

Return an instance of this class formed fromjson.

hook(hook_id)

Get a single hook.

Parameters:

hook_id (int) – (required), id of the hook

Returns:

the hook

Return type:

OrganizationHook

hooks(number=-1,etag=None)

Iterate over hooks registered on this organization.

Parameters:

• number (int) – (optional), number of hoks to return. Default: -1returns all hooks

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of hooks

Return type:

OrganizationHook

invitations(number=-1,etag=None)

Iterate over outstanding invitations to this organization.

Returns:

generator of invitation objects

Return type:

Invitation

invite(team_ids,invitee_id=None,email=None,role='direct_member')

Invite the user to join this organization.

Parameters:

• team_ids (list[int]) – (required), list of team identifiers to invite the user to

• invitee_id (int) – (required if email is not specified), the identifier for the userbeing invited

• email (str) – (required if invitee_id is not specified), the email address ofthe user being invited

• role (str) – (optional) role to provide to the invited user. Must be one of

Returns:

the created invitation

Return type:

Invitation

is_blocking(username:ShortUser|User|AuthenticatedUser|Collaborator|Contributor|str)→bool

Check if this organization is blocking a specific user.

New in version 2.1.0.

Parameters:

username (str) – Name (or user-like instance) of the user to unblock.

Returns:

True if successful, Fales otherwise

Return type:

bool

is_member(username)

Check if the user namedusername 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 namedusername 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 withprivate 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 returnall available.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of members of this organization

Return type:

ShortUser

membership_for(username)

Obtain the membership status ofusername.

Implementshttps://developer.github.com/v3/orgs/members/#get-organization-membership

Parameters:

username (str) – (required), username name of the user

Returns:

the membership information

Return type:

Membership

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 returnall 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 overall events available.

• etag (str) – (optional), ETag from a previous request to the sameendpoint

Returns:

generator of public events

Return type:

Event

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 returnall available.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of public members

Return type:

ShortUser

publicize_member(username:str)→bool

Makeusername’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

propertyratelimit_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()forring.repositories_by('kennethreitz')]

Without the return value, that would be an array ofNone’s and youwould otherwise have to do:

repos=[rforiing.repositories_by('kennethreitz')][r.refresh()forrinrepos]

Which is really an anti-pattern.

Changed in version 0.5.

Parameters:

conditional (bool) – If True, then we will search for a storedheader (‘Last-Modified’, or ‘ETag’) on the object and send thatas described in theConditional Requests section of the docs

Returns:

self

remove_member(username:str)→bool

Remove the user namedusername from this organization.

Note

Only a user may publicize their own membership. See also:https://developer.github.com/v3/orgs/members/#publicize-a-users-membership

Parameters:

username (str) – name of the user to remove from the org

Returns:

True if successful, False otherwise

Return type:

bool

remove_membership(username)

Removeusername from this organization.

Unlikeremove_member, this will cancel a pending invitation.

Parameters:

username (str) – (required), username of the member to remove

Returns:

bool

remove_repository(repository:Repository|ShortRepository|str,team_id:int)

Removerepository 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='',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 returnall 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:int)→Team|None

Return the team specified byteam_id.

Parameters:

team_id (int) – (required), unique id for the team

Returns:

the team identified by the id in this organization

Return type:

Team

team_by_name(team_slug:str)→Team|None

Return the team specified byteam_slug.

Parameters:

team_slug (str) – (required), slug for the team

Returns:

the team identified by the slug 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 allavailable teams.

• etag (str) – (optional), ETag from a previous request to the same endpoint

Returns:

generator of this organization’s teams

Return type:

ShortTeam

unblock(username:ShortUser|User|AuthenticatedUser|Collaborator|Contributor|str)→bool

Unblock a specific user from an organization.

New in version 2.1.0.

Parameters:

username (str) – Name (or user-like instance) of the user to unblock.

Returns:

True if successful, Fales otherwise

Return type:

bool