elemento-customers 1.0.0__tar.gz

elemento_customers-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+prune *
+include app/__init__.py
+include app/client.py
+include app/types.py

elemento_customers-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: elemento-customers
+Version: 1.0.0
+Summary: Customer service
+Requires-Python: >=3.11
+Requires-Dist: kaiju-tools<3,>=2.4.9
+Requires-Dist: kaiju-models<2,>=1.0.4
+Provides-Extra: server
+Requires-Dist: kaiju-db<3,>=2.3; extra == "server"
+Requires-Dist: kaiju-redis<3,>=2.4; extra == "server"
+Provides-Extra: dev
+Requires-Dist: kaiju-tools[dev]; extra == "dev"

elemento_customers-1.0.0/README.md

@@ -0,0 +1,52 @@
+# Elemento-Customers
+
+Используется для хранения и обработки данных клиентов: их основных атрибутов, параметров анкеты, контактной информации,
+базовой статистики и т.д. Описание доступных методов смотри в `docs/api.http`.
+
+Конкретный набор хранимых данных зависит от настроек анкеты.
+
+# Запуск сервера
+
+Стандартный как для всех Kaiju приложений.
+
+Сервер клиентов требует подключения к `postgres` серверу бд для хранения таблицы клиентов и
+структурированных атрибутов анкеты.
+
+Также сервер требует `redis` с установленным `redis-search` модулем (только при `search_enabled=true`) для поисковых
+запросов по данным анкет.
+
+# Описание важных настроек
+
+- `services_db_host` : str - IP или адрес postgres сервера базы данных
+- `services_db_port`: int - порт postgres сервера базы данных
+- `services_db_database` : str - имя базы данных
+- `services_db_user` : str - имя пользователя postgres (должен обладать правами создавать таблицы)
+- `services_db_password` : str - пароль для учетной записи пользователя postgres
+- `search_enabled` : bool - включить или выключить поисковые сервисы в redis
+- `services_redis_host` : str - IP или адрес сервера redis
+- `services_redis_port` : int - порт сервера redis
+- `services_redis_db` : int - номер базы данных в redis
+- `services_redis_password` : str - пароль для сервера redis
+- `services_redis_cluster`: bool - использовать клиент для кластера redis
+
+# Поддержка
+
+- Периодический вызов `Customers.search.idx.migrate` для перестройки поискового индекса и избежания расхождений.
+- Периодический вызов `brin_summarize_new_values(idx_customers_id)` в Postgres для оптимизации BRIN индекса.
+
+# Установка для разработки
+
+1. Клонировать проект из git
+2. Зайти в директорию проекта и запустить скрипт разработки: `sh setup-dev.sh`
+3. ...
+4. Проверить запуск с помощью `python -m app`
+5. Для запуска в локальной среде рекомендуется установить docker-compose использовать `docker-compose.yaml`.
+
+# Краткое описание работы
+
+1. Сервер хранит структурированный набор анкетных атрибутов клиентов из которых создает модель для валидации входных
+   данных.
+2. При создании клиента ему присваивается автоинкрементный `id` и создается учетная запись в таблице `customers`. Помимо
+   присвоения `id` телефон также является уникальным обязательным атрибутом анкеты и проверяется по индексу БД при создании
+   учетной записи.
+3. При включенном redis данные по анкете также копируются в поисковый индекс. Ошибка при копировании будет проигнорирована.

elemento_customers-1.0.0/app/__init__.py

@@ -0,0 +1,5 @@
+"""Project information."""
+
+__author__ = "Anton Taraskin"
+__email__ = "hel.nidhoggr@gmail.com"
+__version__ = "1.0.0"

elemento_customers-1.0.0/app/client.py

