Skip to content

utils

pykmhelpers.core.utils

Main

Main initialization class for kmhelpers.

Source code in pykmhelpers/core/utils.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
class Main:
    """Main initialization class for kmhelpers."""

    ####################################################
    @staticmethod
    def init(
        default_bin_path: str = "./bin", check_all: bool = True, chdir: str = ""
    ) -> None:
        """
        Initialize kmhelpers by setting up binary paths and checking dependencies.

        Args:
            default_bin_path: Default path for binary executables (default: "./bin").
            check_all: If True, verify all required binaries are available (default: True).
            chdir: If non-empty, change the working directory to this path before initialization.
        """
        if chdir:
            logger.info(f"cd {chdir}")
            os.chdir(chdir)
        Bin.set_default_bin_path(default_bin_path)
        Bin.add_bin_dir_to_syspath()
        logger.info(f"KMHELPERS_BIN_PATH={Bin.get_bin_dir()}")
        os.makedirs(Bin.get_bin_dir(), exist_ok=True)
        if check_all:
            Bin.check_all()

init(default_bin_path='./bin', check_all=True, chdir='') staticmethod

Initialize kmhelpers by setting up binary paths and checking dependencies.

Parameters:

Name Type Description Default
default_bin_path str

Default path for binary executables (default: "./bin").

 './bin'
check_all bool

If True, verify all required binaries are available (default: True).

 True
chdir str

If non-empty, change the working directory to this path before initialization.

 ''
Source code in pykmhelpers/core/utils.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
@staticmethod
def init(
    default_bin_path: str = "./bin", check_all: bool = True, chdir: str = ""
) -> None:
    """
    Initialize kmhelpers by setting up binary paths and checking dependencies.

    Args:
        default_bin_path: Default path for binary executables (default: "./bin").
        check_all: If True, verify all required binaries are available (default: True).
        chdir: If non-empty, change the working directory to this path before initialization.
    """
    if chdir:
        logger.info(f"cd {chdir}")
        os.chdir(chdir)
    Bin.set_default_bin_path(default_bin_path)
    Bin.add_bin_dir_to_syspath()
    logger.info(f"KMHELPERS_BIN_PATH={Bin.get_bin_dir()}")
    os.makedirs(Bin.get_bin_dir(), exist_ok=True)
    if check_all:
        Bin.check_all()

Bin

Binary path management and validation utilities.

Source code in pykmhelpers/core/utils.py 
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
class Bin:
    """Binary path management and validation utilities."""

    ####################################################
    @staticmethod
    def set_default_bin_path(path: str) -> None:
        """
        Set the default binary path if not already set.

        Args:
            path: Path to the binary directory
        """
        os.environ.setdefault("KMHELPERS_BIN_PATH", Toolbox.get_canonical_path(path))

    ####################################################
    @staticmethod
    def fetch(binary: str, path: str) -> None:
        """
        Fetch a binary from a given path and create a symlink in the bin directory.

        Args:
            binary: Name of the binary
            path: Source path of the binary

        Raises:
            AssertionError: If the source binary is not found
        """
        bin_path = Bin.get_bin_path(binary)
        if not os.path.isfile(bin_path):
            assert os.path.isfile(path), f"Binary not found: {path}"
            logger.info(f"Linking {path} to {bin_path}")
            os.symlink(path, bin_path)

    ####################################################
    @staticmethod
    def get_bin_dir() -> str:
        """
        Get the binary directory path.

        Returns:
            The canonical path to the binary directory

        Raises:
            RuntimeError: If Main.init() hasn't been called
        """
        if "KMHELPERS_BIN_PATH" not in os.environ:
            raise RuntimeError(
                "Main.init() must be called at program startup before using get_bin_dir()"
            )
        return Toolbox.get_canonical_path(os.environ["KMHELPERS_BIN_PATH"])

    ####################################################
    @staticmethod
    def get_bin_path(binary: str) -> str:
        """
        Get the full path to a binary executable.

        Args:
            binary: Name of the binary

        Returns:
            Full path to the binary
        """
        return os.path.join(Bin.get_bin_dir(), binary)

    ####################################################
    @staticmethod
    def add_bin_dir_to_syspath() -> None:
        """Add the binary directory to the system PATH."""
        os.environ["PATH"] = (
            f"{Bin.get_bin_dir()}{os.pathsep}{os.environ.get('PATH', '')}"
        )

    ####################################################
    @staticmethod
    def kmindex() -> str:
        """Get the kmindex binary name."""
        return "kmindex"

    ####################################################
    @staticmethod
    def check_bin(binary_name: str) -> None:
        """
        Check if a binary exists in PATH and print a warning if not found.

        Args:
            binary_name: Name of the binary to check
        """
        if not shutil.which(binary_name):
            logger.warning(f"{binary_name} command not found in PATH")

    ####################################################
    @staticmethod
    def check_kmindex() -> None:
        """
        Check if kmindex is available with helpful error message.

        Raises:
            RuntimeError: If kmindex >= 0.5.3 is not found in PATH
        """
        kmindex_path = shutil.which(Bin.kmindex())
        if not kmindex_path:
            raise RuntimeError(
                f"kmindex >= 0.5.3 is required but not found in PATH.\n"
                f"\n"
                f"Install via bioconda:\n"
                f"  conda install -c bioconda kmindex>=0.5.3\n"
                f"\n"
                f"Or compile from source and add to PATH:\n"
                f"  export PATH=/path/to/kmindex/build:$PATH\n"
                f"\n"
                f"Verify installation:\n"
                f"  kmindex --version"
            )

    ####################################################
    @staticmethod
    def check_all() -> None:
        """Check all required binaries are available in PATH."""
        binaries = [
            Bin.kmindex(),
        ]

        for binary in binaries:
            Bin.check_bin(binary)

