Add option to show only the alias for a field

[spacemanspiff2007]

I'm loading the application configuration from a yaml file and want to use autodoc-pydantic to document the available settings.
It's really great that there are so many configuration options so everything can be tailored to ones needs.

However I'm missing one more thing:
Since I load from file I load the corresponding values by alias and not by name.
Would it be possible to add a configuration option which shows the alias instead of the field name?
My users have to enter the alias in the configuration file - the field name is of no use for them and might be confusing.

Example:

class General(BaseModel):
    listen_only: bool = Field(False, alias='listen only')

Valid entry in yaml file

listen only: True

[mansenfranzen]

Hi @spacemanspiff2007,

thanks for sharing your feature request! I think it is a reasonable proposal regarding your use case. However, I believe this use case is rather infrequent and narrow. The tradeoff between introduced complexity and gained functionality might be rather unbalanced towards the former.

I'm not rejecting your request in any way. Rather, please help me justify it ;-). Can you think of other use cases? Or perhaps, if we provide a skeleton example of how an application configuration is loaded from a yaml file and used with autodoc-pydantic to be documented, it would be of use for others too.

[spacemanspiff2007]

Thanks for your reply.
I've been playing around with easyconfig, a very convenient wrapper that allows to

• load data from yaml files
• create a yaml file with defaults and comments

and validates everything with pydantic.
It took some iterations but I think now it's quite convenient (if you like yaml files).
The docs are still a bit lacking, I think I'll have to switch to rtd soon.

The general idea is that you define your configuration in pydantic.
If you want to you can add a class Mixin so you get type hints for the easyconfig functions but that is completely optional.
You than pass the model instance into a function which will create a mutable object from it.
If you then load values from a file the values from the object and subobjects mutate in place.

from pydantic import BaseModel, Field
from easyconfig import AppConfigMixin, create_app_config


class MySimpleAppConfig(BaseModel, AppConfigMixin):  # <-- AppConfigMixin is optional
    retries: int = Field(5, description='Amount of retries on error')
    url: str = 'localhost'
    port: int = 443


# Create a global variable which then can be used throughout your code
# It implements the file loader, yaml logic and optional callbacks in case of value change.
CONFIG = create_app_config(MySimpleAppConfig())

# Use with type hints and auto complete
print(CONFIG.port)

# Load configuration file from disk.
# If the file does not exist it will be created
# Loading will also change all values of CONFIG accordingly
CONFIG.load_config_file('/my/configuration/file.yml')

Created yaml file

retries: 5  # Amount of retries on error
url: localhost
port: 443

Since this is depended on another library I'm not sure if you want it in your docs.
If you do, I'll gladly provide a pr that adds something in examples.

[mansenfranzen]

For clarification: let's assume the alias is shown instead of the original attribute name. Does the original attribute name appear anywhere (e.g. where the alias was shown previously)?

I suggest autodoc_pydantic_field_replace_name_with_alias as a configuration property.

[spacemanspiff2007]

Yes - my first idea would be to not show the name at all.

However if we just add a switch to swap name and alias then we have all use cases covered (e.g. autodoc_pydantic_field_swap_name_and_alias or autodoc_pydantic_field_swap_name_with_alias). The showing of the name would then be controlled by autodoc_pydantic_field_show_alias.

e.g.:

field: int = Field(1, alias="field2")

Config switch	output
show_alias	attribute field: int (alias 'field2')
not show_alias and swap_name_and_alias	attribute field2: int
show_alias and swap_name_and_alias	attribute field2: int (alias 'field') or attribute field2: int (name 'field') since alias is misleading

I currently can't think of a use case where one would show name and alias in switched order so both is fine for me.

[mansenfranzen]

This looks good to me - I agree with autodoc_pydantic_field_swap_name_and_alias.

We have to keep in mind, that field summary list needs to be modified to if name and alias are swapped. Otherwise we would have an inconsistency between the field summary in the model's header and the actual field names.

[mansenfranzen]

@spacemanspiff2007 This is accomplished by #119.

• Documentation on the new configuration property autodoc_pydantic_field_swap_name_and_alias: click
• Updated documentation on the example for swapped field name/alias: click

Before merging the related PR, it would be great if you could test the behavior on your site. To do so, please install the current dev release in your doc-building-environment via pip install git+https://github.com/mansenfranzen/autodoc_pydantic.git@v1.7.0-a.2 and rebuild your docs.

The actual implementation was more complex because of interactions with other configurations (model-show-field-summary, model-show-validator-summary, validator-replace-signature, validator-list-fields) that require a replacement of field name with field alias for consistency reasons. Otherwise, we would show the field alias in one place but the the field name elsewhere.

[spacemanspiff2007]

Thank you very much for the implementation!

I've tested it and it works as desired:

thread_pool: ThreadPoolConfig = Field(default_factory=ThreadPoolConfig, alias='thread pool')

generates

Otherwise, we would show the field alias in one place but the the field name elsewhere.

Good catch!

[mansenfranzen]

This is included in v1.7.0 (released just few minutes ago).