hishel 0.1.5__py3-none-any.whl → 1.0.0.dev1__py3-none-any.whl

hishel/beta/_core/_sync/_storages/_sqlite.py

@@ -1,411 +0,0 @@
-from __future__ import annotations
-
-import time
-import uuid
-from dataclasses import replace
-from typing import (
-    Iterable,
-    Iterator,
-    Callable,
-    List,
-    Literal,
-    Optional,
-    Union,
-)
-
-import sqlite3
-
-from hishel.beta._core._base._storages._base import SyncBaseStorage, ensure_cache_dict
-from hishel.beta._core._base._storages._packing import pack, unpack
-from hishel.beta._core.models import (
-    CompletePair,
-    IncompletePair,
-    Pair,
-    PairMeta,
-    Request,
-    Response,
-)
-
-
-class SyncSqliteStorage(SyncBaseStorage):
-    _STREAM_KIND = {"request": 0, "response": 1}
-    _COMPLETE_CHUNK_NUMBER = -1
-
-    def __init__(
-        self,
-        *,
-        connection: Optional[sqlite3.Connection] = None,
-        database_path: str = "hishel_cache.db",
-        default_ttl: Optional[float] = None,
-        refresh_ttl_on_access: bool = True,
-    ) -> None:
-        base_path = ensure_cache_dict()
-
-        self.connection = connection
-        self.database_path = base_path / database_path
-        self.default_ttl = default_ttl
-        self.refresh_ttl_on_access = refresh_ttl_on_access
-        self.last_cleanup = float("-inf")
-        self._initialized = False
-
-    def _ensure_connection(self) -> sqlite3.Connection:
-        """Ensure connection is established and database is initialized."""
-        if self.connection is None:
-            self.connection = sqlite3.connect(str(self.database_path))
-        if not self._initialized:
-            self._initialize_database()
-            self._initialized = True
-        return self.connection
-
-    def _initialize_database(self) -> None:
-        """Initialize the database schema."""
-        assert self.connection is not None
-        cursor = self.connection.cursor()
-
-        # Table for storing request/response pairs
-        cursor.execute("""
-            CREATE TABLE IF NOT EXISTS entries (
-                id BLOB PRIMARY KEY,
-                cache_key BLOB,
-                data BLOB NOT NULL,
-                created_at REAL NOT NULL,
-                deleted_at REAL
-            )
-        """)
-
-        # Table for storing stream chunks
-        cursor.execute("""
-            CREATE TABLE IF NOT EXISTS streams (
-                entry_id BLOB NOT NULL,
-                kind INTEGER NOT NULL,
-                chunk_number INTEGER NOT NULL,
-                chunk_data BLOB NOT NULL,
-                PRIMARY KEY (entry_id, kind, chunk_number),
-                FOREIGN KEY (entry_id) REFERENCES entries(id) ON DELETE CASCADE
-            )
-        """)
-
-        # Indexes for performance
-        cursor.execute("CREATE INDEX IF NOT EXISTS idx_entries_deleted_at ON entries(deleted_at)")
-        cursor.execute("CREATE INDEX IF NOT EXISTS idx_entries_cache_key ON entries(cache_key)")
-        # Note: PRIMARY KEY (entry_id, kind, chunk_number) already provides an index
-        # for queries like: entry_id = ? AND kind = ? AND chunk_number = ?
-
-        self.connection.commit()
-
-    def create_pair(
-        self,
-        request: Request,
-        id: uuid.UUID | None = None,
-    ) -> IncompletePair:
-        pair_id = id if id is not None else uuid.uuid4()
-        pair_meta = PairMeta(
-            created_at=time.time(),
-        )
-
-        pair = IncompletePair(id=pair_id, request=request, meta=pair_meta)
-
-        packed_pair = pack(pair, kind="pair")
-
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-        cursor.execute(
-            "INSERT INTO entries (id, cache_key, data, created_at, deleted_at) VALUES (?, ?, ?, ?, ?)",
-            (pair_id.bytes, None, packed_pair, pair_meta.created_at, None),
-        )
-        connection.commit()
-
-        assert isinstance(request.stream, Iterable), "Request stream must be an Iterable, not Iterable"
-
-        request = Request(
-            method=request.method,
-            url=request.url,
-            headers=request.headers,
-            metadata=request.metadata,
-            stream=self._save_stream(request.stream, pair_id.bytes, "request"),
-        )
-
-        return replace(pair, request=request)
-
-    def add_response(
-        self,
-        pair_id: uuid.UUID,
-        response: Response,
-        key: str | bytes,
-    ) -> CompletePair:
-        if isinstance(key, str):
-            key = key.encode("utf-8")
-
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-
-        # Get the existing pair
-        cursor.execute("SELECT data FROM entries WHERE id = ?", (pair_id.bytes,))
-        result = cursor.fetchone()
-
-        if result is None:
-            raise ValueError(f"Entry with ID {pair_id} not found.")
-
-        pair = unpack(result[0], kind="pair")
-
-        assert isinstance(response.stream, (Iterator, Iterable))
-        response = replace(response, stream=self._save_stream(response.stream, pair_id.bytes, "response"))
-
-        self._delete_stream(pair.id.bytes, cursor, type="response")
-        complete_pair = CompletePair(id=pair.id, request=pair.request, response=response, meta=pair.meta, cache_key=key)
-
-        # Update the entry with the complete pair and set cache_key
-        cursor.execute(
-            "UPDATE entries SET data = ?, cache_key = ? WHERE id = ?",
-            (pack(complete_pair, kind="pair"), key, pair_id.bytes),
-        )
-        connection.commit()
-
-        return complete_pair
-
-    def get_pairs(self, key: str) -> List[CompletePair]:
-        final_pairs: List[CompletePair] = []
-
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-        # Query entries directly by cache_key
-        cursor.execute("SELECT id, data FROM entries WHERE cache_key = ?", (key.encode("utf-8"),))
-
-        for row in cursor.fetchall():
-            pair_data = unpack(row[1], kind="pair")
-
-            if isinstance(pair_data, IncompletePair):
-                continue
-
-            final_pairs.append(pair_data)
-
-        pairs_with_streams: List[CompletePair] = []
-
-        for pair in final_pairs:
-            pairs_with_streams.append(
-                replace(
-                    pair,
-                    response=replace(
-                        pair.response,
-                        stream=self._stream_data_from_cache(pair.id.bytes, "response"),
-                    ),
-                    request=replace(
-                        pair.request,
-                        stream=self._stream_data_from_cache(pair.id.bytes, "request"),
-                    ),
-                )
-            )
-        return pairs_with_streams
-
-    def update_pair(
-        self,
-        id: uuid.UUID,
-        new_pair: Union[CompletePair, Callable[[CompletePair], CompletePair]],
-    ) -> Optional[CompletePair]:
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-        cursor.execute("SELECT data FROM entries WHERE id = ?", (id.bytes,))
-        result = cursor.fetchone()
-
-        if result is None:
-            return None
-
-        pair = unpack(result[0], kind="pair")
-
-        if isinstance(pair, IncompletePair):
-            return None
-
-        if isinstance(new_pair, CompletePair):
-            complete_pair = new_pair
-        else:
-            complete_pair = new_pair(pair)
-
-        if pair.id != complete_pair.id:
-            raise ValueError("Pair ID mismatch")
-
-        cursor.execute("UPDATE entries SET data = ? WHERE id = ?", (pack(complete_pair, kind="pair"), id.bytes))
-
-        if pair.cache_key != complete_pair.cache_key:
-            cursor.execute(
-                "UPDATE entries SET cache_key = ? WHERE id = ?",
-                (complete_pair.cache_key, complete_pair.id.bytes),
-            )
-
-        connection.commit()
-
-        return complete_pair
-
-    def remove(self, id: uuid.UUID) -> None:
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-        cursor.execute("SELECT data FROM entries WHERE id = ?", (id.bytes,))
-        result = cursor.fetchone()
-
-        if result is None:
-            return None
-
-        pair = unpack(result[0], kind="pair")
-        self._soft_delete_pair(pair, cursor)
-        connection.commit()
-
-    def _is_stream_complete(
-        self, kind: Literal["request", "response"], pair_id: uuid.UUID, cursor: sqlite3.Cursor
-    ) -> bool:
-        kind_id = self._STREAM_KIND[kind]
-        # Check if there's a completion marker (chunk_number = -1)
-        cursor.execute(
-            "SELECT 1 FROM streams WHERE entry_id = ? AND kind = ? AND chunk_number = ? LIMIT 1",
-            (pair_id.bytes, kind_id, self._COMPLETE_CHUNK_NUMBER),
-        )
-        return cursor.fetchone() is not None
-
-    def _soft_delete_pair(self, pair: Union[CompletePair, IncompletePair], cursor: sqlite3.Cursor) -> None:
-        """
-        Mark the pair as deleted by setting the deleted_at timestamp.
-        """
-        marked_pair = self.mark_pair_as_deleted(pair)
-        cursor.execute(
-            "UPDATE entries SET data = ?, deleted_at = ? WHERE id = ?",
-            (pack(marked_pair, kind="pair"), marked_pair.meta.deleted_at, pair.id.bytes),
-        )
-
-    def _is_pair_expired(self, pair: Pair, cursor: sqlite3.Cursor) -> bool:
-        """
-        Check if the pair is expired.
-        """
-        ttl = pair.request.metadata["hishel_ttl"] if "hishel_ttl" in pair.request.metadata else self.default_ttl
-        created_at = pair.meta.created_at
-        if ttl is None:
-            return False
-        return created_at + ttl < time.time()
-
-    def _batch_cleanup(
-        self,
-    ) -> None:
-        """
-        Cleanup expired pairs in the database.
-        """
-        should_mark_as_deleted: List[Union[CompletePair, IncompletePair]] = []
-        should_hard_delete: List[Union[CompletePair, IncompletePair]] = []
-
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-        cursor.execute("SELECT id, data FROM entries")
-
-        for row in cursor.fetchall():
-            pair = unpack(row[1], kind="pair")
-            if pair is None:
-                continue
-            if self._is_pair_expired(pair, cursor) and not self.is_soft_deleted(pair):
-                should_mark_as_deleted.append(pair)
-
-            if (self.is_soft_deleted(pair) and self.is_safe_to_hard_delete(pair)) or self._is_corrupted(
-                pair, cursor
-            ):
-                should_hard_delete.append(pair)
-
-        for pair in should_mark_as_deleted:
-            self._soft_delete_pair(pair, cursor)
-
-        for pair in should_hard_delete:
-            self._hard_delete_pair(pair, cursor)
-
-        connection.commit()
-
-    def _is_corrupted(self, pair: IncompletePair | CompletePair, cursor: sqlite3.Cursor) -> bool:
-        # if pair was created more than 1 hour ago and still not completed
-        if pair.meta.created_at + 3600 < time.time() and isinstance(pair, IncompletePair):
-            return True
-
-        if isinstance(pair, CompletePair) and not self._is_stream_complete("request", pair.id, cursor):
-            return True
-        return False
-
-    def _hard_delete_pair(self, pair: CompletePair | IncompletePair, cursor: sqlite3.Cursor) -> None:
-        """
-        Permanently delete the pair from the database.
-        """
-        cursor.execute("DELETE FROM entries WHERE id = ?", (pair.id.bytes,))
-
-        # Delete all streams (both request and response) for this entry
-        self._delete_stream(pair.id.bytes, cursor)
-
-    def _delete_stream(
-        self,
-        entry_id: bytes,
-        cursor: sqlite3.Cursor,
-        type: Literal["request", "response", "all"] = "all",
-    ) -> None:
-        """
-        Delete all streams (both request and response) associated with the given entry ID.
-        """
-        if type == "request":
-            cursor.execute(
-                "DELETE FROM streams WHERE entry_id = ? AND kind = ?", (entry_id, self._STREAM_KIND["request"])
-            )
-        elif type == "response":
-            cursor.execute(
-                "DELETE FROM streams WHERE entry_id = ? AND kind = ?", (entry_id, self._STREAM_KIND["response"])
-            )
-        elif type == "all":
-            cursor.execute("DELETE FROM streams WHERE entry_id = ?", (entry_id,))
-
-    def _save_stream(
-        self,
-        stream: Iterator[bytes],
-        entry_id: bytes,
-        kind: Literal["response", "request"],
-    ) -> Iterator[bytes]:
-        """
-        Wrapper around an async iterator that also saves the data to the cache in chunks.
-        """
-        kind_id = self._STREAM_KIND[kind]
-        chunk_number = 0
-        for chunk in stream:
-            connection = self._ensure_connection()
-            cursor = connection.cursor()
-            cursor.execute(
-                "INSERT INTO streams (entry_id, kind, chunk_number, chunk_data) VALUES (?, ?, ?, ?)",
-                (entry_id, kind_id, chunk_number, chunk),
-            )
-            connection.commit()
-            chunk_number += 1
-            yield chunk
-
-        # Mark end of stream with chunk_number = -1
-        connection = self._ensure_connection()
-        cursor = connection.cursor()
-        cursor.execute(
-            "INSERT INTO streams (entry_id, kind, chunk_number, chunk_data) VALUES (?, ?, ?, ?)",
-            (entry_id, kind_id, self._COMPLETE_CHUNK_NUMBER, b""),
-        )
-        connection.commit()
-
-    def _stream_data_from_cache(
-        self,
-        entry_id: bytes,
-        kind: Literal["response", "request"],
-    ) -> Iterator[bytes]:
-        """
-        Get an async iterator that yields the stream data from the cache.
-        """
-        kind_id = self._STREAM_KIND[kind]
-        chunk_number = 0
-
-        connection = self._ensure_connection()
-        while True:
-            cursor = connection.cursor()
-            cursor.execute(
-                "SELECT chunk_data FROM streams WHERE entry_id = ? AND kind = ? AND chunk_number = ?",
-                (entry_id, kind_id, chunk_number),
-            )
-            result = cursor.fetchone()
-
-            if result is None:
-                break
-            chunk = result[0]
-            # chunk_number = -1 is the completion marker with empty data
-            if chunk == b"":
-                break
-            yield chunk
-            chunk_number += 1

