게시 됨 업데이트 됨Programming / Python15분안에 읽기 (약 2261 단어)

Python - 파이썬 프로젝트 패키징과 배포하기

파이썬에서 작업한 소스를 공개/비공개 배포하기 위해서 패키징을 하는 방법을 요약, 정리했다.

파이썬 모듈 배포하기

이 글은 setuptools, builds 그리고 PyPI 업로드를 위한 twine 를 사용하고 있다.

[핵심 용어]

  • PyPi, Python Package Index: 파이썬 사용자를 위한 오픈소스 패키지의 공개 저장소 일명 PyPi
  • PyPa, 파이썬 패키징 위원회: 표준 패키징 도구/메타 데이터/파일 형식 표준을 GitHub 와 Bitbucket 을 통해서 여러 패키징 도구, 문서, 이슈 추적기를 관리하고 있다.
  • distutils: 1998년/파이썬 표준 라이브러리 최초의 빌드 및 배포 시스템. 대부분 직접 사용이 단계적으로 폐지되고 있다.
    • distutils는 파이썬 3.10부터 deprecated, 3.12에서 삭제될 예정.
  • setuptools : 2004 공개/ distutils 의 드롭인(drop-in) 대체품. distutils 와 큰 차이는 다른 패키지에 대한 의존성을 선언할 수 있다.
  • [pyproject.toml]: 2016년 setuptools의 메타 파일 setup.py 의존성을 피하고자 독립한 빌드용 선언적 메타정보 파일.
  • wheel: distutils/setuptools 에 bdist_wheel 명령을 추가하는 프로젝트이다. 파이썬 라이브러리를 바이너리 확장을 포함/크로스 플랫폼 바이너리 패키징 형식 지원 (“휠”,”휠 파일”, PEP 427 정의).

도구 설치

setuptools 기반 배포도구 설치

1
python -m pip install setuptools wheel twine

파이썬 패키징

https://packaging.python.org/en/latest/tutorials/packaging-projects/ 내용을 요약, 정리, 보충한다.

프로젝트 생성

패키징 수행하면 별도의 가상환경을 생성해서 진행한다.

프로젝트를 패키징하는 과정을 위해서 packaging_tutorial 폴더 아래에 같은 구조를 갖는다.

1
2
3
4
5
packaging_tutorial/
└── src/
    └── example_package_YOUR_USERNAME_HERE/
        ├── __init__.py
        └── example.py
  • example_package_YOUR_USERNAME_HERE : 프로젝트 이름이고 중복하지 않게 한다.
  • __init__.py : 빈 파일로 폴더를 패키지로 인식하게 한다.
  • example.py : 모듈.

example.py 모듈 소스.

1
2
def add_one(number):
    return number + 1

패키징용 파일 생성

배포를 위한 프로젝트의 구성을 위해 패키징에 필요한 파일을 추가한 구조는 아래 같다.

1
2
3
4
5
6
7
8
9
packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
└── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
└── tests/
  • LICENSE : 라이센서 선언
  • pyproject.toml : 프로젝트 배포 프로젝트 생성에 사용하는 프론트엔드 빌드도구 pip, 백엔드 밸드도구 build
  • README.md
  • tests/ : 테스트 파일용 공간. Leave it empty for now.

패키징의 프론트엔드, 백엔드는 참조의 5번 항목을 살펴보자.

pyproject.toml 구성

보통 파일 내용은 아래 항목으로 구성한다. 이 파일은 TOML 형식의 구조를 따르고 있다. 여기에 대해서는 아래 참조 4번 항목 내용을 보기 바란다.

1
2
3
4
5
6
7
8
9
[build-system]
...

[project]
...

[project.urls]
...

빌드 도구를 명시하는 명세서 pyproject.toml에 setuptools 를 사용한 예이다.

1
2
3
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
  • requires : 빌드용 도구 지시.
  • build-backend : 프론트엔드 (pip)에서 빌드에 사용하는 백엔드 도구

다음은 Hatching 이란 빌드 도구를 사용한 예이다.

1
2
3
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

메타 정보를 포함한 간단한 pyproject.toml 구성 결과.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"

