v0.11.0

This whole release was a result of massive refactoring done by Brian Harring (@ferringb).

Snakeoil's codebase is being modernized and dropping all historical patterns or shims that addressed python <3.11.

Snakeoil's roots map as far back to py2.2, and the code evolved to bridge py2k old style and new style classes, and the py3k changes. Three different object bases, and all the complications and pain that induced. This is now both unnecessarily causing a maintenance burden, but worse it induces downstream users to continue patterns no longer modern.

That is being removed or rewritten so they're using modern python patterns that have evolved over the last 2 decades.

This release is the first main batch of deprecations amd refactoring, but 0.11.x will introduce more deprecations, and modernized alternatives when doing so provides value.

Features

• Snakeoil classes, all that aren't deprecated, are again fully slotted. This is both for the performance that slots bring, and for the robustness it brings - it's impossible to accidentally assigned to the wrong attribute since slotting prevents that.

  Consumers of snakeoil aren't required to slot their derivatives - it is advised however, for the reasons snakeoil does so. With the exception of classes explicitly marked with __slotting_intentionally_disabled__ and what was deprecated in this release, snakeoil classes will be slotted going forward. Tests have been written to enforce this requirement in addition.

• Snakeoil is not yet fully typed, but this has been drastically increased, and will be increased going forward. Until we drop py3.11 support, generic functions will be a known gap. However due to python typing limitations, and snakeoil doing some fairly intrinsic things at times, not everything may be able to be fully typed. What can be typed, will be typed.

  This typing for the duration of 0.11.x should be treated as mostly stable. The underlying API is bound by semver rules, but the typing will need to be iterated on as we extend these changes through the pkgcore ecosystem and fully identify what corner cases downstream consumers rely on, vs how the API was thought to be used.

• Where snakeoil returns multiple objects in a tuple, these are being converted to NamedTuples. snakeoil.sequences.split_negations for example, returns (negated, positives). That is now a NamedTuple that is both
  maintaining the previous API, but allowing one to do this far more maintainable code.

   # previously, this encoded assumptions of the tuple return order.  This is
   # a known fragile pattern since any semver change can break it.
   negatives, positives = split_negations(something)
  
   # Now, the previous still works, and this works.
   results = split_negations(something)
   print(results.negatives)
   print(results.positives)

• class snakeoil.test.AbstractTest: Base ABC class you should use for tests PyTest silently drops collection of all abstract test classes; this is good, exempting when the intention was that it be concrete, but it's still ABC due unintentionally reasons. PyTest will not try to instantiate it, so you have no visibility of this problem; the test just silently drops out of the collection.

  Inherit from this instead of abc.ABC directly. This has subclass checks to detect this situation and fail the derivation unless you've explicitly marked the derivation as intentionally continuing to be abstract. That requirement is annoying, but it is the only way ot prevent this issue with PyTest.

• class snakeoil.klass.GenericEquality: This replaces snakeoil.klass.generic_equality written as a metaclass. This has the same
  basic behavior - it relies on __attr_comparison__ lists, but can optionally also use the slotting information of a class to generate
  __attr_comparison__. Migrate to this, generic_equality will be removed in 0.12.0.

• class snakeoil.GenericRichComparison: This is an __attr_comparison__ based implementation providing total ordering. This derives from GenericEquality, thus has the same convenience directives.

• class snakeoil.test.Modules: ABC test class you can inherit for doing code quality enforcement of your codebase. Currently it just checks for __all__ and verifies that __all__ is accurate. This is usable both as strict test failures, and as xfails.

• class snakeoil.test.NamespaceCollector: ABC base class you can use for working against all modules in a given python namespace. snakeoil.test.Modules uses this for example, for collecting all modules to enforce it's assertions against.

• class snakeoil.test.Slots: ABC test class that you can inherit and use for code quality checks of your codebase for slotting. This includes both requiring slotting (if you wish), and detecting questionable slotting settings.

• class snakeoil.klass.immutable.Simple: Replacement of snakeoil.klass.ImmutableInstance that is significantly more ergonomic. Previous code had to do this:

   class protected(ImmutableInstance):
     def __init__(self, val1, val2, val3):
       object.__setattr__(self, 'val1', val1)
       object.__setattr__(self, 'val2', val2)
       self._subinit(val3)
  
     def _subinit(self, val3):
       object.__setattr__(self, 'val3', val3)
  
     def mutating_func(self, val2):
       object.__setattr__(self, 'val2', val2)

  This was necessary as a way to bypass the __setattr__ and __delattr__ protections. This is still possible, but there are better ways now.

   class protected(Simple):
     def __init__(self, val1, val2, val3):
       self.val1 = val1
       self.val2 = val2
       self._subinit(val3)
  
     def _subinit(self, val3):
       self.val3 = val3
  
     @Simple.__allow_mutation__
     def mutatingb_func(self, val2):
       self.val2 = val2

  __init__ and __setstate__ are automatically wrapped with __allow_mutation__; any method that has mutation allowed, anything it calls, can also mutate. This is thread and async safe.

  The mechanism for this is more ergonomic, but less performant than just invoking object.__setattr__ directly. For hot paths methods it's recommended to continue using object.__setattr__. The performance delta will be addressed in a later release with an extension.

  Using this allows code flow analysis tools to actually make sense of these classes, so it's strongly recommended you use this over Strict if you can.

