globalstash 0.1.0__tar.gz

globalstash-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

globalstash-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+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

globalstash-0.1.0/README.md

@@ -0,0 +1,60 @@
+# 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

globalstash-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "globalstash"
+version = "0.1.0"
+description = "Thread-safe, process-wide global state you can import from any module at any depth."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Your Name", email = "you@example.com" }]
+keywords = ["global", "state", "flask.g", "config", "singleton", "thread-safe"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/your-username/globalstash"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+globalstash = ["py.typed"]

globalstash-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

globalstash-0.1.0/src/globalstash/__init__.py

@@ -0,0 +1,5 @@
+"""globalstash: thread-safe process-wide global state."""
+from .core import GlobalState, g, get_state
+
+__all__ = ["GlobalState", "g", "get_state"]
+__version__ = "0.1.0"

globalstash-0.1.0/src/globalstash/core.py

@@ -0,0 +1,178 @@
+"""Core implementation of globalstash."""
+from __future__ import annotations
+
+import threading
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, Tuple
+
+_MISSING = object()
+
+
+class GlobalState:
+    """A thread-safe namespace for process-wide global values.
+
+    Values can be accessed as attributes or as items::
+
+        g.db = create_pool()
+        g["db"]
+        g.get("missing", None)
+
+    Individual operations are atomic. For compound operations
+    (read-modify-write), use ``incr`` or the ``lock`` context manager::
+
+        with g.lock:
+            g.total = g.total + 1
+
+    Note: names of methods (``get``, ``pop``, ``update``...) can't be used
+    as attribute keys; use item access (``g["get"]``) for those.
+    """
+
+    __slots__ = ("_data", "_lock")
+
+    def __init__(self, **initial: Any) -> None:
+        object.__setattr__(self, "_data", dict(initial))
+        object.__setattr__(self, "_lock", threading.RLock())
+
+    # ---- attribute access -------------------------------------------------
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("__") or name in ("_data", "_lock"):
+            raise AttributeError(name)
+        with self._lock:
+            try:
+                return self._data[name]
+            except KeyError:
+                raise AttributeError(
+                    f"global state has no attribute {name!r}"
+                ) from None
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        with self._lock:
+            self._data[name] = value
+
+    def __delattr__(self, name: str) -> None:
+        with self._lock:
+            try:
+                del self._data[name]
+            except KeyError:
+                raise AttributeError(name) from None
+
+    # ---- item access ------------------------------------------------------
+    def __getitem__(self, key: str) -> Any:
+        with self._lock:
+            return self._data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        with self._lock:
+            self._data[key] = value
+
+    def __delitem__(self, key: str) -> None:
+        with self._lock:
+            del self._data[key]
+
+    def __contains__(self, key: object) -> bool:
+        with self._lock:
+            return key in self._data
+
+    def __iter__(self) -> Iterator[str]:
+        with self._lock:
+            return iter(list(self._data))
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._data)
+
+    def __repr__(self) -> str:
+        with self._lock:
+            return f"GlobalState({self._data!r})"
+
+    # ---- dict-like helpers ------------------------------------------------
+    def get(self, key: str, default: Any = None) -> Any:
+        with self._lock:
+            return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self[key] = value
+
+    def setdefault(self, key: str, default: Any = None) -> Any:
+        with self._lock:
+            return self._data.setdefault(key, default)
+
+    def pop(self, key: str, default: Any = _MISSING) -> Any:
+        with self._lock:
+            if default is _MISSING:
+                return self._data.pop(key)
+            return self._data.pop(key, default)
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        with self._lock:
+            self._data.update(*args, **kwargs)
+
+    def keys(self) -> Tuple[str, ...]:
+        with self._lock:
+            return tuple(self._data.keys())
+
+    def values(self) -> Tuple[Any, ...]:
+        with self._lock:
+            return tuple(self._data.values())
+
+    def items(self) -> Tuple[Tuple[str, Any], ...]:
+        with self._lock:
+            return tuple(self._data.items())
+
+    def clear(self) -> None:
+        with self._lock:
+            self._data.clear()
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a shallow copy of the current state."""
+        with self._lock:
+            return dict(self._data)
+
+    # ---- atomic / compound operations ------------------------------------
+    def incr(self, key: str, amount: int = 1, default: int = 0) -> int:
+        """Atomically add ``amount`` to ``key`` and return the new value."""
+        with self._lock:
+            value = self._data.get(key, default) + amount
+            self._data[key] = value
+            return value
+
+    @property
+    def lock(self) -> "threading.RLock":  # type: ignore[valid-type]
+        """The re-entrant lock, for compound operations: ``with g.lock: ...``"""
+        return self._lock
+
+    @contextmanager
+    def temporary(self, **overrides: Any) -> Iterator["GlobalState"]:
+        """Temporarily override values (handy in tests); restored on exit."""
+        with self._lock:
+            saved = {k: self._data.get(k, _MISSING) for k in overrides}
+            self._data.update(overrides)
+        try:
+            yield self
+        finally:
+            with self._lock:
+                for k, v in saved.items():
+                    if v is _MISSING:
+                        self._data.pop(k, None)
+                    else:
+                        self._data[k] = v
+
+
+# ---- default instance and named registry ---------------------------------
+g = GlobalState()
+
+_registry: Dict[str, GlobalState] = {}
+_registry_lock = threading.Lock()
+
+
+def get_state(name: str) -> GlobalState:
+    """Return the shared ``GlobalState`` registered under ``name``.
+
+    The same name always returns the same object, so independent libraries
+    or components can each keep their own namespace without collisions.
+    """
+    with _registry_lock:
+        state = _registry.get(name)
+        if state is None:
+            state = _registry[name] = GlobalState()
+        return state

globalstash-0.1.0/src/globalstash.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+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

globalstash-0.1.0/src/globalstash.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+src/globalstash/__init__.py
+src/globalstash/core.py
+src/globalstash/py.typed
+src/globalstash.egg-info/PKG-INFO
+src/globalstash.egg-info/SOURCES.txt
+src/globalstash.egg-info/dependency_links.txt
+src/globalstash.egg-info/top_level.txt
+tests/test_core.py

globalstash-0.1.0/src/globalstash.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

globalstash-0.1.0/src/globalstash.egg-info/top_level.txt

@@ -0,0 +1 @@
+globalstash

globalstash-0.1.0/tests/test_core.py

@@ -0,0 +1,88 @@
+import threading
+
+import pytest
+
+from globalstash import GlobalState, g, get_state
+
+
+@pytest.fixture(autouse=True)
+def _clean():
+    g.clear()
+    yield
+    g.clear()
+
+
+def test_attr_and_item_access():
+    g.a = 1
+    g["b"] = 2
+    assert g.a == 1 and g["a"] == 1 and g.b == 2
+    assert "a" in g and len(g) == 2
+
+
+def test_missing_attr_raises():
+    with pytest.raises(AttributeError):
+        g.nope
+
+
+def test_get_pop_setdefault_update():
+    assert g.get("x", 5) == 5
+    assert g.setdefault("x", 1) == 1
+    assert g.setdefault("x", 2) == 1
+    g.update(y=3, z=4)
+    assert g.pop("y") == 3
+    assert g.pop("missing", None) is None
+    assert g.to_dict() == {"x": 1, "z": 4}
+
+
+def test_delete():
+    g.a = 1
+    del g.a
+    assert "a" not in g
+
+
+def test_same_object_across_imports():
+    from globalstash import g as g2
+    g.v = 1
+    assert g2.v == 1
+
+
+def test_named_registry():
+    assert get_state("app") is get_state("app")
+    assert get_state("app") is not get_state("other")
+
+
+def test_temporary():
+    g.a = 1
+    with g.temporary(a=2, b=3):
+        assert g.a == 2 and g.b == 3
+    assert g.a == 1 and "b" not in g
+
+
+def test_incr_is_atomic_across_threads():
+    def work():
+        for _ in range(2000):
+            g.incr("n")
+
+    threads = [threading.Thread(target=work) for _ in range(8)]
+    [t.start() for t in threads]
+    [t.join() for t in threads]
+    assert g.n == 16000
+
+
+def test_lock_compound_op():
+    g.total = 0
+
+    def work():
+        for _ in range(2000):
+            with g.lock:
+                g.total = g.total + 1
+
+    threads = [threading.Thread(target=work) for _ in range(8)]
+    [t.start() for t in threads]
+    [t.join() for t in threads]
+    assert g.total == 16000
+
+
+def test_independent_instances():
+    a, b = GlobalState(x=1), GlobalState()
+    assert "x" not in b and a.x == 1