Common Functions
Common utility functions and classes used by other classes in the sc_utility package.
check_hostname_and_type(target)
staticmethod
Return whether target is a valid IPv4, IPv6, or DNS hostname. Also returns the type.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
str
|
The target string to validate. |
required |
Returns:
| Type | Description |
|---|---|
tuple[bool, str | None]
|
A tuple containing a boolean indicating validity and a string indicating the type ('ipv4', 'ipv6', or 'hostname'). |
check_internet_connection(urls=None, timeout=3)
staticmethod
Check if the system has an active internet connection by trying to open a connection to common websites.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
urls
|
list
|
A list of URLs to check for internet connectivity. Defaults to common DNS servers and websites. |
None
|
timeout
|
int
|
The timeout in seconds for each request. |
3
|
Returns:
| Type | Description |
|---|---|
bool
|
True if the system is connected to the internet, False otherwise. |
get_os()
staticmethod
Return the name of the operating system.
Returns:
| Type | Description |
|---|---|
str
|
The name of the operating system in lowercase. |
get_process_id()
staticmethod
Return the process ID of the current process.
Returns:
| Type | Description |
|---|---|
int
|
The process ID of the current process. |
get_project_root(marker_files=('pyproject.toml', '.project_root', 'uv.lock', '.git'))
staticmethod
Return the root folder of the Python project.
By default, this function looks for marker files like pyproject.toml, .project_root, uv.lock, or .git to identify the project root. It starts from the directory of this file and walks upwards until it finds one of the marker files. If it cannot find any of the marker files, it raises a RuntimeError.
If the environment variable SC_UTILITY_PROJECT_ROOT is set, it will check if that path exists and is a directory, and return it as the project root if so. This allows users to override the automatic detection of the project root if needed (e.g., if they have an unusual project structure or want to use the utility in a different project without copying this file).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
marker_files
|
tuple
|
A tuple of file names that indicate the project root. |
('pyproject.toml', '.project_root', 'uv.lock', '.git')
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the project root cannot be found. |
Returns:
| Name | Type | Description |
|---|---|---|
root_dir |
Path
|
The root folder of the Python project as a Path object. |
is_probable_path(possible_path)
staticmethod
Check if the given string or Path object is likely to be a file path.
This method checks if the string is an absolute path, contains a path separator, or has a file extension.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
possible_path
|
str | Path
|
The string to check. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the string is likely a file path, False otherwise. |
is_valid_hostname(target)
staticmethod
Return whether target is a valid IPv4, IPv6, or DNS hostname.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
str
|
The target string to validate. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
A boolean indicating validity. |
ping_host(ip_address, timeout=1)
staticmethod
Pings an IP address and returns True if the host is responding, False otherwise.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ip_address
|
str
|
The IP address to ping. |
required |
timeout
|
int
|
Timeout in seconds for the ping response. Default is 1 second. |
1
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the IP address is invalid or the ping system call fails. |
Returns:
| Name | Type | Description |
|---|---|---|
result |
bool
|
True if the host responds, False otherwise. |
select_file_location(file_name, create_folder=False)
staticmethod
Select the file location for the given file name. It resolves an absolute path for the file_name as follows.
- If file_name is an absolute path, return it as a Path object.
- If file_name is a relative path (contains parent directories), return the absolute path based on the current working directory.
- If file_name is just a file name, look for it in the current working directory first, then in the root directory.
The root directly is defined as the directory containing the main script being executed (the module containing main).
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the project root cannot be determined. |
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_name
|
str
|
The name of the file to locate. Can be just a file name, or a relative or absolute path. |
required |
create_folder
|
bool
|
If True, create the parent folder if it does not exist. Default is False. |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
file_path |
Path
|
The full path to the file as a Path object. None if the file_name does not appear to be a path. |
select_folder_location(folder_path=None, create_folder=False)
staticmethod
Return an absolute folder path for the given (relative) folder path.
If folder_path is None, return the project root folder. If folder_path is an absolute path, return it as a Path object. If folder_path is a relative path, return the absolute path based on the project root directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
folder_path
|
str | None
|
The folder path to locate. Can be None, or a relative or absolute path. |
None
|
create_folder
|
bool
|
If True, create the folder if it does not exist. Default is False. |
False
|
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If the project root cannot be determined or if folder creation fails. |
Returns:
| Type | Description |
|---|---|
Path | None
|
The full path to the folder as a Path object. None if folder_path is None and project root cannot be determined. |