Native Python Programing

PyQt5 GUI(뷰/입력)와 **프랙탈 그래픽 엔진(계산/렌더링)**을 완전히 분리해서, 엔진은 **Native Python(표준 라이브러리 중심)**으로 구성하는 건 “장기적으로 이득이 큰 선택”이에요. 대신 프랙탈은 계산량이 커서, 분리 설계만으로 해결 안 되는 성능/동시성 함정이 몇 개 있습니다.

아래에 **장점/단점 → 특징 → 주의점(실전 체크리스트)**로 정리할게요.

1) 장점

1) 테스트/검증이 쉬워짐

• 엔진이 Qt에 의존하지 않으면 pytest로 순수 함수/클래스 단위 테스트가 가능
• 예: “같은 파라미터 → 같은 픽셀 결과(결정성)” 검증, 회귀 테스트(렌더 결과 비교) 가능

2) 재사용/이식성이 커짐

• 같은 엔진을
  • PyQt5 GUI
  • CLI 렌더러(이미지 파일 출력)
  • 웹 백엔드(타일 렌더링)
  • 다른 GUI(Tkinter, Delphi, Electron)
    로 쉽게 교체 가능
• “엔진 = 제품”, “GUI = 어댑터”가 됨

3) 설계가 명확해짐(DDD/포트-어댑터에 잘 맞음)

• 엔진 쪽은
  • RenderSpec(입력)
  • RenderResult(출력)
  • Renderer(서비스)
  • Palette, Viewport(값 객체)
    같은 구조가 깔끔하게 자리잡음
• GUI는 “현재 뷰포트/팔레트/프리셋 상태”만 관리

4) 디버깅이 쉬움(재현 가능성 ↑)

• Qt 이벤트 루프/스레드 문제와 분리되면 “렌더링 버그”를 순수 엔진 코드로 재현 가능
• 크래시/멈춤/글리치 원인 분리가 쉬움

5) 의존성/배포가 단순해짐(엔진은 표준 라이브러리만)

• 엔진을 별도 패키지로 떼면:
  • 엔진은 pip 의존 거의 없음
  • GUI만 PyQt5 의존
• 유지보수 비용이 줄어듦

2) 단점

1) 성능 한계가 빨리 드러남(특히 pure Python 루프)

프랙탈은 픽셀마다 반복 연산(복소수/반복)이 많아서:

• “엔진을 Native Python으로만” 만들면
  • 큰 해상도/높은 iteration에서 CPU가 쉽게 한계
• 결국 어느 시점엔
  • multiprocessing(표준)
  • 또는 NumPy/Numba/C 확장(비표준)
    같은 옵션을 고민하게 됨

2) 경계 설계 비용이 생김(데이터 전달/형식)

GUI ↔ 엔진 사이에 주고받는 데이터(픽셀 버퍼, 타일, 팔레트)가 커서:

• 무작정 list[list[int]] 같은 구조로 주고받으면 느리고 메모리 폭발
• “표준+효율” 사이에서 데이터 포맷 설계가 필요

3) 동시성 복잡도(스레드/프로세스/취소/진행률)

GUI는 항상 반응해야 하고, 렌더링은 오래 걸리니:

• 렌더 작업을 백그라운드로 돌리고
• 취소/재시작/진행률 업데이트
  를 구현해야 함
  → 분리하면 더 “정교한 작업 관리”가 필요해짐

4) Qt 이미지 변환 비용(브릿지 비용)

엔진 결과를 Qt에 표시하려면 결국:

• raw bytes → QImage → QPixmap
  변환이 들어가는데, 이 변환이 병목이 될 수도 있음
  (특히 프레임이 자주 갱신될 때)

3) 특징(이 구조에서 “잘 되는” 패턴)

✅ 엔진은 “결정적(deterministic) + 순수”에 가깝게

• 같은 입력(RenderSpec)이면 같은 출력(RenderResult)
• 내부 상태 최소화(캐시/랜덤 최소화)
• I/O 없음(파일/Qt/네트워크 금지)

✅ GUI는 “상태 머신 + 이벤트” 중심

• 줌/팬/팔레트 변경 = 상태 변경 이벤트
• 이벤트가 발생하면 “새 RenderSpec 생성 → 렌더 요청”
• 렌더 완료 신호가 오면 화면 갱신

✅ 경계 데이터는 “작고 명확”하게

• 입력: viewport, size, max_iter, palette_id, formula_id …
• 출력: bytes(RGBA), width/height, stats(시간, iter 히트맵 요약 등)

