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

1""" 

2 

3uritemplate.api 

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

5 

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

7 

8""" 

9import typing as t 

10 

11from uritemplate import variable 

12from uritemplate.orderedset import OrderedSet 

13from uritemplate.template import URITemplate 

14 

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

16 

17 

18def expand( 

19 uri: str, 

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

21 **kwargs: variable.VariableValue, 

22) -> str: 

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

24 

25 :param str uri: The templated URI to expand 

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

27 :param kwargs: Alternative way to pass arguments 

28 :returns: str 

29 

30 Example:: 

31 

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

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

34 

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

36 ``var_dict``. For example:: 

37 

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

39 

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

41 

42 """ 

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

44 

45 

46def partial( 

47 uri: str, 

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

49 **kwargs: variable.VariableValue, 

50) -> URITemplate: 

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

52 

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

54 partially expanded template. 

55 

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

57 :param kwargs: Alternative way to pass arguments 

58 :returns: :class:`URITemplate` 

59 

60 Example:: 

61 

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

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

64 

65 """ 

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

67 

68 

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

70 """Parse the variables of the template. 

71 

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

73 

74 :returns: Set of variable names 

75 :rtype: set 

76 

77 Example:: 

78 

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

80 # => {'end'} 

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

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

83 

84 """ 

85 return OrderedSet(URITemplate(uri).variable_names)