python-taxes 0.1.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_taxes/__init__.py

@@ -0,0 +1,7 @@
+from decimal import Decimal
+
+from pydantic import Field
+
+CURRENT_TAX_YEAR = 2024
+
+currency_field = Field(ge=Decimal("0.01"), decimal_places=2)

python_taxes/federal/__init__.py

@@ -0,0 +1,19 @@
+from decimal import ROUND_HALF_UP, Decimal, getcontext
+
+getcontext().rounding = ROUND_HALF_UP
+
+ROUNDED = Decimal("1.")
+
+NOT_ROUNDED = Decimal("0.01")
+
+rounding = {
+    True: ROUNDED,
+    False: NOT_ROUNDED,
+}
+
+
+# AfterValidator for tax_year
+def is_valid_tax_year(value: int) -> int:
+    if value in [2023, 2024, 2025]:
+        return value
+    raise ValueError("Invalid tax year. Valid tax years are 2023, 2024, and 2025.")

python_taxes/federal/income/__init__.py

@@ -0,0 +1,4 @@
+from .payroll.automated import (
+    employer_withholding,
+    employer_withholding_pre_2020,
+)

python_taxes/federal/income/payroll/automated.py

@@ -0,0 +1,174 @@
+from decimal import Decimal
+from typing import Annotated, Literal
+
+from pydantic import StrictBool, validate_call
+
+from python_taxes import CURRENT_TAX_YEAR, currency_field
+from python_taxes.federal import rounding
+
+from ..tables.percentage.automated import hoh, married, single
+
+PAY_FREQUENCY = {
+    "semiannual": 2,
+    "quarterly": 4,
+    "monthly": 12,
+    "semimonthly": 24,
+    "biweekly": 26,
+    "weekly": 52,
+    "daily": 260,
+}
+
+
+@validate_call
+def employer_withholding(
+    taxable_wages: Annotated[Decimal, currency_field],
+    pay_frequency: Literal[
+        "semiannual",
+        "quarterly",
+        "monthly",
+        "semimonthly",
+        "biweekly",
+        "weekly",
+        "daily",
+    ] = "biweekly",
+    filing_status: Literal["single", "married", "separate", "hoh"] = "single",
+    multiple_jobs: StrictBool = False,
+    tax_credits: Annotated[Decimal, currency_field] = Decimal("0.00"),
+    other_income: Annotated[Decimal, currency_field] = Decimal("0.00"),
+    deductions: Annotated[Decimal, currency_field] = Decimal("0.00"),
+    extra_withholding: Annotated[Decimal, currency_field] = Decimal("0.00"),
+    tax_year: int = CURRENT_TAX_YEAR,
+    rounded: StrictBool = False,
+) -> Decimal:
+    """Calculate income tax withholding.
+
+    Formula used if Form W-4 is 2020 or later.
+    If W-4 is 2019 or earlier, use employer_withholding_pre_2020 instead.
+
+    Parameters:
+    taxable_wages -- Wages earned this year
+    pay_frequency -- Number of pay periods per year (default 'biweekly')
+    filing_status -- Filing status (default 'single')
+    multiple_jobs -- Indicates if box in Step 2 on W-4 is checked (default False)
+    tax_credits -- Dependant claims and other credits from Step 3 (default 0)
+    other_income -- Income not from jobs - Step 4 (default 0)
+    deductions -- If claiming deductions other than standard - Step 4 (default 0)
+    extra_withholding -- Extra amount to withhold each pay period - Step 4 (default 0)
+    tax_year -- Year for which you are filing (default CURRENT_TAX_YEAR)
+    rounded -- Round to nearest whole dollar amount (default False)
+    """
+
+    # Steps 1a-1i
+    match filing_status:
+        case "single" | "separate" if multiple_jobs:
+            withholding_schedule = single.multiple_jobs
+        case "single" | "separate":
+            withholding_schedule = single.standard_schedule
+            deductions = deductions + Decimal("8600.00")
+        case "married" if multiple_jobs:
+            withholding_schedule = married.multiple_jobs
+        case "married":
+            withholding_schedule = married.standard_schedule
+            deductions = deductions + Decimal("12900.00")
+        case "hoh" if multiple_jobs:
+            withholding_schedule = hoh.multiple_jobs
+        case "hoh":
+            withholding_schedule = hoh.standard_schedule
+            deductions = deductions + Decimal("8600.00")
+
+    pay_freq = PAY_FREQUENCY[pay_frequency]
+
+    adjusted_wage = ((taxable_wages * pay_freq) + other_income) - deductions
+
+    # Step 2
+    for row in withholding_schedule[tax_year]:
+        if adjusted_wage >= row.min and adjusted_wage < row.max:
+            withholding_rate = row
+            break
+
+    tax_withholding = (adjusted_wage - withholding_rate.min) * Decimal(
+        withholding_rate.percent / 100
+    ) + withholding_rate.withhold_amount
+
+    withheld_this_period = tax_withholding / pay_freq
+
+    # Step 3
+    if tax_credits:
+        withheld_this_period = withheld_this_period - (tax_credits / pay_freq)
+
+    # Step 4
+    if extra_withholding:
+        withheld_this_period = withheld_this_period + extra_withholding
+
+    return (
+        Decimal(withheld_this_period).quantize(rounding[rounded])
+        if withheld_this_period > 0
+        else Decimal("0.00")
+    )
+
+
+@validate_call
+def employer_withholding_pre_2020(
+    taxable_wages: Annotated[Decimal, currency_field],
+    pay_frequency: Literal[
+        "semiannual",
+        "quarterly",
+        "monthly",
+        "semimonthly",
+        "biweekly",
+        "weekly",
+        "daily",
+    ] = "biweekly",
+    marital_status: Literal["single", "married", "separate"] = "single",
+    allowances_claimed: int = 0,
+    extra_withholding: Annotated[Decimal, currency_field] = Decimal("0.00"),
+    tax_year: int = CURRENT_TAX_YEAR,
+    rounded: StrictBool = False,
+) -> Decimal:
+    """Calculate income tax withholding - only if Form W-4 is 2019 or earlier.
+
+    Parameters:
+    taxable_wages -- Wages earned this year
+    pay_frequency -- Number of pay periods per year (default 'biweekly')
+    marital_status -- Marital status (default 'single')
+    allowances_claimed -- Number of allowances claimed - Step 5 (default 0)
+    extra_withholding -- Extra amount to withhold each pay period - Step 6 (default 0)
+    tax_year -- Year for which you are filing (default CURRENT_TAX_YEAR)
+    rounded -- Round to nearest whole dollar amount (default False)
+    """
+
+    # Steps 1a-1c and 1j-1l
+    match marital_status:
+        case "single" | "separate":
+            withholding_schedule = single.standard_schedule
+        case "married":
+            withholding_schedule = married.standard_schedule
+
+    pay_freq = PAY_FREQUENCY[pay_frequency]
+
+    allowances = allowances_claimed * Decimal("4300.00")
+
+    adjusted_wage = (taxable_wages * pay_freq) - allowances
+
+    # Step 2
+    for row in withholding_schedule[tax_year]:
+        if adjusted_wage >= row.min and adjusted_wage < row.max:
+            withholding_rate = row
+            break
+
+    tax_withholding = (adjusted_wage - withholding_rate.min) * Decimal(
+        withholding_rate.percent / 100
+    ) + withholding_rate.withhold_amount
+
+    withheld_this_period = tax_withholding / pay_freq
+
+    # Step 3 skipped if W4 is from 2019 or earlier
+    # Step 4
+    if extra_withholding:
+        withheld_this_period = withheld_this_period + extra_withholding
+
+    return (
+        Decimal(withheld_this_period).quantize(rounding[rounded])
+        if withheld_this_period > 0
+        else Decimal("0.00")
+    )