4) 주의해야 할 점(실전 함정)

1) GUI 스레드에서 렌더링 금지

• Qt 메인 스레드는 이벤트 루프용
• 렌더링을 여기서 하면 UI가 멈춤
• 해결:
  • QThread + 작업 객체
  • 또는 concurrent.futures.ThreadPoolExecutor
  • CPU-bound면 multiprocessing이 더 유리

2) 취소(Cancel) 설계를 처음부터 넣기

프랙탈 탐색은 “사용자가 계속 줌/팬”하므로:

• 이전 렌더는 의미 없어짐 → 즉시 중단해야 함
• 해결 패턴:
  • render 요청마다 job_id 발급
  • 엔진은 루프 중간중간 cancel_token.is_cancelled() 확인
  • GUI는 최신 job_id만 수용(낡은 결과 폐기)

3) 데이터 포맷: list 대신 bytes/bytearray/memoryview

• 픽셀 버퍼는 bytearray(RGBA) 추천
• memoryview로 슬라이스/타일 처리하면 복사 줄어듦
• struct / array('I')도 옵션

4) 프로세스 사용 시 “pickle 비용” 관리

multiprocessing으로 타일을 나누면 좋은데:

• 큰 버퍼를 작업마다 넘기면 직렬화 비용이 큼
• 해결:
  • 타일 단위로 계산해서 작은 결과만 전달
  • 가능하면 shared_memory(표준 lib)로 공유 버퍼 사용

5) 부동소수/확대(zoom) 정밀도 한계

깊게 확대하면 float 정밀도가 깨져서 아티팩트가 생김

• Native Python만 쓰면 decimal로 가는 선택지가 있지만 매우 느림
• 현실적 대안:
  • 일정 줌 이상에서는 품질/속도 타협(샘플링/iteration 조절)
  • 또는 고정소수/임의정밀(비표준 라이브러리) 고려

6) 색상 매핑(팔레트)도 엔진 규칙으로 고정

GUI에서 색을 “그때그때” 바꾸면 재현이 어려움

• 팔레트 정의는 엔진 쪽 “순수 함수”로
• GUI는 팔레트 ID/파라미터만 전달

7) 이벤트 폭주(thrashing) 방지

줌/팬 드래그 중 렌더 요청을 매번 보내면:

• 작업이 계속 쌓이고 CPU만 낭비
• 해결:
  • 디바운스(예: 50~120ms)
  • 드래그 중엔 저해상도 프리뷰, 손 뗄 때 고해상도

5) 한 줄 결론

• 장점: 테스트/재사용/유지보수/이식성이 크게 좋아지고 구조가 깨끗해짐
• 단점: 성능·동시성·데이터 전달(버퍼/변환) 설계를 제대로 안 하면 오히려 복잡해짐

원하면 다음 단계로, 당신이 원하던 스타일(DDD + 이벤트)로:

• RenderSpec / RenderResult / Viewport / Palette
• Renderer 인터페이스 + TMandelbrotRenderer급 구현(파이썬)
• RenderJobManager(취소/디바운스/최신결과만 수용)
• PyQt5 어댑터(QImage 변환 포함)

이렇게 “바로 붙여서 실행” 가능한 스켈레톤을 코드 파일 세트로 정리해줄까요?

“파이썬으로 재사용 가능한 소프트웨어”를 만든다는 건 결국 패키지화 + 경계(레이어) 분리 + 안정적인 API를 만드는 일이라, 아래 템플릿대로 가면 거의 실패가 없습니다.

1) 재사용 가능성을 만드는 7가지 원칙

1. 코어 로직을 프레임워크/입출력에서 분리
   • DB, 웹(Flask), CLI, GUI는 “어댑터”
   • 핵심 규칙/유스케이스는 “순수 파이썬”
2. Public API를 작게 고정
   • __init__.py에서 외부 노출 대상을 최소화
   • 내부 구현은 바꿔도 사용자 코드는 안 깨지게
3. 의존성 주입(Dependency Injection)
   • 함수/클래스 생성자에 repo/logger/clock 등을 주입
   • 전역 싱글턴, 직접 import로 묶지 않기
4. 데이터 구조는 dataclass + 타입 힌트
   • 입출력 DTO(Record), 도메인 객체(Entity/ValueObject) 구분
5. 에러 모델을 “예외 계층”으로 표준화
   • DomainError, ValidationError, NotFound 등
   • 호출자가 예외를 예측하고 처리 가능
