refactoring upd

Author: EEnota

.dockerignore

@@ -1,11 +1,14 @@
-.git
+.git
 .gitignore
 .venv
 __pycache__
 *.pyc
 *.pyo
 *.pyd
+.pytest_cache
+.ruff_cache
+.mypy_cache
 .env
 data/raw
 data/clean
-notebooks
+notebooks

.env.example

@@ -1,7 +1,22 @@
-DB_HOST=db
+DB_HOST=localhost
 DB_PORT=5432
-DB_USER=news_user
+DB_USER=postgres
 DB_PASSWORD=CHANGE_ME_STRONG_PASSWORD
 DB_ADMIN_DB=postgres
 DB_NEWS=news_db
-NEWSAPI_KEY=YOUR_REAL_NEWSAPI_KEY
+
+NEWSAPI_KEY=YOUR_REAL_NEWSAPI_KEY
+NEWSAPI_URL=https://newsapi.org/v2/everything
+NEWSAPI_DEFAULT_LANGUAGE=ru
+NEWSAPI_SORT_BY=publishedAt
+
+REQUEST_TIMEOUT_SECONDS=15
+REQUEST_MAX_RETRIES=3
+REQUEST_BACKOFF_FACTOR=1
+REQUEST_MAX_BACKOFF_SECONDS=30
+REQUEST_PAGE_SIZE_MAX=100
+MAX_PAGES_PER_REQUEST=50
+NEWSAPI_MAX_TOTAL_RESULTS=1000
+
+DB_CONNECT_TIMEOUT_SECONDS=10
+DB_STATEMENT_TIMEOUT_MS=45000

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements-dev.txt
+
+      - name: Ruff
+        run: ruff check .
+
+      - name: Compile
+        run: python -m compileall .
+
+      - name: Tests
+        run: pytest
+
+      - name: Bandit
+        run: bandit -r src config main.py
+
+      - name: Dependency audit
+        run: pip-audit

.gitignore

