Coverage for pyTooling / GenericPath / URL.py: 80%

1# ==================================================================================================================== # 

2# _____ _ _ ____ _ ____ _ _ # 

3# _ __ _ |_ _|__ ___ | (_)_ __ __ _ / ___| ___ _ __ ___ _ __(_) ___| _ \ __ _| |_| |__ # 

4# | '_ \| | | || |/ _ \ / _ \| | | '_ \ / _` || | _ / _ \ '_ \ / _ \ '__| |/ __| |_) / _` | __| '_ \ # 

5# | |_) | |_| || | (_) | (_) | | | | | | (_| || |_| | __/ | | | __/ | | | (__| __/ (_| | |_| | | | # 

6# | .__/ \__, ||_|\___/ \___/|_|_|_| |_|\__, (_)____|\___|_| |_|\___|_| |_|\___|_| \__,_|\__|_| |_| # 

7# |_| |___/ |___/ # 

8# ==================================================================================================================== # 

9# Authors: # 

10# Patrick Lehmann # 

11# # 

12# License: # 

13# ==================================================================================================================== # 

14# Copyright 2017-2025 Patrick Lehmann - Bötzingen, Germany # 

15# # 

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

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

18# You may obtain a copy of the License at # 

19# # 

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

21# # 

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

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

24# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # 

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

26# limitations under the License. # 

27# # 

28# SPDX-License-Identifier: Apache-2.0 # 

29# ==================================================================================================================== # 

30# 

31""" 

32This package provides a representation for a Uniform Resource Locator (URL). 

33 

34.. code-block:: 

35 

36 [schema://][user[:password]@]domain.tld[:port]/path/to/file[?query][#fragment] 

37""" 

38 

39from enum import IntFlag 

40from re import compile as re_compile 

41from typing import Dict, Optional as Nullable, Mapping 

42 

43try: 

44 from pyTooling.Decorators import export, readonly 

45 from pyTooling.Exceptions import ToolingException 

46 from pyTooling.Common import getFullyQualifiedName 

47 from pyTooling.GenericPath import RootMixIn, ElementMixIn, PathMixIn 

48except (ImportError, ModuleNotFoundError): # pragma: no cover 

49 print("[pyTooling.GenericPath.URL] Could not import from 'pyTooling.*'!") 

50 

51 try: 

52 from Decorators import export, readonly 

53 from Exceptions import ToolingException 

54 from Common import getFullyQualifiedName 

55 from GenericPath import RootMixIn, ElementMixIn, PathMixIn 

56 except (ImportError, ModuleNotFoundError) as ex: # pragma: no cover 

57 print("[pyTooling.GenericPath.URL] Could not import directly!") 

58 raise ex 

59 

60 

61__all__ = ["URL_PATTERN", "URL_REGEXP"] 

62 

63URL_PATTERN = ( 

64 r"""(?:(?P<scheme>\w+)://)?""" 

65 r"""(?:(?P<user>[-a-zA-Z0-9_]+)(?::(?P<password>[-a-zA-Z0-9_]+))?@)?""" 

66 r"""(?:(?P<host>(?:[-a-zA-Z0-9_]+)(?:\.[-a-zA-Z0-9_]+)*\.?)(?:\:(?P<port>\d+))?)?""" 

67 r"""(?P<path>[^?#]*?)""" 

68 r"""(?:\?(?P<query>[^#]+?))?""" 

69 r"""(?:#(?P<fragment>.+?))?""" 

70) #: Regular expression pattern for validating and splitting a URL. 

71URL_REGEXP = re_compile("^" + URL_PATTERN + "$") #: Precompiled regular expression for URL validation. 

72 

73 

74@export 

75class Protocols(IntFlag): 

76 """Enumeration of supported URL schemes.""" 

77 

78 TLS = 1 #: Transport Layer Security 

79 HTTP = 2 #: Hyper Text Transfer Protocol 

80 HTTPS = 4 #: SSL/TLS secured HTTP 

81 FTP = 8 #: File Transfer Protocol 

82 FTPS = 16 #: SSL/TLS secured FTP 

83 FILE = 32 #: Local files 

84 

85 

86@export 

87class Host(RootMixIn): 

88 """Represents a host as either hostname, DNS or IP-address including the port number in a URL.""" 

89 

90 _hostname: str 

91 _port: Nullable[int] 

92 

93 def __init__( 

94 self, 

95 hostname: str, 

96 port: Nullable[int] = None 

97 ) -> None: 

98 """ 

99 Initialize a host instance described by host name and port number. 

100 

101 :param hostname: Name of the host (either IP or DNS). 

102 :param port: Port number. 

103 """ 

104 super().__init__() 

105 

106 if not isinstance(hostname, str): 106 ↛ 107line 106 didn't jump to line 107 because the condition on line 106 was never true

107 ex = TypeError("Parameter 'hostname' is not of type 'str'.") 

108 ex.add_note(f"Got type '{getFullyQualifiedName(hostname)}'.") 

109 raise ex 

