Metadata-Version: 2.4
Name: globalstash
Version: 0.1.0
Summary: Thread-safe, process-wide global state you can import from any module at any depth.
Author-email: Your Name <you@example.com>
License: MIT
Project-URL: Homepage, https://github.com/your-username/globalstash
Keywords: global,state,flask.g,config,singleton,thread-safe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# globalstash

Thread-safe, process-wide global state you can import from **any module at any depth**, with no `sys.path` tricks.

```bash
pip install globalstash
```

## Usage

```python
from globalstash import g

# anywhere in your app
g.db_pool = create_pool()
g["config"] = {"debug": True}

g.get("missing", "default")
g.setdefault("cache", {})
g.update(env="prod", version="1.0")
"db_pool" in g
del g.db_pool
```

Because Python caches modules, every `from globalstash import g` returns the same object.

### Atomic and compound operations

```python
g.incr("requests")          # atomic counter

with g.lock:                # read-modify-write
    g.total = g.total + 1
```

### Named namespaces

```python
from globalstash import get_state

cache = get_state("cache")   # same name -> same object everywhere
cache.ttl = 60
```

### Tests

```python
with g.temporary(debug=True):
    ...   # values restored on exit
```

## Notes

- Method names (`get`, `pop`, `update`, ...) can't be used as attribute keys; use `g["get"]`.
- State lives **per process**. Gunicorn/Uvicorn workers each have their own copy. Use Redis or a database for state shared across processes.
- For per-request state (like `flask.g`), use `contextvars` instead.

## License

MIT
