Python open source 101

오픈소스 라이브러리 개발기
정겨울

View Slide

!2
정겨울
Jung Winter
뱅크샐러드 백엔드 엔지니어
발표자
res_tin
JungWinter

View Slide

੉ ߊ಴ח
!3
라이브러리를 만드는 과정과 느꼈던 점
도움이 될만한 정보 공유
제가 만든 라이브러리 쓰세요
구현상의 문제를 이렇게 해결했고
발표 소개

View Slide

!4
발표 소개 ⏩
보다보면 요런 이모지가 있습니다

View Slide

!5
발표 소개
해당 슬라이드는 제 상황에 국한된 얘기니
깊게 보지 않으셔도 된다는 표시
⏩

View Slide

!6
발표 소개
해당 슬라이드는 제 상황에 국한된 얘기니
깊게 보지 않으셔도 된다는 표시
⏩
= TMI

View Slide

!7
Index
동기
01
구상
02
개발
03
관리
04

View Slide

왜 만들었나
01

View Slide

불편한 점을 개선시키기 위해
!9
01 동기

View Slide

봇을 만든 내 코드가 제일 불편...
!10
01 동기 ⏩

View Slide

자동응답 API 형식
!11
01 동기 ⏩

View Slide

!12
01 동기
고유한 유저 키
⏩

View Slide

!13
01 동기
"text" or "photo"
⏩

View Slide

!14
01 동기
버튼 이름 or 유저 입력 텍스트 or 미디어 파일 URL
⏩

View Slide

session, intent, context
!15
01 동기 ⏩

View Slide

session, intent, context
!16
01 동기 ⏩

View Slide

모든건 POST /message
!17
대부분의 봇 API가 그렇듯 앱이 알아서 처리해야하는 문맥
다만 callback등이 없고 오로지 content 뿐
01 동기 ⏩

View Slide

그러다보니 만들어진건
!18
01 동기
분기 지옥
⏩

View Slide

!19
01 동기 ⏩

View Slide

!20
01 동기
분기의 분기의 분기
어디선가 들고있는 문맥
one magic function
⏩

View Slide

!21
파이썬을 배우기 시작한지 반년
PEP8의 존재도 모름
01 동기 ⏩

View Slide

라이브러리를 만들어 추상화하자!
!22
01 동기

View Slide

무엇을 만드나
02

View Slide

왜 불편한가 생각해보니
!24
02 구상

View Slide

!25
성가신 JSON response 조합
복잡한 if-elif-else 구조
어려운 시나리오 추가
02 구상 ⏩

View Slide

1. 복잡한 구조
!26
02 구상 ⏩

View Slide

2. 어려운 시나리오 대응
!27
02 구상
유저한테 입력을 받은건지 버튼을 클릭한건지 구분할 수 없음
⏩

View Slide

3. 성가신 response 조합
!28
02 구상 ⏩

View Slide

3. 성가신 response 조합
!29
02 구상
3개 중 하나는 필수
있을수도 없을수도
없으면 주관식 입력
⏩

View Slide

그냥 가짓수가 많구나 정도로만
!30
02 구상

View Slide

그 다음 어떻게 사용하고 싶은지
!31
02 구상

View Slide

!32
02 구상
Pythonic하게
명확한 시나리오 플로우
간편한 시나리오, Depth 추가
성가신 JSON response 조합
복잡한 if-elif-else 구조
어려운 시나리오 추가
⏩

View Slide

코드로 상상하기
!33
02 구상

View Slide

최종 컨셉
!34
02 구상 ⏩

View Slide

최종 컨셉
!35
02 구상
상태 전이시 실행할 함수
like view function
chatter.route(request.json)
을 통해 트리거
⏩

View Slide

최종 컨셉
!36
02 구상
데코레이터를 통한 플로우 등록
간단한 키워드 인자 이름
⏩

View Slide

최종 컨셉
!37
02 구상
조합 가능한 response
⏩

View Slide

정리된 주요 컨셉
!38
02 구상

View Slide

!39
02 구상
Response 객체 조합
State rule 기반 라우팅
데코레이터를 통한 플로우 등록
Pythonic하게
명확한 시나리오 플로우
간편한 시나리오, Depth 추가
⏩

View Slide

02 구상
마지막으로 이름 정하기
!40
이미 누가 선점한 chatterbox
→ 패키지 이름은 chatterbox.py지만
import chatterbox 할 수 있게

View Slide

어떻게 만드나
03

View Slide

