ক্যাপস্টোন — দোকানের বিক্রি ও স্টকের একটি আসল Python সিস্টেম

১ · প্রোগ্রাম থেকে সিস্টেম — অনেক ছোট অংশ, প্রতিটির একটি কাজ

পঞ্চাশটি পর্বে আপনি Python-এর প্রায় পুরো ভাণ্ডার দেখেছেন: মূল ভাষা, ডেটা স্ট্রাকচার, module আর package, exception, ফাইল, class, dataclass, Protocol, type hint, টেস্টিং, logging, asyncio, পারফরম্যান্স, ওয়েব আর নিরাপত্তা। পর্ব ২১-এর মাঝপথের প্রজেক্টে বানিয়েছিলেন একটি ছোট টুল — কয়েকটি ফাংশন আর একটি লুপ, সব এক ফাইলে, বন্ধ করলেই সব ডেটা মুছে যায়। এবার তার বড় ভাই: এমন একটি সিস্টেম, যা ডেটা স্থায়ীভাবে রাখে, ভুলে ভাঙে না, টেস্ট দিয়ে প্রমাণিত, আর অন্য কেউ পড়ে বুঝতে ও বাড়াতে পারে।

মিরপুরের একটি মুদি দোকানের মালিক রহমান সাহেব। চাল, ডাল, তেল, ডিম — প্রায় দুশো রকম পণ্য। বিক্রি লেখা হয় খাতায়, স্টক মাথায়। মাস শেষে তিনি টের পান কোনো পণ্য ফুরিয়ে গেছে তিন দিন আগে, অথচ খদ্দের ফিরে গেছেন। কোন পণ্য সবচেয়ে বেশি বিক্রি হয়, আজ মোট কত টাকা এল — হাতে যোগ করতে আধা ঘণ্টা, তাও প্রায়ই মেলে না। তাঁর ছেলে কম্পিউটারে একটু-আধটু কাজ জানে। তাঁদের দরকার একটি ছোট সফটওয়্যার: বিক্রি লিখলেই স্টক কমবে, স্টক না থাকলে বিক্রি আটকাবে, আর দিনের শেষে একটি রিপোর্ট।

এই পর্বে আমরা সেই সিস্টেমটি নকশা করব আর ধাপে ধাপে বানানোর পথ দেখব। পুরো প্রজেক্ট প্রায় ৫০০–৭০০ লাইনের — একটি পর্বে প্রতিটি লাইন দেখানো সম্ভবও নয়, দরকারও নয়। আমরা দেখব সিদ্ধান্তগুলো: কোন অংশ কী করবে, কেন এভাবে, আর প্রতিটি সিদ্ধান্তের দাম কী। মূল কোডের গুরুত্বপূর্ণ অংশগুলো দেখাব, আর অংশ ৬-এ পুরো সিস্টেমের একটি সংক্ষিপ্ত এক-ফাইলের রূপ এই পাতাতেই চালিয়ে দেখবেন।

মাঝপথের প্রজেক্টের তুলনায় নতুন কী আসছে, এক নজরে দেখুন:

বিষয় বাছাইয়েও একটি সিদ্ধান্ত আছে। C++ কোর্সের ক্যাপস্টোন একটি লাইব্রেরির বই ধার দেওয়ার ব্যবস্থা; এখানে আমরা নিয়েছি এমন বিষয়, যেখানে টাকা আর স্টক — দুটি সংখ্যা, যেগুলো কখনো ভুল হতে পারবে না। আপনি চাইলে একই নকশায় কোচিং সেন্টারের ফি ও উপস্থিতি, ফার্মেসির ওষুধের মেয়াদ বা ছাত্রাবাসের মিলের হিসাব বানাতে পারেন; অংশ ১০-এ সে পরামর্শও আছে।

২ · চাহিদা — কমান্ডের টেবিল আর ব্যবসার নিয়ম

রহমান সাহেব আর তাঁর ছেলের সাথে বসে আমরা requirement লিখলাম। প্রথম সংস্করণ চলবে terminal-এ, একটি CLI হিসেবে। প্রতিটি কাজ একটি subcommand — git commit বা pip install-এর মতো, প্রোগ্রামের নামের পরে কাজের নাম:

এখানে SKU মানে প্রতিটি পণ্যের ছোট, অনন্য কোড (rice, oil) — নাম বদলালেও কোড একই থাকে। টেবিলের শেষ কলাম আবারও আমাদের specification: প্রতিটি সারি একেকটি ভবিষ্যৎ টেস্ট। এর সাথে কয়েকটি ব্যবসার নিয়ম লিখে রাখলাম, যা কোনো একটি কমান্ডের নয়, পুরো সিস্টেমের:

• স্টক কখনো ঋণাত্মক হবে না। এটি সিস্টেমের সবচেয়ে গুরুত্বপূর্ণ invariant — সবসময় সত্য থাকা শর্ত।
• প্রতিটি বিক্রি হয় পুরোপুরি হবে, নয় একেবারেই না। স্টক কমল অথচ বিক্রি জমা হলো না — এমন অর্ধেক অবস্থা অসম্ভব।
• টাকার হিসাব পয়সা পর্যন্ত নির্ভুল। দিনের মোট আর প্রতিটি বিক্রির যোগফল হুবহু মিলবে।
• প্রতিটি বিক্রি আর প্রতিটি বাতিল হওয়া চেষ্টা log-এ থাকবে — পরে “কাল বিকেলে তেলের স্টক কীভাবে শূন্য হলো?” প্রশ্নের উত্তর দিতে।

