API リファレンス

Table クラス

class tablelinker.core.table.Table(file: Optional[PathLike] = None, data: Optional[Union[str, bytes]] = None, sheet: Optional[str] = None, is_tempfile: bool = False, skip_cleaning: bool = False)

表形式データを管理するクラスです。

パラメータ:

file (File-like, Path-like) -- このテーブルが管理する入力表データファイルのパス、または file-like オブジェクト。
data (str, bytes) -- CSV 文字列。 file を指定した場合、 data は無視されます。
sheet (str, None) -- 入力ファイルが Excel の場合など、複数の表データを含む場合に対象を指定するためのシート名。省略された場合は最初の表。
is_tempfile (bool) -- 入力表データファイルが一時ファイルかどうかを表すフラグ。 True の場合、オブジェクトが消滅するときに file が指すパスにあるファイルも削除します。
skip_cleaning (bool) -- 表データを読み込む際にクリーニングをスキップするかどうかを指定するフラグ。 True を指定した場合、 file で指定したファイルは文字エンコーディングが UTF-8（BOM無し）、区切り文字はカンマ、先頭部分に説明などの余計な行が含まれていない CSV ファイルである必要があります。

file

パラメータ参照。 data で初期化した場合には、その内容を保存した一時ファイル名を参照します。

Type:: File-like, Path-like

sheet

パラメータ参照。

Type:: str, optional

is_tempfile

パラメータ参照。

Type:: bool

skip_cleaning

パラメータ参照。

Type:: bool

filetype

入力表データファイルの種別。 CSV の場合は csv、 Excel の場合は excel になります。

Type:: str

headers

表データの列ごとの見出しとデータ型を持つリストです。 open() を実行した時にファイルの内容から設定します。実行前は None です。

Type:: List[str, datatype]

サンプル

>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> table.write(lines=2)
観光スポット名称,所在地,緯度,経度,座標系,説明,八丈町ホームページ記載
ホタル水路,,33.108218,139.80102,JGD2011,八丈島は伊豆諸島で唯一、水田耕作がなされた島で鴨川に沿って水田が残っています。ホタル水路は、鴨川の砂防とともに平成元年につくられたもので、毎年6月から7月にかけてホタルの光が美しく幻想的です。,http://www.town.hachijo.tokyo.jp/kankou_spot/mitsune.html#01

サンプル

>>> from tablelinker import Table
>>> table = Table(data="国名,3文字コード\nアメリカ合衆国,USA\n日本,JPN\n")
>>> table.write(lineterminator="\n")
国名,3文字コード
アメリカ合衆国,USA
日本,JPN

メモ

Excel ファイルのシートを開きたい場合、 sheet オプションでシート名を指定します。
```
table = Table(ファイル名, sheet=シート名)
```
is_tempfile に True を指定した場合、オブジェクト削除時に file が指すファイルも削除されます。
CSV データが UTF-8、カンマ区切りの CSV であることが分かっている場合、 skip_cleaning に True を指定することでクリーニング処理をスキップして高速に処理できます。

apply(tasks: Union[Task, List[Task]]) → Table

テーブルが管理する表データにタスクを適用して変換し、変換結果を管理する新しい Table オブジェクトを返します。

パラメータ:: tasks (Task, List[Task]) -- 適用するタスク、またはタスクのリスト。
戻り値:: 変換結果を管理する Table オブジェクト。
戻り値の型:: Table

サンプル

