release: 0.4.0

.github/workflows/ci.yml

@@ -146,7 +146,7 @@ jobs:
           python-version: "3.10"
 
       - name: Setup Poetry
-        uses: abatilo/actions-poetry@v3
+        uses: abatilo/actions-poetry@v4
         with:
           poetry-version: 1.7.1
 

aiobungie/__init__.py

@@ -1,5 +1,7 @@
 # MIT License
-#
+# ruff: noqa: F401
+# ruff: noqa: F403
+# ruff: noqa: F405
 # Copyright (c) 2020 - Present nxtlo
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -36,13 +38,7 @@
 
 from __future__ import annotations
 
-from aiobungie import api
-from aiobungie import builders
-from aiobungie import crates
-from aiobungie import framework
-from aiobungie import traits
-from aiobungie import typedefs
-from aiobungie import url
+from aiobungie import api, builders, crates, framework, traits, typedefs, url
 from aiobungie.client import Client
 from aiobungie.error import *
 from aiobungie.internal.enums import *
@@ -58,26 +54,28 @@
 from .crates.components import ComponentPrivacy
 
 # Entity enums
-from .crates.entity import GatingScope
-from .crates.entity import ObjectiveUIStyle
-from .crates.entity import ValueUIStyle
+from .crates.entity import GatingScope, ObjectiveUIStyle, ValueUIStyle
 
 # Fireteam enums.
-from .crates.fireteams import FireteamActivity
-from .crates.fireteams import FireteamDate
-from .crates.fireteams import FireteamLanguage
-from .crates.fireteams import FireteamPlatform
+from .crates.fireteams import (
+    FireteamActivity,
+    FireteamDate,
+    FireteamLanguage,
+    FireteamPlatform,
+)
 
 # Records enums
 from .crates.records import RecordState
 
 # Package metadata
-from .metadata import __about__
-from .metadata import __author__
-from .metadata import __docs__
-from .metadata import __email__
-from .metadata import __license__
-from .metadata import __url__
-from .metadata import __version__
+from .metadata import (
+    __about__,
+    __author__,
+    __docs__,
+    __email__,
+    __license__,
+    __url__,
+    __version__,
+)
 
 __all__ = [mod for mod in dir() if not mod.startswith("_")]  # type: ignore

aiobungie/api/framework.py

@@ -34,21 +34,23 @@
     from sain import Iterator
 
     from aiobungie import typedefs
-    from aiobungie.crates import activity
-    from aiobungie.crates import application
-    from aiobungie.crates import character
-    from aiobungie.crates import clans
-    from aiobungie.crates import components
-    from aiobungie.crates import entity
-    from aiobungie.crates import fireteams
-    from aiobungie.crates import friends
-    from aiobungie.crates import items
-    from aiobungie.crates import milestones
-    from aiobungie.crates import profile
-    from aiobungie.crates import progressions
-    from aiobungie.crates import records
-    from aiobungie.crates import season
-    from aiobungie.crates import user
+    from aiobungie.crates import (
+        activity,
+        application,
+        character,
+        clans,
+        components,
+        entity,
+        fireteams,
+        friends,
+        items,
+        milestones,
+        profile,
+        progressions,
+        records,
+        season,
+        user,
+    )
 
 
 class Framework(abc.ABC):

aiobungie/api/rest.py

@@ -34,19 +34,16 @@
 import typing
 
 from aiobungie import traits
-from aiobungie.internal import enums
-from aiobungie.internal import helpers
+from aiobungie.internal import enums, helpers
 
 if typing.TYPE_CHECKING:
     import concurrent.futures
     import types
 
     from typing_extensions import Self
 