পর্ব ২১-এর মতোই, MVP-র সীমারেখা লিখিত থাকায় “বাকির খাতাটাও একটু দিয়ে দাও না” শুনে আমরা “না” বলি না — বলি “হ্যাঁ, তালিকায় আছে, পরের ধাপে।” অংশ ১০-এ দেখবেন, আমাদের নকশা এই প্রতিটি সম্প্রসারণের জন্য আগে থেকেই জায়গা রেখেছে।

৩ · স্থাপত্য — চার স্তর: CLI → service → domain → storage

পর্ব ২১-এ আমরা কোডকে তিন ভাগে রেখেছিলাম: কথা বলা, হিসাব, ডেটা। ক্যাপস্টোনে সেই ভাবনাটিই একটি পূর্ণাঙ্গ layered architecture — প্রতিটি স্তর আলাদা module, প্রতিটির একটি দায়িত্ব। এটিই পর্ব ২১-এর separation of concerns, এবার পুরো প্রজেক্টের মাপে।

সবচেয়ে গুরুত্বপূর্ণ নিয়মটি তীরের দিকে: ভেতরের স্তর বাইরের স্তরকে চেনে না। domain জানে না CLI আছে কি না; service জানে না ডেটা SQLite-এ না অন্য কোথাও। এজন্যই কাল যদি একটি ওয়েব পাতা (পর্ব ৪৮-এর FastAPI) লাগে, শুধু CLI-র পাশে আরেকটি বাইরের স্তর বসবে — service আর domain-এর একটি লাইনও বদলাবে না। এই ধারণার একটি জনপ্রিয় নাম hexagonal architecture বা “ports and adapters” — ভাবনার প্রশ্ন ২-এ এর ইতিহাস।

এবার দেখুন একটি বিক্রির কমান্ড চার স্তর কীভাবে পেরোয়। “পরে” চাপুন:

args = parser.parse_args(["sell", "rice", "3"])
args.cmd == "sell" · args.sku == "rice" · args.qty == 3
type=int-এর জন্য "3" ইতিমধ্যে int; "three" দিলে argparse নিজেই থামাত

item, stock = store.get_item("rice")
→ Item(sku='rice', name='Chinigura', price=14050), 20
service জানে না store SQLite না memory — শুধু Protocol-এর method ডাকে

sale = Sale("rice", qty=3, unit_price=14050, day=date(2026, 10, 18))
qty > 0 ✓  ·  sale.total == 42150 পয়সা
if 3 > 20: raise OutOfStock(...)   ← মিথ্যা, তাই এগিয়ে যায়

UPDATE item SET stock = stock - ? WHERE sku = ?   (3, "rice")
INSERT INTO sale VALUES (?, ?, ?, ?)             ("rice", 3, 42150, "2026-10-18")
দুটোই সফল → COMMIT · rice-এর স্টক এখন 17

2026-10-18 19:42:07 INFO shop.service: sold 3 x rice, stock now 17

ok: 3 x Chinigura = Tk 421.50
$ echo $?  →  0

৪ · Domain — dataclass, পয়সায় টাকা আর custom exception

domain স্তর হলো সিস্টেমের হৃদয়: “পণ্য” আর “বিক্রি” বলতে আমরা কী বুঝি, আর তাদের কোন নিয়ম কখনো ভাঙা যাবে না। এখানে কোনো ফাইল, ডেটাবেস বা print নেই — শুধু সাধারণ Python. তাই এটি সবচেয়ে সহজে টেস্ট করা যায়, আর সবচেয়ে কম বদলায়।

টাকা কেন পূর্ণসংখ্যার পয়সায়

পর্ব ০৭-এ দেখেছেন, 0.1 + 0.2 Python-এ 0.30000000000000004. কারণ IEEE 754 float দশমিক ভগ্নাংশকে দুইয়ের ঘাতে রাখে, আর ০.১ সেখানে হুবহু লেখা যায় না। একটি বিক্রিতে এই ভুল চোখে পড়ে না, কিন্তু হাজার বিক্রির যোগফলে পয়সা এদিক-ওদিক হয়, আর == দিয়ে মেলানো ব্যর্থ হয়। সমাধান দুটি:

• পূর্ণসংখ্যায় সবচেয়ে ছোট একক। টাকার minor unit পয়সা (১ টাকা = ১০০ পয়সা)। ৳১৪০.৫০ রাখা হয় 14050 হিসেবে। int-এর যোগ-গুণ সবসময় নির্ভুল, আর Python-এর int যত বড় দরকার তত বড় হয়।
• Decimal — দশমিক পদ্ধতিতেই হিসাব করা সংখ্যা। ব্যবহারকারীর লেখা “140.50” পড়তে আমরা Decimal ব্যবহার করি, যাচাই করি দশমিকের পরে দুই ঘরের বেশি নেই, তারপর পয়সায় বদলাই। ভেতরে সবখানে int.

from decimal import Decimal, InvalidOperation
from shop.domain import InvalidInput

def parse_taka(text: str) -> int:
    """'140.50' → 14050 পয়সা। ঋণাত্মক, শূন্য, তিন ঘর দশমিক বা অক্ষর হলে InvalidInput."""
    try:
        d = Decimal(text)
    except InvalidOperation:
        raise InvalidInput(f"bad price {text!r}") from None
    if not d.is_finite() or d <= 0 or d != d.quantize(Decimal("0.01")):
        raise InvalidInput(f"bad price {text!r}")
    return int(d * 100)

def taka(poisha: int) -> str:
    return f"Tk {poisha // 100:,}.{poisha % 100:02d}"      # 104250 → 'Tk 1,042.50'

