Coverage for /home/pradyumna/Languages/python/packages/xdgpspconf/xdgpspconf/data.py : 100%

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.
22Read:
23 - standard xdg-base locations
24 - current directory and ancestors
25 - custom location
27"""
29import os
30from pathlib import Path
31from typing import List, Union
33from xdgpspconf.common import locate_base, trace_ancestors, xdg_base
36def ancestral_data(child_dir: Path, perm: Union[str, int] = 0) -> List[Path]:
37 """
38 Walk up to nearest mountpoint or project root.
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
46 Args:
47 child_dir: walk ancestry of `this` directory
48 perm: require locations to have permissions
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)
57def xdg_data(perm: Union[int, str] = 0) -> List[Path]:
58 """
59 Get XDG_DATA_HOME locations.
61 `specifications
62 <https://specifications.freedesktop.org/basedir-spec/latest/ar01s03.html>`__
64 Args:
65 perm: require locations to have permissions
67 Returns:
68 List of xdg-data Paths
69 First directory is most dominant
70 """
71 return xdg_base('DATA', perm=perm)
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.
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
89 Returns:
90 List of all possible data paths:
91 Existing and non-existing
92 First directory is most dominant
94 """
95 return locate_base(project, custom, ancestors, 'DATA', py_bin, perm=perm)