marshmallow-code / marshmallow-code/marshmallow

Should the type of `missing` be exposed publicly for use in type annotations?

Open
#1,971 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
7.2k
Forks
738
Avg merge
1d 23h
Merged PRs (30d)
7

Description

I almost filed a PR to make this change, but then I realized that the desirability of this is non-obvious.

I have some code which manipulates a variable like so in a pre-dump hook:
```python
class MySchema(Schema)
raw = fields.Raw()

@pre_dump
def do_pre_dump(self, obj: dict[str, Any], **kwargs: Any) -> dict[str, Any]:
try:
x = complex_func()
except ValueError:
x = missing

return {"raw": x}
```

When adding annotations, how do I annotate `x`? Assuming `complex_func()` returns a `T`, then

```python
x: _Missing | T = complex_func()
```

seems correct. But `_Missing` is an internal detail, not part of `marshmallow`'s exports.

It is not necessary for `x` to ever have a value of `missing` if you have another sentinel value to use (e.g. `None` works for many cases). I've refactored to handle this in my specific case, so there's no urgency here.

I have a branch which renames `_Missing` to `MissingType`, exposes it, and sets `_Missing = MissingType` as a bit of compatibility for anyone using it. But I'm not sure if I should submit the PR?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the current definition and public exports of `_Missing`, then compare them with the proposed `MissingType` rename and compatibility alias described in the issue. The work is done when the public type-annotation API decision is resolved and any resulting change preserves the stated compatibility concern.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend-api-design
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.