নিজের package বানানো — pyproject, wheel আর PyPI

১ · ইনস্টল করা অর্ধেক গল্প — নিজের কোড কেন package হবে

নুসরাত ঢাকার একটি ই-কমার্স কোম্পানিতে Python ডেভেলপার। বছরখানেক আগে তিনি একটি ছোট ফাংশন লিখেছিলেন — format_taka(), যা 1234567-কে লেখে 12,34,567, অর্থাৎ বাংলাদেশের লাখ-কোটির নিয়মে কমা বসায়। ফাংশনটি এত কাজের যে সেটি এখন তিন জায়গায় আছে: ইনভয়েসের অ্যাপে, মাসিক বিক্রির রিপোর্ট-স্ক্রিপ্টে আর দোকানের ওয়েবসাইটে। তিনটিই কপি-পেস্ট করা।

একদিন ধরা পড়ল, ঋণাত্মক টাকায় (ফেরত দেওয়া অর্ডার) ফাংশনটি ভুল কমা বসায়। নুসরাত ইনভয়েস-অ্যাপে ঠিক করলেন। রিপোর্ট-স্ক্রিপ্ট আর ওয়েবসাইটে পুরোনো ভুল রয়ে গেল। এর মধ্যে এক সহকর্মী ওয়েবসাইট থেকে পুরোনো কপিটিই নিজের নতুন প্রজেক্টে নিয়ে গেছেন। এখন চারটি কপি, তিন রকম আচরণ, আর কেউ জানে না কোনটি “আসল”।

পর্ব ২৩-এ আপনি শিখেছেন অন্যের package কীভাবে আনতে হয় — pip, venv, version-শর্ত। কিন্তু সেটি গল্পের অর্ধেক। বাকি অর্ধেক হলো নিজের কোডকে এমন একটি জিনিসে রূপ দেওয়া, যা pip install করা যায়: একটি নাম, একটি version, নিজের dependency-তালিকা আর একটি মানক ফাইল-ফরম্যাট। তখন নুসরাতের সমাধান সহজ — taka-format নামে একটি package, version 0.1.0. ভুল ঠিক হলে 0.1.1, আর প্রতিটি প্রজেক্ট নিজের সুবিধামতো, পরীক্ষা করে আপগ্রেড করে। কোড থাকে এক জায়গায়, ইতিহাস থাকে version নম্বরে।

এই একই পথে তিনটি ভিন্ন গন্তব্যে যাওয়া যায়:

আধুনিক Python-এ পুরো কাজটি ঘোষণামূলক: আপনি একটি ফাইলে লিখে দেন প্রজেক্টটি কী — কোনো স্ক্রিপ্ট লিখে বলতে হয় না কীভাবে বানাতে হবে। তারপর একটি build backend সেই ঘোষণা পড়ে দুটি মানক ফাইল বানায়, যা pip, uv বা যেকোনো ইনস্টলার বোঝে। পুরো যাত্রাটি এক নজরে:

দুটি শব্দ মনে করিয়ে দিই (পর্ব ২২ ও ২৩)। import package হলো __init__.py-সহ একটি ফোল্ডার, কোডে যার নাম লেখেন (import taka_format). আর distribution হলো সেই ফোল্ডার-সহ নাম ও version লাগানো বান্ডিল, যা pip ইনস্টল করে (pip install taka-format). এই পর্বের পুরোটা দ্বিতীয়টি বানানোর গল্প। একটি পরিচিত নিয়ম: distribution-এর নামে সাধারণত হাইফেন, import-এর নামে আন্ডারস্কোর, কারণ Python-এর নামে হাইফেন চলে না।

২ · প্রজেক্ট সাজানো — src layout বনাম flat layout

নুসরাতের package-এর পুরো ফোল্ডার নিচে দেখানো হলো। এই পর্ব লেখার আগে আমরা ঠিক এই প্রজেক্টটি সত্যিই বানিয়ে, build করে, আলাদা venv-এ ইনস্টল করে চালিয়ে দেখেছি — সামনের সব আউটপুট সেখান থেকেই নেওয়া।

taka-format/
├── pyproject.toml          ← পরিচয়পত্র (অংশ ৩)
├── README.md               ← PyPI-র পাতায় দেখাবে
├── LICENSE                 ← ব্যবহারের অনুমতির শর্ত
├── src/
│   └── taka_format/        ← import করা যায় এমন package
│       ├── __init__.py     ← format_taka()
│       ├── cli.py          ← terminal-এর "taka" কমান্ড
│       └── units.txt       ← package-এর সাথে যাওয়া ডেটা-ফাইল
└── tests/
    └── test_format.py

পর্ব ২৩-এ src layout-এর নাম শুনেছেন। এর বিকল্প হলো flat layout, যেখানে taka_format/ ফোল্ডার সরাসরি প্রজেক্টের মূলে থাকে, src/ ছাড়া। দুটিই বৈধ, দুটিই প্রচলিত — Python Packaging User Guide দুটির তুলনাই দেয়। তবে প্রকাশ করার মতো package-এ src layout বেশি নিরাপদ, আর তার কারণ একটি সূক্ষ্ম ফাঁদ।

