Add support for environments (#2223)

github/Environment.py

@@ -0,0 +1,123 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2022 Alson van der Meulen <alson.vandermeulen@dearhealth.com>      #
+#                                                                              #
+# This file is part of PyGithub.                                               #
+# http://pygithub.readthedocs.io/                                              #
+#                                                                              #
+# PyGithub is free software: you can redistribute it and/or modify it under    #
+# the terms of the GNU Lesser General Public License as published by the Free  #
+# Software Foundation, either version 3 of the License, or (at your option)    #
+# any later version.                                                           #
+#                                                                              #
+# PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS    #
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more #
+# details.                                                                     #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with PyGithub. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                              #
+################################################################################
+
+import datetime
+from typing import List
+
+import github.EnvironmentDeploymentBranchPolicy
+import github.EnvironmentProtectionRule
+import github.GithubObject
+
+
+class Environment(github.GithubObject.CompletableGithubObject):
+    """
+    This class represents Environment. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments
+    """
+
+    def __repr__(self):
+        return self.get__repr__({"name": self._name.value})
+
+    @property
+    def created_at(self) -> datetime.datetime:
+        self._completeIfNotSet(self._created_at)
+        return self._created_at.value
+
+    @property
+    def html_url(self) -> str:
+        self._completeIfNotSet(self._html_url)
+        return self._html_url.value
+
+    @property
+    def id(self) -> int:
+        self._completeIfNotSet(self._id)
+        return self._id.value
+
+    @property
+    def name(self) -> str:
+        self._completeIfNotSet(self._name)
+        return self._name.value
+
+    @property
+    def node_id(self) -> str:
+        self._completeIfNotSet(self._node_id)
+        return self._node_id.value
+
+    @property
+    def protection_rules(
+        self,
+    ) -> List[github.EnvironmentProtectionRule.EnvironmentProtectionRule]:
+        self._completeIfNotSet(self._protection_rules)
+        return self._protection_rules.value
+
+    @property
+    def updated_at(self) -> datetime.datetime:
+        self._completeIfNotSet(self._updated_at)
+        return self._updated_at.value
+
+    @property
+    def url(self) -> str:
+        self._completeIfNotSet(self._url)
+        return self._url.value
+
+    @property
+    def deployment_branch_policy(
+        self,
+    ) -> github.EnvironmentDeploymentBranchPolicy.EnvironmentDeploymentBranchPolicy:
+        self._completeIfNotSet(self._deployment_branch_policy)
+        return self._deployment_branch_policy.value
+
+    def _initAttributes(self):
+        self._created_at = github.GithubObject.NotSet
+        self._html_url = github.GithubObject.NotSet
+        self._id = github.GithubObject.NotSet
+        self._name = github.GithubObject.NotSet
+        self._node_id = github.GithubObject.NotSet
+        self._protection_rules = github.GithubObject.NotSet
+        self._updated_at = github.GithubObject.NotSet
+        self._url = github.GithubObject.NotSet
+        self._deployment_branch_policy = github.GithubObject.NotSet
+
+    def _useAttributes(self, attributes):
+        if "created_at" in attributes:  # pragma no branch
+            self._created_at = self._makeDatetimeAttribute(attributes["created_at"])
+        if "html_url" in attributes:  # pragma no branch
+            self._html_url = self._makeStringAttribute(attributes["html_url"])
+        if "id" in attributes:  # pragma no branch
+            self._id = self._makeIntAttribute(attributes["id"])
+        if "name" in attributes:  # pragma no branch
+            self._name = self._makeStringAttribute(attributes["name"])
+        if "node_id" in attributes:  # pragma no branch
+            self._node_id = self._makeStringAttribute(attributes["node_id"])
+        if "protection_rules" in attributes:  # pragma no branch
+            self._protection_rules = self._makeListOfClassesAttribute(
+                github.EnvironmentProtectionRule.EnvironmentProtectionRule,
+                attributes["protection_rules"],
+            )
+        if "updated_at" in attributes:  # pragma no branch
+            self._updated_at = self._makeDatetimeAttribute(attributes["updated_at"])
+        if "url" in attributes:  # pragma no branch
+            self._url = self._makeStringAttribute(attributes["url"])
+        if "deployment_branch_policy" in attributes:  # pragma no branch
+            self._deployment_branch_policy = self._makeClassAttribute(
+                github.EnvironmentDeploymentBranchPolicy.EnvironmentDeploymentBranchPolicy,
+                attributes["deployment_branch_policy"],
+            )

github/EnvironmentDeploymentBranchPolicy.py

@@ -0,0 +1,75 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2022 Alson van der Meulen <alson.vandermeulen@dearhealth.com>      #
+#                                                                              #
+# This file is part of PyGithub.                                               #
+# http://pygithub.readthedocs.io/                                              #
+#                                                                              #
+# PyGithub is free software: you can redistribute it and/or modify it under    #
+# the terms of the GNU Lesser General Public License as published by the Free  #
+# Software Foundation, either version 3 of the License, or (at your option)    #
+# any later version.                                                           #
+#                                                                              #
+# PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS    #
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more #
+# details.                                                                     #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with PyGithub. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                              #
+################################################################################
+
+import github.EnvironmentProtectionRuleReviewer
+import github.GithubObject
+
+
+class EnvironmentDeploymentBranchPolicy(github.GithubObject.NonCompletableGithubObject):
+    """
+    This class represents a deployment branch policy for an environment. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments
+    """
+
+    def __repr__(self):
+        return self.get__repr__({})
+
+    @property
+    def protected_branches(self) -> bool:
+        return self._protected_branches.value
+
+    @property
+    def custom_branch_policies(self) -> bool:
+        return self._custom_branch_policies.value
+
+    def _initAttributes(self):
+        self._protected_branches = github.GithubObject.NotSet
+        self._custom_branch_policies = github.GithubObject.NotSet
+
+    def _useAttributes(self, attributes):
+        if "protected_branches" in attributes:  # pragma no branch
+            self._protected_branches = self._makeBoolAttribute(
+                attributes["protected_branches"]
+            )
+        if "custom_branch_policies" in attributes:  # pragma no branch
+            self._custom_branch_policies = self._makeBoolAttribute(
+                attributes["custom_branch_policies"]
+            )
+
+
+class EnvironmentDeploymentBranchPolicyParams:
+    """
+    This class presents the deployment branch policy parameters as can be configured for an Environment.
+    """
+
+    def __init__(
+        self, protected_branches: bool = False, custom_branch_policies: bool = False
+    ):
+        assert isinstance(protected_branches, bool)
+        assert isinstance(custom_branch_policies, bool)
+        self.protected_branches = protected_branches
+        self.custom_branch_policies = custom_branch_policies
+
+    def _asdict(self) -> dict:
+        return {
+            "protected_branches": self.protected_branches,
+            "custom_branch_policies": self.custom_branch_policies,
+        }

github/EnvironmentProtectionRule.py

@@ -0,0 +1,81 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2022 Alson van der Meulen <alson.vandermeulen@dearhealth.com>      #
+#                                                                              #
+# This file is part of PyGithub.                                               #
+# http://pygithub.readthedocs.io/                                              #
+#                                                                              #
+# PyGithub is free software: you can redistribute it and/or modify it under    #
+# the terms of the GNU Lesser General Public License as published by the Free  #
+# Software Foundation, either version 3 of the License, or (at your option)    #
+# any later version.                                                           #
+#                                                                              #
+# PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS    #
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more #
+# details.                                                                     #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with PyGithub. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                              #
+################################################################################
+
+from typing import List
+
+import github.EnvironmentProtectionRuleReviewer
+import github.GithubObject
+
+
+class EnvironmentProtectionRule(github.GithubObject.NonCompletableGithubObject):
+    """
+    This class represents a protection rule for an environment. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments
+    """
+
+    def __repr__(self):
+        return self.get__repr__({"id": self._id.value})
+
+    @property
+    def id(self) -> int:
+        return self._id.value
+
+    @property
+    def node_id(self) -> str:
+        return self._node_id.value
+
+    @property
+    def type(self) -> str:
+        return self._type.value
+
+    @property
+    def reviewers(
+        self,
+    ) -> List[
+        github.EnvironmentProtectionRuleReviewer.EnvironmentProtectionRuleReviewer
+    ]:
+        return self._reviewers.value
+
+    @property
+    def wait_timer(self) -> int:
+        return self._wait_timer.value
+
+    def _initAttributes(self):
+        self._id = github.GithubObject.NotSet
+        self._node_id = github.GithubObject.NotSet
+        self._type = github.GithubObject.NotSet
+        self._reviewers = github.GithubObject.NotSet
+        self._wait_timer = github.GithubObject.NotSet
+
+    def _useAttributes(self, attributes):
+        if "id" in attributes:  # pragma no branch
+            self._id = self._makeIntAttribute(attributes["id"])
+        if "node_id" in attributes:  # pragma no branch
+            self._node_id = self._makeStringAttribute(attributes["node_id"])
+        if "type" in attributes:  # pragma no branch
+            self._type = self._makeStringAttribute(attributes["type"])
+        if "reviewers" in attributes:  # pragma no branch
+            self._reviewers = self._makeListOfClassesAttribute(
+                github.EnvironmentProtectionRuleReviewer.EnvironmentProtectionRuleReviewer,
+                attributes["reviewers"],
+            )
+        if "wait_timer" in attributes:  # pragma no branch
+            self._wait_timer = self._makeIntAttribute(attributes["wait_timer"])

github/EnvironmentProtectionRuleReviewer.py

@@ -0,0 +1,80 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2022 Alson van der Meulen <alson.vandermeulen@dearhealth.com>      #
+#                                                                              #
+# This file is part of PyGithub.                                               #
+# http://pygithub.readthedocs.io/                                              #
+#                                                                              #
+# PyGithub is free software: you can redistribute it and/or modify it under    #
+# the terms of the GNU Lesser General Public License as published by the Free  #
+# Software Foundation, either version 3 of the License, or (at your option)    #
+# any later version.                                                           #
+#                                                                              #
+# PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS    #
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more #
+# details.                                                                     #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with PyGithub. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                              #
+################################################################################
+
+from __future__ import annotations
+
+import github.GithubObject
+import github.NamedUser
+import github.Team
+
+
+class EnvironmentProtectionRuleReviewer(github.GithubObject.NonCompletableGithubObject):
+    """
+    This class represents a reviewer for an EnvironmentProtectionRule. The reference can be found here https://docs.github.com/en/rest/reference/deployments#environments
+    """
+
+    def __repr__(self):
+        return self.get__repr__({"type": self._type.value})
+
+    @property
+    def type(self) -> str:
+        return self._type.value
+
+    @property
+    def reviewer(self) -> github.NamedUser.NamedUser | github.Team.Team:
+        return self._reviewer.value
+
+    def _initAttributes(self):
+        self._type = github.GithubObject.NotSet
+        self._reviewer = github.GithubObject.NotSet
+
+    def _useAttributes(self, attributes):
+        if "type" in attributes:  # pragma no branch
+            self._type = self._makeStringAttribute(attributes["type"])
+        if "reviewer" in attributes:  # pragma no branch
+            assert self._type.value in ("User", "Team")
+            if self._type.value == "User":
+                self._reviewer = self._makeClassAttribute(
+                    github.NamedUser.NamedUser, attributes["reviewer"]
+                )
+            elif self._type.value == "Team":
+                self._reviewer = self._makeClassAttribute(
+                    github.Team.Team, attributes["reviewer"]
+                )
+
+
+class ReviewerParams:
+    """
+    This class presents reviewers as can be configured for an Environment.
+    """
+
+    def __init__(self, type_: str, id_: int):
+        assert isinstance(type_, str) and type_ in ("User", "Team")
+        assert isinstance(id_, int)
+        self.type = type_
+        self.id = id_
+
+    def _asdict(self) -> dict:
+        return {
+            "type": self.type,
+            "id": self.id,
+        }

github/Repository.py

@@ -100,6 +100,7 @@
 # Copyright 2022 Ibrahim Hussaini <ibrahimhussainialias@outlook.com>           #
 # Copyright 2022 KimSia Sim <245021+simkimsia@users.noreply.github.com>        #
 # Copyright 2022 Marco Köpcke <hello@parakoopa.de>                             #
+# Copyright 2022 Alson van der Meulen <alson.vandermeulen@dearhealth.com>      #
 # Copyright 2023 Jonathan Leitschuh <Jonathan.Leitschuh@gmail.com>             #
 # Copyright 2023 Sol Redfern <59831933+Tsuesun@users.noreply.github.com>       #
 # Copyright 2023 Mikhail f. Shiryaev <mr.felixoid@gmail.com>                   #
@@ -143,6 +144,10 @@ import github.Comparison
 import github.ContentFile
 import github.Deployment
 import github.Download
+import github.Environment
+import github.EnvironmentDeploymentBranchPolicy
+import github.EnvironmentProtectionRule
+import github.EnvironmentProtectionRuleReviewer
 import github.Event
 import github.GitBlob
 import github.GitCommit
@@ -4103,6 +4108,95 @@ class Repository(github.GithubObject.CompletableGithubObject):
             None,
         )
 
