configtool¶

Main Module¶

Author: Jacek ‘Szumak’ Kotlarski –<szumak@virthost.pl> Created: 29.10.2023

Purpose: Main class for creating and processes config files.

class jsktoolbox.configtool.main.Config(filename, main_section_name, auto_create=False)[source]¶

Bases: BData, NoDynamicAttributes

High-level configuration manager combining data and file processors.

### Purpose: Loads, modifies, and saves INI-like configuration files.

Parameters:

filename (str)
main_section_name (str)
auto_create (bool)

__init__(filename, main_section_name, auto_create=False)[source]¶

Initialise Config object.

### Arguments: * filename: str - Path to configuration file. * main_section_name: str - Name of the primary section. * auto_create: bool - Create file on demand when True.

Parameters:

filename (str)
main_section_name (str)
auto_create (bool)

Return type:

None

property file_exists: bool¶

Check if file exists.

### Returns: [bool] - True when configuration file exists.

load()[source]¶

Load config file to DataProcessor.

### Returns: [bool] - True when at least one line was processed.

Return type:: bool

save()[source]¶

Save config file from DataProcessor.

### Returns: [bool] - True after successful write.

Return type:: bool

get(section, varname=None, desc=False)[source]¶

Get and return data.

### Arguments: * section: str - Section name. * varname: Optional[str] - Variable name. * desc: bool - Whether to fetch description.

### Returns: [Any] - Value or description depending on desc.

Parameters:

section (str)
varname (str | None)
desc (bool)

Return type:

Any

set(section, varname=None, value=None, desc=None)[source]¶

Set data.

### Arguments: * section: str - Section name. * varname: Optional[str] - Variable name. * value: Optional[Any] - Value payload. * desc: Optional[str] - Description text.

Parameters:

section (str)
varname (str | None)
value (Any | None)
desc (str | None)

Return type:

None

has_section(section)[source]¶

Check section name in config file.

### Arguments: * section: str - Section name to validate.

### Returns: [bool] - True when section exists.

### Raises: * TypeError: Section name is not a string.

Parameters:: section (str)
Return type:: bool

has_varname(section_name, varname)[source]¶

Check varname in section.

### Arguments: * section_name: str - Section name. * varname: str - Variable name.

### Returns: [bool] - True when variable exists.

### Raises: * TypeError: Variable name is not a string.

Parameters:

section_name (str)
varname (str)

Return type:

bool

property main_section_name: str | None¶

Return main section name string.

### Returns: [Optional[str]] - Name of the main section.

__setattr__(name, value)¶

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:

name (str)
value (Any)

Return type:

None

Configuration Data¶

Author: Jacek ‘Szumak’ Kotlarski –<szumak@virthost.pl> Created: 29.10.2023

Purpose: DataProcessor class for processing dataset operations.

class jsktoolbox.configtool.libs.data.IModel[source]¶

Bases: ABC

Model class interface.

abstract property dump: List[str] | VariableModel¶

Dump data.

### Returns: Union[List[str], VariableModel] - Dumped data as list of strings or model object.

abstract property name: str | None¶

Get name property.

### Returns: Optional[str] - The name property value, or None if not set.

abstract parser(value)[source]¶

Parser method.

Parameters:: value (str)
Return type:: None

abstract search(name)[source]¶

Search method.

Parameters:: name (str)
Return type:: bool

class jsktoolbox.configtool.libs.data.VariableModel(name=None, value=None, desc=None)[source]¶

Bases: BData, IModel, NoDynamicAttributes

Representation of a configuration variable entry.

### Purpose: Stores name, value, and description for a single configuration variable.

Parameters:

name (str | None)
value (str | int | float | bool | List | None)
desc (str | None)

__init__(name=None, value=None, desc=None)[source]¶

Initialise a variable record.

### Arguments: * name: Optional[str] - Variable identifier. * value: Optional[Union[str, int, float, bool, List]] - Payload to store. * desc: Optional[str] - Optional human-friendly description.

Parameters:

name (str | None)
value (str | int | float | bool | List | None)
desc (str | None)

Return type:

None

__repr__()[source]¶

Return representation class string.

### Returns: [str] - Debug-friendly section representation.

Return type:: str

__str__()[source]¶

Return formatted section header.

### Returns: [str] - String in INI-style header format.

Return type:: str

property desc: str | None¶

Get description property.

### Returns: [Optional[str]] - Description string or None.

property dump: VariableModel¶

Dump data.

### Returns: [List[Any]] - Shallow copy of section with variables.

property name: str | None¶

Get name property.

### Returns: [Optional[str]] - Section name.

parser(value)[source]¶

Parse raw string input ensuring valid state.

### Arguments: * value: str - Raw value string.

### Raises: * ValueError: Raised when the parsed value is empty after trimming.

Parameters:: value (str)
Return type:: None

search(name)[source]¶

Search method.

### Arguments: * name: str - Section name to match.

### Returns: [bool] - True when names coincide.

Parameters:: name (str)
Return type:: bool

Get value property.

### Returns: [Optional[Union[str, int, float, bool, List]]] - Stored value.

__setattr__(name, value)¶

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:

name (str)
value (Any)

Return type:

None

class jsktoolbox.configtool.libs.data.SectionModel(name=None)[source]¶

Bases: BData, IModel, NoDynamicAttributes

Representation of a configuration section.

### Purpose: Aggregates variables and descriptions under a named section.

Parameters:: name (str | None)

__init__(name=None)[source]¶