@@ -0,0 +1,181 @@
+"""RPC client services for customer app."""
+
+from typing import Any, Literal
+
+from kaiju_tools.http import RPCClientService
+from kaiju_tools.services import SERVICE_CLASS_REGISTRY
+
+from .types import Customer, CustomerCreate, CustomerId, CustomerUpdate, SearchFilter
+
+
+class ElementoCustomersClient(RPCClientService):
+    """Auto-generated ElementoCustomers RPC client.
+
+    Configuration example:
+
+    .. code-block:: yaml
+
+      - cls: HTTPService
+        name: elemento_customers_conn
+        settings:
+          host: http://0.0.0.0:10001
+      - cls: ElementoCustomersClient
+        settings:
+          transport: elemento_customers_conn
+
+    """
+
+    async def create(
+        self, customer: CustomerCreate.Fields, _max_timeout: int = None, _nowait: bool = False
+    ) -> Customer.Fields:
+        """Call Customers.create."""
+        result = await self.call(
+            method="Customers.create", params=dict(customer=customer), max_timeout=_max_timeout, nowait=_nowait
+        )
+        return Customer.get_struct(result)
+
+    async def get(
+        self, id: CustomerId | int, _max_timeout: int = None, _nowait: bool = False
+    ) -> Customer.Fields | None:
+        """Get customer data by id or return `None` if not exists."""
+        result = await self.call(method="Customers.get", params=dict(id=id), max_timeout=_max_timeout, nowait=_nowait)
+        if result:
+            result = Customer.get_struct(result)
+        return result
+
+    async def get_by_phone(self, phone: str, _max_timeout: int = None, _nowait: bool = False) -> Customer.Fields | None:
+        """Find a customer by phone number or return `None` if not exists."""
+        result = await self.call(
+            method="Customers.get_by_phone", params=dict(phone=phone), max_timeout=_max_timeout, nowait=_nowait
+        )
+        if result:
+            result = Customer.get_struct(result)
+        return result
+
+    async def find(
+        self,
+        *,
+        query: str = "",
+        filters: SearchFilter = None,
+        offset: int = 0,
+        limit: int = 100,
+        sort_key: str = None,
+        sort_order: Literal["asc", "desc"] = None,
+        _max_timeout: int = None,
+        _nowait: bool = False,
+    ) -> list[Customer.Fields]:
+        """Find and list customers.
+
+        :param query: query string
+        :param filters: list of search conditions
+        :param offset: pagination offset
+        :param limit: pagination limit
+        :param sort_key: sorting key
+        :param sort_order: sorting order
+        :param _max_timeout: max request timeout in sec (None == server default)
+        :param _nowait: do not wait for the response (equivalent to id: null in JSONRPC)
+        """
+        result = await self.call(
+            method="Customers.find",
+            params=dict(
+                query=query, filters=filters, offset=offset, limit=limit, sort_key=sort_key, sort_order=sort_order
+            ),
+            max_timeout=_max_timeout,
+            nowait=_nowait,
+        )
+        return [Customer.get_struct(row) for row in result]
+
+    async def block(self, id: CustomerId | int, _max_timeout: int = None, _nowait: bool = False) -> None:
+        """Set customer status to `blocked`."""
+        return await self.call(method="Customers.block", params=dict(id=id), max_timeout=_max_timeout, nowait=_nowait)
+
+    async def unblock(self, id: CustomerId | int, _max_timeout: int = None, _nowait: bool = False) -> None:
+        """Revert customer `blocked` status."""
+        return await self.call(method="Customers.unblock", params=dict(id=id), max_timeout=_max_timeout, nowait=_nowait)
+
+    async def delete(self, id: CustomerId | int, _max_timeout: int = None, _nowait: bool = False) -> None:
+        """Delete customer completely and all its data."""
+        return await self.call(method="Customers.delete", params=dict(id=id), max_timeout=_max_timeout, nowait=_nowait)
+
+    async def update(
+        self,
+        id: CustomerId | int,
+        customer: CustomerUpdate.Fields | dict[str, Any],
+        _max_timeout: int = None,
+        _nowait: bool = False,
+    ) -> Customer.Fields:
+        """Update certain customer profile data or other parameters."""
+        result = await self.call(
+            method="Customers.update", params=dict(id=id, customer=customer), max_timeout=_max_timeout, nowait=_nowait
+        )
+        return Customer.get_struct(result)
+
+    async def get_settings(self, _max_timeout: int = None, _nowait: bool = False) -> dict[str, Any]:
+        """Get current service shared settings.
+
+        :param _max_timeout: max request timeout in sec (None == server default)
+        :param _nowait: do not wait for the response (equivalent to id: null in JSONRPC)
+        """
+        return await self.call(method="Customers.settings.get", params=dict(), max_timeout=_max_timeout, nowait=_nowait)
+
+    async def set_settings(
+        self, value: dict[str, Any], _max_timeout: int = None, _nowait: bool = False
+    ) -> dict[str, Any]:
+        """Create or update service shared settings.
+
+        :param value: new settings (you can pass only updated keys here)
+        :param _max_timeout: max request timeout in sec (None == server default)
+        :param _nowait: do not wait for the response (equivalent to id: null in JSONRPC)
+        """
+        return await self.call(
+            method="Customers.settings.set", params=dict(value=value), max_timeout=_max_timeout, nowait=_nowait
+        )
+
+    async def reset_settings(self, _max_timeout: int = None, _nowait: bool = False) -> dict[str, Any]:
+        """Reset service settings to the initial values.
+
+        :param _max_timeout: max request timeout in sec (None == server default)
+        :param _nowait: do not wait for the response (equivalent to id: null in JSONRPC)
+        """
+        return await self.call(
+            method="Customers.settings.reset", params=dict(), max_timeout=_max_timeout, nowait=_nowait
+        )
+
+    async def init_search_index(
+        self, load_docs: bool = True, _max_timeout: int = None, _nowait: bool = False
+    ) -> int | None:
+        """Init search index if not exists.
+
+        :returns: a number of loaded search documents or `None` if index already exists.
+        """
+        return await self.call(
+            method="Customers.search.idx.init",
+            params=dict(load_docs=load_docs),
+            max_timeout=_max_timeout,
+            nowait=_nowait,
+        )
+
+    async def flush_search_index(self, _max_timeout: int = None, _nowait: bool = False) -> None:
+        """Remove the search index and all related search documents."""
+        return await self.call(
+            method="Customers.search.idx.flush", params=dict(), max_timeout=_max_timeout, nowait=_nowait
+        )
+
+    async def migrate_search_index(
+        self, load_docs: bool = False, _max_timeout: int = None, _nowait: bool = False
+    ) -> int:
+        """Migrate to a new index.
+
+        Use this when you have modified the customer profile schema and need to update the search according to that.
+
+        :returns: a number of loaded search documents
+        """
+        return await self.call(
+            method="Customers.search.idx.migrate",
+            params=dict(load_docs=load_docs),
+            max_timeout=_max_timeout,
+            nowait=_nowait,
+        )
+
+
+SERVICE_CLASS_REGISTRY.register(ElementoCustomersClient)

