Adding feature for enterprise consumed license (#2626)

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

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 @@ from typing import List
 import urllib3
 
 import github.ApplicationOAuth
+import github.Enterprise
 import github.Event
 import github.Gist
 import github.GithubObject
@@ -341,6 +343,16 @@ class Github:
             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: ...

github/NamedEnterpriseUser.py

@@ -0,0 +1,195 @@
+############################ 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
+
+
+class NamedEnterpriseUser(CompletableGithubObject):
+    """
+    This class represents NamedEnterpriseUsers. 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._github_com_login: Attribute[str] = NotSet
+        self._github_com_name: Attribute[str] = NotSet
+        self._enterprise_server_user_ids: Attribute[list] = NotSet
+        self._github_com_user: Attribute[bool] = NotSet
+        self._enterprise_server_user: Attribute[bool] = NotSet
+        self._visual_studio_subscription_user: Attribute[bool] = NotSet
+        self._license_type: Attribute[str] = NotSet
+        self._github_com_profile: Attribute[str] = NotSet
+        self._github_com_member_roles: Attribute[list] = NotSet
+        self._github_com_enterprise_roles: Attribute[list] = NotSet
+        self._github_com_verified_domain_emails: Attribute[list] = NotSet
+        self._github_com_saml_name_id: Attribute[str] = NotSet
+        self._github_com_orgs_with_pending_invites: Attribute[list] = NotSet
+        self._github_com_two_factor_auth: Attribute[bool] = NotSet
+        self._enterprise_server_primary_emails: Attribute[list] = NotSet
+        self._visual_studio_license_status: Attribute[str] = NotSet
+        self._visual_studio_subscription_email: Attribute[str] = NotSet
+        self._total_user_accounts: Attribute[int] = NotSet
+
+    def __repr__(self) -> str:
+        return self.get__repr__({"login": self._github_com_login.value})
+
+    @property
+    def github_com_login(self) -> str:
+        self._completeIfNotSet(self._github_com_login)
+        return self._github_com_login.value
+
+    @property
+    def github_com_name(self) -> str:
+        self._completeIfNotSet(self._github_com_name)
+        return self._github_com_name.value
+
+    @property
+    def enterprise_server_user_ids(self) -> list:
+        self._completeIfNotSet(self._enterprise_server_user_ids)
+        return self._enterprise_server_user_ids.value
+
+    @property
+    def github_com_user(self) -> bool:
+        self._completeIfNotSet(self._github_com_user)
+        return self._github_com_user.value
+
+    @property
+    def enterprise_server_user(self) -> bool:
+        self._completeIfNotSet(self._enterprise_server_user)
+        return self._enterprise_server_user.value
+
+    @property
+    def visual_studio_subscription_user(self) -> bool:
+        self._completeIfNotSet(self._visual_studio_subscription_user)
+        return self._visual_studio_subscription_user.value
+
+    @property
+    def license_type(self) -> str:
+        self._completeIfNotSet(self._license_type)
+        return self._license_type.value
+
+    @property
+    def github_com_profile(self) -> str:
+        self._completeIfNotSet(self._github_com_profile)
+        return self._github_com_profile.value
+
+    @property
+    def github_com_member_roles(self) -> list:
+        self._completeIfNotSet(self._github_com_member_roles)
+        return self._github_com_member_roles.value
+
+    @property
+    def github_com_enterprise_roles(self) -> list:
+        self._completeIfNotSet(self._github_com_enterprise_roles)
+        return self._github_com_enterprise_roles.value
+
+    @property
+    def github_com_verified_domain_emails(self) -> list:
+        self._completeIfNotSet(self._github_com_verified_domain_emails)
+        return self._github_com_verified_domain_emails.value
+
+    @property
+    def github_com_saml_name_id(self) -> str:
+        self._completeIfNotSet(self._github_com_saml_name_id)
+        return self._github_com_saml_name_id.value
+
+    @property
+    def github_com_orgs_with_pending_invites(self) -> list:
+        self._completeIfNotSet(self._github_com_orgs_with_pending_invites)
+        return self._github_com_orgs_with_pending_invites.value
+
+    @property
+    def github_com_two_factor_auth(self) -> bool:
+        self._completeIfNotSet(self._github_com_two_factor_auth)
+        return self._github_com_two_factor_auth.value
+
+    @property
+    def enterprise_server_primary_emails(self) -> list:
+        self._completeIfNotSet(self._enterprise_server_primary_emails)
+        return self._enterprise_server_primary_emails.value
+
+    @property
+    def visual_studio_license_status(self) -> str:
+        self._completeIfNotSet(self._visual_studio_license_status)
+        return self._visual_studio_license_status.value
+
+    @property
+    def visual_studio_subscription_email(self) -> str:
+        self._completeIfNotSet(self._visual_studio_subscription_email)
+        return self._visual_studio_subscription_email.value
+
+    @property
+    def total_user_accounts(self) -> int:
+        self._completeIfNotSet(self._total_user_accounts)
+        return self._total_user_accounts.value
+
+    def _useAttributes(self, attributes: Dict[str, Any]) -> None:
+        if "github_com_login" in attributes:  # pragma no branch
+            self._github_com_login = self._makeStringAttribute(attributes["github_com_login"])
+        if "github_com_name" in attributes:  # pragma no branch
+            self._github_com_name = self._makeStringAttribute(attributes["github_com_name"])
+        if "enterprise_server_user_ids" in attributes:  # pragma no branch
+            self._enterprise_server_user_ids = self._makeListOfStringsAttribute(
+                attributes["enterprise_server_user_ids"]
+            )
+        if "github_com_user" in attributes:  # pragma no branch
+            self._github_com_user = self._makeBoolAttribute(attributes["github_com_user"])
+        if "enterprise_server_user" in attributes:  # pragma no branch
+            self._enterprise_server_user = self._makeBoolAttribute(attributes["enterprise_server_user"])
+        if "visual_studio_subscription_user" in attributes:  # pragma no branch
+            self._visual_studio_subscription_user = self._makeBoolAttribute(
+                attributes["visual_studio_subscription_user"]
+            )
+        if "license_type" in attributes:  # pragma no branch
+            self._license_type = self._makeStringAttribute(attributes["license_type"])
+        if "github_com_profile" in attributes:  # pragma no branch
+            self._github_com_profile = self._makeStringAttribute(attributes["github_com_profile"])
+        if "github_com_member_roles" in attributes:  # pragma no branch
+            self._github_com_member_roles = self._makeListOfStringsAttribute(attributes["github_com_member_roles"])
+        if "github_com_enterprise_roles" in attributes:  # pragma no branch
+            self._github_com_enterprise_roles = self._makeListOfStringsAttribute(
+                attributes["github_com_enterprise_roles"]
+            )
+        if "github_com_verified_domain_emails" in attributes:  # pragma no branch
+            self._github_com_verified_domain_emails = self._makeListOfStringsAttribute(
+                attributes["github_com_verified_domain_emails"]
+            )
+        if "github_com_saml_name_id" in attributes:  # pragma no branch
+            self._github_com_saml_name_id = self._makeStringAttribute(attributes["github_com_saml_name_id"])
+        if "github_com_orgs_with_pending_invites" in attributes:  # pragma no branch
+            self._github_com_orgs_with_pending_invites = self._makeListOfStringsAttribute(
+                attributes["github_com_orgs_with_pending_invites"]
+            )
+        if "github_com_two_factor_auth" in attributes:  # pragma no branch
+            self._github_com_two_factor_auth = self._makeBoolAttribute(attributes["github_com_two_factor_auth"])
+        if "enterprise_server_primary_emails" in attributes:  # pragma no branch
+            self._enterprise_server_primary_emails = self._makeListOfStringsAttribute(
+                attributes["enterprise_server_primary_emails"]
+            )
+        if "visual_studio_license_status" in attributes:  # pragma no branch
+            self._visual_studio_license_status = self._makeStringAttribute(attributes["visual_studio_license_status"])
+        if "visual_studio_subscription_email" in attributes:  # pragma no branch
+            self._visual_studio_subscription_email = self._makeStringAttribute(
+                attributes["visual_studio_subscription_email"]
+            )
+        if "total_user_accounts" in attributes:  # pragma no branch
+            self._total_user_accounts = self._makeIntAttribute(attributes["total_user_accounts"])

github/PaginatedList.py

@@ -52,8 +52,8 @@ class PaginatedListBase(Generic[T]):
     def _fetchNextPage(self) -> List[T]:
         raise NotImplementedError
 
-    def __init__(self) -> None:
-        self.__elements = []
+    def __init__(self, elements: Optional[List[T]] = None) -> None:
+        self.__elements = [] if elements is None else elements
 
     def __getitem__(self, index: Union[int, slice]) -> Any:
         assert isinstance(index, (int, slice))
@@ -138,8 +138,9 @@ class PaginatedList(PaginatedListBase[T]):
         firstParams: Any,
         headers: Optional[Dict[str, str]] = None,
         list_item: str = "items",
+        firstData: Optional[Any] = None,
+        firstHeaders: Optional[Dict[str, Union[str, int]]] = None,
     ):
-        super().__init__()
         self.__requester = requester
         self.__contentClass = contentClass
         self.__firstUrl = firstUrl
@@ -153,6 +154,11 @@ class PaginatedList(PaginatedListBase[T]):
         self._reversed = False
         self.__totalCount: Optional[int] = None
 
+        first_page = []
+        if firstData is not None and firstHeaders is not None:
+            first_page = self._getPage(firstData, firstHeaders)
+        super().__init__(first_page)
+
     @property
     def totalCount(self) -> int:
         if not self.__totalCount:
@@ -214,7 +220,9 @@ class PaginatedList(PaginatedListBase[T]):
             "GET", self.__nextUrl, parameters=self.__nextParams, headers=self.__headers
         )
         data = data if data else []
+        return self._getPage(data, headers)
 
+    def _getPage(self, data: Any, headers: Dict[str, Any]) -> List[T]:
         self.__nextUrl = None  # type: ignore
         if len(data) > 0:
             links = self.__parseLinkHeader(headers)

tests/EnterpriseAdmin.py

@@ -0,0 +1,68 @@
+############################ 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 . import Framework
+
+
+class EnterpriseAdmin(Framework.TestCase):
+    def setUp(self):
+        super().setUp()
+        self.enterprise = self.g.get_enterprise("beaver-group")
+
+    def testAttributes(self):
+        self.assertEqual(self.enterprise.enterprise, "beaver-group")
+        self.assertEqual(self.enterprise.url, "/enterprises/beaver-group")
+        self.assertEqual(repr(self.enterprise), 'Enterprise(enterprise="beaver-group")')
+
+    def testGetConsumedLicenses(self):
+        consumed_licenses = self.enterprise.get_consumed_licenses()
+        self.assertEqual(consumed_licenses.total_seats_consumed, 102)
+        self.assertEqual(consumed_licenses.total_seats_purchased, 103)
+
+    def testGetEnterpriseUsers(self):
+        enterprise_users = self.enterprise.get_consumed_licenses().get_users()
+        enterprise_users_list = [
+            [
+                users.github_com_login,
+                users.github_com_name,
+                users.enterprise_server_user_ids,
+                users.github_com_user,
+                users.enterprise_server_user,
+                users.visual_studio_subscription_user,
+                users.license_type,
+                users.github_com_profile,
+                users.github_com_member_roles,
+                users.github_com_enterprise_roles,
+                users.github_com_verified_domain_emails,
+                users.github_com_saml_name_id,
+                users.github_com_orgs_with_pending_invites,
+                users.github_com_two_factor_auth,
+                users.enterprise_server_primary_emails,
+                users.visual_studio_license_status,
+                users.visual_studio_subscription_email,
+                users.total_user_accounts,
+            ]
+            for users in enterprise_users
+        ]
+        self.assertEqual(len(enterprise_users_list), 102)
+        self.assertEqual(enterprise_users_list[42][0], "beaver-user043")

tests/PaginatedList.py

@@ -37,10 +37,17 @@ class PaginatedList(Framework.TestCase):
         super().setUp()
         self.repo = self.g.get_user("openframeworks").get_repo("openFrameworks")
         self.list = self.repo.get_issues()
+        self.licenses = self.g.get_enterprise("beaver-group").get_consumed_licenses()
 
     def testIteration(self):
         self.assertEqual(len(list(self.list)), 333)
 
+    def testIterationWithPrefetchedFirstPage(self):
+        # test data taken from EnterpriseAdmin.testGetEnterpriseUsers
+        users = self.licenses.get_users()
+        self.assertEqual(len(list(users)), 102)
+        self.assertEqual(len({user.github_com_login for user in users}), 102)
+
     def testSeveralIterations(self):
         self.assertEqual(len(list(self.list)), 333)
         self.assertEqual(len(list(self.list)), 333)