Python 패키지 __init__.py 파일 설정 방법 | Python 패키지 구조

소개

__init__.py 파일을 올바르게 설정하는 것은 잘 구조화된 Python 패키지를 만드는 데 중요한 단계입니다. 이 튜토리얼에서는 __init__.py의 목적을 이해하고, Python 패키지를 구성하며, 코드를 더 유지 관리하고 재사용 가능하게 만들기 위해 __init__.py 파일을 구성하는 방법을 안내합니다.

이 Lab 에서는 간단한 Python 패키지를 단계별로 생성하고 __init__.py 파일을 사용하여 코드를 효과적으로 구조화하는 방법을 배웁니다. 이 Lab 을 마치면 Python 패키지 구성 및 모범 사례에 대한 확실한 이해를 갖게 될 것입니다.

`init.py`의 목적 이해

Python 프로그래밍에서 __init__.py 파일은 디렉토리가 패키지로 취급되어야 함을 Python 에 알리는 마커 역할을 합니다. 이 파일은 관련 코드를 구조화되고 재사용 가능한 형식으로 구성할 수 있게 해줍니다.

Python 패키지란 무엇인가?

Python 패키지는 디렉토리 구조로 구성된 Python 모듈 (파일) 의 모음입니다. 이러한 구성은 관련 코드를 함께 그룹화하여 애플리케이션을 더 쉽게 관리하고 배포할 수 있도록 도와줍니다.

간단한 Python 패키지 구조를 만들어 보겠습니다.

WebIDE 에서 터미널을 열고 프로젝트 디렉토리로 이동합니다.

cd ~/project

패키지를 위한 새 디렉토리를 만듭니다.

mkdir calculator_package

패키지 디렉토리 내에 빈 __init__.py 파일을 만듭니다.

touch calculator_package/__init__.py

초기 패키지 구조를 확인해 보겠습니다.

ls -la calculator_package/

다음과 같은 출력이 표시됩니다.

total 8
drwxr-xr-x 2 labex labex 4096 ... .
drwxr-xr-x 3 labex labex 4096 ... ..
-rw-r--r-- 1 labex labex    0 ... __init__.py

이 시점에서 __init__.py 파일은 비어 있지만, calculator_package 디렉토리가 패키지로 취급되어야 함을 Python 에 알리는 마커 역할을 합니다. 다음 단계에서는 이 파일을 구성하여 패키지의 기능을 향상시키는 방법을 살펴보겠습니다.

기본 패키지 테스트

패키지를 가져올 수 있는지 확인하기 위해 간단한 테스트 스크립트를 만들어 보겠습니다.

WebIDE 에서 프로젝트 디렉토리에 test_package.py라는 새 파일을 만듭니다.
파일에 다음 코드를 추가합니다.

import calculator_package

print("calculator_package 을 성공적으로 가져왔습니다!")

테스트 스크립트를 실행합니다.

python3 test_package.py

다음과 같은 출력이 표시됩니다.

Successfully imported calculator_package!

이것은 기본 패키지 구조가 올바르게 설정되었음을 확인합니다. 빈 __init__.py 파일이 있어도 Python 은 디렉토리를 패키지로 인식하고 가져올 수 있도록 합니다.

패키지 내 모듈 생성

이제 Python 패키지의 기본 구조를 설정했으므로, 패키지 내에 모듈을 생성하여 실제 기능을 추가해 보겠습니다.

패키지에 모듈 추가

모듈은 단순히 함수, 클래스 또는 변수를 포함하는 Python 파일입니다. 계산기 패키지에 대한 몇 가지 모듈을 만들어 보겠습니다.

덧셈 연산을 위한 모듈을 만듭니다.

touch calculator_package/addition.py

WebIDE 에서 addition.py 파일을 열고 다음 코드를 추가합니다.

def add_two_numbers(a, b):
    """Add two numbers and return the result."""
    return a + b

def add_multiple_numbers(*args):
    """Add multiple numbers and return the result."""
    return sum(args)

이제 곱셈 연산을 위한 모듈을 만듭니다.

touch calculator_package/multiplication.py

WebIDE 에서 multiplication.py 파일을 열고 다음 코드를 추가합니다.

def multiply_two_numbers(a, b):
    """Multiply two numbers and return the result."""
    return a * b

def multiply_multiple_numbers(*args):
    """Multiply multiple numbers and return the result."""
    result = 1
    for num in args:
        result *= num
    return result

