Generator

airvpn.api.generator

Config

A single generated VPN configuration file.

Attributes:

Name	Type	Description
filename		The filename this config was stored under in the generator's response (e.g. within its zip archive).
buffer		The raw file contents as bytes.

read() -> str

Return this config's contents as text, decoding if necessary.

Attempts to decode buffer as UTF-8 text, normalizing Windows-style line endings ("\r\n") to "\n". If the buffer isn't valid UTF-8 (e.g. a bundled binary), it's returned as a base64-encoded string instead.

Returns:

Type	Description
str	The decoded text with normalized line endings, or a base64-encoded string if the contents aren't valid UTF-8 text.

write(output_dir: str = None)

Write this config's contents to disk.

Parameters:

Name	Type	Description	Default
output_dir	str	Directory to write the file into. Created (including parents) if it doesn't already exist. If omitted, the file is written to the current working directory using filename as-is.	None

ConfigList

A lazily-fetched, sliceable, iterable collection of generated Config files.

Represents the set of files produced by a single Generator.create call. Individual files are not fetched until accessed (via indexing or iteration), and are cached after their first fetch. Slicing returns a new, independent ConfigList scoped to the sliced subset of files.

Parameters:

Name	Type	Description	Default
generator	Generator	The Generator instance used to fetch individual config files on demand.	required
options	Options	The Options describing the request that produced this file set; used as a template for per-file requests.	required
files	list[str]	The filenames of each config in this list, as reported by the generator API. The list's length determines the size of this ConfigList.	required

__eq__(other)

Return whether other is a ConfigList with an equal hash (i.e. equal Options).

__get_config__(index: int) -> Config

Fetch (or return the cached) Config at a single integer index.

Parameters:

Name	Type	Description	Default
index	int	Zero-based index of the file to fetch. Supports Python-style negative indexing (e.g. -1 for the last file).	required

Raises:

Type	Description
IndexError	If index is out of range (self._size <= index).

Returns:

Type	Description
Config	The Config at index, fetching and caching it first if it hasn't been fetched yet.

__getitem__(index: int | slice) -> Config | ConfigList

Fetch a single Config, or a new ConfigList scoped to a slice.

Parameters:

Name	Type	Description	Default
index	int | slice	Either an integer index (fetches and returns a single Config, see __get_config__) or a slice (returns a new, independent ConfigList containing only the sliced subset of files, cloning Options so the original is unaffected).	required

Returns:

Type	Description
Config | ConfigList	A Config for an integer index, or a new ConfigList for a slice.

__hash__()

Hash based on this list's Options.

__iter__() -> Iterator[Config]

Return a generator yielding each Config in this list, in order.

Each call returns an independent generator with its own position, so multiple concurrent or nested iterations over the same ConfigList don't interfere with each other.

__len__()

Return the number of configs in this list.

__next__()

Return the next Config for manual iteration via next(config_list).

Uses and advances self._index as a persistent cursor, independent of __iter__'s generator-based iteration.

Raises:

Type	Description
StopIteration	Once self._index reaches self._size.

Generator

Generates VPN configuration files via the AirVPN config generator API.

Access type

User-specific, API KEY required.

Wraps the same endpoint used by https://airvpn.org/generator, allowing programmatic creation of OpenVPN/WireGuard configs for one or more servers, systems, and protocols.

create(servers: str | list[str], device: str, system: SystemType = SystemType.WINDOWS, vpn_type: VpnType = VpnType.WIREGUARD, protocol_type: ProtocolType = ProtocolType.UDP, port: int = 1637, entry_ip: int = 3, files_binary: Literal['x64', 'x32'] = '', files_prefix: str = '', openvpn_directives: str = '', openvpn_data_ciphers: Literal['desktop', 'mobile'] = '', openvpn_noembedkeys: bool = None, resolve: bool = False, openvpn_allservers: bool = False, proxy_mode: str = 'none', proxy_host: str = '127.0.0.1', proxy_port: str = '8080', proxy_login: str = '', proxy_password: str = '', proxy_auth: str = 'none', wireguard_mtu: int = 1320, wireguard_persistent_keepalive: int = 15, iplayer_entry: str = 'ipv4', iplayer_exit: str = 'both', **kwargs: dict) -> ConfigList | str

Generate VPN configuration file(s) for one or more servers.

Requests the configuration generator with download="auto" and returns the generated configuration file(s). When the generator returns a single file directly, its contents are returned as a str. When the generator instead reports a set of files (some configuration options produce multiple files, even for a single server), a ConfigList is returned — a lazily-fetched, sliceable, iterable collection covering those files; individual files aren't downloaded until accessed (by index, slice, or iteration), and each fetched file is cached afterward.

