otsucfgmng 1.4.0.312

設定ファイルを扱うクラスを生成するライブラリです。

• 概要
  • インストール
  • 使い方
  • メソッド一覧
  • Q&A
  • プロトコル

概要

このライブラリはjson形式の設定ファイルの読み書きを補助するための基底クラスです。
BaseCMクラスを継承し、__defaults__, <attributes>を定義するだけで必要な操作を行えるようになります。

現在違うセクションに同じキーを持つような設定ファイルには対応していません。
対応しないことに決定しました。(理由はこちら)

このライブラリは以下の環境で作成されています。 Windows10(64bit), Python3.12.1

# 違うセクションに同じキーを持つ例
{
    'app': {'name': 'Hello'},
    'default': {'name': 'Python'}
}

インストール

インストール

pip install otsucfgmng

アップデート

pip install -U otsucfgmng

アンインストール

pip uninstall otsucfgmng

使い方

1. otuvalidatorをインポートし、必要なバリデータ、コンバータを使用できるようにする
   • 自作クラスなどを使用したい場合にはOtsuValidatorや実際のコードを参考に定義する(参考例)
2. otsucfgmngをインポートし、BaseCMを使用できるようにする
3. BaseCMを継承したクラスを定義する
   1. 属性__defaults__に辞書形式で利用する属性名とその初期値を与える
   2. __hidden_options__で隠しオプションを設定する (必要に応じて)
   3. __defaults__で宣言した属性名に1.で用意したコンバータを与える
4. 設定ファイルのパスを与えてインスタンスを作成する
5. インスタンスの属性を書き換えて編集を行う
6. save_cmを呼び出せば設定ファイルが出力される

実行例-設定ファイル管理クラス

• 作成
• 読み込み

作成-設定ファイル管理クラス

実行例に戻る

cfg.jsonという設定ファイルを作成していきます。

# 1.
from otsuvalidator import CBool, CInt, CPath, CString

# 2.
from otsucfgmng import BaseCM


# 3.
class ConfigurationManager(BaseCM):
    # 3.1.
    __defaults__ = {
        'app': {
            'library': 'SampleLibrary.dll',
            'scripts': 'SampleScripts.scrpt',
            'title': 'Sample Program',
            'fullscreen': False
        },
        'audio': {
            'bgm': 100,
            'bgs': 100,
            'se': 100,
            'me': 85
        }
    }

    # 3.3.
    library = CPath('dll')
    scripts = CPath('scrpt')
    title = CString(1, checker=str.istitle)
    fullscreen = CBool()
    bgm = CInt(0, 100)
    bgs = CInt(0, 100)
    se = CInt(0, 100)
    me = CInt(0, 100)


# 4.
cm = ConfigurationManager('cfg.json')

# 5.
cm.bgm = 99
cm.bgs = 50

# 6.
cm.save_cm()

上記の処理で作成されたcfg.jsonの中身は以下の通りです。

{
    "app": {},
    "audio": {
        "bgm": 99,
        "bgs": 50
    }
}

読み込み-設定ファイル管理クラス

実行例に戻る

正しい形式で出力された設定ファイルをインスタンスの生成時に与えると自動で設定を読み込みます。

from otsuvalidator import CBool, CInt, CPath, CString

from otsucfgmng import BaseCM


class ConfigurationManager(BaseCM):
    __defaults__ = {
        'app': {
            'library': 'SampleLibrary.dll',
            'scripts': 'SampleScripts.scrpt',
            'title': 'Sample Program',
            'fullscreen': False
        },
        'audio': {
            'bgm': 100,
            'bgs': 100,
            'se': 100,
            'me': 85
        }
    }
    library = CPath('dll')
    scripts = CPath('scrpt')
    title = CString(1, checker=str.istitle)
    fullscreen = CBool()
    bgm = CInt(0, 100)
    bgs = CInt(0, 100)
    se = CInt(0, 100)
    me = CInt(0, 100)