+    def get_environments(self):
+        """
+        :calls: `GET /repos/{owner}/{repo}/environments <https://docs.github.com/en/rest/reference/deployments#get-all-environments>`_
+        :rtype: :class:`github.PaginatedList.PaginatedList` of :class:`github.Environment.Environment`
+        """
+        return github.PaginatedList.PaginatedList(
+            github.Environment.Environment,
+            self._requester,
+            f"{self.url}/environments",
+            None,
+            list_item="environments",
+        )
+
+    def get_environment(self, environment_name):
+        """
+        :calls: `GET /repos/{owner}/{repo}/environments/{environment_name} <https://docs.github.com/en/rest/reference/deployments#get-an-environment>`_
+        :rtype: :class:`github.Environment.Environment`
+        """
+        assert isinstance(environment_name, str), environment_name
+        headers, data = self._requester.requestJsonAndCheck(
+            "GET", f"{self.url}/environments/{environment_name}"
+        )
+        return github.Environment.Environment(
+            self._requester, headers, data, completed=True
+        )
+
+    def create_environment(
+        self,
+        environment_name,
+        wait_timer=0,
+        reviewers=[],
+        deployment_branch_policy=None,
+    ):
+        """
+        :calls: `PUT /repos/{owner}/{repo}/environments/{environment_name} <https://docs.github.com/en/rest/reference/deployments#create-or-update-an-environment>`_
+        :param environment_name: string
+        :param wait_timer: int
+        :param reviews: List[:class:github.EnvironmentDeploymentBranchPolicy.EnvironmentDeploymentBranchPolicyParams]
+        :param deployment_branch_policy: Optional[:class:github.EnvironmentDeploymentBranchPolicy.EnvironmentDeploymentBranchPolicyParams`]
+        :rtype: :class:`github.Environment.Environment`
+        """
+        assert isinstance(environment_name, str), environment_name
+        assert isinstance(wait_timer, int)
+        assert isinstance(reviewers, list)
+        assert all(
+            [
+                isinstance(
+                    reviewer, github.EnvironmentProtectionRuleReviewer.ReviewerParams
+                )
+                for reviewer in reviewers
+            ]
+        )
+        assert (
+            isinstance(
+                deployment_branch_policy,
+                github.EnvironmentDeploymentBranchPolicy.EnvironmentDeploymentBranchPolicyParams,
+            )
+            or deployment_branch_policy is None
+        )
+
+        put_parameters = {
+            "wait_timer": wait_timer,
+            "reviewers": [reviewer._asdict() for reviewer in reviewers],
+            "deployment_branch_policy": deployment_branch_policy._asdict()
+            if deployment_branch_policy
+            else None,
+        }
+
+        headers, data = self._requester.requestJsonAndCheck(
+            "PUT", f"{self.url}/environments/{environment_name}", input=put_parameters
+        )
+        return github.Environment.Environment(
+            self._requester, headers, data, completed=True
+        )
+
+    update_environment = create_environment
+
+    def delete_environment(self, environment_name):
+        """
+        :calls: `DELETE /repos/{owner}/{repo}/environments/{environment_name} <https://docs.github.com/en/rest/reference/deployments#delete-an-environment>`_
+        :param environment_name: string
+        :rtype: None
+        """
+        assert isinstance(environment_name, str), environment_name
+
+        headers, data = self._requester.requestJsonAndCheck(
+            "DELETE", f"{self.url}/environments/{environment_name}"
+        )
+
     def _initAttributes(self):
         self._allow_auto_merge = github.GithubObject.NotSet
         self._allow_forking = github.GithubObject.NotSet

