تا تاریخ 2026-09-15.
نسخه 3 Beancount، که در اواسط 2024 منتشر شد، تکامل معماری قابل توجهی برای ابزار محبوب حسابداری متن ساده است. در حالی که سازگاری با نسخه‌های قبلی برای فایل‌های دفتر کاربر حفظ می‌شود، ساختار اساسی و ابزارهای همراه تغییرات اساسی کرده‌اند. در اینجا تفکیکی از آنچه در Beancount v3 جدید است — و آنچه در خط 3.1–3.2 از زمان انتشار اولیه این راهنما اضافه شده — ارائه شده است.
برای نحو و دفترهای اولیه، به مرجع نحو Beancount و شروع به کار مراجعه کنید. برای رابط خط فرمان میزبان که بررسی، پرس‌وجو، واردات و گزارش‌ها را پوشش می‌دهد، به مرجع خط فرمان Beancount مراجعه کنید.
معماری ماژولارتر و ساده‌تر
مهم‌ترین تغییر در Beancount v3 حرکت به سمت اکوسیستم ماژولارتر است. چندین قابلیت کلیدی که قبلاً با هسته همراه بودند، به پروژه‌های جداگانه و مستقل تفکیک شده‌اند. این امر هسته Beancount را سبک‌تر می‌کند و امکان توسعه متمرکزتر بر روی اجزای جداگانه را فراهم می‌آورد.
اجزای کلیدی که اکنون بسته‌های جداگانه هستند عبارتند از:
- beanquery: ابزار قدرتمند پرس‌وجو شبیه به SQL برای فایل‌های دفتر شما اکنون در بسته خودش قرار دارد.
- beangulp: این خانه جدید چارچوب واردات داده است که جایگزین ماژول قبلی
beancount.ingestمی‌شود. - beanprice: ابزار اختصاصی برای دریافت قیمت کالاها و سهام.
این جداسازی به این معنی است که کاربران برای حفظ عملکرد کامل که در نسخه 2 به آن عادت داشتند، باید این بسته‌ها را علاوه بر خود beancount نصب کنند.
تغییرات در ابزارهای خط فرمان و گردش‌های کاری
با بازتاب معماری ماژولار جدید، تغییرات قابل توجهی در ابزارهای خط فرمان وجود دارد:
bean-reportحذف شده است: این ابزار حذف شده است. اکنون از کاربران دعوت می‌شود برای نیازهای گزارش‌دهی خود ازbean-query(از بستهbeanquery) استفاده کنند.- گردش کار جدید واردکننده: دستورات
bean-extractوbean-identifyاز هسته حذف شده‌اند. رویکرد جدید باbeangulpمبتنی بر اسکریپت است. کاربران اکنون اسکریپت‌های پایتون خود را برای مدیریت واردات داده از منابع خارجی مانند صورت‌های بانکی ایجاد می‌کنند.
افزایش‌های نحو و ویژگی‌ها
در حالی که اصول اساسی حسابداری یکسان باقی مانده است، Beancount v3 برخی انعطاف‌پذیری‌های خوشایند را به نحو خود معرفی می‌کند:
- کدهای ارز انعطاف‌پذیرتر: محدودیت‌های قبلی در مورد طول و کاراکترهای نام ارز کاهش یافته است. نمادهای ارز تک‌کاراکتری اکنون پشتیبانی می‌شوند.
- پرچم‌های گسترده تراکنش: کاربران اکنون می‌توانند از هر حرف بزرگ از A تا Z به عنوان پرچم برای تراکنش‌ها استفاده کنند، که امکان دسته‌بندی دقیق‌تر را فراهم می‌کند.
مهمتر از همه، این تغییرات با نسخه‌های قبلی سازگار هستند، بنابراین فایل‌های دفتر Beancount v2 موجود شما بدون هیچ تغییری کار خواهند کرد.
بازنویسی C++ و کارایی
یکی از اهداف بلندمدت Beancount بازنویسی اجزای حساس به عملکرد آن در C++ بوده است. نسخه اولیه Beancount v3 شامل هسته C++ نبود، و تا تاریخ 2026-09-15 این امر همچنان صادق است: خط PyPI منتشر شده (تا 3.2.3) هنوز شاخه پایتون ماژولار v3 است. کار تاریخی C++/Bazel در یک شاخه جداگانه cpp قرار دارد و بخشی از بسته‌هایی نیست که کاربران از PyPI نصب می‌کنند. بنابراین عملکرد روزانه انتشارهای فعلی v3 در همان کلاس اواخر v2 است، با بهبودهای افزایشی در تجزیه‌گر و ابزارها به جای بازنویسی C++ با مرتبه بزرگی.
از زمان نوشتن این مطلب (v3.1 → v3.2.x)
منابع اصلی: فایل CHANGES پروژه، نماهای مقایسه گیت‌هاب برای 3.1.0…3.2.0، و PyPI beancount (آخرین 3.2.3 تا 2026-09-15).
- خط 3.1.x — ادامه پاک‌سازی بسته‌بندی و API پس از تقسیم ماژولار 3.0 (
beanquery،beangulp،beanpriceنصب‌های جداگانه باقی می‌مانند). - 3.2.0 (2025-09-14) — کامیت انتشار در
beancount/beancount؛ کار قابل توجه کاربر در این بازه شاملbean-formatچندفایلی، اصلاحات تلورانس/دقت، و نگهداری چرخ/CI است (به لینک مقایسه بالا مراجعه کنید). - 3.2.1–3.2.3 (2026) — انتشارهای دودویی و بسته‌بندی بعدی (شامل پوشش تست پایتون 3.14 و داربست مستندات که در خلاصه 3.2.1 در لیست پستی ذکر شده). با
pip install -U beancountنصب کنید و همراهان (beanquery،beangulp) را هنگام ارتقا به نسخه‌های اصلی مشابه ثابت کنید.
Fava: Fava 1.30 پشتیبانی از Beancount 3 را اضافه کرد (2024-12-29). Fava 1.30.13 (2026-05-19) پشتیبانی از Beancount 2 را حذف کرد و انتظار beangulp را برای واردکننده‌ها دارد. خط PyPI فعلی تا 2026-09-15 1.30.16 است. ارتقاهای Fava را با دفتر Beancount 3 جفت کنید.
مهاجرت از v2 به v3
برای اکثر کاربران، مهاجرت از Beancount v2 به v3 نسبتاً ساده است:
- فایل‌های دفتر: هیچ تغییری برای فایل‌های
.beancountشما لازم نیست. - نصب: باید بسته‌های جدید و جداگانه مانند
beanqueryوbeangulpرا با استفاده ازpipنصب کنید. - اسکریپت‌های واردکننده: اگر واردکننده‌های سفارشی دارید، باید آنها را برای استفاده از API جدید
beangulpبهروزرسانی کنید. این کار عمدتاً شامل تغییر کلاس پایه‌ای است که واردکننده‌های شما از آن ارث می‌برند و تنظیم برخی امضای متدها است. - Fava: رابط وب محبوب Beancount، Fava، برای سازگاری با v3 بهروزرسانی شده است. برای تجربه‌ای بی‌نقص، مطمئن شوید آخرین نسخه Fava را دارید.
در اصل، Beancount v3 یک انتشار بنیادی است که معماری پروژه را ساده‌تر می‌کند، آن را ماژولارتر و در درازمدت آسان‌تر برای نگهداری و توسعه می‌سازد. در حالی که نیاز به برخی تنظیمات در گردش‌های کاری کاربر دارد، به‌ویژه در زمینه واردات داده، زمینه را برای توسعه آینده این ابزار حسابداری قدرتمند فراهم می‌کند.
