1# Python Absl Changelog 2 3All notable changes to Python Absl are recorded here. 4 5The format is based on [Keep a Changelog](https://keepachangelog.com). 6 7## Unreleased 8 9Nothing notable unreleased. 10 11## 2.1.0 (2024-01-16) 12 13### Added 14 15* (flags) Added `absl.flags.override_value` function to provide `FlagHolder` 16 with a construct to modify values. The new interface parallels 17 `absl.flags.FlagValues.__setattr__` but checks that the provided value 18 conforms to the flag's expected type. 19* (testing) Added a new method `absltest.TestCase.assertDataclassEqual` that 20 tests equality of `dataclass.dataclass` objects with better error messages 21 when the assert fails. 22 23### Changed 24 25* (flags) `absl.flags.argparse_flags.ArgumentParser` now correctly inherits 26 an empty instance of `FlagValues` to ensure that absl flags, such as 27 `--flagfile`, `--undefok` are supported. 28* (testing) Do not exit 5 if tests were skipped on Python 3.12. This follows 29 the CPython change in https://github.com/python/cpython/pull/113856. 30 31### Fixed 32 33* (flags) The flag `foo` no longer retains the value `bar` after 34 `FLAGS.foo = bar` fails due to a validation error. 35* (testing) Fixed an issue caused by 36 [this Python 3.12.1 change](https://github.com/python/cpython/pull/109725) 37 where the test reporter crashes when all tests are skipped. 38 39## 2.0.0 (2023-09-19) 40 41### Changed 42 43* `absl-py` no longer supports Python 3.6. It has reached end-of-life for more 44 than a year now. 45* Support Python 3.12. 46* (logging) `logging.exception` can now take `exc_info` as argument, with 47 default value `True`. Prior to this change setting `exc_info` would raise 48 `KeyError`, this change fixes this behaviour. 49* (testing) For Python 3.11+, the calls to `absltest.TestCase.enter_context` 50 are forwarded to `unittest.TestCase.enterContext` (when called via instance) 51 or `unittest.TestCase.enterClassContext` (when called via class) now. As a 52 result, on Python 3.11+, the private `_cls_exit_stack` attribute is not 53 defined on `absltest.TestCase` and `_exit_stack` attribute is not defined on 54 its instances. 55* (testing) `absltest.TestCase.assertSameStructure()` now uses the test case's 56 equality functions (registered with `TestCase.addTypeEqualityFunc()`) for 57 comparing leaves of the structure. 58* (testing) `abslTest.TestCase.fail()` now names its arguments `(self, 59 msg=None, user_msg=None)`, and not `(self, msg=None, prefix=None)`, better 60 reflecting the behavior and usage of the two message arguments. 61* `DEFINE_enum`, `DEFINE_multi_enum`, and `EnumParser` now raise errors when 62 `enum_values` is provided as a single string value. Additionally, 63 `EnumParser.enum_values` is now stored as a list copy of the provided 64 `enum_values` parameter. 65* (testing) Updated `paramaterized.CoopTestCase()` to use Python 3 metaclass 66 idioms. Most uses of this function continued working during the Python 3 67 migration still worked because a Python 2 compatibility `__metaclass__` 68 variables also existed. Now pure Python 3 base classes without backwards 69 compatibility will work as intended. 70* (testing) `absltest.TestCase.assertSequenceStartsWith` now explicitly fail 71 when passed a `Mapping` or `Set` object as the `whole` argument. 72 73## 1.4.0 (2023-01-11) 74 75### New 76 77* (testing) Added `@flagsaver.as_parsed`: this allows saving/restoring flags 78 using string values as if parsed from the command line and will also reflect 79 other flag states after command line parsing, e.g. `.present` is set. 80 81### Changed 82 83* (logging) If no log dir is specified `logging.find_log_dir()` now falls back 84 to `tempfile.gettempdir()` instead of `/tmp/`. 85 86### Fixed 87 88* (flags) Additional kwargs (e.g. `short_name=`) to `DEFINE_multi_enum_class` 89 are now correctly passed to the underlying `Flag` object. 90 91## 1.3.0 (2022-10-11) 92 93### Added 94 95* (flags) Added a new `absl.flags.set_default` function that updates the flag 96 default for a provided `FlagHolder`. This parallels the 97 `absl.flags.FlagValues.set_default` interface which takes a flag name. 98* (flags) The following functions now also accept `FlagHolder` instance(s) in 99 addition to flag name(s) as their first positional argument: 100 - `flags.register_validator` 101 - `flags.validator` 102 - `flags.register_multi_flags_validator` 103 - `flags.multi_flags_validator` 104 - `flags.mark_flag_as_required` 105 - `flags.mark_flags_as_required` 106 - `flags.mark_flags_as_mutual_exclusive` 107 - `flags.mark_bool_flags_as_mutual_exclusive` 108 - `flags.declare_key_flag` 109 110### Changed 111 112* (testing) Assertions `assertRaisesWithPredicateMatch` and 113 `assertRaisesWithLiteralMatch` now capture the raised `Exception` for 114 further analysis when used as a context manager. 115* (testing) TextAndXMLTestRunner now produces time duration values with 116 millisecond precision in XML test result output. 117* (flags) Keyword access to `flag_name` arguments in the following functions 118 is deprecated. This parameter will be renamed in a future 2.0.0 release. 119 - `flags.register_validator` 120 - `flags.validator` 121 - `flags.register_multi_flags_validator` 122 - `flags.multi_flags_validator` 123 - `flags.mark_flag_as_required` 124 - `flags.mark_flags_as_required` 125 - `flags.mark_flags_as_mutual_exclusive` 126 - `flags.mark_bool_flags_as_mutual_exclusive` 127 - `flags.declare_key_flag` 128 129## 1.2.0 (2022-07-18) 130 131### Fixed 132 133* Fixed a crash in Python 3.11 when `TempFileCleanup.SUCCESS` is used. 134 135## 1.1.0 (2022-06-01) 136 137* `Flag` instances now raise an error if used in a bool context. This prevents 138 the occasional mistake of testing an instance for truthiness rather than 139 testing `flag.value`. 140* `absl-py` no longer depends on `six`. 141 142## 1.0.0 (2021-11-09) 143 144### Changed 145 146* `absl-py` no longer supports Python 2.7, 3.4, 3.5. All versions have reached 147 end-of-life for more than a year now. 148* New releases will be tagged as `vX.Y.Z` instead of `pypi-vX.Y.Z` in the git 149 repo going forward. 150 151## 0.15.0 (2021-10-19) 152 153### Changed 154 155* (testing) #128: When running bazel with its `--test_filter=` flag, it now 156 treats the filters as `unittest`'s `-k` flag in Python 3.7+. 157 158## 0.14.1 (2021-09-30) 159 160### Fixed 161 162* Top-level `LICENSE` file is now exported in bazel. 163 164## 0.14.0 (2021-09-21) 165 166### Fixed 167 168* #171: Creating `argparse_flags.ArgumentParser` with `argument_default=` no 169 longer raises an exception when other `absl.flags` flags are defined. 170* #173: `absltest` now correctly sets up test filtering and fail fast flags 171 when an explicit `argv=` parameter is passed to `absltest.main`. 172 173## 0.13.0 (2021-06-14) 174 175### Added 176 177* (app) Type annotations for public `app` interfaces. 178* (testing) Added new decorator `@absltest.skipThisClass` to indicate a class 179 contains shared functionality to be used as a base class for other 180 TestCases, and therefore should be skipped. 181 182### Changed 183 184* (app) Annotated the `flag_parser` paramteter of `run` as keyword-only. This 185 keyword-only constraint will be enforced at runtime in a future release. 186* (app, flags) Flag validations now include all errors from disjoint flag 187 sets, instead of fail fast upon first error from all validators. Multiple 188 validators on the same flag still fails fast. 189 190## 0.12.0 (2021-03-08) 191 192### Added 193 194* (flags) Made `EnumClassSerializer` and `EnumClassListSerializer` public. 195* (flags) Added a `required: Optional[bool] = False` parameter to `DEFINE_*` 196 functions. 197* (testing) flagsaver overrides can now be specified in terms of FlagHolder. 198* (testing) `parameterized.product`: Allows testing a method over cartesian 199 product of parameters values, specified as a sequences of values for each 200 parameter or as kwargs-like dicts of parameter values. 201* (testing) Added public flag holders for `--test_srcdir` and `--test_tmpdir`. 202 Users should use `absltest.TEST_SRCDIR.value` and 203 `absltest.TEST_TMPDIR.value` instead of `FLAGS.test_srcdir` and 204 `FLAGS.test_tmpdir`. 205 206### Fixed 207 208* (flags) Made `CsvListSerializer` respect its delimiter argument. 209 210## 0.11.0 (2020-10-27) 211 212### Changed 213 214* (testing) Surplus entries in AssertionError stack traces from absltest are 215 now suppressed and no longer reported in the xml_reporter. 216* (logging) An exception is now raised instead of `logging.fatal` when logging 217 directories cannot be found. 218* (testing) Multiple flags are now set together before their validators run. 219 This resolves an issue where multi-flag validators rely on specific flag 220 combinations. 221* (flags) As a deterrent for misuse, FlagHolder objects will now raise a 222 TypeError exception when used in a conditional statement or equality 223 expression. 224 225## 0.10.0 (2020-08-19) 226 227### Added 228 229* (testing) `_TempDir` and `_TempFile` now implement `__fspath__` to satisfy 230 `os.PathLike` 231* (logging) `--logger_levels`: allows specifying the log levels of loggers. 232* (flags) `FLAGS.validate_all_flags`: a new method that validates all flags 233 and raises an exception if one fails. 234* (flags) `FLAGS.get_flags_for_module`: Allows fetching the flags a module 235 defines. 236* (testing) `parameterized.TestCase`: Supports async test definitions. 237* (testing,app) Added `--pdb` flag: When true, uncaught exceptions will be 238 handled by `pdb.post_mortem`. This is an alias for `--pdb_post_mortem`. 239 240### Changed 241 242* (testing) Failed tests output a copy/pastable test id to make it easier to 243 copy the failing test to the command line. 244* (testing) `@parameterized.parameters` now treats a single `abc.Mapping` as a 245 single test case, consistent with `named_parameters`. Previously the 246 `abc.Mapping` is treated as if only its keys are passed as a list of test 247 cases. If you were relying on the old inconsistent behavior, explicitly 248 convert the `abc.Mapping` to a `list`. 249* (flags) `DEFINE_enum_class` and `DEFINE_mutlti_enum_class` accept a 250 `case_sensitive` argument. When `False` (the default), strings are mapped to 251 enum member names without case sensitivity, and member names are serialized 252 in lowercase form. Flag definitions for enums whose members include 253 duplicates when case is ignored must now explicitly pass 254 `case_sensitive=True`. 255 256### Fixed 257 258* (flags) Defining an alias no longer marks the aliased flag as always present 259 on the command line. 260* (flags) Aliasing a multi flag no longer causes the default value to be 261 appended to. 262* (flags) Alias default values now matched the aliased default value. 263* (flags) Alias `present` counter now correctly reflects command line usage. 264 265## 0.9.0 (2019-12-17) 266 267### Added 268 269* (testing) `TestCase.enter_context`: Allows using context managers in setUp 270 and having them automatically exited when a test finishes. 271 272### Fixed 273 274* #126: calling `logging.debug(msg, stack_info=...)` no longer throws an 275 exception in Python 3.8. 276 277## 0.8.1 (2019-10-08) 278 279### Fixed 280 281* (testing) `absl.testing`'s pretty print reporter no longer buffers 282 RUN/OK/FAILED messages. 283* (testing) `create_tempfile` will overwrite pre-existing read-only files. 284 285## 0.8.0 (2019-08-26) 286 287### Added 288 289* (testing) `absltest.expectedFailureIf`: a variant of 290 `unittest.expectedFailure` that allows a condition to be given. 291 292### Changed 293 294* (bazel) Tests now pass when bazel 295 `--incompatible_allow_python_version_transitions=true` is set. 296* (bazel) Both Python 2 and Python 3 versions of tests are now created. To 297 only run one major Python version, use `bazel test 298 --test_tag_filters=-python[23]` to ignore the other version. 299* (testing) `assertTotallyOrdered` no longer requires objects to implement 300 `__hash__`. 301* (testing) `absltest` now integrates better with `--pdb_post_mortem`. 302* (testing) `xml_reporter` now includes timestamps to testcases, test_suite, 303 test_suites elements. 304 305### Fixed 306 307* #99: `absl.logging` no longer registers itself to `logging.root` at import 308 time. 309* #108: Tests now pass with Bazel 0.28.0 on macOS. 310 311## 0.7.1 (2019-03-12) 312 313### Added 314 315* (flags) `flags.mark_bool_flags_as_mutual_exclusive`: convenience function to 316 check that only one, or at most one, flag among a set of boolean flags are 317 True. 318 319### Changed 320 321* (bazel) Bazel 0.23+ or 0.22+ is now required for building/testing. 322 Specifically, a Bazel version that supports 323 `@bazel_tools//tools/python:python_version` for selecting the Python 324 version. 325 326### Fixed 327 328* #94: LICENSE files are now included in sdist. 329* #93: Change log added. 330 331## 0.7.0 (2019-01-11) 332 333### Added 334 335* (bazel) testonly=1 has been removed from the testing libraries, which allows 336 their use outside of testing contexts. 337* (flags) Multi-flags now accept any Iterable type for the default value 338 instead of only lists. Strings are still special cased as before. This 339 allows sets, generators, views, etc to be used naturally. 340* (flags) DEFINE_multi_enum_class: a multi flag variant of enum_class. 341* (testing) Most of absltest is now type-annotated. 342* (testing) Made AbslTest.assertRegex available under Python 2. This allows 343 Python 2 code to write more natural Python 3 compatible code. (Note: this 344 was actually released in 0.6.1, but unannounced) 345* (logging) logging.vlog_is_on: helper to tell if a vlog() call will actually 346 log anything. This allows avoiding computing expansive inputs to a logging 347 call when logging isn't enabled for that level. 348 349### Fixed 350 351* (flags) Pickling flags now raises an clear error instead of a cryptic one. 352 Pickling flags isn't supported; instead use flags_into_string to serialize 353 flags. 354* (flags) Flags serialization works better: the resulting serialized value, 355 when deserialized, won't cause --help to be invoked, thus ending the 356 process. 357* (flags) Several flag fixes to make them behave more like the Absl C++ flags: 358 empty --flagfile is allowed; --nohelp and --help=false don't display help 359* (flags) An empty --flagfile value (e.g. "--flagfile=" or "--flagfile=''" 360 doesn't raise an error; its not just ignored. This matches Abseil C++ 361 behavior. 362* (bazel) Building with Bazel 0.2.0 works without extra incompatibility 363 disable build flags. 364 365### Changed 366 367* (flags) Flag serialization is now deterministic: this improves Bazel build 368 caching for tools that are affected by flag serialization. 369 370## 0.6.0 (2018-10-22) 371 372### Added 373 374* Tempfile management APIs for tests: read/write/manage tempfiles for test 375 purposes easily and correctly. See TestCase.create_temp{file/dir} and the 376 corresponding commit for more info. 377 378## 0.5.0 (2018-09-17) 379 380### Added 381 382* Flags enum support: flags.DEFINE_enum_class allows using an `Enum` derived 383 class to define the allowed values for a flag. 384 385## 0.4.1 (2018-08-28) 386 387### Fixed 388 389* Flags no long allow spaces in their names 390 391### Changed 392 393* XML test output is written at the end of all test execution. 394* If the current user's username can't be gotten, fallback to uid, else fall 395 back to a generic 'unknown' string. 396 397## 0.4.0 (2018-08-14) 398 399### Added 400 401* argparse integration: absl-registered flags can now be accessed via argparse 402 using absl.flags.argparse_flags: see that module for more information. 403* TestCase.assertSameStructure now allows mixed set types. 404 405### Changed 406 407* Test output now includes start/end markers for each test ran. This is to 408 help distinguish output from tests clearly. 409 410## 0.3.0 (2018-07-25) 411 412### Added 413 414* `app.call_after_init`: Register functions to be called after app.run() is 415 called. Useful for program-wide initialization that library code may need. 416* `logging.log_every_n_seconds`: like log_every_n, but based on elapsed time 417 between logging calls. 418* `absltest.mock`: alias to unittest.mock (PY3) for better unittest drop-in 419 replacement. For PY2, it will be available if mock is importable. 420 421### Fixed 422 423* `ABSLLogger.findCaller()`: allow stack_info arg and return value for PY2 424* Make stopTest locking reentrant: this prevents deadlocks for test frameworks 425 that customize unittest.TextTestResult.stopTest. 426* Make --helpfull work with unicode flag help strings. 427