"""Implementation of a branch on a repository.""" import typing as t from . import commit from .. import decorators from .. import models if t.TYPE_CHECKING: from .. import apps as tapps from .. import users as tusers from . import orgs class _Branch(models.GitHubCore): """A representation of a branch on a repository. See also https://developer.github.com/v3/repos/branches/ This object has the following attributes: """ # The Accept header will likely be removable once the feature is out of # preview mode. See: http://git.io/v4O1e PREVIEW_HEADERS = {"Accept": "application/vnd.github.loki-preview+json"} class_name = "Repository Branch" def _update_attributes(self, branch): self.commit = commit.MiniCommit(branch["commit"], self) self.name = branch["name"] base = self.commit.url.split("/commit", 1)[0] self._api = self._build_url("branches", self.name, base_url=base) def _repr(self): return f"<{self.class_name} [{self.name}]>" def latest_sha(self, differs_from=""): """Check if SHA-1 is the same as the remote branch. See: https://git.io/vaqIw :param str differs_from: (optional), sha to compare against :returns: string of the SHA or None :rtype: str on Python 3 """ # If-None-Match returns 200 instead of 304 value does not have quotes headers = { "Accept": "application/vnd.github.v3.sha", "If-None-Match": f'"{differs_from}"', } base = self._api.split("/branches", 1)[0] url = self._build_url("commits", self.name, base_url=base) resp = self._get(url, headers=headers) if self._boolean(resp, 200, 304): return resp.text return None @decorators.requires_auth def protection(self) -> "BranchProtection": """Retrieve the protections enabled for this branch. See: https://developer.github.com/v3/repos/branches/#get-branch-protection :returns: The protections enabled for this branch. :rtype: :class:`~github3.repos.branch.BranchProtection` """ url = self._build_url("protection", base_url=self._api) resp = self._get(url) json = self._json(resp, 200) return BranchProtection(json, self) @decorators.requires_auth def protect( self, required_status_checks: t.Optional[t.Mapping[str, t.Any]], enforce_admins: t.Optional[bool], required_pull_request_reviews: t.Optional[t.Mapping[str, t.Any]], restrictions: t.Optional[t.Mapping[str, t.Sequence[str]]], required_linear_history: t.Optional[bool] = None, allow_force_pushes: t.Optional[bool] = None, allow_deletions: t.Optional[bool] = None, required_conversation_resolution: t.Optional[bool] = None, ) -> "BranchProtection": """Enable force push protection and configure status check enforcement. See also: https://docs.github.com/en/rest/reference/repos#update-branch-protection .. versionchanged:: 3.0.0 The GitHub API changed since the last release this was updated in. As such the parameters have to change here. :param requireed_status_checks: Required. Require status checks to pass before merging. Set to null to disable. :param enforce_admins: Required. Enforce all configured restrictions for administrators. Set to true to enforce required status checks for repository administrators. Set to null to disable. :param required_pull_request_reviews: Required. Require at least one approving review on a pull request, before merging. Set to null to disable. :param restrictions: Required. Restrict who can push to the protected branch. User, app, and team restrictions are only available for organization-owned repositories. Set to null to disable. :param required_linear_history: Enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch. Set to true to enforce a linear commit history. Set to false to disable a linear commit Git history. Your repository must allow squash merging or rebase merging before you can enable a linear commit history. Default: false. For more information, see "Requiring a linear commit history" in the GitHub Help documentation. :param allow_force_pushes: Permits force pushes to the protected branch by anyone with write access to the repository. Set to true to allow force pushes. Set to false or null to block force pushes. Default: false. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation." :param allow_deletions: Allows deletion of the protected branch by anyone with write access to the repository. Set to false to prevent deletion of the protected branch. Default: false. For more information, see "Enabling force pushes to a protected branch" in the GitHub Help documentation. :param required_conversation_resolution: Requires all conversations on code to be resolved before a pull request can be merged into a branch that matches this rule. Set to false to disable. Default: false. :returns: BranchProtection if successful :rtype: :class:`BranchProtection` """ edit = { "required_status_checks": required_status_checks, "enforce_admins": enforce_admins, "required_pull_request_reviews": required_pull_request_reviews, "restrictions": restrictions, } if required_linear_history is not None: edit["required_linear_history"] = required_linear_history if allow_force_pushes is not None: edit["allow_force_pushes"] = allow_force_pushes if allow_deletions is not None: edit["allow_deletions"] = allow_deletions if required_conversation_resolution is not None: edit[ "required_conversation_resolution" ] = required_conversation_resolution url = self._build_url("protection", base_url=self._api) resp = self._put(url, json=edit) json = self._json(resp, 200) return BranchProtection(json, self) @decorators.requires_auth def sync_with_upstream(self) -> t.Mapping[str, str]: """Synchronize this branch with the upstream. .. warning:: This API endpoint is still in Beta per gitHub .. versionadded:: 3.0.0 Sync a branch of a forked repository to keep it up-to-date with the upstream repository. See also: https://docs.github.com/en/rest/reference/repos#sync-a-fork-branch-with-the-upstream-repository :returns: The dictionary described in the documentation :rtype: dict """ base = self._api.split("/branches", 1)[0] url = self._build_url("merge-upstream", base_url=base) json = self._json(self._post(url), 200) return json @decorators.requires_auth def unprotect(self) -> bool: """Disable protections on this branch.""" return self._boolean( self._delete(self._build_url("protection", base_url=self._api)), 200, 403, ) class Branch(_Branch): """The representation of a branch returned in a collection. GitHub's API returns different amounts of information about repositories based upon how that information is retrieved. This object exists to represent the limited amount of information returned for a specific branch in a collection. For example, you would receive this class when calling :meth:`~github3.repos.repo.Repository.branches`. To provide a clear distinction between the types of branches, github3.py uses different classes with different sets of attributes. This object has the same attributes as a :class:`~github3.repos.branch.ShortBranch` as well as the following: .. attribute:: links The dictionary of URLs returned by the API as ``_links``. .. attribute:: protected A boolean attribute that describes whether this branch is protected or not. .. attribute:: original_protection .. versionchanged:: 1.1.0 To support a richer branch protection API, this is the new name for the information formerly stored under the attribute ``protection``. A dictionary with details about the protection configuration of this branch. .. attribute:: protection_url The URL to access and manage details about this branch's protection. """ class_name = "Repository Branch" def _update_attributes(self, branch): super()._update_attributes(branch) self.commit = commit.ShortCommit(branch["commit"], self) #: Returns '_links' attribute. self.links = branch["_links"] #: Provides the branch's protection status. self.protected = branch["protected"] self.original_protection = branch["protection"] self.protection_url = branch["protection_url"] if self.links and "self" in self.links: self._api = self.links["self"] class ShortBranch(_Branch): """The representation of a branch returned in a collection. GitHub's API returns different amounts of information about repositories based upon how that information is retrieved. This object exists to represent the limited amount of information returned for a specific branch in a collection. For example, you would receive this class when calling :meth:`~github3.repos.repo.Repository.branches`. To provide a clear distinction between the types of branches, github3.py uses different classes with different sets of attributes. This object has the following attributes: .. attribute:: commit A :class:`~github3.repos.commit.MiniCommit` representation of the newest commit on this branch with the associated repository metadata. .. attribute:: name The name of this branch. """ class_name = "Short Repository Branch" _refresh_to = Branch @t.overload def refresh(self, conditional: bool = False) -> Branch: # noqa: D102 ... class BranchProtection(models.GitHubCore): """The representation of a branch's protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection .. versionchanged:: 3.0.0 Added ``required_linear_history``, ``allow_force_pushes``, ``allow_deletions``, and ``required_conversation_resolution``. This object has the following attributes: .. attribute:: enforce_admins A :class:`~github3.repos.branch.ProtectionEnforceAdmins` instance representing whether required status checks are required for admins. .. attribute:: restrictions A :class:`~github3.repos.branch.ProtectionRestrictions` representing who can push to this branch. Team and user restrictions are only available for organization-owned repositories. .. attribute:: required_pull_request_reviews A :class:`~github3.repos.branch.ProtectionRequiredPullRequestReviews` representing the protection provided by requiring pull request reviews. .. attribute:: required_status_checks A :class:`~github3.repos.branch.ProtectionRequiredStatusChecks` representing the protection provided by requiring status checks. .. attribute:: required_linear_history .. versionadded:: 3.0.0 A :class:`~github3.repos.branch.ProtectionRequiredLinearHistory` representing the information returned by the API about this protection. .. attribute:: allow_force_pushes .. versionadded:: 3.0.0 A :class:`~github3.repos.branch.ProtectionAllowForcePushes` representing the information returned by the API about this protection. .. attribute:: allow_deletions .. versionadded:: 3.0.0 A :class:`~github3.repos.branch.ProtectionAllowDeletions` representing the information returned by the API about this protection. .. attribute:: required_conversation_resolution .. versionadded:: 3.0.0 A :class:`~github3.repos.branch.ProtectionRequiredConversationResolution` representing the information returned by the API about this protection. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection """ def _update_attributes(self, protection): self._api = protection["url"] def _set_conditional_attr(name, cls): value = protection.get(name) setattr(self, name, value) if getattr(self, name): setattr(self, name, cls(value, self)) _set_conditional_attr("enforce_admins", ProtectionEnforceAdmins) _set_conditional_attr("restrictions", ProtectionRestrictions) _set_conditional_attr( "required_pull_request_reviews", ProtectionRequiredPullRequestReviews, ) _set_conditional_attr( "required_status_checks", ProtectionRequiredStatusChecks ) _set_conditional_attr( "required_linear_history", ProtectionRequiredLinearHistory ) _set_conditional_attr( "allow_force_pushes", ProtectionAllowForcePushes ) _set_conditional_attr("allow_deleteions", ProtectionAllowDeletions) _set_conditional_attr( "required_conversation_resolution", ProtectionRequiredConversationResolution, ) @decorators.requires_auth def update( self, enforce_admins=None, required_status_checks=None, required_pull_request_reviews=None, restrictions=None, ): """Enable force push protection and configure status check enforcement. See: http://git.io/v4Gvu :param str enforce_admins: (optional), Specifies the enforcement level of the status checks. Must be one of 'off', 'non_admins', or 'everyone'. Use `None` or omit to use the already associated value. :param list required_status_checks: (optional), A list of strings naming status checks that must pass before merging. Use `None` or omit to use the already associated value. :param obj required_pull_request_reviews: (optional), Object representing the configuration of Request Pull Request Reviews settings. Use `None` or omit to use the already associated value. :param obj restrictions: (optional), Object representing the configuration of Restrictions. Use `None` or omit to use the already associated value. :returns: Updated branch protection :rtype: :class:`~github3.repos.branch.BranchProtection` """ current_status = { "enforce_admins": getattr(self.enforce_admins, "enabled", False), "required_status_checks": ( self.required_status_checks.as_dict() if self.required_status_checks is not None else None ), "required_pull_request_reviews": ( self.required_pull_request_reviews.as_dict() if self.required_pull_request_reviews is not None else None ), "restrictions": ( self.restrictions.as_dict() if self.restrictions is not None else None ), } edit = { "enabled": True, "enforce_admins": ( enforce_admins if enforce_admins is not None else current_status["enforce_admins"] ), "required_status_checks": ( required_status_checks if required_status_checks is not None else current_status["required_status_checks"] ), "required_pull_request_reviews": ( required_pull_request_reviews if required_pull_request_reviews is not None else current_status["required_pull_request_reviews"] ), "restrictions": ( restrictions if restrictions is not None else current_status["restrictions"] ), } json = self._json(self._put(self._api, json=edit), 200) self._update_attributes(json) return self @decorators.requires_auth def delete(self) -> bool: """Remove branch protection. :returns: True if successful, False otherwise :rtype: bool """ resp = self._delete(self._api) return self._boolean(resp, 204, 404) @decorators.requires_auth def requires_signatures(self) -> bool: """Check if commit signatures are presently required. :returns: True if enabled, False otherwise :rtype: bool """ url = self._build_url("required_signatures", base_url=self._api) resp = self._get(url) if resp.status_code == 200: return resp.json()["enabled"] return False @decorators.requires_auth def require_signatures(self) -> bool: """Require commit signatures for commits to this branch. :returns: True if successful, False otherwise :rtype: bool """ url = self._build_url("required_signatures", base_url=self._api) resp = self._post(url) return self._boolean(resp, 200, 404) @decorators.requires_auth def delete_signature_requirements(self) -> bool: """Stop requiring commit signatures for commits to this branch. :returns: True if successful, False otherwise :rtype: bool """ url = self._build_url("required_signatures", base_url=self._api) resp = self._delete(url) return self._boolean(resp, 200, 404) class ProtectionEnforceAdmins(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection `Admin enforcement of protected branch`_ GitHub's documentation of protecting a branch with admins This object has the following attributes: .. attribute:: enabled A boolean attribute indicating whether the ``enforce_admins`` protection is enabled or disabled. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection .. _Admin enforcement of protected branch: https://developer.github.com/v3/repos/branches/#get-admin-enforcement-of-protected-branch """ def _update_attributes(self, protection): self._api = protection["url"] self.enabled = protection["enabled"] @decorators.requires_auth def enable(self): """Enable Admin enforcement for protected branch.""" resp = self._post(self._api) return self._boolean(resp, 200, 404) @decorators.requires_auth def disable(self): """Disable Admin enforcement for protected branch.""" resp = self._delete(self._api) return self._boolean(resp, 204, 404) class ProtectionRestrictions(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection `Branch restriction documentation`_ GitHub's description of branch restriction This object has the following attributes: .. attribute:: original_teams List of :class:`~github3.orgs.ShortTeam` objects representing the teams allowed to push to the protected branch. .. attribute:: original_users List of :class:`~github3.users.ShortUser` objects representing the users allowed to push to the protected branch. .. attribute:: teams_url The URL to retrieve the list of teams allowed to push to the protected branch. .. attribute:: users_url The URL to retrieve the list of users allowed to push to the protected branch. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection .. _Branch restriction documentation: https://help.github.com/articles/about-branch-restrictions """ def _update_attributes(self, protection): from .. import apps, orgs, users self._api = protection["url"] self.users_url = protection["users_url"] self.teams_url = protection["teams_url"] self.apps_url = protection.get("apps_url") self.original_users = protection["users"] if self.original_users: self.original_users = [ users.ShortUser(user, self) for user in self.original_users ] self.original_teams = protection["teams"] if self.original_teams: self.original_teams = [ orgs.ShortTeam(team, self) for team in self.original_teams ] self.original_apps = protection.get("apps") if self.original_apps: self.original_apps = [ apps.App(app, self) for app in self.original_apps ] @decorators.requires_auth def add_teams( self, teams: t.Sequence[str] ) -> t.Sequence["orgs.ShortTeam"]: """Add teams to the protected branch. See: https://developer.github.com/v3/repos/branches/#add-team-restrictions-of-protected-branch .. warning:: This will not update the object to replace the ``original_teams`` attribute. :param list teams: The list of the team names to have access to interact with protected branch. :returns: List of added teams :rtype: List[github3.orgs.ShortTeam] """ from .. import orgs resp = self._post(self.teams_url, data=teams) json = self._json(resp, 200) return [orgs.ShortTeam(team, self) for team in json] if json else [] @decorators.requires_auth def add_users( self, users: t.Sequence[str] ) -> t.Sequence["tusers.ShortUser"]: """Add users to protected branch. See https://developer.github.com/v3/repos/branches/#add-user-restrictions-of-protected-branch .. warning:: This will not update the object to replace the ``original_users`` attribute. :param list users: The list of the user logins to have access to interact with protected branch. :returns: List of added users :rtype: List[github3.users.ShortUser] """ from .. import users as _users json = self._json(self._post(self.users_url, data=users), 200) return [_users.ShortUser(user, self) for user in json] if json else [] @decorators.requires_auth def apps(self, number: int = -1) -> t.Generator["tapps.App", None, None]: """Retrieve current list of apps with access to the protected branch. See https://docs.github.com/en/rest/reference/repos#get-apps-with-access-to-the-protected-branch .. warning:: This will not update the object to replace the ``original_apps`` attribute. :param int number: Limit the number of apps returned :returns: An iterator of apps :rtype: :class:`~github3.apps.App` """ from .. import apps return self._iter(int(number), self.apps_url, apps.App) @decorators.requires_auth def add_app_restrictions( self, apps: t.Sequence[t.Union["tapps.App", str]] ) -> t.List["tapps.App"]: """Grant app push access to the current branch. See https://docs.github.com/en/rest/reference/repos#add-app-access-restrictions Per GitHub's documentation above: Grants the specified apps push access for this branch. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch. :param list apps: List of slugs of apps to grant push access to the protected branch. If you pass a list of :class:`~github3.apps.App` then the library will retrieve the slug for you. :returns: List of apps with push access to the protected branch :rtype: List[:class:`~github3.apps.App`] """ from .. import apps as _apps apps = [getattr(a, "slug", a) for a in apps] json = self._json(self._post(self.apps_url, data=apps), 200) return [_apps.App(a, self) for a in json] @decorators.requires_auth def replace_app_restrictions( self, apps: t.Sequence[t.Union["tapps.App", str]] ) -> t.List["tapps.App"]: """Replace existing app push access with only those specified. See https://docs.github.com/en/rest/reference/repos#set-app-access-restrictions Per GitHub's documentation above: Replaces the list of apps that have push access to this branch. This removes all apps that previously had push access and grants push access to the new list of apps. Only installed GitHub Apps with write access to the contents permission can be added as authorized actors on a protected branch. :param list apps: List of slugs of apps to grant push access to the protected branch. If you pass a list of :class:`~github3.apps.App` then the library will retrieve the slug for you. :returns: List of apps with push access to the protected branch :rtype: List[:class:`~github3.apps.App`] """ from .. import apps as _apps apps = [getattr(a, "slug", a) for a in apps] json = self._json(self._put(self.apps_url, data=apps), 200) return [_apps.App(a, self) for a in json] @decorators.requires_auth def remove_app_restrictions( self, apps: t.Sequence[t.Union["tapps.App", str]] ) -> t.List["tapps.App"]: """Remove the apps' push access to the protected branch. See https://docs.github.com/en/rest/reference/repos#remove-app-access-restrictions :param list apps: List of slugs of apps to revoke push access to the protected branch. If you pass a list of :class:`~github3.apps.App` then the library will retrieve the slug for you. :returns: List of apps that still have push access :rtype: List[:class:`~github3.apps.App`] """ from .. import apps as _apps apps = [getattr(a, "slug", a) for a in apps] json = self._json(self._delete(self.apps_url, data=apps), 200) return [_apps.App(a, self) for a in json] @decorators.requires_auth def delete(self) -> bool: """Completely remove restrictions of the protected branch. See https://developer.github.com/v3/repos/branches/#remove-user-restrictions-of-protected-branch :returns: True if successful, False otherwise. :rtype: bool """ resp = self._delete(self._api) return self._boolean(resp, 204, 404) @decorators.requires_auth def remove_teams( self, teams: t.Sequence[str] ) -> t.Sequence["orgs.ShortTeam"]: """Remove teams from protected branch. See https://developer.github.com/v3/repos/branches/#remove-team-restrictions-of-protected-branch :param list teams: The list of the team names to stop having access to interact with protected branch. :returns: List of removed teams :rtype: List[github3.orgs.ShortTeam] """ from .. import orgs resp = self._delete(self.teams_url, json=teams) json = self._json(resp, 200) return [orgs.ShortTeam(team, self) for team in json] if json else [] @decorators.requires_auth def remove_users( self, users: t.Sequence[str] ) -> t.Sequence["tusers.ShortUser"]: """Remove users from protected branch. See https://developer.github.com/v3/repos/branches/#remove-user-restrictions-of-protected-branch :param list users: The list of the user logins to stop having access to interact with protected branch. :returns: List of removed users :rtype: List[github3.users.ShortUser] """ resp = self._delete(self.users_url, json=users) json = self._json(resp, 200) from .. import users as _users return [_users.ShortUser(user, self) for user in json] if json else [] @decorators.requires_auth def replace_teams( self, teams: t.Sequence[str] ) -> t.Sequence["orgs.ShortTeam"]: """Replace teams that will have access to protected branch. See https://developer.github.com/v3/repos/branches/#replace-team-restrictions-of-protected-branch :param list teams: The list of the team names to have access to interact with protected branch. :returns: List of teams that now have access to the protected branch :rtype: List[github3.orgs.ShortTeam] """ from .. import orgs resp = self._put(self.teams_url, json=teams) json = self._json(resp, 200) return [orgs.ShortTeam(team, self) for team in json] if json else [] @decorators.requires_auth def replace_users( self, users: t.Sequence[str] ) -> t.Sequence["tusers.ShortUser"]: """Replace users that will have access to protected branch. See https://developer.github.com/v3/repos/branches/#replace-user-restrictions-of-protected-branch :param list users: The list of the user logins to have access to interact with protected branch. :returns: List of users that now have access to the protected branch :rtype: List[github3.users.ShortUser] """ users_resp = self._put(self.users_url, json=users) return self._boolean(users_resp, 200, 404) def teams( self, number: int = -1 ) -> t.Generator["orgs.ShortTeam", None, None]: """Retrieve an up-to-date listing of teams. :returns: An iterator of teams :rtype: :class:`~github3.orgs.ShortTeam` """ from .. import orgs return self._iter( int(number), self.teams_url, orgs.ShortTeam, ) def users( self, number: int = -1 ) -> t.Generator["tusers.ShortUser", None, None]: """Retrieve an up-to-date listing of users. :returns: An iterator of users :rtype: :class:`~github3.users.ShortUser` """ from .. import users return self._iter(int(number), self.users_url, users.ShortUser) class ProtectionRequiredPullRequestReviews(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection. `Branch Required Pull Request Reviews`_ GitHub's documentation of required pull request review protections This object has the folllowing attributes: .. attribute:: dismiss_stale_reviews A boolean attribute describing whether stale pull request reviews should be automatically dismissed by GitHub. .. attribute:: dismissal_restrictions If specified, a :class:`~github3.repos.branch.ProtectionRestrictions` object describing the dismissal restrictions for pull request reviews. .. attribute:: require_code_owner_reviews A boolean attribute describing whether to require "code owners" to review a pull request before it may be merged. .. attribute:: required_approving_review_count An integer describing the number (between 1 and 6) of reviews required before a pull request may be merged. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection .. _Branch Required Pull Request Reviews: https://developer.github.com/v3/repos/branches/#get-pull-request-review-enforcement-of-protected-branch """ def _update_attributes(self, protection): self._api = protection["url"] self.dismiss_stale_reviews = protection["dismiss_stale_reviews"] # Use a temporary value to stay under line-length restrictions value = protection["require_code_owner_reviews"] self.require_code_owner_reviews = value # Use a temporary value to stay under line-length restrictions value = protection["required_approving_review_count"] self.required_approving_review_count = value self.dismissal_restrictions = None if "dismissal_restrictions" in protection: self.dismissal_restrictions = ProtectionRestrictions( protection["dismissal_restrictions"], self ) @decorators.requires_auth def update( self, dismiss_stale_reviews=None, require_code_owner_reviews=None, required_approving_review_count=None, dismissal_restrictions=None, ): """Update the configuration for the Required Pull Request Reviews. :param bool dismiss_stale_reviews: Whether or not to dismiss stale pull request reviews automatically :param bool require_code_owner_reviews: Blocks merging pull requests until code owners review them :param int required_approving_review_count: The number of reviewers required to approve pull requests. Acceptable values are between 1 and 6. :param dict dismissal_restrictions: An empty dictionary will disable this. This must have the following keys: ``users`` and ``teams`` each mapping to a list of user logins and team slugs respectively. :returns: A updated instance of the required pull request reviews. :rtype: :class:`~github3.repos.branch.ProtectionRequiredPullRequestReviews` """ existing_values = { "dismiss_stale_reviews": self.dismiss_stale_reviews, "dismissal_restrictions": { "users": [ getattr(u, "login", u) for u in getattr( self.dismissal_restrictions, "original_users", [] ) ], "teams": [ getattr(t, "slug", t) for t in getattr( self.dismissal_restrictions, "original_teams", [] ) ], }, "require_code_owner_reviews": self.require_code_owner_reviews, "required_approving_review_count": ( self.required_approving_review_count ), } update_json = { "dismiss_stale_reviews": ( dismiss_stale_reviews if dismiss_stale_reviews is not None else existing_values["dismiss_stale_reviews"] ), "require_code_owner_reviews": ( require_code_owner_reviews if require_code_owner_reviews is not None else existing_values["require_code_owner_reviews"] ), "required_approving_review_count": ( required_approving_review_count if required_approving_review_count is not None else existing_values["required_approving_review_count"] ), "dismissal_restrictions": ( dismissal_restrictions if dismissal_restrictions is not None else existing_values["dismissal_restrictions"] ), } resp = self._patch(self._api, json=update_json) json = self._json(resp, 200) if json: self._update_attributes(json) return self @decorators.requires_auth def delete(self): """Remove the Required Pull Request Reviews. :returns: Whether the operation finished successfully or not :rtype: bool """ resp = self._delete(self._api) return self._boolean(resp, 204, 404) class ProtectionRequiredStatusChecks(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection `Required Status Checks documentation`_ GitHub's description of required status checks `Required Status Checks API documentation`_ The API documentation for required status checks .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection .. _Required Status Checks documentation: https://help.github.com/articles/about-required-status-checks .. _Required Status Checks API documentation: https://developer.github.com/v3/repos/branches/#get-required-status-checks-of-protected-branch """ def _update_attributes(self, protection): self._api = protection["url"] self.strict = protection["strict"] self.original_contexts = protection["contexts"] self.contexts_url = protection["contexts_url"] @decorators.requires_auth def add_contexts(self, contexts): """Add contexts to the existing list of required contexts. See: https://developer.github.com/v3/repos/branches/#add-required-status-checks-contexts-of-protected-branch :param list contexts: The list of contexts to append to the existing list. :returns: The updated list of contexts. :rtype: list """ resp = self._post(self.contexts_url, data=contexts) json = self._json(resp, 200) return json @decorators.requires_auth def contexts(self): """Retrieve the list of contexts required as status checks. See: https://developer.github.com/v3/repos/branches/#list-required-status-checks-contexts-of-protected-branch :returns: A list of context names which are required status checks. :rtype: list """ resp = self._get(self.contexts_url) json = self._json(resp, 200) return json @decorators.requires_auth def remove_contexts(self, contexts): """Remove the specified contexts from the list of required contexts. See: https://developer.github.com/v3/repos/branches/#remove-required-status-checks-contexts-of-protected-branch :param list contexts: The context names to remove :returns: The updated list of contexts required as status checks. :rtype: list """ resp = self._delete(self.contexts_url, json=contexts) json = self._json(resp, 200) return json @decorators.requires_auth def replace_contexts(self, contexts): """Replace the existing contexts required as status checks. See https://developer.github.com/v3/repos/branches/#replace-required-status-checks-contexts-of-protected-branch :param list contexts: The names of the contexts to be required as status checks :returns: The new list of contexts required as status checks. :rtype: list """ resp = self._put(self.contexts_url, json=contexts) json = self._json(resp, 200) return json @decorators.requires_auth def delete_contexts(self, contexts): """Delete the contexts required as status checks. See https://developer.github.com/v3/repos/branches/#replace-required-status-checks-contexts-of-protected-branch :param list contexts: The names of the contexts to be required as status checks :returns: The updated list of contexts required as status checks. :rtype: list """ resp = self._delete(self.contexts_url, json=contexts) return self._boolean(resp, 204, 404) @decorators.requires_auth def update(self, strict=None, contexts=None): """Update required status checks for the branch. This requires admin or owner permissions to the repository and branch protection to be enabled. .. seealso:: `API docs`_ Descrption of how to update the required status checks. :param bool strict: Whether this should be strict protection or not. :param list contexts: A list of context names that should be required. :returns: A new instance of this class with the updated information :rtype: :class:`~github3.repos.branch.ProtectionRequiredStatusChecks` .. links .. _API docs: https://developer.github.com/v3/repos/branches/#update-required-status-checks-of-protected-branch """ update_data = {} json = None if strict is not None: update_data["strict"] = strict if contexts is not None: update_data["contexts"] = contexts if update_data: resp = self._patch(self.url, json=update_data) json = self._json(resp, 200) if json is not None: self._update_attributes(json) return self @decorators.requires_auth def delete(self): """Remove required status checks from this branch. See: https://developer.github.com/v3/repos/branches/#remove-required-status-checks-of-protected-branch :returns: True if successful, False otherwise :rtype: bool """ resp = self._delete(self.url) return self._boolean(resp, 204, 404) class ProtectionRequiredLinearHistory(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection This object has the following attributes: .. attribute:: enabled A boolean attribute indicating whether the ``required_linear_history`` protection is enabled or disabled. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection """ def _update_attributes(self, protection): self.enabled = protection["enabled"] class ProtectionAllowForcePushes(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection This object has the following attributes: .. attribute:: enabled A boolean attribute indicating whether the ``allow_force_pushes`` protection is enabled or disabled. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection """ def _update_attributes(self, protection): self.enabled = protection["enabled"] class ProtectionAllowDeletions(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection This object has the following attributes: .. attribute:: enabled A boolean attribute indicating whether the ``allow_deletions`` protection is enabled or disabled. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection """ def _update_attributes(self, protection): self.enabled = protection["enabled"] class ProtectionRequiredConversationResolution(models.GitHubCore): """The representation of a sub-portion of branch protection. .. seealso:: `Branch protection API documentation`_ GitHub's documentation of branch protection This object has the following attributes: .. attribute:: enabled A boolean attribute indicating whether the ``required_conversation_resolution`` protection is enabled or disabled. .. links .. _Branch protection API documentation: https://developer.github.com/v3/repos/branches/#get-branch-protection """ def _update_attributes(self, protection): self.enabled = protection["enabled"]