A simple, yet fully-featured python library to work with INI configuration files.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for t1h0 from gravatar.com t1h0

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: Apache Software License
  • Author: Tilman Hornung
  • Tags ini, config, configuration, settings, user interface, interface
  • Requires: Python >=3.12
Classifiers

Project description

SmartIni

Python versions PyPI version License

SmartIni is a simple, yet fully-featured python library to work with INI configuration files. It aims at providing easy access to configurations saved in the INI file structure while eliminating the drawbacks of existing approaches like configparser.

Contents

Getting started

Installation

SmartIni runs on python 3.12+.

Setting up a configuration file

Say you want to distribute a news service that crawls a specific news website periodically and sends a summary of the crawled news per mail. This is what your config.ini file might look like:

[News Crawler]
; Settings for the news crawler

; crawl interval in minutes
interval = 30

; news website to crawl from
news-source = my-favorite-news-source.com

[Mailer]
; Settings for the mailer

; mail address to send to
news-receiver = emma@geller-greene.com

Let's break this down. INI files consist of three possible entities:

  • Section Name: In [brackets]. Denotes the beginning of a new section (and ending of the one before). E.g. [News Crawler].
  • Comment: Preceded by a prefix (usually ;or #). Adds explanation to the other entities. E.g. ; Settings for the news crawler.
  • Option: Consists of a key, a delimiter (usually = or :) and a value. Holds an actual setting. E.g. interval = 30.

Setting up the configuration Schema

To use the configurations in your project, your code ideally needs to know what to access. We therefore mirror the configurations in your project:

import smartini

class Config(smartini.Schema):

    class Crawler(smartini.Section):
        _name = "News Crawler"
        interval = "interval"
        source = "news-source"

    class Mailer(smartini.Section):
        receiver = "news-receiver"

Let's break this down:

  • Your schema class needs to inherit from smartini.Schema.
  • Each section gets its own section class within this schema class, inheriting from smartini.Section.
  • Important! If the actual section name differs from the section class name, it's assigned to the _name class attribute.
  • Each option of a section gets its key assigned to an arbitrary string attribute. The variable name must not start with a leading underscore.

Using the configurations in your code

All that's left to do now is, to initialize the schema class and load the ini file.

config = Config()
config.read_ini("config.ini")

You can now use the stored configurations by simply accessing them through your schema instance:

>>> config.Crawler.interval
30
>>> config.Mailer.receiver
'emma@geller-greene.com'

Similarly, you can assign new values to existing configurations:

>>> config.Crawler.interval = 15
>>> config.Crawler.interval
15
>>> config.Mailer.receiver = "rachel@geller-greene.com"
>>> config.Crawler.receiver
'rachel@geller-greene.com'

Advanced Usage

Multiple configurations using slots

Introduction

Imagine you send your news crawler (from the documentation's introduction) to your dad and they configure it like so:

[News Crawler]
; Settings for the news crawler

; crawl interval in minutes
interval =

; news website to crawl from
news-source = paleontology-papers.com

[Mailer]
; Settings for the mailer

; mail address to send to
news-receiver = ross@geller-greene.com

There are two problems with this file:

  1. The interval option has no value.
  2. The news-source value does not offer an actual news source.

SmartIni offers an easy solution for this: Slots!

Basic concept

You can think of a Slot as a configuration profile: Each configuration file you read is saved into a Slot with its structure (the order in which the entities appear in the file) and all its comments and options. SmartIni intelligently decides which slot to use when you access an option to ensure your code always uses a valid setting.

Slot keys

Each slot has a unique slot key. By default, SmartIni generates numerical slot keys starting from 0 upwards. However, you can also choose your own slot key (int or str) when reading an ini file.

Accessing and setting slots

Automatically

By default, SmartIni chooses the slot to access or set using one of the SlotDeciderMethods. The desired method can be passed during Schema initialization and defaults to "fallback", resulting in the latest slot unless that is None, then the first slot.

Automatic slot access will also work for any smartini method that receives an argument of type SlotAccess.

Manually

However, you can also access or set slots manually using their slot keys or by index:

  • To access or set a slot directly by key, simply use python's item accessing / setting on your schema class.
  • To access or set by index, use the same logic on the schema classes iloc indexer.
# Slot access by slot key
config[0].Crawler.interval

# Slot access by index
config.iloc[0].Crawler.interval

Introduction solution

So how does this help us with our initial problem? Easy!

  1. Load both configuration files into your project.

    >>> config.read_ini("config.ini", slots="default")
>>> config.read_ini("user.ini", slots="dad")

  2. Access the interval option like before. By default, the "fallback" SlotDeciderMethod is used, so smartini will automatically use the first slot for the interval option since the latest is None. However, "cascade down" would also deliver the desired result here.

    >>> config.Crawler.interval
30
>>> config["default"].Crawler.interval
30
>>> config["dad"].Crawler.interval
>>> None

  3. For the news-source option, you could verify your dad's input and if that fails, change his configured website to a news source he'd likely find interesting.

    >>> if not is_news_source(config["dad"].Crawler.source):
...     config["dad"].Crawler.source = "paleantologytoday.com"
...     # or config.Crawler.source = ...
>>> config.Crawler.source
'paleantologytoday.com'

Type hinting and type conversion

By default, SmartIni tries to guess the type of each option value and return it in the respective type or fallback to string representation. However, you can change that behavior for all options or each option individually.

Introduction

Let's assume you add more Mailer settings to your news crawler (from the documentation's introduction) like so:

[Mailer]
; Settings for the mailer

; mail address to send to
news-receiver = ross@geller-greene.com

; Whether the Mail should have a greeting in the beginning.
; + for yes, - for no.
welcome = +

; Time of the day the mail should be sent in 24h format.
time = 15

; Days of the week the mail should be sent.
days = mon, wed, fri

By default, news-receiver, welcome, time and days will be read as str, str, int and list[str], respectively. However, those types are either wrong (in the case of welcome) or can be misleading depending on the input. That's where SmartIni's type converters come into play!

Basic concept

Smartini's type conversion is based on its TypeConverters. Each option's assigned TypeConverter is applied on its value with the conversion result saved separately. TypeConverters always return the unchanged input if they can't convert it. Thus, if conversion is not successful, converted value and input string are equal.

By default, SmartIni assigns the default Guess-TypeConverter to each option. This TypeConverter tries to match the value to one of the ConvertibleTypes. You can change the default TypeConverter to one of the other built-in TypeConverters, to your own TypeConverter or disable default type conversion all along by setting the respective parameter during Schema initialization.

You can also define a specific type - and thus a specific type converter - separately for one or more options using simple python typing. This can be helpful to ensure each option is of correct type or if your ini differs from SmartIni's default conversion behavior.

Built-in TypeConverters

SmartIni comes with the following built-in TypeConverters, that can be used with their default arguments or customized using the respective creator functions:

TypeConverter Default Creator function
Bool DEFAULT_BOOL_CONVERTER bool_converter()
Guess DEFAULT_GUESS_CONVERTER guess_converter()
List DEFAULT_LIST_CONVERTER list_converter()
Numeric DEFAULT_NUMERIC_CONVERTER numeric_converter()

Creating your own TypeConverter

You can also create your own TypeConverter by passing a Callable to type_converters.new_converter. The Callable takes a str as input and returns the converted value or raises type_converters.WrongType if conversion was unsuccessful.

Assigning TypeConverters via type hinting

You can set an option's type and thus its TypeConverter by annotating it in your Schema definition using smartini.TYPE[] in one of the following ways:

Type annotation Explanation
TYPE | GUESS Assigns the Guess-TypeConverter.
Pre-defined type hint Assigns built-in type converters. E.g. BOOL.
TYPE[type[ConvertibleTypes]] Assigns a TypeConverter matching the type. E.g. TYPE[int] will assign a Numeric-TypeConverter that converts to int.
TYPE[type[TypeConverter]] Assigns the annotated TypeConverter (e.g. your own).

Alternatively, SmartIni also comes with pre-defined type hints for its built-in TypeConverters.

Introduction solution

Let's look at our Mailer options again. We want welcome to be represented as a boolean and we might want time to be represented as a datetime.time object. Here's how we can do it:

  1. Create a boolean converter that interprets "+" as True and "-" as False.

    from smartini.type_converters.converters import bool_converter

bool_type = bool_converter(true="+", false="-")

  2. Create a custom converter that converts a value to a datetime.time object.

    from smartini.type_converters.converters import new_converter, WrongType
from datetime import time

def convert_to_time(string:str) -> time:
    try:
        return time(int(string))
    except ValueError:
        raise WrongType

time_type = new_converter(convert_to_time)

  3. Assign both converters respectively.

    from smartini import Schema, Section, TYPE
from smartini.type_converters.type_hints import STR

class Config(Schema):

    ...

    class Mailer(Section):
        receiver: STR = "news-receiver"
        welcome: TYPE[bool_type] = "welcome"
        time: TYPE[time_type] = "time"
        days: TYPE[list[str]] = "days"

    Note:

    • The type annotations for receiver and days are not really necessary here as SmartIni already guesses the correct types.
    • For list type annotations, SmartIni will guess each list item's type if no item type annotation is provided in brackets.

Custom markers

SmartIni allows for customization of the following markers by passing the respective argument during Schema initialization:

Marker argument default Explanation
Option delimiter option_delimiters "=" Separates option key from value, e.g. opt=val. You can pass multiple if the ini file is inconsistent.
Comment prefix comment_prefixes ";" Denotes a comment, e.g. ;comment. You can pass multiple if the ini file is inconsistent.

For further information see Parameters.

Multiline options

SmartIni by default allows for multiline option values, so for the whole value to span over multiple lines. Every line after the first line is called a continuation. You can control this behavior by specifying the three multiline parameters during Schema initialization.

For further information see Parameters.

Undefined configurations

Smartini can also read configurations that are not defined in your Schema class. To do so, simply pass read_undefined = True to your Schema initialization. To access undefined content, use get_sections and get_options with include_undefined="only".

Note: If you leave read_undefined = False (default), smartini will print a warning if it encounters undefined content.

Documentation

smartini.Comment

Comment object holding a comment's content.

Comment(content_without_prefix = None, prefix = None, content_with_prefix = None)

Args

  • content_without_prefix (str | None, optional)

    Content with prefix removed. Should be None if content_with_prefix is provided, otherwise the latter will be ignored. Defaults to None.

  • prefix (VALID_MARKERS | tuple[VALID_MARKERS, ...] | None, optional)

    One or more prefixes that can denote the comment (used for content_with_prefix). Defaults to None.

  • content_with_prefix (str | None, optional)

    Content including prefix. Will be ignored if content_without_prefix is provided. Defaults to None.

smartini.Comment.content

Comment.content

The comment's content.

smartini.Comment.to_string

Comment.to_string(prefix)

Convert the Comment into an ini string.

Args

  • prefix (str | None, optional)

    Prefix to use for the string. Returns to None.

Returns

  • str

    The ini string.

smartini.Option

Option object holding an option's value (per slot) and key.

Option(key, values = None, type_converter = None, slots = None)

Args

  • key (str | int | None, optional)

    The option key. Should be None if from_string is provided, otherwise from_string will be ignored. Defaults to None.

  • values (Any | list[Any] | None, optional)

    The option value or values (one value per slot or one/same value for all slots). Should be None if from_string is provided, otherwise from_string will be ignored. Defaults to None.

  • type_converter (type[TypeConverter|ConvertibleTypes] | None, optional)

    TypeConverter to apply to every option value (and continuation) that is not explicitly annotated. Alternatively one of the ConvertibleTypes that the option values should be interpreted as (will be matched to a TypeConverter). If None, will save all values (and continuations) as strings. Defaults to DEFAULT_GUESS_CONVERTER.

  • slots (SlotAccess, optional)

    Slot(s) to save value(s) in. If None, will create numerical slot keys starting from 0. Otherwise, number of slots must match number of values, unless number of values is 1 (:= same value for all slots). Defaults to None.

smartini.Option.to_string

to_string(delimiter, *, slots = None)

Convert the Option into an ini string.

Args

  • delimiter (VALID_MARKERS)

    The delimiter to use for separating option key and value.

  • slot (SlotAccess, optional)

    The slot to get the value from. If multiple are passed, will take the first that is not None (or return an empty string if all are None). If None, will take the first that is not None of all slots. Defaults to None.

Returns

  • str

    The ini string.

smartini.Parameters

Parameters for reading and writing.

Parameters(comment_prefixes = ";", option_delimiters = "=", multiline_allowed = True, multiline_prefix = None, multiline_ignore = (), ignore_whitespace_lines = True, read_undefined = False, default_type_converter = smartini.type_converters.DEFAULT_GUESS_CONVERTER)

Args

  • comment_prefixes (VALID_MARKERS| tuple[VALID_MARKERS, ...], optional)

    Prefix character(s) that denote a comment. If multiple are given, the first will be taken for writing. If None, will treat every line as comment that is not an option or section name. Defaults to ";".

  • option_delimiters (VALID_MARKERS| tuple[VALID_MARKERS, ...], optional)

    Delimiter character(s) that delimit option keys from values. If multiple are given, the first will be taken for writing. Defaults to "=".

  • multiline_allowed (bool, optional)

    Whether continuations of options (i.e. multiline options) are allowed. Defaults to True.

  • multiline_prefix (VALID_MARKERS | Literal["\t"] | None, optional)

    Prefix to denote continuations of multiline options. If set, will only accept continuations with that prefix. Defaults to None (possible continuation without prefix).

  • multiline_ignore (tuple["section_name" | "option_delimiter" | "comment_prefix", ...] | None, optional)

    Entity identifier(s) to ignore while continuing an option's value. Otherwise lines with those identifiers will be interpreted as a new entity instead of a continuation (despite possibly satisfying multiline rules). Useful if a continuation is possibly in brackets (otherwise interpreted as a section name), contains the option delimiter (e.g. URLs often include a "=") or starts with a comment prefix. Defaults to None.

  • ignore_whitespace_lines (bool, optional)

    Whether to interpret lines with only whitespace characters (space or tab) as empty lines. Defaults to True.

  • read_undefined (bool | "section" | "option", optional)

    Whether undefined content should be read and stored. If True, will read every undefined content. If "section", will read undefined sections and their content but not undefined options within defined sections. "option" will read undefined options within defined sections but not undefined sections and their content. If False, will ignore undefined content. Defaults to False.

  • default_type_converter (type[TypeConverter] | None, optional):

    TypeConverter class to apply to every option value (and continuation) that is not annotated otherwise. If None, will save all values (and continuations) as strings. Defaults to smartini.type_converters.DEFAULT_GUESS_CONVERTER.

smartini.Schema

Schema class to define configuration schema and access loaded configurations.

Schema(parameters = None, method = "fallback", **kwargs)

Parameters will be stored as default read and write parameters.

Args

  • parameters (Parameters| None, optional)

    Default parameters for reading and writing inis, as an Parameters object. Parameters can also be passed as kwargs. Missing parameters (because parameters is None and no or not enough kwargs are passed) will be taken from default parameters. Defaults to None.

  • method (SlotDeciderMethods, optional)

    Method for choosing the slot. Defaults to "fallback".

  • **kwargs (optional)

    Parameters as kwargs.

smartini.Schema.export

Schema.export(path = None, decider_method = None, include_undefined = True, export_comments = False, *, content_slots = None)

Export the saved configuration to a file.

Args

  • path (str | Path)

    Path to the file to export to.

  • structure ("schema" | "content" | None, optional)

    Slot to use for structuring the output (including comments). If "schema", will use original schema definition. If "content", will use slot that is used as content slot (if multiple content slots are given will use the first). If None will use "schema" if content_slots is None and "content" otherwise. Defaults to None.

  • decider_method (SlotDeciderMethods| None, optional)

    Either a decider method to use or None to use the initial decider method. Defaults to None.

  • include_undefined (bool, optional)

    Whether to include undefined entities. Defaults to True.

  • export_comments (bool, optional)

    Whether to export comments. Will use first content slot to get comments from. Comments will be matched to following entities (e.g. all comments above option_a will be above option_a in the exported ini). Defaults to False.

  • content_slots (SlotAccess, optional)

    Slot(s) to use for content (sections and options). If multiple are given, first slot has priority, then second (if first is None) and so on. If None, will use decider method. Defaults to None.

smartini.Schema.get_section

Schema.get_section(section_name)

Get a section by its name.

Args

  • section_name (SectionName | str | None)

    The name of the section to get.

Returns

  • tuple[str, Section]

    Tuple of variable name and section object.

smartini.Schema.get_sections

Schema.get_sections(include_undefined = True, *, slots = None)

Get configuration section(s).

Args

  • include_undefined (bool, optional)

    Whether to also include undefined sections. Defaults to True.

  • slots (SlotAccess, optional)

    Which slot(s) to get sections from. If multiple are given, will return the intersection. If None, will return all. Defaults to None.

Returns

  • OrderedDict[str, Section]

    Variable names as keys and the Sections as values. Order is that of the slot structure if len(slots) == 1. Otherwise, order matches defined schema structure with undefined sections at the end.

smartini.Schema.read_ini

Schema.read_ini(path, parameters = None, parameters_as_default = False, *, slots = False, **kwargs)

Read an INI file. If no parameters are passed (as Parameters object or kwargs), default parameters defined on initialization will be used.

Args

  • path (str | pathlib.Path)

    Path to the INI file.

  • parameters (Parameters| None, optional)

    Parameters for reading and writing INIs, as a Parameters object. Parameters can also be passed as kwargs. Missing parameters (because parameters is None and no or not enough kwargs are passed) will be taken from default parameters that were defined on initialization. Defaults to None.

  • parameters_as_default (bool, optional)

    Whether to save the parameters for this read as default parameters. Defaults to False.

  • **kwargs (optional)

    Parameters as kwargs.

  • slots (SlotAccess| False, optional)

    Slot(s) to save the content in. If False will create new slot. Defaults to False.

smartini.Schema.with_slot

Schema.with_slot(slot)

Access the ini using a specific slot. Equivalent to item access via brackets (i.e. Schema[slot]).

Args

Example

>>> class Config(smartini.Schema):
...     class Section(smartini.Section):
...         option = "option-name"
>>> config = Config()
>>> config.read_ini("config1.ini")
>>> config.read_ini("config2.ini")
>>> config.with_slot(1).Section.option == config[1].Section.option
True

smartini.Section

A configuration section. Holds Options and Comments. If the actual section name differs from class variable, it needs to be assigned to the _name class attribute! Furthermore, class attributes holding options must not start with a leading underscore!

smartini.Section.add_entity

Section.add_entity(entity, positions = None, *, slots = None)

Add a new entity to the section.

Args

  • entity (UndefinedOption|Option|Comment)

    The entity to add.

  • positions (int | list[int | None], optional)

    Where to put the entity in the section's structure. Either one position for all slots or a list with one position per slot. If None, will append to the end in every slot. Defaults to None.

  • slots (SlotAccess, optional)

    Slot(s) to add the entity to. Must match positions. Defaults to None.

Returns

smartini.Section.get_comments_by_content

Section.get_comments_by_content(content)

Get comments matching the content.

Args

  • content (str | re.Pattern)

    The content of the comment.

Returns

  • dict[str, Comment]

    All comments that fit the content argument with variable names as keys and the Comment objects as values.

smartini.Section.get_option

Section.get_option(name = None, key = None)

Get an option by variable name or option key.

Args

  • name (str | None, optional)

    Name of the option variable. Defaults to None.

  • key (SlotKey | None, optional)

    The option key. Will be ignored if name is not None. Defaults to None.

Returns

  • Option

    The requested option.

smartini.Section.get_options

Section.get_options(include_undefined = True, *, slots = None)

Get options of the section.

Args

  • include_undefined (bool | "only", optional)

    Whether to include undefined options. If "only", will return only undefined options. Always False if slots is not None.

  • slots (SlotAccess, optional)

    Which slot(s) to get options from. If multiple are given, will return the intersection. If None will return all. Defaults to None.

Returns

  • OrderedDict[str, Option]

    Variable names as keys and Options as values. Order is that of the slot structure if len(slots) == 1. Otherwise, order matches original schema structure with undefined options at the end.

smartini.Section.set_option

Section.set_option(name, value, positions = None, key = None, *, slots = None)

Set an option's value by accessing it via variable name or option key.

Args

  • name (str | None)

    The variable name of the option. Must be None if key should be used.

  • value (OptionValue)

    The new value for the option.

  • positions (int | list[int | None] | None)

    Position in slots the entity should take. Either int for same position in all slots or one position per slot. If None and for every slot that None is specified for, will take previous position of the Option in the respective slot and will append to slots where Option didn't exist before. Defaults to None.

  • key (str | None, optional)

    The option key. Defaults to None.

  • slots (SlotAccess, optional)

    The slot(s) to use. Defaults to None (all slots).

smartini.SectionName

A configuration section's name.

SectionName(name = None, name_with_brackets = None)

Args

  • name (str | None, optional)

    Name of the section. Should be None if name_with_brackets is provided, otherwise name_with_brackets will be ignored. Defaults to None.

  • name_with_brackets (str | None, optional)

    The name of the section within brackets (to extract the name from). If provided, name argument should be None, otherwise will be ignored. Defaults to None.

smartini.SlotAccess

type SlotAccess = int | str | list[int | str] | None

Identifier for which slot(s) to access.

  • int | str

    Identifier for a single slot.

  • list[int | str]

    Identifier for multiple slots.

  • None

    All slots.

smartini.SlotDeciderMethods

type SlotDeciderMethods = "fallback" | "first" | "cascade up" | "latest" | "cascade down"

Method to decide which slot to use.

  • "fallback"

    Uses first slot whenever latest slot is None, otherwise latest slot. This is especially useful if the first slot provides default fallback values for your configuration.

  • "first"

    Uses first slot.

  • "cascade up"

    Uses the first slot that is not None from first to latest.

  • "latest"

    Uses latest slot.

  • "cascade down"

    Uses first slot that is not None from latest to first.

smartini.TYPE

Type annotation for type converters. All types passed in brackets will be tried for conversion, first successful conversion will be applied.

Example:

option_1: TYPE[int,bool] = "option-1"

SmartIni will try to convert into int first, then into bool, then interpret as str.

smartini.type_converters

SmartIni's type conversion logic.

smartini.type_converters.converters

Converter classes and functions.

smartini.type_converters.converters.bool_converter

type_converters.bool_converter(true = ("1", "true", "yes", "y"), false = ("0", "false", "no", "n"))

Create a new bool converter.

Args

  • true (str | tuple[str, ...], optional)

    String(s) that should be regarded as True. Defaults to ("1", "true", "yes", "y").

  • false (str | tuple[str, ...], optional)

    String(s) that should be regarded as False. Defaults to ("0", "false", "no", "n").

Returns

  • type[TypeConverter[bool]]

    The bool type converter.

smartini.type_converters.converters.ConvertibleTypes

ConvertibleTypes = int | float | complex | bool | list

Types that SmartIni can convert the input strings into.

Note: SmartIni also allows for annotating the item type of a list, e.g. list[int].

smartini.type_converters.converters.DEFAULT_BOOL_CONVERTER

DEFAULT_BOOL_CONVERTER = smartini.type_converters.bool_converter()

Bool converter with default conversion parameters.

smartini.type_converters.converters.DEFAULT_GUESS_CONVERTER

DEFAULT_GUESS_CONVERTER = smartini.type_converters.guess_converter()

Guess converter with default conversion parameters.

smartini.type_converters.converters.DEFAULT_LIST_CONVERTER

DEFAULT_LIST_CONVERTER = smartini.type_converters.list_converter()

List converter with default conversion parameters.

smartini.type_converters.converters.DEFAULT_NUMERIC_CONVERTER

DEFAULT_NUMERIC_CONVERTER = smartini.type_converters.numeric_converter()

Numeric converter with default conversion parameters.

smartini.type_converters.converters.guess_converter

type_converters.guess_converter(*types)

Create a new type converter that guesses the type.

Args

Returns

smartini.type_converters.converters.list_converter

type_converters.list_converter(delimiter = ",", remove_whitespace = True, item_converter = None)

Create a new list type converter.

Args

  • delimiter (str, optional)

    Delimiter that separates list items. Defaults to ",".

  • remove_whitespace (bool, optional)

    Whether whitespace between items and delimiter should be removed. Defaults to True.

  • item_converter (type[TypeConverter[Any]])

    TypeConverter to convert each list item with. If None, will use Guess-TypeConverter. Defaults to None.

Returns

  • type[TypeConverter[list]]

    The new list type converter.

smartini.type_converters.converters.new_converter

type_converters.new_converter(processor, name = None)

Create a new TypeConverter.

Args

  • processor (Callable[[str], T])

    Callable to process the string input and convert it into an instance of arbitrary type. If conversion is not possible, should raise WrongType.

  • name (str | None, optional)

    Name for the new TypeConverter. Will be appended to result into TypeConverter_{name}. If None, will take the processor function's name. Defaults to None.

Returns

  • type[TypeConverter[T]]

    TypeConverter that will return the processed input on call or the input itself if conversion was not possible.

smartini.type_converters.converters.numeric_converter

type_converters.numeric_converter(numeric_type = (int, float, complex), decimal_sep = ".", thousands_sep = ",")

Create a new numeric type converter.

Args

  • numeric_type (type[int | float | complex] | tuple[type[int | float | complex], ...], optional)

    The type to convert to. If multiple are given, the type converter will return the first type that the conversion was successful for. Defaults to (int, float, complex).

  • decimal_sep (str, optional)

    Possible decimal separator inside the string. Defaults to ".".

  • thousands_sep (str, optional)

    Possible thousands separator inside the string. Defaults to ",".

Returns

  • type[TypeConverter[int | float | complex]]

    The numeric type converter.

smartini.type_converters.converters.TypeConverter

Parent class for type converters. To create a type converter, use new_converter().

smartini.type_converters.converters.WrongType

Exception. Raised when a value could not be converted.

smartini.type_converters.type_hints

Pre-defined type hints for built-in type converters.

smartini.type_converters.type_hints.BOOL

BOOL = TYPE[DEFAULT_BOOL_CONVERTER]

Boolean type converter.

smartini.type_converters.type_hints.GUESS

GUESS = TYPE[DEFAULT_GUESS_CONVERTER]

Type converter that will guess the type.

smartini.type_converters.type_hints.LIST

LIST = TYPE[DEFAULT_LIST_CONVERTER]

List type converter.

smartini.type_converters.type_hints.NUMERIC

STR = TYPE[str]

Annotation for a string option value.

smartini.type_converters.type_hints.STR

NUMERIC = TYPE[DEFAULT_NUMERIC_CONVERTER]

Numeric type converter.

smartini.UndefinedOption

Option, that is not hard coded in the provided schema.

UndefinedOption(*args,**kwargs)

Takes args and kwargs identical to Option. Can also take an Option to copy its attributes.

smartini.VALID_MARKERS

VALID_MARKERS = Literal["\\","!",'"',"§","%","&","/","(",")","?",":",";","#","'","*",">","<","=",]

Valid characters for markers (option delimiter, comment prefix or multiline prefix).

Why still ini?

a word from the creator

SmartIni started from a simple problem: I had built this awesome project that I wanted my non-coder friends to be able to use and set up to their needs. However, I didn't have the capacity to build a GUI and didn't want to use JSON or YAML either as they too use concepts foreign to non-coders (like quotation of strings).

INI files provide an intuitive approach to text-based settings, therefore seemed to be the best option for my needs. The only problem left was, that existing modules for handling INI files (like the built-in configparser) suffer from several drawbacks. Luckily, now we have SmartIni :)

