ecodev-core 0.0.57__tar.gz → 0.0.59__tar.gz

{ecodev_core-0.0.57 → ecodev_core-0.0.59}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ecodev-core
-Version: 0.0.57
+Version: 0.0.59
 Summary: Low level sqlmodel/fastapi/pydantic building blocks
 License: MIT
 Author: Thomas Epelbaum

{ecodev_core-0.0.57 → ecodev_core-0.0.59}/ecodev_core/__init__.py

@@ -37,11 +37,17 @@ from ecodev_core.db_connection import engine
 from ecodev_core.db_connection import get_session
 from ecodev_core.db_connection import info_message
 from ecodev_core.db_filters import ServerSideFilter
+from ecodev_core.db_i18n import I18nMixin
+from ecodev_core.db_i18n import Lang
+from ecodev_core.db_i18n import get_lang
+from ecodev_core.db_i18n import localized_col
+from ecodev_core.db_i18n import set_lang
 from ecodev_core.db_insertion import generic_insertion
 from ecodev_core.db_insertion import get_raw_df
 from ecodev_core.db_retrieval import count_rows
 from ecodev_core.db_retrieval import get_rows
 from ecodev_core.db_retrieval import ServerSideField
+from ecodev_core.db_upsertion import add_missing_columns
 from ecodev_core.db_upsertion import add_missing_enum_values
 from ecodev_core.db_upsertion import field
 from ecodev_core.db_upsertion import filter_to_sfield_dict
@@ -111,4 +117,5 @@ __all__ = [
     'sort_by_keys', 'sort_by_values', 'Settings', 'load_yaml_file', 'Deployment', 'Version',
     'sfield', 'field', 'upsert_df_data', 'upsert_deletor', 'get_row_versions', 'get_versions',
     'db_to_value', 'upsert_data', 'upsert_selector', 'get_sfield_columns', 'filter_to_sfield_dict',
-    'SETTINGS', 'add_missing_enum_values', 'ban_token', 'TokenBanlist', 'is_banned']
+    'SETTINGS', 'add_missing_enum_values', 'ban_token', 'TokenBanlist', 'is_banned',
+    'get_lang', 'set_lang', 'Lang', 'localized_col', 'I18nMixin', 'add_missing_columns']

ecodev_core-0.0.59/ecodev_core/db_i18n.py

