초보자를 위한 Python 코드베이스 구성 및 유지 관리 단계

제가 이 글을 쓰는 이유는 많은 기여자들과 함께 프로젝트를 깨끗하게 유지하는 방법에 대한 통찰력을 공유하기 위해서입니다. 끊임없이 변화하는 데이터의 특성과 Python 라이브러리 및 애플리케이션의 처리 요구를 고려할 때 이는 데이터 엔지니어에게 특히 중요합니다.

제목이 다소 클릭을 유도하는 것처럼 들릴 수도 있지만, 다음 단계를 따르면 Python 코드를 관리하기가 훨씬 쉬워질 것입니다. 당신이 선임 개발자라면 아마도 여기서 새로운 것을 발견하지 못할 것입니다. 걱정하지 마십시오. 당신을 위한 재미있는 밈이 있습니다.

1단계: 버전 관리

사소해 보일 수도 있지만 실제로 로컬 컴퓨터에만 코드를 저장하고 다른 곳에 백업하지 않았기 때문에 코드를 잃어버린 사람들을 실제로 알고 있습니다. GitHub, GitLab 및 Bitbucket과 같은 플랫폼에서 작동하는 Git과 같은 여러 버전 제어 시스템을 사용할 수 있습니다. 많은 사람들이 Git을 선택하지만 SVN(Subversion) 및 Mercurial과 같은 다른 버전 제어 시스템은 여전히 ​​코드 관리에서 중요한 역할을 합니다.

이 가이드에서는 기본 데이터 처리를 설명하기 위해 단일 함수가 포함된 작은 데모 Python 라이브러리를 만들려고 합니다. 완전한 툴킷은 아니지만 코드 품질, 환경 관리, CI/CD 워크플로우와 같은 모범 사례를 보여주는 간단한 예입니다.

시작하기 위해 blog_de_toolkit이라는 데모 Python 라이브러리용 저장소를 만들었습니다. 공개되어 있으므로 자유롭게 포크하고 기존 코드를 자신의 프로젝트의 시작점으로 사용하세요. 좋은 문서가 필수적이기 때문에 제안된 빈 README 파일을 포함했습니다. 그리고 저장소를 깔끔하게 유지하기 위해 불필요한 파일이 업로드되는 것을 방지하기 위해 기본 Python .gitignore 템플릿을 추가했습니다.

이제 저장소가 있으므로 복제할 수 있습니다.

여기서 Git 명령을 자세히 다루지는 않겠습니다. 온라인에서 많은 튜토리얼을 찾을 수 있습니다. 일반 터미널 CLI 사용을 좋아하지 않는다면 더욱 시각적이고 직관적인 인터페이스를 제공하는 GitHub Desktop 또는 SourceTree와 같은 도구를 사용하여 리포지토리를 관리할 수도 있습니다.

개인적으로 GitHub Desktop을 사용하는 것을 정말 좋아합니다. 이제 저장소를 로컬 컴퓨터에 복제하고 원하는 IDE에서 열어 보겠습니다.

지금까지 얻은 내용을 살펴보겠습니다.

시작하기에 나쁘지 않습니다!

2단계: 프로젝트 구조

2단계에서는 de_toolkit 프로젝트를 구성하겠습니다. 좋은 구조는 물건을 찾기 쉽고 모든 것을 깔끔하게 유지합니다. 코드, 테스트, 문서용 폴더를 만들어 구축할 간단하고 깔끔한 프레임워크를 설정하겠습니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

추가할 모든 유용한 코드를 위한 기본 폴더, 향후 단위 테스트를 위한 tests 폴더, 저장소에서 불필요한 파일을 보관하기 위한 .gitignore가 있습니다. 프로젝트를 설치 가능하게 만드는 기본 설정인 setup.py 파일도 있습니다. 자세한 내용은 나중에 8단계: 배포 패키지 만들기에서 다루므로 지금은 자세히 다루지 않겠습니다.

프로젝트 구조를 설정할 때 일관성을 유지하는 것이 큰 차이를 만듭니다. 프로젝트가 성장함에 따라 data_tools.py를 csv_tools.py 및 json_tools.py로 분할하는 것과 같이 작업을 더 작은 모듈로 나누는 것이 좋습니다. 이렇게 하면 긴 파일을 뒤질 필요 없이 필요한 것을 더 쉽게 관리하고 찾을 수 있습니다.