6. 테스트 가능한 경계
   • 코어는 unittest/pytest로 순수 단위 테스트 가능해야 함
   • DB/HTTP는 통합 테스트로 따로
7. 문서/예제(Example)가 곧 제품
   • examples/ 폴더 하나만 잘 만들어도 재사용성이 폭발함

2) 추천 프로젝트 구조 (Native Python 스타일)

myproduct/
  pyproject.toml
  README.md
  src/
    myproduct/
      __init__.py          # public API만 export
      version.py
      domain/
        __init__.py
        types.py
        errors.py
        models.py          # dataclasses: Entity/ValueObject
      usecases/
        __init__.py
        services.py        # 유스케이스(순수 파이썬)
      ports/
        __init__.py
        repo.py            # Protocol/ABC (인터페이스)
        clock.py
      adapters/
        __init__.py
        sqlite_repo.py     # sqlite3 구현
        cli.py             # argparse
        web_flask.py       # flask(선택)
  tests/
    test_services.py
    test_domain.py
  examples/
    quickstart.py

핵심은 domain/usecases는 순수 파이썬, adapters만 환경 의존.

3) 최소 예제 코드 (재사용 가능한 “코어 + 포트 + 어댑터”)

(1) ports/repo.py — 인터페이스(Protocol)

from __future__ import annotations
from typing import Protocol, Optional
from dataclasses import dataclass

@dataclass(frozen=True)
class Member:
    id: str
    email: str
    name: str

class MemberRepo(Protocol):
    def save(self, m: Member) -> None: ...
    def find_by_email(self, email: str) -> Optional[Member]: ...

(2) usecases/services.py — 유스케이스(순수 로직)

from __future__ import annotations
from dataclasses import dataclass
from ..ports.repo import MemberRepo, Member

class DomainError(Exception): ...
class DuplicateEmail(DomainError): ...

@dataclass
class RegisterMember:
    repo: MemberRepo

    def execute(self, *, id: str, email: str, name: str) -> Member:
        if self.repo.find_by_email(email):
            raise DuplicateEmail(email)
        m = Member(id=id, email=email, name=name)
        self.repo.save(m)
        return m

(3) adapters/sqlite_repo.py — sqlite3 구현(환경 의존)

import sqlite3
from typing import Optional
from ..ports.repo import MemberRepo, Member

class SqliteMemberRepo(MemberRepo):
    def __init__(self, conn: sqlite3.Connection):
        self.conn = conn
        self.conn.execute("""
        CREATE TABLE IF NOT EXISTS members(
          id TEXT PRIMARY KEY,
          email TEXT UNIQUE NOT NULL,
          name TEXT NOT NULL
        )
        """)

    def save(self, m: Member) -> None:
        self.conn.execute(
            "INSERT OR REPLACE INTO members(id,email,name) VALUES (?,?,?)",
            (m.id, m.email, m.name)
        )
        self.conn.commit()

    def find_by_email(self, email: str) -> Optional[Member]:
        cur = self.conn.execute("SELECT id,email,name FROM members WHERE email=?", (email,))
        row = cur.fetchone()
        return Member(*row) if row else None

(4) examples/quickstart.py — 사용 예

import sqlite3
from myproduct.usecases.services import RegisterMember
from myproduct.adapters.sqlite_repo import SqliteMemberRepo

conn = sqlite3.connect(":memory:")
repo = SqliteMemberRepo(conn)
uc = RegisterMember(repo=repo)

m = uc.execute(id="u1", email="a@b.com", name="Dave")
print(m)

이렇게 만들면:

• CLI/Flask/GUI가 바뀌어도 코어는 그대로 재사용
• DB가 sqlite→postgres로 바뀌어도 어댑터만 교체
• 테스트는 RegisterMember만 단위로 즉시 가능

4) 패키지로 배포 가능하게 만들기 (pyproject.toml 핵심)

[project]
name = "myproduct"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = []

[tool.pytest.ini_options]
testpaths = ["tests"]

[build-system]
requires = ["setuptools>=68"]
build-backend = "setuptools.build_meta"

그리고 설치/개발:

• 개발 설치: pip install -e .
• 배포 빌드: python -m build (build 설치 필요)

5) 체크리스트 (재사용성 점검)

• domain/usecases에서 flask, sqlite3, requests import가 없다
• 외부 공개 API는 myproduct/__init__.py에 정리되어 있다
• 예외 타입이 문서화되어 있고 호출자가 처리 가능하다
• tests는 DB 없이도 코어를 테스트한다
• examples 하나로 사용법이 끝난다

