Repository: hikari-py/hikari
Pull request #2018 (2024-08-15 13:08:07)

Bump griffe-inherited-docstrings from 1.0.0 to 1.0.1
Bumps [griffe-inherited-docstrings](https://github.com/mkdocstrings/griffe-inherited-docstrings) from 1.0.0 to 1.0.1.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/releases">griffe-inherited-docstrings's releases</a>.</em></p>
<blockquote>
<h2>1.0.1</h2>
<h2><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/releases/tag/1.0.1">1.0.1</a> - 2024-08-15</h2>
<p><!-- raw HTML omitted --><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/compare/1.0.0...1.0.1">Compare with 1.0.0</a><!-- raw HTML omitted --></p>
<h3>Build</h3>
<ul>
<li>Depend on Griffe 0.49 (<a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/ce6bf5fe21e839aa7e1b9b84c9c531a5841ece3c">ce6bf5f</a> by Timothée Mazzucotelli).</li>
</ul>
<h3>Code Refactoring</h3>
<ul>
<li>Update code for Griffe 0.49 (<a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/b975f7f523c369c9ab3bc889cf9f558ef7c133a0">b975f7f</a> by Timothée Mazzucotelli).</li>
</ul>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/blob/main/CHANGELOG.md">griffe-inherited-docstrings's changelog</a>.</em></p>
<blockquote>
<h2><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/releases/tag/1.0.1">1.0.1</a> - 2024-08-15</h2>
<p><!-- raw HTML omitted --><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/compare/1.0.0...1.0.1">Compare with 1.0.0</a><!-- raw HTML omitted --></p>
<h3>Build</h3>
<ul>
<li>Depend on Griffe 0.49 (<a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/ce6bf5fe21e839aa7e1b9b84c9c531a5841ece3c">ce6bf5f</a> by Timothée Mazzucotelli).</li>
</ul>
<h3>Code Refactoring</h3>
<ul>
<li>Update code for Griffe 0.49 (<a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/b975f7f523c369c9ab3bc889cf9f558ef7c133a0">b975f7f</a> by Timothée Mazzucotelli).</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/100d391e4da994d4ff67a3d0622b0c8b4387ec81"><code>100d391</code></a> chore: Prepare release 1.0.1</li>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/ce6bf5fe21e839aa7e1b9b84c9c531a5841ece3c"><code>ce6bf5f</code></a> build: Depend on Griffe 0.49</li>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/b975f7f523c369c9ab3bc889cf9f558ef7c133a0"><code>b975f7f</code></a> refactor: Update code for Griffe 0.49</li>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/7abf89d18e2adee9a6825c3eb7c446204a27b9dd"><code>7abf89d</code></a> chore: Template upgrade</li>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/6151aac6d8386a21ae4e809161252e4d3b0b5867"><code>6151aac</code></a> chore: Switch to Copier UV template</li>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/a2faa4fa4307b760a817a91771ec64f2fba343c9"><code>a2faa4f</code></a> chore: Template upgrade</li>
<li><a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/commit/cf7cdd2ba000d3e40d5d13affc6c2bc1829ac92d"><code>cf7cdd2</code></a> docs: Add back insiders goals, needed for docs</li>
<li>See full diff in <a href="https://github.com/mkdocstrings/griffe-inherited-docstrings/compare/1.0.0...1.0.1">compare view</a></li>
</ul>
</details>
<br />


[![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=griffe-inherited-docstrings&package-manager=pip&previous-version=1.0.0&new-version=1.0.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`.

[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)

---

<details>
<summary>Dependabot commands and options</summary>
<br />

You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it
- `@dependabot merge` will merge this PR after your CI passes on it
- `@dependabot squash and merge` will squash and merge this PR after your CI passes on it
- `@dependabot cancel merge` will cancel a previously requested merge and block automerging
- `@dependabot reopen` will reopen this PR if it is closed
- `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
- `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)


</details>


Patch:
diff --git a/changes/2020.feature.md b/changes/2020.feature.md
new file mode 100644
index 00000000..e87de0ac
--- /dev/null
+++ b/changes/2020.feature.md
@@ -0,0 +1,1 @@
+Add `fetch_role` method to `RESTClient`
diff --git a/dev-requirements/mkdocs.txt b/dev-requirements/mkdocs.txt
index 1146dcc3..5bf83ec1 100644
--- a/dev-requirements/mkdocs.txt
+++ b/dev-requirements/mkdocs.txt
@@ -5,7 +5,7 @@ mkdocs-material[imaging]==9.5.31
 
 # Docstring parsing for API reference
 mkdocstrings[python]==0.25.2
-griffe-inherited-docstrings==1.0.0
+griffe-inherited-docstrings==1.0.1
 
 # Generate API reference pages dynamically
 mkdocs-gen-files==0.5.0
diff --git a/hikari/api/rest.py b/hikari/api/rest.py
index 8ad797eb..537f5ab4 100644
--- a/hikari/api/rest.py
+++ b/hikari/api/rest.py
@@ -5926,6 +5926,39 @@ def fetch_bans(
             If an internal error occurs on Discord while handling the request.
         """
 
+    @abc.abstractmethod
+    async def fetch_role(
+        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], role: snowflakes.SnowflakeishOr[guilds.PartialRole]
+    ) -> guilds.Role:
+        """Fetch a single role of a guild.
+
+        Parameters
+        ----------
+        guild
+            The guild to fetch the role from. This may be the
+            object or the ID of an existing guild.
+        role
+            The role to fetch. This may be the object or the
+            ID of an existing role.
+
+        Returns
+        -------
+        hikari.guilds.Role
+            The requested role.
+
+        Raises
+        ------
+        hikari.errors.UnauthorizedError
+            If you are unauthorized to make the request (invalid/missing token).
+        hikari.errors.NotFoundError
+            If the guild or the role is not found.
+        hikari.errors.RateLimitTooLongError
+            Raised in the event that a rate limit occurs that is
+            longer than `max_rate_limit` when making a request.
+        hikari.errors.InternalServerError
+            If an internal error occurs on Discord while handling the request.
+        """
+
     @abc.abstractmethod
     async def fetch_roles(self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild]) -> typing.Sequence[guilds.Role]:
         """Fetch the roles of a guild.
diff --git a/hikari/impl/rest.py b/hikari/impl/rest.py
index f76f4c58..fbceb44c 100644
--- a/hikari/impl/rest.py
+++ b/hikari/impl/rest.py
@@ -3433,6 +3433,15 @@ def fetch_bans(
             self._entity_factory, self._request, guild, newest_first, str(start_at)
         )
 
+    async def fetch_role(
+        self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild], role: snowflakes.SnowflakeishOr[guilds.PartialRole]
+    ) -> guilds.Role:
+        route = routes.GET_GUILD_ROLE.compile(guild=guild, role=role)
+        response = await self._request(route)
+        assert isinstance(response, dict)
+        guild_id = snowflakes.Snowflake(guild)
+        return self._entity_factory.deserialize_role(response, guild_id=guild_id)
+
     async def fetch_roles(self, guild: snowflakes.SnowflakeishOr[guilds.PartialGuild]) -> typing.Sequence[guilds.Role]:
         route = routes.GET_GUILD_ROLES.compile(guild=guild)
         response = await self._request(route)
diff --git a/hikari/internal/routes.py b/hikari/internal/routes.py
index 26ebc20d..484c41fb 100644
--- a/hikari/internal/routes.py
+++ b/hikari/internal/routes.py
@@ -434,6 +434,7 @@ def compile_to_file(
 GET_GUILD_PRUNE: typing.Final[Route] = Route(GET, "/guilds/{guild}/prune")
 POST_GUILD_PRUNE: typing.Final[Route] = Route(POST, "/guilds/{guild}/prune")
 
+GET_GUILD_ROLE: typing.Final[Route] = Route(GET, "/guilds/{guild}/roles/{role}")
 PATCH_GUILD_ROLE: typing.Final[Route] = Route(PATCH, "/guilds/{guild}/roles/{role}")
 DELETE_GUILD_ROLE: typing.Final[Route] = Route(DELETE, "/guilds/{guild}/roles/{role}")
 


Test patch:
diff --git a/tests/hikari/impl/test_rest.py b/tests/hikari/impl/test_rest.py
index 0c068783..b69d752a 100644
--- a/tests/hikari/impl/test_rest.py
+++ b/tests/hikari/impl/test_rest.py
@@ -5130,6 +5130,17 @@ async def test_fetch_ban(self, rest_client):
         rest_client._request.assert_awaited_once_with(expected_route)
         rest_client._entity_factory.deserialize_guild_member_ban.assert_called_once_with({"id": "789"})
 
+    async def test_fetch_role(self, rest_client):
+        role = StubModel(456)
+        expected_route = routes.GET_GUILD_ROLE.compile(guild=123, role=456)
+        rest_client._request = mock.AsyncMock(return_value={"id": "456"})
+        rest_client._entity_factory.deserialize_role = mock.Mock(return_value=role)
+
+        assert await rest_client.fetch_role(StubModel(123), StubModel(456)) is role
+
+        rest_client._request.assert_awaited_once_with(expected_route)
+        rest_client._entity_factory.deserialize_role.assert_called_once_with({"id": "456"}, guild_id=123)
+
     async def test_fetch_roles(self, rest_client):
         role1 = StubModel(456)
         role2 = StubModel(789)