개인 Python 프로젝트를 릴리스 가능한 라이브러리로 전환

저는 프로그래머가 아닌 학문적이며, 연구를 뒷받침 할 목적으로 파이썬 프로그램을 직접 작성해 온 경험이 있습니다. 내 최신 프로젝트는 나뿐만 아니라 다른 많은 사람들에게도 유용 할 것 같으며 오픈 소스 Python 라이브러리로 출시하려고 생각합니다.

그러나 제대로 작동하는 개인 프로젝트에서 다른 사람이 쉽게 설치하고 사용할 수있는 라이브러리로 넘어가는 데 약간의 장애물이있는 것 같습니다. 이 질문은 공개 릴리스를 시작하기 위해 취해야 할 첫 번째 단계에 관한 것입니다.

현재 라이브러리와 라이브러리 자체를 사용하는 코드가 포함 된 단일 git 저장소가 있으며, git을 비상 실행 취소 버튼으로 사용합니다. 이 모든 것이 단일 사용자에게는 잘 작동하지만 릴리스하려는 경우에는 적절하지 않습니다. 내가 끝내고 싶은 곳은 내 라이브러리가 별도의 저장소에 있고를 사용하여 다른 사람이 설치할 수 있고 pip안정적인 API를 가지고 있다는 것입니다.

setuptools 등을 사용하는 법을 배우는 것은 일단 게시하고 싶은 시점에 그렇게 어렵지 않을 것입니다. 제 문제는 그 시점에 도달하기 위해 어떻게 작업 해야하는지 아는 것입니다.

그래서 내 질문은, 공공 소비를 위해 파이썬 라이브러리 프로젝트를 준비하기 위해 취해야 할 첫 단계는 무엇입니까? 라이브러리 릴리스 공개를 위해 작업하기 위해 디렉토리 구조, 자식 저장소 등을 어떻게 재구성해야합니까?

더 일반적으로, 처음 시도 할 때 도움이되는 것으로 알려진 리소스가 있으면 매우 유용합니다. 모범 사례 및 피해야 할 실수 등에 대한 포인터도 매우 유용합니다.

몇 가지 설명 : 현재 답변은 "파이썬 라이브러리를 다른 사람들이 사용하기 좋은 라이브러리로 만들려면 어떻게해야합니까?" 이것은 유용하지만 내가 묻고 자하는 질문과 다릅니다.

저는 현재 프로젝트를 출시하기위한 긴 여정을 시작 하고 있습니다. 내 구현의 핵심은 효과가 있으며 실제로 잘 작동하지만 나보다 앞선 작업량에 압도되는 느낌이 들며 프로세스 탐색 방법에 대한 지침을 찾고 있습니다. 예를 들면 다음과 같습니다.

• 내 라이브러리 코드는 현재이를 사용하는 도메인 고유 코드와 연결되어 있습니다. 하위 폴더에 있으며 동일한 git 저장소를 공유합니다. 결국 독립형 라이브러리로 만들어 자체 저장소에 저장해야하지만 어떻게 해야할지 모릅니다. (여전히 편집 할 수 있도록 '개발 모드'로 라이브러리를 설치하는 방법이나 두 git repos를 동기화 상태로 유지하는 방법도 없습니다.)

• 나는 결국 스핑크스 또는 다른 도구를 사용해야한다는 것을 알고 있기 때문에 내 문서 문자열은 간결합니다. 그러나이 도구는 배우기 쉽지 않은 것처럼 보이므로 이것이 주요 하위 프로젝트가되어 계속 계속 사용합니다.

• 어떤 시점에서 setuptools 또는 다른 도구를 사용하여 패키지화하고 종속성을 추적하는 방법을 배워야합니다. 지금이 작업을 수행해야하는지 여부가 확실하지 않으며 설명서는 새로운 사용자에게는 절대적인 미로이므로 나중에 계속하기로 결정합니다.