লক্ষ করুন, টাকাকে কখনো float-এ নেওয়া হয় না — Decimal("140.50") * 100 হুবহু 14050. d.is_finite() পরীক্ষাটি “NaN” বা “Infinity” লেখাকে আটকায়, যেগুলো Decimal বৈধ সংখ্যা হিসেবে পড়ে ফেলে। আর ছাপার সময় // আর % দিয়ে টাকা ও পয়সা আলাদা। ভ্যাট বা ছাড়ের মতো ভাগের হিসাব এলে Decimal-এর quantize দিয়ে কোন নিয়মে পূর্ণ করবেন তা স্পষ্ট বলে দিন — এটি ব্যবসার সিদ্ধান্ত, কোডের নয়।

নিজেকে পাহারা দেওয়া dataclass

পর্ব ৩২-এর frozen dataclass এখানে আদর্শ। @dataclass নিজেই __init__, __repr__, __eq__ লিখে দেয়; frozen=True তৈরির পরে বদলানো আটকায়; আর __post_init__ তৈরির মুহূর্তে নিয়ম পরীক্ষা করে। ফল: ভুল অবস্থার একটি Sale object পৃথিবীতে থাকতেই পারে না।

from dataclasses import dataclass
from datetime import date

class ShopError(Exception):
    """সব ব্যবসায়িক ভুলের মূল class — CLI শুধু এটাকেই ধরে।"""

class InvalidInput(ShopError): ...
class UnknownItem(ShopError): ...
class DuplicateItem(ShopError): ...

class OutOfStock(ShopError):
    def __init__(self, sku: str, have: int, want: int) -> None:
        super().__init__(f"only {have} {sku} left, asked {want}")
        self.sku, self.have, self.want = sku, have, want     # পরে কাজে লাগবে

@dataclass(frozen=True)
class Item:
    sku: str
    name: str
    price: int                          # পয়সা

    def __post_init__(self) -> None:
        if not (self.sku.isascii() and self.sku.isidentifier()):
            raise InvalidInput(f"SKU must be a short code like 'rice', got {self.sku!r}")
        if self.price <= 0:
            raise InvalidInput("price must be positive")

@dataclass(frozen=True)
class Sale:
    sku: str
    qty: int
    unit_price: int                     # বিক্রির মুহূর্তের দাম, পয়সায়
    day: date

    def __post_init__(self) -> None:
        if self.qty <= 0:
            raise InvalidInput(f"quantity must be positive, got {self.qty}")

    @property
    def total(self) -> int:
        return self.qty * self.unit_price

তিনটি নকশার সিদ্ধান্ত লক্ষ করুন। এক: Sale নিজের মধ্যে unit_price রাখে। কাল তেলের দাম বাড়লেও আজকের বিক্রির টাকা বদলাবে না — হিসাবের খাতায় অতীত কখনো বদলায় না। দুই: total একটি property, জমা রাখা মান নয় — তাই qty আর total-এর অমিল অসম্ভব। তিন: exception-গুলো একটি exception hierarchy: সবাই ShopError-এর সন্তান।

কেন আলাদা আলাদা custom exception, শুধু ValueError নয়? কারণ এগুলো ব্যবসার ঘটনা, প্রোগ্রামের বাগ নয়। CLI একটি মাত্র except ShopError দিয়ে সব ব্যবসায়িক ভুল ধরে সুন্দর বার্তা দেয়; কিন্তু একটি সত্যিকারের বাগ — ধরুন TypeError — সেই জালে ধরা পড়ে না, traceback দিয়ে জোরে চিৎকার করে, যাতে আপনি জানতে পারেন। আর OutOfStock নিজের মধ্যে have আর want বহন করে — ভবিষ্যতের ওয়েব স্তর এগুলো দিয়ে বলতে পারবে “মাত্র ৫টি আছে, ৫টিই নেবেন?”

এবার দেখুন একটি অবৈধ বিক্রি — স্টক ৫, চাওয়া ৬ — কীভাবে বাতিল হয়, আর কোথাও কোনো দাগ রেখে যায় না:

1print(shop.sell("oil", 6))           # cli.py2item, stock = store.get_item("oil")  # service3sale = Sale("oil", 6, item.price, today)4if 6 > stock: raise OutOfStock(...)5store.record_sale(sale)   # চলেই না6except ShopError as e: log.warning(...)7print(f"error: {e}"); return 1

৫ · Storage — একটি Protocol, দুটি রূপ

service-কে ডেটা রাখতে হবে, কিন্তু আমরা চাই না সে SQLite-এর সাথে বাঁধা থাকুক। পর্ব ৩৩-এর Protocol ঠিক এই কাজের যন্ত্র: আমরা লিখে দিই service-এর কোন কোন method লাগবে — একটি চুক্তি। যে class-এ এই method-গুলো আছে, সে-ই চলবে, উত্তরাধিকার ছাড়াই। একে বলে structural typing; mypy চুক্তি মেলে কি না পরীক্ষা করে দেয়।

from datetime import date
from typing import Protocol
from shop.domain import Item, Sale

class Store(Protocol):
    def add_item(self, item: Item, stock: int) -> None: ...
    def get_item(self, sku: str) -> tuple[Item, int] | None: ...
    def record_sale(self, sale: Sale) -> None: ...
    def restock(self, sku: str, qty: int) -> None: ...
    def sales_between(self, start: date, end: date) -> list[Sale]: ...

