API documentation

conf_path(create_if_missing=False)

Returns the path found for the pg_service.conf on the system as string.

Parameters:

Name	Type	Description	Default
create_if_missing	Optional[bool]	Whether to create the file (and eventually its parent folders) if the file does not exist.	False

Returns:

Type	Description
Path	path to the pg_service.conf file as string

Source code in pgserviceparser/__init__.py

def conf_path(create_if_missing: Optional[bool] = False) -> Path:
    """Returns the path found for the pg_service.conf on the system as string.

    Args:
        create_if_missing: Whether to create the file (and eventually its parent folders) if the file does not exist.

    Returns:
        path to the pg_service.conf file as string
    """
    pg_config_path = None
    if getenv("PGSERVICEFILE"):
        pg_config_path = Path(getenv("PGSERVICEFILE"))
    elif getenv("PGSYSCONFDIR"):
        pg_config_path = Path(getenv("PGSYSCONFDIR")) / "pg_service.conf"
    else:
        if platform.system() == "Windows":
            pg_config_path = Path(getenv("APPDATA")) / "postgresql/.pg_service.conf"
        else:  # Linux or Darwin (Mac)
            pg_config_path = Path("~/.pg_service.conf").expanduser()

    if create_if_missing and not pg_config_path.exists():
        # Make sure all parent directories exist
        if not pg_config_path.parent.exists():
            pg_config_path.parent.mkdir(parents=True, exist_ok=True)

        # Finally, make sure the file itself exists
        Path.touch(pg_config_path)

    return pg_config_path

full_config(conf_file_path=None)

Returns full pgservice config as configparser.ConfigParser().

Parameters:

Name	Type	Description	Default
conf_file_path	Optional[Path]	path to configuration file to load. If None the conf_path is used, defaults to None	None

Returns:

Type	Description
ConfigParser	pg services loaded as ConfigParser

Raises:

Type	Description
ServiceFileNotFound	when the service file is not found

Source code in pgserviceparser/__init__.py

def full_config(conf_file_path: Optional[Path] = None) -> configparser.ConfigParser:
    """Returns full pgservice config as configparser.ConfigParser().

    Args:
        conf_file_path: path to configuration file to load. If None the `conf_path` is used, defaults to None

    Returns:
        pg services loaded as ConfigParser

    Raises:
        ServiceFileNotFound: when the service file is not found
    """
    if conf_file_path is None:
        conf_file_path = conf_path()
    else:
        conf_file_path = Path(conf_file_path)

    if not conf_file_path.exists():
        raise ServiceFileNotFound(pg_service_filepath=conf_file_path)

    config = configparser.ConfigParser()
    config.read(conf_file_path)
    return config

remove_service(service_name, conf_file_path=None)

Remove a complete service from the service file.

Parameters:

Name	Type	Description	Default
service_name	str	service name	required
conf_file_path	Optional[Path]	path to the pg_service.conf. If None the conf_path() is used, defaults to None	None

Raises:

Type	Description
ServiceFileNotFound	when the service file is not found
ServiceNotFound	when the service is not found

Source code in pgserviceparser/__init__.py

def remove_service(service_name: str, conf_file_path: Optional[Path] = None) -> None:
    """Remove a complete service from the service file.

    Args:
        service_name: service name
        conf_file_path: path to the pg_service.conf. If None the `conf_path()` is used,
            defaults to None

    Raises:
        ServiceFileNotFound: when the service file is not found
        ServiceNotFound: when the service is not found
    """
    config = full_config(conf_file_path)
    if service_name not in config:
        raise ServiceNotFound(
            service_name=service_name,
            existing_service_names=service_names(),
            pg_service_filepath=conf_file_path or conf_path(),
        )

    config.remove_section(service_name)
    with open(conf_file_path or conf_path(), "w") as configfile:
        config.write(configfile, space_around_delimiters=False)

service_config(service_name, conf_file_path=None)

Returns the config from the given service name as a dict.

Parameters:

Name	Type	Description	Default
service_name	str	service name	required
conf_file_path	Optional[Path]	path to the pg_service.conf. If None the conf_path is used, defaults to None	None

Returns:

Type	Description
dict	service settings as dictionary

Raises:

Type	Description
ServiceNotFound	when the service is not found

Source code in pgserviceparser/__init__.py

