Package: tenforty
tenfortyOverviewtenfortyis 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 theOpen Tax Solverproject, wrapping its
functionality into a Python library.FeaturesCompute 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 withpandassupport.Evaluate "what if" tax scenarios efficiently and reproducibly.Disclaimertenfortyis 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 theLimitationssection below.InstallationpipinstalltenfortyMain Functions DocumentationThe two functionsevaluate_returnandevaluate_returnsare the main
interface totenforty. They take exactly the same arguments, except that any
of the arguments toevaluate_returnsmay either be a single value, or a list
of values.evaluate_returnis for evaluating one single return, andevaluate_returnsevaluates all combinations of inputs subtended by the
provided values and collects the results into a dataframe.The inputs to either function are validated, and if for example a filing status
is misspelled, you'll get an informative error message along with a list of the
valid options.Here are all arguments available for those two functions:ArgumentTypeDefaultNotesyearint20232018-2023 inclusivestatestr | NoneNone"CA", "NY", "MA" + "AK", "FL", "NV", "SD", "TX", "WA", "WY"filing_statusstrSingle"Single", "Married/Joint", "Head_of_House", "Married/Sep", "Widow(er)"num_dependentsint0standard_or_itemizedstrStandard"Standard" or "Itemized"w2_incomefloat0.0taxable_interestfloat0.0qualified_dividendsfloat0.0ordinary_dividendsfloat0.0short_term_capital_gainsfloat0.0long_term_capital_gainsfloat0.0schedule_1_incomefloat0.0itemized_deductionsfloat0.0state_adjustmentfloat0.0incentive_stock_option_gainsfloat0.0The functions output these fields:Output Fieldtotal_taxfederal_adjusted_gross_incomefederal_effective_tax_ratefederal_tax_bracketfederal_taxable_incomefederal_amtfederal_total_taxstate_adjusted_gross_incomestate_taxable_incomestate_total_taxstate_tax_bracketstate_effective_tax_rateExamplesHere are some examples of what you can do withtenforty:Basic EvaluationTheevaluate_returnfunction computes the outputs for a single tax return
given some inputs:fromtenfortyimportevaluate_returnevaluate_return(w2_income=100_000,state="CA",filing_status="Married/Joint",num_dependents=2).model_dump()This results in the following:{'total_tax':8484.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':0.0,'state_taxable_income':0.0,'state_total_tax':0.0,'state_tax_bracket':0.0,'state_effective_tax_rate':0.0}Noyear=argument was specified here, so the current tax year, 2023, 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 IncomeTheevaluate_returnsmethod 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:fromtenfortyimportevaluate_returnsevaluate_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 apandas.DataFrame:w2_incomefederal_effective_tax_ratefederal_tax_bracketstate_effective_tax_ratestate_tax_bracket5000010.3121.5210000011.4123615000014.9224.69.320000017225.99.325000018.5246.69.3Plot: Federal Tax as a Function of W2 IncomeSince the output is a dataframe, one may readily use any of numerous
visualization tools to make plots. Here we revisit the example above, evaluating
a wider range of W2 incomes at finer resolution than before.importseaborn.objectsassodf=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 TimeThe 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
momenttenfortysupports 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,2023],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 GainsBecause Open Tax Solver supports short- and long-term capitals gains
calculations -- although, see theLimitationssection
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=lambdaf: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 situation where they need to pay actual
money in taxes on paper gains, via the alternative minimum tax. Withtenforty'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=lambdaf: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 LimitationsMedicare 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,tenfortyonly supports
California, Massachusetts and New York. (It also 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 & ContributingIf you're interested to learn more about how the package works, please seeDEVELOP.mdin this directory.Contributions totenfortyare welcome! If you have suggestions for
improvements or encounter any issues, please feel free to open an issue or
submit a pull request.Licensetenfortyis released under the MIT License.AcknowledgmentsThis project relies on theOpen Tax
Solverproject for the underlying tax
computation logic.