• 나는 체계적인 테스트를 수행 할 필요는 없었지만,이 프로젝트를 위해 확실히 할 것이므로, (i) 프로젝트에 적합한 방법론을 알기 위해 테스트에 대해 충분히 배워야합니다. (ii) 내가 선택한 방법론에 어떤 도구를 사용할 수 있는지 배우십시오. (iii) 내가 선택한 도구를 사용하는 법을 배우십시오. (iv) 내 프로젝트에 테스트 스위트 등을 구현합니다. 이것은 그 자체로 프로젝트입니다.

• 내가해야 할 다른 일이있을 수도 있습니다. 예를 들어, jonrsharpe 는 git-flow, tox, TravisCI, virtualenv 및 CookieCutter를 언급 한 유용한 링크 를 게시했습니다 . (게시물은 2013 년부터 였으므로 현재 얼마나 많은지 확인하기 위해 몇 가지 작업을 수행해야합니다.)

이 모든 것을 종합하면 엄청난 양의 작업이지만, 계속 연결해두면 모든 작업을 수행 할 수있을 것입니다. 서두르지 않습니다. 내 문제는 그것을 한 번에 하나씩 수행 할 수있는 관리 가능한 단계로 나누는 방법을 아는 것입니다.

다시 말해, 결국 출시 가능한 제품에 도달하기 위해 지금 취할 수있는 가장 중요한 구체적인 단계를 묻습니다. 무료 주말이 있다면이 중 어떤 것에 집중해야합니까? 어느 것이라도 다른 것들과 분리하여 수행 할 수 있으므로 적어도 전체 단계를 수행하지 않고도 한 단계를 완료 할 수 있습니까? 프로젝트 자체에 계속 집중할 시간을 갖도록 이러한 것들을 배우는 가장 효율적인 방법은 무엇입니까? (이 모든 것이 본질적으로 취미가 아니라 취미 프로젝트라는 점을 명심하십시오.) 실제로 수행 할 필요가없는 프로젝트가 있습니까?

모든 답변에 큰 감사를 표하지만 특히 현대적인 Python 개발을 참조하여 이러한 프로젝트 관리 측면에 중점을 둔 답변을 환영합니다.

라이브러리를 사용하려면 setup.py를 추가하는 것이 가장 중요하지 않습니다. 더 중요한 것은 문서를 추가하고 라이브러리를 광고하는 것입니다. 두 번째 요점은 라이브러리에 따라 크게 달라 지므로 문서 측면에 중점을 두겠습니다.

1. 도서관에 대한 모든 것을 알고 있습니다. 그리고 이것은 문제가됩니다. 설치 및 사용 방법을 이미 알고 있으므로 많은 것이 직관적이거나 명백하게 보일 수 있습니다. 불행히도, 사용자에게는 직관적이지 않은 동일한 내용이 명확하지 않을 수 있습니다. 도서관에 대해 아는 것이없는 것처럼 도서관을 살펴보고, 더 중요하게는 다른 사람들에게 도서관 이용을 요청하고 그들이 겪었던 모든 어려움을 찾아보십시오.

2. 도서관이 무엇인지 일반 영어로 설명하십시오. 너무 많은 도서관은 모두가 그들에 대해 알고 있다고 가정합니다. 그렇지 않은 경우, 라이브러리의 목적이 무엇인지 파악하기 어려울 수 있습니다.

3. 자세한 기술 문서를 작성하되 라이브러리에서 일부 작업을 수행하는 방법을 보여주는 짧은 코드도 잊지 마십시오. 대부분의 개발자는 서두르고 기본적인 작업을 수행하는 방법을 이해하기 위해 몇 시간을 소비해야하는 경우 다른 라이브러리로 전환하는 경향이있을 수 있습니다.

