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

1# Copyright (c) 2014 Rackspace 

2# Licensed under the Apache License, Version 2.0 (the "License"); 

3# you may not use this file except in compliance with the License. 

4# You may obtain a copy of the License at 

5# 

6# http://www.apache.org/licenses/LICENSE-2.0 

7# 

8# Unless required by applicable law or agreed to in writing, software 

9# distributed under the License is distributed on an "AS IS" BASIS, 

10# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 

11# implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14""" 

15Module containing the simple and functional API for rfc3986. 

16 

17This module defines functions and provides access to the public attributes 

18and classes of rfc3986. 

19""" 

20 

21import typing as t 

22 

23from .iri import IRIReference 

24from .parseresult import ParseResult 

25from .uri import URIReference 

26 

27 

28def uri_reference( 

29 uri: t.Union[str, bytes], 

30 encoding: str = "utf-8", 

31) -> URIReference: 

32 """Parse a URI string into a URIReference. 

33 

34 This is a convenience function. You could achieve the same end by using 

35 ``URIReference.from_string(uri)``. 

36 

37 :param str uri: The URI which needs to be parsed into a reference. 

38 :param str encoding: The encoding of the string provided 

39 :returns: A parsed URI 

40 :rtype: :class:`URIReference` 

41 """ 

42 return URIReference.from_string(uri, encoding) 

43 

44 

45def iri_reference( 

46 iri: t.Union[str, bytes], 

47 encoding: str = "utf-8", 

48) -> IRIReference: 

49 """Parse a IRI string into an IRIReference. 

50 

51 This is a convenience function. You could achieve the same end by using 

52 ``IRIReference.from_string(iri)``. 

53 

54 :param str iri: The IRI which needs to be parsed into a reference. 

55 :param str encoding: The encoding of the string provided 

56 :returns: A parsed IRI 

57 :rtype: :class:`IRIReference` 

58 """ 

59 return IRIReference.from_string(iri, encoding) 

60 

61 

62def is_valid_uri( 

63 uri: t.Union[str, bytes], 

64 encoding: str = "utf-8", 

65 **kwargs: bool, 

66) -> bool: 

67 """Determine if the URI given is valid. 

68 

69 This is a convenience function. You could use either 

70 ``uri_reference(uri).is_valid()`` or 

71 ``URIReference.from_string(uri).is_valid()`` to achieve the same result. 

72 

73 :param str uri: The URI to be validated. 

74 :param str encoding: The encoding of the string provided 

75 :param bool require_scheme: Set to ``True`` if you wish to require the 

76 presence of the scheme component. 

77 :param bool require_authority: Set to ``True`` if you wish to require the 

78 presence of the authority component. 

79 :param bool require_path: Set to ``True`` if you wish to require the 

80 presence of the path component. 

81 :param bool require_query: Set to ``True`` if you wish to require the 

82 presence of the query component. 

83 :param bool require_fragment: Set to ``True`` if you wish to require the 

84 presence of the fragment component. 

85 :returns: ``True`` if the URI is valid, ``False`` otherwise. 

86 :rtype: bool 

87 """ 

88 return URIReference.from_string(uri, encoding).is_valid(**kwargs) 

89 

90 

91def normalize_uri(uri: t.Union[str, bytes], encoding: str = "utf-8") -> str: 

92 """Normalize the given URI. 

93 

94 This is a convenience function. You could use either 

95 ``uri_reference(uri).normalize().unsplit()`` or 

96 ``URIReference.from_string(uri).normalize().unsplit()`` instead. 

97 

98 :param str uri: The URI to be normalized. 

99 :param str encoding: The encoding of the string provided 

100 :returns: The normalized URI. 

101 :rtype: str 

102 """ 

103 normalized_reference = URIReference.from_string(uri, encoding).normalize() 

104 return normalized_reference.unsplit() 

105 

106 

107def urlparse(uri: t.Union[str, bytes], encoding: str = "utf-8") -> ParseResult: 

108 """Parse a given URI and return a ParseResult. 

109 

110 This is a partial replacement of the standard library's urlparse function. 

111 

112 :param str uri: The URI to be parsed. 

113 :param str encoding: The encoding of the string provided. 

114 :returns: A parsed URI 

115 :rtype: :class:`~rfc3986.parseresult.ParseResult` 

116 """ 

117 return ParseResult.from_string(uri, encoding, strict=False)