Organizations and their Related Objects
This section of the documentation covers the objects that represent data returned by the API for organizations.
Team Objects
- class github3.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
A
URITemplate
instance to either retrieve all members 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 can access.
- slug
The handle for this team or the portion you would use in an at-mention after the
/
, e.g., in@myorg/myteam
the slug ismyteam
.
Please see GitHub’s Team 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 membership has been modified. Options: ‘member’, ‘maintainer’. Default: ‘member’
- Returns:
dictionary of the invitation response
- Return type:
dict
- add_repository(repository, permission='')
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: 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
- 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
.
- 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
- 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:
- 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:
- 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
- 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:
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
- class github3.orgs.Team(json, session: GitHubSession)
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_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 membership has been modified. Options: ‘member’, ‘maintainer’. Default: ‘member’
- Returns:
dictionary of the invitation response
- Return type:
dict
- add_repository(repository, permission='')
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: 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
- 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
.
- 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
- 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:
- 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:
- 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
- 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:
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
- class github3.orgs.Membership(json, session: GitHubSession)
Object describing a user’s membership in teams and organizations.
- organization
A
ShortOrganization
instance representing the organization this membership is part of.
- organization_url
The URL of the organization resource in the API that this membership is 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 to
self.state.lower() == 'active'
.
- pending
Warning
This is a computed attribute, it is not returned by the API.
A boolean attribute equivalent to
self.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
- 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
Organization Objects
- class github3.orgs.ShortOrganization(json, session: GitHubSession)
Object for the shortened representation of an Organization.
GitHub’s API returns different amounts of information about orgs based upon how that information is retrieved. Often times, when iterating over several orgs, GitHub will return less information. To provide a clear distinction between the types of orgs, github3.py uses different classes with 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’s repositories.
- login
The unique username of the organization.
- members_url
The URL to retrieve the members of this organization.
- public_members_urlt
A
uritemplate.URITemplate
that can be expanded to either list the public members of this organization or verify a user is a public member.
- 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 are
member
,admin
. Defaults tomember
.
- Returns:
the created or updated membership
- Return type:
- Raises:
ValueError if role is not a valid choice
- 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
- 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 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:
- cancel_invite(invitee_id)
Cancel the invitation using
invitee_id
of 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)
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_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, 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:
- 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, this will 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), 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.
has_projects (bool) – (optional), If
True
, enable projects for this repository. API default: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 administerrepositories accessible by this team
push
– members can push and pull but not administerrepositories accessible by this team
admin
– members can push, pull and administerrepositories 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 organizationowners and members of this team
closed
– visible to all members of this organization
- Returns:
the created team
- Return type:
- 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 for the organization.
has_repository_projects (bool) – (optional) Toggles whether repository projects are enabled for repositories that belong to the organization.
default_repository_permission (string) –
(optional) Default permission level members have for organization repositories:
read
– (default) can pull, but not push to or administerthis repository.
write
– can pull and push, but not administer thisrepository.
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 to create repositories:
True
– (default) all organization members can createrepositories.
False
– only admin members can create repositories.
- Returns:
True if successful, False otherwise
- Return type:
bool
- failed_invitations()
List failed organization invitations.
- Returns:
bool
- 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
.
- 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: -1 returns 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 user being invited
email (str) – (required if invitee_id is not specified), the email address of the 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 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:
- membership_for(username)
Obtain the membership status of
username
.Implements https://developer.github.com/v3/orgs/members/#get-organization-membership
- Parameters:
username (str) – (required), username name of the user
- Returns:
the membership information
- Return type:
- new_session()
Generate a new session.
- Returns:
A brand new session
- Return type:
- 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:
- 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:
- 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:
- publicize_member(username: str) → bool
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
- 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
- remove_member(username: str) → bool
Remove the user named
username
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)
Remove
username
from this organization.Unlike
remove_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)
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='', 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: int) → Team | None
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_by_name(team_slug: str) → Team | None
Return the team specified by
team_slug
.- Parameters:
team_slug (str) – (required), slug for the team
- Returns:
the team identified by the slug in this organization
- Return type:
- 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:
- 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
- class github3.orgs.Organization(json, session: GitHubSession)
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_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 are
member
,admin
. Defaults tomember
.
- Returns:
the created or updated membership
- Return type:
- Raises:
ValueError if role is not a valid choice
- 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
- 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 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:
- cancel_invite(invitee_id)
Cancel the invitation using
invitee_id
of 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)
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_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, 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:
- 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, this will 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), 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.
has_projects (bool) – (optional), If
True
, enable projects for this repository. API default: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 administerrepositories accessible by this team
push
– members can push and pull but not administerrepositories accessible by this team
admin
– members can push, pull and administerrepositories 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 organizationowners and members of this team
closed
– visible to all members of this organization
- Returns:
the created team
- Return type:
- 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 for the organization.
has_repository_projects (bool) – (optional) Toggles whether repository projects are enabled for repositories that belong to the organization.
default_repository_permission (string) –
(optional) Default permission level members have for organization repositories:
read
– (default) can pull, but not push to or administerthis repository.
write
– can pull and push, but not administer thisrepository.
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 to create repositories:
True
– (default) all organization members can createrepositories.
False
– only admin members can create repositories.
- Returns:
True if successful, False otherwise
- Return type:
bool
- failed_invitations()
List failed organization invitations.
- Returns:
bool
- 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
.
- 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: -1 returns 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 user being invited
email (str) – (required if invitee_id is not specified), the email address of the 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 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:
- membership_for(username)
Obtain the membership status of
username
.Implements https://developer.github.com/v3/orgs/members/#get-organization-membership
- Parameters:
username (str) – (required), username name of the user
- Returns:
the membership information
- Return type:
- new_session()
Generate a new session.
- Returns:
A brand new session
- Return type:
- 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:
- 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:
- 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:
- publicize_member(username: str) → bool
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
- 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
- remove_member(username: str) → bool
Remove the user named
username
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)
Remove
username
from this organization.Unlike
remove_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)
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='', 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: int) → Team | None
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_by_name(team_slug: str) → Team | None
Return the team specified by
team_slug
.- Parameters:
team_slug (str) – (required), slug for the team
- Returns:
the team identified by the slug in this organization
- Return type:
- 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:
- 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