Coverage for python / lsst / ctrl / execute / findPackageFile.py: 25%

1# This file is part of ctrl_execute. 

2# 

3# Developed for the LSST Data Management System. 

4# This product includes software developed by the LSST Project 

5# (https://www.lsst.org). 

6# See the COPYRIGHT file at the top-level directory of this distribution 

7# for details of code ownership. 

8# 

9# This software is dual licensed under the GNU General Public License and also 

10# under a 3-clause BSD license. Recipients may choose which of these licenses 

11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt, 

12# respectively. If you choose the GPL option then the following text applies 

13# (but note that there is still no warranty even if you opt for BSD instead): 

14# 

15# This program is free software: you can redistribute it and/or modify 

16# it under the terms of the GNU General Public License as published by 

17# the Free Software Foundation, either version 3 of the License, or 

18# (at your option) any later version. 

19# 

20# This program is distributed in the hope that it will be useful, 

21# but WITHOUT ANY WARRANTY; without even the implied warranty of 

22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

23# GNU General Public License for more details. 

24# 

25# You should have received a copy of the GNU General Public License 

26# along with this program. If not, see <https://www.gnu.org/licenses/>. 

27 

28import os 

29import sys 

30 

31from lsst.resources import ResourcePath 

32 

33 

34def find_package_file(filename: str, kind: str = "config", platform: str | None = None) -> ResourcePath: 

35 """Find a package file from a set of candidate locations. 

36 

37 Parameters 

38 ---------- 

39 filename : `str` 

40 The unqualified name of a file to locate. 

41 

42 kind : `str` 

43 The name of a subdirectory in which to look for the file within a 

44 package location, relative to an ``etc/`` directory. 

45 

46 platform : `str` | `None` 

47 The name of a platform plugin in which to look for the file, or `None` 

48 if no platform plugin should be searched. 

49 

50 Returns 

51 ------- 

52 `lsst.resources.ResourcePath` 

53 

54 Raises 

55 ------ 

56 FileNotFoundError 

57 If a requested file object cannot be located in the candidate hierarchy 

58 

59 Notes 

60 ----- 

61 The candidate locations are, in descending order of preference: 

62 - An ``.lsst`` directory in the user's home directory. 

63 - An ``lsst`` directory in the user's ``$XDG_CONFIG_HOME`` directory 

64 - An ``etc/{kind}`` directory in the EUPS stack environment for the 

65 platform. 

66 - An ``etc/{kind}`` directory in the current Python environment/venv shared 

67 data directory. 

68 - An ``etc/{kind}`` directory in an installed ``lsst.ctrl.platform.*`` 

69 package. 

70 - An ``etc/{kind}`` directory in the ``lsst.ctrl.execute`` package. 

71 """ 

72 # If the path, after expansion, is absolute, we don't need to go looking 

73 # for it, it should be exactly where it is. 

74 if (_filename := ResourcePath(filename, forceAbsolute=False)).isabs(): 

75 return _filename 

76 

77 home_dir = os.getenv("HOME", "~") 

78 xdg_config_home = os.getenv("XDG_CONFIG_HOME", "~/.config") 

79 

80 file_candidates = [ 

81 ResourcePath(home_dir).join(".lsst").join(_filename), 

82 ResourcePath(xdg_config_home).join("lsst").join(_filename), 

83 ResourcePath(sys.exec_prefix).join("etc").join(kind).join(_filename), 

84 ( 

85 ResourcePath(f"resource://lsst.ctrl.platform.{platform}/etc/{kind}/{_filename}") 

86 if platform 

87 else None 

88 ), 

89 (ResourcePath(f"eups://ctrl_platform_{platform}/{kind}/{_filename}") if platform else None), 

90 ResourcePath(f"resource://lsst.ctrl.execute/etc/{kind}/{_filename}"), 

91 ] 

92 try: 

93 found_file: ResourcePath = [c for c in file_candidates if c is not None and c.exists()][0] 

94 except IndexError: 

95 raise FileNotFoundError(f"No file {filename} found in package file lookup") 

96 return found_file