config.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367
  1. from __future__ import annotations
  2. import errno
  3. import json
  4. import os
  5. import types
  6. import typing as t
  7. from werkzeug.utils import import_string
  8. if t.TYPE_CHECKING:
  9. import typing_extensions as te
  10. from .sansio.app import App
  11. T = t.TypeVar("T")
  12. class ConfigAttribute(t.Generic[T]):
  13. """Makes an attribute forward to the config"""
  14. def __init__(
  15. self, name: str, get_converter: t.Callable[[t.Any], T] | None = None
  16. ) -> None:
  17. self.__name__ = name
  18. self.get_converter = get_converter
  19. @t.overload
  20. def __get__(self, obj: None, owner: None) -> te.Self: ...
  21. @t.overload
  22. def __get__(self, obj: App, owner: type[App]) -> T: ...
  23. def __get__(self, obj: App | None, owner: type[App] | None = None) -> T | te.Self:
  24. if obj is None:
  25. return self
  26. rv = obj.config[self.__name__]
  27. if self.get_converter is not None:
  28. rv = self.get_converter(rv)
  29. return rv # type: ignore[no-any-return]
  30. def __set__(self, obj: App, value: t.Any) -> None:
  31. obj.config[self.__name__] = value
  32. class Config(dict): # type: ignore[type-arg]
  33. """Works exactly like a dict but provides ways to fill it from files
  34. or special dictionaries. There are two common patterns to populate the
  35. config.
  36. Either you can fill the config from a config file::
  37. app.config.from_pyfile('yourconfig.cfg')
  38. Or alternatively you can define the configuration options in the
  39. module that calls :meth:`from_object` or provide an import path to
  40. a module that should be loaded. It is also possible to tell it to
  41. use the same module and with that provide the configuration values
  42. just before the call::
  43. DEBUG = True
  44. SECRET_KEY = 'development key'
  45. app.config.from_object(__name__)
  46. In both cases (loading from any Python file or loading from modules),
  47. only uppercase keys are added to the config. This makes it possible to use
  48. lowercase values in the config file for temporary values that are not added
  49. to the config or to define the config keys in the same file that implements
  50. the application.
  51. Probably the most interesting way to load configurations is from an
  52. environment variable pointing to a file::
  53. app.config.from_envvar('YOURAPPLICATION_SETTINGS')
  54. In this case before launching the application you have to set this
  55. environment variable to the file you want to use. On Linux and OS X
  56. use the export statement::
  57. export YOURAPPLICATION_SETTINGS='/path/to/config/file'
  58. On windows use `set` instead.
  59. :param root_path: path to which files are read relative from. When the
  60. config object is created by the application, this is
  61. the application's :attr:`~flask.Flask.root_path`.
  62. :param defaults: an optional dictionary of default values
  63. """
  64. def __init__(
  65. self,
  66. root_path: str | os.PathLike[str],
  67. defaults: dict[str, t.Any] | None = None,
  68. ) -> None:
  69. super().__init__(defaults or {})
  70. self.root_path = root_path
  71. def from_envvar(self, variable_name: str, silent: bool = False) -> bool:
  72. """Loads a configuration from an environment variable pointing to
  73. a configuration file. This is basically just a shortcut with nicer
  74. error messages for this line of code::
  75. app.config.from_pyfile(os.environ['YOURAPPLICATION_SETTINGS'])
  76. :param variable_name: name of the environment variable
  77. :param silent: set to ``True`` if you want silent failure for missing
  78. files.
  79. :return: ``True`` if the file was loaded successfully.
  80. """
  81. rv = os.environ.get(variable_name)
  82. if not rv:
  83. if silent:
  84. return False
  85. raise RuntimeError(
  86. f"The environment variable {variable_name!r} is not set"
  87. " and as such configuration could not be loaded. Set"
  88. " this variable and make it point to a configuration"
  89. " file"
  90. )
  91. return self.from_pyfile(rv, silent=silent)
  92. def from_prefixed_env(
  93. self, prefix: str = "FLASK", *, loads: t.Callable[[str], t.Any] = json.loads
  94. ) -> bool:
  95. """Load any environment variables that start with ``FLASK_``,
  96. dropping the prefix from the env key for the config key. Values
  97. are passed through a loading function to attempt to convert them
  98. to more specific types than strings.
  99. Keys are loaded in :func:`sorted` order.
  100. The default loading function attempts to parse values as any
  101. valid JSON type, including dicts and lists.
  102. Specific items in nested dicts can be set by separating the
  103. keys with double underscores (``__``). If an intermediate key
  104. doesn't exist, it will be initialized to an empty dict.
  105. :param prefix: Load env vars that start with this prefix,
  106. separated with an underscore (``_``).
  107. :param loads: Pass each string value to this function and use
  108. the returned value as the config value. If any error is
  109. raised it is ignored and the value remains a string. The
  110. default is :func:`json.loads`.
  111. .. versionadded:: 2.1
  112. """
  113. prefix = f"{prefix}_"
  114. for key in sorted(os.environ):
  115. if not key.startswith(prefix):
  116. continue
  117. value = os.environ[key]
  118. key = key.removeprefix(prefix)
  119. try:
  120. value = loads(value)
  121. except Exception:
  122. # Keep the value as a string if loading failed.
  123. pass
  124. if "__" not in key:
  125. # A non-nested key, set directly.
  126. self[key] = value
  127. continue
  128. # Traverse nested dictionaries with keys separated by "__".
  129. current = self
  130. *parts, tail = key.split("__")
  131. for part in parts:
  132. # If an intermediate dict does not exist, create it.
  133. if part not in current:
  134. current[part] = {}
  135. current = current[part]
  136. current[tail] = value
  137. return True
  138. def from_pyfile(
  139. self, filename: str | os.PathLike[str], silent: bool = False
  140. ) -> bool:
  141. """Updates the values in the config from a Python file. This function
  142. behaves as if the file was imported as module with the
  143. :meth:`from_object` function.
  144. :param filename: the filename of the config. This can either be an
  145. absolute filename or a filename relative to the
  146. root path.
  147. :param silent: set to ``True`` if you want silent failure for missing
  148. files.
  149. :return: ``True`` if the file was loaded successfully.
  150. .. versionadded:: 0.7
  151. `silent` parameter.
  152. """
  153. filename = os.path.join(self.root_path, filename)
  154. d = types.ModuleType("config")
  155. d.__file__ = filename
  156. try:
  157. with open(filename, mode="rb") as config_file:
  158. exec(compile(config_file.read(), filename, "exec"), d.__dict__)
  159. except OSError as e:
  160. if silent and e.errno in (errno.ENOENT, errno.EISDIR, errno.ENOTDIR):
  161. return False
  162. e.strerror = f"Unable to load configuration file ({e.strerror})"
  163. raise
  164. self.from_object(d)
  165. return True
  166. def from_object(self, obj: object | str) -> None:
  167. """Updates the values from the given object. An object can be of one
  168. of the following two types:
  169. - a string: in this case the object with that name will be imported
  170. - an actual object reference: that object is used directly
  171. Objects are usually either modules or classes. :meth:`from_object`
  172. loads only the uppercase attributes of the module/class. A ``dict``
  173. object will not work with :meth:`from_object` because the keys of a
  174. ``dict`` are not attributes of the ``dict`` class.
  175. Example of module-based configuration::
  176. app.config.from_object('yourapplication.default_config')
  177. from yourapplication import default_config
  178. app.config.from_object(default_config)
  179. Nothing is done to the object before loading. If the object is a
  180. class and has ``@property`` attributes, it needs to be
  181. instantiated before being passed to this method.
  182. You should not use this function to load the actual configuration but
  183. rather configuration defaults. The actual config should be loaded
  184. with :meth:`from_pyfile` and ideally from a location not within the
  185. package because the package might be installed system wide.
  186. See :ref:`config-dev-prod` for an example of class-based configuration
  187. using :meth:`from_object`.
  188. :param obj: an import name or object
  189. """
  190. if isinstance(obj, str):
  191. obj = import_string(obj)
  192. for key in dir(obj):
  193. if key.isupper():
  194. self[key] = getattr(obj, key)
  195. def from_file(
  196. self,
  197. filename: str | os.PathLike[str],
  198. load: t.Callable[[t.IO[t.Any]], t.Mapping[str, t.Any]],
  199. silent: bool = False,
  200. text: bool = True,
  201. ) -> bool:
  202. """Update the values in the config from a file that is loaded
  203. using the ``load`` parameter. The loaded data is passed to the
  204. :meth:`from_mapping` method.
  205. .. code-block:: python
  206. import json
  207. app.config.from_file("config.json", load=json.load)
  208. import tomllib
  209. app.config.from_file("config.toml", load=tomllib.load, text=False)
  210. :param filename: The path to the data file. This can be an
  211. absolute path or relative to the config root path.
  212. :param load: A callable that takes a file handle and returns a
  213. mapping of loaded data from the file.
  214. :type load: ``Callable[[Reader], Mapping]`` where ``Reader``
  215. implements a ``read`` method.
  216. :param silent: Ignore the file if it doesn't exist.
  217. :param text: Open the file in text or binary mode.
  218. :return: ``True`` if the file was loaded successfully.
  219. .. versionchanged:: 2.3
  220. The ``text`` parameter was added.
  221. .. versionadded:: 2.0
  222. """
  223. filename = os.path.join(self.root_path, filename)
  224. try:
  225. with open(filename, "r" if text else "rb") as f:
  226. obj = load(f)
  227. except OSError as e:
  228. if silent and e.errno in (errno.ENOENT, errno.EISDIR):
  229. return False
  230. e.strerror = f"Unable to load configuration file ({e.strerror})"
  231. raise
  232. return self.from_mapping(obj)
  233. def from_mapping(
  234. self, mapping: t.Mapping[str, t.Any] | None = None, **kwargs: t.Any
  235. ) -> bool:
  236. """Updates the config like :meth:`update` ignoring items with
  237. non-upper keys.
  238. :return: Always returns ``True``.
  239. .. versionadded:: 0.11
  240. """
  241. mappings: dict[str, t.Any] = {}
  242. if mapping is not None:
  243. mappings.update(mapping)
  244. mappings.update(kwargs)
  245. for key, value in mappings.items():
  246. if key.isupper():
  247. self[key] = value
  248. return True
  249. def get_namespace(
  250. self, namespace: str, lowercase: bool = True, trim_namespace: bool = True
  251. ) -> dict[str, t.Any]:
  252. """Returns a dictionary containing a subset of configuration options
  253. that match the specified namespace/prefix. Example usage::
  254. app.config['IMAGE_STORE_TYPE'] = 'fs'
  255. app.config['IMAGE_STORE_PATH'] = '/var/app/images'
  256. app.config['IMAGE_STORE_BASE_URL'] = 'http://img.website.com'
  257. image_store_config = app.config.get_namespace('IMAGE_STORE_')
  258. The resulting dictionary `image_store_config` would look like::
  259. {
  260. 'type': 'fs',
  261. 'path': '/var/app/images',
  262. 'base_url': 'http://img.website.com'
  263. }
  264. This is often useful when configuration options map directly to
  265. keyword arguments in functions or class constructors.
  266. :param namespace: a configuration namespace
  267. :param lowercase: a flag indicating if the keys of the resulting
  268. dictionary should be lowercase
  269. :param trim_namespace: a flag indicating if the keys of the resulting
  270. dictionary should not include the namespace
  271. .. versionadded:: 0.11
  272. """
  273. rv = {}
  274. for k, v in self.items():
  275. if not k.startswith(namespace):
  276. continue
  277. if trim_namespace:
  278. key = k[len(namespace) :]
  279. else:
  280. key = k
  281. if lowercase:
  282. key = key.lower()
  283. rv[key] = v
  284. return rv
  285. def __repr__(self) -> str:
  286. return f"<{type(self).__name__} {dict.__repr__(self)}>"