Skip to main content

PyPI version Python versions CI License: MIT

nodiscard

A @nodiscard decorator and static checker for Python — like Rust's #[must_use] or C++'s [[nodiscard]].

Problem

Frozen/immutable models return new instances from mutation methods. Forgetting to capture the return value is a silent no-op:

user = User(name="Alice")
user.rename("Bob")   # Bug! Returns a new User, but the result is silently discarded.
print(user.name)     # Still "Alice"

Quick Start

pip install nodiscard
from nodiscard import nodiscard

class User:
    @nodiscard
    def rename(self, name: str) -> "User":
        return User(name=name)
nodiscard check src/
# src/app.py:42:5: ND001 Return value of '@nodiscard' method 'rename' is discarded

Usage

Decorator

from nodiscard import nodiscard, NoDiscard
from typing import Annotated

class Schema:
    @nodiscard
    def merge(self, other: "Schema") -> "Schema": ...

    # Alternative: Annotated marker
    def replace(self, **kwargs: object) -> Annotated["Schema", NoDiscard]: ...

Works with @classmethod, @staticmethod, @abstractmethod, async def, and decorator stacking.

CLI

nodiscard check src/                       # Check a directory
nodiscard check src/models.py              # Check a single file
nodiscard check src/ --src src/            # Set import resolution root
nodiscard check src/ --exclude "tests/*"   # Exclude patterns
nodiscard check src/ --format json         # JSON output

Exit codes: 0 = no violations, 1 = violations found, 2 = error (e.g. path not found).

Configuration

# pyproject.toml
[tool.nodiscard]
src = ["src"]
exclude = ["tests/*", "migrations/*"]
format = "text"  # "text" or "json"

CLI arguments override pyproject.toml settings.

Rules

Code Name Description
ND001 discarded-nodiscard-return Return value of a @nodiscard method is discarded

Inline suppression

obj.method()  # nodiscard: ignore

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/KinjiKawaguchi/nodiscard
    rev: v0.1.0
    hooks:
      - id: nodiscard
        args: [check, src/]

Comparison

Feature Rust #[must_use] C++ [[nodiscard]] Python @nodiscard
Compile-time Yes Yes Static analysis
Functions Yes Yes Methods (v0.1)
Custom message Yes C++20 @nodiscard(reason="...")
Suppressible let _ = ... (void)expr _ = expr / # nodiscard: ignore

Limitations

  • v0.1 detects method calls only (not bare function calls)
  • Type inference is local-scope only (no full type resolution like mypy/pyright)
  • No IDE integration yet (LSP planned for future)
  • async task tracking (asyncio.create_task) is not analyzed

Contributing

  • DeepWiki — AI-generated codebase documentation
git clone https://github.com/KinjiKawaguchi/nodiscard.git
cd nodiscard
uv sync
uv run pytest --cov=nodiscard
uv run ruff check src/ tests/

License

MIT

Metadata

Release files for nodiscard 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nodiscard 0.1.1
File Size Uploaded Provenance Actions
nodiscard-0.1.1.tar.gz 107.1 kB With provenance Details for nodiscard-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for nodiscard 0.1.1
File Interpreter ABI Platform Actions
nodiscard-0.1.1-py3-none-any.whl Python 3 none any Details for nodiscard-0.1.1-py3-none-any.whl

Total release size: 124.7 kB

Release files / nodiscard-0.1.1.tar.gz

Download URL nodiscard-0.1.1.tar.gz
Size 107.1 kB
Tags Source
SHA-256 checksum
How to use checksums
9ee63fe3f42ec1863d2a1081c79820be0e36363a0229294c9637e4a2fe370b68
BLAKE2b-256 checksum
How to use checksums
45a944e60fc457d414450532fe954cd1d3512fcf0bb5255fe1cf00ff506d863d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 7, 2026.

Transparency log

Release files / nodiscard-0.1.1-py3-none-any.whl

Download URL nodiscard-0.1.1-py3-none-any.whl
Size 17.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b692e0d9e08d64f13931871d206ec53cc39f734adc3398ae4de45b673696d5ad
BLAKE2b-256 checksum
How to use checksums
53087a1c1c1b443abecc17d1c2d06c5c8d7162d345d127670993b1eb848bf9d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 7, 2026.

Transparency log

Security for nodiscard 0.1.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for nodiscard-0.1.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Apr 7, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page