Skip to content

Event streaming, full shard and bot reimplementation, numerous fixes for bugs.

Pre-release
Pre-release
Compare
Choose a tag to compare
released this 07 Sep 08:28
· 1860 commits to master since this release
4846fef

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 in hikari.Bot has been renamed to logs (see Logging
    subsection below for details on this).
  • Gateway-specific configuration options are now passed to Bot.run or bot.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 to enable_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 and allow_color constructor arguments to compliment the
    existing CLICOLOR and CLICOLOR_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 a hikari.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 passing ignore_session_start_limit=True
    to Bot.run or Bot.start.
  • New asyncio_debug parameter to Bot.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 to bot.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 to Bot.run that can be disabled if you wish to
    implement your own signal handling but still use bot.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 to Bot.run that can be set to False 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 to Bot.run that can be optionally set to True to
    enforce any custom executor passed to the Bot constructor gets closed when the event
    loop shuts down. This defaults to False 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 includes colorama on Windows, which should fix some issues with colour
    support in some terminals, hopefully.
  • logger_level kwarg in hikari.Bot has been renamed to logs, and will now take an
    integer logging level, a string name, or a full logging.config.dictConfig compatible
    schema, as well as None 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 the request_guild_members coroutine function in
    GatewayShard is now named users instead.
  • Implemented an EventStream class to use for generating an async iterator across matching
    inbound events. This can be used as an alternative to BotApp.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 by typing.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 and max_members fields from hikari.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 the hikari[speedups]
    package target, then a pure-Python version is used instead. (Windows only)
  • Added aiodns and cchardet support, documented how to use uvloop and Python
    optimisation flags in README.

Art

  • The hikari.utilities.art API has been removed and replaced with hikari.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 and aio.all_of helpers.