set_default_bin_path(path) staticmethod

Set the default binary path if not already set.

Parameters:

Name Type Description Default
path str

Path to the binary directory

 required
Source code in pykmhelpers/core/utils.py 
43
44
45
46
47
48
49
50
51
@staticmethod
def set_default_bin_path(path: str) -> None:
    """
    Set the default binary path if not already set.

    Args:
        path: Path to the binary directory
    """
    os.environ.setdefault("KMHELPERS_BIN_PATH", Toolbox.get_canonical_path(path))

fetch(binary, path) staticmethod

Fetch a binary from a given path and create a symlink in the bin directory.

Parameters:

Name Type Description Default
binary str

Name of the binary

 required
path str

Source path of the binary

 required

Raises:

Type Description
AssertionError

If the source binary is not found
Source code in pykmhelpers/core/utils.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
@staticmethod
def fetch(binary: str, path: str) -> None:
    """
    Fetch a binary from a given path and create a symlink in the bin directory.

    Args:
        binary: Name of the binary
        path: Source path of the binary

    Raises:
        AssertionError: If the source binary is not found
    """
    bin_path = Bin.get_bin_path(binary)
    if not os.path.isfile(bin_path):
        assert os.path.isfile(path), f"Binary not found: {path}"
        logger.info(f"Linking {path} to {bin_path}")
        os.symlink(path, bin_path)

get_bin_dir() staticmethod

Get the binary directory path.

Returns:

Type Description
str

The canonical path to the binary directory

Raises:

Type Description
RuntimeError

If Main.init() hasn't been called
Source code in pykmhelpers/core/utils.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@staticmethod
def get_bin_dir() -> str:
    """
    Get the binary directory path.

    Returns:
        The canonical path to the binary directory

    Raises:
        RuntimeError: If Main.init() hasn't been called
    """
    if "KMHELPERS_BIN_PATH" not in os.environ:
        raise RuntimeError(
            "Main.init() must be called at program startup before using get_bin_dir()"
        )
    return Toolbox.get_canonical_path(os.environ["KMHELPERS_BIN_PATH"])

get_bin_path(binary) staticmethod

Get the full path to a binary executable.

Parameters:

Name Type Description Default
binary str

Name of the binary

 required

Returns:

Type Description
str

Full path to the binary
Source code in pykmhelpers/core/utils.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
@staticmethod
def get_bin_path(binary: str) -> str:
    """
    Get the full path to a binary executable.

    Args:
        binary: Name of the binary

    Returns:
        Full path to the binary
    """
    return os.path.join(Bin.get_bin_dir(), binary)

add_bin_dir_to_syspath() staticmethod

Add the binary directory to the system PATH.

