ato-benchmark-compare 0.1.3__tar.gz

ato_benchmark_compare-0.1.3/.gitignore

@@ -0,0 +1,53 @@
+# Client and taxpayer data never belongs in this repository.
+# Working files that could carry a real ledger are blocked by name and by folder.
+profit-and-loss*.csv
+p-and-l*.csv
+pnl*.csv
+mapping*.csv
+!tests/fixtures/**
+!examples/**
+client-data/
+clients/
+ledgers/
+exports/
+*.aba
+*.qbo
+*.ofx
+*.xlsx
+*.xls
+*.xlsm
+!tests/fixtures/*.xlsx
+
+# Credentials
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+token.json
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Agent scratch
+.superpowers/
+.claude/settings.local.json

ato_benchmark_compare-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+This tool compares profit and loss figures against the ATO small business benchmarks
+and shows which accounts produced each figure. A person reads the result and decides
+what it means. Keep that boundary: nothing here should present a comparison as a
+conclusion about whether a return is right, and nothing should lodge, submit or
+transmit anything.
+
+## Data boundary
+
+- Use invented data. The `.gitignore` blocks the file names a real ledger arrives
+  under, including `pnl*.csv`, `mapping*.csv`, `client-data/` and spreadsheet files,
+  with exceptions for `examples/` and `tests/fixtures/`. Put new fixtures in one of
+  those two directories.
+- No client, taxpayer or employee data, no ABNs tied to a real business, no
+  screenshots of a live ledger, no credentials.
+- Check what a fixture implies as well as what it says. An invented profit and loss
+  with a real client's account list is still that client's account list.
+
+## ATO rules and figures
+
+- Trace every rule to a primary source and cite it in the pull request. The rules
+  currently implemented are recorded in `docs/ato-source-notes-2026-08-13.md` with
+  the page and QC number each came from.
+- Do not hand edit anything under `atobenchmark/data`. Rebuild it with
+  `tools/build_dataset.py` from the ATO workbook so the SHA-256 in the file still
+  matches the file it came from.
+- When the ATO publishes a new benchmark year, add it as a new dataset file rather
+  than replacing an existing one. A comparison run last year should still reproduce.
+- Cross check at least one industry against the ATO's own industry page before
+  proposing a new dataset year. `tests/test_dataset.py` does this for bakeries.
+
+## Local verification
+
+Python 3.10 or newer. The runtime imports nothing outside the standard library.
+`uv` manages the development environment and the lock file is committed.
+
+```bash
+uv sync --locked --extra dev --python 3.12
+uv run --locked --extra dev --python 3.12 pytest
+uv run --locked --extra dev --python 3.12 python -m build
+uv run --locked --extra dev --with "pip-audit==2.10.1" pip-audit --local --strict
+```
+
+CI repeats this on Ubuntu with Python 3.10 and 3.13, and on Windows with 3.12. Keep
+runtime strings ASCII: on Windows, redirected stdout uses the machine's ANSI codepage
+rather than UTF-8.
+
+## Pull requests
+
+- Name the rule you changed and the test that pins it. Run that test against the old
+  code first. If it passes there too, it is not testing your change.
+- When you change a rule, search for everything else that states it. The README
+  table, a docstring, the `buckets` command output and a warning string can all keep
+  asserting the old rule long after the code has moved.
+- Amounts stay in `Decimal` end to end. A float anywhere in the ratio path will be
+  rejected: 0.31 as a float is not 0.31, and these comparisons are against published
+  figures at two decimal places.
+- A displayed figure and its verdict must never disagree. 30.96% is below a 31% floor
+  and must not print as 31%.
+
+For a suspected security vulnerability, follow [SECURITY.md](SECURITY.md) rather than
+opening an issue.

ato_benchmark_compare-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Duguid
+
+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.

ato_benchmark_compare-0.1.3/NOTICE

@@ -0,0 +1,10 @@
+Third-party data notice
+
+The benchmark figures under atobenchmark/data are derived from Australian
+Taxation Office data, "Small Business Benchmarks", published at
+https://data.gov.au/data/dataset/small-business-benchmarks and licensed under
+Creative Commons Attribution 2.5 Australia
+(https://creativecommons.org/licenses/by/2.5/au/). The data has been converted
+from the published spreadsheet into JSON and turnover band bounds have been made
+adjoining; no published ratio has been altered. The Australian Taxation Office
+has not endorsed this software.

ato_benchmark_compare-0.1.3/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.5
+Name: ato-benchmark-compare
+Version: 0.1.3
+Summary: Compare profit and loss figures against the ATO small business benchmarks
+Project-URL: Homepage, https://github.com/ryanduguid/ato-benchmark-compare
+Project-URL: Issues, https://github.com/ryanduguid/ato-benchmark-compare/issues
+Author: Ryan Duguid
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: accounting,ato,australia,benchmarks,small business,tax
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: openpyxl>=3.1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ato-benchmark-compare
+
+![ato-benchmark-compare](assets/banner.svg)
+
+[![tests](https://github.com/ryanduguid/ato-benchmark-compare/actions/workflows/ci.yml/badge.svg)](https://github.com/ryanduguid/ato-benchmark-compare/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4F485E.svg?labelColor=04001F)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.10%2B-5C2D91.svg?logo=python&logoColor=white&labelColor=04001F)](https://www.python.org/)
+
+Compare a set of profit and loss figures against the ATO small business benchmarks,
+on your own machine, with the working shown.
+
+The ATO publishes benchmark ranges for 100 industries and uses them to pick which
+small businesses to look at more closely. Checking a client against them is a
+sensible thing to do before lodgment, and it is usually done by hand: find the
+industry page, work out which turnover range applies, add up the right accounts, and
+divide. This does that, and it records which accounts went into which figure so the
+answer can be checked by someone else later.
+
+Australian tax rules only. Every figure comes from the ATO's own published dataset,
+and the comparison is a comparison, not advice.
+
+The published Python distribution and command remain `ato-benchmark-compare`, and the
+import package remains `atobenchmark`.
+
+## What it gets right
+
+The arithmetic is not "expenses over income". The ATO defines these ratios narrowly,
+and the differences change the answer:
+
+- **Turnover** is the sales of goods and services label, not total income. It falls
+  back to total business income only when sales are blank, zero, or less than 50% of
+  total business income.
+- **Total expenses** for the ratio is total expenses **less payments to associated
+  persons**. Wages to a spouse or an associated entity come out before the division.
+- **Cost of sales** for the ratio **excludes salary and wages**, so the wages sitting
+  in a bakery's cost of sales are moved out of the numerator and stay in total
+  expenses.
+- **The key range** is cost of sales to turnover where the ATO publishes one for that
+  industry, otherwise total expenses to turnover.
+- **Turnover bands** are treated as adjoining. The ATO prints `$65,000 - $400,000`
+  then `$400,001 - $750,000`, which read literally leaves $400,000.50 in no band at
+  all.
+
+Source: Australian Taxation Office, [How we calculate benchmark
+ratios](https://www.ato.gov.au/businesses-and-organisations/income-deductions-and-concessions/small-business-benchmarks/small-business-benchmarks-methodology-and-ratio-calculations/how-we-calculate-benchmark-ratios)
+(QC 37143).
+
+## Install
+
+```bash
+git clone https://github.com/ryanduguid/ato-benchmark-compare.git ato-benchmark-compare
+cd ato-benchmark-compare
+pip install .
+```
+
+Python 3.10 or later. The runtime has no dependencies at all: the benchmark data
+ships inside the package and nothing is fetched at run time.
+
+## Use it
+
+The flow is two commands, because the middle step is a person reading the ledger.
+
+**1. Draft a mapping from the profit and loss.**
+
+```bash
+ato-benchmark-compare map --profit-and-loss examples/bakery-pnl.csv --out mapping.csv
+```
+
+That writes one row per account with a suggested bucket, the reason it was suggested,
+and the amount it read. Suggestions come from account names alone.
+
+**2. Review it.** Open `mapping.csv`, fix the buckets, and change the `source` column
+to `reviewed`. `ato-benchmark-compare buckets` explains each bucket. This is the step
+that decides whether the answer is worth anything: no account name tells you whether
+wages went to an associate.
+
+The generated mapping includes an `account_key` immediately after `account`. It is a
+SHA-256 digest of the tool's existing case-and-whitespace-insensitive account identity.
+Leave both columns unchanged while reviewing `bucket`, `source` and `note`; `amount` is
+shown for context and is not bound by the key. On the next run, the key lets the tool
+recover a formula-guarded logical account without confusing `=cmd|calc` with the genuine
+account `'=cmd|calc` when both look the same in a spreadsheet.
+
+`account_key` is an identity integrity check, not authentication or tamper resistance.
+Anyone who can edit the file can recompute it, and case- or whitespace-only account edits
+remain valid by design. Older mappings without the column remain readable for ordinary,
+unambiguous account names. A legacy formula-like name or one that could already contain a
+spreadsheet guard must be regenerated; reapply the reviewed bucket, source and note values
+to the new mapping. Profit and loss input parsing strips and normalises leading whitespace,
+so leading tab, carriage-return and newline prefixes are not distinct raw-ledger identities.
+
+**3. Compare.**
+
+```bash
+ato-benchmark-compare compare \
+  --profit-and-loss examples/bakery-pnl.csv \
+  --mapping examples/bakery-mapping.csv \
+  --industry "Bakeries and hot bread shops"
+```
+
+```
+ATO small business benchmark comparison
+=======================================
+Business type:  Bakeries and hot bread shops
+Benchmark year: 2023-24
+Turnover:       $850,000.00 (sales of goods and services)
+Turnover band:  More than $750,000
+
+Ratio                                   This business  ATO range         Result
+---------------------------------------------------------------------------------
+Cost of sales to turnover (key)         31.76%         29% to 36%        within
+Total expenses to turnover              83.17%         82% to 90%        within
+Labour to turnover                      32.68%         -                 no benchmark in this dataset
+Rent to turnover                        7.29%          -                 no benchmark in this dataset
+Motor vehicle expenses to turnover      1.12%          -                 no benchmark in this dataset
+
+Figures used
+  Sales of goods and services   $850,000.00
+  Other business income         $1,200.00
+  Total business income         $851,200.00
+  Total expenses                $751,950.00
+  Less payments to associates   $45,000.00
+  Total expenses for the ratio  $706,950.00
+  Cost of sales excluding wages $270,000.00
+  Labour                        $277,800.00
+```
+
+Add `--json result.json` for the same result as structured data, including every
+bucket total and the source metadata.
+
+Other commands:
+
+```bash
+ato-benchmark-compare industries --search cleaning   # find the ATO business type
+ato-benchmark-compare show "Bakeries and hot bread shops"
+ato-benchmark-compare buckets
+```
+
+## Input formats
+
+The format this tool guarantees is two columns, with an optional `section` column of
+`income`, `cost_of_sales` or `expense`:
+
+```csv
+account,amount
+Sales,850000
+Purchases,290000
+```
+
+A report style export, with a title block, section headings and subtotal rows, is
+also read. Subtotal rows are detected and written into the mapping marked `excluded`
+rather than dropped, so a total can never be quietly added to the figures it totals,
+and nothing vanishes without appearing in a file you can read. Amounts are taken from
+the first column that parses as amounts; `--amount-column` takes a column number or a
+column heading when a comparative export has more than one.
+
+**The report style layout is inferred.** It was written against the shape these
+exports normally take, not verified against a real export from any particular
+accounting package. Check the mapping file against your own export the first time,
+and use `--amount-column` if it picked the wrong period.
+
+## Buckets
+
+| Bucket | What the ATO does with it |
+| --- | --- |
+| `turnover` | Sales of goods and services. The turnover denominator. |
+| `other_income` | Business income that is not sales. Only reaches turnover through the fallback rule. |
+| `cost_of_sales` | Cost of sales, excluding wages inside it. |
+| `cost_of_sales_labour` | Wages inside cost of sales. Kept out of the cost of sales ratio, kept in total expenses and labour. |
+| `salary_wages` | Salary and wages outside cost of sales. |
+| `contractor_commission` | Contractor, subcontractor and commission expenses. |
+| `associated_persons` | Payments to associated persons. Deducted from total expenses. The wage buckets already exclude these, so labour deducts nothing further. |
+| `rent` | Rent expenses. |
+| `motor_vehicle` | Motor vehicle expenses. |
+| `other_expense` | Every other expense, including superannuation and depreciation. |
+| `excluded` | Outside the ATO calculation: income tax expense, subtotal rows. |
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Comparison produced, key ratio inside the ATO range |
+| 1 | Could not produce a comparison, for example an account with no mapping entry |
+| 2 | Comparison produced, key ratio outside the ATO range |
+| 3 | Comparison produced, but accounts still carry suggested buckets |
+
+## What it does not do
+
+- It is not tax advice, and sitting outside a range is not a finding that anything is
+  wrong. The ATO publishes ranges precisely because businesses differ.
+- The bulk dataset the ATO publishes carries the two key ratios only. Labour, rent
+  and motor vehicle ratios are calculated and shown, but the ranges for them are on
+  the ATO's individual industry pages and are not in this dataset yet.
+- Activity statement benchmarks are not covered. The ATO has not produced them since
+  1 July 2017.
+- It reads a profit and loss. It does not read a tax return, so it cannot see the
+  W1 label, the salary and wages code, or anything else that only exists at lodgment.
+  Pass `--w1` if you want the ATO's W1 rule applied to the labour ratio.
+
+## Client data
+
+Nothing leaves the machine. There is no network call anywhere in the runtime.
+
+The `.gitignore` blocks the file names a real ledger arrives under, including
+`pnl*.csv`, `mapping*.csv`, spreadsheets, and `client-data/`. The example files are
+invented. Do not commit a real one.
+
+## Benchmark data
+
+| Year | Business types | Source |
+| --- | --- | --- |
+| 2023-24 | 100 | [ATO Small Business Benchmarks, data.gov.au](https://data.gov.au/data/dataset/small-business-benchmarks) |
+| 2022-23 | 100 | same dataset |
+
+Each shipped file records the resource URL, the date it was retrieved, and the SHA-256
+of the ATO workbook it was built from. The comparison prints all of that, so a report
+can be traced back to a specific published file.
+
+To add a year when the ATO publishes one:
+
+```bash
+uv run --with openpyxl python tools/build_dataset.py \
+  --xlsx small-business-benchmarks-2024-25-data.xlsx \
+  --year 2024-25 \
+  --resource-name "2024-25 Benchmarks" \
+  --resource-url https://data.gov.au/... \
+  --resource-last-modified 2027-03-15T00:00:00 \
+  --retrieved 2027-03-20 \
+  --out atobenchmark/data/benchmarks-2024-25.json
+```
+
+The builder refuses a workbook whose columns are not where it expects them, rather
+than quietly producing a dataset with the ratios in the wrong places.
+
+### Attribution
+
+The benchmark figures are derived from Australian Taxation Office data, [Small
+Business Benchmarks](https://data.gov.au/data/dataset/small-business-benchmarks),
+used under [CC BY 2.5 AU](https://creativecommons.org/licenses/by/2.5/au/). The data
+has been converted from the ATO's spreadsheet into JSON, and turnover band bounds
+have been made adjoining as described above. No published ratio has been altered.
+The ATO has not endorsed this tool and has nothing to do with it.
+
+The code in this repository is MIT licensed. The data attribution is also
+recorded in [NOTICE](NOTICE), which ships inside the wheel and the sdist.
+
+## Author
+
+Written by Ryan Duguid, a provisional member of Chartered Accountants ANZ,
+independently, in his own time and on his own equipment. Nothing here is the work of
+any employer, and no client data was used to build or test it.
+
+Every ATO rule it
+implements was checked against the ATO's own published pages, and the shipped
+benchmark figures were cross checked against the ATO's industry page for the same
+industry.