API 참조

Atio의 모든 함수와 클래스에 대한 상세한 API 문서입니다.

주요 함수

Core 모듈

write()

안전한 원자적 파일 쓰기를 수행하는 메인 함수입니다.

atio.write(obj, target_path=None, format='parquet', **kwargs)

매개변수

obj – 저장할 데이터 객체 (pandas.DataFrame, polars.DataFrame, numpy.ndarray)
target_path – 저장할 파일 경로 (파일 저장 시 필수)
format – 저장 형식 (‘csv’, ‘parquet’, ‘excel’, ‘json’, ‘sql’, ‘database’)
show_progress – 진행률 표시 여부 (기본값: False)
verbose – 상세 성능 정보 출력 여부 (기본값: False)
**kwargs –
형식별 추가 매개변수

반환

None

Raises

ValueError, IOError, DatabaseError

사용 예제:

import atio
import pandas as pd

df = pd.DataFrame({"a": [1, 2, 3]})

# 기본 사용법
atio.write(df, "data.parquet", format="parquet")

# 진행률 표시
atio.write(df, "data.parquet", format="parquet", show_progress=True)

# 성능 정보 출력
atio.write(df, "data.parquet", format="parquet", verbose=True)

write_snapshot()

데이터 스냅샷을 생성하여 버전 관리를 수행합니다.

atio.write_snapshot(obj, table_name, format='parquet', **kwargs)

매개변수

obj – 저장할 데이터 객체
table_name – 테이블 이름 (스냅샷 디렉토리명)
format – 저장 형식
**kwargs –
추가 매개변수

반환

생성된 스냅샷 ID

사용 예제:

# 스냅샷 생성
snapshot_id = atio.write_snapshot(df, "users", format="parquet")
print(f"생성된 스냅샷 ID: {snapshot_id}")

read_table()

스냅샷에서 데이터를 읽어옵니다.

atio.read_table(table_name, snapshot_id='latest', format='parquet', **kwargs)

매개변수

table_name – 테이블 이름
snapshot_id – 스냅샷 ID (기본값: ‘latest’)
format – 읽을 형식
**kwargs –
추가 매개변수

반환

데이터 객체

사용 예제:

# 최신 스냅샷 읽기
df = atio.read_table("users", format="parquet")

# 특정 스냅샷 읽기
df = atio.read_table("users", snapshot_id="20240101_120000", format="parquet")

expire_snapshots()

오래된 스냅샷을 정리합니다.

atio.expire_snapshots(table_name, days=30, format='parquet')

매개변수

table_name – 테이블 이름
days – 보관할 일수 (기본값: 30)
format – 형식

반환

삭제된 스냅샷 수

사용 예제:

# 30일 이상 된 스냅샷 정리
deleted_count = atio.expire_snapshots("users", days=30)
print(f"삭제된 스냅샷 수: {deleted_count}")

Plugins 모듈

atio.plugins.register_writer(obj_type, fmt, handler)[소스]: (객체 타입, 포맷) 쌍으로 쓰기 핸들러를 등록

atio.plugins.get_writer(obj, fmt)[소스]: 객체의 타입과 포맷에 맞는 핸들러를 조회

Utils 모듈

atio.utils.setup_logger(name='atio', debug_level=False)[소스]

atio.utils.check_file_exists(path)[소스]

class atio.utils.ProgressBar(filepath: str, stop_event: Event, description: str = 'Writing')[소스]

기반 클래스: object

파일 쓰기 진행 상황을 콘솔에 표시하는 클래스. 스피너, 처리된 용량, 처리 속도, 경과 시간을 표시합니다.

__init__(filepath: str, stop_event: Event, description: str = 'Writing')[소스]

run()[소스]: 진행도 막대를 실행하는 메인 루프. 이 함수가 모니터링 스레드에서 실행됩니다.

atio.utils.read_json(path: str)[소스]

atio.utils.write_json(data: dict, path: str)[소스]

atio.utils.get_process_pool()[소스]: 단순히 생성된 전역 풀을 반환하는 함수

지원하는 형식

CSV 형식

atio.write(df, "data.csv", format="csv", index=False, encoding='utf-8')

지원 매개변수: - index: 인덱스 포함 여부 - encoding: 인코딩 방식 - sep: 구분자 - na_rep: NA 값 표현

Parquet 형식

atio.write(df, "data.parquet", format="parquet", compression='snappy')

지원 매개변수: - compression: 압축 방식 (‘snappy’, ‘gzip’, ‘brotli’) - engine: 엔진 (‘pyarrow’, ‘fastparquet’)

Excel 형식

atio.write(df, "data.xlsx", format="excel", sheet_name="Sheet1")

지원 매개변수: - sheet_name: 시트 이름 - engine: 엔진 (‘openpyxl’, ‘xlsxwriter’)

JSON 형식

atio.write(df, "data.json", format="json", orient="records")

지원 매개변수: - orient: 방향 (‘records’, ‘split’, ‘index’, ‘columns’, ‘values’, ‘table’)

SQL 형식

atio.write(df, format="sql", name="table_name", con=engine, if_exists="replace")

지원 매개변수: - name: 테이블 이름 - con: 데이터베이스 연결 - if_exists: 테이블 존재 시 동작 (‘fail’, ‘replace’, ‘append’)

예외 처리

Atio는 다음과 같은 예외를 발생시킬 수 있습니다:

ValueError: 잘못된 매개변수나 형식
IOError: 파일 시스템 오류
DatabaseError: 데이터베이스 연결 오류
ImportError: 필요한 패키지가 설치되지 않은 경우

예외 처리 예제:

try:
    atio.write(df, "data.parquet", format="parquet")
except ValueError as e:
    print(f"매개변수 오류: {e}")
except IOError as e:
    print(f"파일 시스템 오류: {e}")
except Exception as e:
    print(f"예상치 못한 오류: {e}")