6.4. Environment variables

   stdout подключён к терминалу  ──►  line buffering
                                       (сброс после каждой строки)

   stdout перенаправлен в канал  ──►  block buffering
   или файл                            (сброс при заполнении ~8 KB)

   приложение печатает "старт"      ──►  4 байта в буфере
   приложение работает 10 минут     ──►  буфер не заполнен, ничего не выведено
   docker logs                      ──►  пусто
   приложение падает                ──►  буфер потерян, логов нет

RUN python -m compileall -q /opt/venv/lib

RUN python -m compileall -q --invalidation-mode checked-hash /opt/venv/lib

   без валидации:
   старт → healthcheck healthy → трафик пошёл → первый запрос → падение

   с валидацией:
   старт → падение с понятным сообщением → оркестратор не пускает трафик

docker exec <container> sh -c "tr '\0' '\n' < /proc/1/environ"

sys.stdout.reconfigure(line_buffering=True)

mkdir -p /tmp/pyenv && cd /tmp/pyenv

cat > buffered.py <<'PY'
import time

print("первая строка — появится сразу?")
time.sleep(5)
print("вторая строка")
PY

cat > Dockerfile.buffered <<'EOF'
FROM python:3.13-slim
COPY buffered.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.buffered -t env:buffered . > /dev/null

docker run -d --name buf env:buffered > /dev/null
sleep 2
echo "логи через 2 секунды после старта:"
docker logs buf 2>&1 | sed 's/^/  /' || echo "  (пусто)"
echo "  строк: $(docker logs buf 2>&1 | wc -l)"
sleep 5
echo "логи после завершения:"
docker logs buf 2>&1 | sed 's/^/  /'
docker rm -f buf > /dev/null

логи через 2 секунды после старта:
  строк: 0
логи после завершения:
  первая строка — появится сразу?
  вторая строка

# способ 1: переменная окружения
cat > Dockerfile.unbuffered <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY buffered.py /app.py
CMD ["python", "/app.py"]
EOF

# способ 2: флаг -u
cat > Dockerfile.flag <<'EOF'
FROM python:3.13-slim
COPY buffered.py /app.py
CMD ["python", "-u", "/app.py"]
EOF

for v in unbuffered flag; do
    docker build -q -f "Dockerfile.$v" -t "env:$v" . > /dev/null
    docker run -d --name "t-$v" "env:$v" > /dev/null
    sleep 2
    printf '%-12s строк в логах через 2 c: %s\n' "$v" "$(docker logs "t-$v" 2>&1 | wc -l)"
    docker rm -f "t-$v" > /dev/null
done

unbuffered   строк в логах через 2 c: 1
flag         строк в логах через 2 c: 1

cat > with_library.py <<'PY'
"""Демонстрация: flush=True в своём коде не влияет на библиотеки."""
import subprocess
import sys
import time

print("моя строка с flush", flush=True)

# Имитация сторонней библиотеки, которая пишет в stdout без flush
code = "import time; print('строка из библиотеки'); time.sleep(4)"
subprocess.run([sys.executable, "-c", code], check=False)
PY

cat > Dockerfile.lib <<'EOF'
FROM python:3.13-slim
COPY with_library.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.lib -t env:lib . > /dev/null
docker run -d --name lib-test env:lib > /dev/null
sleep 2
echo "через 2 секунды видно:"
docker logs lib-test 2>&1 | sed 's/^/  /'
docker rm -f lib-test > /dev/null

через 2 секунды видно:
  моя строка с flush

docker run --rm -d --name lib-fixed -e PYTHONUNBUFFERED=1 env:lib > /dev/null
sleep 2
echo "с PYTHONUNBUFFERED=1:"
docker logs lib-fixed 2>&1 | sed 's/^/  /'
docker rm -f lib-fixed > /dev/null 2>&1 || true

с PYTHONUNBUFFERED=1:
  моя строка с flush
  строка из библиотеки

