Background

In every software you must check carefully that untrusted user input data matches your expectations. Unvalidated user input is a common source of security flaws. However many checks are repetitive and validation logic tends to be scattered all around the code. Because basic checks are duplicated, developers forget to check also for uncommon edge cases. Eventually there is often also some code to convert the input data (usually strings) to more convenient Python data types like int or bool.

pycerberus is a library that tackles these common problems and allows you to write tailored validators to perform additional checks. Furthermore the library also has built-in support for less common (but important) use cases like internationalization.

The library itself is heavily inspired by FormEncode by Ian Bicking. Therefore most of FormEncode’s design rationale is directly applicable to pycerberus. However several things about FormEncode annoyed me so much that I decided to write my own library when I needed one for my SMTP server project pymta.

Philosophy and Design

Rules are declared explicitly: Separating policy from mechanism

pycerberus separates validation rules (“Validators”) from the objects they validate against. It might be tempting to derive the validation rules from restrictions you specified earlier (e.g. from a class which is mapped by an ORM to a database). However that approach completely ignores that validation typically depends on context: In an API you have typically a lot more freedom in regard to allowed values compared to a public web interface where input needs to conform to a lot more checks. In a system where you declare the validation explicitly, this is possible. Also it is quite easy writing some code that generates a bottom line of validation rules automatically based on your ORM model and add additional restrictions depending on the context.

As pycerberus is completely context-agnostic (not being bundled with a specific framework), you can use it in many different places (e.g. web applications with different frameworks, server applications, check parameters in a library, …).

Further reading: FormEncode’s design rationale - most of the design ideas are also present in pycerberus.