ntstatus

What it is and what it does

ntstatus is a reference library that maps Windows API status codes to Python constants and provides bidirectional lookup methods. It defines three main classes—NtStatus, Win32Error, and HResult—each exposing a complete or near-complete set of named constants from the Windows API documentation. Each constant is represented as a ThirtyTwoBits object that can be compared to integers using either their signed or unsigned interpretation, solving the common problem of matching numeric error codes returned by Windows APIs to their symbolic names.

The library is designed for developers working with ctypes, pywin32, or other Windows interop layers who need to decode error codes or check status values against known constants. It has no runtime dependencies and installs cleanly. The package supports Python 3.10 through 3.13 and is licensed under MIT, making it freely usable in any project.

Use it for:

• Decode numeric NTSTATUS values returned by Windows system calls into human-readable constant names for logging or error handling.
• Compare Win32 error codes against known constants without manual hex-to-decimal conversion or sign-extension logic.
• Look up HRESULT values by numeric code in COM interop or Windows API wrapper code to identify failure reasons.
• Build Windows system diagnostics or monitoring tools that need to interpret and report status codes from kernel or system APIs.
• Validate or test Windows API wrapper code by checking that returned codes match expected NTSTATUS or Win32 Error constants.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides Python constants and lookup methods for Windows API NTSTATUS, Win32 Error Code, and HRESULT values, with support for comparing values as both signed and unsigned 32-bit integers.

Yes, if you are writing Windows interop code in Python and need to work with NTSTATUS, Win32 Error, or HRESULT values. The library is lightweight, dependency-free, and solves a real friction point in Windows API integration. However, note that maintenance is aging—the last update was 2025-06-11 with no recent activity, so treat it as stable but not actively developed.

Install

ntstatus on PyPI

pip install ntstatus

uv add ntstatus

poetry add ntstatus

Installing ntstatus

Before you install

Low install friction with no runtime dependencies. Maintenance status is aging—last commit was 2025-06-11 and the project has not been updated in several months, though the repository remains active and not archived.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart

from ntstatus import NtStatus

# Decode a status code by numeric value
status = NtStatus.decode(0xC0000135)
print(status.name)  # STATUS_DLL_NOT_FOUND
print(status.signed_value)  # -1073741515
print(status.unsigned_value)  # 3221225781

Requires Python 3.10 or later.

Verify before relying

• Whether the package is actively maintained or in maintenance-only mode—last update was 2025-06-11 with no recent activity signal.
• Real-world adoption and stability—144527 monthly downloads suggests some use, but project visibility (0 GitHub stars) is unclear.

Package facts

Evidence: ntstatus-2.0-py3-none-any.whl

Tags

More Software Development packages