110 self._hostname = hostname 

111 

112 if port is None: 

113 pass 

114 elif not isinstance(port, int): 114 ↛ 115line 114 didn't jump to line 115 because the condition on line 114 was never true

115 ex = TypeError("Parameter 'port' is not of type 'int'.") 

116 ex.add_note(f"Got type '{getFullyQualifiedName(hostname)}'.") 

117 raise ex 

118 elif not (0 <= port < 65536): 118 ↛ 119line 118 didn't jump to line 119 because the condition on line 118 was never true

119 ex = ValueError("Parameter 'port' is out of range 0..65535.") 

120 ex.add_note(f"Got value '{port}'.") 

121 raise ex 

122 self._port = port 

123 

124 @readonly 

125 def Hostname(self) -> str: 

126 """Hostname or IP address as string.""" 

127 return self._hostname 

128 

129 @readonly 

130 def Port(self) -> Nullable[int]: 

131 """Port number as integer.""" 

132 return self._port 

133 

134 def __str__(self) -> str: 

135 result = self._hostname 

136 if self._port is not None: 

137 result += f":{self._port}" 

138 

139 return result 

140 

141 def Copy(self) -> "Host": 

142 """ 

143 Create a copy of this object. 

144 

145 :return: A new Host instance. 

146 """ 

147 return self.__class__( 

148 self._hostname, 

149 self._port 

150 ) 

151 

152 

153@export 

154class Element(ElementMixIn): 

155 """Derived class for the URL context.""" 

156 

157 

158@export 

159class Path(PathMixIn): 

160 """Represents a path in a URL.""" 

161 

162 ELEMENT_DELIMITER = "/" #: Delimiter symbol in URLs between path elements. 

163 ROOT_DELIMITER = "/" #: Delimiter symbol in URLs between root element and first path element. 

164 

165 @classmethod 

166 def Parse(cls, path: str, root: Nullable[Host] = None) -> "Path": 

167 return super().Parse(path, root, cls, Element) 

168 

169 

170@export 

171class URL: 

172 """ 

173 Represents a URL (Uniform Resource Locator) including scheme, host, credentials, path, query and fragment. 

174 

175 .. code-block:: 

176 

177 [schema://][user[:password]@]domain.tld[:port]/path/to/file[?query][#fragment] 

178 """ 

179 

180 _scheme: Protocols 

181 _user: Nullable[str] 

182 _password: Nullable[str] 

183 _host: Nullable[Host] 

184 _path: Path 

185 _query: Nullable[Dict[str, str]] 

186 _fragment: Nullable[str] 

187 

188 def __init__( 

189 self, 

190 scheme: Protocols, 

191 path: Path, 

192 host: Nullable[Host] = None, 

193 user: Nullable[str] = None, 

194 password: Nullable[str] = None, 

195 query: Nullable[Mapping[str, str]] = None, 

196 fragment: Nullable[str] = None 

197 ) -> None: 

198 """ 

199 Initializes a Uniform Resource Locator (URL). 

200 

201 :param scheme: Transport scheme to be used for a specified resource. 

202 :param path: Path to the resource. 

203 :param host: Hostname where the resource is located. 

204 :param user: Username for basic authentication. 

205 :param password: Password for basic authentication. 

206 :param query: An optional query string. 

207 :param fragment: An optional fragment. 

208 """ 

209 if scheme is not None and not isinstance(scheme, Protocols): 209 ↛ 210line 209 didn't jump to line 210 because the condition on line 209 was never true

210 ex = TypeError("Parameter 'scheme' is not of type 'Protocols'.") 

211 ex.add_note(f"Got type '{getFullyQualifiedName(scheme)}'.") 

212 raise ex 

213 self._scheme = scheme 

214 

215 if user is not None and not isinstance(user, str): 215 ↛ 216line 215 didn't jump to line 216 because the condition on line 215 was never true

216 ex = TypeError("Parameter 'user' is not of type 'str'.") 

217 ex.add_note(f"Got type '{getFullyQualifiedName(user)}'.") 

218 raise ex 

219 self._user = user 

220 

221 if password is not None and not isinstance(password, str): 221 ↛ 222line 221 didn't jump to line 222 because the condition on line 221 was never true

222 ex = TypeError(f"Parameter 'password' is not of type 'str'.") 

223 ex.add_note(f"Got type '{getFullyQualifiedName(password)}'.") 

224 raise ex 

225 self._password = password 

226 

227 if host is not None and not isinstance(host, Host): 227 ↛ 228line 227 didn't jump to line 228 because the condition on line 227 was never true

228 ex = TypeError(f"Parameter 'host' is not of type 'Host'.") 

229 ex.add_note(f"Got type '{getFullyQualifiedName(host)}'.") 

230 raise ex 

231 self._host = host 

232 

233 if path is not None and not isinstance(path, Path): 233 ↛ 234line 233 didn't jump to line 234 because the condition on line 233 was never true

234 ex = TypeError(f"Parameter 'path' is not of type 'Path'.") 