docs/ 폴더를 추가하는 것도 몇 가지 메모로 시작하더라도 현명한 조치입니다. 이는 귀하(및 다른 사람들)가 프로젝트가 진행됨에 따라 작업이 어떻게 진행되는지 추적하는 데 도움이 될 것입니다. YAML 또는 JSON과 같은 구성으로 작업하는 경우 configs/ 폴더를 사용하면 작업을 깔끔하게 유지하는 데 도움이 될 수 있습니다. 자동화 또는 테스트용 스크립트를 작성할 계획이라면 scripts/ 폴더를 사용하여 정리된 상태로 유지하세요.

이 시점에서 프로젝트 구축을 계속하려면 몇 가지 추가 라이브러리를 설치해야 합니다.

3단계: 개발 환경

물론, 명령줄에서 pip install을 실행하여 필요한 종속성을 설치할 수 있습니다. 하지만 각각 다른 버전의 Python과 라이브러리가 필요한 여러 프로젝트를 저글링하는 경우에는 어떻게 될까요? 가상 환경은 특정 Python 버전을 포함하여 각 프로젝트의 종속성을 격리하므로 모든 것이 자립적이고 독립적으로 유지됩니다.

다행히도 가상 환경을 생성할 수 있는 도구가 꽤 많이 있으므로 자신에게 가장 적합한 도구를 선택할 수 있습니다.

• 가상 환경

• 벤브

• 콘다

• pyenv

• pipenv

• 시

개인적으로 pyenv를 좋아하는 편이라 여기서는 이걸 사용하겠습니다. 업무 및 개인 프로젝트를 위해 항상 사용하는 노트북이기 때문에 이미 노트북에 설치해 두었습니다.

Python 설치부터 시작해 보겠습니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

pyenv가 이 Python 버전을 인식하지 못하는 경우 먼저 업데이트해 보세요. 예를 들어, Mac을 사용하고 Homebrew와 함께 pyenv를 설치한 경우 다음을 실행하세요.

pyenv install 3.12.2

ModuleNotFoundError: '_lzma'라는 모듈이 없습니다. 오류가 발생하면 다음을 시도해 보세요.

brew update && brew upgrade pyenv

다음으로 프로젝트 폴더에 새로운 가상 환경을 만들어 보겠습니다.

brew install readline xz

이제 로컬 Python 버전을 방금 생성한 가상 환경으로 설정하세요.

pyenv virtualenv 3.12.2 de_toolkit

MacOS에서 명령을 실행한 후 환경이 전환되지 않으면 해결 방법이 포함된 유용한 온라인 스레드가 있습니다. 모든 것이 올바르게 설정되면 다음과 같이 명령줄 시작 부분에 de_toolkit이 표시됩니다.

이제 종속 항목을 설치해 보겠습니다.

pyenv local de_toolkit

다음으로, 설치된 모든 패키지와 해당 버전을 요구사항.txt 파일에 저장하겠습니다. 이를 통해 프로젝트의 종속성을 쉽게 공유하거나 다른 곳에서 동일한 환경을 다시 만들 수 있습니다.

pip install setuptools wheel twine pandas 

설치된 패키지 목록은 다음과 같습니다.

물론 원하는 경우 요구사항.txt 파일을 편집하여 기본 라이브러리와 해당 버전만 유지할 수도 있습니다.

4단계: 자격 증명 및 비밀 관리

이 단계는 매우 중요합니다. 아마도 가장 중요한 단계 중 하나일 것입니다. 자격 증명이 GitHub 리포지토리에 노출되거나 민감한 토큰이 실수로 공개적으로 공유된다는 끔찍한 이야기를 들어보셨을 것입니다. 이를 방지하려면 처음부터 민감한 정보를 코드에서 제외하는 것이 중요합니다. 그렇지 않으면 데이터베이스 비밀번호를 하드코딩했다는 사실을 잊어버리고 변경 사항을 푸시한 후 붐을 일으키기 쉽습니다. 이제 귀하의 자격 증명이 공개됩니다.

