Mga module at package ng Python: import, pip, venv, at library sa simpleng salita

Ang module sa Python ay ordinaryong file na may code, at ang import ang paraan para kunin mula rito ang mga function at class. Mula sa mga module nabubuo ang mga package, at mula sa mga package ang mga library. Para hindi magkagulo ang mga third-party na library ng iba't ibang proyekto, inilalagay ang mga ito sa virtual environment na venv. Tatalakayin natin ang buong kadena: ano ang nangyayari kapag nag-import, paano nakaayos ang package, paano gumagana ang pip at venv sa Python, at ano ang mga lazy import na lumitaw sa Python 3.15.

Module, package, library: ano ang pagkakaiba

Madalas paghaluin ang mga salitang "library", "package", at "module" sa usapan — normal lang iyon. Ang mahalaga, sa teknikal na paraan, palaging nilo-load ng import ang module o package, at ang pip ay nag-i-install ng distribution mula sa PyPI, na naglalaman ng mga package.

Paano gumagana ang import sa Python

May ilang anyo ng import, at lahat ay makikita sa totoong code:

import math                    # buong module, gamit ang math.sqrt
from math import sqrt, pi      # mga partikular na pangalan
import datetime as dt          # alias
from collections import Counter as C

print(math.sqrt(16), sqrt(9), pi)
print(dt.date.today())

Karaniwan na ang mga alias para sa malalaking library: import numpy as np, import pandas as pd. Huwag gamitin ang from module import *: pinupuno nito ang namespace at tinatago kung saan galing ang pangalan.

Ano ang aktwal na ginagawa ng import

1. Hinahanap ang module sa cache na sys.modules. Kung na-load na ito, ibinabalik lang.
2. Kung wala, hinahanap ang file sa listahan ng folder na sys.path: folder ng script na pinapatakbo, standard library, at site-packages ng environment.
3. Pinapatakbo ang nakitang file mula itaas pababa, buo.
4. Inilalagay ang object ng module sa cache at tinatalian ng pangalan.

Dalawang praktikal na konklusyon dito. Halos libre ang ulit na import ng parehong module — hindi na muling tinatakbo ang code. At ang lahat ng code sa antas ng itaas ng module, kasama ang print at mabibigat na kalkulasyon, ay tumatakbo na sa pag-import.

import sys
for p in sys.path:
    print(p)
print("math" in sys.modules)

if __name__ == "__main__"

Dahil pinapatakbo ng import ang file, kailangan ng paraan para malaman kung "pinatakbo ako bilang script" o "ini-import ako". Ginagamit para dito ang variable na __name__: kapag pinatakbo ang file, "__main__" ang halaga nito; kapag ini-import, pangalan ng module ang halaga.

# categories.py
def guess(title: str) -> str:
    return "pagkain" if "kape" in title.lower() else "iba"

if __name__ == "__main__":
    print(guess("Kapehan sa bahay"))   # tatakbo lang kapag python categories.py

Para sa package, may alternatibo: ang file na __main__.py sa loob nito at ang pagpapatakbo gamit ang python -m expenses.

Mga standard module ng Python

Dumarating ang Python na "may kasamang baterya": daan-daang built-in na module ang available agad, nang walang pag-install. Ang pinakagamit ay:

Makikita ang buong listahan ng mga module ng standard library sa sys.stdlib_module_names (Python 3.10+). Para malaman ang laman ng isang module, gamitin ang dir(math) at help(math).

Sariling package: istruktura ng proyekto

Kapag dumami ang mga module, pinagsasama-sama ang mga ito sa package. Karaniwang ayos ang src-layout:

expenses-project/
├── pyproject.toml
└── src/
    └── expenses/
        ├── __init__.py
        ├── cli.py
        ├── parsing.py
        ├── categories.py
        └── report.py

