macrs 0.1.0__py3-none-any.whl

macrs/__init__.py

@@ -0,0 +1,40 @@
+"""macrs — IRS Publication 946 MACRS depreciation schedules.
+
+Deterministic, decimal-precise depreciation schedules for US tax depreciation
+under the Modified Accelerated Cost Recovery System. Rates come from IRS
+Publication 946 Appendix A tables.
+
+Not tax advice. Verify recovery period, convention, section 179, and bonus
+depreciation eligibility against current law and the current Publication 946
+before filing.
+"""
+
+from .models import AssetInput, DepreciationSchedule, ScheduleLine, money
+from .schedule import (
+    asset_from_class,
+    build_schedule,
+    lookup_asset_class,
+    mid_quarter_required,
+    month_to_quarter,
+    schedule_for_class,
+)
+from .tables import ASSET_CLASSES, TABLE_SOURCE, TABLE_URL
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ASSET_CLASSES",
+    "AssetInput",
+    "DepreciationSchedule",
+    "ScheduleLine",
+    "TABLE_SOURCE",
+    "TABLE_URL",
+    "asset_from_class",
+    "build_schedule",
+    "lookup_asset_class",
+    "mid_quarter_required",
+    "money",
+    "month_to_quarter",
+    "schedule_for_class",
+    "__version__",
+]

macrs/cli.py

