配置系统 (astropy.config ）

介绍

Astropy配置系统旨在让用户控制Astropy或附属软件包中使用的各种参数，而无需深入研究源代码进行这些更改。

注解

配置系统在年进行了一次大修 astropy 0.4作为APE3的一部分。看到了吗 配置转换 有关更新代码以使用新API的信息。

入门

Astropy配置选项最方便的设置方式是修改配置文件。当你第一次导入Astropy时，它将自动生成所有的默认值。您可以通过以下操作找到确切位置：

>>> from astropy.config import get_config_dir
>>> get_config_dir()

你应该看到你的配置目录的位置。标准方案通常将您的配置目录放在 $HOME/.astropy/config . 可以使用环境变量进行自定义 XDG_CONFIG_HOME 以及 $XDG_CONFIG_HOME/astropy 目录必须存在。请注意 XDG_CONFIG_HOME 来自以Linux为中心的规范（请参见 here 但Astropy将在任何操作系统上使用此方法作为一种更通用的方法来了解用户特定的配置应该写在哪里。

注解

见 Astropy的默认配置文件 此配置文件的内容。

找到配置文件后，用您最喜欢的编辑器打开它。它应该包含您可能需要的所有部分，包括描述和接受的值类型。你可以随意编辑它，任何这些改变都会在你下一次开始Astropy时被反映出来。或者，如果你想在你当前的Astropy会话中立即看到你的变化，请：

>>> from astropy.config import reload_config
>>> reload_config()

注解

无论出于什么原因 $HOME/.astropy 目录不可访问（即 astropy 以根用户身份运行，但您不是root用户），最好的解决方案是设置 XDG_CONFIG_HOME 和 XDG_CACHE_HOME 指向目录的环境变量，并创建 astropy 每个目录里面都有。然后，配置和数据下载系统都将使用这些目录，并且从不尝试访问 $HOME/.astropy 目录。

使用 astropy.config

访问值

按照惯例，配置参数位于名为 conf 在每个子包的根目录下。例如，与数据文件相关的配置参数位于 astropy.utils.data.conf . 此对象具有用于获取和设置单个配置参数的属性。例如，获取 astropy 远程数据，do:：

>>> from astropy.utils.data import conf
>>> conf.dataurl
'http://data.astropy.org/'

在运行时更改值

通过如上所述编辑配置文件来更改配置值的持久状态。但是，也可以在活动Python会话中通过设置 conf 对象。

例子

如果配置文件的一部分如下所示：

[utils.data]

# URL for astropy remote data site.
dataurl = http://data.astropy.org/

# Time to wait for remote data query (in seconds).
remote_timeout = 3.0

您应该能够通过以下方式在运行时修改值：

>>> from astropy.utils.data import conf
>>> conf.dataurl
'http://data.astropy.org/'
>>> conf.dataurl = 'http://astropydata.mywebsite.com'
>>> conf.dataurl
'http://astropydata.mywebsite.com'
>>> conf.remote_timeout
3.0
>>> conf.remote_timeout = 4.5
>>> conf.remote_timeout
4.5

重新加载配置

您也可以修改配置文件，然后重新加载，而不是修改Python中的变量。

例子

如果将配置文件修改为：

[utils.data]

# URL for astropy remote data site.
dataurl = http://myotherdata.mywebsite.com/

# Time to wait for remote data query (in seconds).
remote_timeout = 6.3

然后运行以下命令：

>>> conf.reload('dataurl')
>>> conf.reload('remote_timeout')

这将使用配置文件中的值更新变量：

>>> conf.dataurl
'http://myotherdata.mywebsite.com/'
>>> conf.remote_timeout
6.3

可以重新加载 conf 通过调用 reload 无参数：

>>> conf.reload()

或者如果你想一次重新加载所有的Astropy配置，使用 reload_config 功能：

>>> from astropy import config
>>> config.reload_config('astropy')

也可以将配置参数重置回其默认值。注意，这是Python代码中定义的默认值，与磁盘上的配置文件无关：

>>> conf.reset('dataurl')
>>> conf.dataurl
'http://data.astropy.org/'

正在探索配置

查看为给定的 conf ：：

>>> from astropy.utils.iers import conf
>>> [key for key in conf]
['auto_download',
 'auto_max_age',
 ...,
 'ietf_leap_second_auto_url']
>>> conf.auto_max_age
30.0

您也可以迭代 conf 像字典一样：

>>> [key for key in conf.keys()]
['auto_download',
 'auto_max_age',
 ...,
 'ietf_leap_second_auto_url']
>>> [cfgitem for cfgitem in conf.values()]
[<ConfigItem: name='auto_download' value=True at ...>,
 <ConfigItem: name='auto_max_age' value=30.0 at ...>,
 ...,
 <ConfigItem: name='ietf_leap_second_auto_url' value=...>]
>>> for (key, cfgitem) in conf.items():
...     if key == 'auto_max_age':
...         print(f'{cfgitem.description} Value is {cfgitem()}')
Maximum age (days) of predictive data before auto-downloading. Default is 30. Value is 30.0

升级 astropy

每次升级到新的主版本时 astropy ，配置参数可能已更改。

如果您从未编辑过配置文件，您就没有什么可做的了。它将自动替换为新安装版本的配置文件模板 astropy .

如果您定制了您的配置文件，它将不会被触摸。相反，一个新的配置文件模板将与文件名中的版本号一起安装 astropy.0.4.cfg . 您可以将此文件与 astropy.cfg 文件以查看需要更改或更新的内容。

添加新配置项

如果需要与系统配置绑定的选项或设置，或者应该在 astropy 或者一个附属的包裹。可能影响科学计算结果的选项不应该是配置项，而应该是配置项 astropy.utils.state.ScienceState 因此，可以在不受特定环境中设置的配置参数影响的情况下重现科学结果。诚然，这仅仅是一个指导原则，因为在某些情况下，配置项优于某个函数的关键字选项在某种程度上是个人偏好。但是，它是持久配置的首选形式，并且 astropy 所有的软件包都必须使用它（建议附属软件包使用）。

下面的参考指南描述了创建 conf 具有多个配置参数的对象。它们应该在顶层定义（即 __init__.py 包含配置项的每个子包）：：

""" This is the docstring at the beginning of a module
"""
from astropy import config as _config

class Conf(_config.ConfigNamespace):
    """
    Configuration parameters for my subpackage.
    """
    some_setting = _config.ConfigItem(
        1, 'Description of some_setting')
    another_setting = _config.ConfigItem(
        'string value', 'Description of another_setting')
# Create an instance for the user
conf = Conf()

... implementation ...
def some_func():
    #to get the value of these options, I might do:
    something = conf.some_setting + 2
    return conf.another_setting + ' Also, I added text.'

配置项还需要添加到配置文件模板中。为 astropy ，此文件位于 astropy/astropy.cfg . 例如，对于一个名为， packagename ，文件位于 packagename/packagename.cfg . 对于上面的示例，以下内容将添加到配置文件模板中：

[subpackage]
## Description of some_setting
# some_setting = 1

## Description of another_setting
# another_setting = foo

请注意，键/值对被注释掉了。这将允许在将来的版本中更改默认值 astropy 不需要用户编辑他们的配置文件来利用新的默认值。按照惯例，每个参数的描述都在注释行中，以两个哈希字符开头 (## )将它们与注释掉的键/值对区分开。

项目类型和验证

如果未另行规定，则 ConfigItem 从 defaultvalue 它是在创建时给出的。该项只能设置为此类型的对象。因此：

some_setting = ConfigItem(1, 'A description.')
...
conf.some_setting = 1.2

会失败，因为 1.2 是漂浮物 1 是一个整数。

请注意，如果您希望配置项仅限于一组特定的选项，则应将一个列表作为 defaultvalue 选项。列表中的第一个条目将被视为默认值，列表作为一个整体给出了所有有效的选项。例如：：

an_option = ConfigItem(
    ['a', 'b', 'c'],
    "This option can be 'a', 'b', or 'c'")
...
conf.an_option = 'b'  # succeeds
conf.an_option = 'c'  # succeeds
conf.an_option = 'd'  # fails!
conf.an_option = 6    # fails!

最后，A ConfigItem 可以通过 cfgtype 选项：

an_int_setting = ConfigItem(
    1, 'A description.', cfgtype='integer')
...
conf.an_int_setting = 3     # works fine
conf.an_int_setting = 4.2   # fails!

如果默认值的类型不匹配 cfgtype , the ConfigItem 无法创建：：

an_int_setting = ConfigItem(
    4.2, 'A description.', cfgtype='integer')

总之，默认行为（自动确定 cfgtype )通常是你想要的。主要的例外是当您希望您的配置项是一个列表时。默认行为将把它视为 选项 除非你明确告诉它 ConfigItem 它本身应该是一个列表：

a_list_setting = ConfigItem([1, 2, 3], 'A description.')

a_list_setting = ConfigItem([1, 2, 3], 'A description.', cfgtype='list')

所有有效的 cfgtype 项目可以在 validation section of the configobj manual . 下面是有效值的列表，供快速参考：

• '整数'

• “飘浮”

• '布尔值'

• “弦”

• 'ip_addr'

• '列表'

• '元组'

• 'int_list'

• 'float_list'

• 'bool_list'

• 'string_list'

• 'ip_addr_list'

• 'mixed_list'

• '选项'

• '通过'

使用提示

记住 ConfigItem 用户可以在运行时更改对象。因此，建议在使用前立即读取它们的值，而不是将它们的初始值存储到其他变量（或用作函数的默认值）。例如，下面的用法是正确的：

def some_func(val=conf.some_setting):
    return val + 2

只要用户在运行时不更改它的值，这种方法就可以正常工作，但是如果用户更改了，函数将不知道该更改：

>>> some_func()
3
>>> conf.some_setting = 3
>>> some_func()  # naively should return 5, because 3 + 2 = 5
3

有两种方法可以解决这个问题。典型/预期的方式是：

def some_func():
    """
    The `SOME_SETTING` configuration item influences this output
    """
    return conf.some_setting + 2

或者，如果选项需要作为函数参数使用：

def some_func(val=None):
    """
    If not specified, `val` is set by the `SOME_SETTING` configuration item.
    """
    return (conf.some_setting if val is None else val) + 2

在关联包中自定义配置

这个 astropy.config 包可以被其他包使用。默认情况下，在另一个包中创建配置对象将导致配置文件使用 astropy 配置目录（即。， <astropy_config>/packagename.cfg ）

可以配置此行为，以便为包创建自定义配置目录，例如， ~/.packagename/packagename.cfg . 为此，创建一个 packagename.config 分装并将以下内容放入 __init__.py 文件：：

import astropy.config as astropyconfig


class ConfigNamespace(astropyconfig.ConfigNamespace):
    rootname = 'packagename'


class ConfigItem(astropyconfig.ConfigItem):
    rootname = 'packagename'

然后替换所有导入的 astropy.config 具有 packagename.config .

也见

• Astropy的默认配置文件
• 配置转换
  • 为用户
  • 对于附属软件包作者

日志系统 （概述 astropy.logger ）

参考/API

astropy.config文件包裹

此模块包含Astropy项目的配置和设置实用程序。这包括与关联的包索引相关的所有功能。

功能

create_config_file \(Pkg[, rootname, overwrite] )	创建指定包的默认配置文件。
generate_config \ [pkgname, filename, verbose] ）	从列表中生成配置文件 ConfigItem 每个子包的对象。
get_cache_dir \ [rootname] ）	确定Astropy缓存目录名，并在目录不存在时创建该目录。
get_config \ [packageormod, reload, rootname] ）	获取与特定包或模块关联的配置对象或节。
get_config_dir \ [rootname] ）	确定包配置目录名，并在目录不存在时创建该目录。
reload_config \ [packageormod, rootname] ）	从所请求包/模块的根包的配置文件中重新加载配置设置。

Classes

ConfigItem \ [defaultvalue, description, ...] ）	存储在配置文件中的一种设置和相关联的值。
ConfigNamespace （）	配置项的命名空间。
ConfigurationMissingWarning	当无法访问配置目录（通常是由于权限问题）时发出的警告。
InvalidConfigurationItemWarning	当astropy配置文件中指定的配置值与该配置值的预期类型不匹配时发出的警告。
set_temp_cache \ [path, delete] ）	Context manager为Astropy下载缓存设置临时路径，主要用于测试（尽管可能还有其他应用程序用于设置不同的缓存目录，例如切换到专用于大文件的缓存）。
set_temp_config \ [path, delete] ）	上下文管理器为Astropy配置设置临时路径，主要用于测试。

类继承图