Library to compute US federal taxes, and state taxes for some states.
Project description
tenforty
Overview
tenforty
is an open-source Python package designed to help demystify US
federal and state tax computations. This project offers an accessible way to
explore tax scenarios, compare different tax situations, and understand the
impact of various factors on tax liabilities. It's particularly useful for those
who would like to understand or optimize their taxes by evaluating how tax form
inputs affect their outputs.
The package is built on top of the Open Tax Solver project, wrapping its functionality into a Python library.
Features
- Compute US federal taxes, as well as taxes for several US states.
- Explore how taxes vary as a function of income, state, filing status, and year.
- Easily integrate with data analysis and visualization tools in Python with
pandas
support. - Evaluate "what if" tax scenarios efficiently and reproducibly.
Disclaimer
tenforty
is an open-source tool intended for informational and educational
purposes only and does not provide tax advice.
Known limitations of this package are detailed in the Limitations section below.
Installation
pip install tenforty
Main Functions Documentation
The two functions evaluate_return
and evaluate_returns
are the main
interface to tenforty
. They take exactly the same arguments, except that any
of the arguments to evaluate_returns
may either be a single value, or a list
of values. evaluate_return
is for evaluating one single return, and
evaluate_returns
evaluates all combinations of inputs subtended by the
provided values and collects the results into a dataframe.
The inputs to either function are "guarded" by a pydantic model, so you'll get an informative message about why your input was invalid if it was, along with a list of the valid options. (And if you're using a modern editor, you'll get nice autocomplete on the valid options.)
Here are all arguments available for those two functions:
Argument | Type | Default | Notes |
---|---|---|---|
year |
int | 2022 | 2018-2022 inclusive |
state |
str | None | None | "CA", "NY", "MA" + "AK", "FL", "NV", "SD", "TX", "WA", "WY" |
filing_status |
str | Single | "Single", "Married/Joint", "Head_of_House", "Married/Sep", "Widow(er)" |
num_dependents |
int | 0 | |
standard_or_itemized |
str | Standard | "Standard" or "Itemized" |
w2_income |
float | 0.0 | |
taxable_interest |
float | 0.0 | |
qualified_dividends |
float | 0.0 | |
ordinary_dividends |
float | 0.0 | |
short_term_capital_gains |
float | 0.0 | |
long_term_capital_gains |
float | 0.0 | |
schedule_1_income |
float | 0.0 | |
itemized_deductions |
float | 0.0 | |
state_adjustment |
float | 0.0 | |
incentive_stock_option_gains |
float | 0.0 |
Several concrete examples of calling either function are given in the Examples section.
Examples
Here are some examples of what you can do with tenforty:
Basic Evaluation
The evaluate_return
function computes the outputs for a single tax return
given some inputs:
from tenforty import evaluate_return
evaluate_return(
w2_income=100_000, state="CA", filing_status="Married/Joint", num_dependents=2
).model_dump()
This results in the following:
{'total_tax': 10043.0,
'federal_adjusted_gross_income': 100000.0,
'federal_effective_tax_rate': 11.4,
'federal_tax_bracket': 12.0,
'federal_taxable_income': 74100.0,
'federal_amt': 0.0,
'federal_total_tax': 8484.0,
'state_adjusted_gross_income': 100000.0,
'state_taxable_income': 89596.0,
'state_total_tax': 1559.0,
'state_tax_bracket': 6.0,
'state_effective_tax_rate': 3.0}
No year=
argument was specified here, so the current tax year, 2022, was used.
The output is a pydantic model, and we've called its .model_dump()
method to
show the result as a dictionary.
Creating Tax Tables: Federal/State Tax Brackets as a Function of W2 Income
The evaluate_returns
method sweeps out a grid over any input arguments that
are provided as lists, allowing you to evaluate a wide array of tax scenarios.
Here we make a simple tax table by varying W2 income:
from tenforty import evaluate_returns
evaluate_returns(
w2_income=list(range(50_000, 250_001, 50_000)),
state="CA",
filing_status="Married/Joint",
num_dependents=2,
)[
[
"w2_income",
"federal_effective_tax_rate",
"federal_tax_bracket",
"state_effective_tax_rate",
"state_tax_bracket",
]
]
This results in a pandas.DataFrame
:
w2_income federal_effective_tax_rate federal_tax_bracket state_effective_tax_rate state_tax_bracket
0 50000 10.3 12.0 1.5 2.0
1 100000 11.4 12.0 3.0 6.0
2 150000 14.9 22.0 4.6 9.3
3 200000 17.0 22.0 5.9 9.3
4 250000 18.5 24.0 6.6 9.3
Plot: Federal Tax as a Function of W2 Income
Since the output is a dataframe, one can use their visualization tool of choice to make plots. Here we revisit the example above, evaluating a wider range of W2 incomes at finer resolution than before.
import seaborn.objects as so
df = evaluate_returns(w2_income=list(range(0, 250_001, 1_000)))
(
so.Plot(df, x="w2_income", y="total_tax")
.add(so.Line())
.label(
x="W2 Income", y="Federal Tax", title="Federal Tax as a Function of W2 Income"
)
)
Plot: Federal Tax Over Time
The good people at Open Tax Solver have published editions each year for 21
years, so one can just as easily vary the year as any other parameter. At the
moment tenforty
supports back to the 2018 tax year. Here we show the federal
tax on $100K of W2 income for the past five years.
df = evaluate_returns(
year=[2018, 2019, 2020, 2021, 2022], w2_income=100_000
).astype({"year": "category"})
(
so.Plot(df, x="year", y="total_tax")
.add(so.Line())
.add(so.Dot())
.label(
x="Year",
y="Federal Tax",
title="Federal Tax on $100K W2 Income Over Time",
)
)
This one's a little melodramatic because we don't make the y-axis go to zero; it's only about a 3% drop over the years.
Plot: Impact of Long-Term Capital Gains
Because Open Tax Solver supports short- and long-term capitals gains calculations -- although, see the Limitations section below -- you can ask questions about the impact on your taxes of selling some appreciated stock this year, and show the breakdown between state and federal taxes:
df = (
evaluate_returns(
w2_income=75_000,
state="CA",
long_term_capital_gains=list(range(0, 125_001, 5000)),
)
.loc[:, ["long_term_capital_gains", "state_total_tax", "federal_total_tax"]]
.melt("long_term_capital_gains", var_name="Type", value_name="tax")
.assign(
Type=lambda f: f.Type.map(
{"state_total_tax": "State", "federal_total_tax": "Federal"}
)
)
)
(
so.Plot(df, x="long_term_capital_gains", y="tax", color="Type").add(
so.Area(alpha=0.7), so.Stack()
)
.label(
x="Long-Term Capital Gains",
y="Total Tax",
title="Impact of LTCG on Total Tax for California Resident",
)
)
Plot: Will I Incur Alternative Minimum Tax (AMT)?
Employees at tech companies are commonly issued incentive stock options, the
exercise of which can put them in a (surprising!) situation where they need to
pay actual money in taxes on paper gains, via the alternative minimum tax. With
tenforty
's help you can see it coming at least: ;)
df = (
tenforty.evaluate_returns(
w2_income=100_000, incentive_stock_option_gains=list(range(0, 100_001, 2500))
)
.loc[:, ["incentive_stock_option_gains", "federal_total_tax", "federal_amt"]]
.melt("incentive_stock_option_gains", var_name="Type", value_name="tax")
.assign(
Type=lambda f: f.Type.map(
{"federal_amt": "AMT", "federal_total_tax": '"Regular" Tax'}
)
)
)
(
so.Plot(df, x="incentive_stock_option_gains", y="tax", color="Type")
.add(so.Area(alpha=0.7), so.Stack())
.label(
x="Incentive Stock Option Gains",
y="Total Federal Tax",
title="Effect of ISO Gains on Federal Alternative Minimum Tax\nGiven $100K W2 Income",
)
)
Known Limitations
- Medicare and Net Investment Income Tax are not automatically computed on capital gains, so if those apply to your situation the output tax will be underestimated.
- Although Open Tax Solver includes support for more,
tenforty
only supports California, Massachusetts and New York. (Technically it supports all the no-income-tax states like Texas and Nevada. :) ) Furthermore, only California has been tested against any tax returns prepared independently by professional tax software, so the Massachusetts and New York support is especially provisional.
Development & Contributing
If you're interested to learn more about how the package works, please see DEVELOP.md in this directory.
Contributions to tenforty
are welcome! If you have suggestions for
improvements or encounter any issues, please feel free to open an issue or
submit a pull request.
License
tenforty
is released under the MIT License.
Acknowledgments
This project relies on the Open Tax Solver project for the underlying tax computation logic.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for tenforty-2022.3-cp312-cp312-musllinux_1_1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 24c3d18b40c85af4a67777f6bf8c1ffa5d74ce0db39a99d8c45b64dfa923a6ba |
|
MD5 | 4782b9acbb29d7fe28c4fdf16dfa96a8 |
|
BLAKE2b-256 | baefccbb34c71258139a5d5d5b9db561a3152fdfff17a689b75d1ec916caba0e |
Hashes for tenforty-2022.3-cp312-cp312-musllinux_1_1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 509e4d9c38742af1b418b487834eb2ec0e4ad8552d07dd1b3f5e2f58901b6ee4 |
|
MD5 | dcb29c0bd405686879c5d99a50c99263 |
|
BLAKE2b-256 | 040d5e782dd47fef972ae45b773298280c92a730d4811baf5f9a8fa8e28ea337 |
Hashes for tenforty-2022.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 88a34d2135868e26ffbde3e2ea1fcfe6d29ac40e596bfe596b61244795839c85 |
|
MD5 | 6ac8245f78524d3486e21267d433cee7 |
|
BLAKE2b-256 | 233e8482ea09e870e9a8a47cecbd63c446c2c82328d321367954cca566773dd9 |
Hashes for tenforty-2022.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 86625cdd9026f907c125f05776adcd0fbcadda2e007fe51da5afa95a288990f1 |
|
MD5 | d329d8e3e8cc7f694b841b0381e5cbcc |
|
BLAKE2b-256 | d0e16351f799beacd6b27a009f279d976bd2cc34af6980d693398753072bb5e9 |
Hashes for tenforty-2022.3-cp312-cp312-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1aefb3b1385461368a64dea6453d4a21ae8264b0a8044a4c4ccd0d4957579594 |
|
MD5 | 88159346d1e340818257698f8367c520 |
|
BLAKE2b-256 | fc9bd25bf599b90a241fbe6d6beacae8fdac1e04d2b9a1b54037edf0a29c9610 |
Hashes for tenforty-2022.3-cp312-cp312-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 44d4deca314de9681a820438f5c9654071906ef32ce8dcbb0bcff61caf4a05dc |
|
MD5 | 61c568ee1803661ae541370b4ea33e04 |
|
BLAKE2b-256 | 5d51436815fbd9b9bd77cd239739243888c737aed4dc3dc13d0d5e870fd05b98 |
Hashes for tenforty-2022.3-cp311-cp311-musllinux_1_1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 533b49f5973f718546ea3d8d2871bfa61992fb372ccb5432002ace24925e7374 |
|
MD5 | c36c4c7fde9566433ea3f262ff8d401a |
|
BLAKE2b-256 | f2100b98dc91947bb2a211b2c68d6b3e0a2318730ddbdc52101832e1eea49a57 |
Hashes for tenforty-2022.3-cp311-cp311-musllinux_1_1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 225a6bd4932874c68e7febee50c5287371965c86497bd3ca757a35135ed8ad86 |
|
MD5 | 7da2eefbd09b8a301bb9400a16524e0c |
|
BLAKE2b-256 | d8191a983a07df89beb5d2ec7cd4985e280999ee571f75d4896ddcceb93cf23a |
Hashes for tenforty-2022.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 93f906ddbb6018b1b4025751399c1a4529a3094dd15cd70ca15842b254ba671e |
|
MD5 | ce21cb10358d86d2f7164e1d164e40be |
|
BLAKE2b-256 | 8469355168ecd84a90b28d93365afbd317692096d16339182406e14463ff116d |
Hashes for tenforty-2022.3-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 626d871770807ef2571b7dcfba2ed39a767c94559803a316a35b08d12bc240da |
|
MD5 | 000f03b61d4a327aa26a3a516400f459 |
|
BLAKE2b-256 | 976f15ea91883679f9241ee1aca6541ed278c69f5a4b39f15d6a6311ab910a2c |
Hashes for tenforty-2022.3-cp311-cp311-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b56dfc158adbe28cb6a7c733dcb02c90d562966478070ee119eff53f062dfde |
|
MD5 | 76fab661f07a1664bd1478b77e97ae41 |
|
BLAKE2b-256 | 64941884bcb3faf064560567b99edcffd236837ba47dab12d786ba5c38b88d47 |
Hashes for tenforty-2022.3-cp311-cp311-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c6ea6f77f1b65184867c631db810d7be0cd03cd59f4d14afcdda56007835e7c6 |
|
MD5 | 91d7c7c361db723665bf32e6cd308472 |
|
BLAKE2b-256 | 4d333d0bbb28ec220a0bd007d33ce9ccd7d821a04a671e6fd811925e3f0d53f3 |
Hashes for tenforty-2022.3-cp310-cp310-musllinux_1_1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4390cc5e216eb89ba3b8346e429760f8c7022e8379ab4483443b8b04fb70dceb |
|
MD5 | 54633df921d8f79fb8db392649a8f410 |
|
BLAKE2b-256 | 293abed170dbe556257faf7811a6296e1a8505dac4c9a6546f1d1a9d8cc88930 |
Hashes for tenforty-2022.3-cp310-cp310-musllinux_1_1_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3fb8ce0573b4bd4d41b56a12a93089796b0422478e8357c82b4e0904b43bb948 |
|
MD5 | 429f4c8e3f48b93a9ae4af2aa908dd1a |
|
BLAKE2b-256 | f25c9512de2e9e21b543f6e0acf704da56f11524c3833c1e76e733b14d711255 |
Hashes for tenforty-2022.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6ef555fbaa2d799596fab3d3e28086dc5b5e99756ef251515845c71dc2ac72e8 |
|
MD5 | f55abc16402f9370806d48d8167762cf |
|
BLAKE2b-256 | 86b85eaf035c013a40885b71c6583ed36db941af82bcfe230393c473f351d950 |
Hashes for tenforty-2022.3-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c339badd03de4648e896bdce56c10961b113362c36ce86899d684914d52b3e76 |
|
MD5 | 8845c8f4a8ac95813c311b12c4421389 |
|
BLAKE2b-256 | 8115f0789122fac335e682d4d56fec3fe2f43e58df86e7caee91f8de93496f07 |
Hashes for tenforty-2022.3-cp310-cp310-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b870f87f06b0152be7e7cd76102c98ff5d3e047518589a9c645d40c9d604435 |
|
MD5 | 7b996b3f32f7a7ac6fc1f3551ae72126 |
|
BLAKE2b-256 | 0e90cb15ef05e889422f935220a2f248eee0a7c39c05cb240e8492ecb7a7a02d |
Hashes for tenforty-2022.3-cp310-cp310-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4b7786e302284c55cdb221b6b64ea1e0223798ad9cf325808c5b1dd9fc87f699 |
|
MD5 | a07175f24ef0f4683be053d8e38270ff |
|
BLAKE2b-256 | b02e81241ee9ff74c1ced86554daca43bb87c23e02dcad2eb7f623c7338aa53e |