fhir.resources 7.1.0

FHIR注释（JSON）

可以在JSON中添加注释，类似于XML，但需要遵循一些约定，由Grahame Grieve提出；在此实现了。

还可以生成不带注释的json字符串输出。

示例

>>> observation_str = b"""{
...  "resourceType": "Observation",
...  "id": "f001",
...    "fhir_comments": [
...      "   a specimen identifier - e.g. assigned when the specimen was taken by the orderer/placer  use the accession number for the filling lab   ",
...      "  Placer ID  "
...    ],
...  "text": {
...      "fhir_comments": [
...      "   a specimen identifier - e.g. assigned when the specimen was taken by the orderer/placer  use the accession number for the filling lab   ",
...      "  Placer ID  "
...    ],
...    "status": "generated",
...    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">.........</div>"
...  },
...  "identifier": [
...    {
...      "use": "official",
...      "system": "http://www.bmc.nl/zorgportal/identifiers/observations",
...      "value": "6323"
...    }
...  ],
...  "status": "final",
...  "_status": {
...      "fhir_comments": [
...            "  EH: Note to balloters  - lots of choices for whole blood I chose this.  "
...          ]
...  },
...  "code": {
...    "coding": [
...      {
...        "system": "http://loinc.org",
...        "code": "15074-8",
...        "display": "Glucose [Moles/volume] in Blood"
...      }
...    ]
...  },
...  "subject": {
...    "reference": "Patient/f001",
...    "display": "P. van de Heuvel"
...  },
...  "effectivePeriod": {
...    "start": "2013-04-02T09:30:10+01:00"
...  },
...  "issued": "2013-04-03T15:30:10+01:00",
...  "performer": [
...    {
...      "reference": "Practitioner/f005",
...      "display": "A. Langeveld"
...    }
...  ],
...  "valueQuantity": {
...    "value": 6.3,
...    "unit": "mmol/l",
...    "system": "http://unitsofmeasure.org",
...    "code": "mmol/L"
...  },
...  "interpretation": [
...    {
...      "coding": [
...        {
...          "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
...          "code": "H",
...          "display": "High"
...        }
...      ]
...    }
...  ],
...  "referenceRange": [
...    {
...      "low": {
...        "value": 3.1,
...        "unit": "mmol/l",
...        "system": "http://unitsofmeasure.org",
...        "code": "mmol/L"
...      },
...      "high": {
...        "value": 6.2,
...        "unit": "mmol/l",
...        "system": "http://unitsofmeasure.org",
...        "code": "mmol/L"
...      }
...    }
...  ]
... }"""
>>> from fhir.resources.observation import Observation
>>> obj = Observation.parse_raw(observation_str)
>>> "fhir_comments" in obj.json()
>>> # Test comments filtering
>>> "fhir_comments" not in obj.json(exclude_comments=True)

特殊情况：缺少数据

