Metadata-Version: 2.1
Name: clients
Version: 1.5
Summary: High-level HTTP clients for Python.
Author-email: Aric Coady <aric.coady@gmail.com>
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.
        
Project-URL: Homepage, https://github.com/coady/clients
Project-URL: Documentation, https://coady.github.io/clients
Project-URL: Changelog, https://github.com/coady/clients/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/coady/clients/issues
Keywords: requests,sessions,responses,resources,asyncio
Classifier: Development Status :: 6 - Mature
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: httpx >=0.25

[![image](https://img.shields.io/pypi/v/clients.svg)](https://pypi.org/project/clients/)
![image](https://img.shields.io/pypi/pyversions/clients.svg)
[![image](https://pepy.tech/badge/clients)](https://pepy.tech/project/clients)
![image](https://img.shields.io/pypi/status/clients.svg)
[![image](https://github.com/coady/clients/workflows/build/badge.svg)](https://github.com/coady/clients/actions)
[![image](https://codecov.io/gh/coady/clients/branch/main/graph/badge.svg)](https://codecov.io/gh/coady/clients/)
[![image](https://github.com/coady/clients/workflows/codeql/badge.svg)](https://github.com/coady/clients/security/code-scanning)
[![image](https://img.shields.io/badge/code%20style-black-000000.svg)](https://pypi.org/project/black/)
[![image](https://mypy-lang.org/static/mypy_badge.svg)](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]
```
