testgres.postgres-configuration 0.4.0__tar.gz → 0.5.0__tar.gz

testgres_postgres_configuration-0.5.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: testgres.postgres_configuration
+Version: 0.5.0
+Summary: PostgreSQL Configuration Python Library
+Author-email: Postgres Professional <testgres@postgrespro.ru>
+License: PostgreSQL
+Project-URL: HomePage, https://github.com/postgrespro/testgres.pg_conf
+Keywords: postgresql,postgres,test
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.7.3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: testgres.common<2.0.0,>=1.0.3
+Dynamic: license-file
+
+[![CI Status](https://img.shields.io/github/actions/workflow/status/postgrespro/testgres.pg_conf/.github/workflows/ci.yml?label=CI)](https://github.com/postgrespro/testgres.pg_conf/actions/workflows/ci.yml)
+[![PyPI package version](https://badge.fury.io/py/testgres_postgres-configuration.svg)](https://badge.fury.io/py/testgres.postgres-configuration)
+[![PyPI python versions](https://img.shields.io/pypi/pyversions/testgres_postgres_configuration)](https://pypi.org/project/testgres.postgres-configuration)
+
+# testgres.postgres_configration
+
+A robust, enterprise-grade Python library designed for parsing, manipulating, and writing PostgreSQL configuration files. This library functions as a modular component of the `testgres` ecosystem.
+
+## What is it?
+
+`testgres.postgres_configration` provides a comprehensive object-oriented interface to manage complex, multi-file PostgreSQL configurations (such as `postgresql.conf` and `postgresql.auto.conf`). It allows developers and QA engineers to programmatically inspect, modify, and save database settings within isolation layers, making it ideal for automated testing infrastructure and database orchestration.
+
+## Key Features
+
+* **Multi-File & Include Directive Support:** Seamlessly loads, traverses, and writes deeply nested configuration structures utilizing `include`, `include_if_exists`, and `include_dir` directives.
+* **Preservation of Comments and Formatting:** Built using a dedicated layout tracking engine that preserves human-written inline comments, block comments, blank lines, and file indentation patterns upon serialization.
+* **Advanced List-Option Manipulation:** Provides high-level APIs like `SetOptionValueItem` to append items to comma-separated parameters (e.g., `shared_preload_libraries`) uniquely, eliminating string-concatenation errors.
+* **Flexible Validation Strategies (`Strict` vs `Standard`):** 
+  * `Standard` mode mimics real-world PostgreSQL behavior where parameter overrides and duplicates are allowed ("last definition wins").
+  * `Strict` mode enforces single-definition invariants, throwing structured errors when accidental duplicates are detected.
+* **Fail-Safe Lifecycle Verification:** Leverages internal `IsAlive` state validation mechanics to safeguard against modifying zombie reference nodes or processing out-of-sync cache handles.
+* **Native `TestgresException` Integration:** Features a fully typed, strict hierarchy of operational errors and fatal bug checks derived directly from the core `testgres` exception package.
+
+## Installation
+
+Install the library using `pip`:
+
+```bash
+pip install testgres.postgres-configuration
+```
+
+## Quick Start Example
+
+The following complete end-to-end example demonstrates how to initialize a temporary cluster via `testgres`, load its configuration, modify scalar and list properties, and verify changes natively using SQL statements.
+
+```python
+import testgres
+import testgres.postgres_configuration as testgres_pg_conf
+
+# 1. Initialize a standard temporary PostgreSQL node using testgres
+node = testgres.PostgresNode()
+node.init()
+
+# 2. Attach our configuration manager to the node's data directory (PGDATA)
+cfg = testgres_pg_conf.PostgresConfiguration(node.data_dir)
+
+# Load existing configuration files (postgresql.conf, etc.) from disk
+testgres_pg_conf.PostgresConfigurationReader.LoadConfiguration(cfg)
+
+# ----------------------------------------------------------------------
+# Setup Initial State for List Demonstration
+# ----------------------------------------------------------------------
+# Let's explicitly define a base preloaded library first
+cfg.SetOptionValue("shared_preload_libraries", "auto_explain")
+
+# ----------------------------------------------------------------------
+# Demonstration of GetOptionValue (Reading Current Values)
+# ----------------------------------------------------------------------
+# Read the current port configuration. It retrieves the effective value
+# from the configuration tree (handling overrides if multiple exist).
+current_port = cfg.GetOptionValue("port")
+print(f"Initial PostgreSQL port: {current_port}")
+
+# ----------------------------------------------------------------------
+# Demonstration of SetOptionValue (Scalar Options)
+# ----------------------------------------------------------------------
+# Change the maximum number of concurrent connections from default 100 to 15.
+# In 'Standard' mode, this creates or updates the postgresql.auto.conf file.
+cfg.SetOptionValue("max_connections", 15)
+
+# ----------------------------------------------------------------------
+# Demonstration of SetOptionValueItem (List/Array Options - Appending)
+# ----------------------------------------------------------------------
+# Unique append: instead of replacing 'auto_explain', this method appends
+# 'pg_stat_statements' into the existing list parameter.
+cfg.SetOptionValueItem("shared_preload_libraries", "pg_stat_statements")
+
+# ----------------------------------------------------------------------
+# Save and Apply Changes
+# ----------------------------------------------------------------------
+# Flush all modified in-memory configuration trees back to the file system
+testgres_pg_conf.PostgresConfigurationWriter.WriteConfiguration(cfg)
+
+# 3. Start the PostgreSQL server to let it pick up the new configuration
+node.start()
+
+# 4. Verify modified options via standard SQL queries
+# Verify max_connections changes
+res_conn = node.execute("SELECT setting FROM pg_settings WHERE name = 'max_connections';")
+print(f"Configured max_connections: {res_conn}")  # Output: 15
+
+# Verify preloaded libraries using native SHOW command.
+# Output will prove that 'pg_stat_statements' was safely appended to 'auto_explain'.
+res_libs = node.execute("SHOW shared_preload_libraries;")
+print(f"Preloaded libraries: {res_libs}")  # Expected output: auto_explain,pg_stat_statements
+
+# 5. Stop the process and clean up temporary node directories
+node.cleanup()
+```
+Output:
+```
+Initial PostgreSQL port: 53916
+Configured max_connections: 15
+Preloaded libraries: auto_explain,pg_stat_statements
+```
+
+
+## Authors
+
+[Postgres Professional](https://postgrespro.ru/about)

testgres_postgres_configuration-0.5.0/README.md

@@ -0,0 +1,110 @@
+[![CI Status](https://img.shields.io/github/actions/workflow/status/postgrespro/testgres.pg_conf/.github/workflows/ci.yml?label=CI)](https://github.com/postgrespro/testgres.pg_conf/actions/workflows/ci.yml)
+[![PyPI package version](https://badge.fury.io/py/testgres_postgres-configuration.svg)](https://badge.fury.io/py/testgres.postgres-configuration)
+[![PyPI python versions](https://img.shields.io/pypi/pyversions/testgres_postgres_configuration)](https://pypi.org/project/testgres.postgres-configuration)
+
+# testgres.postgres_configration
+
+A robust, enterprise-grade Python library designed for parsing, manipulating, and writing PostgreSQL configuration files. This library functions as a modular component of the `testgres` ecosystem.
+
+## What is it?
+
+`testgres.postgres_configration` provides a comprehensive object-oriented interface to manage complex, multi-file PostgreSQL configurations (such as `postgresql.conf` and `postgresql.auto.conf`). It allows developers and QA engineers to programmatically inspect, modify, and save database settings within isolation layers, making it ideal for automated testing infrastructure and database orchestration.
+
+## Key Features
+
+* **Multi-File & Include Directive Support:** Seamlessly loads, traverses, and writes deeply nested configuration structures utilizing `include`, `include_if_exists`, and `include_dir` directives.
+* **Preservation of Comments and Formatting:** Built using a dedicated layout tracking engine that preserves human-written inline comments, block comments, blank lines, and file indentation patterns upon serialization.
+* **Advanced List-Option Manipulation:** Provides high-level APIs like `SetOptionValueItem` to append items to comma-separated parameters (e.g., `shared_preload_libraries`) uniquely, eliminating string-concatenation errors.
+* **Flexible Validation Strategies (`Strict` vs `Standard`):** 
+  * `Standard` mode mimics real-world PostgreSQL behavior where parameter overrides and duplicates are allowed ("last definition wins").
+  * `Strict` mode enforces single-definition invariants, throwing structured errors when accidental duplicates are detected.
+* **Fail-Safe Lifecycle Verification:** Leverages internal `IsAlive` state validation mechanics to safeguard against modifying zombie reference nodes or processing out-of-sync cache handles.
+* **Native `TestgresException` Integration:** Features a fully typed, strict hierarchy of operational errors and fatal bug checks derived directly from the core `testgres` exception package.
+
+## Installation
+
+Install the library using `pip`:
+
+```bash
+pip install testgres.postgres-configuration
+```
+
+## Quick Start Example
+
+The following complete end-to-end example demonstrates how to initialize a temporary cluster via `testgres`, load its configuration, modify scalar and list properties, and verify changes natively using SQL statements.
+
+```python
+import testgres
+import testgres.postgres_configuration as testgres_pg_conf
+
+# 1. Initialize a standard temporary PostgreSQL node using testgres
+node = testgres.PostgresNode()
+node.init()
+
+# 2. Attach our configuration manager to the node's data directory (PGDATA)
+cfg = testgres_pg_conf.PostgresConfiguration(node.data_dir)
+
+# Load existing configuration files (postgresql.conf, etc.) from disk
+testgres_pg_conf.PostgresConfigurationReader.LoadConfiguration(cfg)
+
+# ----------------------------------------------------------------------
+# Setup Initial State for List Demonstration
+# ----------------------------------------------------------------------
+# Let's explicitly define a base preloaded library first
+cfg.SetOptionValue("shared_preload_libraries", "auto_explain")
+
+# ----------------------------------------------------------------------
+# Demonstration of GetOptionValue (Reading Current Values)
+# ----------------------------------------------------------------------
+# Read the current port configuration. It retrieves the effective value
+# from the configuration tree (handling overrides if multiple exist).
+current_port = cfg.GetOptionValue("port")
+print(f"Initial PostgreSQL port: {current_port}")
+
+# ----------------------------------------------------------------------
+# Demonstration of SetOptionValue (Scalar Options)
+# ----------------------------------------------------------------------
+# Change the maximum number of concurrent connections from default 100 to 15.
+# In 'Standard' mode, this creates or updates the postgresql.auto.conf file.
+cfg.SetOptionValue("max_connections", 15)
+
+# ----------------------------------------------------------------------
+# Demonstration of SetOptionValueItem (List/Array Options - Appending)
+# ----------------------------------------------------------------------
+# Unique append: instead of replacing 'auto_explain', this method appends
+# 'pg_stat_statements' into the existing list parameter.
+cfg.SetOptionValueItem("shared_preload_libraries", "pg_stat_statements")
+
+# ----------------------------------------------------------------------
+# Save and Apply Changes
+# ----------------------------------------------------------------------
+# Flush all modified in-memory configuration trees back to the file system
+testgres_pg_conf.PostgresConfigurationWriter.WriteConfiguration(cfg)
+
+# 3. Start the PostgreSQL server to let it pick up the new configuration
+node.start()
+
+# 4. Verify modified options via standard SQL queries
+# Verify max_connections changes
+res_conn = node.execute("SELECT setting FROM pg_settings WHERE name = 'max_connections';")
+print(f"Configured max_connections: {res_conn}")  # Output: 15
+
+# Verify preloaded libraries using native SHOW command.
+# Output will prove that 'pg_stat_statements' was safely appended to 'auto_explain'.
+res_libs = node.execute("SHOW shared_preload_libraries;")
+print(f"Preloaded libraries: {res_libs}")  # Expected output: auto_explain,pg_stat_statements
+
+# 5. Stop the process and clean up temporary node directories
+node.cleanup()
+```
+Output:
+```
+Initial PostgreSQL port: 53916
+Configured max_connections: 15
+Preloaded libraries: auto_explain,pg_stat_statements
+```
+
+
+## Authors
+
+[Postgres Professional](https://postgrespro.ru/about)

{testgres_postgres_configuration-0.4.0 → testgres_postgres_configuration-0.5.0}/pyproject.toml

@@ -19,7 +19,7 @@ log_file_date_format = "%Y-%m-%d %H:%M:%S"
 
 [project]
 name = "testgres.postgres_configuration"
-version = "0.4.0"
+version = "0.5.0"
 
 description = "PostgreSQL Configuration Python Library"
 readme = "README.md"
@@ -57,6 +57,7 @@ classifiers = [
 ]
 
 dependencies = [
+    "testgres.common>=1.0.3,<2.0.0",
 ]
 
 [project.urls]

{testgres_postgres_configuration-0.4.0 → testgres_postgres_configuration-0.5.0}/src/abstract/v00/configuration.py

@@ -102,12 +102,16 @@ class PostgresConfigurationOption(PostgresConfigurationElement):
         RaiseError.MethodIsNotImplemented(__class__, "get_Value")
 
     # --------------------------------------------------------------------
-    def set_Value(self, value: typing.Any) -> PostgresConfigurationSetOptionValueResult:
+    def set_Value(
+        self,
+        value: typing.Any,
+    ) -> PostgresConfigurationSetOptionValueResult:
         RaiseError.MethodIsNotImplemented(__class__, "set_Value")
 
     # --------------------------------------------------------------------
     def set_ValueItem(
-        self, value_item: typing.Any
+        self,
+        value_item: typing.Any,
     ) -> PostgresConfigurationSetOptionValueResult:
         assert value_item is not None
         RaiseError.MethodIsNotImplemented(__class__, "set_ValueItem")
@@ -127,6 +131,7 @@ class PostgresConfigurationOptionsIterator(
     def __iter__(self) -> PostgresConfigurationOptionsIterator:
         RaiseError.MethodIsNotImplemented(__class__, "__iter__")
 
+    # --------------------------------------------------------------------
     def __next__(self) -> PostgresConfigurationOption:
         RaiseError.MethodIsNotImplemented(__class__, "__next__")
 
@@ -161,7 +166,10 @@ class PostgresConfigurationInclude(PostgresConfigurationElement):
         RaiseError.MethodIsNotImplemented(__class__, "get_File")
 
     # --------------------------------------------------------------------
-    def Delete(self, withLine: bool) -> None:
+    def Delete(
+        self,
+        withLine: bool,
+    ) -> None:
         assert type(withLine) is bool
         RaiseError.MethodIsNotImplemented(__class__, "Delete")
 
@@ -180,7 +188,9 @@ class PostgresConfigurationFileLine(PostgresConfigurationObject):
 
     # --------------------------------------------------------------------
     def AddComment(
-        self, text: str, offset: typing.Optional[int]
+        self,
+        text: str,
+        offset: typing.Optional[int],
     ) -> PostgresConfigurationComment:
         assert type(text) is str
         assert (offset is None) or (type(offset) is int)
@@ -188,7 +198,10 @@ class PostgresConfigurationFileLine(PostgresConfigurationObject):
 
     # --------------------------------------------------------------------
     def AddOption(
-        self, name: str, value: typing.Any, offset: typing.Optional[int]
+        self,
+        name: str,
+        value: typing.Any,
+        offset: typing.Optional[int],
     ) -> PostgresConfigurationOption:
         assert type(name) is str
         assert name != ""
@@ -198,7 +211,9 @@ class PostgresConfigurationFileLine(PostgresConfigurationObject):
 
     # --------------------------------------------------------------------
     def AddInclude(
-        self, path: str, offset: typing.Optional[int]
+        self,
+        path: str,
+        offset: typing.Optional[int],
     ) -> PostgresConfigurationInclude:
         assert type(path) is str
         assert path != ""
@@ -224,6 +239,7 @@ class PostgresConfigurationFileLinesIterator(
     def __iter__(self) -> PostgresConfigurationFileLinesIterator:
         RaiseError.MethodIsNotImplemented(__class__, "__iter__")
 
+    # --------------------------------------------------------------------
     def __next__(self) -> PostgresConfigurationFileLine:
         RaiseError.MethodIsNotImplemented(__class__, "__next__")
 
@@ -270,19 +286,29 @@ class PostgresConfigurationFile(PostgresConfigurationObject):
         RaiseError.MethodIsNotImplemented(__class__, "AddEmptyLine")
 
     # --------------------------------------------------------------------
-    def AddComment(self, text: str) -> PostgresConfigurationComment:
+    def AddComment(
+        self,
+        text: str,
+    ) -> PostgresConfigurationComment:
         assert type(text) is str
         RaiseError.MethodIsNotImplemented(__class__, "AddComment")
 
     # --------------------------------------------------------------------
-    def AddOption(self, name: str, value: typing.Any) -> PostgresConfigurationOption:
+    def AddOption(
+        self,
+        name: str,
+        value: typing.Any,
+    ) -> PostgresConfigurationOption:
         assert type(name) is str
         assert name != ""
         assert value is not None
         RaiseError.MethodIsNotImplemented(__class__, "AddOption")
 
     # --------------------------------------------------------------------
-    def AddInclude(self, path: str) -> PostgresConfigurationInclude:
+    def AddInclude(
+        self,
+        path: str,
+    ) -> PostgresConfigurationInclude:
         assert type(path) is str
         assert path != ""
         RaiseError.MethodIsNotImplemented(__class__, "AddInclude")
@@ -299,7 +325,9 @@ class PostgresConfigurationFile(PostgresConfigurationObject):
     #  PostgresConfigurationSetOptionValueResult object.
     #
     def SetOptionValue(
-        self, name: str, value: typing.Any
+        self,
+        name: str,
+        value: typing.Any,
     ) -> PostgresConfigurationSetOptionValueResult:
         assert type(name) is str
         assert name != ""
@@ -313,13 +341,18 @@ class PostgresConfigurationFile(PostgresConfigurationObject):
     #  - Value of option.
     #  - None if option is not found in this file.
     #
-    def GetOptionValue(self, name: str) -> typing.Any:
+    def GetOptionValue(
+        self,
+        name: str,
+    ) -> typing.Any:
         assert type(name) is str
         RaiseError.MethodIsNotImplemented(__class__, "GetOptionValue")
 
     # --------------------------------------------------------------------
     def SetOptionValueItem(
-        self, name: str, value_item: typing.Any
+        self,
+        name: str,
+        value_item: typing.Any,
     ) -> PostgresConfigurationSetOptionValueResult:
         assert type(name) is str
         assert name != ""
@@ -339,6 +372,7 @@ class PostgresConfigurationFilesIterator(typing.Iterator[PostgresConfigurationFi
     def __iter__(self) -> PostgresConfigurationFilesIterator:
         RaiseError.MethodIsNotImplemented(__class__, "__iter__")
 
+    # --------------------------------------------------------------------
     def __next__(self) -> PostgresConfigurationFile:
         RaiseError.MethodIsNotImplemented(__class__, "__next__")
 
@@ -360,7 +394,10 @@ class PostgresConfigurationFiles(typing.Iterable[PostgresConfigurationFile]):
         RaiseError.MethodIsNotImplemented(__class__, "__iter__")
 
     # --------------------------------------------------------------------
-    def GetFileByName(self, file_name: str) -> PostgresConfigurationFile:
+    def GetFileByName(
+        self,
+        file_name: str,
+    ) -> PostgresConfigurationFile:
         assert file_name is not None
         RaiseError.MethodIsNotImplemented(__class__, "GetFileByName")
 
@@ -374,13 +411,20 @@ class PostgresConfiguration(PostgresConfigurationObject):
         pass
 
     # interface ----------------------------------------------------------
-    def AddTopLevelFile(self, path: str) -> PostgresConfigurationFile:
+    def AddTopLevelFile(
+        self,
+        path: str,
+    ) -> PostgresConfigurationFile:
         assert type(path) is str
         assert path != ""
         RaiseError.MethodIsNotImplemented(__class__, "AddTopLevelFile")
 
     # --------------------------------------------------------------------
-    def AddOption(self, name: str, value: typing.Any) -> PostgresConfigurationOption:
+    def AddOption(
+        self,
+        name: str,
+        value: typing.Any,
+    ) -> PostgresConfigurationOption:
         assert type(name) is str
         assert name != ""
         assert value is not None
@@ -398,7 +442,9 @@ class PostgresConfiguration(PostgresConfigurationObject):
     #  PostgresConfigurationSetOptionValueResult object.
     #
     def SetOptionValue(
-        self, name: str, value: typing.Any
+        self,
+        name: str,
+        value: typing.Any,
     ) -> PostgresConfigurationSetOptionValueResult:
         assert type(name) is str
         RaiseError.MethodIsNotImplemented(__class__, "SetOptionValue")
@@ -411,13 +457,18 @@ class PostgresConfiguration(PostgresConfigurationObject):
     #  - Value of option.
     #  - None if option is not found.
     #
-    def GetOptionValue(self, name: str) -> typing.Any:
+    def GetOptionValue(
+        self,
+        name: str,
+    ) -> typing.Any:
         assert type(name) is str
         RaiseError.MethodIsNotImplemented(__class__, "GetOptionValue")
 
     # --------------------------------------------------------------------
     def SetOptionValueItem(
-        self, name: str, value_item: typing.Any
+        self,
+        name: str,
+        value_item: typing.Any,
     ) -> PostgresConfigurationSetOptionValueResult:
         assert type(name) is str
         assert value_item is not None