এই চুক্তির দুটি বাস্তবায়ন। MemoryStore — একটি dict আর একটি list, প্রায় ২৫ লাইন; টেস্টে ব্যবহারের জন্য, মিলিসেকেন্ডে চলে, কোনো ফাইল তৈরি করে না। এটি একধরনের fake object. আর SqliteStore — আসল কাজের জন্য, পর্ব ৫০-এর নিরাপত্তার নিয়ম মেনে:

import sqlite3
from pathlib import Path

SCHEMA = """
CREATE TABLE IF NOT EXISTS item (
    sku   TEXT PRIMARY KEY,
    name  TEXT NOT NULL,
    price INTEGER NOT NULL CHECK (price > 0),
    stock INTEGER NOT NULL CHECK (stock >= 0)
);
CREATE TABLE IF NOT EXISTS sale (
    id INTEGER PRIMARY KEY, sku TEXT NOT NULL REFERENCES item(sku),
    qty INTEGER NOT NULL, unit_price INTEGER NOT NULL, day TEXT NOT NULL
);
"""

class SqliteStore:
    def __init__(self, path: Path | str = ":memory:") -> None:
        self.conn = sqlite3.connect(path)
        self.conn.executescript(SCHEMA)

    def record_sale(self, sale: Sale) -> None:
        with self.conn:                     # সফল হলে COMMIT, exception হলে ROLLBACK
            self.conn.execute("UPDATE item SET stock = stock - ? WHERE sku = ?",
                              (sale.qty, sale.sku))
            self.conn.execute("INSERT INTO sale (sku, qty, unit_price, day) VALUES (?, ?, ?, ?)",
                              (sale.sku, sale.qty, sale.unit_price, sale.day.isoformat()))

চারটি জিনিস খেয়াল করুন:

• Parameterized query: প্রতিটি মান যায় ? দিয়ে, আলাদা tuple-এ। কখনো f-string দিয়ে SQL বানানো নয় — নইলে কেউ SKU-র জায়গায় SQL লিখে দিলেই SQL injection (পর্ব ৫০)।
• Transaction: with self.conn: ব্লকের দুটি লেখা একসাথে commit হয়; মাঝে কিছু ব্যর্থ হলে rollback. মনে রাখবেন, এই with connection বন্ধ করে না — শুধু transaction সামলায়।
• ডেটাবেসেও পাহারা: CHECK (stock >= 0) — service-এর নিয়মে কোনো বাগ থাকলেও ডেটাবেস ঋণাত্মক স্টক জমা নেবে না, sqlite3.IntegrityError তুলবে, আর transaction ফিরে যাবে। দুই স্তরে পাহারা, একটি ভুললে অন্যটি ধরে।
• ":memory:" default: path না দিলে পুরো ডেটাবেস থাকে RAM-এ — একটি in-memory database. টেস্টে আর এই পাতার চালানো উদাহরণে ঠিক এটিই ব্যবহার করব; আসল দোকানে shop.db ফাইল।

Protocol-এর আসল শক্তি দেখুন: কোন storage বসবে, তা ঠিক হয় এক জায়গায়, আর বাকি সব অপরিবর্তিত।

৬ · এক ফাইলে পুরো সিস্টেম — চালিয়ে দেখুন

আসল প্রজেক্ট কয়েকটি ফাইলে ভাগ করা, কিন্তু এই পাতার runner একটি ফাইলই চালাতে পারে। তাই নিচে চার স্তরের একটি সংক্ষিপ্ত রূপ, এক ফাইলে: domain (Sale, exception), storage (Store Protocol আর :memory: SQLite), service (Shop), আর CLI. প্রজেক্ট বলে এটি অন্য উদাহরণের চেয়ে অনেক লম্বা — প্রায় ৮০ লাইন — কিন্তু প্রতিটি অংশ আপনি এই পর্বে আলাদা করে দেখেছেন। কয়েকটি সরলীকরণ: পণ্যগুলো শুরুতেই কোডে যোগ করা, তারিখ নেই, আর argparse-এর বদলে একটি কমান্ড-লুপ, কারণ runner শুধু ইনপুট-লাইন দিতে পারে।

স্ক্রিপ্ট করা সেশনে বৈধ বিক্রি, স্টকের চেয়ে বেশি চাওয়া, শূন্য পরিমাণ, অজানা পণ্য আর ভুল লেখা — সবই আছে। চালানোর আগে অনুমান করুন রিপোর্টের মোট কত হবে:

import logging, sqlite3, sys
from collections import Counter
from dataclasses import dataclass
from typing import Protocol

logging.basicConfig(stream=sys.stdout, format="  log %(levelname)s: %(message)s", level=logging.INFO)
log = logging.getLogger("shop")
class ShopError(Exception): pass                   # base of all business errors
class OutOfStock(ShopError): pass
class UnknownItem(ShopError): pass
def taka(poisha: int) -> str:
    return f"Tk {poisha // 100:,}.{poisha % 100:02d}"
@dataclass(frozen=True)
class Sale:                                        # domain: guards its own rules
    sku: str
    qty: int
    unit_price: int                                # poisha, never float
    def __post_init__(self) -> None:
        if self.qty <= 0:
            raise ShopError(f"quantity must be positive, got {self.qty}")
    @property
    def total(self) -> int:
        return self.qty * self.unit_price
class Store(Protocol):                             # what the service needs
    def get(self, sku: str) -> tuple[str, int, int] | None: ...
    def record_sale(self, sale: Sale) -> None: ...
    def sales(self) -> list[tuple[str, int, int]]: ...
