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 aResult:Okwith the tables, orErrwith anEncodingErrorwhosemessagegives the line and column. A date-time with an offset becomes adatetimein UTC; a local date, date-time or time stays a string. It follows Effect's parser, which is not always whattomllibaccepts or rejects. Usetomllibwhen a file must follow the TOML specification to the letter.yaml.parse(text)returns the value of one document and raisesValueErroron text it can't read, as Effect'sYaml.parsethrows. Anchors, aliases and YAML 1.1 merge keys work:<<: *basecopiesbaseinto 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=isTrue, andtrue,falseandnullbecomeTrue,FalseandNone. 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'sini).
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 writtenSemantic 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.
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.
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 NoneReference: pyfect.encoding.toml,
pyfect.encoding.yaml,
pyfect.encoding.ini,
pyfect.semver,
pyfect.semver_range,
pyfect.big_decimal.