@@ -0,0 +1,213 @@
+"""
+Module implementing internationalization (i18n) for sqlmodel
+"""
+
+import contextvars
+from enum import Enum
+from typing import Optional
+
+from sqlalchemy import Label
+from sqlalchemy import label
+from sqlmodel import func
+from sqlmodel.main import SQLModelMetaclass
+
+from ecodev_core.list_utils import first_func_or_default
+
+class Lang(str, Enum):
+    """
+    Enum of the languages available for localization.
+    """
+    EN = 'en'
+    FR = 'fr'
+
+
+DB_Lang = 'db_Lang'
+CONTEXT_DB_Lang = contextvars.ContextVar(DB_Lang, default=Lang.EN)
+"""Context variables for storing the active database language, defaults to Lang.EN"""
+
+
+def set_lang(lang: Lang) -> None:
+    """
+    Sets the `CONTEXT_DB_Lang` context var.
+
+    Args:
+        lang (Lang): The language to assign to the `CONTEXT_DB_Lang` context var.
+    """
+    CONTEXT_DB_Lang.set(lang)
+
+
+def get_lang() -> Lang:
+    """
+    Fetches the value of `CONTEXT_DB_Lang` context var.
+
+    Returns:
+        lang (Lang): The value of `CONTEXT_DB_Lang` context var
+    """
+    return Lang(CONTEXT_DB_Lang.get())
+
+
+class I18nMixin:
+    """
+    I18n (localization) mixin for string attributes of pydantic BaseModel classes.
+
+    Maps arbitrary string attributes of the class to their localized values. Localized fields 
+    should be defined following the rules below :
+        - The field name must be defined as a key of the private attribute `__localized_fields__`
+        - Each field defined in `__localized_fields__` must be present as an attribute for \
+            each of its localized versions in the following format <field>_<lang>.
+            For example :
+            ```
+            __localized_fields__ = {
+                'name':[Lang.EN, Lang.FR]
+                }
+            ```
+            assumes that the attributes `name_en` and `name_fr` are attribute of the class.
+            These attributes must have a type `str`.
+        - All localized field must have a localized version using `__fallback_lang__`
+
+    Args:
+        __localized_fields__ (dict[str, list[Lang]]): Mapping between localized fields and a \
+            list of their available localized versions. Defaults to {}.
+        __fallback_lang__ (Lang): Fallback locale if the requested localized version of a \
+            field is None. Defaults to Lang.EN.
+    """
+    __localized_fields__: dict[str, list[Lang]] = {}
+    __fallback_lang__: Lang = Lang.EN
+
+    @classmethod
+    def _get_lang_chain(cls, field: str, lang: Optional[Lang] = None) -> list[Lang]:
+        """
+        Returns the chain of localized versions of the requested field with the priority given
+        to the `lang` argument, followed by the lang returned by
+        [get_lang][ecodev_core.db_i18n.get_lang] and finally the lang defined in
+        `cls.__fallback_lang__`.
+
+        Args:
+            field (str): Name of the attribute/field to localize
+            lang (Optional[Lang]): The requested locale language. If none, then uses that
+            returned by [get_lang][ecodev_core.db_i18n.get_lang]. Defaults to None.
+
+        Returns:
+            list[Lang]: List of Lang enums to use for generating the name of the localized \
+                fields.
+        """
+        if field not in cls.__localized_fields__:
+            raise AttributeError(f'Field {field!r} is not internationalized.')
+        
+        available_langs = cls.__localized_fields__[field]
+        
+        if cls.__fallback_lang__ not in available_langs:
+            raise AttributeError(
+                f'Fallback language {cls.__fallback_lang__!r} not available for field {field!r}. '
+                f'Available: {available_langs}'
+            )
+        
+        lang = lang or get_lang()
+        if lang not in cls.__localized_fields__[field]:
+            raise AttributeError(f'Field {field!r} is not localized to {lang!r}')
+
+        return list(set([lang, cls.__fallback_lang__]))
+
+    @classmethod
+    def _get_localized_field_name(cls, field: str, lang: Lang) -> str:
+        """
+        Returns the name of the localized version of `field` for the requested `lang` in the
+        following format <field>_<lang>.
+
+        Args:
+            field (str): Name of the attribute/field to localize
+            lang (Optional[Lang]): The requested locale language.
+        Returns:
+            str: the name of the localized version of `field` for the requested `lang`
+        """
+        return f'{field}_{lang.value}'
+
+    @classmethod
+    def get_localized_field_chain(cls, field: str, lang: Optional[Lang] = None) -> list[str]:
+        """
+        Returns a chain of the localized versions of the requested field with the priority given
+        to the `lang` argument, followed by the lang returned by
+        [get_lang][ecodev_core.db_i18n.get_lang] and finally
+        the lang defined in `cls.__fallback_lang__`
+
+        Args:
+            field (str): Name of the attribute/field to localize
+            lang (Optional[Lang]): The requested locale language. If none, then uses that
+            returned by [get_lang][ecodev_core.db_i18n.get_lang]. Defaults to None.
+
+        Returns:
+            list[str]: chain of the localized versions of the requested field.
+
+        """
+        return [cls._get_localized_field_name(field, lang) 
+                for lang in cls._get_lang_chain(field, lang)]
+
+    def _get_localized(self, field: str, lang: Optional[Lang] = None) -> Optional[str]:
+        """
+        Returns the localized version of a field.
+
+        The localized version is returned following the rules defined below :
+            - If the requested localized version is not available then the an attempt \
+                will be made to localize the field using `__fallback_lang__`
+            - The specified language can be passed to `_get_localized`. If it is not passed, \
+                the value returned by [get_lang][ecodev_core.db_i18n.get_lang]
+                is  used instead (Defaults to Lang.EN)
+            - If None is returned using the format <field>_<lang> for the language defined in \
+                `__localized_fields__` & `__fallback_lang__` is found then returns None
+
+        Args:
+            field (str): Name of the attribute/field to localize
+            lang (Optional[Lang]): Requested locale. If None, then fetched from \
+                [get_lang][ecodev_core.db_i18n.get_lang]. Defaults to None.
+
+        Return:
+            localized_field (Optional[str]): localized version of the field
+        """
+        lang_chain = self._get_lang_chain(field=field, lang=lang)
+
+        for lang in lang_chain:
+            attr = self._get_localized_field_name(field=field, lang=lang)
+            value = getattr(self, attr, None)
+            if value:
+                return value
+
+        return None
+
+    def __getattr__(self, item: str) -> Optional[str]:
+        """
+        Overrides __getattr__ to get the localized value of a item if it figures in
+        `__localized_fields__`.
+        """
+        if item in self.__localized_fields__:
+            return self._get_localized(item)
+        raise AttributeError(f'{self.__class__.__name__!r} object has no attribute {item!r}')
+
+
+def localized_col(
+    field: str,
+    db_schema: SQLModelMetaclass,
+    lang: Optional[Lang] = None,
+) -> Label:
+    """
+    Returns the localized version of `field` for the requested `lang` of a
+    given SqlModel class. If `lang` is not specified, then fetches the active
+    locale from [get_lang][ecodev_core.db_i18n.get_lang].
+
+    Args:
+        field (str): Name of the field to localize
+        db_schema (SQLModelMetaclass): SQLModelMetaclass instance from which the localized \
+            fields will be fetched
+        lang (Optional[Lang]): Requested locale language. If None, then fetches language \
+            from [get_lang][ecodev_core.db_i18n.get_lang] Defaults to None.
+
+    Returns:
+        localized_field (Label): Localized version of the requested `field` wrapped in label \
+            with the name of `field`.
+    """
+    if not issubclass(db_schema, I18nMixin):
+        raise TypeError(f"{db_schema.__name__} does not inherit from I18nMixin")
+    
+    localized_fields_chain = db_schema.get_localized_field_chain(field, lang)
+    coalesce_fields = [getattr(db_schema, field_name) for field_name in localized_fields_chain]
+
+    return label(field, func.coalesce(*coalesce_fields))

