add get_tunnel to Cobalt() obj, more details on 0byte download error,…

… add docs about .env vars, bump version

README.md

@@ -97,6 +97,20 @@ disable print info
 await download(url, status_callback=None, done_callback=None)  # You can replace callbacks with your custom sync/async funcion!
 ```
 
+# 📦 Applying enviroment (.env) variables
+
+If you want pybalt to always use your proxy, user agent or something else you can configure enviroment variables, pybalt will use them if none was provided as a parameter.
+
+```sh
+COBALT_PROXY=http://...
+COBALT_USER_AGENT=...
+COBALT_TIMEOUT=12
+COBALT_API_KEY=key
+COBALT_DEBUG=true
+COBALT_LOCAL_INSTANCE=http://127.0.0.1:9000
+COBALT_LOCAL_INSTANCE_API_KEY=ye
+```
+
 # 👥 Used by
 
 pybalt is used by the following projects:

pybalt/core/client.py

@@ -1,6 +1,6 @@
 from aiohttp import ClientSession
-from .misc import Translator, DefaultCallbacks, StatusParent, lprint
-from typing import Literal, Union, Dict, Callable, Coroutine, Unpack, TypedDict
+from .misc import Translator, DefaultCallbacks, StatusParent
+from typing import Literal, Dict, Callable, Coroutine, Unpack, TypedDict
 from asyncio import sleep, iscoroutinefunction, wait_for, TimeoutError
 from .constants import DEFAULT_TIMEOUT
 from time import time
@@ -319,7 +319,9 @@ async def download_from_url(
                                 (len(chunk) - max_speed) / (max_speed / 1024 / 1024)
                             )
             if downloaded_size <= 1024:
-                raise exceptions.DownloadError("Download failed, no data received")
+                raise exceptions.DownloadError(
+                    "Download failed, no data received. That's a problem with cobalt instance, try enabling youtubeHLS, if this issue persist host your own local instance."
+                )
             if options.get("status_parent", None):
                 if isinstance(options.get("status_parent"), StatusParent):
                     options.get("status_parent").downloaded_size = downloaded_size

pybalt/core/cobalt.py

@@ -9,14 +9,12 @@
     TypedDict,
     Literal,
     LiteralString,
-    Self,
     Any,
     Coroutine,
     Callable,
-    Generator,
     AsyncGenerator,
 )
-from .misc import Translator, lprint, check_updates, cfg_value, StatusParent
+from .misc import Translator, lprint, check_updates, cfg_value
 from .client import RequestClient, _DownloadOptions
 from .constants import (
     FALLBACK_INSTANCE,
@@ -352,7 +350,7 @@ async def fetch_instances(self) -> List[Instance]:
             try:
                 self.debug("Fetching local instance info...", end="\r")
                 await self.local_instance.get_instance_info()
-                self.instances += [self.local_instance]
+                self.instances = [self.local_instance] + self.instances
             except Exception:
                 self.debug("Didn't find local instance, skipping")
             self.debug(f"Fetched {len(self.instances)} instances")
@@ -362,6 +360,26 @@ async def fetch_instances(self) -> List[Instance]:
             self.instances = [self.fallback_instance]
             return self.instances
 
+    async def get_tunnel(self, url: str, **body: Unpack[_CobaltBodyOptions]) -> Tunnel:
+        tunnels = []
+        for instance in await self.fetch_instances():
+            try:
+                async for tunnel in instance.get_tunnel(
+                    url=url,
+                    **{
+                        key: value
+                        for key, value in body.items()
+                        if key in _CobaltBodyOptions.__annotations__.keys()
+                    },
+                ):
+                    tunnels += [tunnel]
+                return tunnels if len(tunnels) > 1 else tunnels[0]
+            except Exception as exc:
+                self.debug(exc)
+        raise exceptions.AllInstancesFailed(
+            f"Failed to get tunnel of {url} using any of {len(self.instances)} instances. If this issue persists, you can host your own local instance, more on it here: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md"
+        )
+
     async def download(
         self, url: Union[str, Tunnel], **body: Unpack[_CobaltDownloadOptions]
     ) -> Path | List[Path]:

pybalt/core/constants.py

@@ -1,4 +1,4 @@
-VERSION = "2025.1.2"
+VERSION = "2025.1.3"
 FALLBACK_INSTANCE = "https://dwnld.nichind.dev"
 FALLBACK_INSTANCE_API_KEY = "b05007aa-bb63-4267-a66e-78f8e10bf9bf"
 DEFAULT_UA = "pybalt/python"