elemento_customers-1.0.0/app/types.py

@@ -0,0 +1,67 @@
+"""Basic data types."""
+
+from datetime import date
+from typing import Any, NewType, TypedDict
+
+from kaiju_models import BooleanField, DateField, EmailField, IntegerField, JsonMapField, Model, StringField
+
+
+__all__ = ["CustomerId", "Customer", "CustomerUpdate", "CustomerCreate", "SearchFilter"]
+
+CustomerId = NewType("CustomerId", int)
+
+
+class SearchFilter(TypedDict):
+    """UI search filter data."""
+
+    id: str
+    kind: str
+    condition: str
+    value: Any
+
+
+class CustomerUpdate(Model["CustomerUpdate.Fields"]):
+    """Data to update customer."""
+
+    class Fields(Model.Fields):
+        blocked: bool = BooleanField()
+        email: str | None = EmailField()
+        email_confirmed: bool = BooleanField()
+        profile: dict[str, Any] = JsonMapField()  # profile data is dynamic and determined by settings
+        meta: dict[str, Any] = JsonMapField()  # meta is dynamic and determined by settings
+        subscriptions: dict[str, Any] = JsonMapField()  # subs data is dynamic and determined by settings
+        loyalty_enabled: bool = BooleanField()
+
+
+class CustomerCreate(Model["CustomerCreate.Fields"]):
+    """Data to create a new customer."""
+
+    class Fields(Model.Fields):
+        phone: str = StringField(pattern="7[0-9]{10}", required=True)
+        source_id: str | None = StringField()
+        email: str | None = EmailField()
+        email_confirmed: bool = BooleanField(default=False)
+        profile: dict[str, Any] = JsonMapField()  # profile data is dynamic and determined by settings
+        meta: dict[str, Any] = JsonMapField()  # meta is dynamic and determined by settings
+        subscriptions: dict[str, Any] = JsonMapField()  # subs data is dynamic and determined by settings
+        loyalty_enabled: bool = BooleanField(default=False)
+        accept_tender_offer: bool = BooleanField(default=True)
+        created: date = DateField()  # TODO: remove after loading the initial db
+
+
+class Customer(Model["Customer.Fields"]):
+    """Customer data"""
+
+    class Fields(Model.Fields):
+        id: CustomerId = IntegerField()
+        phone: str = StringField()
+        source_id: str | None = StringField()
+        email: str | None = EmailField()
+        email_confirmed: bool = BooleanField(default=False)
+        blocked: bool = BooleanField(default=False)
+        profile: dict[str, Any] = JsonMapField()  # profile data is dynamic and determined by settings
+        meta: dict[str, Any] = JsonMapField()  # meta is dynamic and determined by settings
+        subscriptions: dict[str, Any] = JsonMapField()  # subs data is dynamic and determined by settings
+        loyalty_enabled: bool = BooleanField(default=False)
+        created: date = DateField()
+        accept_tender_offer: bool = BooleanField(default=True)