# コンテキストマネージャを使用すると自動でsave_cmされます。
with ConfigurationManager('cfg.json') as cm:
    print(cm.user_cm())
    cm.fullscreen = 'yes'
    print(cm.user_cm())

### 出力は以下のようになります ###
{'app': {}, 'audio': {'bgs': 50, 'bgm': 99}}
{'app': {'fullscreen': True}, 'audio': {'bgs': 50, 'bgm': 99}}

上記の処理で作成されたcfg.jsonの中身は以下の通りです。

{
    "app": {
        "fullscreen": true
    },
    "audio": {
        "bgs": 50,
        "bgm": 99
    }
}

隠しオプション

先ほどのコードに隠しオプションを追加します。
方法はシンプルで、__hidden_options__に対象の属性名のタプルを渡すだけです。
今回はfullscreenとme属性を隠しオプションにしてみます。

from otsuvalidator import CBool, CInt, CPath, CString

from otsucfgmng import BaseCM


class ConfigurationManager(BaseCM):
    __defaults__ = {
        'app': {
            'library': 'SampleLibrary.dll',
            'scripts': 'SampleScripts.scrpt',
            'title': 'Sample Program',
            'fullscreen': False
        },
        'audio': {
            'bgm': 100,
            'bgs': 100,
            'se': 100,
            'me': 85
        }
    }
    __hidden_options__ = ('fullscreen', 'me')  # この行を追加
    library = CPath('dll')
    scripts = CPath('scrpt')
    title = CString(1, checker=str.istitle)
    fullscreen = CBool()
    bgm = CInt(0, 100)
    bgs = CInt(0, 100)
    se = CInt(0, 100)
    me = CInt(0, 100)


with ConfigurationManager('cfg.json') as cm:
    print(cm.cfg_to_str_cm(True))

出力

{
    "defaults": {
        "app": {
            "fullscreen": false,
            "library": "SampleLibrary.dll",
            "scripts": "SampleScripts.scrpt",
            "title": "Sample Program"
        },
        "audio": {
            "bgm": 100,
            "bgs": 100,
            "se": 100
        }
    },
    "user": {
        "app": {
            "fullscreen": true
        },
        "audio": {
            "bgm": 99,
            "bgs": 50
        }
    }
}

cfg.jsonはここで作成されたものが存在する前提になります。
隠しオプションに設定したmeは表示されていませんが、fullscreenは表示されていることがわかるかと思います。
これはfullscreenが変更可能であることを知っている場合には隠す意味がないからです。

メソッド一覧

argparseやGUIなどで設定項目を編集するための補助を想定しています。
showコマンドを作成してcfg_to_str_cmを制御するなど、自身のUIに合うように紐づけて使ってください。

名前	概要	戻り値	戻り値型
cfg_to_str_cm	設定をjson.dumpsして返す allをTrueにしている場合は標準設定も表示される ユーザが変更していない__hidden_options__は表示されない ユーザに設定を見せる場合にはこのメソッドを使って出力する	設定	str
load_cm	設定ファイルを読み込む __init__から勝手に呼び出されるので、基本的に使用する必要はない		None
save_cm	現在の設定を書き出す コンテキストマネージャを使用していれば勝手に呼び出される		None
reset_cm	各属性を初期値に戻す		None
defaults_cm	__defaults__のコピーを返す	初期設定	dict
user_cm	ユーザが変更した属性の辞書を返す	変更された設定	dict
key_place_cm	各属性がどのセクションに属するかを記録した辞書を返す ユーザにアクセスを許すと__hidden_options__が意味をなくす	属性の所属先	dict
attributes_cm	設定項目の一覧を返す ユーザにアクセスを許すと__hidden_options__が意味をなくす	設定項目の一覧	set

Q&A

以下の説明でcmが登場した場合、ユーザが定義した設定ファイル管理クラスのインスタンスだと解釈してください。