Contributing

As of now, this has been a one person project. If you want to contribute to it, you're very invited to do so by:

  1. Cloning the repository

    git clone git@github.com:t1h0/smartini.git

  2. Installing the repositories into an python 3.12+ environment

    cd smartini
pip install -r requirements.txt

  3. Add appropriate test files to ./tests and make sure pytest . finishes without a warning or exception.

  4. Send a pull request once you're done :)

Note: SmartIni's stub files "fool" type checkers by giving them false type annotations to ensure intuitive functionality (e.g. Schema.iloc is annotated to return the Schema (Self) although it actually returns a SlotIlocViewer). For development, you should disable the stub files (i.e. ignore them in your type checker config or rename them).

By contributing to this project, you agree that your contributions will be licensed under the project's license.

License

Smartini is licensed under the Apache-2.0 license, as found in the LICENSE file.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for t1h0 from gravatar.com t1h0

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: Apache Software License
  • Author: Tilman Hornung
  • Tags ini, config, configuration, settings, user interface, interface
  • Requires: Python >=3.12
Classifiers

Release history Release notifications | RSS feed

This version

1.1.2

1.1.1

1.1.0

1.0.1

1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

smartini-1.1.2.tar.gz (66.6 kB view details)

Uploaded Source

Built Distribution

smartini-1.1.2-py3-none-any.whl (47.9 kB view details)

Uploaded Python 3

File details

Details for the file smartini-1.1.2.tar.gz.

File metadata

  • Download URL: smartini-1.1.2.tar.gz
  • Upload date:
  • Size: 66.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.3

File hashes

Hashes for smartini-1.1.2.tar.gz
Algorithm Hash digest
SHA256 4420ca0b56e39efe863dd2c93f5f4c6a88c58650549abc9e743ee955b5bca16f
MD5 58ba4d9c40f47286b9ed518820c783c7
BLAKE2b-256 9015280086cfc5fb9699599d9cbe3b045189a20829bcb37bfa7e0fff04672c19

See more details on using hashes here.

File details

Details for the file smartini-1.1.2-py3-none-any.whl.

File metadata

  • Download URL: smartini-1.1.2-py3-none-any.whl
  • Upload date:
  • Size: 47.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.3

File hashes

Hashes for smartini-1.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 94cc15746cec18e82d919ccf4179a55baa8589e4373e6e615164043f2d38db5a
MD5 a582db349d21b04e4720451165315a56
BLAKE2b-256 dd246cd80a86ffde8220e21b2f6163b999053d535eeceed26098fb63d32b4896

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page