하드 코딩된 비밀번호, API 키 또는 데이터베이스 자격 증명은 주요 보안 위험입니다. 이것이 공개 저장소로 만들어지면 전체 시스템이 손상될 수 있습니다. 비밀을 처리하는 가장 안전한 방법은 비밀을 환경 변수나 .env 파일에 저장하는 것입니다. 이러한 변수를 Python 프로젝트에 로드하는 데 도움이 되도록 python-dotenv 라이브러리를 사용합니다. .env 파일에서 키-값 쌍을 읽고 코드에서 환경 변수로 사용할 수 있도록 합니다.

먼저 다음을 사용하여 라이브러리를 설치합니다.

pip freeze > requirements.txt

프로젝트 폴더에 다음 콘텐츠가 포함된 .env 파일을 만듭니다.

pip install python-dotenv

이제 python-dotenv:

를 사용하여 이러한 비밀을 로드하도록 data_tools.py를 수정해 보겠습니다.

load_dotenv()를 호출하면 현재 디렉터리에서 .env 파일을 검색하고 해당 내용을 환경에 로드합니다. os.getenv()를 사용하면 코드에서 이러한 변수에 안전하게 액세스하여 자격 증명을 소스 코드와 격리하고 우발적인 노출 위험을 줄일 수 있습니다.

중요한 팁은 .env 파일을 버전 관리에 적용하지 않는 것입니다. 실수로 푸시되는 것을 방지하려면 .gitignore에 추가하세요.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

VSCode를 사용하는 경우 .env * 파일을 자동으로 인식하는 유용한 dotenv 확장 프로그램이 있습니다. 터미널에서 작업하는 것을 선호한다면 다음과 같이 *.env 파일을 내보낼 수 있습니다.

pyenv install 3.12.2

5단계: 코드 작성

프로젝트 작업을 할 때 이해하고 관리하기 쉬운 작고 재사용 가능한 함수를 작성해 보세요. 좋은 경험 법칙은 다음과 같습니다. “두 번 이상 사용한다면 함수로 변환하세요.”

data_tools.py에서 CSV에서 데이터를 로드하고 정리하는 등 일반적인 데이터 엔지니어링 논리를 보여주는 함수를 만들어 보겠습니다.

전문가 팁: Python에서 함수 및 변수 이름을 지정하려면 snake_case

를 사용하세요. 그러면 코드가 일관되고 읽기 쉬워집니다. x 또는 df2와 같은 비밀스러운 이름은 피하세요. 명확하고 설명적인 이름을 사용하면 코드 작업이 더 쉬워집니다.

우리는 함수가 수행하는 작업, 매개변수 및 반환 유형을 설명하기 위해 여기서 독스트링을 사용합니다. 이를 통해 다른 개발자(및 미래의 개발자)가 기능 사용 방법을 쉽게 이해할 수 있습니다. 널리 사용되는 여러 독스트링 규칙이 있지만 가장 일반적인 규칙으로는 PEP 257, Google 스타일 및 NumPy 스타일이 있습니다.

더 작은 기능의 경우 PEP 257이면 충분하지만 더 복잡한 프로젝트의 경우 Google 또는 NumPy 스타일이 더 명확성과 구조를 제공합니다.

예제의 file_path: str과 같이 Python에서 힌트를 입력하면 함수 입력 및 출력에 대해 예상되는 데이터 유형이 표시됩니다. 명확한 기대치를 설정하여 가독성을 높이고 버그를 잡는 데 도움을 주며 공동 작업을 더 쉽게 만듭니다.

다음은 유형 힌트가 함수 서명을 어떻게 개선하는지 보여주는 예입니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

이 예에서 file_path: str 유형 힌트는 인수가 문자열이어야 한다는 것을 보여주고, -> pd.DataFrame은 함수가 Pandas DataFrame을 반환함을 나타냅니다. 이렇게 하면 함수의 동작을 한눈에 쉽게 이해할 수 있습니다. 유형 힌트는 PyCharm, VSCode 또는 mypy와 같은 IDE 및 Linter와도 잘 작동하여 호환되지 않는 유형이 전달될 경우 자동 완성 및 조기 경고를 제공합니다.