업데이트된 패키지 구조를 확인해 보겠습니다.

ls -la calculator_package/

다음과 같은 출력이 표시됩니다.

total 16
drwxr-xr-x 2 labex labex 4096 ... .
drwxr-xr-x 3 labex labex 4096 ... ..
-rw-r--r-- 1 labex labex    0 ... __init__.py
-rw-r--r-- 1 labex labex  xxx ... addition.py
-rw-r--r-- 1 labex labex  xxx ... multiplication.py

개별 모듈 테스트

모듈이 올바르게 작동하는지 확인하기 위해 테스트 스크립트를 만들어 보겠습니다.

프로젝트 디렉토리에 test_modules.py라는 새 파일을 만듭니다.
파일에 다음 코드를 추가합니다.

from calculator_package.addition import add_two_numbers
from calculator_package.multiplication import multiply_two_numbers

## Test addition
result1 = add_two_numbers(5, 3)
print(f"5 + 3 = {result1}")

## Test multiplication
result2 = multiply_two_numbers(5, 3)
print(f"5 * 3 = {result2}")

테스트 스크립트를 실행합니다.

python3 test_modules.py

다음과 같은 출력이 표시됩니다.

5 + 3 = 8
5 * 3 = 15

이것은 모듈이 올바르게 작동함을 확인합니다. 그러나 현재 가져오기 구문 (from calculator_package.addition import add_two_numbers) 은 다소 장황합니다. 다음 단계에서는 __init__.py 파일을 구성하여 패키지에서 함수를 더 편리하게 가져올 수 있도록 하겠습니다.

`init.py` 파일 구성

이제 모듈로 패키지 구조를 만들었으므로, __init__.py 파일을 구성하여 패키지를 사용자 친화적으로 만들 차례입니다. __init__.py 파일은 다음 용도로 사용할 수 있습니다.

모듈에서 특정 함수 또는 클래스를 가져오기
패키지 수준 변수 정의
패키지가 가져올 때 초기화 작업 수행

패키지 수준에서 함수 사용 가능하게 만들기

__init__.py 파일을 구성하여 특정 함수를 패키지 수준에서 직접 노출해 보겠습니다.

WebIDE 에서 __init__.py 파일을 열고 다음 코드를 추가합니다.

## Import functions from modules
from .addition import add_two_numbers, add_multiple_numbers
from .multiplication import multiply_two_numbers, multiply_multiple_numbers

## Define package-level variables
__version__ = "0.1.0"
__author__ = "Your Name"

## Print a message when the package is imported
print(f"Calculator Package v{__version__} initialized")

이 구성은 몇 가지 중요한 작업을 수행합니다.

상대 가져오기 (모듈 이름 앞에 점이 있음) 를 사용하여 모듈에서 특정 함수를 가져옵니다.
패키지 수준 변수 __version__ 및 __author__를 정의합니다.
패키지가 가져올 때 메시지를 출력합니다.

가장 중요한 장점은 사용자가 이제 내부 모듈 구조를 몰라도 패키지에서 직접 함수를 가져올 수 있다는 것입니다.

구성된 패키지 테스트

향상된 가져오기 경험을 보여주기 위해 새 테스트 파일을 만들어 보겠습니다.

프로젝트 디렉토리에 test_configured_package.py라는 새 파일을 만듭니다.
파일에 다음 코드를 추가합니다.

## Import functions directly from the package
from calculator_package import add_two_numbers, multiply_multiple_numbers
from calculator_package import __version__

## Display package version
print(f"Using Calculator Package version: {__version__}")

## Test addition function
result1 = add_two_numbers(10, 5)
print(f"10 + 5 = {result1}")

## Test multiplication function
result2 = multiply_multiple_numbers(2, 3, 4)
print(f"2 * 3 * 4 = {result2}")

테스트 스크립트를 실행합니다.

python3 test_configured_package.py

다음과 같은 출력이 표시됩니다.

Calculator Package v0.1.0 initialized
Using Calculator Package version: 0.1.0
10 + 5 = 15
2 * 3 * 4 = 24

패키지가 가져올 때 초기화 메시지가 출력되고 __version__ 변수를 통해 패키지 버전에 액세스할 수 있음을 확인하십시오. 가장 중요한 것은 이제 함수가 속한 모듈을 지정하지 않고도 패키지에서 직접 함수를 가져올 수 있다는 것입니다.

