Common Functions
Common functions and classes used by other classes in the sc_foundation 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_external_ip()
staticmethod
Query multiple external IP-echo services in turn to get the public IP address of the machine.
Returns:
| Type | Description |
|---|---|
str
|
The external IP address as a string. |
Raises:
| Type | Description |
|---|---|
RuntimeError
|
If all IP-echo services fail. |
get_geo_location(location_config=None, google_maps_url=None)
staticmethod
Get the geographical location based on the provided configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
location_config
|
dict | None
|
A dictionary containing location configuration. If None, defaults to an empty dictionary. |
None
|
google_maps_url
|
str | None
|
A Google Maps URL to extract the location from. If None, defaults to None. |
None
|
location_config is the YAML Location configuration dictionary. It can conatin the following keys (examples shown): - Latitude: 51.4993124 - Longitude: -0.1353157 - GoogleMapsURL: https://www.google.com/maps/place/Buckingham+Palace/@51.4993124,-0.1353157,14.92z
The returned dictionary will contain the following keys
- method: The method used to determine the location (e.g., "config", "google_maps_url").
- latitude: The latitude of the location.
- longitude: The longitude of the location.
- timezone: The timezone of the location (if available).
- city, state and country if available from a lookup on openstreetmap.org.
If location_config contains a lat/long pair, this will be used directly. If it contains a Google Maps URL, the lat/long will be extracted from the URL. If neither is provided, the function will attempt to determine the location using other means (e.g., IP-based geolocation).
Returns:
| Type | Description |
|---|---|
dict
|
A dictionary containing the geographical location information. |
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_FOUNDATION_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 foundation 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. |