함수가 여러 유형을 반환하거나 None을 반환할 수 있는 경우 입력 모듈에서 Optional을 사용할 수 있습니다.

pyenv install 3.12.2

이는 함수가 문자열 또는 None을 반환할 수 있음을 나타냅니다. 더 복잡한 데이터 구조의 경우 타이핑 모듈에서 List, Dict 또는 Tuple을 사용하여 예상 유형을 지정할 수 있습니다.

6단계: 테스트 작성

단위 테스트를 작성하는 것은 예상치 못한 상황 없이 코드가 예상대로 작동하는지 확인하는 간단한 방법입니다. 모든 것이 여전히 예상대로 작동한다는 사실을 알고 버그를 조기에 발견하고 자신 있게 변경하는 데 도움이 됩니다. Python에는 각각의 장점과 생태계를 갖춘 단위 테스트에 사용할 수 있는 여러 라이브러리가 있습니다.

• 유닛 테스트

• pytest

• 코2

• 가설

이 가이드에서는 간단하고 유연하며 사용하기 쉬운 pytest를 사용하겠습니다. 다음을 사용하여 설치할 수 있습니다.

brew update && brew upgrade pyenv

다음으로 tests/ 폴더 안에 test_data_tools.py라는 파일을 만듭니다. 이전에 구현한 코드에 대한 몇 가지 테스트를 작성해 보겠습니다. 다음은 load_and_clean_data() 함수 및 환경 변수 검색 논리에 대한 샘플 테스트입니다.

test_load_and_clean_data()에서는 StringIO를 사용하여 CSV 파일을 입력으로 시뮬레이션합니다. 이를 통해 실제 파일 없이도 테스트할 수 있습니다. 테스트에서는 함수가 중복 및 NaN 값을 올바르게 제거하는지 확인하고, DataFrame에 누락된 데이터가 없는지 확인하고, "이름" 열의 고유 항목이 올바른지 확인합니다.

test_get_database_url()과 test_get_api_key()에서는 pytest에서 제공하는 유틸리티인 monkeypatch를 사용하여 테스트 중에 환경 변수를 임시로 설정합니다. 이렇게 하면 실제 환경 변수 없이도 함수가 예상 값을 반환할 수 있습니다.

모든 테스트를 실행하려면 다음 명령을 실행하면 됩니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

제가 pytest를 좋아하는 이유 중 하나는 유연성입니다. 이는 고정 장치, 매개변수화된 테스트 및 플러그인과 같은 강력한 기능을 제공하여 기본 단위 테스트를 뛰어넘습니다. Fixture를 사용하면 여러 테스트에서 재사용할 수 있는 테스트 데이터 또는 구성을 설정하여 코드를 DRY(반복하지 마세요)로 유지할 수 있습니다. 매개변수화된 테스트를 사용하면 서로 다른 입력으로 동일한 테스트를 실행하여 시간을 절약하고 중복을 줄일 수 있습니다. pytest의 기능을 확장해야 하는 경우 Django 앱 테스트, 코드 적용 범위 측정, HTTP 요청 모의 등을 위한 광범위한 플러그인 생태계가 있습니다.

7단계: 코드 품질 및 사전 커밋 후크

높은 코드 품질을 유지하면 코드를 쉽게 읽고 유지 관리할 수 있으며 일반적인 버그가 발생하지 않습니다. 여러 가지 도구를 사용하면 일관된 코딩 표준을 적용하고, 자동으로 코드 형식을 지정하고, 잠재적인 문제를 조기에 감지할 수 있습니다. 인기 있는 옵션으로는 pylint, flake8, black, Detect-secrets

등이 있습니다.

• pylint는 코딩 표준을 시행하고 일반적인 오류를 잡아냅니다.

• flake8은 스타일 위반 및 논리적 오류를 감지하는 도구를 결합합니다.

• black은 코드가 PEP8 표준을 따르도록 보장하는 독보적인 포맷터입니다.

• Detect-secrets는 코드를 스캔하여 하드 코딩된 비밀이 노출되는 것을 방지합니다.

