/usr/share/doc/python-validictory-doc/html/usage.html is in python-validictory-doc 0.8.3-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using validictory — validictory 0.8.3 documentation</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '0.8.3',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="validictory 0.8.3 documentation" href="index.html" />
<link rel="next" title="validictory module" href="validictory.html" />
<link rel="prev" title="validictory 0.8.3" href="index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="validictory.html" title="validictory module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="index.html" title="validictory 0.8.3"
accesskey="P">previous</a> |</li>
<li><a href="index.html">validictory 0.8.3 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="using-validictory">
<h1>Using validictory<a class="headerlink" href="#using-validictory" title="Permalink to this headline">¶</a></h1>
<p>Normal use of validictory is as simple as calling <a class="reference internal" href="validictory.html#validictory.validate" title="validictory.validate"><tt class="xref py py-func docutils literal"><span class="pre">validictory.validate()</span></tt></a>,
the only thing to learn is how to craft a schema.</p>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<p>JSON documents and schema must first be loaded into a Python dictionary type
before it can be validated.</p>
<p>Parsing a simple JSON document:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">validictory</span>
<span class="gp">>>> </span><span class="n">validictory</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="s">"roast beef"</span><span class="p">,</span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"string"</span><span class="p">})</span>
</pre></div>
</div>
<p>Parsing a more complex JSON document:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">json</span>
<span class="gp">>>> </span><span class="kn">import</span> <span class="nn">validictory</span>
<span class="gp">>>> </span><span class="n">data</span> <span class="o">=</span> <span class="n">json</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="s">'["foo", {"bar":["baz", null, 1.0, 2]}]'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">schema</span> <span class="o">=</span> <span class="p">{</span>
<span class="gp">... </span> <span class="s">"type"</span><span class="p">:</span><span class="s">"array"</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">"items"</span><span class="p">:[</span>
<span class="gp">... </span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"string"</span><span class="p">},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"object"</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">"properties"</span><span class="p">:{</span>
<span class="gp">... </span> <span class="s">"bar"</span><span class="p">:{</span>
<span class="gp">... </span> <span class="s">"items"</span><span class="p">:[</span>
<span class="gp">... </span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"string"</span><span class="p">},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"any"</span><span class="p">},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"number"</span><span class="p">},</span>
<span class="gp">... </span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"integer"</span><span class="p">}</span>
<span class="gp">... </span> <span class="p">]</span>
<span class="gp">... </span> <span class="p">}</span>
<span class="gp">... </span> <span class="p">}</span>
<span class="gp">... </span> <span class="p">}</span>
<span class="gp">... </span> <span class="p">]</span>
<span class="gp">... </span><span class="p">}</span>
<span class="gp">>>> </span><span class="n">validictory</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">data</span><span class="p">,</span><span class="n">schema</span><span class="p">)</span>
</pre></div>
</div>
<p>Catch ValueErrors to handle validation issues:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">validictory</span>
<span class="gp">>>> </span><span class="k">try</span><span class="p">:</span>
<span class="gp">... </span> <span class="n">validictory</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="s">"short"</span><span class="p">,</span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span><span class="s">"string"</span><span class="p">,</span><span class="s">"minLength"</span><span class="p">:</span><span class="mi">15</span><span class="p">})</span>
<span class="gp">... </span><span class="k">except</span> <span class="ne">ValueError</span><span class="p">,</span> <span class="n">error</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span> <span class="n">error</span>
<span class="gp">...</span>
<span class="go">Length of value 'short' for field '_data' must be greater than or equal to 15</span>
</pre></div>
</div>
<p>For more example usage of all schema options check out the tests within
<tt class="docutils literal"><span class="pre">validictory/tests</span></tt>.</p>
</div>
<div class="section" id="schema-options">
<h2>Schema Options<a class="headerlink" href="#schema-options" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">type</span></tt></dt>
<dd><p class="first">Validate that an item in the data is of a particular type.</p>
<p>If a list of values is provided then any of the specified types
will be accepted.</p>
<p>Provided value can be any combination of the following:</p>
<ul class="last simple">
<li><tt class="docutils literal"><span class="pre">string</span></tt> - str and unicode objects</li>
<li><tt class="docutils literal"><span class="pre">integer</span></tt> - ints</li>
<li><tt class="docutils literal"><span class="pre">number</span></tt> - ints and floats</li>
<li><tt class="docutils literal"><span class="pre">boolean</span></tt> - bools</li>
<li><tt class="docutils literal"><span class="pre">object</span></tt> - dicts</li>
<li><tt class="docutils literal"><span class="pre">array</span></tt> - lists and tuples</li>
<li><tt class="docutils literal"><span class="pre">null</span></tt> - None</li>
<li><tt class="docutils literal"><span class="pre">any</span></tt> - any type is acceptable</li>
</ul>
</dd>
<dt><tt class="docutils literal"><span class="pre">properties</span></tt></dt>
<dd><p class="first">List of validators for properties of the object.</p>
<p class="last">In essence each item in the provided dict for properties is a sub-schema
applied against the property (if present) with the same name in the data.</p>
</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">patternProperties</span></tt></p>
<blockquote>
<div><p>Define a set of patterns that validate against subschemas.</p>
<p>Similarly to how <tt class="docutils literal"><span class="pre">properties</span></tt> works, any properties in the data that have
a name matching a particular pattern must validate against the provided
sub-schema.</p>
</div></blockquote>
<p><tt class="docutils literal"><span class="pre">additionalProperties</span></tt></p>
<blockquote>
<div><p>Schema for all additional properties not included in properties.</p>
<p>Can be <tt class="docutils literal"><span class="pre">False</span></tt> to disallow any additional properties not in
<tt class="docutils literal"><span class="pre">properties</span></tt>, or can be a sub-schema that all properties
not included in <tt class="docutils literal"><span class="pre">properties</span></tt> must match.</p>
</div></blockquote>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">items</span></tt></dt>
<dd><p class="first">Provide a schema or list of schemas to match against a list.</p>
<p>If the provided value is a schema object then every item in the list
will be validated against the given schema.</p>
<p class="last">If the provided value is a list of schemas then each item in the list
must match the schema in the same position of the list. (extra items
will be validated according to <tt class="docutils literal"><span class="pre">additionalItems</span></tt>)</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">additionalItems</span></tt></dt>
<dd>Used in conjunction with <tt class="docutils literal"><span class="pre">items</span></tt>. If False then no additional items
are allowed, if a schema is provided then all additional items must
match the provided schema.</dd>
<dt><tt class="docutils literal"><span class="pre">required</span></tt></dt>
<dd><p class="first">If True, the property must be present to validate.</p>
<p class="last">The default value of this parameter is set on the call to
<a class="reference internal" href="validictory.html#validictory.validate" title="validictory.validate"><tt class="xref py py-func docutils literal"><span class="pre">validate()</span></tt></a>. By default it is <tt class="docutils literal"><span class="pre">True</span></tt>.</p>
</dd>
</dl>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you are following the JSON Schema spec, this diverges from the
official spec as of v3. If you want to validate against v3 more
correctly, be sure to set <tt class="docutils literal"><span class="pre">required_by_default</span></tt> to False.</p>
</div>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">dependencies</span></tt></dt>
<dd>Can be a single string or list of strings representing properties
that must exist if the given property exists.</dd>
</dl>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">schema</span> <span class="o">=</span> <span class="p">{</span><span class="s">"prop01"</span><span class="p">:</span> <span class="p">{</span><span class="s">"required"</span><span class="p">:</span><span class="bp">False</span><span class="p">},</span>
<span class="s">"prop02"</span><span class="p">:</span> <span class="p">{</span><span class="s">"required"</span><span class="p">:</span><span class="bp">False</span><span class="p">,</span> <span class="s">"dependencies"</span><span class="p">:</span><span class="s">"prop01"</span><span class="p">}}</span>
<span class="c"># would validate</span>
<span class="p">{</span><span class="s">"prop01"</span><span class="p">:</span> <span class="mi">7</span><span class="p">}</span>
<span class="c"># would fail (missing prop01)</span>
<span class="p">{</span><span class="s">"prop02"</span><span class="p">:</span> <span class="mi">7</span><span class="p">}</span>
</pre></div>
</div>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">minimum</span></tt> and <tt class="docutils literal"><span class="pre">maximum</span></tt></dt>
<dd><p class="first">If the value is a number (int or float), these methods will validate
that the values are less than or greater than the given minimum/maximum.</p>
<p class="last">Minimum and maximum values are inclusive by default.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">exclusiveMinimum</span></tt> and <tt class="docutils literal"><span class="pre">exclusiveMaximum</span></tt></dt>
<dd>If these values are present and set to True, they will modify the
<tt class="docutils literal"><span class="pre">minimum</span></tt> and <tt class="docutils literal"><span class="pre">maximum</span></tt> tests to be exclusive.</dd>
<dt><tt class="docutils literal"><span class="pre">minItems</span></tt>, <tt class="docutils literal"><span class="pre">minLength</span></tt>, <tt class="docutils literal"><span class="pre">maxItems</span></tt>, and <tt class="docutils literal"><span class="pre">maxLength</span></tt></dt>
<dd><p class="first">If the value is a list or str, these will test the length of the list
or string.</p>
<p class="last">There is no difference in implementation between the items/length variants.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">uniqueItems</span></tt></dt>
<dd>Indicate that all attributes in a list must be unique.</dd>
<dt><tt class="docutils literal"><span class="pre">pattern</span></tt></dt>
<dd>If the value is a string, this provides a regular expression that
the string must match to be valid.</dd>
<dt><tt class="docutils literal"><span class="pre">blank</span></tt></dt>
<dd><p class="first">If False, validate that string values are not blank (the empty string).</p>
<p class="last">The default value of this parameter is set when initializing
<cite>SchemaValidator</cite>. By default it is <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">enum</span></tt></dt>
<dd>Provides an array that the value must match if present.</dd>
<dt><tt class="docutils literal"><span class="pre">format</span></tt></dt>
<dd><p class="first">Validate that the value matches a predefined format.</p>
<p>By default several formats are recognized:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">date-time</span></tt>: ‘yyyy-mm-ddhh:mm:ssZ’</li>
<li><tt class="docutils literal"><span class="pre">date</span></tt>: ‘yyyy-mm-dd’</li>
<li><tt class="docutils literal"><span class="pre">time</span></tt>: ‘hh:mm::ss’</li>
<li><tt class="docutils literal"><span class="pre">utc-millisec</span></tt>: number of seconds since UTC</li>
</ul>
<p class="last">formats can be provided as the <tt class="docutils literal"><span class="pre">format_validators</span></tt> argument to
<tt class="docutils literal"><span class="pre">validictory.validate</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">divisibleBy</span></tt></dt>
<dd>Ensures that the data value can be divided (without remainder) by a
given divisor (<strong>not 0</strong>).</dd>
<dt><tt class="docutils literal"><span class="pre">title</span></tt> and <tt class="docutils literal"><span class="pre">description</span></tt></dt>
<dd>These do no validation, but if provided must be strings or a
<tt class="docutils literal"><span class="pre">~validictory.SchemaError</span></tt> will be raised.</dd>
</dl>
</div>
<div class="section" id="common-recipes">
<h2>Common Recipes<a class="headerlink" href="#common-recipes" title="Permalink to this headline">¶</a></h2>
<p>A situation that often arises is the need to validate that all members of
a list validate according to one type of object or another. This can be
achieved by combining the “items”, “type”, and “object” schema options.</p>
<p>To define a property that you want to be a list of one or more types you’d
need to follow the following recipe (filling in foo and bar definition with
normal schema definition):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">schema</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"object"</span><span class="p">,</span>
<span class="s">"properties"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"foo_or_bar_list"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"array"</span><span class="p">,</span>
<span class="s">"items"</span><span class="p">:</span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span><span class="s">"type"</span><span class="p">:</span> <span class="s">"object"</span><span class="p">,</span>
<span class="c"># foo definition</span>
<span class="p">},</span>
<span class="p">{</span><span class="s">"type"</span><span class="p">:</span> <span class="s">"object"</span><span class="p">,</span>
<span class="c"># bar definition</span>
<span class="p">},</span>
<span class="p">]}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>A common example of this is the GeoJSON spec, which allows for a geometry
collection to have a list of geometries (Point, MultiPoint, LineString,
MultiLineString, Polygon, MultiPolygon).</p>
<p>Simplified GeoJSON example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="c"># to simplify things we make a few subschema dicts</span>
<span class="n">position</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"array"</span><span class="p">,</span>
<span class="s">"minItems"</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
<span class="s">"maxItems"</span><span class="p">:</span> <span class="mi">3</span>
<span class="p">}</span>
<span class="n">point</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"object"</span><span class="p">,</span>
<span class="s">"properties"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"pattern"</span><span class="p">:</span> <span class="s">"Point"</span>
<span class="p">},</span>
<span class="s">"coordinates"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="n">position</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="n">multipoint</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"object"</span><span class="p">,</span>
<span class="s">"properties"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"pattern"</span><span class="p">:</span> <span class="s">"MultiPoint"</span>
<span class="p">},</span>
<span class="s">"coordinates"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"array"</span><span class="p">,</span>
<span class="s">"minItems"</span><span class="p">:</span> <span class="mi">2</span><span class="p">,</span>
<span class="s">"items"</span><span class="p">:</span> <span class="n">position</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="c"># the main schema</span>
<span class="n">simplified_geojson_geometry</span> <span class="o">=</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"object"</span><span class="p">,</span>
<span class="s">"properties"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"pattern"</span><span class="p">:</span> <span class="s">"GeometryCollection"</span>
<span class="p">},</span>
<span class="c"># this defines an array ('geometries') that is a list of objects</span>
<span class="c"># which conform to one of the schemas in the type list</span>
<span class="s">"geometries"</span><span class="p">:</span> <span class="p">{</span>
<span class="s">"type"</span><span class="p">:</span> <span class="s">"array"</span><span class="p">,</span>
<span class="s">"items"</span><span class="p">:</span> <span class="p">{</span><span class="s">"type"</span><span class="p">:</span> <span class="p">[</span><span class="n">point</span><span class="p">,</span> <span class="n">multipoint</span><span class="p">]}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>(thanks to Jason Sanford for bringing this need to my attention)</p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using validictory</a><ul>
<li><a class="reference internal" href="#examples">Examples</a></li>
<li><a class="reference internal" href="#schema-options">Schema Options</a></li>
<li><a class="reference internal" href="#common-recipes">Common Recipes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">validictory 0.8.3</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="validictory.html"
title="next chapter">validictory module</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="validictory.html" title="validictory module"
>next</a> |</li>
<li class="right" >
<a href="index.html" title="validictory 0.8.3"
>previous</a> |</li>
<li><a href="index.html">validictory 0.8.3 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2011, James Turk.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>
|