# pnwkit-py
<p align="center">
<a href="https://github.com/Village05/pnwkit-py">
<img src="https://raw.githubusercontent.com/Village05/pnwkit-py/master/logo.png" alt="Logo" width="120" height="120">
</a>
<h3 align="center">pnwkit-py</h3>
<p align="center">
Politics & War API Library
<br />
<a href="https://pnwkit-py.readthedocs.io"><strong>Explore the docs</strong></a>
<br />
<br />
<a href="https://www.npmjs.com/package/pnwkit">JavaScript/TypeScript Version</a>
-
<a href="https://github.com/Village05/pnwkit-py/issues">Report Bug</a>
-
<a href="https://github.com/Village05/pnwkit-py/issues">Request Feature</a>
</p>
</p>
pnwkit-py is here to make interacting with the V3 Politics and War API easy. All you have to do is import the library, add your key, and make a query.
## Getting Started
To get started using pnwkit-py you must first have Python and PIP installed.
### Installing
Python 3.9 or higher is required.
Install the library using PIP.
```sh
# Linux/MacOS
python3 -m pip install -U pnwkit-py
# Windows
py -3 -m pip install -U pnwkit-py
```
## Usage
To use pnwkit-py just import the library, create a QueryKit, then you can make synchronous or asynchronous queries.
```py
import pnwkit
kit = pnwkit.QueryKit("YOUR_API_KEY")
query = kit.query("nations", {"id": 251584, "first": 1}, "nation_name")
# get synchronously
result = query.get()
# get asynchronously
result = await query.get_async()
# OR
result = await query
print(f"Nation name: {result.nations[0].nation_name}")
```
If you want to paginate your query for more results, just ask to paginate the query. Instead of returning a tuple of results, pnwkit will return a `Paginator` object which you can iterate through. For asynchronous queries you can use `async for` to iterate through the results. In addition, async paginators support batching queries to perform multiple queries simultaneously.
```py
# .batch is async only, will perform 2 queries
# when it runs out of results instead of one at a time
nations = query.paginate("nations")
# async only
async_nations = query.paginate("nations").batch(2)
for nation in nations:
print(f"Nation name: {nation.nation_name}")
async for nation in nations:
print(f"Nation name: {nation.nation_name}")
print(f"Current page: {nations.paginator_info.currentPage}")
```
The queries are written in normal GraphQL, so you can get all the cities in a nation like this
```py
query = kit.query("nations", {"id", 251584, "first": 1},
"""
nation_name
cities {
name
}
"""
)
result = query.get()
print(f"First city of {result.nations[0].nation_name}: {result.nations[0].cities[0].name}")
```
Unlike the JavaScript/TypeScript and Google Apps Script libraries, the Python library has a few additional features.
- Support for subscriptions
```py
async def callback(nation):
... # this function will be called every time an event is received
# nation is a Nation object with the updated fields
subscription = await kit.subscribe("nation", "update")
async for nation in subscription:
... # here nation is a Nation object with the updated fields
```
- Additional arguments on a query will be concatenated with the first to form the query.
- You can also just pnwkit.Field to get support for nested fields without using raw GraphQL.
```py
query = kit.query("nations", {"id", 251584, "first": 1}, "nation_name", pnwkit.Field("cities", {}, "name"))
result = query.get()
print(f"First city of {result.nations[0].nation_name}: {result.nations[0].cities[0].name}")
```
- Keyword arguments provided to a query function will be passed in as query variables.
- When pnwkit.Variable, check the API docs for the correct type for your argument.
```py
query = kit.query("nations", {"id": pnwkit.Variable("id", pnwkit.VariableType.INT_ARRAY), "first": 1}, "nation_name", pnwkit.Field("cities", {}, "name"), id=251584)
# variables can also be set with the set_variables method
query.set_variables(id=251584)
result = query.get()
print(f"First city of {result.nations[0].nation_name}: {result.nations[0].cities[0].name}")
```
- Extensions to access the daily data dumps and scrape data from the game.
- Access to the bankWithdraw and bankDeposit mutations.
```py
# the API requires a verified bot key to use mutations
kit = pnwkit.QueryKit("YOUR_API_KEY", bot_key="YOUR_BOT_KEY", bot_key_api_key="YOUR_BOT_KEY_API_KEY")
query = kit.mutation("bankDeposit", {"money": 100}, "id")
result = query.get()
print(f"Deposited ${result.bankDeposit.money} as bank record #{result.bankDeposit.id}")
```
- Query fields as aliases
```py
query = kit.query_as("nations", "the_nations", {"id": 251584, "first": 1}, "nation_name", pnwkit.Field("cities", {}, "name"))
result = query.get()
print(f"First city of {result.the_nations[0].nation_name}: {result.the_nations[0].cities[0].name}")
```
- Ordering results
```py
query = kit.query("nations", {}, "nation_name", pnwkit.OrderBy("date", pnwkit.Order.DESC))
result = query.get()
print(f"Oldest nation {result.the_nations[0].nation_name}")
```
You can look at the arguments and possible data to collect here by experimenting on the [GraphQL Playground](https://api.politicsandwar.com/graphql-playground).
## Moving Forward
- Improved support for query variables
- Argument typings
- In-built cache management with subscriptions
- Support for query fragments
Raw data
{
"_id": null,
"home_page": "https://github.com/Village05/pnwkit-py",
"name": "pnwkit-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": "",
"keywords": "",
"author": "Village",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/8c/67/292966e60dcc1d16ead0d0ebd3c7ba9163dc15fcd6dd9713fecaafbe9372/pnwkit-py-2.6.19.tar.gz",
"platform": null,
"description": "# pnwkit-py\n\n<p align=\"center\">\n <a href=\"https://github.com/Village05/pnwkit-py\">\n <img src=\"https://raw.githubusercontent.com/Village05/pnwkit-py/master/logo.png\" alt=\"Logo\" width=\"120\" height=\"120\">\n </a>\n\n <h3 align=\"center\">pnwkit-py</h3>\n\n <p align=\"center\">\n Politics & War API Library\n <br />\n <a href=\"https://pnwkit-py.readthedocs.io\"><strong>Explore the docs</strong></a>\n <br />\n <br />\n <a href=\"https://www.npmjs.com/package/pnwkit\">JavaScript/TypeScript Version</a>\n -\n <a href=\"https://github.com/Village05/pnwkit-py/issues\">Report Bug</a>\n -\n <a href=\"https://github.com/Village05/pnwkit-py/issues\">Request Feature</a>\n </p>\n</p>\n\npnwkit-py is here to make interacting with the V3 Politics and War API easy. All you have to do is import the library, add your key, and make a query.\n\n## Getting Started\n\nTo get started using pnwkit-py you must first have Python and PIP installed.\n\n### Installing\n\nPython 3.9 or higher is required.\n\nInstall the library using PIP.\n\n```sh\n# Linux/MacOS\npython3 -m pip install -U pnwkit-py\n\n# Windows\npy -3 -m pip install -U pnwkit-py\n```\n\n## Usage\n\nTo use pnwkit-py just import the library, create a QueryKit, then you can make synchronous or asynchronous queries.\n\n```py\nimport pnwkit\nkit = pnwkit.QueryKit(\"YOUR_API_KEY\")\n\nquery = kit.query(\"nations\", {\"id\": 251584, \"first\": 1}, \"nation_name\")\n# get synchronously\nresult = query.get()\n# get asynchronously\nresult = await query.get_async()\n# OR\nresult = await query\n\nprint(f\"Nation name: {result.nations[0].nation_name}\")\n```\n\nIf you want to paginate your query for more results, just ask to paginate the query. Instead of returning a tuple of results, pnwkit will return a `Paginator` object which you can iterate through. For asynchronous queries you can use `async for` to iterate through the results. In addition, async paginators support batching queries to perform multiple queries simultaneously.\n\n```py\n# .batch is async only, will perform 2 queries\n# when it runs out of results instead of one at a time\nnations = query.paginate(\"nations\")\n# async only\nasync_nations = query.paginate(\"nations\").batch(2)\n\nfor nation in nations:\n print(f\"Nation name: {nation.nation_name}\")\nasync for nation in nations:\n print(f\"Nation name: {nation.nation_name}\")\nprint(f\"Current page: {nations.paginator_info.currentPage}\")\n```\n\nThe queries are written in normal GraphQL, so you can get all the cities in a nation like this\n\n```py\nquery = kit.query(\"nations\", {\"id\", 251584, \"first\": 1},\n \"\"\"\n nation_name\n cities {\n name\n }\n \"\"\"\n)\nresult = query.get()\n\nprint(f\"First city of {result.nations[0].nation_name}: {result.nations[0].cities[0].name}\")\n```\n\nUnlike the JavaScript/TypeScript and Google Apps Script libraries, the Python library has a few additional features.\n\n- Support for subscriptions\n\n```py\nasync def callback(nation):\n ... # this function will be called every time an event is received\n # nation is a Nation object with the updated fields\n\nsubscription = await kit.subscribe(\"nation\", \"update\")\nasync for nation in subscription:\n ... # here nation is a Nation object with the updated fields\n```\n\n- Additional arguments on a query will be concatenated with the first to form the query.\n- You can also just pnwkit.Field to get support for nested fields without using raw GraphQL.\n\n```py\nquery = kit.query(\"nations\", {\"id\", 251584, \"first\": 1}, \"nation_name\", pnwkit.Field(\"cities\", {}, \"name\"))\nresult = query.get()\n\nprint(f\"First city of {result.nations[0].nation_name}: {result.nations[0].cities[0].name}\")\n```\n\n- Keyword arguments provided to a query function will be passed in as query variables.\n- When pnwkit.Variable, check the API docs for the correct type for your argument.\n\n```py\nquery = kit.query(\"nations\", {\"id\": pnwkit.Variable(\"id\", pnwkit.VariableType.INT_ARRAY), \"first\": 1}, \"nation_name\", pnwkit.Field(\"cities\", {}, \"name\"), id=251584)\n# variables can also be set with the set_variables method\nquery.set_variables(id=251584)\nresult = query.get()\n\n\nprint(f\"First city of {result.nations[0].nation_name}: {result.nations[0].cities[0].name}\")\n```\n\n- Extensions to access the daily data dumps and scrape data from the game.\n- Access to the bankWithdraw and bankDeposit mutations.\n\n```py\n# the API requires a verified bot key to use mutations\nkit = pnwkit.QueryKit(\"YOUR_API_KEY\", bot_key=\"YOUR_BOT_KEY\", bot_key_api_key=\"YOUR_BOT_KEY_API_KEY\")\n\nquery = kit.mutation(\"bankDeposit\", {\"money\": 100}, \"id\")\nresult = query.get()\n\nprint(f\"Deposited ${result.bankDeposit.money} as bank record #{result.bankDeposit.id}\")\n```\n\n- Query fields as aliases\n\n```py\nquery = kit.query_as(\"nations\", \"the_nations\", {\"id\": 251584, \"first\": 1}, \"nation_name\", pnwkit.Field(\"cities\", {}, \"name\"))\nresult = query.get()\n\nprint(f\"First city of {result.the_nations[0].nation_name}: {result.the_nations[0].cities[0].name}\")\n```\n\n- Ordering results\n\n```py\nquery = kit.query(\"nations\", {}, \"nation_name\", pnwkit.OrderBy(\"date\", pnwkit.Order.DESC))\nresult = query.get()\n\nprint(f\"Oldest nation {result.the_nations[0].nation_name}\")\n```\n\nYou can look at the arguments and possible data to collect here by experimenting on the [GraphQL Playground](https://api.politicsandwar.com/graphql-playground).\n\n## Moving Forward\n\n- Improved support for query variables\n- Argument typings\n- In-built cache management with subscriptions\n- Support for query fragments\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python wrapper for the Politics and War API.",
"version": "2.6.19",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70f7323a29f6e923d143751a2c75bef3b205e9e0582a9b60aefee715f37d1704",
"md5": "3eb9c725ee23c6c0aa3ad1b5e1a33acd",
"sha256": "9bc20281fb4c2eeec796771f29327e54d459db4a07c8181e1a848b8c69037e59"
},
"downloads": -1,
"filename": "pnwkit_py-2.6.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3eb9c725ee23c6c0aa3ad1b5e1a33acd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 59001,
"upload_time": "2023-01-25T03:08:19",
"upload_time_iso_8601": "2023-01-25T03:08:19.643874Z",
"url": "https://files.pythonhosted.org/packages/70/f7/323a29f6e923d143751a2c75bef3b205e9e0582a9b60aefee715f37d1704/pnwkit_py-2.6.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8c67292966e60dcc1d16ead0d0ebd3c7ba9163dc15fcd6dd9713fecaafbe9372",
"md5": "7bb7b10bdee19b96ccec16a324eaf386",
"sha256": "c6657af587459296d24e07c73ce3a1551f45a739f0de3cdf25a79325e4087dee"
},
"downloads": -1,
"filename": "pnwkit-py-2.6.19.tar.gz",
"has_sig": false,
"md5_digest": "7bb7b10bdee19b96ccec16a324eaf386",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 52620,
"upload_time": "2023-01-25T03:08:21",
"upload_time_iso_8601": "2023-01-25T03:08:21.199574Z",
"url": "https://files.pythonhosted.org/packages/8c/67/292966e60dcc1d16ead0d0ebd3c7ba9163dc15fcd6dd9713fecaafbe9372/pnwkit-py-2.6.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-25 03:08:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Village05",
"github_project": "pnwkit-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
"<",
"3.9.0"
],
[
">=",
"3.7.0"
]
]
},
{
"name": "requests",
"specs": [
[
"<",
"2.29.0"
],
[
">=",
"2.25.0"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.10.0"
],
[
"<",
"4.12.0"
]
]
}
],
"lcname": "pnwkit-py"
}
JSON
