# NSSurge Python API Client
Python implementation of the [Surge HTTP API spec](https://manual.nssurge.com/others/http-api.html) client using `aiohttp`.
You can use it to get/set Surge rules / policies / proxy groups, get recent requests / events and much more.
This projects fully implements the [Surge HTTP API spec](https://manual.nssurge.com/others/http-api.html).
If you're looking for a command line tool to interact with your running Surge app, check out [NSSurge CLI](https://github.com/tddschn/nssurge-cli).
- [NSSurge Python API Client](#nssurge-python-api-client)
- [Installation](#installation)
- [pip](#pip)
- [Usage](#usage)
- [Develop](#develop)
- [See also](#see-also)
## Installation
### [pip](https://pypi.org/project/nssurge-api/)
```
$ pip install nssurge-api
```
## Usage
```python
# source: https://github.com/tddschn/nssurge-cli/blob/master/nssurge_cli/cap_commands.py
from nssurge_cli.types import OnOffToggleEnum
from nssurge_api import SurgeAPIClient
from nssurge_api.types import Capability
import asyncio
async def get_set_cap(
capability: Capability, on_off: OnOffToggleEnum | None = None
) -> bool | tuple[bool, bool]:
"""
Get or set a capability
"""
async with SurgeAPIClient(*get_config()) as client:
state_orig = await get_cap_state(client, capability)
match on_off:
case OnOffToggleEnum.on | OnOffToggleEnum.off:
await client.set_cap(capability, s2b(on_off))
case OnOffToggleEnum.toggle:
await client.set_cap(capability, not state_orig)
case _:
return state_orig
state_new = await get_cap_state(client, capability)
return state_orig, state_new
```
## Develop
```
$ git clone https://github.com/tddschn/nssurge-api.git
$ cd nssurge-api
$ poetry install
```
## See also
- [NSSurge CLI](https://github.com/tddschn/nssurge-cli): Command line Surge HTTP API Client built with this library
- [Surge HTTP API spec](https://manual.nssurge.com/others/http-api.html)
Raw data
{
"_id": null,
"home_page": "https://github.com/tddschn/nssurge-api",
"name": "nssurge-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "nssurge,api,aiohttp",
"author": "Xinyuan Chen",
"author_email": "45612704+tddschn@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/e2/49/e67df2df5fe47d4a9afd5a586a621cf3f1a6f6a3630047daedf00f55acf9/nssurge_api-0.2.17.tar.gz",
"platform": null,
"description": "# NSSurge Python API Client\n\nPython implementation of the [Surge HTTP API spec](https://manual.nssurge.com/others/http-api.html) client using `aiohttp`.\n\nYou can use it to get/set Surge rules / policies / proxy groups, get recent requests / events and much more. \n\nThis projects fully implements the [Surge HTTP API spec](https://manual.nssurge.com/others/http-api.html).\n\nIf you're looking for a command line tool to interact with your running Surge app, check out [NSSurge CLI](https://github.com/tddschn/nssurge-cli).\n\n- [NSSurge Python API Client](#nssurge-python-api-client)\n - [Installation](#installation)\n - [pip](#pip)\n - [Usage](#usage)\n - [Develop](#develop)\n - [See also](#see-also)\n\n\n## Installation\n\n### [pip](https://pypi.org/project/nssurge-api/)\n\n```\n$ pip install nssurge-api\n```\n\n## Usage\n\n```python\n# source: https://github.com/tddschn/nssurge-cli/blob/master/nssurge_cli/cap_commands.py\nfrom nssurge_cli.types import OnOffToggleEnum\nfrom nssurge_api import SurgeAPIClient\nfrom nssurge_api.types import Capability\nimport asyncio\n\nasync def get_set_cap(\n capability: Capability, on_off: OnOffToggleEnum | None = None\n) -> bool | tuple[bool, bool]:\n \"\"\"\n Get or set a capability\n \"\"\"\n async with SurgeAPIClient(*get_config()) as client:\n state_orig = await get_cap_state(client, capability)\n match on_off:\n case OnOffToggleEnum.on | OnOffToggleEnum.off:\n await client.set_cap(capability, s2b(on_off))\n case OnOffToggleEnum.toggle:\n await client.set_cap(capability, not state_orig)\n case _:\n return state_orig\n state_new = await get_cap_state(client, capability)\n return state_orig, state_new\n```\n\n## Develop\n\n```\n$ git clone https://github.com/tddschn/nssurge-api.git\n$ cd nssurge-api\n$ poetry install\n```\n\n## See also\n\n- [NSSurge CLI](https://github.com/tddschn/nssurge-cli): Command line Surge HTTP API Client built with this library\n- [Surge HTTP API spec](https://manual.nssurge.com/others/http-api.html)",
"bugtrack_url": null,
"license": "MIT",
"summary": "NSSurge HTTP API for Python",
"version": "0.2.17",
"project_urls": {
"Bug Tracker": "https://github.com/tddschn/nssurge-api/issues",
"Homepage": "https://github.com/tddschn/nssurge-api",
"Repository": "https://github.com/tddschn/nssurge-api"
},
"split_keywords": [
"nssurge",
"api",
"aiohttp"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d42fdd9e8537ccee1561236a5c5077957992fa1b0168c7f65641d951d928bc14",
"md5": "d94f061152deb66527c589472ee74704",
"sha256": "cc83a9a4042b6d1aac8bb4ff30f0e0f534525f09c2c7b035ca56e32391801f11"
},
"downloads": -1,
"filename": "nssurge_api-0.2.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d94f061152deb66527c589472ee74704",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 6790,
"upload_time": "2023-05-31T14:37:21",
"upload_time_iso_8601": "2023-05-31T14:37:21.502999Z",
"url": "https://files.pythonhosted.org/packages/d4/2f/dd9e8537ccee1561236a5c5077957992fa1b0168c7f65641d951d928bc14/nssurge_api-0.2.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e249e67df2df5fe47d4a9afd5a586a621cf3f1a6f6a3630047daedf00f55acf9",
"md5": "6eb98504fb5b121f3fb40a021fa93f55",
"sha256": "0ac9f517f7bc57dd2dcea55747d9d35bce1cfb42e4f2dcddea69bc399c2bc484"
},
"downloads": -1,
"filename": "nssurge_api-0.2.17.tar.gz",
"has_sig": false,
"md5_digest": "6eb98504fb5b121f3fb40a021fa93f55",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 5741,
"upload_time": "2023-05-31T14:37:23",
"upload_time_iso_8601": "2023-05-31T14:37:23.182425Z",
"url": "https://files.pythonhosted.org/packages/e2/49/e67df2df5fe47d4a9afd5a586a621cf3f1a6f6a3630047daedf00f55acf9/nssurge_api-0.2.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-31 14:37:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tddschn",
"github_project": "nssurge-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nssurge-api"
}
JSON