Sa loob ng package, nag-iimport ang mga module sa isa't isa sa pamamagitan ng pangalan ng package (from expenses.categories import guess) o kamag-anak (from .categories import guess). Gumagana lang ang relative import sa loob ng package, hindi sa file na direktang pinatakbo bilang script.

pip sa Python: pag-install ng library

Nasa PyPI ang mga third-party na library, at ini-install ang mga ito ng pip, na kasama ng Python. Pinakamaaasahang tawagin ito sa pamamagitan ng interpreter — sa ganitong paraan, siguradong mapupunta ang library sa Python na ginagamit mo sa pagpapatakbo ng code.

python -m pip install requests          # mag-install
python -m pip install "pandas>=2.3"     # may limitasyon sa bersyon
python -m pip install --upgrade requests
python -m pip uninstall requests        # magtanggal
python -m pip list                      # listahan ng naka-install na package
python -m pip show requests             # bersyon at dependency
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

Sa Windows, madalas gamitin ang launcher na py sa halip na python. Kung hindi mahanap ang pip, ini-install ito ng built-in na module: python -m ensurepip --upgrade.

Mga sikat na library sa Python

Daan-daang libo ang package sa PyPI, pero sa karamihan ng proyekto, iisang maikling listahan ang lumilitaw. Dito dapat magsimula, hindi sa paghahanap ng kakaiba.

Pansinin: hindi laging magkapareho ang pangalan para sa pag-install at pangalan para sa pag-import. Ini-install ang pip install pillow, pero isinusulat ang from PIL import Image; ini-install ang opencv-python, pero ang ina-import ay cv2. Kung bumagsak ang import kaagad pagkatapos mag-install, tingnan sa dokumentasyon ng package kung anong pangalan ang ginagamit sa pag-import.

Pag-install ng library sa Linux

Sa mga bagong bersyon ng Debian at Ubuntu, nagtatapos sa error na externally-managed-environment (PEP 668) ang pip install sa system Python. Proteksiyon ito: pag-aari ng package manager ng OS ang system Python, at hindi dapat ito sirain ng pip. Ang tamang solusyon ay hindi ang --break-system-packages, kundi ang virtual environment.

venv sa Python: virtual environment

Ang virtual environment ay hiwalay na folder na may sariling kopya ng interpreter (o reference dito) at sariling site-packages. Nakikita lang ng proyektong ito ang mga library na naka-install dito. Kaya maaaring gumamit ang isang proyekto ng Django 4, at ang kalapit na proyekto ng Django 5, nang walang alitan.

Built-in sa Python ang module na venv, kaya hindi na ito kailangang i-install nang hiwalay. (Sa Debian/Ubuntu, minsan kailangan ang system package na python3-venv.)

# gumawa ng environment sa folder na .venv
python -m venv .venv

# i-activate: Linux at macOS
source .venv/bin/activate
# i-activate: Windows PowerShell
.venv\Scripts\Activate.ps1

# mula ngayon, ang pip ay nag-i-install sa loob ng .venv
python -m pip install requests
python -c "import sys; print(sys.prefix)"

# lumabas sa environment
deactivate

Pagkatapos i-activate, lalabas ang (.venv) sa simula ng linya ng terminal. Huwag i-commit sa git ang folder ng environment (idagdag ang .venv/ sa .gitignore), at huwag itong ilipat sa ibang makina — sa halip, itago ang listahan ng dependency at muling gawin ang environment. Kung hinaharangan ng PowerShell ang pagpapatakbo ng activation script, payagan ito para sa user: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

uv at pyproject.toml

Inilalarawan ng mga modernong proyekto ang kanilang dependency sa pyproject.toml. Pinagsasama ng uv, na ginagamit sa kurso, ang paggawa ng environment at pag-install: ang uv add pandas ay nagda-download ng package, isinusulat ito sa pyproject.toml, at tinatandaan ang eksaktong bersyon sa uv.lock. Kapag na-clone ng kasamahan ang proyekto at pinatakbo ang uv sync, makukuha niya ang parehong environment.

