セクションの複数ページをまとめています。印刷またはPDF形式で保存...

最適な出力のために、Google Chrome（15以降）または Microsoft Edge（79以降）を推奨いたします。

2024-05-17 現在

mwings.common モジュール

mwings.common

ライブラリ全体で使用するデータや手続きを格納しています。

src/mwings/common.py

`AccelEvent`

加速度イベントの識別子

継承：enum.IntEnum

DICE_1 サイコロ：1
DICE_2 サイコロ：2
DICE_3 サイコロ：3
DICE_4 サイコロ：4
DICE_5 サイコロ：5
DICE_6 サイコロ：6
SHAKE シェイク
MOVE ムーブ
NONE イベントなし

`AppPalNoticeBlinkSpeed`

通知パル／点滅速度の識別子

継承：enum.IntEnum

ALWAYS_ON 常時点灯
SLOW おちついた点滅
MEDIUM ほどほどの点滅
FAST せわしない点滅

`AppPalNoticeColor`

通知パル／点灯色の識別子

継承：enum.IntEnum

RED 赤
GREEN 緑
BLUE 青
YELLOW 黄
PURPLE 紫
LIGHT_BLUE 水色
WHITE 白
WARM_WHITE 暖かな白

`AppPalNoticeRGBWColor`

通知パル／RGBWによる点灯色のデータ

継承：pydantic.BaseModel

`AppPalNoticeRGBWColor()`

AppPalNoticeRGBWColor(*, red=0, green=0, blue=0, white=15)

引数

名称	型	内容
`red`	`common.UInt8`	赤：`0`-`0xF`
`green`	`common.UInt8`	緑：`0`-`0xF`
`blue`	`common.UInt8`	青：`0`-`0xF`
`white`	`common.UInt8`	白：`0`-`0xF`

** で unpack した辞書を渡すことができます。

`u16()`

u16()

RGBWの16ビット表現を取得します。

引数

なし

戻り値

型	値	内容
`common.UInt16`	-	RGBWの16ビット表現

`BarePacket`

素のパケットデータ

継承：pydantic.BaseModel

`BarePacket()`

BarePacket(payload, checksum=None, logical_and_command_id=None)

引数

名称	型	内容
`payload`	`bytes`	ペイロードのバイナリデータ
`checksum`	`optional common.UInt8`	LRC8：`None`で自動計算
`logical_and_command_id`	`optional tuple(common.UInt8, common.UInt8)`	論理デバイスIDとコマンドID

第3引数を指定する場合は、ペイロードの冒頭を省略します。

`i16_at()`

i16_at(index)

指定した位置の符号あり16ビット整数を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける位置

戻り値

型	値	内容
`common.Int16`	-	数値データ

`i32_at()`

i32_at(index)

指定した位置の符号あり32ビット整数を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける位置

戻り値

型	値	内容
`common.Int32`	-	数値データ

`i8_at()`

i8_at(index)

指定した位置の符号あり8ビット整数を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける位置

戻り値

型	値	内容
`common.Int8`	-	数値データ

`u16_at()`

u16_at(index)

指定した位置の符号なし16ビット整数を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける位置

戻り値

型	値	内容
`common.UInt16`	-	数値データ

`u32_at()`

u32_at(index)

指定した位置の符号なし32ビット整数を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける位置

戻り値

型	値	内容
`common.UInt32`	-	数値データ

`u8_at()`

u8_at(index)

指定した位置の符号なし8ビット整数を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける位置

戻り値

型	値	内容
`common.UInt8`	-	数値データ

`u8_from()`

u8_from(index)

指定した位置に続くバイト列を取得します。

引数

名称	型	内容
`index`	`int`	ペイロードにおける先頭の位置

戻り値

型	値	内容
`optional bytes`	`bytes`	部分的なバイト列
	`None`	指定位置が無効

`CommandBase`

コマンドの抽象基底クラス

継承：ABC, pydantic.BaseModel

`CommandBase()`

CommandBase(*, destination_logical_id=120)

引数

名称	型	内容
`destination_logical_id`	`common.UInt8`	送信先の論理デバイスID

** で unpack した辞書を渡すことができます。

`is_valid()`

is_valid()

コマンドデータが有効であるか否かを確認します。

