Adding feature for enterprise consumed license (#2626)

Co-authored-by: Enrico Minack <github@enrico.minack.dev>

Author: YugoHino

doc/examples/MainClass.rst

@@ -39,6 +39,16 @@ Get organization by name
     >>> org.login
     u'PyGithub'
 
+Get enterprise consumed licenses by name
+------------------------
+
+.. code-block:: python
+
+    >>> enterprise = g.get_enterprise_consumed_licenses("PyGithub")
+    >>> enterprise_consumed_licenses = enterprise.get_enterprise_consumed_licenses()
+    >>> enterprise_consumed_licenses.total_seats_consumed
+    5000
+
 Search repositories by language
 -------------------------------
 

github/Enterprise.py

@@ -0,0 +1,71 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2023 Yugo Hino <henom06@gmail.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 Any, Dict
+
+from github.EnterpriseConsumedLicenses import EnterpriseConsumedLicenses
+from github.GithubObject import Attribute, NonCompletableGithubObject, NotSet
+from github.Requester import Requester
+
+
+class Enterprise(NonCompletableGithubObject):
+    """
+    This class represents Enterprises. Such objects do not exist in the Github API, so this class merely collects all endpoints the start with /enterprises/{enterprise}/. See methods below for specific endpoints and docs.
+    https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin?apiVersion=2022-11-28
+    """
+
+    def __init__(
+        self,
+        requester: Requester,
+        enterprise: str,
+    ):
+        super().__init__(requester, {}, {"enterprise": enterprise, "url": f"/enterprises/{enterprise}"}, True)
+
+    def _initAttributes(self) -> None:
+        self._enterprise: Attribute[str] = NotSet
+        self._url: Attribute[str] = NotSet
+
+    def __repr__(self) -> str:
+        return self.get__repr__({"enterprise": self._enterprise.value})
+
+    @property
+    def enterprise(self) -> str:
+        return self._enterprise.value
+
+    @property
+    def url(self) -> str:
+        return self._url.value
+
+    def get_consumed_licenses(self) -> EnterpriseConsumedLicenses:
+        """
+        :calls: `GET /enterprises/{enterprise}/consumed-licenses <https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses>`_
+        """
+        headers, data = self._requester.requestJsonAndCheck("GET", self.url + "/consumed-licenses")
+        if "url" not in data:
+            data["url"] = self.url + "/consumed-licenses"
+
+        return EnterpriseConsumedLicenses(self._requester, headers, data, completed=True)
+
+    def _useAttributes(self, attributes: Dict[str, Any]) -> None:
+        if "enterprise" in attributes:  # pragma no branch
+            self._enterprise = self._makeStringAttribute(attributes["enterprise"])
+        if "url" in attributes:  # pragma no branch
+            self._url = self._makeStringAttribute(attributes["url"])

github/EnterpriseConsumedLicenses.py

@@ -0,0 +1,86 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2023 Yugo Hino <henom06@gmail.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 Any, Dict
+
+from github.GithubObject import Attribute, CompletableGithubObject, NotSet
+from github.NamedEnterpriseUser import NamedEnterpriseUser
+from github.PaginatedList import PaginatedList
+
+
+class EnterpriseConsumedLicenses(CompletableGithubObject):
+    """
+    This class represents license consumed by enterprises. The reference can be found here https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses
+    """
+
+    def _initAttributes(self) -> None:
+        self._total_seats_consumed: Attribute[int] = NotSet
+        self._total_seats_purchased: Attribute[int] = NotSet
+        self._enterprise: Attribute[str] = NotSet
+        self._url: Attribute[str] = NotSet
+
+    def __repr__(self) -> str:
+        return self.get__repr__({"enterprise": self._enterprise.value})
+
+    @property
+    def total_seats_consumed(self) -> int:
+        return self._total_seats_consumed.value
+
+    @property
+    def total_seats_purchased(self) -> int:
+        return self._total_seats_purchased.value
+
+    @property
+    def enterprise(self) -> str:
+        self._completeIfNotSet(self._enterprise)
+        return self._enterprise.value
+
+    @property
+    def url(self) -> str:
+        self._completeIfNotSet(self._url)
+        return self._url.value
+
+    def get_users(self) -> PaginatedList[NamedEnterpriseUser]:
+        """
+        :calls: `GET /enterprises/{enterprise}/consumed-licenses <https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin/license#list-enterprise-consumed-licenses>`_
+        """
+
+        url_parameters: Dict[str, Any] = {}
+        return PaginatedList(
+            NamedEnterpriseUser,
+            self._requester,
+            self.url,
+            url_parameters,
+            None,
+            "users",
+            self.raw_data,
+            self.raw_headers,
+        )
+
+    def _useAttributes(self, attributes: Dict[str, Any]) -> None:
+        if "total_seats_consumed" in attributes:  # pragma no branch
+            self._total_seats_consumed = self._makeIntAttribute(attributes["total_seats_consumed"])
+        if "total_seats_purchased" in attributes:  # pragma no branch
+            self._total_seats_purchased = self._makeIntAttribute(attributes["total_seats_purchased"])
+        if "enterprise" in attributes:  # pragma no branch
+            self._enterprise = self._makeStringAttribute(attributes["enterprise"])
+        if "url" in attributes:  # pragma no branch
+            self._url = self._makeStringAttribute(attributes["url"])

github/MainClass.py

@@ -28,6 +28,7 @@
 # Copyright 2018 itsbruce <it.is.bruce@gmail.com>                              #
 # Copyright 2019 Tomas Tomecek <tomas@tomecek.net>                             #
 # Copyright 2019 Rigas Papathanasopoulos <rigaspapas@gmail.com>                #
+# Copyright 2023 Yugo Hino <henom06@gmail.com>                                 #
 #                                                                              #
 # This file is part of PyGithub.                                               #
 # http://pygithub.readthedocs.io/                                              #
@@ -55,6 +56,7 @@
 import urllib3
 
 import github.ApplicationOAuth
+import github.Enterprise
 import github.Event
 import github.Gist
 import github.GithubObject
@@ -341,6 +343,16 @@ def get_organizations(self, since=github.GithubObject.NotSet):
             url_parameters,
         )
 
