The alias documentation is incorrect

[kzrnm]

import sys

from pydantic import AliasChoices, AliasPath, Field

from pydantic_settings import BaseSettings


class User(BaseSettings, cli_parse_args=True):
    first_name: str = Field(
        validation_alias=AliasChoices('f', 'fname', AliasPath('name', 0))
    )
    last_name: str = Field(
        validation_alias=AliasChoices('l', 'lname', AliasPath('name', 1))
    )


sys.argv = ['example.py', '--fname', 'John', '--lname', 'Doe']
print(User().model_dump())
# pydantic_settings.exceptions.SettingsError: error parsing value for field "first_name" from source "EnvSettingsSource"

https://docs.pydantic.dev/latest/concepts/pydantic_settings/#aliases

[hramezani]

Thanks @kzrnm for this issue.

I run your example code and got {'first_name': 'John', 'last_name': 'Doe'}

What is wrong here? Could you explain more?

[kzrnm]

It seems the issue was caused by the NAME environment variable already being set (possibly because it was run under WSL).
In any case, explicit arguments being overridden by environment variables is unexpected, so this still appears to be a bug.

import os
import sys

from pydantic import AliasChoices, AliasPath, Field

from pydantic_settings import BaseSettings


if 'NAME' in os.environ:
    del os.environ['NAME']
class User(BaseSettings, cli_parse_args=True):
    first_name: str = Field(default='', validation_alias=AliasChoices('f', 'fname', AliasPath('name', 0)))
    last_name: str = Field(default='', validation_alias=AliasChoices('l', 'lname', AliasPath('name', 1)))

sys.argv = ['example.py', '--fname', 'John', '--lname', 'Doe']
print(User().model_dump())
# {'first_name': 'John', 'last_name': 'Doe'}


os.environ['NAME'] = 'Jhon,Doe'
print(User().model_dump())
# pydantic_settings.exceptions.SettingsError: error parsing value for field "first_name" from source "EnvSettingsSource"

[hramezani]

This is because pydantic-settings extracts values from different sources and then provides all of them to pydantic for validation. So it tries to prepare values for env source.
pydantic-settings considers a field value as a complex value if the field alias has a length > 1. So, the value of first_name field will be considered as a complex value. pydantic-settings json parse complex values. That's why you see the above error.

[kzrnm]

@hramezani I understand that this behavior is technically expected. However, having it fail when run via copy and paste on WSL is not desirable, so I think using a different name makes more sense.
I’ve opened pull request #747 to change --name to --fullname.