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

20import typing as t 

21 

22from .iri import IRIReference 

23from .parseresult import ParseResult 

24from .uri import URIReference 

25 

26 

27def uri_reference( 

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

29 encoding: str = "utf-8", 

30) -> URIReference: 

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

32 

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

34 ``URIReference.from_string(uri)``. 

35 

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

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

38 :returns: A parsed URI 

39 :rtype: :class:`URIReference` 

40 """ 

41 return URIReference.from_string(uri, encoding) 

42 

43 

44def iri_reference( 

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

46 encoding: str = "utf-8", 

47) -> IRIReference: 

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

49 

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

51 ``IRIReference.from_string(iri)``. 

52 

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

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

55 :returns: A parsed IRI 

56 :rtype: :class:`IRIReference` 

57 """ 

58 return IRIReference.from_string(iri, encoding) 

59 

60 

61def is_valid_uri( 

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

63 encoding: str = "utf-8", 

64 **kwargs: bool, 

65) -> bool: 

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

67 

68 This is a convenience function. You could use either 

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

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

71 

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

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

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

75 presence of the scheme component. 

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

77 presence of the authority component. 

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

79 presence of the path component. 

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

81 presence of the query component. 

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

83 presence of the fragment component. 

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

85 :rtype: bool 

86 """ 

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

88 

89 

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

91 """Normalize the given URI. 

92 

93 This is a convenience function. You could use either 

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

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

96 

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

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

99 :returns: The normalized URI. 

100 :rtype: str 

101 """ 

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

103 return normalized_reference.unsplit() 

104 

105 

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

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

108 

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

110 

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

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

113 :returns: A parsed URI 

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

115 """ 

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