{ecodev_core-0.0.57 → ecodev_core-0.0.59}/ecodev_core/db_upsertion.py

@@ -1,14 +1,21 @@
 """
 Module handling CRUD and version operations
 """
+import enum
+import json
+import types
 from datetime import datetime
 from enum import EnumType
 from functools import partial
 from typing import Any
+from typing import get_args
+from typing import get_origin
+from typing import Iterator
 from typing import Union
 
 import pandas as pd
 import progressbar
+from pydantic_core._pydantic_core import PydanticUndefined
 from sqlmodel import and_
 from sqlmodel import Field
 from sqlmodel import inspect
@@ -191,3 +198,185 @@ def filter_to_sfield_dict(row: dict | SQLModelMetaclass,
     """
     return {pk: getattr(row, pk)
             for pk in get_sfield_columns(db_schema or row.__class__)}
+
+
+def add_missing_columns(model: Any, session: Session) -> None:
+    """
+      Create all columns corresponding to fields in the passed model that are not yet columns in the
+     corresponding db table.
+
+    NB: The ORM not permitting to create new columns, we unfortunately have to rely on sqlalchemy
+     text sql statements.
+
+    NB2: As of 2025/10/01, handle the creation of int, float, str, bool, bytes, JSONB, Enum columns
+
+    NB3: possible to index columns, and to add foreign key.
+
+    NB4: Possible to have a non NULL default value
+    """
+    table = model.__tablename__
+    current_cols,  = get_existing_columns(table, session),
+    for col, py_type, fld in [(c, p, f) for c, p, f in _get_cols(model) if c not in current_cols]:
+        is_null = _is_type_nullable(py_type)
+        default = _get_default_value(fld, is_null)
+        _add_column(table, col, _py_type_to_sql(_clean_py_type(py_type)), default, is_null, session)
+        if getattr(fld, 'index', False):
+            _add_index(table, col, session)
+        if isinstance((fk := getattr(fld, 'foreign_key', None)), str) and fk.strip():
+            _add_foreign_key(f"{fk.split('.')[0]}(id)", table, col, session)
+        session.commit()
+
+
+def _get_default_value(fld: Any, nullable: bool) -> Any:
+    """
+    Find if any the field default value
+    """
+    if not nullable and hasattr(fld, 'default') and fld.default is not None:
+        return fld.default
+    return None
+
+
+def _add_column(table: str,
+                col: str,
+                sql_type: str,
+                default: Any,
+                nullable: bool,
+                session: Session
+                ) -> None:
+    """
+     Add the new column with sql_type to the passed table
+    """
+    session.execute(text(f'ALTER TABLE {table} ADD COLUMN {col} {sql_type} '
+                         f'{_get_additional_request(col, sql_type, default, nullable)}'))
+
+
+def _get_additional_request(col: str, sql_type: str, default_value: Any, nullable: bool) -> str:
+    """
+    Add if any the default value for the passed col.
+    """
+    if nullable:
+        return 'NULL'
+
+    if default_value is not None:
+        if (default_sql := _python_default_to_sql(default_value, sql_type)) == 'NULL':
+            raise ValueError(f'Non-nullable column {col} requires a default_value')
+        return f'DEFAULT {default_sql} NOT NULL'
+
+    raise ValueError(f'Non-nullable column {col} requires a default_value')
+
+
+def _add_index(table: str, col: str, session: Session):
+    """
+    Index the new table column
+    """
+    session.execute(text(f'CREATE INDEX IF NOT EXISTS ix_{table}_{col} ON {table} ({col})'))
+
+
+def _add_foreign_key(fk: str, table: str, col: str, session: Session):
+    """
+    Add a fk foreign key on the passed table column
+    """
+    session.execute(text(
+        f'ALTER TABLE {table} ADD CONSTRAINT fk_{table}_{col} FOREIGN KEY ({col}) REFERENCES {fk}'))
+
+
+def _get_cols(model: Any) -> Iterator[tuple[str, Any, Any]]:
+    """
+    Retrieve all fields and their corresponding sql types from the passed model
+    """
+    for col, field in model.model_fields.items():
+        if (col_type := getattr(field, 'annotation', None)) is not None:
+            yield col, col_type, field
+
+
+def get_existing_columns(table_name: str, session: Session) -> set[str]:
+    """
+    Retrieve all column names from the passed table
+    """
+    result = session.execute(text('SELECT column_name FROM information_schema.columns WHERE '
+                                  'table_name = :table_name'), {'table_name': table_name})
+    return {r[0] for r in result}
+
+
+def _clean_py_type(col_type: Any) -> Any:
+    """
+    Convert union and optional types to their non-None types, return directly passed type otherwise.
+    - Handle Python 3.10+ UnionType (aka X | Y)
+    - Unpack Optional types (Union[X, NoneType])
+    """
+    if isinstance(col_type, types.UnionType):
+        if len((args := [t for t in col_type.__args__ if t is not type(None)])) == 1:
+            return args[0]
+
+    if get_origin(col_type) is Union:
+        if len((args := [t for t in get_args(col_type) if t is not type(None)])) == 1:
+            return args[0]
+
+    return col_type
+
+
+def _is_type_nullable(col_type: Any) -> bool:
+    """
+    Return True if col_type is Optional or Union[..., None].
+    """
+    if isinstance(col_type, types.UnionType):
+        return type(None) in col_type.__args__
+
+    if get_origin(col_type) is Union:
+        return type(None) in get_args(col_type)
+
+    return col_type is type(None)
+
+
+def _python_default_to_sql(value: Any, sql_type: str) -> str:
+    """
+    Convert Python default to SQL literal, handling common types.
+    """
+    if value is None or value == PydanticUndefined:
+        return 'NULL'
+    if sql_type in ('VARCHAR', 'TEXT', 'CHAR'):
+        safe_value = value.replace("'", "''")
+        return f"'{safe_value}'"
+    if sql_type in ('INTEGER', 'FLOAT', 'NUMERIC', 'DOUBLE PRECISION'):
+        return str(value)
+    if sql_type == 'BOOLEAN':
+        return 'TRUE' if value else 'FALSE'
+    if sql_type == 'BYTEA':
+        if isinstance(value, bytes):
+            return f"decode('{value.hex()}', 'hex')"
+        raise ValueError('Default for BYTEA must be bytes')
+    if sql_type == 'JSONB':
+        json_str = json.dumps(value).replace("'", "''")
+        return f"'{json_str}'::jsonb"
+    if isinstance(value, enum.Enum):
+        return f"'{str(value.name)}'"
+    return str(value)
+
+
+def _py_type_to_sql(col_type: type) -> str:
+    """
+    Convert a python type to a sql one. Only working for (as of 2025/10/01):
+    - int
+    - float
+    - str
+    - bool
+    - bytes
+    - jsonB
+    - Enum
+    NB: for enum, assumes type is already created in DB
+    """
+    if col_type is str:
+        return 'VARCHAR'
+    if col_type is int:
+        return 'INTEGER'
+    if col_type is float:
+        return 'FLOAT'
+    if col_type is bool:
+        return 'BOOLEAN'
+    if col_type is bytes:
+        return 'BYTEA'
+    if col_type is dict:
+        return 'JSONB'
+    if hasattr(col_type, '__members__'):
+        return col_type.__name__.lower()
+    raise ValueError(f'Unsupported column type: {col_type}')

{ecodev_core-0.0.57 → ecodev_core-0.0.59}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "ecodev-core"
-version = "0.0.57"
+version = "0.0.59"
 description = "Low level sqlmodel/fastapi/pydantic building blocks"
 authors = ["Thomas Epelbaum <tomepel@gmail.com>",
 					 "Olivier Gabriel <olivier.gabriel.geom@gmail.com>",