Metadata-Version: 2.1
Name: hishel
Version: 0.0.11
Summary: Persistant cache implementation for httpx and httpcore
Project-URL: Homepage, https://github.com/karosis88/hishel
Project-URL: Source, https://github.com/karosis88/hishel
Author-email: Kar Petrosyan <kar.petrosyanpy@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Framework :: Trio
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Requires-Dist: httpx>=0.22.0
Provides-Extra: redis
Requires-Dist: redis==4.6.0; extra == 'redis'
Provides-Extra: yaml
Requires-Dist: pyyaml==6.0.1; extra == 'yaml'
Description-Content-Type: text/markdown

<p align="center">
  <a href=""><img width="350" height="250" src="https://raw.githubusercontent.com/karosis88/hishel/master/.github/logo.jpg" alt='HTTPX'></a>
</p>


<p align="center"><strong>Hishel</strong> <em>- An elegant HTTP Cache implementation for httpx and httpcore.</em></p>

<p align="center">

  <a href="https://pypi.org/project/hishel">
      <img src="https://img.shields.io/pypi/v/hishel.svg" alt="pypi">
  </a>

  <a href="https://img.shields.io/pypi/l/hishel">
      <img src="https://img.shields.io/pypi/l/hishel" alt="license">
  </a>

  <a href="https://img.shields.io/codecov/c/github/karosis88/hishel">
      <img src="https://img.shields.io/codecov/c/github/karosis88/hishel" alt="license">
  </a>

</p>

-----

**Hishel (հիշել, remember)** is a library that implements HTTP Caching for [HTTPX](https://github.com/encode/httpx) and [HTTP Core](https://github.com/encode/httpcore) libraries in accordance with **RFC 9111**, the most recent caching specification.

## Features

- 💾 Persistence: Responses are cached in the [**persistent memory**](https://en.m.wikipedia.org/wiki/Persistent_memory) for later use.
- 🤲 Compatibility: It is completely compatible with your existing transports or connection pools, **whether they are default, custom, or provided by third-party libraries.**
- 🤗 Easy to use: You continue to use the httpx and httpcore interfaces. **Can be integrated with no changes to the code.**
- 🧠 Smart: Attempts to clearly implement RFC 9111, understands `Vary`, `Etag`, `Last-Modified`,  `Cache-Control`, and `Expires` headers, and **handles response re-validation automatically**.
- ⚙️ Configurable: You have complete control over how the responses are stored and serialized, and there is built-in support for filesystem and redis backends.
- 🚀 Very fast: Your requests will be even faster if there are **no IO operations**.

## Documentation
Go through the [Hishel documentation](https://karosis88.github.io/hishel/).

## QuickStart

Install `Hishel` using pip:
``` shell
$ pip install hishel
```

Let's begin with an example of a httpx client.

```python
import hishel

with hishel.CacheClient() as client:
    client.get("https://www.github.com")
    client.get("https://www.github.com")  # takes from the cache (very fast!)
```

or in asynchronous context

```python
import hishel

async with hishel.AsyncCacheClient() as client:
    await client.get("https://www.github.com")
    await client.get("https://www.github.com")  # takes from the cache
```

## HTTPX and HTTP Core

`Hishel` also supports the transports of `HTTPX` and the connection pools of `HTTP Core`.

`Hishel` respects existing **transports** and **connection pools** and can therefore work **on top of them**, making hishel a very **compatible and flexible library**.


**Transports** example:

``` python
import httpx
import hishel

transport = httpx.HTTPTransport()
cache_transport = hishel.CacheTransport(transport=transport)

req = httpx.Request("GET", "https://www.github.com")

cache_transport.handle_request(req)
cache_transport.handle_request(req)  # takes from the cache
```

**Connection Pool** example:


```python
import httpcore
import hishel

pool = hishel.CacheConnectionPool(pool=httpcore.ConnectionPool())

pool.request("GET", "https://www.github.com")
pool.request("GET", "https://www.github.com")  # takes from the cache

```

## How and where are the responses saved?

The responses are stored by `Hishel` in [storages](https://karosis88.github.io/hishel/userguide/#storages).
You have complete control over them; you can change storage or even write your own if necessary.


## Contributing

`Hishel` is a powerful tool, but it is also a new project with potential flaws, so we welcome contributions!

You can open the pull request by following these instructions if you want to improve `Hishel`. 💓

- Fork the project.
- Make change.
- Open the pull request.

# Changelog

## 0.0.11 (8/15/2023) 

- Add support for request `cache-control` directives. (#42)
- Drop httpcore dependencie. (#40)
- Support HTTP methods only if they are defined as cacheable. (#37)

## 0.0.10 (8/7/2023) 

- Add Response metadata. (#33)
- Add API Reference documentation. (#30)
- Use stale responses only if the client is disconnected. (#28)

## 0.0.9 (8/1/2023) 

- Expose Controller API. (#23)

## 0.0.8 (7/31/2023)

- Skip redis tests if the server was not found. (#16)
- Decrease sleep time for the storage ttl tests. (#18)
- Fail coverage under 100. (#19)

## 0.0.7 (7/30/2023)

- Add support for `Heuristic Freshness`. (#11)
- Change `Controller.cache_heuristically` to `Controller.allow_heuristics`. (#12)
- Handle import errors. (#13)

## 0.0.6 (7/29/2023)

- Fix `Vary` header validation. (#8)
- Dump original requests with the responses. (#7) 

## 0.0.5 (7/29/2023)

- Fix httpx response streaming.

## 0.0.4 (7/29/2023)

- Change `YamlSerializer` name to `YAMLSerializer`.

## 0.0.3 (7/28/2023)

- Add `from_cache` response extension.
- Add `typing_extensions` into the requirements.

## 0.0.2 (7/25/2023)

- Add [redis](https://redis.io/) support.
- Make backends thread and task safe.
- Add black as a new linter.
- Add an expire time for cached responses.
