element.
- # For black navbar, do "navbar navbar-inverse"
- "navbar_class": "navbar navbar-inverse",
- # Fix navigation bar to top of page?
- # Values: "true" (default) or "false"
- "navbar_fixed_top": "true",
- # Location of link to source.
- # Options are "nav" (default), "footer" or anything else to exclude.
- "source_link_position": "footer",
- # Bootswatch (http://bootswatch.com/) theme.
- #
- # Options are nothing (default) or the name of a valid theme
- # such as "cosmo" or "sandstone".
- #
- # The set of valid themes depend on the version of Bootstrap
- # that's used (the next config option).
- #
- # Currently, the supported themes are:
- # - Bootstrap 2: https://bootswatch.com/2
- # - Bootstrap 3: https://bootswatch.com/3
- "bootswatch_theme": None,
- # Choose Bootstrap version.
- # Values: "3" (default) or "2" (in quotes)
- "bootstrap_version": "3",
-}
-
-# -- Autodoc options ---------------------------------------------------------
-autoclass_content = "both"
-
-autodoc_default_options = {
- # "member-order": "bysource",
- # "member-order": "alphabetical",
- "member-order": "groupwise",
- "undoc-members": False,
- "exclude-members": "__weakref__",
- "show_inheritance": True,
- "inherited_members": True,
- "members": True,
-}
-
-# -- Intersphinx options -----------------------------------------------------
-intersphinx_mapping = {
- "python": ("https://docs.python.org/3", None),
- "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
- "websockets": ("https://websockets.readthedocs.io/en/stable/", None),
-}
-
-# -- Autosummary settings... ---------------------------------------------
-
-autosummary_generate_overwrite = False
-
-# -- Epilog to inject into each page... ---------------------------------------------
-
-
-rst_epilog = """
-.. |rawEvent| replace:: This is is a raw event. This means that it is fired with the raw data sent by Discord's gateway
- without any form of pre-processing or validation. Corresponding information may be incorrect,
- sent multiple times, or refer to information that is not cached. The implementation specifics
- of this are documented on the developer portal for Discord at
- https://discordapp.com/developers/docs/topics/gateway#commands-and-events
-
-.. |selfHealing| replace:: You do not have to do anything in this situation. The gateway client in Hikari will attempt
- to resolve these issues for you.
-"""
-
-if not is_staging:
- rst_epilog += textwrap.dedent(
- """.. |staging_link| replace:: If you want the latest staging documentation instead, please visit
- `this page
`__."""
- )
-else:
- rst_epilog += textwrap.dedent(
- """.. |staging_link| replace:: This is the documentation for the development release"""
- )
-
-
-def setup(app):
- app.add_stylesheet("style.css")
-
- # Little easteregg.
- try:
- if datetime.datetime.now().month == 12:
- with requests.get("http://www.schillmania.com/projects/snowstorm/snowstorm.js") as resp:
- resp.raise_for_status()
- with open("docs/_static/snowstorm.js", "w") as fp:
- fp.write(resp.text)
- app.add_javascript("snowstorm.js")
- except Exception:
- traceback.print_exc()
diff --git a/docs/config.mako b/docs/config.mako
new file mode 100644
index 0000000000..a3b7eef318
--- /dev/null
+++ b/docs/config.mako
@@ -0,0 +1,59 @@
+
+
+<%!
+ from distutils import version as _version
+
+ import hikari as _hikari
+
+ show_inherited_members = True
+ extract_module_toc_into_sidebar = True
+ list_class_variables_in_index = True
+ sort_identifiers = True
+ show_type_annotations = True
+
+ show_source_code = True
+
+ git_link_template = "https://gitlab.com/nekokatt/hikari/blob/{commit}/{path}#L{start_line}-L{end_line}"
+
+ link_prefix = ""
+
+ hljs_style = "atom-one-dark"
+
+ if "dev" in _version.LooseVersion(_hikari.__version__).version:
+ search_query = "inurl:github.com/nekokatt/hikari site:nekokatt.gitlab.io/hikari/hikari"
+ else: # TODO: "hikari/staging/hikari" temporarily changed to "hikari/hikari" for staging site search link.
+ search_query = "inurl:github.com/nekokatt/hikari site:nekokatt.gitlab.io/hikari/hikari"
+
+ site_accent = "#ff029a"
+ site_logo = "https://nekokatt.gitlab.io/hikari/logo.png"
+ site_description = "A Discord Bot framework for modern Python and asyncio built on good intentions"
+
+ # Versions of stuff
+ mathjax_version = "2.7.5"
+ bootstrap_version = "4.5.0"
+ highlightjs_version = "9.12.0"
+ jquery_version = "3.5.1"
+ popperjs_version = "1.16.0"
+
+ root_url = "https://gitlab.com/nekokatt/hikari"
+%>
diff --git a/docs/css.mako b/docs/css.mako
new file mode 100644
index 0000000000..b048dd454d
--- /dev/null
+++ b/docs/css.mako
@@ -0,0 +1,231 @@
+* {
+ scrollbar-color: #202324 #454a4d;
+ scroll-behavior: smooth;
+}
+
+img#logo {
+ border-radius: 15px;
+ width: 30px;
+ height: 30px;
+ margin-right: 0.5em;
+}
+
+small.smaller {
+ font-size: 0.75em;
+}
+
+body {
+ background-color: #181A1B;
+ color: #C9C5C0;
+}
+
+h1 {
+ margin-top: 3rem;
+}
+
+h2 {
+ margin-top: 1.75rem;
+ margin-bottom: 1em;
+}
+
+h3 {
+ margin-top: 1.25rem;
+}
+
+h4 {
+ margin-top: 1rem;
+}
+
+.nav-section {
+ margin-top: 2em;
+}
+
+.monospaced {
+ font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+}
+
+a.sidebar-nav-pill,
+a.sidebar-nav-pill:active,
+a.sidebar-nav-pill:hover {
+ color: #BDB7AF;
+}
+
+.module-source > details > pre {
+ display: block;
+ overflow-x: auto;
+ overflow-y: auto;
+ max-height: 600px;
+ font-size: 0.8em;
+}
+
+a {
+ color: #DE4F91;
+}
+
+a:hover {
+ color: #64B1F2;
+}
+
+.jumbotron {
+ background-color: #232627;
+}
+
+.breadcrumb-item.inactive > a {
+ color: #d264d0 !important;
+}
+
+.breadcrumb-item.active > a {
+ color: #de4f91 !important;
+}
+
+.breadcrumb-item+.breadcrumb-item::before {
+ content: ".";
+}
+
+.module-breadcrumb {
+ padding-left: 0 !important;
+ background-color: #232627;
+}
+
+ul.nested {
+ margin-left: 1em;
+}
+
+h2#parameters::after {
+ margin-left: 2em;
+}
+
+dt {
+ margin-left: 2em;
+}
+
+dd {
+ margin-left: 4em;
+}
+
+dl.no-nest > dt {
+ margin-left: 0em;
+}
+
+dl.no-nest > dd {
+ margin-left: 2em;
+}
+
+dl.root {
+ margin-bottom: 2em;
+}
+
+.definition {
+ display: block;
+ margin-bottom: 8em !important;
+}
+
+.definition .row {
+ display: block;
+ margin-bottom: 4em !important;
+}
+
+.definition h2 {
+ font-size: 1em;
+ font-weight: bolder;
+}
+
+.sep {
+ height: 2em;
+}
+
+code {
+ color: #DB61D9;
+}
+
+## Check this to change it
+code .active {
+ color: #e83e8c;
+}
+
+code a {
+ color: #E94A93;
+}
+
+a.dotted:hover, abbr:hover {
+ text-decoration: underline #9E9689 dotted !important;
+}
+
+a.dotted, abbr {
+ text-decoration: none !important;
+}
+
+## Custom search formatting to look somewhat bootstrap-py
+.gsc-search-box, .gsc-search-box-tools, .gsc-control-cse {
+ background: none !important;
+ border: none !important;
+}
+
+.gsc-search-button-v2, .gsc-search-button-v2:hover, .gsc-search-button-v2:focus {
+ color: var(--success) !important;
+ border-color: var(--success) !important;
+ background: none !important;
+ padding: 6px 32px !important;
+ font-size: inherit !important;
+}
+
+.gsc-search-button-v2 > svg {
+ fill: var(--success) !important;
+}
+
+.gsc-input-box {
+ border-radius: 3px;
+}
+
+.gsc-control-cse {
+ width: 300px !important;
+ margin-top: 0 !important;
+}
+
+.gsc-control-cse .gsc-control-cse-en {
+ margin-top: 0 !important;
+}
+
+.bg-dark {
+ background-color: #2C2F31 !important;
+}
+
+.text-muted {
+ color: #9E9689 !important;
+}
+
+.alert-primary {
+ color: #7CC3FF;
+ background-color: #262A2B;
+ border-color: #003B7B;
+}
+
+.alert-secondary {
+ color: #C2BCB4;
+ background-color: #282B2C;
+ border-color: #3B4042;
+}
+
+.alert-success {
+ color: #99E6AB;
+ background-color: #1A3E29;
+ border-color: #255A32;
+}
+
+.alert-info {
+ color: #8EE3F1;
+ background-color: #143B43;
+ border-color: #1E5961;
+}
+
+.alert-warning {
+ color: #FBD770;
+ background-color: #513E00;
+ border-color: #7B5C00;
+}
+
+.alert-danger {
+ color: rgb(225, 134, 143);
+ background-color: rgb(67, 12, 17);
+ border-color: rgb(104, 18, 27);
+}
\ No newline at end of file
diff --git a/docs/documentation.mako b/docs/documentation.mako
new file mode 100644
index 0000000000..912ab900eb
--- /dev/null
+++ b/docs/documentation.mako
@@ -0,0 +1,936 @@
+<%!
+ import os
+ import typing
+ import builtins
+ import importlib
+ import inspect
+ import re
+ import sphobjinv
+ import urllib.error
+
+ inventory_urls = [
+ "https://docs.python.org/3/objects.inv",
+ "https://docs.aiohttp.org/en/stable/objects.inv",
+ "https://www.attrs.org/en/stable/objects.inv",
+ "https://multidict.readthedocs.io/en/latest/objects.inv",
+ "https://yarl.readthedocs.io/en/latest/objects.inv",
+ ]
+
+ inventories = {}
+
+ for i in inventory_urls:
+ try:
+ print("Prefetching", i)
+ inv = sphobjinv.Inventory(url=i)
+ url, _, _ = i.partition("objects.inv")
+ inventories[url] = inv.json_dict()
+ except urllib.error.URLError as ex:
+ # Ignore not being able to fetch inventory when not on CI
+ if "CI" not in os.environ:
+ print(f"Not able to prefetch {i}. Will continue without it")
+ else:
+ raise ex from None
+
+ located_external_refs = {}
+ unlocatable_external_refs = set()
+
+ def discover_source(fqn):
+ if fqn in unlocatable_external_refs:
+ return
+
+ if fqn.startswith("builtins."):
+ fqn = fqn.replace("builtins.", "")
+
+ if fqn not in located_external_refs:
+ # print("attempting to find intersphinx reference for", fqn)
+ for base_url, inv in inventories.items():
+ for obj in inv.values():
+ if isinstance(obj, dict) and obj["name"] == fqn:
+ uri_frag = obj["uri"]
+ if uri_frag.endswith("$"):
+ uri_frag = uri_frag[:-1] + fqn
+
+ url = base_url + uri_frag
+ # print("discovered", fqn, "at", url)
+ located_external_refs[fqn] = url
+ break
+ try:
+ return located_external_refs[fqn]
+ except KeyError:
+ # print("blacklisting", fqn, "as it cannot be dereferenced from external documentation")
+ unlocatable_external_refs.add(fqn)
+
+ project_inventory = sphobjinv.Inventory()
+
+ import atexit
+
+ @atexit.register
+ def dump_inventory():
+ import hikari
+
+ project_inventory.project = "hikari"
+ project_inventory.version = hikari.__version__
+
+ text = project_inventory.data_file(contract=True)
+ ztext = sphobjinv.compress(text)
+ sphobjinv.writebytes('public/objects.inv', ztext)
+
+
+ # To get links to work in type hints to builtins, we do a bit of hacky search-replace using regex.
+ # This generates regex to match general builtins in typehints.
+ builtin_patterns = [
+ re.compile(f"(?
+<%
+ import abc
+ import ast
+ import enum
+ import functools
+ import inspect
+ import re
+ import textwrap
+
+ import pdoc
+
+ from pdoc.html_helpers import extract_toc, glimpse, to_html as _to_html, format_git_link
+
+ # Allow imports to resolve properly.
+ typing.TYPE_CHECKING = True
+
+
+ QUAL_ABC = "abstract "
+ QUAL_ABSTRACT = "abstract "
+ QUAL_ASYNC_DEF = "async def "
+ QUAL_CLASS = "class "
+ QUAL_DATACLASS = "dataclass "
+ QUAL_CACHED_PROPERTY = "cached property "
+ QUAL_CONST = "const "
+ QUAL_DEF = "def "
+ QUAL_ENUM = "enum "
+ QUAL_ENUM_FLAG = "enum flag "
+ QUAL_EXCEPTION = "exception "
+ QUAL_EXTERNAL = "extern "
+ QUAL_INTERFACE = "abstract trait "
+ QUAL_METACLASS = "meta "
+ QUAL_MODULE = "module "
+ QUAL_NAMESPACE = "namespace "
+ QUAL_PACKAGE = "package "
+ QUAL_PROPERTY = "property "
+ QUAL_PROTOCOL = "trait "
+ QUAL_TYPEHINT = "type hint "
+ QUAL_VAR = "var "
+ QUAL_WARNING = "warning "
+
+ def get_url_for_object_from_imports(name, dobj):
+ if dobj.module:
+ fqn = dobj.module.obj.__name__ + "." + dobj.obj.__qualname__
+ elif hasattr(dobj.obj, "__module__"):
+ fqn = dobj.obj.__module__ + "." + dobj.obj.__qualname__
+ else:
+ fqn = dobj.name
+
+ url = discover_source(fqn)
+ if url is None:
+ url = discover_source(name)
+
+ if url is None:
+ url = get_url_from_imports(fqn)
+
+ return url
+
+ def get_url_from_imports(fqn):
+ if fqn_match := re.match(r"([a-z_]+)\.((?:[^\.]|^\s)+)", fqn):
+ if import_match := re.search(f"from (.*) import (.*) as {fqn_match.group(1)}", module.source):
+ old_fqn = fqn
+ fqn = import_match.group(1) + "." + import_match.group(2) + "." + fqn_match.group(2)
+ try:
+ return pdoc._global_context[fqn].url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+ # print(old_fqn, "->", fqn, "via", url)
+ except KeyError:
+ # print("maybe", fqn, "is external but aliased?")
+ return discover_source(fqn)
+ elif import_match := re.search(f"from (.*) import {fqn_match.group(1)}", module.source):
+ old_fqn = fqn
+ fqn = import_match.group(1) + "." + fqn_match.group(1) + "." + fqn_match.group(2)
+ try:
+ return pdoc._global_context[fqn].url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+ # print(old_fqn, "->", fqn, "via", url)
+ except KeyError:
+ # print("maybe", fqn, "is external but aliased?")
+ return discover_source(fqn)
+ elif import_match := re.search(f"import (.*) as {fqn_match.group(1)}", module.source):
+ old_fqn = fqn
+ fqn = import_match.group(1) + "." + fqn_match.group(2)
+ try:
+ return pdoc._global_context[fqn].url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+ # print(old_fqn, "->", fqn, "via", url)
+ except KeyError:
+ # print("maybe", fqn, "is external but aliased?")
+ return discover_source(fqn)
+ else:
+ return None
+
+ def get_url_to_object_maybe_module(dobj):
+ try:
+ # ref = dobj if not hasattr(dobj.obj, "__module__") else pdoc._global_context[dobj.obj.__module__ + "." + dobj.obj.__qualname__]
+ ref = pdoc._global_context[dobj.obj.__module__ + "." + dobj.obj.__qualname__]
+ return ref.url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+ except Exception:
+ return dobj.url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+
+ def debuiltinify(phrase: str):
+ if phrase.startswith("builtins."):
+ phrase = phrase[len("builtins."):]
+ elif phrase.startswith("typing."):
+ phrase = phrase[len("typing."):]
+ elif phrase.startswith("asyncio."):
+ phrase = phrase[len("asyncio."):]
+ return phrase
+
+ # Fixed Linkify that works with nested type hints...
+ def _fixed_linkify(match: typing.Match, *, link: typing.Callable[..., str], module: pdoc.Module, wrap_code=False):
+ #print("matched", match.groups(), match.group())
+
+ try:
+ code_span = match.group('code')
+ except IndexError:
+ code_span = match.group()
+
+ if code_span.startswith("`") and code_span.endswith("`"):
+ code_span = codespan[1:-1]
+
+ try:
+ # If it doesn't parse, it isn't a valid reference.
+ ast.parse(code_span)
+
+ # Extract identifiers.
+ items = list(re.finditer(r"(\w|\.)+", code_span))[::-1]
+
+ # For each identifier, replace it with a link.
+ for match in items:
+ phrase = match.group()
+
+ ident = module.find_ident(phrase)
+
+ if isinstance(ident, pdoc.External):
+ phrase = debuiltinify(ident.name)
+
+ url = get_url_for_object_from_imports(phrase, ident)
+
+ if url is None:
+ bits = ident.name.split(".")[:-1]
+
+ while bits:
+ partial_phrase = ".".join(bits)
+ if partial_phrase in pdoc._global_context:
+ url = pdoc._global_context[partial_phrase].url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+ a_tag = f"{repr(phrase)[1:-1]} "
+ break
+
+ bits = bits[:-1]
+ else:
+ a_tag = phrase
+ else:
+ a_tag = f"{repr(phrase)[1:-1]} "
+
+
+ else:
+ url = ident.url(relative_to=module, link_prefix=link_prefix, top_ancestor=not show_inherited_members)
+ a_tag = f"{repr(ident.name)[1:-1]} "
+
+ chunk = slice(*match.span())
+ code_span = "".join((
+ code_span[:chunk.start],
+ a_tag,
+ code_span[chunk.stop:],
+ ))
+
+ if wrap_code:
+ code_span = code_span.replace('[', '\\[')
+
+
+ except SyntaxError:
+ """Raised if it wasn't a valid piece of Python that was given.
+
+ This can happen with `builtins.True`, `builtins.False` or
+ `builtins.None`
+ """
+ if code_span.startswith("builtins."):
+ phrase = debuiltinify(code_span)
+ url = discover_source(code_span)
+ code_span = f"{repr(phrase)[1:-1]} "
+
+
+ if wrap_code:
+ # Wrapping in HTML as opposed to backticks evaluates markdown */_ markers,
+ # so let's escape them in text (but not in HTML tag attributes).
+ # Backticks also cannot be used because html returned from `link()`
+ # would then become escaped.
+ # This finds overlapping matches, https://stackoverflow.com/a/5616910/1090455
+ cleaned = re.sub(r'(_(?=[^>]*?(?:<|$)))', r'\\\1', code_span)
+ return '{}'.format(cleaned)
+ return code_span
+
+
+ from pdoc import html_helpers
+ html_helpers._linkify = _fixed_linkify
+
+ # Help, it is a monster!
+ def link(
+ dobj: pdoc.Doc,
+ *,
+ with_prefixes=False,
+ simple_names=False,
+ css_classes="",
+ name=None,
+ default_type="",
+ dotted=True,
+ anchor=False,
+ fully_qualified=False,
+ hide_ref=False,
+ recurse=True,
+ ):
+ prefix = ""
+ name = name or dobj.name
+
+ name = debuiltinify(name)
+
+ show_object = False
+ if with_prefixes:
+ if isinstance(dobj, pdoc.Function):
+ qual = QUAL_ASYNC_DEF if dobj._is_async else QUAL_DEF
+
+ if not simple_names:
+ if getattr(dobj.obj, "__isabstractmethod__", False):
+ prefix = f"{QUAL_ABSTRACT} "
+
+ prefix = "" + prefix + qual + " {prefix}{qual} {prefix}{QUAL_TYPEHINT} {prefix}{QUAL_CONST} {prefix}{QUAL_VAR} {qual} {qual} {QUAL_EXTERNAL} {default_type} {default_type} {} {}'.format(prefix, dobj.name + " -- " + glimpse(dobj.docstring), url, anchor, class_str, name, extra)
+
+ def simple_name(s):
+ _, _, name = s.rpartition(".")
+ return name
+
+ def get_annotation(bound_method, sep=':'):
+ annot = bound_method(link=link)
+
+ annot = annot.replace("NoneType", "None")
+ # Remove quotes.
+ if annot.startswith("'") and annot.endswith("'"):
+ annot = annot[1:-1]
+
+ if annot.startswith("builtins."):
+ annot = annot[len("builtins."):]
+
+ if annot:
+ annot = ' ' + sep + '\N{NBSP}' + annot
+
+ # for pattern in builtin_patterns:
+ # annot = pattern.sub(r"builtins.\1", annot)
+
+ return annot
+
+ def to_html(text):
+ text = _to_html(text, module=module, link=link, latex_math=latex_math)
+ replacements = [
+ ('class="admonition info"', 'class="alert alert-primary"'),
+ ('class="admonition warning"', 'class="alert alert-warning"'),
+ ('class="admonition danger"', 'class="alert alert-danger"'),
+ ('class="admonition note"', 'class="alert alert-success"')
+ ]
+
+ for before, after in replacements:
+ text = text.replace(before, after)
+
+ return text
+%>
+
+<%def name="ident(name)">${name}
+
+<%def name="breadcrumb()">
+ <%
+ module_breadcrumb = []
+
+ sm = module
+ while sm is not None:
+ module_breadcrumb.append(sm)
+ sm = sm.supermodule
+
+ module_breadcrumb.reverse()
+ %>
+
+
+
+ % for m in module_breadcrumb:
+ % if m is module:
+ ${m.name | simple_name} ${link(m, with_prefixes=False, simple_names=True)}
+ % endif
+ % endfor
+
+
+
+
+<%def name="show_var(v, is_nested=False)">
+ <%
+ return_type = get_annotation(v.type_annotation)
+ parent = v.cls.obj if v.cls is not None else v.module.obj
+ if return_type == "":
+
+ if hasattr(parent, "mro"):
+ for cls in parent.mro():
+ if hasattr(cls, "__annotations__") and v.name in cls.__annotations__:
+ return_type = get_annotation(lambda *_, **__: cls.__annotations__[v.name])
+ if return_type != "":
+ break
+
+ if hasattr(parent, "__annotations__") and v.name in parent.__annotations__:
+ return_type = get_annotation(lambda *_, **__: parent.__annotations__[v.name])
+
+ value = None
+ if v.cls is not None:
+ try:
+ obj = getattr(v.cls.obj, v.name)
+
+ simple_bases = (
+ bytes, int, bool, str, float, complex, list, set, frozenset, dict, tuple, type(None),
+ enum.Enum, typing.Container
+ )
+
+ if isinstance(obj, simple_bases):
+ value = str(obj)
+
+ # Combined enum tidyup
+ if value.count("|") > 3 and isinstance(obj, enum.Enum):
+ start = "\n\N{EM SPACE}\N{EM SPACE}\N{EM SPACE}"
+ value = f"({start} " + f"{start} | ".join(value.split(" | ")) + "\n)"
+
+ except Exception as ex:
+ print(v.name, type(ex).__name__, ex)
+
+ if value:
+ return_type += f" = {value}"
+
+ if hasattr(parent, "mro"):
+ name = f"{parent.__module__}.{parent.__qualname__}.{v.name}"
+ else:
+ name = f"{parent.__name__}.{v.qualname}"
+
+ project_inventory.objects.append(
+ sphobjinv.DataObjStr(
+ name = name,
+ domain = "py",
+ role = "var",
+ uri = v.url(),
+ priority = "1",
+ dispname = "-",
+ )
+ )
+ %>
+
+ ${link(v, with_prefixes=True, anchor=True)}${return_type}
+ ${v.docstring | to_html}
+
+
+<%def name="show_func(f, is_nested=False)">
+ <%
+ params = f.params(annotate=show_type_annotations, link=link)
+ return_type = get_annotation(f.return_annotation, '->')
+ qual = QUAL_ASYNC_DEF if f._is_async else QUAL_DEF
+
+ example_str = qual + f.name + "(" + ", ".join(params) + ")" + return_type
+
+ if params and params[0] in ("self", "mcs", "mcls", "metacls"):
+ params = params[1:]
+
+ if len(params) > 4 or len(params) > 0 and len(example_str) > 70:
+ representation = "\n".join((
+ qual + " " + f.name + "(",
+ *(f" {p}," for p in params),
+ ")" + return_type + ": ..."
+ ))
+
+ elif params:
+ representation = f"{qual} {f.name}({', '.join(params)}){return_type}: ..."
+ else:
+ representation = f"{qual} {f.name}(){return_type}: ..."
+
+ if f.module.name != f.obj.__module__:
+ try:
+ ref = pdoc._global_context[f.obj.__module__ + "." + f.obj.__qualname__]
+ redirect = True
+ except KeyError:
+ redirect = False
+ else:
+ redirect = False
+
+ if not redirect:
+ project_inventory.objects.append(
+ sphobjinv.DataObjStr(
+ name = f.obj.__module__ + "." + f.obj.__qualname__,
+ domain = "py",
+ role = "func",
+ uri = f.url(),
+ priority = "1",
+ dispname = "-",
+ )
+ )
+ %>
+
+ ${representation}
+
+ % if inspect.isabstract(f.obj):
+ This function is abstract!
+ % endif
+ % if redirect:
+ ${show_desc(f, short=True)}
+ This function is defined explicitly at ${link(ref, with_prefixes=False, fully_qualified=True)}. Visit that link to view the full documentation!
+ % else:
+ ${show_desc(f)}
+
+ ${show_source(f)}
+ % endif
+
+
+
+
+
+<%def name="show_class(c, is_nested=False)">
+ <%
+ variables = c.instance_variables(show_inherited_members, sort=sort_identifiers) + c.class_variables(show_inherited_members, sort=sort_identifiers)
+ methods = c.methods(show_inherited_members, sort=sort_identifiers) + c.functions(show_inherited_members, sort=sort_identifiers)
+ mro = c.mro()
+ subclasses = c.subclasses()
+
+ # No clue why I need to do this, and I don't care at this point. This hurts my brain.
+ params = [p.replace("builtins.", "") for p in c.params(annotate=show_type_annotations, link=link)]
+
+ example_str = f"{QUAL_CLASS} " + c.name + "(" + ", ".join(params) + ")"
+
+ suppress_params = getattr(c.obj, "_is_protocol", False)
+
+ if not suppress_params and (len(params) > 4 or len(example_str) > 70 and len(params) > 0):
+ representation = "\n".join((
+ f"{QUAL_CLASS} {c.name} (",
+ *(f" {p}," for p in params),
+ "): ..."
+ ))
+ elif params and not suppress_params:
+ representation = f"{QUAL_CLASS} {c.name} (" + ", ".join(params) + "): ..."
+ else:
+ representation = f"{QUAL_CLASS} {c.name}: ..."
+
+ if c.module.name != c.obj.__module__:
+ try:
+ ref = pdoc._global_context[c.obj.__module__ + "." + c.obj.__qualname__]
+ redirect = True
+ except KeyError:
+ redirect = False
+ else:
+ redirect = False
+
+ if not redirect:
+ project_inventory.objects.append(
+ sphobjinv.DataObjStr(
+ name = c.obj.__module__ + "." + c.obj.__qualname__,
+ domain = "py",
+ role = "class",
+ uri = c.url(),
+ priority = "1",
+ dispname = "-",
+ )
+ )
+ %>
+
+ % if redirect:
+ reference to ${link(c, with_prefixes=True, simple_names=True)}${link(c, with_prefixes=True, simple_names=True)}
+ % endif
+
+
+ % if redirect:
+
+
+ Expand signature
+
+ % endif
+ ${representation}
+ ${show_desc(c, short=True)}
+ This class is defined explicitly at ${link(ref, with_prefixes=False, fully_qualified=True)}. Visit that link to view the full documentation!
+ % else:
+ ${show_desc(c)}
+
+ ${show_source(c)}
+
+
+ % if subclasses:
+ Subclasses
+
+ % for sc in subclasses:
+ % if not isinstance(sc, pdoc.External):
+ ${link(sc, with_prefixes=True, default_type="class")}
+ ${sc.docstring or sc.obj.__doc__ | glimpse, to_html}
+ % endif
+ % endfor
+
+
+ % endif
+
+ % if mro:
+ Method resolution order
+
+ ${link(c, with_prefixes=True)}
+ That's this class! ${link(mro_c, with_prefixes=True, default_type="class")}
+ ${mro_c.docstring | glimpse, to_html}
+ % endfor
+
+
+ % endif
+
+ % if methods:
+ Methods
+
+ % for m in methods:
+ ${show_func(m)}
+ % endfor
+
+
+ % endif
+
+ % if variables:
+ Variables and properties
+
+ % for i in variables:
+ ${show_var(i)}
+ % endfor
+
+
+ % endif
+ % endif
+
+
+
+<%def name="show_desc(d, short=False)">
+ <%
+ inherits = ' inherited' if d.inherits else ''
+ docstring = d.docstring or d.obj.__doc__
+ %>
+ % if not short:
+ % if d.inherits:
+
+ Inherited from: ${link(d.inherits.cls, with_prefixes=False)}.${link(d.inherits, name=d.name, with_prefixes=False)}
+ % else:
+ ${link(d.inherits, with_prefixes=False)}
+ % endif
+
+ % endif
+
+ ${docstring | to_html}
+ % else:
+ ${docstring | glimpse, to_html}
+ % endif
+
+
+<%def name="show_source(d)">
+ % if (show_source_code or git_link_template) and d.source and d.obj is not getattr(d.inherits, 'obj', None):
+ <% git_link = format_git_link(git_link_template, d) %>
+ % if show_source_code:
+
+
+ Expand source code
+ % if git_link:
+ Browse git
+ %endif
+
+ ${d.source | h}
+ % elif git_link:
+
+ %endif
+ %endif
+
+
+
+
+
${breadcrumb()}
+
${module.docstring | to_html}
+
+
+
+ <%
+ variables = module.variables(sort=sort_identifiers and module.name != "hikari")
+ classes = module.classes(sort=sort_identifiers and module.name != "hikari")
+ functions = module.functions(sort=sort_identifiers and module.name != "hikari")
+ submodules = module.submodules()
+ supermodule = module.supermodule
+
+ project_inventory.objects.append(
+ sphobjinv.DataObjStr(
+ name = module.name,
+ domain = "py",
+ role = "module",
+ uri = module.url(),
+ priority = "1",
+ dispname = "-",
+ )
+ )
+ %>
+
+
+
+ % if submodules:
+
+ % for child_module in submodules:
+ ${link(child_module, with_prefixes=True, css_classes="sidebar-nav-pill", dotted=False, simple_names=True)}
+ % endfor
+
+ % endif
+
+ % if variables or functions or classes:
+
This module
+ % endif
+
+ % if variables:
+
+ % for variable in variables:
+ ${link(variable, with_prefixes=True, css_classes="sidebar-nav-pill", dotted=False, simple_names=True)}
+ % endfor
+
+ % endif
+
+ % if functions:
+
+ % for function in functions:
+ ${link(function, with_prefixes=True, css_classes="sidebar-nav-pill", dotted=False, simple_names=True)}
+ % endfor
+
+ % endif
+
+ % if classes:
+ % for c in classes:
+ ## Purposely using one item per list for layout reasons.
+
+
+ <%
+ if c.module.name != c.obj.__module__:
+ try:
+ ref = pdoc._global_context[c.obj.__module__ + "." + c.obj.__qualname__]
+ redirect = True
+ except KeyError:
+ redirect = False
+ else:
+ redirect = False
+
+ members = c.functions(sort=sort_identifiers) + c.methods(sort=sort_identifiers)
+
+ if list_class_variables_in_index:
+ members += (c.instance_variables(sort=sort_identifiers) + c.class_variables(sort=sort_identifiers))
+
+ if not show_inherited_members:
+ members = [i for i in members if not i.inherits]
+
+ if sort_identifiers:
+ members = sorted(members)
+ %>
+
+ ${link(c, with_prefixes=True, css_classes="sidebar-nav-pill", dotted=False, simple_names=True)}
+
+
+ % if members and not redirect:
+ % for member in members:
+
+ ${link(member, with_prefixes=True, css_classes="sidebar-nav-pill", dotted=False, simple_names=True)}
+
+ % endfor
+ % endif
+
+
+
+
+ % endfor
+ % endif
+
+
+
+
+
+
+ ${show_source(module)}
+
+
+
+
+ % if submodules:
+
Child Modules
+
+
+ % for m in submodules:
+ ${link(m, simple_names=True, with_prefixes=True, anchor=True)}
+ ${m.docstring | glimpse, to_html}
+ % endfor
+
+
+ % endif
+
+ % if variables:
+
Variables and Type Hints
+
+
+ % for v in variables:
+ ${show_var(v)}
+ % endfor
+
+
+ % endif
+
+ % if functions:
+
Functions
+
+
+ % for f in functions:
+ ${show_func(f)}
+ % endfor
+
+
+ % endif
+
+ % if classes:
+
Classes
+
+
+ % for c in classes:
+ ${show_class(c)}
+ % endfor
+
+
+ % endif
+
+
+
+ v${hikari.__version__}
+
+
diff --git a/docs/html.mako b/docs/html.mako
new file mode 100644
index 0000000000..6d1c0f2faf
--- /dev/null
+++ b/docs/html.mako
@@ -0,0 +1,103 @@
+
+
+############################# IMPORTS ##############################
+<%!
+ import os
+ from pdoc import html_helpers
+%>
+
+########################### CONFIGURATION ##########################
+<%include file="config.mako"/>
+############################ COMPONENTS ############################
+
+
+
+
+ Python module list
+ ${module.name} API documentation
+ >.
+
+ shard: typing.Optional[gateway_shard.GatewayShard] = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """Shard that received the event.
+
+ Returns
+ -------
+ hikari.api.shard.GatewayShard
+ Shard that raised this exception.
+
+ This may be `builtins.None` if no specific shard was the cause of this
+ exception (e.g. when starting up or shutting down).
+ """
+
+ exception: Exception = attr.ib()
+ """Exception that was raised.
+
+ Returns
+ -------
+ builtins.Exception
+ Exception that was raised in the event handler.
+ """
+
+ failed_event: FailedEventT = attr.ib()
+ """Event instance that caused the exception.
+
+ Returns
+ -------
+ hikari.events.base_events.Event
+ Event that was being processed when the exception occurred.
+ """
+
+ # MyPy thinks the attr.ib type hint on the `failed_callback` implies it is a function
+ # defined in class scope, and thus thinks referring to it will make it a bound method.
+ # To get around this, we make this attribute hidden and make a property that casts it
+ # for us to remove this effect. This functionally changes nothing but it helps MyPy.
+ _failed_callback: FailedCallbackT[FailedEventT] = attr.ib()
+
+ @property
+ def failed_callback(self) -> FailedCallbackT[FailedEventT]:
+ """Event callback that threw an exception.
+
+ Returns
+ -------
+ callback
+ Event callback that failed execution.
+ """
+ return self._failed_callback
+
+ @property
+ def exc_info(self) -> typing.Tuple[typing.Type[Exception], Exception, typing.Optional[types.TracebackType]]:
+ """Exception triplet that follows the same format as `sys.exc_info`.
+
+ Returns
+ -------
+ builtins.tuple[typing.Type[Exception], Exception, types.TracebackType or builtins.None]
+ The `sys.exc_info`-compatible tuple of the exception type, the
+ exception instance, and the traceback of the exception.
+ """
+ return type(self.exception), self.exception, self.exception.__traceback__
+
+ async def retry(self) -> None:
+ """Invoke the failed event again.
+
+ If an exception is thrown this time, it will need to be manually
+ caught in-code, or will be discarded.
+ """
+ await self._failed_callback(self.failed_event)
diff --git a/hikari/events/channel_events.py b/hikari/events/channel_events.py
new file mode 100644
index 0000000000..71f1e2a6c3
--- /dev/null
+++ b/hikari/events/channel_events.py
@@ -0,0 +1,587 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events that fire when channels are modified.
+
+This does not include message events, nor reaction events.
+"""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "ChannelEvent",
+ "GuildChannelEvent",
+ "PrivateChannelEvent",
+ "ChannelCreateEvent",
+ "GuildChannelCreateEvent",
+ "PrivateChannelCreateEvent",
+ "ChannelUpdateEvent",
+ "GuildChannelUpdateEvent",
+ "PrivateChannelUpdateEvent",
+ "ChannelDeleteEvent",
+ "GuildChannelDeleteEvent",
+ "PrivateChannelDeleteEvent",
+ "PinsUpdateEvent",
+ "GuildPinsUpdateEvent",
+ "PrivatePinsUpdateEvent",
+ "InviteCreateEvent",
+ "InviteDeleteEvent",
+ "WebhookUpdateEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari import traits
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+ from hikari.api import shard as gateway_shard
+ from hikari.models import channels
+ from hikari.models import invites
+ from hikari.models import webhooks
+ from hikari.utilities import snowflake
+
+
+@base_events.requires_intents(intents.Intents.GUILDS, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ChannelEvent(shard_events.ShardEvent, abc.ABC):
+ """Event base for any channel-bound event in guilds or private messages."""
+
+ @property
+ @abc.abstractmethod
+ def channel_id(self) -> snowflake.Snowflake:
+ """ID of the channel the event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the channel this event relates to.
+ """
+
+ async def fetch_channel(self) -> channels.PartialChannel:
+ """Perform an API call to fetch the details about this channel.
+
+ !!! note
+ For `ChannelDeleteEvent`-derived events, this will always raise
+ an exception, since the channel will have already been removed.
+
+ Returns
+ -------
+ hikari.models.channels.PartialChannel
+ A derivative of `hikari.models.channels.PartialChannel`. The actual
+ type will vary depending on the type of channel this event
+ concerns.
+ """
+ return await self.app.rest.fetch_channel(self.channel_id)
+
+
+@base_events.requires_intents(intents.Intents.GUILDS)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildChannelEvent(ChannelEvent, abc.ABC):
+ """Event base for any channel-bound event in guilds."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild that this event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that relates to this event.
+ """
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.GuildChannel:
+ ...
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateChannelEvent(ChannelEvent, abc.ABC):
+ """Event base for any channel-bound event in private messages."""
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.PrivateChannel:
+ ...
+
+
+@base_events.requires_intents(intents.Intents.GUILDS, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ChannelCreateEvent(ChannelEvent, abc.ABC):
+ """Base event for any channel being created."""
+
+ @property
+ @abc.abstractmethod
+ def channel(self) -> channels.PartialChannel:
+ """Channel this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.PartialChannel
+ The channel that was created.
+ """
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.channel.id
+
+
+@base_events.requires_intents(intents.Intents.GUILDS)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildChannelCreateEvent(GuildChannelEvent, ChannelCreateEvent):
+ """Event fired when a guild channel is created."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel: channels.GuildChannel = attr.ib(repr=True)
+ """Guild channel that this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.GuildChannel
+ The guild channel that was created.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.channel.guild_id
+
+
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateChannelCreateEvent(PrivateChannelEvent, ChannelCreateEvent):
+ """Event fired when a private channel is created."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel: channels.PrivateChannel = attr.ib(repr=True)
+ """Private channel that this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.PrivateChannel
+ The guild channel that was created.
+ """
+
+
+@base_events.requires_intents(intents.Intents.GUILDS, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ChannelUpdateEvent(ChannelEvent, abc.ABC):
+ """Base event for any channel being updated."""
+
+ @property
+ @abc.abstractmethod
+ def channel(self) -> channels.PartialChannel:
+ """Channel this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.PartialChannel
+ The channel that was updated.
+ """
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.channel.id
+
+
+@base_events.requires_intents(intents.Intents.GUILDS)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildChannelUpdateEvent(GuildChannelEvent, ChannelUpdateEvent):
+ """Event fired when a guild channel is edited."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel: channels.GuildChannel = attr.ib(repr=True)
+ """Guild channel that this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.GuildChannel
+ The guild channel that was updated.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.channel.guild_id
+
+
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateChannelUpdateEvent(PrivateChannelEvent, ChannelUpdateEvent):
+ """Event fired when a private channel is edited."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel: channels.PrivateChannel = attr.ib(repr=True)
+ """Private channel that this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.PrivateChannel
+ The private channel that was updated.
+ """
+
+
+@base_events.requires_intents(intents.Intents.GUILDS, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ChannelDeleteEvent(ChannelEvent, abc.ABC):
+ """Base event for any channel being deleted."""
+
+ @property
+ @abc.abstractmethod
+ def channel(self) -> channels.PartialChannel:
+ """Channel this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.PartialChannel
+ The channel that was deleted.
+ """
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.channel.id
+
+ if typing.TYPE_CHECKING:
+ # Channel will never be found.
+ async def fetch_channel(self) -> typing.NoReturn:
+ ...
+
+
+@base_events.requires_intents(intents.Intents.GUILDS)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildChannelDeleteEvent(GuildChannelEvent, ChannelDeleteEvent):
+ """Event fired when a guild channel is deleted."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel: channels.GuildChannel = attr.ib(repr=True)
+ """Guild channel that this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.GuildChannel
+ The guild channel that was deleted.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.channel.guild_id
+
+ if typing.TYPE_CHECKING:
+ # Channel will never be found.
+ async def fetch_channel(self) -> typing.NoReturn:
+ ...
+
+
+# TODO: can this actually ever get fired?
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateChannelDeleteEvent(PrivateChannelEvent, ChannelDeleteEvent):
+ """Event fired when a private channel is deleted."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel: channels.PrivateChannel = attr.ib(repr=True)
+ """Private channel that this event represents.
+
+ Returns
+ -------
+ hikari.models.channels.PrivateChannel
+ The private channel that was deleted.
+ """
+
+ if typing.TYPE_CHECKING:
+ # Channel will never be found.
+ async def fetch_channel(self) -> typing.NoReturn:
+ ...
+
+
+# TODO: find out what private message intents are needed.
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PinsUpdateEvent(ChannelEvent, abc.ABC):
+ """Base event fired when a message is pinned/unpinned in a channel."""
+
+ @property
+ @abc.abstractmethod
+ def last_pin_timestamp(self) -> typing.Optional[datetime.datetime]:
+ """Datetime of when the most recent message was pinned in the channel.
+
+ Will be `builtins.None` if nothing is pinned or the information is
+ unavailable.
+
+ Returns
+ -------
+ datetime.datetime or builtins.None
+ The datetime of the most recent pinned message in the channel,
+ or `builtins.None` if no pins are available.
+ """
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.TextChannel:
+ ...
+
+
+@base_events.requires_intents(intents.Intents.GUILDS)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildPinsUpdateEvent(PinsUpdateEvent, GuildChannelEvent):
+ """Event fired when a message is pinned/unpinned in a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ last_pin_timestamp: typing.Optional[datetime.datetime] = attr.ib(repr=True)
+ # <>.
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.GuildTextChannel:
+ ...
+
+
+# TODO: This is not documented as having an intent, is this right? The guild version requires GUILDS intent.
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivatePinsUpdateEvent(PinsUpdateEvent, PrivateChannelEvent):
+ """Event fired when a message is pinned/unpinned in a private channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ last_pin_timestamp: typing.Optional[datetime.datetime] = attr.ib(repr=True)
+ # <>.
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.PrivateTextChannel:
+ ...
+
+
+@base_events.requires_intents(intents.Intents.GUILD_INVITES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class InviteEvent(GuildChannelEvent, abc.ABC):
+ """Base event type for guild invite updates."""
+
+ @property
+ @abc.abstractmethod
+ def code(self) -> str:
+ """Code that is used in the URL for the invite.
+
+ Returns
+ -------
+ builtins.str
+ The invite code.
+ """
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.GuildTextChannel:
+ ...
+
+ async def fetch_invite(self) -> invites.Invite:
+ """Perform an API call to retrieve an up-to-date image of this invite.
+
+ Returns
+ -------
+ hikari.models.invites.Invite
+ The invite object.
+ """
+ return await self.app.rest.fetch_invite(self.code)
+
+
+@base_events.requires_intents(intents.Intents.GUILD_INVITES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class InviteCreateEvent(InviteEvent):
+ """Event fired when an invite is created in a channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ invite: invites.InviteWithMetadata = attr.ib()
+ """Invite that was created.
+
+ Returns
+ -------
+ hikari.models.invites.InviteWithMetaData
+ The created invite object.
+ """
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.invite.channel_id
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ # This will always be non-None for guild channel invites.
+ assert self.invite.guild_id is not None
+ return self.invite.guild_id
+
+ @property
+ def code(self) -> str:
+ # <>.
+ return self.invite.code
+
+
+@base_events.requires_intents(intents.Intents.GUILD_INVITES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class InviteDeleteEvent(InviteEvent):
+ """Event fired when an invite is deleted from a channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ code: str = attr.ib()
+ # <>.
+
+ if typing.TYPE_CHECKING:
+ # Invite will never be found.
+ async def fetch_invite(self) -> typing.NoReturn:
+ ...
+
+
+@base_events.requires_intents(intents.Intents.GUILD_WEBHOOKS)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class WebhookUpdateEvent(GuildChannelEvent):
+ """Event fired when a webhook is created/updated/deleted in a channel.
+
+ Unfortunately, Discord does not provide any information on what webhook
+ actually changed, nor specifically whether it was created/updated/deleted,
+ so this event is pretty useless unless you keep track of the webhooks in
+ the channel manually beforehand.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ async def fetch_channel_webhooks(self) -> typing.Sequence[webhooks.Webhook]:
+ """Perform an API call to fetch the webhooks for this channel.
+
+ Returns
+ -------
+ typing.Sequence[hikari.models.webhooks.Webhook]
+ The webhooks in this channel.
+ """
+ return await self.app.rest.fetch_channel_webhooks(self.channel_id)
+
+ async def fetch_guild_webhooks(self) -> typing.Sequence[webhooks.Webhook]:
+ """Perform an API call to fetch the webhooks for this guild.
+
+ Returns
+ -------
+ typing.Sequence[hikari.models.webhooks.Webhook]
+ The webhooks in this guild.
+ """
+ return await self.app.rest.fetch_guild_webhooks(self.guild_id)
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.GuildTextChannel:
+ ...
diff --git a/hikari/events/guild_events.py b/hikari/events/guild_events.py
new file mode 100644
index 0000000000..89224a7c8b
--- /dev/null
+++ b/hikari/events/guild_events.py
@@ -0,0 +1,516 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events that fire when something occurs within a guild."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "GuildVisibilityEvent",
+ "GuildAvailableEvent",
+ "GuildUnavailableEvent",
+ "GuildLeaveEvent",
+ "GuildUpdateEvent",
+ "BanEvent",
+ "BanCreateEvent",
+ "BanDeleteEvent",
+ "EmojisUpdateEvent",
+ "IntegrationsUpdateEvent",
+ "PresenceUpdateEvent",
+ "MemberChunkEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import channels as channels_
+ from hikari.models import emojis as emojis_
+ from hikari.models import guilds
+ from hikari.models import presences as presences_
+ from hikari.models import users
+ from hikari.models import voices
+ from hikari.utilities import snowflake
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(
+ intents.Intents.GUILDS, intents.Intents.GUILD_BANS, intents.Intents.GUILD_EMOJIS, intents.Intents.GUILD_PRESENCES
+)
+class GuildEvent(shard_events.ShardEvent, abc.ABC):
+ """Event base for any guild-bound event."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild that this event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that relates to this event.
+ """
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class GuildVisibilityEvent(GuildEvent, abc.ABC):
+ """Event base for any event that changes the visibility of a guild.
+
+ This includes when a guild becomes available after an outage, when a
+ guild becomes available on startup, when a guild becomes unavailable due
+ to an outage, when the user is kicked/banned/leaves a guild, or when
+ the user joins a new guild.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class GuildAvailableEvent(GuildVisibilityEvent):
+ """Event fired when a guild becomes available.
+
+ This will occur on startup, after outages, and if the bot joins a new guild.
+
+ !!! note
+ Some fields like `members` and `include_presences` are included here but not on
+ the other `GuildUpdateEvent` and `GuildUnavailableEvent` guild visibility
+ event models.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild: guilds.GatewayGuild = attr.ib()
+ """Guild that just became available.
+
+ Returns
+ -------
+ hikari.models.guilds.Guild
+ The guild that relates to this event.
+ """
+
+ emojis: typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji] = attr.ib(repr=False)
+ """Mapping of emoji IDs to the emojis in the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.emojis.KnownCustomEmoji]
+ The emojis in the guild.
+ """
+
+ roles: typing.Mapping[snowflake.Snowflake, guilds.Role] = attr.ib(repr=False)
+ """Mapping of role IDs to the roles in the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.guilds.Role]
+ The roles in the guild.
+ """
+
+ channels: typing.Mapping[snowflake.Snowflake, channels_.GuildChannel] = attr.ib(repr=False)
+ """Mapping of channel IDs to the channels in the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.channels.GuildChannel]
+ The channels in the guild.
+ """
+
+ members: typing.Mapping[snowflake.Snowflake, guilds.Member] = attr.ib(repr=False)
+ """Mapping of user IDs to the members in the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.guilds.Member]
+ The members in the guild.
+ """
+
+ presences: typing.Mapping[snowflake.Snowflake, presences_.MemberPresence] = attr.ib(repr=False)
+ """Mapping of user IDs to the include_presences for the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.include_presences.MemberPresence]
+ The member include_presences in the guild.
+ """
+
+ voice_states: typing.Mapping[snowflake.Snowflake, voices.VoiceState] = attr.ib(repr=False)
+ """Mapping of user IDs to the voice states active in this guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.voices.VoiceState]
+ The voice states active in the guild.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.guild.id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class GuildLeaveEvent(GuildVisibilityEvent):
+ """Event fired when the bot is banned/kicked/leaves a guild.
+
+ This will also fire if the guild was deleted.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class GuildUnavailableEvent(GuildVisibilityEvent):
+ """Event fired when a guild becomes unavailable because of an outage."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class GuildUpdateEvent(GuildEvent):
+ """Event fired when an existing guild is updated."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild: guilds.GatewayGuild = attr.ib()
+ """Guild that was just updated.
+
+ Returns
+ -------
+ hikari.models.guilds.Guild
+ The guild that relates to this event.
+ """
+
+ emojis: typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji] = attr.ib(repr=False)
+ """Mapping of emoji IDs to the emojis in the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.emojis.KnownCustomEmoji]
+ The emojis in the guild.
+ """
+
+ roles: typing.Mapping[snowflake.Snowflake, guilds.Role] = attr.ib(repr=False)
+ """Mapping of role IDs to the roles in the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.guilds.Role]
+ The roles in the guild.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.guild.id
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_BANS)
+class BanEvent(GuildEvent, abc.ABC):
+ """Event base for any guild ban or unban."""
+
+ @property
+ @abc.abstractmethod
+ def user(self) -> users.User:
+ """User that this ban event affects.
+
+ Returns
+ -------
+ hikari.models.users.User
+ The user that this event concerns.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_BANS)
+class BanCreateEvent(BanEvent):
+ """Event that is fired when a user is banned from a guild."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ user: users.User = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_BANS)
+class BanDeleteEvent(BanEvent):
+ """Event that is fired when a user is unbanned from a guild."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ user: users.User = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_EMOJIS)
+class EmojisUpdateEvent(GuildEvent):
+ """Event that is fired when the emojis in a guild are updated."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emojis: typing.Sequence[emojis_.KnownCustomEmoji] = attr.ib()
+ """Sequence of all emojis in this guild.
+
+ Returns
+ -------
+ typing.Sequence[emojis_.KnownCustomEmoji]
+ All emojis in the guild.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_EMOJIS)
+class IntegrationsUpdateEvent(GuildEvent):
+ """Event that is fired when the integrations in a guild are changed.
+
+ This may occur when integrations are created, updated, or deleted.
+
+ !!! note
+ This event is similar to
+ `hikari.events.channel_events.WebhookUpdateEvent` in that Discord
+ does not provide any information on what was actually changed, nor
+ how it was changed. The only way you will be able to determine this is
+ to keep a cache of this information manually up to date by fetching
+ it using REST API calls. This is a limitation of Discord's design.
+ We agree that it is not overly helpful to you.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_PRESENCES)
+class PresenceUpdateEvent(shard_events.ShardEvent):
+ """Event fired when a user in a guild updates their presence in a guild.
+
+ Sent when a guild member changes their presence in a specific guild.
+
+ If the user is changed (e.g. new username), then this may fire many times
+ (once for every guild the bot is part of). This is a limitation of how
+ Discord implements their event system, unfortunately.
+
+ Furthermore, if the target user is a bot and the bot only updates their
+ presence on specific shards, this will only fire for the corresponding
+ shards that saw the presence update.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ presence: presences_.MemberPresence = attr.ib()
+ """Member presence.
+
+ Returns
+ -------
+ hikari.models.include_presences.MemberPresence
+ Presence for the user in this guild.
+ """
+
+ user: typing.Optional[users.PartialUser] = attr.ib()
+ """User that was updated.
+
+ This is a partial user object that only contains the fields that were
+ updated on the user profile.
+
+ Will be `builtins.None` if the user itself did not change.
+ This is always the case if the user only updated their member
+ representation and did not change their user profile directly.
+
+ Returns
+ -------
+ hikari.models.users.PartialUser or builtins.None
+ The partial user containing the updated fields.
+ """
+
+ @property
+ def user_id(self) -> snowflake.Snowflake:
+ """User ID of the user that updated their presence.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ ID of the user the event concerns.
+ """
+ return self.presence.user_id
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ """Guild ID that the presence was updated in.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ ID of the guild the event occurred in.
+ """
+ return self.presence.guild_id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class MemberChunkEvent(shard_events.ShardEvent):
+ """Used to represent the response to Guild Request Members."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib(repr=True)
+ # <>.
+
+ members: typing.Mapping[snowflake.Snowflake, guilds.Member] = attr.ib(repr=False)
+ """Mapping of user IDs to the objects of the members in this chunk.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.guilds.Member]
+ Mapping of user IDs to corresponding member objects.
+ """
+
+ index: int = attr.ib(repr=True)
+ """Zero-indexed position of this within the queued up chunks for this request.
+
+ Returns
+ -------
+ builtins.int
+ The sequence index for this chunk.
+ """
+
+ count: int = attr.ib(repr=True)
+ """Total number of expected chunks for the request this is associated with.
+
+ Returns
+ -------
+ builtins.int
+ Total number of chunks to be expected.
+ """
+
+ not_found: typing.Sequence[snowflake.Snowflake] = attr.ib(repr=True)
+ """Sequence of the snowflakes that were not found while making this request.
+
+ This is only applicable when user IDs are specified while making the
+ member request the chunk is associated with.
+
+ Returns
+ -------
+ typing.Sequence[hikari.utilities.snowflake.Snowflake]
+ Sequence of user IDs that were not found.
+ """
+
+ presences: typing.Mapping[snowflake.Snowflake, presences_.MemberPresence] = attr.ib(repr=False)
+ """Mapping of user IDs to found member presence objects.
+
+ This will be empty if no include_presences are found or `include_presences` is not passed as
+ `True` while requesting the member chunks.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.include_presences.MemberPresence]
+ Mapping of user IDs to corresponding include_presences.
+ """
+
+ nonce: typing.Optional[str] = attr.ib(repr=True)
+ """String nonce used to identify the request member chunks are associated with.
+
+ This is the nonce value passed while requesting member chunks.
+
+ Returns
+ -------
+ builtins.str or builtins.None
+ The request nonce if specified, or `builtins.None` otherwise.
+ """
diff --git a/hikari/events/lifetime_events.py b/hikari/events/lifetime_events.py
new file mode 100644
index 0000000000..6597237c9b
--- /dev/null
+++ b/hikari/events/lifetime_events.py
@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events that are bound to the lifetime of an application.
+
+These are types of hooks that can be invoked on startup or shutdown, which can
+be used to initialize other resources, fetch information, and perform checks.
+"""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StartingEvent", "StartedEvent", "StoppingEvent", "StoppedEvent"]
+
+# noinspection PyUnresolvedReferences
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class StartingEvent(base_events.Event):
+ """Event that is triggered before the application connects to discord.
+
+ This will only fire once per `_rest.run`/`_rest.start`, so is suitable for
+ opening database connections and other resources that need to be
+ initialized within a coroutine function.
+
+ !!! warning
+ The application will not proceed to connect to Discord until all event
+ handlers for this event have completed/terminated. This prevents the
+ risk of race conditions occurring (e.g. allowing message events
+ to try to access a database that has not yet connected fully).
+
+ If you want to do something _after_ the application has initialized, you
+ should consider using `StartedEvent` instead.
+
+ See Also
+ --------
+ `StartedEvent`
+ `StoppingEvent`
+ `StoppedEvent`
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class StartedEvent(base_events.Event):
+ """Event that is triggered after the application has started.
+
+ This will only fire once per `_rest.run`/`_rest.start`, so is suitable for
+ opening database connections and other resources that need to be
+ initialized within a coroutine function.
+
+ If you want to do something _before_ the application connects, you should
+ consider using `StartingEvent` instead.
+
+ See Also
+ --------
+ `StartingEvent`
+ `StoppingEvent`
+ `StoppedEvent`
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class StoppingEvent(base_events.Event):
+ """Event that is triggered as soon as the application is requested to close.
+
+ This will fire before the connection is physically disconnected.
+
+ This will only fire once per `_rest.close`, so is suitable for
+ closing database connections and other resources that need to be
+ closed within a coroutine function.
+
+ !!! warning
+ The application will not proceed to disconnect from Discord until all
+ event handlers for this event have completed/terminated. This
+ prevents the risk of race conditions occurring from code that relies
+ on a connection still being available to complete.
+
+ If you want to do something _after_ the disconnection has occurred, you
+ should consider using `StoppedEvent` instead.
+
+ See Also
+ --------
+ `StartingEvent`
+ `StartedEvent`
+ `StoppedEvent`
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class StoppedEvent(base_events.Event):
+ """Event that is triggered once the application has disconnected.
+
+ This will only fire once per `_rest.close`, so is suitable for
+ closing database connections and other resources that need to be
+ closed within a coroutine function.
+
+ !!! warning
+ The application will not proceed to leave the `_rest.run` call until all
+ event handlers for this event have completed/terminated. This
+ prevents the risk of race conditions occurring where a script may
+ terminate the process before a callback can occur.
+
+ If you want to do something when the application is preparing to shut down,
+ but _before_ any connection to discord is closed, you should consider using
+ `StoppingEvent` instead.
+
+ See Also
+ --------
+ `StartingEvent`
+ `StartedEvent`
+ `StoppingEvent`
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
diff --git a/hikari/events/member_events.py b/hikari/events/member_events.py
new file mode 100644
index 0000000000..775c7d7904
--- /dev/null
+++ b/hikari/events/member_events.py
@@ -0,0 +1,172 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events concerning manipulation of members within guilds."""
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "MemberEvent",
+ "MemberCreateEvent",
+ "MemberUpdateEvent",
+ "MemberDeleteEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari import traits
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari.api import shard as gateway_shard
+ from hikari.models import guilds
+ from hikari.models import users
+ from hikari.utilities import snowflake
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MEMBERS)
+class MemberEvent(shard_events.ShardEvent, abc.ABC):
+ """Event base for any events that concern guild members."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild that this event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that relates to this event.
+ """
+
+ @property
+ @abc.abstractmethod
+ def user(self) -> users.User:
+ """User object for the member this event concerns.
+
+ Returns
+ -------
+ hikari.models.users.User
+ User object for the member this event concerns.
+ """
+
+ @property
+ def user_id(self) -> snowflake.Snowflake:
+ """ID of the user that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the user that this event relates to.
+ """
+ return self.user.id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MEMBERS)
+class MemberCreateEvent(MemberEvent):
+ """Event that is fired when a member joins a guild."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ member: guilds.Member = attr.ib()
+ """Member object for the member that joined the guild.
+
+ Returns
+ -------
+ hikari.models.guilds.Member
+ The member object for the member who just joined.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.member.guild_id
+
+ @property
+ def user(self) -> users.User:
+ # <>.
+ return self.member.user
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MEMBERS)
+class MemberUpdateEvent(MemberEvent):
+ """Event that is fired when a member is updated in a guild.
+
+ This may occur if roles are amended, or if the nickname is changed.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ member: guilds.Member = attr.ib()
+ """Member object for the member that was updated.
+
+ Returns
+ -------
+ hikari.models.guilds.Member
+ The member object for the member that was updated.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.member.guild_id
+
+ @property
+ def user(self) -> users.User:
+ # <>.
+ return self.member.user
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MEMBERS)
+class MemberDeleteEvent(MemberEvent):
+ """Event fired when a member is kicked from or leaves a guild."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ user: users.User = attr.ib()
+ # <>.
diff --git a/hikari/events/message_events.py b/hikari/events/message_events.py
new file mode 100644
index 0000000000..492ec7da8b
--- /dev/null
+++ b/hikari/events/message_events.py
@@ -0,0 +1,411 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events that fire if messages are sent/updated/deleted."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "MessagesEvent",
+ "MessageEvent",
+ "GuildMessageEvent",
+ "PrivateMessageEvent",
+ "MessageCreateEvent",
+ "GuildMessageCreateEvent",
+ "PrivateMessageCreateEvent",
+ "MessageUpdateEvent",
+ "GuildMessageUpdateEvent",
+ "PrivateMessageUpdateEvent",
+ "MessageDeleteEvent",
+ "GuildMessageDeleteEvent",
+ "PrivateMessageDeleteEvent",
+ "MessageBulkDeleteEvent",
+ "GuildMessageBulkDeleteEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import messages
+ from hikari.models import users
+ from hikari.utilities import snowflake
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class MessagesEvent(shard_events.ShardEvent, abc.ABC):
+ """Event base for any message-bound event."""
+
+ @property
+ @abc.abstractmethod
+ def channel_id(self) -> snowflake.Snowflake:
+ """ID of the channel that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the channel that this event concerns.
+ """
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class MessageEvent(MessagesEvent, abc.ABC):
+ """Event base for any event that concerns a single message."""
+
+ @property
+ @abc.abstractmethod
+ def message_id(self) -> snowflake.Snowflake:
+ """ID of the message that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the message that this event concerns.
+ """
+
+
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateMessageEvent(MessageEvent, abc.ABC):
+ """Event base for any message-bound event in private messages."""
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildMessageEvent(MessageEvent, abc.ABC):
+ """Event base for any message-bound event in guild messages."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that this event concerns.
+ """
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class MessageCreateEvent(MessageEvent, abc.ABC):
+ """Event base for any message creation event."""
+
+ @property
+ @abc.abstractmethod
+ def message(self) -> messages.Message:
+ """Message that was sent in the event.
+
+ Returns
+ -------
+ hikari.models.messages.Message
+ The message object that was sent with this event.
+ """
+
+ @property
+ def message_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.message.id
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.message.channel_id
+
+ @property
+ def author_id(self) -> snowflake.Snowflake:
+ """ID of the author that triggered this event.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the author that triggered this event concerns.
+ """
+ return self.message.author.id
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class MessageUpdateEvent(MessageEvent, abc.ABC):
+ """Event base for any message update event."""
+
+ @property
+ @abc.abstractmethod
+ def message(self) -> messages.PartialMessage:
+ """Partial message that was sent in the event.
+
+ !!! warning
+ Unlike `MessageCreateEvent`, `MessageUpdateEvent.message` is an
+ arbitrarily partial version of `hikari.models.messages.Message`
+ where any field except `id` and `channel_id` may be set to
+ `hikari.utilities.undefined.UndefinedType` (a singleton) to indicate
+ that it has not been changed.
+
+ Returns
+ -------
+ hikari.models.messages.PartialMessage
+ The partially populated message object that was sent with this
+ event.
+ """
+
+ @property
+ def message_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.message.id
+
+ @property
+ def author_id(self) -> snowflake.Snowflake:
+ """ID of the author that triggered this event.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the author that triggered this event concerns.
+ """
+ # Looks like `author` is always present in this event variant.
+ return typing.cast("users.PartialUser", self.message.author).id
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.message.channel_id
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES, intents.Intents.PRIVATE_MESSAGES)
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class MessageDeleteEvent(MessageEvent, abc.ABC):
+ """Event base for any message delete event."""
+
+ @property
+ @abc.abstractmethod
+ def message(self) -> messages.PartialMessage:
+ """Partial message that was sent in the event.
+
+ !!! warning
+ Unlike `MessageCreateEvent`, `message` is a severely limited partial
+ version of `hikari.models.messages.Message`. The only attributes
+ that will not be `hikari.utilities.undefined.UNDEFINED` will be
+ `id`, `channel_id`, and `guild_id` if the message was in a guild.
+ This is a limitation of Discord.
+
+ Furthermore, this partial message will represent a message that no
+ longer exists. Thus, attempting to edit/delete/react or un-react to
+ this message or attempting to fetch the full version will result
+ in a `hikari.errors.NotFound` being raised.
+
+ Returns
+ -------
+ hikari.models.messages.PartialMessage
+ The partially populated message object that was sent with this
+ event.
+ """
+
+ @property
+ def message_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.message.id
+
+ @property
+ def channel_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.message.channel_id
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildMessageCreateEvent(GuildMessageEvent, MessageCreateEvent):
+ """Event triggered when a message is sent to a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ message: messages.Message = attr.ib()
+ # <>.
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ # Always present in this event.
+ return typing.cast("snowflake.Snowflake", self.message.guild_id)
+
+
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateMessageCreateEvent(PrivateMessageEvent, MessageCreateEvent):
+ """Event triggered when a message is sent to a private channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ message: messages.Message = attr.ib()
+ # <>.
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildMessageUpdateEvent(GuildMessageEvent, MessageUpdateEvent):
+ """Event triggered when a message is updated in a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ message: messages.PartialMessage = attr.ib()
+ # <>.
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ # Always present in this event.
+ return typing.cast("snowflake.Snowflake", self.message.guild_id)
+
+
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateMessageUpdateEvent(PrivateMessageEvent, MessageUpdateEvent):
+ """Event triggered when a message is updated in a private channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ message: messages.PartialMessage = attr.ib()
+ # <>.
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildMessageDeleteEvent(GuildMessageEvent, MessageDeleteEvent):
+ """Event triggered when a message is deleted from a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ message: messages.PartialMessage = attr.ib()
+ # <>.
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ # Always present in this event.
+ return typing.cast("snowflake.Snowflake", self.message.guild_id)
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+class PrivateMessageDeleteEvent(PrivateMessageEvent, MessageDeleteEvent):
+ """Event triggered when a message is deleted from a private channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ message: messages.PartialMessage = attr.ib()
+ # <>.
+
+
+# NOTE: if this ever has a private channel equivalent implemented, this intents
+# constraint should be relaxed.
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES)
+class MessageBulkDeleteEvent(MessagesEvent, abc.ABC):
+ """Event triggered when messages are bulk-deleted from a channel.
+
+ !!! note
+ There is only a guild equivalent of this event at the time of writing.
+ However, Discord appear to not be ruling out that this ability may
+ be implemented for private channels in the future. Thus, this base
+ exists for future compatibility and consistency.
+
+ If you care about the event occurring in a guild specifically, you
+ should use the `GuildMessageBulkDeleteEvent`. Otherwise, using this
+ event base is acceptable.
+
+ See https://github.com/discord/discord-api-docs/issues/1633 for
+ Discord's response.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGES)
+class GuildMessageBulkDeleteEvent(MessageBulkDeleteEvent):
+ """Event triggered when messages are bulk-deleted from a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ """ID of the guild that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that this event concerns.
+ """
+
+ message_ids: typing.Sequence[snowflake.Snowflake] = attr.ib()
+ """Sequence of message IDs that were bulk deleted.
+
+ Returns
+ -------
+ typing.Sequence[hikari.utilities.snowflake.Snowflake]
+ A sequence of message IDs that were bulk deleted.
+ """
diff --git a/hikari/events/reaction_events.py b/hikari/events/reaction_events.py
new file mode 100644
index 0000000000..df799f5b88
--- /dev/null
+++ b/hikari/events/reaction_events.py
@@ -0,0 +1,401 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events that fire if messages are reacted to."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "ReactionEvent",
+ "GuildReactionEvent",
+ "PrivateReactionEvent",
+ "ReactionAddEvent",
+ "ReactionDeleteEvent",
+ "ReactionDeleteEmojiEvent",
+ "ReactionDeleteAllEvent",
+ "GuildReactionAddEvent",
+ "GuildReactionDeleteEvent",
+ "GuildReactionDeleteEmojiEvent",
+ "GuildReactionDeleteAllEvent",
+ "PrivateReactionAddEvent",
+ "PrivateReactionDeleteEvent",
+ "PrivateReactionDeleteEmojiEvent",
+ "PrivateReactionDeleteAllEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import emojis
+ from hikari.models import guilds
+ from hikari.utilities import snowflake
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS, intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class ReactionEvent(shard_events.ShardEvent, abc.ABC):
+ """Event base for any message reaction event."""
+
+ @property
+ @abc.abstractmethod
+ def channel_id(self) -> snowflake.Snowflake:
+ """ID of the channel that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the channel that this event concerns.
+ """
+
+ @property
+ @abc.abstractmethod
+ def message_id(self) -> snowflake.Snowflake:
+ """ID of the message that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the message that this event concerns.
+ """
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS)
+class GuildReactionEvent(ReactionEvent, abc.ABC):
+ """Event base for any reaction-bound event in guild messages."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that this event concerns.
+ """
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class PrivateReactionEvent(ReactionEvent, abc.ABC):
+ """Event base for any reaction-bound event in private messages."""
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS, intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class ReactionAddEvent(ReactionEvent, abc.ABC):
+ """Event base for any reaction that is added to a message."""
+
+ @property
+ @abc.abstractmethod
+ def user_id(self) -> snowflake.Snowflake:
+ """ID of the user that added this reaction.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the user that added this reaction.
+ """
+
+ @property
+ @abc.abstractmethod
+ def emoji(self) -> emojis.Emoji:
+ """Emoji that was added.
+
+ Returns
+ -------
+ hikari.models.emojis.Emoji
+ The `hikari.models.emojis.UnicodeEmoji` or
+ `hikari.models.emojis.CustomEmoji` that was added to the message.
+ """
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS, intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class ReactionDeleteEvent(ReactionEvent, abc.ABC):
+ """Event base for any single reaction that is removed from a message."""
+
+ @property
+ @abc.abstractmethod
+ def user_id(self) -> snowflake.Snowflake:
+ """User ID for the user that added this reaction initially.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the user that removed this reaction.
+ """
+
+ @property
+ @abc.abstractmethod
+ def emoji(self) -> emojis.Emoji:
+ """Emoji that was removed.
+
+ Returns
+ -------
+ hikari.models.emojis.Emoji
+ The `hikari.models.emojis.UnicodeEmoji` or
+ `hikari.models.emojis.CustomEmoji` that was removed from the
+ message.
+ """
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS, intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class ReactionDeleteAllEvent(ReactionEvent, abc.ABC):
+ """Event base fired when all reactions are removed from a message."""
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS, intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class ReactionDeleteEmojiEvent(ReactionEvent, abc.ABC):
+ """Event base fired when all reactions are removed for one emoji."""
+
+ @property
+ @abc.abstractmethod
+ def emoji(self) -> emojis.Emoji:
+ """Emoji that was removed.
+
+ Returns
+ -------
+ hikari.models.emojis.Emoji
+ The `hikari.models.emojis.UnicodeEmoji` or
+ `hikari.models.emojis.CustomEmoji` that was removed from the
+ message.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS)
+class GuildReactionAddEvent(GuildReactionEvent, ReactionAddEvent):
+ """Event fired when a reaction is added to a guild message."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ member: guilds.Member = attr.ib()
+ """Member that added the reaction.
+
+ Returns
+ -------
+ hikari.models.guilds.Member
+ The member which added this reaction.
+ """
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emoji: emojis.Emoji = attr.ib()
+ # <>.
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.member.guild_id
+
+ @property
+ def user_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.member.user.id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS)
+class GuildReactionDeleteEvent(GuildReactionEvent, ReactionDeleteEvent):
+ """Event fired when a reaction is removed from a guild message."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ user_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emoji: emojis.Emoji = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS)
+class GuildReactionDeleteEmojiEvent(GuildReactionEvent, ReactionDeleteEmojiEvent):
+ """Event fired when an emoji is removed from a guild message's reactions."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emoji: emojis.Emoji = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_REACTIONS)
+class GuildReactionDeleteAllEvent(GuildReactionEvent, ReactionDeleteAllEvent):
+ """Event fired when all of a guild message's reactions are removed."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class PrivateReactionAddEvent(PrivateReactionEvent, ReactionAddEvent):
+ """Event fired when a reaction is added to a guild message."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ user_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emoji: emojis.Emoji = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class PrivateReactionDeleteEvent(PrivateReactionEvent, ReactionDeleteEvent):
+ """Event fired when a reaction is removed from a private message."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ user_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emoji: emojis.Emoji = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class PrivateReactionDeleteEmojiEvent(PrivateReactionEvent, ReactionDeleteEmojiEvent):
+ """Event fired when an emoji is removed from a private message's reactions."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ emoji: emojis.Emoji = attr.ib()
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGE_REACTIONS)
+class PrivateReactionDeleteAllEvent(PrivateReactionEvent, ReactionDeleteAllEvent):
+ """Event fired when all of a private message's reactions are removed."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ message_id: snowflake.Snowflake = attr.ib()
+ # <>.
diff --git a/hikari/events/role_events.py b/hikari/events/role_events.py
new file mode 100644
index 0000000000..9e41fd65be
--- /dev/null
+++ b/hikari/events/role_events.py
@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events pertaining to manipulation of roles within guilds."""
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "RoleEvent",
+ "RoleCreateEvent",
+ "RoleUpdateEvent",
+ "RoleDeleteEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import guilds
+ from hikari.utilities import snowflake
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class RoleEvent(shard_events.ShardEvent, abc.ABC):
+ """Event base for any event that involves guild roles."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild that this event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that relates to this event.
+ """
+
+ @property
+ @abc.abstractmethod
+ def role_id(self) -> snowflake.Snowflake:
+ """ID of the role that this event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the role that relates to this event.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class RoleCreateEvent(RoleEvent):
+ """Event fired when a role is created."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ role: guilds.Role = attr.ib()
+ """Role that was created.
+
+ Returns
+ -------
+ hikari.models.guilds.Role
+ The created role.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.role.guild_id
+
+ @property
+ def role_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.role.id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class RoleUpdateEvent(RoleEvent):
+ """Event fired when a role is updated."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ role: guilds.Role = attr.ib()
+ """Role that was updated.
+
+ Returns
+ -------
+ hikari.models.guilds.Role
+ The created role.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.role.guild_id
+
+ @property
+ def role_id(self) -> snowflake.Snowflake:
+ # <>.
+ return self.role.id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+@base_events.requires_intents(intents.Intents.GUILDS)
+class RoleDeleteEvent(RoleEvent):
+ """Event fired when a role is deleted."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ role_id: snowflake.Snowflake = attr.ib()
+ # <>.
diff --git a/hikari/events/shard_events.py b/hikari/events/shard_events.py
new file mode 100644
index 0000000000..3a85a006b6
--- /dev/null
+++ b/hikari/events/shard_events.py
@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events relating to specific shards connecting and disconnecting."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "ShardEvent",
+ "ShardStateEvent",
+ "ShardConnectedEvent",
+ "ShardDisconnectedEvent",
+ "ShardReadyEvent",
+ "ShardResumedEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import users
+ from hikari.utilities import snowflake
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ShardEvent(base_events.Event, abc.ABC):
+ """Base class for any event that was shard-specific."""
+
+ @property
+ @abc.abstractmethod
+ def shard(self) -> gateway_shard.GatewayShard:
+ """Shard that received this event.
+
+ Returns
+ -------
+ hikari.api.shard.GatewayShard
+ The shard that triggered the event.
+ """
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ShardStateEvent(ShardEvent, abc.ABC):
+ """Base class for any event concerning the state/connectivity of a shard.
+
+ This currently wraps connection/disconnection/ready/resumed events only.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ShardConnectedEvent(ShardStateEvent):
+ """Event fired when a shard connects."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ShardDisconnectedEvent(ShardStateEvent):
+ """Event fired when a shard disconnects."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ShardReadyEvent(ShardStateEvent):
+ """Event fired when a shard declares it is ready."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ actual_gateway_version: int = attr.ib(repr=True)
+ """Actual gateway version being used.
+
+ Returns
+ -------
+ builtins.int
+ The actual gateway version we are actively using for this protocol.
+ """
+
+ session_id: str = attr.ib(repr=True)
+ """ID for this session.
+
+ Returns
+ -------
+ builtins.str
+ The session ID for this gateway session.
+ """
+
+ my_user: users.OwnUser = attr.ib(repr=True)
+ """User for the current bot account this connection is authenticated with.
+
+ Returns
+ -------
+ hikari.models.users.OwnUser
+ This bot's user.
+ """
+
+ unavailable_guilds: typing.Sequence[snowflake.Snowflake] = attr.ib(repr=False)
+ """Sequence of the IDs for all guilds this bot is currently in.
+
+ All guilds will start off "unavailable" and should become available after
+ a few seconds of connecting one-by-one.
+
+ Returns
+ -------
+ typing.Sequence[hikari.utilities.snowflake.Snowflake]
+ All guild IDs that the bot is in for this shard.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class ShardResumedEvent(ShardStateEvent):
+ """Event fired when a shard resumes an existing session."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
diff --git a/hikari/events/typing_events.py b/hikari/events/typing_events.py
new file mode 100644
index 0000000000..7979fc0b1b
--- /dev/null
+++ b/hikari/events/typing_events.py
@@ -0,0 +1,209 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events fired when users begin typing in channels."""
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "TypingEvent",
+ "GuildTypingEvent",
+ "PrivateTypingEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import channels
+ from hikari.models import guilds
+ from hikari.models import users
+ from hikari.utilities import snowflake
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_TYPING, intents.Intents.PRIVATE_MESSAGE_TYPING)
+class TypingEvent(shard_events.ShardEvent, abc.ABC):
+ """Base event fired when a user begins typing in a channel."""
+
+ @property
+ @abc.abstractmethod
+ def channel_id(self) -> snowflake.Snowflake:
+ """ID of the channel that this event concerns.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the channel that this event concerns.
+ """
+
+ @property
+ @abc.abstractmethod
+ def user_id(self) -> snowflake.Snowflake:
+ """ID of the user who triggered this typing event.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ ID of the user who is typing.
+ """
+
+ @property
+ @abc.abstractmethod
+ def timestamp(self) -> datetime.datetime:
+ """Timestamp of when this typing event started.
+
+ Returns
+ -------
+ datetime.datetime
+ UTC timestamp of when the user started typing.
+ """
+
+ async def fetch_channel(self) -> channels.TextChannel:
+ """Perform an API call to fetch an up-to-date image of this channel.
+
+ Returns
+ -------
+ hikari.models.channels.TextChannel
+ The channel.
+ """
+ return typing.cast("channels.TextChannel", await self.app.rest.fetch_channel(self.channel_id))
+
+ async def fetch_user(self) -> users.User:
+ """Perform an API call to fetch an up-to-date image of this user.
+
+ Returns
+ -------
+ hikari.models.users.user
+ The user.
+ """
+ return await self.app.rest.fetch_user(self.user_id)
+
+
+@base_events.requires_intents(intents.Intents.GUILD_MESSAGE_TYPING)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class GuildTypingEvent(TypingEvent):
+ """Event fired when a user starts typing in a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ user_id: snowflake.Snowflake = attr.ib(repr=True)
+ # <>.
+
+ timestamp: datetime.datetime = attr.ib(repr=False)
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib()
+ """ID of the guild that this event relates to.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The ID of the guild that relates to this event.
+ """
+
+ member: guilds.Member = attr.ib(repr=False)
+ """Member object of the user who triggered this typing event.
+
+ Returns
+ -------
+ hikari.models.guilds.Member
+ Member of the user who triggered this typing event.
+ """
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.GuildTextChannel:
+ ...
+
+ async def fetch_member(self) -> guilds.Member:
+ """Perform an API call to fetch an up-to-date image of this member.
+
+ Returns
+ -------
+ hikari.models.guilds.Member
+ The member.
+ """
+ return await self.app.rest.fetch_member(self.guild_id, self.user_id)
+
+ async def fetch_guild(self) -> guilds.Guild:
+ """Perform an API call to fetch an up-to-date image of this guild.
+
+ Returns
+ -------
+ hikari.models.guilds.Guild
+ The guild.
+ """
+ return await self.app.rest.fetch_guild(self.guild_id)
+
+ async def fetch_guild_preview(self) -> guilds.GuildPreview:
+ """Perform an API call to fetch an up-to-date preview of this guild.
+
+ Returns
+ -------
+ hikari.models.guilds.GuildPreview
+ The guild.
+ """
+ return await self.app.rest.fetch_guild_preview(self.guild_id)
+
+
+@base_events.requires_intents(intents.Intents.PRIVATE_MESSAGES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class PrivateTypingEvent(TypingEvent):
+ """Event fired when a user starts typing in a guild channel."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ channel_id: snowflake.Snowflake = attr.ib()
+ # <>.
+
+ user_id: snowflake.Snowflake = attr.ib(repr=True)
+ # <>.
+
+ timestamp: datetime.datetime = attr.ib(repr=False)
+ # <>.
+
+ if typing.TYPE_CHECKING:
+
+ async def fetch_channel(self) -> channels.PrivateTextChannel:
+ ...
diff --git a/hikari/events/user_events.py b/hikari/events/user_events.py
new file mode 100644
index 0000000000..33777bdd17
--- /dev/null
+++ b/hikari/events/user_events.py
@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events fired when the account user is updated."""
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["OwnUserUpdateEvent"]
+
+import typing
+
+import attr
+
+from hikari.events import shard_events
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import users
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class OwnUserUpdateEvent(shard_events.ShardEvent):
+ """Event fired when the account user is updated."""
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ user: users.OwnUser = attr.ib()
+ """This application user.
+
+ Returns
+ -------
+ hikari.models.users.OwnUser
+ This application user.
+ """
diff --git a/hikari/events/voice_events.py b/hikari/events/voice_events.py
new file mode 100644
index 0000000000..8b314f179c
--- /dev/null
+++ b/hikari/events/voice_events.py
@@ -0,0 +1,148 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Events that fire when voice state changes."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "VoiceEvent",
+ "VoiceStateUpdateEvent",
+ "VoiceServerUpdateEvent",
+]
+
+import abc
+import typing
+
+import attr
+
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents
+from hikari.utilities import attr_extensions
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.api import shard as gateway_shard
+ from hikari.models import voices
+ from hikari.utilities import snowflake
+
+
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class VoiceEvent(shard_events.ShardEvent, abc.ABC):
+ """Base for any voice-related event."""
+
+ @property
+ @abc.abstractmethod
+ def guild_id(self) -> snowflake.Snowflake:
+ """ID of the guild this event is for.
+
+ Returns
+ -------
+ hikari.utilities.snowflake.Snowflake
+ The guild ID of the guild this event relates to.
+ """
+
+
+@base_events.requires_intents(intents.Intents.GUILD_VOICE_STATES)
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class VoiceStateUpdateEvent(VoiceEvent):
+ """Event fired when a user changes their voice state.
+
+ Sent when a user joins, leaves or moves voice channel(s).
+
+ This is also fired for the application user, and is used when preparing
+ to connect to the voice gateway to stream audio or video content.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ state: voices.VoiceState = attr.ib(repr=True)
+ """Voice state that this update contained.
+
+ Returns
+ -------
+ hikari.models.voices.VoiceState
+ The voice state that was updated.
+ """
+
+ @property
+ def guild_id(self) -> snowflake.Snowflake:
+ # <>
+ return self.state.guild_id
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+class VoiceServerUpdateEvent(VoiceEvent):
+ """Event fired when a voice server is changed.
+
+ Sent when initially connecting to voice and when the current voice instance
+ falls over to a new server.
+ """
+
+ app: traits.RESTAware = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ shard: gateway_shard.GatewayShard = attr.ib(metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ # <>.
+
+ guild_id: snowflake.Snowflake = attr.ib(repr=True)
+ # <>
+
+ token: str = attr.ib(repr=False)
+ """Token that should be used to authenticate with the voice gateway.
+
+ Returns
+ -------
+ builtins.str
+ The token to use to authenticate with the voice gateway.
+ """
+
+ raw_endpoint: str = attr.ib(repr=True)
+ """Raw endpoint URL that Discord sent.
+
+ This will always be incorrect, because sending a correct URL would be too
+ useful to you.
+
+ Returns
+ -------
+ builtins.str
+ The incorrect endpoint URL for the voice gateway server to connect to.
+ """
+
+ @property
+ def endpoint(self) -> str:
+ """URI for this voice server host, with the correct port and protocol.
+
+ Returns
+ -------
+ builtins.str
+ The URI to use to connect to the voice gateway.
+ """
+ # Discord have had this wrong for like 4 years, bleh.
+ uri, _, _ = self.raw_endpoint.rpartition(":")
+ return f"wss://{uri}:443"
diff --git a/hikari/impl/__init__.py b/hikari/impl/__init__.py
new file mode 100644
index 0000000000..8b80232ee3
--- /dev/null
+++ b/hikari/impl/__init__.py
@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic implementations of application components.
+
+These components implement the interfaces in `hikari.api` to provide the
+baseline functionality. For most applications that do not have bespoke
+performance or structural requirements, you will want to use these
+implementations.
+"""
+
+__all__ = [] # type: ignore[var-annotated]
diff --git a/hikari/impl/bot.py b/hikari/impl/bot.py
new file mode 100644
index 0000000000..e5ce97d0e9
--- /dev/null
+++ b/hikari/impl/bot.py
@@ -0,0 +1,890 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic implementation the components for a single-process bot."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["BotApp"]
+
+import asyncio
+import contextlib
+import datetime
+import logging
+import math
+import signal
+import sys
+import time
+import typing
+import warnings
+
+from hikari import config
+from hikari import errors
+from hikari import traits
+from hikari.api import event_dispatcher
+from hikari.api import shard as gateway_shard
+from hikari.events import lifetime_events
+from hikari.impl import entity_factory as entity_factory_impl
+from hikari.impl import event_factory as event_factory_impl
+from hikari.impl import rate_limits
+from hikari.impl import rest as rest_client_impl
+from hikari.impl import shard as gateway_shard_impl
+from hikari.impl import stateful_cache as cache_impl
+from hikari.impl import stateful_event_manager
+from hikari.impl import stateful_guild_chunker as guild_chunker_impl
+from hikari.impl import stateless_cache as stateless_cache_impl
+from hikari.impl import stateless_event_manager
+from hikari.impl import stateless_guild_chunker as stateless_guild_chunker_impl
+from hikari.impl import voice
+from hikari.models import intents as intents_
+from hikari.models import presences
+from hikari.utilities import art
+from hikari.utilities import constants
+from hikari.utilities import date
+from hikari.utilities import undefined
+from hikari.utilities import version_sniffer
+
+if typing.TYPE_CHECKING:
+ import concurrent.futures
+
+ from hikari.api import cache as cache_
+ from hikari.api import chunker as guild_chunker_
+ from hikari.events import base_events
+ from hikari.impl import event_manager_base
+ from hikari.models import users
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari")
+
+
+class BotApp(
+ traits.DispatcherAware,
+ traits.EventFactoryAware,
+ traits.RESTAware,
+ traits.ShardAware,
+ event_dispatcher.EventDispatcher,
+):
+ """Implementation of an auto-sharded single-instance bot application.
+
+ Parameters
+ ----------
+ banner_package : builtins.str or builtins.None
+ The package to look for a `banner.txt` in. Will default to Hikari's
+ banner if unspecified. If you set this to `builtins.None`, then no
+ banner will be displayed.
+ debug : builtins.bool
+ Defaulting to `builtins.False`, if `builtins.True`, then each payload sent and received
+ on the gateway will be dumped to debug logs, and every HTTP API request
+ and response will also be dumped to logs. This will provide useful
+ debugging context at the cost of performance. Generally you do not
+ need to enable this.
+ gateway_version : builtins.int
+ The version of the gateway to connect to. At the time of writing,
+ only version `6` and version `7` (undocumented development release)
+ are supported. This defaults to using v6.
+ http_settings : hikari.config.HTTPSettings or builtins.None
+ The HTTP-related settings to use.
+ initial_activity : hikari.utilities.undefined.UndefinedNoneOr[hikari.models.include_presences.Activity]
+ The initial activity to have on each shard.
+ initial_status : hikari.utilities.undefined.UndefinedOr[hikari.models.include_presences.Status]
+ The initial status to have on each shard.
+ initial_idle_since : hikari.utilities.undefined.UndefinedNoneOr[datetime.datetime]
+ The initial time to show as being idle since, or `builtins.None` if not
+ idle, for each shard.
+ initial_is_afk : hikari.utilities.undefined.UndefinedOr[builtins.bool]
+ If `builtins.True`, each shard will appear as being AFK on startup. If `builtins.False`,
+ each shard will appear as _not_ being AFK.
+ intents : hikari.models.intents.Intents or builtins.None
+ The intents to use for each shard. If `builtins.None`, then no intents
+ are passed. Note that on the version `7` gateway, this will cause an
+ immediate connection close with an error code.
+
+ The default for this is to enable all intents that do not require
+ privileges.
+
+ !!! warning
+ Enabling privileged intents without enabling the intent
+ in the Discord developer dashboard will result in shards immediately
+ being disconnected on startup and the application raising an
+ exception.
+ large_threshold : builtins.int
+ The number of members that need to be in a guild for the guild to be
+ considered large. Defaults to the maximum, which is `250`.
+ logging_level : builtins.str or builtins.int or builtins.None
+ If not `builtins.None`, then this will be the logging level set if you
+ have not enabled logging already. In this case, it should be a valid
+ `logging` level that can be passed to `logging.basicConfig`. If you have
+ already initialized logging, then this is irrelevant and this
+ parameter can be safely ignored. If you set this to `builtins.None`,
+ then no logging will initialize if you have a reason to not use any
+ logging or simply wish to initialize it in your own time instead.
+
+ !!! note
+ Initializing logging means already have a handler in the root
+ logger. This is usually achieved by calling `logging.basicConfig`
+ or adding the handler manually.
+ proxy_settings : hikari.config.ProxySettings or builtins.None
+ Settings to use for the proxy.
+ rest_version : int
+ The version of the HTTP API to connect to. At the time of writing,
+ only version `6` and version `7` (undocumented development release)
+ are supported. This defaults to v6.
+ shard_ids : typing.AbstractSet[builtins.int] or builtins.None
+ A set of every shard ID that should be created and started on startup.
+ If left to `builtins.None` along with `shard_count`, then auto-sharding
+ is used instead, which is the default.
+ shard_count : builtins.int or builtins.None
+ The number of shards in the entire application. If left to
+ `builtins.None` along with `shard_ids`, then auto-sharding is used
+ instead, which is the default.
+ stateless : builtins.bool
+ If `builtins.True`, the bot will not implement a cache, and will be
+ considered stateless. If `builtins.False`, then a cache will be used.
+
+ While the cache components are a WIP, this will default to
+ `builtins.True`. This should be expected to be changed to
+ `builtins.False` before the first non-development release is made.
+ token : builtins.str
+ The bot token to use. This should not start with a prefix such as
+ `Bot `, but instead only contain the token itself.
+
+ !!! note
+ The default parameters for `shard_ids` and `shard_count` are marked as
+ undefined. When both of these are left to the default value, the
+ application will use the Discord-provided recommendation for the number
+ of shards to start.
+
+ If only one of these two parameters are specified, expect a
+ `builtins.TypeError` to be raised.
+
+ Likewise, all shard_ids must be greater-than or equal-to `0`, and
+ less than `shard_count` to be valid. Failing to provide valid
+ values will result in a `builtins.ValueError` being raised.
+
+ !!! note
+ If all four of `initial_activity`, `initial_idle_since`,
+ `initial_is_afk`, and `initial_status` are not defined and left to their
+ default values, then the presence will not be _updated_ on startup
+ at all.
+
+ !!! note
+ To disable auto-sharding, you should explicitly specify how many shards
+ you wish to use. For non-sharded applications, this can be done by
+ passing `shard_count` as `1` in the constructor.
+
+ Raises
+ ------
+ builtins.TypeError
+ If sharding information is not specified correctly.
+ builtins.ValueError
+ If sharding information is provided, but is unfeasible or invalid.
+ """
+
+ __slots__: typing.Sequence[str] = (
+ "_cache",
+ "_guild_chunker",
+ "_connector_factory",
+ "_debug",
+ "_entity_factory",
+ "_event_manager",
+ "_event_factory",
+ "_executor",
+ "_global_ratelimit",
+ "_http_settings",
+ "_initial_activity",
+ "_initial_idle_since",
+ "_initial_is_afk",
+ "_initial_status",
+ "_intents",
+ "_large_threshold",
+ "_max_concurrency",
+ "_proxy_settings",
+ "_request_close_event",
+ "_rest",
+ "_shard_count",
+ "_shard_gather_task",
+ "_shard_ids",
+ "_shards",
+ "_started_at_monotonic",
+ "_started_at_timestamp",
+ "_tasks",
+ "_token",
+ "_version",
+ "_voice",
+ "_start_count",
+ )
+
+ def __init__(
+ self,
+ *,
+ banner_package: typing.Optional[str] = "hikari",
+ debug: bool = False,
+ executor: typing.Optional[concurrent.futures.Executor] = None,
+ gateway_version: int = 6,
+ http_settings: typing.Optional[config.HTTPSettings] = None,
+ initial_activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
+ initial_idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
+ initial_is_afk: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ initial_status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
+ intents: typing.Optional[intents_.Intents] = intents_.Intents.ALL_UNPRIVILEGED,
+ large_threshold: int = 250,
+ logging_level: typing.Union[str, int, None] = "INFO",
+ proxy_settings: typing.Optional[config.ProxySettings] = None,
+ rest_version: int = 6,
+ rest_url: typing.Optional[str] = None,
+ shard_ids: typing.Optional[typing.AbstractSet[int]] = None,
+ shard_count: typing.Optional[int] = None,
+ stateless: bool = True,
+ token: str,
+ ) -> None:
+ if undefined.count(shard_ids, shard_count) == 1:
+ raise TypeError("You must provide values for both shard_ids and shard_count, or neither.")
+
+ if logging_level is not None and not _LOGGER.hasHandlers():
+ logging.captureWarnings(True)
+ logging.basicConfig(format=art.get_default_logging_format())
+ logging.root.setLevel(logging_level)
+
+ if banner_package is not None:
+ self._dump_banner(banner_package)
+
+ self._connector_factory = rest_client_impl.BasicLazyCachedTCPConnectorFactory()
+ self._debug = debug
+ self._entity_factory = entity_factory_impl.EntityFactoryImpl(app=self)
+ self._event_factory = event_factory_impl.EventFactoryImpl(app=self)
+ self._executor = executor
+ self._global_ratelimit = rate_limits.ManualRateLimiter()
+ self._http_settings = config.HTTPSettings() if http_settings is None else http_settings
+ self._initial_activity = initial_activity
+ self._initial_idle_since = initial_idle_since
+ self._initial_is_afk = initial_is_afk
+ self._initial_status = initial_status
+ self._intents = intents
+ self._large_threshold = large_threshold
+ self._max_concurrency = 1
+ self._proxy_settings = config.ProxySettings() if proxy_settings is None else proxy_settings
+ self._request_close_event = asyncio.Event()
+ self._rest = rest_client_impl.RESTClientImpl( # noqa: S106 - Possible hardcoded password
+ connector_factory=self._connector_factory,
+ connector_owner=False,
+ debug=debug,
+ entity_factory=self._entity_factory,
+ executor=self._executor,
+ http_settings=self._http_settings,
+ proxy_settings=self._proxy_settings,
+ token=token,
+ token_type=constants.BOT_TOKEN, # nosec
+ rest_url=rest_url,
+ version=rest_version,
+ )
+ self._shard_count: int = shard_count if shard_count is not None else 0
+ self._shard_gather_task: typing.Optional[asyncio.Task[None]] = None
+ self._shard_ids: typing.AbstractSet[int] = set() if shard_ids is None else shard_ids
+ self._shards: typing.Dict[int, gateway_shard.GatewayShard] = {}
+ self._started_at_monotonic: typing.Optional[float] = None
+ self._started_at_timestamp: typing.Optional[datetime.datetime] = None
+ self._tasks: typing.Dict[int, asyncio.Task[typing.Any]] = {}
+ self._token = token
+ self._version = gateway_version
+ # This should always be last so that we don't get an extra error when failed to initialize
+ self._start_count: int = 0
+
+ self._cache: cache_.MutableCache
+ self._guild_chunker: guild_chunker_.GuildChunker
+ self._event_manager: event_manager_base.EventManagerBase
+
+ if stateless:
+ self._cache = stateless_cache_impl.StatelessCacheImpl()
+ self._guild_chunker = stateless_guild_chunker_impl.StatelessGuildChunkerImpl()
+ self._event_manager = stateless_event_manager.StatelessEventManagerImpl(app=self, intents=intents)
+ _LOGGER.info("this application is stateless, cache-based operations will not be available")
+ else:
+ self._cache = cache_impl.StatefulCacheImpl(app=self, intents=intents)
+ self._guild_chunker = guild_chunker_impl.StatefulGuildChunkerImpl(app=self, intents=intents)
+ self._event_manager = stateful_event_manager.StatefulEventManagerImpl(
+ app=self, cache=self._cache, intents=intents
+ )
+
+ self._voice = voice.VoiceComponentImpl(self, self._event_manager)
+
+ def __del__(self) -> None:
+ # If something goes wrong while initializing the bot, `_start_count` might not be there.
+ if hasattr(self, "_start_count") and self._start_count == 0:
+ # TODO: may remove this as it causes issues with tests. Provisionally implemented only.
+ warnings.warn(
+ "Looks like your bot never started. Make sure you called bot.run() after you set the bot object up.",
+ category=errors.HikariWarning,
+ )
+
+ @property
+ def cache(self) -> cache_.Cache:
+ # <>
+ return self._cache
+
+ @property
+ def chunker(self) -> guild_chunker_.GuildChunker:
+ # <>
+ return self._guild_chunker
+
+ @property
+ def dispatcher(self) -> event_dispatcher.EventDispatcher:
+ # <>
+ return self._event_manager
+
+ @property
+ def entity_factory(self) -> entity_factory_impl.EntityFactoryImpl:
+ # <>
+ return self._entity_factory
+
+ @property
+ def event_factory(self) -> event_factory_impl.EventFactoryImpl:
+ # <>
+ return self._event_factory
+
+ @property
+ def executor(self) -> typing.Optional[concurrent.futures.Executor]:
+ # <>
+ return self._executor
+
+ @property
+ def heartbeat_latencies(self) -> typing.Mapping[int, float]:
+ # <>
+ return {shard_id: shard.heartbeat_latency for shard_id, shard in self._shards.items()}
+
+ @property
+ def heartbeat_latency(self) -> float:
+ # <>
+ started_shards = [
+ shard.heartbeat_latency for shard in self._shards.values() if not math.isnan(shard.heartbeat_latency)
+ ]
+
+ if not started_shards:
+ return float("nan")
+
+ return sum(started_shards) / len(started_shards)
+
+ @property
+ def http_settings(self) -> config.HTTPSettings:
+ # <>
+ return self._http_settings
+
+ @property
+ def is_debug_enabled(self) -> bool:
+ """Return `builtins.True` if debugging is enabled.
+
+ Returns
+ -------
+ builtins.bool
+ `builtins.True` if debugging is enabled, `builtins.False` otherwise.
+
+ """
+ return self._debug
+
+ @property
+ def intents(self) -> typing.Optional[intents_.Intents]:
+ # <>
+ return self._intents
+
+ @property
+ def me(self) -> typing.Optional[users.OwnUser]:
+ # <>
+ return self._cache.get_me()
+
+ @property
+ def proxy_settings(self) -> config.ProxySettings:
+ # <>
+ return self._proxy_settings
+
+ @property
+ def rest(self) -> rest_client_impl.RESTClientImpl:
+ # <>
+ return self._rest
+
+ @property
+ def shards(self) -> typing.Mapping[int, gateway_shard.GatewayShard]:
+ # <>
+ return self._shards
+
+ @property
+ def shard_count(self) -> int:
+ # <>
+ return self._shard_count
+
+ @property
+ def voice(self) -> voice.VoiceComponentImpl:
+ # <>
+ return self._voice
+
+ @property
+ def started_at(self) -> typing.Optional[datetime.datetime]:
+ """Return the datetime when the bot first connected.
+
+ Returns
+ -------
+ datetime.datetime or builtins.None
+ The datetime that the bot connected at for the first time, or
+ `builtins.None` if it has not yet connected.
+ """
+ return self._started_at_timestamp
+
+ @property
+ def uptime(self) -> float:
+ """Return the number of seconds that the bot has been up.
+
+ This is a monotonic time. To get the physical startup date, see
+ `BotApp.started_at` instead.
+
+ Returns
+ -------
+ builtins.float
+ The number of seconds the application has been running for.
+ If not started, then this will return `0.0`.
+ """
+ return date.monotonic() - self._started_at_monotonic if self._started_at_monotonic else 0.0
+
+ async def start(self) -> None:
+ """Determine sharding settings if needed, and start all shards.
+
+ This method will first log if any library updates are available.
+
+ The bot user info and sharding settings will be fetched from the REST
+ API. If no explicit shard count/shard IDs have been provided to the
+ constructor of this class, then the recommended shard count that
+ Discord recommends will be used instead.
+
+ The first shard will be started individually first. This ensures that
+ we do not spam IDENTIFY payloads on multiple shards in large
+ applications if the application will be unable to start.
+
+ After this, each remaining shard will be started, respecting the API's
+ max concurrency that Discord specifies.
+
+ This will return once all shards that are to be started have
+ fired their READY event. Any exceptions that are raised before this
+ will be propagated, and all existing connections will be closed again.
+
+ To wait for the bot to close indefinitely, you should call `BotApp.join`
+ immediately after this call returns, else this will attempt to
+ keep-alive in the background.
+ """
+ asyncio.create_task(version_sniffer.log_available_updates(_LOGGER), name="check for hikari library updates")
+
+ self._start_count += 1
+ self._started_at_monotonic = date.monotonic()
+ self._started_at_timestamp = date.local_datetime()
+
+ if self._debug is True:
+ _LOGGER.warning("debug mode is enabled, performance may be affected")
+
+ # If possible, set the coroutine origin tracking depth to a larger value.
+ # This feature is provisional, so don't hold your breath if it doesn't
+ # exist.
+ with contextlib.suppress(AttributeError, NameError):
+ # noinspection PyUnresolvedReferences
+ sys.set_coroutine_origin_tracking_depth(40) # type: ignore[attr-defined]
+
+ # Set debugging on the event loop.
+ asyncio.get_event_loop().set_debug(True)
+
+ self._tasks.clear()
+ self._shard_gather_task = None
+
+ await self._init()
+
+ self._request_close_event.clear()
+
+ await self.dispatch(lifetime_events.StartingEvent(app=self))
+
+ start_time = date.monotonic()
+
+ try:
+ for i, shard_ids in enumerate(self._max_concurrency_chunker()):
+ if self._request_close_event.is_set():
+ break
+
+ if i > 0:
+ _LOGGER.info("backing off for 5 seconds")
+ completed, _ = await asyncio.wait(
+ self._tasks.values(), timeout=5, return_when=asyncio.FIRST_COMPLETED
+ )
+
+ while completed:
+ if (ex := completed.pop().exception()) is not None:
+ raise ex
+
+ window = {}
+ for shard_id in shard_ids:
+ shard_obj = self._shards[shard_id]
+ window[shard_id] = asyncio.create_task(shard_obj.start(), name=f"start gateway shard {shard_id}")
+
+ # Wait for the group to start.
+ await asyncio.gather(*window.values())
+
+ # Store the keep-alive tasks and continue.
+ for shard_id, start_task in window.items():
+ self._tasks[shard_id] = start_task.result()
+
+ finally:
+ if len(self._tasks) != len(self._shards):
+ _LOGGER.warning(
+ "application aborted midway through initialization, will begin shutting down %s shard(s)",
+ len(self._tasks),
+ )
+ await self._abort_shards()
+
+ # We know an error occurred if this condition is met, so re-raise it.
+ raise
+
+ finish_time = date.monotonic()
+ self._shard_gather_task = asyncio.create_task(
+ self._gather_shard_lifecycles(), name=f"zookeeper for {len(self._shards)} shard(s)"
+ )
+
+ # Don't bother logging this if we are single sharded. It is useless information.
+ if len(self._shard_ids) > 1:
+ _LOGGER.info("started %s shard(s) in approx %.2fs", len(self._shards), finish_time - start_time)
+
+ await self.dispatch(lifetime_events.StartedEvent(app=self))
+
+ def listen(
+ self, event_type: typing.Optional[typing.Type[event_dispatcher.EventT_co]] = None,
+ ) -> typing.Callable[
+ [event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]],
+ event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ ]:
+ # <>
+ return self.dispatcher.listen(event_type)
+
+ def get_listeners(
+ self, event_type: typing.Type[event_dispatcher.EventT_co], *, polymorphic: bool = True,
+ ) -> typing.Collection[event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]]:
+ # <>
+ return self.dispatcher.get_listeners(event_type, polymorphic=polymorphic)
+
+ def subscribe(
+ self,
+ event_type: typing.Type[event_dispatcher.EventT_co],
+ callback: event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ ) -> event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]:
+ # <>
+ return self.dispatcher.subscribe(event_type, callback)
+
+ def unsubscribe(
+ self,
+ event_type: typing.Type[event_dispatcher.EventT_co],
+ callback: event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ ) -> None:
+ # <>
+ return self.dispatcher.unsubscribe(event_type, callback)
+
+ async def wait_for(
+ self,
+ event_type: typing.Type[event_dispatcher.EventT_co],
+ /,
+ timeout: typing.Union[float, int, None],
+ predicate: typing.Optional[event_dispatcher.PredicateT[event_dispatcher.EventT_co]] = None,
+ ) -> event_dispatcher.EventT_co:
+ # <>
+ return await self.dispatcher.wait_for(event_type, predicate=predicate, timeout=timeout)
+
+ def dispatch(self, event: base_events.Event) -> asyncio.Future[typing.Any]:
+ # <>
+ return self.dispatcher.dispatch(event)
+
+ async def close(self) -> None:
+ """Request that all shards disconnect and the application shuts down.
+
+ This will close all shards that are running, and then close any
+ REST components and connectors.
+ """
+ self._guild_chunker.close()
+
+ try:
+ if self._tasks:
+ # This way if we cancel the stopping task, we still shut down properly.
+ self._request_close_event.set()
+
+ _LOGGER.info("stopping %s shard(s)", len(self._tasks))
+
+ try:
+ await self.dispatch(lifetime_events.StoppingEvent(app=self))
+ await self._abort_shards()
+ finally:
+ self._tasks.clear()
+ await self.dispatch(lifetime_events.StoppedEvent(app=self))
+ finally:
+ await self._rest.close()
+ await self._connector_factory.close()
+ self._global_ratelimit.close()
+
+ def run(self, *, close_loop: bool = True) -> None:
+ """Run this application on the current thread in an event loop.
+
+ This will use the event loop that is set for the current thread, or
+ it will create one if it does not already exist.
+
+ This call will **block** the current thread until the application
+ has closed. Additionally, it will hook into any OS signals to
+ detect external interrupts to request the process terminates.
+
+ All hooks will be removed again on shutdown. Any fatal exceptions
+ that may have occurred during the startup or execution of the
+ application will be propagated.
+
+ The application is always guaranteed to be shut down before this
+ function completes or propagates any exception.
+
+ Parameters
+ ----------
+ close_loop : builtins.bool
+ If `builtins.True` (per the default), then the event loop will
+ be explicitly closed once the application has closed. If
+ `builtins.False`, this behaviour will not occur.
+
+ Setting this to `builtins.False` may be desirable if you wish
+ to continue using the event loop after the application has closed.
+ """
+ try:
+ loop = asyncio.get_event_loop()
+ except RuntimeError:
+ _LOGGER.debug("no event loop registered on this thread; now creating one...")
+ loop = asyncio.new_event_loop()
+ asyncio.set_event_loop(loop)
+
+ try:
+ self._map_signal_handlers(
+ loop.add_signal_handler,
+ lambda *_: loop.create_task(self.close(), name="signal interrupt shutting down application"),
+ )
+ loop.run_until_complete(self._shard_management_lifecycle())
+
+ except KeyboardInterrupt as ex:
+ _LOGGER.info("received signal to shut down client")
+ if self._debug:
+ raise
+ # The user will not care where this gets raised from, unless we are
+ # debugging. It just causes a lot of confusing spam.
+ raise ex.with_traceback(None) from None
+
+ finally:
+ self._map_signal_handlers(loop.remove_signal_handler)
+ _LOGGER.info("client has shut down")
+
+ if close_loop and not loop.is_closed():
+ _LOGGER.info("closing event loop")
+ loop.close()
+
+ async def join(self) -> None:
+ """Wait for the application to finish running.
+
+ If the application has not started, then calling this will return
+ immediately.
+
+ Any exceptions that are raised by the application that go unhandled
+ will be propagated.
+ """
+ if self._shard_gather_task is not None:
+ await self._shard_gather_task
+
+ async def update_presence(
+ self,
+ *,
+ status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
+ activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
+ idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
+ afk: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ ) -> None:
+ """Update the presence on all shards.
+
+ This call will patch the presence on each shard. This means that
+ unless you explicitly specify a parameter, the previous value will be
+ retained. This means you do not have to track the global presence
+ in your code.
+
+ Parameters
+ ----------
+ status : hikari.utilities.undefined.UndefinedOr[hikari.models.presences.Status]
+ The status to set all shards to. If undefined, no statuses are
+ changed.
+ activity : hikari.utilities.undefined.UndefinedNoneOr[hikari.models.presences.Activity]
+ The activity to set. May be `builtins.None` if the activity should
+ be cleared. If undefined, no activities are changed.
+ idle_since : hikari.utilities.undefined.UndefinedNoneOr[datetime.datetime]
+ The datetime to appear to be idle since. If `builtins.None`, then
+ this is not sent (this does not need to be specified to set the
+ bot's status to idle). If undefined, the idle timestamp is not
+ changed.
+ afk : hikari.utilities.undefined.UndefinedOr[builtins.bool]
+ If `builtins.True`, then the bot is marked as being AFK. If
+ `builtins.False`, the bot is marked as not being AFK. If
+ unspecified, this is not changed.
+
+ !!! note
+ This will only send the update payloads to shards that are alive.
+ Any shards that are not alive will cache the new presence for
+ when they do start.
+
+ !!! note
+ If you want to set presences per shard, access the shard you wish
+ to update (e.g. by using `BotApp.shards`), and call
+ `hikari.api.shard.IGatewayShard.update_presence` on that shard.
+
+ This method is simply a facade to make performing this in bulk
+ simpler.
+ """
+ coros = [
+ s.update_presence(status=status, activity=activity, idle_since=idle_since, afk=afk)
+ for s in self._shards.values()
+ ]
+
+ await asyncio.gather(*coros)
+
+ async def _init(self) -> None:
+ gw_recs, bot_user = await asyncio.gather(self.rest.fetch_gateway_bot(), self.rest.fetch_my_user())
+
+ self._cache.set_me(bot_user)
+
+ self._shard_count = self._shard_count if self._shard_count else gw_recs.shard_count
+ self._shard_ids = self._shard_ids if self._shard_ids else set(range(self._shard_count))
+ self._max_concurrency = gw_recs.session_start_limit.max_concurrency
+ url = gw_recs.url
+
+ reset_at = gw_recs.session_start_limit.reset_at.strftime("%d/%m/%y %H:%M:%S %Z").rstrip()
+
+ shard_clients: typing.Dict[int, gateway_shard.GatewayShard] = {}
+ for shard_id in self._shard_ids:
+ # TODO: allow custom connector factory?
+ shard = gateway_shard_impl.GatewayShardImpl(
+ compression=gateway_shard.GatewayCompression.PAYLOAD_ZLIB_STREAM,
+ data_format=gateway_shard.GatewayDataFormat.JSON,
+ debug=self._debug,
+ event_consumer=self._event_manager.consume_raw_event,
+ http_settings=self._http_settings,
+ initial_activity=self._initial_activity,
+ initial_idle_since=self._initial_idle_since,
+ initial_is_afk=self._initial_is_afk,
+ initial_status=self._initial_status,
+ intents=self._intents,
+ large_threshold=self._large_threshold,
+ proxy_settings=self._proxy_settings,
+ shard_id=shard_id,
+ shard_count=self._shard_count,
+ token=self._token,
+ url=url,
+ version=self._version,
+ )
+ shard_clients[shard_id] = shard
+
+ self._shards = shard_clients
+
+ if len(self._shard_ids) == 1 and self._shard_ids == {0}:
+ _LOGGER.info(
+ "single-sharded configuration -- you have started %s/%s sessions prior to connecting (resets at %s)",
+ gw_recs.session_start_limit.used,
+ gw_recs.session_start_limit.total,
+ reset_at,
+ )
+ else:
+ _LOGGER.info(
+ "will connect %s/%s shards with a max concurrency of %s -- "
+ "you have started %s/%s sessions prior to connecting (resets at %s)",
+ len(self._shard_ids),
+ self._shard_count,
+ self._max_concurrency,
+ gw_recs.session_start_limit.used,
+ gw_recs.session_start_limit.total,
+ reset_at,
+ )
+
+ def _max_concurrency_chunker(self) -> typing.Iterator[typing.Iterator[int]]:
+ """Yield generators of shard IDs.
+
+ Each yielded generator will yield every shard ID that can be started
+ at the same time.
+
+ You should then wait 5 seconds between each window.
+
+ The first window will always contain a single shard.
+ The reasoning behind this is to ensure we are able to successfully
+ connect on one shard before spamming the gateway with failed
+ connections on large applications, as this can exhaust the daily
+ identify limit.
+ """
+ n = 0
+ is_first = True
+
+ while n < self._shard_count:
+ next_window = [i for i in range(n, n + self._max_concurrency) if i in self._shard_ids]
+ # Don't yield anything if no IDs are in the given window.
+ if next_window:
+ if is_first:
+ is_first = False
+ first, next_window = next_window[0], next_window[1:]
+ yield iter((first,))
+
+ yield iter(next_window)
+ n += self._max_concurrency
+
+ async def _abort_shards(self) -> None:
+ """Close all shards and wait for them to terminate."""
+ for shard_id in self._tasks:
+ if self._shards[shard_id].is_alive:
+ _LOGGER.debug("stopping shard %s", shard_id)
+ await self._shards[shard_id].close()
+ await asyncio.gather(*self._tasks.values(), return_exceptions=True)
+
+ async def _gather_shard_lifecycles(self) -> None:
+ """Await all shards.
+
+ Ensure shards are requested to close before the coroutine function
+ completes.
+ """
+ try:
+ _LOGGER.debug("gathering shards")
+ await asyncio.gather(*self._tasks.values())
+ finally:
+ _LOGGER.debug("gather terminated, shutting down shard(s)")
+ await asyncio.shield(self.close())
+
+ async def _shard_management_lifecycle(self) -> None:
+ """Start all shards and then wait for them to finish."""
+ await self.start()
+ await self.join()
+
+ @staticmethod
+ def _map_signal_handlers(
+ mapping_function: typing.Callable[..., None], *args: typing.Callable[[], typing.Any]
+ ) -> None:
+ """Register/deregister a given signal handler to all signals."""
+ valid_interrupts = signal.valid_signals()
+ # We must getattr on these, or we risk an exception occurring on Windows.
+ for interrupt_name in ("SIGQUIT", "SIGTERM"):
+ interrupt = getattr(signal, interrupt_name, None)
+ if interrupt in valid_interrupts:
+ with contextlib.suppress(NotImplementedError):
+ mapping_function(interrupt, *args)
+
+ @staticmethod
+ def _dump_banner(banner_package: str) -> None:
+ """Dump the banner art and wait for it to flush before continuing."""
+ sys.stdout.write(art.get_banner(banner_package) + "\n")
+ sys.stdout.flush()
+ # Give the TTY time to flush properly.
+ time.sleep(0.05)
diff --git a/hikari/impl/buckets.py b/hikari/impl/buckets.py
new file mode 100644
index 0000000000..779002e86a
--- /dev/null
+++ b/hikari/impl/buckets.py
@@ -0,0 +1,593 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Rate-limit extensions for RESTful bucketed endpoints.
+
+Provides implementations for the complex rate limiting mechanisms that Discord
+requires for rate limit handling that conforms to the passed bucket headers
+correctly.
+
+This was initially a bit of a headache for me to understand, personally, since
+there is a lot of "implicit detail" that is easy to miss from the documentation.
+
+In an attempt to make this somewhat understandable by anyone else, I have tried
+to document the theory of how this is handled here.
+
+What is the theory behind this implementation?
+----------------------------------------------
+
+In this module, we refer to a `hikari.utilities.routes.CompiledRoute` as a definition
+of a route with specific major parameter values included (e.g.
+`POST /channels/123/messages`), and a `hikari.utilities.routes.Route` as a
+definition of a route without specific parameter values included (e.g.
+`POST /channels/{channel}/messages`). We can compile a
+`hikari.utilities.routes.CompiledRoute` from a `hikari.utilities.routes.Route`
+by providing the corresponding parameters as kwargs, as you may already know.
+
+In this module, a "bucket" is an internal data structure that tracks and
+enforces the rate limit state for a specific `hikari.utilities.routes.CompiledRoute`,
+and can manage delaying tasks in the event that we begin to get rate limited.
+It also supports providing in-order execution of queued tasks.
+
+Discord allocates types of buckets to routes. If you are making a request and
+there is a valid rate limit on the route you hit, you should receive an
+`X-RateLimit-Bucket` header from the server in your response. This is a hash
+that identifies a route based on internal criteria that does not include major
+parameters. This `X-RateLimitBucket` is known in this module as an "bucket hash".
+
+This means that generally, the route `POST /channels/123/messages` and
+`POST /channels/456/messages` will usually sit in the same bucket, but
+`GET /channels/123/messages/789` and `PATCH /channels/123/messages/789` will
+usually not share the same bucket. Discord may or may not change this at any
+time, so hard coding this logic is not a useful thing to be doing.
+
+Rate limits, on the other hand, apply to a bucket and are specific to the major
+parameters of the compiled route. This means that `POST /channels/123/messages`
+and `POST /channels/456/messages` do not share the same real bucket, despite
+Discord providing the same bucket hash. A real bucket hash is the `builtins.str` hash of
+the bucket that Discord sends us in a response concatenated to the corresponding
+major parameters. This is used for quick bucket indexing internally in this
+module.
+
+One issue that occurs from this is that we cannot effectively hash a
+`hikari.utilities.routes.CompiledRoute` that has not yet been hit, meaning that
+until we receive a response from this endpoint, we have no idea what our rate
+limits could be, nor the bucket that they sit in. This is usually not
+problematic, as the first request to an endpoint should never be rate limited
+unless you are hitting it from elsewhere in the same time window outside your
+hikari.models.applications. To manage this situation, unknown endpoints are allocated to
+a special unlimited bucket until they have an initial bucket hash code allocated
+from a response. Once this happens, the route is reallocated a dedicated bucket.
+Unknown buckets have a hardcoded initial hash code internally.
+
+Initially acquiring time on a bucket
+------------------------------------
+
+Each time you `BaseRateLimiter.acquire()` a request timeslice for a given
+`hikari.utilities.routes.Route`, several things happen. The first is that we
+attempt to find the existing bucket for that route, if there is one, or get an
+unknown bucket otherwise. This is done by creating a real bucket hash from the
+compiled route. The initial hash is calculated using a lookup table that maps
+`hikari.utilities.routes.CompiledRoute` objects to their corresponding initial hash
+codes, or to the unknown bucket hash code if not yet known. This initial hash is
+processed by the `hikari.utilities.routes.CompiledRoute` to provide the real bucket
+hash we need to get the route's bucket object internally.
+
+The `BaseRateLimiter.acquire()` method will take the bucket and acquire a new
+timeslice on it. This takes the form of a `asyncio.Future` which should be
+awaited by the caller and will complete once the caller is allowed to make a
+request. Most of the time, this is done instantly, but if the bucket has an
+active rate limit preventing requests being sent, then the future will be paused
+until the rate limit is over. This may be longer than the rate limit period if
+you have queued a large number of requests during this limit, as it is
+first-come-first-served.
+
+Acquiring a rate limited bucket will start a bucket-wide task (if not already
+running) that will wait until the rate limit has completed before allowing more
+futures to complete. This is done while observing the rate limits again, so can
+easily begin to re-ratelimit itself if needed. Once the task is complete, it
+tidies itself up and disposes of itself. This task will complete once the queue
+becomes empty.
+
+The result of `RESTBucketManager.acquire()` is a tuple of a `asyncio.Future` to
+await on which completes when you are allowed to proceed with making a request,
+and a real bucket hash which should be stored temporarily. This will be
+explained in the next section.
+
+When you make your response, you should be sure to set the
+`X-RateLimit-Precision` header to `millisecond` to ensure a much greater
+accuracy against rounding errors for rate limits (reduces the error margin from
+`1` second to `1` millisecond).
+
+Handling the rate limit headers of a response
+---------------------------------------------
+
+Once you have received your response, you are expected to extract the values of
+the vital rate limit headers manually and parse them to the correct data types.
+These headers are:
+
+* `Date`:
+ the response date on the server. This should be parsed to a
+ `datetime.datetime` using `email.utils.parsedate_to_datetime`.
+* `X-RateLimit-Limit`:
+ an `builtins.int` describing the max requests in the bucket from empty to being rate
+ limited.
+* `X-RateLimit-Remaining`:
+ an `builtins.int` describing the remaining number of requests before rate limiting
+ occurs in the current window.
+* `X-RateLimit-Bucket`:
+ a `builtins.str` containing the initial bucket hash.
+* `X-RateLimit-Reset`:
+ a `builtins.float` containing the number of seconds since
+ 1st January 1970 at 0:00:00 UTC at which the current ratelimit window
+ resets. This should be parsed to a `datetime.datetime` using
+ `datetime.datetime.fromtimestamp`, passing `datetime.timezone.utc`
+ as `tz`.
+
+Each of the above values should be passed to the `update_rate_limits` method to
+ensure that the bucket you acquired time from is correctly updated should
+Discord decide to alter their ratelimits on the fly without warning (including
+timings and the bucket).
+
+This method will manage creating new buckets as needed and resetting vital
+information in each bucket you use.
+
+Tidying up
+----------
+
+To prevent unused buckets cluttering up memory, each `RESTBucketManager`
+instance spins up a `asyncio.Task` that periodically locks the bucket list
+(not threadsafe, only using the concept of asyncio not yielding in regular
+functions) and disposes of any clearly stale buckets that are no longer needed.
+These will be recreated again in the future if they are needed.
+
+When shutting down an application, one must remember to `close()` the
+`RESTBucketManager` that has been used. This will ensure the garbage collection
+task is stopped, and will also ensure any remaining futures in any bucket queues
+have an `asyncio.CancelledError` set on them to prevent deadlocking ratelimited
+calls that may be waiting to be unlocked.
+
+Body-field-specific rate limiting
+---------------------------------
+
+As of the start of June, 2020, Discord appears to be enforcing another layer
+of rate limiting logic to their HTTP APIs which is field-specific. This means
+that special rate limits will also exist on some endpoints that limit based
+on what attributes you send in a JSON or form data payload.
+
+No information is sent in headers about these specific limits. You will only
+be made aware that they exist once you get ratelimited. In the 429 ratelimited
+response, you will have the `"global"` attribute set to `builtins.False`, and a
+`"reset_after"` attribute that differs entirely to the `X-RateLimit-Reset`
+header. Thus, it is important to not assume the value in the 429 response
+for the reset time is the same as the one in the bucket headers. Hikari's
+`hikari.api.rest.RESTClient` implementation specifically uses the value furthest
+in the future when working out which bucket to adhere to.
+
+It is worth remembering that there is an API limit to the number of 401s,
+403s, and 429s you receive, which is around 10,000 per 15 minutes. Passing this
+limit results in a soft ban of your account.
+
+At the time of writing, the only example of this appears to be on the
+`PATCH /channels/{channel_id}` endpoint. This has a limit of two changes per
+10 minutes. More details about how this is implemented have yet to be
+released or documented...
+
+
+Caveats
+-------
+
+These implementations rely on Discord sending consistent buckets back to us.
+
+This also begins to crumble if more than one HTTP client is in use, since
+there is no performent way to communicate shared rate limits between
+distributed applications. The general concept to follow is that if you are
+making repeated API calls, or calls that are not event-based (e.g.
+fetching messages on a timer), then this can be considered a form of API abuse
+and should be used sparingly.
+"""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["UNKNOWN_HASH", "RESTBucket", "RESTBucketManager"]
+
+import asyncio
+import datetime
+import logging
+import typing
+
+from hikari.impl import rate_limits
+from hikari.utilities import aio
+from hikari.utilities import date
+from hikari.utilities import routes
+
+if typing.TYPE_CHECKING:
+ import types
+
+
+UNKNOWN_HASH: typing.Final[str] = "UNKNOWN"
+"""The hash used for an unknown bucket that has not yet been resolved."""
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari.ratelimits")
+
+
+class RESTBucket(rate_limits.WindowedBurstRateLimiter):
+ """Represents a rate limit for an HTTP endpoint.
+
+ Component to represent an active rate limit bucket on a specific HTTP _route
+ with a specific major parameter combo.
+
+ This is somewhat similar to the `WindowedBurstRateLimiter` in how it
+ works.
+
+ This algorithm will use fixed-period time windows that have a given limit
+ (capacity). Each time a task requests processing time, it will drip another
+ unit into the bucket. Once the bucket has reached its limit, nothing can
+ drip and new tasks will be queued until the time window finishes.
+
+ Once the time window finishes, the bucket will empty, returning the current
+ capacity to zero, and tasks that are queued will start being able to drip
+ again.
+
+ Additional logic is provided by the `RESTBucket.update_rate_limit` call
+ which allows dynamically changing the enforced rate limits at any time.
+ """
+
+ __slots__: typing.Sequence[str] = ("compiled_route",)
+
+ compiled_route: typing.Final[routes.CompiledRoute]
+ """The compiled _route that this rate limit is covering."""
+
+ def __init__(self, name: str, compiled_route: routes.CompiledRoute) -> None:
+ super().__init__(name, 1, 1)
+ self.compiled_route = compiled_route
+
+ @property
+ def is_unknown(self) -> bool:
+ """Return `builtins.True` if the bucket represents an `UNKNOWN` bucket."""
+ return self.name.startswith(UNKNOWN_HASH)
+
+ def acquire(self) -> asyncio.Future[None]:
+ """Acquire time on this rate limiter.
+
+ !!! note
+ You should afterwards invoke `RESTBucket.update_rate_limit` to
+ update any rate limit information you are made aware of.
+
+ Returns
+ -------
+ asyncio.Future[builtins.None]
+ A future that should be awaited immediately. Once the future completes,
+ you are allowed to proceed with your operation.
+ """
+ return aio.completed_future(None) if self.is_unknown else super().acquire()
+
+ def update_rate_limit(self, remaining: int, limit: int, reset_at: float) -> None:
+ """Amend the rate limit.
+
+ Parameters
+ ----------
+ remaining : builtins.int
+ The calls remaining in this time window.
+ limit : builtins.int
+ The total calls allowed in this time window.
+ reset_at : builtins.float
+ The epoch at which to reset the limit.
+
+ !!! note
+ The `reset_at` epoch is expected to be a `date.monotonic_timestamp`
+ monotonic epoch, rather than a `time.time` date-based epoch.
+ """
+ self.remaining = remaining
+ self.limit = limit
+ self.reset_at = reset_at
+ self.period = max(0.0, self.reset_at - date.monotonic())
+
+ def drip(self) -> None:
+ """Decrement the remaining count for this bucket.
+
+ !!! note
+ If the bucket is marked as `RESTBucket.is_unknown`, then this will
+ not do anything. `Unknown` buckets have infinite rate limits.
+ """
+ # We don't drip unknown buckets: we cannot rate limit them as we don't know their real bucket hash or
+ # the current rate limit values Discord put on them...
+ if not self.is_unknown:
+ self.remaining -= 1
+
+
+class RESTBucketManager:
+ """The main rate limiter implementation for HTTP clients.
+
+ This is designed to provide bucketed rate limiting for Discord HTTP
+ endpoints that respects the `X-RateLimit-Bucket` rate limit header. To do
+ this, it makes the assumption that any limit can change at any time.
+ """
+
+ _POLL_PERIOD: typing.Final[typing.ClassVar[int]] = 20
+ _EXPIRE_PERIOD: typing.Final[typing.ClassVar[int]] = 10
+
+ __slots__: typing.Sequence[str] = (
+ "routes_to_hashes",
+ "real_hashes_to_buckets",
+ "closed_event",
+ "gc_task",
+ )
+
+ routes_to_hashes: typing.Final[typing.MutableMapping[routes.Route, str]]
+ """Maps routes to their `X-RateLimit-Bucket` header being used."""
+
+ real_hashes_to_buckets: typing.Final[typing.MutableMapping[str, RESTBucket]]
+ """Maps full bucket hashes (`X-RateLimit-Bucket` appended with a hash of
+ major parameters used in that compiled _route) to their corresponding rate
+ limiters.
+ """
+
+ closed_event: typing.Final[asyncio.Event]
+ """An internal event that is set when the object is shut down."""
+
+ gc_task: typing.Optional[asyncio.Task[None]]
+ """The internal garbage collector task."""
+
+ def __init__(self) -> None:
+ self.routes_to_hashes = {}
+ self.real_hashes_to_buckets = {}
+ self.closed_event: asyncio.Event = asyncio.Event()
+ self.gc_task: typing.Optional[asyncio.Task[None]] = None
+
+ def __enter__(self) -> RESTBucketManager:
+ return self
+
+ def __exit__(self, exc_type: typing.Type[Exception], exc_val: Exception, exc_tb: types.TracebackType) -> None:
+ self.close()
+
+ def __del__(self) -> None:
+ self.close()
+
+ def start(self, poll_period: float = _POLL_PERIOD, expire_after: float = _EXPIRE_PERIOD) -> None:
+ """Start this ratelimiter up.
+
+ This spins up internal garbage collection logic in the background to
+ keep memory usage to an optimal level as old routes and bucket hashes
+ get discarded and replaced.
+
+ Parameters
+ ----------
+ poll_period : builtins.float
+ Period to poll the garbage collector at in seconds. Defaults
+ to `20` seconds.
+ expire_after : builtins.float
+ Time after which the last `reset_at` was hit for a bucket to
+ remove it. Higher values will retain unneeded ratelimit info for
+ longer, but may produce more effective rate-limiting logic as a
+ result. Using `0` will make the bucket get garbage collected as soon
+ as the rate limit has reset. Defaults to `10` seconds.
+ """
+ if not self.gc_task:
+ self.gc_task = asyncio.get_running_loop().create_task(self.gc(poll_period, expire_after))
+
+ def close(self) -> None:
+ """Close the garbage collector and kill any tasks waiting on ratelimits.
+
+ Once this has been called, this object is considered to be effectively
+ dead. To reuse it, one should create a new instance.
+ """
+ self.closed_event.set()
+ for bucket in self.real_hashes_to_buckets.values():
+ bucket.close()
+ self.real_hashes_to_buckets.clear()
+ self.routes_to_hashes.clear()
+
+ # Ignore docstring not starting in an imperative mood
+ async def gc(self, poll_period: float, expire_after: float) -> None: # noqa: D401
+ """The garbage collector loop.
+
+ This is designed to run in the background and manage removing unused
+ _route references from the rate-limiter collection to save memory.
+
+ This will run forever until `RESTBucketManager. closed_event` is set.
+ This will invoke `RESTBucketManager.do_gc_pass` periodically.
+
+ Parameters
+ ----------
+ poll_period : builtins.float
+ The period to poll at.
+ expire_after : builtins.float
+ Time after which the last `reset_at` was hit for a bucket to
+ remove it. Higher values will retain unneeded ratelimit info for
+ longer, but may produce more effective ratelimiting logic as a
+ result. Using `0` will make the bucket get garbage collected as soon
+ as the rate limit has reset.
+
+ !!! warning
+ You generally have no need to invoke this directly. Use
+ `RESTBucketManager.start` and `RESTBucketManager.close` to control
+ this instead.
+ """
+ # Prevent filling memory increasingly until we run out by removing dead buckets every 20s
+ # Allocations are somewhat cheap if we only do them every so-many seconds, after all.
+ _LOGGER.debug("rate limit garbage collector started")
+ while not self.closed_event.is_set():
+ try:
+ await asyncio.wait_for(self.closed_event.wait(), timeout=poll_period)
+ except asyncio.TimeoutError:
+ _LOGGER.debug("performing rate limit garbage collection pass")
+ self.do_gc_pass(expire_after)
+ self.gc_task = None
+
+ def do_gc_pass(self, expire_after: float) -> None:
+ """Perform a single garbage collection pass.
+
+ This will assess any routes stored in the internal mappings of this
+ object and remove any that are deemed to be inactive or dead in order
+ to save memory.
+
+ If the removed routes are used again in the future, they will be
+ re-cached automatically.
+
+ Parameters
+ ----------
+ expire_after : builtins.float
+ Time after which the last `reset_at` was hit for a bucket to\
+ remove it. Defaults to `reset_at` + 20 seconds. Higher values will
+ retain unneeded ratelimit info for longer, but may produce more
+ effective ratelimiting logic as a result.
+
+ !!! warning
+ You generally have no need to invoke this directly. Use
+ `RESTBucketManager.start` and `RESTBucketManager.close` to control
+ this instead.
+ """
+ buckets_to_purge = []
+
+ now = date.monotonic()
+
+ # We have three main states that a bucket can be in:
+ # 1. active - the bucket is active and is not at risk of deallocation
+ # 2. survival - the bucket is inactive but is still fresh enough to be kept alive.
+ # 3. death - the bucket has been inactive for too long.
+ active = 0
+
+ # Discover and purge
+ bucket_pairs = self.real_hashes_to_buckets.items()
+
+ for full_hash, bucket in bucket_pairs:
+ if bucket.is_empty and bucket.reset_at + expire_after < now:
+ # If it is still running a throttle and is in memory, it will remain in memory
+ # but we will not know about it.
+ buckets_to_purge.append(full_hash)
+
+ if bucket.reset_at >= now:
+ active += 1
+
+ dead = len(buckets_to_purge)
+ total = len(bucket_pairs)
+ survival = total - active - dead
+
+ for full_hash in buckets_to_purge:
+ self.real_hashes_to_buckets[full_hash].close()
+ del self.real_hashes_to_buckets[full_hash]
+
+ _LOGGER.debug("purged %s stale buckets, %s remain in survival, %s active", dead, survival, active)
+
+ def acquire(self, compiled_route: routes.CompiledRoute) -> asyncio.Future[None]:
+ """Acquire a bucket for the given _route.
+
+ Parameters
+ ----------
+ compiled_route : hikari.utilities.routes.CompiledRoute
+ The _route to get the bucket for.
+
+ Returns
+ -------
+ asyncio.Future[builtins.None]
+ A future to await that completes when you are allowed to run
+ your request logic.
+
+ !!! note
+ The returned future MUST be awaited, and will complete when your
+ turn to make a call comes along. You are expected to await this and
+ then immediately make your HTTP call. The returned future may
+ already be completed if you can make the call immediately.
+ """
+ # Returns a future to await on to wait to be allowed to send the request, and a
+ # bucket hash to use to update rate limits later.
+ template = compiled_route.route
+
+ if template in self.routes_to_hashes:
+ bucket_hash = self.routes_to_hashes[template]
+ else:
+ bucket_hash = UNKNOWN_HASH
+ self.routes_to_hashes[template] = bucket_hash
+
+ real_bucket_hash = compiled_route.create_real_bucket_hash(bucket_hash)
+
+ try:
+ bucket = self.real_hashes_to_buckets[real_bucket_hash]
+ _LOGGER.debug("%s is being mapped to existing bucket %s", compiled_route, real_bucket_hash)
+ except KeyError:
+ _LOGGER.debug("%s is being mapped to new bucket %s", compiled_route, real_bucket_hash)
+ bucket = RESTBucket(real_bucket_hash, compiled_route)
+ self.real_hashes_to_buckets[real_bucket_hash] = bucket
+
+ return bucket.acquire()
+
+ def update_rate_limits(
+ self,
+ compiled_route: routes.CompiledRoute,
+ bucket_header: str,
+ remaining_header: int,
+ limit_header: int,
+ date_header: datetime.datetime,
+ reset_at_header: datetime.datetime,
+ ) -> None:
+ """Update the rate limits for a bucket using info from a response.
+
+ Parameters
+ ----------
+ compiled_route : hikari.utilities.routes.CompiledRoute
+ The compiled _route to get the bucket for.
+ bucket_header : builtins.str or builtins.None
+ The `X-RateLimit-Bucket` header that was provided in the response.
+ remaining_header : builtins.int
+ The `X-RateLimit-Remaining` header cast to an `builtins.int`.
+ limit_header : builtins.int
+ The `X-RateLimit-Limit`header cast to an `builtins.int`.
+ date_header : datetime.datetime
+ The `Date` header value as a `datetime.datetime`.
+ reset_at_header : datetime.datetime
+ The `X-RateLimit-Reset` header value as a `datetime.datetime`.
+ """
+ self.routes_to_hashes[compiled_route.route] = bucket_header
+
+ real_bucket_hash = compiled_route.create_real_bucket_hash(bucket_header)
+
+ reset_after = (reset_at_header - date_header).total_seconds()
+ reset_at_monotonic = date.monotonic() + reset_after
+
+ if real_bucket_hash in self.real_hashes_to_buckets:
+ bucket = self.real_hashes_to_buckets[real_bucket_hash]
+ _LOGGER.debug(
+ "updating %s with bucket %s [reset-after:%ss, limit:%s, remaining:%s]",
+ compiled_route,
+ real_bucket_hash,
+ reset_after,
+ limit_header,
+ remaining_header,
+ )
+ else:
+ bucket = RESTBucket(real_bucket_hash, compiled_route)
+ self.real_hashes_to_buckets[real_bucket_hash] = bucket
+ _LOGGER.debug(
+ "remapping %s with bucket %s [reset-after:%ss, limit:%s, remaining:%s]",
+ compiled_route,
+ real_bucket_hash,
+ reset_after,
+ limit_header,
+ remaining_header,
+ )
+
+ bucket.update_rate_limit(remaining_header, limit_header, reset_at_monotonic)
+
+ @property
+ def is_started(self) -> bool:
+ """Return `builtins.True` if the rate limiter GC task is started."""
+ return self.gc_task is not None
diff --git a/hikari/impl/entity_factory.py b/hikari/impl/entity_factory.py
new file mode 100644
index 0000000000..27cd459ce8
--- /dev/null
+++ b/hikari/impl/entity_factory.py
@@ -0,0 +1,1855 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic implementation of an entity factory for general bots and HTTP apps."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["EntityFactoryImpl"]
+
+import datetime
+import typing
+
+import attr
+
+from hikari import traits
+from hikari.api import entity_factory
+from hikari.models import applications as application_models
+from hikari.models import audit_logs as audit_log_models
+from hikari.models import channels as channel_models
+from hikari.models import colors as color_models
+from hikari.models import embeds as embed_models
+from hikari.models import emojis as emoji_models
+from hikari.models import gateway as gateway_models
+from hikari.models import guilds as guild_models
+from hikari.models import invites as invite_models
+from hikari.models import messages as message_models
+from hikari.models import permissions as permission_models
+from hikari.models import presences as presence_models
+from hikari.models import users as user_models
+from hikari.models import voices as voice_models
+from hikari.models import webhooks as webhook_models
+from hikari.utilities import attr_extensions
+from hikari.utilities import data_binding
+from hikari.utilities import date
+from hikari.utilities import files
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+
+def _deserialize_seconds_timedelta(seconds: typing.Union[str, int]) -> datetime.timedelta:
+ return datetime.timedelta(seconds=int(seconds))
+
+
+def _deserialize_day_timedelta(days: typing.Union[str, int]) -> datetime.timedelta:
+ return datetime.timedelta(days=int(days))
+
+
+def _deserialize_max_uses(age: int) -> typing.Optional[int]:
+ return age if age > 0 else None
+
+
+def _deserialize_max_age(seconds: int) -> typing.Optional[datetime.timedelta]:
+ return datetime.timedelta(seconds=seconds) if seconds > 0 else None
+
+
+@attr_extensions.with_copy
+@attr.s(init=True, kw_only=True, repr=False, slots=True, weakref_slot=False)
+class _PartialGuildFields:
+ id: snowflake.Snowflake = attr.ib()
+ name: str = attr.ib()
+ icon_hash: str = attr.ib()
+ features: typing.Sequence[typing.Union[guild_models.GuildFeature, str]] = attr.ib()
+
+
+@attr_extensions.with_copy
+@attr.s(init=True, kw_only=True, repr=False, slots=True, weakref_slot=False)
+class _GuildChannelFields:
+ id: snowflake.Snowflake = attr.ib()
+ name: typing.Optional[str] = attr.ib()
+ type: channel_models.ChannelType = attr.ib()
+ guild_id: snowflake.Snowflake = attr.ib()
+ position: int = attr.ib()
+ permission_overwrites: typing.Mapping[snowflake.Snowflake, channel_models.PermissionOverwrite] = attr.ib()
+ is_nsfw: typing.Optional[bool] = attr.ib()
+ parent_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+
+
+@attr_extensions.with_copy
+@attr.s(init=True, kw_only=True, repr=False, slots=True, weakref_slot=False)
+class _IntegrationFields:
+ id: snowflake.Snowflake = attr.ib()
+ name: str = attr.ib()
+ type: str = attr.ib()
+ account: guild_models.IntegrationAccount = attr.ib()
+
+
+@attr_extensions.with_copy
+@attr.s(init=True, kw_only=True, repr=False, slots=True, weakref_slot=False)
+class _GuildFields(_PartialGuildFields):
+ splash_hash: typing.Optional[str] = attr.ib()
+ discovery_splash_hash: typing.Optional[str] = attr.ib()
+ owner_id: snowflake.Snowflake = attr.ib()
+ region: str = attr.ib()
+ afk_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ afk_timeout: datetime.timedelta = attr.ib()
+ verification_level: guild_models.GuildVerificationLevel = attr.ib()
+ default_message_notifications: guild_models.GuildMessageNotificationsLevel = attr.ib()
+ explicit_content_filter: guild_models.GuildExplicitContentFilterLevel = attr.ib()
+ mfa_level: guild_models.GuildMFALevel = attr.ib()
+ application_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ widget_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ system_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ is_widget_enabled: typing.Optional[bool] = attr.ib()
+ system_channel_flags: guild_models.GuildSystemChannelFlag = attr.ib()
+ rules_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ max_presences: typing.Optional[int] = attr.ib()
+ max_members: typing.Optional[int] = attr.ib()
+ max_video_channel_users: typing.Optional[int] = attr.ib()
+ vanity_url_code: typing.Optional[str] = attr.ib()
+ description: typing.Optional[str] = attr.ib()
+ banner_hash: typing.Optional[str] = attr.ib()
+ premium_tier: guild_models.GuildPremiumTier = attr.ib()
+ premium_subscription_count: typing.Optional[int] = attr.ib()
+ preferred_locale: str = attr.ib()
+ public_updates_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+
+
+@attr_extensions.with_copy
+@attr.s(init=True, kw_only=True, repr=False, slots=True, weakref_slot=False)
+class _InviteFields:
+ code: str = attr.ib()
+ guild: typing.Optional[invite_models.InviteGuild] = attr.ib()
+ guild_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ channel: typing.Optional[channel_models.PartialChannel] = attr.ib()
+ channel_id: snowflake.Snowflake = attr.ib()
+ inviter: typing.Optional[user_models.User] = attr.ib()
+ target_user: typing.Optional[user_models.User] = attr.ib()
+ target_user_type: typing.Optional[invite_models.TargetUserType] = attr.ib()
+ approximate_presence_count: typing.Optional[int] = attr.ib()
+ approximate_member_count: typing.Optional[int] = attr.ib()
+
+
+@attr_extensions.with_copy
+@attr.s(init=True, kw_only=True, repr=False, slots=True, weakref_slot=False)
+class _UserFields:
+ id: snowflake.Snowflake = attr.ib()
+ discriminator: str = attr.ib()
+ username: str = attr.ib()
+ avatar_hash: str = attr.ib()
+ is_bot: bool = attr.ib()
+ is_system: bool = attr.ib()
+
+
+class EntityFactoryImpl(entity_factory.EntityFactory):
+ """Standard implementation for a serializer/deserializer.
+
+ This will convert objects to/from JSON compatible representations.
+ """
+
+ __slots__: typing.Sequence[str] = (
+ "_app",
+ "_audit_log_entry_converters",
+ "_audit_log_event_mapping",
+ "_dm_channel_type_mapping",
+ "_guild_channel_type_mapping",
+ )
+
+ def __init__(self, app: traits.RESTAware) -> None:
+ self._app = app
+ self._audit_log_entry_converters: typing.Mapping[str, typing.Callable[[typing.Any], typing.Any]] = {
+ audit_log_models.AuditLogChangeKey.OWNER_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.AFK_CHANNEL_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.AFK_TIMEOUT: _deserialize_seconds_timedelta,
+ audit_log_models.AuditLogChangeKey.MFA_LEVEL: guild_models.GuildMFALevel,
+ audit_log_models.AuditLogChangeKey.VERIFICATION_LEVEL: guild_models.GuildVerificationLevel,
+ audit_log_models.AuditLogChangeKey.EXPLICIT_CONTENT_FILTER: guild_models.GuildExplicitContentFilterLevel,
+ audit_log_models.AuditLogChangeKey.DEFAULT_MESSAGE_NOTIFICATIONS: guild_models.GuildMessageNotificationsLevel,
+ # noqa: E501 - Line too long
+ audit_log_models.AuditLogChangeKey.PRUNE_DELETE_DAYS: _deserialize_day_timedelta,
+ audit_log_models.AuditLogChangeKey.WIDGET_CHANNEL_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.POSITION: int,
+ audit_log_models.AuditLogChangeKey.BITRATE: int,
+ audit_log_models.AuditLogChangeKey.APPLICATION_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.PERMISSIONS: permission_models.Permissions,
+ audit_log_models.AuditLogChangeKey.COLOR: color_models.Color,
+ audit_log_models.AuditLogChangeKey.ALLOW: permission_models.Permissions,
+ audit_log_models.AuditLogChangeKey.DENY: permission_models.Permissions,
+ audit_log_models.AuditLogChangeKey.CHANNEL_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.INVITER_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.MAX_USES: _deserialize_max_uses,
+ audit_log_models.AuditLogChangeKey.USES: int,
+ audit_log_models.AuditLogChangeKey.MAX_AGE: _deserialize_max_age,
+ audit_log_models.AuditLogChangeKey.ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.TYPE: str,
+ audit_log_models.AuditLogChangeKey.ENABLE_EMOTICONS: bool,
+ audit_log_models.AuditLogChangeKey.EXPIRE_BEHAVIOR: guild_models.IntegrationExpireBehaviour,
+ audit_log_models.AuditLogChangeKey.EXPIRE_GRACE_PERIOD: _deserialize_day_timedelta,
+ audit_log_models.AuditLogChangeKey.RATE_LIMIT_PER_USER: _deserialize_seconds_timedelta,
+ audit_log_models.AuditLogChangeKey.SYSTEM_CHANNEL_ID: snowflake.Snowflake,
+ audit_log_models.AuditLogChangeKey.ADD_ROLE_TO_MEMBER: self._deserialize_audit_log_change_roles,
+ audit_log_models.AuditLogChangeKey.REMOVE_ROLE_FROM_MEMBER: self._deserialize_audit_log_change_roles,
+ audit_log_models.AuditLogChangeKey.PERMISSION_OVERWRITES: self._deserialize_audit_log_overwrites,
+ }
+ self._audit_log_event_mapping: typing.Mapping[
+ typing.Union[int, audit_log_models.AuditLogEventType],
+ typing.Callable[[data_binding.JSONObject], audit_log_models.BaseAuditLogEntryInfo],
+ ] = {
+ audit_log_models.AuditLogEventType.CHANNEL_OVERWRITE_CREATE: self._deserialize_channel_overwrite_entry_info,
+ audit_log_models.AuditLogEventType.CHANNEL_OVERWRITE_UPDATE: self._deserialize_channel_overwrite_entry_info,
+ audit_log_models.AuditLogEventType.CHANNEL_OVERWRITE_DELETE: self._deserialize_channel_overwrite_entry_info,
+ audit_log_models.AuditLogEventType.MESSAGE_PIN: self._deserialize_message_pin_entry_info,
+ audit_log_models.AuditLogEventType.MESSAGE_UNPIN: self._deserialize_message_pin_entry_info,
+ audit_log_models.AuditLogEventType.MEMBER_PRUNE: self._deserialize_member_prune_entry_info,
+ audit_log_models.AuditLogEventType.MESSAGE_BULK_DELETE: self._deserialize_message_bulk_delete_entry_info,
+ audit_log_models.AuditLogEventType.MESSAGE_DELETE: self._deserialize_message_delete_entry_info,
+ audit_log_models.AuditLogEventType.MEMBER_DISCONNECT: self._deserialize_member_disconnect_entry_info,
+ audit_log_models.AuditLogEventType.MEMBER_MOVE: self._deserialize_member_move_entry_info,
+ }
+ self._dm_channel_type_mapping = {
+ channel_models.ChannelType.PRIVATE_TEXT: self.deserialize_private_text_channel,
+ channel_models.ChannelType.PRIVATE_GROUP_TEXT: self.deserialize_private_group_text_channel,
+ }
+ self._guild_channel_type_mapping = {
+ channel_models.ChannelType.GUILD_CATEGORY: self.deserialize_guild_category,
+ channel_models.ChannelType.GUILD_TEXT: self.deserialize_guild_text_channel,
+ channel_models.ChannelType.GUILD_NEWS: self.deserialize_guild_news_channel,
+ channel_models.ChannelType.GUILD_STORE: self.deserialize_guild_store_channel,
+ channel_models.ChannelType.GUILD_VOICE: self.deserialize_guild_voice_channel,
+ }
+
+ ######################
+ # APPLICATION MODELS #
+ ######################
+
+ def deserialize_own_connection(self, payload: data_binding.JSONObject) -> application_models.OwnConnection:
+ if (integration_payloads := payload.get("integrations")) is not None:
+ integrations = [self.deserialize_partial_integration(integration) for integration in integration_payloads]
+ else:
+ integrations = []
+
+ return application_models.OwnConnection(
+ id=payload["id"],
+ name=payload["name"],
+ type=payload["type"],
+ is_revoked=payload["revoked"],
+ integrations=integrations,
+ is_verified=payload["verified"],
+ is_friend_sync_enabled=payload["friend_sync"],
+ is_activity_visible=payload["show_activity"],
+ visibility=application_models.ConnectionVisibility(payload["visibility"]),
+ )
+
+ def deserialize_own_guild(self, payload: data_binding.JSONObject) -> application_models.OwnGuild:
+ guild_fields = self._set_partial_guild_attributes(payload)
+ return application_models.OwnGuild(
+ app=self._app,
+ id=guild_fields.id,
+ name=guild_fields.name,
+ icon_hash=guild_fields.icon_hash,
+ features=guild_fields.features,
+ is_owner=bool(payload["owner"]),
+ my_permissions=permission_models.Permissions(int(payload["permissions_new"])),
+ )
+
+ def deserialize_application(self, payload: data_binding.JSONObject) -> application_models.Application:
+ team: typing.Optional[application_models.Team] = None
+ if (team_payload := payload.get("team")) is not None:
+ members = {}
+ for member_payload in team_payload["members"]:
+ team_member = application_models.TeamMember(
+ app=self._app,
+ membership_state=application_models.TeamMembershipState(member_payload["membership_state"]),
+ permissions=member_payload["permissions"],
+ team_id=snowflake.Snowflake(member_payload["team_id"]),
+ user=self.deserialize_user(member_payload["user"]),
+ )
+ members[team_member.user.id] = team_member
+
+ team = application_models.Team(
+ app=self._app,
+ id=snowflake.Snowflake(team_payload["id"]),
+ icon_hash=team_payload["icon"],
+ members=members,
+ owner_id=snowflake.Snowflake(team_payload["owner_user_id"]),
+ )
+
+ primary_sku_id = snowflake.Snowflake(payload["primary_sku_id"]) if "primary_sku_id" in payload else None
+
+ return application_models.Application(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload["name"],
+ description=payload["description"],
+ is_bot_public=payload.get("bot_public"),
+ is_bot_code_grant_required=payload.get("bot_require_code_grant"),
+ owner=self.deserialize_user(payload["owner"]) if "owner" in payload else None,
+ rpc_origins=payload["rpc_origins"] if "rpc_origins" in payload else None,
+ summary=payload["summary"],
+ verify_key=bytes(payload["verify_key"], "utf-8") if "verify_key" in payload else None,
+ icon_hash=payload.get("icon"),
+ team=team,
+ guild_id=snowflake.Snowflake(payload["guild_id"]) if "guild_id" in payload else None,
+ primary_sku_id=primary_sku_id,
+ slug=payload.get("slug"),
+ cover_image_hash=payload.get("cover_image"),
+ )
+
+ #####################
+ # AUDIT LOGS MODELS #
+ #####################
+
+ def _deserialize_audit_log_change_roles(
+ self, payload: data_binding.JSONArray
+ ) -> typing.Mapping[snowflake.Snowflake, guild_models.PartialRole]:
+ roles = {}
+ for role_payload in payload:
+ role = guild_models.PartialRole(
+ app=self._app, id=snowflake.Snowflake(role_payload["id"]), name=role_payload["name"]
+ )
+ roles[role.id] = role
+
+ return roles
+
+ def _deserialize_audit_log_overwrites(
+ self, payload: data_binding.JSONArray
+ ) -> typing.Mapping[snowflake.Snowflake, channel_models.PermissionOverwrite]:
+ return {
+ snowflake.Snowflake(overwrite["id"]): self.deserialize_permission_overwrite(overwrite)
+ for overwrite in payload
+ }
+
+ @staticmethod
+ def _deserialize_channel_overwrite_entry_info(
+ payload: data_binding.JSONObject,
+ ) -> audit_log_models.ChannelOverwriteEntryInfo:
+ return audit_log_models.ChannelOverwriteEntryInfo(
+ id=snowflake.Snowflake(payload["id"]),
+ type=channel_models.PermissionOverwriteType(payload["type"]),
+ role_name=payload.get("role_name"),
+ )
+
+ @staticmethod
+ def _deserialize_message_pin_entry_info(payload: data_binding.JSONObject) -> audit_log_models.MessagePinEntryInfo:
+ return audit_log_models.MessagePinEntryInfo(
+ channel_id=snowflake.Snowflake(payload["channel_id"]), message_id=snowflake.Snowflake(payload["message_id"])
+ )
+
+ @staticmethod
+ def _deserialize_member_prune_entry_info(payload: data_binding.JSONObject) -> audit_log_models.MemberPruneEntryInfo:
+ return audit_log_models.MemberPruneEntryInfo(
+ delete_member_days=datetime.timedelta(days=int(payload["delete_member_days"])),
+ members_removed=int(payload["members_removed"]),
+ )
+
+ @staticmethod
+ def _deserialize_message_bulk_delete_entry_info(
+ payload: data_binding.JSONObject,
+ ) -> audit_log_models.MessageBulkDeleteEntryInfo:
+ return audit_log_models.MessageBulkDeleteEntryInfo(count=int(payload["count"]))
+
+ @staticmethod
+ def _deserialize_message_delete_entry_info(
+ payload: data_binding.JSONObject,
+ ) -> audit_log_models.MessageDeleteEntryInfo:
+ return audit_log_models.MessageDeleteEntryInfo(
+ channel_id=snowflake.Snowflake(payload["channel_id"]), count=int(payload["count"])
+ )
+
+ @staticmethod
+ def _deserialize_member_disconnect_entry_info(
+ payload: data_binding.JSONObject,
+ ) -> audit_log_models.MemberDisconnectEntryInfo:
+ return audit_log_models.MemberDisconnectEntryInfo(count=int(payload["count"]))
+
+ @staticmethod
+ def _deserialize_member_move_entry_info(payload: data_binding.JSONObject) -> audit_log_models.MemberMoveEntryInfo:
+ return audit_log_models.MemberMoveEntryInfo(
+ channel_id=snowflake.Snowflake(payload["channel_id"]), count=int(payload["count"])
+ )
+
+ @staticmethod
+ def _deserialize_unrecognised_audit_log_entry_info(
+ payload: data_binding.JSONObject,
+ ) -> audit_log_models.UnrecognisedAuditLogEntryInfo:
+ return audit_log_models.UnrecognisedAuditLogEntryInfo(payload)
+
+ def deserialize_audit_log(self, payload: data_binding.JSONObject) -> audit_log_models.AuditLog:
+ entries = {}
+ for entry_payload in payload["audit_log_entries"]:
+ entry_id = snowflake.Snowflake(entry_payload["id"])
+
+ changes = []
+ if (change_payloads := entry_payload.get("changes")) is not None:
+ for change_payload in change_payloads:
+ key: typing.Union[audit_log_models.AuditLogChangeKey, str]
+ try:
+ # noinspection PyArgumentList
+ key = audit_log_models.AuditLogChangeKey(change_payload["key"])
+ except ValueError:
+ key = change_payload["key"]
+
+ new_value: typing.Any = change_payload.get("new_value")
+ old_value: typing.Any = change_payload.get("old_value")
+ if value_converter := self._audit_log_entry_converters.get(key):
+ new_value = value_converter(new_value) if new_value is not None else None
+ old_value = value_converter(old_value) if old_value is not None else None
+
+ changes.append(audit_log_models.AuditLogChange(key=key, new_value=new_value, old_value=old_value))
+
+ target_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_target_id := entry_payload["target_id"]) is not None:
+ target_id = snowflake.Snowflake(raw_target_id)
+
+ user_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_user_id := entry_payload["user_id"]) is not None:
+ user_id = snowflake.Snowflake(raw_user_id)
+
+ action_type: typing.Union[audit_log_models.AuditLogEventType, int]
+ try:
+ # noinspection PyArgumentList
+ action_type = audit_log_models.AuditLogEventType(entry_payload["action_type"])
+ except ValueError:
+ action_type = entry_payload["action_type"]
+
+ options: typing.Optional[audit_log_models.BaseAuditLogEntryInfo] = None
+ if (raw_option := entry_payload.get("options")) is not None:
+ option_converter = (
+ self._audit_log_event_mapping.get(action_type)
+ or self._deserialize_unrecognised_audit_log_entry_info # noqa: W503
+ )
+ options = option_converter(raw_option)
+
+ entries[entry_id] = audit_log_models.AuditLogEntry(
+ app=self._app,
+ id=entry_id,
+ target_id=target_id,
+ changes=changes,
+ user_id=user_id,
+ action_type=action_type,
+ options=options,
+ reason=entry_payload.get("reason"),
+ )
+
+ integrations = {
+ snowflake.Snowflake(integration["id"]): self.deserialize_partial_integration(integration)
+ for integration in payload["integrations"]
+ }
+ users = {snowflake.Snowflake(user["id"]): self.deserialize_user(user) for user in payload["users"]}
+ webhooks = {
+ snowflake.Snowflake(webhook["id"]): self.deserialize_webhook(webhook) for webhook in payload["webhooks"]
+ }
+ return audit_log_models.AuditLog(entries=entries, integrations=integrations, users=users, webhooks=webhooks)
+
+ ##################
+ # CHANNEL MODELS #
+ ##################
+
+ def deserialize_permission_overwrite(self, payload: data_binding.JSONObject) -> channel_models.PermissionOverwrite:
+ # noinspection PyArgumentList
+ return channel_models.PermissionOverwrite(
+ id=snowflake.Snowflake(payload["id"]),
+ type=channel_models.PermissionOverwriteType(payload["type"]),
+ allow=permission_models.Permissions(int(payload["allow_new"])),
+ deny=permission_models.Permissions(int(payload["deny_new"])),
+ )
+
+ def serialize_permission_overwrite(self, overwrite: channel_models.PermissionOverwrite) -> data_binding.JSONObject:
+ # https://github.com/discord/discord-api-docs/pull/1843/commits/470677363ba88fbc1fe79228821146c6d6b488b9
+ # allow and deny can be strings instead now.
+ return {
+ "id": str(overwrite.id),
+ "type": overwrite.type,
+ "allow": str(int(overwrite.allow)),
+ "deny": str(int(overwrite.deny)),
+ }
+
+ def deserialize_partial_channel(self, payload: data_binding.JSONObject) -> channel_models.PartialChannel:
+ return channel_models.PartialChannel(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload.get("name"),
+ type=channel_models.ChannelType(payload["type"]),
+ )
+
+ def deserialize_private_text_channel(self, payload: data_binding.JSONObject) -> channel_models.PrivateTextChannel:
+ last_message_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_last_message_id := payload["last_message_id"]) is not None:
+ last_message_id = snowflake.Snowflake(raw_last_message_id)
+
+ return channel_models.PrivateTextChannel(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload.get("name"),
+ type=channel_models.ChannelType(payload["type"]),
+ last_message_id=last_message_id,
+ recipient=self.deserialize_user(payload["recipients"][0]),
+ )
+
+ def deserialize_private_group_text_channel(
+ self, payload: data_binding.JSONObject
+ ) -> channel_models.GroupPrivateTextChannel:
+ last_message_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_last_message_id := payload["last_message_id"]) is not None:
+ last_message_id = snowflake.Snowflake(raw_last_message_id)
+
+ if (raw_nicks := payload.get("nicks")) is not None:
+ nicknames = {snowflake.Snowflake(entry["id"]): entry["nick"] for entry in raw_nicks}
+ else:
+ nicknames = {}
+
+ recipients = {snowflake.Snowflake(user["id"]): self.deserialize_user(user) for user in payload["recipients"]}
+
+ return channel_models.GroupPrivateTextChannel(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload.get("name"),
+ type=channel_models.ChannelType(payload["type"]),
+ last_message_id=last_message_id,
+ owner_id=snowflake.Snowflake(payload["owner_id"]),
+ icon_hash=payload["icon"],
+ nicknames=nicknames,
+ application_id=snowflake.Snowflake(payload["application_id"]) if "application_id" in payload else None,
+ recipients=recipients,
+ )
+
+ def _set_guild_channel_attributes(
+ self, payload: data_binding.JSONObject, *, guild_id: undefined.UndefinedOr[snowflake.Snowflake],
+ ) -> _GuildChannelFields:
+ if guild_id is undefined.UNDEFINED:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+
+ permission_overwrites = {
+ snowflake.Snowflake(overwrite["id"]): self.deserialize_permission_overwrite(overwrite)
+ for overwrite in payload["permission_overwrites"]
+ } # TODO: while snowflakes are guaranteed to be unique within their own resource, there is no guarantee for
+ # across between resources (user and role in this case); while in practice we will not get overlap there is a
+ # chance that this may happen in the future, would it be more sensible to use a Sequence here?
+
+ parent_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_parent_id := payload.get("parent_id")) is not None:
+ parent_id = snowflake.Snowflake(raw_parent_id)
+
+ return _GuildChannelFields(
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload.get("name"),
+ type=channel_models.ChannelType(payload["type"]),
+ guild_id=guild_id,
+ position=int(payload["position"]),
+ permission_overwrites=permission_overwrites,
+ is_nsfw=payload.get("nsfw"),
+ parent_id=parent_id,
+ )
+
+ def deserialize_guild_category(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> channel_models.GuildCategory:
+ channel_fields = self._set_guild_channel_attributes(payload, guild_id=guild_id)
+ return channel_models.GuildCategory(
+ app=self._app,
+ id=channel_fields.id,
+ name=channel_fields.name,
+ type=channel_fields.type,
+ guild_id=channel_fields.guild_id,
+ position=channel_fields.position,
+ permission_overwrites=channel_fields.permission_overwrites,
+ is_nsfw=channel_fields.is_nsfw,
+ parent_id=channel_fields.parent_id,
+ )
+
+ def deserialize_guild_text_channel(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> channel_models.GuildTextChannel:
+ channel_fields = self._set_guild_channel_attributes(payload, guild_id=guild_id)
+
+ last_message_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_last_message_id := payload["last_message_id"]) is not None:
+ last_message_id = snowflake.Snowflake(raw_last_message_id)
+
+ last_pin_timestamp: typing.Optional[datetime.datetime] = None
+ if (raw_last_pin_timestamp := payload.get("last_pin_timestamp")) is not None:
+ last_pin_timestamp = date.iso8601_datetime_string_to_datetime(raw_last_pin_timestamp)
+
+ return channel_models.GuildTextChannel(
+ app=self._app,
+ id=channel_fields.id,
+ name=channel_fields.name,
+ type=channel_fields.type,
+ guild_id=channel_fields.guild_id,
+ position=channel_fields.position,
+ permission_overwrites=channel_fields.permission_overwrites,
+ is_nsfw=channel_fields.is_nsfw,
+ parent_id=channel_fields.parent_id,
+ topic=payload["topic"],
+ last_message_id=last_message_id,
+ # Usually this is 0 if unset, but some old channels made before the
+ # rate_limit_per_user field was implemented will not have this field
+ # at all if they have never had the rate limit changed...
+ rate_limit_per_user=datetime.timedelta(seconds=payload.get("rate_limit_per_user", 0)),
+ last_pin_timestamp=last_pin_timestamp,
+ )
+
+ def deserialize_guild_news_channel(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> channel_models.GuildNewsChannel:
+ channel_fields = self._set_guild_channel_attributes(payload, guild_id=guild_id)
+
+ last_message_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_last_message_id := payload["last_message_id"]) is not None:
+ last_message_id = snowflake.Snowflake(raw_last_message_id)
+
+ last_pin_timestamp: typing.Optional[datetime.datetime] = None
+ if (raw_last_pin_timestamp := payload.get("last_pin_timestamp")) is not None:
+ last_pin_timestamp = date.iso8601_datetime_string_to_datetime(raw_last_pin_timestamp)
+
+ return channel_models.GuildNewsChannel(
+ app=self._app,
+ id=channel_fields.id,
+ name=channel_fields.name,
+ type=channel_fields.type,
+ guild_id=channel_fields.guild_id,
+ position=channel_fields.position,
+ permission_overwrites=channel_fields.permission_overwrites,
+ is_nsfw=channel_fields.is_nsfw,
+ parent_id=channel_fields.parent_id,
+ topic=payload["topic"],
+ last_message_id=last_message_id,
+ last_pin_timestamp=last_pin_timestamp,
+ )
+
+ def deserialize_guild_store_channel(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> channel_models.GuildStoreChannel:
+ channel_fields = self._set_guild_channel_attributes(payload, guild_id=guild_id)
+ return channel_models.GuildStoreChannel(
+ app=self._app,
+ id=channel_fields.id,
+ name=channel_fields.name,
+ type=channel_fields.type,
+ guild_id=channel_fields.guild_id,
+ position=channel_fields.position,
+ permission_overwrites=channel_fields.permission_overwrites,
+ is_nsfw=channel_fields.is_nsfw,
+ parent_id=channel_fields.parent_id,
+ )
+
+ def deserialize_guild_voice_channel(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> channel_models.GuildVoiceChannel:
+ channel_fields = self._set_guild_channel_attributes(payload, guild_id=guild_id)
+ return channel_models.GuildVoiceChannel(
+ app=self._app,
+ id=channel_fields.id,
+ name=channel_fields.name,
+ type=channel_fields.type,
+ guild_id=channel_fields.guild_id,
+ position=channel_fields.position,
+ permission_overwrites=channel_fields.permission_overwrites,
+ is_nsfw=channel_fields.is_nsfw,
+ parent_id=channel_fields.parent_id,
+ bitrate=int(payload["bitrate"]),
+ user_limit=int(payload["user_limit"]),
+ )
+
+ def deserialize_channel(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> channel_models.PartialChannel:
+ channel_type = payload["type"]
+ if channel_model := self._guild_channel_type_mapping.get(channel_type):
+ # noinspection PyArgumentList
+ return channel_model(payload, guild_id=guild_id)
+
+ # noinspection PyArgumentList
+ return self._dm_channel_type_mapping[channel_type](payload)
+
+ ################
+ # EMBED MODELS #
+ ################
+
+ def deserialize_embed(self, payload: data_binding.JSONObject) -> embed_models.Embed:
+ # Keep these separate to aid debugging later.
+ title = payload.get("title")
+ description = payload.get("description")
+ url = payload.get("url")
+ color = color_models.Color(payload["color"]) if "color" in payload else None
+ timestamp = date.iso8601_datetime_string_to_datetime(payload["timestamp"]) if "timestamp" in payload else None
+ fields: typing.Optional[typing.MutableSequence[embed_models.EmbedField]] = None
+
+ image: typing.Optional[embed_models.EmbedImage[files.AsyncReader]] = None
+ if image_payload := payload.get("image"):
+ image = embed_models.EmbedImage(
+ resource=files.ensure_resource(image_payload.get("url")),
+ proxy_resource=files.ensure_resource(image_payload.get("proxy_url")),
+ height=image_payload.get("height"),
+ width=image_payload.get("width"),
+ )
+
+ thumbnail: typing.Optional[embed_models.EmbedImage[files.AsyncReader]] = None
+ if thumbnail_payload := payload.get("thumbnail"):
+ thumbnail = embed_models.EmbedImage(
+ resource=files.ensure_resource(thumbnail_payload.get("url")),
+ proxy_resource=files.ensure_resource(thumbnail_payload.get("proxy_url")),
+ height=thumbnail_payload.get("height"),
+ width=thumbnail_payload.get("width"),
+ )
+
+ video: typing.Optional[embed_models.EmbedVideo[files.AsyncReader]] = None
+ if video_payload := payload.get("video"):
+ video = embed_models.EmbedVideo(
+ resource=files.ensure_resource(video_payload.get("url")),
+ height=video_payload.get("height"),
+ width=video_payload.get("width"),
+ )
+
+ provider: typing.Optional[embed_models.EmbedProvider] = None
+ if provider_payload := payload.get("provider"):
+ provider = embed_models.EmbedProvider(name=provider_payload.get("name"), url=provider_payload.get("url"))
+
+ icon: typing.Optional[embed_models.EmbedResourceWithProxy[files.AsyncReader]]
+ author: typing.Optional[embed_models.EmbedAuthor] = None
+ if author_payload := payload.get("author"):
+ icon = None
+ if "icon_url" in author_payload:
+ icon = embed_models.EmbedResourceWithProxy(
+ resource=files.ensure_resource(author_payload.get("icon_url")),
+ proxy_resource=files.ensure_resource(author_payload.get("proxy_icon_url")),
+ )
+
+ author = embed_models.EmbedAuthor(
+ name=author_payload.get("name"), url=author_payload.get("url"), icon=icon,
+ )
+
+ footer: typing.Optional[embed_models.EmbedFooter] = None
+ if footer_payload := payload.get("footer"):
+ icon = None
+ if "icon_url" in footer_payload:
+ icon = embed_models.EmbedResourceWithProxy(
+ resource=files.ensure_resource(footer_payload.get("icon_url")),
+ proxy_resource=files.ensure_resource(footer_payload.get("proxy_icon_url")),
+ )
+
+ footer = embed_models.EmbedFooter(text=footer_payload.get("text"), icon=icon)
+
+ if fields_array := payload.get("fields"):
+ fields = []
+ for field_payload in fields_array:
+ field = embed_models.EmbedField(
+ name=field_payload["name"], value=field_payload["value"], inline=field_payload.get("inline", False),
+ )
+ fields.append(field)
+
+ return embed_models.Embed.from_received_embed(
+ title=title,
+ description=description,
+ url=url,
+ color=color,
+ timestamp=timestamp,
+ image=image,
+ thumbnail=thumbnail,
+ video=video,
+ provider=provider,
+ author=author,
+ footer=footer,
+ fields=fields,
+ )
+
+ def serialize_embed( # noqa: C901
+ self, embed: embed_models.Embed,
+ ) -> typing.Tuple[data_binding.JSONObject, typing.List[files.Resource[files.AsyncReader]]]:
+
+ payload: data_binding.JSONObject = {}
+ uploads: typing.List[files.Resource[files.AsyncReader]] = []
+
+ if embed.title is not None:
+ payload["title"] = embed.title
+
+ if embed.description is not None:
+ payload["description"] = embed.description
+
+ if embed.url is not None:
+ payload["url"] = embed.url
+
+ if embed.timestamp is not None:
+ payload["timestamp"] = embed.timestamp.isoformat()
+
+ if embed.color is not None:
+ payload["color"] = int(embed.color)
+
+ if embed.footer is not None:
+ footer_payload: data_binding.JSONObject = {}
+
+ if embed.footer.text is not None:
+ footer_payload["text"] = embed.footer.text
+
+ if embed.footer.icon is not None:
+ if not isinstance(embed.footer.icon.resource, files.WebResource):
+ uploads.append(embed.footer.icon.resource)
+
+ footer_payload["icon_url"] = embed.footer.icon.url
+
+ payload["footer"] = footer_payload
+
+ if embed.image is not None:
+ image_payload: data_binding.JSONObject = {}
+
+ if not isinstance(embed.image.resource, files.WebResource):
+ uploads.append(embed.image.resource)
+
+ image_payload["url"] = embed.image.url
+ payload["image"] = image_payload
+
+ if embed.thumbnail is not None:
+ thumbnail_payload: data_binding.JSONObject = {}
+
+ if not isinstance(embed.thumbnail.resource, files.WebResource):
+ uploads.append(embed.thumbnail.resource)
+
+ thumbnail_payload["url"] = embed.thumbnail.url
+ payload["thumbnail"] = thumbnail_payload
+
+ if embed.author is not None:
+ author_payload: data_binding.JSONObject = {}
+
+ if embed.author.name is not None:
+ author_payload["name"] = embed.author.name
+
+ if embed.author.url is not None:
+ author_payload["url"] = embed.author.url
+
+ if embed.author.icon is not None:
+ if not isinstance(embed.author.icon.resource, files.WebResource):
+ uploads.append(embed.author.icon.resource)
+ author_payload["icon_url"] = embed.author.icon.url
+
+ payload["author"] = author_payload
+
+ if embed.fields:
+ field_payloads: data_binding.JSONArray = []
+ for i, field in enumerate(embed.fields):
+
+ # Yep, this is technically two unreachable branches. However, this is an incredibly
+ # common mistake to make when working with embeds and not using a static type
+ # checker, so I have added these as additional safeguards for UX and ease
+ # of debugging. The case that there are `None` should be detected immediately by
+ # static type checkers, regardless.
+
+ name = str(field.name) if field.name is not None else None # type: ignore[unreachable]
+ value = str(field.value) if field.value is not None else None # type: ignore[unreachable]
+
+ if name is None:
+ raise TypeError(f"in embed.fields[{i}].name - cannot have `None`")
+ if not name:
+ raise TypeError(f"in embed.fields[{i}].name - cannot have empty string")
+ if not name.strip():
+ raise TypeError(f"in embed.fields[{i}].name - cannot have only whitespace")
+
+ if value is None:
+ raise TypeError(f"in embed.fields[{i}].value - cannot have `None`")
+ if not value:
+ raise TypeError(f"in embed.fields[{i}].value - cannot have empty string")
+ if not value.strip():
+ raise TypeError(f"in embed.fields[{i}].value - cannot have only whitespace")
+
+ # Name and value always have to be specified; we can always
+ # send a default `inline` value also just to keep this simpler.
+ field_payloads.append({"name": name, "value": value, "inline": field.is_inline})
+ payload["fields"] = field_payloads
+
+ return payload, uploads
+
+ ################
+ # EMOJI MODELS #
+ ################
+
+ def deserialize_unicode_emoji(self, payload: data_binding.JSONObject) -> emoji_models.UnicodeEmoji:
+ return emoji_models.UnicodeEmoji(name=payload["name"])
+
+ def deserialize_custom_emoji(self, payload: data_binding.JSONObject) -> emoji_models.CustomEmoji:
+ return emoji_models.CustomEmoji(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload["name"],
+ is_animated=payload.get("animated", False),
+ )
+
+ def deserialize_known_custom_emoji(
+ self, payload: data_binding.JSONObject, *, guild_id: snowflake.Snowflake
+ ) -> emoji_models.KnownCustomEmoji:
+ role_ids = [snowflake.Snowflake(role_id) for role_id in payload["roles"]] if "roles" in payload else []
+
+ user: typing.Optional[user_models.User] = None
+ if (raw_user := payload.get("user")) is not None:
+ user = self.deserialize_user(raw_user)
+
+ return emoji_models.KnownCustomEmoji(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ name=payload["name"],
+ is_animated=payload.get("animated", False),
+ guild_id=guild_id,
+ role_ids=role_ids,
+ user=user,
+ is_colons_required=payload["require_colons"],
+ is_managed=payload["managed"],
+ is_available=payload["available"],
+ )
+
+ def deserialize_emoji(
+ self, payload: data_binding.JSONObject
+ ) -> typing.Union[emoji_models.UnicodeEmoji, emoji_models.CustomEmoji]:
+ if payload.get("id") is not None:
+ return self.deserialize_custom_emoji(payload)
+
+ return self.deserialize_unicode_emoji(payload)
+
+ ##################
+ # GATEWAY MODELS #
+ ##################
+
+ def deserialize_gateway_bot(self, payload: data_binding.JSONObject) -> gateway_models.GatewayBot:
+ session_start_limit_payload = payload["session_start_limit"]
+ session_start_limit = gateway_models.SessionStartLimit(
+ total=int(session_start_limit_payload["total"]),
+ remaining=int(session_start_limit_payload["remaining"]),
+ reset_after=datetime.timedelta(milliseconds=session_start_limit_payload["reset_after"]),
+ # I do not trust that this may never be zero for some unknown reason. If it was 0, it
+ # would hang the application on start up, so I enforce it is at least 1.
+ max_concurrency=max(session_start_limit_payload.get("max_concurrency", 0), 1),
+ )
+ return gateway_models.GatewayBot(
+ url=payload["url"], shard_count=int(payload["shards"]), session_start_limit=session_start_limit,
+ )
+
+ ################
+ # GUILD MODELS #
+ ################
+
+ def deserialize_guild_widget(self, payload: data_binding.JSONObject) -> guild_models.GuildWidget:
+ channel_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_channel_id := payload["channel_id"]) is not None:
+ channel_id = snowflake.Snowflake(raw_channel_id)
+
+ return guild_models.GuildWidget(app=self._app, channel_id=channel_id, is_enabled=payload["enabled"])
+
+ def deserialize_member(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ user: undefined.UndefinedOr[user_models.User] = undefined.UNDEFINED,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> guild_models.Member:
+ if user is undefined.UNDEFINED:
+ user = self.deserialize_user(payload["user"])
+
+ if guild_id is undefined.UNDEFINED:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+
+ role_ids = [snowflake.Snowflake(role_id) for role_id in payload["roles"]]
+
+ joined_at = date.iso8601_datetime_string_to_datetime(payload["joined_at"])
+
+ premium_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED
+ if "premium_since" in payload:
+ raw_premium_since = payload["premium_since"]
+ premium_since = (
+ date.iso8601_datetime_string_to_datetime(raw_premium_since) if raw_premium_since is not None else None
+ )
+
+ return guild_models.Member(
+ user=user,
+ guild_id=guild_id,
+ role_ids=role_ids,
+ joined_at=joined_at,
+ nickname=payload["nick"] if "nick" in payload else undefined.UNDEFINED,
+ premium_since=premium_since,
+ is_deaf=payload["deaf"] if "deaf" in payload else undefined.UNDEFINED,
+ is_mute=payload["mute"] if "mute" in payload else undefined.UNDEFINED,
+ )
+
+ def deserialize_role(
+ self, payload: data_binding.JSONObject, *, guild_id: snowflake.Snowflake,
+ ) -> guild_models.Role:
+ return guild_models.Role(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ guild_id=guild_id,
+ name=payload["name"],
+ color=color_models.Color(payload["color"]),
+ is_hoisted=payload["hoist"],
+ position=int(payload["position"]),
+ # https://github.com/discord/discord-api-docs/pull/1843/commits/470677363ba88fbc1fe79228821146c6d6b488b9
+ permissions=permission_models.Permissions(int(payload["permissions_new"])),
+ is_managed=payload["managed"],
+ is_mentionable=payload["mentionable"],
+ )
+
+ @staticmethod
+ def _set_partial_integration_attributes(payload: data_binding.JSONObject) -> _IntegrationFields:
+ account_payload = payload["account"]
+ account = guild_models.IntegrationAccount(id=account_payload["id"], name=account_payload["name"])
+ return _IntegrationFields(
+ id=snowflake.Snowflake(payload["id"]), name=payload["name"], type=payload["type"], account=account,
+ )
+
+ def deserialize_partial_integration(self, payload: data_binding.JSONObject) -> guild_models.PartialIntegration:
+ integration_fields = self._set_partial_integration_attributes(payload)
+ return guild_models.PartialIntegration(
+ id=integration_fields.id,
+ name=integration_fields.name,
+ type=integration_fields.type,
+ account=integration_fields.account,
+ )
+
+ def deserialize_integration(self, payload: data_binding.JSONObject) -> guild_models.Integration:
+ integration_fields = self._set_partial_integration_attributes(payload)
+
+ role_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_role_id := payload.get("role_id")) is not None:
+ role_id = snowflake.Snowflake(raw_role_id)
+
+ last_synced_at: typing.Optional[datetime.datetime] = None
+ if (raw_last_synced_at := payload.get("synced_at")) is not None:
+ last_synced_at = date.iso8601_datetime_string_to_datetime(raw_last_synced_at)
+
+ return guild_models.Integration(
+ id=integration_fields.id,
+ name=integration_fields.name,
+ type=integration_fields.type,
+ account=integration_fields.account,
+ is_enabled=payload["enabled"],
+ is_syncing=payload["syncing"],
+ role_id=role_id,
+ is_emojis_enabled=payload.get("enable_emoticons"),
+ expire_behavior=guild_models.IntegrationExpireBehaviour(payload["expire_behavior"]),
+ expire_grace_period=datetime.timedelta(days=payload["expire_grace_period"]),
+ user=self.deserialize_user(payload["user"]),
+ last_synced_at=last_synced_at,
+ )
+
+ def deserialize_guild_member_ban(self, payload: data_binding.JSONObject) -> guild_models.GuildMemberBan:
+ return guild_models.GuildMemberBan(reason=payload["reason"], user=self.deserialize_user(payload["user"]))
+
+ def deserialize_unavailable_guild(self, payload: data_binding.JSONObject) -> guild_models.UnavailableGuild:
+ return guild_models.UnavailableGuild(id=snowflake.Snowflake(payload["id"]))
+
+ @staticmethod
+ def _set_partial_guild_attributes(payload: data_binding.JSONObject) -> _PartialGuildFields:
+ features = []
+ for feature in payload["features"]:
+ try:
+ # noinspection PyArgumentList
+ features.append(guild_models.GuildFeature(feature))
+ except ValueError:
+ features.append(feature)
+
+ return _PartialGuildFields(
+ id=snowflake.Snowflake(payload["id"]), name=payload["name"], icon_hash=payload["icon"], features=features,
+ )
+
+ def deserialize_guild_preview(self, payload: data_binding.JSONObject) -> guild_models.GuildPreview:
+ guild_fields = self._set_partial_guild_attributes(payload)
+ emojis = {
+ snowflake.Snowflake(emoji["id"]): self.deserialize_known_custom_emoji(emoji, guild_id=guild_fields.id)
+ for emoji in payload["emojis"]
+ }
+ return guild_models.GuildPreview(
+ app=self._app,
+ id=guild_fields.id,
+ name=guild_fields.name,
+ icon_hash=guild_fields.icon_hash,
+ features=guild_fields.features,
+ splash_hash=payload["splash"],
+ discovery_splash_hash=payload["discovery_splash"],
+ emojis=emojis,
+ approximate_presence_count=int(payload["approximate_presence_count"]),
+ approximate_member_count=int(payload["approximate_member_count"]),
+ description=payload["description"],
+ )
+
+ def _set_guild_attributes(self, payload: data_binding.JSONObject) -> _GuildFields:
+ guild_fields = self._set_partial_guild_attributes(payload)
+ afk_channel_id = payload["afk_channel_id"]
+ default_message_notifications = guild_models.GuildMessageNotificationsLevel(
+ payload["default_message_notifications"]
+ )
+ application_id = payload["application_id"]
+ widget_channel_id = payload.get("widget_channel_id")
+ system_channel_id = payload["system_channel_id"]
+ rules_channel_id = payload["rules_channel_id"]
+ max_presences = payload.get("max_presences")
+ max_video_channel_users = (
+ int(payload["max_video_channel_users"]) if "max_video_channel_users" in payload else None
+ )
+ public_updates_channel_id = payload["public_updates_channel_id"]
+ public_updates_channel_id = (
+ snowflake.Snowflake(public_updates_channel_id) if public_updates_channel_id is not None else None
+ )
+ return _GuildFields(
+ id=guild_fields.id,
+ name=guild_fields.name,
+ icon_hash=guild_fields.icon_hash,
+ features=guild_fields.features,
+ splash_hash=payload["splash"],
+ discovery_splash_hash=payload["discovery_splash"],
+ owner_id=snowflake.Snowflake(payload["owner_id"]),
+ region=payload["region"],
+ afk_channel_id=snowflake.Snowflake(afk_channel_id) if afk_channel_id is not None else None,
+ afk_timeout=datetime.timedelta(seconds=payload["afk_timeout"]),
+ verification_level=guild_models.GuildVerificationLevel(payload["verification_level"]),
+ default_message_notifications=default_message_notifications,
+ explicit_content_filter=guild_models.GuildExplicitContentFilterLevel(payload["explicit_content_filter"]),
+ mfa_level=guild_models.GuildMFALevel(payload["mfa_level"]),
+ application_id=snowflake.Snowflake(application_id) if application_id is not None else None,
+ widget_channel_id=snowflake.Snowflake(widget_channel_id) if widget_channel_id is not None else None,
+ system_channel_id=snowflake.Snowflake(system_channel_id) if system_channel_id is not None else None,
+ is_widget_enabled=payload["widget_enabled"] if "widget_enabled" in payload else None,
+ system_channel_flags=guild_models.GuildSystemChannelFlag(payload["system_channel_flags"]),
+ rules_channel_id=snowflake.Snowflake(rules_channel_id) if rules_channel_id is not None else None,
+ max_presences=int(max_presences) if max_presences is not None else None,
+ max_members=int(payload["max_members"]) if "max_members" in payload else None,
+ max_video_channel_users=max_video_channel_users,
+ vanity_url_code=payload["vanity_url_code"],
+ description=payload["description"],
+ banner_hash=payload["banner"],
+ premium_tier=guild_models.GuildPremiumTier(payload["premium_tier"]),
+ premium_subscription_count=payload.get("premium_subscription_count"),
+ preferred_locale=payload["preferred_locale"],
+ public_updates_channel_id=public_updates_channel_id,
+ )
+
+ def deserialize_rest_guild(self, payload: data_binding.JSONObject) -> guild_models.RESTGuild:
+ guild_fields = self._set_guild_attributes(payload)
+ approximate_member_count = (
+ int(payload["approximate_member_count"]) if "approximate_member_count" in payload else None
+ )
+ approximate_active_member_count = (
+ int(payload["approximate_presence_count"]) if "approximate_presence_count" in payload else None
+ )
+
+ roles = {
+ snowflake.Snowflake(role["id"]): self.deserialize_role(role, guild_id=guild_fields.id)
+ for role in payload["roles"]
+ }
+ emojis = {
+ snowflake.Snowflake(emoji["id"]): self.deserialize_known_custom_emoji(emoji, guild_id=guild_fields.id)
+ for emoji in payload["emojis"]
+ }
+ guild = guild_models.RESTGuild(
+ app=self._app,
+ id=guild_fields.id,
+ name=guild_fields.name,
+ icon_hash=guild_fields.icon_hash,
+ features=guild_fields.features,
+ splash_hash=guild_fields.splash_hash,
+ discovery_splash_hash=guild_fields.discovery_splash_hash,
+ owner_id=guild_fields.owner_id,
+ region=guild_fields.region,
+ afk_channel_id=guild_fields.afk_channel_id,
+ afk_timeout=guild_fields.afk_timeout,
+ verification_level=guild_fields.verification_level,
+ default_message_notifications=guild_fields.default_message_notifications,
+ explicit_content_filter=guild_fields.explicit_content_filter,
+ mfa_level=guild_fields.mfa_level,
+ application_id=guild_fields.application_id,
+ widget_channel_id=guild_fields.widget_channel_id,
+ system_channel_id=guild_fields.system_channel_id,
+ is_widget_enabled=guild_fields.is_widget_enabled,
+ system_channel_flags=guild_fields.system_channel_flags,
+ rules_channel_id=guild_fields.rules_channel_id,
+ max_presences=guild_fields.max_presences,
+ max_members=guild_fields.max_members,
+ max_video_channel_users=guild_fields.max_video_channel_users,
+ vanity_url_code=guild_fields.vanity_url_code,
+ description=guild_fields.description,
+ banner_hash=guild_fields.banner_hash,
+ premium_tier=guild_fields.premium_tier,
+ premium_subscription_count=guild_fields.premium_subscription_count,
+ preferred_locale=guild_fields.preferred_locale,
+ public_updates_channel_id=guild_fields.public_updates_channel_id,
+ approximate_member_count=approximate_member_count,
+ approximate_active_member_count=approximate_active_member_count,
+ roles=roles,
+ emojis=emojis,
+ )
+ return guild
+
+ def deserialize_gateway_guild(self, payload: data_binding.JSONObject) -> entity_factory.GatewayGuildDefinition:
+ guild_fields = self._set_guild_attributes(payload)
+ my_permissions = permission_models.Permissions(payload["permissions"]) if "permissions" in payload else None
+ is_large = payload["large"] if "large" in payload else None
+ joined_at = date.iso8601_datetime_string_to_datetime(payload["joined_at"]) if "joined_at" in payload else None
+ member_count = int(payload["member_count"]) if "member_count" in payload else None
+
+ guild = guild_models.GatewayGuild(
+ app=self._app,
+ id=guild_fields.id,
+ name=guild_fields.name,
+ icon_hash=guild_fields.icon_hash,
+ features=guild_fields.features,
+ splash_hash=guild_fields.splash_hash,
+ discovery_splash_hash=guild_fields.discovery_splash_hash,
+ owner_id=guild_fields.owner_id,
+ region=guild_fields.region,
+ afk_channel_id=guild_fields.afk_channel_id,
+ afk_timeout=guild_fields.afk_timeout,
+ verification_level=guild_fields.verification_level,
+ default_message_notifications=guild_fields.default_message_notifications,
+ explicit_content_filter=guild_fields.explicit_content_filter,
+ mfa_level=guild_fields.mfa_level,
+ application_id=guild_fields.application_id,
+ widget_channel_id=guild_fields.widget_channel_id,
+ system_channel_id=guild_fields.system_channel_id,
+ is_widget_enabled=guild_fields.is_widget_enabled,
+ system_channel_flags=guild_fields.system_channel_flags,
+ rules_channel_id=guild_fields.rules_channel_id,
+ max_presences=guild_fields.max_presences,
+ max_members=guild_fields.max_members,
+ max_video_channel_users=guild_fields.max_video_channel_users,
+ vanity_url_code=guild_fields.vanity_url_code,
+ description=guild_fields.description,
+ banner_hash=guild_fields.banner_hash,
+ premium_tier=guild_fields.premium_tier,
+ premium_subscription_count=guild_fields.premium_subscription_count,
+ preferred_locale=guild_fields.preferred_locale,
+ public_updates_channel_id=guild_fields.public_updates_channel_id,
+ my_permissions=my_permissions,
+ is_large=is_large,
+ joined_at=joined_at,
+ member_count=member_count,
+ )
+
+ members: typing.Optional[typing.MutableMapping[snowflake.Snowflake, guild_models.Member]] = None
+ if "members" in payload:
+ members = {}
+
+ for member_payload in payload["members"]:
+ member = self.deserialize_member(member_payload, guild_id=guild.id)
+ members[member.user.id] = member
+
+ channels: typing.Optional[typing.MutableMapping[snowflake.Snowflake, channel_models.GuildChannel]] = None
+ if "channels" in payload:
+ channels = {}
+
+ for channel_payload in payload["channels"]:
+ channel = typing.cast(
+ "channel_models.GuildChannel", self.deserialize_channel(channel_payload, guild_id=guild.id)
+ )
+ channels[channel.id] = channel
+
+ presences: typing.Optional[typing.MutableMapping[snowflake.Snowflake, presence_models.MemberPresence]] = None
+ if "presences" in payload:
+ presences = {}
+
+ for presence_payload in payload["presences"]:
+ presence = self.deserialize_member_presence(presence_payload, guild_id=guild.id)
+ presences[presence.user_id] = presence
+
+ voice_states: typing.Optional[typing.MutableMapping[snowflake.Snowflake, voice_models.VoiceState]] = None
+ if "voice_states" in payload:
+ voice_states = {}
+ assert members is not None
+
+ for voice_state_payload in payload["voice_states"]:
+ member = members[snowflake.Snowflake(voice_state_payload["user_id"])]
+ voice_state = self.deserialize_voice_state(voice_state_payload, guild_id=guild.id, member=member)
+ voice_states[voice_state.user_id] = voice_state
+
+ roles = {
+ snowflake.Snowflake(role["id"]): self.deserialize_role(role, guild_id=guild.id) for role in payload["roles"]
+ }
+ emojis = {
+ snowflake.Snowflake(emoji["id"]): self.deserialize_known_custom_emoji(emoji, guild_id=guild.id)
+ for emoji in payload["emojis"]
+ }
+
+ return entity_factory.GatewayGuildDefinition(guild, channels, members, presences, roles, emojis, voice_states)
+
+ #################
+ # INVITE MODELS #
+ #################
+
+ def deserialize_vanity_url(self, payload: data_binding.JSONObject) -> invite_models.VanityURL:
+ return invite_models.VanityURL(app=self._app, code=payload["code"], uses=int(payload["uses"]))
+
+ def _set_invite_attributes(self, payload: data_binding.JSONObject) -> _InviteFields:
+ guild: typing.Optional[invite_models.InviteGuild] = None
+ guild_id: typing.Optional[snowflake.Snowflake] = None
+ if "guild" in payload:
+ guild_payload = payload["guild"]
+ guild_fields = self._set_partial_guild_attributes(guild_payload)
+ guild = invite_models.InviteGuild(
+ app=self._app,
+ id=guild_fields.id,
+ name=guild_fields.name,
+ features=guild_fields.features,
+ icon_hash=guild_fields.icon_hash,
+ splash_hash=guild_payload["splash"],
+ banner_hash=guild_payload["banner"],
+ description=guild_payload["description"],
+ verification_level=guild_models.GuildVerificationLevel(guild_payload["verification_level"]),
+ vanity_url_code=guild_payload["vanity_url_code"],
+ )
+ guild_id = guild.id
+ elif "guild_id" in payload:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+
+ channel: typing.Optional[channel_models.PartialChannel] = None
+ if (raw_channel := payload.get("channel")) is not None:
+ channel = self.deserialize_partial_channel(raw_channel)
+ channel_id = channel.id
+ else:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+
+ # noinspection PyArgumentList
+ target_user_type = (
+ invite_models.TargetUserType(payload["target_user_type"]) if "target_user_type" in payload else None
+ )
+ approximate_presence_count = (
+ int(payload["approximate_presence_count"]) if "approximate_presence_count" in payload else None
+ )
+ approximate_member_count = (
+ int(payload["approximate_member_count"]) if "approximate_member_count" in payload else None
+ )
+ return _InviteFields(
+ code=payload["code"],
+ guild=guild,
+ guild_id=guild_id,
+ channel=channel,
+ channel_id=channel_id,
+ inviter=self.deserialize_user(payload["inviter"]) if "inviter" in payload else None,
+ target_user=self.deserialize_user(payload["target_user"]) if "target_user" in payload else None,
+ target_user_type=target_user_type,
+ approximate_presence_count=approximate_presence_count,
+ approximate_member_count=approximate_member_count,
+ )
+
+ def deserialize_invite(self, payload: data_binding.JSONObject) -> invite_models.Invite:
+ invite_fields = self._set_invite_attributes(payload)
+ return invite_models.Invite(
+ app=self._app,
+ code=invite_fields.code,
+ guild=invite_fields.guild,
+ guild_id=invite_fields.guild_id,
+ channel=invite_fields.channel,
+ channel_id=invite_fields.channel_id,
+ inviter=invite_fields.inviter,
+ target_user=invite_fields.target_user,
+ target_user_type=invite_fields.target_user_type,
+ approximate_member_count=invite_fields.approximate_member_count,
+ approximate_presence_count=invite_fields.approximate_presence_count,
+ )
+
+ def deserialize_invite_with_metadata(self, payload: data_binding.JSONObject) -> invite_models.InviteWithMetadata:
+ invite_fields = self._set_invite_attributes(payload)
+ max_age = payload["max_age"]
+ return invite_models.InviteWithMetadata(
+ app=self._app,
+ code=invite_fields.code,
+ guild=invite_fields.guild,
+ guild_id=invite_fields.guild_id,
+ channel=invite_fields.channel,
+ channel_id=invite_fields.channel_id,
+ inviter=invite_fields.inviter,
+ target_user=invite_fields.target_user,
+ target_user_type=invite_fields.target_user_type,
+ approximate_member_count=invite_fields.approximate_member_count,
+ approximate_presence_count=invite_fields.approximate_presence_count,
+ uses=int(payload["uses"]),
+ max_uses=int(payload["max_uses"]),
+ max_age=datetime.timedelta(seconds=max_age) if max_age > 0 else None,
+ is_temporary=payload["temporary"],
+ created_at=date.iso8601_datetime_string_to_datetime(payload["created_at"]),
+ )
+
+ ##################
+ # MESSAGE MODELS #
+ ##################
+
+ def deserialize_partial_message(self, payload: data_binding.JSONObject) -> message_models.PartialMessage:
+ author: undefined.UndefinedOr[user_models.User] = undefined.UNDEFINED
+ if "author" in payload:
+ author = self.deserialize_user(payload["author"])
+
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED
+ if "guild_id" in payload:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+
+ member: undefined.UndefinedOr[guild_models.Member] = undefined.UNDEFINED
+ if "member" in payload:
+ assert author is not undefined.UNDEFINED
+ assert guild_id is not undefined.UNDEFINED
+ member = self.deserialize_member(payload["member"], user=author, guild_id=guild_id)
+
+ timestamp: undefined.UndefinedOr[datetime.datetime] = undefined.UNDEFINED
+ if "timestamp" in payload:
+ timestamp = date.iso8601_datetime_string_to_datetime(payload["timestamp"])
+
+ edited_timestamp: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED
+ if "edited_timestamp" in payload:
+ if (raw_edited_timestamp := payload["edited_timestamp"]) is not None:
+ edited_timestamp = date.iso8601_datetime_string_to_datetime(raw_edited_timestamp)
+ else:
+ edited_timestamp = None
+
+ is_mentioning_everyone = payload["mention_everyone"] if "mention_everyone" in payload else undefined.UNDEFINED
+
+ user_mentions: undefined.UndefinedOr[typing.Sequence[snowflake.Snowflake]] = undefined.UNDEFINED
+ if "mentions" in payload:
+ user_mentions = [snowflake.Snowflake(mention["id"]) for mention in payload["mentions"]]
+
+ role_mentions: undefined.UndefinedOr[typing.Sequence[snowflake.Snowflake]] = undefined.UNDEFINED
+ if "mention_roles" in payload:
+ role_mentions = [snowflake.Snowflake(mention) for mention in payload["mention_roles"]]
+
+ channel_mentions: undefined.UndefinedOr[typing.Sequence[snowflake.Snowflake]] = undefined.UNDEFINED
+ if "mention_channels" in payload:
+ channel_mentions = [snowflake.Snowflake(mention["id"]) for mention in payload["mention_channels"]]
+
+ attachments: undefined.UndefinedOr[typing.MutableSequence[message_models.Attachment]] = undefined.UNDEFINED
+ if "attachments" in payload:
+ attachments = []
+ for attachment_payload in payload["attachments"]:
+ attachment = message_models.Attachment(
+ id=snowflake.Snowflake(attachment_payload["id"]),
+ filename=attachment_payload["filename"],
+ size=int(attachment_payload["size"]),
+ url=attachment_payload["url"],
+ proxy_url=attachment_payload["proxy_url"],
+ height=attachment_payload.get("height"),
+ width=attachment_payload.get("width"),
+ )
+ attachments.append(attachment)
+
+ embeds: undefined.UndefinedOr[typing.Sequence[embed_models.Embed]] = undefined.UNDEFINED
+ if "embeds" in payload:
+ embeds = [self.deserialize_embed(embed) for embed in payload["embeds"]]
+
+ reactions: undefined.UndefinedOr[typing.MutableSequence[message_models.Reaction]] = undefined.UNDEFINED
+ if "reactions" in payload:
+ reactions = []
+ for reaction_payload in payload["reactions"]:
+ reaction = message_models.Reaction(
+ count=int(reaction_payload["count"]),
+ emoji=self.deserialize_emoji(reaction_payload["emoji"]),
+ is_me=reaction_payload["me"],
+ )
+ reactions.append(reaction)
+
+ activity: undefined.UndefinedOr[message_models.MessageActivity] = undefined.UNDEFINED
+ if "activity" in payload:
+ activity_payload = payload["activity"]
+ activity = message_models.MessageActivity(
+ type=message_models.MessageActivityType(activity_payload["type"]),
+ party_id=activity_payload.get("party_id"),
+ )
+
+ application: undefined.UndefinedOr[application_models.Application] = undefined.UNDEFINED
+ if "application" in payload:
+ application = self.deserialize_application(payload["application"])
+
+ message_reference: undefined.UndefinedOr[message_models.MessageCrosspost] = undefined.UNDEFINED
+ if "message_reference" in payload:
+ crosspost_payload = payload["message_reference"]
+ message_reference = message_models.MessageCrosspost(
+ app=self._app,
+ id=snowflake.Snowflake(crosspost_payload["message_id"]) if "message_id" in crosspost_payload else None,
+ channel_id=snowflake.Snowflake(crosspost_payload["channel_id"]),
+ guild_id=snowflake.Snowflake(crosspost_payload["guild_id"])
+ if "guild_id" in crosspost_payload
+ else None,
+ )
+
+ return message_models.PartialMessage(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ channel_id=snowflake.Snowflake(payload["channel_id"]),
+ guild_id=guild_id,
+ author=author,
+ member=member,
+ content=payload["content"] if "content" in payload else undefined.UNDEFINED,
+ timestamp=timestamp,
+ edited_timestamp=edited_timestamp,
+ is_tts=payload["tts"] if "tts" in payload else undefined.UNDEFINED,
+ is_mentioning_everyone=is_mentioning_everyone,
+ user_mentions=user_mentions,
+ role_mentions=role_mentions,
+ channel_mentions=channel_mentions,
+ attachments=attachments,
+ embeds=embeds,
+ reactions=reactions,
+ is_pinned=payload["pinned"] if "pinned" in payload else undefined.UNDEFINED,
+ webhook_id=snowflake.Snowflake(payload["webhook_id"]) if "webhook_id" in payload else undefined.UNDEFINED,
+ type=message_models.MessageType(payload["type"]) if "type" in payload else undefined.UNDEFINED,
+ activity=activity,
+ application=application,
+ message_reference=message_reference,
+ flags=message_models.MessageFlag(payload["flags"]) if "flags" in payload else undefined.UNDEFINED,
+ nonce=payload["nonce"] if "nonce" in payload else undefined.UNDEFINED,
+ )
+
+ def deserialize_message(self, payload: data_binding.JSONObject) -> message_models.Message:
+ guild_id = snowflake.Snowflake(payload["guild_id"]) if "guild_id" in payload else None
+ author = self.deserialize_user(payload["author"])
+
+ member: typing.Optional[guild_models.Member] = None
+ if "member" in payload:
+ assert guild_id is not None
+ member = self.deserialize_member(payload["member"], guild_id=guild_id, user=author)
+
+ edited_timestamp: typing.Optional[datetime.datetime] = None
+ if (raw_edited_timestamp := payload["edited_timestamp"]) is not None:
+ edited_timestamp = date.iso8601_datetime_string_to_datetime(raw_edited_timestamp)
+
+ user_mentions = [snowflake.Snowflake(mention["id"]) for mention in payload["mentions"]]
+ role_mentions = [snowflake.Snowflake(mention) for mention in payload["mention_roles"]]
+ channel_mentions = (
+ [snowflake.Snowflake(mention["id"]) for mention in payload["mention_channels"]]
+ if "mention_channels" in payload
+ else []
+ )
+
+ attachments = []
+ for attachment_payload in payload["attachments"]:
+ attachment = message_models.Attachment(
+ id=snowflake.Snowflake(attachment_payload["id"]),
+ filename=attachment_payload["filename"],
+ size=int(attachment_payload["size"]),
+ url=attachment_payload["url"],
+ proxy_url=attachment_payload["proxy_url"],
+ height=attachment_payload.get("height"),
+ width=attachment_payload.get("width"),
+ )
+ attachments.append(attachment)
+
+ embeds = [self.deserialize_embed(embed) for embed in payload["embeds"]]
+
+ reactions = []
+ if "reactions" in payload:
+ for reaction_payload in payload["reactions"]:
+ reaction = message_models.Reaction(
+ count=int(reaction_payload["count"]),
+ emoji=self.deserialize_emoji(reaction_payload["emoji"]),
+ is_me=reaction_payload["me"],
+ )
+ reactions.append(reaction)
+
+ activity: typing.Optional[message_models.MessageActivity] = None
+ if "activity" in payload:
+ activity_payload = payload["activity"]
+ activity = message_models.MessageActivity(
+ type=message_models.MessageActivityType(activity_payload["type"]),
+ party_id=activity_payload.get("party_id"),
+ )
+
+ crosspost: typing.Optional[message_models.MessageCrosspost] = None
+ if "message_reference" in payload:
+ crosspost_payload = payload["message_reference"]
+ crosspost_id = (
+ snowflake.Snowflake(crosspost_payload["message_id"]) if "message_id" in crosspost_payload else None
+ )
+ crosspost = message_models.MessageCrosspost(
+ app=self._app,
+ id=crosspost_id,
+ channel_id=snowflake.Snowflake(crosspost_payload["channel_id"]),
+ guild_id=snowflake.Snowflake(crosspost_payload["guild_id"])
+ if "guild_id" in crosspost_payload
+ else None,
+ )
+
+ return message_models.Message(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ channel_id=snowflake.Snowflake(payload["channel_id"]),
+ guild_id=guild_id,
+ author=author,
+ member=member,
+ content=payload["content"],
+ timestamp=date.iso8601_datetime_string_to_datetime(payload["timestamp"]),
+ edited_timestamp=edited_timestamp,
+ is_tts=payload["tts"],
+ is_mentioning_everyone=payload["mention_everyone"],
+ user_mentions=user_mentions,
+ role_mentions=role_mentions,
+ channel_mentions=channel_mentions,
+ attachments=attachments,
+ embeds=embeds,
+ reactions=reactions,
+ is_pinned=payload["pinned"],
+ webhook_id=snowflake.Snowflake(payload["webhook_id"]) if "webhook_id" in payload else None,
+ type=message_models.MessageType(payload["type"]),
+ activity=activity,
+ application=self.deserialize_application(payload["application"]) if "application" in payload else None,
+ message_reference=crosspost,
+ flags=message_models.MessageFlag(payload["flags"]) if "flags" in payload else None,
+ nonce=payload.get("nonce"),
+ )
+
+ ###################
+ # PRESENCE MODELS #
+ ###################
+
+ def deserialize_member_presence( # noqa: CFQ001 # TODO: what's CFQ001?
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> presence_models.MemberPresence:
+ role_ids = [snowflake.Snowflake(role_id) for role_id in payload["roles"]] if "roles" in payload else None
+
+ activities = []
+ for activity_payload in payload["activities"]:
+ timestamps: typing.Optional[presence_models.ActivityTimestamps] = None
+ if "timestamps" in activity_payload:
+ timestamps_payload = activity_payload["timestamps"]
+ start = (
+ date.unix_epoch_to_datetime(timestamps_payload["start"]) if "start" in timestamps_payload else None
+ )
+ end = date.unix_epoch_to_datetime(timestamps_payload["end"]) if "end" in timestamps_payload else None
+ timestamps = presence_models.ActivityTimestamps(start=start, end=end)
+
+ application_id = (
+ snowflake.Snowflake(activity_payload["application_id"])
+ if "application_id" in activity_payload
+ else None
+ )
+
+ party: typing.Optional[presence_models.ActivityParty] = None
+ if "party" in activity_payload:
+ party_payload = activity_payload["party"]
+
+ current_size: typing.Optional[int]
+ max_size: typing.Optional[int]
+ if "size" in party_payload:
+ raw_current_size, raw_max_size = party_payload["size"]
+ current_size = int(raw_current_size)
+ max_size = int(raw_max_size)
+ else:
+ current_size = max_size = None
+
+ party = presence_models.ActivityParty(
+ id=party_payload.get("id"), current_size=current_size, max_size=max_size
+ )
+
+ assets: typing.Optional[presence_models.ActivityAssets] = None
+ if "assets" in activity_payload:
+ assets_payload = activity_payload["assets"]
+ assets = presence_models.ActivityAssets(
+ large_image=assets_payload.get("large_image"),
+ large_text=assets_payload.get("large_text"),
+ small_image=assets_payload.get("small_image"),
+ small_text=assets_payload.get("small_text"),
+ )
+
+ secrets: typing.Optional[presence_models.ActivitySecret] = None
+ if "secrets" in activity_payload:
+ secrets_payload = activity_payload["secrets"]
+ secrets = presence_models.ActivitySecret(
+ join=secrets_payload.get("join"),
+ spectate=secrets_payload.get("spectate"),
+ match=secrets_payload.get("match"),
+ )
+
+ emoji: typing.Optional[emoji_models.Emoji] = None
+ raw_emoji = activity_payload.get("emoji")
+ if raw_emoji is not None:
+ emoji = self.deserialize_emoji(raw_emoji)
+
+ activity = presence_models.RichActivity(
+ name=activity_payload["name"],
+ type=presence_models.ActivityType(activity_payload["type"]),
+ url=activity_payload.get("url"),
+ created_at=date.unix_epoch_to_datetime(activity_payload["created_at"]),
+ timestamps=timestamps,
+ application_id=application_id,
+ details=activity_payload.get("details"),
+ state=activity_payload.get("state"),
+ emoji=emoji,
+ party=party,
+ assets=assets,
+ secrets=secrets,
+ is_instance=activity_payload.get("instance"), # TODO: can we safely default this to False?
+ flags=presence_models.ActivityFlag(activity_payload["flags"]) if "flags" in activity_payload else None,
+ )
+ activities.append(activity)
+
+ client_status_payload = payload["client_status"]
+ desktop = (
+ presence_models.Status(client_status_payload["desktop"])
+ if "desktop" in client_status_payload
+ else presence_models.Status.OFFLINE
+ )
+ mobile = (
+ presence_models.Status(client_status_payload["mobile"])
+ if "mobile" in client_status_payload
+ else presence_models.Status.OFFLINE
+ )
+ web = (
+ presence_models.Status(client_status_payload["web"])
+ if "web" in client_status_payload
+ else presence_models.Status.OFFLINE
+ )
+ client_status = presence_models.ClientStatus(desktop=desktop, mobile=mobile, web=web)
+ # TODO: do we want to differentiate between undefined and null here?
+ premium_since = payload.get("premium_since")
+ premium_since = date.iso8601_datetime_string_to_datetime(premium_since) if premium_since is not None else None
+ return presence_models.MemberPresence(
+ app=self._app,
+ user_id=snowflake.Snowflake(payload["user"]["id"]),
+ role_ids=role_ids,
+ guild_id=guild_id if guild_id is not undefined.UNDEFINED else snowflake.Snowflake(payload["guild_id"]),
+ visible_status=presence_models.Status(payload["status"]),
+ activities=activities,
+ client_status=client_status,
+ premium_since=premium_since,
+ # TODO: do we want to differentiate between undefined and null here?
+ nickname=payload.get("nick"),
+ )
+
+ ###############
+ # USER MODELS #
+ ###############
+
+ @staticmethod
+ def _set_user_attributes(payload: data_binding.JSONObject) -> _UserFields:
+ return _UserFields(
+ id=snowflake.Snowflake(payload["id"]),
+ discriminator=payload["discriminator"],
+ username=payload["username"],
+ avatar_hash=payload["avatar"],
+ is_bot=payload.get("bot", False),
+ is_system=payload.get("system", False),
+ )
+
+ def deserialize_user(self, payload: data_binding.JSONObject) -> user_models.User:
+ user_fields = self._set_user_attributes(payload)
+ flags = (
+ user_models.UserFlag(payload["public_flags"]) if "public_flags" in payload else user_models.UserFlag.NONE
+ )
+ return user_models.UserImpl(
+ app=self._app,
+ id=user_fields.id,
+ discriminator=user_fields.discriminator,
+ username=user_fields.username,
+ avatar_hash=user_fields.avatar_hash,
+ is_bot=user_fields.is_bot,
+ is_system=user_fields.is_system,
+ flags=flags,
+ )
+
+ def deserialize_my_user(self, payload: data_binding.JSONObject) -> user_models.OwnUser:
+ user_fields = self._set_user_attributes(payload)
+ return user_models.OwnUser(
+ app=self._app,
+ id=user_fields.id,
+ discriminator=user_fields.discriminator,
+ username=user_fields.username,
+ avatar_hash=user_fields.avatar_hash,
+ is_bot=user_fields.is_bot,
+ is_system=user_fields.is_system,
+ is_mfa_enabled=payload["mfa_enabled"],
+ locale=payload.get("locale"),
+ is_verified=payload.get("verified"),
+ email=payload.get("email"),
+ flags=user_models.UserFlag(payload["flags"]),
+ premium_type=user_models.PremiumType(payload["premium_type"]) if "premium_type" in payload else None,
+ )
+
+ ################
+ # VOICE MODELS #
+ ################
+
+ def deserialize_voice_state(
+ self,
+ payload: data_binding.JSONObject,
+ *,
+ guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ member: undefined.UndefinedOr[guild_models.Member] = undefined.UNDEFINED,
+ ) -> voice_models.VoiceState:
+ if guild_id is undefined.UNDEFINED:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+
+ channel_id: typing.Optional[snowflake.Snowflake] = None
+ if (raw_channel_id := payload["channel_id"]) is not None:
+ channel_id = snowflake.Snowflake(raw_channel_id)
+
+ if member is undefined.UNDEFINED:
+ member = self.deserialize_member(payload["member"], guild_id=guild_id)
+
+ return voice_models.VoiceState(
+ app=self._app,
+ guild_id=guild_id,
+ channel_id=channel_id,
+ user_id=snowflake.Snowflake(payload["user_id"]),
+ member=member,
+ session_id=payload["session_id"],
+ is_guild_deafened=payload["deaf"],
+ is_guild_muted=payload["mute"],
+ is_self_deafened=payload["self_deaf"],
+ is_self_muted=payload["self_mute"],
+ is_streaming=payload.get("self_stream", False),
+ is_video_enabled=payload["self_video"],
+ is_suppressed=payload["suppress"],
+ )
+
+ def deserialize_voice_region(self, payload: data_binding.JSONObject) -> voice_models.VoiceRegion:
+ return voice_models.VoiceRegion(
+ id=payload["id"],
+ name=payload["name"],
+ is_vip=payload["vip"],
+ is_optimal_location=payload["optimal"],
+ is_deprecated=payload["deprecated"],
+ is_custom=payload["custom"],
+ )
+
+ ##################
+ # WEBHOOK MODELS #
+ ##################
+
+ def deserialize_webhook(self, payload: data_binding.JSONObject) -> webhook_models.Webhook:
+ return webhook_models.Webhook(
+ app=self._app,
+ id=snowflake.Snowflake(payload["id"]),
+ type=webhook_models.WebhookType(payload["type"]),
+ guild_id=snowflake.Snowflake(payload["guild_id"]) if "guild_id" in payload else None,
+ channel_id=snowflake.Snowflake(payload["channel_id"]),
+ author=self.deserialize_user(payload["user"]) if "user" in payload else None,
+ name=payload["name"],
+ avatar_hash=payload["avatar"],
+ token=payload.get("token"),
+ )
diff --git a/hikari/impl/event_factory.py b/hikari/impl/event_factory.py
new file mode 100644
index 0000000000..2731b414fe
--- /dev/null
+++ b/hikari/impl/event_factory.py
@@ -0,0 +1,544 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Implementation for a singleton bot event factory."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["EventFactoryImpl"]
+
+import datetime
+import typing
+
+from hikari import traits
+from hikari.api import event_factory
+from hikari.api import shard as gateway_shard
+from hikari.events import channel_events
+from hikari.events import guild_events
+from hikari.events import member_events
+from hikari.events import message_events
+from hikari.events import reaction_events
+from hikari.events import role_events
+from hikari.events import shard_events
+from hikari.events import typing_events
+from hikari.events import user_events
+from hikari.events import voice_events
+from hikari.models import channels as channel_models
+from hikari.models import users as user_models
+from hikari.utilities import data_binding
+from hikari.utilities import date
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+
+class EventFactoryImpl(event_factory.EventFactory):
+ """Implementation for a single-application bot event factory."""
+
+ def __init__(self, app: traits.RESTAware) -> None:
+ self._app = app
+
+ ##################
+ # CHANNEL EVENTS #
+ ##################
+
+ def deserialize_channel_create_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.ChannelCreateEvent:
+ channel = self._app.entity_factory.deserialize_channel(payload)
+ if isinstance(channel, channel_models.GuildChannel):
+ return channel_events.GuildChannelCreateEvent(app=self._app, shard=shard, channel=channel)
+ if isinstance(channel, channel_models.PrivateChannel):
+ return channel_events.PrivateChannelCreateEvent(app=self._app, shard=shard, channel=channel)
+ raise TypeError(f"Expected GuildChannel or PrivateChannel but received {type(channel).__name__}")
+
+ def deserialize_channel_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.ChannelUpdateEvent:
+ channel = self._app.entity_factory.deserialize_channel(payload)
+ if isinstance(channel, channel_models.GuildChannel):
+ return channel_events.GuildChannelUpdateEvent(app=self._app, shard=shard, channel=channel)
+ if isinstance(channel, channel_models.PrivateChannel):
+ return channel_events.PrivateChannelUpdateEvent(app=self._app, shard=shard, channel=channel)
+ raise TypeError(f"Expected GuildChannel or PrivateChannel but received {type(channel).__name__}")
+
+ def deserialize_channel_delete_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.ChannelDeleteEvent:
+ channel = self._app.entity_factory.deserialize_channel(payload)
+ if isinstance(channel, channel_models.GuildChannel):
+ return channel_events.GuildChannelDeleteEvent(app=self._app, shard=shard, channel=channel)
+ if isinstance(channel, channel_models.PrivateChannel):
+ return channel_events.PrivateChannelDeleteEvent(app=self._app, shard=shard, channel=channel)
+ raise TypeError(f"Expected GuildChannel or PrivateChannel but received {type(channel).__name__}")
+
+ def deserialize_channel_pins_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.PinsUpdateEvent:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+
+ # Turns out this _can_ be None or not present. Only set it if it is actually available.
+ if (raw := payload.get("last_pin_timestamp")) is not None:
+ last_pin_timestamp: typing.Optional[datetime.datetime] = date.iso8601_datetime_string_to_datetime(raw)
+ else:
+ last_pin_timestamp = None
+
+ if "guild_id" in payload:
+ return channel_events.GuildPinsUpdateEvent(
+ app=self._app,
+ shard=shard,
+ channel_id=channel_id,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ last_pin_timestamp=last_pin_timestamp,
+ )
+
+ return channel_events.PrivatePinsUpdateEvent(
+ app=self._app, shard=shard, channel_id=channel_id, last_pin_timestamp=last_pin_timestamp
+ )
+
+ def deserialize_webhook_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.WebhookUpdateEvent:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+ return channel_events.WebhookUpdateEvent(app=self._app, shard=shard, channel_id=channel_id, guild_id=guild_id,)
+
+ def deserialize_typing_start_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> typing_events.TypingEvent:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+ user_id = snowflake.Snowflake(payload["user_id"])
+ # Turns out that this endpoint uses seconds rather than milliseconds.
+ timestamp = date.unix_epoch_to_datetime(payload["timestamp"], is_millis=False)
+
+ if "guild_id" in payload:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ member = self._app.entity_factory.deserialize_member(payload["member"], guild_id=guild_id)
+ return typing_events.GuildTypingEvent(
+ app=self._app,
+ shard=shard,
+ channel_id=channel_id,
+ guild_id=guild_id,
+ user_id=user_id,
+ timestamp=timestamp,
+ member=member,
+ )
+
+ return typing_events.PrivateTypingEvent(
+ app=self._app, shard=shard, channel_id=channel_id, user_id=user_id, timestamp=timestamp
+ )
+
+ def deserialize_invite_create_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.InviteCreateEvent:
+ invite = self._app.entity_factory.deserialize_invite_with_metadata(payload)
+ return channel_events.InviteCreateEvent(app=self._app, shard=shard, invite=invite)
+
+ def deserialize_invite_delete_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> channel_events.InviteDeleteEvent:
+
+ if "guild_id" not in payload:
+ raise TypeError("Expected guild invite delete, but received unexpected payload")
+
+ return channel_events.InviteDeleteEvent(
+ app=self._app,
+ shard=shard,
+ code=payload["code"],
+ channel_id=snowflake.Snowflake(payload["channel_id"]),
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ )
+
+ ################
+ # GUILD EVENTS #
+ ################
+
+ def deserialize_guild_create_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.GuildAvailableEvent:
+ guild_information = self._app.entity_factory.deserialize_gateway_guild(payload)
+ assert guild_information.channels is not None
+ assert guild_information.members is not None
+ assert guild_information.presences is not None
+ assert guild_information.voice_states is not None
+ return guild_events.GuildAvailableEvent(
+ app=self._app,
+ shard=shard,
+ guild=guild_information.guild,
+ emojis=guild_information.emojis,
+ roles=guild_information.roles,
+ channels=guild_information.channels,
+ members=guild_information.members,
+ presences=guild_information.presences,
+ voice_states=guild_information.voice_states,
+ )
+
+ def deserialize_guild_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.GuildUpdateEvent:
+ guild_information = self._app.entity_factory.deserialize_gateway_guild(payload)
+ return guild_events.GuildUpdateEvent(
+ app=self._app,
+ shard=shard,
+ guild=guild_information.guild,
+ emojis=guild_information.emojis,
+ roles=guild_information.roles,
+ )
+
+ def deserialize_guild_leave_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.GuildLeaveEvent:
+ return guild_events.GuildLeaveEvent(app=self._app, shard=shard, guild_id=snowflake.Snowflake(payload["id"]))
+
+ def deserialize_guild_unavailable_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.GuildUnavailableEvent:
+ return guild_events.GuildUnavailableEvent(
+ app=self._app, shard=shard, guild_id=snowflake.Snowflake(payload["id"])
+ )
+
+ def deserialize_guild_ban_add_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.BanCreateEvent:
+ return guild_events.BanCreateEvent(
+ app=self._app,
+ shard=shard,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ user=self._app.entity_factory.deserialize_user(payload["user"]),
+ )
+
+ def deserialize_guild_ban_remove_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.BanDeleteEvent:
+ return guild_events.BanDeleteEvent(
+ app=self._app,
+ shard=shard,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ user=self._app.entity_factory.deserialize_user(payload["user"]),
+ )
+
+ def deserialize_guild_emojis_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.EmojisUpdateEvent:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ emojis = [
+ self._app.entity_factory.deserialize_known_custom_emoji(emoji, guild_id=guild_id)
+ for emoji in payload["emojis"]
+ ]
+ return guild_events.EmojisUpdateEvent(app=self._app, shard=shard, guild_id=guild_id, emojis=emojis)
+
+ def deserialize_guild_integrations_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.IntegrationsUpdateEvent:
+ return guild_events.IntegrationsUpdateEvent(
+ app=self._app, shard=shard, guild_id=snowflake.Snowflake(payload["guild_id"]),
+ )
+
+ def deserialize_guild_member_add_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> member_events.MemberCreateEvent:
+ member = self._app.entity_factory.deserialize_member(payload)
+ return member_events.MemberCreateEvent(app=self._app, shard=shard, member=member)
+
+ def deserialize_guild_member_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> member_events.MemberUpdateEvent:
+ member = self._app.entity_factory.deserialize_member(payload)
+ return member_events.MemberUpdateEvent(app=self._app, shard=shard, member=member)
+
+ def deserialize_guild_member_remove_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> member_events.MemberDeleteEvent:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ user = self._app.entity_factory.deserialize_user(payload["user"])
+ return member_events.MemberDeleteEvent(app=self._app, shard=shard, guild_id=guild_id, user=user)
+
+ def deserialize_guild_role_create_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> role_events.RoleCreateEvent:
+ role = self._app.entity_factory.deserialize_role(
+ payload["role"], guild_id=snowflake.Snowflake(payload["guild_id"]),
+ )
+ return role_events.RoleCreateEvent(app=self._app, shard=shard, role=role)
+
+ def deserialize_guild_role_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> role_events.RoleUpdateEvent:
+ role = self._app.entity_factory.deserialize_role(
+ payload["role"], guild_id=snowflake.Snowflake(payload["guild_id"]),
+ )
+ return role_events.RoleUpdateEvent(app=self._app, shard=shard, role=role)
+
+ def deserialize_guild_role_delete_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> role_events.RoleDeleteEvent:
+ return role_events.RoleDeleteEvent(
+ app=self._app,
+ shard=shard,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ role_id=snowflake.Snowflake(payload["role_id"]),
+ )
+
+ def deserialize_presence_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.PresenceUpdateEvent:
+ presence = self._app.entity_factory.deserialize_member_presence(payload)
+
+ user_payload = payload["user"]
+ user: typing.Optional[user_models.PartialUser] = None
+ # Here we're told that the only guaranteed field is "id", so if we only get 1 field in the user payload then
+ # then we've only got an ID and there's no reason to form a user object.
+ if len(user_payload) > 1:
+ # PartialUser
+ discriminator = user_payload["discriminator"] if "discriminator" in user_payload else undefined.UNDEFINED
+ flags: undefined.UndefinedOr[user_models.UserFlag] = undefined.UNDEFINED
+ if "public_flags" in user_payload:
+ flags = user_models.UserFlag(user_payload["public_flags"])
+
+ user = user_models.PartialUserImpl(
+ app=self._app,
+ id=snowflake.Snowflake(user_payload["id"]),
+ discriminator=discriminator,
+ username=user_payload.get("username", undefined.UNDEFINED),
+ avatar_hash=user_payload.get("avatar", undefined.UNDEFINED),
+ is_bot=user_payload.get("bot", undefined.UNDEFINED),
+ is_system=user_payload.get("system", undefined.UNDEFINED),
+ flags=flags,
+ )
+ # noinspection PyArgumentList
+
+ return guild_events.PresenceUpdateEvent(app=self._app, shard=shard, presence=presence, user=user)
+
+ ##################
+ # MESSAGE EVENTS #
+ ##################
+
+ def deserialize_message_create_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> message_events.MessageCreateEvent:
+ message = self._app.entity_factory.deserialize_message(payload)
+
+ if message.guild_id is None:
+ return message_events.PrivateMessageCreateEvent(app=self._app, shard=shard, message=message)
+
+ return message_events.GuildMessageCreateEvent(app=self._app, shard=shard, message=message)
+
+ def deserialize_message_update_event( # noqa: CFQ001
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> message_events.MessageUpdateEvent:
+ message = self._app.entity_factory.deserialize_partial_message(payload)
+
+ if message.guild_id is None:
+ return message_events.PrivateMessageUpdateEvent(app=self._app, shard=shard, message=message)
+
+ return message_events.GuildMessageUpdateEvent(app=self._app, shard=shard, message=message)
+
+ def deserialize_message_delete_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> message_events.MessageDeleteEvent:
+ message = self._app.entity_factory.deserialize_partial_message(payload)
+
+ if message.guild_id is None:
+ return message_events.PrivateMessageDeleteEvent(app=self._app, shard=shard, message=message)
+
+ return message_events.GuildMessageDeleteEvent(app=self._app, shard=shard, message=message)
+
+ def deserialize_message_delete_bulk_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> message_events.MessageBulkDeleteEvent:
+ if "guild_id" not in payload:
+ raise NotImplementedError("No implementation for private message bulk delete events")
+
+ return message_events.GuildMessageBulkDeleteEvent(
+ app=self._app,
+ shard=shard,
+ channel_id=snowflake.Snowflake(payload["channel_id"]),
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ message_ids=[snowflake.Snowflake(message_id) for message_id in payload["ids"]],
+ )
+
+ def deserialize_message_reaction_add_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> reaction_events.ReactionAddEvent:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+ message_id = snowflake.Snowflake(payload["message_id"])
+ emoji = self._app.entity_factory.deserialize_emoji(payload["emoji"])
+
+ if "member" in payload:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ member = self._app.entity_factory.deserialize_member(payload["member"], guild_id=guild_id)
+ return reaction_events.GuildReactionAddEvent(
+ app=self._app, shard=shard, member=member, channel_id=channel_id, message_id=message_id, emoji=emoji,
+ )
+
+ user_id = snowflake.Snowflake(payload["user_id"])
+ return reaction_events.PrivateReactionAddEvent(
+ app=self._app, shard=shard, channel_id=channel_id, message_id=message_id, user_id=user_id, emoji=emoji,
+ )
+
+ def deserialize_message_reaction_remove_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> reaction_events.ReactionDeleteEvent:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+ message_id = snowflake.Snowflake(payload["message_id"])
+ user_id = snowflake.Snowflake(payload["user_id"])
+ emoji = self._app.entity_factory.deserialize_emoji(payload["emoji"])
+
+ if "guild_id" in payload:
+ return reaction_events.GuildReactionDeleteEvent(
+ app=self._app,
+ shard=shard,
+ user_id=user_id,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ channel_id=channel_id,
+ message_id=message_id,
+ emoji=emoji,
+ )
+
+ return reaction_events.PrivateReactionDeleteEvent(
+ app=self._app, shard=shard, user_id=user_id, channel_id=channel_id, message_id=message_id, emoji=emoji,
+ )
+
+ def deserialize_message_reaction_remove_all_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> reaction_events.ReactionDeleteAllEvent:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+ message_id = snowflake.Snowflake(payload["message_id"])
+
+ if "guild_id" in payload:
+ return reaction_events.GuildReactionDeleteAllEvent(
+ app=self._app,
+ shard=shard,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ channel_id=channel_id,
+ message_id=message_id,
+ )
+
+ # TODO: check if this can even occur.
+ return reaction_events.PrivateReactionDeleteAllEvent(
+ app=self._app, shard=shard, channel_id=channel_id, message_id=message_id,
+ )
+
+ def deserialize_message_reaction_remove_emoji_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> reaction_events.ReactionDeleteEmojiEvent:
+ channel_id = snowflake.Snowflake(payload["channel_id"])
+ message_id = snowflake.Snowflake(payload["message_id"])
+ emoji = self._app.entity_factory.deserialize_emoji(payload["emoji"])
+
+ if "guild_id" in payload:
+ return reaction_events.GuildReactionDeleteEmojiEvent(
+ app=self._app,
+ shard=shard,
+ emoji=emoji,
+ guild_id=snowflake.Snowflake(payload["guild_id"]),
+ channel_id=channel_id,
+ message_id=message_id,
+ )
+
+ # TODO: check if this can even occur.
+ return reaction_events.PrivateReactionDeleteEmojiEvent(
+ app=self._app, shard=shard, emoji=emoji, channel_id=channel_id, message_id=message_id,
+ )
+
+ ################
+ # OTHER EVENTS #
+ ################
+
+ def deserialize_ready_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> shard_events.ShardReadyEvent:
+ gateway_version = int(payload["v"])
+ my_user = self._app.entity_factory.deserialize_my_user(payload["user"])
+ unavailable_guilds = [snowflake.Snowflake(guild["id"]) for guild in payload["guilds"]]
+ session_id = payload["session_id"]
+
+ return shard_events.ShardReadyEvent(
+ app=self._app,
+ shard=shard,
+ actual_gateway_version=gateway_version,
+ session_id=session_id,
+ my_user=my_user,
+ unavailable_guilds=unavailable_guilds,
+ )
+
+ def deserialize_own_user_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> user_events.OwnUserUpdateEvent:
+ return user_events.OwnUserUpdateEvent(
+ app=self._app, shard=shard, user=self._app.entity_factory.deserialize_my_user(payload)
+ )
+
+ def deserialize_guild_member_chunk_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> guild_events.MemberChunkEvent:
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ index = int(payload["chunk_index"])
+ count = int(payload["chunk_count"])
+ members = {
+ snowflake.Snowflake(m["user"]["id"]): self._app.entity_factory.deserialize_member(m, guild_id=guild_id)
+ for m in payload["members"]
+ }
+ # Note, these IDs may be returned as ints or strings based on whether they're over a certain value.
+ not_found = [snowflake.Snowflake(sn) for sn in payload["not_found"]] if "not_found" in payload else []
+
+ nonce = typing.cast("typing.Optional[str]", payload.get("nonce"))
+
+ if (presence_payloads := payload.get("include_presences")) is not None:
+ presences = {
+ snowflake.Snowflake(p["user"]["id"]): self._app.entity_factory.deserialize_member_presence(
+ p, guild_id=guild_id
+ )
+ for p in presence_payloads
+ }
+ else:
+ presences = {}
+
+ return guild_events.MemberChunkEvent(
+ app=self._app,
+ shard=shard,
+ guild_id=guild_id,
+ members=members,
+ index=index,
+ count=count,
+ not_found=not_found,
+ presences=presences,
+ nonce=nonce,
+ )
+
+ ################
+ # VOICE EVENTS #
+ ################
+
+ def deserialize_voice_state_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> voice_events.VoiceStateUpdateEvent:
+ state = self._app.entity_factory.deserialize_voice_state(payload)
+ return voice_events.VoiceStateUpdateEvent(app=self._app, shard=shard, state=state)
+
+ def deserialize_voice_server_update_event(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> voice_events.VoiceServerUpdateEvent:
+ token = payload["token"]
+ guild_id = snowflake.Snowflake(payload["guild_id"])
+ raw_endpoint = payload["endpoint"]
+ return voice_events.VoiceServerUpdateEvent(
+ app=self._app, shard=shard, guild_id=guild_id, token=token, raw_endpoint=raw_endpoint
+ )
diff --git a/hikari/impl/event_manager_base.py b/hikari/impl/event_manager_base.py
new file mode 100644
index 0000000000..5a1eab2080
--- /dev/null
+++ b/hikari/impl/event_manager_base.py
@@ -0,0 +1,310 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""A base implementation for an event manager."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["EventManagerBase"]
+
+import asyncio
+import logging
+import typing
+import warnings
+
+from hikari import errors
+from hikari import traits
+from hikari.api import event_dispatcher
+from hikari.events import base_events
+from hikari.events import shard_events
+from hikari.models import intents as intents_
+from hikari.utilities import aio
+from hikari.utilities import data_binding
+from hikari.utilities import reflect
+
+if typing.TYPE_CHECKING:
+ from hikari.api import shard as gateway_shard
+
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari")
+
+if typing.TYPE_CHECKING:
+ ListenerMapT = typing.MutableMapping[
+ typing.Type[event_dispatcher.EventT_co],
+ typing.MutableSequence[event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]],
+ ]
+ WaiterT = typing.Tuple[
+ event_dispatcher.PredicateT[event_dispatcher.EventT_co], asyncio.Future[event_dispatcher.EventT_co]
+ ]
+ WaiterMapT = typing.MutableMapping[
+ typing.Type[event_dispatcher.EventT_co], typing.MutableSet[WaiterT[event_dispatcher.EventT_co]]
+ ]
+
+
+def _default_predicate(_: event_dispatcher.EventT_inv) -> bool:
+ return True
+
+
+class EventManagerBase(event_dispatcher.EventDispatcher):
+ """Provides functionality to consume and dispatch events.
+
+ Specific event handlers should be in functions named `on_xxx` where `xxx`
+ is the raw event name being dispatched in lower-case.
+ """
+
+ __slots__: typing.Sequence[str] = ("_app", "_intents", "_listeners", "_waiters")
+
+ def __init__(self, app: traits.BotAware, intents: typing.Optional[intents_.Intents]) -> None:
+ self._app = app
+ self._intents = intents
+ self._listeners: ListenerMapT[base_events.Event] = {}
+ self._waiters: WaiterMapT[base_events.Event] = {}
+
+ async def consume_raw_event(
+ self, shard: gateway_shard.GatewayShard, event_name: str, payload: data_binding.JSONObject
+ ) -> None:
+ try:
+ callback = getattr(self, "on_" + event_name.lower())
+ except AttributeError:
+ _LOGGER.debug("ignoring unknown event %s", event_name)
+ else:
+ await callback(shard, payload)
+
+ def subscribe(
+ self,
+ event_type: typing.Type[event_dispatcher.EventT_co],
+ callback: event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ *,
+ _nested: int = 0,
+ ) -> event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]:
+ # `_nested` is used to show the correct source code snippet if an intent
+ # warning is triggered.
+ self._check_intents(event_type, _nested)
+
+ if event_type not in self._listeners:
+ self._listeners[event_type] = []
+
+ if not asyncio.iscoroutinefunction(callback):
+ raise TypeError("Event callbacks must be coroutine functions (`async def')")
+
+ _LOGGER.debug(
+ "subscribing callback 'async def %s%s' to event-type %s.%s",
+ getattr(callback, "__name__", ""),
+ reflect.resolve_signature(callback),
+ event_type.__module__,
+ event_type.__qualname__,
+ )
+
+ self._listeners[event_type].append(callback) # type: ignore[arg-type]
+
+ return callback
+
+ def _check_intents(self, event_type: typing.Type[event_dispatcher.EventT_co], nested: int) -> None:
+ # If None, the user is on v6 with intents disabled, so we don't care.
+ if self._intents is not None:
+ # Collection of combined bitfield combinations of intents that
+ # could be enabled to receive this event.
+ expected_intent_groups = base_events.get_required_intents_for(event_type)
+
+ if expected_intent_groups:
+ for expected_intent_group in expected_intent_groups:
+ if (self._intents & expected_intent_group) == expected_intent_group:
+ break
+ else:
+ expected_intents_str = ", ".join(map(str, expected_intent_groups))
+
+ warnings.warn(
+ f"You have tried to listen to {event_type.__name__}, but this will only ever be triggered if "
+ f"you enable one of the following intents: {expected_intents_str}.",
+ category=errors.MissingIntentWarning,
+ stacklevel=nested + 3,
+ )
+
+ def get_listeners(
+ self, event_type: typing.Type[event_dispatcher.EventT_co], *, polymorphic: bool = True,
+ ) -> typing.Collection[event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]]:
+ if polymorphic:
+ listeners: typing.List[event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]] = []
+ for subscribed_event_type, subscribed_listeners in self._listeners.items():
+ if issubclass(subscribed_event_type, event_type):
+ listeners += subscribed_listeners
+ return listeners
+ else:
+ items = self._listeners.get(event_type)
+ if items is not None:
+ return items[:]
+
+ return []
+
+ def unsubscribe(
+ self,
+ event_type: typing.Type[event_dispatcher.EventT_co],
+ callback: event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ ) -> None:
+ if event_type in self._listeners:
+ _LOGGER.debug(
+ "unsubscribing callback %s%s from event-type %s.%s",
+ getattr(callback, "__name__", ""),
+ reflect.resolve_signature(callback),
+ event_type.__module__,
+ event_type.__qualname__,
+ )
+ self._listeners[event_type].remove(callback) # type: ignore[arg-type]
+ if not self._listeners[event_type]:
+ del self._listeners[event_type]
+
+ def listen(
+ self, event_type: typing.Optional[typing.Type[event_dispatcher.EventT_co]] = None,
+ ) -> typing.Callable[
+ [event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]],
+ event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ ]:
+ def decorator(
+ callback: event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co],
+ ) -> event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_co]:
+ nonlocal event_type
+
+ signature = reflect.resolve_signature(callback)
+ params = signature.parameters.values()
+
+ if len(params) != 1:
+ raise TypeError("Event listener must have exactly one parameter, the event object.")
+
+ event_param = next(iter(params))
+
+ if event_type is None:
+ if event_param.annotation is event_param.empty:
+ raise TypeError("Must provide the event type in the @listen decorator or as a type hint!")
+
+ event_type = event_param.annotation
+
+ if not isinstance(event_type, type) or not issubclass(event_type, base_events.Event):
+ raise TypeError("Event type must derive from Event")
+
+ self.subscribe(event_type, callback, _nested=1)
+ return callback
+
+ return decorator
+
+ def dispatch(self, event: event_dispatcher.EventT_inv) -> asyncio.Future[typing.Any]:
+ if not isinstance(event, base_events.Event):
+ raise TypeError(f"Events must be subclasses of {base_events.Event.__name__}, not {type(event).__name__}")
+
+ # We only need to iterate through the MRO until we hit Event, as
+ # anything after that is random garbage we don't care about, as they do
+ # not describe event types. This improves efficiency as well.
+ mro = type(event).mro()
+
+ tasks: typing.List[typing.Coroutine[None, typing.Any, None]] = []
+
+ for cls in mro[: mro.index(base_events.Event) + 1]:
+
+ if cls in self._listeners:
+ for callback in self._listeners[cls]:
+ tasks.append(self._invoke_callback(callback, event))
+
+ if cls in self._waiters:
+ for predicate, future in self._waiters[cls]:
+ # noinspection PyTypeChecker
+ tasks.append(self._test_waiter(event, predicate, future)) # type: ignore[misc]
+
+ return asyncio.gather(*tasks) if tasks else aio.completed_future()
+
+ @staticmethod
+ async def _test_waiter(
+ event: event_dispatcher.EventT_inv,
+ predicate: event_dispatcher.PredicateT[event_dispatcher.EventT_inv],
+ future: asyncio.Future[event_dispatcher.EventT_inv],
+ ) -> None:
+ try:
+ result = predicate(event)
+ if asyncio.iscoroutine(result):
+ result = await result # type: ignore
+
+ if not result:
+ return
+
+ except Exception as ex:
+ future.set_exception(ex)
+ else:
+ future.set_result(event)
+
+ async def _invoke_callback(
+ self, callback: event_dispatcher.AsyncCallbackT[event_dispatcher.EventT_inv], event: event_dispatcher.EventT_inv
+ ) -> None:
+ try:
+ result = callback(event)
+ if asyncio.iscoroutine(result):
+ await result
+
+ except Exception as ex:
+ # Skip the first frame in logs, we don't care for it.
+ trio = type(ex), ex, ex.__traceback__.tb_next if ex.__traceback__ is not None else None
+
+ if base_events.is_no_recursive_throw_event(event):
+ _LOGGER.error("an exception occurred handling an event, but it has been ignored", exc_info=trio)
+ else:
+ _LOGGER.error("an exception occurred handling an event", exc_info=trio)
+ await self.dispatch(
+ base_events.ExceptionEvent(
+ app=self._app,
+ shard=getattr(event, "shard") if isinstance(event, shard_events.ShardEvent) else None,
+ exception=ex,
+ failed_event=event,
+ failed_callback=callback,
+ )
+ )
+
+ async def wait_for(
+ self,
+ event_type: typing.Type[event_dispatcher.EventT_co],
+ /,
+ timeout: typing.Union[float, int, None],
+ predicate: typing.Optional[event_dispatcher.PredicateT[event_dispatcher.EventT_co]] = None,
+ ) -> event_dispatcher.EventT_co:
+
+ if predicate is None:
+ predicate = _default_predicate
+
+ self._check_intents(event_type, 1)
+
+ future: asyncio.Future[event_dispatcher.EventT_co] = asyncio.get_event_loop().create_future()
+
+ try:
+ waiter_set = self._waiters[event_type]
+ except KeyError:
+ waiter_set = set()
+ self._waiters[event_type] = waiter_set
+
+ pair = (predicate, future)
+
+ waiter_set.add(pair) # type: ignore[arg-type]
+
+ try:
+ if timeout is not None:
+ return await asyncio.wait_for(future, timeout=timeout)
+ else:
+ return await future
+
+ finally:
+ waiter_set.remove(pair) # type: ignore[arg-type]
+ if not waiter_set:
+ del self._waiters[event_type]
diff --git a/hikari/impl/rate_limits.py b/hikari/impl/rate_limits.py
new file mode 100644
index 0000000000..af1f90270c
--- /dev/null
+++ b/hikari/impl/rate_limits.py
@@ -0,0 +1,500 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic lazy ratelimit systems for asyncio.
+
+See `hikari.impl.buckets` for HTTP-specific rate-limiting logic.
+"""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "BaseRateLimiter",
+ "BurstRateLimiter",
+ "ManualRateLimiter",
+ "WindowedBurstRateLimiter",
+ "ExponentialBackOff",
+]
+
+import abc
+import asyncio
+import logging
+import random
+import typing
+
+from hikari.utilities import date
+
+if typing.TYPE_CHECKING:
+ import types
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari.ratelimits")
+
+
+class BaseRateLimiter(abc.ABC):
+ """Base for any asyncio-based rate limiter being used.
+
+ Supports being used as a synchronous context manager.
+
+ !!! warning
+ Async context manager support is not supported and will not be supported.
+ """
+
+ __slots__: typing.Sequence[str] = ()
+
+ @abc.abstractmethod
+ def acquire(self) -> asyncio.Future[None]:
+ """Acquire permission to perform a task that needs to have rate limit management enforced.
+
+ Returns
+ -------
+ asyncio.Future[builtins.None]
+ A future that should be awaited. Once the future is complete, you
+ can proceed to execute your rate-limited task.
+ """
+
+ @abc.abstractmethod
+ def close(self) -> None:
+ """Close the rate limiter, cancelling any internal tasks that are executing."""
+
+ def __enter__(self) -> BaseRateLimiter:
+ return self
+
+ def __exit__(self, exc_type: typing.Type[Exception], exc_val: Exception, exc_tb: types.TracebackType) -> None:
+ self.close()
+
+
+class BurstRateLimiter(BaseRateLimiter, abc.ABC):
+ """Base implementation for a burst-based rate limiter.
+
+ This provides an internal queue and throttling placeholder, as well as
+ complete logic for safely aborting any pending tasks when being shut down.
+ """
+
+ __slots__: typing.Sequence[str] = ("name", "throttle_task", "queue", "_closed")
+
+ name: typing.Final[str]
+ """The name of the rate limiter."""
+
+ throttle_task: typing.Optional[asyncio.Task[typing.Any]]
+ """The throttling task, or `builtins.None` if it is not running."""
+
+ queue: typing.Final[typing.List[asyncio.Future[typing.Any]]]
+ """The queue of any futures under a rate limit."""
+
+ def __init__(self, name: str) -> None:
+ self.name = name
+ self.throttle_task = None
+ self.queue = []
+ self._closed = False
+
+ @abc.abstractmethod
+ def acquire(self) -> asyncio.Future[typing.Any]:
+ """Acquire time on this rate limiter.
+
+ The implementation should define this.
+
+ Returns
+ -------
+ asyncio.Future[typing.Any]
+ A future that should be immediately awaited. Once the await
+ completes, you are able to proceed with the operation that is
+ under this rate limit.
+ """
+
+ def close(self) -> None:
+ """Close the rate limiter, and shut down any pending tasks.
+
+ Once this is invoked, you should not reuse this object.
+ """
+ if self._closed:
+ return
+
+ if self.throttle_task is not None:
+ self.throttle_task.cancel()
+
+ failed_tasks = 0
+ while self.queue:
+ failed_tasks += 1
+ future = self.queue.pop(0)
+ # Make the future complete with an exception
+ future.cancel()
+
+ if failed_tasks:
+ _LOGGER.debug("%s rate limiter closed with %s pending tasks!", self.name, failed_tasks)
+ else:
+ _LOGGER.debug("%s rate limiter closed", self.name)
+ self._closed = True
+
+ @property
+ def is_empty(self) -> bool:
+ """Return `builtins.True` if no futures are on the queue being rate limited."""
+ return len(self.queue) == 0
+
+
+@typing.final
+class ManualRateLimiter(BurstRateLimiter):
+ """Rate limit handler for the global HTTP rate limit.
+
+ This is a non-preemptive rate limiting algorithm that will always return
+ completed futures until `ManualRateLimiter.throttle` is invoked. Once this
+ is invoked, any subsequent calls to `ManualRateLimiter.acquire` will return
+ incomplete futures that will be enqueued to an internal queue. A task will
+ be spun up to wait for a period of time given to the
+ `ManualRateLimiter.throttle`. Once that has passed, the lock will begin to
+ re-consume incomplete futures on the queue, completing them.
+
+ Triggering a throttle when it is already set will cancel the current
+ throttle task that is sleeping and replace it.
+
+ This is used to enforce the global HTTP rate limit that will occur
+ "randomly" during HTTP API interaction.
+
+ Expect random occurrences.
+ """
+
+ __slots__: typing.Sequence[str] = ()
+
+ def __init__(self) -> None:
+ super().__init__("global")
+
+ def acquire(self) -> asyncio.Future[typing.Any]:
+ """Acquire time on this rate limiter.
+
+ Returns
+ -------
+ asyncio.Future[typing.Any]
+ A future that should be immediately awaited. Once the await
+ completes, you are able to proceed with the operation that is
+ under this rate limit.
+ """
+ loop = asyncio.get_running_loop()
+ future = loop.create_future()
+ if self.throttle_task is not None:
+ self.queue.append(future)
+ else:
+ future.set_result(None)
+ return future
+
+ def throttle(self, retry_after: float) -> None:
+ """Perform the throttling rate limiter logic.
+
+ Iterates repeatedly while the queue is not empty, adhering to any
+ rate limits that occur in the mean time.
+
+ Parameters
+ ----------
+ retry_after : builtins.float
+ How long to sleep for before unlocking and releasing any futures
+ in the queue.
+
+ !!! note
+ This will invoke `ManualRateLimiter.unlock_later` as a scheduled
+ task in the future (it will not await it to finish).
+
+ When the `ManualRateLimiter.unlock_later` coroutine function
+ completes, it should be expected to set the `throttle_task` to
+ `builtins.None`. This means you can check if throttling is occurring
+ by checking if `throttle_task` is not `builtins.None`.
+
+ If this is invoked while another throttle is in progress, that one
+ is cancelled and a new one is started. This enables new rate limits
+ to override existing ones.
+ """
+ if self.throttle_task is not None:
+ self.throttle_task.cancel()
+
+ loop = asyncio.get_running_loop()
+ self.throttle_task = loop.create_task(self.unlock_later(retry_after))
+
+ async def unlock_later(self, retry_after: float) -> None:
+ """Sleeps for a while, then removes the lock.
+
+ Parameters
+ ----------
+ retry_after : builtins.float
+ How long to sleep for before unlocking and releasing any futures
+ in the queue.
+
+ !!! note
+ You should not need to invoke this directly. Call
+ `ManualRateLimiter.throttle` instead.
+
+ When the `ManualRateLimiter.unlock_later` coroutine function
+ completes, it should be expected to set the `throttle_task` to
+ `builtins.None`. This means you can check if throttling is occurring
+ by checking if `throttle_task` is not `builtins.None`.
+ """
+ _LOGGER.warning("you are being globally rate limited for %ss", retry_after)
+ await asyncio.sleep(retry_after)
+ while self.queue:
+ next_future = self.queue.pop(0)
+ next_future.set_result(None)
+ self.throttle_task = None
+
+
+class WindowedBurstRateLimiter(BurstRateLimiter):
+ """Windowed burst rate limiter.
+
+ Rate limiter for rate limits that last fixed periods of time with a
+ fixed number of times it can be used in that time frame.
+
+ To use this, you should call WindowedBurstRateLimiter.aquire` and await the
+ result immediately before performing your rate-limited task.
+
+ If the rate limit has been hit, acquiring time will return an incomplete
+ future that is placed on the internal queue. A throttle task is then spun up
+ if not already running that will be expected to provide some implementation
+ of backing off and sleeping for a given period of time until the limit has
+ passed, and then proceed to consume futures from the queue while adhering
+ to those rate limits.
+
+ If the throttle task is already running, the acquired future will always be
+ incomplete and enqueued regardless of whether the rate limit is actively
+ reached or not.
+
+ Acquiring a future from this limiter when no throttling task is running and
+ when the rate limit is not reached will always result in the task invoking
+ a drip and a completed future being returned.
+
+ Dripping is left to the implementation of this class, but will be expected
+ to provide some mechanism for updating the internal statistics to represent
+ that a unit has been placed into the bucket.
+ """
+
+ __slots__: typing.Sequence[str] = ("reset_at", "remaining", "limit", "period")
+
+ reset_at: float
+ """The `date.monotonic_timestamp` that the limit window ends at."""
+
+ remaining: int
+ """The number of `WindowedBurstRateLimiter.acquire`'s left in this window
+ before you will get rate limited.
+ """
+
+ period: float
+ """How long the window lasts for from the start in seconds."""
+
+ limit: int
+ """The maximum number of `WindowedBurstRateLimiter.acquire`'s allowed in
+ this time window.
+ """
+
+ def __init__(self, name: str, period: float, limit: int) -> None:
+ super().__init__(name)
+ self.reset_at = 0.0
+ self.remaining = 0
+ self.limit = limit
+ self.period = period
+
+ def acquire(self) -> asyncio.Future[typing.Any]:
+ """Acquire time on this rate limiter.
+
+ Returns
+ -------
+ asyncio.Future[typing.Any]
+ A future that should be immediately awaited. Once the await
+ completes, you are able to proceed with the operation that is
+ under this rate limit.
+ """
+ loop = asyncio.get_running_loop()
+ future = loop.create_future()
+
+ # If we are rate limited, delegate invoking this to the throttler and spin it up
+ # if it hasn't started. Likewise, if the throttle task is still running, we should
+ # delegate releasing the future to the throttler task so that we still process
+ # first-come-first-serve
+ if self.throttle_task is not None or self.is_rate_limited(date.monotonic()):
+ self.queue.append(future)
+ if self.throttle_task is None:
+ self.throttle_task = loop.create_task(self.throttle())
+ else:
+ self.drip()
+ future.set_result(None)
+
+ return future
+
+ def get_time_until_reset(self, now: float) -> float:
+ """Determine how long until the current rate limit is reset.
+
+ Parameters
+ ----------
+ now : builtins.float
+ The monotonic `date.monotonic_timestamp` timestamp.
+
+ !!! warning
+ Invoking this method will update the internal state if we were
+ previously rate limited, but at the given time are no longer under
+ that limit. This makes it imperative that you only pass the current
+ timestamp to this function, and not past or future timestamps. The
+ effects of doing the latter are undefined behaviour.
+
+ Returns
+ -------
+ builtins.float
+ The time left to sleep before the rate limit is reset. If no rate limit
+ is in effect, then this will return `0.0` instead.
+ """
+ if not self.is_rate_limited(now):
+ return 0.0
+ return self.reset_at - now
+
+ def is_rate_limited(self, now: float) -> bool:
+ """Determine if we are under a rate limit at the given time.
+
+ Parameters
+ ----------
+ now : builtins.float
+ The monotonic `date.monotonic_timestamp` timestamp.
+
+ Returns
+ -------
+ builtins.bool
+ `builtins.True` if we are being rate limited, or `builtins.False` if
+ we are not.
+
+ !!! warning
+ Invoking this method will update the internal state if we were
+ previously rate limited, but at the given time are no longer under
+ that limit. This makes it imperative that you only pass the current
+ timestamp to this function, and not past or future timestamps. The
+ effects of doing the latter are undefined behaviour.
+ """
+ if self.reset_at <= now:
+ self.remaining = self.limit
+ self.reset_at = now + self.period
+ return False
+
+ return self.remaining <= 0
+
+ def drip(self) -> None:
+ """Decrements the remaining counter."""
+ self.remaining -= 1
+
+ async def throttle(self) -> None:
+ """Perform the throttling rate limiter logic.
+
+ Iterates repeatedly while the queue is not empty, adhering to any
+ rate limits that occur in the mean time.
+
+ !!! note
+ You should usually not need to invoke this directly, but if you do,
+ ensure to call it using `asyncio.create_task`, and store the
+ task immediately in `throttle_task`.
+
+ When this coroutine function completes, it will set the
+ `throttle_task` to `builtins.None`. This means you can check if throttling
+ is occurring by checking if `throttle_task` is not `builtins.None`.
+ """
+ _LOGGER.debug(
+ "you are being rate limited on bucket %s, backing off for %ss",
+ self.name,
+ self.get_time_until_reset(date.monotonic()),
+ )
+
+ while self.queue:
+ sleep_for = self.get_time_until_reset(date.monotonic())
+ await asyncio.sleep(sleep_for)
+
+ while self.remaining > 0 and self.queue:
+ self.drip()
+ self.queue.pop(0).set_result(None)
+
+ self.throttle_task = None
+
+
+@typing.final
+class ExponentialBackOff:
+ r"""Implementation of an asyncio-compatible exponential back-off algorithm with random jitter.
+
+ .. math::
+
+ t_{backoff} = b^{i} + m \cdot \mathrm{rand}()
+
+ Such that \(t_{backoff}\) is the backoff time, \(b\) is the base,
+ \(i\) is the increment that increases by 1 for each invocation, and
+ \(m\) is the jitter multiplier. \(\mathrm{rand}()\) returns a value in
+ the range \([0,1]\).
+
+ Parameters
+ ----------
+ base : builtins.float
+ The base to use. Defaults to `2`.
+ maximum : builtins.float or builtins.None
+ If not `builtins.None`, then this is the max value the backoff can be
+ in a single iteration before an `asyncio.TimeoutError` is raised.
+ Defaults to `64` seconds.
+ jitter_multiplier : builtins.float
+ The multiplier for the random jitter. Defaults to `1`.
+ Set to `0` to disable jitter.
+ initial_increment : builtins.int
+ The initial increment to start at. Defaults to `0`.
+ """
+
+ __slots__: typing.Sequence[str] = ("base", "increment", "maximum", "jitter_multiplier")
+
+ base: typing.Final[float]
+ """The base to use. Defaults to 2."""
+
+ increment: int
+ """The current increment."""
+
+ maximum: typing.Optional[float]
+ """If not `builtins.None`, then this is the max value the backoff can be in a
+ single iteration before an `asyncio.TimeoutError` is raised.
+ """
+
+ jitter_multiplier: typing.Final[float]
+ """The multiplier for the random jitter.
+
+ This defaults to `1`. Set to `0` to disable jitter.
+ """
+
+ def __init__(
+ self,
+ base: float = 2,
+ maximum: typing.Optional[float] = 64,
+ jitter_multiplier: float = 1,
+ initial_increment: int = 0,
+ ) -> None:
+ self.base = base
+ self.maximum = maximum
+ self.increment = initial_increment
+ self.jitter_multiplier = jitter_multiplier
+
+ def __next__(self) -> float:
+ """Get the next back off to sleep by."""
+ value = self.base ** self.increment
+
+ self.increment += 1
+
+ if self.maximum is not None and value >= self.maximum:
+ raise asyncio.TimeoutError
+
+ value += random.random() * self.jitter_multiplier # nosec # noqa S311 rng for cryptography
+ return value
+
+ def __iter__(self) -> ExponentialBackOff:
+ """Return this object, as it is an iterator."""
+ return self
+
+ def reset(self) -> None:
+ """Reset the exponential back-off."""
+ self.increment = 0
diff --git a/hikari/impl/rest.py b/hikari/impl/rest.py
new file mode 100644
index 0000000000..7444100aee
--- /dev/null
+++ b/hikari/impl/rest.py
@@ -0,0 +1,2239 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Implementation of a V6 and V7 compatible HTTP API for Discord.
+
+This also includes implementations of `hikari.api.app.IApp` designed towards
+providing RESTful functionality.
+"""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "BasicLazyCachedTCPConnectorFactory",
+ "RESTApp",
+ "RESTClientImpl",
+]
+
+import asyncio
+import collections
+import contextlib
+import datetime
+import http
+import logging
+import math
+import os
+import re
+import typing
+
+import aiohttp
+import attr
+
+from hikari import config
+from hikari import errors
+from hikari import traits
+from hikari.api import rest as rest_api
+from hikari.impl import buckets
+from hikari.impl import entity_factory as entity_factory_impl
+from hikari.impl import rate_limits
+from hikari.impl import special_endpoints
+from hikari.models import channels
+from hikari.models import embeds as embeds_
+from hikari.models import emojis
+from hikari.models import guilds
+from hikari.models import users
+from hikari.utilities import constants
+from hikari.utilities import data_binding
+from hikari.utilities import date
+from hikari.utilities import files
+from hikari.utilities import iterators
+from hikari.utilities import net
+from hikari.utilities import routes
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+if typing.TYPE_CHECKING:
+ import concurrent.futures
+ import types
+
+ from hikari.api import entity_factory as entity_factory_
+ from hikari.models import applications
+ from hikari.models import audit_logs
+ from hikari.models import colors
+ from hikari.models import gateway
+ from hikari.models import invites
+ from hikari.models import messages as messages_
+ from hikari.models import permissions as permissions_
+ from hikari.models import voices
+ from hikari.models import webhooks
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari.rest")
+
+
+@typing.final
+class BasicLazyCachedTCPConnectorFactory(rest_api.ConnectorFactory):
+ """Lazy cached TCP connector factory."""
+
+ __slots__: typing.Sequence[str] = ("connector", "connector_kwargs")
+
+ def __init__(self, **kwargs: typing.Any) -> None:
+ self.connector: typing.Optional[aiohttp.TCPConnector] = None
+ self.connector_kwargs = kwargs
+
+ async def close(self) -> None:
+ if self.connector is not None:
+ await self.connector.close()
+ self.connector = None
+
+ def acquire(self) -> aiohttp.BaseConnector:
+ if self.connector is None:
+ self.connector = aiohttp.TCPConnector(**self.connector_kwargs)
+
+ return self.connector
+
+
+class _RESTProvider(traits.RESTAware):
+ __slots__: typing.Sequence[str] = ("_rest",)
+
+ def __init__(self, rest: typing.Callable[[], rest_api.RESTClient]) -> None:
+ self._rest = rest
+
+ @property
+ def rest(self) -> rest_api.RESTClient:
+ return self._rest()
+
+ @property
+ def http_settings(self) -> config.HTTPSettings:
+ return self._rest().http_settings
+
+ @property
+ def proxy_settings(self) -> config.ProxySettings:
+ return self._rest().proxy_settings
+
+
+class RESTApp(traits.ExecutorAware):
+ """The base for a HTTP-only Discord application.
+
+ This comprises of a shared TCP connector connection pool, and can have
+ `hikari.api.rest.IRESTApp` instances for specific credentials acquired
+ from it.
+
+ Parameters
+ ----------
+ connector_factory : ConnectorFactory or builtins.None
+ A factory that produces an `aiohttp.BaseConnector` when requested.
+
+ Defaults to a connector for a shared `aiohttp.TCPConnector` if
+ `builtins.None`.
+
+ The connector factory is expected to handle providing locks around
+ resources and caching any result as desired.
+ connector_owner : builtins.bool
+ If you created the connector yourself, set this to `builtins.True` if
+ you want this component to destroy the connector once closed. Otherwise,
+ `builtins.False` will prevent this and you will have to do this
+ manually. The latter is useful if you wish to maintain a shared
+ connection pool across your application with other non-Hikari
+ components.
+ debug : builtins.bool
+ If `builtins.True`, then much more information is logged each time a
+ request is made. Generally you do not need this to be on, so it will
+ default to `builtins.False` instead.
+ executor : concurrent.futures.Executor or builtins.None
+ The executor to use for blocking file IO operations. If `builtins.None`
+ is passed, then the default `concurrent.futures.ThreadPoolExecutor` for
+ the `asyncio.AbstractEventLoop` will be used instead.
+ http_settings : hikari.config.HTTPSettings or builtins.None
+ HTTP settings to use. Sane defaults are used if this is
+ `builtins.None`.
+ proxy_settings : hikari.config.ProxySettings or builtins.None
+ Proxy settings to use. If `builtins.None` then no proxy configuration
+ will be used.
+ url : str or hikari.utilities.undefined.UndefinedType
+ The base URL for the API. You can generally leave this as being
+ `undefined` and the correct default API base URL will be generated.
+ version : builtins.int
+ The Discord API version to use. Can be `6` (stable, default), or `7`
+ (undocumented development release).
+
+ !!! note
+ This event loop will be bound to a connector when the first call
+ to `acquire` is made.
+ """
+
+ __slots__: typing.Sequence[str] = (
+ "_connector_factory",
+ "_connector_owner",
+ "_debug",
+ "_event_loop",
+ "_executor",
+ "_http_settings",
+ "_proxy_settings",
+ "_url",
+ "_version",
+ )
+
+ def __init__(
+ self,
+ *,
+ connector_factory: typing.Optional[rest_api.ConnectorFactory] = None,
+ connector_owner: bool = True,
+ debug: bool = False,
+ executor: typing.Optional[concurrent.futures.Executor] = None,
+ http_settings: typing.Optional[config.HTTPSettings] = None,
+ proxy_settings: typing.Optional[config.ProxySettings] = None,
+ url: typing.Optional[str] = None,
+ version: int = 6,
+ ) -> None:
+ # Lazy initialized later, since we must initialize this in the event
+ # loop we run the application from, otherwise aiohttp throws complaints
+ # at us. Quart, amongst other libraries, causes issues with this by
+ # making a new event loop on startup, which means if we initialised
+ # the connector here and initialised this class in global scope, it
+ # would potentially end up using the wrong event loop and aiohttp
+ # would then fail when creating an HTTP request.
+ self._connector_factory: rest_api.ConnectorFactory = connector_factory or BasicLazyCachedTCPConnectorFactory()
+ self._connector_owner = connector_owner
+ self._debug = debug
+ self._event_loop: typing.Optional[asyncio.AbstractEventLoop] = None
+ self._executor = executor
+ self._http_settings = config.HTTPSettings() if http_settings is None else http_settings
+ self._proxy_settings = config.ProxySettings() if proxy_settings is None else proxy_settings
+ self._url = url
+ self._version = version
+
+ @property
+ def executor(self) -> typing.Optional[concurrent.futures.Executor]:
+ return self._executor
+
+ @property
+ def http_settings(self) -> config.HTTPSettings:
+ return self._http_settings
+
+ @property
+ def is_debug_enabled(self) -> bool:
+ return self._debug
+
+ @property
+ def proxy_settings(self) -> config.ProxySettings:
+ return self._proxy_settings
+
+ def acquire(self, token: str, token_type: str = constants.BEARER_TOKEN) -> rest_api.RESTClient:
+ loop = asyncio.get_running_loop()
+
+ if self._event_loop is None:
+ self._event_loop = loop
+
+ if loop != self._event_loop:
+ raise RuntimeError("Cannot use this object on a different event loop... please create a new instance.")
+
+ # Since we essentially mimic a fake App instance, we need to make a circular provider.
+ # We can achieve this using a lambda. This allows the entity factory to build models that
+ # are also REST-aware
+ entity_factory = entity_factory_impl.EntityFactoryImpl(_RESTProvider(lambda: rest_client))
+
+ rest_client = RESTClientImpl(
+ connector_factory=self._connector_factory,
+ connector_owner=self._connector_owner,
+ debug=self._debug,
+ entity_factory=entity_factory,
+ executor=self._executor,
+ http_settings=self._http_settings,
+ proxy_settings=self._proxy_settings,
+ token=token,
+ token_type=token_type,
+ rest_url=self._url,
+ version=self._version,
+ )
+
+ return rest_client
+
+ async def close(self) -> None:
+ if self._connector_owner:
+ await self._connector_factory.close()
+
+ async def __aenter__(self) -> RESTApp:
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: typing.Optional[typing.Type[BaseException]],
+ exc_val: typing.Optional[BaseException],
+ exc_tb: typing.Optional[types.TracebackType],
+ ) -> None:
+ await self.close()
+
+
+class RESTClientImpl(rest_api.RESTClient):
+ """Implementation of the V6 and V7-compatible Discord HTTP API.
+
+ This manages making HTTP/1.1 requests to the API and using the entity
+ factory within the passed application instance to deserialize JSON responses
+ to Pythonic data classes that are used throughout this library.
+
+ Parameters
+ ----------
+ connector_factory : ConnectorFactory or builtins.None
+ A factory that produces an `aiohttp.BaseConnector` when requested.
+
+ Defaults to a connector for a shared `aiohttp.TCPConnector` if
+ `builtins.None`.
+
+ The connector factory is expected to handle providing locks around
+ resources and caching any result as desired.
+ connector_owner : builtins.bool
+ If you created the connector yourself, set this to `builtins.True` if
+ you want this component to destroy the connector once closed. Otherwise,
+ `builtins.False` will prevent this and you will have to do this
+ manually. The latter is useful if you wish to maintain a shared
+ connection pool across your application with other non-Hikari
+ components.
+ debug : builtins.bool
+ If `builtins.True`, this will enable logging of each payload sent and
+ received, as well as information such as DNS cache hits and misses, and
+ other information useful for debugging this application. These logs will
+ be written as DEBUG log entries. For most purposes, this should be
+ left `builtins.False`.
+ entity_factory : hikari.api.entity_factory.EntityFactory
+ The entity factory to use.
+ executor : concurrent.futures.Executor or builtins.None
+ The executor to use for blocking IO. Defaults to the `asyncio` thread
+ pool if set to `builtins.None`.
+ token : hikari.utilities.undefined.UndefinedOr[builtins.str]
+ The bot or bearer token. If no token is to be used,
+ this can be undefined.
+ token_type : hikari.utilities.undefined.UndefinedOr[builtins.str]
+ The type of token in use. If no token is used, this can be ignored and
+ left to the default value. This can be `"Bot"` or `"Bearer"`.
+ rest_url : builtins.str
+ The HTTP API base URL. This can contain format-string specifiers to
+ interpolate information such as API version in use.
+ version : builtins.int
+ The API version to use. Currently only supports `6` and `7`.
+
+ !!! warning
+ The V7 API at the time of writing is considered to be experimental and
+ is undocumented. While currently almost identical in most places to the
+ V6 API, it should not be used unless you are sure you understand the
+ risk that it might break without warning.
+ """
+
+ __slots__: typing.Sequence[str] = (
+ "buckets",
+ "global_rate_limit",
+ "version",
+ "_client_session",
+ "_closed_event",
+ "_connector_factory",
+ "_connector_owner",
+ "_debug",
+ "_entity_factory",
+ "_executor",
+ "_http_settings",
+ "_proxy_settings",
+ "_rest_url",
+ "_token",
+ )
+
+ buckets: buckets.RESTBucketManager
+ """Bucket ratelimiter manager."""
+
+ global_rate_limit: rate_limits.ManualRateLimiter
+ """Global ratelimiter."""
+
+ version: int
+ """API version in-use."""
+
+ @attr.s(auto_exc=True, slots=True, repr=False, weakref_slot=False)
+ class _RetryRequest(RuntimeError):
+ ...
+
+ def __init__(
+ self,
+ *,
+ connector_factory: rest_api.ConnectorFactory,
+ connector_owner: bool,
+ debug: bool,
+ entity_factory: entity_factory_.EntityFactory,
+ executor: typing.Optional[concurrent.futures.Executor],
+ http_settings: config.HTTPSettings,
+ proxy_settings: config.ProxySettings,
+ token: typing.Optional[str],
+ token_type: typing.Optional[str],
+ rest_url: typing.Optional[str],
+ version: int,
+ ) -> None:
+ self.buckets = buckets.RESTBucketManager()
+ # We've been told in DAPI that this is per token.
+ self.global_rate_limit = rate_limits.ManualRateLimiter()
+ self.version = version
+
+ self._client_session: typing.Optional[aiohttp.ClientSession] = None
+ self._closed_event = asyncio.Event()
+ self._connector_factory = connector_factory
+ self._connector_owner = connector_owner
+ self._debug = debug
+ self._entity_factory = entity_factory
+ self._executor = executor
+ self._http_settings = http_settings
+ self._proxy_settings = proxy_settings
+
+ if token is None:
+ full_token = None
+ else:
+ if token_type is None:
+ token_type = constants.BOT_TOKEN
+
+ full_token = f"{token_type.title()} {token}"
+
+ self._token: typing.Optional[str] = full_token
+
+ if rest_url is None:
+ rest_url = constants.REST_API_URL
+
+ self._rest_url = rest_url.format(self)
+
+ @property
+ def http_settings(self) -> config.HTTPSettings:
+ return self._http_settings
+
+ @property
+ def proxy_settings(self) -> config.ProxySettings:
+ return self._proxy_settings
+
+ @typing.final
+ async def close(self) -> None:
+ """Close the HTTP client and any open HTTP connections."""
+ if self._client_session is not None:
+ await self._client_session.close()
+ self.global_rate_limit.close()
+ self.buckets.close()
+ self._closed_event.set()
+
+ async def __aenter__(self) -> RESTClientImpl:
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: typing.Optional[typing.Type[BaseException]],
+ exc_val: typing.Optional[BaseException],
+ exc_tb: typing.Optional[types.TracebackType],
+ ) -> None:
+ await self.close()
+
+ @typing.final
+ def _acquire_client_session(self) -> aiohttp.ClientSession:
+ if self._client_session is None:
+ self._closed_event.clear()
+ self._client_session = aiohttp.ClientSession(
+ # Should not need a lock, since we don't technically await anything.
+ connector=self._connector_factory.acquire(),
+ connector_owner=self._connector_owner,
+ version=aiohttp.HttpVersion11,
+ timeout=aiohttp.ClientTimeout(
+ total=self._http_settings.timeouts.total,
+ connect=self._http_settings.timeouts.acquire_and_connect,
+ sock_read=self._http_settings.timeouts.request_socket_read,
+ sock_connect=self._http_settings.timeouts.request_socket_connect,
+ ),
+ trust_env=self._proxy_settings.trust_env,
+ )
+
+ elif self._client_session.closed:
+ raise errors.HTTPClientClosedError
+
+ return self._client_session
+
+ @typing.final
+ async def _request(
+ self,
+ compiled_route: routes.CompiledRoute,
+ *,
+ query: typing.Optional[data_binding.StringMapBuilder] = None,
+ form: typing.Optional[aiohttp.FormData] = None,
+ json: typing.Union[data_binding.JSONObjectBuilder, data_binding.JSONArray, None] = None,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ no_auth: bool = False,
+ ) -> typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]:
+ # Make a ratelimit-protected HTTP request to a JSON endpoint and expect some form
+ # of JSON response. If an error occurs, the response body is returned in the
+ # raised exception as a bytes object. This is done since the differences between
+ # the V6 and V7 API error messages are not documented properly, and there are
+ # edge cases such as Cloudflare issues where we may receive arbitrary data in
+ # the response instead of a JSON object.
+
+ if not self.buckets.is_started:
+ self.buckets.start()
+
+ headers = data_binding.StringMapBuilder()
+ headers.setdefault(constants.USER_AGENT_HEADER, constants.HTTP_USER_AGENT)
+ headers.put(constants.X_RATELIMIT_PRECISION_HEADER, constants.MILLISECOND_PRECISION)
+
+ if self._token is not None and not no_auth:
+ headers[constants.AUTHORIZATION_HEADER] = self._token
+
+ headers.put(constants.X_AUDIT_LOG_REASON_HEADER, reason)
+
+ while True:
+ try:
+ url = compiled_route.create_url(self._rest_url)
+
+ # Wait for any rate-limits to finish.
+ await asyncio.gather(self.buckets.acquire(compiled_route), self.global_rate_limit.acquire())
+
+ uuid = date.uuid()
+
+ if self._debug:
+ headers_str = "\n".join(f"\t\t{name}:{value}" for name, value in headers.items())
+ _LOGGER.debug(
+ "%s %s %s\n\theaders:\n%s\n\tbody:\n\t\t%r",
+ uuid,
+ compiled_route.method,
+ url,
+ headers_str,
+ json,
+ )
+ else:
+ _LOGGER.debug("%s %s %s", uuid, compiled_route.method, url)
+
+ # Make the request.
+ session = self._acquire_client_session()
+ start = date.monotonic()
+ response = await session.request(
+ compiled_route.method,
+ url,
+ headers=headers,
+ params=query,
+ json=json,
+ data=form,
+ allow_redirects=self._http_settings.allow_redirects,
+ max_redirects=self._http_settings.max_redirects,
+ proxy=self._proxy_settings.url,
+ proxy_headers=self._proxy_settings.all_headers,
+ verify_ssl=self._http_settings.verify_ssl,
+ )
+ time_taken = (date.monotonic() - start) * 1_000
+
+ if self._debug:
+ headers_str = "\n".join(
+ f"\t\t{name.decode('utf-8')}:{value.decode('utf-8')}" for name, value in response.raw_headers
+ )
+ _LOGGER.debug(
+ "%s %s %s in %sms\n\theaders:\n%s\n\tbody:\n\t\t%r",
+ uuid,
+ response.status,
+ response.reason,
+ time_taken,
+ headers_str,
+ await response.read(),
+ )
+ else:
+ _LOGGER.debug("%s %s %s in %sms", uuid, response.status, response.reason, time_taken)
+
+ # Ensure we aren't rate limited, and update rate limiting headers where appropriate.
+ await self._parse_ratelimits(compiled_route, response)
+
+ # Don't bother processing any further if we got NO CONTENT. There's not anything
+ # to check.
+ if response.status == http.HTTPStatus.NO_CONTENT:
+ return None
+
+ # Handle the response.
+ if 200 <= response.status < 300:
+ if response.content_type == constants.APPLICATION_JSON:
+ # Only deserializing here stops Cloudflare shenanigans messing us around.
+ return data_binding.load_json(await response.read())
+
+ real_url = str(response.real_url)
+ raise errors.HTTPError(f"Expected JSON [{response.content_type=}, {real_url=}]")
+
+ await self._handle_error_response(response)
+
+ except self._RetryRequest:
+ continue
+
+ @staticmethod
+ @typing.final
+ async def _handle_error_response(response: aiohttp.ClientResponse) -> typing.NoReturn:
+ raise await net.generate_error_response(response)
+
+ @typing.final
+ async def _parse_ratelimits(self, compiled_route: routes.CompiledRoute, response: aiohttp.ClientResponse) -> None:
+ # Worth noting there is some bug on V6 that rate limits me immediately if I have an invalid token.
+ # https://github.com/discord/discord-api-docs/issues/1569
+
+ # Handle rate limiting.
+ resp_headers = response.headers
+ limit = int(resp_headers.get(constants.X_RATELIMIT_LIMIT_HEADER, "1"))
+ remaining = int(resp_headers.get(constants.X_RATELIMIT_REMAINING_HEADER, "1"))
+ bucket = resp_headers.get(constants.X_RATELIMIT_BUCKET_HEADER, "None")
+ reset_at = float(resp_headers.get(constants.X_RATELIMIT_RESET_HEADER, "0"))
+ reset_after = float(resp_headers.get(constants.X_RATELIMIT_RESET_AFTER_HEADER, "0"))
+ reset_date = datetime.datetime.fromtimestamp(reset_at, tz=datetime.timezone.utc)
+ now_date = date.rfc7231_datetime_string_to_datetime(resp_headers[constants.DATE_HEADER])
+
+ is_rate_limited = response.status == http.HTTPStatus.TOO_MANY_REQUESTS
+
+ self.buckets.update_rate_limits(
+ compiled_route=compiled_route,
+ bucket_header=bucket,
+ remaining_header=remaining,
+ limit_header=limit,
+ date_header=now_date,
+ reset_at_header=reset_date,
+ )
+
+ if not is_rate_limited:
+ return
+
+ if response.content_type != constants.APPLICATION_JSON:
+ # We don't know exactly what this could imply. It is likely Cloudflare interfering
+ # but I'd rather we just give up than do something resulting in multiple failed
+ # requests repeatedly.
+ raise errors.HTTPResponseError(
+ str(response.real_url),
+ http.HTTPStatus.TOO_MANY_REQUESTS,
+ response.headers,
+ await response.read(),
+ f"received rate limited response with unexpected response type {response.content_type}",
+ )
+
+ body = await response.json()
+ body_retry_after = float(body["retry_after"]) / 1_000
+
+ if body.get("global", False) is True:
+ self.global_rate_limit.throttle(body_retry_after)
+
+ _LOGGER.warning("you are being rate-limited globally - trying again after %ss", body_retry_after)
+ raise self._RetryRequest
+
+ # Discord have started applying ratelimits to operations on some endpoints
+ # based on specific fields used in the JSON body.
+ # This does not get reflected in the headers. The first we know is when we
+ # get a 429.
+ # The issue is that we may get the same response if Discord dynamically
+ # adjusts the bucket ratelimits.
+ #
+ # We have no mechanism for handing field-based ratelimits, so if we get
+ # to here, but notice remaining is greater than zero, we should just error.
+ #
+ # Worth noting we still ignore the retry_after in the body. I have no clue
+ # if there is some weird edge case where a bucket rate limit can occur on
+ # top of a non-global one, but in this case this check will misbehave and
+ # instead of erroring, will trigger a backoff that might be 10 minutes or
+ # more...
+
+ # I realise remaining should never be less than zero, but quite frankly, I don't
+ # trust that voodoo type stuff will not ever occur with that value from them...
+ if remaining <= 0:
+ # We can retry and we will then abide by the updated bucket ratelimits.
+ _LOGGER.debug(
+ "rate-limited on bucket %s at %s. This is a bucket discrepancy, so we will retry at %s",
+ bucket,
+ compiled_route,
+ reset_date,
+ )
+
+ # If the values are within 20% of eachother by relativistic tolerance, it is probably
+ # safe to retry the request, as they are likely the same value just with some
+ # measuring difference. 20% was used as a rounded figure.
+ if math.isclose(body_retry_after, reset_after, rel_tol=0.20):
+ raise self._RetryRequest
+
+ raise errors.RateLimitedError(
+ url=str(response.real_url),
+ route=compiled_route,
+ headers=response.headers,
+ raw_body=body,
+ retry_after=body_retry_after,
+ )
+
+ @staticmethod
+ @typing.final
+ def _generate_allowed_mentions(
+ mentions_everyone: undefined.UndefinedOr[bool],
+ user_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[users.PartialUser]], bool]
+ ],
+ role_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]], bool]
+ ],
+ ) -> data_binding.JSONObject:
+ parsed_mentions: typing.List[str] = []
+ allowed_mentions = {"parse": parsed_mentions}
+
+ if mentions_everyone is True:
+ parsed_mentions.append("everyone")
+
+ if user_mentions is True:
+ parsed_mentions.append("users")
+ elif isinstance(user_mentions, typing.Collection):
+ # Duplicates will cause discord to error.
+ snowflakes = {str(int(u)) for u in user_mentions}
+ allowed_mentions["users"] = list(snowflakes)
+
+ if role_mentions is True:
+ parsed_mentions.append("roles")
+ elif isinstance(role_mentions, typing.Collection):
+ # Duplicates will cause discord to error.
+ snowflakes = {str(int(r)) for r in role_mentions}
+ allowed_mentions["roles"] = list(snowflakes)
+
+ return allowed_mentions
+
+ async def fetch_channel(
+ self, channel: snowflake.SnowflakeishOr[channels.PartialChannel]
+ ) -> channels.PartialChannel:
+ route = routes.GET_CHANNEL.compile(channel=channel)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_channel(response)
+
+ async def edit_channel(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.GuildChannel],
+ /,
+ *,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ nsfw: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ bitrate: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ user_limit: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ rate_limit_per_user: undefined.UndefinedOr[date.Intervalish] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Sequence[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ parent_category: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.GuildCategory]] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> channels.PartialChannel:
+ route = routes.PATCH_CHANNEL.compile(channel=channel)
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ body.put("position", position)
+ body.put("topic", topic)
+ body.put("nsfw", nsfw)
+ body.put("bitrate", bitrate)
+ body.put("user_limit", user_limit)
+ body.put("rate_limit_per_user", rate_limit_per_user)
+ body.put_snowflake("parent_id", parent_category)
+ body.put_array(
+ "permission_overwrites",
+ permission_overwrites,
+ conversion=self._entity_factory.serialize_permission_overwrite,
+ )
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_channel(response)
+
+ async def delete_channel(self, channel: snowflake.SnowflakeishOr[channels.PartialChannel]) -> None:
+ route = routes.DELETE_CHANNEL.compile(channel=channel)
+ await self._request(route)
+
+ async def edit_permission_overwrites(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.GuildChannel],
+ target: typing.Union[
+ snowflake.Snowflakeish, users.PartialUser, guilds.PartialRole, channels.PermissionOverwrite
+ ],
+ *,
+ target_type: undefined.UndefinedOr[typing.Union[channels.PermissionOverwriteType, str]] = undefined.UNDEFINED,
+ allow: undefined.UndefinedOr[permissions_.Permissions] = undefined.UNDEFINED,
+ deny: undefined.UndefinedOr[permissions_.Permissions] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ if target_type is undefined.UNDEFINED:
+ if isinstance(target, users.PartialUser):
+ target_type = channels.PermissionOverwriteType.MEMBER
+ elif isinstance(target, guilds.Role):
+ target_type = channels.PermissionOverwriteType.ROLE
+ elif isinstance(target, channels.PermissionOverwrite):
+ target_type = target.type
+ else:
+ raise TypeError(
+ "Cannot determine the type of the target to update. Try specifying 'target_type' manually."
+ )
+
+ route = routes.PATCH_CHANNEL_PERMISSIONS.compile(channel=channel, overwrite=target)
+ body = data_binding.JSONObjectBuilder()
+ body.put("type", target_type)
+ body.put("allow", allow)
+ body.put("deny", deny)
+
+ await self._request(route, json=body, reason=reason)
+
+ async def delete_permission_overwrite(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.GuildChannel],
+ target: snowflake.SnowflakeishOr[
+ typing.Union[channels.PermissionOverwrite, guilds.PartialRole, users.PartialUser, snowflake.Snowflakeish]
+ ],
+ ) -> None:
+ route = routes.DELETE_CHANNEL_PERMISSIONS.compile(channel=channel, overwrite=target)
+ await self._request(route)
+
+ async def fetch_channel_invites(
+ self, channel: snowflake.SnowflakeishOr[channels.GuildChannel]
+ ) -> typing.Sequence[invites.InviteWithMetadata]:
+ route = routes.GET_CHANNEL_INVITES.compile(channel=channel)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_invite_with_metadata)
+
+ async def create_invite(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.GuildChannel],
+ *,
+ max_age: undefined.UndefinedOr[date.Intervalish] = undefined.UNDEFINED,
+ max_uses: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ temporary: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ unique: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ target_user: undefined.UndefinedOr[snowflake.SnowflakeishOr[users.PartialUser]] = undefined.UNDEFINED,
+ target_user_type: undefined.UndefinedOr[invites.TargetUserType] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> invites.InviteWithMetadata:
+ route = routes.POST_CHANNEL_INVITES.compile(channel=channel)
+ body = data_binding.JSONObjectBuilder()
+ body.put("max_age", max_age, conversion=date.timespan_to_int)
+ body.put("max_uses", max_uses)
+ body.put("temporary", temporary)
+ body.put("unique", unique)
+ body.put_snowflake("target_user_id", target_user)
+ body.put("target_user_type", target_user_type)
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_invite_with_metadata(response)
+
+ def trigger_typing(
+ self, channel: snowflake.SnowflakeishOr[channels.TextChannel]
+ ) -> special_endpoints.TypingIndicator:
+ return special_endpoints.TypingIndicator(
+ request_call=self._request, channel=channel, rest_closed_event=self._closed_event
+ )
+
+ async def fetch_pins(
+ self, channel: snowflake.SnowflakeishOr[channels.TextChannel]
+ ) -> typing.Sequence[messages_.Message]:
+ route = routes.GET_CHANNEL_PINS.compile(channel=channel)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_message)
+
+ async def pin_message(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ ) -> None:
+ route = routes.PUT_CHANNEL_PINS.compile(channel=channel, message=message)
+ await self._request(route)
+
+ async def unpin_message(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ ) -> None:
+ route = routes.DELETE_CHANNEL_PIN.compile(channel=channel, message=message)
+ await self._request(route)
+
+ def fetch_messages(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ *,
+ before: undefined.UndefinedOr[snowflake.SearchableSnowflakeishOr[snowflake.Unique]] = undefined.UNDEFINED,
+ after: undefined.UndefinedOr[snowflake.SearchableSnowflakeishOr[snowflake.Unique]] = undefined.UNDEFINED,
+ around: undefined.UndefinedOr[snowflake.SearchableSnowflakeishOr[snowflake.Unique]] = undefined.UNDEFINED,
+ ) -> iterators.LazyIterator[messages_.Message]:
+ if undefined.count(before, after, around) < 2:
+ raise TypeError("Expected no kwargs, or maximum of one of 'before', 'after', 'around'")
+
+ timestamp: undefined.UndefinedOr[str]
+
+ if before is not undefined.UNDEFINED:
+ direction = "before"
+ if isinstance(before, datetime.datetime):
+ timestamp = str(snowflake.Snowflake.from_datetime(before))
+ else:
+ timestamp = str(int(before))
+ elif after is not undefined.UNDEFINED:
+ direction = "after"
+ if isinstance(after, datetime.datetime):
+ timestamp = str(snowflake.Snowflake.from_datetime(after))
+ else:
+ timestamp = str(int(after))
+ elif around is not undefined.UNDEFINED:
+ direction = "around"
+ if isinstance(around, datetime.datetime):
+ timestamp = str(snowflake.Snowflake.from_datetime(around))
+ else:
+ timestamp = str(int(around))
+ else:
+ direction = "before"
+ timestamp = undefined.UNDEFINED
+
+ return special_endpoints.MessageIterator(
+ entity_factory=self._entity_factory,
+ request_call=self._request,
+ channel=channel,
+ direction=direction,
+ first_id=timestamp,
+ )
+
+ async def fetch_message(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ ) -> messages_.Message:
+ route = routes.GET_CHANNEL_MESSAGE.compile(channel=channel, message=message)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_message(response)
+
+ async def create_message(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
+ *,
+ embed: undefined.UndefinedOr[embeds_.Embed] = undefined.UNDEFINED,
+ attachment: undefined.UndefinedOr[files.Resourceish] = undefined.UNDEFINED,
+ attachments: undefined.UndefinedOr[typing.Sequence[files.Resourceish]] = undefined.UNDEFINED,
+ tts: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ user_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[users.PartialUser]], bool]
+ ] = undefined.UNDEFINED,
+ role_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]], bool]
+ ] = undefined.UNDEFINED,
+ ) -> messages_.Message:
+ if not undefined.count(attachment, attachments):
+ raise ValueError("You may only specify one of 'attachment' or 'attachments', not both")
+
+ if not isinstance(attachments, typing.Collection) and attachments is not undefined.UNDEFINED:
+ raise ValueError(
+ "You passed a non-collection to 'attachments', but this expects a collection. Maybe you meant to "
+ "use 'attachment' (singular) instead?"
+ )
+
+ route = routes.POST_CHANNEL_MESSAGES.compile(channel=channel)
+
+ if embed is undefined.UNDEFINED and isinstance(content, embeds_.Embed):
+ # Syntatic sugar, common mistake to accidentally send an embed
+ # as the content, so lets detect this and fix it for the user.
+ embed = content
+ content = undefined.UNDEFINED
+
+ elif undefined.count(attachment, attachments) == 2 and isinstance(
+ content, (files.Resource, files.RAWISH_TYPES, os.PathLike)
+ ):
+ # Syntatic sugar, common mistake to accidentally send an attachment
+ # as the content, so lets detect this and fix it for the user. This
+ # will still then work with normal implicit embed attachments as
+ # we work this out later.
+ attachment = content
+ content = undefined.UNDEFINED
+
+ body = data_binding.JSONObjectBuilder()
+ body.put("allowed_mentions", self._generate_allowed_mentions(mentions_everyone, user_mentions, role_mentions))
+ body.put("content", content, conversion=str)
+ body.put("nonce", nonce)
+ body.put("tts", tts)
+
+ final_attachments: typing.List[files.Resource[files.AsyncReader]] = []
+
+ if attachment is not undefined.UNDEFINED:
+ final_attachments.append(files.ensure_resource(attachment))
+ if attachments is not undefined.UNDEFINED:
+ final_attachments.extend([files.ensure_resource(a) for a in attachments])
+
+ if embed is not undefined.UNDEFINED:
+ embed_payload, embed_attachments = self._entity_factory.serialize_embed(embed)
+ body.put("embed", embed_payload)
+ final_attachments.extend(embed_attachments)
+
+ if final_attachments:
+ form = data_binding.URLEncodedForm()
+ form.add_field("payload_json", data_binding.dump_json(body), content_type=constants.APPLICATION_JSON)
+
+ stack = contextlib.AsyncExitStack()
+
+ try:
+ for i, attachment in enumerate(final_attachments):
+ stream = await stack.enter_async_context(attachment.stream(executor=self._executor))
+ form.add_field(
+ f"file{i}", stream, filename=stream.filename, content_type=constants.APPLICATION_OCTET_STREAM
+ )
+
+ raw_response = await self._request(route, form=form)
+ finally:
+ await stack.aclose()
+ else:
+ raw_response = await self._request(route, json=body)
+
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_message(response)
+
+ async def edit_message(
+ self,
+ channel: typing.Union[snowflake.SnowflakeishOr[channels.TextChannel]],
+ message: typing.Union[snowflake.SnowflakeishOr[messages_.Message]],
+ content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
+ *,
+ embed: undefined.UndefinedNoneOr[embeds_.Embed] = undefined.UNDEFINED,
+ mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ user_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[users.PartialUser]], bool]
+ ] = undefined.UNDEFINED,
+ role_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]], bool]
+ ] = undefined.UNDEFINED,
+ flags: undefined.UndefinedOr[messages_.MessageFlag] = undefined.UNDEFINED,
+ ) -> messages_.Message:
+ route = routes.PATCH_CHANNEL_MESSAGE.compile(channel=channel, message=message)
+ body = data_binding.JSONObjectBuilder()
+ body.put("flags", flags)
+ if undefined.count(mentions_everyone, user_mentions, role_mentions) != 3:
+ body.put(
+ "allowed_mentions", self._generate_allowed_mentions(mentions_everyone, user_mentions, role_mentions)
+ )
+
+ if embed is undefined.UNDEFINED and isinstance(content, embeds_.Embed):
+ # Syntatic sugar, common mistake to accidentally send an embed
+ # as the content, so lets detect this and fix it for the user.
+ embed = content
+ content = undefined.UNDEFINED
+
+ if content is not None:
+ body.put("content", content, conversion=str)
+ else:
+ body.put("content", None)
+
+ if isinstance(embed, embeds_.Embed):
+ embed_payload, _ = self._entity_factory.serialize_embed(embed)
+ body.put("embed", embed_payload)
+ elif embed is None:
+ body.put("embed", None)
+
+ raw_response = await self._request(route, json=body)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_message(response)
+
+ async def delete_message(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ ) -> None:
+ route = routes.DELETE_CHANNEL_MESSAGE.compile(channel=channel, message=message)
+ await self._request(route)
+
+ async def delete_messages(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ /,
+ *messages: snowflake.SnowflakeishOr[messages_.Message],
+ ) -> None:
+ route = routes.POST_DELETE_CHANNEL_MESSAGES_BULK.compile(channel=channel)
+
+ pending: typing.Deque[snowflake.SnowflakeishOr[messages_.Message]] = collections.deque(messages)
+ deleted: typing.Deque[snowflake.SnowflakeishOr[messages_.Message]] = collections.deque()
+
+ while pending:
+ # Discord only allows 2-100 messages in the BULK_DELETE endpoint. Because of that,
+ # if the user wants 101 messages deleted, we will post 100 messages in bulk delete
+ # and then the last message in a normal delete.
+ # Along with this, the bucket size for v6 and v7 seems to be a bit restrictive. As of
+ # 30th July 2020, this endpoint returned the following headers when being ratelimited:
+ # x-ratelimit-bucket b05c0d8c2ab83895085006a8eae073a3
+ # x-ratelimit-limit 1
+ # x-ratelimit-remaining 0
+ # x-ratelimit-reset 1596033974.096
+ # x-ratelimit-reset-after 3.000
+ # This kind of defeats the point of asynchronously gathering any of these
+ # in the first place really. To save clogging up the event loop
+ # (albeit at a cost of maybe a couple-dozen milliseconds per call),
+ # I am just gonna invoke these sequentially instead.
+ try:
+ if len(pending) == 1:
+ message = pending.popleft()
+ await self.delete_message(channel, message)
+ deleted.append(message)
+ else:
+ body = data_binding.JSONObjectBuilder()
+ chunk = [pending.popleft() for _ in range(min(100, len(pending)))]
+ body.put_snowflake_array("messages", chunk)
+ await self._request(route, json=body)
+ deleted += chunk
+ except Exception as ex:
+ raise errors.BulkDeleteError(deleted, pending) from ex
+
+ # Custom emoji mentions are in the format of <:name:id> for static emoji, or
+ # for animated emoji.
+ _CUSTOM_EMOJI_PATTERN: typing.Final[typing.ClassVar[re.Pattern[str]]] = re.compile(r"")
+
+ def _transform_emoji_to_url_format(self, emoji: emojis.Emojiish) -> str:
+ # Given an emojiish, check if it is a valid custom emoji mention. If it
+ # is, then convert it to the name:id format (remove the wrapping
+ # characters), then return it. If the emoji is an emojis.CustomEmoji
+ # directly, then get the url_name of it. All other emojis and objects
+ # can just be cast to string, as they are probably unicode emoji objects
+ # or unicode emoji strings.
+ if isinstance(emoji, emojis.CustomEmoji):
+ return emoji.url_name
+
+ if isinstance(emoji, str) and (custom_mention_match := self._CUSTOM_EMOJI_PATTERN.match(emoji)) is not None:
+ # False positive in PyCharm, yet again.
+ # noinspection PyUnboundLocalVariable
+ return custom_mention_match.group(1)
+
+ return str(emoji)
+
+ async def add_reaction(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ emoji: emojis.Emojiish,
+ ) -> None:
+ route = routes.PUT_MY_REACTION.compile(
+ emoji=self._transform_emoji_to_url_format(emoji), channel=channel, message=message,
+ )
+ await self._request(route)
+
+ async def delete_my_reaction(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ emoji: emojis.Emojiish,
+ ) -> None:
+ route = routes.DELETE_MY_REACTION.compile(
+ emoji=self._transform_emoji_to_url_format(emoji), channel=channel, message=message,
+ )
+ await self._request(route)
+
+ async def delete_all_reactions_for_emoji(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ emoji: emojis.Emojiish,
+ ) -> None:
+ route = routes.DELETE_REACTION_EMOJI.compile(
+ emoji=self._transform_emoji_to_url_format(emoji), channel=channel, message=message,
+ )
+ await self._request(route)
+
+ async def delete_reaction(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ emoji: emojis.Emojiish,
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ ) -> None:
+ route = routes.DELETE_REACTION_USER.compile(
+ emoji=self._transform_emoji_to_url_format(emoji), channel=channel, message=message, user=user,
+ )
+ await self._request(route)
+
+ async def delete_all_reactions(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ ) -> None:
+ route = routes.DELETE_ALL_REACTIONS.compile(channel=channel, message=message)
+ await self._request(route)
+
+ def fetch_reactions_for_emoji(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages_.Message],
+ emoji: emojis.Emojiish,
+ ) -> iterators.LazyIterator[users.User]:
+ return special_endpoints.ReactorIterator(
+ entity_factory=self._entity_factory,
+ request_call=self._request,
+ channel=channel,
+ message=message,
+ emoji=self._transform_emoji_to_url_format(emoji),
+ )
+
+ async def create_webhook(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ name: str,
+ *,
+ avatar: typing.Optional[files.Resourceish] = None,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> webhooks.Webhook:
+ route = routes.POST_CHANNEL_WEBHOOKS.compile(channel=channel)
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+
+ if avatar is not None:
+ avatar_resource = files.ensure_resource(avatar)
+ async with avatar_resource.stream(executor=self._executor) as stream:
+ body.put("avatar", await stream.data_uri())
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_webhook(response)
+
+ async def fetch_webhook(
+ self,
+ webhook: snowflake.SnowflakeishOr[webhooks.Webhook],
+ *,
+ token: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> webhooks.Webhook:
+ if token is undefined.UNDEFINED:
+ route = routes.GET_WEBHOOK.compile(webhook=webhook)
+ no_auth = False
+ else:
+ route = routes.GET_WEBHOOK_WITH_TOKEN.compile(webhook=webhook, token=token)
+ no_auth = True
+
+ raw_response = await self._request(route, no_auth=no_auth)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_webhook(response)
+
+ async def fetch_channel_webhooks(
+ self, channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ ) -> typing.Sequence[webhooks.Webhook]:
+ route = routes.GET_CHANNEL_WEBHOOKS.compile(channel=channel)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_webhook)
+
+ async def fetch_guild_webhooks(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ ) -> typing.Sequence[webhooks.Webhook]:
+ route = routes.GET_GUILD_WEBHOOKS.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_webhook)
+
+ async def edit_webhook(
+ self,
+ webhook: snowflake.SnowflakeishOr[webhooks.Webhook],
+ *,
+ token: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ avatar: undefined.UndefinedNoneOr[files.Resourceish] = undefined.UNDEFINED,
+ channel: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.TextChannel]] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> webhooks.Webhook:
+ if token is undefined.UNDEFINED:
+ route = routes.PATCH_WEBHOOK.compile(webhook=webhook)
+ no_auth = False
+ else:
+ route = routes.PATCH_WEBHOOK_WITH_TOKEN.compile(webhook=webhook, token=token)
+ no_auth = True
+
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ body.put_snowflake("channel", channel)
+
+ if avatar is None:
+ body.put("avatar", None)
+ elif avatar is not undefined.UNDEFINED:
+ avatar_resource = files.ensure_resource(avatar)
+ async with avatar_resource.stream(executor=self._executor) as stream:
+ body.put("avatar", await stream.data_uri())
+
+ raw_response = await self._request(route, json=body, reason=reason, no_auth=no_auth)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_webhook(response)
+
+ async def delete_webhook(
+ self,
+ webhook: snowflake.SnowflakeishOr[webhooks.Webhook],
+ *,
+ token: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ if token is undefined.UNDEFINED:
+ route = routes.DELETE_WEBHOOK.compile(webhook=webhook)
+ no_auth = False
+ else:
+ route = routes.DELETE_WEBHOOK_WITH_TOKEN.compile(webhook=webhook, token=token)
+ no_auth = True
+
+ await self._request(route, no_auth=no_auth)
+
+ async def execute_webhook(
+ self,
+ webhook: snowflake.SnowflakeishOr[webhooks.Webhook],
+ token: str,
+ content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
+ *,
+ username: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ avatar_url: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ embed: undefined.UndefinedOr[embeds_.Embed] = undefined.UNDEFINED,
+ embeds: undefined.UndefinedOr[typing.Sequence[embeds_.Embed]] = undefined.UNDEFINED,
+ attachment: undefined.UndefinedOr[files.Resourceish] = undefined.UNDEFINED,
+ attachments: undefined.UndefinedOr[typing.Sequence[files.Resourceish]] = undefined.UNDEFINED,
+ tts: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ user_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[users.PartialUser]], bool]
+ ] = undefined.UNDEFINED,
+ role_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]], bool]
+ ] = undefined.UNDEFINED,
+ ) -> messages_.Message:
+ if not undefined.count(attachment, attachments):
+ raise ValueError("You may only specify one of 'attachment' or 'attachments', not both")
+
+ if not undefined.count(embed, embeds):
+ raise ValueError("You may only specify one of 'embed' or 'embeds', not both")
+
+ if not isinstance(embeds, typing.Collection) and embeds is not undefined.UNDEFINED:
+ raise TypeError(
+ "You passed a non collection to 'embeds', but this expects a collection. Maybe you meant to "
+ "use 'embed' (singular) instead?"
+ )
+
+ if not isinstance(attachments, typing.Collection) and attachments is not undefined.UNDEFINED:
+ raise TypeError(
+ "You passed a non collection to 'attachments', but this expects a collection. Maybe you meant to "
+ "use 'attachment' (singular) instead?"
+ )
+
+ if undefined.count(embed, embeds) == 2 and isinstance(content, embeds_.Embed):
+ # Syntatic sugar, common mistake to accidentally send an embed
+ # as the content, so lets detect this and fix it for the user.
+ embed = content
+ content = undefined.UNDEFINED
+
+ elif undefined.count(attachment, attachments) == 2 and isinstance(
+ content, (files.Resource, files.RAWISH_TYPES, os.PathLike)
+ ):
+ # Syntatic sugar, common mistake to accidentally send an attachment
+ # as the content, so lets detect this and fix it for the user. This
+ # will still then work with normal implicit embed attachments as
+ # we work this out later.
+ attachment = content
+ content = undefined.UNDEFINED
+
+ route = routes.POST_WEBHOOK_WITH_TOKEN.compile(webhook=webhook, token=token)
+
+ final_attachments: typing.List[files.Resource[files.AsyncReader]] = []
+ if attachment is not undefined.UNDEFINED:
+ final_attachments.append(files.ensure_resource(attachment))
+ if attachments is not undefined.UNDEFINED:
+ final_attachments.extend([files.ensure_resource(a) for a in attachments])
+
+ serialized_embeds: data_binding.JSONArray = []
+
+ if embeds is not undefined.UNDEFINED:
+ for embed in embeds:
+ embed_payload, embed_attachments = self._entity_factory.serialize_embed(embed)
+ serialized_embeds.append(embed_payload)
+ final_attachments.extend(embed_attachments)
+
+ body = data_binding.JSONObjectBuilder()
+ body.put("mentions", self._generate_allowed_mentions(mentions_everyone, user_mentions, role_mentions))
+ body.put("content", content, conversion=str)
+ body.put("embeds", serialized_embeds)
+ body.put("username", username)
+ body.put("avatar_url", avatar_url)
+ body.put("tts", tts)
+ query = data_binding.StringMapBuilder()
+ query.put("wait", True)
+
+ if final_attachments:
+ form = data_binding.URLEncodedForm()
+ form.add_field("payload_json", data_binding.dump_json(body), content_type=constants.APPLICATION_JSON)
+
+ stack = contextlib.AsyncExitStack()
+
+ try:
+ for i, attachment in enumerate(final_attachments):
+ stream = await stack.enter_async_context(attachment.stream(executor=self._executor))
+ form.add_field(
+ f"file{i}", stream, filename=stream.filename, content_type=constants.APPLICATION_OCTET_STREAM
+ )
+
+ raw_response = await self._request(route, query=query, form=form, no_auth=True)
+ finally:
+ await stack.aclose()
+ else:
+ raw_response = await self._request(route, query=query, json=body, no_auth=True)
+
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_message(response)
+
+ async def fetch_gateway_url(self) -> str:
+ route = routes.GET_GATEWAY.compile()
+ # This doesn't need authorization.
+ raw_response = await self._request(route, no_auth=True)
+ response = typing.cast("typing.Mapping[str, str]", raw_response)
+ return response["url"]
+
+ async def fetch_gateway_bot(self) -> gateway.GatewayBot:
+ route = routes.GET_GATEWAY_BOT.compile()
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_gateway_bot(response)
+
+ async def fetch_invite(self, invite: invites.Inviteish) -> invites.Invite:
+ route = routes.GET_INVITE.compile(invite_code=invite if isinstance(invite, str) else invite.code)
+ query = data_binding.StringMapBuilder()
+ query.put("with_counts", True)
+ raw_response = await self._request(route, query=query)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_invite(response)
+
+ async def delete_invite(self, invite: invites.Inviteish) -> None:
+ route = routes.DELETE_INVITE.compile(invite_code=invite if isinstance(invite, str) else invite.code)
+ await self._request(route)
+
+ async def fetch_my_user(self) -> users.OwnUser:
+ route = routes.GET_MY_USER.compile()
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_my_user(response)
+
+ async def edit_my_user(
+ self,
+ *,
+ username: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ avatar: undefined.UndefinedNoneOr[files.Resourceish] = undefined.UNDEFINED,
+ ) -> users.OwnUser:
+ route = routes.PATCH_MY_USER.compile()
+ body = data_binding.JSONObjectBuilder()
+ body.put("username", username)
+
+ if avatar is None:
+ body.put("avatar", None)
+ elif avatar is not undefined.UNDEFINED:
+ avatar_resource = files.ensure_resource(avatar)
+ async with avatar_resource.stream(executor=self._executor) as stream:
+ body.put("avatar", await stream.data_uri())
+
+ raw_response = await self._request(route, json=body)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_my_user(response)
+
+ async def fetch_my_connections(self) -> typing.Sequence[applications.OwnConnection]:
+ route = routes.GET_MY_CONNECTIONS.compile()
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_own_connection)
+
+ def fetch_my_guilds(
+ self,
+ *,
+ newest_first: bool = False,
+ start_at: undefined.UndefinedOr[snowflake.SearchableSnowflakeishOr[guilds.PartialGuild]] = undefined.UNDEFINED,
+ ) -> iterators.LazyIterator[applications.OwnGuild]:
+ if start_at is undefined.UNDEFINED:
+ start_at = snowflake.Snowflake.max() if newest_first else snowflake.Snowflake.min()
+ elif isinstance(start_at, datetime.datetime):
+ start_at = snowflake.Snowflake.from_datetime(start_at)
+ else:
+ start_at = int(start_at)
+
+ return special_endpoints.OwnGuildIterator(
+ entity_factory=self._entity_factory,
+ request_call=self._request,
+ newest_first=newest_first,
+ first_id=str(start_at),
+ )
+
+ async def leave_guild(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild], /) -> None:
+ route = routes.DELETE_MY_GUILD.compile(guild=guild)
+ await self._request(route)
+
+ async def create_dm_channel(
+ self, user: snowflake.SnowflakeishOr[users.PartialUser], /
+ ) -> channels.PrivateTextChannel:
+ route = routes.POST_MY_CHANNELS.compile()
+ body = data_binding.JSONObjectBuilder()
+ body.put_snowflake("recipient_id", user)
+ raw_response = await self._request(route, json=body)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_private_text_channel(response)
+
+ async def fetch_application(self) -> applications.Application:
+ route = routes.GET_MY_APPLICATION.compile()
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_application(response)
+
+ async def add_user_to_guild(
+ self,
+ access_token: str,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ *,
+ nick: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ roles: undefined.UndefinedOr[
+ typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]]
+ ] = undefined.UNDEFINED,
+ mute: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ deaf: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ ) -> typing.Optional[guilds.Member]:
+ route = routes.PUT_GUILD_MEMBER.compile(guild=guild, user=user)
+ body = data_binding.JSONObjectBuilder()
+ body.put("access_token", access_token)
+ body.put("nick", nick)
+ body.put("mute", mute)
+ body.put("deaf", deaf)
+ body.put_snowflake_array("roles", roles)
+
+ if (raw_response := await self._request(route, json=body)) is not None:
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_member(response, guild_id=snowflake.Snowflake(guild))
+ else:
+ # User already is in the guild.
+ return None
+
+ async def fetch_voice_regions(self) -> typing.Sequence[voices.VoiceRegion]:
+ route = routes.GET_VOICE_REGIONS.compile()
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_voice_region)
+
+ async def fetch_user(self, user: snowflake.SnowflakeishOr[users.PartialUser]) -> users.User:
+ route = routes.GET_USER.compile(user=user)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_user(response)
+
+ def fetch_audit_log(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ before: undefined.UndefinedOr[snowflake.SearchableSnowflakeishOr[snowflake.Unique]] = undefined.UNDEFINED,
+ user: undefined.UndefinedOr[snowflake.SnowflakeishOr[users.PartialUser]] = undefined.UNDEFINED,
+ event_type: undefined.UndefinedOr[audit_logs.AuditLogEventType] = undefined.UNDEFINED,
+ ) -> iterators.LazyIterator[audit_logs.AuditLog]:
+
+ timestamp: undefined.UndefinedOr[str]
+ if before is undefined.UNDEFINED:
+ timestamp = undefined.UNDEFINED
+ elif isinstance(before, datetime.datetime):
+ timestamp = str(snowflake.Snowflake.from_datetime(before))
+ else:
+ timestamp = str(int(before))
+
+ return special_endpoints.AuditLogIterator(
+ entity_factory=self._entity_factory,
+ request_call=self._request,
+ guild=guild,
+ before=timestamp,
+ user=user,
+ action_type=event_type,
+ )
+
+ async def fetch_emoji(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ # This is an emoji ID, which is the URL-safe emoji name, not the snowflake alone.
+ # likewise this only is valid for custom emojis, unicode emojis make little sense here.
+ emoji: typing.Union[str, emojis.CustomEmoji],
+ ) -> emojis.KnownCustomEmoji:
+ route = routes.GET_GUILD_EMOJI.compile(guild=guild, emoji=self._transform_emoji_to_url_format(emoji))
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_known_custom_emoji(response, guild_id=snowflake.Snowflake(guild))
+
+ async def fetch_guild_emojis(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]
+ ) -> typing.Sequence[emojis.KnownCustomEmoji]:
+ route = routes.GET_GUILD_EMOJIS.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(
+ response, self._entity_factory.deserialize_known_custom_emoji, guild_id=snowflake.Snowflake(guild)
+ )
+
+ async def create_emoji(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ name: str,
+ image: files.Resourceish,
+ *,
+ roles: undefined.UndefinedOr[
+ typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]]
+ ] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> emojis.KnownCustomEmoji:
+ route = routes.POST_GUILD_EMOJIS.compile(guild=guild)
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ image_resource = files.ensure_resource(image)
+ async with image_resource.stream(executor=self._executor) as stream:
+ body.put("image", await stream.data_uri())
+
+ body.put_snowflake_array("roles", roles)
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_known_custom_emoji(response, guild_id=snowflake.Snowflake(guild))
+
+ async def edit_emoji(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ # This is an emoji ID, which is the URL-safe emoji name, not the snowflake alone.
+ # likewise this only is valid for custom emojis, unicode emojis make little sense here.
+ emoji: typing.Union[str, emojis.CustomEmoji],
+ *,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ roles: undefined.UndefinedOr[
+ typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]]
+ ] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> emojis.KnownCustomEmoji:
+ route = routes.PATCH_GUILD_EMOJI.compile(guild=guild, emoji=self._transform_emoji_to_url_format(emoji))
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ body.put_snowflake_array("roles", roles)
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_known_custom_emoji(response, guild_id=snowflake.Snowflake(guild))
+
+ async def delete_emoji(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ # This is an emoji ID, which is the URL-safe emoji name, not the snowflake alone.
+ # likewise this only is valid for custom emojis, unicode emojis make little sense here.
+ emoji: typing.Union[str, emojis.CustomEmoji],
+ ) -> None:
+ route = routes.DELETE_GUILD_EMOJI.compile(guild=guild, emoji=self._transform_emoji_to_url_format(emoji))
+ await self._request(route)
+
+ def guild_builder(self, name: str, /) -> special_endpoints.GuildBuilder:
+ return special_endpoints.GuildBuilder(
+ entity_factory=self._entity_factory, executor=self._executor, request_call=self._request, name=name
+ )
+
+ async def fetch_guild(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]) -> guilds.RESTGuild:
+ route = routes.GET_GUILD.compile(guild=guild)
+ query = data_binding.StringMapBuilder()
+ query.put("with_counts", True)
+ raw_response = await self._request(route, query=query)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_rest_guild(response)
+
+ async def fetch_guild_preview(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]) -> guilds.GuildPreview:
+ route = routes.GET_GUILD_PREVIEW.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_guild_preview(response)
+
+ async def edit_guild(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ region: undefined.UndefinedOr[voices.VoiceRegionish] = undefined.UNDEFINED,
+ verification_level: undefined.UndefinedOr[guilds.GuildVerificationLevel] = undefined.UNDEFINED,
+ default_message_notifications: undefined.UndefinedOr[
+ guilds.GuildMessageNotificationsLevel
+ ] = undefined.UNDEFINED,
+ explicit_content_filter_level: undefined.UndefinedOr[
+ guilds.GuildExplicitContentFilterLevel
+ ] = undefined.UNDEFINED,
+ afk_channel: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.GuildVoiceChannel]] = undefined.UNDEFINED,
+ afk_timeout: undefined.UndefinedOr[date.Intervalish] = undefined.UNDEFINED,
+ icon: undefined.UndefinedNoneOr[files.Resourceish] = undefined.UNDEFINED,
+ owner: undefined.UndefinedOr[snowflake.SnowflakeishOr[users.PartialUser]] = undefined.UNDEFINED,
+ splash: undefined.UndefinedNoneOr[files.Resourceish] = undefined.UNDEFINED,
+ banner: undefined.UndefinedNoneOr[files.Resourceish] = undefined.UNDEFINED,
+ system_channel: undefined.UndefinedNoneOr[
+ snowflake.SnowflakeishOr[channels.GuildTextChannel]
+ ] = undefined.UNDEFINED,
+ rules_channel: undefined.UndefinedNoneOr[
+ snowflake.SnowflakeishOr[channels.GuildTextChannel]
+ ] = undefined.UNDEFINED,
+ public_updates_channel: undefined.UndefinedNoneOr[
+ snowflake.SnowflakeishOr[channels.GuildTextChannel]
+ ] = undefined.UNDEFINED,
+ preferred_locale: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> guilds.RESTGuild:
+ route = routes.PATCH_GUILD.compile(guild=guild)
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ body.put("region", region, conversion=str)
+ body.put("verification", verification_level)
+ body.put("notifications", default_message_notifications)
+ body.put("explicit_content_filter", explicit_content_filter_level)
+ body.put("afk_timeout", afk_timeout)
+ body.put("preferred_locale", preferred_locale, conversion=str)
+ body.put_snowflake("afk_channel_id", afk_channel)
+ body.put_snowflake("owner_id", owner)
+ body.put_snowflake("system_channel_id", system_channel)
+ body.put_snowflake("rules_channel_id", rules_channel)
+ body.put_snowflake("public_updates_channel_id", public_updates_channel)
+
+ tasks: typing.List[asyncio.Task[str]] = []
+
+ if icon is None:
+ body.put("icon", None)
+ elif icon is not undefined.UNDEFINED:
+ icon_resource = files.ensure_resource(icon)
+ async with icon_resource.stream(executor=self._executor) as stream:
+ task = asyncio.create_task(stream.data_uri())
+ task.add_done_callback(lambda future: body.put("icon", future.result()))
+ tasks.append(task)
+
+ if splash is None:
+ body.put("splash", None)
+ elif splash is not undefined.UNDEFINED:
+ splash_resource = files.ensure_resource(splash)
+ async with splash_resource.stream(executor=self._executor) as stream:
+ task = asyncio.create_task(stream.data_uri())
+ task.add_done_callback(lambda future: body.put("splash", future.result()))
+ tasks.append(task)
+
+ if banner is None:
+ body.put("banner", None)
+ elif banner is not undefined.UNDEFINED:
+ banner_resource = files.ensure_resource(banner)
+ async with banner_resource.stream(executor=self._executor) as stream:
+ task = asyncio.create_task(stream.data_uri())
+ task.add_done_callback(lambda future: body.put("banner", future.result()))
+ tasks.append(task)
+
+ await asyncio.gather(*tasks)
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_rest_guild(response)
+
+ async def delete_guild(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]) -> None:
+ route = routes.DELETE_GUILD.compile(guild=guild)
+ await self._request(route)
+
+ async def fetch_guild_channels(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]
+ ) -> typing.Sequence[channels.GuildChannel]:
+ route = routes.GET_GUILD_CHANNELS.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ channel_sequence = data_binding.cast_json_array(response, self._entity_factory.deserialize_channel)
+ # Will always be guild channels unless Discord messes up severely on something!
+ return typing.cast("typing.Sequence[channels.GuildChannel]", channel_sequence)
+
+ async def create_guild_text_channel(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ name: str,
+ *,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ nsfw: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ rate_limit_per_user: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Sequence[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ category: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.GuildCategory]] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> channels.GuildTextChannel:
+ channel = await self._create_guild_channel(
+ guild,
+ name,
+ channels.ChannelType.GUILD_TEXT,
+ position=position,
+ topic=topic,
+ nsfw=nsfw,
+ rate_limit_per_user=rate_limit_per_user,
+ permission_overwrites=permission_overwrites,
+ category=category,
+ reason=reason,
+ )
+ return typing.cast(channels.GuildTextChannel, channel)
+
+ async def create_guild_news_channel(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ name: str,
+ *,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ nsfw: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ rate_limit_per_user: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Sequence[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ category: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.GuildCategory]] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> channels.GuildNewsChannel:
+ channel = await self._create_guild_channel(
+ guild,
+ name,
+ channels.ChannelType.GUILD_NEWS,
+ position=position,
+ topic=topic,
+ nsfw=nsfw,
+ rate_limit_per_user=rate_limit_per_user,
+ permission_overwrites=permission_overwrites,
+ category=category,
+ reason=reason,
+ )
+ return typing.cast(channels.GuildNewsChannel, channel)
+
+ async def create_guild_voice_channel(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ name: str,
+ *,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ user_limit: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ bitrate: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Sequence[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ category: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.GuildCategory]] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> channels.GuildVoiceChannel:
+ channel = await self._create_guild_channel(
+ guild,
+ name,
+ channels.ChannelType.GUILD_VOICE,
+ position=position,
+ user_limit=user_limit,
+ bitrate=bitrate,
+ permission_overwrites=permission_overwrites,
+ category=category,
+ reason=reason,
+ )
+ return typing.cast(channels.GuildVoiceChannel, channel)
+
+ async def create_guild_category(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ name: str,
+ *,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Sequence[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> channels.GuildCategory:
+ channel = await self._create_guild_channel(
+ guild,
+ name,
+ channels.ChannelType.GUILD_CATEGORY,
+ position=position,
+ permission_overwrites=permission_overwrites,
+ reason=reason,
+ )
+ return typing.cast(channels.GuildCategory, channel)
+
+ async def _create_guild_channel(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ name: str,
+ type_: channels.ChannelType,
+ *,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ nsfw: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ bitrate: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ user_limit: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ rate_limit_per_user: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Sequence[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ category: undefined.UndefinedOr[snowflake.SnowflakeishOr[channels.GuildCategory]] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> channels.GuildChannel:
+ route = routes.POST_GUILD_CHANNELS.compile(guild=guild)
+ body = data_binding.JSONObjectBuilder()
+ body.put("type", type_)
+ body.put("name", name)
+ body.put("position", position)
+ body.put("topic", topic)
+ body.put("nsfw", nsfw)
+ body.put("bitrate", bitrate)
+ body.put("user_limit", user_limit)
+ body.put("rate_limit_per_user", rate_limit_per_user)
+ body.put_snowflake("category_id", category)
+ body.put_array(
+ "permission_overwrites",
+ permission_overwrites,
+ conversion=self._entity_factory.serialize_permission_overwrite,
+ )
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ channel = self._entity_factory.deserialize_channel(response)
+ return typing.cast(channels.GuildChannel, channel)
+
+ async def reposition_channels(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ positions: typing.Mapping[int, typing.Union[snowflake.SnowflakeishOr[channels.GuildChannel]]],
+ ) -> None:
+ route = routes.POST_GUILD_CHANNELS.compile(guild=guild)
+ body = [{"id": str(int(channel)), "position": pos} for pos, channel in positions.items()]
+ await self._request(route, json=body)
+
+ async def fetch_member(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild], user: snowflake.SnowflakeishOr[users.PartialUser],
+ ) -> guilds.Member:
+ route = routes.GET_GUILD_MEMBER.compile(guild=guild, user=user)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_member(response, guild_id=snowflake.Snowflake(guild))
+
+ def fetch_members(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]
+ ) -> iterators.LazyIterator[guilds.Member]:
+ return special_endpoints.MemberIterator(
+ entity_factory=self._entity_factory, request_call=self._request, guild=guild
+ )
+
+ async def edit_member(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ *,
+ nick: undefined.UndefinedNoneOr[str] = undefined.UNDEFINED,
+ roles: undefined.UndefinedOr[
+ typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]]
+ ] = undefined.UNDEFINED,
+ mute: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ deaf: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ voice_channel: undefined.UndefinedNoneOr[
+ snowflake.SnowflakeishOr[channels.GuildVoiceChannel]
+ ] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.PATCH_GUILD_MEMBER.compile(guild=guild, user=user)
+ body = data_binding.JSONObjectBuilder()
+ body.put("nick", nick)
+ body.put("mute", mute)
+ body.put("deaf", deaf)
+ body.put_snowflake_array("roles", roles)
+
+ if voice_channel is None:
+ body.put("channel_id", None)
+ elif voice_channel is not undefined.UNDEFINED:
+ body.put_snowflake("channel_id", voice_channel)
+
+ await self._request(route, json=body, reason=reason)
+
+ async def edit_my_nick(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.Guild],
+ nick: typing.Optional[str],
+ *,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.PATCH_MY_GUILD_NICKNAME.compile(guild=guild)
+ body = data_binding.JSONObjectBuilder()
+ body.put("nick", nick)
+ await self._request(route, json=body, reason=reason)
+
+ async def add_role_to_member(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ role: snowflake.SnowflakeishOr[guilds.PartialRole],
+ *,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.PUT_GUILD_MEMBER_ROLE.compile(guild=guild, user=user, role=role)
+ await self._request(route, reason=reason)
+
+ async def remove_role_from_member(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ role: snowflake.SnowflakeishOr[guilds.PartialRole],
+ *,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.DELETE_GUILD_MEMBER_ROLE.compile(guild=guild, user=user, role=role)
+ await self._request(route, reason=reason)
+
+ async def kick_user(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ *,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.DELETE_GUILD_MEMBER.compile(guild=guild, user=user)
+ await self._request(route, reason=reason)
+
+ kick_member = kick_user
+
+ async def ban_user(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ *,
+ delete_message_days: undefined.UndefinedNoneOr[int] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ body = data_binding.JSONObjectBuilder()
+ body.put("delete_message_days", delete_message_days)
+ # This endpoint specifies a reason in the body, specifically.
+ body.put("reason", reason)
+ route = routes.PUT_GUILD_BAN.compile(guild=guild, user=user)
+ await self._request(route, json=body)
+
+ ban_member = ban_user
+
+ async def unban_user(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ user: snowflake.SnowflakeishOr[users.PartialUser],
+ *,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.DELETE_GUILD_BAN.compile(guild=guild, user=user)
+ await self._request(route, reason=reason)
+
+ unban_member = unban_user
+
+ async def fetch_ban(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild], user: snowflake.SnowflakeishOr[users.PartialUser],
+ ) -> guilds.GuildMemberBan:
+ route = routes.GET_GUILD_BAN.compile(guild=guild, user=user)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_guild_member_ban(response)
+
+ async def fetch_bans(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]
+ ) -> typing.Sequence[guilds.GuildMemberBan]:
+ route = routes.GET_GUILD_BANS.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_guild_member_ban)
+
+ async def fetch_roles(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild],) -> typing.Sequence[guilds.Role]:
+ route = routes.GET_GUILD_ROLES.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(
+ response, self._entity_factory.deserialize_role, guild_id=snowflake.Snowflake(guild)
+ )
+
+ async def create_role(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ permissions: undefined.UndefinedOr[permissions_.Permissions] = undefined.UNDEFINED,
+ 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,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> guilds.Role:
+ if not undefined.count(color, colour):
+ raise TypeError("Can not specify 'color' and 'colour' together.")
+
+ route = routes.POST_GUILD_ROLES.compile(guild=guild)
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ body.put("permissions", permissions)
+ body.put("color", color)
+ body.put("color", colour)
+ body.put("hoist", hoist)
+ body.put("mentionable", mentionable)
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_role(response, guild_id=snowflake.Snowflake(guild))
+
+ async def reposition_roles(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ positions: typing.Mapping[int, snowflake.SnowflakeishOr[guilds.PartialRole]],
+ ) -> None:
+ route = routes.POST_GUILD_ROLES.compile(guild=guild)
+ body = [{"id": str(int(role)), "position": pos} for pos, role in positions.items()]
+ await self._request(route, json=body)
+
+ async def edit_role(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ role: snowflake.SnowflakeishOr[guilds.PartialRole],
+ *,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ permissions: undefined.UndefinedOr[permissions_.Permissions] = undefined.UNDEFINED,
+ 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,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> guilds.Role:
+ if not undefined.count(color, colour):
+ raise TypeError("Can not specify 'color' and 'colour' together.")
+
+ route = routes.PATCH_GUILD_ROLE.compile(guild=guild, role=role)
+
+ body = data_binding.JSONObjectBuilder()
+ body.put("name", name)
+ body.put("permissions", permissions)
+ body.put("color", color)
+ body.put("color", colour)
+ body.put("hoist", hoist)
+ body.put("mentionable", mentionable)
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_role(response, guild_id=snowflake.Snowflake(guild))
+
+ async def delete_role(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild], role: snowflake.SnowflakeishOr[guilds.PartialRole],
+ ) -> None:
+ route = routes.DELETE_GUILD_ROLE.compile(guild=guild, role=role)
+ await self._request(route)
+
+ async def estimate_guild_prune_count(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ days: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ include_roles: undefined.UndefinedOr[
+ typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]]
+ ] = undefined.UNDEFINED,
+ ) -> int:
+ route = routes.GET_GUILD_PRUNE.compile(guild=guild)
+ query = data_binding.StringMapBuilder()
+ query.put("days", days)
+ if include_roles is not undefined.UNDEFINED:
+ roles = ",".join(str(int(role)) for role in include_roles)
+ query.put("include_roles", roles)
+ raw_response = await self._request(route, query=query)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return int(response["pruned"])
+
+ async def begin_guild_prune(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ days: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ compute_prune_count: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ include_roles: undefined.UndefinedOr[
+ typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]]
+ ] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> typing.Optional[int]:
+ route = routes.POST_GUILD_PRUNE.compile(guild=guild)
+ body = data_binding.JSONObjectBuilder()
+ body.put("days", days)
+ body.put("compute_prune_count", compute_prune_count)
+ body.put_snowflake_array("include_roles", include_roles)
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ pruned = response.get("pruned")
+ return int(pruned) if pruned is not None else None
+
+ async def fetch_guild_voice_regions(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ ) -> typing.Sequence[voices.VoiceRegion]:
+ route = routes.GET_GUILD_VOICE_REGIONS.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_voice_region)
+
+ async def fetch_guild_invites(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ ) -> typing.Sequence[invites.InviteWithMetadata]:
+ route = routes.GET_GUILD_INVITES.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_invite_with_metadata)
+
+ async def fetch_integrations(
+ self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ ) -> typing.Sequence[guilds.Integration]:
+ route = routes.GET_GUILD_INTEGRATIONS.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONArray, raw_response)
+ return data_binding.cast_json_array(response, self._entity_factory.deserialize_integration)
+
+ async def edit_integration(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ integration: snowflake.SnowflakeishOr[guilds.Integration],
+ *,
+ expire_behaviour: undefined.UndefinedOr[guilds.IntegrationExpireBehaviour] = undefined.UNDEFINED,
+ expire_grace_period: undefined.UndefinedOr[date.Intervalish] = undefined.UNDEFINED,
+ enable_emojis: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.PATCH_GUILD_INTEGRATION.compile(guild=guild, integration=integration)
+ body = data_binding.JSONObjectBuilder()
+ body.put("expire_behaviour", expire_behaviour)
+ body.put("expire_grace_period", expire_grace_period, conversion=date.timespan_to_int)
+ # Inconsistent naming in the API itself, so I have changed the name.
+ body.put("enable_emoticons", enable_emojis)
+ await self._request(route, json=body, reason=reason)
+
+ async def delete_integration(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ integration: snowflake.SnowflakeishOr[guilds.Integration],
+ *,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ route = routes.DELETE_GUILD_INTEGRATION.compile(guild=guild, integration=integration)
+ await self._request(route, reason=reason)
+
+ async def sync_integration(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ integration: snowflake.SnowflakeishOr[guilds.Integration],
+ ) -> None:
+ route = routes.POST_GUILD_INTEGRATION_SYNC.compile(guild=guild, integration=integration)
+ await self._request(route)
+
+ async def fetch_widget(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]) -> guilds.GuildWidget:
+ route = routes.GET_GUILD_WIDGET.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_guild_widget(response)
+
+ async def edit_widget(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ channel: undefined.UndefinedNoneOr[snowflake.SnowflakeishOr[channels.GuildChannel]] = undefined.UNDEFINED,
+ enabled: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ reason: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> guilds.GuildWidget:
+ route = routes.PATCH_GUILD_WIDGET.compile(guild=guild)
+
+ body = data_binding.JSONObjectBuilder()
+ body.put("enabled", enabled)
+ if channel is None:
+ body.put("channel", None)
+ elif channel is not undefined.UNDEFINED:
+ body.put_snowflake("channel", channel)
+
+ raw_response = await self._request(route, json=body, reason=reason)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_guild_widget(response)
+
+ async def fetch_vanity_url(self, guild: snowflake.SnowflakeishOr[guilds.PartialGuild]) -> invites.VanityURL:
+ route = routes.GET_GUILD_VANITY_URL.compile(guild=guild)
+ raw_response = await self._request(route)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+ return self._entity_factory.deserialize_vanity_url(response)
diff --git a/hikari/impl/shard.py b/hikari/impl/shard.py
new file mode 100644
index 0000000000..9470dda4ed
--- /dev/null
+++ b/hikari/impl/shard.py
@@ -0,0 +1,924 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Single-shard implementation for the V6 and V7 event gateway for Discord."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "GatewayShardImplV6",
+ "GatewayShardImpl",
+]
+
+import asyncio
+import datetime
+import enum
+import logging
+import random
+import typing
+import urllib.parse
+import zlib
+
+import aiohttp
+import attr
+
+from hikari import errors
+from hikari.api import shard
+from hikari.impl import rate_limits
+from hikari.models import intents as intents_
+from hikari.models import presences
+from hikari.utilities import constants
+from hikari.utilities import data_binding
+from hikari.utilities import date
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+if typing.TYPE_CHECKING:
+ from hikari import config
+ from hikari.models import channels
+ from hikari.models import guilds
+ from hikari.models import users
+
+
+@typing.final
+class GatewayShardImplV6(shard.GatewayShard):
+ """Implementation of a V6 and V7 compatible gateway.
+
+ Parameters
+ ----------
+ compression : buitlins.str or buitlins.None
+ Compression format to use for the shard. Only supported values are
+ `"payload_zlib_stream"` or `builtins.None` to disable it.
+ data_format : builtins.str
+ Data format to use for inbound data. Only supported format is
+ `"json"`.
+ debug : builtins.bool
+ If `builtins.True`, each sent and received payload is dumped to the
+ logs. If `builtins.False`, only the fact that data has been
+ sent/received will be logged.
+ event_consumer
+ A coroutine function consuming a `GatewayShardImplV6`,
+ a `builtins.str` event name, and a
+ `hikari.utilities.data_binding.JSONObject` event object as parameters.
+ This should return `builtins.None`, and will be called asynchronously
+ with each event that fires.
+ http_settings : hikari.config.HTTPSettings
+ The HTTP-related settings to use while negotiating a websocket.
+ initial_activity : hikari.utilities.undefined.UndefinedNoneOr[hikari.models.include_presences.Activity]
+ The initial activity to appear to have for this shard.
+ initial_idle_since : hikari.utilities.undefined.UndefinedNoneOr[datetime.datetime]
+ The datetime to appear to be idle since.
+ initial_is_afk : hikari.utilities.undefined.UndefinedOr[bool]
+ Whether to appear to be AFK or not on login.
+ initial_status : hikari.utilities.undefined.UndefinedOr[hikari.models.include_presences.Status]
+ The initial status to set on login for the shard.
+ intents : hikari.models.intents.Intents or builtins.None
+ Collection of intents to use, or `builtins.None` to not use intents at
+ all.
+ large_threshold : builtins.int
+ The number of members to have in a guild for it to be considered large.
+ proxy_settings : hikari.config.ProxySettings
+ The proxy settings to use while negotiating a websocket.
+ shard_id : builtins.int
+ The shard ID.
+ shard_count : builtins.int
+ The shard count.
+ token : builtins.str
+ The bot token to use.
+ url : builtins.str
+ The gateway URL to use. This should not contain a query-string or
+ fragments.
+ version : builtins.int
+ Gateway API version to use.
+
+ !!! note
+ If all four of `initial_activity`, `initial_idle_since`,
+ `initial_is_afk`, and `initial_status` are not defined and left to their
+ default values, then the presence will not be _updated_ on startup
+ at all.
+
+ If any of these _are_ specified, then any that are not specified will
+ be set to sane defaults, which may change the previous status. This will
+ only occur during startup, and is an artifact of how Discord manages
+ these updates internally. All other calls to update the status of
+ the shard will support partial updates.
+ """
+
+ __slots__: typing.Sequence[str] = (
+ "_activity",
+ "_backoff",
+ "_compression",
+ "_connected_at",
+ "_data_format",
+ "_debug",
+ "_event_consumer",
+ "_handshake_event",
+ "_heartbeat_interval",
+ "_heartbeat_latency",
+ "_http_settings",
+ "_idle_since",
+ "_intents",
+ "_is_afk",
+ "_large_threshold",
+ "_last_heartbeat_sent",
+ "_last_message_received",
+ "_last_run_started_at",
+ "_logger",
+ "_proxy_settings",
+ "_ratelimiter",
+ "_request_close_event",
+ "_seq",
+ "_session_id",
+ "_session_started_at",
+ "_shard_id",
+ "_shard_count",
+ "_status",
+ "_token",
+ "_user_id",
+ "_version",
+ "_ws",
+ "_zlib",
+ "_zombied",
+ "url",
+ )
+
+ @enum.unique
+ @typing.final
+ class _Opcode(enum.IntEnum):
+ DISPATCH = 0
+ HEARTBEAT = 1
+ IDENTIFY = 2
+ PRESENCE_UPDATE = 3
+ VOICE_STATE_UPDATE = 4
+ RESUME = 6
+ RECONNECT = 7
+ REQUEST_GUILD_MEMBERS = 8
+ INVALID_SESSION = 9
+ HELLO = 10
+ HEARTBEAT_ACK = 11
+
+ @attr.s(slots=True, repr=False, weakref_slot=False)
+ @typing.final
+ class _Reconnect(RuntimeError):
+ pass
+
+ @attr.s(slots=True, repr=False, weakref_slot=False)
+ @typing.final
+ class _SocketClosed(RuntimeError):
+ pass
+
+ @attr.s(auto_exc=True, slots=True, repr=False, weakref_slot=False)
+ @typing.final
+ class _InvalidSession(RuntimeError):
+ can_resume: bool = attr.ib(default=False)
+
+ _RESTART_RATELIMIT_WINDOW: typing.Final[typing.ClassVar[float]] = 30.0
+ """If the shard restarts more than once within this period of time, then
+ exponentially back-off to prevent spamming the gateway or tanking the CPU.
+
+ This is potentially important if the internet connection turns off, as the
+ bot will simply attempt to reconnect repeatedly until the connection
+ resumes.
+ """
+
+ _NO_SESSION_INVALIDATION_CLOSE_CODE: typing.Final[typing.ClassVar[int]] = 3000
+ """Discord seems to invalidate sessions if I send a 1xxx, which is useless
+ for invalid session and reconnect messages where I want to be able to
+ resume.
+ """
+
+ def __init__(
+ self,
+ *,
+ compression: typing.Optional[str] = shard.GatewayCompression.PAYLOAD_ZLIB_STREAM,
+ data_format: str = shard.GatewayDataFormat.JSON,
+ debug: bool = False,
+ event_consumer: typing.Callable[
+ [shard.GatewayShard, str, data_binding.JSONObject], typing.Coroutine[None, None, None]
+ ],
+ http_settings: config.HTTPSettings,
+ initial_activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
+ initial_idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
+ initial_is_afk: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ initial_status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
+ intents: typing.Optional[intents_.Intents] = None,
+ large_threshold: int = 250,
+ proxy_settings: config.ProxySettings,
+ shard_id: int = 0,
+ shard_count: int = 1,
+ token: str,
+ url: str,
+ version: int = 6,
+ ) -> None:
+ self._activity: undefined.UndefinedNoneOr[presences.Activity] = initial_activity
+ self._backoff = rate_limits.ExponentialBackOff(base=1.85, maximum=600, initial_increment=2)
+ self._compression = compression.lower() if compression is not None else None
+ self._connected_at: typing.Optional[float] = None
+ self._data_format = data_format.lower()
+ self._debug = debug
+ self._event_consumer = event_consumer
+ self._handshake_event = asyncio.Event()
+ self._heartbeat_interval = float("nan")
+ self._heartbeat_latency = float("nan")
+ self._http_settings = http_settings
+ self._idle_since: undefined.UndefinedNoneOr[datetime.datetime] = initial_idle_since
+ self._intents: typing.Optional[intents_.Intents] = intents
+ self._is_afk: undefined.UndefinedOr[bool] = initial_is_afk
+ self._large_threshold = large_threshold
+ self._last_heartbeat_sent = float("nan")
+ self._last_message_received = float("nan")
+ self._last_run_started_at = float("nan")
+ self._logger = logging.getLogger(f"hikari.gateway.{shard_id}")
+ self._proxy_settings = proxy_settings
+ self._ratelimiter = rate_limits.WindowedBurstRateLimiter(str(shard_id), 60.0, 120)
+ self._request_close_event = asyncio.Event()
+ self._seq: typing.Optional[int] = None
+ self._session_id: typing.Optional[str] = None
+ self._session_started_at: typing.Optional[float] = None
+ self._shard_id: int = shard_id
+ self._shard_count: int = shard_count
+ self._status: undefined.UndefinedOr[presences.Status] = initial_status
+ self._token = token
+ self._user_id: typing.Optional[snowflake.Snowflake] = None
+ self._version = version
+ self._ws: typing.Optional[aiohttp.ClientWebSocketResponse] = None
+ self._zlib: typing.Any = None # No typeshed/stub.
+ self._zombied = False
+
+ scheme, netloc, path, params, _, _ = urllib.parse.urlparse(url, allow_fragments=True)
+
+ if self._data_format != shard.GatewayDataFormat.JSON:
+ raise NotImplementedError(f"Unsupported gateway data format: {self._data_format}")
+
+ new_query = dict(v=int(version), encoding=self._data_format)
+
+ if self._compression is not None:
+ if self._compression == shard.GatewayCompression.PAYLOAD_ZLIB_STREAM:
+ new_query["compress"] = "zlib-stream"
+ else:
+ raise NotImplementedError(f"Unsupported compression format {self._compression}")
+
+ new_query = urllib.parse.urlencode(new_query)
+ self.url = urllib.parse.urlunparse((scheme, netloc, path, params, new_query, ""))
+
+ @property
+ def compression(self) -> typing.Optional[str]:
+ return self._compression
+
+ @property
+ def connection_uptime(self) -> float:
+ return date.monotonic() - self._connected_at if self._connected_at is not None else 0
+
+ @property
+ def data_format(self) -> str:
+ return self._data_format
+
+ @property
+ def heartbeat_interval(self) -> float:
+ return self._heartbeat_interval
+
+ @property
+ def heartbeat_latency(self) -> float:
+ return self._heartbeat_latency
+
+ @property
+ def http_settings(self) -> config.HTTPSettings:
+ return self._http_settings
+
+ @property
+ def id(self) -> int:
+ return self._shard_id
+
+ @property
+ def intents(self) -> typing.Optional[intents_.Intents]:
+ return self._intents
+
+ @property
+ def is_alive(self) -> bool:
+ return self._connected_at is not None
+
+ @property
+ def proxy_settings(self) -> config.ProxySettings:
+ return self._proxy_settings
+
+ @property
+ def sequence(self) -> typing.Optional[int]:
+ return self._seq
+
+ @property
+ def session_id(self) -> typing.Optional[str]:
+ return self._session_id
+
+ @property
+ def session_uptime(self) -> float:
+ return date.monotonic() - self._session_started_at if self._session_started_at is not None else 0
+
+ @property
+ def shard_count(self) -> int:
+ return self._shard_count
+
+ @property
+ def version(self) -> int:
+ return self._version
+
+ async def get_user_id(self) -> snowflake.Snowflake:
+ await self._handshake_event.wait()
+ if self._user_id is None:
+ raise RuntimeError("user_id was not known, this is probably a bug")
+ return self._user_id
+
+ async def start(self) -> asyncio.Task[None]:
+ run_task = asyncio.create_task(self._run(), name=f"shard {self._shard_id} keep-alive")
+ handshake_future = asyncio.ensure_future(self._handshake_event.wait())
+ await asyncio.wait([run_task, handshake_future], return_when=asyncio.FIRST_COMPLETED) # type: ignore
+
+ # Ensure we propagate a startup error without joining the run task first.
+ # We should not need to kill the handshake event, that should be done for us.
+ if run_task.done() and (exception := run_task.exception()) is not None:
+ raise exception
+
+ return run_task
+
+ async def close(self) -> None:
+ """Close the websocket."""
+ if not self._request_close_event.is_set():
+ if self.is_alive:
+ self._logger.info("received request to shut down shard")
+ else:
+ self._logger.debug("shard marked as closed when it was not running")
+ self._request_close_event.set()
+
+ if self._ws is not None:
+ self._logger.warning("gateway client closed, will not attempt to restart")
+ await self._close_ws(errors.ShardCloseCode.NORMAL_CLOSURE, "client shut down")
+
+ async def update_presence(
+ self,
+ *,
+ idle_since: undefined.UndefinedNoneOr[datetime.datetime] = undefined.UNDEFINED,
+ afk: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ activity: undefined.UndefinedNoneOr[presences.Activity] = undefined.UNDEFINED,
+ status: undefined.UndefinedOr[presences.Status] = undefined.UNDEFINED,
+ ) -> None:
+ if idle_since is undefined.UNDEFINED:
+ self._idle_since = self._idle_since if self._idle_since is not undefined.UNDEFINED else None
+ if afk is undefined.UNDEFINED:
+ self._is_afk = self._is_afk if self._is_afk is not undefined.UNDEFINED else False
+ if status is undefined.UNDEFINED:
+ self._status = self._status if self._status is not undefined.UNDEFINED else presences.Status.ONLINE
+ if activity is undefined.UNDEFINED:
+ self._activity = self._activity if self._activity is not undefined.UNDEFINED else None
+
+ # TODO: make parameters get passed to this method instead of it
+ # assuming it is already set correctly.
+ presence = self._serialize_presence_payload()
+
+ payload: data_binding.JSONObject = {"op": self._Opcode.PRESENCE_UPDATE, "d": presence}
+
+ if self.is_alive:
+ await self._send_json(payload)
+ else:
+ self._logger.debug("not sending presence update, I am not alive")
+
+ # Update internal status.
+ self._idle_since = idle_since
+ self._is_afk = afk
+ self._activity = activity
+ self._status = status
+
+ async def update_voice_state(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ channel: typing.Optional[snowflake.SnowflakeishOr[channels.GuildVoiceChannel]],
+ *,
+ self_mute: bool = False,
+ self_deaf: bool = False,
+ ) -> None:
+ await self._send_json(
+ {
+ "op": self._Opcode.VOICE_STATE_UPDATE,
+ "d": {
+ "guild_id": str(int(guild)),
+ "channel_id": str(int(channel)) if channel is not None else None,
+ "mute": self_mute,
+ "deaf": self_deaf,
+ },
+ }
+ )
+
+ async def request_guild_members(
+ self,
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ include_presences: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ query: str = "",
+ limit: int = 0,
+ user_ids: undefined.UndefinedOr[typing.Sequence[snowflake.SnowflakeishOr[users.User]]] = undefined.UNDEFINED,
+ nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ ) -> None:
+ if self._intents is not 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 is not undefined.UNDEFINED and not self._intents & intents_.Intents.GUILD_PRESENCES:
+ raise errors.MissingIntentError(intents_.Intents.GUILD_PRESENCES)
+
+ if user_ids 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 user_ids is not undefined.UNDEFINED and len(user_ids) > 100:
+ raise ValueError("'users' is limited to 100 users")
+
+ payload = data_binding.JSONObjectBuilder()
+ payload.put_snowflake("guild_id", guild)
+ payload.put("include_presences", include_presences)
+ payload.put("query", query)
+ payload.put("limit", limit)
+ payload.put_snowflake_array("user_ids", user_ids)
+ payload.put("nonce", nonce)
+
+ await self._send_json({"op": self._Opcode.REQUEST_GUILD_MEMBERS, "d": payload})
+
+ async def _run(self) -> None:
+ """Start the shard and wait for it to shut down."""
+ async with aiohttp.ClientSession(
+ connector_owner=True,
+ connector=aiohttp.TCPConnector(
+ verify_ssl=self._http_settings.verify_ssl,
+ # We are never going to want more than one connection. This will be spammy on
+ # big sharded bots and waste a lot of time, so theres no reason to bother.
+ limit=1,
+ limit_per_host=1,
+ ),
+ version=aiohttp.HttpVersion11,
+ timeout=aiohttp.ClientTimeout(
+ total=self._http_settings.timeouts.total,
+ connect=self._http_settings.timeouts.acquire_and_connect,
+ sock_read=self._http_settings.timeouts.request_socket_read,
+ sock_connect=self._http_settings.timeouts.request_socket_connect,
+ ),
+ trust_env=self._proxy_settings.trust_env,
+ ) as client_session:
+ try:
+ # This may be set if we are stuck in a reconnect loop.
+ while not self._request_close_event.is_set() and await self._run_once_shielded(client_session):
+ pass
+
+ # Allow zookeepers to stop gathering tasks for each shard.
+ raise errors.GatewayClientClosedError
+ finally:
+ # This is set to ensure that the `start' waiter does not deadlock if
+ # we cannot connect successfully. It is a hack, but it works.
+ self._handshake_event.set()
+
+ async def _run_once_shielded(self, client_session: aiohttp.ClientSession) -> bool:
+ # Returns `builtins.True` if we can reconnect, or `builtins.False` otherwise.
+ # Wraps the runner logic in the standard exception handling mechanisms.
+ try:
+ await self._run_once(client_session)
+ return False
+
+ except aiohttp.ClientConnectorError as ex:
+ # TODO: will I need to reset the session_id and seq ever here? I don't think I do, but I should check
+ self._logger.error(
+ "failed to connect to Discord because %s.%s: %s", type(ex).__module__, type(ex).__qualname__, str(ex),
+ )
+
+ except self._InvalidSession as ex:
+ if ex.can_resume:
+ self._logger.warning("invalid session, so will attempt to resume session %s now", self._session_id)
+ await self._close_ws(self._NO_SESSION_INVALIDATION_CLOSE_CODE, "invalid session (resume)")
+ self._backoff.reset()
+ else:
+ self._logger.warning("invalid session, so will attempt to reconnect with new session in a few seconds")
+ await self._close_ws(errors.ShardCloseCode.NORMAL_CLOSURE, "invalid session (no resume)")
+ self._seq = None
+ self._session_id = None
+ self._session_started_at = None
+
+ except self._Reconnect:
+ self._logger.warning("instructed by Discord to reconnect and resume session %s", self._session_id)
+ self._backoff.reset()
+ await self._close_ws(self._NO_SESSION_INVALIDATION_CLOSE_CODE, "reconnecting")
+
+ except self._SocketClosed:
+ # The socket has already closed, so no need to close it again.
+ if self._zombied:
+ self._backoff.reset()
+
+ if not self._request_close_event.is_set():
+ self._logger.warning("unexpected socket closure, will attempt to resume")
+ else:
+ self._session_started_at = None
+
+ return not self._request_close_event.is_set()
+
+ except errors.GatewayServerClosedConnectionError as ex:
+ if ex.can_reconnect:
+ self._logger.warning(
+ "server closed the connection with %s (%s), will attempt to reconnect", ex.code, ex.reason,
+ )
+ else:
+ self._seq = None
+ self._session_id = None
+ self._session_started_at = None
+ self._backoff.reset()
+ self._request_close_event.set()
+ raise
+
+ except Exception as ex:
+ self._logger.error("unexpected exception occurred, shard will now die", exc_info=ex)
+ self._seq = None
+ self._session_id = None
+ self._session_started_at = None
+ await self._close_ws(errors.ShardCloseCode.UNEXPECTED_CONDITION, "unexpected error occurred")
+ raise
+
+ return True
+
+ async def _run_once(self, client_session: aiohttp.ClientSession) -> None:
+ # Physical runner logic without error handling.
+ self._request_close_event.clear()
+
+ self._zombied = False
+
+ if date.monotonic() - self._last_run_started_at < self._RESTART_RATELIMIT_WINDOW:
+ # Interrupt sleep immediately if a request to close is fired.
+ wait_task = asyncio.create_task(
+ self._request_close_event.wait(), name=f"gateway shard {self._shard_id} backing off"
+ )
+ try:
+ backoff = next(self._backoff)
+ self._logger.debug("backing off for %ss", backoff)
+ await asyncio.wait_for(wait_task, timeout=backoff)
+
+ # If this line gets reached, the wait didn't time out, meaning
+ # the user told the client to shut down gracefully before the
+ # backoff completed.
+ return
+ except asyncio.TimeoutError:
+ pass
+
+ # Do this after. It prevents backing off on the first try.
+ self._last_run_started_at = date.monotonic()
+
+ self._logger.debug("creating websocket connection to %s", self.url)
+ self._ws = await client_session.ws_connect(
+ url=self.url,
+ autoping=True,
+ autoclose=True,
+ proxy=self._proxy_settings.url,
+ proxy_headers=self._proxy_settings.all_headers,
+ verify_ssl=self._http_settings.verify_ssl,
+ # Discord can send massive messages that lead us to being disconnected
+ # without this. It is a bit shit that there is no guarantee of the size
+ # of these messages, but there is not much we can do about this one.
+ max_msg_size=0,
+ )
+
+ self._connected_at = date.monotonic()
+
+ # Technically we are connected after the hello, but this ensures we can send and receive
+ # before firing that event.
+ self._dispatch("CONNECTED", {})
+
+ try:
+
+ self._zlib = zlib.decompressobj()
+
+ self._handshake_event.clear()
+ self._request_close_event.clear()
+
+ await self._handshake()
+
+ # We should ideally set this after HELLO, but it should be fine
+ # here as well. If we don't heartbeat in time, something probably
+ # went majorly wrong anyway.
+ heartbeat = asyncio.create_task(
+ self._heartbeat_keepalive(), name=f"gateway shard {self._shard_id} heartbeat"
+ )
+
+ try:
+ await self._poll_events()
+ finally:
+ heartbeat.cancel()
+ finally:
+ self._dispatch("DISCONNECTED", {})
+ self._connected_at = None
+
+ async def _close_ws(self, code: int, message: str) -> None:
+ self._logger.debug("sending close frame with code %s and message %r", int(code), message)
+ # None if the websocket error'ed on initialization.
+ if self._ws is not None:
+ await self._ws.close(code=code, message=bytes(message, "utf-8"))
+
+ async def _handshake(self) -> None:
+ hello = await self._expect_opcode(self._Opcode.HELLO)
+ self._heartbeat_interval = hello["heartbeat_interval"] / 1_000.0
+ self._logger.info("received HELLO, heartbeat interval is %ss", self._heartbeat_interval)
+
+ if self._session_id is not None:
+ await self._send_json(
+ {
+ "op": self._Opcode.RESUME,
+ "d": {"token": self._token, "seq": self._seq, "session_id": self._session_id},
+ }
+ )
+ else:
+ payload: data_binding.JSONObject = {
+ "op": self._Opcode.IDENTIFY,
+ "d": {
+ "token": self._token,
+ "compress": False,
+ "large_threshold": self._large_threshold,
+ "properties": {
+ "$os": constants.SYSTEM_TYPE,
+ "$browser": constants.AIOHTTP_VERSION,
+ "$device": constants.LIBRARY_VERSION,
+ },
+ "shard": [self._shard_id, self._shard_count],
+ },
+ }
+
+ if self._intents is not None:
+ payload["d"]["intents"] = self._intents
+
+ if undefined.count(self._activity, self._status, self._idle_since, self._is_afk) != 4:
+ payload["d"]["presence"] = self._serialize_presence_payload()
+
+ await self._send_json(payload)
+
+ async def _heartbeat_keepalive(self) -> None:
+ # Wait a random offset between 0ms and ms before
+ # sending the first heartbeat. This helps not overload the gateway
+ # after recovering from an outage.
+ #
+ # S311 - Dont use random for security/cryptographic purposes
+ offset = random.random() * self._heartbeat_interval # noqa: S311
+ await asyncio.sleep(offset)
+
+ try:
+ while not self._request_close_event.is_set():
+ now = date.monotonic()
+ time_since_message = now - self._last_message_received
+ time_since_heartbeat_sent = now - self._last_heartbeat_sent
+
+ if self._heartbeat_interval < time_since_message:
+ self._logger.error(
+ "connection is a zombie, haven't received any message for %ss, last heartbeat sent %ss ago",
+ time_since_message,
+ time_since_heartbeat_sent,
+ )
+ await self._close_zombie()
+ return
+
+ self._logger.debug(
+ "preparing to send HEARTBEAT [s:%s, interval:%ss]", self._seq, self._heartbeat_interval
+ )
+ await self._send_json({"op": self._Opcode.HEARTBEAT, "d": self._seq})
+ self._last_heartbeat_sent = date.monotonic()
+
+ try:
+ await asyncio.wait_for(self._request_close_event.wait(), timeout=self._heartbeat_interval)
+ except asyncio.TimeoutError:
+ pass
+
+ except asyncio.CancelledError:
+ # This happens if the poll task has stopped. It is not a problem we need to report.
+ pass
+
+ async def _close_zombie(self) -> None:
+ # https://gitlab.com/nekokatt/hikari/-/issues/462
+ #
+ # aiohttp has a little "race condition" where it will try to wait for the close frame to be
+ # sent before it physically proceeds to close the aiohttp.ClientResponse. This is a bit
+ # annoying for us, since when we are zombied, this frame will probably never be able to be
+ # sent (if the network went down). However, to feed a socket closure message into the
+ # message receive loop, we need to make this call.
+ #
+ # Thus, the best solution here is to make a task to perform this call in the background,
+ # and await for a short amount of time to let it feed the close message before it proceeds.
+ # After this, we manually close the internal aiohttp ClientResponse to force that close frame
+ # to fail to send immediately, before proceeding to await the original close task from then
+ # on.
+ #
+ # Probably should file a bug report at some point... if I remember.
+ self._zombied = True
+ close_task = asyncio.create_task(
+ self._close_ws(code=errors.ShardCloseCode.PROTOCOL_ERROR, message="heartbeat timeout")
+ )
+ await asyncio.sleep(0.1)
+ # noinspection PyProtectedMember
+ self._ws._response.close() # type: ignore[union-attr]
+ try:
+ await close_task
+ finally:
+ # Discard any exception, I don't care, as this is broken anyway.
+ return
+
+ async def _poll_events(self) -> None:
+ while not self._request_close_event.is_set():
+ message = await self._receive_json()
+
+ op = message["op"]
+ data = message["d"]
+
+ if op == self._Opcode.DISPATCH:
+ event = message["t"]
+ self._seq = message["s"]
+
+ if event == "READY":
+ self._session_id = data["session_id"]
+ user_pl = data["user"]
+ user_id = user_pl["id"]
+ self._user_id = snowflake.Snowflake(user_id)
+ tag = user_pl["username"] + "#" + user_pl["discriminator"]
+ self._logger.info(
+ "shard is ready [session:%s, user_id:%s, tag:%s]", self._session_id, user_id, tag,
+ )
+ self._handshake_event.set()
+ self._session_started_at = date.monotonic()
+
+ elif event == "RESUME":
+ self._logger.info("shard has resumed [session:%s, seq:%s]", self._session_id, self._seq)
+ self._handshake_event.set()
+
+ self._dispatch(event, data)
+
+ elif op == self._Opcode.HEARTBEAT:
+ self._logger.debug("received HEARTBEAT; sending HEARTBEAT ACK")
+ await self._send_json({"op": self._Opcode.HEARTBEAT_ACK})
+
+ elif op == self._Opcode.HEARTBEAT_ACK:
+ self._heartbeat_latency = date.monotonic() - self._last_heartbeat_sent
+ self._logger.debug("received HEARTBEAT ACK [latency:%ss]", self._heartbeat_latency)
+
+ elif op == self._Opcode.RECONNECT:
+ self._logger.debug("RECONNECT")
+ raise self._Reconnect
+
+ elif op == self._Opcode.INVALID_SESSION:
+ self._logger.debug("INVALID SESSION [resume:%s]", data)
+ raise self._InvalidSession(data)
+
+ else:
+ self._logger.debug("ignoring unrecognised opcode %s", op)
+
+ async def _expect_opcode(self, opcode: _Opcode) -> data_binding.JSONObject:
+ message = await self._receive_json()
+ op = message["op"]
+
+ if op == opcode:
+ return typing.cast("data_binding.JSONObject", message["d"])
+
+ error_message = f"Unexpected opcode {op} received, expected {opcode}"
+ await self._close_ws(errors.ShardCloseCode.PROTOCOL_ERROR, error_message)
+ raise errors.GatewayError(error_message)
+
+ async def _receive_json(self) -> data_binding.JSONObject:
+ message = await self._receive_raw()
+
+ payload: data_binding.JSONObject
+
+ if message.type == aiohttp.WSMsgType.BINARY:
+ n, string = await self._receive_zlib_message(message.data)
+ payload = data_binding.load_json(string) # type: ignore[assignment]
+ self._log_debug_payload(
+ string, "received %s zlib encoded packets [t:%s, op:%s]", n, payload.get("t"), payload.get("op"),
+ )
+ return payload
+
+ if message.type == aiohttp.WSMsgType.TEXT:
+ string = message.data
+ payload = data_binding.load_json(string) # type: ignore[assignment]
+ self._log_debug_payload(string, "received text payload [t:%s, op:%s]", payload.get("t"), payload.get("op"))
+ return payload
+
+ # This should NEVER occur unless we broke this badly.
+ raise TypeError("Unexpected message type " + message.type)
+
+ async def _receive_zlib_message(self, first_packet: bytes) -> typing.Tuple[int, str]:
+ # Alloc new array each time; this prevents consuming a large amount of
+ # unused memory because of Discord sending massive payloads on connect
+ # initially before the payloads shrink in size. Python may not shrink
+ # this dynamically if not...
+ buff = bytearray(first_packet)
+
+ packets = 1
+
+ while not buff.endswith(b"\x00\x00\xff\xff"):
+ message = await self._receive_raw()
+ if message.type != aiohttp.WSMsgType.BINARY:
+ raise errors.GatewayError(f"Expected a binary message but got {message.type}")
+ buff.append(message.data)
+ packets += 1
+
+ return packets, self._zlib.decompress(buff).decode("utf-8")
+
+ async def _receive_raw(self) -> aiohttp.WSMessage:
+ message: aiohttp.WSMessage = await self._ws.receive() # type: ignore[union-attr]
+ self._last_message_received = date.monotonic()
+
+ if message.type == aiohttp.WSMsgType.CLOSE:
+ close_code = int(message.data)
+ reason = message.extra
+ self._logger.error("connection closed with code %s (%s)", close_code, reason)
+
+ can_reconnect = close_code < 4000 or close_code in (
+ errors.ShardCloseCode.DECODE_ERROR,
+ errors.ShardCloseCode.INVALID_SEQ,
+ errors.ShardCloseCode.UNKNOWN_ERROR,
+ errors.ShardCloseCode.SESSION_TIMEOUT,
+ errors.ShardCloseCode.RATE_LIMITED,
+ )
+
+ # Assume we can always resume first.
+ raise errors.GatewayServerClosedConnectionError(reason, close_code, can_reconnect)
+
+ if message.type == aiohttp.WSMsgType.CLOSING or message.type == aiohttp.WSMsgType.CLOSED:
+ raise self._SocketClosed
+
+ if message.type == aiohttp.WSMsgType.ERROR:
+ # Assume exception for now.
+ ex = self._ws.exception() # type: ignore[union-attr]
+ self._logger.warning(
+ "encountered unexpected error: %s",
+ ex,
+ exc_info=ex if self._logger.isEnabledFor(logging.DEBUG) else None,
+ )
+ raise errors.GatewayError("Unexpected websocket exception from gateway") from ex
+
+ return message
+
+ async def _send_json(self, payload: data_binding.JSONObject) -> None:
+ await self._ratelimiter.acquire()
+ message = data_binding.dump_json(payload)
+ self._log_debug_payload(message, "sending json payload [op:%s]", payload.get("op"))
+ await self._ws.send_str(message) # type: ignore[union-attr]
+
+ def _dispatch(self, event_name: str, event: data_binding.JSONObject) -> asyncio.Task[None]:
+ return asyncio.create_task(
+ self._event_consumer(self, event_name, event), name=f"gateway shard {self._shard_id} dispatch {event_name}",
+ )
+
+ def _log_debug_payload(self, payload: str, message: str, *args: typing.Any) -> None:
+ # Prevent logging these payloads if logging is not enabled. This aids performance a little.
+ if not self._logger.isEnabledFor(logging.DEBUG):
+ return
+
+ message = f"{message} [seq:%s, session:%s, size:%s]"
+ if self._debug:
+ message = f"{message} with raw payload: %s"
+ args = (*args, self._seq, self._session_id, len(payload), payload)
+ else:
+ args = (*args, self._seq, self._session_id, len(payload))
+
+ self._logger.debug(message, *args)
+
+ def _serialize_presence_payload(self) -> data_binding.JSONObject:
+ idle_since = self._idle_since if self._idle_since is not undefined.UNDEFINED else None
+ afk = self._is_afk if self._is_afk is not undefined.UNDEFINED else False
+ status = self._status if self._status is not undefined.UNDEFINED else presences.Status.ONLINE
+ activity = self._activity if self._activity is not undefined.UNDEFINED else None
+ presence_pl = data_binding.JSONObjectBuilder()
+
+ if activity is not None:
+ presence_pl.put("game", {"name": activity.name, "url": activity.url, "type": activity.type})
+ else:
+ presence_pl.put("game", None)
+
+ presence_pl.put("since", int(idle_since.timestamp() * 1_000) if idle_since is not None else None)
+ presence_pl.put("afk", afk)
+
+ # Turns out Discord don't document this properly. I can send "offline"
+ # to the gateway, but it will actually just result in the bot not
+ # changing the status. I have to set it to "invisible" instead to get
+ # this to work...
+ presence_pl.put("status", "invisible" if status is presences.Status.OFFLINE else status)
+
+ return presence_pl
+
+
+GatewayShardImpl = GatewayShardImplV6
+"""Most up-to-date documented and stable release."""
diff --git a/hikari/impl/special_endpoints.py b/hikari/impl/special_endpoints.py
new file mode 100644
index 0000000000..b109ef66b6
--- /dev/null
+++ b/hikari/impl/special_endpoints.py
@@ -0,0 +1,584 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Special endpoint implementations.
+
+You should never need to make any of these objects manually.
+"""
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["TypingIndicator", "GuildBuilder"]
+
+import asyncio
+import contextlib
+import datetime
+import typing
+
+import attr
+
+from hikari import errors
+from hikari.api import special_endpoints
+from hikari.models import channels
+from hikari.utilities import attr_extensions
+from hikari.utilities import data_binding
+from hikari.utilities import date
+from hikari.utilities import files
+from hikari.utilities import iterators
+from hikari.utilities import routes
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+if typing.TYPE_CHECKING:
+ import concurrent.futures
+ import types
+
+ from hikari.api import entity_factory as entity_factory_
+ from hikari.models import applications
+ from hikari.models import audit_logs
+ from hikari.models import colors
+ from hikari.models import guilds
+ from hikari.models import messages
+ from hikari.models import permissions as permissions_
+ from hikari.models import users
+
+
+@typing.final
+class TypingIndicator(special_endpoints.TypingIndicator):
+ """Result type of `hikari.api.rest.RESTClient.trigger_typing`.
+
+ This is an object that can either be awaited like a coroutine to trigger
+ the typing indicator once, or an async context manager to keep triggering
+ the typing indicator repeatedly until the context finishes.
+
+ !!! 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.
+ """
+
+ __slots__: typing.Sequence[str] = ("_route", "_request_call", "_task", "_rest_close_event", "_task_name")
+
+ def __init__(
+ self,
+ request_call: typing.Callable[
+ ..., typing.Coroutine[None, None, typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]]
+ ],
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ rest_closed_event: asyncio.Event,
+ ) -> None:
+ self._route = routes.POST_CHANNEL_TYPING.compile(channel=channel)
+ self._request_call = request_call
+ self._task_name = f"repeatedly trigger typing in {channel}"
+ self._task: typing.Optional[asyncio.Task[None]] = None
+ self._rest_close_event = rest_closed_event
+
+ def __await__(self) -> typing.Generator[typing.Any, typing.Any, typing.Any]:
+ return self._request_call(self._route).__await__()
+
+ async def __aenter__(self) -> None:
+ if self._task is not None:
+ raise TypeError("cannot enter a typing indicator context more than once.")
+ self._task = asyncio.create_task(self._keep_typing(), name=self._task_name)
+
+ async def __aexit__(
+ self,
+ exception_type: typing.Type[BaseException],
+ exception: BaseException,
+ exception_traceback: types.TracebackType,
+ ) -> None:
+ # This will always be true, but this keeps MyPy quiet.
+ if self._task is not None:
+ self._task.cancel()
+
+ async def _keep_typing(self) -> None:
+ # Cancelled error will occur when the context manager is requested to
+ # stop.
+ with contextlib.suppress(asyncio.CancelledError, errors.HTTPClientClosedError):
+ # If the REST API closes while typing, just stop.
+ while not self._rest_close_event.is_set():
+ # Use slightly less than 10s to ensure latency does not
+ # cause the typing indicator to stop showing for a split
+ # second if the request is slow to execute.
+ with contextlib.suppress(asyncio.TimeoutError):
+ await asyncio.gather(self, asyncio.wait_for(self._rest_close_event.wait(), timeout=9.0))
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, weakref_slot=False)
+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.models.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.models.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.utilities.snowflake.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,
+ hoisted: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ mentionable: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ permissions: undefined.UndefinedOr[permissions_.Permissions] = undefined.UNDEFINED,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ ) -> snowflake.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, hoisted, mentionable, position) != 5:
+ raise ValueError(
+ "Cannot pass 'color', 'colour', 'hoisted', '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("hoisted", hoisted)
+ payload.put("mentionable", mentionable)
+ payload.put("permissions", permissions)
+ 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,
+ ) -> snowflake.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 add_text_channel(
+ self,
+ name: str,
+ /,
+ *,
+ parent_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ topic: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ rate_limit_per_user: undefined.UndefinedOr[date.Intervalish] = undefined.UNDEFINED,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Collection[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ nsfw: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ ) -> snowflake.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_TEXT)
+ payload.put("topic", topic)
+ payload.put("rate_limit_per_user", rate_limit_per_user, conversion=date.timespan_to_int)
+ payload.put("position", position)
+ payload.put("nsfw", nsfw)
+ payload.put_snowflake("parent_id", parent_id)
+
+ payload.put_array(
+ "permission_overwrites",
+ permission_overwrites,
+ conversion=self._entity_factory.serialize_permission_overwrite,
+ )
+
+ self._channels.append(payload)
+ return snowflake_id
+
+ def add_voice_channel(
+ self,
+ name: str,
+ /,
+ *,
+ parent_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ bitrate: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ position: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ permission_overwrites: undefined.UndefinedOr[
+ typing.Collection[channels.PermissionOverwrite]
+ ] = undefined.UNDEFINED,
+ user_limit: undefined.UndefinedOr[int] = undefined.UNDEFINED,
+ ) -> snowflake.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_VOICE)
+ payload.put("bitrate", bitrate)
+ payload.put("position", position)
+ payload.put("user_limit", user_limit)
+ payload.put_snowflake("parent_id", parent_id)
+
+ payload.put_array(
+ "permission_overwrites",
+ permission_overwrites,
+ conversion=self._entity_factory.serialize_permission_overwrite,
+ )
+
+ self._channels.append(payload)
+ return snowflake_id
+
+ def _new_snowflake(self) -> snowflake.Snowflake:
+ value = self._counter
+ self._counter += 1
+ return snowflake.Snowflake.from_data(datetime.datetime.now(tz=datetime.timezone.utc), 0, 0, value,)
+
+
+# We use an explicit forward reference for this, since this breaks potential
+# circular import issues (once the file has executed, using those resources is
+# not an issue for us).
+class MessageIterator(iterators.BufferedLazyIterator["messages.Message"]):
+ """Implementation of an iterator for message history."""
+
+ __slots__: typing.Sequence[str] = ("_entity_factory", "_request_call", "_direction", "_first_id", "_route")
+
+ def __init__(
+ self,
+ entity_factory: entity_factory_.EntityFactory,
+ request_call: typing.Callable[
+ ..., typing.Coroutine[None, None, typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]]
+ ],
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ direction: str,
+ first_id: undefined.UndefinedOr[str],
+ ) -> None:
+ super().__init__()
+ self._entity_factory = entity_factory
+ self._request_call = request_call
+ self._direction = direction
+ self._first_id = first_id
+ self._route = routes.GET_CHANNEL_MESSAGES.compile(channel=channel)
+
+ async def _next_chunk(self) -> typing.Optional[typing.Generator[messages.Message, typing.Any, None]]:
+ query = data_binding.StringMapBuilder()
+ query.put(self._direction, self._first_id)
+ query.put("limit", 100)
+
+ raw_chunk = await self._request_call(compiled_route=self._route, query=query)
+ chunk = typing.cast(data_binding.JSONArray, raw_chunk)
+
+ if not chunk:
+ return None
+ if self._direction == "after":
+ chunk.reverse()
+
+ self._first_id = chunk[-1]["id"]
+ return (self._entity_factory.deserialize_message(m) for m in chunk)
+
+
+# We use an explicit forward reference for this, since this breaks potential
+# circular import issues (once the file has executed, using those resources is
+# not an issue for us).
+class ReactorIterator(iterators.BufferedLazyIterator["users.User"]):
+ """Implementation of an iterator for message reactions."""
+
+ __slots__: typing.Sequence[str] = ("_entity_factory", "_first_id", "_route", "_request_call")
+
+ def __init__(
+ self,
+ entity_factory: entity_factory_.EntityFactory,
+ request_call: typing.Callable[
+ ..., typing.Coroutine[None, None, typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]]
+ ],
+ channel: snowflake.SnowflakeishOr[channels.TextChannel],
+ message: snowflake.SnowflakeishOr[messages.Message],
+ emoji: str,
+ ) -> None:
+ super().__init__()
+ self._entity_factory = entity_factory
+ self._request_call = request_call
+ self._first_id = undefined.UNDEFINED
+ self._route = routes.GET_REACTIONS.compile(channel=channel, message=message, emoji=emoji)
+
+ async def _next_chunk(self) -> typing.Optional[typing.Generator[users.User, typing.Any, None]]:
+ query = data_binding.StringMapBuilder()
+ query.put("after", self._first_id)
+ query.put("limit", 100)
+
+ raw_chunk = await self._request_call(compiled_route=self._route, query=query)
+ chunk = typing.cast(data_binding.JSONArray, raw_chunk)
+
+ if not chunk:
+ return None
+
+ self._first_id = chunk[-1]["id"]
+ return (self._entity_factory.deserialize_user(u) for u in chunk)
+
+
+# We use an explicit forward reference for this, since this breaks potential
+# circular import issues (once the file has executed, using those resources is
+# not an issue for us).
+class OwnGuildIterator(iterators.BufferedLazyIterator["applications.OwnGuild"]):
+ """Implementation of an iterator for retrieving guilds you are in."""
+
+ __slots__: typing.Sequence[str] = ("_entity_factory", "_request_call", "_route", "_newest_first", "_first_id")
+
+ def __init__(
+ self,
+ entity_factory: entity_factory_.EntityFactory,
+ request_call: typing.Callable[
+ ..., typing.Coroutine[None, None, typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]]
+ ],
+ newest_first: bool,
+ first_id: str,
+ ) -> None:
+ super().__init__()
+ self._entity_factory = entity_factory
+ self._newest_first = newest_first
+ self._request_call = request_call
+ self._first_id = first_id
+ self._route = routes.GET_MY_GUILDS.compile()
+
+ async def _next_chunk(self) -> typing.Optional[typing.Generator[applications.OwnGuild, typing.Any, None]]:
+ query = data_binding.StringMapBuilder()
+ query.put("before" if self._newest_first else "after", self._first_id)
+ query.put("limit", 100)
+
+ raw_chunk = await self._request_call(compiled_route=self._route, query=query)
+ chunk = typing.cast(data_binding.JSONArray, raw_chunk)
+
+ if not chunk:
+ return None
+
+ self._first_id = chunk[-1]["id"]
+ return (self._entity_factory.deserialize_own_guild(g) for g in chunk)
+
+
+# We use an explicit forward reference for this, since this breaks potential
+# circular import issues (once the file has executed, using those resources is
+# not an issue for us).
+class MemberIterator(iterators.BufferedLazyIterator["guilds.Member"]):
+ """Implementation of an iterator for retrieving members in a guild."""
+
+ __slots__: typing.Sequence[str] = ("_entity_factory", "_guild_id", "_request_call", "_route", "_first_id")
+
+ def __init__(
+ self,
+ entity_factory: entity_factory_.EntityFactory,
+ request_call: typing.Callable[
+ ..., typing.Coroutine[None, None, typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]]
+ ],
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ ) -> None:
+ super().__init__()
+ self._guild_id = snowflake.Snowflake(str(int(guild)))
+ self._route = routes.GET_GUILD_MEMBERS.compile(guild=guild)
+ self._request_call = request_call
+ self._entity_factory = entity_factory
+ # This starts at the default provided by discord instead of the max snowflake
+ # because that caused discord to take about 2 seconds more to return the first response.
+ self._first_id = undefined.UNDEFINED
+
+ async def _next_chunk(self) -> typing.Optional[typing.Generator[guilds.Member, typing.Any, None]]:
+ query = data_binding.StringMapBuilder()
+ query.put("after", self._first_id)
+ query.put("limit", 100)
+
+ raw_chunk = await self._request_call(compiled_route=self._route, query=query)
+ chunk = typing.cast(data_binding.JSONArray, raw_chunk)
+
+ if not chunk:
+ return None
+
+ # noinspection PyTypeChecker
+ self._first_id = chunk[-1]["user"]["id"]
+
+ return (self._entity_factory.deserialize_member(m, guild_id=self._guild_id) for m in chunk)
+
+
+# We use an explicit forward reference for this, since this breaks potential
+# circular import issues (once the file has executed, using those resources is
+# not an issue for us).
+class AuditLogIterator(iterators.LazyIterator["audit_logs.AuditLog"]):
+ """Iterator implementation for an audit log."""
+
+ __slots__: typing.Sequence[str] = (
+ "_entity_factory",
+ "_action_type",
+ "_request_call",
+ "_route",
+ "_first_id",
+ "_user",
+ )
+
+ def __init__(
+ self,
+ entity_factory: entity_factory_.EntityFactory,
+ request_call: typing.Callable[
+ ..., typing.Coroutine[None, None, typing.Union[None, data_binding.JSONObject, data_binding.JSONArray]]
+ ],
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ before: undefined.UndefinedOr[str],
+ user: undefined.UndefinedOr[snowflake.SnowflakeishOr[users.PartialUser]],
+ action_type: undefined.UndefinedOr[int],
+ ) -> None:
+ self._action_type = action_type
+ self._entity_factory = entity_factory
+ self._first_id = before
+ self._request_call = request_call
+ self._route = routes.GET_GUILD_AUDIT_LOGS.compile(guild=guild)
+ self._user = user
+
+ async def __anext__(self) -> audit_logs.AuditLog:
+ query = data_binding.StringMapBuilder()
+ query.put("limit", 100)
+ query.put("user_id", self._user)
+ query.put("event_type", self._action_type)
+ query.put("before", self._first_id)
+
+ raw_response = await self._request_call(compiled_route=self._route, query=query)
+ response = typing.cast(data_binding.JSONObject, raw_response)
+
+ if not response["audit_log_entries"]:
+ raise StopAsyncIteration
+
+ log = self._entity_factory.deserialize_audit_log(response)
+ self._first_id = str(min(log.entries.keys()))
+ return log
diff --git a/hikari/impl/stateful_cache.py b/hikari/impl/stateful_cache.py
new file mode 100644
index 0000000000..4661ecb488
--- /dev/null
+++ b/hikari/impl/stateful_cache.py
@@ -0,0 +1,2074 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic implementation of a cache for general bots and gateway apps."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StatefulCacheImpl"]
+
+import abc
+import array
+import bisect
+import copy
+import datetime
+import itertools
+import logging
+import reprlib
+import typing
+
+import attr
+
+from hikari import errors
+from hikari.api import cache
+from hikari.models import channels
+from hikari.models import emojis
+from hikari.models import guilds
+from hikari.models import intents as intents_
+from hikari.models import invites
+from hikari.models import presences
+from hikari.models import users
+from hikari.models import voices
+from hikari.utilities import attr_extensions
+from hikari.utilities import date
+from hikari.utilities import iterators
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+
+
+_DataT = typing.TypeVar("_DataT", bound="_BaseData[typing.Any]")
+_KeyT = typing.TypeVar("_KeyT", bound=typing.Hashable)
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari.cache")
+_ValueT = typing.TypeVar("_ValueT")
+
+
+class _IDTable(typing.MutableSet[snowflake.Snowflake]):
+ """Compact 64-bit integer bisected-array-set of snowflakes."""
+
+ __slots__: typing.Sequence[str] = ("_ids",)
+
+ def __init__(self) -> None:
+ self._ids = array.array("Q")
+
+ def add(self, sf: snowflake.Snowflake) -> None:
+ if not self._ids:
+ self._ids.append(sf)
+ else:
+ index = bisect.bisect_left(self._ids, sf)
+ if len(self._ids) == index or self._ids[index] != sf:
+ self._ids.insert(index, sf)
+
+ def add_all(self, sfs: typing.Iterable[snowflake.Snowflake]) -> None:
+ for sf in sfs:
+ self.add(sf)
+
+ def discard(self, sf: snowflake.Snowflake) -> None:
+ index = self._index_of(sf)
+ if index != -1:
+ del self._ids[index]
+
+ def _index_of(self, sf: int) -> int:
+ index = bisect.bisect_left(self._ids, sf)
+ return index if index < len(self._ids) or self._ids[index] == sf else -1
+
+ def __contains__(self, value: typing.Any) -> bool:
+ if not isinstance(value, int):
+ return False
+
+ return self._index_of(value) != -1
+
+ def __len__(self) -> int:
+ return len(self._ids)
+
+ def __iter__(self) -> typing.Iterator[snowflake.Snowflake]:
+ return map(snowflake.Snowflake, self._ids)
+
+ def __repr__(self) -> str:
+ return "SnowflakeTable" + reprlib.repr(self._ids)[5:]
+
+
+class _StatefulCacheMappingView(cache.CacheView[_KeyT, _ValueT], typing.Generic[_KeyT, _ValueT]):
+ __slots__: typing.Sequence[str] = ("_builder", "_data", "_unpack", "_predicate")
+
+ def __init__(
+ self,
+ items: typing.Mapping[_KeyT, typing.Union[_ValueT, _DataT, _GenericRefWrapper[_ValueT]]],
+ *,
+ builder: typing.Optional[typing.Callable[[_DataT], _ValueT]] = None,
+ unpack: bool = False,
+ predicate: typing.Optional[typing.Callable[[typing.Any], bool]] = None,
+ ) -> None:
+ self._builder = builder
+ self._data = items
+ self._unpack = unpack
+ self._predicate = predicate
+
+ @classmethod
+ def _copy(cls, value: _ValueT) -> _ValueT:
+ return copy.copy(value)
+
+ def __contains__(self, key: typing.Any) -> bool:
+ return key in self._data and (self._predicate is None or self._predicate(self._data[key]))
+
+ def __getitem__(self, key: _KeyT) -> _ValueT:
+ entry = self._data[key]
+
+ if self._predicate is not None and not self._predicate(entry):
+ raise KeyError(key)
+
+ if self._builder is not None:
+ entry = self._builder(entry) # type: ignore[arg-type]
+ elif self._unpack:
+ assert isinstance(entry, _GenericRefWrapper)
+ entry = self._copy(entry.object)
+ else:
+ entry = self._copy(entry) # type: ignore[arg-type]
+
+ return entry
+
+ def __iter__(self) -> typing.Iterator[_KeyT]:
+ if self._predicate is None:
+ return iter(self._data)
+ else:
+ return (key for key, value in self._data.items() if self._predicate(value))
+
+ def __len__(self) -> int:
+ if self._predicate is None:
+ return len(self._data)
+ else:
+ return sum(1 for value in self._data.values() if self._predicate(value))
+
+ def get_item_at(self, index: int) -> _ValueT:
+ current_index = -1
+
+ for key, value in self._data.items():
+ if self._predicate is None or self._predicate(value):
+ index += 1
+
+ if current_index == index:
+ return self[key]
+
+ raise IndexError(index)
+
+ def iterator(self) -> iterators.LazyIterator[_ValueT]:
+ return iterators.FlatLazyIterator(self.values())
+
+
+class _EmptyCacheView(cache.CacheView[typing.Any, typing.Any]):
+ __slots__: typing.Sequence[str] = ()
+
+ def __contains__(self, _: typing.Any) -> typing.Literal[False]:
+ return False
+
+ def __getitem__(self, key: typing.Any) -> typing.NoReturn:
+ raise KeyError(key)
+
+ def __iter__(self) -> typing.Iterator[typing.Any]:
+ yield from ()
+
+ def __len__(self) -> typing.Literal[0]:
+ return 0
+
+ def get_item_at(self, index: int) -> typing.NoReturn:
+ raise IndexError(index)
+
+ def iterator(self) -> iterators.LazyIterator[_ValueT]:
+ return iterators.FlatLazyIterator(())
+
+
+@attr_extensions.with_copy
+@attr.s(slots=True, repr=False, hash=False, weakref_slot=False)
+class _GuildRecord:
+ is_available: typing.Optional[bool] = attr.ib(default=None)
+ guild: typing.Optional[guilds.GatewayGuild] = attr.ib(default=None)
+ # TODO: some of these will be iterated across more than they will searched by a specific ID...
+ # ... identify these cases and convert to lists.
+ channels: typing.Optional[typing.MutableSet[snowflake.Snowflake]] = attr.ib(default=None)
+ emojis: typing.Optional[typing.MutableSet[snowflake.Snowflake]] = attr.ib(default=None)
+ invites: typing.Optional[typing.MutableSequence[str]] = attr.ib(default=None)
+ members: typing.Optional[typing.MutableMapping[snowflake.Snowflake, _MemberData]] = attr.ib(default=None)
+ presences: typing.Optional[typing.MutableMapping[snowflake.Snowflake, _MemberPresenceData]] = attr.ib(default=None)
+ roles: typing.Optional[typing.MutableSet[snowflake.Snowflake]] = attr.ib(default=None)
+ voice_states: typing.Optional[typing.MutableMapping[snowflake.Snowflake, _VoiceStateData]] = attr.ib(default=None)
+
+ _FIELDS_TO_CHECK: typing.Final[typing.Collection[str]] = (
+ "channels",
+ "emojis",
+ "guild",
+ "invites",
+ "members",
+ "presences",
+ "roles",
+ "voice_states",
+ )
+
+ def __bool__(self) -> bool:
+ return any(getattr(self, attribute) for attribute in self._FIELDS_TO_CHECK)
+
+
+@attr.s(slots=True, repr=False, hash=False, init=True, weakref_slot=False)
+class _BaseData(abc.ABC, typing.Generic[_ValueT]):
+ """A data class used for storing entities in a more primitive form.
+
+ !!! note
+ This base implementation assumes that all the fields it'll handle will
+ be immutable and to handle mutable fields you'll have to override
+ build_entity and build_from_entity to explicitly copy them.
+ """
+
+ __slots__: typing.Sequence[str] = ()
+
+ @classmethod
+ @abc.abstractmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ """Get the fields that should be automatically handled on the target entity.
+
+ !!! note
+ These fields should match up with both the target entity and the
+ data class itself.
+
+ Returns
+ -------
+ typing.Collection[builtins.str]
+ A collection of the names of fields to handle.
+ """
+
+ def build_entity(self, target: typing.Type[_ValueT], **kwargs: typing.Any) -> _ValueT:
+ """Build an entity object from this data object.
+
+ Parameters
+ ----------
+ target
+ The class of the entity object to add attributes to.
+ kwargs
+ Extra fields to pass on to the entity's initialiser. These will take
+ priority over fields on the builder.
+
+ Returns
+ -------
+ The initialised entity object.
+ """
+ for field in self.get_fields():
+ if field not in kwargs:
+ kwargs[field] = getattr(self, field)
+
+ return target(**kwargs) # type: ignore[call-arg]
+
+ @classmethod
+ def build_from_entity(cls: typing.Type[_DataT], entity: _ValueT, **kwargs: typing.Any) -> _DataT:
+ """Build a data object from an initialised entity.
+
+ Parameters
+ ----------
+ entity
+ The entity object to build a data class from.
+ kwargs
+ Extra fields to add to the data class. Fields here will take
+ priority over fields on `entity`.
+
+ Returns
+ -------
+ The built data class.
+ """
+ for field in cls.get_fields():
+ if field not in kwargs:
+ kwargs[field] = getattr(entity, field)
+
+ return cls(**kwargs) # type: ignore[call-arg]
+
+ def replace(self: _DataT, **kwargs: typing.Any) -> _DataT:
+ data = copy.copy(self)
+
+ for attribute, value in kwargs.items():
+ setattr(data, attribute, value)
+
+ return data
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _PrivateTextChannelData(_BaseData[channels.PrivateTextChannel]):
+ id: snowflake.Snowflake = attr.ib()
+ name: typing.Optional[str] = attr.ib()
+ last_message_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ recipient_id: snowflake.Snowflake = attr.ib()
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return "id", "name", "last_message_id"
+
+ def build_entity(
+ self, target: typing.Type[channels.PrivateTextChannel], **kwargs: typing.Any
+ ) -> channels.PrivateTextChannel:
+ return super().build_entity(target, type=channels.ChannelType.PRIVATE_TEXT, **kwargs)
+
+ @classmethod
+ def build_from_entity(
+ cls: typing.Type[_PrivateTextChannelData], entity: channels.PrivateTextChannel, **kwargs: typing.Any
+ ) -> _PrivateTextChannelData:
+ return super().build_from_entity(entity, **kwargs, recipient_id=entity.recipient.id)
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _InviteData(_BaseData[invites.InviteWithMetadata]):
+ code: str = attr.ib()
+ guild_id: typing.Optional[snowflake.Snowflake] = attr.ib() # TODO: This should not ever be none here
+ channel_id: snowflake.Snowflake = attr.ib()
+ inviter_id: typing.Optional[
+ snowflake.Snowflake
+ ] = attr.ib() # TODO: do we get these events if we don't have manage invite perm? ( we don't )
+ target_user_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ target_user_type: typing.Optional[invites.TargetUserType] = attr.ib()
+ uses: int = attr.ib()
+ max_uses: typing.Optional[int] = attr.ib()
+ max_age: typing.Optional[datetime.timedelta] = attr.ib()
+ is_temporary: bool = attr.ib()
+ created_at: datetime.datetime = attr.ib()
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return (
+ "code",
+ "guild_id",
+ "channel_id",
+ "target_user_type",
+ "uses",
+ "max_uses",
+ "max_age",
+ "is_temporary",
+ "created_at",
+ )
+
+ def build_entity(
+ self, target: typing.Type[invites.InviteWithMetadata], **kwargs: typing.Any
+ ) -> invites.InviteWithMetadata:
+ return super().build_entity(
+ target, approximate_member_count=None, approximate_presence_count=None, channel=None, guild=None, **kwargs,
+ )
+
+ @classmethod
+ def build_from_entity(
+ cls: typing.Type[_InviteData], entity: invites.InviteWithMetadata, **kwargs: typing.Any
+ ) -> _InviteData:
+ return super().build_from_entity(
+ entity,
+ **kwargs,
+ inviter_id=entity.inviter.id if entity.inviter is not None else None,
+ target_user_id=entity.target_user.id if entity.target_user is not None else None,
+ )
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _MemberData(_BaseData[guilds.Member]):
+ id: snowflake.Snowflake = attr.ib()
+ guild_id: snowflake.Snowflake = attr.ib()
+ nickname: undefined.UndefinedNoneOr[str] = attr.ib()
+ role_ids: typing.Tuple[snowflake.Snowflake, ...] = attr.ib()
+ joined_at: undefined.UndefinedOr[datetime.datetime] = attr.ib()
+ premium_since: undefined.UndefinedNoneOr[datetime.datetime] = attr.ib()
+ is_deaf: undefined.UndefinedOr[bool] = attr.ib()
+ is_mute: undefined.UndefinedOr[bool] = attr.ib()
+ # meta-attribute
+ has_been_deleted: bool = attr.ib(default=False)
+ ref_count: int = attr.ib(default=0)
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return "guild_id", "nickname", "role_ids", "joined_at", "premium_since", "is_deaf", "is_mute"
+
+ @classmethod
+ def build_from_entity(cls: typing.Type[_MemberData], entity: guilds.Member, **kwargs: typing.Any) -> _MemberData:
+ return super().build_from_entity(entity, **kwargs, id=entity.user.id, role_ids=tuple(entity.role_ids))
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _KnownCustomEmojiData(_BaseData[emojis.KnownCustomEmoji]):
+ id: snowflake.Snowflake = attr.ib()
+ name: typing.Optional[str] = attr.ib() # TODO: should not ever be None here
+ is_animated: typing.Optional[bool] = attr.ib() # TODO: should not ever be None here
+ guild_id: snowflake.Snowflake = attr.ib()
+ role_ids: typing.Tuple[snowflake.Snowflake, ...] = attr.ib()
+ user_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ is_colons_required: bool = attr.ib()
+ is_managed: bool = attr.ib()
+ is_available: bool = attr.ib()
+ # meta-attributes
+ has_been_deleted: bool = attr.ib(default=False) # We need test coverage for this systm
+ ref_count: int = attr.ib(default=0)
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return "id", "name", "is_animated", "guild_id", "role_ids", "is_colons_required", "is_managed", "is_available"
+
+ @classmethod
+ def build_from_entity(
+ cls: typing.Type[_KnownCustomEmojiData], entity: emojis.KnownCustomEmoji, **kwargs: typing.Any
+ ) -> _KnownCustomEmojiData:
+ return super().build_from_entity(
+ entity, **kwargs, user_id=entity.user.id if entity.user else None, role_ids=tuple(entity.role_ids)
+ )
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _RichActivityData(_BaseData[presences.RichActivity]):
+ name: str = attr.ib()
+ url: str = attr.ib()
+ type: presences.ActivityType = attr.ib()
+ created_at: datetime.datetime = attr.ib()
+ timestamps: typing.Optional[presences.ActivityTimestamps] = attr.ib()
+ application_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ details: typing.Optional[str] = attr.ib()
+ state: typing.Optional[str] = attr.ib()
+ emoji_id_or_name: typing.Union[snowflake.Snowflake, str, None] = attr.ib()
+ party: typing.Optional[presences.ActivityParty] = attr.ib()
+ assets: typing.Optional[presences.ActivityAssets] = attr.ib()
+ secrets: typing.Optional[presences.ActivitySecret] = attr.ib()
+ is_instance: typing.Optional[bool] = attr.ib()
+ flags: typing.Optional[presences.ActivityFlag] = attr.ib()
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return "name", "url", "type", "created_at", "application_id", "details", "state", "is_instance", "flags"
+
+ @classmethod
+ def build_from_entity(
+ cls: typing.Type[_RichActivityData], entity: presences.RichActivity, **kwargs: typing.Any
+ ) -> _RichActivityData:
+ emoji_id_or_name: typing.Union[snowflake.Snowflake, str, None]
+ if entity.emoji is None:
+ emoji_id_or_name = None
+ elif isinstance(entity.emoji, emojis.CustomEmoji):
+ emoji_id_or_name = entity.emoji.id
+ else:
+ emoji_id_or_name = entity.emoji.name
+
+ timestamps = copy.copy(entity.timestamps) if entity.timestamps is not None else None
+ party = copy.copy(entity.party) if entity.party is not None else None
+ assets = copy.copy(entity.assets) if entity.assets is not None else None
+ secrets = copy.copy(entity.secrets) if entity.secrets is not None else None
+ return super().build_from_entity(
+ entity,
+ emoji_id_or_name=emoji_id_or_name,
+ timestamps=timestamps,
+ party=party,
+ assets=assets,
+ secrets=secrets,
+ )
+
+ def build_entity(self, target: typing.Type[presences.RichActivity], **kwargs: typing.Any) -> presences.RichActivity:
+ return super().build_entity(
+ target,
+ timestamps=copy.copy(self.timestamps) if self.timestamps is not None else None,
+ party=copy.copy(self.party) if self.party is not None else None,
+ assets=copy.copy(self.assets) if self.assets is not None else None,
+ secrets=copy.copy(self.secrets) if self.secrets is not None else None,
+ **kwargs,
+ )
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _MemberPresenceData(_BaseData[presences.MemberPresence]):
+ user_id: snowflake.Snowflake = attr.ib()
+ role_ids: typing.Optional[typing.Tuple[snowflake.Snowflake, ...]] = attr.ib()
+ guild_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ visible_status: presences.Status = attr.ib()
+ activities: typing.Tuple[_RichActivityData, ...] = attr.ib()
+ client_status: presences.ClientStatus = attr.ib()
+ premium_since: typing.Optional[datetime.datetime] = attr.ib()
+ nickname: typing.Optional[str] = attr.ib()
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return "user_id", "role_ids", "guild_id", "visible_status", "premium_since", "nickname"
+
+ @classmethod
+ def build_from_entity(
+ cls: typing.Type[_MemberPresenceData], entity: presences.MemberPresence, **kwargs: typing.Any
+ ) -> _MemberPresenceData:
+ return super().build_from_entity(
+ entity,
+ role_ids=tuple(entity.role_ids) if entity.role_ids is not None else None,
+ activities=tuple(_RichActivityData.build_from_entity(activity) for activity in entity.activities),
+ client_status=copy.copy(entity.client_status),
+ )
+
+ def build_entity(
+ self, target: typing.Type[presences.MemberPresence], **kwargs: typing.Any,
+ ) -> presences.MemberPresence:
+ presence_kwargs = kwargs.pop("presence_kwargs")
+ activities = [
+ activity.build_entity(presences.RichActivity, **kwargs_)
+ for activity, kwargs_ in zip(self.activities, presence_kwargs)
+ ]
+ return super().build_entity(
+ target, activities=activities, client_status=copy.copy(self.client_status), **kwargs
+ )
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _VoiceStateData(_BaseData[voices.VoiceState]):
+ channel_id: typing.Optional[snowflake.Snowflake] = attr.ib()
+ guild_id: snowflake.Snowflake = attr.ib()
+ is_guild_deafened: bool = attr.ib()
+ is_guild_muted: bool = attr.ib()
+ is_self_deafened: bool = attr.ib()
+ is_self_muted: bool = attr.ib()
+ is_streaming: bool = attr.ib()
+ is_suppressed: bool = attr.ib()
+ is_video_enabled: bool = attr.ib()
+ user_id: snowflake.Snowflake = attr.ib()
+ session_id: str = attr.ib()
+
+ @classmethod
+ def get_fields(cls) -> typing.Collection[str]:
+ return (
+ "channel_id",
+ "guild_id",
+ "is_guild_deafened",
+ "is_guild_muted",
+ "is_self_deafened",
+ "is_self_muted",
+ "is_streaming",
+ "is_suppressed",
+ "is_video_enabled",
+ "user_id",
+ "session_id",
+ )
+
+
+@attr_extensions.with_copy
+@attr.s(kw_only=True, slots=True, repr=False, hash=False, weakref_slot=False)
+class _GenericRefWrapper(typing.Generic[_ValueT]):
+ object: _ValueT = attr.ib()
+ ref_count: int = attr.ib(default=0)
+
+
+class _PrivateTextChannelMRUMutableMapping(typing.MutableMapping[snowflake.Snowflake, _PrivateTextChannelData]):
+ __slots__: typing.Sequence[str] = ("_data", "_expiry")
+
+ def __init__(
+ self,
+ source: typing.Union[typing.Mapping[snowflake.Snowflake, _PrivateTextChannelData], None] = None,
+ /,
+ *,
+ expiry: datetime.timedelta,
+ ) -> None:
+ if expiry <= datetime.timedelta():
+ raise ValueError("expiry time must be greater than 0 microseconds.")
+
+ self._data: typing.Dict[snowflake.Snowflake, _PrivateTextChannelData] = dict(source or ())
+ self._expiry = expiry
+
+ def _garbage_collect(self) -> None:
+ current_time = date.utc_datetime()
+ for channel_id, channel in tuple(self._data.items()):
+ if channel.last_message_id and current_time - channel.last_message_id.created_at < self._expiry:
+ break
+
+ del self._data[channel_id]
+
+ def __delitem__(self, sf: snowflake.Snowflake) -> None:
+ del self._data[sf]
+ self._garbage_collect()
+
+ def __getitem__(self, sf: snowflake.Snowflake) -> _PrivateTextChannelData:
+ return self._data[sf]
+
+ def __iter__(self) -> typing.Iterator[snowflake.Snowflake]:
+ return iter(self._data)
+
+ def __len__(self) -> int:
+ return len(self._data)
+
+ def __setitem__(self, sf: snowflake.Snowflake, value: _PrivateTextChannelData) -> None:
+ self._garbage_collect()
+ # Seeing as we rely on insertion order in _garbage_collect, we have to make sure that each item is added to
+ # the end of the dict.
+ if value.last_message_id is not None and sf in self:
+ del self[sf]
+
+ self._data[sf] = value
+
+
+def _copy_guild_channel(channel: channels.GuildChannel) -> channels.GuildChannel:
+ channel = copy.copy(channel)
+ channel.permission_overwrites = {
+ sf: copy.copy(channel.permission_overwrites[sf]) for sf in channel.permission_overwrites
+ }
+ return channel
+
+
+class _GuildChannelCacheMappingView(_StatefulCacheMappingView[snowflake.Snowflake, channels.GuildChannel]):
+ __slots__: typing.Sequence[str] = ()
+
+ @classmethod
+ def _copy(cls, value: channels.GuildChannel) -> channels.GuildChannel:
+ return _copy_guild_channel(value)
+
+
+class _3DCacheMappingView(_StatefulCacheMappingView[snowflake.Snowflake, cache.CacheView[_KeyT, _ValueT]]):
+ __slots__: typing.Sequence[str] = ()
+
+ @classmethod
+ def _copy(cls, value: cache.CacheView[_KeyT, _ValueT]) -> cache.CacheView[_KeyT, _ValueT]:
+ return value
+
+
+class StatefulCacheImpl(cache.MutableCache):
+ """In-memory cache implementation."""
+
+ __slots__: typing.Sequence[str] = (
+ "_app",
+ "_private_text_channel_entries",
+ "_emoji_entries",
+ "_guild_channel_entries",
+ "_guild_entries",
+ "_intents",
+ "_invite_entries",
+ "_me",
+ "_role_entries",
+ "_unknown_emoji_entries",
+ "_user_entries",
+ )
+
+ def __init__(self, app: traits.RESTAware, intents: typing.Optional[intents_.Intents]) -> None:
+ self._app = app
+ self._me: typing.Optional[users.OwnUser] = None
+ self._private_text_channel_entries: typing.MutableMapping[
+ snowflake.Snowflake, _PrivateTextChannelData
+ ] = _PrivateTextChannelMRUMutableMapping(expiry=datetime.timedelta(minutes=5))
+ self._emoji_entries: typing.MutableMapping[snowflake.Snowflake, _KnownCustomEmojiData] = {}
+ self._guild_channel_entries: typing.MutableMapping[snowflake.Snowflake, channels.GuildChannel] = {}
+ self._guild_entries: typing.MutableMapping[snowflake.Snowflake, _GuildRecord] = {}
+ self._invite_entries: typing.MutableMapping[str, _InviteData] = {}
+ self._role_entries: typing.MutableMapping[snowflake.Snowflake, guilds.Role] = {}
+ self._unknown_emoji_entries: typing.MutableMapping[
+ typing.Union[str, snowflake.Snowflake],
+ _GenericRefWrapper[typing.Union[emojis.UnicodeEmoji, emojis.CustomEmoji]],
+ ] = {}
+ self._user_entries: typing.MutableMapping[snowflake.Snowflake, _GenericRefWrapper[users.User]] = {}
+
+ self._intents = intents
+
+ def _assert_has_intent(self, intents: intents_.Intents, /) -> None:
+ if self._intents is not None and self._intents ^ intents:
+ raise errors.MissingIntentError(intents) from None
+
+ def _is_intent_enabled(self, intents: intents_.Intents, /) -> bool:
+ return self._intents is None or (self._intents & intents) == intents
+
+ def _build_private_text_channel(
+ self,
+ channel_data: _PrivateTextChannelData,
+ cached_users: typing.Optional[typing.Mapping[snowflake.Snowflake, _GenericRefWrapper[users.User]]] = None,
+ ) -> channels.PrivateTextChannel:
+ if cached_users:
+ recipient = copy.copy(cached_users[channel_data.recipient_id].object)
+ else:
+ recipient = copy.copy(self._user_entries[channel_data.recipient_id].object)
+
+ return channel_data.build_entity(channels.PrivateTextChannel, app=self._app, recipient=recipient)
+
+ def clear_private_text_channels(self) -> cache.CacheView[snowflake.Snowflake, channels.PrivateTextChannel]:
+ if not self._private_text_channel_entries:
+ return _EmptyCacheView()
+
+ cached_channels = self._private_text_channel_entries
+ self._private_text_channel_entries = {}
+ cached_users = {}
+
+ for user_id in cached_channels.keys():
+ cached_users[user_id] = self._user_entries[user_id]
+ self._garbage_collect_user(user_id, decrement=1)
+
+ return _StatefulCacheMappingView(
+ cached_channels, builder=lambda channel: self._build_private_text_channel(channel, cached_users)
+ )
+
+ def delete_private_text_channel(
+ self, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[channels.PrivateTextChannel]:
+ channel_data = self._private_text_channel_entries.pop(user_id, None)
+ if channel_data is None:
+ return None
+
+ channel = self._build_private_text_channel(channel_data)
+ self._garbage_collect_user(user_id, decrement=1)
+ return channel
+
+ def get_private_text_channel(self, user_id: snowflake.Snowflake, /) -> typing.Optional[channels.PrivateTextChannel]:
+ if user_id in self._private_text_channel_entries:
+ return self._build_private_text_channel(self._private_text_channel_entries[user_id])
+
+ return None
+
+ def get_private_text_channels_view(self) -> cache.CacheView[snowflake.Snowflake, channels.PrivateTextChannel]:
+ if not self._private_text_channel_entries:
+ return _EmptyCacheView()
+
+ cached_channels = dict(self._private_text_channel_entries)
+ cached_users = {user_id: self._user_entries[user_id] for user_id in cached_channels}
+ return _StatefulCacheMappingView(
+ cached_channels, builder=lambda channel: self._build_private_text_channel(channel, cached_users),
+ )
+
+ def set_private_text_channel(self, channel: channels.PrivateTextChannel, /) -> None:
+ self.set_user(channel.recipient)
+
+ if channel.recipient.id not in self._private_text_channel_entries:
+ self._increment_user_ref_count(channel.recipient.id)
+
+ self._private_text_channel_entries[channel.recipient.id] = _PrivateTextChannelData.build_from_entity(channel)
+
+ def update_private_text_channel(
+ self, channel: channels.PrivateTextChannel, /
+ ) -> typing.Tuple[typing.Optional[channels.PrivateTextChannel], typing.Optional[channels.PrivateTextChannel]]:
+ cached_channel = self.get_private_text_channel(channel.recipient.id)
+ self.set_private_text_channel(channel)
+ return cached_channel, self.get_private_text_channel(channel.recipient.id)
+
+ def _build_emoji(
+ self,
+ emoji_data: _KnownCustomEmojiData,
+ cached_users: typing.Optional[typing.Mapping[snowflake.Snowflake, _GenericRefWrapper[users.User]]] = None,
+ ) -> emojis.KnownCustomEmoji:
+ user: typing.Optional[users.User]
+ if cached_users is not None and emoji_data.user_id is not None:
+ user = copy.copy(cached_users[emoji_data.user_id].object)
+ elif emoji_data.user_id is not None:
+ user = copy.copy(self._user_entries[emoji_data.user_id].object)
+ else:
+ user = None
+
+ return emoji_data.build_entity(emojis.KnownCustomEmoji, app=self._app, user=user)
+
+ def _increment_emoji_ref_count(self, emoji_id: snowflake.Snowflake, increment: int = 1) -> None:
+ self._emoji_entries[emoji_id].ref_count += increment
+
+ def _garbage_collect_emoji(self, emoji_id: snowflake.Snowflake, decrement: int = 0) -> None:
+ emoji_data = self._emoji_entries.get(emoji_id)
+
+ if emoji_data is None:
+ return None
+
+ emoji_data.ref_count -= decrement
+
+ if self._can_remove_emoji(emoji_data):
+ del self._emoji_entries[emoji_id]
+
+ @staticmethod
+ def _can_remove_emoji(emoji: _KnownCustomEmojiData) -> bool:
+ return emoji.has_been_deleted is True and emoji.ref_count < 1
+
+ def _clear_emojis(
+ self, guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ emoji_ids: typing.Iterable[snowflake.Snowflake]
+ if guild_id is undefined.UNDEFINED:
+ emoji_ids = tuple(self._emoji_entries.keys())
+ else:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.emojis is None: # TODO: explicit is vs implicit bool consistency
+ return _EmptyCacheView()
+
+ emoji_ids = guild_record.emojis
+ guild_record.emojis = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ cached_emojis = {}
+ cached_users = {}
+
+ for emoji_id in emoji_ids:
+ emoji_data = self._emoji_entries[emoji_id]
+ emoji_data.has_been_deleted = True
+ if not self._can_remove_emoji(emoji_data):
+ continue
+
+ del self._emoji_entries[emoji_id]
+ cached_emojis[emoji_id] = emoji_data
+
+ if emoji_data.user_id is not None:
+ cached_users[emoji_data.user_id] = self._user_entries[emoji_data.user_id]
+ self._garbage_collect_user(emoji_data.user_id, decrement=1)
+
+ return _StatefulCacheMappingView(
+ cached_emojis, builder=lambda emoji: self._build_emoji(emoji, cached_users=cached_users)
+ )
+
+ def clear_emojis(self) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ result = self._clear_emojis()
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if guild_record.emojis is not None: # TODO: add test coverage for this.
+ guild_record.emojis = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return result
+
+ def clear_emojis_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ return self._clear_emojis(guild_id)
+
+ def delete_emoji(self, emoji_id: snowflake.Snowflake, /) -> typing.Optional[emojis.KnownCustomEmoji]:
+ emoji_data = self._emoji_entries.pop(emoji_id, None)
+ if emoji_data is None:
+ return None
+
+ emoji_data.has_been_deleted = True
+ if not self._can_remove_emoji(emoji_data):
+ return None
+
+ emoji = self._build_emoji(emoji_data)
+
+ if emoji_data.user_id is not None:
+ self._garbage_collect_user(emoji_data.user_id, decrement=1)
+
+ guild_record = self._guild_entries.get(emoji_data.guild_id)
+ if guild_record and guild_record.emojis: # TODO: should this make assumptions and be flat?
+ guild_record.emojis.remove(emoji_id)
+
+ if not guild_record.emojis:
+ guild_record.emojis = None
+
+ return emoji
+
+ def get_emoji(self, emoji_id: snowflake.Snowflake, /) -> typing.Optional[emojis.KnownCustomEmoji]:
+ return self._build_emoji(self._emoji_entries[emoji_id]) if emoji_id in self._emoji_entries else None
+
+ def _get_emojis_view(
+ self, guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED
+ ) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ cached_emojis = {}
+ cached_users = {}
+ emoji_ids: typing.Iterable[snowflake.Snowflake]
+
+ if guild_id is undefined.UNDEFINED:
+ emoji_ids = self._emoji_entries.keys()
+ else:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or not guild_record.emojis:
+ return _EmptyCacheView()
+
+ emoji_ids = guild_record.emojis
+
+ for emoji_id in tuple(emoji_ids):
+ emoji_data = self._emoji_entries[emoji_id]
+ cached_emojis[emoji_id] = emoji_data
+
+ if emoji_data.user_id is not None:
+ cached_users[emoji_data.user_id] = self._user_entries[emoji_data.user_id]
+
+ return _StatefulCacheMappingView(
+ cached_emojis, builder=lambda emoji: self._build_emoji(emoji, cached_users=cached_users)
+ )
+
+ def get_emojis_view(self) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ return self._get_emojis_view()
+
+ def get_emojis_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ return self._get_emojis_view(guild_id=guild_id)
+
+ def set_emoji(self, emoji: emojis.KnownCustomEmoji, /) -> None:
+ if emoji.user is not None:
+ self.set_user(emoji.user)
+ if emoji.id not in self._emoji_entries:
+ self._increment_user_ref_count(emoji.user.id)
+
+ self._emoji_entries[emoji.id] = _KnownCustomEmojiData.build_from_entity(emoji)
+ guild_container = self._get_or_create_guild_record(emoji.guild_id)
+
+ if guild_container.emojis is None: # TODO: add test cases when it is not None?
+ guild_container.emojis = _IDTable()
+
+ guild_container.emojis.add(emoji.id)
+
+ def update_emoji(
+ self, emoji: emojis.KnownCustomEmoji, /
+ ) -> typing.Tuple[typing.Optional[emojis.KnownCustomEmoji], typing.Optional[emojis.KnownCustomEmoji]]:
+ cached_emoji = self.get_emoji(emoji.id)
+ self.set_emoji(emoji)
+ return cached_emoji, self.get_emoji(emoji.id)
+
+ def _remove_guild_record_if_empty(self, guild_id: snowflake.Snowflake) -> None:
+ if guild_id in self._guild_entries and not self._guild_entries[guild_id]:
+ del self._guild_entries[guild_id]
+
+ def _get_or_create_guild_record(self, guild_id: snowflake.Snowflake) -> _GuildRecord:
+ if guild_id not in self._guild_entries:
+ self._guild_entries[guild_id] = _GuildRecord()
+
+ return self._guild_entries[guild_id]
+
+ def clear_guilds(self) -> cache.CacheView[snowflake.Snowflake, guilds.GatewayGuild]:
+ cached_guilds = {}
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if guild_record.guild is None:
+ continue
+
+ cached_guilds[guild_id] = guild_record.guild
+ guild_record.guild = None
+ guild_record.is_available = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return _StatefulCacheMappingView(cached_guilds) if cached_guilds else _EmptyCacheView()
+
+ def delete_guild(self, guild_id: snowflake.Snowflake, /) -> typing.Optional[guilds.GatewayGuild]:
+ if guild_id not in self._guild_entries:
+ return None
+
+ guild_record = self._guild_entries[guild_id]
+ guild = guild_record.guild
+
+ if guild is not None:
+ guild_record.guild = None
+ guild_record.is_available = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return guild
+
+ def get_guild(self, guild_id: snowflake.Snowflake, /) -> typing.Optional[guilds.GatewayGuild]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is not None:
+ if guild_record.guild and not guild_record.is_available:
+ raise errors.UnavailableGuildError(guild_record.guild) from None
+
+ return copy.copy(guild_record.guild)
+
+ return None
+
+ def get_guilds_view(self) -> cache.CacheView[snowflake.Snowflake, guilds.GatewayGuild]:
+ results = {
+ sf: guild_record.guild for sf, guild_record in tuple(self._guild_entries.items()) if guild_record.guild
+ } # TODO: do we want to include unavailable guilds here or hide them?
+ return _StatefulCacheMappingView(results) if results else _EmptyCacheView()
+
+ def set_guild(self, guild: guilds.GatewayGuild, /) -> None:
+ guild_record = self._get_or_create_guild_record(guild.id)
+ guild_record.guild = copy.copy(guild)
+ guild_record.is_available = True
+
+ def set_guild_availability(self, guild_id: snowflake.Snowflake, is_available: bool, /) -> None:
+ guild_record = self._get_or_create_guild_record(guild_id=guild_id)
+ guild_record.is_available = is_available # TODO: only set this if guild object cached?
+
+ # TODO: is this the best way to handle this?
+ def set_initial_unavailable_guilds(self, guild_ids: typing.Collection[snowflake.Snowflake], /) -> None:
+ # Invoked when we receive ON_READY, assume all of these are unavailable on startup.
+ self._guild_entries = {guild_id: _GuildRecord(is_available=False) for guild_id in guild_ids}
+
+ def update_guild(
+ self, guild: guilds.GatewayGuild, /
+ ) -> typing.Tuple[typing.Optional[guilds.GatewayGuild], typing.Optional[guilds.GatewayGuild]]:
+ guild = copy.copy(guild)
+ guild_record = self._guild_entries.get(guild.id)
+ cached_guild = guild_record.guild if guild_record is not None else None
+
+ # We have to manually update these because inconsistency by Discord.
+ if cached_guild is not None:
+ guild.member_count = cached_guild.member_count
+ guild.joined_at = cached_guild.joined_at
+ guild.is_large = cached_guild.is_large
+
+ self.set_guild(guild)
+ guild_record = self._guild_entries.get(guild.id)
+ return cached_guild, guild_record.guild if guild_record is not None else None
+
+ def clear_guild_channels(self) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ cached_channels = self._guild_channel_entries
+ self._guild_channel_entries = {}
+
+ for guild_id, guild_record in self._guild_entries.items():
+ if guild_record.channels is not None:
+ guild_record.channels = None
+ self._garbage_collect_user(guild_id)
+
+ return _StatefulCacheMappingView(cached_channels)
+
+ def clear_guild_channels_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.channels is None:
+ return _EmptyCacheView()
+
+ cached_channels = {sf: self._guild_channel_entries.pop(sf) for sf in guild_record.channels}
+ guild_record.channels = None
+ self._remove_guild_record_if_empty(guild_id)
+ return _StatefulCacheMappingView(cached_channels)
+
+ def delete_guild_channel(self, channel_id: snowflake.Snowflake, /) -> typing.Optional[channels.GuildChannel]:
+ channel = self._guild_channel_entries.pop(channel_id, None)
+
+ if channel is not None: # TODO: flat and make assumptions?
+ guild_record = self._guild_entries.get(channel.guild_id)
+
+ if guild_record and guild_record.channels is not None:
+ guild_record.channels.remove(channel_id)
+
+ return channel
+
+ def get_guild_channel(self, channel_id: snowflake.Snowflake, /) -> typing.Optional[channels.GuildChannel]:
+ channel = self._guild_channel_entries.get(channel_id)
+ return _copy_guild_channel(channel) if channel is not None else None
+
+ def get_guild_channels_view(self) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ return _GuildChannelCacheMappingView(dict(self._guild_channel_entries))
+
+ def get_guild_channels_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or not guild_record.channels:
+ return _EmptyCacheView()
+
+ cached_channels = {sf: self._guild_channel_entries[sf] for sf in tuple(guild_record.channels)}
+
+ def sorter(args: typing.Tuple[snowflake.Snowflake, channels.GuildChannel]) -> typing.Tuple[int, int, int]:
+ channel = args[1]
+ if isinstance(channel, channels.GuildCategory):
+ return channel.position, -1, 0
+
+ parent_position = -1 if channel.parent_id is None else cached_channels[channel.parent_id].position
+
+ if not isinstance(channel, channels.GuildVoiceChannel):
+ return parent_position, 0, channel.position
+
+ return parent_position, 1, channel.position
+
+ cached_channels = dict(sorted(cached_channels.items(), key=sorter))
+ return _GuildChannelCacheMappingView(cached_channels)
+
+ def set_guild_channel(self, channel: channels.GuildChannel, /) -> None:
+ self._guild_channel_entries[channel.id] = _copy_guild_channel(channel)
+ guild_record = self._get_or_create_guild_record(channel.guild_id)
+
+ if guild_record.channels is None:
+ guild_record.channels = _IDTable()
+
+ guild_record.channels.add(channel.id)
+
+ def update_guild_channel(
+ self, channel: channels.GuildChannel, /
+ ) -> typing.Tuple[typing.Optional[channels.GuildChannel], typing.Optional[channels.GuildChannel]]:
+ cached_channel = self.get_guild_channel(channel.id)
+ self.set_guild_channel(channel)
+ return cached_channel, self.get_guild_channel(channel.id)
+
+ def _build_invite(
+ self,
+ invite_data: _InviteData,
+ cached_users: undefined.UndefinedOr[
+ typing.Mapping[snowflake.Snowflake, _GenericRefWrapper[users.User]]
+ ] = undefined.UNDEFINED,
+ ) -> invites.InviteWithMetadata:
+ inviter: typing.Optional[users.User]
+ if cached_users is not undefined.UNDEFINED and invite_data.inviter_id is not None:
+ inviter = copy.copy(cached_users[invite_data.inviter_id].object)
+ elif invite_data.inviter_id is not None:
+ inviter = copy.copy(self._user_entries[invite_data.inviter_id].object)
+ else:
+ inviter = None
+
+ target_user: typing.Optional[users.User]
+ if cached_users is not undefined.UNDEFINED and invite_data.target_user_id is not None:
+ target_user = copy.copy(cached_users[invite_data.target_user_id].object)
+ elif invite_data.target_user_id is not None:
+ target_user = copy.copy(self._user_entries[invite_data.target_user_id].object)
+ else:
+ target_user = None
+
+ return invite_data.build_entity(
+ invites.InviteWithMetadata, app=self._app, inviter=inviter, target_user=target_user
+ )
+
+ def _clear_invites(
+ self, guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED,
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ invite_codes: typing.Iterable[str]
+ if guild_id is not undefined.UNDEFINED:
+ guild_record = self._guild_entries.get(guild_id)
+
+ if guild_record is None or guild_record.invites is None:
+ return _EmptyCacheView()
+
+ invite_codes = guild_record.invites
+ guild_record.invites = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ else:
+ invite_codes = tuple(self._invite_entries.keys())
+
+ cached_invites = {}
+ cached_users = {}
+
+ for code in invite_codes:
+ invite_data = self._invite_entries.pop(code)
+ cached_invites[code] = invite_data
+
+ if invite_data.inviter_id is not None:
+ cached_users[invite_data.inviter_id] = self._user_entries[invite_data.inviter_id]
+ self._garbage_collect_user(invite_data.inviter_id, decrement=1)
+
+ if invite_data.target_user_id is not None:
+ cached_users[invite_data.target_user_id] = self._user_entries[invite_data.target_user_id]
+ self._garbage_collect_user(invite_data.target_user_id, decrement=1)
+
+ return _StatefulCacheMappingView(
+ cached_invites, builder=lambda invite_data: self._build_invite(invite_data, cached_users=cached_users)
+ )
+
+ def clear_invites(self) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ return self._clear_invites()
+
+ def clear_invites_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ return self._clear_invites(guild_id=guild_id)
+
+ def clear_invites_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.invites is None:
+ return _EmptyCacheView()
+
+ cached_invites = {}
+ cached_users = {}
+
+ for code in tuple(guild_record.invites):
+ invite_data = self._invite_entries[code]
+ if invite_data.channel_id != channel_id:
+ continue
+
+ cached_invites[code] = invite_data
+ del self._invite_entries[code]
+ guild_record.invites.remove(code)
+
+ if invite_data.inviter_id is not None:
+ cached_users[invite_data.inviter_id] = self._user_entries[invite_data.inviter_id]
+ self._garbage_collect_user(invite_data.inviter_id, decrement=1)
+
+ if invite_data.target_user_id is not None:
+ cached_users[invite_data.target_user_id] = self._user_entries[invite_data.target_user_id]
+ self._garbage_collect_user(invite_data.target_user_id, decrement=1)
+
+ if not guild_record.invites:
+ guild_record.invites = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return _StatefulCacheMappingView(
+ cached_invites, builder=lambda invite_data: self._build_invite(invite_data, cached_users=cached_users)
+ )
+
+ def delete_invite(self, code: str, /) -> typing.Optional[invites.InviteWithMetadata]:
+ if code not in self._invite_entries:
+ return None
+
+ invite = self._build_invite(self._invite_entries.pop(code))
+
+ if invite.inviter is not None:
+ self._garbage_collect_user(invite.inviter.id, decrement=1)
+
+ if invite.target_user is not None:
+ self._garbage_collect_user(invite.target_user.id, decrement=1)
+
+ if invite.guild_id is not None: # TODO: test case when this is None?
+ guild_record = self._guild_entries.get(invite.guild_id)
+ if guild_record and guild_record.invites is not None: # TODO: should this make assumptions and be flat?
+ guild_record.invites.remove(code)
+
+ if not guild_record.invites:
+ guild_record.invites = None # TODO: test when this is set to None
+ self._remove_guild_record_if_empty(invite.guild_id)
+
+ return invite
+
+ def get_invite(self, code: str, /) -> typing.Optional[invites.InviteWithMetadata]:
+ return self._build_invite(self._invite_entries[code]) if code in self._invite_entries else None
+
+ def _get_invites_view(
+ self, guild_id: undefined.UndefinedOr[snowflake.Snowflake] = undefined.UNDEFINED
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ invite_ids: typing.Iterable[str]
+ if guild_id is undefined.UNDEFINED:
+ invite_ids = self._invite_entries.keys()
+
+ else:
+ guild_entry = self._guild_entries.get(guild_id)
+ if guild_entry is None or guild_entry.invites is None:
+ return _EmptyCacheView()
+
+ invite_ids = guild_entry.invites
+
+ cached_invites = {}
+ cached_users = {}
+
+ for code in tuple(invite_ids):
+ invite_data = self._invite_entries[code]
+ cached_invites[code] = invite_data
+
+ if invite_data.inviter_id is not None:
+ cached_users[invite_data.inviter_id] = self._user_entries[invite_data.inviter_id]
+
+ if invite_data.target_user_id is not None:
+ cached_users[invite_data.target_user_id] = self._user_entries[invite_data.target_user_id]
+
+ return _StatefulCacheMappingView(
+ cached_invites, builder=lambda invite_data: self._build_invite(invite_data, cached_users=cached_users)
+ )
+
+ def get_invites_view(self) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ return self._get_invites_view()
+
+ def get_invites_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ return self._get_invites_view(guild_id=guild_id)
+
+ def get_invites_view_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /,
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ guild_entry = self._guild_entries.get(guild_id)
+ if guild_entry is None or guild_entry.invites is None:
+ return _EmptyCacheView()
+
+ cached_invites = {}
+ cached_users = {}
+ invite_ids: typing.Iterable[str]
+
+ for code in tuple(guild_entry.invites):
+ invite_data = self._invite_entries[code]
+ if invite_data.channel_id != channel_id:
+ continue
+
+ cached_invites[code] = invite_data
+ guild_entry.invites.remove(code)
+ del self._invite_entries[code]
+
+ if invite_data.inviter_id is not None:
+ cached_users[invite_data.inviter_id] = self._user_entries[invite_data.inviter_id]
+
+ if invite_data.target_user_id is not None:
+ cached_users[invite_data.target_user_id] = self._user_entries[invite_data.target_user_id]
+
+ if not guild_entry.channels: # TODO: test coverage
+ guild_entry.channels = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return _StatefulCacheMappingView(
+ cached_invites, builder=lambda invite_data: self._build_invite(invite_data, cached_users=cached_users)
+ )
+
+ def set_invite(self, invite: invites.InviteWithMetadata, /) -> None:
+ if invite.inviter is not None:
+ self.set_user(invite.inviter)
+ if invite.code not in self._invite_entries:
+ self._increment_user_ref_count(invite.inviter.id)
+
+ if invite.target_user is not None:
+ self.set_user(invite.target_user)
+ if invite.code not in self._invite_entries:
+ self._increment_user_ref_count(invite.target_user.id)
+
+ self._invite_entries[invite.code] = _InviteData.build_from_entity(invite)
+ if invite.guild_id:
+ guild_entry = self._get_or_create_guild_record(invite.guild_id)
+
+ if guild_entry.invites is None:
+ guild_entry.invites = []
+
+ guild_entry.invites.append(invite.code)
+
+ def update_invite(
+ self, invite: invites.InviteWithMetadata, /
+ ) -> typing.Tuple[typing.Optional[invites.InviteWithMetadata], typing.Optional[invites.InviteWithMetadata]]:
+ cached_invite = self.get_invite(invite.code)
+ self.set_invite(invite)
+ return cached_invite, self.get_invite(invite.code)
+
+ def delete_me(self) -> typing.Optional[users.OwnUser]:
+ cached_user = self._me
+ self._me = None
+ return cached_user
+
+ def get_me(self) -> typing.Optional[users.OwnUser]:
+ return copy.copy(self._me)
+
+ def set_me(self, user: users.OwnUser, /) -> None:
+ self._me = copy.copy(user)
+
+ def update_me(
+ self, user: users.OwnUser, /
+ ) -> typing.Tuple[typing.Optional[users.OwnUser], typing.Optional[users.OwnUser]]:
+ _LOGGER.debug("setting my user to %s", user)
+ cached_user = self.get_me()
+ self.set_me(user)
+ return cached_user, self._me
+
+ def _build_member(
+ self,
+ member_data: _MemberData,
+ cached_users: typing.Optional[typing.Mapping[snowflake.Snowflake, _GenericRefWrapper[users.User]]] = None,
+ ) -> guilds.Member:
+ if cached_users is None:
+ user = copy.copy(self._user_entries[member_data.id].object)
+ else:
+ user = copy.copy(cached_users[member_data.id].object)
+
+ return member_data.build_entity(guilds.Member, user=user)
+
+ @staticmethod
+ def _can_remove_member(member: _MemberData, guild_record: _GuildRecord) -> bool:
+ if member.has_been_deleted is False:
+ return False
+
+ return bool(not guild_record.voice_states or member.id not in guild_record.voice_states)
+
+ def _garbage_collect_member(self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake) -> None:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.members is None or user_id not in guild_record.members:
+ return
+
+ member_data = guild_record.members[user_id]
+ if not self._can_remove_member(member_data, guild_record):
+ return
+
+ del guild_record.members[user_id]
+ if not guild_record.members:
+ guild_record.members = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ def _chainable_remove_member(self, member: _MemberData, guild_record: _GuildRecord) -> typing.Optional[_MemberData]:
+ assert guild_record.members
+ member.has_been_deleted = True
+ if not self._can_remove_member(member, guild_record):
+ return None
+
+ self._garbage_collect_user(member.id, decrement=1)
+ del guild_record.members[member.id]
+ return member
+
+ def clear_members(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, guilds.Member]]:
+ views = {}
+ cached_users = dict(self._user_entries)
+
+ def build_member(member: _MemberData) -> guilds.Member:
+ return self._build_member(member, cached_users=cached_users)
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if not guild_record.members:
+ continue
+
+ cached_members = {
+ member.id: member
+ for member in itertools.starmap(
+ self._chainable_remove_member, ((m, guild_record) for m in tuple(guild_record.members.values())),
+ )
+ if member is not None
+ }
+
+ if not guild_record.members:
+ guild_record.members = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ views[guild_id] = _StatefulCacheMappingView(cached_members, builder=build_member)
+
+ return _StatefulCacheMappingView(views)
+
+ def clear_members_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Member]:
+ guild_record = self._guild_entries.get(guild_id) # TODO: optional return on clear?
+ if guild_record is None or guild_record.members is None:
+ return _EmptyCacheView()
+
+ cached_users = {user_id: self._user_entries[user_id] for user_id in guild_record.members}
+ cached_members = {
+ member.id: member
+ for member in itertools.starmap(
+ self._chainable_remove_member, ((m, guild_record) for m in tuple(guild_record.members.values())),
+ )
+ if member is not None
+ }
+
+ if not guild_record.members:
+ guild_record.members = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return _StatefulCacheMappingView(
+ cached_members, builder=lambda member: self._build_member(member, cached_users=cached_users)
+ )
+
+ def delete_member(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[guilds.Member]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.members is None:
+ return None
+
+ member_data = guild_record.members.get(user_id)
+ if member_data is None or not self._can_remove_member(member_data, guild_record):
+ return None
+
+ member = self._build_member(member_data)
+ del guild_record.members[user_id]
+ if not guild_record.members:
+ guild_record.members = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ self._garbage_collect_user(user_id, decrement=1)
+ return member
+
+ def get_member(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[guilds.Member]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.members is None:
+ return None
+
+ member = guild_record.members.get(user_id)
+ return self._build_member(member) if member is not None else None
+
+ def get_members_view(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, guilds.Member]]:
+ cached_users = dict(self._user_entries)
+
+ def member_builder(member: _MemberData) -> guilds.Member:
+ return self._build_member(member, cached_users=cached_users)
+
+ return _3DCacheMappingView(
+ {
+ guild_id: _StatefulCacheMappingView(view.members, builder=member_builder)
+ for guild_id, view in self._guild_entries.items()
+ if view.members
+ }
+ )
+
+ def get_members_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Member]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.members is None:
+ return _EmptyCacheView()
+
+ cached_members = {
+ user_id: member for user_id, member in tuple(guild_record.members.items()) if not member.has_been_deleted
+ }
+ cached_users = {user_id: self._user_entries[user_id] for user_id in cached_members}
+
+ return _StatefulCacheMappingView(
+ cached_members, builder=lambda member: self._build_member(member, cached_users=cached_users)
+ )
+
+ def set_member(self, member: guilds.Member, /) -> None:
+ guild_record = self._get_or_create_guild_record(member.guild_id)
+ self.set_user(member.user)
+ member_data = _MemberData.build_from_entity(member)
+
+ if guild_record.members is None: # TODO: test when this is not None
+ guild_record.members = {}
+
+ if member.user.id not in guild_record.members:
+ self._increment_user_ref_count(member.user.id)
+
+ guild_record.members[member_data.id] = member_data
+
+ def update_member(
+ self, member: guilds.Member, /
+ ) -> typing.Tuple[typing.Optional[guilds.Member], typing.Optional[guilds.Member]]:
+ cached_member = self.get_member(member.guild_id, member.user.id)
+ self.set_member(member)
+ return cached_member, self.get_member(member.guild_id, member.user.id)
+
+ def _build_presence(
+ self,
+ presence_data: _MemberPresenceData,
+ cached_emojis: typing.Optional[
+ typing.Mapping[typing.Union[str, snowflake.Snowflake], typing.Union[emojis.Emoji, _KnownCustomEmojiData]]
+ ] = None,
+ cached_users: typing.Optional[typing.Mapping[snowflake.Snowflake, _GenericRefWrapper[users.User]]] = None,
+ ) -> presences.MemberPresence:
+ presence_kwargs: typing.MutableSequence[typing.Mapping[str, typing.Optional[emojis.Emoji]]] = []
+ for activity_data in presence_data.activities:
+ identifier = activity_data.emoji_id_or_name
+ if identifier is None:
+ presence_kwargs.append({"emoji": None})
+
+ elif cached_emojis:
+ emoji = cached_emojis[identifier]
+ if isinstance(emoji, _KnownCustomEmojiData):
+ presence_kwargs.append({"emoji": self._build_emoji(emoji, cached_users=cached_users)})
+ else:
+ presence_kwargs.append({"emoji": copy.copy(emoji)})
+
+ elif isinstance(identifier, snowflake.Snowflake) and identifier in self._emoji_entries:
+ presence_kwargs.append(
+ {"emoji": self._build_emoji(self._emoji_entries[identifier], cached_users=cached_users)}
+ )
+
+ else:
+ presence_kwargs.append({"emoji": copy.copy(self._unknown_emoji_entries[identifier].object)})
+
+ return presence_data.build_entity(presences.MemberPresence, app=self._app, presence_kwargs=presence_kwargs)
+
+ def _garbage_collect_unknown_emoji(
+ self, emoji_id_or_name: typing.Union[snowflake.Snowflake, str], decrement: int = 0
+ ) -> None:
+ emoji = self._unknown_emoji_entries.get(emoji_id_or_name) # TODO: use this style for all gc methods
+ if emoji is None:
+ return None
+
+ emoji.ref_count -= decrement
+ if emoji.ref_count == 0:
+ del self._unknown_emoji_entries[emoji_id_or_name]
+
+ def clear_presences(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, presences.MemberPresence]]:
+ views = {}
+
+ for guild_id, guild_record in self._guild_entries.items():
+ if not guild_record.presences:
+ continue
+
+ views[guild_id] = self.clear_presences_for_guild(guild_id)
+
+ return _StatefulCacheMappingView(views)
+
+ def clear_presences_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, presences.MemberPresence]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.presences is None:
+ return _EmptyCacheView()
+
+ cached_emojis: typing.MutableMapping[
+ typing.Union[str, snowflake.Snowflake], typing.Union[emojis.Emoji, _KnownCustomEmojiData]
+ ] = {}
+ cached_users = {}
+ cached_presences = {}
+
+ for user_id, presence_data in guild_record.presences.items():
+ cached_presences[user_id] = presence_data
+
+ for activity_data in presence_data.activities:
+ emoji_identifier = activity_data.emoji_id_or_name
+ if emoji_identifier is None:
+ continue
+
+ if isinstance(emoji_identifier, snowflake.Snowflake) and emoji_identifier in self._emoji_entries:
+ known_emoji_data = self._emoji_entries[emoji_identifier]
+
+ if known_emoji_data.user_id is not None:
+ cached_users[known_emoji_data.user_id] = self._user_entries[known_emoji_data.user_id]
+
+ cached_emojis[emoji_identifier] = known_emoji_data
+ self._garbage_collect_emoji(emoji_identifier, decrement=-1)
+
+ else:
+ cached_emojis[emoji_identifier] = self._unknown_emoji_entries[emoji_identifier].object
+ self._garbage_collect_unknown_emoji(emoji_identifier, decrement=1)
+
+ return _StatefulCacheMappingView(
+ cached_presences,
+ builder=lambda presence_data_: self._build_presence(
+ presence_data_, cached_users=cached_users, cached_emojis=cached_emojis
+ ),
+ )
+
+ def delete_presence(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[presences.MemberPresence]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.presences is None:
+ return None
+
+ presence_data = guild_record.presences.pop(user_id, None)
+
+ if presence_data is None:
+ return None
+
+ presence = self._build_presence(presence_data)
+
+ for activity in presence.activities:
+ if activity.emoji is None:
+ continue
+
+ if isinstance(activity.emoji, emojis.KnownCustomEmoji):
+ self._garbage_collect_emoji(activity.emoji.id, decrement=-1)
+
+ else:
+ emoji_identifier: typing.Union[snowflake.Snowflake, str]
+ if isinstance(activity.emoji, emojis.CustomEmoji):
+ emoji_identifier = activity.emoji.id
+ else:
+ assert activity.emoji.name is not None
+ emoji_identifier = activity.emoji.name
+
+ self._garbage_collect_unknown_emoji(
+ emoji_identifier, decrement=1,
+ )
+
+ return presence
+
+ def get_presence(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[presences.MemberPresence]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.presences is None:
+ return None
+
+ return self._build_presence(guild_record.presences[user_id]) if user_id in guild_record.presences else None
+
+ def get_presences_view(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, presences.MemberPresence]]:
+ views = {}
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if not guild_record.presences:
+ continue
+
+ views[guild_id] = self.get_presences_view_for_guild(guild_id)
+
+ return _3DCacheMappingView(views)
+
+ def get_presences_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, presences.MemberPresence]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.presences is None:
+ return _EmptyCacheView()
+
+ cached_emojis: typing.MutableMapping[
+ typing.Union[str, snowflake.Snowflake], typing.Union[emojis.Emoji, _KnownCustomEmojiData]
+ ] = {}
+ cached_users = {}
+ cached_presences = {}
+
+ for user_id, presence_data in tuple(guild_record.presences.items()):
+ cached_presences[user_id] = presence_data
+
+ for activity_data in presence_data.activities:
+ emoji_identifier = activity_data.emoji_id_or_name
+
+ if emoji_identifier is None or emoji_identifier in cached_emojis:
+ continue
+
+ if isinstance(emoji_identifier, snowflake.Snowflake) and emoji_identifier in self._emoji_entries:
+ emoji_data = self._emoji_entries[emoji_identifier]
+
+ if emoji_data.user_id is not None:
+ cached_users[emoji_data.user_id] = self._user_entries[emoji_data.user_id]
+
+ cached_emojis[emoji_identifier] = emoji_data
+
+ else:
+ cached_emojis[emoji_identifier] = self._unknown_emoji_entries[emoji_identifier].object
+
+ return _StatefulCacheMappingView(
+ cached_presences,
+ builder=lambda presence_data_: self._build_presence(
+ presence_data_, cached_users=cached_users, cached_emojis=cached_emojis
+ ),
+ )
+
+ def set_presence(self, presence: presences.MemberPresence, /) -> None:
+ presence_data = _MemberPresenceData.build_from_entity(presence)
+
+ for activity in presence.activities:
+ emoji = activity.emoji
+ if not emoji:
+ continue
+
+ if isinstance(emoji, emojis.CustomEmoji) and emoji.id in self._emoji_entries:
+ self._increment_emoji_ref_count(emoji.id)
+ else:
+ emoji_identifier: typing.Union[snowflake.Snowflake, str]
+ if isinstance(emoji, emojis.CustomEmoji):
+ emoji_identifier = emoji.id
+ else:
+ # should always be Unicode otherwise
+ emoji = typing.cast(emojis.UnicodeEmoji, emoji)
+ emoji_identifier = emoji.name
+
+ wrapped_emoji = _GenericRefWrapper(object=copy.copy(emoji), ref_count=1)
+
+ if emoji_identifier in self._unknown_emoji_entries:
+ wrapped_emoji.ref_count += self._unknown_emoji_entries[emoji_identifier].ref_count
+
+ self._unknown_emoji_entries[emoji_identifier] = wrapped_emoji
+
+ guild_record = self._get_or_create_guild_record(presence.guild_id)
+ if guild_record.presences is None:
+ guild_record.presences = {}
+
+ guild_record.presences[presence.user_id] = presence_data
+
+ def update_presence(
+ self, presence: presences.MemberPresence, /
+ ) -> typing.Tuple[typing.Optional[presences.MemberPresence], typing.Optional[presences.MemberPresence]]:
+ cached_presence = self.get_presence(presence.guild_id, presence.user_id)
+ self.set_presence(presence)
+ return cached_presence, self.get_presence(presence.guild_id, presence.user_id)
+
+ def clear_roles(self) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ if not self._role_entries:
+ return _EmptyCacheView()
+
+ roles = self._role_entries
+ self._role_entries = {}
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if guild_record.roles is not None: # TODO: test coverage for this
+ guild_record.roles = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return _StatefulCacheMappingView(roles)
+
+ def clear_roles_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or not guild_record.roles:
+ return _EmptyCacheView()
+
+ view = _StatefulCacheMappingView({role_id: self._role_entries[role_id] for role_id in guild_record.roles})
+ guild_record.roles = None
+ self._remove_guild_record_if_empty(guild_id)
+ return view
+
+ def delete_role(self, role_id: snowflake.Snowflake, /) -> typing.Optional[guilds.Role]:
+ role = self._role_entries.pop(role_id, None) # TODO: this honestly feels jank, should we redo this?
+ if role is None:
+ return None
+
+ guild_record = self._guild_entries.get(role.guild_id)
+ if guild_record and guild_record.roles is not None:
+ guild_record.roles.remove(role_id)
+
+ if not guild_record.roles: # TODO: should this make assumptions and be flat?
+ guild_record.roles = None
+ self._remove_guild_record_if_empty(role.guild_id)
+
+ return role
+
+ def get_role(self, role_id: snowflake.Snowflake, /) -> typing.Optional[guilds.Role]:
+ return self._role_entries.get(role_id)
+
+ def get_roles_view(self) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ return _StatefulCacheMappingView(dict(self._role_entries))
+
+ def get_roles_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.roles is None:
+ return _EmptyCacheView()
+
+ return _StatefulCacheMappingView(
+ {role_id: self._role_entries[role_id] for role_id in tuple(guild_record.roles)}
+ )
+
+ def set_role(self, role: guilds.Role, /) -> None:
+ self._role_entries[role.id] = role
+ guild_record = self._get_or_create_guild_record(role.guild_id)
+
+ if guild_record.roles is None: # TODO: test when this is not None
+ guild_record.roles = _IDTable()
+
+ guild_record.roles.add(role.id)
+
+ def update_role(
+ self, role: guilds.Role, /
+ ) -> typing.Tuple[typing.Optional[guilds.Role], typing.Optional[guilds.Role]]:
+ cached_role = self.get_role(role.id)
+ self.set_role(role)
+ return cached_role, self.get_role(role.id)
+
+ @staticmethod
+ def _can_remove_user(user_data: typing.Optional[_GenericRefWrapper[users.User]]) -> bool:
+ return bool(user_data and user_data.ref_count == 0)
+
+ def _increment_user_ref_count(self, user_id: snowflake.Snowflake, increment: int = 1) -> None:
+ self._user_entries[user_id].ref_count += increment
+
+ def _garbage_collect_user(self, user_id: snowflake.Snowflake, *, decrement: typing.Optional[int] = None) -> None:
+ if decrement is not None and user_id in self._user_entries:
+ self._increment_user_ref_count(user_id, -decrement)
+
+ if self._can_remove_user(self._user_entries.get(user_id)):
+ del self._user_entries[user_id]
+
+ def clear_users(self) -> cache.CacheView[snowflake.Snowflake, users.User]:
+ if not self._user_entries:
+ return _EmptyCacheView()
+
+ cached_users = {}
+
+ for user_id, user in tuple(self._user_entries.items()):
+ if user.ref_count > 0:
+ continue
+
+ cached_users[user_id] = user.object
+ del self._user_entries[user_id]
+
+ return _StatefulCacheMappingView(cached_users) if cached_users else _EmptyCacheView()
+
+ def delete_user(self, user_id: snowflake.Snowflake, /) -> typing.Optional[users.User]:
+ if self._can_remove_user(self._user_entries.get(user_id)):
+ return self._user_entries.pop(user_id).object
+
+ return None
+
+ def get_user(self, user_id: snowflake.Snowflake, /) -> typing.Optional[users.User]:
+ return copy.copy(self._user_entries[user_id].object) if user_id in self._user_entries else None
+
+ def get_users_view(self) -> cache.CacheView[snowflake.Snowflake, users.User]:
+ if not self._user_entries:
+ return _EmptyCacheView()
+
+ return _StatefulCacheMappingView(dict(self._user_entries.items()), unpack=True)
+
+ def set_user(self, user: users.User, /) -> None:
+ wrapper_user = _GenericRefWrapper(object=copy.copy(user))
+
+ if user.id in self._user_entries: # TODO: test this behaviour
+ wrapper_user.ref_count = self._user_entries[user.id].ref_count
+
+ self._user_entries[user.id] = wrapper_user
+
+ def update_user(
+ self, user: users.User, /
+ ) -> typing.Tuple[typing.Optional[users.User], typing.Optional[users.User]]:
+ cached_user = self.get_user(user.id)
+ self.set_user(user)
+ return cached_user, self.get_user(user.id)
+
+ def _build_voice_state(
+ self,
+ voice_data: _VoiceStateData,
+ cached_members: typing.Optional[typing.Mapping[snowflake.Snowflake, _MemberData]] = None,
+ cached_users: typing.Optional[typing.Mapping[snowflake.Snowflake, _GenericRefWrapper[users.User]]] = None,
+ ) -> voices.VoiceState:
+ if cached_members:
+ member = self._build_member(cached_members[voice_data.user_id], cached_users=cached_users)
+ else:
+ guild_record = self._guild_entries[voice_data.guild_id]
+ assert guild_record.members is not None
+ member_data = guild_record.members[voice_data.user_id]
+ member = self._build_member(member_data, cached_users=cached_users)
+
+ return voice_data.build_entity(voices.VoiceState, app=self._app, member=member)
+
+ def clear_voice_states(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, voices.VoiceState]]:
+ views = {}
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if not guild_record.voice_states:
+ continue
+
+ views[guild_id] = self.clear_voice_states_for_guild(guild_id)
+
+ return _StatefulCacheMappingView(views)
+
+ def clear_voice_states_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.voice_states is None:
+ return _EmptyCacheView()
+
+ assert guild_record.members is not None
+ cached_members = {}
+ cached_users = {}
+ cached_voice_states = {}
+
+ for user_id, voice_state in guild_record.voice_states.items():
+ if voice_state.channel_id != channel_id:
+ continue
+
+ cached_members[user_id] = guild_record.members[user_id]
+ cached_users[user_id] = self._user_entries[user_id]
+ cached_voice_states[user_id] = voice_state
+
+ if not guild_record.voice_states:
+ guild_record.voice_states = None
+ self._remove_guild_record_if_empty(guild_id)
+
+ return _StatefulCacheMappingView(
+ cached_voice_states,
+ builder=lambda voice_state: self._build_voice_state(
+ voice_state, cached_members=cached_members, cached_users=cached_users
+ ),
+ )
+
+ def clear_voice_states_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ guild_record = self._guild_entries.get(guild_id)
+
+ if guild_record is None or guild_record.voice_states is None:
+ return _EmptyCacheView()
+
+ assert guild_record.members is not None
+ cached_voice_states = guild_record.voice_states
+ guild_record.voice_states = None
+ cached_members = {}
+ cached_users = {}
+
+ for user_id in cached_voice_states:
+ cached_members[user_id] = guild_record.members[user_id]
+ cached_users[user_id] = self._user_entries[user_id]
+ self._garbage_collect_member(guild_id, user_id)
+
+ self._remove_guild_record_if_empty(guild_id)
+ return _StatefulCacheMappingView(
+ cached_voice_states,
+ builder=lambda voice_data: self._build_voice_state(
+ voice_data, cached_members=cached_members, cached_users=cached_users
+ ),
+ )
+
+ def delete_voice_state(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[voices.VoiceState]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None:
+ return None
+
+ voice_state_data = guild_record.voice_states.pop(user_id, None) if guild_record.voice_states else None
+ if voice_state_data is None:
+ return None
+
+ if not guild_record.voice_states:
+ guild_record.voice_states = None
+
+ voice_state = self._build_voice_state(voice_state_data)
+ self._garbage_collect_member(voice_state.guild_id, voice_state.user_id)
+ self._remove_guild_record_if_empty(guild_id)
+ return voice_state
+
+ def get_voice_state(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[voices.VoiceState]:
+ guild_record = self._guild_entries.get(guild_id)
+ voice_data = guild_record.voice_states.get(user_id) if guild_record and guild_record.voice_states else None
+ return self._build_voice_state(voice_data) if voice_data else None
+
+ def get_voice_states_view(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, voices.VoiceState]]:
+ views = {}
+
+ for guild_id, guild_record in tuple(self._guild_entries.items()):
+ if not guild_record.voice_states:
+ continue
+
+ views[guild_id] = self.get_voice_states_view_for_guild(guild_id)
+
+ return _3DCacheMappingView(views)
+
+ def get_voice_states_view_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.voice_states is None:
+ return _EmptyCacheView()
+
+ assert guild_record.members is not None # noqa S10
+ cached_members = {}
+ cached_users = {}
+ cached_voice_states = {}
+
+ for user_id, voice_state in tuple(guild_record.voice_states.items()):
+ if voice_state.channel_id != channel_id:
+ continue
+
+ cached_members[user_id] = guild_record.members[user_id]
+ cached_users[user_id] = self._user_entries[user_id]
+ cached_voice_states[user_id] = voice_state
+
+ return _StatefulCacheMappingView(
+ cached_voice_states,
+ builder=lambda voice_data: self._build_voice_state(
+ voice_data, cached_members=cached_members, cached_users=cached_users
+ ),
+ )
+
+ def get_voice_states_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ guild_record = self._guild_entries.get(guild_id)
+ if guild_record is None or guild_record.voice_states is None:
+ return _EmptyCacheView()
+
+ assert guild_record.members is not None # noqa S10
+ voice_states = dict(guild_record.voice_states)
+ cached_members = {}
+ cached_users = {}
+
+ for user_id in voice_states:
+ cached_members[user_id] = guild_record.members[user_id]
+ cached_users[user_id] = self._user_entries[user_id]
+
+ return _StatefulCacheMappingView(
+ voice_states,
+ builder=lambda voice_data: self._build_voice_state(
+ voice_data, cached_members=cached_members, cached_users=cached_users
+ ),
+ )
+
+ def set_voice_state(self, voice_state: voices.VoiceState, /) -> None:
+ guild_record = self._get_or_create_guild_record(voice_state.guild_id)
+
+ if guild_record.voice_states is None: # TODO: test when this is not None
+ guild_record.voice_states = {}
+
+ self.set_member(voice_state.member)
+ assert guild_record.members # TOOD: account for this method not setting the member in some cases later on
+ guild_record.members[voice_state.member.id].has_been_deleted = True
+ guild_record.voice_states[voice_state.user_id] = _VoiceStateData.build_from_entity(voice_state)
+
+ def update_voice_state(
+ self, voice_state: voices.VoiceState, /
+ ) -> typing.Tuple[typing.Optional[voices.VoiceState], typing.Optional[voices.VoiceState]]:
+ cached_voice_state = self.get_voice_state(voice_state.guild_id, voice_state.user_id)
+ self.set_voice_state(voice_state)
+ return cached_voice_state, self.get_voice_state(voice_state.guild_id, voice_state.user_id)
diff --git a/hikari/impl/stateful_event_manager.py b/hikari/impl/stateful_event_manager.py
new file mode 100644
index 0000000000..3925b4ef1e
--- /dev/null
+++ b/hikari/impl/stateful_event_manager.py
@@ -0,0 +1,366 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Event handling logic for more info."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StatefulEventManagerImpl"]
+
+import typing
+
+from hikari import traits
+from hikari.events import shard_events
+from hikari.impl import event_manager_base
+from hikari.models import channels
+from hikari.models import intents as intents_
+from hikari.models import presences
+
+if typing.TYPE_CHECKING:
+ from hikari.api import cache as cache_
+ from hikari.api import shard as gateway_shard
+ from hikari.events import guild_events as guild_events
+ from hikari.utilities import data_binding
+
+
+class StatefulEventManagerImpl(event_manager_base.EventManagerBase):
+ """Provides event handling logic for Discord events."""
+
+ __slots__: typing.Sequence[str] = ("_cache",)
+
+ def __init__(
+ self, app: traits.BotAware, cache: cache_.MutableCache, intents: typing.Optional[intents_.Intents],
+ ) -> None:
+ self._cache = cache
+ super().__init__(app=app, intents=intents)
+
+ async def on_connected(self, shard: gateway_shard.GatewayShard, _: data_binding.JSONObject) -> None:
+ """Handle connection events.
+
+ This is a synthetic event produced by the gateway implementation in
+ Hikari.
+ """
+ # TODO: this should be in entity factory
+ await self.dispatch(shard_events.ShardConnectedEvent(app=self._app, shard=shard))
+
+ async def on_disconnected(self, shard: gateway_shard.GatewayShard, _: data_binding.JSONObject) -> None:
+ """Handle disconnection events.
+
+ This is a synthetic event produced by the gateway implementation in
+ Hikari.
+ """
+ # TODO: this should be in entity factory
+ await self.dispatch(shard_events.ShardDisconnectedEvent(app=self._app, shard=shard))
+
+ async def on_ready(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#ready for more info."""
+ # TODO: cache unavailable guilds on startup, I didn't bother for the time being.
+ event = self._app.event_factory.deserialize_ready_event(shard, payload)
+ self._cache.update_me(event.my_user)
+ self._cache.set_initial_unavailable_guilds(event.unavailable_guilds)
+ await self.dispatch(event)
+
+ async def on_resumed(self, shard: gateway_shard.GatewayShard, _: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#resumed for more info."""
+ # TODO: this should be in entity factory
+ await self.dispatch(shard_events.ShardResumedEvent(app=self._app, shard=shard))
+
+ async def on_channel_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-create for more info."""
+ event = self._app.event_factory.deserialize_channel_create_event(shard, payload)
+
+ if isinstance(event.channel, channels.GuildChannel):
+ self._cache.set_guild_channel(event.channel)
+ else:
+ self._cache.set_private_text_channel(typing.cast(channels.PrivateTextChannel, event.channel))
+
+ await self.dispatch(event)
+
+ async def on_channel_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-update for more info."""
+ event = self._app.event_factory.deserialize_channel_update_event(shard, payload)
+
+ if isinstance(event.channel, channels.GuildChannel):
+ self._cache.update_guild_channel(event.channel)
+ else:
+ self._cache.update_private_text_channel(typing.cast(channels.PrivateTextChannel, event.channel))
+
+ await self.dispatch(event)
+
+ async def on_channel_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-delete for more info."""
+ event = self._app.event_factory.deserialize_channel_delete_event(shard, payload)
+
+ if isinstance(event.channel, channels.GuildChannel):
+ self._cache.delete_guild_channel(event.channel.id)
+ else:
+ self._cache.delete_private_text_channel(
+ typing.cast(channels.PrivateTextChannel, event.channel).recipient.id
+ )
+
+ await self.dispatch(event)
+
+ async def on_channel_pins_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-pins-update for more info."""
+ # TODO: we need a method for this specifically
+ await self.dispatch(self._app.event_factory.deserialize_channel_pins_update_event(shard, payload))
+
+ async def on_guild_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-create for more info."""
+ event = self._app.event_factory.deserialize_guild_create_event(shard, payload)
+ self._cache.update_guild(event.guild)
+
+ self._cache.clear_guild_channels_for_guild(event.guild.id)
+ for channel in event.channels.values():
+ self._cache.set_guild_channel(channel)
+
+ self._cache.clear_emojis_for_guild(event.guild.id)
+ for emoji in event.emojis.values():
+ self._cache.set_emoji(emoji)
+
+ self._cache.clear_roles_for_guild(event.guild.id)
+ for role in event.roles.values():
+ self._cache.set_role(role)
+
+ # TODO: do we really want to invalidate these all after an outage.
+ self._cache.clear_members_for_guild(event.guild.id)
+ for member in event.members.values():
+ self._cache.set_member(member)
+
+ self._cache.clear_presences_for_guild(event.guild.id)
+ for presence in event.presences.values():
+ self._cache.set_presence(presence)
+
+ for voice_state in event.voice_states.values():
+ self._cache.set_voice_state(voice_state)
+
+ if event.guild.is_large and (self._intents is None or self._intents & intents_.Intents.GUILD_MEMBERS):
+ await self._app.chunker.request_guild_chunk(event.guild)
+
+ await self.dispatch(event)
+
+ async def on_guild_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-update for more info."""
+ event = self._app.event_factory.deserialize_guild_update_event(shard, payload)
+ self._cache.update_guild(event.guild)
+
+ self._cache.clear_roles_for_guild(event.guild.id)
+ for role in event.roles.values(): # TODO: do we actually get this here?
+ self._cache.set_role(role)
+
+ self._cache.clear_emojis_for_guild(event.guild.id) # TODO: do we actually get this here?
+ for emoji in event.emojis.values():
+ self._cache.set_emoji(emoji)
+
+ await self.dispatch(event)
+
+ async def on_guild_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-delete for more info."""
+ event: typing.Union[guild_events.GuildUnavailableEvent, guild_events.GuildLeaveEvent]
+ if payload.get("unavailable", False):
+ event = self._app.event_factory.deserialize_guild_unavailable_event(shard, payload)
+ self._cache.set_guild_availability(event.guild_id, False)
+
+ else:
+ event = self._app.event_factory.deserialize_guild_leave_event(shard, payload)
+ # TODO: this doesn't work in all intent scenarios
+ self._cache.delete_guild(event.guild_id)
+ self._cache.clear_voice_states_for_guild(event.guild_id)
+ self._cache.clear_invites_for_guild(event.guild_id)
+ self._cache.clear_members_for_guild(event.guild_id)
+ self._cache.clear_presences_for_guild(event.guild_id)
+ self._cache.clear_guild_channels_for_guild(event.guild_id)
+ self._cache.clear_emojis_for_guild(event.guild_id)
+ self._cache.clear_roles_for_guild(event.guild_id)
+
+ await self.dispatch(event)
+
+ async def on_guild_ban_add(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-ban-add for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_ban_add_event(shard, payload))
+
+ async def on_guild_ban_remove(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-ban-remove for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_ban_remove_event(shard, payload))
+
+ async def on_guild_emojis_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-emojis-update for more info."""
+ event = self._app.event_factory.deserialize_guild_emojis_update_event(shard, payload)
+ self._cache.clear_emojis_for_guild(event.guild_id)
+
+ for emoji in event.emojis:
+ self._cache.set_emoji(emoji)
+
+ await self.dispatch(event)
+
+ async def on_guild_integrations_update(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-integrations-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_integrations_update_event(shard, payload))
+
+ async def on_guild_member_add(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-member-add for more info."""
+ event = self._app.event_factory.deserialize_guild_member_add_event(shard, payload)
+ self._cache.update_user(event.user) # TODO: do we still need this here if user is set in set member?
+ # or should those be switched?
+ self._cache.update_member(event.member)
+ await self.dispatch(event)
+
+ async def on_guild_member_remove(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-member-remove for more info."""
+ event = self._app.event_factory.deserialize_guild_member_remove_event(shard, payload)
+ self._cache.update_user(event.user)
+ self._cache.delete_member(event.guild_id, event.user.id)
+ await self.dispatch(event)
+
+ async def on_guild_member_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-member-update for more info."""
+ event = self._app.event_factory.deserialize_guild_member_update_event(shard, payload)
+ self._cache.update_member(event.member)
+ await self.dispatch(event)
+
+ async def on_guild_members_chunk(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-members-chunk for more info."""
+ event = self._app.event_factory.deserialize_guild_member_chunk_event(shard, payload)
+
+ for member in event.members.values():
+ self._cache.set_member(member)
+
+ for presence in event.presences.values():
+ self._cache.set_presence(presence)
+
+ await self.dispatch(event)
+
+ async def on_guild_role_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-role-create for more info."""
+ event = self._app.event_factory.deserialize_guild_role_create_event(shard, payload)
+ self._cache.set_role(event.role)
+ await self.dispatch(event)
+
+ async def on_guild_role_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-role-update for more info."""
+ event = self._app.event_factory.deserialize_guild_role_update_event(shard, payload)
+ self._cache.update_role(event.role)
+ await self.dispatch(event)
+
+ async def on_guild_role_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-role-delete for more info."""
+ event = self._app.event_factory.deserialize_guild_role_delete_event(shard, payload)
+ self._cache.delete_role(event.role_id)
+ await self.dispatch(event)
+
+ async def on_invite_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#invite-create for more info."""
+ event = self._app.event_factory.deserialize_invite_create_event(shard, payload)
+ self._cache.set_invite(event.invite)
+ await self.dispatch(event)
+
+ async def on_invite_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#invite-delete for more info."""
+ event = self._app.event_factory.deserialize_invite_delete_event(shard, payload)
+ self._cache.delete_invite(event.code)
+ await self.dispatch(event)
+
+ async def on_message_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-create for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_create_event(shard, payload))
+
+ # TODO: message cache.
+
+ async def on_message_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_update_event(shard, payload))
+
+ async def on_message_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-delete for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_delete_event(shard, payload))
+
+ async def on_message_delete_bulk(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-delete-bulk for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_delete_bulk_event(shard, payload))
+
+ async def on_message_reaction_add(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-add for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_add_event(shard, payload))
+
+ # TODO: this is unlikely but reaction cache?
+
+ async def on_message_reaction_remove(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-remove for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_remove_event(shard, payload))
+
+ async def on_message_reaction_remove_all(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-remove-all for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_remove_all_event(shard, payload))
+
+ async def on_message_reaction_remove_emoji(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-remove-emoji for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_remove_emoji_event(shard, payload))
+
+ async def on_presence_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#presence-update for more info."""
+ event = self._app.event_factory.deserialize_presence_update_event(shard, payload)
+
+ if event.presence.visible_status is presences.Status.OFFLINE:
+ self._cache.delete_presence(event.presence.guild_id, event.presence.user_id)
+ else:
+ self._cache.update_presence(event.presence)
+
+ # TODO: update user here when partial_user is set self._cache.update_user(event.partial_user)
+ await self.dispatch(event)
+
+ async def on_typing_start(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#typing-start for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_typing_start_event(shard, payload))
+
+ async def on_user_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#user-update for more info."""
+ event = self._app.event_factory.deserialize_own_user_update_event(shard, payload)
+ self._cache.update_me(event.user)
+ await self.dispatch(event)
+
+ async def on_voice_state_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#voice-state-update for more info."""
+ event = self._app.event_factory.deserialize_voice_state_update_event(shard, payload)
+
+ if event.state.channel_id is None:
+ self._cache.delete_voice_state(event.state.guild_id, event.state.user_id)
+ else:
+ self._cache.update_voice_state(event.state)
+
+ await self.dispatch(event)
+
+ async def on_voice_server_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#voice-server-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_voice_server_update_event(shard, payload))
+
+ async def on_webhooks_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#webhooks-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_webhook_update_event(shard, payload))
diff --git a/hikari/impl/stateful_guild_chunker.py b/hikari/impl/stateful_guild_chunker.py
new file mode 100644
index 0000000000..e99dd78f5e
--- /dev/null
+++ b/hikari/impl/stateful_guild_chunker.py
@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic implementation of a guild chunker."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StatefulGuildChunkerImpl"]
+
+import asyncio
+import logging
+import typing
+
+from hikari.api import chunker
+from hikari.impl import rate_limits
+from hikari.models import intents as intents_
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.models import guilds
+
+_LOGGER = logging.getLogger("hikari.guild_chunker")
+
+
+class StatefulGuildChunkerImpl(chunker.GuildChunker):
+ """Guild chunker implementation."""
+
+ __slots__: typing.Sequence[str] = ("_app", "_presences", "_queues", "_chunkers")
+
+ def __init__(self, app: traits.ShardAware, intents: typing.Optional[intents_.Intents]):
+ self._app = app
+ self._presences: bool = intents is None or bool(intents & intents_.Intents.GUILD_PRESENCES)
+ self._queues: typing.Dict[int, typing.List[int]] = {}
+ self._chunkers: typing.Dict[int, asyncio.Task[None]] = {}
+
+ async def request_guild_chunk(self, guild: guilds.GatewayGuild) -> None:
+ if (shard_id := guild.shard_id) is not None:
+ if shard_id not in self._queues:
+ self._queues[shard_id] = []
+
+ self._queues[shard_id].append(guild.id)
+
+ if shard_id not in self._chunkers:
+ task = asyncio.create_task(self._request_chunk(shard_id))
+ self._chunkers[shard_id] = task
+ else:
+ raise RuntimeError("Guild did not have sharding information available")
+
+ async def _request_chunk(self, shard_id: int) -> None:
+ # Since this is not an endpoint but a request, we dont get the ratelimit info
+ # to go off from. This will allow 60 requests per 60 seconds, which should be
+ # a reasonable ratelimit. This will also leave 60 more requests per 60 seconds
+ # for other shard requests if this were to be exausted.
+ with rate_limits.WindowedBurstRateLimiter(f"chunking guilds on shard {shard_id}", 60, 60) as limit:
+ while len(self._queues[shard_id]) != 0:
+ await limit.acquire()
+ guild_id = self._queues[shard_id].pop()
+ message = "requesting guild members for guild %s on shard %s"
+ if self._presences:
+ message = f"{message} with presences"
+ _LOGGER.debug(message, guild_id, shard_id)
+ await self._app.shards[shard_id].request_guild_members(guild_id, include_presences=self._presences)
+
+ del self._chunkers[shard_id]
+
+ def close(self) -> None:
+ while self._chunkers:
+ _, future = self._chunkers.popitem()
+ future.cancel()
diff --git a/hikari/impl/stateless_cache.py b/hikari/impl/stateless_cache.py
new file mode 100644
index 0000000000..e6760d9fd6
--- /dev/null
+++ b/hikari/impl/stateless_cache.py
@@ -0,0 +1,403 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Bare-bones implementation of a cache that never stores anything.
+
+This is used to enable compatibility with HTTP applications and stateless
+bots where desired.
+"""
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StatelessCacheImpl"]
+
+import typing
+
+from hikari.api import cache
+
+if typing.TYPE_CHECKING:
+ from hikari.models import channels
+ from hikari.models import emojis
+ from hikari.models import guilds
+ from hikari.models import invites
+ from hikari.models import presences
+ from hikari.models import users
+ from hikari.models import voices
+ from hikari.utilities import snowflake
+
+
+@typing.final
+class StatelessCacheImpl(cache.MutableCache):
+ """Stateless cache.
+
+ A stateless cache implementation that implements dummy operations for
+ each of the required attributes of a functional cache implementation.
+ Any descriptors will always return `builtins.NotImplemented`, and any
+ methods will always raise `hikari.errors.HikariError` when being invoked.
+
+ The only state that _is_ stored will be the bot user, as this is generally
+ useful information to always know about, and is required for some
+ functionality such as voice support.
+ """
+
+ __slots__: typing.Sequence[str] = ("_app", "_me")
+
+ def __init__(self) -> None:
+ self._me: typing.Optional[users.OwnUser] = None
+
+ def get_me(self) -> typing.Optional[users.OwnUser]:
+ return self._me
+
+ def set_me(self, user: users.OwnUser, /) -> None:
+ self._me = user
+
+ @staticmethod
+ def _no_cache() -> NotImplementedError:
+ return NotImplementedError("This application is stateless, cache operations are not implemented.")
+
+ def clear_private_text_channels(self) -> cache.CacheView[snowflake.Snowflake, channels.PrivateTextChannel]:
+ raise self._no_cache()
+
+ def delete_private_text_channel(
+ self, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[channels.PrivateTextChannel]:
+ raise self._no_cache()
+
+ def get_private_text_channel(self, user_id: snowflake.Snowflake, /) -> typing.Optional[channels.PrivateTextChannel]:
+ raise self._no_cache()
+
+ def get_private_text_channels_view(self) -> cache.CacheView[snowflake.Snowflake, channels.PrivateTextChannel]:
+ raise self._no_cache()
+
+ def set_private_text_channel(self, channel: channels.PrivateTextChannel, /) -> None:
+ raise self._no_cache()
+
+ def update_private_text_channel(
+ self, channel: channels.PrivateTextChannel, /
+ ) -> typing.Tuple[typing.Optional[channels.PrivateTextChannel], typing.Optional[channels.PrivateTextChannel]]:
+ raise self._no_cache()
+
+ def clear_emojis(self) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ raise self._no_cache()
+
+ def clear_emojis_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ raise self._no_cache()
+
+ def delete_emoji(self, emoji_id: snowflake.Snowflake, /) -> typing.Optional[emojis.KnownCustomEmoji]:
+ raise self._no_cache()
+
+ def get_emoji(self, emoji_id: snowflake.Snowflake, /) -> typing.Optional[emojis.KnownCustomEmoji]:
+ raise self._no_cache()
+
+ def get_emojis_view(self) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ raise self._no_cache()
+
+ def get_emojis_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, emojis.KnownCustomEmoji]:
+ raise self._no_cache()
+
+ def set_emoji(self, emoji: emojis.KnownCustomEmoji, /) -> None:
+ raise self._no_cache()
+
+ def update_emoji(
+ self, emoji: emojis.KnownCustomEmoji, /
+ ) -> typing.Tuple[typing.Optional[emojis.KnownCustomEmoji], typing.Optional[emojis.KnownCustomEmoji]]:
+ raise self._no_cache()
+
+ def clear_guilds(self) -> cache.CacheView[snowflake.Snowflake, guilds.GatewayGuild]:
+ raise self._no_cache()
+
+ def delete_guild(self, guild_id: snowflake.Snowflake, /) -> typing.Optional[guilds.GatewayGuild]:
+ raise self._no_cache()
+
+ def get_guild(self, guild_id: snowflake.Snowflake, /) -> typing.Optional[guilds.GatewayGuild]:
+ raise self._no_cache()
+
+ def get_guilds_view(self) -> cache.CacheView[snowflake.Snowflake, guilds.GatewayGuild]:
+ raise self._no_cache()
+
+ def set_guild(self, guild: guilds.GatewayGuild, /) -> None:
+ raise self._no_cache()
+
+ def set_guild_availability(self, guild_id: snowflake.Snowflake, is_available: bool, /) -> None:
+ raise self._no_cache()
+
+ def set_initial_unavailable_guilds(self, guild_ids: typing.Collection[snowflake.Snowflake], /) -> None:
+ raise self._no_cache()
+
+ def update_guild(
+ self, guild: guilds.GatewayGuild, /
+ ) -> typing.Tuple[typing.Optional[guilds.GatewayGuild], typing.Optional[guilds.GatewayGuild]]:
+ raise self._no_cache()
+
+ def clear_guild_channels(self) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ raise self._no_cache()
+
+ def clear_guild_channels_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ raise self._no_cache()
+
+ def delete_guild_channel(self, channel_id: snowflake.Snowflake, /) -> typing.Optional[channels.GuildChannel]:
+ raise self._no_cache()
+
+ def get_guild_channel(self, channel_id: snowflake.Snowflake, /) -> typing.Optional[channels.GuildChannel]:
+ raise self._no_cache()
+
+ def get_guild_channels_view(self) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ raise self._no_cache()
+
+ def get_guild_channels_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, channels.GuildChannel]:
+ raise self._no_cache()
+
+ def set_guild_channel(self, channel: channels.GuildChannel, /) -> None:
+ raise self._no_cache()
+
+ def update_guild_channel(
+ self, channel: channels.GuildChannel, /
+ ) -> typing.Tuple[typing.Optional[channels.GuildChannel], typing.Optional[channels.GuildChannel]]:
+ raise self._no_cache()
+
+ def clear_invites(self) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def clear_invites_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def clear_invites_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def delete_invite(self, code: str, /) -> typing.Optional[invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def get_invite(self, code: str, /) -> typing.Optional[invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def get_invites_view(self) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def get_invites_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def get_invites_view_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[str, invites.InviteWithMetadata]:
+ raise self._no_cache()
+
+ def set_invite(self, invite: invites.InviteWithMetadata, /) -> None:
+ raise self._no_cache()
+
+ def update_invite(
+ self, invite: invites.InviteWithMetadata, /
+ ) -> typing.Tuple[typing.Optional[invites.InviteWithMetadata], typing.Optional[invites.InviteWithMetadata]]:
+ raise self._no_cache()
+
+ def delete_me(self) -> typing.Optional[users.OwnUser]:
+ raise self._no_cache()
+
+ def update_me(
+ self, user: users.OwnUser, /
+ ) -> typing.Tuple[typing.Optional[users.OwnUser], typing.Optional[users.OwnUser]]:
+ raise self._no_cache()
+
+ def clear_members(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, guilds.Member]]:
+ raise self._no_cache()
+
+ def clear_members_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Member]:
+ raise self._no_cache()
+
+ def delete_member(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[guilds.Member]:
+ raise self._no_cache()
+
+ def get_member(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[guilds.Member]:
+ raise self._no_cache()
+
+ def get_members_view(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, guilds.Member]]:
+ raise self._no_cache()
+
+ def get_members_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Member]:
+ raise self._no_cache()
+
+ def set_member(self, member: guilds.Member, /) -> None:
+ raise self._no_cache()
+
+ def update_member(
+ self, member: guilds.Member, /
+ ) -> typing.Tuple[typing.Optional[guilds.Member], typing.Optional[guilds.Member]]:
+ raise self._no_cache()
+
+ def clear_presences(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, presences.MemberPresence]]:
+ raise self._no_cache()
+
+ def clear_presences_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, presences.MemberPresence]:
+ raise self._no_cache()
+
+ def delete_presence(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[presences.MemberPresence]:
+ raise self._no_cache()
+
+ def get_presence(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[presences.MemberPresence]:
+ raise self._no_cache()
+
+ def get_presences_view(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, presences.MemberPresence]]:
+ raise self._no_cache()
+
+ def get_presences_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, presences.MemberPresence]:
+ raise self._no_cache()
+
+ def set_presence(self, presence: presences.MemberPresence, /) -> None:
+ raise self._no_cache()
+
+ def update_presence(
+ self, presence: presences.MemberPresence, /
+ ) -> typing.Tuple[typing.Optional[presences.MemberPresence], typing.Optional[presences.MemberPresence]]:
+ raise self._no_cache()
+
+ def clear_roles(self) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ raise self._no_cache()
+
+ def clear_roles_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ raise self._no_cache()
+
+ def delete_role(self, role_id: snowflake.Snowflake, /) -> typing.Optional[guilds.Role]:
+ raise self._no_cache()
+
+ def get_role(self, role_id: snowflake.Snowflake, /) -> typing.Optional[guilds.Role]:
+ raise self._no_cache()
+
+ def get_roles_view(self) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ raise self._no_cache()
+
+ def get_roles_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, guilds.Role]:
+ raise self._no_cache()
+
+ def set_role(self, role: guilds.Role, /) -> None:
+ raise self._no_cache()
+
+ def update_role(
+ self, role: guilds.Role, /
+ ) -> typing.Tuple[typing.Optional[guilds.Role], typing.Optional[guilds.Role]]:
+ raise self._no_cache()
+
+ def clear_users(self) -> cache.CacheView[snowflake.Snowflake, users.User]:
+ raise self._no_cache()
+
+ def delete_user(self, user_id: snowflake.Snowflake, /) -> typing.Optional[users.User]:
+ raise self._no_cache()
+
+ def get_user(self, user_id: snowflake.Snowflake, /) -> typing.Optional[users.User]:
+ raise self._no_cache()
+
+ def get_users_view(self) -> cache.CacheView[snowflake.Snowflake, users.User]:
+ raise self._no_cache()
+
+ def set_user(self, user: users.User, /) -> None:
+ raise self._no_cache()
+
+ def update_user(
+ self, user: users.User, /
+ ) -> typing.Tuple[typing.Optional[users.User], typing.Optional[users.User]]:
+ raise self._no_cache()
+
+ def clear_voice_states(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, voices.VoiceState]]:
+ raise self._no_cache()
+
+ def clear_voice_states_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ raise self._no_cache()
+
+ def clear_voice_states_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ raise self._no_cache()
+
+ def delete_voice_state(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[voices.VoiceState]:
+ raise self._no_cache()
+
+ def get_voice_state(
+ self, guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake, /
+ ) -> typing.Optional[voices.VoiceState]:
+ raise self._no_cache()
+
+ def get_voice_states_view(
+ self,
+ ) -> cache.CacheView[snowflake.Snowflake, cache.CacheView[snowflake.Snowflake, voices.VoiceState]]:
+ raise self._no_cache()
+
+ def get_voice_states_view_for_channel(
+ self, guild_id: snowflake.Snowflake, channel_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ raise self._no_cache()
+
+ def get_voice_states_view_for_guild(
+ self, guild_id: snowflake.Snowflake, /
+ ) -> cache.CacheView[snowflake.Snowflake, voices.VoiceState]:
+ raise self._no_cache()
+
+ def set_voice_state(self, voice_state: voices.VoiceState, /) -> None:
+ raise self._no_cache()
+
+ def update_voice_state(
+ self, voice_state: voices.VoiceState, /
+ ) -> typing.Tuple[typing.Optional[voices.VoiceState], typing.Optional[voices.VoiceState]]:
+ raise self._no_cache()
diff --git a/hikari/impl/stateless_event_manager.py b/hikari/impl/stateless_event_manager.py
new file mode 100644
index 0000000000..f6827d7c96
--- /dev/null
+++ b/hikari/impl/stateless_event_manager.py
@@ -0,0 +1,221 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Event handling logic."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StatelessEventManagerImpl"]
+
+import logging
+import typing
+
+from hikari.events import shard_events
+from hikari.impl import event_manager_base
+
+if typing.TYPE_CHECKING:
+
+ from hikari.api import shard as gateway_shard
+ from hikari.utilities import data_binding
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari")
+
+
+class StatelessEventManagerImpl(event_manager_base.EventManagerBase):
+ """Provides event handling logic for Discord events without a cache."""
+
+ __slots__: typing.Sequence[str] = ()
+
+ async def on_connected(self, shard: gateway_shard.GatewayShard, _: data_binding.JSONObject) -> None:
+ """Handle connection events.
+
+ This is a synthetic event produced by the gateway implementation in
+ Hikari.
+ """
+ # TODO: this should be in entity factory
+ await self.dispatch(shard_events.ShardConnectedEvent(app=self._app, shard=shard))
+
+ async def on_disconnected(self, shard: gateway_shard.GatewayShard, _: data_binding.JSONObject) -> None:
+ """Handle disconnection events.
+
+ This is a synthetic event produced by the gateway implementation in
+ Hikari.
+ """
+ # TODO: this should be in entity factory
+ await self.dispatch(shard_events.ShardDisconnectedEvent(app=self._app, shard=shard))
+
+ async def on_ready(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#ready for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_ready_event(shard, payload))
+
+ async def on_resumed(self, shard: gateway_shard.GatewayShard, _: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#resumed for more info."""
+ # TODO: this should be in entity factory
+ await self.dispatch(shard_events.ShardResumedEvent(app=self._app, shard=shard))
+
+ async def on_channel_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-create for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_channel_create_event(shard, payload))
+
+ async def on_channel_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_channel_update_event(shard, payload))
+
+ async def on_channel_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-delete for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_channel_delete_event(shard, payload))
+
+ async def on_channel_pins_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#channel-pins-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_channel_pins_update_event(shard, payload))
+
+ async def on_guild_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-create for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_create_event(shard, payload))
+
+ async def on_guild_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_update_event(shard, payload))
+
+ async def on_guild_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-delete for more info."""
+ if payload.get("unavailable", False):
+ await self.dispatch(self._app.event_factory.deserialize_guild_unavailable_event(shard, payload))
+ else:
+ await self.dispatch(self._app.event_factory.deserialize_guild_leave_event(shard, payload))
+
+ async def on_guild_ban_add(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-ban-add for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_ban_add_event(shard, payload))
+
+ async def on_guild_ban_remove(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-ban-remove for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_ban_remove_event(shard, payload))
+
+ async def on_guild_emojis_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-emojis-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_emojis_update_event(shard, payload))
+
+ async def on_guild_integrations_update(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-integrations-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_integrations_update_event(shard, payload))
+
+ async def on_guild_member_add(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-member-add for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_member_add_event(shard, payload))
+
+ async def on_guild_member_remove(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-member-remove for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_member_remove_event(shard, payload))
+
+ async def on_guild_member_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-member-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_member_update_event(shard, payload))
+
+ async def on_guild_members_chunk(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-members-chunk for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_member_chunk_event(shard, payload))
+
+ async def on_guild_role_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-role-create for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_role_create_event(shard, payload))
+
+ async def on_guild_role_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-role-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_role_update_event(shard, payload))
+
+ async def on_guild_role_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#guild-role-delete for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_guild_role_delete_event(shard, payload))
+
+ async def on_invite_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#invite-create for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_invite_create_event(shard, payload))
+
+ async def on_invite_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#invite-delete for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_invite_delete_event(shard, payload))
+
+ async def on_message_create(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-create for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_create_event(shard, payload))
+
+ async def on_message_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_update_event(shard, payload))
+
+ async def on_message_delete(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-delete for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_delete_event(shard, payload))
+
+ async def on_message_delete_bulk(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-delete-bulk for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_delete_bulk_event(shard, payload))
+
+ async def on_message_reaction_add(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-add for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_add_event(shard, payload))
+
+ async def on_message_reaction_remove(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-remove for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_remove_event(shard, payload))
+
+ async def on_message_reaction_remove_all(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-remove-all for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_remove_all_event(shard, payload))
+
+ async def on_message_reaction_remove_emoji(
+ self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject
+ ) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#message-reaction-remove-emoji for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_message_reaction_remove_emoji_event(shard, payload))
+
+ async def on_presence_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#presence-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_presence_update_event(shard, payload))
+
+ async def on_typing_start(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#typing-start for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_typing_start_event(shard, payload))
+
+ async def on_user_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#user-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_own_user_update_event(shard, payload))
+
+ async def on_voice_state_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#voice-state-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_voice_state_update_event(shard, payload))
+
+ async def on_voice_server_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#voice-server-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_voice_server_update_event(shard, payload))
+
+ async def on_webhooks_update(self, shard: gateway_shard.GatewayShard, payload: data_binding.JSONObject) -> None:
+ """See https://discord.com/developers/docs/topics/gateway#webhooks-update for more info."""
+ await self.dispatch(self._app.event_factory.deserialize_webhook_update_event(shard, payload))
diff --git a/hikari/impl/stateless_guild_chunker.py b/hikari/impl/stateless_guild_chunker.py
new file mode 100644
index 0000000000..0ea4e1c5ca
--- /dev/null
+++ b/hikari/impl/stateless_guild_chunker.py
@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Basic implementation of a guild chunker."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["StatelessGuildChunkerImpl"]
+
+import typing
+
+from hikari.api import chunker
+
+if typing.TYPE_CHECKING:
+ from hikari.models import guilds
+
+
+class StatelessGuildChunkerImpl(chunker.GuildChunker):
+ """Stateless guild chunker.
+
+ A stateless guild chunker implementation that implements dummy operations
+ for each of the required attributes of a functional guild chunker
+ implementation. Any methods will always raise `builtins.NotImplemented`
+ when being invoked.
+ """
+
+ __slots__: typing.Sequence[str] = ()
+
+ async def request_guild_chunk(self, guild: guilds.GatewayGuild) -> None:
+ raise NotImplementedError("This application is stateless, guild chunking operations are not implemented.")
+
+ def close(self) -> None:
+ return
diff --git a/hikari/impl/voice.py b/hikari/impl/voice.py
new file mode 100644
index 0000000000..5701f7e957
--- /dev/null
+++ b/hikari/impl/voice.py
@@ -0,0 +1,232 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Implementation of a simple voice management system."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = []
+
+import asyncio
+
+# noinspection PyUnresolvedReferences
+import logging
+import typing
+
+from hikari import errors
+from hikari.api import event_dispatcher
+from hikari.api import voice
+from hikari.events import voice_events
+from hikari.impl import bot
+from hikari.models import channels
+from hikari.models import guilds
+from hikari.utilities import snowflake
+
+if typing.TYPE_CHECKING:
+ _VoiceEventCallbackT = typing.Callable[[voice_events.VoiceEvent], typing.Coroutine[None, typing.Any, None]]
+
+
+_LOGGER: typing.Final[logging.Logger] = logging.getLogger("hikari.voice.management")
+
+
+_VoiceConnectionT = typing.TypeVar("_VoiceConnectionT", bound="voice.VoiceConnection")
+
+
+class VoiceComponentImpl(voice.VoiceComponent):
+ """A standard voice component management implementation.
+
+ This is the regular implementation you will generally use to connect to
+ voice channels with.
+ """
+
+ __slots__: typing.Sequence[str] = ("_app", "_connections", "_dispatcher")
+
+ def __init__(self, app: bot.BotApp, dispatcher: event_dispatcher.EventDispatcher) -> None:
+ self._app = app
+ self._dispatcher = dispatcher
+ self._connections: typing.Dict[snowflake.Snowflake, voice.VoiceConnection] = {}
+ self._dispatcher.subscribe(voice_events.VoiceEvent, self._on_voice_event)
+
+ @property
+ def app(self) -> bot.BotApp:
+ return self._app
+
+ @property
+ def connections(self) -> typing.Mapping[snowflake.Snowflake, voice.VoiceConnection]:
+ return self._connections.copy()
+
+ async def disconnect(self) -> None:
+ if self._connections:
+ _LOGGER.info("shutting down %s voice connection(s)", len(self._connections))
+ await asyncio.gather(*(c.disconnect() for c in self._connections.values()))
+
+ async def close(self) -> None:
+ await self.disconnect()
+ self._dispatcher.unsubscribe(voice_events.VoiceEvent, self._on_voice_event)
+
+ async def connect_to(
+ self,
+ channel: snowflake.SnowflakeishOr[channels.GuildVoiceChannel],
+ guild: snowflake.SnowflakeishOr[guilds.PartialGuild],
+ *,
+ deaf: bool = False,
+ mute: bool = False,
+ voice_connection_type: typing.Type[_VoiceConnectionT],
+ **kwargs: typing.Any,
+ ) -> _VoiceConnectionT:
+ guild_id = snowflake.Snowflake(guild)
+ # TODO: this and the same logic in channels.py and guilds.py logic should go in a file somewhere
+ shard_id = (guild_id >> 22) % self._app.shard_count
+
+ if shard_id is None:
+ raise errors.VoiceError(
+ "Cannot connect to voice. Ensure the application is configured as a gateway zookeeper and try again."
+ )
+
+ if guild_id in self._connections:
+ raise errors.VoiceError(
+ "The bot is already in a voice channel for this guild. Close the other connection first, or "
+ "request that the application moves to the new voice channel instead."
+ )
+
+ try:
+ shard = self._app.shards[shard_id]
+ except KeyError:
+ raise errors.VoiceError(
+ f"Cannot connect to shard {shard_id}, it is not present in this application."
+ ) from None
+
+ if not shard.is_alive:
+ # Not sure if I can think of a situation this will happen in... really.
+ # Unless the user sleeps for a bit then tries to connect, and in the mean time the
+ # shard has disconnected.
+ # TODO: make shards declare if they are in the process of reconnecting, if they are, make them wait
+ # for a little bit.
+ raise errors.VoiceError(f"Cannot connect to shard {shard_id}, the shard is not online.")
+
+ _LOGGER.debug("attempting to connect to voice channel %s in %s via shard %s", channel, guild, shard_id)
+
+ user_id = await shard.get_user_id()
+ await asyncio.wait_for(shard.update_voice_state(guild, channel, self_deaf=deaf, self_mute=mute), timeout=5.0)
+
+ _LOGGER.debug(
+ "waiting for voice events for connecting to voice channel %s in %s via shard %s", channel, guild, shard_id
+ )
+
+ state_event, server_event = await asyncio.wait_for(
+ asyncio.gather(
+ # Voice state update:
+ self._dispatcher.wait_for(
+ voice_events.VoiceStateUpdateEvent,
+ timeout=None,
+ predicate=self._init_state_update_predicate(guild_id, user_id),
+ ),
+ # Server update:
+ self._dispatcher.wait_for(
+ voice_events.VoiceServerUpdateEvent,
+ timeout=None,
+ predicate=self._init_server_update_predicate(guild_id),
+ ),
+ ),
+ timeout=10.0,
+ )
+
+ _LOGGER.debug(
+ "joined voice channel %s in guild %s via shard %s using endpoint %s. Session will be %s. "
+ "Delegating to voice websocket",
+ state_event.state.channel_id,
+ state_event.state.guild_id,
+ shard_id,
+ server_event.endpoint,
+ state_event.state.session_id,
+ )
+
+ try:
+ voice_connection = await voice_connection_type.initialize(
+ channel_id=snowflake.Snowflake(channel),
+ debug=self._app.is_debug_enabled,
+ endpoint=server_event.endpoint,
+ guild_id=guild_id,
+ on_close=self._on_connection_close,
+ owner=self,
+ session_id=state_event.state.session_id,
+ shard_id=shard_id,
+ token=server_event.token,
+ user_id=user_id,
+ **kwargs,
+ )
+ except Exception:
+ _LOGGER.debug(
+ "error occurred in initialization, leaving voice channel %s in guild %s again", channel, guild
+ )
+ await asyncio.wait_for(shard.update_voice_state(guild, None), timeout=5.0)
+ raise
+
+ self._connections[guild_id] = voice_connection
+ return voice_connection
+
+ @staticmethod
+ def _init_state_update_predicate(
+ guild_id: snowflake.Snowflake, user_id: snowflake.Snowflake,
+ ) -> typing.Callable[[voice_events.VoiceStateUpdateEvent], bool]:
+ def predicate(event: voice_events.VoiceStateUpdateEvent) -> bool:
+ return event.state.guild_id == guild_id and event.state.user_id == user_id
+
+ return predicate
+
+ @staticmethod
+ def _init_server_update_predicate(
+ guild_id: snowflake.Snowflake,
+ ) -> typing.Callable[[voice_events.VoiceServerUpdateEvent], bool]:
+ def predicate(event: voice_events.VoiceServerUpdateEvent) -> bool:
+ return event.guild_id == guild_id
+
+ return predicate
+
+ async def _on_connection_close(self, connection: voice.VoiceConnection) -> None:
+ try:
+ del self._connections[connection.guild_id]
+
+ # Leave the voice channel explicitly, otherwise we will just appear to
+ # not leave properly.
+ await self._app.shards[connection.shard_id].update_voice_state(
+ guild=connection.guild_id, channel=None,
+ )
+
+ _LOGGER.debug(
+ "successfully unregistered voice connection %s to guild %s and left voice channel %s",
+ connection,
+ connection.guild_id,
+ connection.channel_id,
+ )
+
+ except KeyError:
+ _LOGGER.warning(
+ "ignored closure of phantom unregistered voice connection %s to guild %s. Perhaps this is a bug?",
+ connection,
+ connection.guild_id,
+ )
+
+ async def _on_voice_event(self, event: voice_events.VoiceEvent) -> None:
+ if event.guild_id in self._connections:
+ connection = self._connections[event.guild_id]
+ _LOGGER.debug("notifying voice connection %s in guild %s of event %s", connection, event.guild_id, event)
+ await connection.notify(event)
diff --git a/hikari/internal_utilities/__init__.py b/hikari/internal_utilities/__init__.py
deleted file mode 100644
index 019aae3887..0000000000
--- a/hikari/internal_utilities/__init__.py
+++ /dev/null
@@ -1,31 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-# Copyright © Nekokatt 2019-2020
-#
-# This file is part of Hikari.
-#
-# Hikari 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.
-#
-# Hikari 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 Hikari. If not, see )
+
+ # Changing timezones.
+ >>> dt = datetime.datetime.now(tz=datetime.timezone.utc)
+ >>> print(dt)
+ datetime.datetime(2020, 6, 5, 18, 38, 27, 863990, tzinfo=datetime.timezone.utc)
+ >>> dt.astimezone(tzlocal.get_localzone())
+ datetime.datetime(2020, 6, 5, 19, 38, 27, 863990, tzinfo=)
+
+ ...this is not required, but you may find it more useful if using the
+ timestamps in debug logs, for example.
+ """
+ return self._timestamp
+
+ @timestamp.setter
+ def timestamp(self, value: typing.Optional[datetime.datetime]) -> None:
+ if value is not None and value.tzinfo is None:
+ self.__warn_naive_datetime()
+ value = value.astimezone()
+
+ self._timestamp = value
+
+ @staticmethod
+ def __warn_naive_datetime() -> None:
+ message = textwrap.dedent(
+ """
+ You forgot to set a timezone on the timestamp you just set in an embed!
+
+ Hikari converts all datetime objects to UTC (GMT+0) internally, since
+ Discord expects all timestamps to be provided using UTC. This means
+ that failing to set a timezone may result in bugs where the time appears
+ to be incorrectly offset by several hours.
+
+ To avoid this, you should tell the datetime to use the system timezone
+ explicitly, or specify a timezone when creating your datetime object.
+ Hikari will detect this and perform the correct conversion for you.
+
+ timestamp = datetime.datetime.now().astimezone()
+ # or
+ timestamp = datetime.datetime.now(tz=datetime.timezone.utc)
+
+ NOTE: datetime.utcnow WILL NOT WORK CORRECTLY WITH THIS IMPLEMENTATION.
+
+ Relying on timezone-naive datetimes may be deprecated and result in
+ an error in future releases.
+
+ The offending line of code causing this warning was:"""
+ )
+
+ warnings.warn(
+ message, category=errors.HikariWarning, stacklevel=3,
+ )
+
+ @property
+ def footer(self) -> typing.Optional[EmbedFooter]:
+ """Return the footer of the embed.
+
+ Will be `builtins.None` if not set.
+
+ EmbedFooter or builtins.None
+ The footer of the embed.
+ """
+ return self._footer
+
+ @property
+ def image(self) -> typing.Optional[EmbedImage[files.AsyncReader]]:
+ """Return the image set in the embed.
+
+ Will be `builtins.None` if not set.
+
+ EmbedImage or builtins.None
+ The image of the embed.
+
+ !!! note
+ Use `set_image` to update this value.
+ """
+ return self._image
+
+ @property
+ def thumbnail(self) -> typing.Optional[EmbedImage[files.AsyncReader]]:
+ """Return the thumbnail set in the embed.
+
+ Will be `builtins.None` if not set.
+
+ EmbedImage or builtins.None
+ The thumbnail of the embed.
+
+ !!! note
+ Use `set_thumbnail` to update this value.
+ """
+ return self._thumbnail
+
+ @property
+ def video(self) -> typing.Optional[EmbedVideo[files.AsyncReader]]:
+ """Return the video to show in the embed.
+
+ Will be `builtins.None` if not set.
+
+ Returns
+ -------
+ EmbedVideo or builtins.None
+ The video of the embed.
+
+ !!! note
+ This object cannot be set by bots or webhooks while sending an embed
+ and will be ignored during serialization. Expect this to be
+ populated on any received embed attached to a message event with a
+ video attached.
+ """
+ return self._video
+
+ @property
+ def provider(self) -> typing.Optional[EmbedProvider]:
+ """Return the provider to show in the embed.
+
+ Will be `builtins.None` if not set.
+
+ Returns
+ -------
+ EmbedProvider or builtins.None
+ The provider of the embed.
+
+ !!! note
+ This object cannot be set by bots or webhooks while sending an embed
+ and will be ignored during serialization. Expect this to be
+ populated on any received embed attached to a message event with a
+ custom provider set.
+ """
+ return self._provider
+
+ @property
+ def author(self) -> typing.Optional[EmbedAuthor]:
+ """Return the author to show in the embed.
+
+ Will be `builtins.None` if not set.
+
+ Returns
+ -------
+ EmbedAuthor or builtins.None
+ The author of the embed.
+
+ !!! note
+ Use `set_author` to update this value.
+ """
+ return self._author
+
+ @property
+ def fields(self) -> typing.Sequence[EmbedField]:
+ """Return the sequence of fields in the embed.
+
+ !!! note
+ Use `add_field` to add a new field, `edit_field` to edit an existing
+ field, or `remove_field` to remove a field.
+ """
+ return self._fields if self._fields else []
+
+ def set_author(
+ self,
+ *,
+ name: typing.Optional[str] = None,
+ url: typing.Optional[str] = None,
+ icon: typing.Optional[files.Resourceish] = None,
+ ) -> Embed:
+ """Set the author of this embed.
+
+ Parameters
+ ----------
+ name : builtins.str or builtins.None
+ The optional name of the author.
+ url : builtins.str or builtins.None
+ The optional URL of the author.
+ icon : hikari.utilities.files.Resourceish or builtins.None
+ The optional image to show next to the embed author.
+
+ This can be many different things, to aid in convenience.
+
+ - If `builtins.None`, nothing is set.
+ - If a `pathlib.PurePath` or `builtins.str` to a valid URL, the URL
+ is linked to directly.
+ - Subclasses of `hikari.utilities.files.WebResource` such as
+ `hikari.utilities.files.URL`,
+ `hikari.models.messages.Attachment`,
+ `hikari.models.emojis.Emoji`,
+ `EmbedResource`, etc will have their URL linked to directly.
+ this field.
+ - If a `hikari.utilities.files.Bytes` is passed, or a `builtins.str`
+ that contains a valid data URI is passed, then this is uploaded
+ as an attachment and linked into the embed.
+ - If a `hikari.utilities.files.File`, `pathlib.PurePath` or
+ `builtins.str` that is an absolute or relative path to a file
+ on your file system is passed, then this resource is uploaded
+ as an attachment using non-blocking code internally and linked
+ into the embed.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+ """
+ if name is None and url is None and icon is None:
+ self._author = None
+ else:
+ self._author = EmbedAuthor()
+ self._author.name = name
+ self._author.url = url
+ if icon is not None:
+ self._author.icon = EmbedResourceWithProxy(resource=files.ensure_resource(icon))
+ else:
+ self._author.icon = None
+ return self
+
+ def set_footer(self, *, text: typing.Optional[str], icon: typing.Optional[files.Resourceish] = None) -> Embed:
+ """Set the footer of this embed.
+
+ Parameters
+ ----------
+ text : str or builtins.None
+ The mandatory text string to set in the footer.
+ If `builtins.None`, the footer is removed.
+ icon : hikari.utilities.files.Resourceish or builtins.None
+ The optional image to show next to the embed footer.
+
+ This can be many different things, to aid in convenience.
+
+ - If `builtins.None`, nothing is set.
+ - If a `pathlib.PurePath` or `builtins.str` to a valid URL, the URL
+ is linked to directly.
+ - Subclasses of `hikari.utilities.files.WebResource` such as
+ `hikari.utilities.files.URL`,
+ `hikari.models.messages.Attachment`,
+ `hikari.models.emojis.Emoji`,
+ `EmbedResource`, etc will have their URL linked to directly.
+ this field.
+ - If a `hikari.utilities.files.Bytes` is passed, or a `builtins.str`
+ that contains a valid data URI is passed, then this is uploaded
+ as an attachment and linked into the embed.
+ - If a `hikari.utilities.files.File`, `pathlib.PurePath` or
+ `builtins.str` that is an absolute or relative path to a file
+ on your file system is passed, then this resource is uploaded
+ as an attachment using non-blocking code internally and linked
+ into the embed.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+ """
+ if text is None:
+ if icon is not None:
+ raise TypeError(
+ "Cannot specify footer text in embed to be None while setting a non-None icon. "
+ "Set some textual content in order to use a footer icon."
+ )
+
+ self._footer = None
+ else:
+ self._footer = EmbedFooter()
+ self._footer.text = text
+ if icon is not None:
+ self._footer.icon = EmbedResourceWithProxy(resource=files.ensure_resource(icon))
+ else:
+ self._footer.icon = None
+ return self
+
+ def set_image(self, image: typing.Optional[files.Resourceish] = None, /) -> Embed:
+ """Set the image on this embed.
+
+ Parameters
+ ----------
+ image : hikari.utilities.files.Resourceish or builtins.None
+ The optional resource to show for the embed image.
+
+ This can be many different things, to aid in convenience.
+
+ - If `builtins.None`, nothing is set.
+ - If a `pathlib.PurePath` or `builtins.str` to a valid URL, the URL
+ is linked to directly.
+ - Subclasses of `hikari.utilities.files.WebResource` such as
+ `hikari.utilities.files.URL`,
+ `hikari.models.messages.Attachment`,
+ `hikari.models.emojis.Emoji`,
+ `EmbedResource`, etc will have their URL linked to directly.
+ this field.
+ - If a `hikari.utilities.files.Bytes` is passed, or a `builtins.str`
+ that contains a valid data URI is passed, then this is uploaded
+ as an attachment and linked into the embed.
+ - If a `hikari.utilities.files.File`, `pathlib.PurePath` or
+ `builtins.str` that is an absolute or relative path to a file
+ on your file system is passed, then this resource is uploaded
+ as an attachment using non-blocking code internally and linked
+ into the embed.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+ """
+ if image is not None:
+ self._image = EmbedImage(resource=files.ensure_resource(image))
+ else:
+ self._image = None
+
+ return self
+
+ def set_thumbnail(self, image: typing.Optional[files.Resourceish] = None, /) -> Embed:
+ """Set the image on this embed.
+
+ Parameters
+ ----------
+ image : hikari.utilities.files.Resourceish or builtins.None
+ The optional resource to show for the embed thumbnail.
+
+ This can be many different things, to aid in convenience.
+
+ - If `builtins.None`, nothing is set.
+ - If a `pathlib.PurePath` or `builtins.str` to a valid URL, the URL
+ is linked to directly.
+ - Subclasses of `hikari.utilities.files.WebResource` such as
+ `hikari.utilities.files.URL`,
+ `hikari.models.messages.Attachment`,
+ `hikari.models.emojis.Emoji`,
+ `EmbedResource`, etc will have their URL linked to directly.
+ - If a `hikari.utilities.files.Bytes` is passed, or a `builtins.str`
+ that contains a valid data URI is passed, then this is uploaded
+ as an attachment and linked into the embed.
+ - If a `hikari.utilities.files.File`, `pathlib.PurePath` or
+ `builtins.str` that is an absolute or relative path to a file
+ on your file system is passed, then this resource is uploaded
+ as an attachment using non-blocking code internally and linked
+ into the embed.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+ """
+ if image is not None:
+ self._thumbnail = EmbedImage(resource=files.ensure_resource(image))
+ else:
+ self._thumbnail = None
+
+ return self
+
+ def add_field(self, name: str, value: str, *, inline: bool = False) -> Embed:
+ """Add a new field to this embed.
+
+ Parameters
+ ----------
+ name : str
+ The mandatory non-empty field name. This must contain at least one
+ non-whitespace character to be valid.
+ value : str
+ The mandatory non-empty field value. This must contain at least one
+ non-whitespace character to be valid.
+ inline : bool
+ If `builtins.True`, the embed field may be shown "inline" on some
+ Discord clients with other fields. If `builtins.False`, it is always placed
+ on a separate line. This will default to `builtins.False`.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+ """
+ if self._fields is None:
+ self._fields = []
+ self._fields.append(EmbedField(name=name, value=value, inline=inline))
+ return self
+
+ def edit_field(
+ self,
+ index: int,
+ name: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ value: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ /,
+ *,
+ inline: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ ) -> Embed:
+ """Edit an existing field on this embed.
+
+ Parameters
+ ----------
+ index : int
+ The index of the field to edit.
+ name : hikari.utilities.undefined.UndefinedOr[str]
+ The new field name to use. If left to the default (`undefined`),
+ then it will not be changed.
+ value : hikari.utilities.undefined.UndefinedOr[str]
+ The new field value to use. If left to the default (`undefined`),
+ then it will not be changed.
+ inline : hikari.utilities.undefined.UndefinedOr[builtins.bool]
+ `builtins.True` to inline the field, or `builtins.False` to force
+ it to be on a separate line. If left to the default (`undefined`),
+ then it will not be changed.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+
+ Raises
+ ------
+ builtins.IndexError
+ Raised if the index is greater than `len(embed.fields) - 1` or
+ less than `-len(embed.fields)`
+ """
+ if not self._fields:
+ raise IndexError(index)
+
+ field = self._fields[index]
+ if name is not undefined.UNDEFINED:
+ field.name = name
+ if value is not undefined.UNDEFINED:
+ field.value = value
+ if inline is not undefined.UNDEFINED:
+ field.is_inline = inline
+ return self
+
+ def remove_field(self, index: int, /) -> Embed:
+ """Remove an existing field from this embed.
+
+ Parameters
+ ----------
+ index : int
+ The index of the embed field to remove.
+
+ Returns
+ -------
+ Embed
+ This embed. Allows for call chaining.
+
+ Raises
+ ------
+ builtins.IndexError
+ Raised if the index is greater than `len(embed.fields) - 1` or
+ less than `-len(embed.fields)`
+ """
+ if self._fields:
+ del self._fields[index]
+ if not self._fields:
+ self._fields = None
+ return self
+
+ def __repr__(self) -> str:
+ return f"Embed(title={self.title}, color={self.color}, timestamp={self.timestamp})"
+
+ def __eq__(self, other: typing.Any) -> bool:
+ if isinstance(other, type(self)):
+ for attrib in self.__slots__:
+ if getattr(self, attrib) != getattr(other, attrib):
+ break
+ else:
+ return True
+ return False
diff --git a/hikari/models/emojis.py b/hikari/models/emojis.py
new file mode 100644
index 0000000000..41ade7618f
--- /dev/null
+++ b/hikari/models/emojis.py
@@ -0,0 +1,331 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Application and entities that are used to describe emojis on Discord."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["Emoji", "UnicodeEmoji", "CustomEmoji", "KnownCustomEmoji", "Emojiish"]
+
+import abc
+import typing
+import unicodedata
+
+import attr
+
+from hikari.utilities import attr_extensions
+from hikari.utilities import constants
+from hikari.utilities import files
+from hikari.utilities import routes
+from hikari.utilities import snowflake
+
+if typing.TYPE_CHECKING:
+ from hikari import traits
+ from hikari.models import users
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Emoji(files.WebResource, abc.ABC):
+ """Base class for all emojis.
+
+ Any emoji implementation supports being used as a
+ `hikari.utilities.files.Resource` when uploading an attachment to the API.
+ This is achieved in the same way as using a
+ `hikari.utilities.files.WebResource` would achieve this.
+ """
+
+ @property
+ @abc.abstractmethod
+ def name(self) -> typing.Optional[str]:
+ """Return the generic name/representation for this emoji."""
+
+ @property
+ @abc.abstractmethod
+ def url(self) -> str:
+ """URL of the emoji image to display in clients."""
+
+ @property
+ @abc.abstractmethod
+ def url_name(self) -> str:
+ """Name of the part of the emoji to use in requests."""
+
+ @property
+ def is_mentionable(self) -> bool:
+ """Whether the emoji can be mentioned or not."""
+ return True
+
+ @property
+ @abc.abstractmethod
+ def mention(self) -> str:
+ """Mention string to use to mention the emoji with."""
+
+
+@attr_extensions.with_copy
+@attr.s(hash=True, init=True, kw_only=False, slots=True, eq=False, weakref_slot=False)
+class UnicodeEmoji(Emoji):
+ """Represents a unicode emoji.
+
+ !!! warning
+ A word of warning if you try to upload this emoji as a file attachment.
+
+ While this emoji type can be used to upload the Twemoji representations
+ of this emoji as a PNG, this is NOT foolproof. The mapping between
+ Discord's implementation and official Twemoji bindings is very flaky.
+ Responsible implementations relying on this behaviour will be
+ implemented to expect this behaviour in the form of
+ `hikari.errors.NotFound` exceptions being raised when a mismatch may
+ occur. It is also likely that this will change in the future without
+ notice, so you will likely be relying on flaky behaviour.
+
+ If this is proven to be too unstable, this functionality will be
+ removed in a future release after a deprecation period.
+ """
+
+ name: str = attr.ib(repr=True, hash=True)
+ """The code points that form the emoji."""
+
+ def __str__(self) -> str:
+ return self.name
+
+ def __eq__(self, other: typing.Any) -> bool:
+ if isinstance(other, Emoji):
+ return self.name == other.name
+ if isinstance(other, str):
+ return self.name == other
+ return False
+
+ @property
+ @typing.final
+ def url_name(self) -> str:
+ return self.name
+
+ @property
+ def mention(self) -> str:
+ return self.name
+
+ @property
+ @typing.final
+ def codepoints(self) -> typing.Sequence[int]:
+ """Integer codepoints that make up this emoji, as UTF-8."""
+ return [ord(c) for c in self.name]
+
+ @property
+ def filename(self) -> str:
+ """Filename to use if re-uploading this emoji's PNG."""
+ codepoints = self.codepoints
+ # It looks like the rule is to delete character #2 if the value
+ # of this is 0xfe0f and the character is 4 characters long.
+ # Other than that, the mapping is 1-to-1. I'll set up a CI task to
+ # double check this each day so we know when Discord breaks it again.
+ # The gay-pride flag is an outlier, for god knows what reason. I don't
+ # care that much but if Discord start breaking this regularly I might
+ # need to ask for a more permanent solution.
+ # This is provisionally provided. If we find it breaks in other ways, I
+ # will just revoke this functionality in a future update.
+ if codepoints[1:2] == [0xFE0F] and len(codepoints) <= 4 and codepoints != [0x1F3F3, 0xFE0F, 0x200D, 0x1F308]:
+ codepoints = [codepoints[0], *codepoints[2:]]
+
+ return "-".join(hex(c)[2:] for c in codepoints) + ".png"
+
+ @property
+ def url(self) -> str:
+ """Get the URL of the PNG rendition of this emoji.
+
+ This will use the official Twitter "twemoji" repository to fetch
+ this information, as Discord only stores this in a hashed format
+ that uses SVG files, which is not usually of any use.
+
+ Since this uses "twemoji" directly, the emojis may not directly
+ match what is on Discord if Discord have failed to keep their emoji
+ packs up-to-date with this repository.
+
+ Example
+ -------
+ https://github.com/twitter/twemoji/raw/master/assets/72x72/1f004.png
+ """
+ return constants.TWEMOJI_PNG_BASE_URL + self.filename
+
+ @property
+ @typing.final
+ def unicode_names(self) -> typing.Sequence[str]:
+ """Get the unicode name of the emoji as a sequence.
+
+ This returns the name of each codepoint. If only one codepoint exists,
+ then this will only have one item in the resulting sequence.
+ """
+ return [unicodedata.name(c) for c in self.name]
+
+ @property
+ @typing.final
+ def unicode_escape(self) -> str:
+ """Get the unicode escape string for this emoji."""
+ return bytes(self.name, "unicode_escape").decode("utf-8")
+
+ @classmethod
+ @typing.final
+ def from_codepoints(cls, codepoint: int, *codepoints: int) -> UnicodeEmoji:
+ """Create a unicode emoji from one or more UTF-32 codepoints."""
+ return cls(name="".join(map(chr, (codepoint, *codepoints))))
+
+ @classmethod
+ @typing.final
+ def from_emoji(cls, emoji: str) -> UnicodeEmoji:
+ """Create a unicode emoji from a raw emoji."""
+ return cls(name=emoji)
+
+ @classmethod
+ @typing.final
+ def from_unicode_escape(cls, escape: str) -> UnicodeEmoji:
+ """Create a unicode emoji from a unicode escape string."""
+ return cls(name=str(escape.encode("utf-8"), "unicode_escape"))
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class CustomEmoji(snowflake.Unique, Emoji):
+ """Represents a custom emoji.
+
+ This is a custom emoji that is from a guild you might not be part of.
+
+ All CustomEmoji objects and their derivatives act as valid
+ `hikari.utilities.files.Resource` objects. This means you can use them as a
+ file when sending a message.
+
+ >>> emojis = await bot.rest.fetch_guild_emojis(12345)
+ >>> picks = random.choices(emojis, 5)
+ >>> await event.reply(files=picks)
+
+ !!! warning
+ Discord will not provide information on whether these emojis are
+ animated or not when a reaction is removed and an event is fired. This
+ is problematic if you need to try and determine the emoji that was
+ removed. The side effect of this means that mentions for animated emojis
+ will not be correct.
+
+ This will not be changed as stated here:
+ https://github.com/discord/discord-api-docs/issues/1614#issuecomment-628548913
+ """
+
+ app: traits.RESTAware = attr.ib(
+ repr=False, eq=False, hash=False, init=True, metadata={attr_extensions.SKIP_DEEP_COPY: True}
+ )
+ """The client application that models may use for procedures."""
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ # TODO: document when this is None, or fix it to not be optional?
+ name: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=True)
+ """The name of the emoji."""
+
+ is_animated: typing.Optional[bool] = attr.ib(eq=False, hash=False, repr=True)
+ """Whether the emoji is animated.
+
+ Will be `builtins.None` when received in Message Reaction Remove and Message
+ Reaction Remove Emoji events.
+ """
+
+ def __str__(self) -> str:
+ return self.name if self.name is not None else f"Unnamed emoji ID {self.id}"
+
+ @property
+ def filename(self) -> str:
+ return str(self.id) + (".gif" if self.is_animated else ".png")
+
+ @property
+ @typing.final
+ def url_name(self) -> str:
+ return f"{self.name}:{self.id}"
+
+ @property
+ @typing.final
+ def mention(self) -> str:
+ return f"<{'a' if self.is_animated else ''}:{self.url_name}>"
+
+ @property
+ def is_mentionable(self) -> bool:
+ return self.is_animated is not None
+
+ @property
+ @typing.final
+ def url(self) -> str:
+ ext = "gif" if self.is_animated else "png"
+
+ return routes.CDN_CUSTOM_EMOJI.compile(constants.CDN_URL, emoji_id=self.id, file_format=ext)
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class KnownCustomEmoji(CustomEmoji):
+ """Represents an emoji that is known from a guild the bot is in.
+
+ This is a specialization of `CustomEmoji` that is from a guild that you
+ _are_ part of. As a result, it contains a lot more information with it.
+ """
+
+ guild_id: snowflake.Snowflake = attr.ib(eq=False, hash=False, repr=False)
+ """The ID of the guild this emoji belongs to."""
+
+ role_ids: typing.Sequence[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The IDs of the roles that are whitelisted to use this emoji.
+
+ If this is empty then any user can use this emoji regardless of their roles.
+ """
+
+ user: typing.Optional[users.User] = attr.ib(eq=False, hash=False, repr=False)
+ """The user that created the emoji.
+
+ !!! note
+ This will be `builtins.None` if you are missing the `MANAGE_EMOJIS`
+ permission in the server the emoji is from.
+ """
+
+ is_animated: bool = attr.ib(eq=False, hash=False, repr=True)
+ """Whether the emoji is animated.
+
+ Unlike in `CustomEmoji`, this information is always known, and will thus
+ never be `builtins.None`.
+ """
+
+ is_colons_required: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether this emoji must be wrapped in colons."""
+
+ is_managed: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether the emoji is managed by an integration."""
+
+ is_available: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether this emoji can currently be used.
+
+ May be `builtins.False` due to a loss of Sever Boosts on the emoji's guild.
+ """
+
+
+Emojiish = typing.Union[str, Emoji]
+"""Type hint representing a string emoji or an `Emoji`-derived object.
+
+Examples include:
+
+- Unicode emoji strings, such as `"\N{OK HAND SIGN}"`, `"\\N{OK HAND SIGN}"`,
+ `"\\U0001f44c"`.
+- Custom emoji names in the format `name:id`, such as
+ `"rosaThonk:733073048646713364"`.
+- Derivative instances of `Emoji`, i.e. `UnicodeEmoji`, `CustomEmoji` and
+ `KnownCustomEmoji`.
+"""
diff --git a/hikari/models/gateway.py b/hikari/models/gateway.py
new file mode 100644
index 0000000000..ade5ff6fc2
--- /dev/null
+++ b/hikari/models/gateway.py
@@ -0,0 +1,92 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Entities directly related to creating and managing gateway shards."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["GatewayBot", "SessionStartLimit"]
+
+import typing
+
+import attr
+
+from hikari.utilities import attr_extensions
+from hikari.utilities import date
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class SessionStartLimit:
+ """Used to represent information about the current session start limits."""
+
+ total: int = attr.ib(repr=True)
+ """The total number of session starts the current bot is allowed."""
+
+ remaining: int = attr.ib(repr=True)
+ """The remaining number of session starts this bot has."""
+
+ reset_after: datetime.timedelta = attr.ib(repr=True)
+ """When `SessionStartLimit.remaining` will reset for the current bot.
+
+ After it resets it will be set to `SessionStartLimit.total`.
+ """
+
+ # This is not documented at the time of writing, but is a confirmed API
+ # feature, so I have included it for completeness.
+ max_concurrency: int = attr.ib(repr=True)
+ """Maximum connection concurrency.
+
+ This defines how many shards can be started at once within a 5 second
+ window. For most bots, this will always be `1`, but for very large bots,
+ this may be increased to reduce startup times. Contact Discord for
+ more information.
+ """
+
+ _created_at: datetime.datetime = attr.ib(factory=date.local_datetime, init=False)
+
+ @property
+ def used(self) -> int:
+ """Return how many times you have sent an IDENTIFY in the window."""
+ return self.total - self.remaining
+
+ @property
+ def reset_at(self) -> datetime.datetime:
+ """Return the approximate time that the IDENTIFY limit resets at."""
+ return self._created_at + self.reset_after
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class GatewayBot:
+ """Used to represent gateway information for the connected bot."""
+
+ url: str = attr.ib(repr=True)
+ """The WSS URL that can be used for connecting to the gateway."""
+
+ shard_count: int = attr.ib(repr=True)
+ """The recommended number of shards to use when connecting to the gateway."""
+
+ session_start_limit: SessionStartLimit = attr.ib(repr=True)
+ """Information about the bot's current session start limit."""
diff --git a/hikari/models/guilds.py b/hikari/models/guilds.py
new file mode 100644
index 0000000000..8b2a260d2d
--- /dev/null
+++ b/hikari/models/guilds.py
@@ -0,0 +1,1284 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Application and entities that are used to describe guilds on Discord."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "Guild",
+ "RESTGuild",
+ "GatewayGuild",
+ "GuildWidget",
+ "Role",
+ "GuildFeature",
+ "GuildFeatureish",
+ "GuildSystemChannelFlag",
+ "GuildMessageNotificationsLevel",
+ "GuildExplicitContentFilterLevel",
+ "GuildMFALevel",
+ "GuildVerificationLevel",
+ "GuildPremiumTier",
+ "GuildPreview",
+ "Member",
+ "Integration",
+ "GuildMemberBan",
+ "IntegrationAccount",
+ "IntegrationExpireBehaviour",
+ "PartialGuild",
+ "PartialIntegration",
+ "PartialRole",
+ "UnavailableGuild",
+]
+
+import abc
+import enum
+import typing
+
+import attr
+
+from hikari.models import users
+from hikari.utilities import attr_extensions
+from hikari.utilities import constants
+from hikari.utilities import files
+from hikari.utilities import flag
+from hikari.utilities import routes
+from hikari.utilities import snowflake
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+ from hikari import traits
+ from hikari.models import channels as channels_
+ from hikari.models import colors
+ from hikari.models import colours
+ from hikari.models import emojis as emojis_
+ from hikari.models import permissions as permissions_
+ from hikari.models import presences as presences_
+ from hikari.models import voices as voices_
+ from hikari.utilities import undefined
+
+
+@enum.unique
+@typing.final
+class GuildExplicitContentFilterLevel(enum.IntEnum):
+ """Represents the explicit content filter setting for a guild."""
+
+ DISABLED = 0
+ """No explicit content filter."""
+
+ MEMBERS_WITHOUT_ROLES = 1
+ """Filter posts from anyone without a role."""
+
+ ALL_MEMBERS = 2
+ """Filter all posts."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@enum.unique
+@typing.final
+class GuildFeature(str, enum.Enum):
+ """Features that a guild can provide."""
+
+ ANIMATED_ICON = "ANIMATED_ICON"
+ """Guild has access to set an animated guild icon."""
+
+ BANNER = "BANNER"
+ """Guild has access to set a guild banner image."""
+
+ COMMERCE = "COMMERCE"
+ """Guild has access to use commerce features (i.e. create store channels)."""
+
+ COMMUNITY = "COMMUNITY"
+ """Guild has community features enabled."""
+
+ DISCOVERABLE = "DISCOVERABLE"
+ """Guild is able to be discovered in the directory.
+
+ This also implies the guild can be viewed without joining.
+ """
+
+ FEATURABLE = "FEATURABLE"
+ """Guild is able to be featured in the directory."""
+
+ INVITE_SPLASH = "INVITE_SPLASH"
+ """Guild has access to set an invite splash background."""
+
+ MORE_EMOJI = "MORE_EMOJI"
+ """More emojis can be hosted in this guild than normal."""
+
+ NEWS = "NEWS"
+ """Guild has access to create news channels."""
+
+ PARTNERED = "PARTNERED"
+ """Guild is partnered."""
+
+ PUBLIC = "PUBLIC"
+ """Guild is public, go figure."""
+
+ PUBLIC_DISABLED = "PUBLIC_DISABLED"
+ """Guild cannot be public. Who would have guessed?"""
+
+ VANITY_URL = "VANITY_URL"
+ """Guild has access to set a vanity URL."""
+
+ VERIFIED = "VERIFIED"
+ """Guild is verified."""
+
+ VIP_REGIONS = "VIP_REGIONS"
+ """Guild has access to set 384kbps bitrate in voice.
+
+ Previously gave access to VIP voice servers.
+ """
+
+ WELCOME_SCREEN_ENABLED = "WELCOME_SCREEN_ENABLED"
+ """Guild has enabled the welcome screen."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+GuildFeatureish = typing.Union[str, GuildFeature]
+"""Type hint for possible guild features.
+
+Generally these will be of type `GuildFeature`, but undocumented or new
+fields may just be `builtins.str` until they are documented and amended to the
+library.
+"""
+
+
+@enum.unique
+@typing.final
+class GuildMessageNotificationsLevel(enum.IntEnum):
+ """Represents the default notification level for new messages in a guild."""
+
+ ALL_MESSAGES = 0
+ """Notify users when any message is sent."""
+
+ ONLY_MENTIONS = 1
+ """Only notify users when they are @mentioned."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@enum.unique
+@typing.final
+class GuildMFALevel(enum.IntEnum):
+ """Represents the multi-factor authorization requirement for a guild."""
+
+ NONE = 0
+ """No MFA requirement."""
+
+ ELEVATED = 1
+ """MFA requirement."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@enum.unique
+@typing.final
+class GuildPremiumTier(enum.IntEnum):
+ """Tier for Discord Nitro boosting in a guild."""
+
+ NONE = 0
+ """No Nitro boost level."""
+
+ TIER_1 = 1
+ """Level 1 Nitro boost."""
+
+ TIER_2 = 2
+ """Level 2 Nitro boost."""
+
+ TIER_3 = 3
+ """Level 3 Nitro boost."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@enum.unique
+@typing.final
+class GuildSystemChannelFlag(flag.Flag):
+ """Defines which features are suppressed in the system channel."""
+
+ NONE = 0
+ """Nothing is suppressed."""
+
+ SUPPRESS_USER_JOIN = 1 << 0
+ """Display a message about new users joining."""
+
+ SUPPRESS_PREMIUM_SUBSCRIPTION = 1 << 1
+ """Display a message when the guild is Nitro boosted."""
+
+
+@enum.unique
+@typing.final
+class GuildVerificationLevel(enum.IntEnum):
+ """Represents the level of verification of a guild."""
+
+ NONE = 0
+ """Unrestricted."""
+
+ LOW = 1
+ """Must have a verified email on their account."""
+
+ MEDIUM = 2
+ """Must have been registered on Discord for more than 5 minutes."""
+
+ HIGH = 3
+ """Must also be a member of the guild for longer than 10 minutes."""
+
+ VERY_HIGH = 4
+ """Must have a verified phone number."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class GuildWidget:
+ """Represents a guild widget."""
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ channel_id: typing.Optional[snowflake.Snowflake] = attr.ib(repr=True)
+ """The ID of the channel the invite for this embed targets, if enabled."""
+
+ is_enabled: bool = attr.ib(repr=True)
+ """Whether this embed is enabled."""
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Member(users.User):
+ """Used to represent a guild bound member."""
+
+ guild_id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of the guild this member belongs to."""
+
+ # This is technically optional, since UPDATE MEMBER and MESSAGE CREATE
+ # events do not inject the user into the member payload, but specify it
+ # separately. However, to get around this inconsistency, we force the
+ # entity factory to always provide the user object in these cases, so we
+ # can assume this is always set, and thus we are always able to get info
+ # such as the ID of the user this member represents.
+ # TODO: make member generic on this field (e.g. Member[PartialUser], Member[UserImpl], Member[OwnUser], etc)?
+ user: users.User = attr.ib(eq=True, hash=True, repr=True)
+ """This member's corresponding user object."""
+
+ nickname: undefined.UndefinedNoneOr[str] = attr.ib(
+ eq=False, hash=False, repr=True,
+ )
+ """This member's nickname.
+
+ This will be `builtins.None` if not set.
+
+ On member update events, this may not be included at all.
+ In this case, this will be undefined.
+ """
+
+ role_ids: typing.Sequence[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """A sequence of the IDs of the member's current roles."""
+
+ joined_at: datetime.datetime = attr.ib(eq=False, hash=False, repr=True)
+ """The datetime of when this member joined the guild they belong to."""
+
+ premium_since: undefined.UndefinedNoneOr[datetime.datetime] = attr.ib(eq=False, hash=False, repr=False)
+ """The datetime of when this member started "boosting" this guild.
+
+ This will be `builtins.None` if they aren't boosting and
+ `hikari.utilities.undefined.UndefinedType` if their boosting status is
+ unknown.
+ """
+
+ is_deaf: undefined.UndefinedOr[bool] = attr.ib(eq=False, hash=False, repr=False)
+ """`builtins.True` if this member is deafened in the current voice channel.
+
+ This will be `hikari.utilities.undefined.UndefinedType if it's state is
+ unknown.
+ """
+
+ is_mute: undefined.UndefinedOr[bool] = attr.ib(eq=False, hash=False, repr=False)
+ """`builtins.True` if this member is muted in the current voice channel.
+
+ This will be `hikari.utilities.undefined.UndefinedType if it's state is unknown.
+ """
+
+ @property
+ def app(self) -> traits.RESTAware:
+ """Return the app that is bound to the user object."""
+ return self.user.app
+
+ @property
+ def id(self) -> snowflake.Snowflake:
+ return self.user.id
+
+ @id.setter
+ def id(self, value: snowflake.Snowflake) -> None:
+ raise TypeError("Cannot mutate the ID of a member")
+
+ @property
+ def username(self) -> str:
+ return self.user.username
+
+ @property
+ def discriminator(self) -> str:
+ return self.user.discriminator
+
+ @property
+ def avatar_hash(self) -> typing.Optional[str]:
+ return self.user.avatar_hash
+
+ @property
+ def is_bot(self) -> bool:
+ return self.user.is_bot
+
+ @property
+ def is_system(self) -> bool:
+ return self.user.is_system
+
+ @property
+ def flags(self) -> users.UserFlag:
+ return self.user.flags
+
+ @property
+ def avatar(self) -> files.URL:
+ return self.user.avatar
+
+ # noinspection PyShadowingBuiltins
+ def format_avatar(self, *, format: typing.Optional[str] = None, size: int = 4096) -> typing.Optional[files.URL]:
+ return self.user.format_avatar(format=format, size=size)
+
+ @property
+ def default_avatar(self) -> files.URL:
+ return self.user.default_avatar
+
+ @property
+ def display_name(self) -> str:
+ """Return the member's display name.
+
+ If the member has a nickname, this will return that nickname.
+ Otherwise, it will return the username instead.
+
+ Returns
+ -------
+ builtins.str
+ The member display name.
+
+ See Also
+ --------
+ Nickname: `Member.nickname`
+ Username: `Member.username`
+ """
+ return self.nickname if isinstance(self.nickname, str) else self.username
+
+ @property
+ def mention(self) -> str:
+ """Return a raw mention string for the given member.
+
+ If the member has a known nickname, we always return
+ a bang ("`!`") before the ID part of the mention string. This
+ mimics the behaviour Discord clients tend to provide.
+
+ Example
+ -------
+
+ ```py
+ >>> some_member_without_nickname.mention
+ '<@123456789123456789>'
+ >>> some_member_with_nickname.mention
+ '<@!123456789123456789>'
+ ```
+
+ Returns
+ -------
+ builtins.str
+ The mention string to use.
+ """
+ return f"<@!{self.id}>" if self.nickname is not None else self.user.mention
+
+ def __str__(self) -> str:
+ return str(self.user)
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class PartialRole(snowflake.Unique):
+ """Represents a partial guild bound Role object."""
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ name: str = attr.ib(eq=False, hash=False, repr=True)
+ """The role's name."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Role(PartialRole):
+ """Represents a guild bound Role object."""
+
+ color: colors.Color = attr.ib(eq=False, hash=False, repr=True)
+ """The colour of this role.
+
+ This will be applied to a member's name in chat if it's their top coloured role.
+ """
+
+ guild_id: snowflake.Snowflake = attr.ib(eq=False, hash=False, repr=True)
+ """The ID of the guild this role belongs to"""
+
+ is_hoisted: bool = attr.ib(eq=False, hash=False, repr=True)
+ """Whether this role is hoisting the members it's attached to in the member list.
+
+ members will be hoisted under their highest role where this is set to `builtins.True`.
+ """
+
+ position: int = attr.ib(eq=False, hash=False, repr=True)
+ """The position of this role in the role hierarchy.
+
+ This will start at `0` for the lowest role (@everyone)
+ and increase as you go up the hierarchy.
+ """
+
+ permissions: permissions_.Permissions = attr.ib(eq=False, hash=False, repr=False)
+ """The guild wide permissions this role gives to the members it's attached to,
+
+ This may be overridden by channel overwrites.
+ """
+
+ is_managed: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether this role is managed by an integration."""
+
+ is_mentionable: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether this role can be mentioned by all regardless of permissions."""
+
+ @property
+ def colour(self) -> colours.Colour:
+ """Alias for the `color` field."""
+ return self.color
+
+
+@enum.unique
+@typing.final
+class IntegrationExpireBehaviour(enum.IntEnum):
+ """Behavior for expiring integration subscribers."""
+
+ REMOVE_ROLE = 0
+ """Remove the role."""
+
+ KICK = 1
+ """Kick the subscriber."""
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class IntegrationAccount:
+ """An account that's linked to an integration."""
+
+ id: str = attr.ib(eq=True, hash=True, repr=True)
+ """The string ID of this (likely) third party account."""
+
+ name: str = attr.ib(eq=False, hash=False, repr=True)
+ """The name of this account."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class PartialIntegration(snowflake.Unique):
+ """A partial representation of an integration, found in audit logs."""
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ name: str = attr.ib(eq=False, hash=False, repr=True)
+ """The name of this integration."""
+
+ type: str = attr.ib(eq=False, hash=False, repr=True)
+ """The type of this integration."""
+
+ account: IntegrationAccount = attr.ib(eq=False, hash=False, repr=False)
+ """The account connected to this integration."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Integration(PartialIntegration):
+ """Represents a guild integration object."""
+
+ is_enabled: bool = attr.ib(eq=False, hash=False, repr=True)
+ """Whether this integration is enabled."""
+
+ is_syncing: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether this integration is syncing subscribers/emojis."""
+
+ role_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The ID of the managed role used for this integration's subscribers."""
+
+ is_emojis_enabled: typing.Optional[bool] = attr.ib(eq=False, hash=False, repr=False)
+ """Whether users under this integration are allowed to use it's custom emojis."""
+
+ expire_behavior: IntegrationExpireBehaviour = attr.ib(eq=False, hash=False, repr=False)
+ """How members should be treated after their connected subscription expires.
+
+ This will not be enacted until after `GuildIntegration.expire_grace_period`
+ passes.
+ """
+
+ expire_grace_period: datetime.timedelta = attr.ib(eq=False, hash=False, repr=False)
+ """How many days users with expired subscriptions are given until
+ `GuildIntegration.expire_behavior` is enacted out on them
+ """
+
+ user: users.User = attr.ib(eq=False, hash=False, repr=False)
+ """The user this integration belongs to."""
+
+ last_synced_at: typing.Optional[datetime.datetime] = attr.ib(eq=False, hash=False, repr=False)
+ """The datetime of when this integration's subscribers were last synced."""
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class GuildMemberBan:
+ """Used to represent guild bans."""
+
+ reason: typing.Optional[str] = attr.ib(repr=True)
+ """The reason for this ban, will be `builtins.None` if no reason was given."""
+
+ user: users.User = attr.ib(repr=True)
+ """The object of the user this ban targets."""
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+@typing.final
+class UnavailableGuild(snowflake.Unique):
+ """An unavailable guild object, received during gateway events such as READY.
+
+ An unavailable guild cannot be interacted with, and most information may
+ be outdated if that is the case.
+ """
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ # Ignore docstring not starting in an imperative mood
+ @property
+ def is_unavailable(self) -> bool: # noqa: D401
+ """`builtins.True` if this guild is unavailable, else `builtins.False`.
+
+ This value is always `builtins.True`, and is only provided for consistency.
+ """
+ return True
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class PartialGuild(snowflake.Unique):
+ """Base object for any partial guild objects."""
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ name: str = attr.ib(eq=False, hash=False, repr=True)
+ """The name of the guild."""
+
+ icon_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash for the guild icon, if there is one."""
+
+ features: typing.Sequence[GuildFeatureish] = attr.ib(eq=False, hash=False, repr=False)
+ """A list of the features in this guild."""
+
+ def __str__(self) -> str:
+ return self.name
+
+ @property
+ def shard_id(self) -> typing.Optional[int]:
+ """Return the ID of the shard this guild is served by.
+
+ This may return `None` if the application does not have a gateway
+ connection.
+ """
+ try:
+ # This is only sensible if there is a shard.
+ return (self.id >> 22) % typing.cast(int, getattr(self.app, "shard_count"))
+ except (TypeError, AttributeError, NameError):
+ return None
+
+ @property
+ def icon_url(self) -> typing.Optional[files.URL]:
+ """Icon for the guild, if set; otherwise `builtins.None`."""
+ return self.format_icon()
+
+ def format_icon(self, *, format_: typing.Optional[str] = None, size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's icon, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str or builtins.None
+ The format to use for this URL, defaults to `png` or `gif`.
+ Supports `png`, `jpeg`, `jpg`, `webp` and `gif` (when
+ animated).
+
+ If `builtins.None`, then the correct default format is determined
+ based on whether the icon is animated or not.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The URL to the resource, or `builtins.None` if no icon is set.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.icon_hash is None:
+ return None
+
+ if format_ is None:
+ if self.icon_hash.startswith("a_"):
+ format_ = "gif"
+ else:
+ format_ = "png"
+
+ return routes.CDN_GUILD_ICON.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.icon_hash, size=size, file_format=format_,
+ )
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class GuildPreview(PartialGuild):
+ """A preview of a guild with the `GuildFeature.PUBLIC` feature."""
+
+ splash_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash of the splash for the guild, if there is one."""
+
+ discovery_splash_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash of the discovery splash for the guild, if there is one."""
+
+ emojis: typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji] = attr.ib(eq=False, hash=False, repr=False)
+ """The mapping of IDs to the emojis this guild provides."""
+
+ approximate_presence_count: int = attr.ib(eq=False, hash=False, repr=True)
+ """The approximate amount of include_presences in guild."""
+
+ approximate_member_count: int = attr.ib(eq=False, hash=False, repr=True)
+ """The approximate amount of members in this guild."""
+
+ description: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The guild's description, if set."""
+
+ @property
+ def splash_url(self) -> typing.Optional[files.URL]:
+ """Splash for the guild, if set."""
+ return self.format_splash()
+
+ def format_splash(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's splash image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The URL to the splash, or `builtins.None` if not set.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.splash_hash is None:
+ return None
+
+ return routes.CDN_GUILD_SPLASH.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.splash_hash, size=size, file_format=format_,
+ )
+
+ @property
+ def discovery_splash(self) -> typing.Optional[files.URL]:
+ """Discovery splash for the guild, if set."""
+ return self.format_discovery_splash()
+
+ def format_discovery_splash(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's discovery splash image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The string URL.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.discovery_splash_hash is None:
+ return None
+
+ return routes.CDN_GUILD_DISCOVERY_SPLASH.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.discovery_splash_hash, size=size, file_format=format_,
+ )
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Guild(PartialGuild, abc.ABC):
+ """A representation of a guild on Discord."""
+
+ splash_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash of the splash for the guild, if there is one."""
+
+ discovery_splash_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash of the discovery splash for the guild, if there is one."""
+
+ owner_id: snowflake.Snowflake = attr.ib(eq=False, hash=False, repr=True)
+ """The ID of the owner of this guild."""
+
+ region: str = attr.ib(eq=False, hash=False, repr=False)
+ """The voice region for the guild."""
+
+ afk_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The ID for the channel that AFK voice users get sent to.
+
+ If `builtins.None`, then no AFK channel is set up for this guild.
+ """
+
+ afk_timeout: datetime.timedelta = attr.ib(eq=False, hash=False, repr=False)
+ """Timeout for activity before a member is classed as AFK.
+
+ How long a voice user has to be AFK for before they are classed as being
+ AFK and are moved to the AFK channel (`Guild.afk_channel_id`).
+ """
+
+ verification_level: GuildVerificationLevel = attr.ib(eq=False, hash=False, repr=False)
+ """The verification level required for a user to participate in this guild."""
+
+ default_message_notifications: GuildMessageNotificationsLevel = attr.ib(eq=False, hash=False, repr=False)
+ """The default setting for message notifications in this guild."""
+
+ explicit_content_filter: GuildExplicitContentFilterLevel = attr.ib(eq=False, hash=False, repr=False)
+ """The setting for the explicit content filter in this guild."""
+
+ mfa_level: GuildMFALevel = attr.ib(eq=False, hash=False, repr=False)
+ """The required MFA level for users wishing to participate in this guild."""
+
+ application_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The ID of the application that created this guild.
+
+ This will always be `builtins.None` for guilds that weren't created by a bot.
+ """
+
+ is_widget_enabled: typing.Optional[bool] = attr.ib(eq=False, hash=False, repr=False)
+ """Describes whether the guild widget is enabled or not.
+
+ If this information is not present, this will be `builtins.None`.
+ """
+
+ widget_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The channel ID that the widget's generated invite will send the user to.
+
+ If this information is unavailable or this is not enabled for the guild then
+ this will be `builtins.None`.
+ """
+
+ system_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The ID of the system channel or `builtins.None` if it is not enabled.
+
+ Welcome messages and Nitro boost messages may be sent to this channel.
+ """
+
+ system_channel_flags: GuildSystemChannelFlag = attr.ib(eq=False, hash=False, repr=False)
+ """Flags for the guild system channel to describe which notifications are suppressed."""
+
+ rules_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The ID of the channel where guilds with the `GuildFeature.PUBLIC`
+ `features` display rules and guidelines.
+
+ If the `GuildFeature.PUBLIC` feature is not defined, then this is `builtins.None`.
+ """
+
+ max_presences: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The maximum number of include_presences for the guild.
+
+ If this is `builtins.None`, then the default value is used (currently 25000).
+ """
+
+ max_members: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The maximum number of members allowed in this guild.
+
+ This information may not be present, in which case, it will be `builtins.None`.
+ """
+
+ max_video_channel_users: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The maximum number of users allowed in a video channel together.
+
+ This information may not be present, in which case, it will be `builtins.None`.
+ """
+
+ vanity_url_code: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The vanity URL code for the guild's vanity URL.
+
+ This is only present if `GuildFeature.VANITY_URL` is in `Guild.features` for
+ this guild. If not, this will always be `builtins.None`.
+ """
+
+ description: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The guild's description.
+
+ This is only present if certain `GuildFeature`'s are set in
+ `Guild.features` for this guild. Otherwise, this will always be `builtins.None`.
+ """
+
+ banner_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash for the guild's banner.
+
+ This is only present if the guild has `GuildFeature.BANNER` in
+ `Guild.features` for this guild. For all other purposes, it is `builtins.None`.
+ """
+
+ premium_tier: GuildPremiumTier = attr.ib(eq=False, hash=False, repr=False)
+ """The premium tier for this guild."""
+
+ premium_subscription_count: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The number of nitro boosts that the server currently has.
+
+ This information may not be present, in which case, it will be `builtins.None`.
+ """
+
+ preferred_locale: str = attr.ib(eq=False, hash=False, repr=False)
+ """The preferred locale to use for this guild.
+
+ This can only be change if `GuildFeature.PUBLIC` is in `Guild.features`
+ for this guild and will otherwise default to `en-US`.
+ """
+
+ public_updates_channel_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=False)
+ """The channel ID of the channel where admins and moderators receive notices
+ from Discord.
+
+ This is only present if `GuildFeature.PUBLIC` is in `Guild.features` for
+ this guild. For all other purposes, it should be considered to be `builtins.None`.
+ """
+
+ @property
+ @abc.abstractmethod
+ def roles(self) -> typing.Mapping[snowflake.Snowflake, Role]:
+ """Return the roles in this guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, Role]
+ A mapping of role IDs to the objects of roles in this guild.
+ """
+
+ @property
+ @abc.abstractmethod
+ def emojis(self) -> typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji]:
+ """Return the emojis in this guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.emojis.KnownCustomEmoji]
+ A mapping of emoji IDs to the objects of emojis in this guild.
+ """
+
+ @abc.abstractmethod
+ def get_role(self, role: snowflake.SnowflakeishOr[Role]) -> typing.Optional[Role]:
+ """Get a role from the cache by it's ID."""
+
+ @abc.abstractmethod
+ def get_emoji(
+ self, emoji: snowflake.SnowflakeishOr[emojis_.CustomEmoji]
+ ) -> typing.Optional[emojis_.KnownCustomEmoji]:
+ """Get an emoji from the cache by it's ID."""
+
+ @property
+ def splash_url(self) -> typing.Optional[files.URL]:
+ """Splash for the guild, if set."""
+ return self.format_splash()
+
+ def format_splash(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's splash image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The URL to the splash, or `builtins.None` if not set.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.splash_hash is None:
+ return None
+
+ return routes.CDN_GUILD_SPLASH.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.splash_hash, size=size, file_format=format_,
+ )
+
+ @property
+ def discovery_splash(self) -> typing.Optional[files.URL]:
+ """Discovery splash for the guild, if set."""
+ return self.format_discovery_splash()
+
+ def format_discovery_splash(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's discovery splash image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The string URL.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.discovery_splash_hash is None:
+ return None
+
+ return routes.CDN_GUILD_DISCOVERY_SPLASH.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.discovery_splash_hash, size=size, file_format=format_,
+ )
+
+ @property
+ def banner(self) -> typing.Optional[files.URL]:
+ """Banner for the guild, if set."""
+ return self.format_banner()
+
+ def format_banner(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's banner image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The URL of the banner, or `builtins.None` if no banner is set.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.banner_hash is None:
+ return None
+
+ return routes.CDN_GUILD_BANNER.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.banner_hash, size=size, file_format=format_,
+ )
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class RESTGuild(Guild):
+ """Guild specialization that is sent via the REST API only."""
+
+ _roles: typing.Mapping[snowflake.Snowflake, Role] = attr.ib(eq=False, hash=False, repr=False)
+ """The roles in this guild, represented as a mapping of role ID to role object."""
+
+ _emojis: typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji] = attr.ib(eq=False, hash=False, repr=False)
+ """A mapping of emoji IDs to the objects of the emojis this guild provides."""
+
+ approximate_member_count: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The approximate number of members in the guild.
+
+ This information will be provided by HTTP API calls fetching the guilds that
+ a bot account is in. For all other purposes, this should be expected to
+ remain `builtins.None`.
+ """
+
+ approximate_active_member_count: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The approximate number of members in the guild that are not offline.
+
+ This information will be provided by HTTP API calls fetching the guilds that
+ a bot account is in. For all other purposes, this should be expected to
+ remain `builtins.None`.
+ """
+
+ @property
+ def roles(self) -> typing.Mapping[snowflake.Snowflake, Role]:
+ # <>.
+ return self._roles
+
+ @property
+ def emojis(self) -> typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji]:
+ # <>.
+ return self._emojis
+
+ def get_role(self, role: snowflake.SnowflakeishOr[Role]) -> typing.Optional[Role]:
+ # <>.
+ return self._roles.get(snowflake.Snowflake(role))
+
+ def get_emoji(
+ self, emoji: snowflake.SnowflakeishOr[emojis_.CustomEmoji]
+ ) -> typing.Optional[emojis_.KnownCustomEmoji]:
+ # <>.
+ return self._emojis.get(snowflake.Snowflake(emoji))
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class GatewayGuild(Guild):
+ """Guild specialization that is sent via the gateway only."""
+
+ my_permissions: typing.Optional[permissions_.Permissions] = attr.ib(eq=False, hash=False, repr=False)
+ """The guild-level permissions that apply to the bot user.
+
+ This will not take into account permission overwrites or implied
+ permissions (for example, `ADMINISTRATOR` implies all other permissions).
+ """
+
+ joined_at: typing.Optional[datetime.datetime] = attr.ib(eq=False, hash=False, repr=False)
+ """The date and time that the bot user joined this guild.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `builtins.None`.
+ """
+
+ is_large: typing.Optional[bool] = attr.ib(eq=False, hash=False, repr=False)
+ """Whether the guild is considered to be large or not.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `builtins.None`.
+
+ The implications of a large guild are that presence information will not be
+ sent about members who are offline or invisible.
+ """
+
+ member_count: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The number of members in this guild.
+
+ This information is only available if the guild was sent via a `GUILD_CREATE`
+ event. If the guild is received from any other place, this will always be
+ `builtins.None`.
+ """
+
+ @property
+ def roles(self) -> typing.Mapping[snowflake.Snowflake, Role]:
+ # <>.
+ return self.app.cache.get_roles_view_for_guild(self.id)
+
+ @property
+ def emojis(self) -> typing.Mapping[snowflake.Snowflake, emojis_.KnownCustomEmoji]:
+ # <>.
+ return self.app.cache.get_emojis_view_for_guild(self.id)
+
+ @property
+ def members(self) -> typing.Mapping[snowflake.Snowflake, Member]:
+ """Get the members cached for the guild.
+
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, Member]
+ A mapping of user IDs to objects of the members cached for the guild.
+ """
+ return self.app.cache.get_members_view_for_guild(self.id)
+
+ @property
+ def channels(self) -> typing.Mapping[snowflake.Snowflake, channels_.GuildChannel]:
+ """Get the channels cached for the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.channels.GuildChannel]
+ A mapping of channel IDs to objects of the channels cached for the
+ guild.
+ """
+ return self.app.cache.get_guild_channels_view_for_guild(self.id)
+
+ @property
+ def presences(self) -> typing.Mapping[snowflake.Snowflake, presences_.MemberPresence]:
+ """Get the include_presences cached for the guild.
+
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.include_presences.MemberPresence]
+ A mapping of user IDs to objects of the include_presences cached for the
+ guild.
+ """
+ return self.app.cache.get_presences_view_for_guild(self.id)
+
+ @property
+ def voice_states(self) -> typing.Mapping[snowflake.Snowflake, voices_.VoiceState]:
+ """Get the voice states cached for the guild.
+
+ Returns
+ -------
+ typing.Mapping[hikari.utilities.snowflake.Snowflake, hikari.models.voices.VoiceState]
+ A mapping of user IDs to objects of the voice states cached for the
+ guild.
+ """
+ return self.app.cache.get_voice_states_view_for_guild(self.id)
+
+ def get_role(self, role: snowflake.SnowflakeishOr[Role]) -> typing.Optional[Role]:
+ """Get a cached role that belongs to the guild by it's ID or object.
+
+ Parameters
+ ----------
+ role : hikari.utilities.snowflake.SnowflakeishOr[Role]
+ The object or ID of the role to get for this guild from the cache.
+
+ Returns
+ -------
+ Role or builtins.None
+ The object of the role found in cache, else `builtins.None`.
+ """
+ return self.app.cache.get_role(snowflake.Snowflake(role))
+
+ def get_emoji(
+ self, emoji: snowflake.SnowflakeishOr[emojis_.CustomEmoji]
+ ) -> typing.Optional[emojis_.KnownCustomEmoji]:
+ """Get a cached role that belongs to the guild by it's ID or object.
+
+ Parameters
+ ----------
+ emoji : hikari.utilities.snowflake.SnowflakeishOr[hikari.models.emojis.CustomEmoji]
+ The object or ID of the emoji to get from the cache.
+
+ Returns
+ -------
+ hikari.models.emojis.KnownCustomEmoji or builtins.None
+ The object of the custom emoji if found in cache, else
+ `builtins.None`.
+ """
+ return self.app.cache.get_emoji(snowflake.Snowflake(emoji))
+
+ def get_channel(
+ self, channel: snowflake.SnowflakeishOr[channels_.GuildChannel],
+ ) -> typing.Optional[channels_.GuildChannel]:
+ """Get a cached channel that belongs to the guild by it's ID or object.
+
+ Parameters
+ ----------
+ channel : hikari.utilities.snowflake.SnowflakeishOr[hikari.models.channels.GuildChannel]
+ The object or ID of the guild channel to get from the cache.
+
+ Returns
+ -------
+ hikari.models.channels.GuildChannel or builtins.None
+ The object of the guild channel found in cache or `builtins.None.
+ """
+ return self.app.cache.get_guild_channel(snowflake.Snowflake(channel))
+
+ def get_member(self, user: snowflake.SnowflakeishOr[users.User]) -> typing.Optional[Member]:
+ """Get a cached member that belongs to the guild by it's user ID or object.
+
+ Parameters
+ ----------
+ user : hikari.utilities.snowflake.SnowflakkeisOr[hikari.models.users.User]
+ The object or ID of the user to get the cached member for.
+
+ Returns
+ -------
+ Member or builtins.None
+ The cached member object if found, else `builtins.None`.
+ """
+ return self.app.cache.get_member(self.id, snowflake.Snowflake(user))
+
+ def get_presence(self, user: snowflake.SnowflakeishOr[users.User]) -> typing.Optional[presences_.MemberPresence]:
+ """Get a cached presence that belongs to the guild by it's user ID or object.
+
+ Parameters
+ ----------
+ user : hikari.utilities.snowflake.SnowflakeishOr[hikari.models.users.User]
+ The object or ID of the user to get the cached presence for.
+
+ Returns
+ -------
+ hikari.models.include_presences.MemberPresence or builtins.None
+ The cached presence object if found, else `builtins.None`.
+ """
+ return self.app.cache.get_presence(self.id, snowflake.Snowflake(user))
+
+ def get_voice_state(self, user: snowflake.SnowflakeishOr[users.User]) -> typing.Optional[voices_.VoiceState]:
+ """Get a cached voice state that belongs to the guild by it's user.
+
+ Parameters
+ ----------
+ user : hikari.utilities.snowflake.SnowflakeishOr[hikari.models.users.User]
+ The object or ID of the user to get the cached voice state for.
+
+ Returns
+ -------
+ hikari.models.voice.VoiceState or builtins.None
+ The cached voice state object if found, else `builtins.None`.
+ """
+ return self.app.cache.get_voice_state(self.id, snowflake.Snowflake(user))
diff --git a/hikari/models/intents.py b/hikari/models/intents.py
new file mode 100644
index 0000000000..52af22d366
--- /dev/null
+++ b/hikari/models/intents.py
@@ -0,0 +1,370 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Shard intents for controlling which events the application receives."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["Intents"]
+
+# noinspection PyUnresolvedReferences
+import typing
+
+from hikari.utilities import flag
+
+
+@typing.final
+class Intents(flag.Flag):
+ """Represents an intent on the gateway.
+
+ This is a bitfield representation of all the categories of event
+ that you wish to receive.
+
+ Any events not in an intent category will be fired regardless of what
+ intents you provide.
+
+ !!! info
+ Discord now places limits on certain events you can receive without
+ whitelisting your bot first. On the `Bot` tab in the developer's portal
+ for your bot, you should now have the option to enable functionality
+ for receiving these events.
+
+ If you attempt to request an intent type that you have not whitelisted
+ your bot for, you will be disconnected on startup with a `4014` closure
+ code.
+
+ !!! warning
+ If you are using the V7 Gateway, you will be REQUIRED to provide some
+ form of intent value when you connect. Failure to do so may result in
+ immediate termination of the session server-side.
+
+ This enum is an `enum.IntFlag`, which means that you can use bitwise
+ operators to join and splice multiple intents into one value.
+
+ For example, if we wish to only refer to the `GUILDS` intent, then it is
+ simply a case of accessing it normally.
+
+ ```py
+ my_intents = Intents.GUILDS
+ ```
+
+ If we wanted to have several intents grouped together, we would use the
+ bitwise-or operator to combine them (`|`). This can be done in-place
+ with the `|=` operator if needed.
+
+ ```py
+ # One or two values that fit on one line.
+ my_intents = Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES
+
+ # Several intents together. You may find it useful to format these like
+ # so to keep your code readable.
+ my_intents = (
+ Intents.GUILDS |
+ Intents.GUILD_BANS |
+ Intents.GUILD_EMOJIS |
+ Intents.GUILD_INTEGRATIONS |
+ Intents.GUILD_MESSAGES |
+ Intents.PRIVATE_MESSAGES
+ )
+ ```
+
+ To check if an intent **is present** in a given intents bitfield, you can
+ use the bitwise-and operator (`&`) to check. This returns the "intersection"
+ or "crossover" between the left and right-hand side of the `&`. You can then
+ use the `==` operator to check that specific values are present. You can
+ check in-place with the `&=` operator if needed.
+
+ ```py
+ # Check if an intent is set:
+ if (my_intents & Intents.GUILD_MESSAGES) == Intents.GUILD_MESSAGES:
+ print("Guild messages are enabled")
+
+ # Checking if ALL in a combination are set:
+ expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
+ if (my_intents & expected_intents) == expected_intents:
+ print("Messages are enabled in guilds and private messages.")
+
+ # Checking if AT LEAST ONE in a combination is set:
+ expected_intents = (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
+ if my_intents & expected_intents:
+ print("Messages are enabled in guilds or private messages.")
+ ```
+
+ Removing one or more intents from a combination can be done with the
+ bitwise-xor (`^`) operator. The `^=` operator can do this in-place.
+
+ ```py
+ # Remove GUILD_MESSAGES
+ my_intents = my_intents ^ Intents.GUILD_MESSAGES
+ # or, simplifying:
+ my_intents ^= Intents.GUILD_MESSAGES
+
+ # Remove all messages events.
+ my_intents = my_intents ^ (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
+ # or, simplifying
+ my_intents ^= (Intents.GUILD_MESSAGES | Intents.PRIVATE_MESSAGES)
+ ```
+
+ What is and is not covered by intents?
+ --------------------------------------
+
+ The following unprivileged events require intents to be dispatched:
+
+ - `GUILD_CREATE`
+ - `GUILD_UPDATE`
+ - `GUILD_DELETE`
+ - `GUILD_ROLE_CREATE`
+ - `GUILD_ROLE_UPDATE`
+ - `GUILD_ROLE_DELETE`
+ - `GUILD_BAN_ADD`
+ - `GUILD_BAN_REMOVE`
+ - `GUILD_EMOJIS_UPDATE`
+ - `GUILD_INTEGRATIONS_UPDATE`
+ - `INVITE_CREATE`
+ - `INVITE_DELETE`
+ - `CHANNEL_CREATE`
+ - `CHANNEL_UPDATE`
+ - `CHANNEL_DELETE`
+ - `CHANNEL_PINS_UPDATE (guilds only)`
+ - `MESSAGE_CREATE`
+ - `MESSAGE_UPDATE`
+ - `MESSAGE_DELETE`
+ - `MESSAGE_BULK_DELETE`
+ - `MESSAGE_REACTION_ADD`
+ - `MESSAGE_REACTION_REMOVE`
+ - `MESSAGE_REACTION_REMOVE_ALL`
+ - `MESSAGE_REACTION_REMOVE_EMOJI`
+ - `TYPING_START`
+ - `VOICE_STATE_UPDATE`
+ - `WEBHOOKS_UPDATE`
+
+ The following privileged events require intents to be dispatched:
+
+ - `GUILD_MEMBER_ADD`
+ - `GUILD_MEMBER_UPDATE`
+ - `GUILD_MEMBER_REMOVE`
+ - `PRESENCE_UPDATE`
+
+ All events not listed above will be dispatched regardless of whether
+ intents are used or not.
+ """
+
+ NONE = 0
+ """Represents no intents."""
+
+ GUILDS = 1 << 0
+ """Subscribes to the following events:
+
+ * `GUILD_CREATE`
+ * `GUILD_UPDATE`
+ * `GUILD_DELETE`
+ * `GUILD_ROLE_CREATE`
+ * `GUILD_ROLE_UPDATE`
+ * `GUILD_ROLE_DELETE`
+ * `CHANNEL_CREATE`
+ * `CHANNEL_UPDATE`
+ * `CHANNEL_DELETE`
+ * `CHANNEL_PINS_UPDATE`
+ """
+
+ GUILD_MEMBERS = 1 << 1
+ """Subscribes to the following events:
+
+ * `GUILD_MEMBER_ADD`
+ * `GUILD_MEMBER_UPDATE`
+ * `GUILD_MEMBER_REMOVE`
+
+ !!! warning
+ This intent is privileged, and requires enabling/whitelisting to use.
+ """
+
+ GUILD_BANS = 1 << 2
+ """Subscribes to the following events:
+
+ * `GUILD_BAN_ADD`
+ * `GUILD_BAN_REMOVE`
+ """
+
+ GUILD_EMOJIS = 1 << 3
+ """Subscribes to the following events:
+
+ * `GUILD_EMOJIS_UPDATE`
+ """
+
+ GUILD_INTEGRATIONS = 1 << 4
+ """Subscribes to the following events:
+
+ * `GUILD_INTEGRATIONS_UPDATE`
+ """
+
+ GUILD_WEBHOOKS = 1 << 5
+ """Subscribes to the following events:
+
+ * `WEBHOOKS_UPDATE`
+ """
+
+ GUILD_INVITES = 1 << 6
+ """Subscribes to the following events:
+
+ * `INVITE_CREATE`
+ * `INVITE_DELETE`
+ """
+
+ GUILD_VOICE_STATES = 1 << 7
+ """Subscribes to the following events:
+
+ * `VOICE_STATE_UPDATE`
+ """
+
+ GUILD_PRESENCES = 1 << 8
+ """Subscribes to the following events:
+
+ * `PRESENCE_UPDATE`
+
+ !!! warning
+ This intent is privileged, and requires enabling/whitelisting to use."""
+
+ GUILD_MESSAGES = 1 << 9
+ """Subscribes to the following events:
+
+ * `MESSAGE_CREATE` (in guilds only)
+ * `MESSAGE_UPDATE` (in guilds only)
+ * `MESSAGE_DELETE` (in guilds only)
+ * `MESSAGE_BULK_DELETE` (in guilds only)
+ """
+
+ GUILD_MESSAGE_REACTIONS = 1 << 10
+ """Subscribes to the following events:
+
+ * `MESSAGE_REACTION_ADD` (in guilds only)
+ * `MESSAGE_REACTION_REMOVE` (in guilds only)
+ * `MESSAGE_REACTION_REMOVE_ALL` (in guilds only)
+ * `MESSAGE_REACTION_REMOVE_EMOJI` (in guilds only)
+ """
+
+ GUILD_MESSAGE_TYPING = 1 << 11
+ """Subscribes to the following events:
+
+ * `TYPING_START` (in guilds only)
+ """
+
+ PRIVATE_MESSAGES = 1 << 12
+ """Subscribes to the following events:
+
+ * `CHANNEL_CREATE` (in private message channels only)
+ * `MESSAGE_CREATE` (in private message channels only)
+ * `MESSAGE_UPDATE` (in private message channels only)
+ * `MESSAGE_DELETE` (in private message channels only)
+ """
+
+ PRIVATE_MESSAGE_REACTIONS = 1 << 13
+ """Subscribes to the following events:
+
+ * `MESSAGE_REACTION_ADD` (in private message channels only)
+ * `MESSAGE_REACTION_REMOVE` (in private message channels only)
+ * `MESSAGE_REACTION_REMOVE_ALL` (in private message channels only)
+ * `MESSAGE_REACTION_REMOVE_EMOJI` (in private message channels only)
+ """
+
+ PRIVATE_MESSAGE_TYPING = 1 << 14
+ """Subscribes to the following events
+
+ * `TYPING_START` (in private message channels only)
+ """
+
+ # Annoyingly, enums hide classmethods and staticmethods from __dir__ in
+ # EnumMeta which means if I make methods to generate these, then stuff
+ # will not be documented by pdoc. Alas, my dream of being smart with
+ # operator.or_ and functools.reduce has been destroyed.
+
+ ALL_GUILDS_UNPRIVILEGED = (
+ GUILDS
+ | GUILD_BANS
+ | GUILD_EMOJIS
+ | GUILD_INTEGRATIONS
+ | GUILD_WEBHOOKS
+ | GUILD_INVITES
+ | GUILD_VOICE_STATES
+ | GUILD_MESSAGES
+ | GUILD_MESSAGE_REACTIONS
+ | GUILD_MESSAGE_TYPING
+ )
+ """All unprivileged guild-related intents."""
+
+ ALL_GUILDS_PRIVILEGED = GUILD_MEMBERS | GUILD_PRESENCES
+ """All privileged guild intents.
+
+ !!! warning
+ This set of intent is privileged, and requires enabling/whitelisting to
+ use.
+ """
+
+ ALL_GUILDS = ALL_GUILDS_UNPRIVILEGED | ALL_GUILDS_PRIVILEGED
+ """All unprivileged guild intents and all privileged guild intents.
+
+ This combines `Intents.ALL_GUILDS_UNPRIVILEGED` and
+ `Intents.ALL_GUILDS_PRIVILEGED`.
+
+ !!! warning
+ This set of intent is privileged, and requires enabling/whitelisting to
+ use.
+ """
+
+ ALL_PRIVATE = PRIVATE_MESSAGES | PRIVATE_MESSAGE_TYPING | PRIVATE_MESSAGE_REACTIONS
+ """All private message intents."""
+
+ ALL_MESSAGES = PRIVATE_MESSAGES | GUILD_MESSAGES
+ """All message intents."""
+
+ ALL_MESSAGE_REACTIONS = PRIVATE_MESSAGE_REACTIONS | GUILD_MESSAGE_REACTIONS
+ """All message reaction intents."""
+
+ ALL_MESSAGE_TYPING = PRIVATE_MESSAGE_TYPING | GUILD_MESSAGE_TYPING
+ """All typing indicator intents."""
+
+ ALL_UNPRIVILEGED = ALL_GUILDS_UNPRIVILEGED | ALL_PRIVATE
+ """All unprivileged intents."""
+
+ ALL_PRIVILEGED = ALL_GUILDS_PRIVILEGED
+ """All privileged intents.
+
+ !!! warning
+ This set of intent is privileged, and requires enabling/whitelisting to
+ use.
+ """
+
+ ALL = ALL_UNPRIVILEGED | ALL_PRIVILEGED
+ """All unprivileged and privileged intents.
+
+ !!! warning
+ This set of intent is privileged, and requires enabling/whitelisting to
+ use.
+ """
+
+ @property
+ def is_privileged(self) -> bool:
+ """Determine whether the intent requires elevated privileges.
+
+ If this is `builtins.True`, you will be required to opt-in to using
+ this intent on the Discord Developer Portal before you can utilise it
+ in your application.
+ """
+ return bool(self & (self.GUILD_MEMBERS | self.GUILD_PRESENCES))
diff --git a/hikari/models/invites.py b/hikari/models/invites.py
new file mode 100644
index 0000000000..c4cb13566e
--- /dev/null
+++ b/hikari/models/invites.py
@@ -0,0 +1,312 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Application and entities that are used to describe invites on Discord."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "TargetUserType",
+ "VanityURL",
+ "InviteGuild",
+ "Invite",
+ "InviteWithMetadata",
+ "Inviteish",
+]
+
+import abc
+import enum
+import typing
+
+import attr
+
+from hikari.models import guilds
+from hikari.utilities import attr_extensions
+from hikari.utilities import constants
+from hikari.utilities import files
+from hikari.utilities import routes
+from hikari.utilities import snowflake
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+ from hikari import traits
+ from hikari.models import channels
+ from hikari.models import users
+
+
+@enum.unique
+@typing.final
+class TargetUserType(enum.IntEnum):
+ """The reason a invite targets a user."""
+
+ STREAM = 1
+ """This invite is targeting a "Go Live" stream."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+class InviteCode(abc.ABC):
+ """A representation of a guild/channel invite."""
+
+ __slots__: typing.Sequence[str] = ()
+
+ @property
+ @abc.abstractmethod
+ def code(self) -> str:
+ """Return the code for this invite.
+
+ Returns
+ -------
+ builtins.str
+ The invite code that can be appended to a URL.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class VanityURL(InviteCode):
+ """A special case invite object, that represents a guild's vanity url."""
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ code: str = attr.ib(eq=True, hash=True, repr=True)
+ """The code for this invite."""
+
+ uses: int = attr.ib(eq=False, hash=False, repr=True)
+ """The amount of times this invite has been used."""
+
+ def __str__(self) -> str:
+ return f"https://discord.gg/{self.code}"
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class InviteGuild(guilds.PartialGuild):
+ """Represents the partial data of a guild that is attached to invites."""
+
+ splash_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash of the splash for the guild, if there is one."""
+
+ banner_hash: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The hash for the guild's banner.
+
+ This is only present if `hikari.models.guilds.GuildFeature.BANNER` is in the
+ `features` for this guild. For all other purposes, it is `builtins.None`.
+ """
+
+ description: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=False)
+ """The guild's description.
+
+ This is only present if certain `features` are set in this guild.
+ Otherwise, this will always be `builtins.None`. For all other purposes, it is `builtins.None`.
+ """
+
+ verification_level: guilds.GuildVerificationLevel = attr.ib(eq=False, hash=False, repr=False)
+ """The verification level required for a user to participate in this guild."""
+
+ vanity_url_code: typing.Optional[str] = attr.ib(eq=False, hash=False, repr=True)
+ """The vanity URL code for the guild's vanity URL.
+
+ This is only present if `hikari.models.guilds.GuildFeature.VANITY_URL` is in the
+ `features` for this guild. If not, this will always be `builtins.None`.
+ """
+
+ @property
+ def splash_url(self) -> typing.Optional[files.URL]:
+ """Splash for the guild, if set."""
+ return self.format_splash()
+
+ def format_splash(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's splash image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The URL to the splash, or `builtins.None` if not set.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.splash_hash is None:
+ return None
+
+ return routes.CDN_GUILD_SPLASH.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.splash_hash, size=size, file_format=format_,
+ )
+
+ @property
+ def banner(self) -> typing.Optional[files.URL]:
+ """Banner for the guild, if set."""
+ return self.format_banner()
+
+ def format_banner(self, *, format_: str = "png", size: int = 4096) -> typing.Optional[files.URL]:
+ """Generate the guild's banner image, if set.
+
+ Parameters
+ ----------
+ format_ : builtins.str
+ The format to use for this URL, defaults to `png`.
+ Supports `png`, `jpeg`, `jpg` and `webp`.
+ size : builtins.int
+ The size to set for the URL, defaults to `4096`.
+ Can be any power of two between 16 and 4096.
+
+ Returns
+ -------
+ hikari.utilities.files.URL or builtins.None
+ The URL of the banner, or `builtins.None` if no banner is set.
+
+ Raises
+ ------
+ builtins.ValueError
+ If `size` is not a power of two or not between 16 and 4096.
+ """
+ if self.banner_hash is None:
+ return None
+
+ return routes.CDN_GUILD_BANNER.compile_to_file(
+ constants.CDN_URL, guild_id=self.id, hash=self.banner_hash, size=size, file_format=format_,
+ )
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Invite(InviteCode):
+ """Represents an invite that's used to add users to a guild or group dm."""
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ code: str = attr.ib(eq=True, hash=True, repr=True)
+ """The code for this invite."""
+
+ guild: typing.Optional[InviteGuild] = attr.ib(eq=False, hash=False, repr=False)
+ """The partial object of the guild this invite belongs to.
+
+ Will be `builtins.None` for group DM invites and when attached to a gateway event;
+ for invites received over the gateway you should refer to `Invite.guild_id`.
+ """
+
+ guild_id: typing.Optional[snowflake.Snowflake] = attr.ib(eq=False, hash=False, repr=True)
+ """The ID of the guild this invite belongs to.
+
+ Will be `builtins.None` for group DM invites.
+ """
+
+ channel: typing.Optional[channels.PartialChannel] = attr.ib(eq=False, hash=False, repr=False)
+ """The partial object of the channel this invite targets.
+
+ Will be `builtins.None` for invite objects that are attached to gateway events,
+ in which case you should refer to `Invite.channel_id`.
+ """
+
+ channel_id: snowflake.Snowflake = attr.ib(eq=False, hash=False, repr=True)
+ """The ID of the channel this invite targets."""
+
+ inviter: typing.Optional[users.User] = attr.ib(eq=False, hash=False, repr=False)
+ """The object of the user who created this invite."""
+
+ target_user: typing.Optional[users.User] = attr.ib(eq=False, hash=False, repr=False)
+ """The object of the user who this invite targets, if set."""
+
+ target_user_type: typing.Optional[TargetUserType] = attr.ib(eq=False, hash=False, repr=False)
+ """The type of user target this invite is, if applicable."""
+
+ approximate_presence_count: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The approximate amount of include_presences in this invite's guild.
+
+ This is only present when `with_counts` is passed as `builtins.True` to the GET
+ Invites endpoint.
+ """
+
+ approximate_member_count: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=False)
+ """The approximate amount of members in this invite's guild.
+
+ This is only present when `with_counts` is passed as `builtins.True` to the GET
+ Invites endpoint.
+ """
+
+ def __str__(self) -> str:
+ return f"https://discord.gg/{self.code}"
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class InviteWithMetadata(Invite):
+ """Extends the base `Invite` object with metadata.
+
+ The metadata is only returned when getting an invite with
+ guild permissions, rather than it's code.
+ """
+
+ uses: int = attr.ib(eq=False, hash=False, repr=True)
+ """The amount of times this invite has been used."""
+
+ max_uses: typing.Optional[int] = attr.ib(eq=False, hash=False, repr=True)
+ """The limit for how many times this invite can be used before it expires.
+
+ If set to `builtins.None` then this is unlimited.
+ """
+
+ # TODO: can we use a non-None value to represent infinity here somehow, or
+ # make a timedelta that is infinite for comparisons?
+ max_age: typing.Optional[datetime.timedelta] = attr.ib(eq=False, hash=False, repr=False)
+ """The timedelta of how long this invite will be valid for.
+
+ If set to `builtins.None` then this is unlimited.
+ """
+
+ is_temporary: bool = attr.ib(eq=False, hash=False, repr=True)
+ """Whether this invite grants temporary membership."""
+
+ created_at: datetime.datetime = attr.ib(eq=False, hash=False, repr=False)
+ """When this invite was created."""
+
+ @property
+ def expires_at(self) -> typing.Optional[datetime.datetime]:
+ """When this invite should expire, if `InviteWithMetadata.max_age` is set.
+
+ If this invite doesn't have a set expiry then this will be `builtins.None`.
+ """
+ if self.max_age is not None:
+ return self.created_at + self.max_age
+ return None
+
+
+# TODO: converter to remove discord.gg part to allow URLs here too.
+Inviteish = typing.Union[str, InviteCode]
+"""Type hint for an invite, vanity URL, or invite code.
+
+This must be a representation of an invite that is a `builtins.str` containing
+the invite code, an `Invite`/`InviteWithMetadata`, or a `VanityURL` instance.
+"""
diff --git a/hikari/models/messages.py b/hikari/models/messages.py
new file mode 100644
index 0000000000..2abf5b8774
--- /dev/null
+++ b/hikari/models/messages.py
@@ -0,0 +1,887 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Application and entities that are used to describe messages on Discord."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "MessageType",
+ "MessageFlag",
+ "MessageActivityType",
+ "Attachment",
+ "Reaction",
+ "MessageActivity",
+ "MessageCrosspost",
+ "PartialMessage",
+ "Message",
+]
+
+import enum
+import typing
+
+import attr
+
+from hikari.utilities import attr_extensions
+from hikari.utilities import constants
+from hikari.utilities import files
+from hikari.utilities import flag
+from hikari.utilities import snowflake
+from hikari.utilities import undefined
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+ from hikari import traits
+ from hikari.models import applications
+ from hikari.models import channels
+ from hikari.models import embeds as embeds_
+ from hikari.models import emojis as emojis_
+ from hikari.models import guilds
+ from hikari.models import users
+
+
+@enum.unique
+@typing.final
+class MessageType(enum.IntEnum):
+ """The type of a message."""
+
+ DEFAULT = 0
+ """A normal message."""
+
+ RECIPIENT_ADD = 1
+ """A message to denote a new recipient in a group."""
+
+ RECIPIENT_REMOVE = 2
+ """A message to denote that a recipient left the group."""
+
+ CALL = 3
+ """A message to denote a VoIP call."""
+
+ CHANNEL_NAME_CHANGE = 4
+ """A message to denote that the name of a channel changed."""
+
+ CHANNEL_ICON_CHANGE = 5
+ """A message to denote that the icon of a channel changed."""
+
+ CHANNEL_PINNED_MESSAGE = 6
+ """A message to denote that a message was pinned."""
+
+ GUILD_MEMBER_JOIN = 7
+ """A message to denote that a member joined the guild."""
+
+ USER_PREMIUM_GUILD_SUBSCRIPTION = 8
+ """A message to denote a Nitro subscription."""
+
+ USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_1 = 9
+ """A message to denote a tier 1 Nitro subscription."""
+
+ USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_2 = 10
+ """A message to denote a tier 2 Nitro subscription."""
+
+ USER_PREMIUM_GUILD_SUBSCRIPTION_TIER_3 = 11
+ """A message to denote a tier 3 Nitro subscription."""
+
+ CHANNEL_FOLLOW_ADD = 12
+ """Channel follow add."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@enum.unique
+@typing.final
+class MessageFlag(flag.Flag):
+ """Additional flags for message options."""
+
+ NONE = 0
+ """None"""
+
+ CROSSPOSTED = 1 << 0
+ """This message has been published to subscribed channels via channel following."""
+
+ IS_CROSSPOST = 1 << 1
+ """This message originated from a message in another channel via channel following."""
+
+ SUPPRESS_EMBEDS = 1 << 2
+ """Any embeds on this message should be omitted when serializing the message."""
+
+ SOURCE_MESSAGE_DELETED = 1 << 3
+ """The message this crosspost originated from was deleted via channel following."""
+
+ URGENT = 1 << 4
+ """This message came from the urgent message system."""
+
+
+@enum.unique
+@typing.final
+class MessageActivityType(enum.IntEnum):
+ """The type of a rich presence message activity."""
+
+ NONE = 0
+ """No activity."""
+
+ JOIN = 1
+ """Join an activity."""
+
+ SPECTATE = 2
+ """Spectating something."""
+
+ LISTEN = 3
+ """Listening to something."""
+
+ JOIN_REQUEST = 5
+ """Request to join an activity."""
+
+ def __str__(self) -> str:
+ return self.name
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Attachment(snowflake.Unique, files.WebResource):
+ """Represents a file attached to a message.
+
+ You can use this object in the same way as a `hikari.utilities.files.WebResource`,
+ by passing it as an attached file when creating a message, etc.
+ """
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ url: str = attr.ib(repr=True)
+ """The source URL of file."""
+
+ filename: str = attr.ib(repr=True)
+ """The name of the file."""
+
+ size: int = attr.ib(repr=True)
+ """The size of the file in bytes."""
+
+ proxy_url: str = attr.ib(repr=False)
+ """The proxied URL of file."""
+
+ height: typing.Optional[int] = attr.ib(repr=False)
+ """The height of the image (if the file is an image)."""
+
+ width: typing.Optional[int] = attr.ib(repr=False)
+ """The width of the image (if the file is an image)."""
+
+ def __str__(self) -> str:
+ return self.filename
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Reaction:
+ """Represents a reaction in a message."""
+
+ count: int = attr.ib(eq=False, hash=False, repr=True)
+ """The number of times the emoji has been used to react."""
+
+ emoji: typing.Union[emojis_.UnicodeEmoji, emojis_.CustomEmoji] = attr.ib(eq=True, hash=True, repr=True)
+ """The emoji used to react."""
+
+ is_me: bool = attr.ib(eq=False, hash=False, repr=False)
+ """Whether the current user reacted using this emoji."""
+
+ def __str__(self) -> str:
+ return str(self.emoji)
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class MessageActivity:
+ """Represents the activity of a rich presence-enabled message."""
+
+ type: MessageActivityType = attr.ib(repr=True)
+ """The type of message activity."""
+
+ party_id: typing.Optional[str] = attr.ib(repr=True)
+ """The party ID of the message activity."""
+
+
+@attr_extensions.with_copy
+@attr.s(eq=True, hash=False, init=True, kw_only=True, slots=True, weakref_slot=False)
+class MessageCrosspost:
+ """Represents information about a cross-posted message.
+
+ This is a message that is sent in one channel/guild and may be
+ "published" to another.
+ """
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ # TODO: get clarification on this! If it cannot happen, this should subclass PartialMessage too.
+ id: typing.Optional[snowflake.Snowflake] = attr.ib(repr=True)
+ """The ID of the message.
+
+ !!! warning
+ This may be `builtins.None` in some cases according to the Discord API
+ documentation, but the situations that cause this to occur are not
+ currently documented.
+ """
+
+ channel_id: snowflake.Snowflake = attr.ib(repr=True)
+ """The ID of the channel that the message originated from."""
+
+ guild_id: typing.Optional[snowflake.Snowflake] = attr.ib(repr=True)
+ """The ID of the guild that the message originated from.
+
+ !!! warning
+ This may be `builtins.None` in some cases according to the Discord API
+ documentation, but the situations that cause this to occur are not
+ currently documented.
+ """
+
+
+@attr_extensions.with_copy
+@attr.s(slots=True, kw_only=True, init=True, repr=True, eq=False, weakref_slot=False)
+class PartialMessage(snowflake.Unique):
+ """A message representation containing partially populated information.
+
+ This contains arbitrary fields that may be updated in a
+ `MessageUpdateEvent`, but for all other purposes should be treated as
+ being optionally specified.
+
+ !!! warn
+ All fields on this model except `channel` and `id` may be set to
+ `hikari.utilities.undefined.UndefinedType` (a singleton) if we have not
+ received information about their state from Discord alongside field
+ nullability.
+ """
+
+ app: traits.RESTAware = attr.ib(repr=False, eq=False, hash=False, metadata={attr_extensions.SKIP_DEEP_COPY: True})
+ """The client application that models may use for procedures."""
+
+ id: snowflake.Snowflake = attr.ib(eq=True, hash=True, repr=True)
+ """The ID of this entity."""
+
+ channel_id: snowflake.Snowflake = attr.ib(repr=True)
+ """The ID of the channel that the message was sent in."""
+
+ guild_id: undefined.UndefinedNoneOr[snowflake.Snowflake] = attr.ib(repr=True)
+ """The ID of the guild that the message was sent in."""
+
+ author: undefined.UndefinedOr[users.User] = attr.ib(repr=True)
+ """The author of this message."""
+
+ member: undefined.UndefinedNoneOr[guilds.Member] = attr.ib(repr=False)
+ """The member properties for the message's author."""
+
+ content: undefined.UndefinedNoneOr[str] = attr.ib(repr=False)
+ """The content of the message."""
+
+ timestamp: undefined.UndefinedOr[datetime.datetime] = attr.ib(repr=False)
+ """The timestamp that the message was sent at."""
+
+ edited_timestamp: undefined.UndefinedNoneOr[datetime.datetime] = attr.ib(repr=False)
+ """The timestamp that the message was last edited at.
+
+ Will be `builtins.None` if the message wasn't ever edited, or `undefined`
+ if the info is not available.
+ """
+
+ is_tts: undefined.UndefinedOr[bool] = attr.ib(repr=False)
+ """Whether the message is a TTS message."""
+
+ is_mentioning_everyone: undefined.UndefinedOr[bool] = attr.ib(repr=False)
+ """Whether the message mentions `@everyone` or `@here`."""
+
+ user_mentions: undefined.UndefinedOr[typing.Sequence[snowflake.Snowflake]] = attr.ib(repr=False)
+ """The users the message mentions."""
+
+ role_mentions: undefined.UndefinedOr[typing.Sequence[snowflake.Snowflake]] = attr.ib(repr=False)
+ """The roles the message mentions."""
+
+ channel_mentions: undefined.UndefinedOr[typing.Sequence[snowflake.Snowflake]] = attr.ib(repr=False)
+ """The channels the message mentions."""
+
+ attachments: undefined.UndefinedOr[typing.Sequence[Attachment]] = attr.ib(repr=False)
+ """The message attachments."""
+
+ embeds: undefined.UndefinedOr[typing.Sequence[embeds_.Embed]] = attr.ib(repr=False)
+ """The message's embeds."""
+
+ reactions: undefined.UndefinedOr[typing.Sequence[Reaction]] = attr.ib(repr=False)
+ """The message's reactions."""
+
+ is_pinned: undefined.UndefinedOr[bool] = attr.ib(repr=False)
+ """Whether the message is pinned."""
+
+ webhook_id: undefined.UndefinedNoneOr[snowflake.Snowflake] = attr.ib(repr=False)
+ """If the message was generated by a webhook, the webhook's ID."""
+
+ type: undefined.UndefinedOr[MessageType] = attr.ib(repr=False)
+ """The message's type."""
+
+ activity: undefined.UndefinedNoneOr[MessageActivity] = attr.ib(repr=False)
+ """The message's activity."""
+
+ application: undefined.UndefinedNoneOr[applications.Application] = attr.ib(repr=False)
+ """The message's application."""
+
+ message_reference: undefined.UndefinedNoneOr[MessageCrosspost] = attr.ib(repr=False)
+ """The message's cross-posted reference data."""
+
+ flags: undefined.UndefinedNoneOr[MessageFlag] = attr.ib(repr=False)
+ """The message's flags."""
+
+ nonce: undefined.UndefinedNoneOr[str] = attr.ib(repr=False)
+ """The message nonce.
+
+ This is a string used for validating a message was sent.
+ """
+
+ @property
+ def link(self) -> str:
+ """Jump link to the message.
+
+ Returns
+ -------
+ builtins.str
+ The jump link to the message.
+ """
+ if self.guild_id is None:
+ return f"{constants.BASE_URL}/channels/@me/{self.channel_id}/{self.id}"
+ return f"{constants.BASE_URL}/channels/{self.guild_id}/{self.channel_id}/{self.id}"
+
+ async def fetch_channel(self) -> channels.PartialChannel:
+ """Fetch the channel this message was created in.
+
+ Returns
+ -------
+ hikari.models.channels.PartialChannel
+ The object of the channel this message belongs to.
+
+ Raises
+ ------
+ hikari.errors.BadRequest
+ If any invalid snowflake IDs are passed; a snowflake may be invalid
+ due to it being outside of the range of a 64 bit integer.
+ hikari.errors.Forbidden
+ If you don't have access to the channel this message belongs to.
+ hikari.errors.NotFound
+ If the channel this message was created in does not exist.
+ """
+ return await self.app.rest.fetch_channel(self.channel_id)
+
+ async def edit(
+ self,
+ content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
+ *,
+ embed: undefined.UndefinedNoneOr[embeds_.Embed] = undefined.UNDEFINED,
+ mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ user_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[users.PartialUser]], bool]
+ ] = undefined.UNDEFINED,
+ role_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]], bool]
+ ] = undefined.UNDEFINED,
+ flags: undefined.UndefinedOr[MessageFlag] = undefined.UNDEFINED,
+ ) -> Message:
+ """Edit an existing message in a given channel.
+
+ Parameters
+ ----------
+ content : hikari.utilities.undefined.UndefinedOr[typing.Any]
+ The message content to update with. If
+ `hikari.utilities.undefined.UNDEFINED`, then the content will not
+ be changed. If `builtins.None`, then the content will be removed.
+
+ Any other value will be cast to a `builtins.str` before sending.
+
+ If this is a `hikari.models.embeds.Embed` and no `embed` kwarg is
+ provided, then this will instead update the embed. This allows for
+ simpler syntax when sending an embed alone.
+ embed : hikari.utilities.undefined.UndefinedNoneOr[hikari.models.embeds.Embed]
+ The embed to set on the message. If
+ `hikari.utilities.undefined.UNDEFINED`, the previous embed if
+ present is not changed. If this is `builtins.None`, then the embed
+ is removed if present. Otherwise, the new embed value that was
+ provided will be used as the replacement.
+ mentions_everyone : hikari.utilities.undefined.UndefinedOr[builtins.bool]
+ Sanitation for `@everyone` mentions. If
+ `hikari.utilities.undefined.UNDEFINED`, then the previous setting is
+ not changed. If `builtins.True`, then `@everyone`/`@here` mentions
+ in the message content will show up as mentioning everyone that can
+ view the chat.
+ user_mentions : hikari.utilities.undefined.UndefinedOr[typing.Collection[hikari.utilities.snowflake.SnowflakeishOr[hikari.models.users.PartialUser] or builtins.bool]
+ Sanitation for user mentions. If
+ `hikari.utilities.undefined.UNDEFINED`, then the previous setting is
+ not changed. If `builtins.True`, all valid user mentions will behave
+ as mentions. If `builtins.False`, all valid user mentions will not
+ behave as mentions.
+
+ You may alternatively pass a collection of
+ `hikari.utilities.snowflake.Snowflake` user IDs, or
+ `hikari.models.users.PartialUser`-derived objects.
+ role_mentions : hikari.utilities.undefined.UndefinedOr[typing.Collection[hikari.utilities.snowflake.SnowflakeishOr[hikari.models.guilds.PartialRole] or builtins.bool]
+ Sanitation for role mentions. If
+ `hikari.utilities.undefined.UNDEFINED`, then the previous setting is
+ not changed. If `builtins.True`, all valid role mentions will behave
+ as mentions. If `builtins.False`, all valid role mentions will not
+ behave as mentions.
+
+ You may alternatively pass a collection of
+ `hikari.utilities.snowflake.Snowflake` role IDs, or
+ `hikari.models.guilds.PartialRole`-derived objects.
+ flags : hikari.utilities.undefined.UndefinedOr[hikari.models.messages.MessageFlag]
+ Optional flags to set on the message. If
+ `hikari.utilities.undefined.UNDEFINED`, then nothing is changed.
+
+ Note that some flags may not be able to be set. Currently the only
+ flags that can be set are `NONE` and `SUPPRESS_EMBEDS`. If you
+ have `MANAGE_MESSAGES` permissions, you can use this call to
+ suppress embeds on another user's message.
+
+ !!! note
+ Mentioning everyone, roles, or users in message edits currently
+ will not send a push notification showing a new mention to people
+ on Discord. It will still highlight in their chat as if they
+ were mentioned, however.
+
+ !!! note
+ There is currently no documented way to clear attachments or edit
+ attachments from a previously sent message on Discord's API. To
+ do this, `delete` the message and re-send it.
+
+ !!! warning
+ If the message was not sent by your user, the only parameter
+ you may provide to this call is the `flags` parameter. Anything
+ else will result in a `hikari.errors.Forbidden` being raised.
+
+ Returns
+ -------
+ hikari.models.messages.Message
+ The edited message.
+
+ Raises
+ ------
+ hikari.errors.BadRequest
+ This may be raised in several discrete situations, such as messages
+ being empty with no embeds; messages with more than 2000 characters
+ in them, embeds that exceed one of the many embed
+ limits; invalid image URLs in embeds; users in `user_mentions` not
+ being mentioned in the message content; roles in `role_mentions` not
+ being mentioned in the message content.
+ hikari.errors.Unauthorized
+ If you are unauthorized to make the request (invalid/missing token).
+ hikari.errors.Forbidden
+ If you lack permissions to send messages in the given channel; if
+ you try to change the contents of another user's message; or if you
+ try to edit the flags on another user's message without the
+ permissions to manage messages.
+ hikari.errors.NotFound
+ If the channel or message is not found.
+ hikari.errors.ServerHTTPErrorResponse
+ If an internal error occurs on Discord while handling the request.
+ """ # noqa: E501 - Line too long
+ return await self.app.rest.edit_message(
+ message=self.id,
+ channel=self.channel_id,
+ content=content,
+ embed=embed,
+ mentions_everyone=mentions_everyone,
+ user_mentions=user_mentions,
+ role_mentions=role_mentions,
+ flags=flags,
+ )
+
+ async def reply(
+ self,
+ content: undefined.UndefinedOr[typing.Any] = undefined.UNDEFINED,
+ *,
+ embed: undefined.UndefinedOr[embeds_.Embed] = undefined.UNDEFINED,
+ attachment: undefined.UndefinedOr[files.Resourceish] = undefined.UNDEFINED,
+ attachments: undefined.UndefinedOr[typing.Sequence[files.Resourceish]] = undefined.UNDEFINED,
+ tts: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ nonce: undefined.UndefinedOr[str] = undefined.UNDEFINED,
+ mentions_everyone: undefined.UndefinedOr[bool] = undefined.UNDEFINED,
+ user_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[users.PartialUser]], bool]
+ ] = undefined.UNDEFINED,
+ role_mentions: undefined.UndefinedOr[
+ typing.Union[typing.Collection[snowflake.SnowflakeishOr[guilds.PartialRole]], bool]
+ ] = undefined.UNDEFINED,
+ ) -> Message:
+ """Create a message in the given channel.
+
+ Parameters
+ ----------
+ content : hikari.utilities.undefined.UndefinedOr[typing.Any]
+ If specified, the message contents. If
+ `hikari.utilities.undefined.UNDEFINED`, then nothing will be sent
+ in the content. Any other value here will be cast to a
+ `builtins.str`.
+
+ If this is a `hikari.models.embeds.Embed` and no `embed` kwarg is
+ provided, then this will instead update the embed. This allows for
+ simpler syntax when sending an embed alone.
+
+ Likewise, if this is a `hikari.utilities.files.Resource`, then the
+ content is instead treated as an attachment if no `attachment` and
+ no `attachments` kwargs are provided.
+ embed : hikari.utilities.undefined.UndefinedOr[hikari.models.embeds.Embed]
+ If specified, the message embed.
+ attachment : hikari.utilities.undefined.UndefinedOr[hikari.utilities.files.Resourceish],
+ If specified, the message attachment. This can be a resource,
+ or string of a path on your computer or a URL.
+ attachments : hikari.utilities.undefined.UndefinedOr[typing.Sequence[hikari.utilities.files.Resourceish]],
+ If specified, the message attachments. These can be resources, or
+ strings consisting of paths on your computer or URLs.
+ tts : hikari.utilities.undefined.UndefinedOr[builtins.bool]
+ If specified, whether the message will be TTS (Text To Speech).
+ nonce : hikari.utilities.undefined.UndefinedOr[builtins.str]
+ If specified, a nonce that can be used for optimistic message
+ sending.
+ mentions_everyone : hikari.utilities.undefined.UndefinedOr[builtins.bool]
+ If specified, whether the message should parse @everyone/@here
+ mentions.
+ user_mentions : hikari.utilities.undefined.UndefinedOr[typing.Collection[hikari.utilities.snowflake.SnowflakeishOr[hikari.models.users.PartialUser] or builtins.bool]
+ If specified, and `builtins.True`, all mentions will be parsed.
+ If specified, and `builtins.False`, no mentions will be parsed.
+ Alternatively this may be a collection of
+ `hikari.utilities.snowflake.Snowflake`, or
+ `hikari.models.users.PartialUser` derivatives to enforce mentioning
+ specific users.
+ role_mentions : hikari.utilities.undefined.UndefinedOr[typing.Collection[hikari.utilities.snowflake.SnowflakeishOr[hikari.models.guilds.PartialRole] or builtins.bool]
+ If specified, and `builtins.True`, all mentions will be parsed.
+ If specified, and `builtins.False`, no mentions will be parsed.
+ Alternatively this may be a collection of
+ `hikari.utilities.snowflake.Snowflake`, or
+ `hikari.models.guilds.PartialRole` derivatives to enforce mentioning
+ specific roles.
+
+ !!! note
+ Attachments can be passed as many different things, to aid in
+ convenience.
+
+ - If a `pathlib.PurePath` or `builtins.str` to a valid URL, the
+ resource at the given URL will be streamed to Discord when
+ sending the message. Subclasses of
+ `hikari.utilities.files.WebResource` such as
+ `hikari.utilities.files.URL`,
+ `hikari.models.messages.Attachment`,
+ `hikari.models.emojis.Emoji`,
+ `EmbedResource`, etc will also be uploaded this way.
+ This will use bit-inception, so only a small percentage of the
+ resource will remain in memory at any one time, thus aiding in
+ scalability.
+ - If a `hikari.utilities.files.Bytes` is passed, or a `builtins.str`
+ that contains a valid data URI is passed, then this is uploaded
+ with a randomized file name if not provided.
+ - If a `hikari.utilities.files.File`, `pathlib.PurePath` or
+ `builtins.str` that is an absolute or relative path to a file
+ on your file system is passed, then this resource is uploaded
+ as an attachment using non-blocking code internally and streamed
+ using bit-inception where possible. This depends on the
+ type of `concurrent.futures.Executor` that is being used for
+ the application (default is a thread pool which supports this
+ behaviour).
+
+ Returns
+ -------
+ hikari.models.messages.Message
+ The created message.
+
+ Raises
+ ------
+ hikari.errors.BadRequest
+ This may be raised in several discrete situations, such as messages
+ being empty with no attachments or embeds; messages with more than
+ 2000 characters in them, embeds that exceed one of the many embed
+ limits; too many attachments; attachments that are too large;
+ invalid image URLs in embeds; users in `user_mentions` not being
+ mentioned in the message content; roles in `role_mentions` not
+ being mentioned in the message content.
+ hikari.errors.Unauthorized
+ If you are unauthorized to make the request (invalid/missing token).
+ hikari.errors.Forbidden
+ If you lack permissions to send messages in the given channel.
+ hikari.errors.NotFound
+ If the channel is not found.
+ hikari.errors.ServerHTTPErrorResponse
+ If an internal error occurs on Discord while handling the request.
+ builtins.ValueError
+ If more than 100 unique objects/entities are passed for
+ `role_mentions` or `user_mentions`.
+ builtins.TypeError
+ If both `attachment` and `attachments` are specified.
+
+ !!! warning
+ You are expected to make a connection to the gateway and identify
+ once before being able to use this endpoint for a bot.
+ """ # noqa: E501 - Line too long
+ return await self.app.rest.create_message(
+ channel=self.channel_id,
+ content=content,
+ embed=embed,
+ attachment=attachment,
+ attachments=attachments,
+ nonce=nonce,
+ tts=tts,
+ mentions_everyone=mentions_everyone,
+ user_mentions=user_mentions,
+ role_mentions=role_mentions,
+ )
+
+ async def delete(self) -> None:
+ """Delete this message.
+
+ Raises
+ ------
+ hikari.errors.NotFound
+ If the channel this message was created in is not found, or if the
+ message has already been deleted.
+ hikari.errors.Forbidden
+ If you lack the permissions to delete the message.
+ """
+ await self.app.rest.delete_message(self.channel_id, self.id)
+
+ async def add_reaction(self, emoji: emojis_.Emojiish) -> None:
+ r"""Add a reaction to this message.
+
+ Parameters
+ ----------
+ emoji : hikari.models.emojis.Emojiish
+ The emoji to add. This may be a unicode emoji string, the
+ `name:id` of a custom emoji, or a subclass of
+ `hikari.models.emojis.Emoji`.
+
+ Note that if the emoji is an `hikari.models.emojis.CustomEmoji`
+ and is not from a guild the bot user is in, then this will fail.
+
+ Examples
+ --------
+ ```py
+ # Using a unicode emoji.
+ await message.add_reaction("👌")
+
+ # Using a unicode emoji name.
+ await message.add_reaction("\N{OK HAND SIGN}")
+
+ # Using the `name:id` format.
+ await message.add_reaction("rooAYAYA:705837374319493284")
+
+ # Using a raw custom emoji mention (unanimated and animated)
+ await message.add_reaction("<:rooAYAYA:705837374319493284>")
+ await message.add_reaction("")
+
+ # Using an Emoji-derived object.
+ await message.add_reaction(some_emoji_object)
+ ```
+
+ Raises
+ ------
+ hikari.errors.BadRequest
+ If the emoji is invalid, unknown, or formatted incorrectly.
+ hikari.errors.Forbidden
+ If this is the first reaction using this specific emoji on this
+ message and you lack the `ADD_REACTIONS` permission. If you lack
+ `READ_MESSAGE_HISTORY`, this may also raise this error.
+ hikari.errors.NotFound
+ If the channel or message is not found, or if the emoji is not
+ found.
+
+ This will also occur if you try to add an emoji from a
+ guild you are not part of if no one else has previously
+ reacted with the same emoji.
+ """
+ await self.app.rest.add_reaction(channel=self.channel_id, message=self.id, emoji=emoji)
+
+ async def remove_reaction(
+ self,
+ emoji: emojis_.Emojiish,
+ *,
+ user: undefined.UndefinedOr[snowflake.SnowflakeishOr[users.PartialUser]] = undefined.UNDEFINED,
+ ) -> None:
+ r"""Remove a reaction from this message.
+
+ Parameters
+ ----------
+ emoji : hikari.models.emojis.Emojiish
+ The emoji to remove.
+ user : hikari.utilities.undefined.UndefinedOr[hikari.utilities.snowflake.SnowflakeishOr[hikari.models.users.PartialUser]]
+ The user of the reaction to remove. If unspecified, then the bot's
+ reaction is removed instead.
+
+ Examples
+ --------
+ # Using a unicode emoji and removing the bot's reaction from this
+ # reaction.
+ await message.remove_reaction("\N{OK HAND SIGN}")
+
+ # Using a unicode emoji and removing a specific user from this
+ # reaction.
+ await message.remove_reaction("\N{OK HAND SIGN}", some_user)
+
+ # Using a raw custom emoji mention (unanimated and animated)
+ await message.remove_reaction("<:rooAYAYA:705837374319493284>", some_user)
+ await message.remove_reaction("", some_user)
+
+ # Using an Emoji object and removing a specific user from this
+ # reaction.
+ await message.remove_reaction(some_emoji_object, some_user)
+
+ Raises
+ ------
+ hikari.errors.BadRequest
+ If the emoji is invalid, unknown, or formatted incorrectly.
+ If any invalid snowflake IDs are passed; a snowflake may be invalid
+ due to it being outside of the range of a 64 bit integer.
+ hikari.errors.Forbidden
+ If this is the first reaction using this specific emoji on this
+ message and you lack the `ADD_REACTIONS` permission. If you lack
+ `READ_MESSAGE_HISTORY`, this may also raise this error. If you
+ remove the reaction of another user without `MANAGE_MESSAGES`, this
+ will be raised.
+ hikari.errors.NotFound
+ If the channel or message is not found, or if the emoji is not
+ found.
+ """
+ if user is undefined.UNDEFINED:
+ await self.app.rest.delete_my_reaction(channel=self.channel_id, message=self.id, emoji=emoji)
+ else:
+ await self.app.rest.delete_reaction(channel=self.channel_id, message=self.id, emoji=emoji, user=user)
+
+ async def remove_all_reactions(self, emoji: undefined.UndefinedOr[emojis_.Emojiish] = undefined.UNDEFINED) -> None:
+ r"""Remove all users' reactions for a specific emoji from the message.
+
+ Parameters
+ ----------
+ emoji : hikari.utilities.undefined.UndefinedOr[hikari.models.emojis.Emojiish]
+ The emoji to remove all reactions for. If not specified, then all
+ emojis are removed.
+
+ Example
+ --------
+ # Using a unicode emoji and removing all 👌 reacts from the message.
+ # reaction.
+ await message.remove_all_reactions("\N{OK HAND SIGN}")
+
+ # Using a raw custom emoji mention (unanimated and animated)
+ await message.remove_all_reactions("<:rooAYAYA:705837374319493284>")
+ await message.remove_all_reactions("")
+
+ # Removing all reactions entirely.
+ await message.remove_all_reactions()
+
+ Raises
+ ------
+ hikari.errors.Forbidden
+ If you are missing the `MANAGE_MESSAGES` permission, or the
+ permission to view the channel
+ hikari.errors.NotFound
+ If the channel or message is not found, or if the emoji is not
+ found.
+ hikari.errors.BadRequest
+ If the emoji is invalid, unknown, or formatted incorrectly.
+ If any invalid snowflake IDs are passed; a snowflake may be invalid
+ due to it being outside of the range of a 64 bit integer.
+ """
+ if emoji is undefined.UNDEFINED:
+ await self.app.rest.delete_all_reactions(channel=self.channel_id, message=self.id)
+ else:
+ await self.app.rest.delete_all_reactions_for_emoji(channel=self.channel_id, message=self.id, emoji=emoji)
+
+
+@attr.s(eq=True, hash=True, init=True, kw_only=True, slots=True, weakref_slot=False)
+class Message(PartialMessage):
+ """Represents a message with all known details."""
+
+ # These are purposely not auto attribs, but instead just specify a
+ # tighter type bounds (i.e. none are allowed to be undefined.Undefined
+ # in this model). We use this in cases where we know all information is
+ # present. DO NOT ADD attr.ib TO ANY OF THESE, OR ENABLE auto_attribs
+ # IN THIS CLASS, the latter will mess up slotting or cause layout conflicts
+ # and possibly result in large amounts of unwasted memory if you get that
+ # far.
+
+ guild_id: typing.Optional[snowflake.Snowflake]
+ """The ID of the guild that the message was sent in."""
+
+ author: users.User
+ """The author of this message."""
+
+ member: typing.Optional[guilds.Member]
+ """The member properties for the message's author."""
+
+ content: typing.Optional[str]
+ """The content of the message."""
+
+ timestamp: datetime.datetime
+ """The timestamp that the message was sent at."""
+
+ edited_timestamp: typing.Optional[datetime.datetime]
+ """The timestamp that the message was last edited at.
+
+ Will be `builtins.None` if it wasn't ever edited.
+ """
+
+ is_tts: bool
+ """Whether the message is a TTS message."""
+
+ is_mentioning_everyone: bool
+ """Whether the message mentions `@everyone` or `@here`."""
+
+ user_mentions: typing.Sequence[snowflake.Snowflake]
+ """The users the message mentions."""
+
+ role_mentions: typing.Sequence[snowflake.Snowflake]
+ """The roles the message mentions."""
+
+ channel_mentions: typing.Sequence[snowflake.Snowflake]
+ """The channels the message mentions."""
+
+ attachments: typing.Sequence[Attachment]
+ """The message attachments."""
+
+ embeds: typing.Sequence[embeds_.Embed]
+ """The message embeds."""
+
+ reactions: typing.Sequence[Reaction]
+ """The message reactions."""
+
+ is_pinned: bool
+ """Whether the message is pinned."""
+
+ webhook_id: typing.Optional[snowflake.Snowflake]
+ """If the message was generated by a webhook, the webhook's id."""
+
+ type: MessageType
+ """The message type."""
+
+ activity: typing.Optional[MessageActivity]
+ """The message activity."""
+
+ application: typing.Optional[applications.Application]
+ """The message application."""
+
+ message_reference: typing.Optional[MessageCrosspost]
+ """The message crossposted reference data."""
+
+ flags: typing.Optional[MessageFlag]
+ """The message flags."""
+
+ nonce: typing.Optional[str]
+ """The message nonce. This is a string used for validating a message was sent."""
diff --git a/hikari/models/permissions.py b/hikari/models/permissions.py
new file mode 100644
index 0000000000..e66dbd8ca7
--- /dev/null
+++ b/hikari/models/permissions.py
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Bitfield of permissions."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = ["Permissions"]
+
+import enum
+
+# noinspection PyUnresolvedReferences
+import typing
+
+from hikari.utilities import flag
+
+
+@enum.unique
+@typing.final
+class Permissions(flag.Flag):
+ """Represents the permissions available in a given channel or guild.
+
+ This is an int-flag enum. This means that you can **combine multiple
+ permissions together** into one value using the bitwise-OR operator (`|`).
+
+ my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD
+
+ your_perms = (
+ Permissions.CREATE_INSTANT_INVITE
+ | Permissions.KICK_MEMBERS
+ | Permissions.BAN_MEMBERS
+ | Permissions.MANAGE_GUILD
+ )
+
+ You can **check if a permission is present** in a set of combined
+ permissions by using the bitwise-AND operator (`&`). This will return
+ the int-value of the permission if it is present, or `0` if not present.
+
+ my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD
+
+ if my_perms & Permissions.MANAGE_CHANNELS:
+ if my_perms & Permissions.MANAGE_GUILD:
+ print("I have the permission to both manage the guild and the channels in it!")
+ else:
+ print("I have the permission to manage channels!")
+ else:
+ print("I don't have the permission to manage channels!")
+
+ # Or you could simplify it:
+
+ if my_perms & (Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD):
+ print("I have the permission to both manage the guild and the channels in it!")
+ elif my_perms & Permissions.MANAGE_CHANNELS:
+ print("I have the permission to manage channels!")
+ else:
+ print("I don't have the permission to manage channels!")
+
+ If you need to **check that a permission is not present**, you can use the
+ bitwise-XOR operator (`^`) to check. If the permission is not present, it
+ will return a non-zero value, otherwise if it is present, it will return `0`.
+
+ my_perms = Permissions.MANAGE_CHANNELS | Permissions.MANAGE_GUILD
+
+ if my_perms ^ Permissions.MANAGE_CHANNELS:
+ print("Please give me the MANAGE_CHANNELS permission!")
+
+ Lastly, if you need all the permissions set except the permission you want,
+ you can use the inversion operator (`~`) to do that.
+
+ # All permissions except ADMINISTRATOR.
+ my_perms = ~Permissions.ADMINISTRATOR
+
+ """
+
+ NONE = 0
+ """Empty permission."""
+
+ CREATE_INSTANT_INVITE = 1 << 0
+ """Allows creation of instant invites."""
+
+ KICK_MEMBERS = 1 << 1
+ """Allows kicking members"""
+
+ BAN_MEMBERS = 1 << 2
+ """Allows banning members."""
+
+ ADMINISTRATOR = 1 << 3
+ """Allows all permissions and bypasses channel permission overwrites."""
+
+ MANAGE_CHANNELS = 1 << 4
+ """Allows management and editing of channels."""
+
+ MANAGE_GUILD = 1 << 5
+ """Allows management and editing of the guild."""
+
+ ADD_REACTIONS = 1 << 6
+ """Allows for the addition of reactions to messages."""
+
+ VIEW_AUDIT_LOG = 1 << 7
+ """Allows for viewing of audit logs."""
+
+ PRIORITY_SPEAKER = 1 << 8
+ """Allows for using priority speaker in a voice channel."""
+
+ STREAM = 1 << 9
+ """Allows the user to go live."""
+
+ VIEW_CHANNEL = 1 << 10
+ """Allows guild members to view a channel, which includes reading messages in text channels."""
+
+ SEND_MESSAGES = 1 << 11
+ """Allows for sending messages in a channel."""
+
+ SEND_TTS_MESSAGES = 1 << 12
+ """Allows for sending of `/tts` messages."""
+
+ MANAGE_MESSAGES = 1 << 13
+ """Allows for deletion of other users messages."""
+
+ EMBED_LINKS = 1 << 14
+ """Links sent by users with this permission will be auto-embedded."""
+
+ ATTACH_FILES = 1 << 15
+ """Allows for uploading images and files."""
+
+ READ_MESSAGE_HISTORY = 1 << 16
+ """Allows for reading of message history."""
+
+ MENTION_ROLES = 1 << 17
+ """Allows for using the `@everyone` tag to notify all users in a channel,
+ and the `@here` tag to notify all online users in a channel, and the
+ `@role` tag (even if the role is not mentionable) to notify all users with
+ that role in a channel.
+ """
+
+ USE_EXTERNAL_EMOJIS = 1 << 18
+ """Allows the usage of custom emojis from other guilds."""
+
+ VIEW_GUILD_INSIGHTS = 1 << 19
+ """Allows the user to view guild insights for eligible guilds."""
+
+ CONNECT = 1 << 20
+ """Allows for joining of a voice channel."""
+
+ SPEAK = 1 << 21
+ """Allows for speaking in a voice channel."""
+
+ MUTE_MEMBERS = 1 << 22
+ """Allows for muting members in a voice channel."""
+
+ DEAFEN_MEMBERS = 1 << 23
+ """Allows for deafening of members in a voice channel."""
+
+ MOVE_MEMBERS = 1 << 24
+ """Allows for moving of members between voice channels."""
+
+ USE_VAD = 1 << 25
+ """Allows for using voice-activity-detection in a voice channel."""
+
+ CHANGE_NICKNAME = 1 << 26
+ """Allows for modification of own nickname."""
+
+ MANAGE_NICKNAMES = 1 << 27
+ """Allows for modification of other users nicknames."""
+
+ MANAGE_ROLES = 1 << 28
+ """Allows management and editing of roles."""
+
+ MANAGE_WEBHOOKS = 1 << 29
+ """Allows management and editing of webhooks."""
+
+ MANAGE_EMOJIS = 1 << 30
+ """Allows management and editing of emojis."""
diff --git a/hikari/models/presences.py b/hikari/models/presences.py
new file mode 100644
index 0000000000..79a7370a9c
--- /dev/null
+++ b/hikari/models/presences.py
@@ -0,0 +1,312 @@
+# -*- coding: utf-8 -*-
+# cython: language_level=3
+# Copyright (c) 2020 Nekokatt
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+"""Application and entities that are used to describe guilds on Discord."""
+
+from __future__ import annotations
+
+__all__: typing.Final[typing.List[str]] = [
+ "Activity",
+ "ActivityAssets",
+ "ActivityFlag",
+ "ActivitySecret",
+ "ActivityTimestamps",
+ "ActivityType",
+ "ActivityParty",
+ "ClientStatus",
+ "MemberPresence",
+ "RichActivity",
+ "Status",
+]
+
+import enum
+import typing
+
+import attr
+
+from hikari.utilities import attr_extensions
+from hikari.utilities import flag
+from hikari.utilities import snowflake
+
+if typing.TYPE_CHECKING:
+ import datetime
+
+ from hikari import traits
+ from hikari.models import emojis as emojis_
+
+
+@enum.unique
+@typing.final
+class ActivityType(enum.IntEnum):
+ """The activity type."""
+
+ PLAYING = 0
+ """Shows up as `Playing