পর্ব ২২-এ দেখেছেন, কোনো স্ক্রিপ্ট চালালে তার ফোল্ডার (আর python -m বা REPL-এ বর্তমান ফোল্ডার) sys.path-এর একেবারে শুরুতে বসে। Flat layout-এ প্রজেক্টের মূল থেকে টেস্ট চালালে import taka_format তাই ইনস্টল করা package নয়, পাশের ফোল্ডারটিই পেয়ে যায়। ফলে wheel-এ কোনো ফাইল বাদ পড়লেও আপনার কম্পিউটারে সব ঠিকঠাক চলে — ভাঙে শুধু ব্যবহারকারীর কম্পিউটারে। ধাপে ধাপে দেখুন:

taka-format/
├── pyproject.toml
├── taka_format/       ← সরাসরি এখানে
│   ├── __init__.py
│   └── units.txt
└── tests/

taka_format/__init__.py
taka_format/cli.py
taka_format/units.txt      ← নেই!
taka_format-0.1.0.dist-info/...

$ python -m pytest
sys.path[0] = taka-format/   → import taka_format
            = পাশের ফোল্ডার, যেখানে units.txt আছে
1 passed

$ taka
FileNotFoundError: ... taka_format/units.txt
ইনস্টল করা wheel-এ ফাইলটি কখনো ছিলই না

$ python -c "import taka_format"
ModuleNotFoundError: No module named 'taka_format'
→ আগে ইনস্টল করতেই হবে; টেস্ট চলে ইনস্টল করা কপিতে

এখন package-এর আসল কোড। নিচের ফাংশনটি src/taka_format/__init__.py-এর হৃদয় (সেখানে বাড়তি শুধু version পড়ার দুটি লাইন, অংশ ৬-এ দেখবেন)। লাখ-কোটির নিয়ম: শেষ তিন অঙ্ক একটি দল, তারপর বাঁ দিকে দুই অঙ্ক করে। প্রকাশের আগে package-এর আচরণ টেস্ট দিয়ে বেঁধে ফেলা জরুরি — নুসরাতের ঋণাত্মক সংখ্যার বাগটিও এখানে একটি টেস্ট:

def format_taka(amount: int) -> str:
    """1234567 -> "12,34,567": শেষে ৩ অঙ্ক, তারপর ২ অঙ্ক করে দল।"""
    sign = "-" if amount < 0 else ""
    digits = str(abs(amount))
    head, tail = digits[:-3], digits[-3:]
    groups = []
    while head:
        groups.insert(0, head[-2:])
        head = head[:-2]
    return sign + ",".join(groups + [tail])

tests = {0: "0", 999: "999", 1000: "1,000", 100000: "1,00,000",
         1234567: "12,34,567", 10000000: "1,00,00,000", -5000: "-5,000"}
for n, want in tests.items():
    got = format_taka(n)
    assert got == want, f"{n}: পেলাম {got!r}, চাই {want!r}"
    print(f"{n:>9} -> {got}")
print("৭টি টেস্টই পাস")

৩ · pyproject.toml — পরিচয়পত্রের প্রতিটি ঘর

পর্ব ২৩-এ একটি ছোট pyproject.toml দেখেছেন — নাম, version, dependency আর একটি কমান্ড। প্রকাশ করার মতো package-এ আরও কিছু ঘর লাগে, কারণ এগুলোই PyPI-র পাতায় দেখা যায়, আর ব্যবহারকারী ও টুল এগুলো পড়েই সিদ্ধান্ত নেয়। নিচেরটি আমাদের পরীক্ষিত taka-format-এর হুবহু ফাইল:

# pyproject.toml
[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"

[project]
name = "taka-format"
version = "0.1.0"
description = "Format numbers in Bangladeshi lakh/crore style"
readme = "README.md"
requires-python = ">=3.10"
license = "MIT"
license-files = ["LICENSE"]
authors = [{ name = "Nusrat Jahan", email = "nusrat@example.com" }]
dependencies = []
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent",
]

[project.optional-dependencies]
cli = ["rich>=13"]

[project.urls]
Source = "https://github.com/example/taka-format"

[project.scripts]
taka = "taka_format.cli:main"

License — SPDX expression (PEP 639)

অনেক বছর ধরে license লেখার কোনো একক নিয়ম ছিল না: কেউ লিখতেন license = {text = "MIT"}, কেউ classifier দিতেন "License :: OSI Approved :: MIT License", কেউ দুটোই — আর মাঝে মাঝে দুটি আলাদা কথা বলত। PEP 639 (২০২৪-২৫ সালে গৃহীত) একটি পরিষ্কার নিয়ম আনে: license-এ একটি SPDX license expression, যেমন "MIT", "Apache-2.0" বা দুটির যেকোনো একটি বেছে নেওয়ার জন্য "MIT OR Apache-2.0". আর license-files-এ license-এর আসল লেখার ফাইল, যা wheel-এর ভেতরে যায় — আমাদের wheel-এ সেটি বসেছে .dist-info/licenses/LICENSE-এ।

