python-taxes 0.4.0__py3-none-any.whl → 0.6.0a3__py3-none-any.whl

python_taxes/__init__.py

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

python_taxes/__main__.py

@@ -0,0 +1,4 @@
+if __name__ == "__main__":
+    from python_taxes.cli import app
+
+    app()

python_taxes/cli.py

@@ -0,0 +1,147 @@
+import sys
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated
+
+from pydantic import StrictBool, validate_call
+
+from python_taxes import CURRENT_TAX_YEAR, currency_field
+from python_taxes.federal.income import employer_withholding as income_withholding
+from python_taxes.federal.medicare import required_withholding as med_withholding
+from python_taxes.federal.social_security import withholding as ss_withholding
+
+try:
+    import typer
+except ImportError:  # pragma: no cover
+    print("Error: typer not found. Command-line (cli) not available.")
+    sys.exit(1)
+
+app = typer.Typer()
+
+
+class PayFrequency(str, Enum):
+    semiannual = "semiannual"
+    quarterly = "quarterly"
+    monthly = "monthly"
+    semimonthly = "semimonthly"
+    biweekly = "biweekly"
+    weekly = "weekly"
+    daily = "daily"
+
+
+class FilingStatus(str, Enum):
+    single = "single"
+    married = "married"
+    separate = "separate"
+    hoh = "hoh"
+
+
+@validate_call
+def currency(value: Annotated[Decimal, currency_field]) -> Decimal:
+    return value
+
+
+@app.callback()
+def callback():
+    """
+    Calculate federal income related taxes with python-taxes CLI app: pytax
+    """
+
+
+@app.command()
+def med(
+    wages: Annotated[
+        Decimal, typer.Argument(parser=currency, help="Taxable wages this period")
+    ],
+    ytd: Annotated[
+        Decimal,
+        typer.Option(
+            parser=currency,
+            help="Total taxable wages paid year-to-date",
+        ),
+    ] = Decimal("0.00"),
+    selfemp: Annotated[
+        StrictBool,
+        typer.Option(help="Whether to calculate as self-employed"),
+    ] = False,
+    round: Annotated[
+        StrictBool,
+        typer.Option(help="Whether to round the final value"),
+    ] = False,
+):
+    value = med_withholding(wages, ytd, selfemp, round)
+    print(value)
+
+
+@app.command()
+def ss(
+    wages: Annotated[
+        Decimal,
+        typer.Argument(parser=currency, help="Taxable wages this period"),
+    ],
+    ytd: Annotated[
+        Decimal,
+        typer.Option(parser=currency, help="Total taxable wages paid year-to-date"),
+    ] = Decimal("0.00"),
+    selfemp: Annotated[
+        StrictBool,
+        typer.Option(help="Whether to calculate as self-employed"),
+    ] = False,
+    year: Annotated[int, typer.Option(help="Enter the tax year")] = CURRENT_TAX_YEAR,
+    round: Annotated[
+        StrictBool,
+        typer.Option(help="Whether to round the final value"),
+    ] = False,
+):
+    value = ss_withholding(wages, ytd, selfemp, year, round)
+    print(value)
+
+
+@app.command()
+def income(
+    wages: Annotated[
+        Decimal,
+        typer.Argument(parser=currency, help="Taxable wages this period"),
+    ],
+    freq: Annotated[
+        PayFrequency, typer.Option(help="Pay frequency", case_sensitive=False)
+    ] = PayFrequency.biweekly,
+    status: Annotated[
+        FilingStatus, typer.Option(help="Filing status", case_sensitive=False)
+    ] = FilingStatus.single,
+    mjobs: Annotated[
+        StrictBool,
+        typer.Option(help="Multiple jobs: Select True if box in Step 2 on W-4 checked"),
+    ] = False,
+    credits: Annotated[
+        Decimal,
+        typer.Option(
+            parser=currency, help="Amount to claim for dependents and credits"
+        ),
+    ] = Decimal("0.00"),
+    other: Annotated[
+        Decimal,
+        typer.Option(parser=currency, help="Income not from jobs"),
+    ] = Decimal("0.00"),
+    deduct: Annotated[
+        Decimal,
+        typer.Option(parser=currency, help="Deductions other than standard"),
+    ] = Decimal("0.00"),
+    extra: Annotated[
+        Decimal,
+        typer.Option(parser=currency, help="Extra to withhold each period"),
+    ] = Decimal("0.00"),
+    year: Annotated[int, typer.Option(help="Enter the tax year")] = CURRENT_TAX_YEAR,
+    round: Annotated[
+        StrictBool,
+        typer.Option(help="Whether to round the final value"),
+    ] = False,
+):
+    value = income_withholding(
+        wages, freq, status, mjobs, credits, other, deduct, extra, year, round
+    )
+    print(value)
+
+
+if __name__ == "__main__":
+    app()  # pragma: no cover

python_taxes/federal/__init__.py

@@ -1,19 +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.")
+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

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

python_taxes/federal/income/payroll/automated.py

@@ -1,174 +1,184 @@
-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")
-    )
+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: Annotated[
+        str,
+        Literal[
+            "semiannual",
+            "quarterly",
+            "monthly",
+            "semimonthly",
+            "biweekly",
+            "weekly",
+            "daily",
+        ],
+    ] = "biweekly",
+    filing_status: Annotated[
+        str, 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
+    if adjusted_wage < 0:
+        withholding_rate = withholding_schedule[tax_year][0]
+    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: Annotated[
+        str,
+        Literal[
+            "semiannual",
+            "quarterly",
+            "monthly",
+            "semimonthly",
+            "biweekly",
+            "weekly",
+            "daily",
+        ],
+    ] = "biweekly",
+    marital_status: Annotated[str, 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

@@ -1,15 +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)
+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)