pythonnative/pythonnative

Problem pn codegen exists in _build_parser() and is used in the native-contracts guide, but the hand-written Subcommands list in docs/api/cli.md omits it. Its generated function documentation is only a one-line summary, so users scanning the CLI reference can't discover the options or their defaults. In src/pythonnative/cli/pn.py, the command accepts --output (a path, default generated) and repeatable --module arguments. It imports those schema modules before generation and prints each generated file's path. Requested change Add a pn codegen entry to the CLI Subcommands list covering --output, its default directory, and repeatable --module imports. Add a short example showing an explicit output directory. Explain that extension module names must be importable in the interpreter running pn. Link to docs/guides/native-contracts.md for the extension workflow and to the generated-source section of CONTRIBUTING.md for repository contributors. Explain that this generates contract files and

Problem The async guide tells users that use_query(..., client=...) accepts a pythonnative.query.QueryClient with configurable capacity and stale time. However, there is no docs/api/query.md or query-cache entry in the API navigation. src/pythonnative/query.py already contains QueryClient, QuerySnapshot, and their method docstrings. Readers currently have to open the source to find operations such as invalidate(), set_data(), and close(). Requested change Add docs/api/query.md, following the layout of docs/api/storage.md: a short introduction, an explicitly scoped mkdocstrings block for QueryClient and QuerySnapshot, and related links. Add the page beside the async/data APIs in mkdocs.yml. Link to it from the custom-client paragraph in docs/guides/async.md and the async-hooks section of docs/api/hooks.md. Include a compact example of creating one stable client with capacity and stale_time, passing it to use_query with a hashable key, and invalidating that key. Explain that the owner c

Problem The warning log in src/pythonnative/diagnostics.py retains the most recent 200 messages, returns a snapshot in oldest-first order, and clears both messages and deduplication keys when clear_warnings() is called. tests/test_core_semantics.py already tests deduplication for an explicit key and some production-mode behavior, but it doesn't directly cover log eviction, snapshot isolation, or resetting deduplication. These guarantees keep diagnostics useful during long preview sessions and prevent tests from leaking warning state. Requested change Extend the existing diagnostics-primitives section of tests/test_core_semantics.py, using its dev_mode fixture and pytest capture helpers. No runtime changes are expected. Acceptance criteria Record 201 distinct warnings and assert that exactly the newest 200 remain in oldest-first order. Mutating the list returned by get_warnings() doesn't change the internal log. clear_warnings() empties the log and allows a previously used warn_once ke

Problem src/pythonnative/project/icons.py promises that icon and splash generation returns False when the optional Pillow dependency is unavailable, allowing the build to retain its template assets. dominant_background_color() similarly returns None. The tests in tests/project/test_icons.py cover the successful image-generation paths, but their module-level skipif skips the entire file when Pillow is missing. There are no tests protecting the fallback behavior or proving that it leaves existing assets alone. Requested change Add a separate tests/project/test_icons_optional.py that doesn't import Pillow or inherit the existing module-wide skip. Monkeypatch icons.pillow_available to return False so the tests run regardless of whether Pillow is installed on the contributor's machine. Acceptance criteria generate_ios_icons(), generate_android_icons(), generate_ios_splash(), and generate_android_splash_icon() return False. dominant_background_color() returns None. Missing source files don'

Problem The equal() helper in src/pythonnative/equality.py defines how hook dependencies and state snapshots signal a change. Its contract deliberately treats identity as equal, accepts a boolean comparison result, and treats exceptions or nonboolean comparison results as unequal without coercing them to bool. src/pythonnative/hooks.py uses it for dependency comparison and state updates. The test suite has Element equality tests, but no direct tests for this helper's unusual-comparison behavior. Replacing it with a naive bool(left == right) would break array-like application values. Requested change Add tests/test_equality.py with focused tests of the existing behavior. Use tiny custom Python classes to model unusual comparisons so contributors don't need NumPy or another new dependency. Acceptance criteria Equal and unequal ordinary scalar/container values return actual booleans. The same object returns True without invoking its __eq__, even if that method would raise. Distinct objec