• なぜ異なるセクションで同名キーを持てないようにしましたか？
• 自作クラスを使用する場合に必要なバリデータとコンバータをどう用意すればいいですか？

なぜ異なるセクションで同名キーを持てないようにしましたか？

1. 残念ながらライブラリ作成者の技術的な面も大きいです。
2. 後述する理由を克服、緩和する方法が追加、あるいは理解できれば異なるセクションでの同名キーを持てるようになる可能性もなくはないです。

ロガーの設定ファイルなど、異なるセクションで同名キーを持ちたい状況はありますが、それに対応する場合、アクセスが複雑になりすぎる恐れがあります。

例えば、現在の属性へのアクセスcm.<key>に加えて、辞書を持つキーをSectionクラスとして変換すればcm.<section>.<key>, cm.<sectionA>.<sectionB>.~.<key>というように管理することは技術的に可能になります。

しかしそうなると、実行例で使用したような構造の設定ではアクセスが煩雑になるデメリットもあります。
cm.fullscreenでアクセスしていたものがcm.app.fullscreenとなる等。
また、動的にクラスを生成する都合上、コード入力支援が受けられず、ヒューマンエラーのリスクも上がってしまいます。

自作クラスを使用する場合に必要なバリデータとコンバータをどう用意すればいいですか？

1. otsuvalidator.basesからConverter, Validatorをインポートし、使用できるようにする
   1. その他必要なライブラリをインポート
2. 自作クラスを定義する
   1. 好きなようにクラスを設計する (__eq__メソッドを定義していない場合__hidden_options__が正常に機能しない場合があります)
   2. __str__かto_jsonメソッドを定義する
3. 自作クラスに対応したValidatorを定義する(以下そのValidatorをVMyClassとする)
4. VMyClassとConverterを継承したCMyClassを定義する
5. 使い方どおり

実行例-自作クラスの使用

• 作成
• 読み込み

作成-自作クラスの使用

実行例に戻る

my_company.jsonという設定ファイルを作成していきます。

ConfigurationManagerではjson.dumpできない属性はotsucfgmng.funcs.support_json_dump関数で変換を試みます(※独自に指定しない限り)
この関数ではto_jsonを持つクラスをcls.to_jsonで、それ以外のクラスをstr(cls)で変換します。
なので、cls.to_jsonで返る値をclsに復元できるようなConverterを定義すれば読み込み時に復元されます。

# 1. & 1.1.
from typing import Any

from otsuvalidator import CNoneable
from otsuvalidator.bases import Converter, Validator

from otsucfgmng import BaseCM


# 2.
class Person:
    # 2.1.
    def __init__(self, name: str, age: int, gender: str):
        self.name = name
        self.age = age
        self.gender = gender

    def show_profile(self):
        print(self)

    # 2.2.
    def __str__(self) -> str:
        data = (
            ('名前', self.name),
            ('年齢', self.age),
            ('性', self.gender),
        )
        prof = []
        for k, v in data:
            prof.append(f'{k}\t: {v}')
        prof = '\n'.join(prof)
        return prof

    def to_json(self) -> dict:
        data = {'name': self.name, 'age': self.age, 'gender': self.gender}
        return data


# 3.
class VPerson(Validator):
    def validate(self, value: Any) -> Person:
        if type(value) is not Person:
            msg = self.ERRMSG('Person型である必要があります', value)
            raise TypeError(msg)
        return value


# 4.
class CPerson(VPerson, Converter):
    def validate(self, value: Any) -> Person:
        if type(value) is not Person:
            try:
                if isinstance(value, dict):
                    value = Person(**value)
                else:
                    raise TypeError
            except:
                msg = self.ERRMSG('Person型として扱える必要があります。', value)
                raise TypeError(msg)
        return super().validate(value)

    def super_validate(self, value: Any) -> Person:
        return super().super_validate(value)