• backend-কে নতুন হতে হবে: hatchling 1.27 আর setuptools 77 থেকে এই রূপ সমর্থিত। তাই আমাদের ফাইলে hatchling>=1.27. আমাদের build-এর METADATA-তে এসেছে License-Expression: MIT.
• পুরোনো রূপ এড়ান: license = {text = ...} টেবিল-রূপ এখন বাতিলের পথে, আর License :: classifier SPDX expression-এর সাথে একসাথে দিলে নতুন টুল error দিতে পারে। একটিই সত্যের উৎস — license.
• license না দিলে: আইনের চোখে কোড ব্যবহারের অনুমতি অস্পষ্ট থাকে, আর সাবধানী কোম্পানি সেই package ব্যবহারই করে না। ছোট utility-তে MIT বা Apache-2.0 সবচেয়ে প্রচলিত; কোনটি বাছবেন, সেটি আইনি সিদ্ধান্ত — কোম্পানির কোড হলে আগে অনুমতি নিন।

Classifier, extra আর এমন জিনিস যা প্রকাশ হয় না

Classifier হলো PyPI-র নির্দিষ্ট তালিকা থেকে নেওয়া লেবেল — কোন Python, কোন OS, প্রজেক্টের পরিপক্কতা (Development Status :: 4 - Beta). এগুলো খোঁজায় সাহায্য করে, কিন্তু ইনস্টলের নিয়ম বদলায় না — Python version-এর আসল নিয়ন্ত্রণ requires-python. একটি কাজের কৌশল: Private :: দিয়ে শুরু হওয়া যেকোনো classifier (যেমন "Private :: Do Not Upload") PyPI ইচ্ছাকৃতভাবে ফিরিয়ে দেয়। কোম্পানির ভেতরের package-এ এটি দিলে ভুল করে পাবলিক PyPI-তে আপলোড হওয়া আটকায়।

Optional dependencies (extra) দিয়ে ভারী বা বিশেষ dependency ঐচ্ছিক রাখা যায়। আমাদের METADATA-তে এটি দেখা গেছে এভাবে: Provides-Extra: cli আর Requires-Dist: rich>=13; extra == 'cli' — অর্থাৎ rich আসবে শুধু [cli] চাইলে। আর যেসব dependency শুধু ডেভেলপারের লাগে (pytest, ruff), সেগুলো ব্যবহারকারীর কাছে যাওয়া উচিত নয়। এর জন্য নতুন মানক [dependency-groups] অংশ (PEP 735, ২০২৪) — এটি wheel-এর metadata-তে যায় না; uv এটি পড়ে, আর pip 25.1 থেকে --group দিয়ে। টুলের নিজস্ব সেটিং থাকে [tool.ruff], [tool.pytest.ini_options]-এর মতো [tool.*] অংশে (পর্ব ৪২, ৪৭)।

৪ · Build backend বাছাই — frontend আর backend-এর ভাগাভাগি

package বানানোর কাজে দুই ধরনের টুল আছে, আর এদের ভাগটা বুঝলে বাকি সব সহজ হয়ে যায়। Build frontend হলো যে টুল আপনি চালান — python -m build, pip বা uv build. এটি নিজে কিছু বানায় না। সে [build-system] পড়ে, একটি অস্থায়ী, আলাদা পরিবেশ তৈরি করে, সেখানে backend ইনস্টল করে, তারপর PEP 517-এর মানক ফাংশন (build_wheel, build_sdist) ডেকে backend-কে বলে “বানাও”। এই আলাদা পরিবেশকে বলে build isolation — আপনার venv-এ কী আছে না আছে, build তার ওপর নির্ভর করে না, তাই সবার কম্পিউটারে একই ফল।

Backend হলো যে আসলে ফাইল বানায়। কোনটি বাছবেন? সত্যি কথা হলো, বিশুদ্ধ Python package-এর জন্য সবগুলোই ভালো, আর একই [project] অংশ সবাই পড়ে — backend বদলাতে সাধারণত শুধু [build-system]-এর দুটি লাইন আর backend-নির্ভর [tool.*] সেটিং বদলাতে হয়।

ভেতরে C, C++ বা Rust কোড থাকলে আলাদা জাতের backend লাগে — যেমন CMake-ভিত্তিক scikit-build-core বা Rust-এর জন্য maturin. version নম্বরগুলো এই লেখার সময়ের; backend দ্রুত বদলায়, তাই নতুন প্রজেক্ট শুরুর সময় সংশ্লিষ্ট ডকুমেন্টেশন একবার দেখে নিন।

৫ · Build করা — আর wheel-এর ভেতরে আসলে কী থাকে

প্রজেক্টের মূল ফোল্ডারে একটি আলাদা venv-এ build নামের frontend ইনস্টল করে একটি কমান্ড দিন:

python -m venv .venv
.venv\Scripts\Activate.ps1          # Mac/Linux: source .venv/bin/activate
python -m pip install build
python -m build                     # dist/ ফোল্ডারে sdist আর wheel

প্রত্যাশিত আউটপুট (সংক্ষেপে) — আমাদের নিজের চালানো থেকে, build 1.6.1 দিয়ে:

* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - hatchling>=1.27
* Installed build dependency versions:
  - hatchling==1.32.4
* Building sdist...
* Building wheel from sdist
...
Successfully built taka_format-0.1.0.tar.gz and taka_format-0.1.0-py3-none-any.whl

লক্ষ করুন Building wheel from sdist: build প্রথমে sdist বানায়, তারপর সেই sdist খুলে তা থেকে wheel বানায়। এটি একটি চমৎকার পরীক্ষা — sdist-এ কোনো দরকারি ফাইল বাদ পড়লে wheel build এখানেই ব্যর্থ হবে, ব্যবহারকারীর কম্পিউটারে নয়। পুরো যাত্রাটি, ইনস্টল পর্যন্ত:

[build-system]
requires = ["hatchling>=1.27"]
build-backend = "hatchling.build"
→ অস্থায়ী venv বানাও, hatchling ইনস্টল করো

taka_format-0.1.0/pyproject.toml
taka_format-0.1.0/README.md
taka_format-0.1.0/LICENSE
taka_format-0.1.0/src/taka_format/__init__.py
taka_format-0.1.0/src/taka_format/cli.py
taka_format-0.1.0/src/taka_format/units.txt
taka_format-0.1.0/tests/test_format.py
taka_format-0.1.0/PKG-INFO    ← metadata

   416  taka_format/__init__.py
   357  taka_format/cli.py
    36  taka_format/units.txt
   575  taka_format-0.1.0.dist-info/METADATA
    87  taka_format-0.1.0.dist-info/WHEEL
    46  taka_format-0.1.0.dist-info/entry_points.txt
   141  taka_format-0.1.0.dist-info/licenses/LICENSE
   645  taka_format-0.1.0.dist-info/RECORD

$ python -m pip install dist/taka_format-0.1.0-py3-none-any.whl
Processing .\dist\taka_format-0.1.0-py3-none-any.whl
Installing collected packages: taka-format
Successfully installed taka-format-0.1.0
site-packages/taka_format/  +  taka_format-0.1.0.dist-info/

$ taka 1234567 -5000 999
৳ 12,34,567
৳ -5,000
৳ 999
Windows-এ .venv\Scripts\taka.exe, Linux/Mac-এ .venv/bin/taka

wheel খুলে দেখা — শুধু standard library দিয়ে

wheel যেহেতু সাধারণ zip, Python-এর zipfile দিয়েই খোলা যায়, আর METADATA ফাইলটি ইমেইলের হেডারের মতো “নাম: মান” ফরম্যাটে লেখা — তাই email.parser দিয়ে পড়া যায়। এই পাতায় আসল ফাইল নেই, তাই নিচের কোড মেমরিতে একটি ছোট “wheel” বানিয়ে তারপর সেটি পড়ে:

import io
import zipfile
from email.parser import Parser

DI = "taka_format-0.1.0.dist-info"
buf = io.BytesIO()                       # ডিস্কে নয়, মেমরিতে একটি "wheel"
with zipfile.ZipFile(buf, "w") as whl:
    whl.writestr("taka_format/__init__.py", "def format_taka(n): ...\n")
    whl.writestr(f"{DI}/METADATA", "Metadata-Version: 2.4\nName: taka-format\n"
                 "Version: 0.1.0\nLicense-Expression: MIT\nRequires-Python: >=3.10\n")
    whl.writestr(f"{DI}/entry_points.txt", "[console_scripts]\ntaka = taka_format.cli:main\n")

with zipfile.ZipFile(buf) as whl:
    print(*whl.namelist(), sep="\n")
    meta = Parser().parsestr(whl.read(f"{DI}/METADATA").decode())
    print("নাম:", meta["Name"], "| version:", meta["Version"], "| license:", meta["License-Expression"])

name, ver, py, abi, plat = "taka_format-0.1.0-py3-none-any.whl".removesuffix(".whl").split("-")
print(f"Python ট্যাগ={py}, ABI={abi}, প্ল্যাটফর্ম={plat}")

wheel-এর নামের ট্যাগ — কে কোথায় চলবে

wheel-এর নামের গঠন: {নাম}-{version}-{python}-{abi}-{প্ল্যাটফর্ম}.whl. এই শেষ তিনটি অংশকে বলে wheel tag, আর pip এগুলো মিলিয়েই ঠিক করে কোন ফাইল আপনার কম্পিউটারে চলবে:

platform wheel বানানো ঝামেলার — প্রতিটি OS, প্রসেসর আর Python version-এর জন্য আলাদা। বড় প্রজেক্টগুলো এজন্য cibuildwheel-এর মতো টুল দিয়ে CI-তে একসাথে ডজনখানেক wheel বানায়। আমাদের taka-format-এর মতো বিশুদ্ধ Python-এ সেই চিন্তা নেই।