python_taxes/federal/income/tables/percentage/__init__.py

@@ -0,0 +1,15 @@
+from decimal import Decimal
+from typing import NamedTuple
+
+from pydantic import Field, PositiveInt
+
+MAX = Decimal("999999999999.99")
+
+
+class RateRow(NamedTuple):
+    """Tax withholding rate schedule."""
+
+    min: Decimal = Field(ge=Decimal("0.00"), le=MAX, decimal_places=2)
+    max: Decimal = Field(ge=Decimal("0.00"), le=MAX, decimal_places=2)
+    withhold_amount: Decimal = Field(ge=Decimal("0.00"), le=MAX, decimal_places=2)
+    percent: PositiveInt = Field(le=100)

python_taxes/federal/income/tables/percentage/automated/hoh.py

@@ -0,0 +1,309 @@
+from decimal import Decimal
+
+from .. import MAX, RateRow
+
+standard_schedule = {
+    2023: [
+        RateRow(
+            min=Decimal("0.00"),
+            max=Decimal("12199.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=0,
+        ),
+        RateRow(
+            min=Decimal("12200.00"),
+            max=Decimal("27899.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=10,
+        ),
+        RateRow(
+            min=Decimal("27900.00"),
+            max=Decimal("72049.99"),
+            withhold_amount=Decimal("1570.00"),
+            percent=12,
+        ),
+        RateRow(
+            min=Decimal("72050.00"),
+            max=Decimal("107549.99"),
+            withhold_amount=Decimal("6868.00"),
+            percent=22,
+        ),
+        RateRow(
+            min=Decimal("107550.00"),
+            max=Decimal("194299.99"),
+            withhold_amount=Decimal("14678.00"),
+            percent=24,
+        ),
+        RateRow(
+            min=Decimal("194300.00"),
+            max=Decimal("243449.99"),
+            withhold_amount=Decimal("35498.00"),
+            percent=32,
+        ),
+        RateRow(
+            min=Decimal("243450.00"),
+            max=Decimal("590299.99"),
+            withhold_amount=Decimal("51226.00"),
+            percent=35,
+        ),
+        RateRow(
+            min=Decimal("590300.00"),
+            max=MAX,
+            withhold_amount=Decimal("172623.50"),
+            percent=37,
+        ),
+    ],
+    2024: [
+        RateRow(
+            min=Decimal("0.00"),
+            max=Decimal("13299.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=0,
+        ),
+        RateRow(
+            min=Decimal("13300.00"),
+            max=Decimal("29849.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=10,
+        ),
+        RateRow(
+            min=Decimal("29850.00"),
+            max=Decimal("76399.99"),
+            withhold_amount=Decimal("1655.00"),
+            percent=12,
+        ),
+        RateRow(
+            min=Decimal("76400.00"),
+            max=Decimal("113799.99"),
+            withhold_amount=Decimal("7241.00"),
+            percent=22,
+        ),
+        RateRow(
+            min=Decimal("113800.00"),
+            max=Decimal("205249.99"),
+            withhold_amount=Decimal("15469.00"),
+            percent=24,
+        ),
+        RateRow(
+            min=Decimal("205250.00"),
+            max=Decimal("256999.99"),
+            withhold_amount=Decimal("37417.00"),
+            percent=32,
+        ),
+        RateRow(
+            min=Decimal("257000.00"),
+            max=Decimal("622649.99"),
+            withhold_amount=Decimal("53977.00"),
+            percent=35,
+        ),
+        RateRow(
+            min=Decimal("622650.00"),
+            max=MAX,
+            withhold_amount=Decimal("181954.50"),
+            percent=37,
+        ),
+    ],
+    2025: [
+        RateRow(
+            min=Decimal("0.00"),
+            max=Decimal("13899.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=0,
+        ),
+        RateRow(
+            min=Decimal("13900.00"),
+            max=Decimal("30899.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=10,
+        ),
+        RateRow(
+            min=Decimal("30900.00"),
+            max=Decimal("78749.99"),
+            withhold_amount=Decimal("1700.00"),
+            percent=12,
+        ),
+        RateRow(
+            min=Decimal("78750.00"),
+            max=Decimal("117249.99"),
+            withhold_amount=Decimal("7442.00"),
+            percent=22,
+        ),
+        RateRow(
+            min=Decimal("117250.00"),
+            max=Decimal("211199.99"),
+            withhold_amount=Decimal("15912.00"),
+            percent=24,
+        ),
+        RateRow(
+            min=Decimal("211200.00"),
+            max=Decimal("264399.99"),
+            withhold_amount=Decimal("38460.00"),
+            percent=32,
+        ),
+        RateRow(
+            min=Decimal("264400.00"),
+            max=Decimal("640249.99"),
+            withhold_amount=Decimal("55484.00"),
+            percent=35,
+        ),
+        RateRow(
+            min=Decimal("640250.00"),
+            max=MAX,
+            withhold_amount=Decimal("187031.50"),
+            percent=37,
+        ),
+    ],
+}
+
+multiple_jobs = {
+    2023: [
+        RateRow(
+            min=Decimal("0.00"),
+            max=Decimal("10399.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=0,
+        ),
+        RateRow(
+            min=Decimal("10400.00"),
+            max=Decimal("18249.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=10,
+        ),
+        RateRow(
+            min=Decimal("18250.00"),
+            max=Decimal("40324.99"),
+            withhold_amount=Decimal("785.00"),
+            percent=12,
+        ),
+        RateRow(
+            min=Decimal("40325.00"),
+            max=Decimal("58074.99"),
+            withhold_amount=Decimal("3434.00"),
+            percent=22,
+        ),
+        RateRow(
+            min=Decimal("58075.00"),
+            max=Decimal("101449.99"),
+            withhold_amount=Decimal("7339.00"),
+            percent=24,
+        ),
+        RateRow(
+            min=Decimal("101450.00"),
+            max=Decimal("126024.99"),
+            withhold_amount=Decimal("17749.00"),
+            percent=32,
+        ),
+        RateRow(
+            min=Decimal("126025.00"),
+            max=Decimal("299449.99"),
+            withhold_amount=Decimal("25613.00"),
+            percent=35,
+        ),
+        RateRow(
+            min=Decimal("299450.00"),
+            max=MAX,
+            withhold_amount=Decimal("86311.75"),
+            percent=37,
+        ),
+    ],
+    2024: [
+        RateRow(
+            min=Decimal("0.00"),
+            max=Decimal("10949.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=0,
+        ),
+        RateRow(
+            min=Decimal("10950.00"),
+            max=Decimal("19224.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=10,
+        ),
+        RateRow(
+            min=Decimal("19225.00"),
+            max=Decimal("42499.99"),
+            withhold_amount=Decimal("827.50"),
+            percent=12,
+        ),
+        RateRow(
+            min=Decimal("42500.00"),
+            max=Decimal("61199.99"),
+            withhold_amount=Decimal("3620.50"),
+            percent=22,
+        ),
+        RateRow(
+            min=Decimal("61200.00"),
+            max=Decimal("106924.99"),
+            withhold_amount=Decimal("7734.50"),
+            percent=24,
+        ),
+        RateRow(
+            min=Decimal("106925.00"),
+            max=Decimal("132799.99"),
+            withhold_amount=Decimal("18708.50"),
+            percent=32,
+        ),
+        RateRow(
+            min=Decimal("132800.00"),
+            max=Decimal("315624.99"),
+            withhold_amount=Decimal("26988.50"),
+            percent=35,
+        ),
+        RateRow(
+            min=Decimal("315625.00"),
+            max=MAX,
+            withhold_amount=Decimal("90977.25"),
+            percent=37,
+        ),
+    ],
+    2025: [
+        RateRow(
+            min=Decimal("0.00"),
+            max=Decimal("11249.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=0,
+        ),
+        RateRow(
+            min=Decimal("11250.00"),
+            max=Decimal("19749.99"),
+            withhold_amount=Decimal("0.00"),
+            percent=10,
+        ),
+        RateRow(
+            min=Decimal("19750.00"),
+            max=Decimal("43674.99"),
+            withhold_amount=Decimal("850.00"),
+            percent=12,
+        ),
+        RateRow(
+            min=Decimal("43675.00"),
+            max=Decimal("62924.99"),
+            withhold_amount=Decimal("3721.00"),
+            percent=22,
+        ),
+        RateRow(
+            min=Decimal("62925.00"),
+            max=Decimal("109899.99"),
+            withhold_amount=Decimal("7956.00"),
+            percent=24,
+        ),
+        RateRow(
+            min=Decimal("109900.00"),
+            max=Decimal("136499.99"),
+            withhold_amount=Decimal("19230.00"),
+            percent=32,
+        ),
+        RateRow(
+            min=Decimal("136500.00"),
+            max=Decimal("324424.99"),
+            withhold_amount=Decimal("27742.00"),
+            percent=35,
+        ),
+        RateRow(
+            min=Decimal("324425.00"),
+            max=MAX,
+            withhold_amount=Decimal("93515.75"),
+            percent=37,
+        ),
+    ],
+}