# 5.
class ConfigurationManager(BaseCM):
    __defaults__ = {
        'president': Person('山田太郎', 28, '男'),
        'employee': {
            'director': Person('部長花子', 28, '女'),
            'manager': Person('課長夢', 28, '女'),
            'chief': Person('係長次郎', 28, '男')
        }
    }
    president = CPerson()
    director = CNoneable(CPerson())
    manager = CNoneable(CPerson())
    chief = CNoneable(CPerson())


with ConfigurationManager('my_company.json') as cm:
    cm.president = Person('乙八', 28, '男')
    cm.director = Person('部長夢', 28, '女')
    cm.manager = None
    cm.chief = None

上記の処理で作成されたmy_company.jsonの中身は以下の通りです。

{
    "employee": {
        "chief": null,
        "manager": null,
        "director": {
            "name": "部長夢",
            "age": 28,
            "gender": "女"
        }
    },
    "president": {
        "name": "乙八",
        "age": 28,
        "gender": "男"
    }
}

定義通りPersonクラスはperson.to_jsonを通して辞書形式に変換されていることがわかります。

読み込み-自作クラスの使用

実行例に戻る

# 1. & 1.1.
from typing import Any

from otsuvalidator import CNoneable
from otsuvalidator.bases import Converter, Validator

from otsucfgmng import BaseCM


# 2.
class Person:
    # 2.1.
    def __init__(self, name: str, age: int, gender: str):
        self.name = name
        self.age = age
        self.gender = gender

    def show_profile(self):
        print(self)

    # 2.2.
    def __str__(self) -> str:
        data = (
            ('名前', self.name),
            ('年齢', self.age),
            ('性', self.gender),
        )
        prof = []
        for k, v in data:
            prof.append(f'{k}\t: {v}')
        prof = '\n'.join(prof)
        return prof

    def to_json(self) -> dict:
        data = {'name': self.name, 'age': self.age, 'gender': self.gender}
        return data


# 3.
class VPerson(Validator):
    def validate(self, value: Any) -> Person:
        if type(value) is not Person:
            msg = self.ERRMSG('Person型である必要があります', value)
            raise TypeError(msg)
        return value


# 4.
class CPerson(VPerson, Converter):
    def validate(self, value: Any) -> Person:
        if type(value) is not Person:
            try:
                if isinstance(value, dict):
                    value = Person(**value)
                else:
                    raise TypeError
            except:
                msg = self.ERRMSG('Person型として扱える必要があります。', value)
                raise TypeError(msg)
        return super().validate(value)

    def super_validate(self, value: Any) -> Person:
        return super().super_validate(value)


# 5.
class ConfigurationManager(BaseCM):
    __defaults__ = {
        'president': Person('山田太郎', 28, '男'),
        'employee': {
            'director': Person('部長花子', 28, '女'),
            'manager': Person('課長夢', 28, '女'),
            'chief': Person('係長次郎', 28, '男')
        }
    }
    president = CPerson()
    director = CNoneable(CPerson())
    manager = CNoneable(CPerson())
    chief = CNoneable(CPerson())


with ConfigurationManager('my_company.json') as cm:
    for i, key in enumerate(('president', 'director', 'manager', 'chief')):
        if i:
            print('-' * 75)
        print(f'{key}\n{getattr(cm,key)}')

### 出力は以下のようになります ###
president
名前    : 乙八
年齢    : 28
性      : 男
---------------------------------------------------------------------------
director
名前    : 部長夢
年齢    : 28
性      : 女
---------------------------------------------------------------------------
manager
None
---------------------------------------------------------------------------
chief
None

プロトコル

コーディングの最中、docstringが欲しくなった時の場合のためにotsucfgmng.protocol.PBaseCM(以後、PBaseCM)があります。

使い方-プロトコル

ここで定義したConfigurationManagerクラスのプロトコルを作成して利用する例を示します。

設定ファイルのパスは一度決めてしまえば不変である可能性が高いので、引数無しでConfigurationManagerインスタンスを生成して返す関数を作成します。

