hmrclib
Comprehensive, typed Python client for the HMRC Developer Hub APIs (Making Tax Digital).
hmrclib is a PyPI package that wraps every REST API published on the
HMRC Developer Hub
with:
- Generated pydantic v2 models for every OpenAPI schema in every API
- Typed client classes — one per API, one method per endpoint
- Full OAuth2 support:
client_credentials(application-restricted),authorization_code+refresh_token(user-restricted), with an optional FastAPI callback server for the browser redirect journey - Strict typing — the package itself is
mypy --strictclean andruffclean
Installation
pip install hmrclib
# or, with the OAuth callback server extra:
pip install "hmrclib[server]"
Quick start
import os
from hmrclib import OAuth2Client, HMRCClient
from hmrclib.generated.clients import VatApiClient, VatRegisteredCompaniesApiClient
os.environ["HMRC_ENV"] = "sandbox"
os.environ["HMRC_CLIENT_ID"] = "..."
os.environ["HMRC_CLIENT_SECRET"] = "..."
oauth = OAuth2Client()
oauth.client_credentials("read:vat")
client = HMRCClient(oauth=oauth, scope="read:vat")
vat = VatApiClient(client)
# GET /organisations/vat/{vrn}/obligations
result = vat.get_organisations_vat_vrn_obligations(vrn="123456789")
print(result)
Supported APIs
All 73 REST APIs published on the HMRC Developer Hub are generated from
their official OpenAPI specifications (vendored under specs/),
including Making Tax Digital (Self Assessment, VAT, Property, CIS), Customs,
Lifetime ISA, Agent Authorisation, and the test-support APIs.
OAuth2
from hmrclib import OAuth2Client
oauth = OAuth2Client()
oauth.client_credentials("read:vat") # application-restricted
# user-restricted: build the authorize URL, then exchange the code
url = oauth.authorization_url("hello", state="abc123")
# ... user completes the browser journey ...
token = oauth.authorization_code("CODE_FROM_REDIRECT")
token = oauth.refresh(token.refresh_token) # keep it alive
OAuth callback server (FastAPI)
uvicorn hmrclib.server:app --port 8300
Serve the registered redirect URI (e.g. https://baseframe.rodmena.co.uk/oauth/hmrc/callback),
capture the code and exchange it for tokens:
curl https://baseframe.rodmena.co.uk/oauth/hmrc/result
Development
uv pip install -e ".[dev]"
ruff check .
mypy .
pytest
The generated code can be regenerated from the vendored specs:
python -m hmrclib.codegen --specs specs --out src/hmrclib/generated
License
MIT. hmrclib is not affiliated with HMRC; the API specifications it
implements are © Crown copyright, available under the
Open Government Licence v3.0.
Metadata
Release files for hmrclib 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hmrclib-0.1.3.tar.gz | 850.8 kB | Without provenance | Details for hmrclib-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hmrclib-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for hmrclib-0.1.3-py3-none-any.whl |
Total release size: 1.0 MB
Release files / hmrclib-0.1.3.tar.gz
| Download URL | hmrclib-0.1.3.tar.gz |
|---|---|
| Size | 850.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2bd76f77bfef535b68b6b6a8bad1920915d310958fefb09c60ec3a20bdd4cc2a
|
|
BLAKE2b-256 checksum How to use checksums |
c3fda47a1a053a43a01f854cb56094ff2830bd94016a8fdc8effbdb9625abd31
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / hmrclib-0.1.3-py3-none-any.whl
| Download URL | hmrclib-0.1.3-py3-none-any.whl |
|---|---|
| Size | 187.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f94339ff337d72e7acdf3fbd0c2ca40e3923bbdc592b9c454398d33ee2e5482d
|
|
BLAKE2b-256 checksum How to use checksums |
963f0da7b60f03941b3258c8c4403cdeb592f4d5a55a8a714129795518f2c0ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for hmrclib 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.