cat > Dockerfile.pyc-default <<'EOF'
FROM python:3.13-slim
RUN pip install --no-cache-dir fastapi==0.141.1
CMD ["python", "-c", "import fastapi; print('импортирован')"]
EOF

cat > Dockerfile.pyc-off <<'EOF'
FROM python:3.13-slim
ENV PYTHONDONTWRITEBYTECODE=1
RUN pip install --no-cache-dir fastapi==0.141.1
CMD ["python", "-c", "import fastapi; print('импортирован')"]
EOF

cat > Dockerfile.pyc-precompiled <<'EOF'
FROM python:3.13-slim
ENV PYTHONDONTWRITEBYTECODE=1
RUN pip install --no-cache-dir fastapi==0.141.1 \
 && python -m compileall -q --invalidation-mode checked-hash \
        /usr/local/lib/python3.13/site-packages
CMD ["python", "-c", "import fastapi; print('импортирован')"]
EOF

for v in pyc-default pyc-off pyc-precompiled; do
    docker build -q -f "Dockerfile.$v" -t "env:$v" . > /dev/null
    count="$(docker run --rm --entrypoint sh "env:$v" -c \
        'find /usr/local/lib/python3.13/site-packages -name "*.pyc" | wc -l')"
    size="$(docker images "env:$v" --format '{{.Size}}')"
    printf '%-18s .pyc: %-6s размер: %s\n' "$v" "$count" "$size"
done

pyc-default        .pyc: 1834   размер: 251MB
pyc-off            .pyc: 1834   размер: 251MB
pyc-precompiled    .pyc: 1834   размер: 251MB

cat > mymodule.py <<'PY'
def hello():
    return "привет"
PY

cat > Dockerfile.runtime-pyc <<'EOF'
FROM python:3.13-slim
WORKDIR /app
COPY mymodule.py .
CMD ["sh", "-c", "python -c 'import mymodule; print(mymodule.hello())'; find /app -name '*.pyc' | wc -l"]
EOF

cat > Dockerfile.runtime-nopyc <<'EOF'
FROM python:3.13-slim
ENV PYTHONDONTWRITEBYTECODE=1
WORKDIR /app
COPY mymodule.py .
CMD ["sh", "-c", "python -c 'import mymodule; print(mymodule.hello())'; find /app -name '*.pyc' | wc -l"]
EOF

for v in runtime-pyc runtime-nopyc; do
    docker build -q -f "Dockerfile.$v" -t "env:$v" . > /dev/null
    printf '%-16s ' "$v"
    docker run --rm "env:$v" | tr '\n' ' '
    echo
done

runtime-pyc      привет 1
runtime-nopyc    привет 0

docker run --rm -v "$PWD:/app" python:3.13-slim \
    python -c "import sys; sys.path.insert(0,'/app'); import mymodule"
ls -d __pycache__ 2>/dev/null && echo "  __pycache__ появился на host (принадлежит root)" || echo "  чисто"
sudo rm -rf __pycache__ 2>/dev/null || rm -rf __pycache__ 2>/dev/null

docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -v "$PWD:/app" python:3.13-slim \
    python -c "import sys; sys.path.insert(0,'/app'); import mymodule"
ls -d __pycache__ 2>/dev/null && echo "  __pycache__ появился" || echo "  с PYTHONDONTWRITEBYTECODE=1: чисто"

  __pycache__ появился на host (принадлежит root)
  с PYTHONDONTWRITEBYTECODE=1: чисто

cat > crash.py <<'PY'
"""Провоцирует сегфолт через ctypes."""
import ctypes

print("сейчас будет сегфолт", flush=True)
ctypes.string_at(0)   # разыменование нулевого указателя
PY

cat > Dockerfile.nofault <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY crash.py /app.py
CMD ["python", "/app.py"]
EOF

cat > Dockerfile.fault <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 \
    PYTHONFAULTHANDLER=1
COPY crash.py /app.py
CMD ["python", "/app.py"]
EOF

