airvpn 0.1.0__tar.gz

airvpn-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Crunchyroll+
+
+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.

airvpn-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: airvpn
+Version: 0.1.0
+Summary: A Python wrapper for the AirVPN API
+Author: chonker
+License: MIT
+Project-URL: Homepage, https://github.com/ch0nker/airvpn
+Project-URL: Repository, https://github.com/ch0nker/airvpn
+Project-URL: Changelog, https://github.com/ch0nker/airvpn/tree/main/docs/CHANGELOG.md
+Project-URL: Documentation, https://github.com/ch0nker/airvpn/tree/main/docs/api/README.md
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: python-wireguard
+Dynamic: license-file
+
+# Python AirVPN Wrapper
+
+> **Note:** The docstrings and most of the documentation was generated with AI. If you spot any errors I haven't caught yet, please open a PR or an issue.
+
+A Python wrapper for AirVPN's [API](https://airvpn.org/apisettings/).
+
+## Guide
+- [Changelog](docs/CHANGELOG.md)
+- [Contributing](docs/CONTRIBUTING.md)
+- [Example](#example)
+- [API Documentation](docs/api/README.md)
+- [Test Documentation](docs/tests/README.md)
+
+## Installation
+```bash
+pip install airvpn
+```
+
+## Example
+```py
+from airvpn import AirVPN
+
+api = AirVPN(API_KEY)  # API_KEY is optional for public services like whatismyip
+
+print(api.userinfo.login)
+```

airvpn-0.1.0/README.md

@@ -0,0 +1,26 @@
+# Python AirVPN Wrapper
+
+> **Note:** The docstrings and most of the documentation was generated with AI. If you spot any errors I haven't caught yet, please open a PR or an issue.
+
+A Python wrapper for AirVPN's [API](https://airvpn.org/apisettings/).
+
+## Guide
+- [Changelog](docs/CHANGELOG.md)
+- [Contributing](docs/CONTRIBUTING.md)
+- [Example](#example)
+- [API Documentation](docs/api/README.md)
+- [Test Documentation](docs/tests/README.md)
+
+## Installation
+```bash
+pip install airvpn
+```
+
+## Example
+```py
+from airvpn import AirVPN
+
+api = AirVPN(API_KEY)  # API_KEY is optional for public services like whatismyip
+
+print(api.userinfo.login)
+```

airvpn-0.1.0/airvpn/__init__.py

@@ -0,0 +1,164 @@
+from airvpn.network import AirSession
+from airvpn.devices import Devices, Device
+from airvpn.dns_lists import DnsLists
+from airvpn.generator import Generator
+from airvpn.status import Status, Server
+from airvpn.userinfo import UserInfo
+from airvpn.whatismyip import WhatIsMyIp
+
+from airvpn.disconnect import disconnect
+from airvpn.notification import send_notification
+
+class AirVPN:
+    """Main entry point for interacting with the AirVPN API.
+
+    Provides access to all available services (devices, DNS lists, config
+    generator, network status, user info, and IP lookup) as lazily-created,
+    cached properties, plus convenience methods for one-off actions like
+    sending notifications and disconnecting sessions.
+
+    Attributes:
+        api_key: The API key used for authenticated requests, if provided.
+        session: The underlying AirSession used to make API requests.
+        devices: The devices service, created and cached on first access.
+        dns_lists: The DNS lists service, created and cached on first access.
+        generator: The config generator service, created and cached on
+            first access.
+        status: The network status service, created and cached on first
+            access.
+        userinfo: The user info service, created and cached on first access.
+        whatismyip: The IP lookup service, created and cached on first
+            access.
+    """
+    __service_classes__ = {
+        "devices": Devices,
+        "dns_lists": DnsLists,
+        "generator": Generator,
+        "status": Status,
+        "userinfo": UserInfo,
+        "whatismyip": WhatIsMyIp
+    }
+
+    def __init__(self, API_KEY: str = None):
+        self.api_key = API_KEY
+        self.session = AirSession(API_KEY)
+
+        self._devices = None
+        self._dns_lists = None
+        self._generator = None
+        self._status = None
+        self._userinfo = None
+        self._whatismyip = None
+
+    def get_service(self, service: str):
+        """Instantiate a named service class, enforcing its API key requirement.
+
+        Args:
+            service: The service name (e.g. "devices", "status"), matched
+                case-insensitively against the registered service classes.
+
+        Returns:
+            An instance of the requested service class.
+
+        Raises:
+            AssertionError: If the service name is invalid.
+            Exception: If the service requires an API key and none was provided.
+        """
+        service_class = AirVPN.__service_classes__.get(service.lower())
+        assert service_class, f"Invalid service name: {service}"
+
+        service = service_class(self.session)
+        if service_class.KEY_NEEDED and not self.api_key:
+            raise Exception(f"API key is required to use \"{service}\"")
+
+        assert service, "Failed to create service"
+
+        return service
+    
+    @property
+    def devices(self) -> Devices:
+        """The devices service, created and cached on first access."""
+        if not self._devices:
+            self._devices = self.get_service("devices")
+        return self._devices
+
+    @property
+    def dns_lists(self) -> DnsLists:
+        """The DNS lists service, created and cached on first access."""
+        if not self._dns_lists:
+            self._dns_lists = self.get_service("dns_lists")
+        return self._dns_lists
+    
+    @property
+    def generator(self) -> Generator:
+        """The config generator service, created and cached on first access."""
+        if not self._generator:
+            self._generator = self.get_service("generator")
+        return self._generator
+
+    @property
+    def status(self) -> Status:
+        """The network status service, created and cached on first access."""
+        if not self._status:
+            self._status = self.get_service("status")
+        return self._status
+
+    @property
+    def userinfo(self) -> UserInfo:
+        """The user info service, created and cached on first access."""
+        if not self._userinfo:
+            self._userinfo = self.get_service("userinfo")
+        return self._userinfo
+    
+    @property
+    def whatismyip(self) -> WhatIsMyIp:
+        """The IP lookup service, created and cached on first access."""
+        if not self._whatismyip:
+            self._whatismyip = self.get_service("whatismyip")
+        return self._whatismyip
+    
+    def send_notification(self, subject: str, body: str):
+        """Send a message to yourself.
+
+        Args:
+            subject: The notification's subject line.
+            body: The notification's message content.
+
+        Returns:
+            True if the notification was sent successfully, False otherwise.
+
+        Access type:
+            User-specific, API KEY required.
+        """
+        assert self.api_key, "API key is required"
+
+        return send_notification(self.session, subject, body)
+
+    def disconnect(self,
+                    server: Server = None,
+                    device: Device = None,
+                    server_name: str = None,
+                    device_id: str = None):
+        """Requests a disconnection. If none of the filter parameters is specified, disconnect all sessions of the user.
+
+        Args:
+            server: A Server object to disconnect from; its public_name is
+                used if server_name is not explicitly provided.
+            device: A Device object to disconnect; its id is used if
+                device_id is not explicitly provided.
+            server_name: Name of the server to disconnect from. Ignored if
+                server is provided.
+            device_id: ID of the device to disconnect. Ignored if device
+                is provided.
+
+        Returns:
+            The number of sessions that were disconnected.
+
+        Access type:
+            User-specific, API KEY required.
+        """
+        assert self.api_key, "API key is required"
+
+        disconnect(self.session, 
+                   server_name=server.name if server else server_name,
+                   device_id=device.id if device else device_id)

airvpn-0.1.0/airvpn/devices/__init__.py

@@ -0,0 +1,125 @@
+from airvpn.network import AirSession, Status
+from airvpn.devices.models import Device
+
+from enum import StrEnum
+
+class DeviceAction(StrEnum):
+    """Actions available for managing devices via the devices endpoint."""
+    LIST = "list"
+    ADD = "add"
+    DELETE = "delete"
+    MODIFY = "modify"
+    RENEW = "renew"
+
+class Devices:
+    """
+    Manages registered devices/keys associated with the account.
+    
+    Access type:
+        User-specific, API KEY required
+    """
+
+    KEY_NEEDED = True
+
+    def __init__(self, session: AirSession):
+        self.session = session
+    
+    def action(self,
+               action: DeviceAction,
+               id: str | None = None,
+               name: str | None = None,
+               description: str | None = None):
+        """Send a raw devices action request.
+
+        Args:
+            action: The device action to perform.
+            id: The device's ID. Required for delete, renew, and modify.
+            name: The device's name. Used for add and modify.
+            description: The device's description. Used for add and modify.
+
+        Returns:
+            The parsed JSON response from the devices endpoint.
+
+        Raises:
+            AssertionError: If the response contains an error.
+
+        """
+
+        result = self.session.get("devices", params={
+            "action": action, "id": id, "name": name, "description": description
+        }).json()
+
+        error = result.get("error", None)
+        assert not error, error
+
+        return result
+
+    def list(self):
+        """List all devices registered to the account.
+
+        Returns:
+            A list of Device objects.
+        """
+
+        response = self.action(DeviceAction.LIST)
+
+        return [Device(**device) for device in response.get("devices", [])]
+    
+    def add(self):
+        """Register a new device.
+
+        Returns:
+            The ID of the newly created device, or None if not returned.
+        """
+
+        response = self.action(DeviceAction.ADD)
+
+        return response.get("id", None)
+    
+    def delete(self, id: str):
+        """Delete a device.
+
+        Args:
+            id: The ID of the device to delete.
+
+        Returns:
+            True if successful in deleting the device.
+        """
+
+        response = self.action(DeviceAction.DELETE, id=id)
+
+        return response.get("result", "error") == "ok"
+    
+    def renew(self, id: str):
+        """Renew a device.
+
+        Args:
+            id: The ID of the device to renew.
+
+        Returns:
+            True if successful in renewing the device.
+        """
+
+        response = self.action(DeviceAction.RENEW, id=id)
+
+        return response.get("result", "error") == "ok"
+
+    def modify(self, id: str, name: str | None = None, description: str | None = None):
+        """Modify a device's name and/or description.
+
+        Args:
+            id: The ID of the device to modify.
+            name: The new name for the device, if changing it.
+            description: The new description for the device, if changing it.
+
+        Returns:
+            True if successful in modifying the device.
+
+        Raises:
+            AssertionError: If neither name nor description is provided.
+        """
+        assert name is not None or description is not None, "You either need to modify name or description."
+
+        response = self.action(DeviceAction.MODIFY, id=id, name=name, description=description)
+        
+        return response.get("result", "error") == "ok"

airvpn-0.1.0/airvpn/devices/models.py

@@ -0,0 +1,70 @@
+from typing import Unpack, TypedDict
+
+class DeviceDict(TypedDict):
+    id: str
+    name: str
+    description: str
+    version: str
+    renew_first_unix: int
+    renew_first_date: str
+    renew_last_unix: int
+    renew_last_date: str
+    renew_counter: int
+    wireguard_public_key: str
+    wireguard_ipv4: str
+    wireguard_ipv6: str
+    vpn_last_from_unix: int
+    vpn_last_from_date: str
+    vpn_last_to_unix: int
+    vpn_last_to_date: str
+    vpn_attempt_unix: int
+    vpn_attempt_date: str
+    vpn_attempt_message: str
+    status: str
+
+class Device:
+    """Represents a registered device associated with the account.
+
+    Attributes:
+        id: Unique identifier for the device.
+        name: Display name of the device.
+        description: Description of the device.
+        version: Version of the client/software associated with the device.
+        renew_first_unix: Unix timestamp of the device's first renewal.
+        renew_first_date: Human-readable date of the device's first renewal.
+        renew_last_unix: Unix timestamp of the device's most recent renewal.
+        renew_last_date: Human-readable date of the device's most recent renewal.
+        renew_counter: Number of times the device has been renewed.
+        wireguard_public_key: The device's WireGuard public key.
+        wireguard_ipv4: IPv4 address assigned to the device over WireGuard.
+        wireguard_ipv6: IPv6 address assigned to the device over WireGuard.
+        vpn_last_from_unix: Unix timestamp of the start of the device's last VPN session.
+        vpn_last_from_date: Human-readable start date of the device's last VPN session.
+        vpn_last_to_unix: Unix timestamp of the end of the device's last VPN session.
+        vpn_last_to_date: Human-readable end date of the device's last VPN session.
+        vpn_attempt_unix: Unix timestamp of the device's last connection attempt.
+        vpn_attempt_date: Human-readable date of the device's last connection attempt.
+        vpn_attempt_message: Message/result associated with the last connection attempt.
+        status: Current status of the device.
+    """
+    def __init__(self, **kwargs: Unpack[DeviceDict]):
+        self.id = kwargs.get("id")
+        self.name = kwargs.get("name")
+        self.description = kwargs.get("description")
+        self.version = kwargs.get("version")
+        self.renew_first_unix = kwargs.get("renew_first_unix")
+        self.renew_first_date = kwargs.get("renew_first_date")
+        self.renew_last_unix = kwargs.get("renew_last_unix")
+        self.renew_last_date = kwargs.get("renew_last_date")
+        self.renew_counter = kwargs.get("renew_counter")
+        self.wireguard_public_key = kwargs.get("wireguard_public_key")
+        self.wireguard_ipv4 = kwargs.get("wireguard_ipv4")
+        self.wireguard_ipv6 = kwargs.get("wireguard_ipv6")
+        self.vpn_last_from_unix = kwargs.get("vpn_last_from_unix")
+        self.vpn_last_from_date = kwargs.get("vpn_last_from_date")
+        self.vpn_last_to_unix = kwargs.get("vpn_last_to_unix")
+        self.vpn_last_to_date = kwargs.get("vpn_last_to_date")
+        self.vpn_attempt_unix = kwargs.get("vpn_attempt_unix")
+        self.vpn_attempt_date = kwargs.get("vpn_attempt_date")
+        self.vpn_attempt_message = kwargs.get("vpn_attempt_message")
+        self.status = kwargs.get("status")

airvpn-0.1.0/airvpn/disconnect.py

@@ -0,0 +1,30 @@
+from airvpn.network import AirSession
+
+
+def disconnect(session: AirSession,
+               server_name: str = None,
+               device_id: str = None):
+    """Requests a disconnection. If none of the filter parameters is specified, disconnect all sessions of the user.
+
+    Args:
+        session: The active AirSession used to make the API request.
+        server_name: Name of the server to disconnect from. Ignored if
+            server is provided.
+        device_id: ID of the device to disconnect. Ignored if device
+            is provided.
+
+    Returns:
+        The number of sessions that were disconnected.
+
+    Access type:
+        User-specific, API KEY required.
+    """
+
+    response = session.get("disconnect", params={
+        "server": server_name,
+        "device": device_id
+    })
+    
+    json = response.json()
+
+    return json.get("sessions_disconnected", 0)

airvpn-0.1.0/airvpn/dns_lists/__init__.py

@@ -0,0 +1,29 @@
+"""
+I can't really understand the documentation for dns_lists.
+
+If you can understand it or can get it to change at all please open an issue or create a PR with how you did it.
+"""
+
+from airvpn.network import AirSession
+from airvpn.dns_lists.models import Dns
+
+class DnsLists:
+    """Fetches available DNS filtering lists.
+
+    Attributes:
+        lists: A dict mapping list keys to their corresponding Dns objects.
+
+    Access type:
+        Public, no API KEY required
+    """
+
+    KEY_NEEDED = False
+
+    def __init__(self, session: AirSession):
+        response = session.get("dns_lists")
+        json = response.json()
+
+        self.lists: dict[str, Dns] = {}
+
+        for key, dns in json.get("lists", {}).items():
+            self.lists[key] = Dns(**dns)

airvpn-0.1.0/airvpn/dns_lists/models.py

@@ -0,0 +1,26 @@
+from typing import Unpack, TypedDict
+
+class DnsDict(TypedDict, total=False):
+    name: str
+    description: str
+    home: str | None
+    last_update_unix: int
+    n_items: int
+
+class Dns:
+    """Represents a DNS filtering list/profile.
+
+    Attributes:
+        name: The DNS list's name.
+        description: Description of the DNS list.
+        home: URL of the DNS list's home page/source, if available;
+            otherwise None.
+        last_update_unix: Unix timestamp of when the DNS list was last updated.
+        n_items: Number of entries in the DNS list.
+    """
+    def __init__(self, **kwargs: Unpack[DnsDict]):
+        self.name = kwargs.get("name")
+        self.description = kwargs.get("description")
+        self.home = kwargs.get("home")
+        self.last_update_unix = kwargs.get("last_update_unix")
+        self.n_items = kwargs.get("n_items")

airvpn-0.1.0/airvpn/generator/__init__.py

@@ -0,0 +1,124 @@
+# https://airvpn.org/api/generator/?protocols=wireguard_3_udp_1637&servers=xamidimura&device=Default
+# https://airvpn.org/api/generator/?protocols=openvpn_3_udp_443%2Copenvpn_3_tcp_443%2Cwireguard_3_udp_1637%2Copenvpn_4_udp_443&servers=asellus&device=Default
+# https://airvpn.org/api/generator/?protocols=openvpn_3_udp_443%2Copenvpn_3_tcp_443%2Cwireguard_3_udp_1637%2Copenvpn_4_udp_443&servers=grus%2Casellus&device=Default
+# https://airvpn.org/api/generator/?protocols=openvpn_3_udp_443%2Copenvpn_3_tcp_443%2Cwireguard_3_udp_1637%2Copenvpn_4_udp_443&servers=america%2Casia%2Cearth%2Cbr%2Cca%2Cgrus%2Casellus%2Cvulpecula%2Cxamidimura&system=linux&device=Default
+
+from typing import Unpack
+from airvpn.network import AirSession
+from airvpn.generator.models import SystemType, ProtocolType, VpnType, OptionsDict
+
+class Generator:
+    """Generates VPN configuration files via the AirVPN config generator API.
+
+    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.
+
+    Access type:
+        User-specific, API KEY required.
+    """
+
+    KEY_NEEDED = True
+
+    def __init__(self, session: AirSession):
+        self.session = session
+
+    def create_config(self,
+                  server: str,
+                  device: str,
+                  system: SystemType = SystemType.WINDOWS,
+                  vpn_type: VpnType = VpnType.WIREGUARD,
+                  protocol_type: ProtocolType = ProtocolType.UDP,
+                  port: int = 1637,
+                  entry_ip: int = 3,
+                  download: str = "auto",
+                  files_binary: str = "",
+                  files_prefix: str = "",
+                  openvpn_directives: str = "",
+                  openvpn_data_ciphers: str = "",
+                  resolve: bool = False,
+                  openvpn_allserver: 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: Unpack[OptionsDict]
+                ):
+        """Generate a VPN configuration file for one or more servers.
+
+        Args:
+            server: Server name(s) to generate the config for. Multiple
+                servers, countries, continents, or "earth" can be combined
+                with commas (e.g. "america,asia,earth,br,ca").
+            device: The device profile name to associate with this config.
+            system: Target operating system for the generated config.
+            vpn_type: VPN protocol family (e.g. WireGuard, OpenVPN).
+            protocol_type: Transport protocol (UDP or TCP).
+            port: Port number to connect on.
+            entry_ip: IP version/entry point selector for the connection.
+            download: Download mode for the generated files ("auto" or
+                a specific format).
+            files_binary: Optional binary/executable to bundle with the config.
+            files_prefix: Optional filename prefix for generated files.
+            openvpn_directives: Additional custom directives to inject into
+                an OpenVPN config.
+            openvpn_data_ciphers: Custom data cipher list for OpenVPN.
+            resolve: Whether to resolve server hostnames instead of using
+                raw IPs in the config.
+            openvpn_allserver: Whether to include all servers in a single
+                OpenVPN config.
+            proxy_mode: Proxy mode to configure in the generated config
+                ("none" or a specific proxy type).
+            proxy_auth: Proxy authentication method/type, if proxy_mode
+                    is enabled.
+            proxy_host: Proxy host address, if proxy_mode is enabled.
+            proxy_port: Proxy port, if proxy_mode is enabled.
+            proxy_login: Proxy authentication username, if required.
+            proxy_password: Proxy authentication password, if required.
+            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
+                ("ipv4", "ipv6", or "both").
+            iplayer_exit: IP layer to use for the exit connection
+                ("ipv4", "ipv6", or "both").
+            **kwargs: Additional generator options not covered by the named
+                parameters above. These override any matching keys built
+                from the named parameters. Supported keys include:
+
+                openvpn_version: OpenVPN version to target.
+                openvpn_noembedkeys: Whether to omit embedding keys directly
+                    in the OpenVPN config (reference external key files instead).
+                openvpn_allservers: Whether to include all servers in a single
+                    OpenVPN config. Note: this is a separate key from the
+                    openvpn_allserver named parameter above and does not
+                    override it.
+
+                See OptionsDict for the full list of supported keys.
+
+        Returns:
+            The raw text response from the generator endpoint (typically
+            the generated config file contents).
+        """
+        options = locals()
+
+        options.pop("self")
+        options.pop("server")
+        options.pop("kwargs")
+
+        protocol = f"{vpn_type}_{entry_ip}_{protocol_type}_{port}"
+
+        options["protocols"] = protocol
+        options["servers"] = server
+
+        options = options | kwargs
+
+        response = self.session.get("generator", params=options)
+
+        return response.text