235 ex.add_note(f"Got type '{getFullyQualifiedName(path)}'.") 

236 raise ex 

237 self._path = path 

238 

239 if query is not None: 

240 if not isinstance(query, Mapping): 240 ↛ 241line 240 didn't jump to line 241 because the condition on line 240 was never true

241 ex = TypeError(f"Parameter 'query' is not a mapping ('dict', ...).") 

242 ex.add_note(f"Got type '{getFullyQualifiedName(query)}'.") 

243 raise ex 

244 

245 self._query = {keyword: value for keyword, value in query.items()} 

246 else: 

247 self._query = None 

248 

249 if fragment is not None and not isinstance(fragment, str): 249 ↛ 250line 249 didn't jump to line 250 because the condition on line 249 was never true

250 ex = TypeError(f"Parameter 'fragment' is not of type 'str'.") 

251 ex.add_note(f"Got type '{getFullyQualifiedName(fragment)}'.") 

252 raise ex 

253 self._fragment = fragment 

254 

255 @readonly 

256 def Scheme(self) -> Protocols: 

257 return self._scheme 

258 

259 @readonly 

260 def User(self) -> Nullable[str]: 

261 return self._user 

262 

263 @readonly 

264 def Password(self) -> Nullable[str]: 

265 return self._password 

266 

267 @readonly 

268 def Host(self) -> Nullable[Host]: 

269 """ 

270 Returns the host part (host name and port number) of the URL. 

271 

272 :return: The host part of the URL. 

273 """ 

274 return self._host 

275 

276 @readonly 

277 def Path(self) -> Path: 

278 return self._path 

279 

280 @readonly 

281 def Query(self) -> Nullable[Dict[str, str]]: 

282 """ 

283 Returns a dictionary of key-value pairs representing the query part in a URL. 

284 

285 :returns: A dictionary representing the query. 

286 """ 

287 return self._query 

288 

289 @readonly 

290 def Fragment(self) -> Nullable[str]: 

291 """ 

292 Returns the fragment part of the URL. 

293 

294 :return: The fragment part of the URL. 

295 """ 

296 return self._fragment 

297 

298 # http://semaphore.plc2.de:5000/api/v1/semaphore?name=Riviera&foo=bar#page2 

299 @classmethod 

300 def Parse(cls, url: str) -> "URL": 

301 """ 

302 Parse a URL string and returns a URL object. 

303 

304 :param url: URL as string to be parsed. 

305 :returns: A URL object. 

306 :raises ToolingException: When syntax does not match. 

307 """ 

308 matches = URL_REGEXP.match(url) 

309 if matches is not None: 309 ↛ 343line 309 didn't jump to line 343 because the condition on line 309 was always true

310 scheme = matches.group("scheme") 

311 user = matches.group("user") 

312 password = matches.group("password") 

313 host = matches.group("host") 

314 

315 port = matches.group("port") 

316 if port is not None: 

317 port = int(port) 

318 path = matches.group("path") 

319 query = matches.group("query") 

320 fragment = matches.group("fragment") 

321 

322 scheme = None if scheme is None else Protocols[scheme.upper()] 

323 hostObj = None if host is None else Host(host, port) 

324 

325 pathObj = Path.Parse(path, hostObj) 

326 

327 parameters = {} 

328 if query is not None: 

329 for pair in query.split("&"): 

330 key, value = pair.split("=") 

331 parameters[key] = value 

332 

333 return cls( 

334 scheme, 

335 pathObj, 

336 hostObj, 

337 user, 

338 password, 

339 parameters if len(parameters) > 0 else None, 

340 fragment 

341 ) 

342 

343 raise ToolingException(f"Syntax error when parsing URL '{url}'.") 

344 

345 def __str__(self) -> str: 

346 """ 

347 Formats the URL object as a string representation. 

348 

349 :return: Formatted URL object. 

350 """ 

351 result = str(self._path) 

352 

353 if self._host is not None: 353 ↛ 356line 353 didn't jump to line 356 because the condition on line 353 was always true

354 result = str(self._host) + result 

355 

356 if self._user is not None: 

357 if self._password is not None: 

358 result = f"{self._user}:{self._password}@{result}" 

359 else: 

360 result = f"{self._user}@{result}" 

361 

362 if self._scheme is not None: 

363 result = self._scheme.name.lower() + "://" + result 

364 

365 if self._query is not None and len(self._query) > 0: 

366 result = result + "?" + "&".join([f"{key}={value}" for key, value in self._query.items()]) 

367 

368 if self._fragment is not None: 

369 result = result + "#" + self._fragment 

370 

371 return result 

372 

373 def WithoutCredentials(self) -> "URL": 

374 """ 

375 Returns a URL object without credentials (username and password). 

376 

377 :return: New URL object without credentials. 

378 """ 

379 return self.__class__( 

380 scheme=self._scheme, 

381 path=self._path, 

382 host=self._host, 

383 query=self._query, 

384 fragment=self._fragment 

385 )