class SqliteStore:
    def __init__(self) -> None:
        self.db = sqlite3.connect(":memory:")
        self.db.executescript("CREATE TABLE item(sku TEXT PRIMARY KEY, name TEXT, price INT, stock INT);"
                              "CREATE TABLE sale(sku TEXT, qty INT, total INT);")
    def add_item(self, sku: str, name: str, price: int, stock: int) -> None:
        self.db.execute("INSERT INTO item VALUES (?, ?, ?, ?)", (sku, name, price, stock))
    def get(self, sku: str) -> tuple[str, int, int] | None:
        return self.db.execute("SELECT name, price, stock FROM item WHERE sku = ?", (sku,)).fetchone()
    def record_sale(self, sale: Sale) -> None:
        with self.db:                              # one transaction: both or neither
            self.db.execute("UPDATE item SET stock = stock - ? WHERE sku = ?", (sale.qty, sale.sku))
            self.db.execute("INSERT INTO sale VALUES (?, ?, ?)", (sale.sku, sale.qty, sale.total))
    def sales(self) -> list[tuple[str, int, int]]:
        return self.db.execute("SELECT sku, qty, total FROM sale").fetchall()
class Shop:                                        # service: business rules, no print/input
    def __init__(self, store: Store) -> None:
        self.store = store
    def sell(self, sku: str, qty: int) -> str:
        if (item := self.store.get(sku)) is None:
            raise UnknownItem(f"no item '{sku}'")
        name, price, stock = item
        sale = Sale(sku, qty, price)
        if qty > stock:
            raise OutOfStock(f"only {stock} {name} left, asked {qty}")
        self.store.record_sale(sale)
        log.info("sold %d x %s, stock now %d", qty, sku, stock - qty)
        return f"ok: {qty} x {name} = {taka(sale.total)}"
    def report(self) -> list[str]:
        pcs, money = Counter(), Counter()
        for sku, qty, total in self.store.sales():
            pcs[sku] += qty
            money[sku] += total
        rows = [f"{s:<5}{pcs[s]:>3} pcs {taka(money[s]):>11}" for s in sorted(money, key=lambda s: (-money[s], s))]
        return rows + [f"TOTAL {taka(sum(money.values())):>18}"]

store = SqliteStore()
for row in [("rice", "Chinigura", 14050, 20), ("egg", "Egg", 1350, 30), ("oil", "Soyabean", 18900, 5)]:
    store.add_item(*row)                           # Tk 140.50 = 14050 poisha
shop = Shop(store)
for line in sys.stdin:                             # CLI: read, call the service, print
    print(">", line.strip())
    cmd, *args = line.split() or [""]
    try:
        match cmd, args:
            case "sell", [sku, qty] if qty.lstrip("-").isdecimal():
                print("  " + shop.sell(sku, int(qty)))
            case "report", []:
                print("\n".join("  " + row for row in shop.report()))
            case _:
                print("  usage: sell SKU QTY | report")
    except ShopError as e:
        log.warning("%s: %s", type(e).__name__, e)
        print(f"  error: {e}")

৭ · ধাপে ধাপে বানানো — ছয় মাইলস্টোন আর প্রজেক্টের কাঠামো

পর্ব ২১-এ পাঁচটি milestone ছিল; এবার ছয়টি, আর ক্রমটি গুরুত্বপূর্ণ: ভেতর থেকে বাইরে। প্রথমে domain, কারণ সেটি কাউকে চেনে না আর সবচেয়ে সহজে টেস্ট হয়; সবশেষে বাইরের জিনিস — ডেটাবেস আর ফাইল। প্রতিটি মাইলস্টোনের শেষে টেস্ট পাস, একটি git commit, আর একটি প্রশ্ন: “আজ থামতে হলে হাতে কী আছে?”

parse_taka("140.50") == 14050 · parse_taka("1.005") → InvalidInput
Sale("oil", 0, 18900, d) → InvalidInput
টেস্ট: টাকার সীমা · NaN · ০ পরিমাণ · frozen-এ বদলাতে গেলে FrozenInstanceError

shop = Shop(MemoryStore(), today=lambda: date(2026, 10, 18))
shop.sell("oil", 6) → OutOfStock · stock অপরিবর্তিত
টেস্ট: বিক্রি · স্টক কম · অজানা SKU · ডুপ্লিকেট SKU · restock

$ python -m shop sell oil 6
error: only 5 oil left, asked 6        (exit code 1)
টেস্ট: main(["sell", "oil", "6"]) == 1 · capsys দিয়ে আউটপুট মেলানো

@pytest.fixture(params=["memory", "sqlite"])
M2-এর সব টেস্ট এবার দুই store-এ · তার সাথে: ঋণাত্মক স্টকে IntegrityError
নতুন কোনো service টেস্ট লিখতে হলো না

$ python -m shop report --date 2026-10-18
rice  3 pcs  Tk 421.50 ... TOTAL Tk 1,042.50 · top: rice, oil, egg
টেস্ট: খালি দিন · সমান টাকায় ক্রম · CSV-তে বাংলা নাম round trip

$ ruff check . && mypy src && pytest
All checks passed! · Success: no issues found · 24 passed
GitHub-এ প্রতিটি push-এ এই তিনটি স্বয়ংক্রিয়ভাবে (CI)

প্রজেক্টের কাঠামো আর pyproject.toml

পর্ব ২২-২৩-এ শেখা src layout:

shop-ledger/
├── pyproject.toml
├── README.md
├── src/shop/
│   ├── __init__.py
│   ├── __main__.py      # python -m shop
│   ├── cli.py           # argparse, logging config, exit code
│   ├── service.py       # Shop
│   ├── domain.py        # Item, Sale, ShopError…
│   ├── money.py         # parse_taka, taka
│   ├── storage.py       # Store, MemoryStore, SqliteStore
│   └── report.py        # daily_report, export_csv, export_json
└── tests/
    ├── conftest.py      # shop fixture (memory + sqlite)
    ├── test_domain.py
    ├── test_service.py
    └── test_cli.py

