Package: habutax
HabuTaxHabuTax is a package designed to help you compute your United States income tax
return. It aims to be simple (both in implementation and ease of use) and
extensible (to make it easy for contributors to expand the existing set of
forms).Design GoalsFail loudly:If a particular form or calculation is not implemented,
HabuTax should inform the user and fail to complete their return. Even if a
particular case is rare, we would rather notify the user that something is
amiss than silently fail to correctly calculate their return.Simplicity:HabuTax aims to be simple in order to ease implementation and
reduce the chance of errors or other bugs. For now, this means the primary
interface is the command-line and text files.Form Modularity:Much of the complexity of US income tax returns comes
from the quantity of calculations rather than the complexity of any individual
calculation. HabuTax tackles this complexity with a divide-and-conquer
approach: It specifies calculations and dependencies at the level of
individual form fields and uses a generic dependency solver to identify the
dependencies and perform all calculations. This makes it much easier to add
and modify tax forms as well as detect/report unimplemented scenarios at a
fine granularity.Tested:We seek to test HabuTax with various income tax return scenarios
to ensure its calculations are correct.Implemented FormsForm 1040, U.S. Individual Income Tax ReturnSchedule 1 (Form 1040), Additional Income and Adjustments to IncomeSchedule 3 (Form 1040), Additional Credits and Payments (part I only)Schedule A (Form 1040), Itemized DeductionsSchedule B (Form 1040), Interest and Ordinary DividendsSchedule 8812 (Form 1040), Credits for Qualifying Children and Other
DependentsForm 8606, Nondeductible IRAsForm 8959, Additional Medicare TaxForm 8995, Qualified Business Income Deduction Simplified Computation
(currently only Section 199a dividends, but additional Qualified Business
Income support could be added upon request)Form 8889, Health Savings AccountsNC Tax Forms (Form D-400, N.C. Individual Income Tax Return plus schedules A and S)InputsIn addition to the above "output" forms, HabuTax supports the following forms
provided to you by your employer or financial institution:Form 1098, Mortgage Interest StatementForm 1099-DIV, Dividends and DistributionsForm 1099-G, Certain Government Payments (previous-year state income tax
refunds)Form 1099-INT, Interest IncomeForm 1099-R, Distributions From Pensions, Annuities, Retirement or
Profit-Sharing Plans, IRAs, Insurance Contracts, etc.Form W-2, Wage and Tax StatementInstallationHabuTax can be used either directly from a source checkout, or by installing it
as a package.DependenciesHabuTax requires Python >= 3.8. An installation ofpdftkis additionally required to fill
PDF forms after solving (output to plain text does not require it).Package InstallationInstalling the latest released version of HabuTax is as easy aspip install habutax.Package Installation (from Source)To install HabuTax as a local python package using the latest source (regardless
of whether it is released), execute the following commands (noting that the
version number may change from the below):% git clone https://github.com/habutax/habutax && cd habutax
% python -m build
% pip install dist/habutax-0.0.1-py3-none-any.whl
% habutax --helpRunning Directly from Source DirectoryTo run out of your source directory, clone the git repository and prefix thehabutaxcommand withpython3 -m:% git clone https://github.com/habutax/habutax && cd habutax
% python3 -m habutax --helpNote that the remainder of the documentation assumes that you have HabuTax
installed as a package, so if you choose to run it out of the source directory,
you will need to prefix all thehabutaxcommands you see withpython3 -m,
and ensure you are running out of the root of the directory.UsageYou can test HabuTax out with the following command-line:habutax solve \
    --year 2023 \
    --form 1040 \
    --writeback-input \
    --prompt-missing \
    --solution taxes_2023.solution \
    taxes_2023.habutaxtaxes_2023.habutax is a plain-text input file, inINI
format. Each form has its own
section in the input file. If you don't want to supply anything up front, you
don't need to: the--promptoption causes HabuTax to prompt you for any
missing input, while--writeback-inputcauses any values you enter
interactively in this way to be written back to the input file.The above example saves the results to a file namedtaxes_2023.solution. If
you omit the--solutionargument, it will print the results to stdout instead.Once you have successfully "solved" your taxes, you can write the results to PDF
using:habutax fill-pdfs \
    taxes_2023.solution \
    taxes_2023.pdfHabuTax also has sub-commands for listing the available forms (habutax list-forms) or list all possible inputs form a form (habutax list-form-inputs).For complete help text for the command-line interface, you can usehabutax --help(--helpis also available on the sub-commands).Can You Help?Pleaseopen an issueif you
want to help or have ideas for improving HabuTax, or jump straight to a merge
request if you have fairly simple code contributions. Opening an issue to
discuss the architecture of your contribution first may be helpful to avoid
wasted effort for more significant changes.One of the primary motivations in the design of HabuTax is to ensure it is easy
toadd and maintain new
forms.
Crowdsourcing this piece is important to ensure this project remains healthy
long-term. We are open to ideas of how best to do so: One idea is to have
contributors informally agree to update and/or test an individual form for
coming tax year. Our guess is that, on average, updating a single form for a new
year will take less time than filling out a personal income tax return!To learn more about the HabuTax internals, you may wish to read our
documentation abouthow the solver
worksorhow to
add/modify tax
forms.Tests and Form Data for ThemTests are currently run usingmake testin the root directory of the
repository. We are always looking to add additional tests, and particularly
welcome your contribution of anonymized tax input data (along with the right
answers!) to help ensure HabuTax's calculations remain correct for all
scenarios. Even data from a single form in isolation is quite helpful. Please
free toopen an issuedescribing what you would like to do!