4. 연락처 정보를 포함하십시오. 만약 당신의 도서관이 성공적이라면 (그리고 내 자신의 경험에 의하면 이것은 심지어 알려지지 않은 도서관의 경우에도 해당됨), 사람들은 도서관에 어려움을 겪을 것입니다. 도서관을 개선하기 위해 피드백을받는 것이 유용한 경우가 종종 있습니다. 문제를보고 한 사람마다 문제가 발생했을 때 다른 도서관으로 바꾸는 것을 선호하는 수백 명이있을 수 있습니다.

그 외에도 :

1. 라이브러리가 Python 2 또는 3 또는 둘 다에서 작동하는지 확인하십시오.

2. 라이브러리가 Windows에서 작동하지 않으면 그렇게 말하십시오.

3. 공식 규칙을 사용해야합니다 (pep8을 사용하여 확인). 그렇지 않은 경우 명확하게 설명하거나 수정하십시오.

4. 엣지 케이스 취급에주의하십시오. 라이브러리가 잘못된 유형 또는 지원되지 않는 값으로 호출되면 일반 영어로 정확히 무엇이 잘못되었는지 말해야합니다. 하지 말아야 할 것은 스택 아래로 10 가지 수준의 암호 예외를 발생시키고 사용자가 무엇이 잘못되었는지 알아내는 것입니다.

배포 도구를 선택한 후에는 몇 년 동안 성숙한 라이브러리보다 공정하지 않은 라이브러리를 사용하여 다음과 같은 작업을 수행합니다. 라이브러리는 커뮤니티를 구축 할 수있는 유용한 기능을 수행합니까?

라이브러리 종속성을 식별하십시오.

도킷 컨테이너 또는 VM 중 하나 인 클린 환경으로 배치를 시도하십시오. 문제를 일으키는 개인 환경에 고유 한 무언가가 있기 때문에이 단계가 중요하다고 생각합니다.

앞으로 도서관을 유지할 사람을 고려하십시오 .3-4 년 동안 누군가의 애완 동물 프로젝트였던 도서관을 방문한 다음 최신 상태로 유지하는 데 필요한 업데이트를 얻지 못하는 것보다 더 실망스러운 것은 없습니다.

귀하 또는 귀하의 팀이 라이브러리를 테스트하고 문서화하기 위해 노력하고 있는지 고려하십시오 (단위 테스트 및 CI 파이프 라인은 방정식의 일부가되기 시작합니다).

아마도 당신은 당신의 분야에서 성숙한 OSS 프로젝트를 찾아서 그 프로젝트에 코드를 기여할 수 있습니까? 다음과 같은 장점이 있습니다.

• 당신은 당신의 기여를 극대화 할 수 있습니다. 실제로 많은 "취미"OSS 프로젝트는 잠재적으로 가치가 있지만 커뮤니티에서는 거의 사용하지 않습니다 (@ReaddyEddy 답변 참조). 처음에는 프로젝트를 처음부터 시작한 다음 유지 보수, 광고, 적절한 예제 및 문서 등을 제공하기 위해 많은 노력을 기울입니다.
• 언급 한 많은 기술 문제는 이미 성숙한 프로젝트에서 해결되었을 것입니다.
• 라이브러리가 OSS 프로젝트에 가치를 더한다면 기여자들이 코드를 프로젝트 표준에 맞게 도울 수 있습니다. 따라서 노력을 절약하고 경험을 얻을 수 있습니다. 또한 Sphinx, TravisCI, CookieCutter 및 기타 기술적 측면에 대한 구체적인 답변을 얻을 수 있습니다.

당신이 좋아하고 사용하는 관련 OSS 프로젝트가 있다면, 이슈 나 풀 요청을 열거 나 관리자와 연락하는 것이 어떻습니까? 시작하는 좋은 방법은 기존 문제를 해결하는 것입니다.

2019 년에 가장 현대적인 도구부터 시작하는 것이 좋습니다. 당신은 setup.py파이썬 커뮤니티의 사람들이 제거하고 싶어하는 무언가 가 필요하지 않으며 결국에는 그렇게 될 것이라고 믿습니다.