다음 도구를 사용하여 설치할 수 있습니다.

pyenv install 3.12.2

예를 들어 특정 파일이나 디렉터리에서 pylint를 실행합니다.

brew update && brew upgrade pyenv

코드 개선을 위한 경고와 제안이 포함된 보고서를 받게 됩니다. 특정 경고를 무시하려면 다음을 사용하세요.

brew install readline xz

flake8을 사용하여 스타일 문제와 논리적 오류를 찾을 수도 있습니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

코드 형식을 자동으로 지정하려면 black:

을 실행하세요.

pyenv install 3.12.2

변경할 때마다 이러한 도구를 수동으로 실행하는 대신 커밋 전 후크를 사용하여 프로세스를 자동화할 수 있습니다. 사전 커밋 후크는 각 커밋 전에 자동으로 실행되어 도구가 실패할 경우 커밋을 차단합니다.

먼저 pre-commit 패키지를 설치합니다.

brew update && brew upgrade pyenv

다음으로, 프로젝트 디렉토리에 다음 내용으로 .pre-commit-config.yaml 파일을 생성합니다(여기서는 제가 가장 좋아하는 기본 사전 커밋을 모두 사용했습니다).

로컬 저장소에서 사전 커밋 후크를 활성화합니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

이제 커밋을 시도할 때마다 이러한 도구가 자동으로 실행됩니다. 도구가 실패하면 문제가 해결될 때까지 커밋이 차단됩니다. 코드베이스 전체에서 모든 후크를 수동으로 실행할 수도 있습니다.

pyenv install 3.12.2

8단계: 배포 패키지 만들기

이제 프로젝트를 빌드하고, 코드를 작성하고, 테스트를 추가하고, 커밋 전 후크를 설정했으므로 다음 단계는 다른 사람(또는 미래의 우리)이 이를 쉽게 사용할 수 있는 방법을 알아내는 것입니다. 프로젝트를 패키징하면 이것이 가능해집니다. 모든 것을 깔끔하게 묶어서 파일을 수동으로 복사하지 않고도 설치하고 사용할 수 있습니다.

프로젝트를 공유하려면 패키지를 올바르게 구성하고, 의미 있는 README를 작성하고, 시작 스크립트를 만들고, 배포 패키지를 생성해야 합니다. 좋은 README에는 일반적으로 프로젝트 이름과 해당 기능에 대한 간략한 설명, 설치 지침, 사용 예, 환경 설정을 위한 개발 지침 및 기여 지침이 포함됩니다. 저장소에서 blog_de_toolkit 프로젝트에 대한 간단한 README.md 예제를 찾을 수 있습니다.

모든 Python 패키지의 핵심에는 setup.py 파일이 있습니다. 이 파일은 프로젝트를 패키징하고 설치하는 데 필요한 메타데이터와 구성을 정의하는 곳입니다. 여기에는 프로젝트를 식별할 수 있는 이름, 버전, 설명이 포함됩니다. long_description은 README 파일을 읽어 사용자가 PyPI에서 프로젝트를 볼 때 프로젝트에 대한 더 많은 컨텍스트를 제공합니다. install_requires 목록에 종속성을 지정하여 패키지와 함께 자동으로 설치되도록 합니다. entry_points 섹션은 명령줄 인터페이스(CLI) 항목을 정의하므로 사용자는 터미널에서 도구를 실행할 수 있습니다. find_packages()를 사용하여 패키지의 모든 하위 모듈을 포함하고 classifiers 섹션에서는 프로젝트에서 사용하는 Python 버전 및 라이선스와 같은 메타데이터를 제공합니다. 마지막으로 python_requires 필드는 호환되는 Python 버전에만 패키지가 설치되도록 보장합니다. blog_de_toolkit 프로젝트에 대한 setup.py 구성은 다음과 같습니다.

setup.py가 구성되면 배포 패키지를 빌드할 수 있습니다. 다음을 사용하여 필요한 도구를 설치하는 것으로 시작하세요.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

그런 다음 패키지를 빌드합니다.

pyenv install 3.12.2

이 명령은 두 개의 배포 파일을 생성합니다.

