CountryAlpha2 class example use-case results in mypy error

[TeaDrinkingProgrammer]

When the documented example use-case of CountryAlpha2 is used with Mypy, it results in a type error.

Code:

from pydantic import BaseModel

from pydantic_extra_types.country import CountryAlpha2


class Product(BaseModel):
    made_in: CountryAlpha2


product = Product(made_in='ES')
print(product)
# > made_in='ES'

Results in:

Argument "made_in" to "Product" has incompatible type "str"; expected "CountryAlpha2" [arg-type]

[menzenski]

Getting the same behavior with TimeZoneName. Both mypy and ty raise a type error.

I am using pydantic_extra_types.TimeZoneName in the normal way, per the docs.

Code

# model_test.py

from pydantic import BaseModel
from pydantic_extra_types.timezone_name import TimeZoneName

class TimeZonePolicyData(BaseModel):
    time_zone_name: TimeZoneName


class AmericaNewYorkTimeZonePolicy:

    def get_policy_data(self) -> TimeZonePolicyData:
        return TimeZonePolicyData(
            time_zone_name="America/New_York",
        )

mypy

Running uv run mypy model_test.py gives:

model_test.py:14: error: Argument "time_zone_name" to "TimeZonePolicyData" has incompatible type "str"; expected "TimeZoneName"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

ty

Running uv run ty check model_test.py (tested on ty versions 0.0.1a6 and 0.0.1a7) gives

error[invalid-argument-type]: Argument is incorrect
  --> model_test.py:14:13
   |
12 |     def get_policy_data(self) -> TimeZonePolicyData:
13 |         return TimeZonePolicyData(
14 |             time_zone_name="America/New_York",
   |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Expected `TimeZoneName`, found `Literal["America/New_York"]`
15 |         )
   |
info: rule `invalid-argument-type` is enabled by default

[apoorva-01]

Hey, ran into this and spent an hour on it today, sharing what I found in case it helps.

Tried to reproduce on current main with Python 3.14:

• mypy 1.19.1 with the pydantic.mypy plugin: passes, no error
• mypy 1.19.1 without the plugin: also passes — looks like mypy itself got better at this at some point
• ty 0.0.32: still errors with Expected CountryAlpha2, found Literal["ES"]
• pyright: errors, same as in the original report from @TeaDrinkingProgrammer

So this isn't really fixed. Anyone using pyright or ty still hits it (neither has a pydantic plugin, they just see class CountryAlpha2(str) and treat it as a strict subclass).

I tried sketching a fix and honestly bounced off it a few times, which I'm guessing is why the issue has been sitting. There seem to be three reasonable options and none of them is obviously right:

1. Switch to Annotated[str, _CountryAlpha2Validator] aliases. This is the modern pydantic-recommended pattern and would be the cleanest, but it's actually a breaking change — CountryAlpha2 today is a class with .alpha3, .numeric_code, .short_name properties. Going to an Annotated alias loses those. You could move them to module-level functions but then existing code that does country.alpha3 breaks.

2. Keep the class but add if TYPE_CHECKING: CountryAlpha2 = str. Not pretty, but the runtime stays exactly the same, the API stays the same, and type-checkers are happy. Some other libraries do something similar for NewType-style patterns.

3. Add a __new__ overload that accepts str. Keeps the subclass relationship, but when I poked at this mypy and pyright didn't always honor __new__ overloads in the call sites I tried, so it only seems to half-fix it.

Whatever the fix is, the same thing applies to CountryAlpha3, CountryShortName, CountryNumericCode, TimeZoneName, and probably Coordinate / Latitude / Longitude too — should all get the same treatment.

I'm happy to put up a PR if there's a direction the maintainers would prefer. My gut says (2) because it's the smallest change and breaks nothing, but (1) is what you'd genuinely recommend to someone starting fresh today, so I don't want to just guess. Any preference?