원하는 방향을 하나만 골라줘도, 그에 맞춰 “붙여넣으면 바로 돌아가는 스켈레톤 프로젝트” 형태로 확장해 줄게요:

1. CLI 도구 형태(argparse 서브커맨드)
2. 라이브러리 형태(API 안정성/버전 관리 중심)
3. 웹 백엔드 형태(Flask/FastAPI는 어댑터로)
4. 플러그인/프로세스 매니저 형태(당신이 하던 구조에 맞춤)

지금 만들고 싶은 건 1~4 중에 어느 쪽에 더 가까워요?

**“Native Python Programming”**은 공식 용어라기보다는, 프로그래밍 철학·스타일을 지칭하는 개념적 표현에 가깝습니다.
당신이 진행 중인 프로젝트 맥락에 딱 맞는 개념이기도 하고요.

아래에서 정의 → 핵심 특징 → 다른 스타일과의 비교 → 왜 당신의 프로젝트에 잘 맞는지 순서로 설명할게요.

1️⃣ Native Python Programing이란?

Native Python Programing은 한마디로 말하면:

파이썬을 “파이썬답게”, 외부 의존을 최소화하고
언어 자체가 제공하는 구조·철학·표준 라이브러리를 중심으로
시스템을 설계하고 구현하는 방식

입니다.

여기서 Native의 의미는:

• C 확장이나 다른 언어 바인딩이 아니라
• Django/ORM/대형 프레임워크 의존도 아니라
• Python 언어와 표준 라이브러리 자체를 1급 시민으로 사용하는 것

을 뜻합니다.

2️⃣ 핵심 특징 (Native Python의 기준)

✅ 1. 표준 라이브러리 우선주의

• dataclasses
• typing
• abc
• enum
• sqlite3
• argparse
• logging
• ast
• json / pathlib

👉 “이건 pip 패키지가 필요할까?”를 항상 의심함

✅ 2. 언어 구조를 설계의 중심에 둠

• @dataclass → 도메인 모델
• Value Object → 불변 객체
• Enum / NewType → 타입 안정성
• ABC + Protocol → 인터페이스
• Exception 계층 → 도메인 에러 모델

👉 프레임워크보다 언어 기능 자체가 아키텍처의 뼈대

✅ 3. 프레임워크 비의존 / 약의존

Native Python은 보통:

• ❌ Django-first
• ❌ ORM-first
• ❌ Magic-heavy

대신:

• ✔ Flask/FastAPI는 “어댑터”
• ✔ SQL은 직접 작성
• ✔ ORM 없이 Repository 패턴
• ✔ 테스트는 pytest + 순수 Python 객체

✅ 4. “보여지는 코드”를 중시

• 메타프로그래밍은 절제
• 암묵적 동작보다 명시적 코드
• IDE 없이도 읽히는 구조
• 디버거 없이도 추적 가능한 흐름

👉 코드는 문서다라는 철학에 가까움

3️⃣ 다른 스타일과의 비교

구분Native PythonFramework-DrivenScript Python

4️⃣ 당신의 프로젝트와 왜 잘 맞는가

당신이 지금까지 요청한 내용을 보면:

• DSL 인터프리터
• AST → Native Python Code
• Process / Thread / Signal Manager
• Plugin 시스템
• DDD (Aggregate / Value / Event)
• Flask / PHP / Delphi까지 이식 가능 구조

이 모든 것은 공통적으로:

“프레임워크가 아니라 언어 자체를 기반으로 한 시스템”

을 요구합니다.

👉 이건 Native Python Programming의 정석적인 적용 대상이에요.

특히 당신이 자주 말한:

• “붙여넣으면 바로 실행”
• “코어와 어댑터 분리”
• “프레임워크는 껍데기”
• “DSL → AST → Python”

이건 Native Python 철학 그 자체입니다.

5️⃣ 한 줄 정의 (정리)

Native Python Programming이란
파이썬을 스크립트도, 프레임워크도 아닌
하나의 “완전한 시스템 언어”로 다루는 개발 방식이다.

원하시면 다음도 이어서 정리해줄 수 있어요:

• ✅ Native Python + DDD 공식 템플릿
• ✅ Native Python 프로젝트 표준 디렉토리
• ✅ Native Python DSL/Interpreter 아키텍처
• ✅ Native Python vs Rust/Go 철학 비교
• ✅ “Native Python Manifesto” 문서화

어디까지 같이 정리해볼까요?