Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/uritemplate/api.py: 75%

1""" 

2 

3uritemplate.api 

4=============== 

5 

6This module contains the very simple API provided by uritemplate. 

7 

8""" 

9 

10import typing as t 

11 

12from uritemplate import variable 

13from uritemplate.orderedset import OrderedSet 

14from uritemplate.template import URITemplate 

15 

16__all__ = ("OrderedSet", "URITemplate", "expand", "partial", "variables") 

17 

18 

19def expand( 

20 uri: str, 

21 var_dict: t.Optional[variable.VariableValueDict] = None, 

22 **kwargs: variable.VariableValue, 

23) -> str: 

24 """Expand the template with the given parameters. 

25 

26 :param str uri: The templated URI to expand 

27 :param dict var_dict: Optional dictionary with variables and values 

28 :param kwargs: Alternative way to pass arguments 

29 :returns: str 

30 

31 Example:: 

32 

33 expand('https://api.github.com{/end}', {'end': 'users'}) 

34 expand('https://api.github.com{/end}', end='gists') 

35 

36 .. note:: Passing values by both parts, may override values in 

37 ``var_dict``. For example:: 

38 

39 expand('https://{var}', {'var': 'val1'}, var='val2') 

40 

41 ``val2`` will be used instead of ``val1``. 

42 

43 """ 

44 return URITemplate(uri).expand(var_dict, **kwargs) 

45 

46 

47def partial( 

48 uri: str, 

49 var_dict: t.Optional[variable.VariableValueDict] = None, 

50 **kwargs: variable.VariableValue, 

51) -> URITemplate: 

52 """Partially expand the template with the given parameters. 

53 

54 If all of the parameters for the template are not given, return a 

55 partially expanded template. 

56 

57 :param dict var_dict: Optional dictionary with variables and values 

58 :param kwargs: Alternative way to pass arguments 

59 :returns: :class:`URITemplate` 

60 

61 Example:: 

62 

63 t = URITemplate('https://api.github.com{/end}') 

64 t.partial() # => URITemplate('https://api.github.com{/end}') 

65 

66 """ 

67 return URITemplate(uri).partial(var_dict, **kwargs) 

68 

69 

70def variables(uri: str) -> OrderedSet: 

71 """Parse the variables of the template. 

72 

73 This returns all of the variable names in the URI Template. 

74 

75 :returns: Set of variable names 

76 :rtype: set 

77 

78 Example:: 

79 

80 variables('https://api.github.com{/end}) 

81 # => {'end'} 

82 variables('https://api.github.com/repos{/username}{/repository}') 

83 # => {'username', 'repository'} 

84 

85 """ 

86 return OrderedSet(URITemplate(uri).variable_names)