pystackquery 1.0.1__tar.gz

pystackquery-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI and GitHub Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          pip install uv
+          uv sync --all-extras --dev
+      - name: Run Tests
+        run: uv run pytest
+
+  build-and-publish:
+    name: Build and Publish
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

pystackquery-1.0.1/.gitignore

@@ -0,0 +1,203 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python,pythonvanilla
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,pythonvanilla
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### PythonVanilla ###
+# Byte-compiled / optimized / DLL files
+
+# C extensions
+
+# Distribution / packaging
+
+# Installer logs
+
+# Unit test / coverage reports
+
+# Translations
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+
+
+# End of https://www.toptal.com/developers/gitignore/api/python,pythonvanilla

pystackquery-1.0.1/.python-version

@@ -0,0 +1 @@
+3.12

pystackquery-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to PyStackQuery
+
+First off, thank you for considering contributing to PyStackQuery! It's people like you that make PyStackQuery such a great tool.
+
+## Code of Conduct
+
+By participating in this project, you are expected to uphold our high standards of professional conduct and technical excellence.
+
+## How Can I Contribute?
+
+### Reporting Bugs
+*   **Check the existing issues** to see if the bug has already been reported.
+*   If you can't find an open issue that addresses the problem, **open a new one**.
+*   Include a **reproducible example** and details about your environment (OS, Python version).
+
+### Suggesting Enhancements
+*   Open an issue to discuss the change before starting work.
+*   Explain why the feature would be useful to most users.
+
+### Pull Requests
+1.  Fork the repo and create your branch from `main`.
+2.  Install dependencies using `uv sync --dev`.
+3.  If you've added code that should be tested, add tests.
+4.  Ensure the test suite passes (`uv run pytest`).
+5.  Run linting and type checking (`uv run ruff check .` and `uv run mypy .`).
+6.  Ensure your code adheres to the existing style and architecture (PEP 695 generics, PEP 8).
+
+## Development Setup
+
+We use `uv` for dependency management.
+
+```bash
+# Clone the repo
+git clone https://github.com/yourusername/pystackquery.git
+cd pystackquery
+
+# Install dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest
+```
+
+## Styling & Standards
+*   **Python 3.12+**: Use modern syntax (Built-in generics, `|` unions).
+*   **Linting**: We use Ruff. Always run `ruff check --fix .` before committing.
+*   **Typing**: Static typing is mandatory. Ensure `mypy .` returns zero errors.
+*   **Documentation**: Update documentation in `docs/` if you change any public APIs.

pystackquery-1.0.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: pystackquery
+Version: 1.0.1
+Summary: Async data fetching and caching library for Python
+License-Expression: MIT
+Keywords: async,cache,data-fetching,query,state-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.9; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'

pystackquery-1.0.1/README.md