추가 패키지 구성 기술

더 큰 프로젝트의 경우 하위 패키지로 패키지를 구성할 수 있습니다. 이를 보여주기 위해 간단한 하위 패키지를 만들어 보겠습니다.

고급 연산을 위한 하위 패키지 디렉토리를 만듭니다.

mkdir calculator_package/advanced

하위 패키지에 대한 __init__.py 파일을 만듭니다.

touch calculator_package/advanced/__init__.py

하위 패키지에 모듈을 만듭니다.

touch calculator_package/advanced/scientific.py

WebIDE 에서 scientific.py 파일을 열고 다음 코드를 추가합니다.

import math

def square_root(x):
    """Calculate the square root of a number."""
    return math.sqrt(x)

def power(x, y):
    """Calculate x raised to the power of y."""
    return math.pow(x, y)

하위 패키지의 __init__.py 파일을 구성합니다.

calculator_package/advanced/__init__.py 파일을 열고 다음을 추가합니다.

from .scientific import square_root, power

print("Advanced calculator functions loaded")

주 패키지의 __init__.py 파일을 업데이트하여 하위 패키지를 포함합니다.

calculator_package/__init__.py의 끝에 이 줄을 추가합니다.

## Import the advanced subpackage
from . import advanced

하위 패키지를 테스트합니다.

프로젝트 디렉토리에 새 파일 test_subpackage.py를 만듭니다.

from calculator_package.advanced import square_root, power

## Test square root
result1 = square_root(16)
print(f"Square root of 16 = {result1}")

## Test power
result2 = power(2, 3)
print(f"2 raised to the power of 3 = {result2}")

테스트를 실행합니다.

python3 test_subpackage.py

다음과 같은 출력이 표시됩니다.

Calculator Package v0.1.0 initialized
Advanced calculator functions loaded
Square root of 16 = 4.0
2 raised to the power of 3 = 8.0

이것은 하위 패키지를 사용하여 더 복잡한 Python 패키지를 구성하는 방법을 보여줍니다.

완전한 패키지 구조 만들기

이제 Python 패키지의 기본 원리와 __init__.py 파일의 역할을 이해했으므로, 모범 사례를 따르는 보다 완전한 패키지 구조를 만들어 보겠습니다. 이렇게 하면 더 큰 프로젝트를 효과적으로 구성하는 데 도움이 됩니다.

패키지 구조에 대한 모범 사례

잘 구성된 Python 패키지는 일반적으로 다음과 같은 구조를 따릅니다.

package_name/
├── __init__.py
├── module1.py
├── module2.py
├── subpackage1/
│   ├── __init__.py
│   └── module3.py
├── subpackage2/
│   ├── __init__.py
│   └── module4.py
├── README.md
├── setup.py
└── tests/
    ├── __init__.py
    ├── test_module1.py
    └── test_module2.py

계산기 패키지에 대한 이 구조의 단순화된 버전을 구현해 보겠습니다.

README.md 파일을 만듭니다.

touch ~/project/calculator_package/README.md

WebIDE 에서 README.md 파일을 열고 다음을 추가합니다.

Calculator Package

기본 및 고급 계산기 기능을 제공하는 간단한 Python 패키지입니다.

기능

기본 산술 연산 (덧셈, 곱셈)
고급 과학 연산 (제곱근, 거듭제곱)

사용법

from calculator_package import add_two_numbers, multiply_two_numbers
from calculator_package.advanced import square_root, power

## Basic operations
result1 = add_two_numbers(5, 3)
result2 = multiply_two_numbers(4, 2)

## Advanced operations
result3 = square_root(16)
result4 = power(2, 3)

tests 디렉토리를 만듭니다.

mkdir ~/project/calculator_package/tests
touch ~/project/calculator_package/tests/__init__.py

테스트 파일을 만듭니다.

touch ~/project/calculator_package/tests/test_basic.py

WebIDE 에서 test_basic.py를 열고 다음을 추가합니다.

import unittest
from calculator_package import add_two_numbers, multiply_two_numbers

class TestBasicOperations(unittest.TestCase):

    def test_addition(self):
        self.assertEqual(add_two_numbers(5, 3), 8)
        self.assertEqual(add_two_numbers(-1, 1), 0)

    def test_multiplication(self):
        self.assertEqual(multiply_two_numbers(5, 3), 15)
        self.assertEqual(multiply_two_numbers(-2, 3), -6)

