Event streaming, full shard and bot reimplementation, numerous fixes for bugs.
Pre-release
Pre-release
API changes
There have been a large number of possibly breaking changes over the past week to make
this API more stable, more efficient, and tidier and clearer to understand. So please
bare with us! I have attempted to document every change below.
hikari.Bot / hikari.impl.bot.BotApp
- The bot implementation has been rewritten from scratch.
logger_level
kwarg inhikari.Bot
has been renamed tologs
(seeLogging
subsection below for details on this).- Gateway-specific configuration options are now passed to
Bot.run
orbot.start
instead of the constructor. This will allow future releases of this library to
potentially handle stuff like automatically rescaling if the bot reaches a sharding
limit during execution. It also allows you to implement your own resharding strategies. stateless
constructor parameter has been changed toenable_cache
.is_stateless
property has been removed. Users are encouraged to use an
"ask for forgiveness" approach by checking the cache regardless of the cache
implementation, and then observing the result (whether any match for their query is
found or not) to determine what to do next (i.e. whether to make an API call or not).- New
chunking_limit
constructor argument. - New
force_color
andallow_color
constructor arguments to compliment the
existingCLICOLOR
andCLICOLOR_FORCE
environment variable support. - You can no longer force a specific gateway version or REST API version
(without manipulating the URLs). token
is now able to be used as a positional argument in the constructor.- An overridable
print_banner
staticmethod has been provided that will allow library
vendors to bundle or inject their own banners as they see fit for their libraries
that build on top of hikari. - The session start limit is now considered before starting an application. If you have
10 sessions left for the 24 hour window, but try to start 20 shards, the application
will fail with ahikari.errors.GatewayError
immediately. This will prevent your token
being potentially reset by Discord without you realising if your application gets stuck
in a restart loop. You can disable this check by passingignore_session_start_limit=True
toBot.run
orBot.start
. - New
asyncio_debug
parameter toBot.run
to toggle asyncio debugging mode on the
event loop. - You can no longer change the event loop that the application is running on. You should
declare the bot object on the thread you are wishing to run it from, and only do this
once the event loop you wish to use is initialized. This prevents major bugs that were
manifested in the previous implementation of this mechanism. - New
coroutine_tracking_depth
argument tobot.run
to customise the coroutine
tracking depth provisionally. This may be removed from CPython at any time without
warning, so the mechanism will revert to doing "nothing" if your interpreter does not
support setting this in the future. - New
enable_signal_handlers
argument toBot.run
that can be disabled if you wish to
implement your own signal handling but still usebot.run
. - The default executor for the asyncio event loop will now be gracefully shut down when
Bot.run
closes the event loop on exit. This will only be present in Python 3.9 and
newer. In Python 3.8, this functionality is not available. - New
close_loop
argument toBot.run
that can be set toFalse
optionally to stop
the event loop being cleared up, any outstanding tasks being cancelled, asyncgens being
shut down, and the event loop being closed. This will also toggle whether the default
executor for the event loop is closed or not on Python 3.9 and newer. Bot.close
now requests shut down only. It can be made to wait until the application
terminates, or left to run in the background (preventing exceptions being thrown
everywhere if you invoke this as part of an event callback, such as a "close bot" command).- New
close_executor
argument toBot.run
that can be optionally set toTrue
to
enforce any custom executor passed to theBot
constructor gets closed when the event
loop shuts down. This defaults toFalse
as to not assume ownership. - Start up and shutdown orchestration logic has been completely overhauled. You can now
safely terminate a multisharded bot midway through startup. - New
Bot.terminate
which can be used to manually destroy the entire application immediately.
This is done concurrently, so should also be faster than before.
Gateway Shard implementation
- The gateway shard implementation has been fully rewritten from scratch. The existing API
is mostly the same but a large number of "pointless" properties that consumers will not
usually ever need to know about have been removed. - Reconnect logic has been rewritten, shards should now be much more stable.
- Logging has been rewritten.
- There is now assurance that the gateway close code is sent on close, and only sent once.
- The gateway close code is now 1xxx if shutting down permanently, which should allow the
bot to appear offline "immediately" when closing down.
Logging
- Banner and logging have been overhauled.
colorlog
is now used for the default logging
configuration, which means log entries will now default to being coloured based on their
severity, which should make reading logs when DEBUG is on much easier on the eyes. colorlog
includescolorama
on Windows, which should fix some issues with colour
support in some terminals, hopefully.logger_level
kwarg inhikari.Bot
has been renamed tologs
, and will now take an
integer logging level, a string name, or a fulllogging.config.dictConfig
compatible
schema, as well asNone
to disable automatically initializing logging.
You can now use a module like pyyaml or json to pull logging config from a config file
and pass it directly to your application. Configuration-as-code for the masses!
Rate limiting
- Internal exponential backoffs should not explode now when they get too large. This was
fixed by amending a second hidden bug that had not been spotted that allowed exponential
backoffs to surpass their limits. - Exponential backoffs must ALWAYS have a maximum value now.
Guild member chunking and event streaming
- The guild member chunking interface is now part of the public API.
- Shard request_guild_members now limits the nonce to a valid constrained value. This
should prevent invalid inputs from causing the gateway connection to die. - A "feature" on Discord where the use of intents prevents guild member details being
sent on GUILD_CREATE unless you have the GUILD_PRESENCES intent enabled has been
remediated. Using intents now chunks all guilds to ensure member data is present
consistently, as long as the privileged intents for GUILD_MEMBERS or GUILD_PRESENCES
is enabled. - The
user_ids
parameter on therequest_guild_members
coroutine function in
GatewayShard
is now namedusers
instead. - Implemented an EventStream class to use for generating an async iterator across matching
inbound events. This can be used as an alternative toBotApp.wait_for
which handles
registering and deregistering internal listeners for you automatically. - Event streaming is used for guild member chunking, and is now lock-based.
- Guild member chunking has been redesigned to follow a more user-oriented design.
- Guild member chunks now behave as if they were a
typing.Sequence
of members, and
thus support the standard operations that are exposed bytyping.Sequence
.
User flags
- User flags have been renamed appropriately. Check the documentation to view the changes.
Guild model consistency
- REST Guilds now require the approximate presences and members counts fields.
API calls will always request that those values be passed. - Removed
max_presences
andmax_members
fields fromhikari.GatewayBot
,
as they were unused and would never be populated with anything but default
values. - Fixed an issue where Discord are not always sending
display_splash
in GUILD_CREATE
despite documenting that they should.
Speedups
- Fixed that ciso8601 dependency requires Microsoft Visual C++ Redistributable 14.0 to
be installed to allow the library to install. If you do not use thehikari[speedups]
package target, then a pure-Python version is used instead. (Windows only) - Added
aiodns
andcchardet
support, documented how to useuvloop
and Python
optimisation flags inREADME
.
Art
- The
hikari.utilities.art
API has been removed and replaced withhikari.utilities.ux
which provides a different and simpler interface.
Version Sniffer
- Library version checks have been integrated into
hikari.utilities.ux
, the
hikari.utilities.version_sniffer
module has been removed entirely.
Changes to internals and development environment, documentation
- Snowflake#calculate_shard_id has been implemented.
- Updated flake8-pytest-style from v1.2.3 to 1.3.0.
- Requirements are now frozen rather than bounded by a minor version.
- New test suites.
- Shard tests have been disabled while they await a rewrite.
- hikari.api.rest.REST is now almost fully documented.
- Documentation fixes and Pdoc QA.
- Twemoji pipeline should now be much faster (4-8 seconds to complete).
- GuildEvent is now documented.
aio.first_completed
andaio.all_of
helpers.