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

python_taxes/federal/social_security.py

@@ -0,0 +1,57 @@
+from decimal import Decimal
+from typing import Annotated
+
+from pydantic import AfterValidator, StrictBool, validate_call
+
+from python_taxes import CURRENT_TAX_YEAR, currency_field
+from python_taxes.federal import is_valid_tax_year, rounding
+
+STANDARD_TAX = Decimal("6.200") / 100
+
+SELF_EMPLOYED_TAX = Decimal("12.400") / 100
+
+wage_limit = {
+    2023: Decimal("160200"),
+    2024: Decimal("168600"),
+    2025: Decimal("176100"),
+}
+
+
+@validate_call
+def withholding(
+    taxable_wages: Annotated[Decimal, currency_field],
+    taxable_wages_ytd: Annotated[Decimal, currency_field] = Decimal("0.00"),
+    self_employed: StrictBool = False,
+    tax_year: Annotated[int, AfterValidator(is_valid_tax_year)] = CURRENT_TAX_YEAR,
+    rounded: StrictBool = False,
+) -> Decimal:
+    """
+    Social security tax withholding.
+
+    Parameters:
+    taxable_wages -- Wages earned this period
+    taxable_wages_ytd -- Wages earned this year
+    self_employed -- True if self-employed (default False)
+    tax_year -- Year for which you are filing (default CURRENT_TAX_YEAR)
+    rounded -- Round to nearest whole dollar amount (default False)
+    """
+
+    if self_employed:
+        tax_rate = SELF_EMPLOYED_TAX
+        taxable_wages = taxable_wages * (Decimal("92.35") / 100)
+        print("Taxable Wages: ", taxable_wages)
+        taxable_wages_ytd = taxable_wages_ytd * (Decimal("92.35") / 100)
+        print("Taxable Wages YTD: ", taxable_wages_ytd)
+    else:
+        tax_rate = STANDARD_TAX
+
+    limit = wage_limit[tax_year]
+
+    if taxable_wages_ytd > limit:
+        return Decimal("0.00")  # Tax is 0 because limit is reached
+
+    if (taxable_wages + taxable_wages_ytd) > limit:
+        over = (taxable_wages + taxable_wages_ytd) - limit
+        taxable_wages = taxable_wages - over
+
+    return (taxable_wages * tax_rate).quantize(rounding[rounded])