Parameters:

Name	Type	Description	Default
servers	str | list[str]	Server name(s) and/or planet grouping(s) to generate configs for — e.g. an individual server name, or "earth" for all servers. Accepts a single value or a list, which will be comma-joined; multiple values can be combined with commas (e.g. "earth,SERVERNAME").	required
device	str	The device profile name to associate with these configs.	required
system	SystemType	Target operating system for the generated configs.	WINDOWS
vpn_type	VpnType	VPN protocol family (e.g. WireGuard, OpenVPN).	WIREGUARD
protocol_type	ProtocolType	Transport protocol (UDP or TCP).	UDP
port	int	Port number to connect on.	1637
entry_ip	int	IP version/entry point selector for the connection.	3
files_binary	Literal['x64', 'x32']	Optional binary/executable to bundle with the configs.	''
files_prefix	str	Optional filename prefix for generated files.	''
openvpn_directives	str	Additional custom directives to inject into an OpenVPN config.	''
openvpn_data_ciphers	Literal['desktop', 'mobile']	Custom data cipher list for OpenVPN.	''
openvpn_noembedkeys	bool	Whether to omit embedding keys directly in the OpenVPN config (reference external key files instead).	None
resolve	bool	Whether to resolve server hostnames instead of using raw IPs in the config.	False
openvpn_allservers	bool	Whether to include all servers in a single OpenVPN config.	False
proxy_mode	str	Proxy mode to configure in the generated config ("none" or a specific proxy type).	'none'
proxy_host	str	Proxy host address, if proxy_mode is enabled.	'127.0.0.1'
proxy_port	str	Proxy port, if proxy_mode is enabled.	'8080'
proxy_login	str	Proxy authentication username, if required.	''
proxy_password	str	Proxy authentication password, if required.	''
proxy_auth	str	Proxy authentication method/type, if proxy_mode is enabled.	'none'
wireguard_mtu	int	MTU value for WireGuard configs.	1320
wireguard_persistent_keepalive	int	Persistent keepalive interval, in seconds, for WireGuard configs.	15
iplayer_entry	str	IP layer to use for the entry connection ("ipv4", "ipv6", or "both").	'ipv4'
iplayer_exit	str	IP layer to use for the exit connection ("ipv4", "ipv6", or "both").	'both'
**kwargs	dict	Additional API parameters passed through as-is. Used primarily for per-server download selection: pass server_SERVERNAME="on" for each server you want included in the downloaded bundle (e.g. server_earth="on", server_america="on"). Any other undocumented API parameters can also be passed this way.	{}

Returns:

Type	Description
ConfigList | str	A str with the config file's contents (Windows-style line endings normalized to "\n") when the generator returns exactly one file directly; otherwise a ConfigList covering all generated files. Fetching an individual Config from a ConfigList decodes it the same way, except any file that isn't valid UTF-8 text (e.g. a bundled binary from files_binary) is returned as a base64 encoded string instead.

download(output_dir: str, servers: str | list[str], device: str, system: SystemType = SystemType.WINDOWS, vpn_type: VpnType = VpnType.WIREGUARD, protocol_type: ProtocolType = ProtocolType.UDP, port: int = 1637, entry_ip: int = 3, files_binary: Literal['x64', 'x32'] = '', files_prefix: str = '', openvpn_directives: str = '', openvpn_data_ciphers: Literal['desktop', 'mobile'] = '', openvpn_noembedkeys: bool = None, resolve: bool = False, openvpn_allservers: bool = False, proxy_mode: str = 'none', proxy_host: str = '127.0.0.1', proxy_port: str = '8080', proxy_login: str = '', proxy_password: str = '', proxy_auth: str = 'none', wireguard_mtu: int = 1320, wireguard_persistent_keepalive: int = 15, iplayer_entry: str = 'ipv4', iplayer_exit: str = 'both', **kwargs: dict)

Generate VPN configuration file(s) for one or more servers and write them to disk.

Requests a zip bundle from the generator endpoint (forcing download="zip" internally) and extracts its contents directly into output_dir, creating the directory if it doesn't already exist.

Parameters:

Name	Type	Description	Default
output_dir	str	Directory to extract the generated config files into. Created (including parents) if it doesn't already exist.	required
servers	str | list[str]	Server name(s) and/or planet grouping(s) to generate configs for — e.g. an individual server name, or "earth" for all servers. Accepts a single value or a list, which will be comma-joined; multiple values can be combined with commas (e.g. "earth,SERVERNAME"). Note this always requests a zip bundle and extracts everything the API returns, which may include more than one file even for a single server (e.g. SSH configs).	required
device	str	The device profile name to associate with these configs.	required
system	SystemType	Target operating system for the generated configs.	WINDOWS
vpn_type	VpnType	VPN protocol family (e.g. WireGuard, OpenVPN).	WIREGUARD
protocol_type	ProtocolType	Transport protocol (UDP or TCP).	UDP
port	int	Port number to connect on.	1637
entry_ip	int	IP version/entry point selector for the connection.	3
files_binary	Literal['x64', 'x32']	Optional binary/executable to bundle with the configs.	''
files_prefix	str	Optional filename prefix for generated files.	''
openvpn_directives	str	Additional custom directives to inject into an OpenVPN config.	''
openvpn_data_ciphers	Literal['desktop', 'mobile']	Custom data cipher list for OpenVPN.	''
openvpn_noembedkeys	bool	Whether to omit embedding keys directly in the OpenVPN config (reference external key files instead).	None
resolve	bool	Whether to resolve server hostnames instead of using raw IPs in the config.	False
openvpn_allservers	bool	Whether to include all servers in a single OpenVPN config.	False
proxy_mode	str	Proxy mode to configure in the generated config ("none" or a specific proxy type).	'none'
proxy_host	str	Proxy host address, if proxy_mode is enabled.	'127.0.0.1'
proxy_port	str	Proxy port, if proxy_mode is enabled.	'8080'
proxy_login	str	Proxy authentication username, if required.	''
proxy_password	str	Proxy authentication password, if required.	''
proxy_auth	str	Proxy authentication method/type, if proxy_mode is enabled.	'none'
wireguard_mtu	int	MTU value for WireGuard configs.	1320
wireguard_persistent_keepalive	int	Persistent keepalive interval, in seconds, for WireGuard configs.	15
iplayer_entry	str	IP layer to use for the entry connection ("ipv4", "ipv6", or "both").	'ipv4'
iplayer_exit	str	IP layer to use for the exit connection ("ipv4", "ipv6", or "both").	'both'
**kwargs	dict	Additional API parameters passed through as-is. Used primarily for per-server download selection: pass server_SERVERNAME="on" for each server you want included in the downloaded bundle (e.g. server_earth="on", server_america="on"). Any other undocumented API parameters can also be passed this way.	{}

Options

Mutable container for the parameters used to request a VPN config.

Instances are typically constructed from the generator API's own options response payload (via Options(**option_data)) and are reused/mutated to request individual files from a ConfigList (e.g. by setting download before each request).

Attributes:

Name	Type	Description
protocols		List of protocol strings (split from a comma-separated string if a string was passed in).
servers		List of server names (split from a comma-separated string if a string was passed in).
download		Download/file-index selector used for per-file requests.
system		Target operating system.
openvpn_version		OpenVPN version string, if applicable.
device		Device profile name associated with these configs.
files_binary		Optional bundled binary/executable identifier.
files_prefix		Optional filename prefix for generated files.
openvpn_noembedkeys		Whether to omit embedding keys directly in OpenVPN configs.
openvpn_directives		Additional custom OpenVPN directives.
openvpn_data_ciphers		Custom OpenVPN data cipher list.
resolve		Whether to resolve hostnames instead of using raw IPs.
openvpn_allservers		Whether to include all servers in a single OpenVPN config.
proxy_mode		Proxy mode ("none" or a specific proxy type).
proxy_host		Proxy host address.
proxy_port		Proxy port.
proxy_auth		Proxy authentication method/type.
proxy_login		Proxy authentication username.
proxy_password		Proxy authentication password.
wireguard_mtu		MTU value for WireGuard configs.
wireguard_persistent_keepalive		Persistent keepalive interval, in seconds, for WireGuard configs.
iplayer_entry		IP layer to use for the entry connection.
iplayer_exit		IP layer to use for the exit connection.

__hash__()

Hash based on the integer value of this instance's __str__() bytes.

Note this is derived from __str__, so two Options instances with equal attributes will hash equally.

__str__()

Return the string form of this instance's __dict__.

clone() -> Options

Return a new Options instance with a shallow copy of this instance's attributes.

Since protocols/servers etc. are passed straight through __init__, list-valued attributes are re-referenced rather than deep-copied unless __init__ creates a new list (as it does when given a comma-separated string). Mutating a cloned list in place (e.g. .append()) may still affect the original; prefer reassignment (e.g. slicing) when working with a clone.

Returns:

Type	Description
Options	A new, independent Options instance with the same attribute values.

ProtocolType

Bases: StrEnum

Transport protocol used for the VPN connection.

SystemType

Bases: StrEnum

Target operating system for a generated config bundle.

VpnType

Bases: StrEnum

VPN protocol family supported by the config generator.