pnwkit-py


Namepnwkit-py JSON
Version 2.6.26 PyPI version JSON
download
home_pagehttps://github.com/Village05/pnwkit-py
SummaryA Python wrapper for the Politics and War API.
upload_time2024-02-12 21:16:08
maintainer
docs_urlNone
authorVillage
requires_python>=3.8.0
licenseMIT
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.23906s