pydicom.valuerep.PersonName¶

class pydicom.valuerep.PersonName(*args: Any, **kwargs: Any)[source]¶

Representation of the value for an element with VR PN.

Create a new PersonName.

Parameters:

val (str, bytes, PersonName) – The value to use for the PN element.
encodings (list of str, optional) – A list of the encodings used for the value.
original_string (bytes, optional) – When creating a PersonName using a decoded string, this is the original encoded value.

Notes

A PersonName may also be constructed by specifying individual components using the from_named_components() and from_named_components_veterinary() class methods.

Methods

`__init__`(val[, encodings, original_string, ...])	Create a new `PersonName`.
`decode`([encodings])	Return the patient name decoded by the given encodings.
`encode`([encodings])	Return the patient name decoded by the given encodings.
`family_comma_given`()	Return the name as "Family, Given".
`formatted`(format_str)	Return the name as a `str` formatted using format_str.
`from_named_components`([family_name, ...])	Construct a PersonName from explicit named components.
`from_named_components_veterinary`([...])	Construct a PersonName from explicit named components following the veterinary usage convention.

Attributes

`alphabetic`	Return the first (alphabetic) person name component as a unicode string
`components`	Returns up to three decoded person name components as a `tuple` of `str`.
`family_name`	Return the first (family name) group of the alphabetic person name representation as a unicode string
`given_name`	Return the second (given name) group of the alphabetic person name representation as a unicode string
`ideographic`	Return the second (ideographic) person name component as a unicode string
`middle_name`	Return the third (middle name) group of the alphabetic person name representation as a unicode string
`name_prefix`	Return the fourth (name prefix) group of the alphabetic person name representation as a unicode string
`name_suffix`	Return the fifth (name suffix) group of the alphabetic person name representation as a unicode string
`phonetic`	Return the third (phonetic) person name component as a unicode string

property alphabetic: str¶: Return the first (alphabetic) person name component as a unicode string

property components: tuple[str, ...]¶

Returns up to three decoded person name components as a tuple of str.

Returns:: The (alphabetic, ideographic, phonetic) components of the decoded person name. Any of the components may be absent.
Return type:: Tuple[str, …]

decode(encodings: Sequence[str] | None = None) → PersonName[source]¶

Return the patient name decoded by the given encodings.

Parameters:: encodings (list of str, optional) – The list of encodings used for decoding the byte string. If not given, the initial encodings set in the object are used.
Returns:: A person name object that will return the decoded string with the given encodings on demand. If the encodings are not given, the current object is returned.
Return type:: valuerep.PersonName

encode(encodings: Sequence[str] | None = None) → bytes[source]¶

Return the patient name decoded by the given encodings.

Parameters:: encodings (list of str, optional) – The list of encodings used for encoding the unicode string. If not given, the initial encodings set in the object are used.
Returns:: The person name encoded with the given encodings as a byte string. If no encoding is given, the original byte string is returned, if available, otherwise each group of the patient name is encoded with the first matching of the given encodings.
Return type:: bytes

family_comma_given() → str[source]¶: Return the name as “Family, Given”.

property family_name: str¶: Return the first (family name) group of the alphabetic person name representation as a unicode string

formatted(format_str: str) → str[source]¶: Return the name as a str formatted using format_str.

Construct a PersonName from explicit named components.

The DICOM standard describes human names using five components: family name, given name, middle name, name prefix, and name suffix. Any component may be an empty string (the default) if not used. A component may contain multiple space-separated words if there are, for example, multiple given names, middle names, or titles.

Additionally, each component may be represented in ideographic or phonetic form in addition to (or instead of) alphabetic form.

For more information see the following parts of the DICOM standard: - Value Representations - PN Examples - PN Precise semantics

Example

A case with multiple given names and suffixes (DICOM standard, part 5, sect 6.2.1.1):

>>> pn = PersonName.from_named_components(
        family_name='Adams',
        given_name='John Robert Quincy',
        name_prefix='Rev.',
        name_suffix='B.A. M.Div.'
    )

A Korean case with phonetic and ideographic representations (PS3.5-2008 section I.2 p. 108):

