ga-configreader 0.1.3__py3-none-any.whl

configreader/__init__.py

@@ -0,0 +1,8 @@
+"""configreader package
+Simple library functions for the project.
+"""
+
+from ._version import __version__
+from .configreader import ConfigReader, ConfigSource
+
+__all__ = ["__version__", "ConfigReader", "ConfigSource"]

configreader/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.3"

configreader/configreader.py

@@ -0,0 +1,481 @@
+from __future__ import annotations
+
+import os
+import ast
+import configparser
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+try:
+    from sqlalchemy import create_engine
+    from sqlalchemy import inspect
+    from sqlalchemy import text
+    from sqlalchemy.orm import sessionmaker
+    from sqlalchemy.exc import SQLAlchemyError
+except Exception:
+    create_engine = None
+    inspect = None
+    text = None
+    sessionmaker = None
+    SQLAlchemyError = Exception
+
+
+class ConfigSource(Enum):
+    """Supported configuration providers.
+
+    Attributes:
+        INI: Read values from an INI file.
+        DB: Read values from a database using SQLAlchemy.
+        ENV: Read values from environment variables.
+        DICT: Read values from an in-memory dictionary.
+    """
+
+    INI = "ini"
+    DB = "db"
+    ENV = "env"
+    DICT = "dict"
+
+    @classmethod
+    def parse(cls, value: str) -> ConfigSource | None:
+        """Parse a provider string into a ConfigSource enum value.
+
+        Args:
+            value: Provider name (e.g. "ini", "db", "env", "dict").
+
+        Returns:
+            The matching ConfigSource member, or None if unsupported.
+
+        Raises:
+            None.
+        """
+        for item in cls:
+            if item.value == value:
+                return item
+        return None
+
+    def __str__(self) -> str:
+        """Return the provider name as a string.
+
+        Returns:
+            The provider value (e.g. "ini", "db", "env", "dict").
+
+        Raises:
+            None.
+        """
+        return self.value
+
+
+class ConfigReader:
+    """Read configuration values from multiple providers with fallback order.
+
+    The reader checks providers in order and returns the first non-None value.
+    """
+
+    def __init__(
+        self,
+        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,
+    ):
+        """Initialize the reader with one or more configuration providers.
+
+        Args:
+            file: Optional path to an INI file.
+            dictionary: Optional nested dictionary grouped by section and key.
+            db_url: Optional SQLAlchemy database URL.
+            db_query: Optional SQL query with :section and :name bind parameters.
+            use_env: Enable or disable environment variable lookup.
+            providers: Provider priority order. Accepts ConfigSource values or strings.
+
+        Raises:
+            FileNotFoundError: If file is provided and does not exist.
+            ImportError: If DB provider is enabled and SQLAlchemy is unavailable.
+        """
+        self.config = configparser.ConfigParser()
+
+        # File .ini
+        self.use_ini = file is not None
+
+        if self.use_ini:
+            file_name: str = str(file)
+            if os.path.exists(file_name):
+                self.config.read(file_name)
+            else:
+                raise FileNotFoundError(f"INI file '{file_name}' does not exist")
+
+        self.use_db = db_url is not None
+        self.db_url = db_url
+        self.db_query = db_query or "SELECT value FROM settings WHERE section = :section AND name = :name"
+        self.db_session = None
+
+        self.use_env = use_env
+
+        self.use_dict = dictionary is not None
+        self.dictionary = dictionary
+
+        if self.use_db and self.db_url:
+            self._init_db()
+
+        # Keep provider ordering explicit and stable while avoiding mutable defaults.
+        if providers is None:
+            providers = [ConfigSource.INI, ConfigSource.DB, ConfigSource.ENV, ConfigSource.DICT]
+        self.order = [p if isinstance(p, ConfigSource) else ConfigSource.parse(p) for p in providers]
+
+    def items(self):
+        """Iterate over all entries loaded from the INI provider.
+
+        Yields:
+            Tuples in the form (section, name, value).
+
+        Raises:
+            None.
+        """
+        for sec in self.config.sections():
+            for name, value in self.config.items(sec):
+                yield sec, name, value
+
+    def _init_db(self):
+        """Create and store a SQLAlchemy session for DB lookups.
+
+        Raises:
+            ImportError: If SQLAlchemy is not installed.
+            ValueError: If db_url is missing.
+
+        Notes:
+            SQLAlchemy runtime connection errors are caught and logged, and do not
+            raise further exceptions from this method.
+        """
+        if create_engine is None or sessionmaker is None:
+            raise ImportError("SQLAlchemy is not available")
+        if not self.db_url:
+            raise ValueError("Database URL is not provided")
+        try:
+            engine = create_engine(self.db_url)
+            Session = sessionmaker(bind=engine)
+            self.db_session = Session()
+        except SQLAlchemyError as ex:
+            print(f"Error initializing database connection: {ex}")
+
+    @staticmethod
+    def check_db_connection(db_url: str) -> bool:
+        """Check whether a DB connection can be established for a URL.
+
+        Args:
+            db_url: SQLAlchemy connection URL.
+
+        Returns:
+            True if a connection can be opened, False otherwise.
+
+        Raises:
+            None.
+        """
+        if create_engine is None:
+            return False
+        try:
+            engine = create_engine(db_url)
+            with engine.connect() as connection:
+                connection.close()
+            return True
+        except SQLAlchemyError:
+            return False
+
+    @staticmethod
+    def check_db_exists(db_url: str, table_name: str = "settings") -> bool:
+        """Check whether a table exists in the target database.
+
+        Args:
+            db_url: SQLAlchemy connection URL.
+            table_name: Table to check for existence.
+
+        Returns:
+            True if the table exists, False otherwise.
+
+        Raises:
+            None.
+        """
+        if create_engine is None or inspect is None:
+            return False
+        try:
+            engine = create_engine(db_url)
+            inspector = inspect(engine)
+            return inspector.has_table(table_name)
+        except SQLAlchemyError:
+            return False
+
+    def _get_from_dict(self, section: str, name: str) -> str | None:
+        """Read a value from the dictionary provider.
+
+        Args:
+            section: Configuration section.
+            name: Configuration key.
+
+        Returns:
+            Value converted to string if found, otherwise None.
+
+        Raises:
+            None.
+        """
+        if not self.use_dict:
+            return None
+        if not self.dictionary:
+            return None
+        value = self.dictionary.get(section, {}).get(name)
+        return str(value) if value is not None else None
+
+    def _get_from_db(self, section: str, name: str) -> str | None:
+        """Read a value from the database provider.
+
+        Args:
+            section: Configuration section.
+            name: Configuration key.
+
+        Returns:
+            Database value as string if found, otherwise None.
+
+        Raises:
+            None.
+
+        Notes:
+            SQLAlchemy runtime errors are caught and logged.
+        """
+        if not self.use_db:
+            return None
+        if not self.db_session:
+            return None
+        if text is None:
+            return None
+        try:
+            statement = text(self.db_query)
+            result = self.db_session.execute(statement, {"name": name, "section": section}).scalar_one_or_none()
+            return result if isinstance(result, str) else (str(result) if result is not None else None)
+        except SQLAlchemyError as ex:
+            print(f"Error fetching {name} from database: {ex}")
+            return None
+
+    def _get_from_ini(self, section: str, name: str) -> str | None:
+        """Read a value from the INI provider using ConfigParser fallback.
+
+        Args:
+            section: Configuration section.
+            name: Configuration key.
+
+        Returns:
+            INI value if found, otherwise None.
+
+        Raises:
+            None.
+        """
+        if not self.use_ini:
+            return None
+        return self.config.get(section, name, fallback=None)
+
+    def _get_from_env(self, section: str, name: str) -> str | None:
+        """Read a value from environment variables.
+
+        Naming convention:
+            - DEFAULT section: NAME
+            - Custom section: SECTION_NAME
+
+        Args:
+            section: Configuration section.
+            name: Configuration key.
+
+        Returns:
+            Environment variable value if found, otherwise None.
+
+        Raises:
+            None.
+        """
+        if not self.use_env:
+            return None
+        # DEFAULT uses NAME; custom sections use SECTION_NAME.
+        if section.upper() == "DEFAULT":
+            return os.getenv(name.upper())
+        return os.getenv(f"{section}_{name}".upper())
+
+    def get(self, name: str, default: str | None = None, section: str = "DEFAULT") -> str | None:
+        """Resolve a configuration value using provider priority order.
+
+        Args:
+            name: Key name inside the section.
+            default: Value returned when no provider has a value.
+            section: Configuration section.
+
+        Returns:
+            The first resolved value as a string, otherwise default.
+
+        Raises:
+            None.
+        """
+        value = None
+        # Providers are queried in order; first non-None wins.
+        for provider in self.order:
+            if provider == ConfigSource.INI:
+                value = self._get_from_ini(section, name)
+            elif provider == ConfigSource.DB:
+                value = self._get_from_db(section, name)
+            elif provider == ConfigSource.ENV:
+                value = self._get_from_env(section, name)
+            elif provider == ConfigSource.DICT:
+                value = self._get_from_dict(section, name)
+
+            if value is not None:
+                break
+
+        return value if value is not None else default
+
+    def getint(self, name: str, default: int | None = None, section: str = "DEFAULT") -> int | None:
+        """Get a value and convert it to int.
+
+        Args:
+            name: Configuration key.
+            default: Returned when no value is found.
+            section: Configuration section.
+
+        Returns:
+            Parsed integer value, or default if unresolved.
+
+        Raises:
+            ValueError: If the resolved value cannot be converted to int.
+            TypeError: If the resolved value type is not compatible with int().
+        """
+        value = self.get(name, section=section, default=None)
+        return int(value) if value is not None else default
+
+    def getboolean(self, name: str, default: bool | None = None, section: str = "DEFAULT") -> bool | None:
+        """Get a value and convert it to bool.
+
+        Truthy values are: "true", "1", "yes" (case-insensitive).
+
+        Args:
+            name: Configuration key.
+            default: Returned when no value is found.
+            section: Configuration section.
+
+        Returns:
+            True for truthy strings, False for other resolved strings,
+            or default if unresolved.
+
+        Raises:
+            None.
+        """
+        value = self.get(name, section=section, default=None)
+        return value.lower() in ("true", "1", "yes") if value is not None else default
+
+    def getfloat(self, name: str, default: float | None = None, section: str = "DEFAULT") -> float | None:
+        """Get a value and convert it to float.
+
+        Args:
+            name: Configuration key.
+            default: Returned when no value is found.
+            section: Configuration section.
+
+        Returns:
+            Parsed float value, or default if unresolved.
+
+        Raises:
+            ValueError: If the resolved value cannot be converted to float.
+            TypeError: If the resolved value type is not compatible with float().
+        """
+        value = self.get(name, section=section, default=None)
+        return float(value) if value is not None else default
+
+    def getlist(self, name: str, default: list[Any] | None = None, section: str = "DEFAULT") -> list[Any] | None:
+        """Get a value and parse it as a Python list literal.
+
+        Args:
+            name: Configuration key.
+            default: Returned when no value is found.
+            section: Configuration section.
+
+        Returns:
+            Parsed Python object from literal_eval, or default if unresolved.
+
+        Raises:
+            ValueError: If the value contains a malformed literal.
+            SyntaxError: If the value is not valid Python literal syntax.
+            MemoryError: In rare cases for extremely large literals.
+        """
+        value = self.get(name, section=section, default=None)
+        # Complex values are parsed from string literals.
+        return ast.literal_eval(value) if value is not None else default
+
+    def getset(self, name: str, default: set[Any] | None = None, section: str = "DEFAULT") -> set[Any] | None:
+        """Get a value and parse it as a set.
+
+        If the resolved value is already a set, it is returned as-is.
+
+        Args:
+            name: Configuration key.
+            default: Returned when no value is found.
+            section: Configuration section.
+
+        Returns:
+            Parsed set value, or default if unresolved.
+
+        Raises:
+            ValueError: If the value contains a malformed literal.
+            SyntaxError: If the value is not valid Python literal syntax.
+            TypeError: If the parsed value is not iterable for set conversion.
+        """
+        value = self.get(name, section=section, default=None)
+        if isinstance(value, set):
+            return value
+        return set(ast.literal_eval(value)) if value is not None else default
+
+    def gettuple(
+        self, name: str, section: str = "DEFAULT", default: tuple[Any, ...] | None = None
+    ) -> tuple[Any, ...] | None:
+        """Get a value and parse it as a tuple.
+
+        If the resolved value is already a tuple, it is returned as-is.
+
+        Args:
+            name: Configuration key.
+            section: Configuration section.
+            default: Returned when no value is found.
+
+        Returns:
+            Parsed tuple value, or default if unresolved.
+
+        Raises:
+            ValueError: If the value contains a malformed literal.
+            SyntaxError: If the value is not valid Python literal syntax.
+            TypeError: If the parsed value is not iterable for tuple conversion.
+        """
+        value = self.get(name, section=section, default=None)
+        if isinstance(value, tuple):
+            return value
+        return tuple(ast.literal_eval(value)) if value is not None else default
+
+    def getdict(
+        self, name: str, section: str = "DEFAULT", default: dict[Any, Any] | None = None
+    ) -> dict[Any, Any] | None:
+        """Get a value and parse it as a dictionary.
+
+        If the resolved value is already a dict, it is returned as-is.
+
+        Args:
+            name: Configuration key.
+            section: Configuration section.
+            default: Returned when no value is found.
+
+        Returns:
+            Parsed dictionary value, or default if unresolved.
+
+        Raises:
+            ValueError: If the value contains a malformed literal.
+            SyntaxError: If the value is not valid Python literal syntax.
+            TypeError: If the parsed value cannot be converted to dict.
+        """
+        value = self.get(name, section=section, default=None)
+        if isinstance(value, dict):
+            return value
+        return dict(ast.literal_eval(value)) if value is not None else default
+
+
+__all__ = ["ConfigReader", "ConfigSource"]

configreader/py.typed

@@ -0,0 +1 @@
+

ga_configreader-0.1.3.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+configreader/__init__.py,sha256=bQHeQEeXGCvs9Pu9DzgkCAkRFEFe3pb1vBWAXPUrSGs,217
+configreader/_version.py,sha256=XEqb2aiIn8fzGE68Mph4ck1FtQqsR_am0wRWvrYPffQ,22
+configreader/configreader.py,sha256=LJC0H5imNXGBgCQqcK9aeXUqbWSo5tLAJar_SbExGWI,16376
+configreader/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+ga_configreader-0.1.3.dist-info/licenses/LICENSE,sha256=qu2EXOee5U25eaDf50dc7Rmuysbz9BNo0hhJ2D9vawc,1069
+ga_configreader-0.1.3.dist-info/METADATA,sha256=4wbT64viQ66shO4MIMK_ShnACelOqVwxopQBKPF_C18,5728
+ga_configreader-0.1.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ga_configreader-0.1.3.dist-info/top_level.txt,sha256=OpY58yfn954wkqaetoS2uQ2VJi4Nw6rpv_PYJwPKG7Q,13
+ga_configreader-0.1.3.dist-info/RECORD,,

ga_configreader-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ga_configreader-0.1.3.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+configreader