[project]
name = "expenses"
version = "0.1.0"
requires-python = ">=3.15"
dependencies = [
    "pandas>=2.3",
]

[project.scripts]
expenses = "expenses.cli:main"

Mga lazy import sa Python 3.15 (PEP 810)

Ang pangunahing bagong katangian ng 3.15 sa paksang ito ay ang keyword na lazy. Mabagal i-load ang mabibigat na library: sa sukat ng kurso sa imahe ng python:3.15-slim, humigit-kumulang 415 ms ang karaniwang import pandas, at humigit-kumulang 13 ms ang lazy import pandas. Para sa CLI na utility na pinapatakbo para lang sa --help, napakalaki ng pagkakaiba.

lazy import pandas as pd
lazy from expenses.report import build_report

def main() -> None:
    ...
    df = pd.read_csv(path)   # dito talaga nilo-load ang pandas

Sa halip na module, inilalagay sa pangalan ang proxy object (types.LazyImportType), at nagaganap ang totoong import sa unang paggamit ng pangalan. Kung hindi ito nagamit, walang oras na nasasayang.

Mga limitasyon ng lazy import

• Pinapayagan lamang sa antas ng itaas ng module: sa loob ng function, class, o try/except — SyntaxError.
• Ipinagbabawal ang lazy from x import *.
• Lalabas ang ModuleNotFoundError hindi sa pagsisimula, kundi sa unang paggamit.
• Nagbabago ang oras ng side effect ng module (pagre-rehistro ng plugin, at iba pa).

Maaaring gawing lazy ang lahat ng import nang sabay gamit ang flag na -X lazy_imports=all o ang variable na PYTHON_LAZY_IMPORTS=all; ang mga eksepsiyon ay itinatakda gamit ang sys.set_lazy_imports_filter(). Para sa code na dapat gumana rin sa mas lumang bersyon, may module variable na __lazy_modules__ = ["pandas"]: gagawing lazy ito ng 3.15, at ang mas lumang bersyon ay magsasagawa lamang ng karaniwang import. Ipinapakita ng python -X importtime -c "import pandas" kung saan napupunta ang oras sa pagsisimula. Pinakanakikinabang dito ang mga programang madalas tumakbo nang maikli; halos walang epekto ito sa matagal nang tumatakbong server.

Karaniwang pagkakamali

• ModuleNotFoundError: No module named 'requests' — na-install ang library sa ibang Python, o hindi na-activate ang environment. Tingnan gamit ang python -m pip show requests gamit ang parehong interpreter.
• Pinangalanan ang sariling file na json.py, random.py, o csv.py — nasa unahan ng sys.path ang folder ng script at tinatakpan nito ang standard module. Mula Python 3.13, may mungkahing "consider renaming" sa error. Palitan ang pangalan ng file at burahin ang __pycache__.
• Circular import: nag-iimport ang a.py ng b.py, at ang b.py naman ay ng a.py. Ilagay ang nakabahaging code sa ikatlong module, o mag-import sa loob ng function.
• Pinatakbo ang pip sa loob ng interpreter ng Python (>>> pip install) — SyntaxError ang makukuha mo. Ang mga utos ng pip ay pinapatakbo sa terminal.

Buod

Ang module ay file, ang package ay folder ng mga module, at ang library ay handang hanay nito; hinahanap ng import ang module sa cache at sa sys.path, at pinapatakbo ito nang isang beses. Ang mga third-party na library ay i-install gamit ang pip o uv lamang sa virtual environment na venv — sa ganitong paraan, hindi nagbabanggaan ang mga proyekto, at madaling maulit ang environment. Tinalakay ang paksang ito nang praktikal sa kurso ng Python: nagiging package na may mga dependency ang tagasubaybay ng gastos, at mas mabilis ang pagsisimula dahil sa mga lazy import.