>>> from tablelinker import Table, Task
>>> table = Table("ma030000.csv")
>>> table.write(lines=2)
,人口,出生数,死亡数,（再掲）,,自　然,死産数,,,周産期死亡数,,,婚姻件数,離婚件数
,,,,乳児死亡数,新生児,増減数,総数,自然死産,人工死産,総数,22週以後,早期新生児,,
>>> table.apply(Task.from_files("task1.json")).write(lines=2)
地域,人口,出生数,死亡数,（再掲）,,自　然,死産数,,,周産期死亡数,,,婚姻件数,離婚件数
,,,,乳児死亡数,新生児,増減数,総数,自然死産,人工死産,総数,22週以後,早期新生児,,
>>> tasks = Task.from_files(["task1.json", "task2.json"])
>>> table.apply(tasks).write(lines=3)
地域,人口,出生数,死亡数,（再掲）乳児死亡数,（再掲）新生児死亡数,自　然増減数,死産数総数,死産数自然死産,死産数人工死産,周産期死亡数総数,周産期死亡数22週以後の死産数,周産期死亡数早期新生児死亡数,婚姻件数,離婚件数
全　国,123398962,840835,1372755,1512,704,-531920,17278,8188,9090,2664,2112,552,525507,193253
01 北海道,5188441,29523,65078,59,25,-35555,728,304,424,92,75,17,20904,9070

close(): ファイルを閉じます。開いていない場合には何もしません。

convert(convertor: str, params: dict, output: Optional[PathLike] = None) → Table

テーブルが管理する表データにコンバータを適用して変換し、変換結果を管理する新しい Table オブジェクトを返します。

パラメータ:

convertor (str) -- 適用するコンバータ名 (例: 'rename_col')。
params (dict) -- コンバータに渡すパラメータ名・値の辞書。例: {"input_col_idx": 1, "new_col_name": "番号"}
output (Path-like, optional) -- 出力結果を保存する CSV ファイル名を指定します。省略した場合には一時ファイルを作成します。途中経過を保存したい場合に指定してください。ここで作成したファイルは変換処理完了後も削除されません。

戻り値:

変換結果を管理する Table オブジェクト。

戻り値の型:

Table

サンプル

>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> table.write(lines=1)
観光スポット名称,所在地,緯度,経度,座標系,説明,八丈町ホームページ記載
>>> table = table.convert(
...     convertor="rename_col",
...     params={"input_col_idx":0, "output_col_name":"名称"},
... )
>>> table.write(lines=1)
名称,所在地,緯度,経度,座標系,説明,八丈町ホームページ記載

メモ

変換結果はテンポラリディレクトリ (/tmp/ など) の下に table_ から始まるファイル名を持つファイルに出力されます。
このメソッドが返す Table オブジェクトが削除される際に、変換結果ファイルも自動的に削除されます。
ただしエラーや中断により途中で停止した場合には、変換結果ファイルが残る場合があります。

classmethod fromPandas(df: DataFrame) → Table

Pandas DataFrame から Table オブジェクトを作成します。

パラメータ:: df (pandas.core.frame.DataFrame) -- 表データを持つ Pandas DataFrame オブジェクト。
戻り値:: 新しい Table オブジェクト。
戻り値の型:: Table

サンプル

>>> from tablelinker import Table
>>> import pandas as pd
>>> df = pd.DataFrame({
...     "国名":["アメリカ合衆国","日本","中国"],
...     "3文字コード":["USA","JPN","CHN"],
... })
>>> table = Table.fromPandas(df)
>>> table.write(lineterminator="\n")
国名,3文字コード
アメリカ合衆国,USA
日本,JPN
中国,CHN

メモ

このメソッドは、一度 DataFrame のすべてのデータを CSV ファイル（一時ファイル）に出力します。

classmethod fromPolars(df) → Optional[Table]

Polars DataFrame から Table オブジェクトを作成します。

パラメータ:: df (polars.DataFrame) -- 表データを持つ Polars DataFrame オブジェクト。
戻り値:: 新しい Table オブジェクト。
戻り値の型:: Table

サンプル

>>> from tablelinker import Table
>>> import polars as pl
>>> df = pl.DataFrame({
...     "国名":["アメリカ合衆国","日本","中国"],
...     "3文字コード":["USA","JPN","CHN"],
... })
>>> df.columns
['国名', '3文字コード']
>>> table = Table.fromPolars(df)
>>> table.write(lineterminator="\n")
国名,3文字コード
アメリカ合衆国,USA
日本,JPN
中国,CHN

