Package: pycosmiconfig
pycosmiconfigPycosmiconfig is the Python port of the popularCosmiconfigpackage (3.7k ⭐️).NOTE: Pycosmiconfig uses the same version number as the Cosmiconfig version it's equivalent to. E.g. Pycosmiconfig v8.3.6 == Cosmiconfig v8.3.6NOTE 2: Pycosmiconfig differs in 3 features from original Cosmiconfig:Pycosmiconfig prefixes searched property withtool.when searching inpyproject.toml. SopackageNamebecomestool.packageName. On contrary, Cosmiconfig searches for propertypackageNameinpackage.json.The settings toconfigure Pycosmiconfigare under thepycosmiconfigproperty, instead of Cosmiconfig'scosmiconfig.Pycosmiconfig has only synchronous operations and thesyncsuffix is omitted. So the two versions below are identical:# Pythonfrompycosmiconfigimportcosmiconfigresult=cosmiconfig('foo').search()// JavaScriptconst{cosmiconfigSync}=require("cosmiconfig");constresult=cosmiconfigSync("foo").search();Cosmiconfig searches for and loads configuration for your program.It features smart defaults based on conventional expectations.
But it's also flexible enough to search wherever you'd like to search, and load whatever you'd like to load.By default, Cosmiconfig will start where you tell it to start and search up the directory tree for the following:a[tool.{package}]property inpyproject.{toml,tml}a JSON or YAML, extensionless "rc file"an "rc file" with the extensions.json,.yaml,.yml,.toml,.tmlor.pyany of the above two inside a.configsubdirectorya.config.pyfileFor example, if your module's name is "myapp", cosmiconfig will search up the directory tree for configuration in the following places:a[tool.myapp]property inpyproject.tomlandpyproject.tmla.myapprcfile in JSON or YAML formata.myapprc.json,.myapprc.yaml,.myapprc.yml,.myapprc.toml,.myapprc.tml,.myapprc.pyfileamyapprc,myapprc.json,myapprc.yaml,myapprc.yml,myapprc.toml,myapprc.tml,myapprc.pyfile inside a.configsubdirectoryamyapp.config.pyfileCosmiconfig continues to search up the directory tree, checking each of these places in each directory, until it finds some acceptable configuration (or hits the home directory).Table of contentsInstallationUsage for tooling developersResultSynchronous APIcosmiconfig()explorer.search()explorer.load()explorer.clear_load_cache()explorer.clear_search_cache()explorer.clear_caches()CosmiconfigOptionssearch_placesloaderspackage_propstop_dircachetransformignore_empty_search_placesLoading Python modulesCachingUsage for end usersContributing & DevelopmentInstallationPip:pip install pycosmiconfigPoetry:poetry add pycosmiconfigTested in Python 3.8+.Usage for tooling developersIf you are an end user (i.e. a user of a tool that uses cosmiconfig, likeprettierorstylelint),
you can skip down tothe end user section.Create a Cosmiconfig explorer, then eithersearchfor or directlyloada configuration file.frompycosmiconfigimportcosmiconfig# ...explorer=cosmiconfig(module_name)# E.g. 'foo'# Search for a configuration by walking up directories.# See documentation for search, below.try:result=explorer.search()# result.config is the parsed configuration object.# result.filepath is the path to the config file that was found.# result.is_empty is True if there was nothing to parse in the config file.exceptExceptionaserror:# Do something constructive.# Load a configuration directly when you know where it should be.# The result object is the same as for search.# See documentation for load, below.result=explorer.load(path_to_config)ResultThe result object you get fromsearchorloadhas the following properties:config:The parsed configuration object.Noneif the file is empty.filepath:The path to the configuration file that was found.is_empty:Trueif the configuration file is empty. This property will not be present if the configuration file is not empty.Synchronous APIcosmiconfig()frompycosmiconfigimportcosmiconfigexporer=cosmiconfig(module_name[,**cosmiconfig_options])# E.g.exporer=cosmiconfig('foo',stop_dir='.',transform=lambdax:x)Creates asynchronouscosmiconfig instance ("explorer") configured according to the arguments, and initializes its caches.module_nameType:str.Required.Your module name. This is used to create the defaultsearch_placesandpackage_prop.If yoursearch_placesvalue will include files, as it does by default (e.g.${module_name}rc), yourmodule_namemust consist of characters allowed in filenames. That means you should not use package names, such as@my-org/my-package, directly inmodule_name.CosmiconfigOptionsare documented below.You may not need them, and should first read about the functions you'll use.explorer.search()result=explorer.search([search_from])# E.g.result=explorer.search()result=explorer.search('./configs')Searches for a configuration file. Returns aresultorNone, if no configuration file is found.Let's say your module name isgoldengrahamsso you initialized withexplorer = cosmiconfig('goldengrahams').
Here's how your defaultsearch()will work:Starting fromos.getcwd()(or some other directory defined by thesearch_fromargument tosearch()), look for configuration objects in the following places:Atool.goldengrahamsproperty in apyproject.tomlorpyproject.tmlfiles.A.goldengrahamsrcfile with JSON or YAML syntax.A.goldengrahamsrc.json,.goldengrahamsrc.yaml,.goldengrahamsrc.yml,.goldengrahamsrc.toml,.goldengrahamsrc.tml,.goldengrahamsrc.pyfile. (To learn more about how Python files are loaded, see"Loading Python modules".)Agoldengrahamsrc,goldengrahamsrc.json,goldengrahamsrc.yaml,goldengrahamsrc.yml,goldengrahamsrc.toml,goldengrahamsrc.tml,goldengrahamsrc.pyfile in the.configsubdirectory.Agoldengrahams.config.pyfile. (To learn more about how Python files are loaded, see"Loading Python modules".)If none of those searches reveal a configuration object, move up one directory level and try again.
So the search continues in./,../,../../,../../../, etc., checking the same places in each directory.Continue searching until arriving at your home directory (or some other directory defined by the cosmiconfig optionstop_dir).For Python files,If at any point a parsable configuration is found,search()returns with theresult.If no configuration object is found,search()returnsNone.If a configuration object is foundbut is malformed(causing a parsing error),search()throws an error.If you know exactly where your configuration file should be, you can useload(), instead.The search process is highly customizable.Use the cosmiconfig optionssearch_placesandloadersto precisely define where you want to look for configurations and how you want to load them.search_fromType:str.
Default:os.getcwd().A filename.search()will start its search here.If the value is a directory, that's where the search starts.
If it's a file, the search starts in that file's directory.explorer.load()result=explorer.load(load_path)Loads a configuration file. Returnsresultor raises an error if the file does not exist or cannot be loaded.Useloadif you already know where the configuration file is and you just need to load it.explorer.load("load/this/file.json")# Tries to load load/this/file.json.If you load apyproject.tomlorpyproject.tmlfile, the result will be derived from whatever property is specified as yourpackage_prop.NOTE:package_propwill be prefixed withtool., so if your package name ismypkg, and you setpackage_prop="mypkg", then yourpyproject.tomlshould have atool.mypkgproperty:[tool.poetry]...[tool.mypkg]val_a="hello"world={b=2}explorer.clear_load_cache()Clears the cache used inload().explorer.clear_search_cache()Clears the cache used insearch().explorer.clear_caches()Performs bothclear_load_cache()andclear_search_cache().CosmiconfigOptionsPossible options are documented below.search_placesType:List[str].
Default: See below.An list of places thatsearch()will check in each directory as it moves up the directory tree.
Each place is relative to the directory being searched, and the places are checked in the specified order.Defaultsearch_places:["pyproject.toml","pyproject.tml",f".{module_name}rc",f".{module_name}rc.json",f".{module_name}rc.yaml",f".{module_name}rc.yml",f".{module_name}rc.toml",f".{module_name}rc.tml",f".{module_name}rc.py",f".config/{module_name}rc",f".config/{module_name}rc.json",f".config/{module_name}rc.yaml",f".config/{module_name}rc.yml",f".config/{module_name}rc.toml",f".config/{module_name}rc.tml",f".config/{module_name}rc.py",f"{module_name}.config.py",]Create your own array to search more, fewer, or altogether different places.Every item insearch_placesneeds to have a loader inloadersthat corresponds to its extension.
(Common extensions are covered by default loaders.)
Read more aboutloadersbelow.pyproject.tomlandpyproject.tmlare special values: When they are included insearch_places, Cosmiconfig will always parse it as TOML and load a property within it, not the whole file.
That property is defined with thepackage_propoption, and defaults to your module name.Examples, with a module namedporgy:# Disallow extensions on rc files:["pyproject.toml",".porgyrc","porgy.config.py"]# Limit the options dramatically:["pyproject.toml",".porgyrc"]# Maybe you want to look for a wide variety of python flavors:["porgy.config.py","porgy.config.py3","porgy.config.py2",# ^^ You will need to designate custom loaders to tell# Cosmiconfig how to handle `.py2` and `.py3` files.]# Look within a .config/ subdirectory of every searched directory:["pyproject.toml",".porgyrc",".config/.porgyrc",".porgyrc.json",".config/.porgyrc.json"]loadersType:Dict[str, Loader].
Default: See below.A dictionary that maps extensions to the loader functions responsible for loading and parsing files with those extensions.Cosmiconfig exposes its default loaders on the named exportdefault_loaders.Defaultloaders:frompycosmiconfigimportdefault_loadersprint(default_loaders.items())# dict_items([#     ( '.py', <Function: load_py at ...> ),#     ( '.json', <Function: load_json at ...> ),#     ( '.yaml', <Function: load_yaml at ...> ),#     ( '.yml', <Function: load_yaml at ...> ),#     ( '.toml', <Function: load_toml at ...> ),#     ( '.tml', <Function: load_toml at ...> ),#     ( 'noExt', <Function: load_yaml at ...> ),# ])(YAML is a superset of JSON; which means YAML parsers can parse JSON; which is how extensionless files can be either YAMLorJSON with only one parser.)If you provide aloadersobject, your object will bemergedwith the defaults.So you can override one or two without having to override them all.Keys inloadersare extensions (starting with a period), ornoExtto specify the loader for fileswithoutextensions, like.myapprc.Values inloadersare a loader function (described below) whose values are loader functions.The most common use case for custom loaders value is to load extensionlessrcfiles as strict JSON, instead of JSONorYAML (the default).
To accomplish that, provide the followingloadersvalue:{"noExt":default_loaders[".json"];}If you want to load files that are not handled by the loader functions Cosmiconfig exposes, you can write a custom loader function or use one from PyPI if it exists.Third-party loaders:Do you know of third-party loaders? Open an issue or PR to have it added here.Use cases for custom loader function:Allow configuration syntaxes that aren't handled by Cosmiconfig's defaults, like JSON5, INI, or XML.Pre-process Python files before deriving the configuration.Custom loader functionshave the following signature:# Syncdefmy_loader(filepath:str,content:str)->Dict|None:...Cosmiconfig reads the file when it checks whether the file exists, so it will provide you with both the file's path and its content.
Do whatever you need to, and return either a configuration object orNone.Noneindicates that no real configuration was found and the search should continue.Examples:// Allow JSON5 syntax:{'.json':json5_loader}// Allow a special configuration syntax of your own creation:{'.special':special_loader}package_propType:str | List[str].
Default:`{module_name}`.Name of the property inpyproject.{toml,tml}to look for.package_propis prefixed withtool.when searching inpyproject.toml. So if you setpackage_propto"module_name", then cosmiconfig will search fortool.module_nameinpyproject.toml.Use a period-delimited string or an array of strings to describe a path to nested properties.For example, the value'my_package.configs.one'or['my_package', 'configs', 'one']will get you the"one"value in apyproject.tomllike this:[tool.poetry]...[tool.my_package]configs={one=1}Or this[tool.poetry]...[tool.my_package.configs]one=1If nested property names within the path include periods, you need to use an array of strings. For example, the value['my_package', 'configs', 'foo.bar', 'baz']will get you the"baz"value in apyproject.tomllike this:[tool.poetry]...[tool.my_package]configs={"foo.bar"={baz=2}}If a string includes period but corresponds to a top-level property name, it will not be interpreted as a period-delimited path. For example, the value'one.two'will get you the"three"value in apyproject.tomllike this:[tool.poetry]...tool."one.two"="three"[tool.one]two="four"stop_dirType:str.
Default: Absolute path to your home directory.Directory where the search will stop.cacheType:bool.
Default:True.IfFalse, no caches will be used.
Read more about"Caching"below.transformType:(Result) => Result.A function that transforms the parsed configuration. Receives theresult.The reason you might use this option — instead of simply applying your transform function some other way — is thatthe transformed result will be cached. If your transformation involves additional filesystem I/O or other potentially slow processing, you can use this option to avoid repeating those steps every time a given configuration is searched or loaded.ignore_empty_search_placesType:bool.
Default:True.By default, ifsearch()encounters an empty file (containing nothing but whitespace) in one of thesearch_places, it will ignore the empty file and move on.
If you'd like to load empty configuration files, instead, set this option toFalse.Why might you want to load empty configuration files?
If you want to throw an error, or if an empty configuration file means something to your program.Loading Python modulesThe defaultsearch_placesinclude.pyfiles. Python files MUST define aconfigtop-level variable. This way you don't have to worry about accidentally exposing imported modules and internal variables.Here is an example config file{my_module}.config.py:# Imports are not exposedimportos# This value is ignoredsome_value_read_from_os=os.name# Only this config variable will be exposed to Cosmiconfigconfig={"name":some_value_read_from_os,"indent":4}Cosmiconfig attempts to load Python file in two ways. First, it tries to loads the file as a module withimportlib.import_module. Hence, you should avoid naming your config files such that their names could conflict with standard python modules, or any packages you've installed, likejson.py,toml.py, etc.Ifimportlib.import_modulefails, then the.pyfile isloaded as a source file.CachingCosmiconfig uses caching to reduce the need for repetitious reading of the filesystem or expensive transforms. Every new cosmiconfig instance (created withcosmiconfig()) has its own caches.To avoid or work around caching, you can do the following:Set thecosmiconfigoptioncachetoFalse.Use the cache-clearing methodsclear_load_cache(),clear_search_cache(), andclear_caches().Create separate instances of cosmiconfig (separate "explorers").Usage for end usersWhen configuring a tool, you can use multiple file formats and put these in multiple places.Usually, a tool would mention this in its own README file,
but by default, these are the following places, where{NAME}represents the name of the tool:pyproject.toml
pyproject.tml
.{NAME}rc
.{NAME}rc.json
.{NAME}rc.yaml
.{NAME}rc.yml
.{NAME}rc.toml
.{NAME}rc.tml
.{NAME}rc.py
.config/{NAME}rc
.config/{NAME}rc.json
.config/{NAME}rc.yaml
.config/{NAME}rc.yml
.config/{NAME}rc.toml
.config/{NAME}rc.tml
.config/{NAME}rc.py
{NAME}.config.pyThe contents of these files are defined by the tool.
For example, you can configure prettier to enforce semicolons at the end of the line
using a file named.config/prettierrc.yml:semi:trueAdditionally, you have the option to put a property named after the tool in yourpyproject.tomlfile,
with the contents of that property being the same as the file contents.If the tool is named{NAME}, then the property inpyproject.tomlwill be prefixed withtool., so it becomestool.{NAME}:[tool.poetry]...[tool.my_package]config_val_a=1This has the advantage that you can put the configuration of all tools
(at least the ones that use cosmiconfig) in one file.Configure CosmiconfigYou can also add atool.pycosmiconfigkey within yourpyproject.tomlfile or add apycosmiconfigkey to one of the following files
to configurepycosmiconfigitself:.config.json
.config.yaml
.config.yml
.config.toml
.config.tml
.config.pyThe following property is currently actively supported in these places:pycosmiconfig:# overrides where configuration files are being searched to enforce a custom naming convention and formatsearch_places:-.config/{name}.ymlNote:Technically, you can overwrite all options described incosmiconfigOptionshere,
but everything not listed above should be used at your own risk, as it has not been tested explicitly.You can also add more root properties outside thepycosmiconfigproperty
to configure your tools, entirely eliminating the need to look for additional configuration files:pycosmiconfig:search_places:[]prettier:semi:trueContributing & DevelopmentPlease note that this project is released with aContributor Code of Conduct. By participating in this project you agree to abide by its terms.And please do participate!