# Moduli na pakiti za Python: import, pip, venv na maktaba kwa lugha rahisi

URL: https://skillaria.top/sw/guides/python/moduli-python

Moduli katika Python ni faili la .py, pakiti ni folda ya moduli, na maktaba ni seti ya pakiti zinazoitwa kwa import. Maktaba za nje husakinishwa kwa pip (au uv) ndani ya mazingira pepe venv — folda iliyotengwa yenye mkalimani na pakiti za mradi mmoja, ili matoleo ya miradi tofauti yasigongane.

Moduli katika Python ni faili la kawaida lenye msimbo, na `import` ndiyo njia ya kuchukua kazi na madarasa kutoka humo. Moduli hukusanywa kuwa pakiti, pakiti kuwa maktaba, na ili maktaba za nje za miradi tofauti zisigongane, husakinishwa kwenye mazingira pepe venv. Hebu tuchunguze mnyororo mzima: nini kinatokea wakati wa import, pakiti inavyopangwa, pip na venv zinavyofanya kazi, na lazy imports zilizoongezwa katika Python 3.15.

## Moduli, pakiti, maktaba: tofauti yake

| Dhana | Ni nini | Mfano |
| --- | --- | --- |

| Moduli | Faili moja `.py`; jina la moduli ni jina la faili bila kiendelezi | `categories.py` → `import categories` |

| Pakiti | Folda yenye moduli na faili `__init__.py` | `expenses/report.py` → `from expenses.report import build` |

| Maktaba | Seti tayari ya moduli na pakiti kwa kazi fulani | `requests`, `pandas`, `pathlib` ya kawaida |

| Kifurushi cha usambazaji (kifurushi cha PyPI) | Kumbukumbu inayosakinishwa na pip | `pip install requests` |

Maneno "maktaba", "pakiti" na "moduli" mara nyingi huchanganywa katika mazungumzo — ni kawaida. Jambo la msingi ni kwamba kitaalamu `import` hupakia moduli au pakiti kila wakati, na pip husakinisha kifurushi kutoka PyPI, ambacho ndani yake kuna pakiti.

## Jinsi import inavyofanya kazi katika Python

Kuna aina kadhaa za import, na zote hukutana katika msimbo halisi:

```
import math                    # moduli nzima, matumizi math.sqrt
from math import sqrt, pi      # majina mahususi
import datetime as dt          # jina bandia
from collections import Counter as C

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

Majina bandia ni ya kawaida kwa maktaba kubwa: `import numpy as np`, `import pandas as pd`. Muundo `from module import *` ni bora kuepukwa: unachafua nafasi ya majina na kuficha asili ya jina.

### Import hufanya nini hasa

1. Inatafuta moduli kwenye kache ya `sys.modules`. Ikiwa tayari imepakiwa — inarudisha tu.
2. Ikiwa haipo — inatafuta faili kwenye orodha ya folda `sys.path`: folda ya skripti inayoendeshwa, maktaba ya kawaida, site-packages ya mazingira.
3. Inatekeleza faili lililopatikana lote kutoka juu kwenda chini.
4. Inaweka kitu cha moduli kwenye kache na kukiunganisha na jina.

Kutokana na hili kuna hitimisho mbili za vitendo. Import ya pili ya moduli hiyo hiyo karibu haina gharama — msimbo hautekelezwi tena. Na msimbo wote wa ngazi ya juu wa moduli, pamoja na `print` na hesabu nzito, unatekelezwa wakati wa import.

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

### if __name__ == "__main__"

Kwa kuwa import hutekeleza faili, kunahitajika njia ya kutofautisha "niliendeshwa kama skripti" na "niliingizwa kama moduli". Kwa hilo kuna kigezo `__name__`: wakati faili linaendeshwa ni `"__main__"`, wakati linapoingizwa ni jina la moduli.

```
# categories.py
def guess(title: str) -> str:
    return "chakula" if "mkahawa" in title.lower() else "nyingine"

if __name__ == "__main__":
    print(guess("Mkahawa wa nyumbani"))   # itatekelezwa tu kwa python categories.py