引数

なし

戻り値

型	値	内容
`bool`	`True`	有効
	`False`	無効

`CommandSerializerBase`

コマンドシリアライザの静的抽象基底クラス

継承：ABC

`serialize()`

serialize(command)

与えられたコマンドを素のパケットのバイト列へ展開します。

引数

名称	型	内容
`command`	`common.SomeCommand`	何らかのコマンドデータ

戻り値

型	値	内容
`optional common.BarePacket`	`common.BarePacket`	展開したデータ
	`None`	無効なコマンドデータである

`CrossSectional[T]`

特定の時刻における横断的なデータ列を格納するためのタプルに相当するクラス

継承：common.FixedTuple[T]

`CrossSectional[T]()`

CrossSectional[T](length, elements)

引数

名称	型	内容
`T`	`common.T`	要素の型
`length`	`int`	要素の数
`elements`	`Iterable[T]`	要素

例外

ValueError 要素の数が不正

`DtypedDecimal`

pandas の dtype 属性を保持する数値型のための抽象基底クラス

`get_dtype()`

get_dtype()

pandas の dtype 識別子を取得します。

引数

なし

戻り値

型	値	内容
`str`	-	`dtype` 識別子

`FixedList[T]`

固定長リストに相当するクラス

継承：MutableSequence[T]

`FixedList[T]()`

FixedList[T](length, initial_elements)

引数

名称	型	内容
`T`	`common.T`	要素の型
`length`	`int`	要素の数
`initial_elements`	`Iterable[T]`	初期の要素

例外

ValueError 要素の数が不正

`insert()`

insert(index, value)

指定した位置へ要素を配置します。

引数

名称	型	内容
`index`	`int`	配置する位置
`value`	`common.T`	配置する要素

戻り値

なし

例外

IndexError 位置が不正

`FixedTuple[T]`

固定長タプルに相当するクラス

継承：Sequence[T]

`FixedTuple[T]()`

FixedTuple[T](length, elements)

引数

名称	型	内容
`T`	`common.T`	要素の型
`length`	`int`	要素の数
`elements`	`Iterable[T]`	要素

例外

ValueError 要素の数が不正

`Float32`

32ビット浮動小数点数を格納するクラス

継承：float, common.DtypedDecimal

`Float32()`

Float32(value=None)

引数

名称	型	内容
`value`	`optional float`	初期の値

例外

ValueError 範囲外の値

`Float64`

64ビット浮動小数点数を格納するクラス

継承：float, common.DtypedDecimal

`Float64()`

Float64(value=None)

引数

名称	型	内容
`value`	`optional float`	初期の値

例外

ValueError 範囲外の値

`Int16`

16ビット整数を格納するクラス

継承：int, common.DtypedDecimal

`Int16()`

Int16(value=None)

引数

名称	型	内容
`value`	`optional int`	初期の値

例外

ValueError 範囲外の値

`hex()`

hex()

16進数表記の文字列を取得します。

Python 組み込み関数の hex() は int のサブクラスを受け付けません。float に対する組み込みメソッド hex() と同じように扱えるようにしています。

引数

なし

戻り値

型	値	内容
`str`	-	16進数表記の文字列（小文字）

`Int32`

32ビット整数を格納するクラス

継承：int, common.DtypedDecimal

`Int32()`

Int32(value=None)

引数

名称	型	内容
`value`	`optional int`	初期の値

例外

ValueError 範囲外の値

`hex()`

hex()

16進数表記の文字列を取得します。

Python 組み込み関数の hex() は int のサブクラスを受け付けません。float に対する組み込みメソッド hex() と同じように扱えるようにしています。

引数

なし

戻り値

型	値	内容
`str`	-	16進数表記の文字列（小文字）

`Int8`

8ビット整数を格納するクラス

継承：int, common.DtypedDecimal

`Int8()`

Int8(value=None)

引数

名称	型	内容
`value`	`optional int`	初期の値

例外

ValueError 範囲外の値

`hex()`

hex()

16進数表記の文字列を取得します。

Python 組み込み関数の hex() は int のサブクラスを受け付けません。float に対する組み込みメソッド hex() と同じように扱えるようにしています。

引数

なし

戻り値

