Initialize python project

so99ynoodles commented 9 months ago

@SpiralMoon 아직 개발중이지만 방향성만 봐주시면 감사하겠습니다.

SpiralMoon commented 9 months ago

@so99ynoodles 우선 적극적인 PR 참여 감사드립니다. 전체적으로 제가 원하던 모양새와 일치하는 것 같아 좋습니다!

MapleStoryApiError와 MapleStoryApiErrorCode를 사전 정의해두고 API 호출 시 server에서 error response를 리턴하면 MaplestoryApi 클래스에서 MapleStoryApiError 오류를 발생시키면 좋겠습니다.
```
// error response body json
```

{ "error": { "name": "OPENAPI00004", "message": "Please input valid parameter" } }

// mapleStoryApiError.ts 로 구현된 예시

/**

MapleStory OpenAPI error.
Please refer to MapleStory API guide for the error details. */ class MapleStoryApiError extends Error {

readonly name = 'MapleStoryApiError';

readonly errorCode: MapleStoryApiErrorCode;

readonly message: string;

constructor(errorBody: MapleStoryErrorBody) { const {name, message} = errorBody.error;
```
super(message);

this.errorCode = errorMap[name];
this.message = message;
```
} }

/**

MapleStory OpenAPI error codes.
Please refer to MapleStory API guide for the error code details. */ enum MapleStoryApiErrorCode { OPENAPI00001, OPENAPI00002, OPENAPI00003, OPENAPI00004, OPENAPI00005, OPENAPI00006, OPENAPI00007, }

const errorMap: {

} = {

['OPENAPI00002']: MapleStoryApiErrorCode.OPENAPI00002,
['OPENAPI00003']: MapleStoryApiErrorCode.OPENAPI00003,
['OPENAPI00004']: MapleStoryApiErrorCode.OPENAPI00004,
['OPENAPI00005']: MapleStoryApiErrorCode.OPENAPI00005,
['OPENAPI00006']: MapleStoryApiErrorCode.OPENAPI00006,
['OPENAPI00007']: MapleStoryApiErrorCode.OPENAPI00007,

}

export {MapleStoryApiError, MapleStoryApiErrorCode};


2. 제 쪽 코드에서는 `toDateString()`을 사용할 때 `minDate`보다 이전 날짜를 사용하면 명시적으로 오류를 발생시키도록 하고 있습니다. 이전 날짜가 감지되면 `minDate`로 자동으로 변경되는 기능도 좋아보이나, 라이브러리 사용자 측에서는 본인이 요청한 데이터 날짜와 response의 date 값이 일치하는지 매번 검사해야되는 문제가 발생할 수 있기 때문에 추천하지 않습니다.
3. `/maplestory_openapi/MaplestoryApi.py` → `/maplestory_openapi/api/MapleStoryApi.py` 네이밍 변경 및 디렉토리 위치 변경 가능할까요?

SpiralMoon commented 9 months ago

