async def create(self) -> guilds.RESTGuild:
route = routes.POST_GUILDS.compile()
payload = data_binding.JSONObjectBuilder()
payload.put("name", self.name)
payload.put_array("roles",
self._roles if self._roles else undefined.UNDEFINED)
payload.put_array(
"channels",
self._channels if self._channels else undefined.UNDEFINED)
payload.put("region", self.region)
payload.put("verification_level", self.verification_level)
payload.put("default_message_notifications",
self.default_message_notifications)
payload.put("explicit_content_filter",
self.explicit_content_filter_level)
if self.icon is not undefined.UNDEFINED:
icon = files.ensure_resource(self.icon)
async with icon.stream(executor=self._executor) as stream:
data_uri = await stream.data_uri()
payload.put("icon", data_uri)
raw_response = await self._request_call(route, json=payload)
response = typing.cast(data_binding.JSONObject, raw_response)
return self._entity_factory.deserialize_rest_guild(response)
def test__put_array_defined(self):
m1 = mock.Mock()
m2 = mock.Mock()
m3 = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put_array("ttt", [m1, m2, m3])
assert builder == {"ttt": [m1, m2, m3]}
def test_put_array_with_conversion_uses_conversion_result(self):
r1 = mock.Mock()
r2 = mock.Mock()
r3 = mock.Mock()
convert = mock.Mock(side_effect=[r1, r2, r3])
builder = data_binding.JSONObjectBuilder()
builder.put_array("www", [object(), object(), object()], conversion=convert)
assert builder == {"www": [r1, r2, r3]}
def test_put_array_with_conversion_passes_raw_input_to_converter(self):
m1 = mock.Mock()
m2 = mock.Mock()
m3 = mock.Mock()
convert = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put_array("xxx", [m1, m2, m3], conversion=convert)
assert convert.call_args_list[0] == mock.call(m1)
assert convert.call_args_list[1] == mock.call(m2)
assert convert.call_args_list[2] == mock.call(m3)
async def request_guild_members(
self,
guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
*,
include_presences: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
query: str = "",
limit: int = 0,
users: undefined.UndefinedOr[typing.Sequence[snowflakes.SnowflakeishOr[
users_.User]]] = undefined.UNDEFINED,
nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
) -> None:
if not query and not limit and not self._intents & intents_.Intents.GUILD_MEMBERS:
raise errors.MissingIntentError(intents_.Intents.GUILD_MEMBERS)
if include_presences and not self._intents & intents_.Intents.GUILD_PRESENCES:
raise errors.MissingIntentError(intents_.Intents.GUILD_PRESENCES)
if users is not undefined.UNDEFINED and (query or limit):
raise ValueError("Cannot specify limit/query with users")
if not 0 <= limit <= 100:
raise ValueError(
"'limit' must be between 0 and 100, both inclusive")
if users is not undefined.UNDEFINED and len(users) > 100:
raise ValueError("'users' is limited to 100 users")
if nonce is not undefined.UNDEFINED and len(bytes(nonce,
"utf-8")) > 32:
raise ValueError(
"'nonce' can be no longer than 32 byte characters long.")
await self._chunking_rate_limit.acquire()
payload = data_binding.JSONObjectBuilder()
payload.put_snowflake("guild_id", guild)
payload.put("presences", include_presences)
payload.put("query", query)
payload.put("limit", limit)
payload.put_snowflake_array("user_ids", users)
payload.put("nonce", nonce)
await self._ws.send_json({
_OP: _REQUEST_GUILD_MEMBERS,
_D: payload
}) # type: ignore[union-attr]
async def update_voice_state(
self,
guild: snowflakes.SnowflakeishOr[guilds.PartialGuild],
channel: typing.Optional[snowflakes.SnowflakeishOr[
channels.GuildVoiceChannel]],
*,
self_mute: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
self_deaf: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
) -> None:
self._check_if_alive()
payload = data_binding.JSONObjectBuilder()
payload.put_snowflake("guild_id", guild)
payload.put_snowflake("channel_id", channel)
payload.put("self_mute", self_mute)
payload.put("self_deaf", self_deaf)
await self._send_json({_OP: _VOICE_STATE_UPDATE, _D: payload})
def build(self, entity_factory: entity_factory_.EntityFactory,
/) -> data_binding.JSONObject:
data = data_binding.JSONObjectBuilder()
data.put("content", self.content)
if self._embeds:
data["embeds"] = [
entity_factory.serialize_embed(embed) for embed in self._embeds
]
data.put("flags", self.flags)
data.put("tts", self.is_tts)
if not undefined.all_undefined(self.mentions_everyone,
self.user_mentions, self.role_mentions):
data["allowed_mentions"] = mentions.generate_allowed_mentions(
self.mentions_everyone, undefined.UNDEFINED,
self.user_mentions, self.role_mentions)
return {"type": self._type, "data": data}
def _serialize_and_store_presence_payload(
self,
idle_since: undefined.UndefinedNoneOr[
datetime.datetime] = undefined.UNDEFINED,
afk: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
activity: undefined.UndefinedNoneOr[
presences.Activity] = undefined.UNDEFINED,
) -> data_binding.JSONObject:
payload = data_binding.JSONObjectBuilder()
if activity is undefined.UNDEFINED:
activity = self._activity
else:
self._activity = activity
if status is undefined.UNDEFINED:
status = self._status
else:
self._status = status
if idle_since is undefined.UNDEFINED:
idle_since = self._idle_since
else:
self._idle_since = idle_since
if afk is undefined.UNDEFINED:
afk = self._is_afk
else:
self._is_afk = afk
payload.put("since", idle_since, conversion=self._serialize_datetime)
payload.put("afk", afk)
payload.put("game", activity, conversion=self._serialize_activity)
# Sending "offline" to the gateway wont do anything, we will have to
# send "invisible" instead for this to work.
if status is presences.Status.OFFLINE:
payload.put("status", "invisible")
else:
payload.put("status", status)
return payload
def test_put_none_and_conversion(self):
mock_convert = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put("foo", None, conversion=mock_convert)
assert builder == {"foo": None}
mock_convert.assert_not_called()
payload.put("position", position)
self._roles.append(payload)
return snowflake_id
def add_category(
self,
name: str,
/,
*,
position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
permission_overwrites: undefined.UndefinedOr[typing.Collection[
channels.PermissionOverwrite]] = undefined.UNDEFINED,
nsfw: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
) -> snowflakes.Snowflake:
snowflake_id = self._new_snowflake()
payload = data_binding.JSONObjectBuilder()
payload.put_snowflake("id", snowflake_id)
payload.put("name", name)
payload.put("type", channels.ChannelType.GUILD_CATEGORY)
payload.put("position", position)
payload.put("nsfw", nsfw)
payload.put_array(
"permission_overwrites",
permission_overwrites,
conversion=self._entity_factory.serialize_permission_overwrite,
)
self._channels.append(payload)
return snowflake_id
def test_put_with_conversion_passes_raw_input_to_converter(self):
m = mock.Mock()
convert = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put("bar", m, conversion=convert)
convert.assert_called_once_with(m)
def test_put_with_conversion_uses_conversion_result(self):
m = mock.Mock()
convert = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put("rawr", m, conversion=convert)
assert builder == {"rawr": convert()}
def test_put_defined(self):
m = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put("bar", m)
assert builder == {"bar": m}
class GuildBuilder(special_endpoints.GuildBuilder):
"""Result type of `hikari.api.rest.RESTClient.guild_builder`.
This is used to create a guild in a tidy way using the HTTP API, since
the logic behind creating a guild on an API level is somewhat confusing
and detailed.
!!! note
This is a helper class that is used by `hikari.api.rest.RESTClient`.
You should only ever need to use instances of this class that are
produced by that API, thus, any details about the constructor are
omitted from the following examples for brevity.
Examples
--------
Creating an empty guild.
```py
guild = await rest.guild_builder("My Server!").create()
```
Creating a guild with an icon
```py
from hikari.files import WebResourceStream
guild_builder = rest.guild_builder("My Server!")
guild_builder.icon = WebResourceStream("cat.png", "http://...")
guild = await guild_builder.create()
```
Adding roles to your guild.
```py
from hikari.permissions import Permissions
guild_builder = rest.guild_builder("My Server!")
everyone_role_id = guild_builder.add_role("@everyone")
admin_role_id = guild_builder.add_role("Admins", permissions=Permissions.ADMINISTRATOR)
await guild_builder.create()
```
!!! warning
The first role must always be the `@everyone` role.
!!! note
If you call `add_role`, the default roles provided by discord will
be created. This also applies to the `add_` functions for
text channels/voice channels/categories.
!!! note
Functions that return a `hikari.snowflakes.Snowflake` do
**not** provide the final ID that the object will have once the
API call is made. The returned IDs are only able to be used to
re-reference particular objects while building the guild format.
This is provided to allow creation of channels within categories,
and to provide permission overwrites.
Adding a text channel to your guild.
```py
guild_builder = rest.guild_builder("My Server!")
category_id = guild_builder.add_category("My safe place")
channel_id = guild_builder.add_text_channel("general", parent_id=category_id)
await guild_builder.create()
```
"""
# Required arguments.
_entity_factory: entity_factory_.EntityFactory = attr.ib(
metadata={attr_extensions.SKIP_DEEP_COPY: True})
_executor: typing.Optional[concurrent.futures.Executor] = attr.ib(
metadata={attr_extensions.SKIP_DEEP_COPY: True})
_name: str = attr.ib()
# Optional args that we kept hidden.
_channels: typing.MutableSequence[data_binding.JSONObject] = attr.ib(
factory=list, init=False)
_counter: int = attr.ib(default=0, init=False)
_request_call: typing.Callable[..., typing.Coroutine[
None, None,
typing.Union[None, data_binding.JSONObject,
data_binding.JSONArray]]] = attr.ib(
metadata={attr_extensions.SKIP_DEEP_COPY: True})
_roles: typing.MutableSequence[data_binding.JSONObject] = attr.ib(
factory=list, init=False)
@property
def name(self) -> str:
return self._name
async def create(self) -> guilds.RESTGuild:
route = routes.POST_GUILDS.compile()
payload = data_binding.JSONObjectBuilder()
payload.put("name", self.name)
payload.put_array("roles",
self._roles if self._roles else undefined.UNDEFINED)
payload.put_array(
"channels",
self._channels if self._channels else undefined.UNDEFINED)
payload.put("region", self.region)
payload.put("verification_level", self.verification_level)
payload.put("default_message_notifications",
self.default_message_notifications)
payload.put("explicit_content_filter",
self.explicit_content_filter_level)
if self.icon is not undefined.UNDEFINED:
icon = files.ensure_resource(self.icon)
async with icon.stream(executor=self._executor) as stream:
data_uri = await stream.data_uri()
payload.put("icon", data_uri)
raw_response = await self._request_call(route, json=payload)
response = typing.cast(data_binding.JSONObject, raw_response)
return self._entity_factory.deserialize_rest_guild(response)
def add_role(
self,
name: str,
/,
*,
color: undefined.UndefinedOr[colors.Colorish] = undefined.UNDEFINED,
colour: undefined.UndefinedOr[colors.Colorish] = undefined.UNDEFINED,
hoist: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
mentionable: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
permissions: undefined.UndefinedOr[
permissions_.Permissions] = undefined.UNDEFINED,
position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
) -> snowflakes.Snowflake:
if not undefined.count(color, colour):
raise TypeError("Cannot specify 'color' and 'colour' together.")
if len(self._roles) == 0:
if name != "@everyone":
raise ValueError(
"First role must always be the '@everyone' role")
if undefined.count(color, colour, hoist, mentionable,
position) != 5:
raise ValueError(
"Cannot pass 'color', 'colour', 'hoist', 'mentionable' nor 'position' to the '@everyone' role."
)
snowflake_id = self._new_snowflake()
payload = data_binding.JSONObjectBuilder()
payload.put_snowflake("id", snowflake_id)
payload.put("name", name)
payload.put("color", color)
payload.put("color", colour)
payload.put("hoist", hoist)
payload.put("mentionable", mentionable)
payload.put("permissions", permissions)
payload.put("position", position)
self._roles.append(payload)
return snowflake_id
def test_put_snowflake_array(self):
builder = data_binding.JSONObjectBuilder()
builder.put_snowflake_array("DESU!", [123, 456, 987, 115])
assert builder == {"DESU!": ["123", "456", "987", "115"]}
def test_put_snowflake_none(self):
builder = data_binding.JSONObjectBuilder()
builder.put_snowflake("wawawa osuremono", None)
assert builder == {"wawawa osuremono": None}
def test_put_undefined_and_conversion(self):
mock_convert = mock.Mock()
builder = data_binding.JSONObjectBuilder()
builder.put("foo", undefined.UNDEFINED, conversion=mock_convert)
assert builder == {}
mock_convert.assert_not_called()
def test_put_snowflake(self, input_value, expected_str):
builder = data_binding.JSONObjectBuilder()
builder.put_snowflake("WAWAWA!", input_value)
assert builder == {"WAWAWA!": expected_str}
def test_is_mapping(self):
assert isinstance(data_binding.JSONObjectBuilder(), typing.Mapping)
def test_put_snowflake_array_conversions(self, input_value, expected_str):
builder = data_binding.JSONObjectBuilder()
builder.put_snowflake_array("WAWAWAH!", [input_value] * 5)
assert builder == {"WAWAWAH!": [expected_str] * 5}
def test_starts_empty(self):
assert data_binding.JSONObjectBuilder() == {}
def test_put_snowflake_array_undefined(self):
builder = data_binding.JSONObjectBuilder()
builder.put_snowflake_array("test", undefined.UNDEFINED)
assert builder == {}
def test_put_undefined(self):
builder = data_binding.JSONObjectBuilder()
builder.put("foo", undefined.UNDEFINED)
assert builder == {}
