Metadata-Version: 2.1
Name: aiobungie
Version: 0.2.11
Summary: A Python and Asyncio API wrapper for Bungie's API.
Home-page: https://github.com/nxtlo/aiobungie
License: MIT
Keywords: async,api,destiny,bungie
Author: nxtlo
Author-email: dhmony-99@hotmail.com
Requires-Python: >=3.10.0,<3.13
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: full
Provides-Extra: speedup
Requires-Dist: aiohttp (==3.9.3)
Requires-Dist: attrs (==23.2.0)
Requires-Dist: backports-datetime-fromisoformat (==2.0.1) ; python_version == "3.10"
Project-URL: Repository, https://github.com/nxtlo/aiobungie
Description-Content-Type: text/markdown

# aiobungie

A statically typed, asynchronous API wrapper for building clients for Bungie's API in Python.

## Installing

Currently Python 3.10, 3.11 and 3.12 are supported.

Stable release.

```sh
pip install aiobungie
```

Development via github master.

```sh
pip install git+https://github.com/nxtlo/aiobungie@master
```

## Quick Example

See [Examples for advance usage.](https://github.com/nxtlo/aiobungie/tree/master/examples)

```py
import aiobungie

client = aiobungie.Client('YOUR_API_KEY')

async def main() -> None:
    # Fetch a Destiny 2 character passing a component.
    # This includes Equipments, Inventory, Records, etc.
    async with client.rest:
        my_warlock = await client.fetch_character(
            member_id=4611686018484639825,
            membership_type=aiobungie.MembershipType.STEAM,
            character_id=2305843009444904605,
            components=[aiobungie.ComponentType.CHARACTER_EQUIPMENT],
        )
        # Other components will be populated when passed to `components=[...]`
        # Otherwise will be `None`

        # Make sure the component is fetched.
        assert my_warlock.equipment is not None

        # Get the first item equipped on this character.
        item = my_warlock.equipment[0]
        print(item.hash, item.location)

        # Fetch this item, Note that this performs an HTTP request.
        # Alternatively, You can use the manifest here instead.
        # See examples folder for more information.
        item = await client.fetch_inventory_item(item.hash)
        print(item.name, item.type_and_tier_name)
        # Prints: Izanagi's Burden Exotic Sniper Rifle

# You can either run it using the client or just asyncio.run(main())
client.run(main())
```

## RESTful clients

aiobungie also provides a stand-alone `RESTClient` / `RESTPool` which's what `Client` built on top of, These clients just provide a lower-level abstraction.

A key note is that any `Client` based user can access the `RESTClient` instance bound to it with `.rest` property.

### Key Features

* Lower level, allows to read and deserialize the JSON objects yourself.
* `RESTClient`s do not turn response payloads into one of `aiobungie.crates` object.
* RESTful, You can use this as your REST API client in backend directly.
* Both `Manifest` and `OAuth` methods are usable directly.

### Example

```py
import aiobungie
import asyncio

# Single REST client connection.
client = aiobungie.RESTClient("...")

async def main() -> None:
    async with client:
        # Download and open the JSON manifest.
        manifest = await client.download_json_manifest(name="latest_manifest")
        with manifest.open("r") as file:
            data = file.read()

        # OAuth2 API. 2 simple methods for fetching and refreshing tokens.
        tokens = await client.fetch_oauth2_tokens('code')
        refreshed_tokens = await client.refresh_access_token(tokens.refresh_token)

        # Testing your own requests.
        response = await client.static_request(
            "GET", # Method.
            "Destiny2/path/to/route", # Route.
            auth="optional_access_token", # If the method requires OAuth2.
            json={"some_key": "some_value"} # If you need to pass JSON data.
        )

asyncio.run(main())
```

## Dependancies

* aiohttp
* attrs
* `backports.datetime_fromisoformat`, required for `Python 3.10` only.

### Features

aiobungie features are extra dependencies that replaces the standard library with either faster/neater pkgs.

* `speedup`
This will include and uses [orjson](https://github.com/ijl/orjson) or [ujson](https://github.com/ultrajson/ultrajson)
as the default `json` parser. They provide faster json serialization and de-serialization than the standard Python JSON pkg.
* `full`: This will include all of the features above.

For installing the specified feature, type `pip install aiobungie[feature-name]`

## Contributing

Please read this [manual](https://github.com/nxtlo/aiobungie/blob/master/CONTRIBUTING.md)

## Related Projects

If you have used aiobungie and want to show your work, Feel free to Open a PR including it.

* [Fated](https://github.com/nxtlo/Fated/blob/master/core/components/destiny.py): A Discord BOT that uses aiobungie.

## Useful Resources

* Discord Username: `vfate`
* aiobungie Documentation: [Here](https://nxtlo.github.io/aiobungie/).
* BungieAPI Discord: [Here](https://discord.gg/vP7VC7TKUG)
* Official Bungie Documentation: [Here](https://bungie-net.github.io/multi/index.html)
* Bungie Developer Portal: [Here](https://www.bungie.net/en/Application)

### Additional information

If you have any question you can either open a blank issue, open a new github discussion, or just tag me in BungieAPI discord server.