elemento_customers-1.0.0/elemento_customers.egg-info/SOURCES.txt

@@ -0,0 +1,6 @@
+MANIFEST.in
+README.md
+pyproject.toml
+app/__init__.py
+app/client.py
+app/types.py

elemento_customers-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "elemento-customers"
+version = "1.0.0"
+description = "Customer service"
+requires-python = ">=3.11"
+dependencies = [
+    "kaiju-tools>=2.4.9,<3",
+    "kaiju-models>=1.0.4,<2"
+]
+
+[project.optional-dependencies]
+server = [
+    "kaiju-db>=2.3,<3",
+    "kaiju-redis>=2.4,<3",
+]
+dev = [
+    "kaiju-tools [dev]"
+]
+
+# --- BUILD CONFIGURATION ---
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["elemento_customers"]
+py-modules = []
+package-dir={elemento_customers = 'app'}
+
+# --- TOOL CONFIGURATION ---
+
+[tool.bandit]
+skips = ["B101"]  # , "B105", "B110", "B310", "B311", "B404", "B601", "B602", "B603", "B608", "B701"
+
+[tool.black]
+line-length = 120
+target-version = ['py311']
+
+[tool.isort]
+profile = "black"
+multi_line_output = 3
+lines_after_imports = 2
+skip_gitignore = true
+balanced_wrapping = true
+line_length = 120
+wrap_length = 120
+known_first_party = ["app"]
+src_paths = ["app"]
+skip = ['conftest.py', '__init__.py', '__main__.py', 'setup.py']
+skip_glob = ['docs/*', 'tests/*']
+
+[tool.pylint]
+load-plugins = [
+    'pylint.extensions.check_elif',
+    'pylint.extensions.docstyle',
+    'pylint.extensions.dunder',
+    'pylint.extensions.eq_without_hash',
+    'pylint.extensions.mccabe',
+    'pylint.extensions.overlapping_exceptions',
+    'pylint.extensions.private_import'
+]
+disable = ['C0114', 'C0116', 'C0115', 'R0902', 'R0903', 'R0913', 'R1735', 'W0622', 'W0611', 'W0707', 'R0917', 'R1260', 'W0613', 'R0912']
+max-line-length = 120
+
+[tool.pytest.ini_options]
+log_cli = true
+log_level = "DEBUG"
+log_format = '"%(name)s %(levelname)s %(message)s"'
+log_cli_level = "DEBUG"
+max_args = 10
+addopts = "--doctest-modules --doctest-continue-on-failure --ignore=docs/source/conf.py --ignore=conftest.py --ignore=setup.py"
+markers = ['docker', 'benchmark']

elemento_customers-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+