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

URL: https://skillaria.top/tl/guides/python/module-python-pip-venv

Ang module sa Python ay file na .py, ang package ay folder ng mga module, at ang library ay handang hanay ng mga package na ini-import gamit ang import. Ang mga third-party na library ay ini-install gamit ang pip (o uv) sa virtual environment na venv — hiwalay na folder na may sariling interpreter at mga package ng isang proyekto, para hindi magbanggaan ang mga bersyon ng iba't ibang proyekto.

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

| Konsepto | Ano ito | Halimbawa |
| --- | --- | --- |

| Module | Isang file na `.py`; ang pangalan ng module ay pangalan ng file na walang extension | `categories.py` → `import categories` |

| Package | Folder na may mga module at file na `__init__.py` | `expenses/report.py` → `from expenses.report import build` |

| Library | Handang hanay ng mga module at package para sa isang gawain | `requests`, `pandas`, ang standard na `pathlib` |

| Distribution (package sa PyPI) | Archive na ini-install ng pip | `pip install requests` |

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:

| Module | Para saan |
| --- | --- |

| `os`, `sys`, `pathlib`, `shutil` | Sistema, path, file |

| `json`, `csv`, `pickle` | Mga format ng datos |

| `datetime`, `time`, `calendar` | Petsa at oras |

| `math`, `random`, `statistics`, `fractions` | Mga numero |

| `re`, `string` | Pagtatrabaho sa teksto |

| `collections`, `itertools`, `functools` | Mga istruktura ng datos at iterator |

| `logging`, `argparse`, `subprocess` | Mga log, argumento ng command line, pagpapatakbo ng programa |

| `asyncio`, `threading` | Asynchronous at thread |

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.

| Gawain | Mga library |
| --- | --- |

| HTTP request at API | `requests`, `httpx` |

| Pagsusuri ng datos at talahanayan | `pandas`, `numpy` |

| Mga chart | `matplotlib` |

| Web service | `fastapi`, `django`, `flask` |

| Mga test | `pytest` |

| Mga larawan | `pillow` (ina-import bilang `PIL`) |

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.

## FAQ

**Kailangan bang gumawa ng venv para sa bawat proyekto?**

Oo, mainam itong gawi: may kanya-kanyang bersyon ng library ang bawat proyekto, at naiiwasan ng hiwalay na environment ang alitan at hindi nito dinudumihan ang system Python.

**Ano ang pagkakaiba ng pip at uv?**

Nag-iinstall lang ng package ang pip, samantalang ginagawa rin ng uv ang environment, isinusulat ang dependency sa pyproject.toml, at tinatandaan ang eksaktong bersyon sa lock file; mas mabilis din ito nang malaki.

**Paano makita ang listahan ng naka-install na library ng Python?**

Patakbuhin ang python -m pip list sa tamang environment; ang pip freeze ay magpapakita ng parehong listahan sa format ng requirements.txt.

**Saan nakalagay ang mga naka-install na module?**

Sa folder na site-packages ng kasalukuyang environment. Ipinapakita ng attribute na __file__ ang eksaktong path ng module, halimbawa: import requests; print(requests.__file__).

**Maaari bang ilipat ang folder ng venv sa ibang computer?**

Hindi, nakatali ang environment sa mga path at interpreter ng makina; ang inililipat ay ang listahan ng dependency, at saka gagawin muli ang environment.


---
Source: Skillaria.Top (https://skillaria.top)