[project]
name = "shop-ledger"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = []                       # শুধু standard library

[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy"]

[project.scripts]
shop = "shop.cli:main"                  # pip install করলে "shop sell rice 3"

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

dependencies = [] একটি সচেতন সিদ্ধান্ত: sqlite3, argparse, logging, csv, json, decimal — সবই standard library-তে। দোকানের পুরোনো কম্পিউটারে শুধু Python থাকলেই চলবে, আর পর্ব ৫০-এর supply-chain ঝুঁকিও প্রায় শূন্য। [project.scripts] একটি entry point বানায়: pip install -e . করলে shop নামে একটি কমান্ড তৈরি হয়। আর python -m shop কাজ করে __main__.py-এর জন্য:

def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)          # subcommand: add, sell, restock…
    logging.basicConfig(filename=args.log, level=logging.INFO,
                        format="%(asctime)s %(levelname)s %(name)s: %(message)s")
    shop = Shop(SqliteStore(args.db))               # এখানেই, শুধু এখানেই, storage বাছাই
    try:
        match args.cmd:
            case "sell":
                print(shop.sell(args.sku, args.qty))
            case "report":
                print(render(shop.daily_report(args.date)))
            # … add, restock, stock, export
    except ShopError as e:
        log.warning("%s: %s", type(e).__name__, e)
        print(f"error: {e}", file=sys.stderr)
        return 1
    return 0

# __main__.py — পুরো ফাইল
from shop.cli import main
raise SystemExit(main())

রিপোর্ট আর export — Counter, groupby, CSV, JSON

দৈনিক রিপোর্ট মূলত তিনটি প্রশ্নের উত্তর: কোন পণ্যে কত টাকা, মোট কত, আর সেরা তিনটি কোনগুলো। পর্ব ২৭-এর Counter গোনার জন্য তৈরি, আর তার most_common() সেরা তালিকা দেয়। কয়েক দিনের রিপোর্ট একসাথে লাগলে পর্ব ৩৮-এর groupby — তবে মনে রাখবেন, groupby শুধু পাশাপাশি থাকা সমান key-কে এক দলে আনে, তাই আগে সাজাতে হয়:

from collections import Counter
from itertools import groupby
from operator import attrgetter

def daily_report(sales: list[Sale]) -> Report:
    money: Counter[str] = Counter()
    for s in sales:
        money[s.sku] += s.total
    rows = sorted(money.items(), key=lambda kv: (-kv[1], kv[0]))   # টাকা ↓, তারপর SKU
    return Report(rows=rows, total=sum(money.values()),
                  top=[sku for sku, _ in rows[:3]])

def by_day(sales: list[Sale]) -> dict[date, int]:
    ordered = sorted(sales, key=attrgetter("day"))                  # groupby-র আগে sort!
    return {day: sum(s.total for s in grp)
            for day, grp in groupby(ordered, key=attrgetter("day"))}

def export_csv(sales: list[Sale], path: Path) -> None:
    with path.open("w", newline="", encoding="utf-8-sig") as f:     # BOM: Excel-এ বাংলা ঠিক
        w = csv.writer(f)
        w.writerow(["day", "sku", "qty", "unit_price_taka", "total_taka"])
        w.writerows([s.day.isoformat(), s.sku, s.qty, taka_plain(s.unit_price),
                     taka_plain(s.total)] for s in sales)

লক্ষ করুন, most_common()-এর বদলে আমরা নিজেরা সাজিয়েছি: most_common সমান সংখ্যার ক্ষেত্রে প্রথম দেখার ক্রম রাখে, যা দিনভেদে বদলাতে পারে; আমাদের tuple-চাবি ফলকে পুরোপুরি নির্দিষ্ট করে। CSV-তে newline="" (পর্ব ২৬) আর utf-8-sig — শেষেরটি ফাইলের শুরুতে একটি BOM বসায়, যাতে Excel বাংলা নাম ঠিকঠাক দেখায়। JSON export-এ json.dumps(..., ensure_ascii=False, indent=2), যাতে “চিনিগুঁড়া” চ... হয়ে না যায়।

৮ · টেস্ট আর নকশার সিদ্ধান্ত

পর্ব ৩৯-এর pytest এখানে পুরো শক্তিতে। সবচেয়ে মূল্যবান কৌশলটি conftest.py-এর একটি fixture, যা প্রতিটি টেস্টকে দুটি store-এ চালায়:

import pytest
from datetime import date
from shop.domain import InvalidInput, OutOfStock
from shop.service import Shop
from shop.storage import MemoryStore, SqliteStore

@pytest.fixture(params=["memory", "sqlite"])
def shop(request, tmp_path):
    store = MemoryStore() if request.param == "memory" else SqliteStore(tmp_path / "t.db")
    s = Shop(store, today=lambda: date(2026, 10, 18))
    s.add_item("oil", "Soyabean", "189", stock=5)
    return s

def test_sell_reduces_stock(shop):
    assert shop.sell("oil", 2) == "ok: 2 x Soyabean = Tk 378.00"
    assert shop.stock("oil") == 3

def test_out_of_stock_changes_nothing(shop):
    with pytest.raises(OutOfStock) as exc:
        shop.sell("oil", 6)
    assert exc.value.have == 5
    assert shop.stock("oil") == 5 and shop.daily_report().total == 0