• sdist: 소스 아카이브(예: .tar.gz)

• bdist_wheel: 빌드된 패키지(예: .whl)

이러한 파일은 dist/ 디렉터리에 있습니다. 패키지를 테스트하려면 다음을 사용하여 로컬로 설치하세요.

brew update && brew upgrade pyenv

다음을 실행하여 CLI 명령을 테스트할 수도 있습니다.

brew install readline xz

sample_data.csv에서 데이터베이스 URL, API 키 및 정리된 데이터를 인쇄해야 합니다.

패키지를 공개적으로 공유하려면 PyPI에 업로드하면 됩니다. 먼저 Twine을 설치하세요.

pyenv virtualenv 3.12.2 de_toolkit

그런 다음 패키지를 업로드하세요.

pyenv local de_toolkit

PyPI 자격 증명을 입력하라는 메시지가 표시됩니다. 업로드되면 다른 사람들이 다음을 사용하여 PyPI에서 직접 패키지를 설치할 수 있습니다.

pip install setuptools wheel twine pandas 

10단계: 기본 분기 보호

프로젝트가 성장함에 따라 더 많은 사람들이 동일한 코드베이스에서 종종 동시에 작업하게 됩니다. 적절한 보호 장치가 없으면 실수, 테스트되지 않은 코드 또는 우발적인 병합이 몰래 들어와서 문제를 일으키기 쉽습니다. 원활한 운영을 유지하고 높은 표준을 유지하려면 주요 지점을 보호하는 것이 필수적입니다. 이 단계에서는 브랜치 보호 규칙을 설정하는 방법을 살펴보고 풀 요청에 대한 원활한 코드 검토를 수행하기 위한 몇 가지 팁을 공유하겠습니다.

분기 보호 규칙은 누구도 테스트를 통과하거나 코드 검토를 받지 않고 기본 분기로 직접 푸시할 수 없도록 보장합니다. 이는 완료되지 않은 기능, 버그 또는 잘못된 코드가 몰래 들어와 프로젝트를 중단시키는 것을 방지합니다. 또한 끌어오기 요청을 요구하여 다른 사람에게 피드백을 제공할 기회를 제공함으로써 팀워크를 촉진합니다. 또한 테스트 및 린터와 같은 자동화된 검사를 통해 병합하기 전에 코드가 견고한지 확인합니다.

GitHub에서 분기 보호 규칙을 설정하는 것은 매우 간단합니다. 저장소의 설정으로 이동하여 “코드 및 자동화” 섹션에서 브랜치를 클릭하세요. 분기 보호 규칙을 찾아 분기 보호 규칙 추가를 클릭하세요. 지점 이름 필드에 main을 입력하고 이제 몇 가지 설정을 조정할 차례입니다.

풀 요청 검토를 요구하도록 분기 보호 규칙을 설정하여 병합되기 전에 누군가 코드를 확인하도록 할 수 있습니다. 상태 확인을 통해 테스트가 통과하고 Linter가 원활하게 실행되는지 확인하고 분기를 최신 변경 사항으로 최신 상태로 유지하면 충돌을 방지하는 데 도움이 됩니다. 필요한 경우 브랜치에 푸시할 수 있는 사람을 제한하거나 추가 보안을 위해 서명된 커밋을 요구할 수도 있습니다. 모든 것이 설정되면 만들기를 클릭하세요. 그러면 더 이상 직접 푸시하거나 테스트를 건너뛰지 않아도 됩니다.

풀 요청이 검토 대상이 되면 검토자가 작업을 쉽게 할 수 있도록 하는 것이 좋습니다. 변경 사항이 무엇인지, 왜 필요한지에 대한 명확한 설명부터 시작하세요. 업데이트된 내용을 반영하는 의미 있는 커밋 메시지를 사용하세요. 변경 사항이 작고 집중적이면 검토 프로세스가 더 원활하고 빨라집니다. 댓글에 정중하게 응답하고 요청된 변경 사항에 대해 후속 조치를 취하는 것을 잊지 마세요. 이는 피드백을 소중히 여기며 긍정적인 협업을 유지하는 데 도움이 된다는 것을 보여줍니다.

