Coverage for src/bunches/settings.py: 100%

1"""Settings for `bunches`. 

2 

3Contents: 

4 set_key_namer: sets the global function used to name items. 

5 set_subset_return: sets the global default `returns` option for `subset` 

6 methods. 

7 _ALL_KEYS: keys that a `Catalog` treats as a request for all values. 

8 _DEFAULT_KEYS: keys that a `Catalog` treats as a request for its default 

9 values. 

10 _KEY_NAMER: function used to name items in a `Repository` or `DictList`. 

11 _NONE_KEYS: keys that a `Catalog` treats as a request for no values. 

12 _SUBSET_RETURN: default `returns` option for `subset` methods. 

13 

14The module-level values hold the package-wide defaults. They are read at call 

15time, so the `set_*` functions take effect immediately for all `bunches` 

16classes. 

17 

18""" 

19 

20from __future__ import annotations 

21 

22from collections.abc import Callable 

23from typing import TYPE_CHECKING, Any 

24 

25from . import utilities 

26 

27if TYPE_CHECKING: 

28 from .kinds import SubsetReturns 

29 

30 

31_ALL_KEYS: list[Any] = ['all', 'All', ['all'], ['All']] 

32_DEFAULT_KEYS: list[Any] = [ 

33 'default', 

34 'defaults', 

35 'Default', 

36 'Defaults', 

37 ['default'], 

38 ['defaults'], 

39 ['Default'], 

40 ['Defaults']] 

41_KEY_NAMER: Callable[[object | type[Any]], str | None] = utilities._namify 

42_NONE_KEYS: list[Any] = ['none', 'None', ['none'], ['None']] 

43_SUBSET_RETURN: SubsetReturns = 'class' 

44 

45 

46""" Public Functions """ 

47 

48 

49def set_key_namer(namer: Callable[[object | type[Any]], str | None]) -> None: 

50 """Sets the global default function used to name items. 

51 

52 Args: 

53 namer: function that returns a `str` name of any item passed. 

54 

55 Raises: 

56 TypeError: if 'namer' is not callable. 

57 

58 """ 

59 if not callable(namer): 

60 raise TypeError('namer argument must be a callable') 

61 globals()['_KEY_NAMER'] = namer 

62 

63 

64def set_subset_return(returns: SubsetReturns) -> None: 

65 """Sets the global default for the `returns` argument of `subset` methods. 

66 

67 Args: 

68 returns: whether `subset` methods return a new instance of the class 

69 ('class'), a deep copy of the instance ('copy') or the simple 

70 native Python type ('simple'). 

71 

72 Raises: 

73 ValueError: if 'returns' is not 'class', 'copy', or 'simple'. 

74 

75 """ 

76 if returns not in ('class', 'copy', 'simple'): 

77 message = 'returns argument must be "class", "copy", or "simple"' 

78 raise ValueError(message) 

79 globals()['_SUBSET_RETURN'] = returns