@@ -0,0 +1,156 @@
+# PyStackQuery
+
+Async data fetching and caching library for Python.
+
+PyStackQuery handles the hard parts of working with async data: caching, deduplication, retries, and reactive state updates. You focus on *what* to fetch, the library handles *how*.
+
+## Installation
+
+```bash
+pip install pystackquery
+```
+
+Requires Python 3.11+
+
+## Quick Start
+
+```python
+import asyncio
+from pystackquery import QueryClient, QueryOptions
+
+client = QueryClient()
+
+async def fetch_user(user_id: int) -> dict:
+    # Your async fetch logic here
+    async with aiohttp.ClientSession() as session:
+        async with session.get(f"https://api.example.com/users/{user_id}") as resp:
+            return await resp.json()
+
+async def main():
+    # Fetch with automatic caching
+    user = await client.fetch_query(
+        QueryOptions(
+            query_key=("user", "123"),
+            query_fn=lambda: fetch_user(123)
+        )
+    )
+
+    # Second call returns cached data instantly
+    user_again = await client.fetch_query(
+        QueryOptions(
+            query_key=("user", "123"),
+            query_fn=lambda: fetch_user(123)
+        )
+    )
+
+asyncio.run(main())
+```
+
+That's it. The first call fetches from the API. The second call returns instantly from cache.
+
+## What Problems Does This Solve?
+
+**Without PyStackQuery**, you write code like this over and over:
+
+```python
+cache = {}
+pending = {}
+lock = asyncio.Lock()
+
+async def get_user(user_id):
+    key = f"user_{user_id}"
+
+    async with lock:
+        if key in cache:
+            return cache[key]
+        if key in pending:
+            return await pending[key]
+
+        task = asyncio.create_task(fetch_user(user_id))
+        pending[key] = task
+
+    try:
+        result = await task
+        cache[key] = result
+        return result
+    finally:
+        del pending[key]
+```
+
+**With PyStackQuery**, you write:
+
+```python
+user = await client.fetch_query(
+    QueryOptions(("user", user_id), lambda: fetch_user(user_id))
+)
+```
+
+The library handles:
+- Caching
+- Request deduplication (concurrent calls share one request)
+- Automatic retries with backoff
+- Stale-while-revalidate
+- Cache invalidation
+- Reactive updates
+
+## Core Concepts
+
+### Query Keys
+
+Every query needs a unique key. Keys are tuples of strings:
+
+```python
+("users",)                    # All users
+("user", "123")               # Specific user
+("posts", "user", "123")      # Posts by user 123
+```
+
+Keys enable:
+- Cache lookups
+- Partial invalidation (invalidate `("users",)` clears all user queries)
+
+### Query Options
+
+Configure how a query behaves:
+
+```python
+QueryOptions(
+    query_key=("user", "123"),
+    query_fn=lambda: fetch_user(123),
+    stale_time=60.0,    # Data fresh for 60 seconds
+    retry=3,            # Retry 3 times on failure
+)
+```
+
+### Stale-While-Revalidate
+
+When data becomes stale, you get the cached data immediately while a background refresh happens:
+
+```python
+# First call: fetches from API
+data = await client.fetch_query(opts)
+
+# Wait for stale_time to pass...
+
+# Second call: returns stale data instantly, refreshes in background
+data = await client.fetch_query(opts)
+```
+
+Your users see data immediately. Fresh data loads in the background.
+
+## Documentation
+
+See the [docs/](./docs/) folder for comprehensive documentation:
+
+- [Getting Started](./docs/getting-started.md) - Installation and basic usage
+- [Query Options](./docs/query-options.md) - All configuration options explained
+- [Mutations](./docs/mutations.md) - Handling POST/PUT/DELETE operations
+- [Cache Management](./docs/cache-management.md) - Invalidation, prefetching, manual updates
+- [Observers](./docs/observers.md) - Reactive state updates
+- [Advanced Patterns](./docs/advanced-patterns.md) - Dependent queries, parallel fetching
+- [Framework Integrations](./docs/framework-integrations.md) - FastAPI, Tkinter, Textual, CLI tools, Jupyter
+- [API Reference](./docs/api-reference.md) - Complete API documentation
+
+## License
+
+MIT

pystackquery-1.0.1/RELEASING.md

@@ -0,0 +1,44 @@
+# Release Process
+
+This project uses GitHub Actions to automate publishing to PyPI and creating GitHub Releases.
+
+## Prerequisites
+1.  **PyPI API Token**: Ensure `PYPI_API_TOKEN` is set in the GitHub Repository Secrets.
+2.  **Clean State**: Ensure all tests, linting, and type checks pass.
+
+## Step-by-Step Release
+
+### 1. Update the Version
+Modify the `version` field in `pyproject.toml`.
+
+```toml
+[project]
+name = "pystackquery"
+version = "0.1.0"  # Update this!
+```
+
+### 2. Commit the change
+```bash
+git add pyproject.toml
+git commit -m "chore: bump version to 0.1.0"
+git push origin main
+```
+
+### 3. Tag and Push
+Creating a tag that matches the pattern `v*.*.*` will trigger the `Publish` workflow.
+
+```bash
+# Create the tag locally
+git tag v0.1.0
+
+# Push the tag to GitHub
+git push origin v0.1.0
+```
+
+## What Happens Automatically?
+Once the tag is pushed:
+1.  **Test Job**: GitHub Actions runs the full test suite.
+2.  **Publish Job**: If tests pass, it builds the package and uploads it to PyPI.
+3.  **Release Job**: A GitHub Release is created automatically with:
+    *   Automatic release notes (based on commit messages).
+    *   Built wheel and source distribution files attached.

pystackquery-1.0.1/docs/advanced-patterns.md