Source code in pykmhelpers/core/utils.py 
105
106
107
108
109
110
@staticmethod
def add_bin_dir_to_syspath() -> None:
    """Add the binary directory to the system PATH."""
    os.environ["PATH"] = (
        f"{Bin.get_bin_dir()}{os.pathsep}{os.environ.get('PATH', '')}"
    )

kmindex() staticmethod

Get the kmindex binary name.

Source code in pykmhelpers/core/utils.py 
113
114
115
116
@staticmethod
def kmindex() -> str:
    """Get the kmindex binary name."""
    return "kmindex"

check_bin(binary_name) staticmethod

Check if a binary exists in PATH and print a warning if not found.

Parameters:

Name Type Description Default
binary_name str

Name of the binary to check

 required
Source code in pykmhelpers/core/utils.py 
119
120
121
122
123
124
125
126
127
128
@staticmethod
def check_bin(binary_name: str) -> None:
    """
    Check if a binary exists in PATH and print a warning if not found.

    Args:
        binary_name: Name of the binary to check
    """
    if not shutil.which(binary_name):
        logger.warning(f"{binary_name} command not found in PATH")

check_kmindex() staticmethod

Check if kmindex is available with helpful error message.

Raises:

Type Description
RuntimeError

If kmindex >= 0.5.3 is not found in PATH
Source code in pykmhelpers/core/utils.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
@staticmethod
def check_kmindex() -> None:
    """
    Check if kmindex is available with helpful error message.

    Raises:
        RuntimeError: If kmindex >= 0.5.3 is not found in PATH
    """
    kmindex_path = shutil.which(Bin.kmindex())
    if not kmindex_path:
        raise RuntimeError(
            f"kmindex >= 0.5.3 is required but not found in PATH.\n"
            f"\n"
            f"Install via bioconda:\n"
            f"  conda install -c bioconda kmindex>=0.5.3\n"
            f"\n"
            f"Or compile from source and add to PATH:\n"
            f"  export PATH=/path/to/kmindex/build:$PATH\n"
            f"\n"
            f"Verify installation:\n"
            f"  kmindex --version"
        )

check_all() staticmethod

Check all required binaries are available in PATH.

Source code in pykmhelpers/core/utils.py 
155
156
157
158
159
160
161
162
163
@staticmethod
def check_all() -> None:
    """Check all required binaries are available in PATH."""
    binaries = [
        Bin.kmindex(),
    ]

    for binary in binaries:
        Bin.check_bin(binary)

Toolbox

Utility class for common operations.

Source code in pykmhelpers/core/utils.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
class Toolbox:
    """Utility class for common operations."""

    ####################################################
    @staticmethod
    def get_size(filename: str) -> int:
        return os.stat(filename).st_size

    ####################################################
    @staticmethod
    def get_canonical_path(path: str) -> str:
        """
        Get the canonical absolute path of a given path.

        Args:
            path (str): The input path to resolve.

        Returns:
            str: The canonical absolute path.
        """
        return os.path.realpath(os.path.expanduser(path))

    ####################################################
    @staticmethod
    def get_basename(path: str) -> str:
        """
        Get the base name of a given path.

        Args:
            path (str): The input path.

        Returns:
            str: The base name of the path.
        """
        return os.path.basename(Toolbox.get_canonical_path(path))

get_canonical_path(path) staticmethod

Get the canonical absolute path of a given path.

Parameters:

Name Type Description Default
path str

The input path to resolve.

 required

Returns:

Name Type Description
str str

The canonical absolute path.
Source code in pykmhelpers/core/utils.py 
179
180
181
182
183
184
185
186
187
188
189
190
@staticmethod
def get_canonical_path(path: str) -> str:
    """
    Get the canonical absolute path of a given path.

    Args:
        path (str): The input path to resolve.

    Returns:
        str: The canonical absolute path.
    """
    return os.path.realpath(os.path.expanduser(path))

get_basename(path) staticmethod

Get the base name of a given path.

Parameters:

Name Type Description Default
path str

The input path.

 required

Returns:

Name Type Description
str str

The base name of the path.
Source code in pykmhelpers/core/utils.py 
193
194
195
196
197
198
199
200
201
202
203
204
@staticmethod
def get_basename(path: str) -> str:
    """
    Get the base name of a given path.

    Args:
        path (str): The input path.

    Returns:
        str: The base name of the path.
    """
    return os.path.basename(Toolbox.get_canonical_path(path))