if __name__ == '__main__':
    unittest.main()

패키지 배포를 위한 setup.py 파일을 만듭니다.

touch ~/project/setup.py

WebIDE 에서 setup.py를 열고 다음을 추가합니다.

from setuptools import setup, find_packages

setup(
    name="calculator_package",
    version="0.1.0",
    author="Your Name",
    author_email="your.email@example.com",
    description="A simple calculator package",
    packages=find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires=">=3.6",
)

단위 테스트를 실행해 보겠습니다.

cd ~/project
python3 -m calculator_package.tests.test_basic

다음과 유사한 출력이 표시됩니다.

Calculator Package v0.1.0 initialized
..
----------------------------------------------------------------------
Ran 2 tests in 0.001s

OK

이것은 패키지가 잘 구성되었고 테스트가 올바르게 작동함을 확인합니다.

Docstrings 를 사용한 패키지 문서화

좋은 문서는 모든 Python 패키지에 필수적입니다. 패키지에 적절한 docstring 을 추가해 보겠습니다.

패키지 수준 docstring 을 포함하도록 calculator_package/__init__.py 파일을 업데이트합니다.

"""
Calculator Package - A collection of calculator functions.

This package provides various calculator functions including basic
arithmetic operations and advanced scientific operations.
"""

## Import functions from modules
from .addition import add_two_numbers, add_multiple_numbers
from .multiplication import multiply_two_numbers, multiply_multiple_numbers

## Define package-level variables
__version__ = "0.1.0"
__author__ = "Your Name"

## Print a message when the package is imported
print(f"Calculator Package v{__version__} initialized")

## Import the advanced subpackage
from . import advanced

Python 의 help 함수를 사용하여 docstring 을 볼 수 있습니다.

cd ~/project
python3 -c "import calculator_package; help(calculator_package)"

이렇게 하면 패키지 문서가 표시됩니다.

Help on package calculator_package:

NAME
    calculator_package - Calculator Package - A collection of calculator functions.

DESCRIPTION
    This package provides various calculator functions including basic
    arithmetic operations and advanced scientific operations.

PACKAGE CONTENTS
    addition
    advanced (package)
    multiplication
    tests (package)

DATA
    __author__ = 'Your Name'
    __version__ = '0.1.0'

FILE
    /home/labex/project/calculator_package/__init__.py

이 문서는 사용자가 패키지의 목적과 기능을 이해하는 데 도움이 됩니다.

요약

이 랩에서는 __init__.py 파일을 사용하여 Python 패키지를 올바르게 설정하고 구성하는 방법을 배웠습니다. 이제 다음을 이해하게 되었습니다.

패키지 마커 및 구성 파일로서의 __init__.py 파일의 목적
패키지 내에서 모듈을 구성하는 방법
패키지 수준에서 함수와 클래스를 사용할 수 있도록 하는 방법
패키지 메타데이터 및 초기화 코드를 포함하는 방법
하위 패키지, 테스트 및 문서를 사용하여 완전한 Python 패키지를 구성하는 방법

이러한 기술은 잘 구성되고 유지 관리 가능하며 재사용 가능한 Python 코드를 만드는 데 도움이 됩니다. 프로젝트의 복잡성이 증가함에 따라 적절한 패키지 구조는 코드를 관리하고 다른 개발자와 협업하는 데 점점 더 중요해집니다.

이제 이러한 개념을 자신의 Python 프로젝트에 적용하여 더욱 모듈화되고 전문적으로 만들 수 있습니다.

Python 패키지에서 __init__.py 파일을 올바르게 설정하는 방법

소개

__init__.py의 목적 이해

Python 패키지란 무엇인가?

기본 패키지 테스트

패키지 내 모듈 생성

패키지에 모듈 추가

개별 모듈 테스트

__init__.py 파일 구성

패키지 수준에서 함수 사용 가능하게 만들기

구성된 패키지 테스트

추가 패키지 구성 기술

완전한 패키지 구조 만들기

패키지 구조에 대한 모범 사례

Calculator Package

기능

사용법

Docstrings 를 사용한 패키지 문서화

요약

Python 패키지에서 init.py 파일을 올바르게 설정하는 방법

`init.py`의 목적 이해

`init.py` 파일 구성