Moduły i importy w Pythonie: import, from-import, pip i pakiety

Jeden plik to jeden moduł

Gdy twój kod w Pythonie przerośnie pojedynczy skrypt, zechcesz podzielić go na kilka plików. System modułów w Pythonie jest prosty: każdy plik .py automatycznie jest modułem, który można zaimportować po nazwie.

Powiedzmy, że masz plik util.py:

# util.py
def greet(name):
    return f"Hello, {name}"

PI = 3.14159

Z innego pliku w tym samym katalogu, main.py, możesz go użyć:

# main.py
import util

print(util.greet("Ada"))
print(util.PI)

Uruchom python3 main.py, a Python znajdzie util.py, wykona go raz i udostępni wszystko, co zdefiniowano na najwyższym poziomie (funkcje, zmienne, klasy), jako atrybuty modułu util.

Trzy formy importu

Import całego modułu. Do zawartości odwołujesz się przez nazwę modułu:

import math

print(math.sqrt(2))
print(math.pi)

Import konkretnych nazw. Stają się dostępne bezpośrednio:

from math import sqrt, pi

print(sqrt(2))
print(pi)

Import z aliasem. Przydaje się, gdy nazwa modułu jest długa albo gdy dwa moduły mają tę samą nazwę:

import numpy as np
import pandas as pd

# Teraz używaj np.array(...), pd.DataFrame(...) itd.

Istnieje czwarta forma, from math import *, która wciąga wszystko do twojej przestrzeni nazw. Unikaj jej poza eksperymentami w REPL: nie da się wtedy stwierdzić, skąd pochodzi dana nazwa, a do tego powstają ciche kolizje nazw.

Kiedy wykonują się importy

Python wykonuje kod najwyższego poziomu importowanego modułu raz, przy pierwszym imporcie w danym programie. Kolejne importy tego samego modułu zwracają już wczytaną wersję. Zatem to:

# setup.py
print("setup module loading...")
VALUE = 42

# main.py
import setup
import setup  # zaimportowany dwa razy, ale "loading" wypisuje się tylko raz
print(setup.VALUE)

Wypisuje "setup module loading..." tylko raz. To ważne: jeśli umieścisz efekty uboczne (na przykład otwieranie pliku albo wypisywanie) na najwyższym poziomie modułu, wydarzą się w chwili importu, a zwykle nie o to chodzi. Umieszczaj je w funkcjach.

Biblioteka standardowa

Python ma dużą bibliotekę standardową modułów. Kilka z nich już się pojawiło. Po niektóre będziesz sięgać bez przerwy:

• math: sqrt, sin, log, stałe takie jak pi i e.
• random: liczby losowe, losowy wybór, tasowanie.
• datetime: daty i czas.
• json: odczyt i zapis JSON.
• os, os.path: ścieżki i operacje na systemie plików.
• pathlib: nowoczesna obsługa ścieżek, często wygodniejsza niż os.path.
• re: wyrażenia regularne.
• collections: wyspecjalizowane typy kolekcji (Counter, defaultdict, deque itd.).
• itertools, functools: narzędzia do iteratorów i funkcji.
• csv: odczyt i zapis plików CSV.

Biblioteka standardowa jest już zainstalowana, nie trzeba niczego instalować przez pip.

import random

items = ["red", "green", "blue"]
print(random.choice(items))
print(random.randint(1, 100))

Zewnętrzne pakiety i pip

Na wszystko, czego nie obejmuje biblioteka standardowa, Python Package Index (PyPI) oferuje setki tysięcy pakietów. Instalujesz je przez pip:

pip install requests
pip install pandas
pip install --upgrade requests
pip uninstall requests

Po instalacji importuje się je jak wszystko inne:

import requests

response = requests.get("https://api.example.com/data")
print(response.status_code)

Kilka wskazówek, jak zarządzać tym z głową:

Używaj środowisk wirtualnych

Instalowanie wszystkiego globalnie kończy się bólem. Różne projekty potrzebują różnych wersji, niektóre pakiety zależą od konkretnych wersji Pythona, a w niektórych systemach globalna instalacja wymaga uprawnień administratora. Środowisko wirtualne to odizolowana instalacja Pythona tylko dla jednego projektu:

python3 -m venv .venv
source .venv/bin/activate    # macOS/Linux
.venv\Scripts\activate       # Windows

pip install requests

Gdy venv jest aktywne, pip instaluje pakiety do folderu projektu, a nie do systemu. Po skończonej pracy wyłącz je poleceniem deactivate.

Przypinaj zależności

Zapisz listę zainstalowanych pakietów, żeby inni (w tym ty w przyszłości) mogli odtworzyć to samo środowisko:

pip freeze > requirements.txt

A później:

pip install -r requirements.txt

Narzędzia takie jak Poetry, pipenv i uv robią to wygodniej, ale do nauki zwykły przepływ pip + requirements.txt w zupełności wystarczy.

Pisanie własnych modułów

Gdy masz funkcje, których chcesz używać w wielu plikach, umieść je we własnym module. Konwencje nazewnictwa:

• Nazwy plików powinny mieć postać lower_snake_case.py.
• Funkcje i zmienne na poziomie modułu też lower_snake_case.
• Klasy używają PascalCase.

# shopping.py
PRICES = {"apple": 0.50, "bread": 2.00}

def total(items):
    return sum(PRICES[item] for item in items)

# main.py
from shopping import total, PRICES

print(total(["apple", "bread"]))
print(PRICES)

Jeśli dwa pliki w tym samym folderze importują siebie nawzajem, możesz przypadkiem stworzyć import cykliczny. Zwykle rozwiązaniem jest przeniesienie wspólnego kodu do trzeciego pliku, który importują oba.

Pakiety: foldery z modułami

Gdy modułów jest więcej niż kilka, pogrupuj je w pakiet, czyli folder z plikiem __init__.py:

myproject/
├── main.py
└── utils/
    ├── __init__.py
    ├── text.py
    └── numbers.py

Potem:

from utils.text import slugify
from utils import numbers

print(slugify("Hello, World"))
print(numbers.mean([1, 2, 3]))

Plik __init__.py może być pusty; to jego obecność sprawia, że utils jest pakietem. Współczesny Python obsługuje też "pakiety przestrzeni nazw" bez __init__.py, ale na początek jawna wersja jest czytelniejsza.

Mała lista kontrolna, gdy importy się sypią

• "ModuleNotFoundError: No module named X". Albo pakiet nie jest zainstalowany, albo uruchamiasz Pythona z innego interpretera niż ten, dla którego wykonano pip install. W venv upewnij się, że środowisko jest aktywne.
• "ImportError: cannot import name Y from X". Moduł istnieje, ale nie ma w nim nazwy, o którą prosisz. Sprawdź literówki i zajrzyj do faktycznej zawartości modułu.
• "Circular import". Dwa moduły importują siebie nawzajem. Przenieś wspólny kod do trzeciego modułu.

Dalej: instalowanie zewnętrznych pakietów

Własne moduły zaprowadzą cię daleko, ale większość prawdziwych projektów korzysta też z bibliotek z PyPI: requests, pandas, frameworka do testów. Następna strona opisuje pip, czyste instalowanie pakietów i zapisywanie, od czego zależy twój projekt.