メモ

このメソッドは、一度 DataFrame のすべてのデータを CSV ファイル（一時ファイル）に出力します。

get_reader()

管理している表データへの reader オブジェクトを取得します。

戻り値:: reader オブジェクト。ただし open() を実行する前は None を返します。
戻り値の型:: csv.reader, csv.DictReader

mapping(template: Table, threshold: Optional[int] = None) → dict

他のテーブル（テンプレート）に変換するための対応表を生成します。

パラメータ:

template (Table) -- 変換対象のテーブルオブジェクト。
threshold (int, optional) -- 一致する列と判定する際のしきい値。0-100 で指定し、 0 の場合が最も緩く、100の場合は完全一致した場合しか対応しているとみなしません。

戻り値:

キーに変換先テーブルの列名、値にその列に対応すると判定された自テーブルの列名を持つ dict を返します。

戻り値の型:

dict

メモ

結果の dict はコンバータ mapping_cols の column_map パラメータにそのまま利用できます。

mapping_with_headers(headers: List[str], threshold: Optional[int] = None) → dict

テンプレートの見出し列に一致するように変換するための対応表を生成します。

パラメータ:

headers (List[str]) -- テンプレートの見出し列。
threshold (int, optional) -- 一致する列と判定する際のしきい値。0-100 で指定し、 0 の場合が最も緩く、100の場合は完全一致した場合しか対応しているとみなしません。

戻り値:

キーに変換先テーブルの列名、値にその列に対応すると判定された自テーブルの列名を持つ dict を返します。

戻り値の型:

dict

メモ

結果の dict はコンバータ mapping_cols の column_map パラメータにそのまま利用できます。

merge(target: Union[str, PathLike, Table])

Table オブジェクトが管理する表データを、指定したファイルまたは Table の末尾に結合 (merge) します。

パラメータ:: target (os.PathLike, Table) -- 結合先の CSV ファイルのパスまたは Table。

サンプル

>>> import shutil
>>> from tablelinker import Table
>>> _ = shutil.copy("katsushika_tourism.csv", "tourism.csv")
>>> table_src = Table("shimabara_tourism.csv")
>>> table_src.merge("tourism.csv")  # ファイルの末尾に結合
>>> with Table("tourism.csv").open() as reader:
...     nlines = 0
...     for _ in reader:
...         nlines += 1
...
>>> nlines
32

サンプル

>>> import shutil
>>> from tablelinker import Table
>>> _ = shutil.copy("katsushika_tourism.csv", "tourism.csv")
>>> table_src = Table("shimabara_tourism.csv")
>>> table_dst = Table("tourism.csv")
>>> table_src.merge(table_dst)  # 他のテーブルの末尾に結合
>>> with table_dst.open() as reader:
...     nlines = 0
...     for _ in reader:
...         nlines += 1
...
>>> nlines
32

メモ

結合先ファイルの列の順番に合わせて並べ替えます。
文字エンコーディングも結合先ファイルに合わせます。
見出し行は出力しません。

open(as_dict: bool = False, adjust_datatype: bool = False, **kwargs)

表データを開きます。既に開いている場合、先頭に戻します。

パラメータ:

as_dict (bool [False]) -- True が指定された場合、 csv.DictReader オブジェクトを返します。
adjust_datatype (bool [False]) -- True が指定された場合、列ごとにデータ型を推定してその型に合わせた値を返します。
kwargs (dict) -- csv.reader, csv.DictReader に渡すその他のパラメータ。

戻り値:

自分自身を返します。 Table はジェネレータ・イテレータインタフェースを備えているので、サンプルのように for 文で行を順番に読みだしたり、 with 構文でバインドすることができます。

戻り値の型:

Table

サンプル

>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> reader = table.open()
>>> for row in reader:
...     print(",".join(row[0:4]))
...
観光スポット名称,所在地,緯度,経度
ホタル水路,,33.108218,139.80102
登龍峠展望,,33.113154,139.835245
八丈富士,,33.139168,139.762187
永郷展望,,33.153559,139.747501
...