>>> pn = PersonName.from_named_components(
        family_name='Hong',
        given_name='Gildong',
        family_name_ideographic='洪',
        given_name_ideographic='吉洞',
        family_name_phonetic='홍',
        given_name_phonetic='길동',
        encodings=[default_encoding, 'euc_kr']
    )

Parameters:

family_name (str | bytes) – Family name in alphabetic form.
given_name (str | bytes) – Given name in alphabetic form.
middle_name (str | bytes) – Middle name in alphabetic form.
name_prefix (str | bytes) – Name prefix in alphabetic form, e.g. ‘Mrs.’, ‘Dr.’, ‘Sr.’, ‘Rev.’.
name_suffix (str | bytes) – Name prefix in alphabetic form, e.g. ‘M.D.’, ‘B.A., M.Div.’, ‘Chief Executive Officer’.
family_name_ideographic (str | bytes) – Family name in ideographic form.
given_name_ideographic (str | bytes) – Given name in ideographic form.
middle_name_ideographic (str | bytes) – Middle name in ideographic form.
name_prefix_ideographic (str | bytes) – Name prefix in ideographic form.
name_suffix_ideographic (str | bytes) – Name suffix in ideographic form.
family_name_phonetic (str | bytes) – Family name in phonetic form.
given_name_phonetic (str | bytes) – Given name in phonetic form.
middle_name_phonetic (str | bytes) – Middle name in phonetic form.
name_prefix_phonetic (str | bytes) – Name prefix in phonetic form.
name_suffix_phonetic (str | bytes) – Name suffix in phonetic form.
encodings (list[str] | None) – A list of encodings used for the other input parameters.

Returns:

PersonName constructed from the supplied components.

Return type:

PersonName

Notes

Strings may not contain the following characters: ‘^’, ‘=’, or the backslash character.

classmethod from_named_components_veterinary(responsible_party_name: str | bytes = '', patient_name: str | bytes = '', responsible_party_name_ideographic: str | bytes = '', patient_name_ideographic: str | bytes = '', responsible_party_name_phonetic: str | bytes = '', patient_name_phonetic: str | bytes = '', encodings: list[str] | None = None) → PersonName[source]¶

Construct a PersonName from explicit named components following the veterinary usage convention.

The DICOM standard describes names for veterinary use with two components: responsible party family name OR responsible party organization name, and patient name. Any component may be an empty string (the default) if not used. A component may contain multiple space-separated words if necessary.

Additionally, each component may be represented in ideographic or phonetic form in addition to (or instead of) alphabetic form.

For more information see the following parts of the DICOM standard: - Value Representations - PN Examples - PN Precise semantics

Example

A horse whose responsible organization is named “ABC Farms”, and whose name is “Running On Water”

>>> pn = PersonName.from_named_components_veterinary(
        responsible_party_name='ABC Farms',
        patient_name='Running on Water'
    )

Parameters:

responsible_party_name (str | bytes) – Name of the responsible party in alphabetic form. This may be either the family name of the responsible party, or the name of the responsible organization.
patient_name (str | bytes) – Patient name in alphabetic form.
responsible_party_name_ideographic (str | bytes) – Name of the responsible party in ideographic form.
patient_name_ideographic (str | bytes) – Patient name in ideographic form.
responsible_party_name_phonetic (str | bytes) – Name of the responsible party in phonetic form.
patient_name_phonetic (str | bytes) – Patient name in phonetic form.
encodings (list[str] | None) – A list of encodings used for the other input parameters

Returns:

PersonName constructed from the supplied components

Return type:

PersonName

Notes

Strings may not contain the following characters: ‘^’, ‘=’, or the backslash character.

property given_name: str¶: Return the second (given name) group of the alphabetic person name representation as a unicode string

property ideographic: str¶: Return the second (ideographic) person name component as a unicode string

property middle_name: str¶: Return the third (middle name) group of the alphabetic person name representation as a unicode string

property name_prefix: str¶: Return the fourth (name prefix) group of the alphabetic person name representation as a unicode string

property name_suffix: str¶: Return the fifth (name suffix) group of the alphabetic person name representation as a unicode string

property phonetic: str¶: Return the third (phonetic) person name component as a unicode string