!42
03 개발
01 setup.py
02 패키지 매니저
03 린트
04 테스트 & 커버리지
05 CI
06 커밋 메시지
07 TDD
08 표준 라이브러리
09 릴리즈와 태그

View Slide

setup.py
!43
03 개발

View Slide

setup.py
!44
ଵҊೞݶ જਸ kennethreitz/setup.py
03 개발
setup.py

View Slide

setup.py
!45
03 개발
setup.py

View Slide

setup.py
!46
03 개발
setup.py

View Slide

setup.py
!47
03 개발
setup.py

View Slide

setup.py - long_description
!48
Markdown Descriptions on PyPI
03 개발
setup.py

View Slide

setup.py - long_description
!49
Markdown Descriptions on PyPI
03 개발
setup.py

View Slide

setup.py - classifiers
!50
List of classiﬁers
03 개발
setup.py

View Slide

setup.py - test
!51
03 개발
setup.py

View Slide

Python 2 or 3
!52
Python 2를 지원할지 말지
Python 3이라면 어느버전부터 지원할지
각 마이너버전마다 새로 생긴 기능 파악하기
03 개발
setup.py

View Slide

Python 2 or 3
!53
03 개발
setup.py

View Slide

Python 3.4
New modules
asyncio
enum
pathlib
!54
03 개발
setup.py

View Slide

Python 3.5
New syntax
async/await
a @ b
*, ** unpacking 동작 확장 (e.g. {'x': 1, **{'y': 2}})
New modules
typing
!55
03 개발
setup.py

View Slide

Python 3.6
New syntax
F 문자열 포매팅 f'Answer is {value}'

변수 타입 힌팅
async 제네레이터
!56
03 개발
setup.py

View Slide

패키지 매니저
!57
03 개발

View Slide

Pipenv
!58
03 개발
패키지매니저
• Pipfile, Pipfile.lock을 통한 의존성 관리
• pipenv shell 로 가상환경 실행 (source venv/bin/activate)
• 로 호환성유지
• pipenv install --dev 로 개발에만 필요한 패키지 따로 관리
• 중요한건 라이브러리 의존성 명시와 컨트리뷰터를 위한다는 것
pipenv lock -r > requirements.txt
pipenv lock -dr > requirements-dev.txt

View Slide

Pipenv
!59
03 개발
패키지매니저

View Slide

Pipenv
!60
03 개발
패키지매니저

View Slide

린트
!61
03 개발

View Slide

!62
03 개발
린트
PEP8 준수
pylint, flake8 등의 린터를 통해 코드 품질 관리
isort, autopep8, yapf, black 등의 포매터를 통해 
일관된 코드 스타일 보장

View Slide

!63
03 개발
린트
isort
pylint
black

View Slide

!64
03 개발
린트
isort
#

View Slide

테스트 & 커버리지
!65
03 개발

View Slide

03 개발
pytest
unittest + nose < pytest
간결하고 깔끔한 테스트 코드
읽기 쉬운 에러 리포트
fixture
플러그인
테스트

View Slide

pytest
unittest + nose < pytest
fixture
플러그인
모든 unittest 코드는 pytest로 테스트 가능
03 개발
테스트

View Slide

The cleaning hand of pytest
03 개발
테스트

View Slide

일일이 기억해 사용해야 하는 assertXXX 패밀리
03 개발
테스트

View Slide

setUp, tearDown 를 사용하면 더 차이나는 코드
일일이 기억해 사용해야 하는 assertXXX 패밀리
네이티브 문법을 활용해 가독성 확보
03 개발
테스트

View Slide

03 개발
테스트

View Slide

fixture와 플러그인
fixture와 pytest의 내장 기능을 통해 테스트 로직에 집중
03 개발
테스트

View Slide

fixture와 플러그인
Pytest۽ Flask੄ DB పझ౟ ജ҃ ҳ୷ೞӝ
Python pytest ﬁxture
Switching from nose to py.test at Mozilla
03 개발
테스트

View Slide

tox & detox
03 개발
테스트
pyenv + tox로 다양한 파이썬 버전에서 테스팅
detox로 병렬적으로 더 빠르게
tox.ini를 잘 만들어두면 CI도 거저먹기

View Slide

tox & detox
03 개발
테스트
3.4 / 3.5 / 3.6 버전에서 테스트 실행 가능

View Slide

03 개발
커버리지
pytest-cov로 커버리지 리포트 생성 
커버리지는 목표가 아닌 상태