在某些情况下，实现者可能会发现他们没有适合最小基数=1的元素的正确数据。[在此情况下，元素必须存在，除非资源或其配置文件已将原始数据类型的实际值设置为必填，否则可以提供扩展来解释为什么原始值不存在。例如（必需的intent元素缺失，但仍然有效，因为扩展）

>>> json_str = b"""{
...    "resourceType": "MedicationRequest",
...    "id": "1620518",
...    "meta": {
...        "versionId": "1",
...        "lastUpdated": "2020-10-27T11:04:42.215+00:00",
...        "source": "#z072VeAlQWM94jpc",
...        "tag": [
...            {
...                "system": "http://www.alpha.alp/use-case",
...                "code": "EX20"
...            }
...        ]
...    },
...    "status": "completed",
...    "_intent": {
...        "extension": [
...            {
...                "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason",
...                "valueCode": "unknown"
...            }
...        ]
...    },
...    "medicationReference": {
...        "reference": "Medication/1620516",
...        "display": "Erythromycin 250 MG Oral Tablet"
...    },
...    "subject": {
...        "reference": "Patient/1620472"
...    },
...    "encounter": {
...        "reference": "Encounter/1620506",
...        "display": "Follow up encounter"
...    },
...    "authoredOn": "2018-06-16",
...    "requester": {
...        "reference": "Practitioner/1620502",
...        "display": "Dr. Harold Hippocrates"
...    },
...    "reasonReference": [
...        {
...            "reference": "Condition/1620514",
...            "display": "Otitis Media"
...        }
...    ],
...    "dosageInstruction": [
...        {
...            "text": "250 mg 4 times per day for 10 days",
...            "timing": {
...                "repeat": {
...                    "boundsDuration": {
...                        "value": 10,
...                        "unit": "day",
...                        "system": "http://unitsofmeasure.org",
...                        "code": "d"
...                    },
...                    "frequency": 4,
...                    "period": 1,
...                    "periodUnit": "d"
...                }
...            },
...            "doseAndRate": [
...                {
...                    "doseQuantity": {
...                        "value": 250,
...                        "unit": "mg",
...                        "system": "http://unitsofmeasure.org",
...                        "code": "mg"
...                    }
...                }
...            ]
...        }
...    ],
...    "priorPrescription": {
...        "reference": "MedicationRequest/1620517",
...        "display": "Amoxicillin prescription"
...    }
... }"""
>>> from fhir.resources.medicationrequest import MedicationRequest
>>> obj = MedicationRequest.parse_raw(json_str)
>>> "intent" not in obj.dict()

自定义验证器

《fhir.resources》提供广泛的API，用于将自定义验证器附加到任何模型。有关更多信息，请参阅关于根验证器。在创建根验证器时，您需要遵循一些约定。

1. 参数数量是固定的，名称也是固定的。例如 (cls, values)。

2. 应该返回 values，除非需要引发异常。

3. 验证器只能为单个模型附加一次。更新：从现在起，无法在同一类上多次附加相同名称的验证器。

示例1：Patient验证器

from typing import Dict
from fhir.resources.patient import Patient

import datetime

def validate_birthdate(cls, values: Dict):
    if not values:
        return values
    if "birthDate" not in values:
        raise ValueError("Patient's ``birthDate`` is required.")

    minimum_date = datetime.date(2002, 1, 1)
    if values["birthDate"] > minimum_date:
        raise ValueError("Minimum 18 years patient is allowed to use this system.")
    return values
# we want this validator to execute after data evaluating by individual field validators.
Patient.add_root_validator(validate_gender, pre=False)

示例2：从验证器类创建的Patient验证器

from typing import Dict
from fhir.resources.patient import Patient

import datetime

class MyValidator:
    @classmethod
    def validate_birthdate(cls, values: Dict):
        if not values:
            return values
        if "birthDate" not in values:
            raise ValueError("Patient's ``birthDate`` is required.")

        minimum_date = datetime.date(2002, 1, 1)
        if values["birthDate"] > minimum_date:
            raise ValueError("Minimum 18 years patient is allowed to use this system.")
        return values
# we want this validator to execute after data evaluating by individual field validators.
Patient.add_root_validator(MyValidator.validate_gender, pre=False)

重要提示 可以将根验证器添加到任何基类，如 DomainResource。在这种情况下，您必须确保在导入派生类之前将根验证器附加到其中，否则验证器将不会触发（如果导入在先），这是出于自然原因。

ENUM验证器

《fhir.resources》为每个字段（如果适用）提供枚举约束的API，但它本身并不强制执行基于枚举的验证！请参阅此处讨论。如果您想强制执行枚举约束，您必须创建一个验证器。

示例：性别枚举

from typing import Dict
from fhir.resources.patient import Patient

def validate_gender(cls, values: Dict):
    if not values:
        return values
    enums = cls.__fields__["gender"].field_info.extra["enum_values"]
    if "gender" in values and values["gender"] not in enums:
        raise ValueError("write your message")
    return values

Patient.add_root_validator(validate_gender, pre=True)

引用验证器

《fhir.resources》还通过字段属性 enum_reference_types 提供类似枚举的允许资源类型列表。您可以通过以下方式获取该列表（枚举）方法 resource_types = cls.__fields__["managingOrganization"].field_info.extra["enum_reference_types"]

orjson的使用

orjson 是最快的Python JSON库之一，比标准json库更正确（根据他们的文档）。好消息是 fhir.resource 对 orjson 有广泛的支持，并且启用它非常简单。您需要做的只是将 orjson 作为您的项目依赖项！

pydantic字段类型支持

所有可用的fhir资源（类型）都可以用作 pydantic 字段的价值类型。请参阅问题#46 对FastAPI pydantic响应模型的支持。模块 fhirtypes.py 包含所有fhir资源相关类型，并应自动触发验证器。

Resource.id 即 fhirtypes.Id 约束可扩展性

在此有许多关于 Resource.Id 的值长度的讨论。基于这些讨论，我们建议将您的 Resource.Id 尺寸保持在64个字母以内（为了与第三方系统的互操作性），但我们也在尊重其他意见的同时提供了关于Id长度的自由度，即64个字符的长度不足。 fhirtypes.Id.configure_constraints() 提供了根据您的需求自定义的功能。

示例：

>>> from fhir.resources.fhirtypes import Id
>>> Id.configure_constraints(min_length=16, max_length=128)

注意：当您更改此行为时，它将影响您的整个项目。

XML支持

除了JSON字符串导出之外，还可以导出为XML字符串！在使用此功能之前，请确保已安装相关的依赖库。使用 fhir.resources[xml] 或 fhir.resources[all] 作为您的项目要求。

XML模式验证器！ 在从文件或字符串加载时，可以提供自定义xmlparser，这意味着您可以针对FHIR XML模式（和/或您的自定义模式）验证数据。

示例-1 导出：

>>> from fhir.resources.patient import Patient
>>> data = {"active": True, "gender": "male", "birthDate": "2000-09-18", "name": [{"text": "Primal Kons"}]}
>>> patient_obj = Patient(**data)
>>> xml_str = patient_obj.xml(pretty_print=True)
>>> print(xml_str)
<?xml version='1.0' encoding='utf-8'?>
<Patient xmlns="http://hl7.org/fhir">
  <active value="true"/>
  <name>
    <text value="Primal Kons"/>
  </name>
  <gender value="male"/>
  <birthDate value="2000-09-18"/>
</Patient>

示例-2 从字符串导入：

>>> from fhir.resources.patient import Patient
>>> data = {"active": True, "gender": "male", "birthDate": "2000-09-18", "name": [{"text": "Primal Kons"}]}
>>> patient_obj = Patient(**data)
>>> xml_str = patient_obj.xml(pretty_print=True)
>>> print(xml_str)
>>> data = b"""<?xml version='1.0' encoding='utf-8'?>
... <Patient xmlns="http://hl7.org/fhir">
...   <active value="true"/>
...   <name>
...     <text value="Primal Kons"/>
...   </name>
...   <gender value="male"/>
...   <birthDate value="2000-09-18"/>
... </Patient>"""
>>> patient = Patient.parse_raw(data, content_type="text/xml")
>>> print(patient.json(indent=2))
{
  "resourceType": "Patient",
  "active": true,
  "name": [
    {
      "text": "Primal Kons",
      "family": "Kons",
      "given": [
        "Primal"
      ]
    }
  ],
  "gender": "male",
  "birthDate": "2000-09-18"
}

>>> with xml parser
>>> import lxml
>>> schema = lxml.etree.XMLSchema(file=str(FHIR_XSD_DIR / "patient.xsd"))
>>> xmlparser = lxml.etree.XMLParser(schema=schema)
>>> patient2 = Patient.parse_raw(data, content_type="text/xml", xmlparser=xmlparser)
>>> patient2 == patient
True

示例-3 从文件导入：

>>> patient3 = Patient.parse_file("Patient.xml")
>>> patient3 == patient and patient3 == patient2
True

XML常见问题解答

• 尽管在测试中对生成的XML进行了对FHIR/patient.xsd和FHIR/observation.xsd的验证，但我们建议您检查生产数据的输出。

• 包含注释功能，但我们在复杂的使用中建议您进行检查。

YAML支持

尽管FHIR规范中没有记录官方对YAML的支持，但作为一个实验性功能，我们添加了此支持。现在可以导出/导入YAML字符串。在使用此功能之前，请确保已安装相关的依赖库。根据您的项目需求使用fhir.resources[yaml]或fhir.resources[all]。

示例-1 导出：

>>> from fhir.resources.patient import Patient
>>> data = {"active": True, "gender": "male", "birthDate": "2000-09-18", "name": [{"text": "Primal Kons", "family": "Kons", "given": ["Primal"]}]}
>>> patient_obj = Patient(**data)
>>> yml_str = patient_obj.yaml(indent=True)
>>> print(yml_str)
resourceType: Patient
active: true
name:
- text: Primal Kons
  family: Kons
  given:
  - Primal
gender: male
birthDate: 2000-09-18

示例-2 从YAML字符串导入：

>>> from fhir.resources.patient import Patient
>>> data = b"""
... resourceType: Patient
... active: true
... name:
... - text: Primal Kons
...   family: Kons
...   given:
...   - Primal
...  gender: male
...  birthDate: 2000-09-18
... """
>>> patient_obj = Patient.parse_raw(data, content_type="text/yaml")
>>> json_str = patient_obj.json(indent=True)
>>> print(json_str)
{
  "resourceType": "Patient",
  "active": true,
  "name": [
    {
      "text": "Primal Kons",
      "family": "Kons",
      "given": [
        "Primal"
      ]
    }
  ],
  "gender": "male",
  "birthDate": "2000-09-18"
}

示例-3 从YAML文件导入：

>>> from fhir.resources.patient import Patient
>>> patient_obj = Patient.parse_file("Patient.yml")
>>> json_str = patient_obj.json(indent=True)
>>> print(json_str)
{
  "resourceType": "Patient",
  "active": true,
  "name": [
    {
      "text": "Primal Kons",
      "family": "Kons",
      "given": [
        "Primal"
      ]
    }
  ],
  "gender": "male",
  "birthDate": "2000-09-18"
}

YAML常见问题解答

• 我们使用https://pyyaml.org/ PyYAML库进行序列化和反序列化，但如果我们找到更快的库，我们可能会使用它。欢迎您提供您的建议。

• 尚不支持基于YAML的注释，而是使用json注释语法！当然，此注释功能也在我们的待办事项列表中。

允许空字符串

尽管允许空字符串值对FHIR基本数据类型String不是好的实践。但在现实生活中，有时这是不可避免的。

示例：

请将此代码放在您的__init__.py模块或任何位置，以确保此代码片段在运行时执行。

>>> from fhir.resources.fhirtypes import String
>>> String.configure_empty_str(allow=True)

fhir.resources.fhirelementfactory.FHIRElementFactory::instantiate

替换： fhir.resources.construct_fhir_element

• 第一个参数的值与之前相同，即资源名称。

• 第二个参数比之前的更灵活！不仅可以提供json字典，还可以提供json字符串或json文件路径。

• 没有第三个参数，与之前的版本相同。

fhir.resources.fhirabstractbase.FHIRAbstractBase::__init__

替换： fhir.resources.fhirabstractmodel.FHIRAbstractModel::parse_obj<classmethod>

• 第一个参数的值与之前相同，即json字典。

• 没有第二个参数，与之前的版本相同。

fhir.resources.fhirabstractbase.FHIRAbstractBase::as_json

替换： fhir.resources.fhirabstractmodel.FHIRAbstractModel::dict

• 输出几乎与之前相同，但在某些日期类型方面有一些差异，例如Python中的日期、datetime和Decimal都是对象表示。

• 当需要json字符串时，可以使用fhir.resources.fhirabstractmodel.FHIRAbstractModel::json作为替换（因此不需要进一步从字典中进行json序列化）。

注意

所有资源/类都源自fhir.resources.fhirabstractmodel.FHIRAbstractModel，之前源自fhir.resources.fhirabstractbase.FHIRAbstractBase。