Merge pull request #1049 from sigmavirus24/branch-protection

Update branch protection API support

docs/source/release-notes/3.0.0.rst

@@ -0,0 +1,34 @@
+3.0.0: 2021-10-30
+-----------------
+
+Backwards Incompatible Changes
+``````````````````````````````
+
+- :meth:`~github3.repos.branch.Branch.protect` has been updated to reflect the
+  GitHub API
+
+Features Added
+``````````````
+
+- Add ``maintainer_can_modify`` parameter to
+  :meth:`~github3.repos.repo.Repository.create_pull`
+
+- Add :attr:`~github3.repos.branch.BranchProtection.required_linear_history`,
+  :attr:`~github3.repos.branch.BranchProtection.allow_force_pushes`,
+  :attr:`~github3.repos.branch.BranchProtection.allow_deletions`, and
+  :attr:`~github3.repos.branch.BranchProtection.required_conversation_resolution`.
+
+- Add support for blocking users to :class:`~github3.github.GitHub` and
+  :class:`~github3.orgs.Organization`.
+
+  - :meth:`~github3.github.GitHub.blocked_users`
+  - :meth:`~github3.github.GitHub.block`
+  - :meth:`~github3.github.GitHub.is_blocking`
+  - :meth:`~github3.github.GitHub.unblock`
+  - :meth:`~github3.orgs.Organization.blocked_users`
+  - :meth:`~github3.orgs.Organization.block`
+  - :meth:`~github3.orgs.Organization.is_blocking`
+  - :meth:`~github3.orgs.Organization.unblock`
+
+- Add support for beta branch synchronization endpoint
+  :meth:`~github3.repos.branch.Branch.sync_with_upstream`

docs/source/release-notes/index.rst

@@ -5,44 +5,49 @@
 All of the release notes that have been recorded for github3.py are organized
 here with the newest releases first.
 
+3.x Release Series
+==================
+
+.. toctree::
+   3.0.0
+
 2.x Release Series
 ==================
 
 .. toctree::
-    2.1.0
-    2.0.0
+   2.0.0
 
 1.x Release Series
 ==================
 
 .. toctree::
-    1.3.0
-    1.2.0
-    1.1.0
-    1.0.2
-    1.0.1
-    1.0.0
+   1.3.0
+   1.2.0
+   1.1.0
+   1.0.2
+   1.0.1
+   1.0.0
 
 0.x Release Series
 ==================
 
 .. toctree::
-    0.9.3
-    0.9.2
-    0.9.1
-    0.9.0
-    0.8.2
-    0.8.1
-    0.8.0
-    0.7.1
-    0.7.0
-    0.6.1
-    0.6.0
-    0.5.3
-    0.5.2
-    0.5.1
-    0.5.0
-    0.4.0
-    0.3.0
-    0.2.0
-    0.1.0
+   0.9.3
+   0.9.2
+   0.9.1
+   0.9.0
+   0.8.2
+   0.8.1
+   0.8.0
+   0.7.1
+   0.7.0
+   0.6.1
+   0.6.0
+   0.5.3
+   0.5.2
+   0.5.1
+   0.5.0
+   0.4.0
+   0.3.0
+   0.2.0
+   0.1.0

setup.cfg

@@ -1,5 +1,6 @@
 [metadata]
 name = github3.py
