dol 0.3.76__tar.gz → 0.3.78__tar.gz

{dol-0.3.76 → dol-0.3.78}/.claude/skills/dol-dev-wrap-kvs/SKILL.md

@@ -136,12 +136,13 @@ wrappers, and test all four forms (see `tests/test_trans.py::test_redirect_getat
 dol is editably installed across the local ecosystem, so **dependents already import your
 working-tree dol** — no reinstall needed. Before landing a wrap_kvs/Store.wrap change:
 1. Measure blast radius statically: AST-scan dependents for transforms passed to
-   wrap_kvs-family whose first param ∈ self_names (see `misc/data/` scan scripts;
+   wrap_kvs-family whose first param ∈ self_names (the `misc/fleet_ledger` census lists every call site with its kwargs and their kinds;
    the reusable pattern found 0 breaking + 12 safe self-convention sites).
 2. Run the dependents test-gate **baseline vs modified**: run each key dependent's suite
    with your change, then `git stash` your dol edits, run again (baseline), `git stash pop`;
-   a `PASS→FAIL` delta is a real regression (env `FAIL→FAIL` is not). Helpers and the
-   gate order live in `misc/data/` (gitignored). Prioritize `config2py → graze → ju →
+   a `PASS→FAIL` delta is a real regression (env `FAIL→FAIL` is not). The ledger does this
+   per test id: `python -m misc.fleet_ledger baseline` before and after, then `diff`
+   (see `misc/fleet_ledger/README.md`); `priv test-dependents dol` is the quick gate. Prioritize `config2py → graze → ju →
    tabled → oa` (highest transitive fan-out) plus the self-convention users
    (`py2store, sqldol, tec, unbox, mongodol`).
 

{dol-0.3.76 → dol-0.3.78}/CLAUDE.md

@@ -227,15 +227,7 @@ and the full doc index with status labels. The table below is the quick version.
 | [dol_content_metadata_bifurcation.md](misc/docs/dol_content_metadata_bifurcation.md) | The content/metadata split-store problem (feeds issue #80) |
 | [code-quality-improvements.md](misc/docs/code-quality-improvements.md) | Tech-debt tracker: dead code, coverage gaps (feeds issue #94) |
 
-> The **fleet usage ledger** ([#91](https://github.com/i2mint/dol/issues/91)) lives
-> in gitignored `misc/data/` — start at its [README](misc/data/README.md).
-> `python -m fleet_ledger scan` records one immutable, timestamped scan: dol's **89
-> direct dependents** pinned at full 40-char commits, their imports, AST-verified
-> subclasses and call-site kwargs (all `file:line`), a generated zero-usage report,
-> and the pre-PR test-gate order. `baseline` captures every dependent's suite result
-> so a candidate's damage can be told apart from pre-existing red; `pin restore`
-> freezes the fleet at a scan and `pin undo` releases it. Scans accumulate — nothing
-> is overwritten. Figures quoted in these docs are from the 2026-08-21 scan.
+> The **fleet usage ledger** ([#91](https://github.com/i2mint/dol/issues/91)) is committed code in `misc/fleet_ledger/` — start at its [README](misc/fleet_ledger/README.md). Its *output* is never committed (it is derived from the fleet, some of it private): it lives in `~/.local/share/dol/fleet_ledger/dol/`. `python -m misc.fleet_ledger scan` records one immutable, timestamped scan: every direct dependent (from priv's `dep_graph`) pinned at its full commit, its imports, AST-verified subclasses and call-site kwargs (all `file:line`), and a generated zero-usage report (`zero-usage`). `baseline` captures every dependent's suite result with its failing test ids, so `diff` tells a candidate's damage apart from pre-existing red; `pin restore` freezes the fleet at a scan and `pin undo` releases it. Scans accumulate — nothing is overwritten. Figures quoted in these docs are from the 2026-08-21 scan; rescan for current ones.
 
 ---
 

{dol-0.3.76 → dol-0.3.78}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dol
-Version: 0.3.76
+Version: 0.3.78
 Summary: Base builtin tools make and transform data object layers (dols).
 Project-URL: Homepage, https://github.com/i2mint/dol
 License: MIT

{dol-0.3.76 → dol-0.3.78}/dol/base.py

@@ -51,7 +51,7 @@ from collections.abc import (
 from typing import Any, Tuple, Union, Optional
 from collections.abc import Iterable, Callable
 
-from dol.errors import OutOfScopeKeyError
+from dol.errors import OutOfScopeKeyError, may_raise_out_of_scope
 from dol.util import (
     wraps,
     _disabled_clear_method,
@@ -814,8 +814,8 @@ class Store(KvPersister):
         lacks the prefix/suffix the layer strips) has no outer key, so it is skipped:
         the store is a *view* of the in-scope ids. Reading or writing such an id through
         an outer key is still impossible, and calling ``_key_of_id`` directly still
-        raises (i2mint/dol#82, #114). Note that ``len`` counts inner ids, so it may
-        exceed the number of keys iterated.
+        raises (i2mint/dol#82, #114). ``len`` and ``bool`` agree with this iteration
+        (see ``__len__``).
         """
         key_of_id = self._key_of_id
         for _id in self.store:
@@ -826,7 +826,24 @@ class Store(KvPersister):
             yield k
 
     def __len__(self) -> int:
-        return len(self.store)
+        """The inner store's ``len``, or, when the key layer is scoped (its
+        ``_key_of_id`` is marked with ``raises_out_of_scope``), the number of in-scope
+        ids, which takes a scan (i2mint/dol#123).
+
+        The inner ``len`` is always asked first, so an inner store that refuses ``len``
+        (e.g. a remote listing, to spare ``list()`` a second scan) still refuses it
+        here, and an empty one costs no scan. Otherwise note that ``list(store)`` of a
+        scoped layer scans twice: once to size the list, once to fill it.
+        """
+        n = len(self.store)
+        if n and may_raise_out_of_scope(self._key_of_id):
+            return sum(1 for _ in self)
+        return n
+
+    def __bool__(self) -> bool:
+        if may_raise_out_of_scope(self._key_of_id):
+            return any(True for _ in self)  # stops at the first in-scope id
+        return len(self) > 0
 
     def __contains__(self, k) -> bool:
         return self._id_of_key(k) in self.store

{dol-0.3.76 → dol-0.3.78}/dol/errors.py

@@ -145,11 +145,42 @@ class OutOfScopeKeyError(KeyError, ValueError):
     __str__ = Exception.__str__  # plain message, not KeyError's repr of it
 
 
+_RAISES_OUT_OF_SCOPE = "_dol_raises_out_of_scope"
+
+
+def raises_out_of_scope(func):
+    """Mark ``func``, a ``key_of_id``, as one that may raise ``OutOfScopeKeyError``.
+
+    A ``Store`` layer whose ``_key_of_id`` is so marked is a *view* of the in-scope
+    ids, so its ``len`` counts them (a scan) instead of returning ``len`` of the inner
+    store, which would overcount (i2mint/dol#123). Unmarked key mappings keep the inner
+    store's (often O(1)) ``len``. Returns ``func``, so it works as a decorator.
+
+    ``wrap_kvs`` (and so the codecs), ``Pipe`` and subclasses made by class wrapping
+    carry the mark over; a ``_key_of_id`` you override by hand (even one calling
+    ``super()``) does not, so mark it too if it can raise.
+
+    >>> @raises_out_of_scope
+    ... def key_of_id(_id):
+    ...     return _id
+    >>> may_raise_out_of_scope(key_of_id), may_raise_out_of_scope(str.upper)
+    (True, False)
+    """
+    setattr(func, _RAISES_OUT_OF_SCOPE, True)
+    return func
+
+
+def may_raise_out_of_scope(func) -> bool:
+    """Whether ``func`` was marked with :func:`raises_out_of_scope` (a bound method
+    reads the mark off its function)."""
+    return getattr(func, _RAISES_OUT_OF_SCOPE, False) is True
+
+
 def out_of_scope_prefix_error(_id, prefix):
     """The ``OutOfScopeKeyError`` for an ``_id`` that doesn't start with ``prefix``."""
     return OutOfScopeKeyError(
         f"{_id!r} does not start with the prefix {prefix!r}, so it is outside this "
-        "store's scope, so iterating the store skips it and it can't be read or "
+        "store's scope: iterating the store skips it, and it can't be read or "
         "written through an outer key (see i2mint/dol#82)."
     )
 
@@ -158,7 +189,7 @@ def out_of_scope_suffix_error(_id, suffix):
     """The ``OutOfScopeKeyError`` for an ``_id`` that doesn't end with ``suffix``."""
     return OutOfScopeKeyError(
         f"{_id!r} does not end with the suffix {suffix!r}, so it is outside this "
-        "store's scope, so iterating the store skips it and it can't be read or "
+        "store's scope: iterating the store skips it, and it can't be read or "
         "written through an outer key (see i2mint/dol#114)."
     )
 

{dol-0.3.76 → dol-0.3.78}/dol/filesys.py

@@ -448,6 +448,46 @@ def path_is_under(path: str, rootdir: str) -> bool:
         return False
 
 
+def dotdot_resolves_lexically(path: str, *, base: str = "") -> bool:
+    """Whether every ``..`` in ``path`` undoes the segment before it, as
+    ``os.path.normpath`` assumes.
+
+    It doesn't when a symlink comes before a ``..``: the OS then climbs out of the
+    link's target, so ``root/lnk/../x`` with ``root/lnk -> /elsewhere/deep`` addresses
+    ``/elsewhere/x``, not ``root/x`` (i2mint/dol#123). Paths without a ``..`` segment
+    are not touched (no file-system access); otherwise the part up to the last ``..``
+    is resolved both ways and compared.
+
+    With ``base`` (a string prefix of ``path``, e.g. a store's ``rootdir``), only the
+    ``..`` segments after it count: ``base`` itself is taken as the OS resolves it,
+    whatever ``..`` it holds. Conservative by design: a ``..`` after a symlink is
+    refused even when the link points back inside ``base``.
+
+    >>> dotdot_resolves_lexically('/data/root/a/b.txt')
+    True
+    >>> dotdot_resolves_lexically('/no/such/dir/../file')  # nothing to follow: lexical
+    True
+    """
+    if base and path.startswith(base):
+        base, path = path[: len(base)], path[len(base) :]
+    else:
+        base = ""
+    if os.pardir not in path:  # fast path: the common case, e.g. every listed key
+        return True
+    if os.altsep:
+        path = path.replace(os.altsep, os.sep)
+    segments = path.split(os.sep)
+    if os.pardir not in segments:
+        return True
+    last_pardir = len(segments) - 1 - segments[::-1].index(os.pardir)
+    head = os.sep.join(segments[: last_pardir + 1])
+    try:
+        physical = os.path.realpath(base + head)
+        return physical == os.path.realpath(base + os.path.normpath(head))
+    except (OSError, ValueError):  # unresolvable: don't vouch for it
+        return False
+
+
 class FileSysCollection(Collection):
     # rootdir = None  # mentioning here so that the attribute is seen as an attribute before instantiation.
 
@@ -503,8 +543,20 @@ class FileSysCollection(Collection):
 
     def is_in_root(self, k):
         """Whether ``k`` stays under ``rootdir`` (always true with
-        ``allow_escape=True`` or an empty ``rootdir``)."""
-        return self.allow_escape or not self.rootdir or path_is_under(k, self.rootdir)
+        ``allow_escape=True`` or an empty ``rootdir``).
+
+        The containment test is lexical (:func:`path_is_under`), so a key whose ``..``
+        follows a symlink -- where the OS climbs out of the link's *target*, not back
+        to the link's directory -- is refused too (i2mint/dol#123).
+        """
+        return (
+            self.allow_escape
+            or not self.rootdir
+            or (
+                path_is_under(k, self.rootdir)
+                and dotdot_resolves_lexically(k, base=self.rootdir)
+            )
+        )
 
     def validate_in_root(self, k):
         """Raise ``KeyValidationError`` if ``k`` leaves ``rootdir`` (i2mint/dol#107).

{dol-0.3.76 → dol-0.3.78}/dol/misc.py

@@ -117,11 +117,8 @@ class MiscReaderMixin:
     Warning: If used as a subclass, this mixin should (in general) be placed before the store
 
     Security:
-        ``.pkl``/``.pickle`` keys are unpickled by default (arbitrary code execution):
-        never use this over untrusted content or with request-derived keys. For
-        ``get_obj`` and the getters this includes URLs: ``get_obj('https://.../x.pkl')``
-        downloads and unpickles. Give it an ``incoming_val_trans_for_key`` without the
-        pickle extensions and such keys come back as raw bytes instead (i2mint/dol#113).
+        ``.pkl``/``.pickle`` keys are unpickled by default, which runs code from the
+        data: see the warning in the ``dol.misc`` module docstring (i2mint/dol#113).
 
 
     >>> # make a reader that will wrap a dict
@@ -253,11 +250,8 @@ def get_obj(
     """A quick way to get an object, with default... everything (but the key, you know, a clue of what you want)
 
     Security:
-        ``.pkl``/``.pickle`` keys are unpickled by default (arbitrary code execution):
-        never use this over untrusted content or with request-derived keys. For
-        ``get_obj`` and the getters this includes URLs: ``get_obj('https://.../x.pkl')``
-        downloads and unpickles. Give it an ``incoming_val_trans_for_key`` without the
-        pickle extensions and such keys come back as raw bytes instead (i2mint/dol#113).
+        ``.pkl``/``.pickle`` keys are unpickled by default, which runs code from the
+        data: see the warning in the ``dol.misc`` module docstring (i2mint/dol#113).
     """
     if k.startswith("http://") or k.startswith("https://"):
         v = url_to_bytes(k)
@@ -285,11 +279,8 @@ class MiscGetter:
     according to a property of the key (default: file extension).
 
     Security:
-        ``.pkl``/``.pickle`` keys are unpickled by default (arbitrary code execution):
-        never use this over untrusted content or with request-derived keys. For
-        ``get_obj`` and the getters this includes URLs: ``get_obj('https://.../x.pkl')``
-        downloads and unpickles. Give it an ``incoming_val_trans_for_key`` without the
-        pickle extensions and such keys come back as raw bytes instead (i2mint/dol#113).
+        ``.pkl``/``.pickle`` keys are unpickled by default, which runs code from the
+        data: see the warning in the ``dol.misc`` module docstring (i2mint/dol#113).
 
     >>> from dol.misc import get_obj, misc_objs_get
     >>> import os
@@ -356,11 +347,8 @@ class MiscStoreMixin(MiscReaderMixin):
         If used as a subclass, this mixin should (in general) be placed before the store
 
     Security:
-        ``.pkl``/``.pickle`` keys are unpickled by default (arbitrary code execution):
-        never use this over untrusted content or with request-derived keys. For
-        ``get_obj`` and the getters this includes URLs: ``get_obj('https://.../x.pkl')``
-        downloads and unpickles. Give it an ``incoming_val_trans_for_key`` without the
-        pickle extensions and such keys come back as raw bytes instead (i2mint/dol#113).
+        ``.pkl``/``.pickle`` keys are unpickled by default, which runs code from the
+        data: see the warning in the ``dol.misc`` module docstring (i2mint/dol#113).
 
     See also:
         preset and postget args from wrap_kvs decorator from dol.trans.
@@ -465,11 +453,8 @@ class MiscGetterAndSetter(MiscGetter):
     according to a property of the key (default: file extension).
 
     Security:
-        ``.pkl``/``.pickle`` keys are unpickled by default (arbitrary code execution):
-        never use this over untrusted content or with request-derived keys. For
-        ``get_obj`` and the getters this includes URLs: ``get_obj('https://.../x.pkl')``
-        downloads and unpickles. Give it an ``incoming_val_trans_for_key`` without the
-        pickle extensions and such keys come back as raw bytes instead (i2mint/dol#113).
+        ``.pkl``/``.pickle`` keys are unpickled by default, which runs code from the
+        data: see the warning in the ``dol.misc`` module docstring (i2mint/dol#113).
 
     >>> from dol.misc import set_obj, misc_objs  # the function and the object
     >>> import json

{dol-0.3.76 → dol-0.3.78}/dol/paths.py

@@ -36,7 +36,7 @@ from operator import getitem
 import os
 
 from dol.base import Store
-from dol.util import lazyprop, add_as_attribute_of, max_common_prefix
+from dol.util import add_as_attribute_of, max_common_prefix
 from dol.trans import (
     store_decorator,
     kv_wrap,
@@ -46,7 +46,7 @@ from dol.trans import (
     add_missing_key_handling,
 )
 from dol.dig import recursive_get_attr
-from dol.errors import out_of_scope_prefix_error
+from dol.errors import out_of_scope_prefix_error, raises_out_of_scope
 from dol._paths_core import (
     PathContext,
     PathCreationError,
@@ -1005,6 +1005,14 @@ class KeyPath:
 # ------------------------------------------------------------------------------
 
 
+def _strip_prefix(_id, prefix):
+    """``_id`` without ``prefix``; ``OutOfScopeKeyError`` if it doesn't start with it
+    (slicing anyway would yield a key addressing a different object, i2mint/dol#82)."""
+    if prefix and _id[: len(prefix)] != prefix:
+        raise out_of_scope_prefix_error(_id, prefix)
+    return _id[len(prefix) :]
+
+
 class PrefixRelativizationMixin:
     """
     Mixin that adds a intercepts the _id_of_key an _key_of_id methods, transforming absolute keys to relative ones.
@@ -1048,20 +1056,13 @@ class PrefixRelativizationMixin:
 
     _prefix_attr_name = "_prefix"
 
-    @lazyprop
-    def _prefix_length(self):
-        return len(getattr(self, self._prefix_attr_name))
-
     def _id_of_key(self, k):
         return getattr(self, self._prefix_attr_name) + k
 
+    @raises_out_of_scope
     def _key_of_id(self, _id):
-        prefix = getattr(self, self._prefix_attr_name)
-        if prefix and _id[: len(prefix)] != prefix:
-            raise out_of_scope_prefix_error(_id, prefix)
-        # slice by the live prefix's length: the cached ``_prefix_length`` goes stale
-        # if the prefix is reassigned after first use
-        return _id[len(prefix) :]
+        # the live prefix, not a cached length: it may be reassigned after first use
+        return _strip_prefix(_id, getattr(self, self._prefix_attr_name))
 
 
 class PrefixRelativization(PrefixRelativizationMixin):
@@ -1259,15 +1260,13 @@ class RelativePathKeyMapper:
 
     def __init__(self, prefix):
         self._prefix = prefix
-        self._prefix_length = len(self._prefix)
 
     def _id_of_key(self, k):
         return self._prefix + k
 
+    @raises_out_of_scope
     def _key_of_id(self, _id):
-        if self._prefix and _id[: self._prefix_length] != self._prefix:
-            raise out_of_scope_prefix_error(_id, self._prefix)
-        return _id[self._prefix_length :]
+        return _strip_prefix(_id, self._prefix)
 
 
 @store_decorator

{dol-0.3.76 → dol-0.3.78}/dol/tests/test_filesys.py

@@ -373,3 +373,139 @@ def test_rootdir_spellings_still_list_their_keys(tmp_path, monkeypatch):
         assert list(Files("/" + str(root))) == [key]  # '//...' rootdir
     monkeypatch.chdir(root)
     assert list(Files(os.path.join("a", ".."))) == [key]  # rootdir normalising to '.'
+
+
+# --- sprint review (i2mint/dol#123): coverage of the #107 containment surface --------
+
+
+def test_path_is_under_mixed_absolute_and_relative_is_false():
+    from dol.filesys import path_is_under
+
+    # commonpath raises ValueError on a mix of absolute and relative paths
+    assert path_is_under(os.path.abspath("x"), "rel/root") is False
+    assert path_is_under("rel/root/x", os.path.abspath("root")) is False
+
+
+def test_zip_readers_read_and_write_keys_inside_rootdir(tmp_path):
+    import zipfile
+    from dol.zipfiledol import ZipFilesReader, ZipFilesReaderAndBytesWriter
+
+    if os.name == "nt":  # ZipFilesReader's default subpath regex is POSIX-only
+        return
+    root = tmp_path / "root"
+    root.mkdir()
+    zip_path = str(root / "in.zip")
+    with zipfile.ZipFile(zip_path, "w") as zf:
+        zf.writestr("member.txt", b"hello")
+    reader = ZipFilesReader(str(root))
+    assert reader[zip_path]["member.txt"] == b"hello"
+    with pytest.raises(KeyError):  # inside the root, but no such file
+        reader[str(root / "missing.zip")]
+    writer = ZipFilesReaderAndBytesWriter(str(root))
+    copy_path = str(root / "copy.zip")
+    writer[copy_path] = (root / "in.zip").read_bytes()
+    assert writer[copy_path]["member.txt"] == b"hello"
+
+
+def test_make_missing_dirs_mixin_reraises_out_of_root_keys(tmp_path):
+    from dol.filesys import FileBytesPersister, MakeMissingDirsStoreMixin
+
+    class S(MakeMissingDirsStoreMixin, FileBytesPersister):
+        pass
+
+    root = _sandbox(tmp_path)
+    s = S(str(root))
+    with pytest.raises(KeyError):
+        s[str(root) + "/../escaped/x.txt"] = b"pwned"
+    assert not (tmp_path / "escaped").exists()
+
+
+# POSIX follows a symlink before applying the next '..'; Windows normalizes '..'
+# lexically first, so there 'lnk/../x' IS 'root/x' and nothing escapes to refuse.
+_DOTDOT_FOLLOWS_SYMLINKS = os.name != "nt"
+
+
+def _symlink_sandbox(tmp_path):
+    """``root/lnk`` -> ``outside/deep``; ``outside/secret.txt`` is outside the root."""
+    root = _sandbox(tmp_path)
+    deep = tmp_path / "outside" / "deep"
+    deep.mkdir(parents=True)
+    (tmp_path / "outside" / "secret.txt").write_bytes(b"secret")
+    try:
+        os.symlink(str(deep), str(root / "lnk"), target_is_directory=True)
+    except (OSError, NotImplementedError):  # e.g. Windows without the privilege
+        pytest.skip("cannot create symlinks here")
+    return root
+
+
+def test_files_symlink_then_dotdot_does_not_escape_rootdir(tmp_path):
+    from dol.filesys import Files
+
+    root = _symlink_sandbox(tmp_path)
+    s = Files(str(root))
+    escaping_key = os.path.join("lnk", "..", "secret.txt")
+    assert escaping_key not in s
+    assert s.get(escaping_key) is None
+    pwn_key = os.path.join("lnk", "..", "pwned.txt")
+    if _DOTDOT_FOLLOWS_SYMLINKS:
+        with pytest.raises(KeyError):
+            s[pwn_key] = b"x"
+    else:
+        s[pwn_key] = b"x"
+        assert (root / "pwned.txt").read_bytes() == b"x"  # contained in the root
+    assert not (tmp_path / "outside" / "pwned.txt").exists()
+
+
+def test_symlinked_subdir_of_rootdir_stays_addressable(tmp_path):
+    # the design #107 kept: a symlink inside the root is followed, and a '..' that
+    # does not come after a symlink still resolves lexically
+    from dol.filesys import Files
+
+    root = _symlink_sandbox(tmp_path)
+    s = Files(str(root))
+    s[os.path.join("lnk", "f.txt")] = b"via link"
+    assert (tmp_path / "outside" / "deep" / "f.txt").read_bytes() == b"via link"
+    assert s[os.path.join("lnk", "f.txt")] == b"via link"
+    assert s[os.path.join("a", "..", "lnk", "f.txt")] == b"via link"
+    assert s[os.path.join("a", "..", "a", "in.txt")] == b"inside"
+
+
+def test_symlink_then_dotdot_is_refused_by_every_containment_user(tmp_path):
+    from dol.filesys import DirReader, Files, mk_dirs_if_missing
+
+    root = _symlink_sandbox(tmp_path)
+    if not _DOTDOT_FOLLOWS_SYMLINKS:
+        pytest.skip("'..' never follows a symlink here: nothing escapes to refuse")
+    (tmp_path / "outside" / "sib").mkdir()
+    with pytest.raises(KeyError):
+        DirReader(str(root))[os.path.join(str(root), "lnk", "..", "sib")]
+    s = mk_dirs_if_missing(Files(str(root)))
+    with pytest.raises(KeyError):
+        s[os.path.join("lnk", "..", "made", "x.txt")] = b"pwned"
+    assert not (tmp_path / "outside" / "made").exists()
+    # allow_escape=True is the explicit opt-out
+    assert Files(str(root), allow_escape=True)[
+        os.path.join("lnk", "..", "secret.txt")
+    ] == b"secret"
+
+
+def test_rootdir_with_dotdot_after_a_symlink_lists_and_reads(tmp_path):
+    # e.g. join(dirname(__file__), '..', 'data') in a symlink-installed package: the
+    # rootdir's own '..' is the OS's business, only the key's part beyond it is checked
+    from dol.filesys import Files
+
+    src = tmp_path / "src"
+    (src / "pkg").mkdir(parents=True)
+    (src / "data" / "sub").mkdir(parents=True)
+    (src / "data" / "a.txt").write_bytes(b"A")
+    site = tmp_path / "site"
+    site.mkdir()
+    try:
+        os.symlink(str(src / "pkg"), str(site / "pkg"), target_is_directory=True)
+    except (OSError, NotImplementedError):
+        pytest.skip("cannot create symlinks here")
+    s = Files(os.path.join(str(site), "pkg", "..", "data"))
+    if os.name != "nt":  # Windows resolves '..' lexically: site/data doesn't exist
+        assert list(s) == ["a.txt"]
+        assert s["a.txt"] == b"A"
+        assert s[os.path.join("sub", "..", "a.txt")] == b"A"

{dol-0.3.76 → dol-0.3.78}/dol/tests/test_paths.py

@@ -233,3 +233,122 @@ def test_head_skips_out_of_scope_ids():
 
     s = KeyCodecs.prefixed("p/")({"stray": 0, "p/a": 1})
     assert s.head() == ("a", 1)
+
+
+# --- sprint review (i2mint/dol#123): len/bool vs the in-scope iteration of #119 -------
+
+
+@pytest.mark.parametrize("name, store", list(_prefix_stores()))
+def test_len_counts_only_in_scope_ids(name, store):
+    assert len(store) == len(list(store)) == 2
+
+
+def test_store_of_only_out_of_scope_ids_is_falsy():
+    from dol import KeyCodecs
+
+    s = KeyCodecs.prefixed("p/")({"stray": 0})
+    assert list(s) == []
+    assert not s
+
+
+def test_len_of_unscoped_store_is_the_inner_len():
+    from dol import wrap_kvs
+
+    s = wrap_kvs({"a": 1, "b": 2}, key_of_id=str.upper, id_of_key=str.lower)
+    assert len(s) == 2 and bool(s)
+    assert len(wrap_kvs({}, key_of_id=str.upper)) == 0
+
+
+def test_head_falls_back_to_inner_ids_when_getitem_fails():
+    from dol import wrap_kvs
+
+    # an asymmetric key mapping: iterated keys can't be read back
+    s = wrap_kvs({"p/stray": 0, "p/a": 1}, key_of_id=lambda _id: _id.upper())
+    with pytest.warns(UserWarning, match="Couldn't get data for the key"):
+        assert s.head() == ("P/STRAY", 0)
+
+
+def test_composed_and_stacked_scoped_layers_count_in_scope_ids():
+    from dol import KeyCodecs, wrap_kvs
+
+    base = {"a/x.txt": 1, "a/y.json": 2, "b/z.txt": 3}
+    composed = (KeyCodecs.prefixed("a/") + KeyCodecs.suffixed(".txt"))(dict(base))
+    assert list(composed) == ["x"] and len(composed) == 1
+    # an unscoped layer over a scoped one gets its len from the scoped inner layer
+    upper = wrap_kvs(KeyCodecs.prefixed("a/")(dict(base)), key_of_id=str.upper)
+    assert sorted(upper) == ["X.TXT", "Y.JSON"] and len(upper) == 2
+
+
+def test_subclass_of_scoped_class_stays_scoped():
+    from dol import KeyCodecs, wrap_kvs
+
+    Scoped = KeyCodecs.prefixed("p/")(dict)
+    Sub = wrap_kvs(Scoped, key_of_id=str.upper, id_of_key=str.lower)
+    s = Sub({"stray": 0, "p/a": 1})
+    assert list(s) == ["A"] and len(s) == 1 and s["A"] == 1
+
+
+def test_empty_affix_codec_keeps_the_inner_len():
+    from dol import KeyCodecs
+    from dol.errors import may_raise_out_of_scope
+
+    codec = KeyCodecs.affixed()
+    assert not may_raise_out_of_scope(codec.decoder)
+    assert len(codec({"a": 1})) == 1
+
+
+def test_scoped_len_keeps_the_inner_stores_refusal_and_empty_shortcut():
+    from collections.abc import Mapping
+    from dol import KeyCodecs
+
+    class NoLenListing(Mapping):
+        """A remote-like store refusing len, so list() lists it only once."""
+
+        def __init__(self, d):
+            self.d, self.listings = d, 0
+
+        def __getitem__(self, k):
+            return self.d[k]
+
+        def __iter__(self):
+            self.listings += 1
+            return iter(self.d)
+
+        def __len__(self):
+            raise TypeError("no len: it would take a full listing")
+
+    inner = NoLenListing({"p/a": 1, "q/b": 2})
+    s = KeyCodecs.prefixed("p/")(inner)
+    assert list(s) == ["a"] and inner.listings == 1
+    with pytest.raises(TypeError):
+        len(s)
+
+    class CountingDict(dict):
+        def __iter__(self):
+            raise AssertionError("an empty inner store needs no scan")
+
+    assert len(KeyCodecs.prefixed("p/")(CountingDict())) == 0
+
+
+def test_first_arg_is_mapping_keeps_the_scope_mark():
+    from dol import wrap_kvs, FirstArgIsMapping
+    from dol.errors import raises_out_of_scope, OutOfScopeKeyError
+
+    @raises_out_of_scope
+    def key_of_id(self, _id):
+        if not _id.startswith("p/"):
+            raise OutOfScopeKeyError(_id)
+        return _id[2:]
+
+    s = wrap_kvs({"p/a": 1, "q/b": 2}, key_of_id=FirstArgIsMapping(key_of_id))
+    assert list(s) == ["a"] and len(s) == 1
+
+
+def test_may_raise_out_of_scope_is_a_real_bool():
+    from dol.errors import may_raise_out_of_scope
+
+    class AnyAttr:
+        def __getattr__(self, name):
+            return "truthy"
+
+    assert may_raise_out_of_scope(AnyAttr()) is False

{dol-0.3.76 → dol-0.3.78}/dol/trans.py

@@ -41,6 +41,8 @@ from dol.errors import (
     SetattrNotAllowed,
     out_of_scope_prefix_error,
     out_of_scope_suffix_error,
+    raises_out_of_scope,
+    may_raise_out_of_scope,
 )
 from dol.base import Store, KvReader, AttrNames, kv_walk
 from dol._paths_core import (
@@ -1966,7 +1968,10 @@ def _wrap_outcoming(
     [7, 14]
     """
     if trans_func is not None:
+        marked = trans_func
         trans_func, wants_self = _resolve_self_convention(trans_func)
+        # read the mark off the transform itself, not a FirstArgIsMapping around it
+        is_scoped = may_raise_out_of_scope(marked) or may_raise_out_of_scope(trans_func)
         wrapped_func = getattr(store_cls, wrapped_method)
 
         if not wants_self:
@@ -1993,6 +1998,8 @@ def _wrap_outcoming(
                     self, getattr(super(store_cls, self), wrapped_method)(x)
                 )
 
+        if is_scoped:  # (``wraps`` already carried over a scoped wrapped_func's mark)
+            raises_out_of_scope(new_method)
         setattr(store_cls, wrapped_method, new_method)
 
 
@@ -3862,9 +3869,11 @@ def affix_key_codec(prefix: str = "", suffix: str = ""):
     >>> codec.decoder('/folder/name.txt')
     'name'
     """
+    decoder = partial(_affix_decoder, prefix=prefix, suffix=suffix)
+    if prefix or suffix:
+        raises_out_of_scope(decoder)
     return KeyCodec(
-        encoder=partial(_affix_encoder, prefix=prefix, suffix=suffix),
-        decoder=partial(_affix_decoder, prefix=prefix, suffix=suffix),
+        encoder=partial(_affix_encoder, prefix=prefix, suffix=suffix), decoder=decoder
     )