hikari config 

Data class containing network-related configuration settings.

This module

Expand source code
Browse git
# -*- coding: utf-8 -*-
# cython: language_level=3
#
# 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.
"""Data class containing network-related configuration settings."""

from __future__ import annotations

__all__: typing.List[str] = [
"ProxySettings",
"HTTPTimeoutSettings",
"HTTPSettings",
"CacheComponents",
"CacheSettings",
]

import base64
import ssl as ssl_
import typing

import attr
import yarl

from hikari.internal import attr_extensions
from hikari.internal import data_binding
from hikari.internal import enums

_BASICAUTH_TOKEN_PREFIX: typing.Final[str] = "Basic"  # nosec

def _ssl_factory(value: typing.Union[bool, ssl_.SSLContext]) -> ssl_.SSLContext:
if not isinstance(value, bool):
return value

ssl = ssl_.create_default_context()
# We can't turn SSL verification off without disabling hostname verification first.
# If we are using verification, this will just leave it enabled, so it is fine.
ssl.check_hostname = value
ssl.verify_mode = ssl_.CERT_REQUIRED if value else ssl_.CERT_NONE
return ssl

@attr_extensions.with_copy
@attr.define(kw_only=True, repr=True, weakref_slot=False)
"""An object that can be set as a producer for a basic auth header."""

Returns
-------
builtins.str
The username to use. This must not contain ":".
"""

Returns
-------
builtins.str
"""

charset: str = attr.field(default="utf-8", validator=attr.validators.instance_of(str))

