Skip to content

API documentation

conf_path()

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

Returns:

Type Description
Path

path to the pg_service.conf file as string
Source code in pgserviceparser/__init__.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def conf_path() -> Path:
    """Returns the path found for the pg_service.conf on the system as string.

    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()

    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 
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
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 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
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 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
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 
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
164
165
166
167
168
169
170
171
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 
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
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)