View Slide

03 개발
커버리지
• codecov, coveralls: CI에서 리포트를 업로드, Integration 활용
• PR이 커버리지를 어떻게 변화시키는지 알 수 있음

View Slide

CI 
(Continuous Integration)
!78
03 개발

View Slide

!79
03 개발
CI
commit push 혹은 PR이 올라오면
travis의 리눅스 환경, appveyor의 윈도우 환경에서
tox를 통해 다양한 파이썬 버전에서
pytest와 pylint를 돌리고
성공/실패를 알려주고 coverage를 codecov에 리포트

View Slide

!80
03 개발
CI

View Slide

!81
03 개발
CI

View Slide

!82
03 개발
CI

View Slide

!83
03 개발
CI

View Slide

!84
03 개발
CI
Integration

View Slide

!85
03 개발
CI
tests
pylint
source
codecov
tox
travis
&
appveyor Python
3.4
Python
3.5
Python
3.6
pytest
push GitHub

View Slide

!86
03 개발
CI
병렬로 실행
tox.ini 재활용한 .travis.yml

View Slide

!87
03 개발
01 setup.py
03 린트
05 CI
06 커밋 메시지
07 TDD
지금까지는 개발을 하기위한 환경이었다면

View Slide

!88
03 개발
01 setup.py
03 린트
05 CI
06 커밋 메시지
07 TDD
지금부터는 개발을 더 잘 하기위한 이야기

View Slide

커밋 메시지
!89
03 개발

View Slide

!90
03 개발
커밋 메시지
requests-html
신경쓰지 않는 메인테이너도 있음

View Slide

!91
03 개발
커밋 메시지
જ਷ ழ޿ ݫद૑ ੘ࢿߨ 1 2
Ӓ۞ա જ਷ ழ޿ ݫद૑ח ࠄੋೠపب ب਑੉ ؽ

View Slide

!92
03 개발
커밋 메시지
⏩
chatterboxח Target: Description ഋध ࢎਊ

Action: Things ഋध, Write what I do э਷ ഋधب оמ

View Slide

TDD
(Test Driven Development)
!93
03 개발

View Slide

!94
03 개발
TDD
• 라이브러리를 개발하는데 가장 추천하고 싶은 부분
• 테스트하지 않은 기능까지 완벽하게 돌아간다고 말할 순 없어도, 테
스트한 기능에 대한 걱정은 없어짐
• 세부 구현을 바꾸거나 최적화, 리팩토링 할 때도 걱정없이
• TDD가 만능은 아니다. 구현하다 기획이 바뀌고 후에 테스트를 고쳐
야 할 때도
• 처음 구상했던 Examples를 토대로 테스트를 먼저 구성하면 좋음

View Slide

!95
03 개발
TDD
야 할 때도

View Slide

!96
03 개발
TDD
야 할 때도

View Slide

!97
03 개발
TDD
Red Green Refactor 과정

View Slide

!98
03 개발
TDD
⏩

View Slide

!99
03 개발
TDD
테스트 코드 또한 하나의 문서라는 생각으로
⏩

View Slide

표준 라이브러리
!100
03 개발

View Slide

!101
03 개발
• 라이브러리를 제작할 때 도움이 되는 기본 라이브러리가 많이 있음
• functools: wraps, partial
• itertools: 뭔가 lazy하게 처리하고 싶을 때, sequence 객체를 다룰 때
• contextlib: sqlite cursor를 다룰 때, contextmanager
• collections: ChainMap, 3.4에서 dict unpacking이 필요할 때
• abc: ABCMeta, abstractmethod를 통해 인터페이스 제공
• pathlib: os.join, os.path가 필요없음

View Slide

!102
03 개발
데코레이터를 위한 functools.wraps

View Slide

!103
03 개발
⏩
특히 유용했던 itertools

View Slide

!104
03 개발
⏩
카카오톡 Response는
itertools & operator

View Slide

!105
03 개발
⏩
3 종류의 message와

View Slide

!106
03 개발
⏩
2 종류의 keyboard로 구성됨

View Slide

!107
03 개발
⏩
2о૑ keyboard
6о૑ message
Text
Photo
Button
Text
Button
X

View Slide

!108
03 개발
⏩

View Slide

!109
03 개발
⏩

View Slide

!110
03 개발
⏩
itertools.combinations으로 
하나일 때, 두개일 때, 모두 있을 때의 조합 생성

View Slide