@@ -0,0 +1,284 @@
+"""Command-line interface for MACRS depreciation schedules."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from decimal import Decimal
+from typing import Optional, Sequence, TextIO
+
+from . import __version__
+from .models import AssetInput, money
+from .schedule import (
+    build_schedule,
+    lookup_asset_class,
+    mid_quarter_required,
+    schedule_for_class,
+)
+from .tables import ASSET_CLASSES, GDS_PERSONAL_PERIODS, TABLE_SOURCE, TABLE_URL
+
+
+def _print_schedule(sched, out: Optional[TextIO] = None, *, verbose: bool = False) -> None:
+    if out is None:
+        out = sys.stdout
+    a = sched.asset
+    print(f"# MACRS depreciation schedule", file=out)
+    if a.label:
+        print(f"# Asset: {a.label}", file=out)
+    if a.description:
+        print(f"# Class: {a.description}", file=out)
+    print(f"# Cost: {a.cost}", file=out)
+    print(f"# Recovery: {a.recovery_years}-year  Convention: {sched.convention}", file=out)
+    print(f"# Table: {sched.table_id}", file=out)
+    print(f"# Source: {sched.table_source}", file=out)
+    print(f"# §179: {sched.section_179_deduction}  Bonus: {sched.bonus_deduction}", file=out)
+    print(f"# MACRS basis: {sched.macrs_basis}", file=out)
+    print(f"# Year-1 total (§179+bonus+MACRS): {sched.total_first_year}", file=out)
+    print(file=out)
+    headers = [
+        "year",
+        "calendar",
+        "rate_%",
+        "depreciation",
+        "cumulative",
+        "remaining",
+    ]
+    print("\t".join(headers), file=out)
+    for line in sched.lines:
+        print(
+            "\t".join(
+                [
+                    str(line.recovery_year),
+                    str(line.calendar_year or ""),
+                    str(line.rate_percent),
+                    str(line.depreciation),
+                    str(line.cumulative_depreciation),
+                    str(line.remaining_basis),
+                ]
+            ),
+            file=out,
+        )
+    print(file=out)
+    print(f"# Total MACRS depreciation: {sched.total_macrs_depreciation}", file=out)
+    if sched.warnings:
+        print("# Warnings:", file=out)
+        for w in sched.warnings:
+            print(f"#   - {w}", file=out)
+    if verbose:
+        print("# Audit trail:", file=out)
+        for r in sched.reasons:
+            print(f"#   - {r}", file=out)
+    print(
+        "# Disclaimer: Not tax advice. Verify against current IRS Publication 946.",
+        file=out,
+    )
+
+
+def cmd_schedule(args: argparse.Namespace) -> int:
+    if args.asset_class:
+        sched = schedule_for_class(
+            args.cost,
+            args.asset_class,
+            convention=args.convention,
+            placed_in_service_month=args.month,
+            placed_in_service_year=args.year,
+            section_179=args.section_179,
+            bonus_percent=args.bonus,
+            business_use_percent=args.business_use,
+            label=args.label,
+        )
+    else:
+        asset = AssetInput(
+            cost=money(args.cost),
+            recovery_years=args.years,
+            convention=args.convention,
+            placed_in_service_month=args.month,
+            placed_in_service_year=args.year,
+            quarter=args.quarter,
+            section_179=money(args.section_179),
+            bonus_percent=Decimal(str(args.bonus)),
+            business_use_percent=Decimal(str(args.business_use)),
+            label=args.label,
+        )
+        sched = build_schedule(asset)
+
+    if args.format == "json":
+        payload = {
+            "cost": str(sched.asset.cost),
+            "recovery_years": sched.asset.recovery_years,
+            "convention": sched.convention,
+            "table_id": sched.table_id,
+            "table_source": sched.table_source,
+            "section_179": str(sched.section_179_deduction),
+            "bonus": str(sched.bonus_deduction),
+            "macrs_basis": str(sched.macrs_basis),
+            "total_first_year": str(sched.total_first_year),
+            "total_macrs": str(sched.total_macrs_depreciation),
+            "lines": sched.to_rows(),
+            "reasons": sched.reasons if args.verbose else [],
+            "warnings": sched.warnings,
+            "disclaimer": "Not tax advice. Verify against current IRS Publication 946.",
+        }
+        json.dump(payload, sys.stdout, indent=2)
+        print()
+    elif args.format == "csv":
+        w = csv.DictWriter(
+            sys.stdout,
+            fieldnames=[
+                "recovery_year",
+                "calendar_year",
+                "rate_percent",
+                "depreciation",
+                "cumulative_depreciation",
+                "remaining_basis",
+                "notes",
+            ],
+        )
+        w.writeheader()
+        for row in sched.to_rows():
+            w.writerow(row)
+    else:
+        _print_schedule(sched, verbose=args.verbose)
+    return 0
+
+
+def cmd_classes(_: argparse.Namespace) -> int:
+    print(f"# Common asset classes (from {TABLE_SOURCE})")
+    print("key\tgds_years\tads_years\tkind\tdescription")
+    for key, meta in sorted(ASSET_CLASSES.items()):
+        print(
+            f"{key}\t{meta['gds_years']}\t{meta['ads_years']}\t"
+            f"{meta['kind']}\t{meta['description']}"
+        )
+    return 0
+
+
+def cmd_mq_test(args: argparse.Namespace) -> int:
+    qs = [args.q1, args.q2, args.q3, args.q4]
+    required, ratio, reasons = mid_quarter_required(qs)
+    if args.format == "json":
+        json.dump(
+            {
+                "mid_quarter_required": required,
+                "q4_ratio": str(ratio),
+                "quarters": [str(money(q)) for q in qs],
+                "reasons": reasons,
+            },
+            sys.stdout,
+            indent=2,
+        )
+        print()
+    else:
+        print(f"Mid-quarter required: {required}")
+        print(f"Q4 ratio: {ratio * 100}%")
+        for r in reasons:
+            print(f"  - {r}")
+    return 0
+
+
+def cmd_rates(args: argparse.Namespace) -> int:
+    from .tables import personal_gds_rates
+
+    rates = personal_gds_rates(
+        args.years,
+        convention=args.convention,
+        quarter=args.quarter,
+    )
+    for i, r in enumerate(rates, 1):
+        print(f"{i}\t{r}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="macrs",
+        description=(
+            "MACRS depreciation schedules from IRS Publication 946 percentage tables. "
+            "Not tax advice."
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"macrs {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("schedule", help="Build a depreciation schedule")
+    s.add_argument("--cost", type=str, required=True, help="Asset cost / basis")
+    s.add_argument(
+        "--years",
+        type=int,
+        default=5,
+        help="Recovery period: 3,5,7,10,15,20 (personal); 27 residential; 39 nonresidential",
+    )
+    s.add_argument(
+        "--convention",
+        default="half_year",
+        choices=["half_year", "mid_quarter", "mid_month"],
+        help="Depreciation convention",
+    )
+    s.add_argument("--month", type=int, default=1, help="Month placed in service (1-12)")
+    s.add_argument("--year", type=int, default=None, help="Calendar year placed in service")
+    s.add_argument("--quarter", type=int, default=None, help="Quarter 1-4 (mid_quarter)")
+    s.add_argument("--section-179", type=str, default="0", dest="section_179")
+    s.add_argument("--bonus", type=str, default="0", help="Bonus depreciation percent 0-100")
+    s.add_argument(
+        "--business-use",
+        type=str,
+        default="100",
+        dest="business_use",
+        help="Business-use percent 0-100",
+    )
+    s.add_argument(
+        "--class",
+        dest="asset_class",
+        default=None,
+        help=f"Named asset class: {', '.join(sorted(ASSET_CLASSES))}",
+    )
+    s.add_argument("--label", default=None)
+    s.add_argument(
+        "--format",
+        choices=["text", "json", "csv"],
+        default="text",
+    )
+    s.add_argument("-v", "--verbose", action="store_true", help="Show audit trail")
+    s.set_defaults(func=cmd_schedule)
+
+    c = sub.add_parser("classes", help="List common asset class shortcuts")
+    c.set_defaults(func=cmd_classes)
+
+    m = sub.add_parser(
+        "mq-test",
+        help="Apply the >40%% fourth-quarter mid-quarter convention test",
+    )
+    m.add_argument("--q1", type=str, required=True)
+    m.add_argument("--q2", type=str, required=True)
+    m.add_argument("--q3", type=str, required=True)
+    m.add_argument("--q4", type=str, required=True)
+    m.add_argument("--format", choices=["text", "json"], default="text")
+    m.set_defaults(func=cmd_mq_test)
+
+    r = sub.add_parser("rates", help="Print raw IRS percentage rates for a class/convention")
+    r.add_argument("--years", type=int, required=True, choices=list(GDS_PERSONAL_PERIODS))
+    r.add_argument(
+        "--convention",
+        default="half_year",
+        choices=["half_year", "mid_quarter"],
+    )
+    r.add_argument("--quarter", type=int, default=None)
+    r.set_defaults(func=cmd_rates)
+
+    return p
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (ValueError, KeyError) as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

macrs/models.py

@@ -0,0 +1,105 @@
+"""Domain models for MACRS depreciation schedules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal
+from typing import List, Optional
+
+
+def money(value: Decimal | int | str | float) -> Decimal:
+    """Quantize to cents using banker's rounding default ROUND_HALF_EVEN via Decimal."""
+    d = value if isinstance(value, Decimal) else Decimal(str(value))
+    return d.quantize(Decimal("0.01"))
+
+
+@dataclass(frozen=True)
+class AssetInput:
+    """Inputs for a single depreciable asset schedule."""
+
+    cost: Decimal
+    recovery_years: int
+    """GDS recovery period: 3,5,7,10,15,20 for personal; 27 for residential; 39 for nonresidential."""
+
+    convention: str = "half_year"
+    """half_year | mid_quarter | mid_month"""
+
+    placed_in_service_month: int = 1
+    """Calendar month (1–12) property was placed in service. Required for mid_month / MQ quarter."""
+
+    placed_in_service_year: Optional[int] = None
+    """Optional calendar year for schedule labeling."""
+
+    quarter: Optional[int] = None
+    """1–4; if omitted and convention is mid_quarter, derived from placed_in_service_month."""
+
+    section_179: Decimal = Decimal("0")
+    """Section 179 expense deducted in year 1 (reduces depreciable basis)."""
+
+    bonus_percent: Decimal = Decimal("0")
+    """Special depreciation allowance % of remaining basis after §179 (0–100)."""
+
+    business_use_percent: Decimal = Decimal("100")
+    """Business/investment use percentage (0–100)."""
+
+    asset_class: Optional[str] = None
+    description: Optional[str] = None
+    label: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "cost", money(self.cost))
+        object.__setattr__(self, "section_179", money(self.section_179))
+        object.__setattr__(
+            self, "bonus_percent", Decimal(str(self.bonus_percent))
+        )
+        object.__setattr__(
+            self, "business_use_percent", Decimal(str(self.business_use_percent))
+        )
+
+
+@dataclass(frozen=True)
+class ScheduleLine:
+    """One recovery year of the depreciation schedule."""
+
+    recovery_year: int
+    calendar_year: Optional[int]
+    rate_percent: Decimal
+    depreciation: Decimal
+    cumulative_depreciation: Decimal
+    remaining_basis: Decimal
+    notes: str = ""
+
+
+@dataclass
+class DepreciationSchedule:
+    """Full MACRS schedule with audit metadata."""
+
+    asset: AssetInput
+    depreciable_basis: Decimal
+    section_179_deduction: Decimal
+    bonus_deduction: Decimal
+    macrs_basis: Decimal
+    convention: str
+    table_id: str
+    table_source: str
+    lines: List[ScheduleLine] = field(default_factory=list)
+    total_macrs_depreciation: Decimal = Decimal("0")
+    total_first_year: Decimal = Decimal("0")
+    warnings: List[str] = field(default_factory=list)
+    reasons: List[str] = field(default_factory=list)
+
+    def to_rows(self) -> List[dict]:
+        rows = []
+        for line in self.lines:
+            rows.append(
+                {
+                    "recovery_year": line.recovery_year,
+                    "calendar_year": line.calendar_year,
+                    "rate_percent": str(line.rate_percent),
+                    "depreciation": str(line.depreciation),
+                    "cumulative_depreciation": str(line.cumulative_depreciation),
+                    "remaining_basis": str(line.remaining_basis),
+                    "notes": line.notes,
+                }
+            )
+        return rows