당신이 끌어오기 요청을 검토하는 사람이라면 당신의 임무는 단순히 실수를 찾아내는 것 이상으로 코드를 개선하고 팀원을 지원하는 것입니다. 변경 사항이 무엇을 달성하려고 하는지 이해하려면 풀 요청 설명을 읽는 것부터 시작하세요. 건설적인 피드백 제공에 집중하세요. 필요한 경우 대안을 제안하고 왜 더 나은 결과를 얻을 수 있는지 설명하세요. 간단한 “Nice refactor ?!”로 좋은 작품을 인정합니다. 긍정적인 리뷰 경험을 만드는 데에도 도움이 됩니다. 테스트가 존재하는지, 관련성이 있는지, 통과하는지 확인하기 위해 계속 주시하세요. 그리고 뭔가 명확하지 않은 경우 가정을 하기보다는 질문을 하세요. 결국 리뷰는 팀워크, 즉 함께 협력하여 더 나은 프로젝트를 만드는 것입니다.

리뷰 템플릿을 사용하면 모든 사람이 중요한 사항에 집중할 수 있게 하여 프로세스를 더욱 원활하게 만드는 데 도움이 될 수 있습니다. 다음은 풀 요청 검토 템플릿의 예입니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

이러한 템플릿을 기여 가이드라인에 추가하거나 저장소에 연결하면 검토자가 쉽게 추적할 수 있습니다. 또한 리뷰 전반에 걸쳐 일관성을 유지하여 팀이 깨끗하고 체계적인 코드베이스를 유지하는 데 도움이 됩니다.

11단계: CI/CD용 GitHub 작업

기본 브랜치를 보호하는 것의 중요성을 바탕으로 모든 코드 변경 사항을 병합하거나 배포하기 전에 적절하게 테스트, 검토 및 검증하는지 확인하는 것도 중요합니다. 지속적 통합(CI)과 지속적 전달/배포(CD)가 필요한 곳입니다. CI/CD는 테스트 실행, 코드 검사 수행, 변경 사항 배포 프로세스를 자동화하여 개발자에게 빠른 피드백을 제공하고 버그가 프로덕션에 유입될 가능성을 줄입니다.

GitHub Actions는 GitHub에 직접 통합된 자동화 도구입니다. 이를 통해 푸시 또는 풀 요청과 같은 리포지토리의 이벤트에 응답하는 워크플로를 생성할 수 있습니다. GitHub Actions에서는 몇 가지 주요 작업을 자동화하여 건강한 코드베이스를 유지할 수 있습니다. 예:

• 코드가 푸시되거나 풀 요청이 생성될 때마다 테스트를 실행하여 새로운 변경 사항으로 인해 문제가 발생하지 않는지 확인합니다.

• 일관적인 코딩 표준을 적용하기 위해 코드 스타일과 Linting을 확인합니다.

• 커밋 전 후크를 적용하여 코드 형식을 지정하고 후행 공백과 같은 작은 문제를 포착합니다.

• 모든 검사를 통과하면 문서를 생성하거나 코드를 배포할 수도 있습니다.

메인 브랜치에서 푸시 또는 풀 요청이 발생할 때마다 단위 테스트를 실행하고 사전 커밋 린터(예: 검정)를 적용하는 GitHub Actions 워크플로를 설정해 보겠습니다.

먼저 워크플로 파일을 만듭니다.

blog_de_toolkit/  
│  
├── de_toolkit/  
│   ├── __init__.py  
│   └── data_tools.py  
│  
├── tests/  
│   ├── __init__.py  
│   └── test_data_tools.py  
│  
├── .gitignore  
├── setup.py  
└── README.md

ci.yml의 콘텐츠는 다음과 같습니다.

이 워크플로는 코드가 푸시되거나 메인 브랜치에서 끌어오기 요청이 열릴 때마다 테스트 및 Linting을 자동화합니다. 코드가 병합되기 전에 모든 품질 검사가 통과되었는지 확인합니다. actions/checkout 작업은 저장소를 실행기에 복제하고 actions/setup-python을 사용하여 작업 흐름에 맞게 Python 3.12를 구성합니다. 종속성은 pip를 사용하여 요구사항.txt에서 설치됩니다. 그 후 모든 테스트는 pytest로 실행되고 사전 커밋 후크는 코드가 형식 지정 및 스타일 지침을 따르는지 확인합니다. 테스트나 확인이 실패하면 손상된 코드가 병합되는 것을 방지하기 위해 워크플로가 중지됩니다.

