scrapbook
1.0.0
스크랩북 라이브러리는 노트북의 데이터 값과 생성된 시각적 콘텐츠를 "스크랩"으로 기록합니다. 녹음된 스크랩은 나중에 읽을 수 있습니다.
스크랩북 사용 방법에 대한 자세한 내용은 스크랩북 설명서를 참조하세요.
노트북 사용자는 노트북 실행 중에 생성된 데이터를 기록하기를 원할 수 있습니다. 이렇게 기록된 데이터인 스크랩은 나중에 사용하거나 워크플로우에서 다른 노트북에 입력으로 전달할 수 있습니다.
즉, 스크랩북을 사용하면 다음을 수행할 수 있습니다.
데이터 및 시각적 콘텐츠 표시를 노트북에 스크랩으로 유지
지속되는 데이터 스크랩을 모두 불러옵니다 .
노트북 모음집을 요약하다
이 라이브러리의 장기 지원 대상은 Python 3.6+입니다. 현재 Python 2가 2020년에 수명이 종료될 때까지 Python 2.7도 지원합니다. 이 날짜 이후에는 Python 2 지원이 중단되고 3.x 버전만 유지됩니다.
pip 사용하여 설치:
pip install scrapbook 선택적 IO 종속성을 설치하려면 s3 또는 azure 와 같은 개별 스토어 번들을 지정할 수 있습니다.
pip install scrapbook[s3] 또는 all 사용:
pip install scrapbook[all]스크랩북은 다음 항목을 정의합니다.
scraps : 문자열, 개체 목록, Pandas 데이터 프레임, 차트, 이미지 또는 데이터 참조와 같은 직렬화 가능한 데이터 값 및 시각화입니다.
노트북 : 스크랩과 상호작용하기 위한 추가 메소드가 포함된 랩핑된 nbformat 노트북 객체입니다.
스크랩북 : 컬렉션에 대해 질문할 수 있는 인터페이스가 있는 노트북 컬렉션입니다.
인코더 : 노트북 저장 형식으로/에서 데이터를 변환하는 등록된 변환기입니다.
scrap 모델 scrap 모델은 다음을 포함하여 튜플에 몇 가지 주요 속성을 포함합니다.
name : 스크랩의 이름
data : 스크랩북 API 호출로 캡처된 모든 데이터
인코더 : 노트북과 데이터를 인코딩/디코딩하는 데 사용되는 인코더의 이름입니다.
display : 시각적 콘텐츠를 표시하기 위해 IPython에서 사용하는 모든 디스플레이 데이터
스크랩북은 다음을 포함하여 데이터를 저장하고 검색할 수 있는 몇 가지 기본 API 명령을 추가합니다.
디스플레이 출력 유무에 관계없이 스크랩을 유지하기 위한 glue
read_notebook 하나의 노트북을 읽습니다.
scraps 이름별로 모든 스크랩의 검색 가능한 사전을 제공합니다.
다른 노트북의 스크랩을 현재 노트북에 복사하는 reglue
read_notebooks 지정된 경로에서 많은 노트북을 읽습니다.
scraps_report 수집된 스크랩에 대한 보고서를 표시합니다.
더 이상 사용되지 않는 두 가지 제지 기능에 대한 이전 버전과의 호환성을 위한 papermill_dataframe 및 papermill_metrics
다음 섹션에서는 이러한 API 명령에 대해 자세히 설명합니다.
glue 해당 노트북 셀에 scrap (데이터 또는 표시 값)을 기록합니다.
scrap (기록된 값)은 나중에 출력 노트를 검사할 때 검색할 수 있습니다.
"""데이터 값 기록을 위한 글루 예"""스크랩북을 sbsb.glue("hello", "world")sb.glue("number", 123)sb.glue("some_list", [1, 3, 5])sb.glue("some_dict", {"a": 1, "b": 2})sb.glue("non_json", df, '화살표') 스크랩북 라이브러리는 나중에 출력 노트북에서 scraps 복구하는 데 사용할 수 있습니다.
# 노트북을 읽고 이전에 기록된 스크랩을 가져옵니다.nb = sb.read_notebook('notebook.ipynb')nb.scraps 스크랩북은 등록된 데이터 인코더의 값 유형에 따른 저장 형식을 의미합니다. 또는 encoder 인수를 특정 인코더의 등록된 이름(예: "json" )으로 설정하여 묵시적 인코딩 형식을 덮어쓸 수 있습니다.
이 데이터는 콘텐츠 인코딩 형식과 데이터를 식별하는 특수 미디어 유형으로 디스플레이 출력을 생성하여 유지됩니다. 이러한 출력은 노트북 렌더링에 항상 표시되는 것은 아니지만 문서에는 계속 존재합니다. 그런 다음 스크랩북은 이러한 셀 출력을 읽어 나중에 노트북과 관련된 데이터를 다시 수화할 수 있습니다.
눈에 보이는 디스플레이 출력으로 명명된 스크랩을 표시하려면 스크랩이 직접 렌더링 가능함을 나타내야 합니다.
이는 display 인수를 전환하여 수행할 수 있습니다.
# 입력 문자열과 함께 UI 메시지를 기록합니다.b.glue("hello", "Hello World", display=True) 이 호출은 Scrap 개체의 데이터와 표시 속성을 저장하여 원래 데이터를 인코딩할 뿐만 아니라 표시되도록 합니다. 이는 IPython.core.formatters.format_display_data 함수를 사용하여 데이터 객체를 노트북 커널이 구문 분석할 수 있는 디스플레이 및 메타데이터 사전으로 변환합니다.
사용할 수 있는 또 다른 패턴은 원본 개체가 아닌 표시 데이터만 저장하도록 지정하는 것입니다. 이는 display 할 인코더를 설정하여 달성됩니다.
# 원래 입력 객체 없이 이미지를 기록합니다.b.glue("sharable_png", IPython.display.Image(filename="sharable.png"), 인코더='display')마지막으로 생성되는 미디어 유형은 목록, 튜플 또는 dict 개체를 표시 인수로 전달하여 제어할 수 있습니다.
sb.glue("media_as_text_only", media_obj, 인코더='display', display=('text/plain',) # 이는 [text/plain]을 format_display_data의 포함 인수에 전달합니다.)sb.glue("media_without_text", media_obj, 인코더 ='display', display={'exclude': 'text/plain'} # format_display_data의 kwargs로 전달) 데이터 스크랩과 마찬가지로 나중에 스크랩의 display 속성에 액세스하여 검색할 수 있습니다. 일반적으로 노트북의 reglue 방법(아래 설명)을 사용합니다.
read_notebook 하나의 노트북을 읽습니다. path 에 지정된 위치에서 로드된 Notebook 개체를 읽습니다. 위의 API 호출 예제에서 이 함수가 어떻게 사용되는지 이미 보았지만 본질적으로 이는 스크랩북 스크랩을 추출하는 기능과 함께 nbformat 의 NotebookNode에 대한 얇은 래퍼를 제공합니다.
nb = sb.read_notebook('노트북.ipynb')이 노트북 개체는 nbformat의 json 스키마를 준수하여 필수 필드에 대한 액세스를 허용합니다.
nb.cells # 노트북nb.metadatanb.nbformatnb.nbformat_minor의 셀
몇 가지 추가 방법이 제공되며, 그 중 대부분이 아래에 자세히 설명되어 있습니다.
nb.스크랩nb.reglue
또한 추상화를 통해 저장된 콘텐츠를 각 키와 소스를 참조하는 데이터 프레임으로 사용할 수 있습니다. 이러한 방법 중 더 많은 방법은 이후 버전에서 제공될 예정입니다.
# ["name", "data", "encoder", "display", "filename"]을 columnsnb.scrap_dataframe으로 사용하여 데이터 프레임을 생성합니다. # 경고: 데이터나 디스플레이가 큰 경우 대형 객체가 될 수 있습니다.
Notebook 개체에는 Papermill의 Notebook 개체 모델과의 하위 호환성을 위한 몇 가지 레거시 기능도 있습니다. 결과적으로 제지실 실행 통계와 스크랩북 추상화를 읽는 데 사용할 수 있습니다.
nb.cell_timing # 셀의 셀 실행 타이밍 목록 ordernb.execution_counts # 셀의 셀 실행 횟수 목록 ordernb.papermill_metrics # 셀 실행 횟수 및 시간의 데이터 프레임nb.papermill_record_dataframe # 노트북 레코드의 데이터 프레임(데이터만 포함된 스크랩)nb.parameter_dataframe # 노트북 매개변수의 데이터프레임nb.papermill_dataframe # 노트북 매개변수 및 셀 스크랩의 데이터프레임
노트북 리더는 Papermill에 등록된 iorw를 사용하여 S3, Azure, Google Cloud 등 다양한 소스에 액세스할 수 있습니다.
scraps 이름을 제공합니다 -> 스크랩 조회 scraps 방법을 사용하면 특정 노트북의 모든 스크랩에 액세스할 수 있습니다.
nb = sb.read_notebook('notebook.ipynb')nb.scraps # 이름별로 모든 스크랩의 사전을 인쇄합니다.이 객체에는 편리한 변환 및 실행을 위한 몇 가지 추가 메서드도 있습니다.
nb.scraps.data_scraps # `data`가 연관된 스크랩만 필터링합니다.nb.scraps.data_dict # `data_scraps`를 `name` -> `data`에 매핑합니다. dictnb.scraps.display_scraps # nb와 연관된 `display`가 있는 스크랩만 필터링합니다. scraps.display_dict # `display_scraps`를 `name` -> `display`에 매핑합니다. dictnb.scraps.dataframe # ["name", "data", "encoder", "display"]를 열로 사용하여 데이터프레임을 생성합니다.
이러한 방법을 사용하면 모델 추상화를 파고들 필요가 없는 간단한 사용 사례가 가능합니다.
reglue 스크랩을 현재 노트북에 복사합니다. reglue 사용하면 접착제로 붙인 스크랩을 하나의 노트북에 넣고 현재 노트북에 붙일 수 있습니다.
nb = sb.read_notebook('notebook.ipynb')nb.reglue("table_scrap") # 이는 데이터와 디스플레이를 모두 복사합니다. 모든 데이터나 표시 정보는 사용자가 원본 소스에서 다시 glue 호출한 것처럼 현재 실행 중인 노트북에 그대로 복사됩니다.
프로세스에서 스크랩의 이름을 바꾸는 것도 가능합니다.
nb.reglue("table_scrap", "old_table_scrap") 그리고 마지막으로 존재 여부를 확인하지 않고 다시 접착을 시도하려는 경우 raise_on_missing 실패 시 메시지를 표시하도록 설정할 수 있습니다.
nb.reglue("maybe_missing", raise_on_missing=False)# => "이 노트에는 'maybe_missing'이라는 이름의 스크랩이 없습니다."read_notebooks 많은 노트북을 읽습니다. 지정된 path 에 있는 모든 노트북을 스크랩북 개체로 읽어옵니다.
# `book`이라는 이름의 스크랩북을 만듭니다.book = sb.read_notebooks('path/to/notebook/collection/')# 기본 노트북을 listbook.notebooks로 가져옵니다 # 또는 `book.values` 경로는 papermill에 등록된 iorw 재사용하여 로컬이 아닌 URL이 데이터를 로드할 수 있도록 다양한 소스의 파일을 나열하고 읽습니다.
# `book`book = sb.read_notebooks('s3://bucket/key/prefix/to/notebook/collection/')이라는 이름의 스크랩북을 만듭니다. 스크랩북(이 예에서는 book )을 사용하여 노트북 컬렉션 전체의 모든 스크랩을 불러올 수 있습니다.
book.notebook_scraps # `notebook` 모양의 사전 -> (`name` -> `scrap`)book.scraps # `name` 모양의 병합된 사전 -> `scrap`
scraps_report 수집된 스크랩에 대한 보고서를 표시합니다. 스크랩북 컬렉션을 사용하면 컬렉션의 모든 스크랩에 대한 scraps_report 를 마크다운 구조화된 출력으로 생성할 수 있습니다.
book.scraps_report()
이 디스플레이는 스크랩 및 노트북 이름을 필터링할 수 있을 뿐만 아니라 디스플레이의 전체 헤더를 활성화하거나 비활성화할 수 있습니다.
book.scraps_report( scrap_names=["scrap1", "scrap2"], Notebook_names=["result1"], # 경로가 지정된 노트북 `/notebook/collections/result1.ipynb`와 일치 헤더=거짓)
기본적으로 보고서는 시각적 요소로만 채워집니다. 데이터 요소에 대해서도 보고하려면 include_data를 설정하세요.
book.scraps_report(include_data=True)
마지막으로 스크랩북은 더 이상 사용되지 않는 papermill 기능에 대해 두 가지 이전 버전과 호환되는 기능을 제공합니다.
book.papermill_dataframebook.papermill_metrics
인코더는 encoders.registry 개체에 대해 등록된 Encoder 개체에 대한 키 이름으로 액세스할 수 있습니다. 새로운 데이터 인코더를 등록하려면 다음을 호출하면 됩니다.
인코더에서 레지스트리 가져오기를 Encoder_registry#으로 레지스트리에 인코더 추가encoder_registry.register("custom_encoder_name", MyCustomEncoder()) encode 클래스는 encode 및 decode 두 가지 메서드를 구현해야 합니다.
class MyCustomEncoder(object):def encode(self, scrap):# scrap.data는 모든 유형이며 일반적으로 인코더 네임패스에 특정합니다. # `data` 유형이 있는 `Scrap`을 반환합니다. 유형은 [None, list, dict, *six .integer_types, *six.string_types]def decode(self, scrap):# scrap.data는 [None, list, dict, *six.integer_types, *six.string_types]pass # `data` 유형이 있는 `Scrap`을 임의의 유형으로 반환합니다. 일반적으로 인코더 이름에 따라 다릅니다.
변환 스크랩을 내용이나 위치를 나타내는 json 객체로 읽어 해당 문자열을 원래 데이터 객체에 다시 로드할 수 있습니다.
text데이터를 Python 문자열로 저장하는 기본 문자열 저장 형식입니다.
sb.glue("안녕하세요", "세계", "텍스트")json sb.glue("foo_json", {"foo": "bar", "baz": 1}, "json")pandas sb.glue("pandas_df",pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]}), "pandas")record 기능 스크랩북은 강력하고 유연한 기록 방식을 제공합니다. 이 라이브러리는 제지공장의 기존 record 기능을 대체합니다.
제지 공장 record 에 대한 문서는 ReadTheDocs에 있습니다. 간단히 말해서, 더 이상 사용되지 않는 record 기능은 다음과 같습니다.
pm.record(name, value) : 노트북에 값을 저장할 수 있도록 합니다. [API 문서]
pm.record("hello", "world")pm.record("number", 123)pm.record("some_list", [1, 3, 5])pm.record("some_dict", {"a" : 1, "b": 2}) pm.read_notebook(notebook) : pandas는 나중에 출력 노트북을 데이터프레임으로 읽어 기록된 값을 복구하는 데 사용할 수 있습니다. 예를 들어:
nb = pm.read_notebook('notebook.ipynb')nb.dataframerecord 지원 중단의 이론적 근거 Papermill의 record 기능은 다음과 같은 제한과 과제로 인해 더 이상 사용되지 않습니다.
record 기능은 Papermill의 노트북 선형 실행 패턴을 따르지 않았습니다. record 제지공장의 추가적인 기능으로 설명하는 것은 어색했고, 실제로는 덜 발전된 두 번째 도서관을 설명하는 것처럼 느껴졌습니다.
녹음/읽기에는 모든 데이터를 JSON으로 변환하는 것이 필요합니다. 이는 데이터프레임에 있어서 지루하고 고통스러운 프로세스입니다.
기록된 값을 데이터프레임으로 읽으면 데이터프레임 모양이 직관적이지 않게 됩니다.
맞춤형 운영자를 등록할 수 있는 다른 제지 공장 구성 요소보다 모듈성과 유연성이 낮습니다.
Papermill의 이러한 한계를 극복하기 위해 스크랩북을 만들기로 결정했습니다.
