# unb-api-py
unb-api-py allows python developers to use the UnbelievaBoat Discord bot API in their own projects! Here's how to get started:
(documentation is coming not-so-soon)
## Getting Started
1. Install the library
```console
pip install unbapi
```
2. Create an UnbelievaBoat Application at https://unbelievaboat.com/applications and copy the token (keep this secret)
3. Import the library, and create an `Application` object. Example:
```py
import unbapi
unbapp = unb.Application("put the token here from step 2.")
```
You've now created an `Application` object. This allows you to get or fetch a guild object. Here's how to get a guild object:
```py
guild = unbapp.get_guild(guild-id)
```
This will create `PartialGuild` object. This allows you to do every action in the guild but doesn't have much information about the app. If you need guild information, such as the name, icon, currency symbol, etc then you should use `unbapp.fetch_guild` which gives a `Guild` object. However, fetching information is slower then 'getting' it.
A `PartialGuild`, or `Guild` object allows you to do things inside of a guild (as long as you have permission), such as: fetching a user's balance (and changing it), getting store items, adding/removing items from user's inventories, and more. Here's how to do each:
## Examples
### Check the bot's permissions in a guild
```py
permissions = guild.fetch_permissions()
print(permissions.economy, permissions.items)
```
### Getting a user's balance
```py
user = guild.fetch_user(user-id)
print(user.cash, user.bank, user.total, user.rank)
```
### Updating a user's balance
This example will add 400 cash to their balance, and remove -100 bank from their bank balance.
```py
user.update_balance(cash=400, bank=-100)
```
### Setting a user's balance
This example set the users cash to 1000, and their bank balance to infinity
```py
import math
user.set_balance(cash=1000, bank=math.inf)
```
### Getting a list of all the items in a user's inventory
```py
for item in user.fetch_inventory():
print(item.name, item.id, item.quantity)
```
### Check how much of an item a user has
```py
user.fetch_item_quantity(item-id)
```
(check out getting an item ID below)
### Add item to user inventory
```py
user.add_item(item-id, quantity=1)
```
(check out getting an item ID below)
### Remove item to user inventory
```py
user.remove_item(item-id, quantity=1)
```
(check out getting an item ID below)
### Get guild leaderboard
```py
for user in user.fetch_leaderboard():
print(user.id, user.rank, user.total)
```
### Get guild store items
```py
for item in user.fetch_items():
print(item.name, item.id, item.price)
```
### Delete guild item
```py
item.delete()
```
Editing guild items will come some time in the future.
## Exceptions
The library may raise these exceptions:
`unbapiException` Base exception for the library
`NotFound` The resource couldn't be found
`InvalidToken` The provided token isn't valid
`Forbidden` The bot can't access this
`TypeError` For a function that accepts `ObjectWithIdAttribute`, the provided object doesn't have an `id` attribute.
## Getting an Item Id
1. Use the `/item info` command from unbelivaboat
2. Click the blue command text after '<your name> used'
3. Copy the long string of numbers in the popup. Example:
Raw data
{
"_id": null,
"home_page": "https://github.com/TreeBen77/unb-api-py",
"name": "unbapi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9.0",
"maintainer_email": "",
"keywords": "",
"author": "TreeBen77",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/4d/72/c56e5a946ac8ea6c13ceb55aaf79014ae381bdc9106fdbf3253c1820c221/unbapi-0.1.0.tar.gz",
"platform": null,
"description": "# unb-api-py\nunb-api-py allows python developers to use the UnbelievaBoat Discord bot API in their own projects! Here's how to get started:\n\n(documentation is coming not-so-soon)\n\n## Getting Started\n\n1. Install the library\n```console\npip install unbapi\n```\n2. Create an UnbelievaBoat Application at https://unbelievaboat.com/applications and copy the token (keep this secret)\n3. Import the library, and create an `Application` object. Example:\n```py\nimport unbapi\n\nunbapp = unb.Application(\"put the token here from step 2.\")\n```\nYou've now created an `Application` object. This allows you to get or fetch a guild object. Here's how to get a guild object:\n```py\nguild = unbapp.get_guild(guild-id)\n```\nThis will create `PartialGuild` object. This allows you to do every action in the guild but doesn't have much information about the app. If you need guild information, such as the name, icon, currency symbol, etc then you should use `unbapp.fetch_guild` which gives a `Guild` object. However, fetching information is slower then 'getting' it.\n\nA `PartialGuild`, or `Guild` object allows you to do things inside of a guild (as long as you have permission), such as: fetching a user's balance (and changing it), getting store items, adding/removing items from user's inventories, and more. Here's how to do each:\n\n## Examples\n\n### Check the bot's permissions in a guild\n```py\npermissions = guild.fetch_permissions()\nprint(permissions.economy, permissions.items)\n```\n\n### Getting a user's balance\n```py\nuser = guild.fetch_user(user-id)\nprint(user.cash, user.bank, user.total, user.rank)\n```\n\n### Updating a user's balance\nThis example will add 400 cash to their balance, and remove -100 bank from their bank balance.\n```py\nuser.update_balance(cash=400, bank=-100)\n```\n\n### Setting a user's balance\nThis example set the users cash to 1000, and their bank balance to infinity\n```py\nimport math\n\nuser.set_balance(cash=1000, bank=math.inf)\n```\n\n### Getting a list of all the items in a user's inventory\n```py\nfor item in user.fetch_inventory():\n print(item.name, item.id, item.quantity)\n```\n\n### Check how much of an item a user has\n```py\nuser.fetch_item_quantity(item-id)\n```\n(check out getting an item ID below)\n\n### Add item to user inventory\n```py\nuser.add_item(item-id, quantity=1)\n```\n(check out getting an item ID below)\n\n### Remove item to user inventory\n```py\nuser.remove_item(item-id, quantity=1)\n```\n(check out getting an item ID below)\n\n### Get guild leaderboard\n```py\nfor user in user.fetch_leaderboard():\n print(user.id, user.rank, user.total)\n```\n\n### Get guild store items\n```py\nfor item in user.fetch_items():\n print(item.name, item.id, item.price)\n```\n\n### Delete guild item\n```py\nitem.delete()\n```\nEditing guild items will come some time in the future.\n\n## Exceptions\nThe library may raise these exceptions:\n`unbapiException` Base exception for the library\n`NotFound` The resource couldn't be found\n`InvalidToken` The provided token isn't valid\n`Forbidden` The bot can't access this\n`TypeError` For a function that accepts `ObjectWithIdAttribute`, the provided object doesn't have an `id` attribute.\n\n## Getting an Item Id\n1. Use the `/item info` command from unbelivaboat\n2. Click the blue command text after '<your name> used'\n3. Copy the long string of numbers in the popup. Example:\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "API wrapper for the UnbelievaBoat Discord bot in Python",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/TreeBen77/unb-api-py"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d6790fc048d5dc4d0b3725ea3c285aa275433903dbc08650a24f41b5e3f129c",
"md5": "e36e521e3c2a826b0cb1623da5219d08",
"sha256": "d91aff8e6a28f32ae1b945a4c6360ae1ca6165e5a08679d727e5cd3bc0a4398e"
},
"downloads": -1,
"filename": "unbapi-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e36e521e3c2a826b0cb1623da5219d08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9.0",
"size": 10984,
"upload_time": "2023-05-24T15:08:19",
"upload_time_iso_8601": "2023-05-24T15:08:19.711898Z",
"url": "https://files.pythonhosted.org/packages/1d/67/90fc048d5dc4d0b3725ea3c285aa275433903dbc08650a24f41b5e3f129c/unbapi-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4d72c56e5a946ac8ea6c13ceb55aaf79014ae381bdc9106fdbf3253c1820c221",
"md5": "5add0ff020d4effd1c702c812a205e4a",
"sha256": "2a9ac24d527fcf7e04d89266a1ba6293161340fc65a3ef8905df307d97982b18"
},
"downloads": -1,
"filename": "unbapi-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5add0ff020d4effd1c702c812a205e4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9.0",
"size": 9261,
"upload_time": "2023-05-24T15:08:21",
"upload_time_iso_8601": "2023-05-24T15:08:21.539783Z",
"url": "https://files.pythonhosted.org/packages/4d/72/c56e5a946ac8ea6c13ceb55aaf79014ae381bdc9106fdbf3253c1820c221/unbapi-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-24 15:08:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TreeBen77",
"github_project": "unb-api-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "unbapi"
}
JSON