def service_config(service_name: str, conf_file_path: Optional[Path] = None) -> dict:
    """Returns the config from the given service name as a dict.

    Args:
        service_name: service name
        conf_file_path: path to the pg_service.conf. If None the `conf_path` is used, defaults to None

    Returns:
        service settings as dictionary

    Raises:
        ServiceNotFound: when the service is not found
    """
    config = full_config(conf_file_path)

    if service_name not in config:
        raise ServiceNotFound(
            service_name=service_name,
            existing_service_names=service_names(),
            pg_service_filepath=conf_file_path or conf_path(),
        )

    return dict(config[service_name])

service_names(conf_file_path=None)

Returns all service names in a list.

Parameters:

Name	Type	Description	Default
conf_file_path	Optional[Path]	path to the pg_service.conf. If None the conf_path() is used, defaults to None	None

Returns:

Type	Description
list[str]	list of every service registered

Raises:

Type	Description
ServiceFileNotFound	when the service file is not found

Source code in pgserviceparser/__init__.py

def service_names(conf_file_path: Optional[Path] = None) -> list[str]:
    """Returns all service names in a list.

    Args:
        conf_file_path: path to the pg_service.conf. If None the `conf_path()` is used, defaults to None

    Returns:
        list of every service registered

    Raises:
        ServiceFileNotFound: when the service file is not found
    """

    config = full_config(conf_file_path)
    return config.sections()

write_service(service_name, settings, conf_file_path=None, create_if_not_found=False)

Writes a complete service to the service file.

Parameters:

Name	Type	Description	Default
service_name	str	service name	required
settings	dict	settings dict defining the service config	required
conf_file_path	Optional[Path]	path to the pg_service.conf. If None the conf_path() is used, defaults to None	None
create_if_not_found	bool	option to create a new service if it does not exist yet. Defaults to False.	False

Raises:

Type	Description
ServiceFileNotFound	when the service file is not found
ServiceNotFound	when the service is not found

Returns:

Type	Description
dict	existing or newly created service as dictionary

Source code in pgserviceparser/__init__.py

def write_service(
    service_name: str, settings: dict, conf_file_path: Optional[Path] = None, create_if_not_found: bool = False
) -> dict:
    """Writes a complete service to the service file.

    Args:
        service_name: service name
        settings: settings dict defining the service config
        conf_file_path: path to the pg_service.conf. If None the `conf_path()` is used,
            defaults to None
        create_if_not_found: option to create a new service if it does not exist yet.
            Defaults to False.

    Raises:
        ServiceFileNotFound: when the service file is not found
        ServiceNotFound: when the service is not found

    Returns:
        existing or newly created service as dictionary
    """
    config = full_config(conf_file_path)
    if service_name not in config and not create_if_not_found:
        raise ServiceNotFound(
            service_name=service_name,
            existing_service_names=service_names(),
            pg_service_filepath=conf_file_path or conf_path(),
        )

    config[service_name] = settings.copy()
    with open(conf_file_path or conf_path(), "w") as configfile:
        config.write(configfile, space_around_delimiters=False)

    return dict(config[service_name])

write_service_setting(service_name, setting_key, setting_value, conf_file_path=None)

Writes a service setting to the service file.

Parameters:

Name	Type	Description	Default
service_name	str	service name	required
setting_key	str	key	required
setting_value	str	value	required
conf_file_path	Optional[Path]	path to the pg_service.conf. If None the conf_path() is used, defaults to None	None

Raises:

Type	Description
ServiceFileNotFound	when the service file is not found
ServiceNotFound	when the service is not found

Source code in pgserviceparser/__init__.py

def write_service_setting(
    service_name: str,
    setting_key: str,
    setting_value: str,
    conf_file_path: Optional[Path] = None,
):
    """Writes a service setting to the service file.

    Args:
        service_name: service name
        setting_key: key
        setting_value: value
        conf_file_path: path to the pg_service.conf. If None the `conf_path()` is used, defaults to None

    Raises:
        ServiceFileNotFound: when the service file is not found
        ServiceNotFound: when the service is not found
    """

    config = full_config(conf_file_path)
    if service_name not in config:
        raise ServiceNotFound(
            service_name=service_name,
            existing_service_names=service_names(),
            pg_service_filepath=conf_file_path or conf_path(),
        )

    config[service_name][setting_key] = setting_value
    with open(conf_file_path or conf_path(), "w") as configfile:
        config.write(configfile, space_around_delimiters=False)