@pytest.mark.parametrize("qty", [0, -1])
def test_bad_quantity_is_rejected(shop, qty):
    with pytest.raises(InvalidInput):
        shop.sell("oil", qty)

তিনটি টেস্ট ফাংশন, কিন্তু চলবে আটটি টেস্ট: প্রথম দুটি দুই store-এ (২ × ২ = ৪), আর শেষটি দুই store × দুই পরিমাণ (৪)। tmp_path pytest-এর দেওয়া একটি অস্থায়ী ফোল্ডার, প্রতিটি টেস্টের জন্য নতুন — টেস্টগুলো একে অপরের ডেটা দেখে না। চালালে মোটামুটি এমন দেখবেন (সময় আর version আপনার কম্পিউটারে আলাদা হবে):

$ pytest tests/test_service.py
============================= test session starts ==============================
collected 8 items

tests/test_service.py ........                                           [100%]

============================== 8 passed in 0.09s ===============================

pytest এই পাতায় চালানো যায় না, তাই নিচে একই ভাবনা সাধারণ assert দিয়ে: টাকার নির্ভুলতা, সফল বিক্রি, আর বাতিল হওয়া বিক্রিতে অবস্থার অপরিবর্তন — একটি MemoryStore-এর ওপর। এখানেও লম্বা, কারণ টেস্টের জন্য domain আর store-এর ছোট রূপ ফাইলের ভেতরেই রাখতে হয়েছে:

import copy
from dataclasses import dataclass
from decimal import Decimal, InvalidOperation

class ShopError(Exception): pass
class OutOfStock(ShopError): pass
def parse_taka(text: str) -> int:                  # "140.50" -> 14050 poisha
    try:
        d = Decimal(text)
    except InvalidOperation:
        raise ShopError(f"bad price {text!r}") from None
    if not d.is_finite() or d <= 0 or d != d.quantize(Decimal("0.01")):
        raise ShopError(f"bad price {text!r}")
    return int(d * 100)
@dataclass(frozen=True)
class Sale:
    sku: str
    qty: int
    unit_price: int
    def __post_init__(self) -> None:
        if self.qty <= 0:
            raise ShopError("quantity must be positive")
class MemoryStore:                                 # same methods as SqliteStore
    def __init__(self) -> None:
        self.items = {"oil": ["Soyabean", 18900, 5]}
        self.sold: list[Sale] = []
    def get(self, sku: str) -> tuple[str, int, int] | None:
        return tuple(self.items[sku]) if sku in self.items else None
    def record_sale(self, sale: Sale) -> None:
        self.items[sale.sku][2] -= sale.qty
        self.sold.append(sale)
def sell(store: MemoryStore, sku: str, qty: int) -> int:   # the service rule, trimmed
    name, price, stock = store.get(sku)
    sale = Sale(sku, qty, price)
    if qty > stock:
        raise OutOfStock(f"only {stock} {name} left")
    store.record_sale(sale)
    return sale.qty * price
def rejects(fn, *args) -> bool:                    # True if fn raises a ShopError
    try:
        fn(*args)
    except ShopError:
        return True
    return False

assert 0.10 + 0.20 != 0.30 and parse_taka("0.10") + parse_taka("0.20") == parse_taka("0.30")
assert all(rejects(parse_taka, t) for t in ["abc", "-5", "0", "1.005", "NaN"])
print("PASS money: integer poisha adds exactly, 5 bad prices rejected")
s = MemoryStore()
assert sell(s, "oil", 2) == 37800 and s.get("oil")[2] == 3 and len(s.sold) == 1
print("PASS sell: stock goes down and the sale is recorded")
before = copy.deepcopy(s.items), list(s.sold)
assert rejects(sell, s, "oil", 4) and rejects(sell, s, "oil", 0)
assert (s.items, s.sold) == before and issubclass(OutOfStock, ShopError)
print("PASS rejected sales (out of stock, qty 0) change nothing")

নকশার সিদ্ধান্ত — কেন এভাবে, আর দাম কী

প্রতিটি বড় সিদ্ধান্ত লিখে রাখুন: কী বেছে নিলেন, কী বাদ দিলেন, কেন। পেশাদার দলে একে বলে architecture decision record. আমাদের সংক্ষিপ্ত তালিকা:

৯ · AI-এর যুগে — ক্যাপস্টোনে AI আপনার pair programmer, মালিক আপনি

“Python-এ দোকানের স্টক ম্যানেজমেন্ট সিস্টেম লেখো” — এক লাইনের এই অনুরোধে AI কয়েক সেকেন্ডে ৩০০ লাইন দেবে, আর সেটি চলবেও। কিন্তু একটু খুঁটিয়ে দেখলে প্রায়ই পাবেন: দাম float-এ, SQL f-string দিয়ে বানানো, স্টক পরীক্ষা আর বিক্রি লেখা আলাদা transaction-এ, সব কাজ এক বিশাল class-এ, কোনো টেস্ট নেই, আর এমন একটি library যা আসলে নেইই। সবচেয়ে বড় সমস্যা হলো, ইন্টারভিউতে কেউ জিজ্ঞেস করলে “এই অংশটা এভাবে কেন?” — আপনার কাছে উত্তর থাকবে না।

