Coverage for cc_modules/cc_formatter.py: 62%
16 statements
« prev ^ index » next coverage.py v6.5.0, created at 2022-11-08 23:14 +0000
« prev ^ index » next coverage.py v6.5.0, created at 2022-11-08 23:14 +0000
1#!/usr/bin/env python
3"""
4camcops_server/cc_modules/cc_formatter.py
6===============================================================================
8 Copyright (C) 2012, University of Cambridge, Department of Psychiatry.
9 Created by Rudolf Cardinal (rnc1001@cam.ac.uk).
11 This file is part of CamCOPS.
13 CamCOPS is free software: you can redistribute it and/or modify
14 it under the terms of the GNU General Public License as published by
15 the Free Software Foundation, either version 3 of the License, or
16 (at your option) any later version.
18 CamCOPS is distributed in the hope that it will be useful,
19 but WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 GNU General Public License for more details.
23 You should have received a copy of the GNU General Public License
24 along with CamCOPS. If not, see <https://www.gnu.org/licenses/>.
26===============================================================================
28**Safe alternative to str.format() that rejects anything not in the list of
29allowed keys.**
31"""
33from string import Formatter
35from typing import Any, Mapping, Sequence, Tuple
38class SafeFormatter(Formatter):
39 """
40 Safe alternative to ``str.format()`` that rejects anything not in the list
41 of allowed keys.
43 Basic usage:
45 .. code-block:: python
47 from camcops_server.cc_modules.cc_formatter import SafeFormatter
49 f = SafeFormatter(["a", "b"])
51 f.format("a={a}, b={b}", a=1, b=2) # OK
52 f.format("a={a.__class__}", a=1) # raises KeyError
53 f.format("a={a}, b={b}, c={c}", a=1, b=2, c=3) # raises KeyError
54 """
56 def __init__(self, allowed_keys: Sequence[str]) -> None:
57 """
58 Args:
59 allowed_keys:
60 Keys that are permitted within a brace-delimited format string.
61 """
62 self._allowed_keys = allowed_keys
63 super().__init__()
65 def get_valid_parameters_string(self) -> str:
66 """
67 Returns a string, such as ``{a}, {b}``, that enumerates the parameters
68 allowed (e.g. for user help).
69 """
70 return ", ".join(f"{{{k}}}" for k in self._allowed_keys)
72 def get_field(
73 self, field_name: str, args: Sequence[Any], kwargs: Mapping[str, Any]
74 ) -> Tuple[Any, str]:
75 """
76 Overrides :meth:`Formatter.get_field` (q.v.).
78 Args:
79 field_name:
80 name of the field to be looked up
81 args:
82 positional arguments passed to :meth:`format` (not including
83 the format string)
84 kwargs:
85 keyword arguments passed to :meth:`format`
87 Returns:
88 tuple: ``(obj, arg_used)`` where ``obj`` is the object that's been
89 looked up, and ``arg_used`` is the argument it came from
91 Raises:
92 - :exc:`KeyError` if the field_name is disallowed
93 """
94 # print(f"field_name={field_name!r}, args={args!r}, kwargs={kwargs!r}")
95 if field_name not in self._allowed_keys:
96 raise KeyError(field_name)
98 return super().get_field(field_name, args, kwargs)
100 def validate(self, format_string: str) -> None:
101 """
102 Checks a format string for validity.
104 Args:
105 format_string:
106 string to check
108 Raises:
109 - :exc:`KeyError` for unknown key
110 - :exc:`ValueError` for unmatched ``{``
112 """
113 test_dict = {k: "" for k in self._allowed_keys}
115 self.format(format_string, **test_dict)