HDX Python库
hdx-python-api的Python项目详细描述
hdx python库的设计使您能够轻松地开发与人道主义数据交互的代码。 Exchange（HDX）平台。图书馆的主要目标是推送和拉取数据 从hdx尽可能简单的最终用户。如果您有与人道主义有关的数据，请将您的数据集上载到 HDX.
欲了解更多目的和设计理念，请访问 hdx python库
用法
库中有详细的api文档，可以找到 这里：http://ocha-dap.github.io/hdx-python-api/。的代码 库在这里：https://github.com/ocha-dap/hdx-python-api
中断更改
从3.7.3开始，add_tag、add_tags和clean_tags的返回类型现在是tuple[list[str]，list[str]] （包含已添加标记列表和已删除标记列表以及未添加标记的元组）。
从3.7.1开始，标签列表必须来自此批准列表
开始
获取API密钥
如果您只想从hdx读取数据，那么不需要api密钥，您可以忽略下面的6个步骤。然而， 如果要将数据写入hdx，则需要在网站上注册以获取api密钥。你可以提供这个 键作为参数或创建API键文件。如果您创建了一个api密钥文件，默认情况下，这被假定为 .hdxkey位于当前用户的主目录中。假设您使用的是桌面浏览器，则 API密钥的获取者：
浏览到HDX网站
如果未登录，请左键单击网页右上角的"登录"并登录
在网页右上角的用户名上单击鼠标左键，然后从下拉菜单中选择"配置文件"
向下滚动到个人资料页的底部
复制API密钥，其格式为：xxxx xxxx-xxxx-xxxx-xxxx-xxxxxxxx
您可以：
a.将此键作为参数或在字典中传递
b.创建一个json或yaml文件。默认路径是 .hdx_configuration.yml在当前用户的主页中 目录。然后放入yaml文件：
hdx_key: "HDX API KEY"< > >如果您只想从hdx读取数据，则不需要api密钥。但是，如果要将数据写入HDX， 然后您需要在网站上注册才能获得api密钥。请看上面关于在哪里找到它的网站。 一旦你有了它，就把它放到主目录中的一个文件中：
cd ~ echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml如果您正在使用Docker映像，则可以跳到步骤6，否则如果未安装，请安装Virtualenv：
pip install virtualenv在某些Linux发行版上，您可以执行以下操作，而不是从发行版的官方 存储库：
sudo apt-get install virtualenv创建一个python 3 virtualenv并激活它：
在windows上（假设python 3可执行文件在您的路径中）：
virtualenv test test\Scripts\activate在其他操作系统上：
virtualenv -p python3 test source test/bin/activate安装hdx python库：
pip install hdx-python-api如果出现错误，可能是密码包的依赖项
启动python:
0hdx_key: "HDX API KEY"导入所需类：
1hdx_key: "HDX API KEY"设置日志记录
2hdx_key: "HDX API KEY"使用默认配置。
如果您只想读取数据，请连接到生产HDX 服务器：
3hdx_key: "HDX API KEY"如果你想写数据，那么为了实验，不要使用 生产HDX服务器。相反，您可以使用其中一个测试服务器。 假设有一个api密钥存储在 当前用户的主目录：
4hdx_key: "HDX API KEY"读取此数据集 1997-2016年非洲的acled冲突数据 从hdx并查看数据集的日期：
5hdx_key: "HDX API KEY"如果您有一个api密钥，作为测试，请更改数据集日期：
6hdx_key: "HDX API KEY"您可以在HDX上查看它，然后再将其更改回来（如果您有API密钥）：
7hdx_key: "HDX API KEY"您可以在HDX上搜索数据集并获取其资源：
8hdx_key: "HDX API KEY"您可以在数据集中下载资源：
9hdx_key: "HDX API KEY"退出并删除virtualenv:
0hdx-python-api==VERSION在Windows上：
1hdx-python-api==VERSION在其他操作系统上：
2hdx-python-api==VERSION< > >填充参数用户代理（可以是项目的名称）
提供用户代理配置yaml，它应该指向包含参数的yaml文件。
提供应指向yaml文件并填充用户代理查找的用户代理配置yaml 要在yaml文件中查找的密钥，其格式应为：
7hdx-python-api==VERSION在下表中列出的配置字典或文件中包括用户代理。 hdx配置json或项目配置dict
< > >
安装库
要在项目中包含hdx python库，必须pip install或添加到requirements.txt文件中 以下行：
hdx-python-api==VERSION
用https://github.com/ocha-dap/hdx-python-api/tags" rel="nofollow">https://github.com/ocha-dap/hdx-python-api/tags中提供的最新标记替换版本。
如果出现依赖项错误，则可能是缺少加密包的依赖项，例如 ubuntu:python dev、libffi dev和libssl-dev。请参阅 加密依赖项
如果出现导入或其他错误，请在使用virtualenv时重新创建，或者卸载 使用pip uninstall的hdx python api、hdx python country和hdx python实用程序，然后安装hdx python api 将拉入其他依赖项）。
码头工人
该库也可以在Docker图像中设置和准备就绪：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
一个简单的例子
让我们从一个简单的示例开始，该示例还可以确保库正常工作。在本教程中，我们使用 virtualenv，一个沙箱，这样您的python安装就不会被修改。
建设项目
立面的默认配置
最简单的开始方法是使用外观和配置默认值。门面设置了伐木和 HDX配置。
默认配置加载库中的内部hdx配置，并假设 当前用户主目录中名为.hdxkey的api密钥文件，以及位于 相对于您必须创建的位于config/project_configuration.yml的工作目录。项目 配置用于特定于项目的任何配置。
默认日志记录配置读取设置彩色控制台的库内部的配置文件 处理程序在调试级别输出，文件处理程序在错误级别写入errors.log。
正面
简单的门面使安装和运行变得更容易：
hdx-python-api==VERSION
keyword arguments facade是相似的，但是传递的是keyword arguments:
hdx-python-api==VERSION
定制配置
必须在facade调用中传递配置参数，例如
hdx-python-api==VERSION
如果不使用facade，可以直接使用配置类的create方法，传入 适当的关键字参数，例如。
hdx-python-api==VERSION
必须使用以下方法之一提供用户代理：
关键字参数可以是：
<表><广告>要访问配置，可以使用配置类的read方法，如下所示：
hdx-python-api==VERSION
对于更高级的用户，有一些方法允许您传入自己的配置对象remote ckan对象 以及有效位置列表。有关详细信息，请参阅API文档。
库默认使用此全局配置，但可以由传递到的配置实例替换 像dataset这样的hdx对象的构造函数，例如
hdx-python-api==VERSION
配置日志记录
如果要更改默认日志记录配置，则需要使用 参数，除非您使用了simple或scraperwiki facades，在这种情况下，您必须更新hdx.facades 模块变量在导入facade之前记录千瓦数。
如果不使用门面：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
如果使用门面：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
关键字参数可以是：
<表><广告>字典
日志配置
日志配置
日志配置.yml
配置字典
日志配置
日志配置
除非使用默认值，否则不要提供smtp-config-dict、smtp-config-json或smtp-config-yaml。 日志配置！
如果使用的是默认日志记录配置，则可以选择使用发送 如果发生严重错误，请通过提供smtp-config-dict，smtp-config-json或 smtp配置文件。下面是一个yaml文件的模板，可以作为smtp-config\u yaml参数传递：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
除非重写，否则默认smtp处理程序的邮件服务器mailhost是localhost和from地址 fromaddr是<；noreply@localhost>；
要在文件中使用日志记录，只需在每个python文件的顶部添加以下行：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
然后像这样使用记录器：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
HDX对象上的操作
可以使用静态的read-from-hdx方法读取现有的hdx对象，该方法接受一个标识符参数和 根据对象是否为 已阅读，例如
αααα35您可以使用带查询参数和 返回适当HDX对象类型的对象列表，例如列表[数据集]。下面是一个示例：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
查询参数采用不同的格式，具体取决于它是否用于 数据集 或一个 资源。 资源级搜索仅限于资源中的字段，因此在大多数情况下，最好搜索 然后获取它们的资源。
可以提供各种附加参数（**kwargs）。这些在api文档中有详细说明。行
数据集参数（资源限制）是返回的最大匹配数，默认情况下是所有匹配项。
可以通过调用构造函数来创建hdx对象，如数据集、资源、展示、组织或用户 使用包含元数据的可选字典。例如：
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
数据集名称不应包含特殊字符，因此如果有可能，则需要 泥泞化的slugifying是使字符串在url中有效的方法（例如，ae替换228）。有很多种 可以做到这一点的软件包，例如：python slugify
您可以使用标准的python字典方括号添加元数据，例如。
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
您也可以通过标准dictionaryupdate方法来执行此操作，该方法接受一个dictionary例如。
docker pull mcarans/hdx-python-api
docker run -i -t mcarans/hdx-python-api:latest python3
最好从文件中添加更多的静态元数据。yaml是很容易理解和推荐的，而json是 也可接受，例如
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
未指定的默认路径是config/hdx_type_static.yml对于yaml和config/hdx_type_static.json对于 json，其中type是hdx对象的类型，如dataset或resource，例如config/hdx_showcase_static.json。YAML 文件格式如下：
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
注意如何在文件中定义资源（每个资源以短划线"-"开头），如上图所示。
您可以通过调用check_required_fields来检查是否填充了hdx所需的所有字段。这将抛出 如果缺少任何字段，则为异常。在库将数据发布到hdx之前，它将自动调用此方法。 您可以在检查中提供要忽略的字段列表。示例用法：
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
一旦hdx对象准备好了，即它拥有所有必需的元数据，您只需调用create_in_hdx例如
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
可以通过调用hdx中的update来更新现有的hdx对象。
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
您可以使用从hdx中删除hdx对象，并使用方法更新hdx中已经存在的对象。 在HDX中更新。它们采用各种布尔参数，这些参数都有默认值，并记录在api文档中。 它们不会返回任何内容，并且会抛出异常，以防出现诸如要更新的对象不存在之类的故障。
数据集特定操作
数据集可以包含资源，也可以位于展示区中。
如果要添加资源，可以提供一个列表并调用"添加更新资源"功能，例如：
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
调用add_update_resources在数据集中创建hdx资源对象列表，可以对其执行操作 那些东西。
要查看资源列表，请使用获取资源功能，例如
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
如果要添加一个资源，可以提供一个id字符串、字典或资源对象，并调用 添加"更新"资源*；函数，例如：
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
您可以使用"删除资源"函数从数据集中删除资源对象，例如：
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
您可以从数据集列表中获取所有资源，如下所示：
cd ~
echo "hdx_key: \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"" > .hdx_configuration.yml
要查看数据集所在的显示案例列表，请使用获取显示案例函数，例如
pip install virtualenv
如果要将数据集添加到Showcase，则必须首先在HDX中创建该Showcase（如果它不存在）：
pip install virtualenv
然后，您可以提供一个id、dictionary或showcase对象，并调用add_u showcase函数，例如：
pip install virtualenv
您可以使用remove_u showcase函数从Showcase中删除数据集，例如：
pip install virtualenv
数据集日期
数据集日期是HDX中的必需字段。此日期是数据集中数据的日期，不要与 上次在数据集中添加/更改数据时。它可以是单个日期或范围。
要确定数据集日期是单个日期还是范围，可以调用：
pip install virtualenv
它返回单个日期的"日期"或日期范围的"范围"。
要以字符串形式获取范围或单个日期的数据集开始日期，可以执行以下操作。你可以提供 日期格式。如果没有，输出 格式为ISO 8601日期2007-01-25。
pip install virtualenv
要获取范围的数据集结束日期，请调用：
pip install virtualenv
若要设置数据集日期，请为某个范围传递开始日期和结束日期，或仅为单个日期传递开始日期。如果你 不提供任何日期格式，该方法将尝试猜测，对于明确的格式，哪种格式应该是正确的。
pip install virtualenv
要将数据集日期或范围检索为datetime.datetime对象，可以执行以下操作：
pip install virtualenv
下面的方法允许您使用datetime.datetime对象设置数据集的日期：
pip install virtualenv
预期更新频率
hdx数据集有一个强制字段，即预期的更新频率。这是您对数据集的频率的最佳猜测 将被更新。
HDX Web界面使用设置的频率：
sudo apt-get install virtualenv
尽管api允许更大的粒度（几天），但是我们鼓励您使用上面的选项 （尽可能避免使用从不）。为了帮助您做到这一点，您可以使用允许这样做的方法。
以下方法将返回与hdx中显示的内容相对应的文本预期更新频率 网络界面。
sudo apt-get install virtualenv
下面的方法允许您使用上面设置的频率之一设置数据集的预期更新频率。（IT） 也允许您以字符串或整数形式传递天数，但不鼓励这样做。）
sudo apt-get install virtualenv
有效更新频率的列表可以使用：
sudo apt-get install virtualenv
使用此功能可以实现表示之间的前后转换：
sudo apt-get install virtualenv
位置
每个HDX数据集必须至少有一个与其关联的位置。
如果要获取当前位置（ISO 3国家/地区代码），可以调用下面的方法：
sudo apt-get install virtualenv
如果要添加一个国家，请按如下所示操作。如果您没有提供ISO3国家代码，您提供的文本将 如果是有效的国家名称，则被解析并转换为ISO 3代码。
sudo apt-get install virtualenv
如果要添加国家列表，可以使用以下方法进行添加。如果你不提供iso 3国家 代码，转换将在找到有效国家/地区名称的地方进行。
sudo apt-get install virtualenv
如果要添加区域，请执行以下操作。如果你不提供三位数 unstats m49区域代码，然后解析和转换将 如果提供了有效的区域名，则发生此错误。
sudo apt-get install virtualenv
<强>dd_region_location接受 unstats m49网站。
如果要添加任何其他类型的位置（必须位于 有效位置列表，您可以按如下所示进行操作。
sudo apt-get install virtualenv
标记
HDX数据集可以有帮助人们找到它们的标签，例如"公共操作数据集-COD"、"难民"。 这些标记来自一组预定义的已批准标记。在中断中有一个指向已批准标记列表的链接 更改前面的部分。如果添加的标记不在核准列表中，库将尝试将它们映射到 基于标记映射的电子表格批准的标记。
如果要获取当前标记，可以使用以下方法：
virtualenv test
test\Scripts\activate
如果要添加标记，请按如下方式进行：
virtualenv test
test\Scripts\activate
如果要添加标记列表，请按以下步骤操作：
virtualenv test
test\Scripts\activate
要获取预定义的已批准标记集：
virtualenv test
test\Scripts\activate
维护人员
HDX数据集必须有维护人员。
如果您希望获得当前的维护人员，可以这样做：
virtualenv test
test\Scripts\activate
如果要设置维护程序，请按如下方式进行：
virtualenv test
test\Scripts\activate
用户可以是字符串ID、字典或用户对象。
组织
HDX数据集必须是组织的一部分。
如果您希望获得当前组织，可以这样做：
virtualenv test
test\Scripts\activate
如果要设置组织，请按如下方式进行：
virtualenv test
test\Scripts\activate
组织是字符串ID、字典或组织 对象：< /P>
特定于资源的操作
您可以使用下载功能下载资源，例如。
virtualenv test
test\Scripts\activate
如果您不提供文件夹下载到，则使用临时文件夹。
在创建或更新资源之前，可以指定要上载到hdx的本地文件的路径 文件存储（如果优先于将文件托管在hdx外部）。而不是指向 您的服务器或API，在这种情况下，URL将指向HDX文件存储中包含文件副本的位置。
virtualenv test
test\Scripts\activate
有一个getter可以读回值：
virtualenv -p python3 test
source test/bin/activate
如果希望在hdx中设置数据预览功能，并且文件（hdx或外部托管）是csv，则可以 调用create_datastore或update_datastore方法。如果不传递任何参数，则 CSV将假定为文本。
virtualenv -p python3 test
source test/bin/activate
通过传递某些参数和使用其他相关方法（例如，
virtualenv -p python3 test
source test/bin/activate
展示管理
Showcase类使您能够管理Showcase、创建、删除和更新（对于其他HDX对象） 根据您的权限。
要查看Showcase所在的数据集列表，请使用获取数据集函数，例如
virtualenv -p python3 test
source test/bin/activate
如果要将数据集添加到Showcase，可以调用添加数据集函数，例如：
virtualenv -p python3 test
source test/bin/activate
您可以使用remove\dataset函数从Showcase中删除数据集，例如：
virtualenv -p python3 test
source test/bin/activate
如果要获取当前标记，可以使用以下方法：
virtualenv -p python3 test
source test/bin/activate
如果要添加标记，请按如下方式进行：
virtualenv -p python3 test
source test/bin/activate
如果要添加标记列表，请按以下步骤操作：
virtualenv -p python3 test
source test/bin/activate
用户管理
用户类使您能够根据 您的权限。
你可以给用户发电子邮件。首先，您需要使用字典或文件设置电子邮件服务器：
virtualenv -p python3 test
source test/bin/activate
然后，您可以向这样的用户发送电子邮件：
pip install hdx-python-api
您可以这样给多个用户发送电子邮件：
pip install hdx-python-api
组织管理
organization类允许您管理组织、创建、删除和更新（对于其他HDX 对象）根据您的权限。
您可以按如下方式获取组织中的数据集：
pip install hdx-python-api
可以提供各种附加参数（**kwargs）。这些在API文档中有详细说明。
您可以在这样的组织中获取用户：
pip install hdx-python-api
可选过滤器可以是成员、编辑、管理员。
您可以添加或更新组织中的用户，如下所示：
pip install hdx-python-api
您需要在"用户"中包含一个"容量"字段，其中"容量"是"成员"、"编辑"、"管理员"。
您可以在一个组织中添加或更新多个用户，如下所示：
pip install hdx-python-api
您可以从组织中删除用户：
pip install hdx-python-api
词汇管理
词汇表类使您能够管理ckan词汇表、创建、删除和更新（对于其他hdx 对象）根据您的权限。
您可以选择使用字典、名称和标记初始化词汇表：
pip install hdx-python-api
如果要获取当前标记，可以使用以下方法：
pip install hdx-python-api
如果要添加标记，请按如下方式进行：
pip install hdx-python-api
如果要添加标记列表，请按以下步骤操作：
α hdx_key: "HDX API KEY"
工作示例
在这里，我们将从头开始创建一个工作示例。
首先，pip安装库，或者将其添加到requirements.txt文件中（如果您愿意的话）。 如上所述。
接下来创建一个名为run.py的文件，并将下面的代码复制到其中。
hdx_key: "HDX API KEY"
上述文件将在hdx中创建一个由名为generate_dataset的函数生成的数据集，可以在 我们现在要编写的文件my_code.py。
创建一个文件并将下面的代码复制到其中：
hdx_key: "HDX API KEY"
然后，您可以根据需要填写函数生成数据集。
acled示例
一个完整的例子可以在这里找到：https://github.com/ocha-dap/hdxscraper-acled
特别是，查看文件run.py、acled.py和config文件夹。如果你运行它不变，它 将覆盖acled组织中的现有数据集！因此，应该在测试服务器上运行它。如果 如果使用它作为代码的基础，则需要在acled.py中修改数据集name，并更改 向您的组织发送组织信息。同时更新config/hdx_dataset_static.yml中的元数据 适当。
acled scraper在hdx中为每个国家创建一个数据集，填充所有必需的元数据。然后创造资源 通过hxl代理指向acled api，该代理动态添加hxl标签。
acled scraper的第一次迭代是在没有hdx python库的情况下编写的，现在可以清楚地看到 以及其他人之前的工作，即有一些操作是经常需要的，并且增加了不必要的复杂性 对hdx进行编码的任务。简化hdx接口推动了python库和 刮刀的第二次迭代是用它建立的。acled从生成文件到创建api，因此 开发了迭代。
通过使用hdx术语和直接映射到数据集、资源和展示案例的接口，acled 刮刀的开发速度更快，对于缺乏刮刀工作原理和工作原理的人来说更容易理解。 做。广泛的日志记录和错误的透明通信是非常宝贵的，可以采取行动 尽快解决问题。acled的静态元数据保存在可读文件中，因此如果需要 修改一下，很简单。This是hdx python库的另一个特性，它使数据 以编程方式轻松地进入HDX。
欢迎加入QQ群-->： 979659372
