# awc
> ari-web comments ( awc ) API wrapper
## what
this libarary is a wrapper for <https://server.ari-web.xyz/> API
to help you manage, query and edit content using it
awc wraps pypika for sql queries and in `sql.helpers` you can access
some pre-made SQL queries, i suggest you use pypika for all ( or at least
most ) sql queries, reason being that manually writing them is
fairly insecure, especially with concat and f-strings
## examples
see the [examples](/examples) folder
## installation
```sh
python3 -m pip install --user awc
```
or ( in the cloned repo dir )
```sh
python3 -m pip install -e .
```
`-e` is for editable, you can also leave it out if you
wont be editing the library
## intro
`awc` is a synchronous library wrapping <https://server.ari-web.xyz/> API, that includes
wrappers for all known endpoints ( see <https://server.ari-web.xyz/git> ) and an interface
to use custom endpoints using `Awc.{request, get, post}` APIs
provided packages :
- `awc` -- base interface for the API ( required for `awc.Awc` interface so other helpers could use it )
- `awc.api` -- wrappers for general APIs ( signatures are `(awc: awc.Awc, ...) -> typing.Any` )
- `awc.const` -- includes required constants for the library and you to use
- \* note : `ip` refers to a SHA256 hash of an IP, not an actual IP
- `awc.exc` -- custom exceptions
- `awc.sql` -- SQL database definitions, wrappers around pypika
- `awc.sql.helpers` -- SQL API helpers, pre-made SQL queries
- `awc.util` -- utilities
- `awc.wrn` -- custom warnings
it all starts from creating an instance of `awc.Awc` object, which is basically
a wrapper around `furl.furl` ( a parsed instance url ) and `requests.Session`
( to make requests to API endpoints ), you instantiate it like this :
```py
api: awc.Awc = awc.Awc("https://some-instance.org/", "optional api key", rate_limit_wait)
```
`rate_limit_wait` is how many seconds should the requester wait if its rate limited ( default value is `5` )
example :
```py
# will sleep 2 seconds if it gets rate limited
api: awc.Awc = awc.Awc("https://google.com/", "HIHIUHIyhu9f839uf9hiuh(U()I*)989hIOUjhfew", 2)
```
after that you are free to use the interface, make requests using the provided requester functions,
get API urls ( `api["some-api-endpoint"]` => `https://google.com/some-api-endpoint` ) and use the
provided library functions, wrappers and abstractions
also, a note : not all library functions will work if you dont have an API key, `awc.Awc.require_key`
decorator is used on all functions that require an API key to work, on no api key it will raise
`awc.exc.NoAPIKeyError` with called function name being the error message
Raw data
{
"_id": null,
"home_page": "https://ari-web.xyz/gh/awc",
"name": "awc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "http,http-client,comments,api,wrapper,https",
"author": "Ari Archer",
"author_email": "ari.web.xyz@gmail.com",
"download_url": "",
"platform": null,
"description": "# awc\n\n> ari-web comments ( awc ) API wrapper\n\n## what\n\nthis libarary is a wrapper for <https://server.ari-web.xyz/> API\nto help you manage, query and edit content using it\n\nawc wraps pypika for sql queries and in `sql.helpers` you can access\nsome pre-made SQL queries, i suggest you use pypika for all ( or at least\nmost ) sql queries, reason being that manually writing them is\nfairly insecure, especially with concat and f-strings\n\n## examples\n\nsee the [examples](/examples) folder\n\n## installation\n\n```sh\npython3 -m pip install --user awc\n```\n\nor ( in the cloned repo dir )\n\n```sh\npython3 -m pip install -e .\n```\n\n`-e` is for editable, you can also leave it out if you\nwont be editing the library\n\n## intro\n\n`awc` is a synchronous library wrapping <https://server.ari-web.xyz/> API, that includes\nwrappers for all known endpoints ( see <https://server.ari-web.xyz/git> ) and an interface\nto use custom endpoints using `Awc.{request, get, post}` APIs\n\nprovided packages :\n\n- `awc` -- base interface for the API ( required for `awc.Awc` interface so other helpers could use it )\n- `awc.api` -- wrappers for general APIs ( signatures are `(awc: awc.Awc, ...) -> typing.Any` )\n- `awc.const` -- includes required constants for the library and you to use\n - \\* note : `ip` refers to a SHA256 hash of an IP, not an actual IP\n- `awc.exc` -- custom exceptions\n- `awc.sql` -- SQL database definitions, wrappers around pypika\n - `awc.sql.helpers` -- SQL API helpers, pre-made SQL queries\n- `awc.util` -- utilities\n- `awc.wrn` -- custom warnings\n\nit all starts from creating an instance of `awc.Awc` object, which is basically\na wrapper around `furl.furl` ( a parsed instance url ) and `requests.Session`\n( to make requests to API endpoints ), you instantiate it like this :\n\n```py\napi: awc.Awc = awc.Awc(\"https://some-instance.org/\", \"optional api key\", rate_limit_wait)\n```\n\n`rate_limit_wait` is how many seconds should the requester wait if its rate limited ( default value is `5` )\n\nexample :\n\n```py\n# will sleep 2 seconds if it gets rate limited\napi: awc.Awc = awc.Awc(\"https://google.com/\", \"HIHIUHIyhu9f839uf9hiuh(U()I*)989hIOUjhfew\", 2)\n```\n\nafter that you are free to use the interface, make requests using the provided requester functions,\nget API urls ( `api[\"some-api-endpoint\"]` => `https://google.com/some-api-endpoint` ) and use the\nprovided library functions, wrappers and abstractions\n\nalso, a note : not all library functions will work if you dont have an API key, `awc.Awc.require_key`\ndecorator is used on all functions that require an API key to work, on no api key it will raise\n`awc.exc.NoAPIKeyError` with called function name being the error message\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "wrapper for ari-web comments API",
"version": "3.1.0",
"project_urls": {
"Homepage": "https://ari-web.xyz/gh/awc"
},
"split_keywords": [
"http",
"http-client",
"comments",
"api",
"wrapper",
"https"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "32bdffcf9a8d11c39e10c2915a979d22d336f56f937976c92cdc69a2c0524654",
"md5": "439cdda0628a2042497d2bf64cead376",
"sha256": "014471411a7a4e82c17b44def6fa7830cb0be02995d86425ba9b55ea87f13c26"
},
"downloads": -1,
"filename": "awc-3.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "439cdda0628a2042497d2bf64cead376",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 23909,
"upload_time": "2023-05-09T16:10:42",
"upload_time_iso_8601": "2023-05-09T16:10:42.594961Z",
"url": "https://files.pythonhosted.org/packages/32/bd/ffcf9a8d11c39e10c2915a979d22d336f56f937976c92cdc69a2c0524654/awc-3.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-09 16:10:42",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "awc"
}
JSON