Django QueryDict Behavior with Empty Lists

You've identified an interesting edge case in Django's QueryDict.__getitem__() method. According to the documentation, this method should return the last value for a key if multiple values exist, or raise a MultiValueDictKeyError if the key doesn't exist.

However, as you've demonstrated, when a key is associated with an empty list (via setlist()), the method returns that empty list rather than raising an error or returning a single value:

PYTHONCopied
>>> from django.http import QueryDict
>>> q = QueryDict('a=1', mutable=True)
>>> q['a']
'1'

>>> q.setlist('b', [])
>>> q['b']
[]

This behavior is indeed not explicitly documented. The issue you've linked (#35915) correctly identifies this as a potential problem, especially for type annotations.

Analysis of the Current Behavior

The current behavior makes QueryDict.__getitem__() return one of:

• A string (when the key exists with one or more values)
• An empty list (when the key exists but has no values)
• Raises KeyError (when the key doesn't exist)

This makes type annotations challenging, as you'd need to use str | list[str] rather than the cleaner str | None.

Potential Solutions

Your suggestion to change the behavior to return None instead of an empty list would indeed make type annotations cleaner. However, this would be a breaking change for code that relies on the current behavior.

Alternative approaches could include:

1. Improving the documentation to explicitly mention this edge case
2. Adding a new method that has more consistent return types
3. Keeping the current behavior but providing better type hints in Django's stub files

Considerations

When working with the current implementation, you might consider:

1. Using the get() method with a default value when you're unsure if a key exists or might have an empty list:

   PYTHONCopied
   value = q.get('key', default_value)

2. Explicitly checking for empty lists when processing values:

   PYTHONCopied
   value = q['key']
   if isinstance(value, list) and not value:
       # Handle empty list case

3. Using getlist() when you specifically want to work with all values:

   PYTHONCopied
   values = q.getlist('key')
   # values will always be a list, empty if the key doesn't exist

The issue you've identified is valid, and improving either the behavior or documentation would be beneficial for Django developers, especially as type annotations become more widely used.