ga-configreader 0.1.3__tar.gz

ga_configreader-0.1.3/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-09-02
+
+- Prepared environment
+- Added complete project documentation in README and docs/ pages

ga_configreader-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Gemma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ga_configreader-0.1.3/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include CHANGELOG.md
+include README.md
+recursive-include docs *.md
+recursive-include src/configreader py.typed

ga_configreader-0.1.3/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: ga-configreader
+Version: 0.1.3
+Summary: Read configuration values from INI, DB, environment variables, and dictionaries
+Author-email: Andrea Gemma <andrea.gemma@uniroma3.it>
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/andreagemma/configreader#readme
+Project-URL: Issues, https://github.com/andreagemma/configreader/issues
+Project-URL: Source, https://github.com/andreagemma/configreader
+Keywords: configuration,ini,environment,sqlalchemy,settings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0; extra == "db"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# configreader
+
+Python library to read configuration values from multiple sources with configurable precedence.
+
+Supported sources:
+- INI file
+- SQL database through SQLAlchemy (optional)
+- environment variables
+- in-memory Python dictionary
+
+Values are resolved in order, and the first non-empty match is returned.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install ga-configreader
+```
+
+### From source
+
+```bash
+git clone https://github.com/andreagemma/configreader.git
+cd configreader
+pip install -e .
+```
+
+### Database support (optional)
+
+Install SQLAlchemy if you want to use the DB provider:
+
+```bash
+pip install sqlalchemy
+```
+
+Or install the project with DB extras:
+
+```bash
+pip install "configreader[db]"
+```
+
+## Quickstart
+
+```python
+from configreader import ConfigReader
+
+reader = ConfigReader(
+    file="config.ini",
+    use_env=True,
+    dictionary={"DEFAULT": {"timeout": "30"}},
+    providers=["env", "ini", "dict"],
+)
+
+host = reader.get("host", default="127.0.0.1")
+port = reader.getint("port", default=8080)
+debug = reader.getboolean("debug", default=False)
+```
+
+## Provider Precedence
+
+The providers list defines lookup order.
+
+Example:
+
+```python
+providers = ["env", "db", "ini", "dict"]
+```
+
+Meaning:
+1. check environment first
+2. then check database
+3. then check INI file
+4. then check dictionary
+
+## Environment Variables
+
+Naming rules:
+- if section="DEFAULT", variable name is NAME
+- for custom sections, variable name is SECTION_NAME
+
+Examples:
+- reader.get("host", section="DEFAULT") reads HOST
+- reader.get("host", section="app") reads APP_HOST
+
+## Using INI Files
+
+Example config.ini:
+
+```ini
+[DEFAULT]
+host = localhost
+port = 5432
+debug = true
+items = [1, 2, 3]
+
+[app]
+workers = 4
+```
+
+Code:
+
+```python
+reader = ConfigReader(file="config.ini")
+
+host = reader.get("host")
+port = reader.getint("port")
+debug = reader.getboolean("debug")
+items = reader.getlist("items")
+workers = reader.getint("workers", section="app")
+```
+
+## Using a Dictionary
+
+```python
+reader = ConfigReader(
+    dictionary={
+        "DEFAULT": {
+            "host": "localhost",
+            "allowed": "['admin', 'user']",
+        },
+        "service": {
+            "retries": "3",
+        },
+    },
+    providers=["dict"],
+)
+
+allowed = reader.getlist("allowed")
+retries = reader.getint("retries", section="service")
+```
+
+## Using a Database
+
+Constructor:
+
+```python
+reader = ConfigReader(
+    db_url="sqlite:///settings.db",
+    db_query="SELECT value FROM settings WHERE section = :section AND name = :name",
+    providers=["db", "env"],
+)
+```
+
+Default query shape:
+
+```sql
+SELECT value FROM settings WHERE section = :section AND name = :name
+```
+
+DB utility methods:
+
+```python
+ok = ConfigReader.check_db_connection("sqlite:///settings.db")
+exists = ConfigReader.check_db_exists("sqlite:///settings.db", table_name="settings")
+```
+
+## Main API
+
+- `get(name, default=None, section="DEFAULT") -> str | None`
+- `getint(name, default=None, section="DEFAULT") -> int | None`
+- `getboolean(name, default=None, section="DEFAULT") -> bool | None`
+- `getfloat(name, default=None, section="DEFAULT") -> float | None`
+- `getlist(name, default=None, section="DEFAULT") -> list[Any] | None`
+- `getset(name, default=None, section="DEFAULT") -> set[Any] | None`
+- `gettuple(name, default=None, section="DEFAULT") -> tuple[Any, ...] | None`
+- `getdict(name, default=None, section="DEFAULT") -> dict[Any, Any] | None`
+- `items()` iterator over loaded INI entries
+
+Full details in [docs/api.md](docs/api.md).
+
+## Errors And Type Conversion
+
+- `FileNotFoundError` is raised if the provided INI file does not exist.
+- Typed getters (`getint`, `getfloat`, `getlist`, etc.) propagate parsing/conversion errors.
+- If SQLAlchemy is not installed, DB features are unavailable.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e .[dev]
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+## More Documentation
+
+- [docs/overview.md](docs/overview.md)
+- [docs/providers.md](docs/providers.md)
+- [docs/api.md](docs/api.md)
+- [docs/examples.md](docs/examples.md)
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE).

ga_configreader-0.1.3/README.md

@@ -0,0 +1,201 @@
+# configreader
+
+Python library to read configuration values from multiple sources with configurable precedence.
+
+Supported sources:
+- INI file
+- SQL database through SQLAlchemy (optional)
+- environment variables
+- in-memory Python dictionary
+
+Values are resolved in order, and the first non-empty match is returned.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install ga-configreader
+```
+
+### From source
+
+```bash
+git clone https://github.com/andreagemma/configreader.git
+cd configreader
+pip install -e .
+```
+
+### Database support (optional)
+
+Install SQLAlchemy if you want to use the DB provider:
+
+```bash
+pip install sqlalchemy
+```
+
+Or install the project with DB extras:
+
+```bash
+pip install "configreader[db]"
+```
+
+## Quickstart
+
+```python
+from configreader import ConfigReader
+
+reader = ConfigReader(
+    file="config.ini",
+    use_env=True,
+    dictionary={"DEFAULT": {"timeout": "30"}},
+    providers=["env", "ini", "dict"],
+)
+
+host = reader.get("host", default="127.0.0.1")
+port = reader.getint("port", default=8080)
+debug = reader.getboolean("debug", default=False)
+```
+
+## Provider Precedence
+
+The providers list defines lookup order.
+
+Example:
+
+```python
+providers = ["env", "db", "ini", "dict"]
+```
+
+Meaning:
+1. check environment first
+2. then check database
+3. then check INI file
+4. then check dictionary
+
+## Environment Variables
+
+Naming rules:
+- if section="DEFAULT", variable name is NAME
+- for custom sections, variable name is SECTION_NAME
+
+Examples:
+- reader.get("host", section="DEFAULT") reads HOST
+- reader.get("host", section="app") reads APP_HOST
+
+## Using INI Files
+
+Example config.ini:
+
+```ini
+[DEFAULT]
+host = localhost
+port = 5432
+debug = true
+items = [1, 2, 3]
+
+[app]
+workers = 4
+```
+
+Code:
+
+```python
+reader = ConfigReader(file="config.ini")
+
+host = reader.get("host")
+port = reader.getint("port")
+debug = reader.getboolean("debug")
+items = reader.getlist("items")
+workers = reader.getint("workers", section="app")
+```
+
+## Using a Dictionary
+
+```python
+reader = ConfigReader(
+    dictionary={
+        "DEFAULT": {
+            "host": "localhost",
+            "allowed": "['admin', 'user']",
+        },
+        "service": {
+            "retries": "3",
+        },
+    },
+    providers=["dict"],
+)
+
+allowed = reader.getlist("allowed")
+retries = reader.getint("retries", section="service")
+```
+
+## Using a Database
+
+Constructor:
+
+```python
+reader = ConfigReader(
+    db_url="sqlite:///settings.db",
+    db_query="SELECT value FROM settings WHERE section = :section AND name = :name",
+    providers=["db", "env"],
+)
+```
+
+Default query shape:
+
+```sql
+SELECT value FROM settings WHERE section = :section AND name = :name
+```
+
+DB utility methods:
+
+```python
+ok = ConfigReader.check_db_connection("sqlite:///settings.db")
+exists = ConfigReader.check_db_exists("sqlite:///settings.db", table_name="settings")
+```
+
+## Main API
+
+- `get(name, default=None, section="DEFAULT") -> str | None`
+- `getint(name, default=None, section="DEFAULT") -> int | None`
+- `getboolean(name, default=None, section="DEFAULT") -> bool | None`
+- `getfloat(name, default=None, section="DEFAULT") -> float | None`
+- `getlist(name, default=None, section="DEFAULT") -> list[Any] | None`
+- `getset(name, default=None, section="DEFAULT") -> set[Any] | None`
+- `gettuple(name, default=None, section="DEFAULT") -> tuple[Any, ...] | None`
+- `getdict(name, default=None, section="DEFAULT") -> dict[Any, Any] | None`
+- `items()` iterator over loaded INI entries
+
+Full details in [docs/api.md](docs/api.md).
+
+## Errors And Type Conversion
+
+- `FileNotFoundError` is raised if the provided INI file does not exist.
+- Typed getters (`getint`, `getfloat`, `getlist`, etc.) propagate parsing/conversion errors.
+- If SQLAlchemy is not installed, DB features are unavailable.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e .[dev]
+```
+
+Run tests:
+
+```bash
+pytest
+```
+
+## More Documentation
+
+- [docs/overview.md](docs/overview.md)
+- [docs/providers.md](docs/providers.md)
+- [docs/api.md](docs/api.md)
+- [docs/examples.md](docs/examples.md)
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE).

ga_configreader-0.1.3/docs/api.md

@@ -0,0 +1,75 @@
+# API Reference
+
+## ConfigSource Enum
+
+Available values:
+- ConfigSource.INI ("ini")
+- ConfigSource.DB ("db")
+- ConfigSource.ENV ("env")
+- ConfigSource.DICT ("dict")
+
+Methods:
+- ConfigSource.parse(value: str) -> ConfigSource | None
+
+## ConfigReader Class
+
+### Constructor
+
+```python
+ConfigReader(
+    file: str | Path | None = None,
+    dictionary: dict[str, dict[str, str]] | None = None,
+    db_url: str | None = None,
+    db_query: str | None = None,
+    use_env: bool = True,
+    providers: list[ConfigSource | str] | None = None,
+)
+```
+
+Parameters:
+- file: path to an INI file.
+- dictionary: in-memory source grouped by section and key.
+- db_url: SQLAlchemy database URL.
+- db_query: SQL query using :section and :name parameters.
+- use_env: enable or disable environment variable lookup.
+- providers: provider precedence order.
+
+### Main Methods
+
+- get(name, default=None, section="DEFAULT") -> str | None
+: reads the raw value as string.
+
+- getint(name, default=None, section="DEFAULT") -> int | None
+: converts using int(...).
+
+- getboolean(name, default=None, section="DEFAULT") -> bool | None
+: returns True when lowercased value is in ("true", "1", "yes"), else False.
+
+- getfloat(name, default=None, section="DEFAULT") -> float | None
+: converts using float(...).
+
+- getlist(name, default=None, section="DEFAULT") -> list[Any] | None
+: parses with ast.literal_eval(...).
+
+- getset(name, default=None, section="DEFAULT") -> set[Any] | None
+: parses with set(ast.literal_eval(...)).
+
+- gettuple(name, section="DEFAULT", default=None) -> tuple[Any, ...] | None
+: parses with tuple(ast.literal_eval(...)).
+
+- getdict(name, section="DEFAULT", default=None) -> dict[Any, Any] | None
+: parses with dict(ast.literal_eval(...)).
+
+- items()
+: iterator of (section, name, value) from loaded INI sections.
+
+### DB Utility Static Methods
+
+- ConfigReader.check_db_connection(db_url: str) -> bool
+- ConfigReader.check_db_exists(db_url: str, table_name: str = "settings") -> bool
+
+## Important Behavior
+
+- If no provider returns a value, default is returned.
+- Typed conversions may raise parsing/conversion exceptions.
+- Without SQLAlchemy, DB methods are unavailable.

ga_configreader-0.1.3/docs/examples.md

@@ -0,0 +1,82 @@
+# Examples
+
+## 1) Fallback Env -> INI
+
+```python
+from configreader import ConfigReader
+
+reader = ConfigReader(
+    file="config.ini",
+    use_env=True,
+    providers=["env", "ini"],
+)
+
+api_url = reader.get("api_url", default="http://localhost:8000")
+```
+
+With this order, an environment variable overrides the INI value.
+
+## 2) Dictionary Only (useful in tests)
+
+```python
+from configreader.configreader import ConfigReader
+
+reader = ConfigReader(
+    dictionary={
+        "DEFAULT": {
+            "retries": "3",
+            "enabled": "true",
+        },
+        "service": {
+            "weights": "[0.4, 0.6]",
+        },
+    },
+    providers=["dict"],
+)
+
+retries = reader.getint("retries", default=1)
+enabled = reader.getboolean("enabled", default=False)
+weights = reader.getlist("weights", section="service", default=[1.0])
+```
+
+## 3) DB With Custom Query
+
+```python
+from configreader.configreader import ConfigReader
+
+reader = ConfigReader(
+    db_url="sqlite:///settings.db",
+    db_query="""
+        SELECT setting_value
+        FROM app_settings
+        WHERE section = :section AND key_name = :name
+    """,
+    providers=["db"],
+)
+
+timeout = reader.getint("timeout", section="http", default=30)
+```
+
+Make sure the query returns exactly one value column.
+
+## 4) Full Chain With All Providers
+
+```python
+from configreader.configreader import ConfigReader
+
+reader = ConfigReader(
+    file="config.ini",
+    db_url="sqlite:///settings.db",
+    use_env=True,
+    dictionary={"DEFAULT": {"workers": "2"}},
+    providers=["env", "db", "ini", "dict"],
+)
+
+workers = reader.getint("workers", default=1)
+```
+
+Practical order:
+1. quick overrides via env
+2. central configuration from DB
+3. local fallback from INI
+4. final hard-coded fallback from dictionary

ga_configreader-0.1.3/docs/index.md

@@ -0,0 +1,10 @@
+# Documentation
+
+Documentation index:
+
+- [Overview](overview.md)
+- [Providers](providers.md)
+- [API Reference](api.md)
+- [Examples](examples.md)
+
+For a quick introduction, start from [README.md](../README.md).

ga_configreader-0.1.3/docs/overview.md

@@ -0,0 +1,35 @@
+# Overview
+
+configreader is a small utility library that centralizes configuration lookup across multiple sources.
+
+Core goals:
+- automatic fallback between providers
+- configurable provider precedence
+- uniform API for raw and typed values
+
+## Supported Sources
+
+- ini: local INI file
+- db: SQL query through SQLAlchemy
+- env: environment variables
+- dict: in-memory Python dictionary
+
+## Resolution Flow
+
+1. a get* method is called
+2. providers are checked in the configured order
+3. the first non-None value is returned
+4. if no value is found, default is returned
+
+## When To Use
+
+- applications with environment-based overrides
+- services with central DB settings and local fallback
+- tests where values are injected from a dictionary
+
+## When Not To Use
+
+- complex schema validation for configuration payloads
+- advanced secret management with rotation policies
+
+In these scenarios, pair this library with dedicated validators or secret management tools.