자세한 메타 정보 내역은 프로젝트 메타정보 정의를 참조한다. 주요 메타 정보의 인자:

  • [project]:
    • requires-python : 패키지가 요구하는 최소 파이썬 버전 명시
    • classifiers: pip가 인지하는 패키지에 대한 정보

README.md / LICENSE 파일

README.md 파일에 패키지 모듈를 설명한다.

1
2
3
4
5
# Example Package

This is a simple example package. You can use
[Github-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

LICENSE 파일에 저작권을 명시한다.

1
2
3
Copyright (c) 2018 The Python Packaging Authority

Permission is hereby granted, free of charge, to any person obtaining a copy

배포 묶음 생성하기

배포를 위한 build 도구를 설치한다.

1
python3 -m pip install --upgrade build

packaging_tutorial 폴더 아래 pyproject.toml 파일이 있는 위치에서 배포를 위한 build 명령으로 소스를 패키징을 한다.

build 를 수행하면 별도의 venv 가상환경을 생성해서 의존성에 명시된 setuptools 등을 설치하고 빌드를 진행한다.

1
2
3
4
5
6
7
> python3 -m build
* Creating venv isolated environment...
* Installing packages in isolated environment... (setuptools>=61.0)
...
...
removing build\bdist.win-amd64\wheel
Successfully built example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz and example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl

이 명령의 결과로 dist 폴더에 우리 프로젝트에 대한 배포용 패키징으로 소스 패키징 .gz 파일, built distribution 패키징 .whl 2개의 파일이 생성된다.

1
2
3
dist/
├── example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
└── example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz

pip 로 wheeels 설치하기

pip 에서 built distribution 파일을 직접 설치할 수 있다. installing-from-wheels 참조.

다음은 우리 프로젝트의 wheel 패키징을 설치한다.

1
python -m pip install example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl

혹은 provides_extras 메타 정보를 사용해 추가 설치를 한다면,

1
python -m pip install './somepackage-1.0-py2.py3-none-any.whl[my-extras]'

Upload

처음 PyPi 에 업로드를 하려면 아래 2가지 단계를 거쳐서 진행해 본다.

  1. https://test.pypi.org/account/register/ 에서 등록
    1. 실제 pypi 가 아닌 튜토리얼과 테스트를 위한 곳.
  2. PyPi 업로드를 완성하려면 PyPI API token 을 발급받아야 한다.
    1. https://test.pypi.org/manage/account/#api-tokens

PyPI에 업로드가 완료되면 pip 를 통해서 패키지를 설치할 수 있다. 업로드를 위해서 Twin 패키지를 설치하고 사용해야 한다.

1
python3 -m pip install --upgrade twine

twine 모듈을 사용해서 dist/ 아래의 모든 소스/휠 패키징 묶음을 업로드할 수 있다. 지금은 testpypi 에 업로드를 해보자.

1
python3 -m twine upload --repository testpypi dist/*
  • 업로드시 username은 __token__ 사용.
  • 패스워드는 발급받은 pypi- 으로 시작하는 token 값.

업로드 진행은 아래 같을 것이다.

1
2
3
4
5
6
7
Uploading distributions to https://test.pypi.org/legacy/
Enter your username: __token__
Uploading example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.2/8.2 kB • 00:01 • ?
Uploading example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.8/6.8 kB • 00:00 • ?

여기서 repository로 testpypi 를 지정했으므로 업로드한 결과는 다음 같이 확인할 수 있다.

  • https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE

저장소에서 설치하기

위에 testpypi 에 업로드한 패키지를 설치하려면 아래 같이 --index-url 로 저장소를 지정해서 사용한다.

1
python3 -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-YOUR-USERNAME-HERE

PyPI 에 업로드

마지막으로 실제 패키지를 PyPI에 업로드하려면 https://pypi.org 등록을 하고, 등록한 사용자 아이디를 사용하고 --repository 인자를 제외하고 업로드하면 된다.

1
python3 -m twine upload dist/*

통합 메타 정보로서 pyproject.toml 활용

테스트, 코드 포맷팅 등에 대한 정보로 활용한다. 대표적으로는 코드 포맷팅 도구인 black, 테스트용 프레임워크인 pytest 등이 pyproject.toml에 설정 값을 저장하고 있다 - 파이썬 패키징의 역사, blog

1
2
3
4
5
# pyproject.toml of black
[tool.black]
line-length = 88
target-version = ['py36', 'py37', 'py38']
include = '\.pyi?$'

다음

이후에 다른 빌드 도구들, 테스트 도구들을 다뤄보자.

참고

  1. 파이썬 모듈 배포하기, python.org
  2. Tool recommendations, python.org
    1. 주요 패키징에 필요한 도구 안내
  3. 파이썬 패키징의 역사, blog
  4. TOML의 이해와 기본 활용, itworld
  5. Python package의 build frontend 와 backend
 게시 됨 업데이트 됨Programming / git14분안에 읽기 (약 2046 단어)

bitbuket 에 SSH key 등록하기

github, bitbucket 같은 클라우드 사이트에 Client 프로그램으로 SSH 접속을 위해서는 SSH 키 쌍 생성하고 클라우드 사이트에 등록해야 한다. 보통 github, bitbucket 등 같은 SSH 접근을 지원하는 사이트는 ssh-agent forwarding 방식을 사용한다.

  1. 클라이언트에서 ssh 키 쌍을 생성
  2. 클라이언트에 개인키를 ssh-agent 에 등록
  3. 클라우드 서비스에 공개키를 등록
  4. 클라이언트 프로그램에서 ssh 사용시 ssh-agent 등록한 개인키로 암호화

여기서는 bitbucket 을 예로 들고 있다.

과정은 bitbucket 을 예로 들었지만 github 도 유사한 과정을 거친다. github에서 Key 등록에 대해서는 링크를 참조한다. github 에 SSH key 등록하기


SSH 구성과 2단계 인증

Git Credential Manager (GCM) 를 git client 에서 bitbucket 에 접속해 사용하는데 이용할 수 있다. SSH 구성을 하지 않고 bitbucket 을 사용하려면 GCM 을 사용하면 된다. Git Credential Manager

단, GCM works over HTTPS, not SSH. 그래서 git clone https://{username}@bitbucket.org/{workspace}/{repository}.git 이렇게 요청해야 한다.

설명에 따라서 먼저 ssh host key 를 생성하고 bitbucket 에서 사용하는 개인용 ssh key 를 만든다. 이후 bitbucket 에 등록하면 된다.

SSH Client Keys

저장소에 접근하는 url은 HTTPS or SSH 에 따라 달라진다.

  1. HTTPS

https://<repo_owner>@bitbucket.org/<accountname>/<reponame>.git

  1. SSH

git@bitbucket.org:<repo_owner>/<reponame>.git

or

ssh://git@bitbucket.org/<repo_owner>/<reponame>.git

bitbucket은 암호 알고리즘으로 keys: Ed25519, ECDSA, RSA, and DSA 를 지원한다.

예를 들어 아래 같이 생성한 공개키를 사용할 수 있다.

1
2
3
4
5
6
7
8
9
10
11
#Ed25519 (ed25519) / 256
$ ssh-keygen -t ed25519 -b 256

# ECDSA (ecdsa) / 256
$ ssh-keygen -t ecdsa -b 256

# RSA (rsa) / 2048
$ ssh-keygen -t rsa -b 2048

# DSA / DSS (dsa) / 1024
$ ssh-keygen -t dsa -b 1024

SSH Host Key 생성

아래는 bitbucket 서버의 공개키 이다.

1
2
3
256 SHA256:FC73VB6C4OQLSCrjEayhMp9UMxS97caD/Yyi2bhW/J0 bitbucket.org (ECDSA)
256 SHA256:ybgmFkzwOSotHTHLJgHO0QN8L0xErw6vd0VhFA9m3SM bitbucket.org (ED25519)
2048 SHA256:46OSHA1Rmj8E8ERTC6xkNcmGOw9oFxYr0WF6zWW8l1E bitbucket.org (RSA)

해당 공개키가 적적할지 확인은 다음 같이 curl 로 테스트해볼 수 있다.

1
curl https://bitbucket.org/site/ssh

개별키 생성

ssh 를 사용해서 bitbucket 클라우드에 접근하려면 사용하는 클라이언트에서 SSH 로 개인키와 공개키를 생성해야 한다. SSH 키를 생성하려면 아래 과정이 필요하다.

  1. Open SSH 설치
  2. SSH 서비스
  3. SSH 키 생성

여기서 Linux/macOS 그리고 Windows 11 에서 키 쌍을 생성해서 bitbucket에 등록하는 과정을 살펴보겠다.


Windows 11에서 키 생성

Windows 11 에서 Git 이 설치되어 있다고 가정.

1
2
3
> get-command git

Application     git.exe                                            2.38.1.1   C:\Program Files\Git\cmd\git.exe

Openssh 확인

1
2
> ssh -V
OpenSSH_for_Windows_8.6p1, LibreSSL 3.4.3

ssh 명령 위치 확인

1
> Get-Command ssh

결과 ssh 명령을 git config 로 ssh 명령을 지정

1
git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

SSH agent 시작

git 이 ssh 키를 사용하려면 SSH agent 가 시작되어야 한다. 보통 Git for windows 와 Windows 11 이후 Windows OpenSSH 를 사용하므로

Windows OpenSSH 사용자는 다음 같이 agent를 확인하고 시작한다.

1
2
3
4
5
> Get-Service ssh-agent

Status   Name               DisplayName
------   ----               -----------
Stopped  ssh-agent          OpenSSH Authentication Agent

ssh-agent 서비스를 시작 하려면 Windows service에서 OpenSSH Authenticate Agent 서비스를 시작해 두어야 한다.

속성에서 시작으로 한다.

서비스가 정상적으로 시작되면 아래 명령으로 시작/종료 그리고 재시작을 할 수 있다. - 시작 안되어 있으면 알수없는 에러가 난다.

1
> Start-Service ssh-agent

Git for windows 를 사용하면 Git for windows의 bash 터미널 에서 다음 같이 확인하고 시작한다.

1
$ ps -a | grep ssh-agent

ssh-agent 를 시작한다.

1
$ eval $(ssh-agent)

에이젼트가 시작되면 git client 에서 ssh 정보를 얻을 수 있다.

bitbucket에 사용할 SSH key pair를 생성

ssh-keygen.exe로 키 쌍, 비밀키/공개키를 생성한다. 키를 생성시 bitbucket 계정의 e-mail 을 포함해 생성한다. 생성시 사용자 홈 디렉토리 .ssh 디렉토리에서 작업한다.

1
> ssh-keygen.exe -t rsa -b 4096 -C "EMAIL" -f "KEY_FILE"
  • EMAIL: bitbucket 계정 이메일
  • KEY_FILE: 파일 이름. 보통 bitbucket_work

.ssh 디렉토리에 키 쌍 KEY_FILE 과 KEY_FILE.pub 이 생성된다.

1
2
3
4
5
6
7
8
9
10
> dir .ssh

    Directory: C:\Users\daddy\.ssh

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---        2023-06-25  오후 6:11           3381 bitbucket_work
-a---        2023-06-25  오후 6:11            744 bitbucket_work.pub
-a---        2020-11-08 오전 12:12           1675 id_rsa
-a---        2020-11-08 오전 12:12            404 id_rsa.pub

이제 키를 SSH Agent 에 등록하자.

SSH Agent 에 키 등록

키 파일을 SSH Agent 에 등록한다. KEY_FILE 은 비밀키 파일을 지정하면 된다.

1
> ssh-add ~/.ssh/KEY_FILE

그리고 명확하게 bitbucket 에 해당 키를 사용하도록 ~/.ssh/config 에 아래 같이 등록한다.

1
2
3
Host bitbucket.org
  AddKeysToAgent yes
  IdentityFile ~/.ssh/KEY_FILE

macOS / Linux

Openssh 확인

1
2
$ ssh -V
OpenSSH_8.2p1 macOS, OpenSSL 1.1.1f  31 Mar 2020

ssh 명령이 없으면 macOS는 brew 로 설치한다.

1
$ brew install openssh

Linux 는 apt, dnf, pacman 을 사용해 설치한다.

1
$ sudo apt update && sudo apt install openssh-client

SSH agent 시작

git 에서 ssh 키를 사용하려면 SSH agent 가 시작한다. bash 터미널 에서 다음 같이 확인하고 시작한다.

1
$ ps -a | grep ssh-agent

ssh-agent 를 시작한다.

1
$ eval $(ssh-agent)

이 명령을 ~/.bashrc, ~/.zshrc, ~/.profile, 등에 등록해 둔다. 에이젼트가 시작되면 git client 에서 ssh 정보를 얻을 수 있다.

bitbucket에 사용할 SSH key pair를 생성

ssh-keygen.exe로 키 쌍, 비밀키/공개키를 생성한다.

  • 키를 생성시 bitbucket 계정의 e-mail 을 포함해 생성한다.
  • 사용자 홈 디렉토리 .ssh 디렉토리에서 작업한다.
1
$ ssh-keygen -t rsa -b 4096 -C "EMAIL" -f "KEY_FILE"
  • EMAIL: bitbucket 계정 이메일
  • KEY_FILE: 파일 이름. 보통 bitbucket_work

.ssh 디렉토리에 키 쌍 KEY_FILE 과 KEY_FILE.pub 이 생성된다.

1
2
3
4
5
6
7
8
$ ls -l .ssh

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---        2023-06-25  오후 6:11           3381 bitbucket_work
-a---        2023-06-25  오후 6:11            744 bitbucket_work.pub
-a---        2020-11-08 오전 12:12           1675 id_rsa
-a---        2020-11-08 오전 12:12            404 id_rsa.pub

이제 키 쌍를 SSH Agent 에 등록하자.

SSH Agent 에 키 등록

키 파일을 SSH Agent 에 등록한다. KEY_FILE 은 비밀키 파일을 지정하면 된다.

1
$ ssh-add ~/.ssh/KEY_FILE

그리고 명확하게 bitbucket 에 해당 키를 사용하도록 ~/.ssh/config 에 아래 같이 등록한다.

1
2
3
Host bitbucket.org
  AddKeysToAgent yes
  IdentityFile ~/.ssh/KEY_FILE

Bitbucket Cloud with your public key

bitbucket 을 위해 생성한 키 쌍에서 공개키 KEY_FILE.pub 를 bitbucket 의 계정에 등록해 주어야 한다.

  1. Settings -> Personal Settings
  1. Secutiry -> SSH Keys -> Add key

생성한 키 쌍에서 bitbucket_work.pub 같이 공개키를 등록하는데, 공개키 파일 내용을 복사해 붙여넣기를 하면 된다.

cat 명령 등으로 내용을 복사한다.

1
2
3
4
5
> cat .\.ssh\bitbucket_work.pub
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDo+7VGfxlhxFsy0Edu+PPmqngJVzwLQuLPanOi5x8t2yu7RmFNlEfU32AgA7vkoLno98XFZaUZ3ZjMwVu7LWeLMNczx5nH//
...
...
+v7ttamzvFe8idOtCjJszG5l8rn4poIN2E24AWGvCGbzs55WRXY/amYEqP5/maH0NT+pYM2ZMV7Nt8Jb86iQ== james@thinkbee.kr

사이트의 Add key 창에 붙여 넣는다.

이제 새 SSH 키가 등록되었다.

클라이언트에서 bitbucket 에 SSH 접속이 가능한지 테스트한다. 단, 모든 SSH 연결은 최초 접속시 호스트 접속 여부를 묻는다. 아래 같이 bitbucket.org 접속시 접속 여부를 묻는 다이얼로그가 나온다.

1
2
3
4
5
6
7
8
9
$ ssh -T git@bitbucket.org
The authenticity of host 'bitbucket.org (104.192.141.1)' can't be established.
ED25519 key fingerprint is SHA256:ybgmFkzwOSotHTHLJgHO0QN8L0xErw6vd0VhFA9m3SM.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added 'bitbucket.org' (ED25519) to the list of known hosts.
authenticated via ssh key.

You can use git to connect to Bitbucket. Shell access is disabled

결과적으로 아래 같이 결과가 출력되면 성공한 상태다.

1
2
3
authenticated via ssh key.

You can use git to connect to Bitbucket. Shell access is disabled

이제 git 클라이언트에서 HTTPS, SSH 를 통해서 bitbucket 과 ssh 연결이 가능하다. git 클라이언트로 push, pull 등을 수행할 수 있다.

참고

  1. https://support.atlassian.com/bitbucket-cloud/docs/configure-ssh-and-two-step-verification/
  2. github 에 SSH key 등록하기
팔로우

최근 글

광고

카테고리

×