Welcome to readycheck’s documentation!

The goal of this module is to allow to add custom checks when accessing class attributes.

It is designed to build classes that store objects not available at import time (e.g. later fetched from a distant service). It avoid us the pain to check if the connection has been established each time we need these objects: trying to access them will automagically raise an exception if they are not ready.

API Reference

Run custom checks on classes attributes when accessing them.

Does one thing, does it well.

exception readycheck.NotReadyError(msg: str, class_: type, attr: str)[source]

An attribute is tried to be accessed before it is ready.

Inherits from RuntimeError.

class_

The class holding the attribute to access.

Type

type

attr

The name of the attribute we tried to access.

Type

str

class readycheck.ReadyCheck(*args: Any, **kwargs: Any)[source]

Proxy class to prevent accessing not initialized objects.

When accessing a class attribute, this class:

  • returns its value (classic behavior) if it is evaluated ready (see below);

  • raises a NotReadyError exception otherwise.

Subclass this class to implement readiness check on class attributes and define readiness as needed. By default, attributes are considered not ready only if their value is None:

class NotNone(ReadyCheck):
    a = None            # NotNone.a will raise a NotReadyError
    b = <any object>    # NotNone.b will be the given object

Use check_type class-definition argument to define readiness based on attributes types (using isinstance()):

class MustBeList(ReadyCheck, check_type=list):
    a = "TBD"           # MustBeList.a will raise a NotReadyError
    b = [1, 2, 3]       # MustBeList.b will be the given list

Use check class-definition argument to define custom readiness check (value -> bool function):

class MustBePositive(ReadyCheck, check=lambda val: val > 0):
    a = 0               # MustBePositive.a will raise a NotReadyError
    b = 37              # MustBePositive.b will be 37

If both arguments are provided, attribute type will be checked first and custom check will be called only for suitable attributes.

Attributes can be set, updated and deleted the normal way. Readiness is evaluated at access time, so changing an attribute’s value will change its readiness with no additional work required, and attributes set after class definition also benefit the checking proxy.

Note

Attributes whose name start with "_" (private and magic attributes) are not affected and will be returned even if not ready.

These classes also implement the iterating protocol to provide access to protected attributes names (order preserved):

for name in NotNone:
    print(name)         # Will print "a" then "b"

Warning

Classes deriving from this class are not meant to be instantiated. Due to the checking proxy on class attributes, instances will not see attributes defined at class level, and attributes defined in __init__ or after construction will not be ready-checked.

This class relies on a custom metaclass: you will not be able to create mixin classes from this one and a custom-metaclass one.

classmethod get_raw(name)

Access to an attribute bypassing ready check.

Parameters

name (str) – name of the attribute. This must be a public attribute (no leading underscore).

Returns

The attribute value, whatever it is.

Raises

AttributeError – if the attribute dosent exist.

Indices and tables