radeklat / settings-doc Goto Github PK
View Code? Open in Web Editor NEWA command line tool for generating Markdown documentation and .env files from pydantic BaseSettings.
License: MIT License
A command line tool for generating Markdown documentation and .env files from pydantic BaseSettings.
License: MIT License
Not sure if I'm right, but it appears only the root fields of BaseSettings are exposed correctly.
From pydantic docs:
class SubModel(BaseModel):
foo = 'bar'
apple = 1
class Settings(BaseSettings):
more_settings: SubModel = SubModel()
class Config:
env_prefix = "QUX__"
env_nested_delimiter = "__"
generates support for QUX__MORE_SETTINGS__FOO
and QUX__MORE_SETTINGS__APPLE
env vars.
I haven't yet checked if this is doable by overriding templates (it would be nice to explain that in README, if that's the case), but even if it is doable, I believe this should work by default.
Hello, great project! This is exactly what people need.
In my case I need env variable docs for all new variables. And if I added a new class, then I want documentation to be generated for it and I didn't have to specify it class manualy via -c
.
How can I use settings-doc if I have multiple settings classes? I would not like to indicate it by hand.
Have you thought about the possibility of passing only the module path or a regular expression or something like that so that the utility can independently find all the classes with settings and return results for them?
Thx, I can help with realization:)
Hello @radeklat , thanks for the last update to expose classes. So far, I am enjoying my experience in auto generating configurations for my apps :D.
Currently I am contemplating the solution for one of my use cases. I want to display the class title and render each classes sorted by their titles. I displayed the title by using the following macro:
{% macro class_title(class) -%}
{% if class.Config|attr('title') -%}
{{ class.Config.title }}
{%- else -%}
{{ class.__name__ }}
{%- endif %}
{%- endmacro %}
However, I reached a conundrum while trying to sort the classes by their title. After some tinkering, I figured out a way to achieve this is to add custom filters. So I modified the main.py
(for testing purpose):
class_title = env.globals["class_title"] = lambda x: x.Config.title if hasattr(getattr(x, 'Config', None), 'title') else x.__name__
env.filters["sort_title"] = lambda x: list(sorted(x, key=class_title))
And I use them in the following way:
{% for class in classes|sort_title %}
{{ heading(2) }} {{ class_title(class) }}
{% endfor %}
I am wondering what are your thoughts on this and if it is worth supporting custom filters without having to modify the main.py
. I will gladly write a pull request if you think that this is a good idea/feature to support.
This is a follow-up from #15 .
Admittedly, what I'm trying to do is somewhat unorthodox. I'm not in love with Pydantic's "nested delimiter" feature. Personally, I'd rather not leak the structure of my configuration model outside of my application. If I decide to restructure my configuration models, I don't want everything that uses my application to need to modify the environment variables they set. In other words, I view the set of configuration parameters (i.e. environment variable names) as an interface that I'd like to be open to extension but closed for modification.
I have my configuration defined like this:
from pydantic_settings import BaseSettings, SettingsConfigDict
PREFIX = "MY_APP_"
class SubConfig(BaseSettings):
model_config = SettingsConfigDict(env_prefix=f"{PREFIX}_SUB_", extra="ignore")
field_a: int
field_b: float
class Config(BaseSettings):
model_config = SettingsConfigDict(env_prefix=PREFIX, extra="ignore")
field_1: str
field_2: bool
sub: SubConfig
In practice, this lets me define environment variables like MY_APP_SUB_FIELD_A
, without the need of a specific delimiter. settings-doc
renders it as follows:
# `MY_APP_FIELD_1`
**Required**
# `MY_APP_FIELD_2`
**Required**
# `MY_APP_SUB`
**Required**
I'd like for settings-doc
to traverse the subconfig and generate documentation for its members. Any help is appreciated.
I use a combination of --module
and --class
to specify Settings sources.
The order how they appear in the output is not stable and changes between runs.
This is especially problematic with pre-commit, which fails if it detects a file change.
I think this can be fixed by sorting
settings-doc/src/settings_doc/main.py
Lines 148 to 150 in 982d3aa
e.g. with
sorted(settings, key=str)
However, I think keeping the order of Settings classes the same as in the input is more user friendly, in that case I think an ordered set will need to be used.
I think it would be a very useful feature to expose this project as a pre-commit-hook.
This way, people would be able to, say, update their README.md file automatically on each change, without running multi-step CI jobs, or doing that manually.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.