!111
03 개발
⏩
itertools.chain으로 ﬂatten하게

View Slide

!112
03 개발
⏩
각 메시지는 __add__를 오버라이드한 객체

View Slide

!113
03 개발
⏩
총 12개의 모든 조합 테스트

View Slide

!114
03 개발
표준 라이브러리 관심사 분리를 위한 contextlib
context를 유지한채 관심사에 집중 가능

View Slide

03 개발
표준 라이브러리 관심사 분리를 위한 contextlib
불필요한 코드를 줄일 수 있음

View Slide

릴리즈와 태그
!116
03 개발

View Slide

!117
03 개발
릴리즈와 태그
• 0.1.0 버전 릴리즈 → git tag v0.1.0
• 버저닝에 관한 내용은 잠시 뒤에
• setup.py의 version과 GitHub의 태그를 동일하게 관리
• changelog 적기 편함

View Slide

!118
03 개발
릴리즈와 태그
태그를 기반으로한 diﬀ → 편해진 체인지로그 작성

View Slide

!119
03 개발
릴리즈와 태그
CHANGELOG.md로 관리 
GitHub 릴리즈 페이지에 적기도

View Slide

마지막 보너스: API 체크리스트
!120
03 개발
python.apichecklist.com

View Slide

!121
03 개발
내 API는 간단한걸 쉽게 만들고
복잡한걸 가능케하며
잘못된건 불가능하게 한다
API 체크리스트
라이브러리

View Slide

!122
03 개발
API 체크리스트
• 간결함 - README 샘플 코드, 보일러 플레이트 줄이기
• 일관성 - 네이밍 (단어 순서, 복수형), 통일된 빈 값
• 유연함 - 함수 분리, 추상화와 커스터마이징, Pythonic
• 안정성 - 빠른 실패
• 각 항목에 대한 예제는 사이트에서 확인 가능

View Slide

책임을 지자
04

View Slide

!124
04 관리
01 의미있는 버저닝
02 문서화
03 기여자를 위해
04 뱃지달기
05 README
06 이슈해결
07 개밥먹기
08 홍보

View Slide

!125
04 관리
의미있는 버저닝
• Semantic versioning (e.g. Python 3.6.5)
• 라이브러리를 다 만들어도 버그 수정, 기능 추가 등의 업데이트는 항
상 존재
• 메이저 버전, 마이너 버전, 패치 버전으로 의미있는 버저닝을 하자
• break change가 있으면 메이저 버전, 새로운 기능추가는 마이너
버전, 버그 해결은 해치 버전 업데이트
• 사람들에게 충분히 받아들여지고 성숙했다고 생각될 때 1.0.0

View Slide

!126
04 관리
상 존재

View Slide

!127
04 관리
상 존재

View Slide

!128
04 관리
• Calendar Versioning (e.g. Pipenv 2018.7.1)
• Ubuntu, pytz, PyCharm, certiﬁ 등
• 릴리즈 사이클이 주기적이거나 (pip), outdated에 민감한 프로젝
트거나 (pytz, certiﬁ), 크거나 포괄적인 프로젝트(Ubuntu,
Pipenv)라면 캘린더 버저닝을 고려

View Slide

!129
04 관리
문서화
• 라이브러리를 사용할 개발자를 위한 문서화
• 나는 내 코드를 다 알지만 다른 사람은 그렇지 않음
• 이 라이브러리는 어떻게 사용해야하고 → Getting started
• 어떤 함수가 있고 파라미터로 어떤걸 받고 뭘 반환하고 → api reference
• sphinx와 read the docs로 문서 유지 (sphinx 첫걸음, 시작하기)

View Slide

!130
04 관리
문서화
• 어떤 함수가 있고 파라미터로 어떤걸 받고 뭘 반환하고 → API Reference

View Slide

!131
04 관리
문서화
• 어떤 함수가 있고 파라미터로 어떤걸 받고 뭘 반환하고 → API Reference

View Slide

!132
04 관리
문서화
README에라도 유즈케이스, 샘플 코드를 적어놔야한다
doctoc로 자동 생성된 ToC

View Slide

!133
04 관리
기여자를 위해
CONTRIBUTING.md 
→ 기여를 위해 알리는 말. 테스트는 어떻게 할 수 있고 컨벤션은 이렇다

View Slide

!134
04 관리
기여자를 위해
CONTRIBUTING.md 
→ 기여를 위해 알리는 말. 테스트는 어떻게 할 수 있고 컨벤션은 이렇다

