Metadata-Version: 2.1
Name: aiobungie
Version: 0.3.0
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.5)
Requires-Dist: attrs (==23.2.0)
Requires-Dist: backports-datetime-fromisoformat (==2.0.1) ; python_version == "3.10"
Requires-Dist: sain (==1.1.0)
Project-URL: Repository, https://github.com/nxtlo/aiobungie
Description-Content-Type: text/markdown

# aiobungie

A statically typed, asynchronous API wrapper that supports Bungie's REST API for Python 3.

## Installing

Currently Python 3.10, 3.11 and 3.12 are supported.

Latest Release using `pip`.

```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
import asyncio

client = aiobungie.Client('YOUR_API_KEY')

async def main() -> None:
    # Search for Destiny 2 players.
    async with client.rest:
        users = await client.search_users("Fate")
        for user in users:
            # Print all Destiny 2 memberships for this user.
            print(user.memberships)
            

asyncio.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 OAuth2 methods are usable directly.

### Example

```py
import aiobungie
import asyncio

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

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())
```

## Dependencies

* aiohttp
* attrs
* [`sain`](https://github.com/nxtlo/sain), this is a dependency free utility package.
* `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)

## FaQ

* I need help with something related to this project: Consider opening a blank issue, discussion or checkout the `useful resources` above.
* aiobungie doesn't support `fetch_xxx` route, what now? aiobungie's REST client exposes a method called `static_request` which allows you
to make your own requests, check out `examples/custom_client` example.

