[](https://pypi.org/project/clients/)
[](https://pepy.tech/project/clients)
[](https://github.com/coady/clients/actions)
[](https://codecov.io/gh/coady/clients/)
[](https://github.com/coady/clients/security/code-scanning)
[](https://pypi.org/project/black/)
[](https://mypy-lang.org/)
Clients originally provided [requests](https://python-requests.org) wrappers to encourage best practices, particularly always using Sessions to connect to the same host or api endpoint. The primary goals were:
* provide a `Client` object with a convenient constructor
* support a base url so that requests can provide a relative path
* provide the same interface for asyncio
Since then [httpx](https://www.encode.io/httpx) has emerged as the successor to `requests`, and supports the above features natively. So `clients.Client` can be replaced with `httpx.Client` for most use cases. The project will continue to be maintained for additional features, such as the `Resource` object.
## Usage
Typical `requests` usage is redundant and inefficient, by not taking advantage of connection pooling.
```python
r = requests.get('https://api.github.com/user', headers={'authorization': token})
r = requests.get('https://api.github.com/user/repos', headers={'authorization': token})
```
Using sessions is the better approach, but more verbose and in practice requires manual url joining.
```python
s = requests.Session()
s.headers['authorization'] = token
r = s.get('https://api.github.com/user')
r = s.get('https://api.github.com/user/repos')
```
### Client
Clients make using sessions easier, with implicit url joining.
```python
client = clients.Client('https://api.github.com/', headers={'authorization': token})
r = client.get('user')
r = client.get('user/repos')
```
### Resource
Resources extend Clients to implicitly handle response content, with proper checking of status_code and content-type.
```python
github = clients.Resource('https://api.github.com/', headers={'authorization': token})
for repo in github.get('user/repos', params={'visibility': 'public'}):
...
```
Resources also implement syntactic support for methods such as __getattr__ and __call__, providing most of the benefits of custom clients as is.
```python
for repo in github.user.repos(visibility='public'):
...
```
Asynchronous variants of all client types are provided, e.g., `AsyncClient`. Additional clients for [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call), [GraphQL](https://graphql.org), and proxies also provided.
## Installation
```console
% pip install clients
```
## Dependencies
* httpx
## Tests
100% branch coverage.
```console
% pytest [--cov]
```
Raw data
{
"_id": null,
"home_page": "",
"name": "clients",
"maintainer": "",
"docs_url": "https://pythonhosted.org/clients/",
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "requests,sessions,responses,resources,asyncio",
"author": "",
"author_email": "Aric Coady <aric.coady@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/97/ac/58af351b3a1cd861911e3cebe9708e659b6ed285fb688b323c24857023d6/clients-1.5.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/clients/)\n\n[](https://pepy.tech/project/clients)\n\n[](https://github.com/coady/clients/actions)\n[](https://codecov.io/gh/coady/clients/)\n[](https://github.com/coady/clients/security/code-scanning)\n[](https://pypi.org/project/black/)\n[](https://mypy-lang.org/)\n\nClients originally provided [requests](https://python-requests.org) wrappers to encourage best practices, particularly always using Sessions to connect to the same host or api endpoint. The primary goals were:\n* provide a `Client` object with a convenient constructor\n* support a base url so that requests can provide a relative path\n* provide the same interface for asyncio\n\nSince then [httpx](https://www.encode.io/httpx) has emerged as the successor to `requests`, and supports the above features natively. So `clients.Client` can be replaced with `httpx.Client` for most use cases. The project will continue to be maintained for additional features, such as the `Resource` object.\n\n## Usage\nTypical `requests` usage is redundant and inefficient, by not taking advantage of connection pooling.\n\n```python\nr = requests.get('https://api.github.com/user', headers={'authorization': token})\nr = requests.get('https://api.github.com/user/repos', headers={'authorization': token})\n```\n\nUsing sessions is the better approach, but more verbose and in practice requires manual url joining.\n\n```python\ns = requests.Session()\ns.headers['authorization'] = token\nr = s.get('https://api.github.com/user')\nr = s.get('https://api.github.com/user/repos')\n```\n\n### Client\nClients make using sessions easier, with implicit url joining.\n\n```python\nclient = clients.Client('https://api.github.com/', headers={'authorization': token})\nr = client.get('user')\nr = client.get('user/repos')\n```\n\n### Resource\nResources extend Clients to implicitly handle response content, with proper checking of status_code and content-type.\n\n```python\ngithub = clients.Resource('https://api.github.com/', headers={'authorization': token})\nfor repo in github.get('user/repos', params={'visibility': 'public'}):\n ...\n```\n\nResources also implement syntactic support for methods such as __getattr__ and __call__, providing most of the benefits of custom clients as is.\n\n```python\nfor repo in github.user.repos(visibility='public'):\n ...\n```\n\nAsynchronous variants of all client types are provided, e.g., `AsyncClient`. Additional clients for [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call), [GraphQL](https://graphql.org), and proxies also provided.\n\n## Installation\n```console\n% pip install clients\n```\n\n## Dependencies\n* httpx\n\n## Tests\n100% branch coverage.\n```console\n% pytest [--cov]\n```\n",
"bugtrack_url": null,
"license": "Copyright 2022 Aric Coady Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "High-level HTTP clients for Python.",
"version": "1.5",
"project_urls": {
"Changelog": "https://github.com/coady/clients/blob/main/CHANGELOG.md",
"Documentation": "https://coady.github.io/clients",
"Homepage": "https://github.com/coady/clients",
"Issues": "https://github.com/coady/clients/issues"
},
"split_keywords": [
"requests",
"sessions",
"responses",
"resources",
"asyncio"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c6627cdbb2d61cea846dfab6f63d0ddad9286369e66ee9c9e2a00c9cf136e12",
"md5": "34294d7037814f52d3e5d73ea75eed48",
"sha256": "36a174fc5247811ea84255f4021a994405975b82b98a1d735d71e3a3da8e6a46"
},
"downloads": -1,
"filename": "clients-1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34294d7037814f52d3e5d73ea75eed48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9096,
"upload_time": "2023-11-19T17:16:13",
"upload_time_iso_8601": "2023-11-19T17:16:13.085442Z",
"url": "https://files.pythonhosted.org/packages/8c/66/27cdbb2d61cea846dfab6f63d0ddad9286369e66ee9c9e2a00c9cf136e12/clients-1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "97ac58af351b3a1cd861911e3cebe9708e659b6ed285fb688b323c24857023d6",
"md5": "64aa6cec0a6b23b109e57255ad4d2514",
"sha256": "845c90539b7c7211dd4ac2fcaecec18ec29dcd03e40a283866c9510f795025b7"
},
"downloads": -1,
"filename": "clients-1.5.tar.gz",
"has_sig": false,
"md5_digest": "64aa6cec0a6b23b109e57255ad4d2514",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 11128,
"upload_time": "2023-11-19T17:16:14",
"upload_time_iso_8601": "2023-11-19T17:16:14.620660Z",
"url": "https://files.pythonhosted.org/packages/97/ac/58af351b3a1cd861911e3cebe9708e659b6ed285fb688b323c24857023d6/clients-1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-19 17:16:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "coady",
"github_project": "clients",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "clients"
}
JSON