View Slide

!135
04 관리
기여자를 위해
ISSUE_TEMPLATE.md 
→ 업데이트로 디렉토리 형식도 지원 
버그 리포트에 필요한 정보를 담게끔 유도

View Slide

!136
04 관리
기여자를 위해

View Slide

!137
04 관리
기여자를 위해

View Slide

!138
04 관리
기여자를 위해
• PULL_REQUEST_TEMPLATE.md → 어떤 변경이 있는지, 체크리스트
로 빼먹은건 없는지 유도
• 프로젝트 최상위 위치에 .github 폴더를 만들어 관리
• 주석을 활용해 불필요한 설명이 노출되지 않도록

View Slide

!139
04 관리
뱃지 달기
• CI: 빌드 상태
• 라이센스
• pypi 기준 라이브러리 버전: stable, unstable
• 지원되는 파이썬 버전
• 코드 커버리지: 이 라이브러리가 이만큼 건강하다
license
license MIT
MIT
build
build passing
passing
build
build passing
passing
pypi
pypi v0.2.4
v0.2.4
python
python 3.4, 3.5, 3.6
3.4, 3.5, 3.6
codecov
codecov 92%
92%

View Slide

!140
04 관리
뱃지 달기
• CI: 빌드 상태
• 라이센스
• pypi 기준 라이브러리 버전: stable, unstable
• 지원되는 파이썬 버전
• 코드 커버리지: 이 라이브러리가 이만큼 건강하다
license
license MIT
MIT
build
build passing
passing
build
build passing
passing
pypi
pypi v0.2.4
v0.2.4
python
python 3.4, 3.5, 3.6
3.4, 3.5, 3.6
codecov
codecov 92%
92%
https://badgen.net

View Slide

!141
04 관리
리드미
• 프로젝트의 대문
• 보통 MD, RST: 이제 pypi에서 Markdown도 지원됨
• 라이브러리의 현재 상태 - 뱃지
• 무엇을 위한 라이브러리인지, 설치 방법, 간단한 사용 사례, 문서
링크, 기여 방법
• 자세한 사용방법은 read the docs로 분리시키기

View Slide

!142
04 관리
이슈해결
• 이슈가 있다는건 관심을 갖고 사용해주시는 분들이 있다는 의미
• 내가 발견하고 내가 수정할 버그더라도 이슈로 남겨두기
• 어떤 커밋을 통해 해결됐는지 명시 (커밋에 Close #4, Fix #3를
적어주면 자동으로 처리)
• 이슈를 올려주는 분들도 고마운 컨트리뷰터분들이라는 생각으로

View Slide

!143
04 관리
개밥먹기
• 돌고돌아 드디어 원래 목적이었던 내 프로젝트에 내 라이브러리
사용하기 달성
• 해당 라이브러리로 개발된 프로젝트가 있다면 좀 더 신뢰할 수 있
고, 개발자 스스로도 지속적인 관심을 가질 수 있음
JungWinter/chef-hong
JungWinter/chatterbox
⏩

View Slide

!144
04 관리
개밥먹기
JungWinter/chef-hong
JungWinter/chatterbox
기존에 있던 프로젝트를 unmaintained 처리
⏩

View Slide

!145
04 관리
홍보
• chatterbox.py는 카카오톡 봇 라이브러리다 보니 국내 개발자가 타겟
• 페이스북 그룹, 개발자 사이트, 트위터 등
• 제작 경험을 공유하는 것 또한 좋은 홍보 방법 (저는 때를 놓쳤지만...)
• 글로벌 타겟이라면 hackernews, reddit, medium 등도 좋은 홍보 수단
이게 마지막입니다

View Slide

마치며

View Slide

!147
마치며
원래 목적을 달성했는가 → ✅
나만 쓰려고 만들기와 모두를 위해 만들기는 매우 달랐다
개발 자체보다 준비, 관리 등 다른 부분이 더 중요하다
문서화는 몰아서 하지말고 그때그때 해두자

View Slide

!148
도움이 된 것들
- Go언어로 오픈소스 배송조회 서비스 만들기
- Tox, Travis 그리고 Codecov 로 오픈소스 생태계에 기여하기
- 파이썬에서 편하게 테스트 케이스 작성하기: pytest, Travis CI, Docker
- 정해진 데드라인

View Slide

Thank You

View Slide

Python open source 101

Python open source 101

Winter Jung

More Decks by Winter Jung

Other Decks in Programming

Featured

Transcript