-    from aiobungie import builders
-    from aiobungie import typedefs
-    from aiobungie.crates import clans
-    from aiobungie.crates import fireteams
+    from aiobungie import builders, typedefs
+    from aiobungie.crates import clans, fireteams
 
     _ALLOWED_LANGS = typing.Literal[
         "en",

aiobungie/builders.py

@@ -23,7 +23,7 @@
 
 from __future__ import annotations
 
-__all__ = ("OAuth2Response", "PlugSocketBuilder", "OAuthURL", "Image")
+__all__ = ("OAuth2Response", "PlugSocketBuilder", "OAuthURL", "Image", "Settings")
 
 import asyncio
 import datetime
@@ -35,22 +35,19 @@
 import aiohttp
 import attrs
 
-from . import error
-from . import url
-from .internal import enums
-from .internal import helpers
+from . import error, url
+from .internal import enums, helpers
 
 if typing.TYPE_CHECKING:
     import collections.abc as collections
     import concurrent.futures
     import os
+    import ssl
     import types
 
-    from typing_extensions import Required
-    from typing_extensions import Self
+    from typing_extensions import Required, Self
 
-    from aiobungie import traits
-    from aiobungie import typedefs
+    from aiobungie import traits, typedefs
 
     class _FinderListingValue(typing.TypedDict):
         valueType: Required[int]
@@ -62,6 +59,49 @@ class _ListingFilter(typing.TypedDict):
         matchType: int
 
 
+@typing.final
+@attrs.define(kw_only=True)
+class Settings:
+    """Basic settings used within aiobungie HTTP clients."""
+
+    http_timeout: aiohttp.ClientTimeout = attrs.field(
+        default=aiohttp.ClientTimeout(30.0)
+    )
+    """Setting to control HTTP request timeouts, This includes
+    the time it takes to acquire the client,
+    timeout for connecting and reading the socket, and more.
+
+    Defaults to total of `30.0` seconds.
+    """
+
+    trust_env: bool = attrs.field(default=False)
+    """Trust environment settings for proxy configuration.
+
+    Gets proxy credentials from `~/.netrc` file if present or
+    Gets HTTP Basic Auth credentials from `~/.netrc` file if present.
+
+    If `NETRC` environment variable is set, read from file specified 
+    there rather than from `~/.netrc`.
+    """
+
+    auth: aiohttp.BasicAuth | None = attrs.field(default=None)
+    """an object that represents HTTP Basic Authorization, Defaults to `None`."""
+
+    headers: collections.Mapping[str, typing.Any] | None = attrs.field(default=None)
+    """Default HTTP headers to send the request with, Defaults to `None`."""
+
+    use_dns_cache: bool = attrs.field(default=True)
+    """References [use_dns_cache](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.TCPConnector)"""
+    ttl_dns_cache: int = attrs.field(default=10)
+    """References [ttl_dns_cache](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.TCPConnector)"""
+    verify_ssl: bool = attrs.field(default=True)
+    """References [verify_ssl](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.TCPConnector)"""
+    ssl_context: ssl.SSLContext | None = attrs.field(default=None)
+    """References [ssl_context](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.TCPConnector)"""
+    ssl: bool | aiohttp.Fingerprint | ssl.SSLContext = attrs.field(default=True)
+    """References [ssl](https://docs.aiohttp.org/en/stable/client_reference.html#aiohttp.TCPConnector)"""
+
+
 @typing.final
 class MimeType(str, enums.Enum):
     """Image mime types enum."""
@@ -82,7 +122,9 @@ def _open_write_path(path: pathlib.Path) -> typing.BinaryIO:
 
 @typing.final
 class Image:
-    """A stream-able Bungie resource.
+    """A streamable Bungie resource.
+
+    Images are _lazy_, which mean they do nothing unless you `await` or poll them.
 
     Example
     -------
@@ -171,7 +213,7 @@ def create_url(self) -> str:
         """
         return url.BASE + "/" + self.path
 
-    async def static_request(self) -> aiohttp.ClientResponse:
+    async def _static_request(self) -> aiohttp.ClientResponse:
         client_session = aiohttp.ClientSession()
         request = client_session.request(
             "GET", self.create_url(), raise_for_status=False
@@ -200,7 +242,7 @@ async def save(
         file_name: str,
         path: str | os.PathLike[str],
         *,
-        mime_type: MimeType | str = MimeType.JPEG,
+        mime_type: MimeType | str = MimeType.PNG,
         executor: concurrent.futures.Executor | None = None,
     ) -> None:
         """Saves this image to a file.
@@ -239,7 +281,7 @@ async def save(
         loop = helpers.get_or_make_loop()
         file = await loop.run_in_executor(executor, _open_write_path, path)
 
-        reader = await self.static_request()
+        reader = await self._static_request()
         try:
             async for chunk in reader.content:
                 await loop.run_in_executor(executor, file.write, chunk)
@@ -268,7 +310,7 @@ async def read(self) -> bytes:
         `bytes`:
             The bytes of this image.
         """
-        return await (await self.static_request()).read()
+        return await (await self._static_request()).read()
 
     async def stream(self) -> aiohttp.streams.AsyncStreamIterator[bytes]:
         """Stream this image's data.
@@ -287,17 +329,16 @@ async def stream(self) -> aiohttp.streams.AsyncStreamIterator[bytes]:
         Returns
         -------
         `AsyncStreamIterator[bytes]`:
-            A lazy async iterator that is ready in memory.
+            A streaming iterator of this image bytes, yielding the entire data as soon as its received.
         """
-        return (await self.static_request()).content.iter_any()
+        return (await self._static_request()).content.iter_any()
 
-    async def chunks(self, size: int) -> aiohttp.streams.AsyncStreamIterator[bytes]:
-        """Stream this image's data in chunks.
+    async def chunks(self, n: int) -> aiohttp.streams.AsyncStreamIterator[bytes]:
+        """Stream the bytes of this image in `n` chunks.
 
         Example
         -------
         ```py
-        # it must be awaited to fetch the image first.
         buffer_size = 1024
         image = Image.default()
 
@@ -313,9 +354,9 @@ async def chunks(self, size: int) -> aiohttp.streams.AsyncStreamIterator[bytes]:
         Returns
         -------
         `AsyncStreamIterator[bytes]`:
-            lazy async iterator that is ready in memory.
+            A chunking stream of bytes.
         """
-        return (await self.static_request()).content.iter_chunked(size)
+        return (await self._static_request()).content.iter_chunked(n)
 
     async def iter(self) -> collections.AsyncGenerator[bytes, None]:
         """Yield each byte in this image from start to end.
@@ -332,7 +373,7 @@ async def iter(self) -> collections.AsyncGenerator[bytes, None]:
         Returns
         -------
         `collections.AsyncGenerator[bytes, None]`
-            An async generator that yields this image's bytes.
+            An async generator that yields this image's bytes from start to end.
         """
 
         reader = await self.chunks(1024)