for v in nofault fault; do
    docker build -q -f "Dockerfile.$v" -t "env:$v" . > /dev/null
    echo "── $v ──"
    docker run --rm "env:$v" 2>&1 | tail -5 | sed 's/^/  /'
    echo "  код возврата: $(docker run --rm "env:$v" > /dev/null 2>&1; echo $?)"
done

── nofault ──
  сейчас будет сегфолт
  код возврата: 139
── fault ──
  сейчас будет сегфолт
  Fatal Python error: Segmentation fault
  
  Current thread 0x00007f8a2c1d5740 (most recent call first):
    File "/app.py", line 6 in <module>
  код возврата: 139

cat > config_app.py <<'PY'
"""Валидация конфигурации при старте."""
from __future__ import annotations

import os
import sys
from dataclasses import dataclass


@dataclass(frozen=True)
class Settings:
    database_url: str
    log_level: str
    workers: int
    timeout: float

    @classmethod
    def from_env(cls) -> Settings:
        errors: list[str] = []

        database_url = os.environ.get("DATABASE_URL", "")
        if not database_url:
            errors.append("DATABASE_URL обязателен")
        elif not database_url.startswith(("postgresql://", "postgres://")):
            errors.append(f"DATABASE_URL должен начинаться с postgresql://, получено: {database_url[:20]}")

        log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
        if log_level not in {"DEBUG", "INFO", "WARNING", "ERROR"}:
            errors.append(f"недопустимый LOG_LEVEL: {log_level}")

        raw_workers = os.environ.get("WEB_CONCURRENCY", "2")
        try:
            workers = int(raw_workers)
            if workers < 1:
                errors.append("WEB_CONCURRENCY должен быть >= 1")
        except ValueError:
            errors.append(f"WEB_CONCURRENCY должен быть числом, получено: {raw_workers!r}")
            workers = 0

        raw_timeout = os.environ.get("TIMEOUT", "30")
        try:
            timeout = float(raw_timeout)
        except ValueError:
            errors.append(f"TIMEOUT должен быть числом, получено: {raw_timeout!r}")
            timeout = 0.0

        if errors:
            print("ОШИБКА КОНФИГУРАЦИИ:", file=sys.stderr)
            for e in errors:
                print(f"  - {e}", file=sys.stderr)
            raise SystemExit(1)

        return cls(database_url, log_level, workers, timeout)