Default is "utf-8", but you may choose to use something else,
including third-party encodings (e.g. IBM's EBCDIC codepages).

Returns
-------
builtins.str
The encoding to use.
"""

@property
"""Create the full Authentication header value.

Returns
-------
builtins.str
A base64-encoded string containing
"{username}:{password}".
"""
token_part = base64.b64encode(raw_token).decode(self.charset)
return f"{_BASICAUTH_TOKEN_PREFIX} {token_part}"

def __str__(self) -> str:

@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class ProxySettings:
"""Settings for configuring an HTTP-based proxy."""

auth: typing.Any = attr.field(default=None)

When cast to a builtins.str, this should provide the full value

If you are using basic auth, you should consider using the
BasicAuthHeader helper object here, as this will provide any
transformations you may require into a base64 string.

The default is to have this set to builtins.None, which will
result in no authentication being provided.

Returns
-------
typing.Any
The value for the Authentication header, or builtins.None
to disable.
"""

url: typing.Union[None, str, yarl.URL] = attr.field(default=None)
"""Proxy URL to use.

Defaults to builtins.None which disables the use of an explicit proxy.

Returns
-------
typing.Union[builtins.None, builtins.str, yarl.URL]
The proxy URL to use, or builtins.None to disable it.
"""

@url.validator
def _(self, _: attr.Attribute[typing.Union[None, str, yarl.URL]], value: typing.Union[None, str, yarl.URL]) -> None:
if value is not None and not isinstance(value, (str, yarl.URL)):
raise ValueError("ProxySettings.url must be None, a str, or a yarl.URL instance")

trust_env: bool = attr.field(default=False, validator=attr.validators.instance_of(bool))
"""Toggle whether to look for a netrc file or environment variables.

If builtins.True, and no url is given on this object, then
HTTP_PROXY and HTTPS_PROXY will be used from the environment
variables, or a netrc file may be read to determine credentials.

If builtins.False, then this information is instead ignored.

Defaults to builtins.False to prevent potentially unwanted behavior.

!!! note
For more details of using netrc, visit:
https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

Returns
-------
builtins.bool
builtins.True if allowing the use of environment variables
and/or netrc to determine proxy settings; builtins.False
if this should be disabled explicitly.
"""

@property

Returns
-------
Any headers that are set, or builtins.None if no headers are to
be sent with any request.
"""
if self.auth is None:
return None

if self.auth is None:

@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class HTTPTimeoutSettings:
"""Settings to control HTTP request timeouts."""

acquire_and_connect: typing.Optional[float] = attr.field(default=None)
"""Timeout for request_socket_connect PLUS connection acquisition.

By default, this has no timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

request_socket_connect: typing.Optional[float] = attr.field(default=None)
"""Timeout for connecting a socket.

By default, this has no timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

By default, this has no timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

total: typing.Optional[float] = attr.field(default=30.0)
"""Total timeout for entire request.

By default, this has a 30 second timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

@acquire_and_connect.validator
@request_socket_connect.validator
@total.validator
def _(self, attrib: attr.Attribute[typing.Optional[float]], value: typing.Optional[float]) -> None:
# This error won't occur until some time in the future where it will be annoying to
# try and determine the root cause, so validate it NOW.
if value is not None and (not isinstance(value, (float, int)) or value <= 0):
raise ValueError(f"HTTPTimeoutSettings.{attrib.name} must be None, or a POSITIVE float/int")

@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class HTTPSettings:
"""Settings to control HTTP clients."""

enable_cleanup_closed: bool = attr.field(default=True, validator=attr.validators.instance_of(bool))
"""Toggle whether to clean up closed transports.

This defaults to builtins.True to combat various protocol and asyncio
issues present when using Microsoft Windows. If you are sure you know
what you are doing, you may instead set this to False to disable this
behavior internally.

Returns
-------
builtins.bool
builtins.True to enable this behavior, builtins.False to disable
it.
"""

force_close_transports: bool = attr.field(default=True, validator=attr.validators.instance_of(bool))
"""Toggle whether to force close transports on shutdown.

This defaults to builtins.True to combat various protocol and asyncio
issues present when using Microsoft Windows. If you are sure you know
what you are doing, you may instead set this to False to disable this
behavior internally.

Returns
-------
builtins.bool
builtins.True to enable this behavior, builtins.False to disable
it.
"""

max_redirects: typing.Optional[int] = attr.field(default=10)
"""Behavior for handling redirect HTTP responses.

If a builtins.int, allow following redirects from 3xx HTTP responses
for up to this many redirects. Exceeding this value will raise an
exception.

If builtins.None, then disallow any redirects.

The default is to disallow this behavior for security reasons.

Generally, it is safer to keep this disabled. You may find a case in the
future where you need to enable this if Discord change their URL without
warning.

!!! note
This will only apply to the REST API. WebSockets remain unaffected
by any value set here.

Returns
-------
typing.Optional[builtins.int]
The number of redirects to allow at a maximum per request.
builtins.None disables the handling
of redirects and will result in exceptions being raised instead
should one occur.
"""

@max_redirects.validator
def _(self, _: attr.Attribute[typing.Optional[int]], value: typing.Optional[int]) -> None:
# This error won't occur until some time in the future where it will be annoying to
# try and determine the root cause, so validate it NOW.
if value is not None and (not isinstance(value, int) or value <= 0):
raise ValueError("http_settings.max_redirects must be None or a POSITIVE integer")

ssl: ssl_.SSLContext = attr.field(
factory=lambda: _ssl_factory(True),
converter=_ssl_factory,
validator=attr.validators.instance_of(ssl_.SSLContext),
)
"""SSL context to use.

This may be __assigned__ a builtins.bool or an ssl.SSLContext object.

If assigned to builtins.True, a default SSL context is generated by
this class that will enforce SSL verification. This is then stored in
this field.

If builtins.False, then a default SSL context is generated by this
class that will **NOT** enforce SSL verification. This is then stored
in this field.

If an instance of ssl.SSLContext, then this context will be used.

!!! warning
Setting a custom value here may have security implications, or
may result in the application being unable to connect to Discord
at all.

!!! warning
Disabling SSL verification is almost always unadvised. This
is because your application will no longer check whether you are
connecting to Discord, or to some third party spoof designed
to steal personal credentials such as your application token.

There may be cases where SSL certificates do not get updated,
and in this case, you may find that disabling this explicitly
allows you to work around any issues that are occurring, but
you should immediately seek a better solution where possible
if any form of personal security is in your interest.

Returns
-------
ssl.SSLContext
The SSL context to use for this application.
"""

timeouts: HTTPTimeoutSettings = attr.field(
factory=HTTPTimeoutSettings, validator=attr.validators.instance_of(HTTPTimeoutSettings)
)
"""Settings to control HTTP request timeouts.

The behaviour if this is not explicitly defined is to use sane
defaults that are most efficient for optimal use of this library.

Returns
-------
HTTPTimeoutSettings
The HTTP timeout settings to use for connection timeouts.
"""

class CacheComponents(enums.Flag):
"""Flags to control the cache components."""

NONE = 0
"""Disables the cache."""

GUILDS = 1 << 0
"""Enables the guild cache."""

GUILD_CHANNELS = 1 << 1
"""Enables the guild channels cache."""

MEMBERS = 1 << 2
"""Enables the members cache."""

ROLES = 1 << 3
"""Enables the roles cache."""

INVITES = 1 << 4
"""Enables the invites cache."""

EMOJIS = 1 << 5
"""Enables the emojis cache."""

PRESENCES = 1 << 6
"""Enables the presences cache."""

VOICE_STATES = 1 << 7
"""Enables the voice states cache."""

MESSAGES = 1 << 8
"""Enables the messages cache."""

DM_CHANNEL_IDS = 1 << 10
"""Enables the DM channel IDs cache."""

ALL = (
GUILDS
| GUILD_CHANNELS
| MEMBERS
| ROLES
| INVITES
| EMOJIS
| PRESENCES
| VOICE_STATES
| MESSAGES
| DM_CHANNEL_IDS
)
"""Fully enables the cache."""

@attr_extensions.with_copy
@attr.define(kw_only=True, weakref_slot=False)
class CacheSettings:
"""Settings to control the cache."""

components: CacheComponents = attr.field(default=CacheComponents.ALL)
"""The cache components to use.

Defaults to CacheComponents.ALL.
"""

max_messages: int = attr.field(default=300)
"""The maximum number of messages to store in the cache at once.

This will have no effect if the messages cache is not enabled.

Defaults to 300.
"""

max_dm_channel_ids: int = attr.field(default=50)
"""The maximum number of channel IDs to store in the cache at once.

This will have no effect if the channel IDs cache is not enabled.

Defaults to 50.
"""

Classes

class BasicAuthHeader (
*,
charset: str = 'utf-8',
): ...

An object that can be set as a producer for a basic auth header.

Method generated by attrs for class BasicAuthHeader.

Expand source code
Browse git
class BasicAuthHeader:
"""An object that can be set as a producer for a basic auth header."""

Returns
-------
builtins.str
The username to use. This must not contain ":".
"""

Returns
-------
builtins.str
"""

charset: str = attr.field(default="utf-8", validator=attr.validators.instance_of(str))

Default is "utf-8", but you may choose to use something else,
including third-party encodings (e.g. IBM's EBCDIC codepages).

Returns
-------
builtins.str
The encoding to use.
"""

@property
"""Create the full Authentication header value.

Returns
-------
builtins.str
A base64-encoded string containing
"{username}:{password}".
"""
token_part = base64.b64encode(raw_token).decode(self.charset)
return f"{_BASICAUTH_TOKEN_PREFIX} {token_part}"

def __str__(self) -> str:
return self.header
Variables and properties
property charset : str

Default is "utf-8", but you may choose to use something else, including third-party encodings (e.g. IBM's EBCDIC codepages).

Returns

str
The encoding to use.
property header : str

Create the full Authentication header value.

Returns

str
A base64-encoded string containing "{username}:{password}".
property password : str

Returns

str
property username : str

Returns

str
The username to use. This must not contain ":".

enum flagCacheComponents

class CacheComponents (
value: int = 0,
): ...

Flags to control the cache components.

Expand source code
Browse git
class CacheComponents(enums.Flag):
"""Flags to control the cache components."""

NONE = 0
"""Disables the cache."""

GUILDS = 1 << 0
"""Enables the guild cache."""

GUILD_CHANNELS = 1 << 1
"""Enables the guild channels cache."""

MEMBERS = 1 << 2
"""Enables the members cache."""

ROLES = 1 << 3
"""Enables the roles cache."""

INVITES = 1 << 4
"""Enables the invites cache."""

EMOJIS = 1 << 5
"""Enables the emojis cache."""

PRESENCES = 1 << 6
"""Enables the presences cache."""

VOICE_STATES = 1 << 7
"""Enables the voice states cache."""

MESSAGES = 1 << 8
"""Enables the messages cache."""

DM_CHANNEL_IDS = 1 << 10
"""Enables the DM channel IDs cache."""

ALL = (
GUILDS
| GUILD_CHANNELS
| MEMBERS
| ROLES
| INVITES
| EMOJIS
| PRESENCES
| VOICE_STATES
| MESSAGES
| DM_CHANNEL_IDS
)
"""Fully enables the cache."""
Method resolution order
enum flag CacheComponents
That's this class!
extern class int

int([x]) -> integer int(x, base=10) -> integer …

enum flag Flag

Clone of Python's enum.Flag implementation …

Variables and properties
property name : str

Return the name of the flag combination as a str.

property value : int

Return the int value of the flag.

const ALL = 1535

Fully enables the cache.

const DM_CHANNEL_IDS = 1024

Enables the DM channel IDs cache.

const EMOJIS = 32

Enables the emojis cache.

const GUILDS = 1

Enables the guild cache.

const GUILD_CHANNELS = 2

Enables the guild channels cache.

const INVITES = 16

Enables the invites cache.

const MEMBERS = 4

Enables the members cache.

const MESSAGES = 256

Enables the messages cache.

const NONE = 0

Disables the cache.

const PRESENCES = 64

Enables the presences cache.

const ROLES = 8

Enables the roles cache.

const VOICE_STATES = 128

Enables the voice states cache.

Methods
def all(
self: _T,
*flags: _T,
) -> bool: ...

Check if all of the given flags are part of this value …

This function is defined explicitly at hikari.internal.enums.Flag.all. Visit that link to view the full documentation!
def any(
self: _T,
*flags: _T,
) -> bool: ...

Check if any of the given flags are part of this value …

This function is defined explicitly at hikari.internal.enums.Flag.any. Visit that link to view the full documentation!
def difference(
self: _T,
other: Union[_T, int],
) -> ~_T: ...

Perform a set difference with the other set …

This function is defined explicitly at hikari.internal.enums.Flag.difference. Visit that link to view the full documentation!
def intersection(
self: _T,
other: Union[_T, int],
) -> ~_T: ...

Return a combination of flags that are set for both given values …

This function is defined explicitly at hikari.internal.enums.Flag.intersection. Visit that link to view the full documentation!
def invert(
self: _T,
) -> ~_T: ...

Return a set of all flags not in the current set.

This function is defined explicitly at hikari.internal.enums.Flag.invert. Visit that link to view the full documentation!
def is_disjoint(
self: _T,
other: Union[_T, int],
) -> bool: ...

Return whether two sets have a intersection or not …

This function is defined explicitly at hikari.internal.enums.Flag.is_disjoint. Visit that link to view the full documentation!
def is_subset(
self: _T,
other: Union[_T, int],
) -> bool: ...

Return whether another set contains this set or not …

This function is defined explicitly at hikari.internal.enums.Flag.is_subset. Visit that link to view the full documentation!
def is_superset(
self: _T,
other: Union[_T, int],
) -> bool: ...

Return whether this set contains another set or not.

This function is defined explicitly at hikari.internal.enums.Flag.is_superset. Visit that link to view the full documentation!
def isdisjoint(
self: _T,
other: Union[_T, int],
) -> bool: ...

Return whether two sets have a intersection or not …

This function is defined explicitly at hikari.internal.enums.Flag.is_disjoint. Visit that link to view the full documentation!
def issubset(
self: _T,
other: Union[_T, int],
) -> bool: ...

Return whether another set contains this set or not …

This function is defined explicitly at hikari.internal.enums.Flag.is_subset. Visit that link to view the full documentation!
def issuperset(
self: _T,
other: Union[_T, int],
) -> bool: ...

Return whether this set contains another set or not.

This function is defined explicitly at hikari.internal.enums.Flag.is_superset. Visit that link to view the full documentation!
def none(
self: _T,
*flags: _T,
) -> bool: ...

Check if none of the given flags are part of this value …

This function is defined explicitly at hikari.internal.enums.Flag.none. Visit that link to view the full documentation!
def split(
self: _T,
) -> Sequence[~_T]: ...

Return a list of all defined atomic values for this flag …

This function is defined explicitly at hikari.internal.enums.Flag.split. Visit that link to view the full documentation!
def symmetric_difference(
self: _T,
other: Union[_T, int],
) -> ~_T: ...

Return a set with the symmetric differences of two flag sets …

This function is defined explicitly at hikari.internal.enums.Flag.symmetric_difference. Visit that link to view the full documentation!
def symmetricdifference(
self: _T,
other: Union[_T, int],
) -> ~_T: ...

Return a set with the symmetric differences of two flag sets …

This function is defined explicitly at hikari.internal.enums.Flag.symmetric_difference. Visit that link to view the full documentation!
def union(
self: _T,
other: Union[_T, int],
) -> ~_T: ...

Return a combination of all flags in this set and the other set …

This function is defined explicitly at hikari.internal.enums.Flag.union. Visit that link to view the full documentation!

dataclassCacheSettings

class CacheSettings (
*,
components: CacheComponents = <CacheComponents.ALL: 1535>,
max_messages: int = 300,
max_dm_channel_ids: int = 50,
): ...

Settings to control the cache.

Method generated by attrs for class CacheSettings.

Expand source code
Browse git
class CacheSettings:
"""Settings to control the cache."""

components: CacheComponents = attr.field(default=CacheComponents.ALL)
"""The cache components to use.

Defaults to CacheComponents.ALL.
"""

max_messages: int = attr.field(default=300)
"""The maximum number of messages to store in the cache at once.

This will have no effect if the messages cache is not enabled.

Defaults to 300.
"""

max_dm_channel_ids: int = attr.field(default=50)
"""The maximum number of channel IDs to store in the cache at once.

This will have no effect if the channel IDs cache is not enabled.

Defaults to 50.
"""
Variables and properties
property components : CacheComponents

The cache components to use.

Defaults to ALL.

property max_dm_channel_ids : int

The maximum number of channel IDs to store in the cache at once.

This will have no effect if the channel IDs cache is not enabled.

Defaults to 50.

property max_messages : int

The maximum number of messages to store in the cache at once.

This will have no effect if the messages cache is not enabled.

Defaults to 300.

dataclassHTTPSettings

class HTTPSettings (
*,
enable_cleanup_closed: bool = True,
force_close_transports: bool = True,
max_redirects: Optional[int] = 10,
ssl: Union[bool, ssl_.SSLContext] = NOTHING,
timeouts: HTTPTimeoutSettings = NOTHING,
): ...

Settings to control HTTP clients.

Method generated by attrs for class HTTPSettings.

Expand source code
Browse git
class HTTPSettings:
"""Settings to control HTTP clients."""

enable_cleanup_closed: bool = attr.field(default=True, validator=attr.validators.instance_of(bool))
"""Toggle whether to clean up closed transports.

This defaults to builtins.True to combat various protocol and asyncio
issues present when using Microsoft Windows. If you are sure you know
what you are doing, you may instead set this to False to disable this
behavior internally.

Returns
-------
builtins.bool
builtins.True to enable this behavior, builtins.False to disable
it.
"""

force_close_transports: bool = attr.field(default=True, validator=attr.validators.instance_of(bool))
"""Toggle whether to force close transports on shutdown.

This defaults to builtins.True to combat various protocol and asyncio
issues present when using Microsoft Windows. If you are sure you know
what you are doing, you may instead set this to False to disable this
behavior internally.

Returns
-------
builtins.bool
builtins.True to enable this behavior, builtins.False to disable
it.
"""

max_redirects: typing.Optional[int] = attr.field(default=10)
"""Behavior for handling redirect HTTP responses.

If a builtins.int, allow following redirects from 3xx HTTP responses
for up to this many redirects. Exceeding this value will raise an
exception.

If builtins.None, then disallow any redirects.

The default is to disallow this behavior for security reasons.

Generally, it is safer to keep this disabled. You may find a case in the
future where you need to enable this if Discord change their URL without
warning.

!!! note
This will only apply to the REST API. WebSockets remain unaffected
by any value set here.

Returns
-------
typing.Optional[builtins.int]
The number of redirects to allow at a maximum per request.
builtins.None disables the handling
of redirects and will result in exceptions being raised instead
should one occur.
"""

@max_redirects.validator
def _(self, _: attr.Attribute[typing.Optional[int]], value: typing.Optional[int]) -> None:
# This error won't occur until some time in the future where it will be annoying to
# try and determine the root cause, so validate it NOW.
if value is not None and (not isinstance(value, int) or value <= 0):
raise ValueError("http_settings.max_redirects must be None or a POSITIVE integer")

ssl: ssl_.SSLContext = attr.field(
factory=lambda: _ssl_factory(True),
converter=_ssl_factory,
validator=attr.validators.instance_of(ssl_.SSLContext),
)
"""SSL context to use.

This may be __assigned__ a builtins.bool or an ssl.SSLContext object.

If assigned to builtins.True, a default SSL context is generated by
this class that will enforce SSL verification. This is then stored in
this field.

If builtins.False, then a default SSL context is generated by this
class that will **NOT** enforce SSL verification. This is then stored
in this field.

If an instance of ssl.SSLContext, then this context will be used.

!!! warning
Setting a custom value here may have security implications, or
may result in the application being unable to connect to Discord
at all.

!!! warning
Disabling SSL verification is almost always unadvised. This
is because your application will no longer check whether you are
connecting to Discord, or to some third party spoof designed
to steal personal credentials such as your application token.

There may be cases where SSL certificates do not get updated,
and in this case, you may find that disabling this explicitly
allows you to work around any issues that are occurring, but
you should immediately seek a better solution where possible
if any form of personal security is in your interest.

Returns
-------
ssl.SSLContext
The SSL context to use for this application.
"""

timeouts: HTTPTimeoutSettings = attr.field(
factory=HTTPTimeoutSettings, validator=attr.validators.instance_of(HTTPTimeoutSettings)
)
"""Settings to control HTTP request timeouts.

The behaviour if this is not explicitly defined is to use sane
defaults that are most efficient for optimal use of this library.

Returns
-------
HTTPTimeoutSettings
The HTTP timeout settings to use for connection timeouts.
"""
Variables and properties
property enable_cleanup_closed : bool

Toggle whether to clean up closed transports.

This defaults to True to combat various protocol and asyncio issues present when using Microsoft Windows. If you are sure you know what you are doing, you may instead set this to False to disable this behavior internally.

Returns

bool
True to enable this behavior, False to disable it.
property force_close_transports : bool

Toggle whether to force close transports on shutdown.

This defaults to True to combat various protocol and asyncio issues present when using Microsoft Windows. If you are sure you know what you are doing, you may instead set this to False to disable this behavior internally.

Returns

bool
True to enable this behavior, False to disable it.
property max_redirects : Optional[int]

Behavior for handling redirect HTTP responses.

If a int, allow following redirects from 3xx HTTP responses for up to this many redirects. Exceeding this value will raise an exception.

If None, then disallow any redirects.

The default is to disallow this behavior for security reasons.

Generally, it is safer to keep this disabled. You may find a case in the future where you need to enable this if Discord change their URL without warning.

Note

This will only apply to the REST API. WebSockets remain unaffected by any value set here.

Returns

Optional[int]
The number of redirects to allow at a maximum per request. None disables the handling of redirects and will result in exceptions being raised instead should one occur.
property ssl : ssl.SSLContext

SSL context to use.

This may be assigned a bool or an ssl.SSLContext object.

If assigned to True, a default SSL context is generated by this class that will enforce SSL verification. This is then stored in this field.

If False, then a default SSL context is generated by this class that will NOT enforce SSL verification. This is then stored in this field.

If an instance of ssl.SSLContext, then this context will be used.

Warning

Setting a custom value here may have security implications, or may result in the application being unable to connect to Discord at all.

Warning

Disabling SSL verification is almost always unadvised. This is because your application will no longer check whether you are connecting to Discord, or to some third party spoof designed to steal personal credentials such as your application token.

There may be cases where SSL certificates do not get updated, and in this case, you may find that disabling this explicitly allows you to work around any issues that are occurring, but you should immediately seek a better solution where possible if any form of personal security is in your interest.

Returns

ssl.SSLContext
The SSL context to use for this application.
property timeouts : HTTPTimeoutSettings

Settings to control HTTP request timeouts.

The behaviour if this is not explicitly defined is to use sane defaults that are most efficient for optimal use of this library.

Returns

HTTPTimeoutSettings
The HTTP timeout settings to use for connection timeouts.

dataclassHTTPTimeoutSettings

class HTTPTimeoutSettings (
*,
acquire_and_connect: Optional[float] = None,
request_socket_connect: Optional[float] = None,
total: Optional[float] = 30.0,
): ...

Settings to control HTTP request timeouts.

Method generated by attrs for class HTTPTimeoutSettings.

Expand source code
Browse git
class HTTPTimeoutSettings:
"""Settings to control HTTP request timeouts."""

acquire_and_connect: typing.Optional[float] = attr.field(default=None)
"""Timeout for request_socket_connect PLUS connection acquisition.

By default, this has no timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

request_socket_connect: typing.Optional[float] = attr.field(default=None)
"""Timeout for connecting a socket.

By default, this has no timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

By default, this has no timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

total: typing.Optional[float] = attr.field(default=30.0)
"""Total timeout for entire request.

By default, this has a 30 second timeout allocated.

Returns
-------
typing.Optional[builtins.float]
The timeout, or builtins.None to disable it.
"""

@acquire_and_connect.validator
@request_socket_connect.validator
@total.validator
def _(self, attrib: attr.Attribute[typing.Optional[float]], value: typing.Optional[float]) -> None:
# This error won't occur until some time in the future where it will be annoying to
# try and determine the root cause, so validate it NOW.
if value is not None and (not isinstance(value, (float, int)) or value <= 0):
raise ValueError(f"HTTPTimeoutSettings.{attrib.name} must be None, or a POSITIVE float/int")
Variables and properties
property acquire_and_connect : Optional[float]

Timeout for request_socket_connect PLUS connection acquisition.

By default, this has no timeout allocated.

Returns

Optional[float]
The timeout, or None to disable it.
property request_socket_connect : Optional[float]

Timeout for connecting a socket.

By default, this has no timeout allocated.

Returns

Optional[float]
The timeout, or None to disable it.
property request_socket_read : Optional[float]

By default, this has no timeout allocated.

Returns

Optional[float]
The timeout, or None to disable it.
property total : Optional[float]

Total timeout for entire request.

By default, this has a 30 second timeout allocated.

Returns

Optional[float]
The timeout, or None to disable it.

dataclassProxySettings

class ProxySettings (
*,
auth: Any = None,
url: Union[None, str, yarl.URL] = None,
trust_env: bool = False,
): ...

Settings for configuring an HTTP-based proxy.

Method generated by attrs for class ProxySettings.

Expand source code
Browse git
class ProxySettings:
"""Settings for configuring an HTTP-based proxy."""

auth: typing.Any = attr.field(default=None)

When cast to a builtins.str, this should provide the full value

If you are using basic auth, you should consider using the
BasicAuthHeader helper object here, as this will provide any
transformations you may require into a base64 string.

The default is to have this set to builtins.None, which will
result in no authentication being provided.

Returns
-------
typing.Any
The value for the Authentication header, or builtins.None
to disable.
"""

url: typing.Union[None, str, yarl.URL] = attr.field(default=None)
"""Proxy URL to use.

Defaults to builtins.None which disables the use of an explicit proxy.

Returns
-------
typing.Union[builtins.None, builtins.str, yarl.URL]
The proxy URL to use, or builtins.None to disable it.
"""

@url.validator
def _(self, _: attr.Attribute[typing.Union[None, str, yarl.URL]], value: typing.Union[None, str, yarl.URL]) -> None:
if value is not None and not isinstance(value, (str, yarl.URL)):
raise ValueError("ProxySettings.url must be None, a str, or a yarl.URL instance")

trust_env: bool = attr.field(default=False, validator=attr.validators.instance_of(bool))
"""Toggle whether to look for a netrc file or environment variables.

If builtins.True, and no url is given on this object, then
HTTP_PROXY and HTTPS_PROXY will be used from the environment
variables, or a netrc file may be read to determine credentials.

If builtins.False, then this information is instead ignored.

Defaults to builtins.False to prevent potentially unwanted behavior.

!!! note
For more details of using netrc, visit:
https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

Returns
-------
builtins.bool
builtins.True if allowing the use of environment variables
and/or netrc to determine proxy settings; builtins.False
if this should be disabled explicitly.
"""

@property

Returns
-------
Any headers that are set, or builtins.None if no headers are to
be sent with any request.
"""
if self.auth is None:
return None

if self.auth is None:
return {**self.headers, _PROXY_AUTHENTICATION_HEADER: self.auth}
Variables and properties
property all_headers : Optional[Mapping[str, str]]

Returns

Optional[Headers]
Any headers that are set, or None if no headers are to be sent with any request.
property auth : Any

When cast to a str, this should provide the full value for the authentication header.

If you are using basic auth, you should consider using the BasicAuthHeader helper object here, as this will provide any transformations you may require into a base64 string.

The default is to have this set to None, which will result in no authentication being provided.

Returns

Any
The value for the Authentication header, or None to disable.
property headers : Optional[Mapping[str, str]]

property trust_env : bool

Toggle whether to look for a netrc file or environment variables.

If True, and no url is given on this object, then HTTP_PROXY and HTTPS_PROXY will be used from the environment variables, or a netrc file may be read to determine credentials.

If False, then this information is instead ignored.

Defaults to False to prevent potentially unwanted behavior.

Note

For more details of using netrc, visit: https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html

Returns

bool
True if allowing the use of environment variables and/or netrc to determine proxy settings; False if this should be disabled explicitly.
property url : Union[None, str, yarl.URL]

Proxy URL to use.

Defaults to None which disables the use of an explicit proxy.

Returns

Union[None, str, yarl.URL]
The proxy URL to use, or None to disable it.