• class snakeoil.klass.immutable.Strict: This is the equivalent of what snakeoil.klass.ImmutableInstance was. You can migrate to it directly without any code change required.

• class snakeoil.suppress_deprecations: Context manager to suppress all deprecation warnings raised within the given context. Deprecation warnings are not exposed at runtime (CLI invocations), so do not use it there. It's actively harmful to do so.

• snakeoil.delayed.regexp: modern replacement for demand_compile_regexp. This takes the standard re.compile arguments and delays creation of the regex until it's accessed.

• snakeoil.klass.abstractclassvar: mechanism to force python's abc.ABC to treat a subclass as still abstract if a class variable hasn't been set. The usage is unfortunately not purely an annotation due to how abc.ABC is implemented, but can be used like this:

   class Base(abc.ABC):
     must_be_defined: ClassVar[str] = abstractclassvar(str)
  
   class StillABC(Base):
     "this class is still abstract, thus cannot be instantiatied until must_be_defined"
     pass
  
   class NoLongerABC(StillABC):
     "Do to the class var definition, this class can now be instantiated"
     must_be_defined = "now defined"

• snakeoil.klass.combine_metaclasses: mildly esoteric functionality for combining two metaclasses into one inherited chain of types. This is a convenience function; for example, it's used for combining abc.ABC with WeakInstMeta.

• snakeoil.klass.copy_class_docs: given a source class, transfer the documentation from that to the target class. This is a convenience tool for when implementing non trivial 'shape' of another class that you can't inherit from.

  Use this when you're implementing the shape of a class, but for whatever reason, cannot inherit from it. Multiple implementations in snakeoil.sequences and snakeoil.mappings implement the same api as things like set- this is used for just transferring the better documentation from the source class and injecting it into the target class.

• snakeoil.klass.copy_docs: this is for transferring the documentation between functions. This may seem like duplication of functools.wraps, but wraps does further mutations to the function that other tooling is aware of. copy_docs shouldn't be used for wrapping; it's for when you're implementing the same function in a different way, but matching the API exactly.

• snakeoil.klass.get_attrs_of: Slots aware tool to do what vars() should. Python's vars() only uses the __dict__ of the object; it cannot return any slotted attribute unless something incorrect has occurred like a slot shadowing.

  TL;dr: use this instead of vars(). The only scenario it cannot find an attribute to return is if a class defined it's __slots__ with a raw iterator, which is a misfeature of python and should never be used.

• snakeoil.klass.get_instances_of: Find every visitable instance of a given class. This should be mostly used in tests, or in very specific scenarios where a registry pattern exists, but a proper registry hasn't been implemented. For example in pkgcheck, there is no registry of checks, it has to scan for any derivative of a class...

v0.10.11

• Fix compatibility with python 3.14 (@mgorny, #105)
• Bump minimal python version to 3.11 (@arthurzam)
• Use ruff for code formatting (@arthurzam)

v0.10.10

• arghparse: fix compatibility with Python 3.12.8 (@mgorny)

v0.10.9

• arghparse: fix compatibility with Python 3.12.7 (@arthurzam)

v0.10.8

• arghparse: fix compatibility with Python 3.11.9 (@arthurzam)

v0.10.7

• ci: add PyPy3.10, Python 3.12 and Python 3.13 to testing (@thesamesam, #99)
• fix and update tox.ini (@arthurzam)
• sphinx_ext: support optional email address in authors (@ferringb)

v0.10.6

• remove deprecated distutils_extensions (@arthurzam, #77)
• enable Python 3.12 support (@thesamesam, #96)
• drop support for Python 3.9 (@arthurzam)

v0.10.5

• cli.arghparse: improve _format_args for Delayed (@arthurzam)
  pkgcore/pkgcheck#520
• compression: prefer gtar over tar if available (@thesamesam, #93)
• format code with black (@ferringb, @arthurzam, #95)

v0.10.4

• Add constraint satisfaction problem solver (#91, @arthurzam)
• dist.sphinxext: mark distutils_extensions as deprecated. This module will be removed in the near releases (@arthurzam)
• generate_man_rsts: improve sub-sectioning for sub-commands (@arthurzam)
• generate_man_rsts: better formatting for command line options (@arthurzam)

v0.10.3

• dist.sphinxext: new internal sphinx extension, used by pkgcore stack. This is considered internal and unstable API. (#89, @arthurzam)