构建具有内置验证的MarineGeo数据输入Excel工作簿
MarinegeoTemplateBuilder的Python项目详细描述
MarineGeo模板生成器
python包，用于为海洋全球地球观测站（marinegeo）网络创建标准化数据输入模板。此软件包是对xlsxwriter的包装，它可以创建带有内置验证和元数据的excel工作簿。模板是使用用户定义的字段列表创建的，这些字段将用作工作簿中的列。每个字段都有几个属性，可以设置这些属性来控制允许的值类型，并提供对数据输入验证的控制。
安装
marinegeotemplatebuilder包可以从使用pip的pypi安装。
pipinstallMarinegeoTemplateBuilder
要求
- 巨蟒2.7+
- xlsxwriter
示例
创建一个包含两列的单页工作簿的简单示例。
# Example of creating an Excel template using the MarinegeoTemplateBuilder packagefromMarinegeoTemplateBuilderimport*# create the example templatemain("Example.xlsx",fields=[Field(sheet="sheet1",fieldName="ColA",fieldDefinition="Column A"),Field(sheet="sheet1",fieldName="ColB",fieldDefinition="Column B")],title="Test Template")
元数据配置
元数据表
每个工作簿都有一个名为元数据的工作表，用于存储有关项目的信息。此工作表是使用默认元数据字段集为所有工作簿自动生成的。使用marinegeotemplatebuilder.main（）中的参数设置配置元数据表的选项。
默认元数据字段
- 标题
- 摘要
- 联系人
- 电子邮件地址
- 人
- 数据输入方式
- 数据输入日期
- 注释
- 原型版本
- 模板版本
- workbookbuildinfo（自动填充）
自定义元数据字段
通过将字段对象列表传递到marinegeotemplatebuilder.main（metadata list=[]）中的metadatalist，可以使用自定义元数据字段。这将覆盖默认的元数据字段选项
custom_metadata=[Field(sheet="Metadata",fieldName="Custom 1",fieldDefinition="Custom Metadata Field 1",),Field(sheet="Metadata",fieldName="Custom 2",fieldDefinition="Custom Metadata Field 2",)]# custom metadatamain(...,metadataList=custom_metadata)
预填充元数据
可以预置元数据元素，以便在创建工作簿时设置默认值。这是通过传递一个python值字典来实现的，该字典使用元数据字段名作为metadata values的键。
metadataValues={"TemplateVersion":"v0.0.1","ProtocolVersion":"v0.0.1","Title":"Please Enter Title Here",}
品牌标志
用户可以通过将图像传递给marinegeotemplatebuilder.main（…，branding='path/to/img'）来更改元数据表顶部的品牌图像。如果未提供图像，则默认设置为在工作表顶部仅留有空白。要使用包中提供的marinegeo徽标，只需将"default"作为参数选项。
注意：版式主要是为marinegeo徽标设计的，因此您可能需要调整图像的大小才能将其正确显示在工作表上。
现场配置
每个模板都有自定义列，这些列可以拆分为工作簿中的多个工作表。这是通过创建要添加的列（字段）列表来控制的到工作簿。字段是添加到工作簿中的列。每个字段都必须有目标（工作表）、列标题名（字段名）、说明（字段定义）和定义的属性类型（字段类型）。某些特殊字段类型将有其他选项，可以设置为控制格式和允许值。
支持的字段类型
- 字符串：无限制的通用格式单元格。
- 日期：带验证的Excel日期格式。日期必须定义格式字符串。
- 日期：带验证的Excel时间格式。时间必须定义
格式字符串。 - 列表：来自电子表格中另一列的验证。必须在
查找变量中定义源。 - 公式：来自其他列的计算字段。公式必须在
查找变量中定义。 - 整数：仅验证整数。可能使用minvalue和maxvalue进行约束。
- 十进制：数字的验证。可以使用minvalue和maxvalue进行约束。
- FKEY：工作簿中其他列（外键）的下拉列表。
字符串
格式字符串。查找变量中定义源。查找变量中定义。字段类型string用于没有限制的常规格式单元格。没有内置的验证规则-单元格中允许所有值。这应该是所有不适合其他特殊字段类型的字段的默认字段类型。
日期
字段类型date用于包含日期字段的列。excel将对单元格进行验证，以确保用户输入的日期有效。要正常工作，该字段必须定义format string来控制日期/时间字符串的格式。一些示例包括日期的yyyy-mm-dd和小时/分钟的hh:mm。有关帮助，请参见excel格式单元格。
次
字段类型time用于包含时间字段的列。excel将对单元格进行验证，以确保用户输入的时间是有效的。要正常工作，该字段必须定义format string来控制日期/时间字符串的格式。一些示例包括日期的yyyy-mm-dd和小时/分钟的hh:mm。有关帮助，请参见excel格式单元格。
列表
字段类型列表项是包含字段受控词汇表的下拉菜单。词汇表术语应加载为vocab（）实例。有关详细信息，请参见词汇部分。
整数
整数字段可以使用fieldtypeinteger设置。通过设置最小值或最大值，整数字段可以限制在特定范围内。最小和最大限制是包含在内的。例如，如果希望列只包含小于或等于3的正整数，请使用minvalue=1，maxvalue=3。如果未设置"最小"和"最大"限制，则列将仅验证输入是否为整数。
小数
可以使用fieldtypedecimal设置十进制字段。十进制字段与整数字段非常相似，但接受所有数字。可以使用字段的最小值和最大值设置可接受值的范围。例如，如果列只需要包含正数，则将验证设置为minvalue=0。如果未设置"最小"和"最大"限制，则列将验证输入是否为数字。
外键
foregin键是对其他工作表中列的引用。此特殊字段类型使用字段类型fkey设置，特殊值指向l中的另一列ookup。查找值的格式必须为sheet$columnname
方程式
计算字段是非常特殊的列。字段类型需要设置为表达式，并且需要使用列字段名在查找属性中写入公式。方程式以等号开头并使用字段名（列名在内部与excel列字母值交换）。公式只能引用活动工作表上的列，不能计算不同行上的单元格。有一个sum列的示例，该列与列相加-"=column1+column2"。默认情况下，所有计算字段都被锁定，无法编辑，并且显示为灰色。注意：使用公式时要谨慎，实现过程比较繁琐，并且会在speadsheet中填充许多空值。
警告级别
每个字段的验证错误级别可以设置为"停止"、"警告"或"信息"。有关详细信息，请参见xlsxwriter error_type。
加载字段
字段可以从csv文件、数据框或field（）对象列表中加载。
sheet,fieldName,fieldDefinition,fieldType,formatString,loopup,unit,minValue,maxValue,warnLevel
Location,site,MarineGEO site abbreviation,list,,,,,,
Location,locationID,Unique code for each sampling location,string,,,,,,
Location,locality,Local or common name of the sampling location,string,,,,,,
Cover,locationID,Foreign key to the locationID defined on the Location sheet,fkey,,Location$locationID,,,,
Cover,transectNumber,"Transect Number",integer,,,dimensionless,1,3,
Cover,stopNumber,"Stop number along transect",integer,,,dimensionless,1,5,
fromMarinegeoTemplateBuilder.classesimportFieldattributes=[Field(sheet="Location",fieldName="site",fieldDefinition="MarineGEO site abbreviation",fieldType="list"),Field(sheet="Location",fieldName="locationID",fieldDefinition="Unique code for each sampling location",fieldType="string"),Field(sheet="Location",fieldName="locality",fieldDefinition="Local or common name of the sampling location",fieldType="string"),Field(sheet="Cover",fieldName="locationID",fieldDefination="Foreign key to the locationID defined on the Location sheet",fieldType="fkey",lookup="Location$locationID"),Field(sheet="Cover",fieldName="transectNumber",fieldDefination="Transect Number",fieldType="integer",unit="dimensionless",minValue=1,maxValue=3),Field(sheet="Cover",fieldName="stopNumber",fieldDefinition="Stop number along transect",fieldType="integer",unit="dimensionless",minValue=1,maxValue=5)]
受控词汇
词汇表是下拉菜单中使用的术语。可以使用两种不同的方法设置词汇表。每个vocab术语都必须有目标字段名、代码和定义。所有术语都将添加到工作簿的"词汇"选项卡中。
字段的受控词汇。受控词汇表用于填充验证下拉菜单。
每个词汇术语都必须有目的字段（fieldname）和术语/代码本身（code）。最好为每个代码包含一个定义。
注意：词汇表的目的地字段名必须与词汇表的字段名匹配，并设置为"list"的字段类型。
加载词汇
词汇术语可以从csv、dataframe或vocab（）类实例列表中加载。
fieldName,code,definition
percentCover,<5%,Less than 5%
percentCover,10%,Between 5-10%
percentCover,15%,Between 10-15%
fromMarinegeoTemplateBuilder.classesimportVocabvocabulary=[Vocab(fieldName="percentCover",code="<5%",definition="Less than 5%"),Vocab(fieldName="percentCover",code="10%",definition="Between 5-10%"),Vocab(fieldName="percentCover",code="15%",definition="Between 10-15%")]
完整示例
# Example of creating an Excel template using the MarinegeoTemplateBuilder packageimportMarinegeoTemplateBuilderfromMarinegeoTemplateBuilder.classesimportField,Vocabimportdatetime# some values to prefill for the metadata sectionmetadataValues={"Title":"MarineGEO Template Builder Workbook Demo","Abstract":"This example illustrates all the configurable options for adding columns with validation to a workbook"" using the MarineGEO Template Builder package.","ContactPerson":"Firstname Lastname","EmailAddress":"first.last@example.com","People":"Person One; Person Two; Person Three","DataEntryBy":"Firstname Lastname","DataEntryDate":datetime.datetime.today().strftime('%Y-%m-%d'),"Notes":"For Demonstration Use Only!","ProtocolVersion":"The version number of the protocol used."}# columns to add to the workbook as a list of Field()'sfields=[# Dropdown list lookup from controlled vocabularyField(sheet="Location",fieldName="site",fieldDefinition="site abbreviation",fieldType="list"),# String data fieldField(sheet="Location",fieldName="locationID",fieldDefinition="unique code for sampling location"),# On new sheet create a foreign key to the location ID on the location sheetField(sheet="Data",fieldName="locationID",fieldDefinition="foreign key for sampling location",fieldType="fkey",lookup="Location$locationID"),# Date field in the format of YEAR-MONTH-DAY (YYYY-MM-DD)Field(sheet="Data",fieldName="date",fieldDefinition="Date Collected",fieldType="date",formatString="YYYY-MM-DD"),# Time field in the format of HH:MMField(sheet="Data",fieldName="time",fieldDefinition="Time Collected",fieldType="time",formatString="HH:MM"),# Another dropdown list that contains controlled vocabularyField(sheet="Data",fieldName="type",fieldDefinition="Type collected",fieldType="list"),# A field that must contain positive integersField(sheet="Data",fieldName="posNum",fieldDefinition="Positive numbers only",fieldType="integer",minValue=0),# A field for decimals between -5.5 and 99.9Field(sheet="Data",fieldName="decimal",fieldDefinition="decimal",fieldType="decimal",minValue=-5.5,maxValue=99.9),# Calculated field that multiplys the PosNum by the DecimalField(sheet="Data",fieldName="multiply",fieldDefinition="PosNum times Decimal",fieldType="equation",lookup="=posNum * decimal"),]# Load the vocab for the controlled vocab fieldsvocab=[Vocab(fieldName="site",code="A",definition="site a"),Vocab(fieldName="site",code="B",definition="site B"),Vocab(fieldName="type",code="Red",definition="site B"),Vocab(fieldName="type",code="Blue",definition="site B")]# create the example templateMarinegeoTemplateBuilder.main("TestTemplate_v0.0.1.xlsx",fields,vocab,branding="DEFAULT",metadataValues=metadataValues,dryrun=False,)
欢迎加入QQ群-->： 979659372