시를 보십시오 , 당신은 그것을 후회하지 않을 것입니다.

이것은 당신이 묻는 복잡한 질문이며 Arseni의 대답에 전적으로 동의합니다 . 좋은 문서는 매우 중요한 측면입니다. 몇 가지 간단한 단계만으로 라이브러리를 성공적으로 시작하고 실행하지 못하면 (실제로 시도하기를 원치 않는 한) 바로 그 라이브러리를 삭제합니다.

당신이 확실히 고려해야 할 것들

• 라이브러리를 어떻게 버전화할 것인지 생각하십시오. 당신은 어떤 수준과의 하위 호환성을 원하고 경로를 따라 버그 수정하고 싶습니다. 시맨틱 버전 관리 에 대해 읽어보기
• 상대적으로 선형으로 git을 사용하고 있습니다 (취소). 당신이 잘 알고있는 자식에 분기 . 실제로 그렇게 어렵지는 않으며 인생을 쉽게 만듭니다. 일단 당신이 가지와 그립을 얻었다. 저장소에 대한 분기 모델을 채택하십시오. 관련 이있는이 분기 모델 의 부분을 선택하십시오 . 또한 이것을 사용중인 리포지토리의 분기와 비교하십시오.
• 라이센스 : 라이브러리의 라이센스를 제공해야합니다. 본인은이 문제에 대한 법률 전문가가 아니므로 일반 라이센스 간 비교에 대한 링크 만 공유 할 수 있습니다 . 이 선택을 가볍게하지 마십시오.
• 버그 추적기. 해당 사용자가 버그 보고서를 제공 할 수 있기를 원합니다. 이를 통해 코드 품질을 향상시킬 수 있습니다. 해결하는 각 버그에 대해 테스트 프레임 작업에 테스트를 추가하여 향후에 제동되지 않도록합니다 (회귀 테스트). 기능 요청에 버그 추적 시스템을 사용할 수 있습니다.
• 사용자 기여. 사용자 기여를 원하십니까? 이것이 오픈 소스 제품에서 일반적으로 어떻게 작동하는지 잘 모르겠지만 사용자가 기능 분기를 만들 수 있다고 상상할 수 있습니다. github을 통해 풀 요청을 통해 이것을 제어 할 수있는 것 같습니다

나는 파이썬에 대한 관련 경험이 없으므로 그 방향에 대한 힌트를 줄 수는 없습니다. 그러나 원격 저장소에서 각 커밋에 의해 트리거되는 모든 테스트를 자동화 할 수 있습니다 (예 : Jenkins 사용 ). 그러나 사전 경험없이 설정하는 것이 많은 작업이기 때문에 이것을 연기하는 것이 좋습니다.

좋은 질문입니다.

릴리스 가능한 라이브러리를 향한 중요한 구체적인 증분 단계 정보 :

• 라이브러리가 될 파일을 나머지 프로젝트와 분리하십시오.
  • 라이브러리는 자체 git 저장소로 이동해야하지만 현재 저장소 내의 별도의 최상위 디렉토리에 라이브러리를 저장하는 유용한 중간 단계를 찾을 수 있습니다. 별도의 리포지토리로 만들면 나머지 프로젝트와 인접한 곳에 저장 한 다음 ../librarypip 패키징 및 개발 모드 단계로 이동할 때까지 참조 할 수 있습니다 .
  • 프로젝트의 나머지 부분에서이 라이브러리로의 모든 액세스는 공개 API를 거쳐야합니다. 애타게 서로 상호 의존성을 찾을 수 있습니다.
