Metadata-Version: 2.4
Name: godlights
Version: 0.1.6
Summary: GL: All In One (aio) - 여러 변수에 같은 attribute/함수를 한 번에 적용하는 유틸. godlights.image에 ArrayPixel 픽셀 콘솔 출력 유틸 포함.
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# godlights

GL: All In One (`aio`) — 여러 변수에 같은 attribute / 같은 함수를 한 번에 적용. 타입힌트가 있고 `py.typed` 마커가 포함돼 있어 mypy/IDE에서 타입 정보를 그대로 사용할 수 있습니다.

## 설치

```bash
pip install .          # 프로젝트 폴더에서
pip install -e .       # 개발용(편집 즉시 반영)
```

## 사용

```python
from godlights import allinone as aio   # 또는: from godlights import aio

class P:
    def __init__(self, hp): self.hp = hp
    def heal(self, amount):
        self.hp += amount
        return self.hp

a, b, c = P(10), P(20), P(30)

aio.call_all(a, b, c, argument="hp")    # [10, 20, 30]
aio.call_all(a, b, c, "hp")             # [10, 20, 30]

aio.set_all(a, b, c, argument="hp", value=100)   # a.hp = b.hp = c.hp = 100, [100, 100, 100] 반환

aio.zip_all(a, b, c, argument="hp", values=[10, 20, 30])   # a.hp, b.hp, c.hp = 10, 20, 30

x1, x2, x3 = aio.run_func(str.upper, "a", "b", "c")   # 'A', 'B', 'C'
d1, d2 = aio.run_func(lambda x, n: x**n, 2, 3, n=2)   # 4, 9

aio.call_method(a, b, c, method="heal", amount=10)   # [110, 110, 110]

aio.flatten_call([a, b, c], argument="hp")   # [110, 110, 110]

aio.condition_all(a, b, c, argument="hp", predicate=lambda hp: hp > 50)   # [True, True, True]

# 예외 안전 버전: 일부 변수에서 실패해도 전체가 죽지 않고 그 자리만 default(기본 None)로 채움
aio.safe_call_all(a, b, c, argument="mp")                 # mp가 없으면 그 자리는 None
aio.safe_run_func(int, "1", "x", "3")                      # [1, None, 3] ("x" 변환 실패)

# 결과를 바로 출력하고 싶으면 뒤에 .print()를 붙이면 됨 (출력 후 같은 값을 그대로 반환)
aio.call_all(a, b, c, argument="hp").print()   # 콘솔에 [110, 110, 110] 출력
```

## 함수

- `call_all(*args, argument)` — 각 변수의 `argument` attribute를 리스트로 반환.
- `set_all(*args, argument, value)` — 각 변수의 `argument` attribute에 동일한 `value`를 한 번에 설정하고, 설정된 값들을 리스트로 반환.
- `zip_all(*args, argument, values)` — 각 변수의 `argument` attribute에 `values`를 순서대로 하나씩 짝지어 설정하고, 설정된 값들을 리스트로 반환. `values` 개수는 변수 개수와 같아야 함.
- `run_func(function, *args, **kwargs)` — `function(arg)`를 각 arg마다 실행해 리스트로 반환. `kwargs`는 공통 전달.
- `call_method(*args, method, **kwargs)` — 각 변수의 같은 메서드를 동일 kwargs로 호출해 결과를 리스트로 반환.
- `flatten_call(iterable, argument)` — list/tuple 등에 든 변수들의 같은 attribute를 리스트로 반환.
- `condition_all(*args, argument, predicate)` — 각 변수의 `argument` attribute가 `predicate`를 만족하는지 bool 리스트로 반환. `SimpleList.filter()`와 짝을 이루는 조회용 헬퍼.
- `safe_call_all(*args, argument, default=None)` — `call_all`의 예외 안전 버전. attribute가 없는 변수 자리는 예외 대신 `default`로 채움.
- `safe_run_func(function, *args, default=None, **kwargs)` — `run_func`의 예외 안전 버전. `function` 호출이 실패한 자리는 예외 대신 `default`로 채움.

모든 `*args` 헬퍼(`call_all`, `set_all`, `zip_all`, `call_method`)는 `argument`/`method`를 키워드로 넘기거나, 마지막 위치 인자로 넘길 수 있습니다.

## `SimpleList`로 결과 체이닝하기

