# pydicom.valuerep.PersonName

class pydicom.valuerep.PersonName(*args: Any, **kwargs: Any)

  Representation of the value for an element with VR PN.

  __init__(val: Union[bytes, str, pydicom.valuerep.PersonName], encodings: Optional[Sequence[str]] = None, original_string: Optional[bytes] = None) → None

    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

  `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 components: Tuple[str, ...]

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

    New in version 1.2.

    Returns

      The (alphabetic, ideographic, phonetic) components of the decoded person name. Any of the components may be absent.

    Return type

      Tuple[str, …]

  decode(encodings: Optional[Sequence[str]] = None) → pydicom.valuerep.PersonName

    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: Optional[Sequence[str]] = None) → bytes

    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

    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

    New in version 1.2.

  formatted(format_str: str) → str

    Return the name as a `str` formatted using format_str.

  classmethod from_named_components(family_name: Union[str, bytes] = '', given_name: Union[str, bytes] = '', middle_name: Union[str, bytes] = '', name_prefix: Union[str, bytes] = '', name_suffix: Union[str, bytes] = '', family_name_ideographic: Union[str, bytes] = '', given_name_ideographic: Union[str, bytes] = '', middle_name_ideographic: Union[str, bytes] = '', name_prefix_ideographic: Union[str, bytes] = '', name_suffix_ideographic: Union[str, bytes] = '', family_name_phonetic: Union[str, bytes] = '', given_name_phonetic: Union[str, bytes] = '', middle_name_phonetic: Union[str, bytes] = '', name_prefix_phonetic: Union[str, bytes] = '', name_suffix_phonetic: Union[str, bytes] = '', encodings: Optional[List[str]] = None) → pydicom.valuerep.PersonName

    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 (Union[str, bytes]) – Family name in alphabetic form.

      - given_name (Union[str, bytes]) – Given name in alphabetic form.

      - middle_name (Union[str, bytes]) – Middle name in alphabetic form.

      - name_prefix (Union[str, bytes]) – Name prefix in alphabetic form, e.g. ‘Mrs.’, ‘Dr.’, ‘Sr.’, ‘Rev.’.

      - name_suffix (Union[str, bytes]) – Name prefix in alphabetic form, e.g. ‘M.D.’, ‘B.A., M.Div.’, ‘Chief Executive Officer’.

      - family_name_ideographic (Union[str, bytes]) – Family name in ideographic form.

      - given_name_ideographic (Union[str, bytes]) – Given name in ideographic form.

      - middle_name_ideographic (Union[str, bytes]) – Middle name in ideographic form.

      - name_prefix_ideographic (Union[str, bytes]) – Name prefix in ideographic form.

      - name_suffix_ideographic (Union[str, bytes]) – Name suffix in ideographic form.

      - family_name_phonetic (Union[str, bytes]) – Family name in phonetic form.

      - given_name_phonetic (Union[str, bytes]) – Given name in phonetic form.

      - middle_name_phonetic (Union[str, bytes]) – Middle name in phonetic form.

      - name_prefix_phonetic (Union[str, bytes]) – Name prefix in phonetic form.

      - name_suffix_phonetic (Union[str, bytes]) – Name suffix in phonetic form.

      - encodings (Optional[List[str]]) – 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: Union[str, bytes] = '', patient_name: Union[str, bytes] = '', responsible_party_name_ideographic: Union[str, bytes] = '', patient_name_ideographic: Union[str, bytes] = '', responsible_party_name_phonetic: Union[str, bytes] = '', patient_name_phonetic: Union[str, bytes] = '', encodings: Optional[List[str]] = None) → pydicom.valuerep.PersonName

    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 (Union[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 (Union[str, bytes]) – Patient name in alphabetic form.

      - responsible_party_name_ideographic (Union[str, bytes]) – Name of the responsible party in ideographic form.

      - patient_name_ideographic (Union[str, bytes]) – Patient name in ideographic form.

      - responsible_party_name_phonetic (Union[str, bytes]) – Name of the responsible party in phonetic form.

      - patient_name_phonetic (Union[str, bytes]) – Patient name in phonetic form.

      - encodings (Optional[List[str]]) – 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

    New in version 1.2.

  property ideographic: str

    Return the second (ideographic) person name component as a unicode string

    New in version 1.2.

  property middle_name: str

    Return the third (middle name) group of the alphabetic person name representation as a unicode string

    New in version 1.2.

  property name_prefix: str

    Return the fourth (name prefix) group of the alphabetic person name representation as a unicode string

    New in version 1.2.

  property name_suffix: str

    Return the fifth (name suffix) group of the alphabetic person name representation as a unicode string

    New in version 1.2.

  property phonetic: str

    Return the third (phonetic) person name component as a unicode string

    New in version 1.2.