python_taxes-0.4.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stacy Noland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_taxes-0.4.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.3
+Name: python-taxes
+Version: 0.4.0
+Summary: A Python library for calculating US Social Security, Medicare, and Federal Income taxes.
+License: MIT License
+         
+         Copyright (c) 2025 Stacy Noland
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Author: Stacy Noland
+Author-email: 46572585+stacynoland@users.noreply.github.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: pydantic (>=2.11.3,<3.0.0)
+Project-URL: Homepage, https://github.com/stacynoland/python-taxes
+Project-URL: Source, https://github.com/stacynoland/python-taxes
+Description-Content-Type: text/markdown
+
+![Python Taxes Image](https://github.com/user-attachments/assets/6c62946b-e749-46bb-a84e-6321397f1753)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/python-taxes?logo=python&logoColor=yellow&label=Python)
+[![GitHub Release](https://img.shields.io/github/v/release/stacynoland/python-taxes?label=Current%20Release)](https://github.com/stacynoland/python-taxes/releases)
+![PyPI - Status](https://img.shields.io/pypi/status/python-taxes?label=Status)
+[![Tests](https://github.com/stacynoland/python-taxes/actions/workflows/test.yml/badge.svg)](https://github.com/stacynoland/python-taxes/actions/workflows/test.yml)
+![Coverage](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fstacynoland%2Fpython-taxes%2Frefs%2Fheads%2Fmain%2Fcoverage.json&query=%24.totals.percent_covered_display&suffix=%25&label=Coverage&color=3fb831)
+[![Poetry Package Manager](https://img.shields.io/endpoint?url=https%3A%2F%2Fpython-poetry.org%2Fbadge%2Fv0.json)](https://python-poetry.org/)
+[![Black](https://img.shields.io/badge/Code%20Style-black-000000)](https://github.com/psf/black)
+
+> Disclaimer: This library is not intended to be used for tax advice. Please consult a tax professional for any tax-related questions or concerns.
+
+Python-Taxes is a library designed to make calculating US Federal taxes easy.
+
+The library supports Social Security, Medicare, and Federal Income taxes for tax years 2023 to 2025. Please note, 2025 is only added for future tax season.
+
+`CURRENT_TAX_YEAR` is set to 2024.
+
+## Installation
+
+To install the library, you can use pip or another dependency manager like Poetry.
+
+`pip install python-taxes`
+
+or
+
+`poetry add python-taxes`
+
+## Usage
+
+### Social Security Tax
+
+To calculate Social Security tax, use the `social_security` module:
+
+```python
+from python_taxes.federal import social_security
+
+social_security.withholding(5000)  # Returns the amount withheld for Social Security tax
+
+social_security.withholding(
+                taxable_wages=3000,
+                taxable_wages_ytd=100000,
+                self_employed=False,
+                tax_year=2024,
+                rounded=True,
+            )
+```
+---
+### Medicare Tax
+
+To calculate Medicare tax, use the `medicare` module. There are two functions available:
+
+`medicare.required_withholding` - Returns the required amount to withhold for Medicare tax regardless of filing status.
+`medicare.additional_withholding` - Returns the amount that should be withheld based on filing status, including Additional Medicare tax.
+
+```python
+from python_taxes.federal import medicare
+
+medicare.required_withholding(5000)  # Returns the amount withheld for Medicare tax
+
+medicare.required_withholding(
+                taxable_wages=5000,
+                taxable_wages_ytd=100000,
+                self_employed=True,
+                rounded=True,
+            )
+
+medicare.additional_withholding(100000, "married")  # Returns the amount withheld for Medicare Tax and Additional Medicare tax, if applicable, based on filing status.
+
+medicare.additional_withholding(
+                taxable_wages_ytd=100000,
+                filing_status="married",
+                self_employed=False,
+                rounded=True,
+            )
+```
+---
+### Federal Income Tax
+
+To calculate Federal Income tax, use the `income` package. Currently, the only payroll withholding supported is for automated systems. Specifically, the percentage tables in IRS Publication 15-T section 1 (Percentage Method Tables for Automated Payroll Systems).
+
+```python
+from python_taxes.federal import income
+
+income.employer_withholding(10000)  # Returns the amount withheld for Federal Income tax
+
+income.employer_withholding(
+                taxable_wages=10000,
+                pay_frequency="monthly",
+                filing_status="married",
+                multiple_jobs=False,
+                tax_credits=0,
+                other_income=0,
+                deductions=0,
+                extra_withholding=0,
+                tax_year=2024,
+                rounded=True,
+            )
+
+income.employer_withholding_pre_2020(10000)  # Returns the amount withheld for Federal Income tax - using this method is required if Form W-4 is from 2019 or earlier.
+
+income.employer_withholding_pre_2020(
+                taxable_wages=10000,
+                pay_frequency="monthly",
+                marital_status="married",
+                allowances_claimed=0,
+                extra_withholding=0,
+                tax_year=2024,
+                rounded=False,
+            )
+```
+

python_taxes-0.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+python_taxes/__init__.py,sha256=Ik5XwXbg3MHgViKIDG3flx2bHK2rVjKZsKeaVmpzXdc,150
+python_taxes/federal/__init__.py,sha256=l5FP5RVNh29ce_y-N1SyNXeD7M7NAsEpV5Vs7qV66yU,443
+python_taxes/federal/income/__init__.py,sha256=w0--WOCcq1_y_XWpp4QhBDzEHr6A1cUP-L2UhQqZQOQ,100
+python_taxes/federal/income/payroll/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_taxes/federal/income/payroll/automated.py,sha256=m_WTb9t6o20O4xKs06CwaOK377vRQmuagJLO8IVmaaE,6185
+python_taxes/federal/income/tables/percentage/__init__.py,sha256=mNIpA4IU-sELTiI6aNdhVkiLGpV9GLgMzR6opZ-0wBc,485
+python_taxes/federal/income/tables/percentage/automated/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_taxes/federal/income/tables/percentage/automated/hoh.py,sha256=Jcs5fV66KBHD4nvD_ZBT-DMc4r0gcateNZf6b0nz2GM,8779
+python_taxes/federal/income/tables/percentage/automated/married.py,sha256=BG6bRObCEnggZD5MvFQMQK7_ydq7J6_v1CP9c7QUbEU,8799
+python_taxes/federal/income/tables/percentage/automated/single.py,sha256=DyZXPLnY3XQxMxCSLRdUR1oZuxAg7qpdHKCk1g0zt64,8765
+python_taxes/federal/medicare.py,sha256=_xspuO9cWr6X5gLCgxS3IMQFWOid1PCrFTo-kmxoqmQ,2882
+python_taxes/federal/social_security.py,sha256=ZTDY0hY7EK7S1ES8G6Ax7itRSD5kaPJdxRB0SJrpWaw,1892
+python_taxes-0.4.0.dist-info/LICENSE,sha256=qXDZCZ5wi5heCp0R_uncT3yCAHireFaSFQjphGDMFU0,1090
+python_taxes-0.4.0.dist-info/METADATA,sha256=oMHrlEhC-a42CK3MVCzdfYMC_qX8CnJ_3uPJSWWV0j8,7034
+python_taxes-0.4.0.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+python_taxes-0.4.0.dist-info/RECORD,,

{python_taxes-0.1.0.dist-info → python_taxes-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.1
+Generator: poetry-core 2.1.2
 Root-Is-Purelib: true
 Tag: py3-none-any

python_taxes/federal/calculators/__init__.py

@@ -1,13 +0,0 @@
-from decimal import Decimal, getcontext, ROUND_HALF_UP
-
-
-getcontext().rounding = ROUND_HALF_UP
-
-ROUNDED = Decimal('1.')
-
-NOT_ROUNDED = Decimal('0.01')
-
-rounding = {
-    True: ROUNDED,
-    False: NOT_ROUNDED,
-}

python_taxes/federal/calculators/medicare.py

@@ -1,88 +0,0 @@
-from decimal import Decimal
-from typing import Annotated, Literal, Optional
-
-from pydantic import Field, StrictBool, validate_call
-
-from . import rounding
-
-
-STANDARD_PERCENT = Decimal("1.45") / 100
-
-SELF_EMPLOYED_PERCENT = Decimal("2.9") / 100
-
-ADDITIONAL_PERCENT = Decimal("0.9") / 100
-
-DEFAULT_THRESHOLD = Decimal("200000")
-
-status_threshold = {
-    'single': DEFAULT_THRESHOLD,
-    'married': Decimal("250000"),
-    'separate': Decimal("125000"),
-    'hoh': DEFAULT_THRESHOLD,
-}
-
-
-@validate_call
-def withholding(
-    taxable_wages: Annotated[Decimal, Field(ge=Decimal("0.01"), decimal_places=2)],
-    taxable_wages_ytd: Optional[
-        Annotated[Decimal, Field(ge=Decimal("0.01"), decimal_places=2)]] = None,
-    self_employed: StrictBool = False,
-    rounded: StrictBool = False,
-) -> Decimal:
-    """Required amount to withhold regardless of filing status
-
-    Parameters:
-    taxable_wages -- Earned this period
-    taxable_wages_ytd -- Earned this year
-    self_employed -- Person/employee is self-employed (default False)
-    round -- Round response to nearest whole dollar amount (default False)
-    """
-
-    if not taxable_wages_ytd:
-        taxable_wages_ytd = 0
-
-    if self_employed:
-        tax_rate = SELF_EMPLOYED_PERCENT
-    else:
-        tax_rate = STANDARD_PERCENT
-
-    if (taxable_wages > DEFAULT_THRESHOLD
-            or (taxable_wages_ytd + taxable_wages) > DEFAULT_THRESHOLD):
-        tax_rate = tax_rate + ADDITIONAL_PERCENT
-
-    return (taxable_wages * tax_rate).quantize(rounding[rounded])
-
-
-@validate_call
-def additional_withholding(
-    taxable_wages_ytd: Annotated[Decimal, Field(ge=Decimal("0.01"), decimal_places=2)],
-    self_employed: StrictBool = False,
-    status: Optional[Literal['single', 'married', 'separate' 'hoh']] = 'single',
-    rounded: StrictBool = False,
-) -> Decimal:
-    """Additional withholding based on status
-
-    Parameters:
-    taxable_wages_ytd -- Earned this year
-    self_employed -- Person/employee is self-employed (default False)
-    status -- Filing status of person (default 'single')
-    round -- Round response to nearest whole dollar amount (default False)
-    """
-
-    if self_employed:
-        tax_rate = SELF_EMPLOYED_PERCENT
-    else:
-        tax_rate = STANDARD_PERCENT
-
-    threshold = status_threshold[status]
-
-    if taxable_wages_ytd > threshold:
-        wages_over_threshold = taxable_wages_ytd - threshold
-        med_taxes = (taxable_wages_ytd - wages_over_threshold) * tax_rate
-        tax_rate = tax_rate + ADDITIONAL_PERCENT
-        med_taxes = med_taxes + (wages_over_threshold * tax_rate)
-    else:
-        med_taxes = taxable_wages_ytd * tax_rate
-
-    return med_taxes.quantize(rounding[rounded])

python_taxes/federal/calculators/social_security.py

@@ -1,32 +0,0 @@
-from decimal import Decimal
-from typing import Annotated, Literal, Optional
-
-from pydantic import Field, StrictBool, validate_call
-
-from . import rounding
-
-STANDARD_TAX = Decimal('6.200') / 100
-
-SELF_EMPLOYED_TAX = Decimal('12.400') / 100
-
-
-@validate_call
-def withholding(
-    taxable_wages: Annotated[Decimal, Field(ge=0.01, decimal_places=2)],
-    self_employed: StrictBool = False,
-    rounded: StrictBool = False,
-) -> Decimal:
-    """Social security tax withholding.
-
-    Parameters:
-    taxable_wages -- Total wages to be taxed
-    self_employed -- Person/employee is self-employed (default False)
-    round -- Round response to nearest whole dollar amount (default False)
-    """
-
-    if self_employed:
-        tax_rate = SELF_EMPLOYED_TAX
-    else:
-        tax_rate = STANDARD_TAX
-
-    return (taxable_wages * tax_rate).quantize(rounding[rounded])

python_taxes-0.1.0.dist-info/METADATA

@@ -1,13 +0,0 @@
-Metadata-Version: 2.3
-Name: python-taxes
-Version: 0.1.0
-Summary: Development in progress - please come back later.
-Author: Stacy Noland
-Author-email: 46572585+stacynoland@users.noreply.github.com
-Requires-Python: >=3.13
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: pydantic (>=2.10.6,<3.0.0)
-Description-Content-Type: text/markdown
-
-

python_taxes-0.1.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-python_taxes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-python_taxes/federal/calculators/__init__.py,sha256=xSbDWGm84eO2TBwOZl_01L5pOyUhuEsO_nyZ-fTNTAw,223
-python_taxes/federal/calculators/medicare.py,sha256=pugSzvgyg9EDUvO0OgsQj72H4rgRMQu0Iy0OmtdOiPU,2771
-python_taxes/federal/calculators/social_security.py,sha256=5tMhu0V0TWzICLb3K4Y4HDT0uQnkggqEAtGCP5QNFq8,888
-python_taxes-0.1.0.dist-info/METADATA,sha256=w7cia8WMXGQvu0cEefMUJSmrQO5i8RXbarKMM3897HY,403
-python_taxes-0.1.0.dist-info/WHEEL,sha256=XbeZDeTWKc1w7CSIyre5aMDU_-PohRwTQceYnisIYYY,88
-python_taxes-0.1.0.dist-info/RECORD,,