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

1#!/usr/bin/env python 

2 

3""" 

4camcops_server/cc_modules/cc_formatter.py 

5 

6=============================================================================== 

7 

8 Copyright (C) 2012, University of Cambridge, Department of Psychiatry. 

9 Created by Rudolf Cardinal (rnc1001@cam.ac.uk). 

10 

11 This file is part of CamCOPS. 

12 

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. 

17 

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. 

22 

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/>. 

25 

26=============================================================================== 

27 

28**Safe alternative to str.format() that rejects anything not in the list of 

29allowed keys.** 

30 

31""" 

32 

33from string import Formatter 

34 

35from typing import Any, Mapping, Sequence, Tuple 

36 

37 

38class SafeFormatter(Formatter): 

39 """ 

40 Safe alternative to ``str.format()`` that rejects anything not in the list 

41 of allowed keys. 

42 

43 Basic usage: 

44 

45 .. code-block:: python 

46 

47 from camcops_server.cc_modules.cc_formatter import SafeFormatter 

48 

49 f = SafeFormatter(["a", "b"]) 

50 

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 """ 

55 

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__() 

64 

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) 

71 

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.). 

77 

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` 

86 

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 

90 

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) 

97 

98 return super().get_field(field_name, args, kwargs) 

99 

100 def validate(self, format_string: str) -> None: 

101 """ 

102 Checks a format string for validity. 

103 

104 Args: 

105 format_string: 

106 string to check 

107 

108 Raises: 

109 - :exc:`KeyError` for unknown key 

110 - :exc:`ValueError` for unmatched ``{`` 

111 

112 """ 

113 test_dict = {k: "" for k in self._allowed_keys} 

114 

115 self.format(format_string, **test_dict)