@@ -1,8 +1,13 @@
-.env
+.env
 .vscode/
 .venv/
 __pycache__/
 *.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Generated ETL artifacts
 data/raw/*
 !data/raw/.gitkeep
 data/clean/*

DockerFile

@@ -1,4 +1,4 @@
-FROM python:3.12-slim
+FROM python:3.12-slim
 
 WORKDIR /app
 
@@ -10,4 +10,10 @@ RUN pip install --no-cache-dir -r requirements.txt
 
 COPY . .
 
-CMD ["python", "main.py"]
+RUN useradd --create-home --shell /bin/bash etluser \
+    && mkdir -p /app/data/raw /app/data/clean \
+    && chown -R etluser:etluser /app
+
+USER etluser
+
+CMD ["python", "main.py", "--worker", "--bootstrap"]

README.md

@@ -1,92 +1,113 @@
-# NEWS_API_ETL_Project
+# NEWS_API_ETL_Project
 
-### Цель
-Обрабатывать из внешнего API новости и используя принцип ETL сохранять нужные новости в базу данных.
+Production-oriented ETL pipeline that collects articles from NewsAPI, validates/transforms them, and loads clean records into PostgreSQL.
 
-### Стек
-Extract: requests(страна, категория, ключевое слово, размер страницы (опционально)) -> сохранение статей в папку data/raw
+## What this project does
+1. `extract`: gets paginated articles from NewsAPI with timeout, retries, and backoff.
+2. `transform`: validates each article, normalizes fields and timestamps, and collects rejection stats.
+3. `load`: upserts articles and links them to user requests with deduplication.
+4. `worker`: atomically claims queued search requests from PostgreSQL and processes them safely.
 
-Transform: Python скрипт читает данные из нового файла data/raw, проверяет чтобы были указаны: автор, заголовок, описание не меньше 20 символов, url ссылка
-
-Load: psycopg2 подключается к PostgreSQL, перед вставкой разрешается конфликт с уникальной url ссылкой. Если такая ссылка уже есть то новость не добавляется в таблицу
-
-db: создается база данных и таблица если их еще нет. url присваивается UNIQUE
-
-Pipeline: программа запускается скриптом разделенным на 5 основных модулей (db.py, extract.py, load.py, transform.py, main.py)
-
-### Схема ETL
-Everything из NewsApi (extract) -> Филтр на наличие автора, заголовка, описания не меньше 20 символов, наличие url (transform) -> загрузка статей чей url отсутствует в базе данных (load)
-
-### Структура папок
+## Repository structure
 ```text
 project/
-├── config
-|   └── config.py
-├── data /
-|   ├──raw / # тут будут храниться статьи до обработки в формате json
-|   └──clean / # тут будут храниться статьи после обработки
-├── notebooks /
-|   └── 01_eda.ipynb
-├── src /
-|   ├── __init__.py
-|   ├── db.py
-|   ├── extract.py
-|   ├── load.py
-|   └── transform.py
-├──.env.example
+├── config/
+│   └── config.py
+├── data/
+│   ├── raw/
+│   └── clean/
+├── notebooks/
+│   └── 01_eda.ipynb
+├── src/
+│   ├── __init__.py
+│   ├── db.py
+│   ├── extract.py
+│   ├── load.py
+│   ├── pipeline.py
+│   ├── transform.py
+│   └── worker.py
+├── .env.example
+├── DockerFile
+├── docker-compose.yml
 ├── main.py
-└── requirements.txt
+├── requirements.txt
+└── requirements-dev.txt
 ```
 
-### Порядок запуска
-#### склонировать репозиторий 
+## Environment variables
+Copy `.env.example` to `.env` and fill your values:
+
 ```bash
-git clone [сслыка на репозиторий]
+cp .env.example .env
 ```
 
-#### перейти в папку проекта
+Key variables:
+- `NEWSAPI_KEY`: required for extract.
+- `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NEWS`.
+- Optional reliability settings: `REQUEST_MAX_RETRIES`, `REQUEST_TIMEOUT_SECONDS`, `MAX_PAGES_PER_REQUEST`, `DB_CONNECT_TIMEOUT_SECONDS`.
+
+## Local run
+### 1. Install
 ```bash
-cd <repo_name>
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
 ```
-#### создать виртуальное окружение
+
+### 2. Initialize DB objects
 ```bash
-py -m venv .venv
+python main.py --init-only
 ```
-после чего
+Alternative for one-shot run: add `--bootstrap` to any run command below.
+
+### 3. Debug run (raw/clean JSON + DB table `bad_news_bears`)
 ```bash
-.venv\Scripts\Activate.ps1
+python main.py --debug --keyword python --limit 20 --page_size 50 --language en
 ```
 
-#### установить библиотеки
-``` bash
-pip install -r requirements.txt
+### 4. Web-mode run (requires existing `app_users` and `search_requests` rows)
+```bash
+python main.py --keyword python --limit 20 --page_size 50 --language en --user_id 1 --search_request_id 1
 ```
 
-#### скопировать .env.exsample
-``` bash
-copy .env.example .env
+### 5. Worker loop
+```bash
+python main.py --worker --poll_interval 3
 ```
-Заполнить .env вашими данными
 
-#### запустить код
+## Docker
+Run app + Postgres with Docker Compose:
+
 ```bash
-python main.py --keyword your_key_word --limit your_articles_limit --page_size your_page_size
+docker compose up --build
 ```
 
-### пример .env
-```.env
-DB_HOST=localhost
-DB_PORT=5432
-DB_USER=postgres
-DB_PASSWORD=1234
-DB_ADMIN_DB=postgres
-DB_NEWS=db_news
-NEWSAPI_KEY =your_key
+By default, app container runs worker mode.
+
+## Quality checks
+```bash
+python -m compileall .
+ruff check .
+pytest -q
+bandit -r src config main.py
+pip-audit
 ```
 
-### Важные моменты
-В папку data/raw сохраняются все статьи которые были получены за 1 запрос по вашим критериям. Им в качестве имени присваивается текущее дата-время, ключевое слово и текущая страница. 
+## Reliability and safety guarantees
+- Request retry with backoff and HTTP status handling (`429`, `5xx`).
+- Input validation in transform layer (bad records are rejected with reason stats).
+- Idempotent article upsert by URL.
+- Atomic worker dequeue (`FOR UPDATE SKIP LOCKED`) to avoid duplicate processing across workers.
+- DB connection timeout and statement timeout support.
+
+## Notes
+- `.env`, `.venv`, `__pycache__`, and generated files under `data/raw` and `data/clean` are ignored by git.
+- Keep secrets only in `.env` (never commit real keys).
 
-В папку data/clean попадают все статьи которые имеют: автора, заголовок, описание 20+ символов и url ссылку. им присвается имя аналогичным способом что и в data/raw однако первым словом в имени является cleaned
+## Troubleshooting
+- `Database 'news_db' does not exist`:
+  - Run `python main.py --init-only` once, or add `--bootstrap` to your run command.
+- `password authentication failed`:
+  - Verify `.env` values `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`.
+  - Manually test credentials with psql/pgAdmin for the same host/port/user.
 
-В папке data/clean/stats содержит статистику по отклоненным статьям. Считаются все недочеты статей, а так же высчитывается первая блокирующая ошибка каждой статьи.