diff --git a/AUTHORS.rst b/AUTHORS.rst index 9f167759..f7e63abd 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -122,3 +122,4 @@ Suggestions and bug reporting: - tan_unique (vinson0522) - lin (theman6660) - HocVoNgThai +- Aschenbath diff --git a/CHANGES.rst b/CHANGES.rst index 237e0d98..9bd9cfb7 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,11 @@ Changelog ========= +Unreleased +---------- + +* Adding #147 StrictBox to reject new fields in attribute assignments while allowing explicit dictionary updates (thanks to Aschenbath) + Version 8.0.1 ------------- diff --git a/README.rst b/README.rst index c5e71ac7..88ca280f 100644 --- a/README.rst +++ b/README.rst @@ -127,6 +127,37 @@ allowing for recursive dot notation access. `Box` also includes helper functions to transform it back into a `dict`, as well as into `JSON`, `YAML`, `TOML`, or `msgpack` strings or files. +Restricting Attribute Assignment +-------------------------------- + +Use ``StrictBox`` to catch misspelled field names in attribute assignments. +Existing fields and their values remain mutable; add fields explicitly using +item assignment or dictionary methods such as ``update``. + +.. code:: python + + from box import StrictBox + + settings = StrictBox(host="localhost", port=8000) + settings.port = 8080 + settings.prot = 8080 # raises BoxKeyError + settings["debug"] = False + settings.debug = True + +Nested dictionaries, including dictionaries inside lists, become ``StrictBox`` +instances by default. Attribute aliases such as ``box.a_b`` for a key named +``"a b"`` still work. Copying, pickling and class methods such as +``StrictBox.from_json`` preserve the restrictions. + +This does not validate a schema: deleting fields, adding them through dictionary +operations, and replacing a nested dictionary with different fields are allowed. +After deleting a field, reintroduce it through item assignment before using +attribute assignment again. ``box_class`` can select a different class for +nested dictionaries. The usual ``default_box`` lookup behavior still applies; +checking an attribute assignment never creates its missing destination. +Subclass property setters and ``_box_internal_attrs`` also retain their behavior. + + Internal Attributes on Subclasses --------------------------------- diff --git a/box/__init__.py b/box/__init__.py index 783a5d0c..a7ff5523 100644 --- a/box/__init__.py +++ b/box/__init__.py @@ -10,12 +10,14 @@ from box.exceptions import BoxError, BoxKeyError from box.from_file import box_from_file, box_from_string from box.shorthand_box import SBox, DDBox +from box.strict_box import StrictBox import box.converters __all__ = [ "Box", "BoxList", "ConfigBox", + "StrictBox", "BoxError", "BoxKeyError", "box_from_file", diff --git a/box/strict_box.py b/box/strict_box.py new file mode 100644 index 00000000..7b2a82a6 --- /dev/null +++ b/box/strict_box.py @@ -0,0 +1,102 @@ +from __future__ import annotations + +from collections.abc import Mapping + +from box.box import Box, _camel_killer, _get_property_func, _parse_box_dots +from box.box_list import BoxList, _list_pos_re +from box.config_box import ConfigBox +from box.exceptions import BoxKeyError + + +def _existing_destination(target, key): + """Check the destination used by item assignment without defaulting missing keys.""" + if isinstance(target, ConfigBox): + key = target._ci_resolve(key) + + if isinstance(target, Box): + if not _existing_parents(target): + return False + if target._Box__process_dotted_key(key): + first, children = _parse_box_dots(target, key) + first = target._Box__dots_int_key(first) + if not dict.__contains__(target, first): + return False + child = dict.__getitem__(target, first) + if hasattr(child, "__setitem__"): + if isinstance(child, Box): + children = child._Box__dots_int_key(children) + return _existing_destination(child, children) + + if not dict.__contains__(target, key) and target._Box__camel_destructive() and isinstance(key, str): + key = _camel_killer(key) + return dict.__contains__(target, key) + + if isinstance(target, BoxList) and target.box_options.get("box_dots") and isinstance(key, str): + if not key.startswith("["): + return False + index = _list_pos_re.search(key) + if index is None: + return False + pos = int(index.group(1)) + if pos >= len(target): + return False + if len(index.group()) == len(key): + return True + children = key[len(index.group()) :].lstrip(".") + child = list.__getitem__(target, pos) + if target.box_options.get("default_box"): + expected = BoxList if children.startswith("[") else Box + if not isinstance(child, expected): + return False + return _existing_destination(child, children) + + if isinstance(target, dict): + return dict.__contains__(target, key) + return isinstance(target, Mapping) and any(stored is key or stored == key for stored in target) + + +def _existing_parents(target): + """An ephemeral default must not attach new parent fields during this write.""" + while target._box_config.get("__pending_parent") is not None: + parent, key = target._box_config["__pending_parent"] + if not dict.__contains__(parent, key): + if not isinstance(target, ConfigBox) or not isinstance(parent, ConfigBox) or parent._ci_key(key) is None: + return False + target = parent + return True + + +class StrictBox(Box): + """ + A Box whose attributes can only update existing fields. + + Use item assignment or dictionary methods to add fields explicitly. Values + remain mutable, and nested dictionaries use StrictBox by default. + + .. code-block:: python + + settings = StrictBox(host="localhost", port=8000) + settings.port = 8080 + settings.prot = 8080 # raises BoxKeyError instead of adding a typo + settings["debug"] = False + settings.debug = True + + This restricts attribute assignment, not the shape or types of the data. + Replacing a nested dictionary establishes its new fields. Normal Box + options, property setters and declared internal attributes still apply. + """ + + def __setattr__(self, key, value): + if key == "_box_config" or key in self._box_internal_attrs: + return super().__setattr__(key, value) + + config = self._box_config + if config["__created"] and not config["frozen_box"] and key not in self._protected_keys: + resolved = config["__safe_keys"].get(self._safe_attr(key), key) + if _get_property_func(self, resolved)[1] is None: + if not _existing_destination(self, resolved): + raise BoxKeyError( + f'Cannot create field "{key}" through attribute assignment; use item assignment instead' + ) + + return super().__setattr__(key, value) diff --git a/box/strict_box.pyi b/box/strict_box.pyi new file mode 100644 index 00000000..00b4843d --- /dev/null +++ b/box/strict_box.pyi @@ -0,0 +1,3 @@ +from box.box import Box as Box + +class StrictBox(Box): ... diff --git a/test/test_strict_box.py b/test/test_strict_box.py new file mode 100644 index 00000000..a3515699 --- /dev/null +++ b/test/test_strict_box.py @@ -0,0 +1,486 @@ +import copy +import pickle +import re +from collections import defaultdict +from collections.abc import MutableMapping + +import pytest + +from box import Box, BoxError, BoxKeyError, ConfigBox, StrictBox + + +def test_existing_fields_remain_mutable(): + settings = StrictBox(host="localhost", port=8000, optional=None, tags=[]) + settings.port = 8080 + settings.optional = "set" + settings.tags.append("local") + with pytest.raises(BoxKeyError, match="Cannot create field"): + settings.prot = 8080 + assert settings.to_dict() == { + "host": "localhost", + "port": 8080, + "optional": "set", + "tags": ["local"], + } + + +@pytest.mark.parametrize("method", ["item", "update", "merge_update", "setdefault", "union"]) +def test_dictionary_operations_can_define_fields(method): + settings = StrictBox() + if method == "item": + settings["name"] = "app" + elif method == "update": + settings.update(name="app") + elif method == "merge_update": + settings.merge_update(name="app") + elif method == "setdefault": + settings.setdefault("name", "app") + else: + settings |= {"name": "app"} + settings.name = "renamed" + assert settings.name == "renamed" + + +def test_nested_boxes_and_list_members(): + settings = StrictBox(server={"port": 8000}, workers=[{"name": "first"}]) + settings.server.port = 8080 + settings.workers[0].name = "changed" + for nested in [settings.server, settings.workers[0]]: + assert isinstance(nested, StrictBox) + with pytest.raises(BoxKeyError): + nested.unknown = True + settings.server = {"host": "localhost"} + settings.server.host = "example.org" + with pytest.raises(BoxKeyError): + settings.server.port = 9000 + settings.workers.append({"name": "second"}) + with pytest.raises(BoxKeyError): + settings.workers[1].unknown = True + + +@pytest.mark.parametrize( + "data, options, attribute, stored", + [ + ({"a b": 1}, {}, "a_b", "a b"), + ({"CamelCase": 1}, {"camel_killer_box": True}, "CamelCase", "camel_case"), + ({"CamelCase": 1}, {"camel_killer_box": True, "camel_killer_box_keep_keys": True}, "camel_case", "CamelCase"), + ({"a.b": 1}, {}, "a_b", "a.b"), + ], +) +def test_attribute_aliases(data, options, attribute, stored): + settings = StrictBox(data, **options) + setattr(settings, attribute, 2) + assert settings.to_dict() == {stored: 2} + with pytest.raises(BoxKeyError): + settings.missing = 3 + + +def test_conversion_can_be_disabled(): + settings = StrictBox({"a b": 1}, conversion_box=False) + with pytest.raises(BoxKeyError): + settings.a_b = 2 + setattr(settings, "a b", 2) + assert settings.to_dict() == {"a b": 2} + + +def test_dotted_attribute_assignment_checks_the_destination(): + settings = StrictBox({"server": {"port": 8000}, "workers": [{"name": "first"}]}, box_dots=True) + setattr(settings, "server.port", 8080) + setattr(settings, "workers[0].name", "changed") + assert settings.server.port == 8080 + assert settings.workers[0].name == "changed" + for path in ["server.prot", "workers[0].unknown", "missing.value"]: + with pytest.raises(BoxKeyError): + setattr(settings, path, True) + assert settings.to_dict() == {"server": {"port": 8080}, "workers": [{"name": "changed"}]} + + +@pytest.mark.parametrize("create_on_get", [False, True]) +def test_default_lookup_does_not_authorize_new_attribute_writes(create_on_get): + settings = StrictBox(existing=1, default_box=True, default_box_create_on_get=create_on_get) + with pytest.raises(BoxKeyError): + settings.unknown = 2 + assert settings.to_dict() == {"existing": 1} + settings.existing = 2 + assert settings.existing == 2 + + +def test_failed_nested_default_assignment_does_not_attach_ephemeral_parents(): + settings = StrictBox(default_box=True) + with pytest.raises(BoxKeyError): + settings.parent.child = 1 + assert settings.to_dict() == {} + + +def test_deleted_field_must_be_explicitly_reintroduced(): + settings = StrictBox({"a b": 1}) + del settings.a_b + with pytest.raises(BoxKeyError): + settings.a_b = 2 + settings["a b"] = 2 + settings.a_b = 3 + assert settings.to_dict() == {"a b": 3} + + +def test_internal_attributes_and_property_setters(): + class Settings(StrictBox): + _box_internal_attrs = ("_source",) + + @property + def doubled(self): + return self.value * 2 + + @doubled.setter + def doubled(self, value): + self.value = value // 2 + + settings = Settings(value=1) + settings._source = "config.json" + settings.doubled = 8 + assert settings.to_dict() == {"value": 4} + assert settings._source == "config.json" + with pytest.raises(BoxKeyError): + settings.other = 1 + + +def test_frozen_and_protected_fields_keep_their_errors(): + settings = StrictBox(value=1, frozen_box=True) + with pytest.raises(BoxError, match="Box is frozen"): + settings.value = 2 + with pytest.raises(BoxError, match="Box is frozen"): + settings.unknown = 2 + settings = StrictBox({"update": 1}) + with pytest.raises(BoxKeyError, match="protected"): + settings.update = 2 + + +@pytest.mark.parametrize( + "clone", [lambda value: value.copy(), copy.copy, copy.deepcopy, lambda value: pickle.loads(pickle.dumps(value))] +) +def test_copies_and_pickle_keep_attribute_restrictions(clone): + settings = StrictBox({"a b": {"value": 1}, "entries": [{"value": 2}]}, box_dots=True) + restored = clone(settings) + assert type(restored) is StrictBox + restored.a_b.value = 3 + restored.entries[0].value = 4 + for target in [restored, restored.a_b, restored.entries[0]]: + assert isinstance(target, StrictBox) + with pytest.raises(BoxKeyError): + target.missing = 5 + + +def test_json_round_trip_and_explicit_nested_class(): + settings = StrictBox(server={"port": 8000}) + restored = StrictBox.from_json(settings.to_json()) + assert isinstance(restored.server, StrictBox) + restored.server.port = 8080 + with pytest.raises(BoxKeyError): + restored.server.prot = 8080 + + settings = StrictBox(server={}, box_class=Box) + settings.server.name = "allowed" + assert type(settings.server) is Box + with pytest.raises(BoxKeyError): + settings.unknown = True + + +def test_subclass_can_set_initial_attributes_during_construction(): + class Settings(StrictBox): + def __init__(self, **kwargs): + self.port = 8000 + super().__init__(**kwargs) + + settings = Settings(port=8080) + assert settings.port == 8080 + with pytest.raises(BoxKeyError): + settings.prot = 9000 + + +@pytest.mark.parametrize("attribute", ["parent.child", "parent_child"]) +def test_shadowed_dotted_path_does_not_create_nested_field(attribute): + value = StrictBox(parent={}, box_dots=True) + value.update({"parent.child": 1}) + with pytest.raises(BoxKeyError): + setattr(value, attribute, 2) + assert value.to_dict() == {"parent": {}, "parent.child": 1} + + +def test_camel_read_alias_does_not_create_new_write_parent(): + value = StrictBox( + {"camel_case": {"field": 1}}, + box_dots=True, + camel_killer_box=True, + default_box=True, + ) + with pytest.raises(BoxKeyError): + setattr(value, "CamelCase.field", 2) + assert value.to_dict() == {"camel_case": {"field": 1}} + + +def test_intact_mapping_missing_hook_is_not_run_by_preflight(): + events = [] + + def factory(): + events.append("missing") + return 0 + + nested = defaultdict(factory) + value = StrictBox(parent=nested, box_dots=True, box_intact_types=(defaultdict,)) + with pytest.raises(BoxKeyError): + setattr(value, "parent.new", 1) + assert not events + assert not nested + + +def test_pending_parent_is_not_attached_by_attribute_assignment(): + value = StrictBox(default_box=True, default_box_attr={"field": 1}) + with pytest.raises(BoxKeyError): + value.missing.field = 2 + assert value.to_dict() == {} + + +def test_property_setter_can_explicitly_define_data_field(): + class Settings(StrictBox): + @property + def port(self): + raise AssertionError("getter must not run during assignment") + + @port.setter + def port(self, value): + self["saved_port"] = value + + settings = Settings() + settings.port = 1234 + assert settings.to_dict() == {"saved_port": 1234} + + +def test_readonly_property_getter_is_not_evaluated(): + class Settings(StrictBox): + @property + def port(self): + raise AssertionError("getter must not run during assignment") + + with pytest.raises(BoxKeyError): + Settings().port = 1234 + + +def test_inherited_property_setter_and_declared_internal_attribute(): + class Base(StrictBox): + _box_internal_attrs = ("_path",) + + @property + def value(self): + return self["stored"] + + @value.setter + def value(self, val): + self["stored"] = val + + class Child(Base): + pass + + item = Child() + item.value = 3 + item._path = "example" + assert item.to_dict() == {"stored": 3} + frozen = Child(frozen_box=True) + frozen._path = "allowed" + assert frozen.to_dict() == {} + + +@pytest.mark.parametrize("attribute", ["nested.port", "nested.PORT", "nested.Port"]) +def test_explicit_nested_config_box_keeps_case_insensitive_writes(attribute): + settings = StrictBox(nested={"PORT": 1}, box_class=ConfigBox, box_dots=True) + setattr(settings, attribute, 2) + assert settings.nested.port == 2 + assert len(settings.nested) == 1 + + +def test_numeric_dotted_segments(): + item = StrictBox({2: {-1: {"value": 1}}}, box_dots=True) + setattr(item, "2.-1.value", 2) + assert item[2][-1].value == 2 + with pytest.raises(BoxKeyError): + setattr(item, "2.-1.unknown", 2) + + +def test_excluded_dotted_key_keeps_literal_meaning(): + item = StrictBox({"a.b": 1}, box_dots=True, box_dots_exclude=re.compile(r"a\.b")) + item.a_b = 2 + assert item.to_dict() == {"a.b": 2} + + +def test_nested_list_paths(): + item = StrictBox(values=[[{"value": 1}]], box_dots=True) + setattr(item, "values[0][0].value", 2) + assert item["values"][0][0].value == 2 + with pytest.raises(BoxKeyError): + setattr(item, "values[0][0].other", 3) + + +def test_intact_mapping_existing_key_never_runs_missing_factory(): + def missing(): + raise AssertionError("missing must not run") + + nested = defaultdict(missing, value=1) + item = StrictBox(parent=nested, box_dots=True, box_intact_types=(defaultdict,)) + setattr(item, "parent.value", 2) + assert nested == {"value": 2} + + +def test_missing_direct_attribute_never_calls_default_factory(): + def missing(): + raise AssertionError("missing must not run") + + item = StrictBox(default_box=True, default_box_attr=missing, default_box_create_on_get=True) + with pytest.raises(BoxKeyError): + item.absent = 2 + assert item.to_dict() == {} + + +def test_existing_nullable_field_with_default_box(): + item = StrictBox(default_box=True) + item["nullable"] = None + item.nullable = 2 + assert item.nullable == 2 + + +def test_detached_default_child_can_be_updated_after_parent_key_was_defined(): + item = StrictBox(default_box=True, default_box_attr={"field": 1}) + child = item.missing + item["missing"] = {"field": 10} + child.field = 2 + assert item.to_dict() == {"missing": {"field": 10}} + assert child.to_dict() == {"field": 2} + + +def test_ordinary_box_baseline_is_unchanged(): + item = Box() + item.new = 2 + assert item.to_dict() == {"new": 2} + + +@pytest.mark.parametrize("path", ["entries.0", "entries[bad]", "entries[3]", "entries[3].value"]) +def test_invalid_or_missing_list_destinations_are_not_created(path): + value = StrictBox(entries=[{"value": 1}], box_dots=True, default_box=True) + with pytest.raises(BoxKeyError): + setattr(value, path, 2) + assert value.to_dict() == {"entries": [{"value": 1}]} + + +def test_existing_list_element_can_be_replaced(): + value = StrictBox(entries=[{"value": 1}], box_dots=True) + setattr(value, "entries[0]", {"replacement": 2}) + assert value.entries[0].replacement == 2 + with pytest.raises(BoxKeyError): + value.entries[0].unknown = 3 + + +@pytest.mark.parametrize("nested", [False, True]) +def test_existing_default_list_paths_are_updated(nested): + entries = [[{"value": 1}]] if nested else [{"value": 1}] + value = StrictBox(entries=entries, box_dots=True, default_box=True) + path = "entries[0][0].value" if nested else "entries[0].value" + setattr(value, path, 2) + expected = [[{"value": 2}]] if nested else [{"value": 2}] + assert value.to_dict() == {"entries": expected} + + +def test_default_list_path_does_not_replace_an_intact_mapping(): + entry = defaultdict(int, value=1) + value = StrictBox(entries=[entry], box_dots=True, default_box=True, box_intact_types=(defaultdict,)) + with pytest.raises(BoxKeyError): + setattr(value, "entries[0].value", 2) + assert value.entries[0] is entry + assert entry == {"value": 1} + + +def test_intact_plain_list_is_not_a_dotted_destination(): + entries = [1] + value = StrictBox(entries=entries, box_dots=True, box_intact_types=(list,)) + with pytest.raises(BoxKeyError): + setattr(value, "entries[0]", 2) + assert entries == [1] + + +def test_dotted_alias_can_update_literal_key_below_non_container(): + value = StrictBox(parent=1, box_dots=True) + value.update({"parent.field": 2}) + value.parent_field = 3 + assert value.to_dict() == {"parent": 1, "parent.field": 3} + + +def test_case_insensitive_parent_does_not_authorize_a_new_exact_key(): + value = ConfigBox(default_box=True, default_box_attr={"field": 1}, box_class=StrictBox) + child = value.MISSING + value["missing"] = {"field": 10} + with pytest.raises(BoxKeyError): + child.field = 2 + assert value.to_dict() == {"missing": {"field": 10}} + assert child.to_dict() == {"field": 1} + + +class DefaultMapping(MutableMapping): + def __init__(self): + self.data = {} + self.defaulted = [] + + def __getitem__(self, key): + if key not in self.data: + self.defaulted.append(key) + self.data[key] = None + return self.data[key] + + def __setitem__(self, key, value): + self.data[key] = value + + def __delitem__(self, key): + del self.data[key] + + def __iter__(self): + return iter(self.data) + + def __len__(self): + return len(self.data) + + +def test_mapping_abc_contains_must_not_trigger_default_lookup(): + nested = DefaultMapping() + value = StrictBox(parent=nested, box_dots=True) + with pytest.raises(BoxKeyError): + setattr(value, "parent.new", 1) + assert nested.data == {} + assert nested.defaulted == [] + + +def test_mapping_abc_existing_field_can_be_replaced(): + nested = DefaultMapping() + nested["existing"] = 1 + value = StrictBox(parent=nested, box_dots=True) + setattr(value, "parent.existing", 2) + assert nested.data == {"existing": 2} + assert nested.defaulted == [] + + +def test_dotted_write_checks_pending_parents_of_nested_destination(): + value = StrictBox( + default_box=True, + default_box_attr={"field": 1}, + box_intact_types=(Box,), + box_dots=True, + ) + value["stored"] = value.missing + with pytest.raises(BoxKeyError): + setattr(value, "stored.field", 2) + assert list(value) == ["stored"] + assert value.stored.field == 1 + + +def test_case_insensitive_child_uses_its_own_pending_parent_rules(): + parent = ConfigBox(default_box=True, default_box_attr={"field": 1}) + child = parent.MISSING + parent["missing"] = {"field": 10} + root = StrictBox(stored=child, box_dots=True, box_intact_types=(Box,)) + setattr(root, "stored.field", 2) + assert parent.to_dict() == {"missing": {"field": 10}} + assert child.to_dict() == {"field": 2}