+    def get_enterprise(self, enterprise):
+        """
+        :calls: `GET /enterprises/{enterprise} <https://docs.github.com/en/enterprise-cloud@latest/rest/enterprise-admin>`_
+        :param enterprise: string
+        :rtype: :class:`Enterprise`
+        """
+        assert isinstance(enterprise, str), enterprise
+        # There is no native "/enterprises/{enterprise}" api, so this function is a hub for apis that start with "/enterprise/{enterprise}".
+        return github.Enterprise.Enterprise(self.__requester, enterprise)
+
     def get_repo(self, full_name_or_id, lazy=False):
         """
         :calls: `GET /repos/{owner}/{repo} <https://docs.github.com/en/rest/reference/repos>`_ or `GET /repositories/{id} <https://docs.github.com/en/rest/reference/repos>`_

github/MainClass.pyi

@@ -10,6 +10,7 @@ from github.Auth import Auth
 from github.AuthenticatedUser import AuthenticatedUser
 from github.Commit import Commit
 from github.ContentFile import ContentFile
+from github.Enterprise import Enterprise
 from github.Event import Event
 from github.Gist import Gist
 from github.GithubApp import GithubApp
@@ -79,6 +80,7 @@ class Github:
     def get_licenses(self) -> PaginatedList[License]: ...
     def get_organization(self, login: str) -> Organization: ...
     def get_organizations(self, since: Union[int, _NotSetType] = ...) -> PaginatedList[Organization]: ...
+    def get_enterprise(self, login: str) -> Enterprise: ...
     def get_project(self, id: int) -> Project: ...
     def get_project_column(self, id: int) -> ProjectColumn: ...
     def get_rate_limit(self) -> RateLimit: ...