github/Repository.pyi

@@ -14,6 +14,11 @@ from github.Comparison import Comparison
 from github.ContentFile import ContentFile
 from github.Deployment import Deployment
 from github.Download import Download
+from github.Environment import Environment
+from github.EnvironmentDeploymentBranchPolicy import (
+    EnvironmentDeploymentBranchPolicyParams,
+)
+from github.EnvironmentProtectionRuleReviewer import ReviewerParams
 from github.Event import Event
 from github.GitBlob import GitBlob
 from github.GitCommit import GitCommit
@@ -142,6 +147,15 @@ class Repository(CompletableGithubObject):
     ) -> Deployment: ...
     def get_repository_advisories(self) -> PaginatedList[RepositoryAdvisory]: ...
     def get_repository_advisory(self, ghsa: str) -> RepositoryAdvisory: ...
+    def create_environment(
+        self,
+        environment_name: str,
+        wait_timer: int = ...,
+        reviewers: List[ReviewerParams] = ...,
+        deployment_branch_policy: Optional[
+            EnvironmentDeploymentBranchPolicyParams
+        ] = ...,
+    ) -> Environment: ...
     def create_file(
         self,
         path: str,
@@ -287,6 +301,7 @@ class Repository(CompletableGithubObject):
     @property
     def default_branch(self) -> str: ...
     def delete(self) -> None: ...
+    def delete_environment(self, environment_name: str) -> None: ...
     def delete_file(
         self,
         path: str,
@@ -392,6 +407,8 @@ class Repository(CompletableGithubObject):
     ) -> List[ContentFile]: ...
     def get_download(self, id: int) -> Download: ...
     def get_downloads(self) -> PaginatedList[Download]: ...
+    def get_environments(self) -> PaginatedList[Environment]: ...
+    def get_environment(self, environment_name: str) -> Environment: ...
     def get_events(self) -> PaginatedList[Event]: ...
     def get_forks(self) -> PaginatedList[Repository]: ...
     def create_fork(
@@ -644,6 +661,15 @@ class Repository(CompletableGithubObject):
     @property
     def trees_url(self) -> str: ...
     def unsubscribe_from_hub(self, event: str, callback: str) -> None: ...
+    def update_environment(
+        self,
+        environment_name: str,
+        wait_timer: int = ...,
+        reviewers: List[ReviewerParams] = ...,
+        deployment_branch_policy: Optional[
+            EnvironmentDeploymentBranchPolicyParams
+        ] = ...,
+    ) -> Environment: ...
     def update_file(
         self,
         path: str,