サンプル

>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> with table.open(as_dict=True) as dictreader:
...     for row in dictreader:
...         print(",".join([row[x] for x in [
...             "観光スポット名称", "所在地", "経度", "緯度"]]))
...
ホタル水路,,139.80102,33.108218
登龍峠展望,,139.835245,33.113154
八丈富士,,139.762187,33.139168
永郷展望,,139.747501,33.153559
...

サンプル

>>> import json
>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> with table.open(adjust_datatype=True) as reader:
...     for row in reader:
...         print(json.dumps(row[0:4], ensure_ascii=False))
...
["観光スポット名称", "所在地", "緯度", "経度"]
["ホタル水路", "", 33.108218, 139.80102]
["登龍峠展望", "", 33.113154, 139.835245]
["八丈富士", "", 33.139168, 139.762187]
["永郷展望", "", 33.153559, 139.747501]
...

メモ

CSV、タブ区切りテキスト、 Excel に対応しています。
表データの確認とクリーニングは、このメソッドが呼ばれたときに実行されます。

save(path: PathLike, encoding='utf-8', **fmtparams)

Table オブジェクトが管理する表データを csv.writer を利用して指定したパスのファイルに保存します。

パラメータ:

path (os.PathLike) -- 保存する CSV ファイルのパス。
encoding (str ["utf-8"]) -- テキストエンコーディング。
fmtparams (dict) -- csv.writer に渡すフォーマットパラメータ。

サンプル

>>> import csv
>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> table.save("hachijo_sightseeing_utf8.csv", quoting=csv.QUOTE_ALL)

toPandas() → DataFrame

Table オブジェクトから Pandas DataFrame を作成します。

戻り値の型:: pandas.core.frame.DataFrame

サンプル

>>> import pandas as pd
>>> from tablelinker import Table
>>> table = Table(data="国名,3文字コード\nアメリカ合衆国,USA\n日本,JPN\n")
>>> df = table.toPandas()
>>> df.columns
Index(['国名', '3文字コード'], dtype='object')

toPolars()

Table オブジェクトから Polars DataFrame を作成します。

戻り値の型:: polars.DataFrame

サンプル

>>> import polars as pl
>>> from tablelinker import Table
>>> table = Table(data="国名,3文字コード\nアメリカ合衆国,USA\n日本,JPN\n")
>>> df = table.toPolars()
>>> df.columns
['国名', '3文字コード']

メモ

Table オブジェクトが明示的にクリーニング不要（skip_cleaning = True）な CSV ファイルを参照している場合、 Polars DataFrame も直接そのファイルを開きます。
それ以外の場合は、一度 Table が参照しているすべてのデータをメモリに読み込んでから Polars DataFrame に渡すため、ファイルサイズが大きい場合には時間がかかることがあります。

to_str(**kwargs)

write() を利用して、クリーンな CSV 文字列を返します。

パラメータ:: **kwargs (dict) -- write() に渡すパラメータを指定します。
戻り値:: CSV 文字列を含む文字列。
戻り値の型:: str

メモ

このメソッドはメモリ上に表データのコピーを作成します。

classmethod useExtraConvertors() → None

拡張コンバータを利用することを宣言します。

メモ

tablelinker.useExtraConvertors() と等価です。

write(lines: int = -1, file=None, skip_header: bool = False, **fmtparams)

入力 CSV データを csv.writer を利用して指定したファイルオブジェクトに出力します。

パラメータ:

lines (int [default:-1]) -- 出力する最大行数。省略された場合、または負の場合は全ての行を出力します。
file (File-like オブジェクト [default: None]) -- 出力先のファイルオブジェクト。省略された場合または None が指定された場合は標準出力。
skip_header (bool [default: False]) -- 見出し行をスキップする場合は True を指定します。
fmtparams (dict) -- csv.writer に渡すフォーマットパラメータ。