python -m pip install twine
twine check dist/*        # README ঠিকমতো দেখাবে কি না, metadata বৈধ কি না

প্রত্যাশিত আউটপুট (সংক্ষেপে) — আমাদের চালানোয় twine 7.0.0:

Checking dist/taka_format-0.1.0-py3-none-any.whl: PASSED
Checking dist/taka_format-0.1.0.tar.gz: PASSED

৬ · Version — PEP 440, pre-release আর এক জায়গায় version

পর্ব ২৩-এ semantic versioning-এর প্রথা দেখেছেন: MAJOR.MINOR.PATCH. ব্যবহারকারী হিসেবে সেটি ছিল “পড়ার” বিষয়; package-এর লেখক হিসেবে এখন এটি আপনার প্রতিশ্রুতি। taka-format-এ format_taka()-এর নাম বদলালে MAJOR বাড়াতে হবে, নতুন ফাংশন যোগ করলে MINOR, শুধু বাগ সারালে PATCH. 0.x version-এর প্রচলিত মানে “এখনো স্থির নয়, MINOR-এও বড় বদল হতে পারে” — তাই প্রথম প্রকাশ প্রায়ই 0.1.0.

Python-এ কোন version লেখা বৈধ আর কোনটি কার চেয়ে বড়, তার আসল নিয়ম PEP 440-এ। semver-এর চেয়ে এটি একটু আলাদা, বিশেষ করে pre-release-এ:

• .devN — ডেভেলপমেন্ট চলাকালীন build; aN / bN / rcN — alpha, beta, release candidate. pip এগুলো নিজে থেকে বাছে না: pip install taka-format সবচেয়ে নতুন স্থিতিশীল version নেয়। pre-release চাইলে --pre দিতে হয়, বা শর্তেই pre-release লিখতে হয় (taka-format==1.0.0rc1).
• .postN — কোড না বদলে শুধু প্রকাশে ভুল সারানো (যেমন README). কোডের বাগ সারালে PATCH বাড়ান, post নয়।
• একবার আপলোড, চিরকাল সেই ফাইল: PyPI একই নাম-version-এর ফাইল দ্বিতীয়বার নেয় না — মুছে দিলেও না। ভুল প্রকাশ হলে নতুন version দিন। খারাপ version-কে “yank” (PEP 592) করা যায়: ফাইল থাকে, কিন্তু শর্ত ছাড়া ইনস্টলে pip সেটি আর বাছে না; যাঁরা == দিয়ে হুবহু চেয়েছেন, শুধু তাঁরা পান।

version এক জায়গায় — importlib.metadata

নতুনরা প্রায়ই version দুই জায়গায় লেখেন — pyproject.toml-এ আর __init__.py-এর __version__-এ। তারপর একটিতে বদলান, অন্যটিতে ভুলে যান। সমাধান: version লিখুন শুধু pyproject.toml-এ, আর কোডে ইনস্টল করা metadata থেকে পড়ুন। আমাদের __init__.py-এর শুরু:

from importlib.metadata import version

__version__ = version("taka-format")   # distribution-এর নাম, import-এর নয়

importlib.metadata (Python 3.8 থেকে standard library-তে) site-packages-এর .dist-info/METADATA পড়ে। আমাদের নতুন venv-এ version('taka-format') দিয়েছে 0.1.0, আর একই module থেকে metadata('taka-format')['License-Expression'] দিয়েছে MIT. একটি শর্ত: package ইনস্টল করা থাকতে হবে (editable হলেও চলে) — src layout-এ এমনিতেই তা থাকে। বিকল্প পথও আছে: backend-কে dynamic = ["version"] দিয়ে বলা যায় version কোডের ফাইল থেকে বা git tag থেকে নিতে (setuptools-scm, hatch-vcs) — তাহলে git tag v0.2.0 দিলেই version ঠিক হয়।

Library-তে পরিসর, অ্যাপে pin

পর্ব ২৩-এর পরামর্শ ছিল: চালানোর উপযোগী অ্যাপে হুবহু pin. library-র ক্ষেত্রে উল্টো। ধরুন taka-format লিখল requests==2.31.0, আর ব্যবহারকারীর আরেকটি library চায় requests>=2.32. দুটি একসাথে ইনস্টল অসম্ভব — আপনার একটি অকারণ সংখ্যার জন্য অন্যের পুরো প্রজেক্ট আটকে গেল। library জানে না সে কার পাশে বসবে, তাই সে শুধু বলে “আমার কমপক্ষে কী লাগে” (requests>=2.31), আর জানা ভাঙন থাকলে সীমা (<3). হুবহু version ঠিক করার দায়িত্ব শেষ অ্যাপের, তার lock file-এ। ওপরের সীমা (upper bound) নিয়ে অভিজ্ঞদের মধ্যেও বিতর্ক আছে: অকারণ <3 ভবিষ্যতে সমাধানহীন জট বানাতে পারে, আবার না দিলে নতুন MAJOR ভাঙতে পারে — জানা কারণ ছাড়া কড়া সীমা দেবেন না।

এবার ব্যবহারকারীর দিক থেকে দেখুন — pip একটি পরিসর পেলে উপলব্ধ version-গুলো থেকে কীভাবে একটি বাছে (তালিকাটি বোঝানোর জন্য বানানো, requests-এর আসল release-তালিকা নয়):

1উপলব্ধ সব version-এর তালিকা2শর্ত ১: >=2.313শর্ত ২: <34pre-release বাদ (ডিফল্ট)5Requires-Python ও wheel মেলানো6সবচেয়ে বড়টি নেওয়া

৭ · Package data, editable install আর নতুন venv-এ পরীক্ষা

taka কমান্ড কোনো সংখ্যা না পেলে units.txt ফাইল থেকে লাখ-কোটির একটি ছোট সারণি দেখায়। .py নয় এমন ফাইল — JSON, CSV, টেমপ্লেট, ছবি — যা package-এর সাথে যায়, তাকে বলে package data. এটি পড়ার সঠিক উপায় importlib.resources:

# src/taka_format/cli.py (অংশ)
from importlib.resources import files

text = files("taka_format").joinpath("units.txt").read_text(encoding="utf-8")

কেন open("units.txt") নয়? কারণ সেটি বর্তমান ফোল্ডারে খোঁজে (পর্ব ২৬-এ দেখবেন), আর ব্যবহারকারী যেকোনো ফোল্ডার থেকে taka চালাতে পারেন। files("taka_format") package যেখানে ইনস্টল হয়েছে সেখান থেকেই খোঁজে — site-packages-এ হোক, editable হোক, এমনকি zip-এর ভেতরে হোক। আরেকটি কথা: ডেটা-ফাইল wheel-এ ঢুকবে কি না, তা backend-এর নিয়মে। hatchling package-ফোল্ডারের ফাইলগুলো ডিফল্টভাবে নেয় (আমাদের wheel-এ units.txt এসেছে), setuptools-এ package-data বা include-package-data সেটিং দেখতে হয়। নিয়ম মুখস্থ করার চেয়ে নিরাপদ অভ্যাস: প্রতিবার wheel খুলে দেখুন (অংশ ৫-এর কোড)।

Editable install — কাজ চলাকালীন

পর্ব ২৩-এ pip install -e . দেখেছেন। package-এর লেখক হিসেবে এটিই আপনার দৈনন্দিন অবস্থা: কোড বদলান, সঙ্গে সঙ্গে পরীক্ষা করুন, আবার ইনস্টল ছাড়াই। আমাদের venv-এ editable ইনস্টলের পর site-packages-এ কোডের কপি নয়, এসেছে _editable_impl_taka_format.pth নামে একটি ছোট নির্দেশক ফাইল আর .dist-info; আর taka_format.__file__ দেখিয়েছে সরাসরি src/taka_format/__init__.py. তবে মনে রাখুন: pyproject.toml বদলালে — নতুন dependency, নতুন কমান্ড, নতুন version — আবার pip install -e . দিতে হয়, কারণ সেগুলো metadata-য় থাকে, কোডে নয়।

প্রকাশের আগে শেষ পরীক্ষা — একদম নতুন venv

editable install আপনার ফোল্ডার দেখায়, ব্যবহারকারী পাবেন wheel. তাই প্রকাশের আগে wheel-টিকে একটি খালি venv-এ ইনস্টল করে ব্যবহারকারীর মতো চালান — প্রজেক্টের ফোল্ডারের বাইরে থেকে:

cd ..                                     # প্রজেক্টের বাইরে
python -m venv try-env
try-env\Scripts\Activate.ps1              # Mac/Linux: source try-env/bin/activate
python -m pip install taka-format/dist/taka_format-0.1.0-py3-none-any.whl
taka 1234567 10000000
taka
python -c "from importlib.metadata import version; print(version('taka-format'))"

প্রত্যাশিত আউটপুট (সংক্ষেপে) — আমাদের চালানো থেকে:

Successfully installed taka-format-0.1.0
৳ 12,34,567
৳ 1,00,00,000
taka-format 0.1.0
lakh = 1,00,000
crore = 1,00,00,000
0.1.0

দ্বিতীয় taka (কোনো সংখ্যা ছাড়া) version আর units.txt-এর লেখা দেখিয়েছে — অর্থাৎ package data সত্যিই wheel-এ গেছে আর importlib.resources সেটি খুঁজে পেয়েছে। এরপর এই venv-এ pytest ইনস্টল করে tests/ চালালে টেস্টগুলো চলবে ইনস্টল করা wheel-এর ওপর (পর্ব ৪২)। Windows-এর পুরোনো console-এ ৳ চিহ্ন ভাঙা দেখালে সেটি terminal-এর encoding-এর ব্যাপার, package-এর নয়।

৮ · প্রকাশ — TestPyPI, token আর Trusted Publishing

wheel পরীক্ষিত, এবার পৃথিবীর হাতে তুলে দেওয়ার পালা। প্রথমবারের প্রস্তুতি:

1. দুটি অ্যাকাউন্ট: pypi.org আর TestPyPI (test.pypi.org) — দুটি সম্পূর্ণ আলাদা সাইট, আলাদা অ্যাকাউন্ট। TestPyPI অনুশীলনের মাঠ: এখানে ভুল করলে কারও ক্ষতি নেই, আর মাঝে মাঝে সেখানকার ডেটা মুছেও ফেলা হয়।
2. 2FA চালু: ২০২৪ সালের শুরু থেকে PyPI-তে আপলোড করতে সব অ্যাকাউন্টে 2FA বাধ্যতামূলক — authenticator অ্যাপ বা security key. recovery code নিরাপদে রেখে দিন।
3. নাম যাচাই: দুটি সাইটেই নামটি খালি কি না দেখুন (অংশ ২-এর normalization মনে রেখে)।

প্রথম পথ — API token আর twine

পাসওয়ার্ড দিয়ে আপলোড PyPI বহু আগেই বন্ধ করেছে। এর বদলে API token: অ্যাকাউন্টের সেটিং থেকে বানানো একটি লম্বা গোপন লেখা, যা pypi- দিয়ে শুরু হয়। প্রথম আপলোডের জন্য পুরো অ্যাকাউন্টের token লাগে; প্রজেক্ট তৈরি হয়ে গেলে শুধু ওই প্রজেক্টে সীমাবদ্ধ (project-scoped) token বানিয়ে পুরোনোটি মুছে দিন — চুরি হলেও ক্ষতি এক প্রজেক্টে সীমিত থাকে।

# ১. আগে TestPyPI-তে (username চাইলে লিখুন __token__, password-এ token)
twine upload --repository testpypi dist/*

# ২. নতুন venv-এ TestPyPI থেকে ইনস্টল করে পরীক্ষা
python -m pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ taka-format

# ৩. সব ঠিক থাকলে আসল PyPI-তে
twine upload dist/*

# uv ব্যবহার করলে একই কাজ:  uv build  তারপর  uv publish

দ্বিতীয় ধাপের --extra-index-url এখানে দরকার, কারণ আপনার package-এর dependency-গুলো TestPyPI-তে নাও থাকতে পারে। তবে এটি শুধু পরীক্ষার জন্য — দুটি index একসাথে দেওয়া কেন কোম্পানির কাজে বিপজ্জনক, তা অংশ ৯-এ দেখবেন। token কোথায় রাখবেন? প্রতিবার হাতে পেস্ট, বা OS-এর keyring-এ (twine এটি সমর্থন করে), বা নিজের হোম ফোল্ডারের .pypirc ফাইলে — কিন্তু কখনো প্রজেক্টের ফোল্ডারে বা git-এ নয়। GitHub-এ পাবলিক কোডে ফাঁস হওয়া PyPI token GitHub-এর secret scanning-এর মাধ্যমে PyPI-কে জানানো হয়, আর PyPI সেটি বাতিল করে দেয় — তবু সেই ভরসায় থাকবেন না।

আরও ভালো পথ — Trusted Publishing

token-এর মূল সমস্যা: এটি দীর্ঘস্থায়ী একটি চাবি। CI-তে (যেমন GitHub Actions) স্বয়ংক্রিয় প্রকাশের জন্য সেটি repository-র secret-এ রাখতে হয়, আর যেকোনো জায়গায় জমা থাকা চাবি একদিন চুরি হতে পারে। ২০২৩ সালে PyPI-তে আসা trusted publishing-এ জমা রাখার মতো কোনো চাবিই থাকে না। আপনি PyPI-কে আগে থেকে বলে রাখেন: “এই GitHub repository-র এই workflow ফাইল থেকে আসা অনুরোধ আমার প্রজেক্টে আপলোড করতে পারবে”। তারপর প্রতিবার প্রকাশের সময় GitHub একটি স্বল্পমেয়াদি, স্বাক্ষর করা পরিচয়পত্র দেয় — OIDC token — আর PyPI সেটি যাচাই করে কয়েক মিনিটের জন্য একটি আপলোড-token দেয়। ধাপে ধাপে:

Owner:        nusrat-dev
Repository:   taka-format
Workflow:     publish.yml
Environment:  pypi          (ঐচ্ছিক, কিন্তু ভালো)
নতুন প্রজেক্টে "pending publisher" হিসেবে আগেই যোগ করা যায়

on:
  release:
    types: [published]
jobs:
  pypi:
    runs-on: ubuntu-latest
    environment: pypi

    permissions:
      id-token: write    ← OIDC token চাওয়ার অনুমতি
    steps:
      - uses: actions/checkout@v4
      - run: pipx run build

স্বাক্ষর GitHub-এর?        ✓
repository = nusrat-dev/taka-format   ✓
workflow   = publish.yml              ✓
environment = pypi                    ✓
→ শুধু taka-format-এর জন্য স্বল্পমেয়াদি API token

      - uses: pypa/gh-action-pypi-publish@release/v1
token বিনিময় + আপলোড এই action-ই করে;
কয়েক মিনিট পরে token নিজেই অকেজো

GitHub ছাড়াও GitLab CI/CD, Google Cloud আর ActiveState থেকে trusted publishing সমর্থিত। আর uv publish-ও GitHub Actions-এ চললে trusted publishing ব্যবহার করতে পারে।

৯ · দল ও কোম্পানির জন্য — private index, project manager আর নিরাপত্তা

সব package পৃথিবীর জন্য নয়। ধরুন একটি বাংলাদেশি ফিনটেক কোম্পানির তিনটি দল একই bKash/Nagad পেমেন্ট-ক্লায়েন্ট কোড ব্যবহার করে, যার ভেতরে কোম্পানির নিজস্ব নিয়ম আছে। এটিকেও একই উপায়ে package বানানো হয় — শুধু প্রকাশ হয় কোম্পানির ভেতরের ভাণ্ডারে:

• ছোট দলের জন্য: সরাসরি git থেকে, নির্দিষ্ট tag দিয়ে — pip install "git+https://github.com/acme/paykit@v1.4.0". index লাগে না, তবে প্রতি ইনস্টলে build হয়, আর tag বদলানো যায় বলে পুরোপুরি স্থির নয়।
• প্রতিষ্ঠানের জন্য private package index: PyPI-র মতোই একটি সার্ভার, শুধু ভেতরের লোকদের জন্য — নিজে চালানো যায় (devpi, Sonatype Nexus, JFrog Artifactory), বা ক্লাউডের সেবা (AWS CodeArtifact, Azure Artifacts, Google Artifact Registry, GitLab-এর package registry). প্রকাশ হয় সেই একই twine upload --repository-url ... বা uv publish --publish-url ... দিয়ে।

uv, Poetry, PDM — পুরো প্রজেক্টের ব্যবস্থাপক

এই পর্বে আমরা ইচ্ছা করেই আলাদা আলাদা টুল (build, twine, pip) ব্যবহার করেছি, যাতে প্রতিটি ধাপ চোখে পড়ে। বাস্তবে অনেক দল একটি project manager ব্যবহার করে, যা venv, dependency, lock file, build আর publish এক জায়গায় সামলায়। মনে রাখার বিষয়: এরা সবাই শেষে একই মানক wheel আর sdist বানায়, আর একই PyPI-তে পাঠায় — তাই ব্যবহারকারী জানতেও পারেন না আপনি কোনটি ব্যবহার করেছেন।

প্রকাশকের নিরাপত্তা-দায়িত্ব

পর্ব ২৩-এ আপনি ছিলেন ব্যবহারকারী — অচেনা package থেকে নিজেকে বাঁচানো। এখন আপনি প্রকাশক, আর অন্যরা আপনাকে বিশ্বাস করে pip install দেবেন। Supply-chain attack-এর সবচেয়ে মূল্যবান লক্ষ্য হলো জনপ্রিয় package-এর প্রকাশকের অ্যাকাউন্ট, কারণ তখন আসল নামের package-ই ক্ষতিকর হয়ে যায়।

• অ্যাকাউন্ট: 2FA (বাধ্যতামূলক), ভালো হলে hardware security key; অ্যাকাউন্টের ইমেইলের ডোমেইন সচল রাখুন।
• token: সম্ভব হলে trusted publishing; না হলে project-scoped token, git-এ কখনো নয়, .gitignore-এ .pypirc আর .env.
• যা প্রকাশ করছেন তা যাচাই: wheel আর sdist খুলে দেখুন — ভুল করে .env, পাসওয়ার্ডের ফাইল বা কোম্পানির ডেটা ঢুকে যায়নি তো? sdist-এ ডিফল্টভাবে অনেক ফাইল যায়।
• Typosquatting-এর উল্টো দিক: আপনার package জনপ্রিয় হলে কেউ কাছাকাছি বানানে (taka-fromat) নকল ছাড়তে পারে। README-তে সঠিক ইনস্টল-কমান্ড স্পষ্ট লিখুন, সন্দেহজনক নকল দেখলে PyPI-তে রিপোর্ট করুন।
• নিজের dependency কম রাখুন: আপনার প্রতিটি dependency আপনার ব্যবহারকারীরও dependency. পাঁচ লাইনের কাজের জন্য নতুন package নয়।

১০ · AI-এর যুগে — AI-এর লেখা packaging কনফিগ যাচাই

“আমার কোডকে PyPI-তে দেওয়ার মতো package বানিয়ে দাও” — AI কয়েক সেকেন্ডে পুরো কনফিগ লিখে দেয়। সমস্যা হলো, packaging-এর নিয়ম গত কয়েক বছরে দ্রুত বদলেছে, আর AI-এর শেখার লেখার বড় অংশ পুরোনো যুগের। সাধারণ ভুলগুলো:

AI-এর দেওয়া packaging কনফিগ প্রকাশের আগে — চেকলিস্ট

• pyproject.toml-এ [build-system] আর [project] আছে; setup.py install/upload-এর মতো কমান্ড নেই
• license একটি SPDX expression, License :: classifier নেই, backend-এর version তা সমর্থন করে
• library-র dependency-তে == নেই; requires-python আছে; version এক জায়গায়
• python -m build চালিয়ে wheel খুলে দেখেছি — দরকারি ফাইল আছে, গোপন ফাইল নেই; twine check পাস
• নতুন venv-এ wheel ইনস্টল করে কমান্ড চালিয়েছি, আগে TestPyPI-তে দিয়েছি
• CI-ফাইল আর repository-তে কোথাও token বা পাসওয়ার্ড লেখা নেই; trusted publishing বা secret ব্যবহার করেছি