시험해 보겠습니다. 먼저, 메인에서 새 브랜치를 생성하고 몇 가지 사항을 변경하세요.

저의 경우 README 파일을 업데이트했습니다. 변경 사항을 커밋하고 메인 브랜치에 풀 요청을 엽니다.

이제 검토가 필요하며 GitHub Actions(GA)가 모든 검사를 실행하고 있음을 알 수 있습니다. 분기 보호 규칙에 의해 병합이 차단되더라도 내 권한이 보호 우회를 허용하기 때문에 "요구 사항이 충족될 때까지 기다리지 않고 병합"할 수 있습니다.

작업 탭에서 GitHub Actions 워크플로의 결과를 추적할 수 있습니다.

다음은 실행 중 pytest 단계가 어떻게 보이는지에 대한 예입니다.

12단계: 의미론적 버전 관리(SemVer)

프로젝트 버전을 수동으로 추적하는 것은 특히 버전이 커짐에 따라 지저분해질 수 있습니다. 이것이 의미적 버전 관리(SemVer)가 등장하는 곳입니다. MAJOR.MINOR.PATCH 패턴을 따라 각 릴리스에서 변경된 내용을 전달합니다. python-semantic-release를 사용하여 버전 관리를 자동화하면 이 작업이 더욱 쉬워집니다. 커밋 메시지를 분석하고, 변경 유형에 따라 버전을 높이고, 릴리스에 태그를 지정하고, 원하는 경우 패키지를 PyPI에 게시할 수도 있습니다. 이를 통해 버전 관리에 대한 추측을 없애고 일관성을 보장합니다.

원활한 버전 관리를 위해 python-semantic-release를 GitHub Actions에 직접 통합할 수 있습니다. 공식 문서는 메인 브랜치로 푸시할 때마다 버전 범프 및 릴리스를 자동화하는 워크플로를 제공합니다. 이 설정을 사용하면 릴리스 프로세스가 원활하게 진행되므로 수동으로 버전을 관리할 걱정 없이 코드 작성에 집중할 수 있습니다.

일반적인 작업 흐름 예 — python-semantic-release

이 작업을 수행하려면 커밋 메시지가 기존 커밋 표준을 따라야 합니다. 각 커밋 유형에 따라 해당 버전이 PATCH, MINOR 또는 MAJOR 수준

에 도달할지 여부가 결정됩니다.

• 수정: PATCH 버전 범프를 트리거합니다(예: 1.0.0 → 1.0.1).

• feat: MINOR 버전 범프를 트리거합니다(예: 1.0.0 → 1.1.0).

• 커밋 메시지의 주요 변경 사항: 또는 !은 주요 버전 범프(예: 1.0.0 → 2.0.0)를 유발합니다.

이러한 간단한 규칙을 따르면 각 새 버전에서 무엇을 기대할 수 있는지 항상 알 수 있습니다.

결론

우리는 프로젝트 구성과 비밀 관리부터 테스트 작성, 워크플로 자동화, 의미 체계 버전 관리를 통한 릴리스 처리에 이르기까지 모든 것을 다루었습니다. 올바른 도구와 프로세스를 사용하면 안정적이고 유지 관리가 가능한 프로젝트를 훨씬 더 원활하고 재미있게 구축할 수 있습니다.

핵심은 일관성을 유지하고, 가능한 부분을 자동화하고, 계속해서 개선하는 것입니다. 각각의 작은 단계는 시간이 지남에 따라 큰 차이를 만듭니다. 이제 여러분의 차례입니다. 직접 구축하고, 실험하고, 그 과정을 즐겨보세요! 다음 프로젝트에 이 단계를 적용해 보고 댓글로 여러분의 경험을 자유롭게 공유해 주세요!

위 내용은 초보자를 위한 Python 코드베이스 구성 및 유지 관리 단계의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!