pnwkit-py

Politics & War API Library
Explore the docs

JavaScript/TypeScript Version - Report Bug - Request Feature

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.

# 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.

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.

# .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

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

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.

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.

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.

# 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

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

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.

Moving Forward

Improved support for query variables
Argument typings
In-built cache management with subscriptions
Support for query fragments

Release files for pnwkit-py 2.6.26

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pnwkit-py 2.6.26
File	Size	Uploaded
pnwkit-py-2.6.26.tar.gz	60.4 kB	Feb 12, 2024	Details

Built distribution (wheel)

Table of built distributions (wheels) for pnwkit-py 2.6.26
File	Interpreter	ABI	Platform	Reset
pnwkit_py-2.6.26-py3-none-any.whl 66.5 kB Feb 12, 2024	Python 3	none	any	Details

Total release size: 126.9 kB

Release files / pnwkit-py-2.6.26.tar.gz

Download URL	pnwkit-py-2.6.26.tar.gz
Size	60.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`5eba2a58d29f5a031994428306aadb88d5bd668811e105fe9245d4438d31bf6d`
BLAKE2b-256 checksum How to use checksums	`41adbb6a4cb560469257241eef587ce30b745b25ab231fe47e47e7664c3cf93f`
Upload date	Feb 12, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.9.18`

Release files / pnwkit_py-2.6.26-py3-none-any.whl

Download URL	pnwkit_py-2.6.26-py3-none-any.whl
Size	66.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b212e8c8d4cbf7d9df19245eabbf56ddba235eed6fa06f9e3c1fa7d5d475bf6c`
BLAKE2b-256 checksum How to use checksums	`53a399db2563a725316155313f98ce4f2d6f041bc826a8e7561339815e202892`
Upload date	Feb 12, 2024
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.9.18`