Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1#!/usr/bin/env python3 

2# -*- coding: utf-8; mode: python; -*- 

3# Copyright © 2021 Pradyumna Paranjape 

4# 

5# This file is part of xdgpspconf. 

6# 

7# xdgpspconf is free software: you can redistribute it and/or modify 

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

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

10# (at your option) any later version. 

11# 

12# xdgpspconf is distributed in the hope that it will be useful, 

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

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

15# GNU Lesser General Public License for more details. 

16# 

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

18# along with xdgpspconf. If not, see <https://www.gnu.org/licenses/>. # 

19""" 

20Locate standard data. 

21 

22Read: 

23 - standard xdg-base locations 

24 - current directory and ancestors 

25 - custom location 

26 

27""" 

28 

29import os 

30from pathlib import Path 

31from typing import List, Union 

32 

33from xdgpspconf.common import locate_base, trace_ancestors, xdg_base 

34 

35 

36def ancestral_data(child_dir: Path, perm: Union[str, int] = 0) -> List[Path]: 

37 """ 

38 Walk up to nearest mountpoint or project root. 

39 

40 - collect all directories containing __init__.py 

41 (assumed to be source directories) 

42 - project root is directory that contains ``setup.cfg`` or ``setup.py`` 

43 - mountpoint is a unix mountpoint or windows drive root 

44 - I am **NOT** my ancestor 

45 

46 Args: 

47 child_dir: walk ancestry of `this` directory 

48 perm: require locations to have permissions 

49 

50 Returns: 

51 List of Paths to ancestral source directories: 

52 First directory is most dominant 

53 """ 

54 return trace_ancestors(child_dir, perm=perm) 

55 

56 

57def xdg_data(perm: Union[int, str] = 0) -> List[Path]: 

58 """ 

59 Get XDG_DATA_HOME locations. 

60 

61 `specifications 

62 <https://specifications.freedesktop.org/basedir-spec/latest/ar01s03.html>`__ 

63 

64 Args: 

65 perm: require locations to have permissions 

66 

67 Returns: 

68 List of xdg-data Paths 

69 First directory is most dominant 

70 """ 

71 return xdg_base('DATA', perm=perm) 

72 

73 

74def locate_data(project: str, 

75 custom: os.PathLike = None, 

76 ancestors: bool = False, 

77 py_bin: os.PathLike = None, 

78 perm: Union[int, str] = 0) -> List[Path]: 

79 """ 

80 Locate data at standard locations. 

81 

82 Args: 

83 project: name of project whose data is being fetched 

84 custom: custom location for data 

85 ancestors: inherit ancestor directories that contain __init__.py 

86 py_bin: namespace.__file__ that imports this function 

87 perm: require locations to have permissions 

88 

89 Returns: 

90 List of all possible data paths: 

91 Existing and non-existing 

92 First directory is most dominant 

93 

94 """ 

95 return locate_base(project, custom, ancestors, 'DATA', py_bin, perm=perm)