GitHub

Data formats

Parse TOML, YAML and INI files, compare semantic versions and match ranges, and compute with exact decimals.

These modules are plain functions and values, with no services to provide. Each follows the Effect module it ports, including where Effect differs from Python's standard library.

TOML, YAML and INI

pyfect.encoding.toml, yaml and ini parse text into dicts, lists and scalars. They only parse; none of them writes text back, as in Effect.

  • toml.parse(text) returns a Result: Ok with the tables, or Err with an EncodingError whose message gives the line and column. A date-time with an offset becomes a datetime in UTC; a local date, date-time or time stays a string. It follows Effect's parser, which is not always what tomllib accepts or rejects. Use tomllib when a file must follow the TOML specification to the letter.
  • yaml.parse(text) returns the value of one document and raises ValueError on text it can't read, as Effect's Yaml.parse throws. Anchors, aliases and YAML 1.1 merge keys work: <<: *base copies base into the mapping, and the mapping's own keys win. Tags, directives and several documents in one stream are not supported.
  • ini.parse(text) never fails. [a.b] sections nest, key[] collects a list, a key without = is True, and true, false and null become True, False and None. Quotes are removed before those words are read, so an INI file can't hold the strings "true", "false" or "null" (as in Effect and npm's ini).
config_files.py
from datetime import UTC, datetime

from pyfect.encoding import ini, toml, yaml
from pyfect.result import Err, Ok

# TOML: a Result. A date-time with an offset becomes a UTC datetime.
match toml.parse(
    """
title = "shop"

[server]
port = 8080
started = 1979-05-27T07:32:00-08:00

[[products]]
name = "hammer"

[[products]]
name = "nail"
"""
):
    case Ok(config):
        print(config["server"]["port"], [p["name"] for p in config["products"]])
        assert config["server"]["started"] == datetime(1979, 5, 27, 15, 32, tzinfo=UTC)
    case Err(error):
        raise AssertionError(error)

match toml.parse("a = 1\na = 2"):
    case Err(error):
        print(error.message)
    case Ok():
        raise AssertionError("a key defined twice")

# YAML: the value, or ValueError. Merge keys copy a mapping; explicit keys win.
settings = yaml.parse(
    """
base: &base
  retries: 3
  timeout: 5
prod:
  <<: *base
  timeout: 30
"""
)
print(settings)
assert settings == {"base": {"retries": 3, "timeout": 5}, "prod": {"retries": 3, "timeout": 30}}

try:
    yaml.parse("hosts: [a, b")
except ValueError as error:
    print("invalid YAML:", error)

# INI: never fails. Quotes are removed before true / false / null are read.
parsed = ini.parse('debug = true\nname = "true"\n[db.main]\nhost = localhost\nflag')
print(parsed)
assert parsed["name"] is True  # the string "true" can't be written

Semantic versions

semver.parse(text) returns a Result of a SemVer (SemVer 2.0.0), or a SemVerError; parse_unsafe raises it instead. A SemVer is a frozen dataclass with major, minor, patch, prerelease and build. < and > follow the spec's precedence, so a pre-release sorts before its release and build metadata is ignored; == includes the build. bump(...) follows npm's semver.inc, and difference(other) names the release type that separates two versions.

semver_range.parse(text) reads npm's range grammar: ^ and ~, comparators, x-ranges (1.x, *), hyphen ranges and ||. matches(version) tests one version and max_satisfying / min_satisfying pick from a list. A pre-release matches only a bound with a pre-release on the same version, unless you pass include_prerelease=True. caret, tilde, between and the comparison functions build ranges without parsing.

versions.py
from pyfect import semver, semver_range
from pyfect.result import Err

version = semver.parse_unsafe("1.2.3-rc.1+build.5")
print(version.prerelease, version.build)
print(version.bump("minor").format(), version.bump("prerelease").format())
assert version < semver.parse_unsafe("1.2.3")

# A pre-release comes before its release; build metadata doesn't count.
print(sorted(["1.10.0", "1.2.0", "1.2.0-alpha"], key=semver.parse_unsafe))
print(version.difference(semver.parse_unsafe("2.0.0")))

match semver.parse("1.2"):
    case Err(error):
        print(error.message)
    case _:
        raise AssertionError("1.2 is not a version")

supported = semver_range.parse_unsafe("^1.2.3 || >=3")
print(supported.matches("1.9.0"), supported.matches("2.1.0"))
best = supported.max_satisfying(["1.2.0", "1.4.1", "2.0.0"])
print(best)
assert best == semver.parse_unsafe("1.4.1")

# A pre-release matches only a bound on the same version, unless asked.
print(supported.matches("1.5.0-beta"), supported.matches("1.5.0-beta", include_prerelease=True))
print(semver_range.tilde("1.2.3").format())

Exact decimals

A BigDecimal is an integer value and a scale, the number being value * 10 ** -scale. Sums, differences and products are exact, and == compares values, so 0.3 equals 0.30. decimal.Decimal instead rounds every result to its context's precision.

from_string returns None for text that isn't a number; from_string_unsafe raises. divide gives 100 significant digits, rounded half up as in Effect, and None for a zero divisor. round(scale=..., mode=...) takes Effect's rounding modes ("half-from-zero" by default, "half-even", "ceil", "floor", "to-zero", ...), and format() prints the number without trailing zeros.

decimals.py
from pyfect import big_decimal
from pyfect.big_decimal import BigDecimal

price = big_decimal.from_string_unsafe("0.1")
fee = big_decimal.from_string_unsafe("0.2")
total = price.sum(fee)
print(total.format())
assert total == big_decimal.from_string_unsafe("0.30")  # 0.3 equals 0.30

# Division gives 100 significant digits; dividing by zero gives None.
third = big_decimal.from_string_unsafe("10").divide_unsafe(BigDecimal(3, 0))
print(third.format()[:12])
assert price.divide(BigDecimal(0, 0)) is None

amount = big_decimal.from_string_unsafe("2.345")
print(amount.round(scale=2).format(), amount.round(scale=2, mode="half-even").format())
print(amount.floor(1).format(), amount.multiply(amount).format())
assert big_decimal.from_string("12,5") is None

Reference: pyfect.encoding.toml, pyfect.encoding.yaml, pyfect.encoding.ini, pyfect.semver, pyfect.semver_range, pyfect.big_decimal.