Install
-------
::
$ pip3 install webclient-helper
Or, install with beautifulsoup4 and lxml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install system requirements for ``lxml``
::
$ sudo apt-get install -y libxml2 libxslt1.1 libxml2-dev libxslt1-dev
or
% brew install libxml2
Install with pip
::
$ pip3 install webclient-helper[bs4]
Usage
-----
``import webclient_helper as wh``
Create an instance of WebClient and use the HTTP methods (OPTIONS, HEAD,
GET, POST, PUT, PATCH, DELETE) to interact with an API.
::
WebClient(username=None, password=None, token=None, token_type=None, base_url='',
user_agent=None, content_type='application/json', extra_headers={})
Interact with an API on the web
If you need to obtain a token from a login endpoint, define a "login"
method when you subclass WebClient and set self._token and self._token_type
Example:
def login(self):
headers = {'Content-Type': 'application/json'}
data = {'email': self._username, 'password': self._password}
response = self.session.post(
self._base_url + '/api/login',
headers=headers,
json=data
)
self._token = response.json().get('access_token')
self._token_type = 'Bearer'
__init__(self, username=None, password=None, token=None, token_type=None,
base_url='', user_agent=None, content_type='application/json',
extra_headers={})
- username: if specified, set auth on session (requires password)
- password: if specified, set auth on session (requires username)
- token: if specified, use this token in the "Authorization" header
(requires token_type)
- token_type: if specified, use as part of the value in the
"Authorization" header
- base_url: base url for service/API that a subclass would interact with
- user_agent: if specified, set "User-Agent" header
- content_type: content type for requests
- extra_headers: a dict of extra headers to set on the session
If no login method is defined, any supplied username/password will be
passed to new_requests_session (for basic auth)
OPTIONS(self, url, headers=None, debug=False, retry=False, **kwargs)
Send a OPTIONS request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
HEAD(self, url, headers=None, debug=False, retry=False, **kwargs)
Send a HEAD request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
GET(self, url, headers=None, params=None, debug=False, retry=False, **kwargs)
Send a GET request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- params: a dict with query string vars and values
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
POST(self, url, headers=None, data=None, json=None, debug=False, retry=False, **kwargs)
Send a POST request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- data: a dict to send in the body (non-JSON)
- json: a dict to send in the body
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
PUT(self, url, headers=None, data=None, debug=False, retry=False, **kwargs)
Send a PUT request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- data: a dict to send in the body (non-JSON)
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
PATCH(self, url, headers=None, data=None, debug=False, retry=False, **kwargs)
Send a PATCH request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- data: a dict to send in the body (non-JSON)
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
DELETE(self, url, headers=None, debug=False, retry=False, **kwargs)
Send a DELETE request and return response object
- url: url/endpoint
- headers: dict of headers to update on the session before making request
- debug: if True, enter debugger before returning
- retry: if True and initial response is "401 Unauthorized", call
self.set_session() and try again
Other kwargs are passed to webclient_helper.session_method
history_explorer(self, return_selections=False)
Select responses from history to explore in ipython (if ipython installed)
- return_selections: if True, return the selections from history
Example (GitHub)
----------------
See https://docs.github.com/en/rest/reference for endpoints to hit.
Note: To (fully) use the GitHub API, first generate a “personal
access token” at https://github.com/settings/tokens/new and save it
to your ``~/.bashrc`` or ``~/.zshrc`` file.
::
export GITHUB_ACCESS_TOKEN="ghp_vx..."
Then use it in your Python code (after ``source ~/.bashrc`` or
``source ~/.zshrc`` for the first time)
::
import webclient_helper as wh
from os import getenv
access_token = getenv('GITHUB_ACCESS_TOKEN')
gh_client = wh.WebClient(token=access_token, token_type='token')
resp = gh_client.GET('https://api.github.com/user/repos')
data = resp.json()
Example (subclass with custom login)
------------------------------------
::
import webclient_helper as wh
class SomeClient(wh.WebClient):
def login(self):
headers = {'Content-Type': 'application/json'}
data = {'email': self._username, 'password': self._password}
response = self.session.post(
self._base_url + '/api/login',
headers=headers,
json=data
)
self._token = response.json().get('access_token')
self._token_type = 'Bearer'
def get_something(self, params=None, debug=False):
return self.GET(
'/api/something',
params=params,
debug=debug
)
some_client = SomeClient(
username='myuser',
password='mypass',
base_url='https://somewhere.com',
)
something1 = some_client.get_something(params={'x': 1, 'y': 5})
something2 = some_client.get_something(params={'x': 2, 'y': 10})
Raw data
{
"_id": null,
"home_page": "https://github.com/kenjyco/webclient-helper",
"name": "webclient-helper",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "webclient,api,requests,soup,beautifulsoup,lxml,http,rest,helper,kenjyco",
"author": "Ken",
"author_email": "kenjyco@gmail.com",
"download_url": "https://github.com/kenjyco/webclient-helper/tarball/v0.0.7",
"platform": null,
"description": "Install\n-------\n\n::\n\n $ pip3 install webclient-helper\n\nOr, install with beautifulsoup4 and lxml\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nInstall system requirements for ``lxml``\n\n::\n\n $ sudo apt-get install -y libxml2 libxslt1.1 libxml2-dev libxslt1-dev\n\n or\n\n % brew install libxml2\n\nInstall with pip\n\n::\n\n $ pip3 install webclient-helper[bs4]\n\nUsage\n-----\n\n ``import webclient_helper as wh``\n\nCreate an instance of WebClient and use the HTTP methods (OPTIONS, HEAD,\nGET, POST, PUT, PATCH, DELETE) to interact with an API.\n\n::\n\n WebClient(username=None, password=None, token=None, token_type=None, base_url='',\n user_agent=None, content_type='application/json', extra_headers={})\n\n Interact with an API on the web\n\n If you need to obtain a token from a login endpoint, define a \"login\"\n method when you subclass WebClient and set self._token and self._token_type\n\n Example:\n\n def login(self):\n headers = {'Content-Type': 'application/json'}\n data = {'email': self._username, 'password': self._password}\n response = self.session.post(\n self._base_url + '/api/login',\n headers=headers,\n json=data\n )\n self._token = response.json().get('access_token')\n self._token_type = 'Bearer'\n\n\n __init__(self, username=None, password=None, token=None, token_type=None,\n base_url='', user_agent=None, content_type='application/json',\n extra_headers={})\n - username: if specified, set auth on session (requires password)\n - password: if specified, set auth on session (requires username)\n - token: if specified, use this token in the \"Authorization\" header\n (requires token_type)\n - token_type: if specified, use as part of the value in the\n \"Authorization\" header\n - base_url: base url for service/API that a subclass would interact with\n - user_agent: if specified, set \"User-Agent\" header\n - content_type: content type for requests\n - extra_headers: a dict of extra headers to set on the session\n\n If no login method is defined, any supplied username/password will be\n passed to new_requests_session (for basic auth)\n\n OPTIONS(self, url, headers=None, debug=False, retry=False, **kwargs)\n Send a OPTIONS request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n HEAD(self, url, headers=None, debug=False, retry=False, **kwargs)\n Send a HEAD request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n GET(self, url, headers=None, params=None, debug=False, retry=False, **kwargs)\n Send a GET request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - params: a dict with query string vars and values\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n POST(self, url, headers=None, data=None, json=None, debug=False, retry=False, **kwargs)\n Send a POST request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - data: a dict to send in the body (non-JSON)\n - json: a dict to send in the body\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n PUT(self, url, headers=None, data=None, debug=False, retry=False, **kwargs)\n Send a PUT request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - data: a dict to send in the body (non-JSON)\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n PATCH(self, url, headers=None, data=None, debug=False, retry=False, **kwargs)\n Send a PATCH request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - data: a dict to send in the body (non-JSON)\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n DELETE(self, url, headers=None, debug=False, retry=False, **kwargs)\n Send a DELETE request and return response object\n\n - url: url/endpoint\n - headers: dict of headers to update on the session before making request\n - debug: if True, enter debugger before returning\n - retry: if True and initial response is \"401 Unauthorized\", call\n self.set_session() and try again\n\n Other kwargs are passed to webclient_helper.session_method\n\n history_explorer(self, return_selections=False)\n Select responses from history to explore in ipython (if ipython installed)\n\n - return_selections: if True, return the selections from history\n\nExample (GitHub)\n----------------\n\n See https://docs.github.com/en/rest/reference for endpoints to hit.\n\n Note: To (fully) use the GitHub API, first generate a \u201cpersonal\n access token\u201d at https://github.com/settings/tokens/new and save it\n to your ``~/.bashrc`` or ``~/.zshrc`` file.\n\n::\n\n export GITHUB_ACCESS_TOKEN=\"ghp_vx...\"\n\nThen use it in your Python code (after ``source ~/.bashrc`` or\n``source ~/.zshrc`` for the first time)\n\n::\n\n import webclient_helper as wh\n from os import getenv\n\n\n access_token = getenv('GITHUB_ACCESS_TOKEN')\n gh_client = wh.WebClient(token=access_token, token_type='token')\n resp = gh_client.GET('https://api.github.com/user/repos')\n data = resp.json()\n\nExample (subclass with custom login)\n------------------------------------\n\n::\n\n import webclient_helper as wh\n\n\n class SomeClient(wh.WebClient):\n def login(self):\n headers = {'Content-Type': 'application/json'}\n data = {'email': self._username, 'password': self._password}\n response = self.session.post(\n self._base_url + '/api/login',\n headers=headers,\n json=data\n )\n self._token = response.json().get('access_token')\n self._token_type = 'Bearer'\n\n def get_something(self, params=None, debug=False):\n return self.GET(\n '/api/something',\n params=params,\n debug=debug\n )\n\n\n some_client = SomeClient(\n username='myuser',\n password='mypass',\n base_url='https://somewhere.com',\n )\n\n something1 = some_client.get_something(params={'x': 1, 'y': 5})\n something2 = some_client.get_something(params={'x': 2, 'y': 10})\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Helpful WebClient class to interact with APIs on the web",
"version": "0.0.7",
"project_urls": {
"Download": "https://github.com/kenjyco/webclient-helper/tarball/v0.0.7",
"Homepage": "https://github.com/kenjyco/webclient-helper"
},
"split_keywords": [
"webclient",
"api",
"requests",
"soup",
"beautifulsoup",
"lxml",
"http",
"rest",
"helper",
"kenjyco"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "06673022eab2ae9298aa69e369991b0222c7f42033a619636632b36272e2d49d",
"md5": "fc086ba78a8709b9f86b237488b8558c",
"sha256": "e791300e901b5ee063afba987546dbb1c3919230d6abe53f7903087a16cac530"
},
"downloads": -1,
"filename": "webclient_helper-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fc086ba78a8709b9f86b237488b8558c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8812,
"upload_time": "2023-08-08T11:05:13",
"upload_time_iso_8601": "2023-08-08T11:05:13.266939Z",
"url": "https://files.pythonhosted.org/packages/06/67/3022eab2ae9298aa69e369991b0222c7f42033a619636632b36272e2d49d/webclient_helper-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-08 11:05:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kenjyco",
"github_project": "webclient-helper",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "webclient-helper"
}
JSON