hishel-0.1.5.dist-info/METADATA

@@ -1,258 +0,0 @@
-Metadata-Version: 2.4
-Name: hishel
-Version: 0.1.5
-Summary: Persistent cache implementation for httpx and httpcore
-Project-URL: Homepage, https://hishel.com
-Project-URL: Source, https://github.com/karpetrosyan/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.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Internet :: WWW/HTTP
-Requires-Python: >=3.9
-Requires-Dist: anyio>=4.9.0
-Requires-Dist: anysqlite>=0.0.5
-Requires-Dist: httpx>=0.28.0
-Requires-Dist: msgpack>=1.1.2
-Requires-Dist: typing-extensions>=4.14.1
-Provides-Extra: httpx
-Requires-Dist: httpx>=0.28.1; extra == 'httpx'
-Provides-Extra: redis
-Requires-Dist: redis==6.2.0; extra == 'redis'
-Provides-Extra: requests
-Requires-Dist: requests>=2.32.5; extra == 'requests'
-Provides-Extra: s3
-Requires-Dist: boto3<=1.15.3,>=1.15.0; (python_version < '3.12') and extra == 's3'
-Requires-Dist: boto3>=1.15.3; (python_version >= '3.12') and extra == 's3'
-Provides-Extra: sqlite
-Requires-Dist: anysqlite>=0.0.5; extra == 'sqlite'
-Provides-Extra: yaml
-Requires-Dist: pyyaml==6.0.2; extra == 'yaml'
-Description-Content-Type: text/markdown
-
-<p align="center" class="logo">
-    <div align="center">
-        <picture>
-            <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png">
-            <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_black.png">
-            <img alt="Logo" src="https://raw.githubusercontent.com/karpetrosyan/hishel/master/docs/static/Shelkopryad_350x250_yellow.png">
-        </picture>
-    </div>
-</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://coveralls.io/github/karpetrosyan/hishel">
-      <img src="https://img.shields.io/coverallsCoverage/github/karpetrosyan/hishel" alt="license">
-  </a>
-
-  <a href="https://github.com/karpetrosyan/hishel">
-      <img src="https://img.shields.io/pypi/dm/hishel.svg" alt="Downloads">
-  </a>
-</p>
-
-<p align="center">
-    <a href="https://buymeacoffee.com/karpetrosyan" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: 41px !important;width: 174px !important;box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;-webkit-box-shadow: 0px 3px 2px 0px rgba(190, 190, 190, 0.5) !important;" ></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**](https://www.rfc-editor.org/rfc/rfc9111.html), 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 httpx while also enabling [web cache](https://en.wikipedia.org/wiki/Web_cache).
-- 🧠 **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.
-- 📦 **From the package**:
-    - Built-in support for [File system](https://en.wikipedia.org/wiki/File_system), [Redis](https://en.wikipedia.org/wiki/Redis), [SQLite](https://en.wikipedia.org/wiki/SQLite), and [AWS S3](https://aws.amazon.com/s3/) backends.
-    - Built-in support for [JSON](https://en.wikipedia.org/wiki/JSON), [YAML](https://en.wikipedia.org/wiki/YAML), and [pickle](https://docs.python.org/3/library/pickle.html) serializers.
-- 🚀 **Very fast**: Your requests will be even faster if there are *no IO operations*.
-
-## Documentation
-Go through the [Hishel documentation](https://hishel.com).
-
-## 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://hishel.com")  # 0.4749558370003797s
-    client.get("https://hishel.com")  # 0.002873589000046195s (~250x faster!)
-```
-
-or in asynchronous context
-
-```python
-import hishel
-
-async with hishel.AsyncCacheClient() as client:
-    await client.get("https://hishel.com")
-    await client.get("https://hishel.com")  # takes from the cache
-```
-
-## Configurations
-
-Configure when and how you want to store your responses.
-
-```python
-import hishel
-
-# All the specification configs
-controller = hishel.Controller(
-        # Cache only GET and POST methods
-        cacheable_methods=["GET", "POST"],
-
-        # Cache only 200 status codes
-        cacheable_status_codes=[200],
-
-        # Use the stale response if there is a connection issue and the new response cannot be obtained.
-        allow_stale=True,
-
-        # First, revalidate the response and then utilize it.
-        # If the response has not changed, do not download the
-        # entire response data from the server; instead,
-        # use the one you have because you know it has not been modified.
-        always_revalidate=True,
-)
-
-# All the storage configs
-storage = hishel.S3Storage(
-        bucket_name="my_bucket_name", # store my cache files in the `my_bucket_name` bucket
-        ttl=3600, # delete the response if it is in the cache for more than an hour
-)
-client = hishel.CacheClient(controller=controller, storage=storage)
-
-
-# Ignore the fact that the server does not recommend you cache this request!
-client.post(
-        "https://example.com",
-        extensions={"force_cache": True}
-)
-
-
-# Return a regular response if it is in the cache; else, return a 504 status code. DO NOT SEND A REQUEST!
-client.post(
-        "https://example.com",
-        headers=[("Cache-Control", "only-if-cached")]
-)
-
-
-# Ignore cached responses and do not store incoming responses!
-response = client.post(
-        "https://example.com",
-        extensions={"cache_disabled": True}
-)
-```
-
-## How and where are the responses saved?
-
-The responses are stored by `Hishel` in [storages](https://hishel.com/userguide/#storages).
-You have complete control over them; you can change storage or even write your own if necessary.
-
-
-## Support the project
-
-You can support the project by simply leaving a GitHub star ⭐ or by [contributing](https://hishel.com/contributing/).
-Help us grow and continue developing good software for you ❤️
-
-## [0.1.5] - 2025-10-18
-
-### 🚀 Features
-
-- *(perf)* Set chunk size to 128KB for httpx to reduce SQLite read/writes
-- Better cache-control parsing
-- Add close method to storages API (#384)
-- *(perf)* Increase requests buffer size to 128KB, disable charset detection
-
-### 🐛 Bug Fixes
-
-- *(docs)* Fix some line breaks
-
-### ⚙️ Miscellaneous Tasks
-
-- Remove some redundant files from repo
-## [0.1.4] - 2025-10-14
-
-### 🚀 Features
-
-- Add support for a sans-IO API (#366)
-- Allow already consumed streams with `CacheTransport` (#377)
-- Add sqlite storage for beta storages
-- Get rid of some locks from sqlite storage
-- Better async implemetation for sqlite storage
-
-### 🐛 Bug Fixes
-
-- Create an sqlite file in a cache folder
-- Fix beta imports
-
-### ⚙️ Miscellaneous Tasks
-
-- Improve CI (#369)
-- *(internal)* Remove src folder (#373)
-- *(internal)* Temporary remove python3.14 from CI
-- *(tests)* Add sqlite tests for new storage
-- *(tests)* Move some tests to beta
-## [0.1.3] - 2025-07-06
-
-### 🚀 Features
-
-- Support providing a path prefix to S3 storage (#342)
-
-### 📚 Documentation
-
-- Update link to httpx transports page (#337)
-## [0.1.2] - 2025-04-04
-
-### 🐛 Bug Fixes
-
-- Requirements.txt to reduce vulnerabilities (#263)
-## [0.0.30] - 2024-07-12
-
-### 🐛 Bug Fixes
-
-- Requirements.txt to reduce vulnerabilities (#245)
-- Requirements.txt to reduce vulnerabilities (#255)
-## [0.0.27] - 2024-05-31
-
-### 🐛 Bug Fixes
-
-- *(redis)* Do not update metadata with negative ttl (#231)
-## [0.0.1] - 2023-07-22