위 5개 함수(`call_all`, `set_all`, `run_func`, `call_method`, `flatten_call`)는 모두 일반 `list`처럼 동작하는 `SimpleList`를 반환합니다. `SimpleList`에는 출력/집계/필터/저장용 메서드가 붙어 있어 결과를 바로 체이닝할 수 있습니다. `SimpleList`는 `godlights.util`에 있고(다른 서브모듈에서도 재사용하는 공용 유틸), 최상위 `godlights`에서도 바로 import할 수 있습니다.

```python
from godlights.util import SimpleList   # 또는: from godlights import SimpleList

# 출력하고 같은 값을 그대로 반환 (체이닝 가능)
aio.call_all(a, b, c, argument="hp").print()   # 콘솔에 [110, 110, 110] 출력

# 집계
aio.call_all(a, b, c, argument="hp").sum()    # 330
aio.call_all(a, b, c, argument="hp").avg()    # 110.0
aio.call_all(a, b, c, argument="hp").min()    # 110
aio.call_all(a, b, c, argument="hp").max()    # 110

# filter / map (결과도 SimpleList라 계속 체이닝 가능)
aio.call_all(a, b, c, argument="hp").filter(lambda hp: hp > 50).print()
aio.call_all(a, b, c, argument="hp").map(lambda hp: hp * 2).print()

# 파일로 저장 (self를 반환하므로 이어서 체이닝 가능)
aio.call_all(a, b, c, argument="hp").save("hp.txt")           # 한 줄에 하나씩 저장
aio.call_all(a, b, c, argument="hp").to_csv("hp.csv", header="hp")

result = aio.call_all(a, b, c, argument="hp")
assert isinstance(result, SimpleList)
assert result == [110, 110, 110]
```

## `godlights.image` — 픽셀 데이터를 콘솔에 출력하기

`ArrayPixel`은 grayscale/rgb 2차원 픽셀 데이터를 ANSI 색상 블록으로 콘솔에 출력하는 유틸입니다. `Generator`는 색상 프리셋(`mode`)과 시작 방위(`starts`)로 그라데이션 rgb 데이터를 만들어줍니다.

```python
from godlights.image import ArrayPixel, Generator

gray_data = ArrayPixel.make_sample_gradient(16, 16, "grayscale")   # 데모용 명암 그라데이션
gray_pixel = ArrayPixel(size="16x16", data=gray_data, type="grayscale")
gray_pixel.print()

rgb_pixel = ArrayPixel(size="16x16", data=Generator(mode="blue", starts="ne").rgb, type="rgb")
rgb_pixel.print()
```

- `ArrayPixel(size, data, type)` — `size`는 `"16x16"` 형식 문자열, `type`은 `"grayscale"`(0~255 int) 또는 `"rgb"`((r,g,b) 0~255 tuple). `.print()`는 self를 반환해 체이닝 가능.
- `ArrayPixel.make_sample_gradient(width, height, type="grayscale", *, starts="nw")` — 데모/테스트용 그라데이션 데이터 생성.
- `Generator(mode, starts, width=16, height=16).rgb` — `mode`(색상 프리셋: `red`/`green`/`blue`/`yellow`/`cyan`/`magenta`/`orange`/`white`)와 `starts`(시작 방위: `n`/`s`/`e`/`w`/`ne`/`nw`/`se`/`sw`/`c`, `c`는 중앙에서 밝은 방사형 그라데이션)로 rgb 데이터를 계산.

`starts`는 가장 밝은(grayscale=255, rgb=프리셋 색상 그대로) 지점이고, 반대쪽으로 갈수록 어두워집니다(0 / 검정).

> 터미널이 24bit true color를 지원해야 색상이 제대로 보입니다 (대부분의 최신 터미널은 지원).

## 빌드 / 배포

```bash
pip install build twine
python -m build            # dist/ 에 sdist, wheel 생성
twine upload dist/*        # PyPI 업로드
```

## 테스트

```bash
pip install pytest
pip install -e .
pytest
```

## CI/CD

- `.github/workflows/test.yml` — push/PR마다 Python 3.8~3.12에서 pytest 실행
- `.github/workflows/publish.yml` — GitHub Release를 publish하면 빌드 후 PyPI에 업로드 (Trusted Publishing/OIDC 사용, PyPI 프로젝트 설정에서 이 저장소를 trusted publisher로 먼저 등록해야 함)

## 로드맵

앞으로 추가할 계획인 기능은 [TODO.md](TODO.md) 참고.