```

Kwa pakiti kuna njia mbadala: faili `__main__.py` ndani yake, na uendeshaji kwa `python -m expenses`.

## Moduli za kawaida za Python

Python inakuja "na betri": mamia ya moduli zilizojengwa ndani zinapatikana mara moja, bila kusakinisha. Zinazotumika zaidi:

| Moduli | Kwa ajili ya nini |
| --- | --- |

| `os`, `sys`, `pathlib`, `shutil` | Mfumo, njia, faili |

| `json`, `csv`, `pickle` | Miundo ya data |

| `datetime`, `time`, `calendar` | Tarehe na muda |

| `math`, `random`, `statistics`, `fractions` | Namba |

| `re`, `string` | Kazi na maandishi |

| `collections`, `itertools`, `functools` | Miundo ya data na iterators |

| `logging`, `argparse`, `subprocess` | Logi, hoja za mstari wa amri, kuendesha programu |

| `asyncio`, `threading` | Asynchronous na threads |

Orodha kamili ya moduli za maktaba ya kawaida imehifadhiwa kwenye `sys.stdlib_module_names` (Python 3.10+). Kuona kilichomo ndani ya moduli, tumia `dir(math)` na `help(math)`.

## Pakiti yako mwenyewe: muundo wa mradi

Moduli zinapokuwa nyingi, zinakusanywa kuwa pakiti. Mpangilio unaotumika sana ni src-layout:

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

Ndani ya pakiti moduli huagizana kwa jina la pakiti (`from expenses.categories import guess`) au kwa njia ya jamaa (`from .categories import guess`). Import ya jamaa inafanya kazi ndani ya pakiti tu, si kwenye faili linaloendeshwa moja kwa moja kama skripti.

## pip katika Python: kusakinisha maktaba

Maktaba za nje zipo kwenye PyPI, na pip ndiyo chombo cha kuzisakinisha, kinachokuja pamoja na Python. Salama zaidi ni kuiita kupitia mkalimani — hivyo maktaba inaingia kwenye Python utakayoendesha msimbo nao.

```
python -m pip install requests          # kusakinisha
python -m pip install "pandas>=2.3"     # kwa kikomo cha toleo
python -m pip install --upgrade requests
python -m pip uninstall requests        # kuondoa
python -m pip list                      # orodha ya pakiti zilizosakinishwa
python -m pip show requests             # toleo na utegemezi
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
```

Kwenye Windows mara nyingi badala ya `python` hutumika kizindua `py`. Pip ikikosekana, moduli iliyojengwa ndani inaisakinisha: `python -m ensurepip --upgrade`.

### Maktaba maarufu za Python

Pakiti kwenye PyPI ni mamia ya maelfu, lakini miradi mingi hutumia orodha fupi moja ileile. Anza nayo, badala ya kutafuta mambo ya ajabu.

| Kazi | Maktaba |
| --- | --- |

| Maombi ya HTTP na API | `requests`, `httpx` |

| Uchambuzi wa data na majedwali | `pandas`, `numpy` |

| Michoro | `matplotlib` |

| Huduma za wavuti | `fastapi`, `django`, `flask` |

| Majaribio | `pytest` |

| Picha | `pillow` (inaingizwa kama `PIL`) |

Angalia: jina la kusakinisha na jina la kuingiza halifanani kila wakati. Unasakinisha `pip install pillow`, lakini unaandika `from PIL import Image`; unasakinisha `opencv-python`, lakini unaingiza `cv2`. Ikiwa `import` inaanguka mara baada ya usakinishaji, angalia kwenye nyaraka za pakiti jina linalotumika kuingiza.

### Kusakinisha maktaba kwenye Linux

Kwenye Debian na Ubuntu za kisasa, amri `pip install` kwenye Python ya mfumo inaishia kwa hitilafu `externally-managed-environment` (PEP 668). Hii ni kinga: Python ya mfumo ni ya meneja wa vifurushi wa OS, na pip haipaswi kuiharibu. Suluhisho sahihi si `--break-system-packages`, bali mazingira pepe.

## venv katika Python: mazingira pepe

Mazingira pepe ni folda tofauti yenye nakala yake ya mkalimani (kiungo kwake) na site-packages yake. Maktaba zilizosakinishwa humo zinaonekana kwa mradi huo tu. Hivyo mradi mmoja unaweza kutumia Django 4 na jirani yake Django 5, bila migogoro.

Moduli `venv` imejengwa ndani ya Python, hairuhusu kusakinishwa tofauti (kwenye Debian/Ubuntu wakati mwingine inahitaji pakiti ya mfumo `python3-venv`).

```
# kuunda mazingira kwenye folda .venv
python -m venv .venv

# kuwezesha: Linux na macOS
source .venv/bin/activate
# kuwezesha: Windows PowerShell
.venv\Scripts\Activate.ps1

# sasa pip inasakinisha pakiti ndani ya .venv
python -m pip install requests
python -c "import sys; print(sys.prefix)"

# kutoka kwenye mazingira
deactivate
```

Baada ya kuwezesha, mwanzoni mwa mstari wa terminal unaonekana `(.venv)`. Folda ya mazingira haiwekwi kwenye git (ongeza `.venv/` kwenye `.gitignore`) wala haihamishwi kati ya mashine — badala yake orodha ya utegemezi inahifadhiwa, na mazingira yanaundwa upya. Ikiwa PowerShell inazuia kuendesha skripti ya kuwezesha, ruhusu kwa mtumiaji: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.

### uv na pyproject.toml

Miradi ya kisasa inaeleza utegemezi katika `pyproject.toml`. Meneja uv, unaotumika kwenye kozi, anachanganya kuunda mazingira na kusakinisha: `uv add pandas` inapakua pakiti, inaiandika kwenye `pyproject.toml` na kurekodi matoleo kamili kwenye `uv.lock`. Mwenzako anaklona mradi, anaendesha `uv sync` — na anapata mazingira yanayofanana kabisa.

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

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

## Lazy imports katika Python 3.15 (PEP 810)

Habari kubwa ya 3.15 katika mada hii ni neno kuu `lazy`. Maktaba nzito hupakia kwa muda mrefu: katika kipimo cha kozi kwenye picha ya `python:3.15-slim`, import ya kawaida ya `pandas` ilichukua takriban 415 ms, na `lazy import pandas` — takriban 13 ms. Kwa zana ya mstari wa amri inayoendeshwa kwa ajili ya `--help`, tofauti hiyo ni kubwa sana.

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

def main() -> None:
    ...
    df = pd.read_csv(path)   # upakiaji halisi wa pandas — hapa
```