サンプル

>>> import csv
>>> from tablelinker import Table
>>> table = Table("sample/datafiles/hachijo_sightseeing.csv")
>>> with open("hachijo_2.csv", "w", newline="") as f:
...     table.write(lines=2, file=f, quoting=csv.QUOTE_ALL)
...

Task クラス

class tablelinker.core.task.Task(convertor: str, params: dict, note: Optional[str] = None)

タスクを管理するクラス。

パラメータ:

convertor (str) -- コンバータ名。
params (dict) -- パラメータ名と値を持つ dict。
note (str, optional) -- タスクの内容に対するメモ。

convertor

パラメータ参照。

Type:: str

params

パラメータ参照。

Type:: dict

note

指定されている場合、変換処理実行時にタスク名をロガーに INFO レベルで出力します。

Type:: str, optional

classmethod create(task: dict) → Task

dict から Task を作成します。パラメータのキーのチェックも行います。

パラメータ:: task (dict) -- キーに "convertor", "params" を必ず含み、オプションとして "note" を含む dict。
戻り値:: 新しい Task オブジェクト。
戻り値の型:: Task

サンプル

>>> from tablelinker import Task
>>> task = Task.create({
...     "convertor": "rename_col",
...     "params": {"input_col_idx":1, "output_col_name":"地域"},
... })
>>> task
rename_col

サンプル

>>> # 不要なキーが含まれていると ValueError を送出します
>>> from tablelinker import Task
>>> task = Task.create({
...     "convertor_name": "rename_col",
...     "params": {"input_col_idx":1, "output_col_name":"地域"},
... })
Traceback (most recent call last):
ValueError: 未定義のキー 'convertor_name' が使われています。

サンプル

>>> # 必要なキーが含まれていない場合も ValueError を送出します
>>> from tablelinker import Task
>>> task = Task.create({
...     "convertor": "rename_col",
... })
Traceback (most recent call last):
ValueError: キー 'params' が必要です。

サンプル

>>> # 未定義のコンバータを指定した場合も ValueError を送出します
>>> from tablelinker import Task
>>> task = Task.create({
...     "convertor": "undefined_convertor",
...     "params": {"input_col_idx": 1},
... })
Traceback (most recent call last):
ValueError: コンバータ 'undefined_convertor' は登録されていません。

サンプル

>>> # ただし params の内容は変換実行時までチェックしません
>>> from tablelinker import Task
>>> task = Task.create({
...     "convertor": "rename_col",
...     "params": None,
... })
>>> task
rename_col

メモ

必要なキーが欠けていたり、不要なキーが含まれていると ValueError 例外を送出します。
キーのチェックしかしないため、正しくない値が指定されていてもエラーにはなりません。
たとえば params にそのコンバータでは利用できないパラメータが指定されていてもエラーになりません。

classmethod from_files(taskfiles: Union[str, PathLike, List[PathLike]], *args) → List[Task]

タスクファイルを読み込み、解析・検証してタスクリストを作成します。

パラメータ:

taskfiles (str, PathLike, List[PathLike]) -- タスクファイルのパス、またはパスのリスト。
args (List[str, PathLike]) -- 追加のタスクファイルのパス。

戻り値:

タスクのリスト。

戻り値の型:

List[Task]

サンプル

>>> # タスクファイルを1つ指定すると、タスクを1つ含むリストを返します。
>>> from tablelinker import Task
>>> Task.from_files("task1.json")
[rename_col]

サンプル

>>> # タスクファイルのリストを指定すると、複数のタスクを含むリストを返します。
>>> Task.from_files(["task1.json", "task2.json"])
[rename_col, concat_title]

サンプル

>>> # タスクファイルを複数のパラメータとして指定しても、複数のタスクを含むリストを返します。
>>> Task.from_files("task1.json", "task2.json")
[rename_col, concat_title]

メモ

タスクが1つの場合でもリストを返します。