Initialise section state.

### Arguments: * name: Optional[str] - Optional section header value.

Parameters:: name (str | None)
Return type:: None

__repr__()[source]¶

Return representation class string.

### Returns: [str] - Debug-friendly section representation.

Return type:: str

__str__()[source]¶

Return formatted section header.

### Returns: [str] - String in INI-style header format.

Return type:: str

property dump: List[Any]¶

Dump data.

### Returns: [List[Any]] - Shallow copy of section with variables.

parser(value)[source]¶

Parse and validate section name.

### Arguments: * value: Optional[str] - Raw header text.

### Raises: * ValueError: Raised when the name resolves to an empty string.

Parameters:: value (str | None)
Return type:: None

search(name)[source]¶

Search method.

### Arguments: * name: str - Section name to match.

### Returns: [bool] - True when names coincide.

Parameters:: name (str)
Return type:: bool

property name: str | None¶

Get name property.

### Returns: [Optional[str]] - Section name.

get_variable(name)[source]¶

Search and return VariableModel if exists.

### Arguments: * name: str - Variable name to locate.

### Returns: [Optional[VariableModel]] - Matching variable instance or None.

Parameters:: name (str)
Return type:: VariableModel | None

set_variable(name=None, value=None, desc=None)[source]¶

Add or update VariableModel.

### Arguments: * name: Optional[str] - Variable name to set or update. * value: Optional[Any] - Value payload. * desc: Optional[str] - Description text.

### Raises: * ValueError: Raised when both name and value are None.

Parameters:

name (str | None)
value (Any | None)
desc (str | None)

Return type:

None

property variables: List[VariableModel]¶

Return list of VariableModel.

### Returns: [List[VariableModel]] - Mutable list of section variables.

__setattr__(name, value)¶

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:

name (str)
value (Any)

Return type:

None

class jsktoolbox.configtool.libs.data.DataProcessor[source]¶

Bases: BData, NoDynamicAttributes

Manage configuration data composed of sections and variables.

### Purpose: Provides helpers for reading, setting, and dumping configuration structures.

__init__()[source]¶

Initialise DataProcessor state.

### Purpose: Ensures the internal container for sections exists.

Return type:: None

__setattr__(name, value)¶

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:

name (str)
value (Any)

Return type:

None

property main_section: str | None¶

Return main section name.

### Returns: [Optional[str]] - Name of the primary section.

property sections: Tuple¶

Return sections keys tuple.

### Returns: [Tuple] - Tuple containing names of tracked sections.

add_section(name)[source]¶

Add section object to dataset.

### Arguments: * name: str - Raw section name.

### Returns: [str] - Sanitised section name actually stored.

Parameters:: name (str)
Return type:: str

get_section(name)[source]¶

Get section object if exists.

### Arguments: * name: str - Section name.

### Returns: [Optional[SectionModel]] - Matching section or None.

Parameters:: name (str)
Return type:: SectionModel | None

set(section, varname=None, value=None, desc=None)[source]¶

Set data to [SectionModel]->[VariableModel].

### Arguments: * section: str - Section name. * varname: Optional[str] - Variable name. * value: Optional[Any] - Value payload. * desc: Optional[str] - Description text.

Parameters:

section (str)
varname (str | None)
value (Any | None)
desc (str | None)

Return type:

None

get(section, varname=None, desc=False)[source]¶

Return value.

### Arguments: * section: str - Section name. * varname: Optional[str] - Variable name to fetch. * desc: bool - When True returns description.

### Returns: [Optional[Any]] - Value or description based on desc.

### Raises: * KeyError: Section not present.

Parameters:

section (str)
varname (str | None)
desc (bool)

Return type:

Any | None

property dump: str¶

Return formatted configuration data string.

### Returns: [str] - Full configuration payload.

### Raises: * KeyError: Main section not set.

File Operations¶

Author: Jacek ‘Szumak’ Kotlarski –<szumak@virthost.pl> Created: 29.10.2023

Purpose: Class for creating and processes config files.

class jsktoolbox.configtool.libs.file.FileProcessor[source]¶

Bases: BData, NoDynamicAttributes

Handle filesystem interactions for configuration files.

### Purpose: Offers helpers to validate paths, read, and persist config data.

__init__()[source]¶

Initialise FileProcessor instance.

The constructor does not perform extra work but keeps parity with other mixins.

Return type:: None

property file: str | None¶

Return config file path.

### Returns: [Optional[str]] - Absolute path or None when not set.

property file_exists: bool¶

Check if the file exists and is a file.

### Returns: [bool] - True when the file exists and is not a directory.

### Raises: * AttributeError: Path not configured prior to call.

file_create()[source]¶

Try to create file.

### Returns: [bool] - True when file already exists or was created.

### Raises: * AttributeError: Path not configured. * OSError: Path points to an existing directory.

Return type:: bool

read()[source]¶

Try to read config file.

### Returns: [str] - Entire file contents as a string.

Return type:: str

readlines()[source]¶

Try to read config file and create list of strings.

### Returns: [List[str]] - List of lines stripped from end markers.

Return type:: List[str]

__setattr__(name, value)¶

Prevent dynamic attribute assignment on instances.

### Raises: * AttributeError: Attribute not previously declared.

Parameters:

name (str)
value (Any)

Return type:

None

write(data)[source]¶

Try to write data to config file.

### Arguments: * data: str - Serialized configuration payload.

Parameters:: data (str)
Return type:: None