Badala ya moduli, jina linapata kitu cha kiwakilishi (proxy) (`types.LazyImportType`), na import halisi hufanyika wakati jina linapotumika kwa mara ya kwanza. Ikiwa hilo halijatokea, hakuna muda unaopotea kabisa.

### Mipaka ya lazy import

- Inaruhusiwa tu kwenye ngazi ya juu ya moduli: ndani ya kazi, darasa au `try/except` — ni `SyntaxError`.
- `lazy from x import *` hairuhusiwi.
- `ModuleNotFoundError` itatokea si wakati wa kuanza, bali wakati wa matumizi ya kwanza.
- Athari za pembeni za moduli (kusajili programu-jalizi na kadhalika) zinahamia kwa wakati.

Kufanya import zote kuwa lazy kwa wakati mmoja kunawezekana kwa bendera `-X lazy_imports=all` au kwa kigezo cha mazingira `PYTHON_LAZY_IMPORTS=all`; vighairi vinawekwa kwa `sys.set_lazy_imports_filter()`. Kwa msimbo unaohitaji kufanya kazi pia kwenye matoleo ya zamani kuna kigezo cha moduli `__lazy_modules__ = ["pandas"]`: 3.15 itafanya import zilizotajwa kuwa lazy, na matoleo ya zamani yatafanya import ya kawaida tu. Muda unaotumika wakati wa kuanza unaonyeshwa na `python -X importtime -c "import pandas"`. Faida kubwa ni kwa programu zinazoanzishwa mara nyingi kwa muda mfupi; seva inayoendelea kufanya kazi kwa muda mrefu haipati faida kubwa.

## Makosa ya kawaida

- `ModuleNotFoundError: No module named 'requests'` — maktaba imesakinishwa kwenye Python nyingine, au mazingira hayajawashwa. Thibitisha kwa `python -m pip show requests` kwa mkalimani uleule.
- Faili lako limeitwa `json.py`, `random.py` au `csv.py` — folda ya skripti iko kwanza kwenye `sys.path`, na linafunika moduli ya kawaida. Python 3.13+ inapendekeza "consider renaming" kwenye kosa. Badilisha jina la faili na ufute `__pycache__`.
- Import ya mzunguko: `a.py` inaingiza `b.py`, na hiyo inaingiza `a.py`. Weka vitu vya pamoja kwenye moduli ya tatu, au ingiza ndani ya kazi.
- pip imeendeshwa ndani ya mkalimani wa Python (`>>> pip install`) — utapata `SyntaxError`. Amri za pip zinaendeshwa kwenye terminal.

## Hitimisho

Moduli ni faili, pakiti ni folda ya moduli, maktaba ni seti yao tayari; `import` hutafuta moduli kwenye kache na kwenye `sys.path`, na kuitekeleza mara moja tu. Maktaba za nje zisakinishe kwa pip au uv pekee ndani ya mazingira pepe ya venv — hivyo miradi haigongani, na mazingira yanaweza kurudiwa kwa urahisi. Katika kozi ya Python mada hii inafundishwa kwa vitendo: kifuatiliaji cha matumizi kinageuka kuwa pakiti yenye utegemezi na kuanza kwa kasi kwa lazy imports.

## FAQ

**Je, ninahitaji kuunda venv kwa kila mradi?**

Ndiyo, ni mazoezi mazuri: kila mradi una matoleo yake ya maktaba, na mazingira tofauti yanazuia migogoro na kuweka Python ya mfumo safi.

**pip inatofautianaje na uv?**

pip husakinisha pakiti tu, wakati uv pia huunda mazingira, huandika utegemezi kwenye pyproject.toml na kurekodi matoleo kamili kwenye faili la lock; pia ni haraka zaidi.

**Ninawezaje kuona orodha ya maktaba zilizosakinishwa katika Python?**

Endesha python -m pip list kwenye mazingira husika; pip freeze hutoa orodha hiyohiyo katika muundo wa requirements.txt.

**Moduli zilizosakinishwa zimehifadhiwa wapi?**

Kwenye folda ya site-packages ya mazingira husika; njia ya moduli fulani inaonyeshwa na sifa __file__, kwa mfano import requests; print(requests.__file__).

**Je, naweza kuhamisha folda ya venv kwenda kompyuta nyingine?**

Hapana, mazingira yanafungwa kwenye njia na mkalimani wa mashine husika; huhamishwa orodha ya utegemezi, na mazingira yanaundwa upya.


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