+version = attr:github3.__about__.__version__
 description = Python wrapper for the GitHub API(http://developer.github.com/v3)
 long_description = file: README.rst
 long_description_content_type = text/x-rst
@@ -35,6 +36,7 @@ install_requires =
     python-dateutil>=2.6.0
     requests>=2.18
     uritemplate>=3.0.0
+    typing-extensions>=3.10.0.2;python_version < "3.7"
 python_requires = >=3.6
 package_dir =
     =src

setup.py

@@ -1,17 +1,4 @@
 """Packaging logic."""
-import re
-
 import setuptools
 
-__version__ = ""
-with open("src/github3/__about__.py") as fd:
-    reg = re.compile(r'__version__ = [\'"]([^\'"]*)[\'"]')
-    for line in fd:
-        m = reg.match(line)
-        if m:
-            __version__ = m.group(1)
-            break
-
-setuptools.setup(
-    version=__version__,
-)
+setuptools.setup()

src/github3/__about__.py

@@ -5,7 +5,7 @@
 __author_email__ = "graffatcolmingov@gmail.com"
 __license__ = "Modified BSD"
 __copyright__ = "Copyright 2012-2021 Ian Stapleton Cordasco"
-__version__ = "2.0.0"
+__version__ = "3.0.0"
 __version_info__ = tuple(
     int(i) for i in __version__.split(".") if i.isdigit()
 )

src/github3/apps.py

@@ -41,6 +41,10 @@ class App(models.GitHubCore):
 
         The description of the App provided by the owner.
 
+    .. attribute:: events
+
+        An array of the event types an App receives
+
     .. attribute:: external_url
 
         The URL provided for the App by the owner.
@@ -69,6 +73,14 @@ class App(models.GitHubCore):
         A :class:`~github3.users.ShortUser` object representing the GitHub
         user who owns the App.
 
+    .. attribute:: permissions
+
+        A dictionary describing the permissions the App has
+
+    .. attribute:: slug
+
+        A short string used to identify the App
+
     .. attribute:: updated_at
 
         A :class:`~datetime.datetime` object representing the day and time
@@ -88,14 +100,16 @@ def _update_attributes(self, json):
         self.created_at = self._strptime(json["created_at"])
         self.description = json["description"]
         self.external_url = json["external_url"]
+        self.events = json["events"]
         self.html_url = json["html_url"]
         self.id = json["id"]
         self.name = json["name"]
         self.node_id = json["node_id"]
         self.owner = users.ShortUser(json["owner"], self)
+        self.permissions = json["permissions"]
+        self.slug = json["slug"]
         self.updated_at = self._strptime(json["updated_at"])
-        _, slug = json["html_url"].rsplit("/", 1)
-        self._api = self.url = self._build_url("apps", slug)
+        self._api = self.url = self._build_url("apps", self.slug)
 
     def _repr(self):
         return f'<App ["{self.name}" by {str(self.owner)}]>'

src/github3/github.py

@@ -506,6 +506,8 @@ def blocked_users(
     ) -> t.Generator[users.ShortUser, None, None]:
         """Iterate over the users blocked by this organization.
 
+        .. versionadded:: 2.1.0
+
         :param int number:
             (optional), number of users to iterate over.  Default: -1 iterates
             over all values
@@ -523,6 +525,8 @@ def blocked_users(
     def block(self, username: users.UserLike) -> bool:
         """Block a specific user from an organization.
 
+        .. versionadded:: 2.1.0
+
         :parameter str username:
             Name (or user-like instance) of the user to block.
         :returns:
@@ -537,6 +541,8 @@ def block(self, username: users.UserLike) -> bool:
     def unblock(self, username: users.UserLike) -> bool:
         """Unblock a specific user from an organization.
 
+        .. versionadded:: 2.1.0
+
         :parameter str username:
             Name (or user-like instance) of the user to unblock.
         :returns:
@@ -551,6 +557,8 @@ def unblock(self, username: users.UserLike) -> bool:
     def is_blocking(self, username: users.UserLike) -> bool:
         """Check if this organization is blocking a specific user.
 
+        .. versionadded:: 2.1.0
+
         :parameter str username:
             Name (or user-like instance) of the user to unblock.
         :returns:

src/github3/models.py

@@ -282,7 +282,7 @@ def ratelimit_remaining(self):
         self._remaining = core.get("remaining", 0)
         return self._remaining
 
-    def refresh(self, conditional=False):
+    def refresh(self, conditional: bool = False) -> "GitHubCore":
         """Re-retrieve the information for this object.
 
         The reasoning for the return value is the following example: ::

src/github3/orgs.py

@@ -439,6 +439,8 @@ def blocked_users(
     ) -> t.Generator[users.ShortUser, None, None]:
         """Iterate over the users blocked by this organization.
 
+        .. versionadded:: 2.1.0
+
         :param int number:
             (optional), number of users to iterate over.  Default: -1 iterates
             over all values
@@ -456,6 +458,8 @@ def blocked_users(
     def block(self, username: users.UserLike) -> bool:
         """Block a specific user from an organization.
 
+        .. versionadded:: 2.1.0
+
         :parameter str username:
             Name (or user-like instance) of the user to block.
         :returns:
@@ -470,6 +474,8 @@ def block(self, username: users.UserLike) -> bool:
     def unblock(self, username: users.UserLike) -> bool:
         """Unblock a specific user from an organization.
 
+        .. versionadded:: 2.1.0
+
         :parameter str username:
             Name (or user-like instance) of the user to unblock.
         :returns:
@@ -484,6 +490,8 @@ def unblock(self, username: users.UserLike) -> bool:
     def is_blocking(self, username: users.UserLike) -> bool:
         """Check if this organization is blocking a specific user.
 
+        .. versionadded:: 2.1.0
+
         :parameter str username:
             Name (or user-like instance) of the user to unblock.
         :returns: