cerberus

Last week, I got a mail from PyPI, the Python package index. They informed me that one of my open source projects had been designated as ‘critical,’ and I was therefore required to enable two-factor authentication. If I didn’t oblige, I would soon lose the ability to add new releases or modify the project. The project in question was Cerberus. The ‘critical’ designation happens when a project has been in the top 1% of downloads over the prior six months. »

Last February I published The State of Eve REST Framework. Among other things in that post, I mentioned that I was looking for ways that would allow me to allocate more time to the project (and its satellites). I really feel like I should put more effort into Eve, Cerberus and satellite projects Eve-Swagger, Flask-Sentinel, Eve.NET, etc. I love working on these projects and I know a lot of people rely on them. »

After a one year long development cycle I am proud to announce that version 1.0 of Cerberus, the data validation and transformation tool for Python, is finally out. A while ago I wrote an article on the new features and breaking changes that come with it, so please check it out carefully along with the changelog. I just wish to reiterate my gratitude towards all the contributors to the project. The ones who specifically worked on this awesome release, those who made it all possible, are: Matthew Ellison, Dominik Kellner, David Kirkendall, Damián Nohales, calve, Jonathan Huot, Roman Redkovich and of course the one and the only Frank Sachsenheim, whose role was pivotal to this release. »

Cerberus is a lightweight and extensible data validation library for Python. Beta has been around since 2012. During this time Cerberus has been serving as the validation system for Eve core. It has been also adopted by a quite a lot open source projects, averaging around 18K downloads per month on PyPI and collecting some remarkable endorsements.

All things considered, I would dare to claim that Cerberus is battle tested to death. This is, in fact, one reason why I believe that the time for a canonical and stable release has come. Another reason is that next release is a major one. It brings a ton of important new features along with very significant code refactoring and a redesigned, powerful API. Third, next release breaks backward compatibility, and we want to signal that in the version number.

So next Cerberus release will be 1.0. If you have been following the development this will come as no surprise, as a Release Candidate has been out for a while. As a Cerberus user you will want to take the plunge and upgrade to 1.0 because well, it is just too cool to be true. If new to Cerberus you will also want to adopt 1.0 right away, for the same reason. If you are new however, make sure you get the basics covered before reading further. By the way, at latest PyCon Italy I gave a talk on Cerberus which also included a preview of several 1.0 features. You can check the slides to get a general idea of the tool, its usage, and upcoming features.

Let’s now look at some of the relevant features and changes introduced with Cerberus 1.0. For a (mostly) accurate list of changes and new features, have a look at the changelog.

A few days ago Cerberus 0.9 was released. It includes a bunch of new cool features, let’s browse through some of them. Collection rules First up is the new set of anyof, allof, noneof and oneof validation rules. anyof allows you to list multiple sets of rules to validate against. The field will be considered valid if it validates against one set in the list. For example, to verify that a property is a number between 0 and 10 or 100 and 110, you could do the following: »

Yesterday Cerberus 0.8.1 was released with a few little fixes, one of them being more a new feature than a fix really: sub-document fields can now be set as field dependencies by using a ‘dotted’ notation. So, suppose we set the following validation schema: schema = { 'test_field': { 'dependencies': [ 'a_dict.foo', 'a_dict.bar' ] }, 'a_dict': { 'type': 'dict', 'schema': { 'foo': {'type': 'string'}, 'bar': {'type': 'string'} } } } Then, we can validate a document like this: »

Eve v0.5 was released today. Cerberus v0.8 only a few days ago. A whole lot of new features, changes and fixes are coming with these releases so make sure to check the official release post to gather all the news. »

People keep telling me that they want to validate class and instance attributes (object properties) with Cerberus. While it certainly wasn’t conceived with that goal in mind, it is actually very possible to leverage both the Python data model and Cerberus extensibility to achieve object validation. Nuts & Bolts Let’s say that we have a simple class: >>> class Person(object): ... pass We create a Person instance and add a few properties and values: »

Eve 0.4 adds cool features like Document Versioning and Coherence Mode. Cerberus 0.7 allows regex validation amongst other niceties. Make sure to check the official v0.4 announcement for all the details. »

The new release changes the way validation errors are reported. Please note that these changes will also affect future releases of Eve, the Python REST API Framework.

What we had before was basically a list of human-readable errors. Each item in the list, while perfectly fine for human reading, wasn’t really ideal for algorithmic parsing. Why would you want to parse the errors with an algorithm? A common case would be when your client is using business objects to represent API resources (think a client-side ORM), and would have a hard time binding validation errors to the objects themselves.

Primo aggiornamento per Cerberus, lo strumento per la convalida dei dizionari Python che ho rilasciato qualche tempo fa. Ora è possibile estendere la lista dei tipi di dato da convalidare, aggiungendone di propri. Per esempio nella nostra REST API (che usa Cerberus per la validazione) uso questa tecnica per implementare e convalidare il tipo ObjectId, tipico di MongoDB. I dettagli li trovate nella documentazione. »

Da qualche giorno ho rilasciato Cerberus, uno strumento per la convalida dei dizionari Python. Gli passate un dizionario, lui lo confronta con uno schema di convalida e, se c’è qualcosa che non va (per esempio una chiave sconosciuta, oppure un valore di tipo sbagliato), ve lo segnala. >>> v = Validator({'name': {'type': 'string'}}) >>> v.validate({'name': 'john doe'}) True Sono due le caratteristiche che rendono Cerberus interessante: è facilmente estensibile (la documentazione include un esempio di estensione del sistema di convalida), e non si blocca sollevando un’eccezione al primo problema riscontrato: gli errori, quando presenti, sono tutti riportati in una lista a fine convalida. »