번거로우시겠지만 get_proper_default_datetime() 동작 수정 요청드립니다. (제보해주신 날짜 오류는 https://github.com/SpiralMoon/maplestory.openapi/issues/26 에서 수정되었습니다.)

함수의 동작은 API 서버의 데이터 갱신 시간에 따라 데이터가 조회 가능한 최신 날짜를 반환합니다.
API 항목마다 데이터 갱신 시간이 별도로 동작하고 있고 조회 가능 날짜가 당일/전일로 나뉘어지고 있기 때문에 get_proper_default_datetime()에서 최신 날짜를 판단하는 기준도 가변적이어야 할 것 같습니다.
- 다음은 typescript로 작성된 로직입니다.
```
/**
```
- API 서버의 데이터 갱신 시간에 따라 데이터가 조회 가능한 최신 날짜를 반환합니다.
- @param options
- @private */ private static getProperDefaultDateOptions( options: LatestApiUpdateTimeOptions, ): DateOptions { const { hour, minute, dateOffset } = options;
const kstNow = dayjs().utcOffset(MapleStoryApi.kstOffset); const updateDate = dayjs() .utcOffset(MapleStoryApi.kstOffset) .hour(hour) .minute(minute);

let adjustedDate: Dayjs;

if (kstNow.isAfter(updateDate)) { adjustedDate = kstNow; } else { adjustedDate = kstNow.subtract(1, 'day'); }

adjustedDate = adjustedDate.subtract(dateOffset ?? 0, 'day');

return { year: adjustedDate.year(), month: adjustedDate.month() + 1, day: adjustedDate.date() }; }

type LatestApiUpdateTimeOptions = { // API 서버의 데이터 갱신 시각 (시) hour: number; // API 서버의 데이터 갱신 시각 (분) minute: number; // 조회 가능한 최근 날짜와 현재 날짜와의 차이. 공식문서에서 "전일 데이터 조회"가 명시되어 있으면 offset을 1로 지정합니다. dateOffset?: number; };

/**
- 날짜 정보를 API 서버에서 요구하는 포맷으로 변환합니다.
- @param minDateOptions API 호출 가능한 최소 날짜
- @param dateOptions 조회 하려는 날짜
- @private */ private static toDateString( minDateOptions: DateOptions, dateOptions: DateOptions, ): string | never {
const { year: minYear, month: minMonth, day: minDay } = minDateOptions; const { year, month, day } = dateOptions;

if ( year < minYear || (year === minYear && month < minMonth) || (year === minYear && month === minMonth && day < minDay) ) { throw new Error( You can only retrieve data after ${dayjs(${minYear}-${minMonth}-${minDay}).format('YYYY-MM-DD')}., ); }

return dayjs(${year}-${month}-${day}).utcOffset(MapleStoryApi.kstOffset).format('YYYY-MM-DD'); }
```
적용 예시 1
```
/**
- 기본 정보를 조회합니다.
- - 2023년 12월 21일 데이터부터 조회할 수 있습니다.
- - 캐릭터 정보 조회 API는 일자별 데이터로 매일 오전 1시부터 전일 데이터 조회가 가능합니다. (예를 들어, 12월 22일 데이터를 조회하면 22일 00시부터 23일의 00시 사이의 데이터가 조회됩니다.)
- - 게임 콘텐츠 변경으로 ocid가 변경될 수 있습니다. ocid 기반 서비스 갱신 시 유의해 주시길 바랍니다.
- @param ocid 캐릭터 식별자
- @param dateOptions 조회 기준일 (KST) */ public async getCharacterBasic( ocid: string, dateOptions: DateOptions = MapleStoryApi.getProperDefaultDateOptions({ // this hour:1, minute: 0, dateOffset: 1 }), ): Promise
  { ... }
```
적용 예시 2
```
  /**
- 종합 랭킹 정보를 조회합니다.
- - 2023년 12월 22일 데이터부터 조회할 수 있습니다.
- - 오전 8시 30분부터 오늘의 랭킹 정보를 조회할 수 있습니다.
- - 게임 콘텐츠 변경으로 ocid가 변경될 수 있습니다. ocid 기반 서비스 갱신 시 유의해 주시길 바랍니다.
- @param filterOptions 검색 기준
- @param dateOptions 조회 기준일 (KST).
- */ public async getOverallRanking( filterOptions?: OverallRankingApiFilterOptions, dateOptions: DateOptions = MapleStoryApi.getProperDefaultDateOptions({ // this hour:8, minute: 30, dateOffset: 0 }), ): Promise { ... }

SpiralMoon commented 9 months ago

공식 문서에 스타포스 API가 추가되었습니다. 큐브 API와 비슷한 인터페이스로 보입니다.

https://openapi.nexon.com/game/maplestory/?id=25

SpiralMoon commented 9 months ago

수고하셨습니다. （〃＾∇＾）o 곧 패키지 배포도 진행하겠습니다.

SpiralMoon / maplestory.openapi

Initialize python project #23