型	値	内容
`str`	-	16進数表記の文字列（小文字）

`MagnetState`

磁石イベントの識別子

継承：enum.IntEnum

NOT_DETECTED 磁石なし
N_POLE_IS_CLOSE N極が近くにある
S_POLE_IS_CLOSE S極が近くにある

`PacketParserBase`

パケットパーサの静的抽象基底クラス

継承：ABC

`is_valid()`

is_valid(bare_packet)

与えられた素のパケットが有効であるか否かを確認します。

引数

名称	型	内容
`bare_packet`	`common.BarePacket`	素のパケットデータ

戻り値

型	値	内容
`bool`	`True`	有効、パース可
	`False`	無効、パース不可

`parse()`

parse(bare_packet)

与えられた素のパケットをパースします。

引数

名称	型	内容
`bare_packet`	`common.BarePacket`	素のパケットデータ

戻り値

型	値	内容
`optional common.ParsedPacketBase`	`common.ParsedPacketBase`を基底クラスにもつデータ	パースしたデータ
	`None`	パース不可

`PacketType`

パケット種別の識別子

継承：enum.StrEnum

BARE 素のパケット（未パース）
ACT act
APP_TWELITE 超簡単！標準アプリ
APP_IO リモコンアプリ
APP_ARIA アリアアプリ
APP_CUE キューアプリ（TWELITE CUE モード）
APP_CUE_PAL_EVENT キューアプリ（動作パルモード：ダイス／ムーブモード）
APP_PAL_OPENCLOSE パルアプリ（開閉パル）
APP_PAL_AMB パルアプリ（環境パル）
APP_PAL_MOT パルアプリ（動作パル）／キューアプリ（動作パルモード：加速度計測）
APP_UART_ASCII シリアル通信アプリ（書式モード：簡易形式）／超簡単！標準アプリ／リモコンアプリ
APP_UART_ASCII_EXTENDED シリアル通信アプリ（書式モード：拡張形式）

`ParsedPacketBase`

パース済みパケットの抽象基底クラス

継承：ABC, pydantic.BaseModel

`ParsedPacketBase()`

ParsedPacketBase(*, time_parsed=None, packet_type=PacketType.BARE, sequence_number=None, source_serial_id=0, source_logical_id=0, lqi=None, supply_voltage=None)

引数

名称	型	内容
`time_parsed`	`optional AwareDatetime`	パース時刻
`packet_type`	`common.PacketType`	パケット種別
`sequence_number`	`optional common.UInt16`	シーケンス番号
`source_serial_id`	`common.UInt32`	送信元のシリアルID
`source_logical_id`	`common.UInt8`	送信元の論理デバイスID
`lqi`	`common.UInt8`	電波通信品質
`supply_voltage`	`optional common.UInt16`	電源電圧（mV）

** で unpack した辞書を渡すことができます。

コンストラクタの引数へ指定する変数に加えて、次の @computed_field を持ちます。

名称	型	内容
`mwings_implementation`	`str`	MWings の実装（`"python"`のみ）
`mwings_version`	`str`	MWings のバージョン（PEP440形式）
`hostname`	`str`	ホストマシン名
`system_type`	`str`	システム種別（`"Linux"`など）

適用される field_validator

source_logical_id：値の範囲を自動的に検証します
- check_source_logical_id(lid)
time_parsed：タイムゾーンが付与されているかを自動的に検証します
- datetime_must_be_clear(dt)

適用される field_serializer

packet_type：列挙子の名前をそのままJSON等に適用します
- serialize_packet_type(packet_type)
source_serial_id：16進表記の文字列をJSON等に適用します
- serialize_source_serial_id(source_serial_id)
time_parsed：ISO 8601形式の文字列をJSON等に適用します
- serialize_time_parsed(dt)

`to_df()`

to_df(include=None, exclude=None, verbose=True)

パースしたデータを pandas のデータフレーム形式へ変換します。

引数

名称	型	内容
`include`	`optional set[str]`	データフレームへ含めるカラム（メンバ）の集合
`exclude`	`optional set[str]`	データフレームへ含めないカラム（メンバ）の集合
`verbose`	`bool`	システム情報の有無（他の引数が`None`の場合のみ）

戻り値

型	値	内容
`pd.DataFrame`	-	変換したデータフレーム

