[pymyrep] python pep8, docstring

7월부터 9월까지 오픈소스 컨트리뷰션 아카데미(OSSCA)에 참가했다. 참가한 프로젝트는 python-mysql-replication으로, mysql에서 replication(복제)을 할 때 replica(slave) 대신 Python을 통해 변동 사항 등을 조회할 수 있도록 하는 오픈소스이다. 좀더 명확한 설명이 있는 것 같지만... 일단 replica(slave) 대신 python이 mysql db의 변화를 사용자에게 전달해주도록 만드는 패키지라고 이해하고 프로젝트에 참여했다.

GitHub - julien-duponchelle/python-mysql-replication: Pure Python Implementation of MySQL replication protocol build on top of P

python-mysql-replication - 공개SW 포털

참여 과정에서 많지는 않지만 어느정도 기여를 하게 되었는데, 그 중 관심있었던 부분인 python 프로젝트의 문서화에 대해 글을 작성해보려고 한다.

1. 발단

Docstring 수정 · Issue #43 · 23-OSSCA-python-mysql-replication/python-mysql-replication

pymyrep 프로젝트는 binary log 기반으로 작동하기 때문에, binlog event를 정의하는 파일이 있었다. 파일에는 각 mysql event들에 대한 파싱이 구현되어 있는데, 오픈소스여서 그런지 docstring이 불완전한 부분이 많았다. 우리 조에서 이에 대해서 분업해서 docstring을 보충하려고 했는데, 다른 조 분께서 먼저 제안을 해주셔서 PEP8에 맞도록 event docstring을 수정하게 되었다.

 

2. PEP8

PEP 8 – Style Guide for Python Code | peps.python.org

Python 코드를 일관되게, 또 가독성 있게 작성하기 위한 스타일 가이드로, 이번 프로젝트를 통해 처음 알게 되었다. 오픈소스 python 프로젝트에 코드를 작성하는 건 처음이라서 이런 규약이 있는 줄도 모르고 있었다...! docstring을 작성할 때도 최대한 이를 지키려고 노력했다.

 

3. Docstring

python에서 간편하게 문서화를 하기 위해 Sphinx를 사용할 수 있다. docstring을 작성하면, 자동으로 문서를 생성해준다. 우리 프로젝트도 sphinx 기반으로 readthedocs 홈페이지를 사용할 수 있었기 때문에, 우리가 할 일은 docstring을 알맞게 수정해주는 것이었다.

Python 문서화, Sphinx로 아주 간단하게 시작해보기

 

4. 작업

나는 event 2개에 대한 docstring을 작성하였다. IntvarEvent는 auto-increment 되는 integer 값을 저장하는 event였고, NotImplementedEvent는 아직 구현되지 않은 event에 임시로 할당하는 event였다. 각각에 대해 다음과 같이 작성하였고, readthedocs.org의 문서를 참고하였다.

 

IntvarEvent

NotImplementedEvent

 

5. PR과 merge

ossca organization 내의 fork repo에서 먼저 pr 형태로 작업을 하였고, 이후 본 repo에 pr을 넣어 merge되었다.

Modify docstrings in event.py by heehehe · Pull Request #58 · 23-OSSCA-python-mysql-replication/python-mysql-replication

docs: modify docstrings in event.py by ebang091 · Pull Request #464 · julien-duponchelle/python-mysql-replication

 

어려운 로직이 있는 건 아니고 간단한 문서화 작업이었지만, python의 스타일 가이드와 sphinx 등 문서화 도구를 알게 되어 python 프로젝트 협업에 필요한 지식을 얻게 된 것 같아 기뻤다:) 다른 기여 내용도 천천히 블로그 글로 작성해보려고 한다.