ক্যাপস্টোনের উদ্দেশ্য কোড পাওয়া নয়, সিদ্ধান্ত নেওয়ার ক্ষমতা দেখানো। তাই AI-কে ব্যবহার করুন pair programming-এর সঙ্গী হিসেবে, চারটি নিয়মে: (১) পরিকল্পনা আপনার — স্পেক, স্তর, ডেটা মডেল আগে নিজে লিখুন, তারপর AI-কে সমালোচনা করতে বলুন। (২) ছোট টুকরোয় চান — একবারে একটি মাইলস্টোন, একটি ফাইল। (৩) কোডের আগে টেস্ট চান, আর টেস্টের প্রত্যাশিত মান নিজে হিসাব করে মেলান। (৪) যন্ত্র দিয়ে যাচাই — AI-এর প্রতিটি কোডে ruff, mypy আর pytest চালান; আর যা ব্যাখ্যা করতে পারেন না, তা paste করবেন না।

AI-এর লেখা কোড প্রজেক্টে ঢোকানোর আগে — চেকলিস্ট

• প্রতিটি লাইন কাউকে মুখে ব্যাখ্যা করতে পারি; না পারলে আগে শিখি, নয়তো বাদ দিই
• কোডটি ঠিক স্তরে আছে: service-এ কোনো print/SQL নেই, domain-এ কোনো I/O নেই
• টাকা কোথাও float নয়; সব SQL-এ ? placeholder; লেখার কাজ transaction-এর ভেতরে
• ব্যবসার ভুল ShopError-এর সন্তান হিসেবে ওঠে; কোথাও খালি except: বা except Exception: pass নেই
• import করা প্রতিটি package সত্যিই আছে আর দরকারি (standard library-তে থাকলে বাইরের package নয়)
• ruff check, mypy আর pytest তিনটিই পরিষ্কার; নতুন আচরণের জন্য অন্তত একটি নতুন টেস্ট, যার প্রত্যাশিত মান আমি নিজে হিসাব করেছি
• commit message-এ সৎভাবে লিখেছি কোন অংশে AI সাহায্য করেছে

১০ · এরপর কোথায় — বাড়ানোর দিক, portfolio আর কোর্সের মানচিত্র

বাড়ানোর দিক — প্রতিটি একটি নতুন স্তর, পুরোনো কোড অক্ষত

from fastapi import FastAPI, HTTPException

app = FastAPI()
shop = Shop(SqliteStore("shop.db"))

@app.post("/sales")
def sell(sku: str, qty: int) -> dict[str, str]:
    try:
        return {"message": shop.sell(sku, qty)}
    except OutOfStock as e:
        raise HTTPException(status_code=409, detail=str(e))
    except ShopError as e:
        raise HTTPException(status_code=400, detail=str(e))

দেখুন, ওয়েব স্তরটি CLI-র প্রায় যমজ: লেখা থেকে মান বানায়, service ডাকে, exception-কে নিজের ভাষায় (HTTP status code) বদলায়। চার স্তরের নকশার সবচেয়ে বড় প্রমাণ এটাই।

Portfolio — প্রজেক্টকে আপনার পরিচয়পত্র বানানো

চাকরির বাজারে, ফ্রিল্যান্সিংয়ে বা উচ্চশিক্ষার আবেদনে “Python জানি” বলার চেয়ে অনেক জোরালো একটি লিংক, যেখানে একটি গোছানো প্রজেক্ট আছে। কয়েকটি পরামর্শ:

• README প্রথম পাতা: এক বাক্যে কী সমস্যা সমাধান করে; ৩০ সেকেন্ডের একটি টার্মিনাল-সেশন (লেখা বা GIF); ইনস্টল আর চালানোর তিনটি কমান্ড; স্থাপত্যের একটি ছবি; “নকশার সিদ্ধান্ত” অংশ (উপরের টেবিলের মতো); আর জানা সীমাবদ্ধতা। শেষেরটি অনেকে বাদ দেন — অথচ সীমাবদ্ধতা স্বীকার করা পরিণত প্রকৌশলীর লক্ষণ।
• GitHub-এ ইতিহাসসহ: একটি বিশাল “final code” commit নয় — মাইলস্টোন ধরে অর্থবহ commit (“M4: SqliteStore passes all service tests”). প্রতিটি push-এ টেস্ট চালানোর CI ব্যাজ।
• ২–৩ মিনিটের ডেমো ভিডিও: একটি বিক্রি, একটি বাতিল হওয়া বিক্রি, রিপোর্ট, আর টেস্ট চালানো। বাংলায় বা ইংরেজিতে, যেটিতে আপনি স্বচ্ছন্দ — মুখে ব্যাখ্যা করতে পারাটাই আসল দেখানোর জিনিস।
• নিজের বিষয় বেছে নিন: হুবহু এই দোকান না বানিয়ে একই নকশায় কোচিং সেন্টারের ফি ও উপস্থিতি, ফার্মেসির ওষুধের মেয়াদ, বা আপনার এলাকার কোনো আসল সমস্যা। একজন আসল ব্যবহারকারী থাকলে আরও ভালো — তাঁর প্রতিক্রিয়া README-তে লিখুন।

ইন্টারভিউয়ে যিনি প্রজেক্ট দেখেন, তিনি সাধারণত লাইনের সংখ্যা গোনেন না। তিনি দেখেন: আপনি কি নিজের সিদ্ধান্ত ব্যাখ্যা করতে পারেন? ভুল কোথায় হতে পারে জানেন? টেস্ট আছে কি, আর কী পরীক্ষা করে? টাকার মতো সংবেদনশীল জিনিস ঠিকভাবে সামলেছেন কি? কোড পড়তে সহজ কি? প্রায়ই তাঁরা বলবেন, “এখানে একটা নতুন নিয়ম যোগ করুন” — তখন বোঝা যায় নকশাটি সত্যিই আপনার কি না।

যা শিখলেন — কোর্সের মানচিত্রে ক্যাপস্টোন