1. ConfigurationManagerとPBaseCM, 型ヒントに使用するクラスをインポートする。
2. PBaseCMを継承したPConfigurationManagerクラスを定義する。
   1. プロパティとして各属性を定義していく。
   2. 必要であれば、常に各属性の初期値を返すdefault_<attribute>_cmも同様に定義していく。
   3. コーディング中の警告が気になるなら2.iで定義したプロパティのセッターも定義しておく。
3. インスタンス生成用関数を定義する。
   1. PConfigurationManagerを返り値の型として指定する。
   2. ConfigurationManagerインスタンスを生成し、返す。
   3. 厳密には対応していないと警告されるので、気になるなら# type: ignoreで無視するようにする。

# 1.
from pathlib import Path
from typing import Any

from otsucfgmng import PBaseCM
from test2 import ConfigurationManager


# 2.
class PConfigurationManager(PBaseCM):
    # 2.1
    @property
    def library(self) -> Path:
        """外部ライブラリのパス。"""
        ...

    @property
    def scripts(self) -> Path:
        """外部スクリプトのパス。"""
        ...

    @property
    def title(self) -> str:
        """アプリケーションのタイトル。"""
        ...

    @property
    def fullscreen(self) -> bool:
        """フルスクリーンで起動するか。"""
        ...

    @property
    def bgm(self) -> int:
        """BGM音量。"""
        ...

    @property
    def bgs(self) -> int:
        """BGS音量。"""
        ...

    @property
    def se(self) -> int:
        """SE音量。"""
        ...

    @property
    def me(self) -> int:
        """ME音量。"""
        ...

    # 2.2
    @property
    def default_library_cm(self) -> Path:
        """外部ライブラリのパス。"""
        ...

    @property
    def default_scripts_cm(self) -> Path:
        """外部スクリプトのパス。"""
        ...

    @property
    def default_title_cm(self) -> str:
        """アプリケーションのタイトル。"""
        ...

    @property
    def default_fullscreen_cm(self) -> bool:
        """フルスクリーンで起動するか。"""
        ...

    @property
    def default_bgm_cm(self) -> int:
        """BGM音量。"""
        ...

    @property
    def default_bgs_cm(self) -> int:
        """BGS音量。"""
        ...

    @property
    def default_se_cm(self) -> int:
        """SE音量。"""
        ...

    @property
    def default_me_cm(self) -> int:
        """ME音量。"""
        ...

    # 2.3
    @library.setter
    def library(self, value: Any) -> None: ...

    @scripts.setter
    def scripts(self, value: Any) -> None: ...

    @title.setter
    def title(self, value: Any) -> None: ...

    @fullscreen.setter
    def fullscreen(self, value: Any) -> None: ...

    @bgm.setter
    def bgm(self, value: Any) -> None: ...

    @bgs.setter
    def bgs(self, value: Any) -> None: ...

    @se.setter
    def se(self, value: Any) -> None: ...

    @me.setter
    def me(self, value: Any) -> None: ...


# 3.
def CfgMng() -> PConfigurationManager:  # 3.1
    # 3.2, 3.3
    return ConfigurationManager("cfg.json", True)  # type: ignore


with CfgMng() as cm:
    # "cm."まで入力した時点で、各属性のdocstring付き候補が表示されるようになる。
    cm.bgm = 10  # 2.iを省略すると警告される。
    print(cm.cfg_to_str_cm(True))

出力

### 出力は以下のようになります ###
{
    "defaults": {
        "app": {
            "fullscreen": false,
            "library": "SampleLibrary.dll",
            "scripts": "SampleScripts.scrpt",
            "title": "Sample Program"
        },
        "audio": {
            "bgm": 100,
            "bgs": 100,
            "me": 85,
            "se": 100
        }
    },
    "user": {
        "app": {},
        "audio": {
            "bgm": 10
        }
    }
}