def main() -> int:
    settings = Settings.from_env()
    print("конфигурация корректна:")
    print(f"  log_level = {settings.log_level}")
    print(f"  workers   = {settings.workers}")
    print(f"  timeout   = {settings.timeout}")
    # секрет не печатаем целиком
    print(f"  database  = {settings.database_url.split('@')[-1]}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
PY

cat > Dockerfile.config <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    LOG_LEVEL=INFO \
    WEB_CONCURRENCY=2 \
    TIMEOUT=30
COPY config_app.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.config -t env:config . > /dev/null

echo "=== корректная конфигурация ==="
docker run --rm -e DATABASE_URL='postgresql://user:pass@db:5432/app' env:config

echo
echo "=== отсутствует обязательная переменная ==="
docker run --rm env:config 2>&1 | sed 's/^/  /'
echo "  код возврата: $(docker run --rm env:config > /dev/null 2>&1; echo $?)"

echo
echo "=== некорректные значения ==="
docker run --rm \
    -e DATABASE_URL='mysql://db/app' \
    -e LOG_LEVEL=VERBOSE \
    -e WEB_CONCURRENCY=abc \
    env:config 2>&1 | sed 's/^/  /'

=== корректная конфигурация ===
конфигурация корректна:
  log_level = INFO
  workers   = 2
  timeout   = 30.0
  database  = db:5432/app

=== отсутствует обязательная переменная ===
  ОШИБКА КОНФИГУРАЦИИ:
    - DATABASE_URL обязателен
  код возврата: 1

=== некорректные значения ===
  ОШИБКА КОНФИГУРАЦИИ:
    - DATABASE_URL должен начинаться с postgresql://, получено: mysql://db/app
    - недопустимый LOG_LEVEL: VERBOSE
    - WEB_CONCURRENCY должен быть числом, получено: 'abc'

docker run -d --name secret-env \
    -e DATABASE_URL='postgresql://admin:SuperSecret123@db:5432/app' \
    env:config sleep 60 > /dev/null 2>&1 || \
docker run -d --name secret-env --entrypoint sleep \
    -e DATABASE_URL='postgresql://admin:SuperSecret123@db:5432/app' \
    env:config 60 > /dev/null

echo "=== где виден пароль ==="
echo "1. docker inspect:"
docker inspect secret-env --format '{{range .Config.Env}}{{println "   " .}}{{end}}' | grep -i database

echo "2. /proc/1/environ внутри container:"
docker exec secret-env sh -c "tr '\0' '\n' < /proc/1/environ | grep DATABASE" | sed 's/^/   /'

echo "3. окружение процесса на host:"
CPID="$(docker inspect secret-env --format '{{.State.Pid}}')"
sudo tr '\0' '\n' < "/proc/$CPID/environ" 2>/dev/null | grep DATABASE | sed 's/^/   /'

docker rm -f secret-env > /dev/null

=== где виден пароль ===
1. docker inspect:
    DATABASE_URL=postgresql://admin:SuperSecret123@db:5432/app
2. /proc/1/environ внутри container:
   DATABASE_URL=postgresql://admin:SuperSecret123@db:5432/app
3. окружение процесса на host:
   DATABASE_URL=postgresql://admin:SuperSecret123@db:5432/app

cat > file_secret.py <<'PY'
import os
from pathlib import Path


def read_secret(name: str) -> str:
    """Читает секрет из файла; путь задаётся переменной с суффиксом _FILE."""
    file_var = f"{name}_FILE"
    if path := os.environ.get(file_var):
        return Path(path).read_text(encoding="utf-8").strip()
    return os.environ.get(name, "")


password = read_secret("DB_PASSWORD")
print(f"пароль прочитан, длина: {len(password)}")
print(f"в окружении DB_PASSWORD: {'есть' if os.environ.get('DB_PASSWORD') else 'НЕТ'}")
PY

echo -n 'SuperSecret123' > db_password.txt

cat > Dockerfile.filesecret <<'EOF'
FROM python:3.13-slim
ENV PYTHONUNBUFFERED=1
COPY file_secret.py /app.py
CMD ["python", "/app.py"]
EOF

docker build -q -f Dockerfile.filesecret -t env:filesecret . > /dev/null
docker run --rm \
    -v "$PWD/db_password.txt:/run/secrets/db_password:ro" \
    -e DB_PASSWORD_FILE=/run/secrets/db_password \
    env:filesecret

пароль прочитан, длина: 14
в окружении DB_PASSWORD: НЕТ

cat > Dockerfile.production <<'EOF'
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONFAULTHANDLER=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

WORKDIR /app
COPY config_app.py .
CMD ["python", "config_app.py"]
EOF

docker build -q -f Dockerfile.production -t env:prod . > /dev/null
docker image inspect env:prod --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -E 'PYTHON|PIP'

PYTHONUNBUFFERED=1
PYTHONDONTWRITEBYTECODE=1
PYTHONFAULTHANDLER=1
PIP_DISABLE_PIP_VERSION_CHECK=1

cd /tmp
docker rmi -f $(docker images -q --filter 'reference=env:*') 2>/dev/null || true
rm -rf /tmp/pyenv

docker run --rm python:3.13-slim python -c "
import sys
print('буферизация stdout:', 'нет' if not sys.stdout.line_buffering else 'построчная')
"
docker run --rm -e PYTHONUNBUFFERED=1 python:3.13-slim python -c "
import sys
print('с PYTHONUNBUFFERED, line_buffering:', sys.stdout.line_buffering)
"