@@ -0,0 +1,69 @@
+# Advanced Patterns
+
+This guide explores architectural patterns for scaling PyStackQuery in complex applications.
+
+## Prefetching for Speed
+
+Anticipate user navigation by warming up the cache. Prefetching is silent and never throws on network failure.
+
+```python
+async def on_user_hover(user_id):
+    # Start fetching data before the user even clicks
+    await client.prefetch_query(
+        QueryOptions(query_key=("user", user_id), query_fn=fetch_user)
+    )
+```
+
+## Parallel and Dependent Queries
+
+### Parallel
+Use `parallel_queries` to reduce total latency when a screen needs data from multiple sources.
+
+```python
+from pystackquery import parallel_queries
+
+# Fetches all three concurrently
+users, settings, posts = await parallel_queries(client, opt1, opt2, opt3)
+```
+
+### Dependent
+Use `dependent_query` when the second request requires an ID from the first.
+
+```python
+from pystackquery import dependent_query
+
+posts = await dependent_query(
+    client,
+    depends_on=QueryOptions(("user", "me"), fetch_me),
+    then=lambda user: QueryOptions(("posts", user["id"]), fetch_posts)
+)
+```
+
+## Testing Observers
+
+Since PyStackQuery uses background tasks for hydration and refetching, your tests should account for event loop cycles.
+
+```python
+async def test_observer_flow(client):
+    observer = client.watch(opts)
+    states = []
+    
+    # Subscribe is synchronous
+    unsub = observer.subscribe(lambda s: states.append(s.status))
+    
+    # Wait for the background fetch to settle
+    await asyncio.sleep(0.1)
+    
+    assert QueryStatus.SUCCESS in states
+    unsub()
+```
+
+## Production L2 Backends
+
+For production, we recommend implementing a robust `StorageBackend` using Redis or SQLite.
+
+### Why SQLite?
+For single-server or desktop applications, SQLite is often faster than Redis and requires zero infrastructure management. It’s perfect for ensuring data persists across application restarts.
+
+### Why Redis?
+Use Redis if you have multiple server instances (distributed system) that need to share the same cached state to stay synchronized.

pystackquery-1.0.1/docs/api-reference.md

@@ -0,0 +1,96 @@
+# API Reference
+
+PyStackQuery is designed to be minimal but powerful. The entire public API revolves around the `QueryClient`.
+
+## QueryClient
+
+The main orchestrator for the dual-tier cache.
+
+### fetch_query
+
+```python
+async def fetch_query[T](self, options: QueryOptions[T]) -> T
+```
+
+The standard way to request data. Uses the **Stale-While-Revalidate** pattern:
+1.  **Fresh L1/L2:** Returns data instantly.
+2.  **Stale L1/L2:** Returns stale data instantly, triggers background network fetch.
+3.  **Cold Cache:** Performs blocking network fetch.
+
+### prefetch_query
+
+```python
+async def prefetch_query[T](self, options: QueryOptions[T]) -> None
+```
+
+Warms up the cache for a specific key. Unlike `fetch_query`, this never blocks for the result and fails silently on network errors.
+
+### watch
+
+```python
+def watch[T](self, options: QueryOptions[T]) -> QueryObserver[T]
+```
+
+Creates a reactive observer. Use this when you need your UI or service to react to data changes over time.
+
+---
+
+## QueryObserver
+
+The bridge between a Query and a listener.
+
+### subscribe
+
+```python
+def subscribe(self, listener: Callable[[QueryState[T, Exception]], object]) -> Callable[[], None]
+```
+
+**Synchronous.** Attaches a callback to the query. 
+- The `listener` is called immediately with the current state.
+- If the query is stale, a background fetch is initiated.
+- Returns an **unsubscribe function**.
+
+---
+
+## Persistence and Hydration
+
+PyStackQuery supports pluggable L2 storage (Redis, SQLite, Disk, etc.).
+
+### How Hydration Works
+1.  When you call `watch()` or `fetch_query()` on a cold key, the client creates a Query instance and starts a background **Hydration Task**.
+2.  `fetch_query()` will `await` this task before checking staleness.
+3.  If L2 data exists, it is loaded into memory (L1).
+4.  This allows data to survive process restarts or be shared across multiple workers.
+
+### Implementation Protocol
+To implement your own L2 storage, provide a class matching the `StorageBackend` Protocol:
+
+```python
+class MyStorage:
+    async def get(self, key: str) -> str | None: ...
+    async def set(self, key: str, value: str, ttl: float | None = None) -> None: ...
+    async def delete(self, key: str) -> None: ...
+```
+
+---
+
+## Core Configuration
+
+### QueryClientConfig
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `stale_time` | `float` | `0.0` | Seconds before data is considered stale. |
+| `gc_time` | `float` | `300.0` | How long inactive queries persist in L1/L2. |
+| `retry` | `int` | `3` | Number of exponential backoff attempts. |
+| `storage` | `StorageBackend` | `None` | The L2 persistence layer. |
+
+### QueryOptions
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `query_key` | `tuple` | **Required** | The hierarchical identifier. |
+| `query_fn` | `coroutine` | **Required** | The async logic to get data. |
+| `refetch_interval` | `float` | `None` | Auto-poll interval (only while observed). |
+| `select` | `callable` | `None` | Transformation applied at the observer level. |
+| `placeholder_data` | `T` | `None` | Instant data to show while first fetch is pending. |