"plistlib" --- 맥 OS X ".plist" 파일 생성과 구문 분석
*****************************************************

**소스 코드:** Lib/plistlib.py

======================================================================

이 모듈은 주로 Mac OS X에서 사용되는 "프로퍼티 리스트(property list)"
파일을 읽고 쓰는 인터페이스를 제공하며 바이너리와 XML plist 파일을 모
두 지원합니다.

프로퍼티 리스트 (".plist") 파일 형식은 딕셔너리, 리스트, 숫자 및 문자
열과 같은 기본 객체 형을 지원하는 간단한 직렬화입니다. 일반적으로 최상
위 객체는 딕셔너리입니다.

plist 파일을 쓰고 구문 분석하려면, "dump()"와 "load()" 함수를 사용하십
시오.

plist 데이터를 바이트열 객체로 작업하려면, "dumps()"와 "loads()"를 사
용하십시오.

값은 문자열, 정수, 부동 소수점, 논릿값, 튜플, 리스트, 딕셔너리 (단, 문
자열 키만 가능), "Data", "bytes", "bytesarray" 또는
"datetime.datetime" 객체일 수 있습니다.

버전 3.4에서 변경: 새 API, 이전 API는 폐지되었습니다. 바이너리 형식
plist에 대한 지원이 추가되었습니다.

버전 3.8에서 변경: NSKeyedArchiver 와 NSKeyedUnarchiver 에서 사용되듯
이 바이너리 plist에서 "UID" 토큰을 읽고 쓰는 것에 대한 지원이 추가되었
습니다.

더 보기:

  PList manual page
     애플의 파일 형식 설명서.

이 모듈은 다음 함수를 정의합니다:

plistlib.load(fp, *, fmt=None, use_builtin_types=True, dict_type=dict)

   plist 파일을 읽습니다. *fp*는 읽을 수 있는 바이너리 파일 객체여야
   합니다. 해독된 루트 객체를 반환합니다 (일반적으로 딕셔너리입니다).

   *fmt*는 파일의 형식이며 다음 값이 유효합니다:

   * "None": 파일 형식을 자동 감지

   * "FMT_XML": XML 파일 형식

   * "FMT_BINARY": 바이너리 plist 형식

   *use_builtin_types*가 참(기본값)이면 바이너리 데이터가 "bytes"의 인
   스턴스로 반환되고, 그렇지 않으면 "Data"의 인스턴스로 반환됩니다.

   *dict_type*은 plist 파일에서 읽은 딕셔너리에 사용되는 형입니다.

   "FMT_XML" 형식의 XML 데이터는 "xml.parsers.expat" 의 Expat 구문 분
   석기로 구문 분석됩니다 -- 잘못된 형식의 XML로 인한 예외에 대해서는
   해당 설명서를 참조하십시오. 알 수 없는 엘리먼트는 plist 구문분석기
   에서 단순히 무시됩니다.

   바이너리 형식의 구문 분석기는 파일을 구문 분석할 수 없을 때
   "InvalidFileException"를 발생시킵니다.

   버전 3.4에 추가.

plistlib.loads(data, *, fmt=None, use_builtin_types=True, dict_type=dict)

   바이트열 객체에서 plist를 로드합니다. 키워드 인자에 대한 설명은
   "load()"를 참조하십시오.

   버전 3.4에 추가.

plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

   plist 파일에 *value*를 씁니다. *Fp*는 쓰기 가능한 바이너리 파일 객
   체여야 합니다.

   *fmt* 인자는 plist 파일의 형식을 지정하며 다음 값 중 하나일 수 있습
   니다:

   * "FMT_XML": XML 형식의 plist 파일

   * "FMT_BINARY": 바이너리 형식의 plist 파일

   *sort_keys*가 참(기본값)이면 딕셔너리의 키가 정렬된 순서로 plist에
   기록되고, 그렇지 않으면 딕셔너리의 이터레이션 순서로 기록됩니다.

   *skipkeys*가 거짓(기본값)일 때, 딕셔너리의 키가 문자열이 아니면 함
   수는 "TypeError"를 발생시킵니다. 그렇지 않으면 해당 키를 건너뜁니다
   .

   객체가 지원되지 않는 형이거나 지원되지 않는 형의 객체를 포함하는 컨
   테이너면 "TypeError"가 발생합니다.

   (바이너리) plist 파일에서 표현할 수 없는 정숫값은 "OverflowError"를
   발생시킵니다.

   버전 3.4에 추가.

plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)

   plist 형식의 바이트열 객체로 *value*를 반환합니다. 이 함수의 키워드
   인자에 대한 설명은 "dump()" 설명서를 참조하십시오.

   버전 3.4에 추가.

다음 함수는 폐지되었습니다:

plistlib.readPlist(pathOrFile)

   plist 파일을 읽습니다. *pathOrFile*은 파일 이름이나 (읽기 가능한 바
   이너리) 파일 객체일 수 있습니다. 해독된 루트 객체를 반환합니다 (일
   반적으로 딕셔너리입니다).

   이 함수는 "load()"를 호출하여 실제 작업을 수행합니다. 키워드 인자에
   대한 설명은 "그 함수" 문서를 참조하십시오.

   버전 3.4부터 폐지: 대신 "load()"를 사용하십시오.

   버전 3.7에서 변경: 결과의 딕셔너리 값은 이제 평범한 dict입니다. 더
   는 이 딕셔너리의 항목을 액세스하기 위해 어트리뷰트 액세스를 사용할
   수 없습니다.

plistlib.writePlist(rootObject, pathOrFile)

   XML plist 파일에 *rootObject*를 씁니다. *pathOrFile*는 파일 이름이
   나 (쓰기 가능한 바이너리) 파일 객체일 수 있습니다

   버전 3.4부터 폐지: 대신 "dump()"를 사용하십시오.

plistlib.readPlistFromBytes(data)

   바이트열 객체에서 plist 데이터를 읽습니다. 루트 객체를 반환합니다.

   키워드 인자에 대한 설명은 "load()"를 참조하십시오.

   버전 3.4부터 폐지: 대신 "loads()"를 사용하십시오.

   버전 3.7에서 변경: 결과의 딕셔너리 값은 이제 평범한 dict입니다. 더
   는 이 딕셔너리의 항목을 액세스하기 위해 어트리뷰트 액세스를 사용할
   수 없습니다.

plistlib.writePlistToBytes(rootObject)

   *rootObject*를 XML plist 형식의 바이트열 객체로 반환합니다.

   버전 3.4부터 폐지: 대신 "dumps()"를 사용하십시오.

다음 클래스를 사용할 수 있습니다:

class plistlib.Data(data)

   바이트열 객체 *data*를 감싸는 "데이터" 래퍼 객체를 반환합니다.
   plist 와 상호 변환하는 함수에서 plist에서 사용할 수 있는 "<data>"
   형을 나타내기 위해 사용됩니다.

   하나의 어트리뷰트 "data"가 있는데, 저장된 파이썬 바이트열 객체를 조
   회하는 데 사용될 수 있습니다.

   버전 3.4부터 폐지: 대신 "bytes" 객체를 사용하십시오.

class plistlib.UID(data)

   "int"를 감쌉니다. 이것은 UID를 포함하는 NSKeyedArchiver 인코딩된 데
   이터를 읽거나 쓸 때 사용됩니다 (PList 매뉴얼을 참조하십시오).

   하나의 어트리뷰트 "data"가 있는데, UID의 int 값을 조회하는 데 사용
   될 수 있습니다. "data"는 반드시 범위 *0 <= data < 2**64*에 있어야
   합니다.

   버전 3.8에 추가.

다음 상수를 사용할 수 있습니다:

plistlib.FMT_XML

   plist 파일의 XML 형식.

   버전 3.4에 추가.

plistlib.FMT_BINARY

   plist 파일의 바이너리 형식

   버전 3.4에 추가.


예제
====

plist 만들기:

   pl = dict(
       aString = "Doodah",
       aList = ["A", "B", 12, 32.1, [1, 2, 3]],
       aFloat = 0.1,
       anInt = 728,
       aDict = dict(
           anotherString = "<hello & hi there!>",
           aThirdString = "M\xe4ssig, Ma\xdf",
           aTrueValue = True,
           aFalseValue = False,
       ),
       someData = b"<binary gunk>",
       someMoreData = b"<lots of binary gunk>" * 10,
       aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
   )
   with open(fileName, 'wb') as fp:
       dump(pl, fp)

plist 구문 분석하기:

   with open(fileName, 'rb') as fp:
       pl = load(fp)
   print(pl["aKey"])