• 라이브러리의 API를 문서화하기 위해 docstring을 점진적으로 작성하십시오.
  • 결국 docstring은 문서화 도구로 제공되지만 중요한 작업은 API를 다른 사람들에게 간결하고 충분히 설명하는 텍스트를 작성하는 것입니다. 한 번에 한 번에 조금씩 채우는 것이 더 쉬우 며, 거친 설명을 작성하고 나중에 더 나은 설명과 예제가 떠오를 때 다시 돌아 오면 훨씬 더 나아질 것입니다.
  • API의 일부를 문서화하기 어려운 경우 API의 해당 부분에 개선의 여지가 있는지 물어보십시오. 더 간단 할 수 있습니까? 더 규칙적인가요? 너무 일반적인가요? 너무 전문? 더 친숙한 이름을 사용할 수 있습니까?
  • 문서 문자열은 도구가 확인할 수있는 구조화 된 주석을 사용하여 인수 유형을 문서화 할 수 있습니다. 아직 그것에 대한 실제 문서를 찾지 못했지만 PyCharm IDE는 이러한 docstring을 구성하는 데 도움이되며 메소드 호출을 편집하는 동안 인수 유형을 즉시 확인합니다.
  • PyCharm은 개발자 시간을 절약하고 코드 품질을 향상시키는 훌륭한 도구입니다. 코드를 편집하는 동안 코드를 확인하기 위해 "검사"를 실행합니다 (예 : 가능한 경우 유형 확인, 누락되거나 사용되지 않은 가져 오기 확인, 중복 메소드, PEP 8 스타일 실수 등).
• 을 사용하여 단위 테스트 작성을 시작하십시오 pytest. 릴리스하기 전에 단위 테스트는 코너 케이스에서 버그를 발견하고 코드 변경으로 문제가 해결되지 않았다는 확신을 제공함으로써 자체 개발에서 성과를 거둘 것입니다. 다시, 당신은 이것을 시간이 지남에 따라 구축 할 수 있습니다. 시작하기가 매우 쉽습니다.
• GitHub에서 기존 오픈 소스 라이브러리 (대략 같은 크기)를 사용하여 파일 및 릴리스 구성 방법을 확인하십시오. 그들이 어떻게 버그 / 문제 추적 및 풀 요청을하는지보십시오. 경험이없는 경우 이러한 여러 사람이 참여하는 프로젝트 조직 프로세스에 대한 경험을 얻으려면 이들 중 하나 이상에 참여하십시오. GitHub에는 이러한 프로세스를위한 훌륭한 도구가 있습니다. README.md최상위 레벨의 문서 파일과 디렉토리 및 라이센스 파일을 사용하여 유용한 작업을 수행 합니다.
• 라이브러리, API 및 문서에 대한 피드백을 얻으려면 공동 작업자를 참여시키는 것이 좋습니다.
  • 릴리스하면 한 명 이상의 공동 작업자가 휴가 중일 때 버그를 수정하고, 사용자 질문에 답변하고, 코드 검토를 통해 풀 요청을 시작하여 라이브러리 해제 작업을 분할하는 데 도움이됩니다. 프로젝트 관리 및 라이브러리 디자인에 대한 추가 경험을 제공합니다.
• 지금까지 선형 git commit history를 수행했습니다. 결국 특정 수정 및 변경에 "발행 지점", 릴리스로 제어 된 런업을위한 "릴리스 지점"및 병합 할 준비가되지 않은 진행중인 여러 사람 작업에 대해서는 "개발 지점"을 사용하는 것이 유용합니다. 마스터 지점으로. 따라서 git 기술에 의존하기 전에 이것에 대해 배우고 연습을 시작하기 위해 하루나 이틀을 따로 준비하십시오. git은 매우 유연하고 유용하지만 사용자 인터페이스 는 혼란 스러울 수 있습니다 .
  • git 브랜치와 그 사용법에 대해 읽을 수있는 곳 은 Pro Git 책 입니다. 브랜치를 사용 하는 많은 방법 중에서 "문제 브랜치"로 시작하십시오.
  • GitHub Desktop 앱은 브랜치를 관리하는 훌륭한 도구입니다. 또한 모든 변경 사항을 검토하면서 커밋 메시지를 쉽게 작성할 수 있으므로 커밋에 좋습니다.