Skip to main content

A Python wrapper for the Politics and War API.

Project description




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.


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


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},
  cities {
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
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 ${} as bank record #{}")
  • 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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pnwkit-py-2.6.26.tar.gz (60.4 kB view hashes)

Uploaded Source

Built Distribution

pnwkit_py-2.6.26-py3-none-any.whl (66.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page