# 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", {"orderBy": pnwkit.OrderBy("date", pnwkit.Order.ASC)}, "nation_name")
result = query.get()
print(f"Oldest nation {result.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/41/ad/bb6a4cb560469257241eef587ce30b745b25ab231fe47e47e7664c3cf93f/pnwkit-py-2.6.26.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\", {\"orderBy\": pnwkit.OrderBy(\"date\", pnwkit.Order.ASC)}, \"nation_name\")\nresult = query.get()\n\nprint(f\"Oldest nation {result.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.26",
"project_urls": {
"Documentation": "https://pnwkit-py.readthedocs.io/en/latest/",
"Homepage": "https://github.com/Village05/pnwkit-py",
"Issue tracker": "https://github.com/Village05/pnwkit-py/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53a399db2563a725316155313f98ce4f2d6f041bc826a8e7561339815e202892",
"md5": "1f1690cc6556616255b1f829c2a406ae",
"sha256": "b212e8c8d4cbf7d9df19245eabbf56ddba235eed6fa06f9e3c1fa7d5d475bf6c"
},
"downloads": -1,
"filename": "pnwkit_py-2.6.26-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f1690cc6556616255b1f829c2a406ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 66523,
"upload_time": "2024-02-12T21:16:05",
"upload_time_iso_8601": "2024-02-12T21:16:05.816366Z",
"url": "https://files.pythonhosted.org/packages/53/a3/99db2563a725316155313f98ce4f2d6f041bc826a8e7561339815e202892/pnwkit_py-2.6.26-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "41adbb6a4cb560469257241eef587ce30b745b25ab231fe47e47e7664c3cf93f",
"md5": "76efa07f098f0d4a463b6a37e6260b5f",
"sha256": "5eba2a58d29f5a031994428306aadb88d5bd668811e105fe9245d4438d31bf6d"
},
"downloads": -1,
"filename": "pnwkit-py-2.6.26.tar.gz",
"has_sig": false,
"md5_digest": "76efa07f098f0d4a463b6a37e6260b5f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 60382,
"upload_time": "2024-02-12T21:16:08",
"upload_time_iso_8601": "2024-02-12T21:16:08.038665Z",
"url": "https://files.pythonhosted.org/packages/41/ad/bb6a4cb560469257241eef587ce30b745b25ab231fe47e47e7664c3cf93f/pnwkit-py-2.6.26.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-12 21:16:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Village05",
"github_project": "pnwkit-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pnwkit-py"
}
JSON
