pnwkit-py


Namepnwkit-py JSON
Version 2.6.19 PyPI version JSON
download
home_pagehttps://github.com/Village05/pnwkit-py
SummaryA Python wrapper for the Politics and War API.
upload_time2023-01-25 03:08:21
maintainer
docs_urlNone
authorVillage
requires_python>=3.8.0
licenseMIT
keywords
VCS
bugtrack_url
requirements aiohttp requests beautifulsoup4
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", {}, "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"
}
        
Elapsed time: 0.10380s