例外

EnvironmentError pandas のない場合

`to_dict()`

to_dict(include=None, exclude=None, verbose=True, spread=False, sort_keys=False)

パースしたデータを辞書形式へ変換します。

引数

名称	型	内容
`include`	`optional set[str]`	辞書へ含めるキー（メンバ）の集合
`exclude`	`optional set[str]`	辞書へ含めないキー（メンバ）の集合
`verbose`	`bool`	システム情報の有無（他の引数が`None`の場合のみ）
`spread`	`bool`	時系列でないlist-likeデータの分割の有無
`sort_keys`	`bool`	キーによるソートの有無

spread を設定すると、common.CrossSectional[T]型のデータを分割します。例えば、超簡単！標準アプリのdi_state[4]をdi_state_1/di_state_2/di_state_3/di_state_4へ分割します。common.TimeSeries[T]型の時系列データは分割しません。

戻り値

型	値	内容
`dict[str, Any]`	-	変換した辞書

`to_json()`

to_json(include=None, exclude=None, verbose=True, spread=False, indent=2, sort_keys=False)

パースしたデータをJSON形式へ変換します。

引数

名称	型	内容
`include`	`optional set[str]`	JSONへ含めるキー（メンバ）の集合
`exclude`	`optional set[str]`	JSONへ含めないキー（メンバ）の集合
`verbose`	`bool`	システム情報の有無（他の引数が`None`の場合のみ）
`spread`	`bool`	時系列でないlist-likeデータの分割の有無
`indent`	`optional int`	インデントの数（`None`で改行なし）
`sort_keys`	`bool`	キーによるソートの有無

戻り値

型	値	内容
`str`	-	変換したJSON文字列

`SomeCallable`

TypeVar("SomeCallable", bound=Callable[..., Any])

各種ハンドラを表す型

`SomeCommand`

TypeVar(‘SomeCommand’, bound=CommandBase)

各種コマンドデータを表す型

`SomeParsedPacket`

TypeVar(‘SomeParsedPacket’, bound=ParsedPacketBase)

各種パケットデータを表す型

`T`

TypeVar("T")

ジェネリクスで利用する型

`TimeSeries[T]`

時系列データを格納するためのタプルに相当するクラス

継承：common.FixedTuple[T]

`TimeSeries[T]()`

TimeSeries[T](length, elements)

引数

名称	型	内容
`T`	`common.T`	要素の型
`length`	`int`	要素の数
`elements`	`Iterable[T]`	要素

例外

ValueError 要素の数が不正

`Timezone`

全体へ適用するtzinfo

`UInt16`

16ビット非不整数を格納するクラス

継承：int, common.DtypedDecimal

`UInt16()`

UInt16(value=None)

引数

名称	型	内容
`value`	`optional int`	初期の値

例外

ValueError 範囲外の値

`hex()`

hex()

16進数表記の文字列を取得します。

Python 組み込み関数の hex() は int のサブクラスを受け付けません。float に対する組み込みメソッド hex() と同じように扱えるようにしています。

引数

なし

戻り値

型	値	内容
`str`	-	16進数表記の文字列（小文字）

`UInt32`

32ビット非不整数を格納するクラス

継承：int, common.DtypedDecimal

`UInt32()`

UInt32(value=None)

引数

名称	型	内容
`value`	`optional int`	初期の値

例外

ValueError 範囲外の値

`hex()`

hex()

16進数表記の文字列を取得します。

Python 組み込み関数の hex() は int のサブクラスを受け付けません。float に対する組み込みメソッド hex() と同じように扱えるようにしています。

引数

なし

戻り値

型	値	内容
`str`	-	16進数表記の文字列（小文字）

`UInt8`

8ビット非不整数を格納するクラス

継承：int, common.DtypedDecimal

`UInt8()`

UInt8(value=None)

引数

名称	型	内容
`value`	`optional int`	初期の値

例外

ValueError 範囲外の値

`hex()`

hex()

16進数表記の文字列を取得します。

Python 組み込み関数の hex() は int のサブクラスを受け付けません。float に対する組み込みメソッド hex() と同じように扱えるようにしています。

引数

なし

戻り値

型	値	内容
`str`	-	16進数表記の文字列（小文字）