/usr/share/doc/python-lxml/html/objectify.html is in python-lxml-doc 3.3.3-1.
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 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 | <!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" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.10: http://docutils.sourceforge.net/" />
<title>lxml.objectify</title>
<meta name="authors" content="Stefan Behnel Holger Joukl" />
<link rel="stylesheet" href="style.css" type="text/css" />
</head>
<body>
<div class="document" id="lxml-objectify">
<div class="sidemenu"><ul id="lxml-section"><li><span class="section title">lxml</span><ul class="menu foreign" id="index-menu"><li class="menu title"><a href="index.html">lxml</a><ul class="submenu"><li class="menu item"><a href="index.html#introduction">Introduction</a></li><li class="menu item"><a href="index.html#support-the-project">Support the project</a></li><li class="menu item"><a href="index.html#documentation">Documentation</a></li><li class="menu item"><a href="index.html#download">Download</a></li><li class="menu item"><a href="index.html#mailing-list">Mailing list</a></li><li class="menu item"><a href="index.html#bug-tracker">Bug tracker</a></li><li class="menu item"><a href="index.html#license">License</a></li><li class="menu item"><a href="index.html#old-versions">Old Versions</a></li><li class="menu item"><a href="index.html#legal-notice-for-donations">Legal Notice for Donations</a></li></ul></li></ul><ul class="menu foreign" id="intro-menu"><li class="menu title"><a href="intro.html">Why lxml?</a><ul class="submenu"><li class="menu item"><a href="intro.html#motto">Motto</a></li><li class="menu item"><a href="intro.html#aims">Aims</a></li></ul></li></ul><ul class="menu foreign" id="installation-menu"><li class="menu title"><a href="installation.html">Installing lxml</a><ul class="submenu"><li class="menu item"><a href="installation.html#requirements">Requirements</a></li><li class="menu item"><a href="installation.html#installation">Installation</a></li><li class="menu item"><a href="installation.html#building-lxml-from-sources">Building lxml from sources</a></li><li class="menu item"><a href="installation.html#using-lxml-with-python-libxml2">Using lxml with python-libxml2</a></li><li class="menu item"><a href="installation.html#ms-windows">MS Windows</a></li><li class="menu item"><a href="installation.html#macos-x">MacOS-X</a></li></ul></li></ul><ul class="menu foreign" id="performance-menu"><li class="menu title"><a href="performance.html">Benchmarks and Speed</a><ul class="submenu"><li class="menu item"><a href="performance.html#general-notes">General notes</a></li><li class="menu item"><a href="performance.html#how-to-read-the-timings">How to read the timings</a></li><li class="menu item"><a href="performance.html#parsing-and-serialising">Parsing and Serialising</a></li><li class="menu item"><a href="performance.html#the-elementtree-api">The ElementTree API</a></li><li class="menu item"><a href="performance.html#xpath">XPath</a></li><li class="menu item"><a href="performance.html#a-longer-example">A longer example</a></li><li class="menu item"><a href="performance.html#lxml-objectify">lxml.objectify</a></li></ul></li></ul><ul class="menu foreign" id="compatibility-menu"><li class="menu title"><a href="compatibility.html">ElementTree compatibility of lxml.etree</a></li></ul><ul class="menu foreign" id="FAQ-menu"><li class="menu title"><a href="FAQ.html">lxml FAQ - Frequently Asked Questions</a><ul class="submenu"><li class="menu item"><a href="FAQ.html#general-questions">General Questions</a></li><li class="menu item"><a href="FAQ.html#installation">Installation</a></li><li class="menu item"><a href="FAQ.html#contributing">Contributing</a></li><li class="menu item"><a href="FAQ.html#bugs">Bugs</a></li><li class="menu item"><a href="FAQ.html#id1">Threading</a></li><li class="menu item"><a href="FAQ.html#parsing-and-serialisation">Parsing and Serialisation</a></li><li class="menu item"><a href="FAQ.html#xpath-and-document-traversal">XPath and Document Traversal</a></li></ul></li></ul></li></ul><ul id="Developing with lxml-section"><li><span class="section title">Developing with lxml</span><ul class="menu foreign" id="tutorial-menu"><li class="menu title"><a href="tutorial.html">The lxml.etree Tutorial</a><ul class="submenu"><li class="menu item"><a href="tutorial.html#the-element-class">The Element class</a></li><li class="menu item"><a href="tutorial.html#the-elementtree-class">The ElementTree class</a></li><li class="menu item"><a href="tutorial.html#parsing-from-strings-and-files">Parsing from strings and files</a></li><li class="menu item"><a href="tutorial.html#namespaces">Namespaces</a></li><li class="menu item"><a href="tutorial.html#the-e-factory">The E-factory</a></li><li class="menu item"><a href="tutorial.html#elementpath">ElementPath</a></li></ul></li></ul><ul class="menu foreign" id="api index-menu"><li class="menu title"><a href="api/index.html">API reference</a></li></ul><ul class="menu foreign" id="api-menu"><li class="menu title"><a href="api.html">APIs specific to lxml.etree</a><ul class="submenu"><li class="menu item"><a href="api.html#lxml-etree">lxml.etree</a></li><li class="menu item"><a href="api.html#other-element-apis">Other Element APIs</a></li><li class="menu item"><a href="api.html#trees-and-documents">Trees and Documents</a></li><li class="menu item"><a href="api.html#iteration">Iteration</a></li><li class="menu item"><a href="api.html#error-handling-on-exceptions">Error handling on exceptions</a></li><li class="menu item"><a href="api.html#error-logging">Error logging</a></li><li class="menu item"><a href="api.html#serialisation">Serialisation</a></li><li class="menu item"><a href="api.html#incremental-xml-generation">Incremental XML generation</a></li><li class="menu item"><a href="api.html#cdata">CDATA</a></li><li class="menu item"><a href="api.html#xinclude-and-elementinclude">XInclude and ElementInclude</a></li><li class="menu item"><a href="api.html#write-c14n-on-elementtree">write_c14n on ElementTree</a></li></ul></li></ul><ul class="menu foreign" id="parsing-menu"><li class="menu title"><a href="parsing.html">Parsing XML and HTML with lxml</a><ul class="submenu"><li class="menu item"><a href="parsing.html#parsers">Parsers</a></li><li class="menu item"><a href="parsing.html#the-target-parser-interface">The target parser interface</a></li><li class="menu item"><a href="parsing.html#the-feed-parser-interface">The feed parser interface</a></li><li class="menu item"><a href="parsing.html#incremental-event-parsing">Incremental event parsing</a></li><li class="menu item"><a href="parsing.html#iterparse-and-iterwalk">iterparse and iterwalk</a></li><li class="menu item"><a href="parsing.html#python-unicode-strings">Python unicode strings</a></li></ul></li></ul><ul class="menu foreign" id="validation-menu"><li class="menu title"><a href="validation.html">Validation with lxml</a><ul class="submenu"><li class="menu item"><a href="validation.html#validation-at-parse-time">Validation at parse time</a></li><li class="menu item"><a href="validation.html#id1">DTD</a></li><li class="menu item"><a href="validation.html#relaxng">RelaxNG</a></li><li class="menu item"><a href="validation.html#xmlschema">XMLSchema</a></li><li class="menu item"><a href="validation.html#id2">Schematron</a></li><li class="menu item"><a href="validation.html#id3">(Pre-ISO-Schematron)</a></li></ul></li></ul><ul class="menu foreign" id="xpathxslt-menu"><li class="menu title"><a href="xpathxslt.html">XPath and XSLT with lxml</a><ul class="submenu"><li class="menu item"><a href="xpathxslt.html#xpath">XPath</a></li><li class="menu item"><a href="xpathxslt.html#xslt">XSLT</a></li></ul></li></ul><ul class="menu current" id="objectify-menu"><li class="menu title"><a href="objectify.html">lxml.objectify</a><ul class="submenu"><li class="menu item"><a href="objectify.html#the-lxml-objectify-api">The lxml.objectify API</a></li><li class="menu item"><a href="objectify.html#asserting-a-schema">Asserting a Schema</a></li><li class="menu item"><a href="objectify.html#objectpath">ObjectPath</a></li><li class="menu item"><a href="objectify.html#python-data-types">Python data types</a></li><li class="menu item"><a href="objectify.html#how-data-types-are-matched">How data types are matched</a></li><li class="menu item"><a href="objectify.html#what-is-different-from-lxml-etree">What is different from lxml.etree?</a></li></ul></li></ul><ul class="menu foreign" id="lxmlhtml-menu"><li class="menu title"><a href="lxmlhtml.html">lxml.html</a><ul class="submenu"><li class="menu item"><a href="lxmlhtml.html#parsing-html">Parsing HTML</a></li><li class="menu item"><a href="lxmlhtml.html#html-element-methods">HTML Element Methods</a></li><li class="menu item"><a href="lxmlhtml.html#running-html-doctests">Running HTML doctests</a></li><li class="menu item"><a href="lxmlhtml.html#creating-html-with-the-e-factory">Creating HTML with the E-factory</a></li><li class="menu item"><a href="lxmlhtml.html#working-with-links">Working with links</a></li><li class="menu item"><a href="lxmlhtml.html#forms">Forms</a></li><li class="menu item"><a href="lxmlhtml.html#cleaning-up-html">Cleaning up HTML</a></li><li class="menu item"><a href="lxmlhtml.html#html-diff">HTML Diff</a></li><li class="menu item"><a href="lxmlhtml.html#examples">Examples</a></li></ul></li></ul><ul class="menu foreign" id="cssselect-menu"><li class="menu title"><a href="cssselect.html">lxml.cssselect</a><ul class="submenu"><li class="menu item"><a href="cssselect.html#the-cssselector-class">The CSSSelector class</a></li><li class="menu item"><a href="cssselect.html#the-cssselect-method">The cssselect method</a></li><li class="menu item"><a href="cssselect.html#supported-selectors">Supported Selectors</a></li><li class="menu item"><a href="cssselect.html#namespaces">Namespaces</a></li></ul></li></ul><ul class="menu foreign" id="elementsoup-menu"><li class="menu title"><a href="elementsoup.html">BeautifulSoup Parser</a><ul class="submenu"><li class="menu item"><a href="elementsoup.html#parsing-with-the-soupparser">Parsing with the soupparser</a></li><li class="menu item"><a href="elementsoup.html#entity-handling">Entity handling</a></li><li class="menu item"><a href="elementsoup.html#using-soupparser-as-a-fallback">Using soupparser as a fallback</a></li><li class="menu item"><a href="elementsoup.html#using-only-the-encoding-detection">Using only the encoding detection</a></li></ul></li></ul><ul class="menu foreign" id="html5parser-menu"><li class="menu title"><a href="html5parser.html">html5lib Parser</a><ul class="submenu"><li class="menu item"><a href="html5parser.html#differences-to-regular-html-parsing">Differences to regular HTML parsing</a></li><li class="menu item"><a href="html5parser.html#function-reference">Function Reference</a></li></ul></li></ul></li></ul><ul id="Extending lxml-section"><li><span class="section title">Extending lxml</span><ul class="menu foreign" id="resolvers-menu"><li class="menu title"><a href="resolvers.html">Document loading and URL resolving</a><ul class="submenu"><li class="menu item"><a href="resolvers.html#xml-catalogs">XML Catalogs</a></li><li class="menu item"><a href="resolvers.html#uri-resolvers">URI Resolvers</a></li><li class="menu item"><a href="resolvers.html#document-loading-in-context">Document loading in context</a></li><li class="menu item"><a href="resolvers.html#i-o-access-control-in-xslt">I/O access control in XSLT</a></li></ul></li></ul><ul class="menu foreign" id="extensions-menu"><li class="menu title"><a href="extensions.html">Python extensions for XPath and XSLT</a><ul class="submenu"><li class="menu item"><a href="extensions.html#xpath-extension-functions">XPath Extension functions</a></li><li class="menu item"><a href="extensions.html#xslt-extension-elements">XSLT extension elements</a></li></ul></li></ul><ul class="menu foreign" id="element classes-menu"><li class="menu title"><a href="element_classes.html">Using custom Element classes in lxml</a><ul class="submenu"><li class="menu item"><a href="element_classes.html#background-on-element-proxies">Background on Element proxies</a></li><li class="menu item"><a href="element_classes.html#element-initialization">Element initialization</a></li><li class="menu item"><a href="element_classes.html#setting-up-a-class-lookup-scheme">Setting up a class lookup scheme</a></li><li class="menu item"><a href="element_classes.html#generating-xml-with-custom-classes">Generating XML with custom classes</a></li><li class="menu item"><a href="element_classes.html#id1">Implementing namespaces</a></li></ul></li></ul><ul class="menu foreign" id="sax-menu"><li class="menu title"><a href="sax.html">Sax support</a><ul class="submenu"><li class="menu item"><a href="sax.html#building-a-tree-from-sax-events">Building a tree from SAX events</a></li><li class="menu item"><a href="sax.html#producing-sax-events-from-an-elementtree-or-element">Producing SAX events from an ElementTree or Element</a></li><li class="menu item"><a href="sax.html#interfacing-with-pulldom-minidom">Interfacing with pulldom/minidom</a></li></ul></li></ul><ul class="menu foreign" id="capi-menu"><li class="menu title"><a href="capi.html">The public C-API of lxml.etree</a><ul class="submenu"><li class="menu item"><a href="capi.html#writing-external-modules-in-cython">Writing external modules in Cython</a></li><li class="menu item"><a href="capi.html#writing-external-modules-in-c">Writing external modules in C</a></li></ul></li></ul></li></ul><ul id="Developing lxml-section"><li><span class="section title">Developing lxml</span><ul class="menu foreign" id="build-menu"><li class="menu title"><a href="build.html">How to build lxml from source</a><ul class="submenu"><li class="menu item"><a href="build.html#cython">Cython</a></li><li class="menu item"><a href="build.html#github-git-and-hg">Github, git and hg</a></li><li class="menu item"><a href="build.html#building-the-sources">Building the sources</a></li><li class="menu item"><a href="build.html#running-the-tests-and-reporting-errors">Running the tests and reporting errors</a></li><li class="menu item"><a href="build.html#building-an-egg-or-wheel">Building an egg or wheel</a></li><li class="menu item"><a href="build.html#building-lxml-on-macos-x">Building lxml on MacOS-X</a></li><li class="menu item"><a href="build.html#static-linking-on-windows">Static linking on Windows</a></li><li class="menu item"><a href="build.html#building-debian-packages-from-svn-sources">Building Debian packages from SVN sources</a></li></ul></li></ul><ul class="menu foreign" id="lxml source howto-menu"><li class="menu title"><a href="lxml-source-howto.html">How to read the source of lxml</a><ul class="submenu"><li class="menu item"><a href="lxml-source-howto.html#what-is-cython">What is Cython?</a></li><li class="menu item"><a href="lxml-source-howto.html#where-to-start">Where to start?</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-etree">lxml.etree</a></li><li class="menu item"><a href="lxml-source-howto.html#python-modules">Python modules</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-objectify">lxml.objectify</a></li><li class="menu item"><a href="lxml-source-howto.html#lxml-html">lxml.html</a></li></ul></li></ul><ul class="menu foreign" id="changes 3 3 3-menu"><li class="menu title"><a href="changes-3.3.3.html">Release Changelog</a></li></ul><ul class="menu foreign" id="credits-menu"><li class="menu title"><a href="credits.html">Credits</a><ul class="submenu"><li class="menu item"><a href="credits.html#main-contributors">Main contributors</a></li><li class="menu item"><a href="credits.html#special-thanks-goes-to">Special thanks goes to:</a></li></ul></li></ul></li><li><a href="http://lxml.de/sitemap.html">Sitemap</a></li></ul></div><h1 class="title">lxml.objectify</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Authors:</th>
<td>Stefan Behnel
<br />Holger Joukl</td></tr>
</tbody>
</table>
<p>lxml supports an alternative API similar to the <a class="reference external" href="http://uche.ogbuji.net/tech/4suite/amara/">Amara</a> bindery or
<a class="reference external" href="http://gnosis.cx/download/">gnosis.xml.objectify</a> through a <a class="reference external" href="element_classes.html">custom Element implementation</a>. The main idea
is to hide the usage of XML behind normal Python objects, sometimes referred
to as data-binding. It allows you to use XML as if you were dealing with a
normal Python object hierarchy.</p>
<p>Accessing the children of an XML element deploys object attribute access. If
there are multiple children with the same name, slicing and indexing can be
used. Python data types are extracted from XML content automatically and made
available to the normal Python operators.</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#the-lxml-objectify-api" id="id1">The lxml.objectify API</a><ul>
<li><a class="reference internal" href="#element-access-through-object-attributes" id="id2">Element access through object attributes</a></li>
<li><a class="reference internal" href="#creating-objectify-trees" id="id3">Creating objectify trees</a></li>
<li><a class="reference internal" href="#tree-generation-with-the-e-factory" id="id4">Tree generation with the E-factory</a></li>
<li><a class="reference internal" href="#namespace-handling" id="id5">Namespace handling</a></li>
</ul>
</li>
<li><a class="reference internal" href="#asserting-a-schema" id="id6">Asserting a Schema</a></li>
<li><a class="reference internal" href="#objectpath" id="id7">ObjectPath</a></li>
<li><a class="reference internal" href="#python-data-types" id="id8">Python data types</a><ul>
<li><a class="reference internal" href="#recursive-tree-dump" id="id9">Recursive tree dump</a></li>
<li><a class="reference internal" href="#recursive-string-representation-of-elements" id="id10">Recursive string representation of elements</a></li>
</ul>
</li>
<li><a class="reference internal" href="#how-data-types-are-matched" id="id11">How data types are matched</a><ul>
<li><a class="reference internal" href="#type-annotations" id="id12">Type annotations</a></li>
<li><a class="reference internal" href="#xml-schema-datatype-annotation" id="id13">XML Schema datatype annotation</a></li>
<li><a class="reference internal" href="#the-dataelement-factory" id="id14">The DataElement factory</a></li>
<li><a class="reference internal" href="#defining-additional-data-classes" id="id15">Defining additional data classes</a></li>
<li><a class="reference internal" href="#advanced-element-class-lookup" id="id16">Advanced element class lookup</a></li>
</ul>
</li>
<li><a class="reference internal" href="#what-is-different-from-lxml-etree" id="id17">What is different from lxml.etree?</a></li>
</ul>
</div>
<p>To set up and use <tt class="docutils literal">objectify</tt>, you need both the <tt class="docutils literal">lxml.etree</tt>
module and <tt class="docutils literal">lxml.objectify</tt>:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">etree</span>
<span class="gp">>>> </span><span class="kn">from</span> <span class="nn">lxml</span> <span class="kn">import</span> <span class="n">objectify</span>
</pre></div>
<p>The objectify API is very different from the ElementTree API. If it
is used, it should not be mixed with other element implementations
(such as trees parsed with <tt class="docutils literal">lxml.etree</tt>), to avoid non-obvious
behaviour.</p>
<p>The <a class="reference external" href="performance.html#lxml-objectify">benchmark page</a> has some hints on performance optimisation of
code using lxml.objectify.</p>
<p>To make the doctests in this document look a little nicer, we also use
this:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">lxml.usedoctest</span>
</pre></div>
<p>Imported from within a doctest, this relieves us from caring about the exact
formatting of XML output.</p>
<div class="section" id="the-lxml-objectify-api">
<h1>The lxml.objectify API</h1>
<p>In <tt class="docutils literal">lxml.objectify</tt>, element trees provide an API that models the behaviour
of normal Python object trees as closely as possible.</p>
<div class="section" id="element-access-through-object-attributes">
<h2>Element access through object attributes</h2>
<p>The main idea behind the <tt class="docutils literal">objectify</tt> API is to hide XML element access
behind the usual object attribute access pattern. Asking an element for an
attribute will return the sequence of children with corresponding tag names:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"root"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"b"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">b</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span>
<span class="go">0</span>
<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"b"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">b</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">b</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">[</span><span class="mi">1</span><span class="p">])</span>
<span class="go">1</span>
</pre></div>
<p>For convenience, you can omit the index '0' to access the first child:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">b</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">index</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="p">)</span>
<span class="go">0</span>
<span class="gp">>>> </span><span class="k">del</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
</pre></div>
<p>Iteration and slicing also obey the requested tag:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">x1</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"x"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">x2</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"x"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">x3</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"x"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="p">]</span>
<span class="go">['x', 'x', 'x']</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">3</span><span class="p">]</span> <span class="p">]</span>
<span class="go">['x', 'x']</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">x</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">:]</span> <span class="p">]</span>
<span class="go">['x']</span>
<span class="gp">>>> </span><span class="k">del</span> <span class="n">root</span><span class="o">.</span><span class="n">x</span><span class="p">[</span><span class="mi">1</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="p">]</span>
<span class="go">['x', 'x']</span>
</pre></div>
<p>If you want to iterate over all children or need to provide a specific
namespace for the tag, use the <tt class="docutils literal">iterchildren()</tt> method. Like the other
methods for iteration, it supports an optional tag keyword argument:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iterchildren</span><span class="p">()</span> <span class="p">]</span>
<span class="go">['b', 'x', 'x']</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">iterchildren</span><span class="p">(</span><span class="n">tag</span><span class="o">=</span><span class="s">'b'</span><span class="p">)</span> <span class="p">]</span>
<span class="go">['b']</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span> <span class="p">]</span>
<span class="go">['b']</span>
</pre></div>
<p>XML attributes are accessed as in the normal ElementTree API:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"c"</span><span class="p">,</span> <span class="n">myattr</span><span class="o">=</span><span class="s">"someval"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"myattr"</span><span class="p">))</span>
<span class="go">someval</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s">"c"</span><span class="p">,</span> <span class="s">"oh-oh"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"c"</span><span class="p">))</span>
<span class="go">oh-oh</span>
</pre></div>
<p>In addition to the normal ElementTree API for appending elements to trees,
subtrees can also be added by assigning them to object attributes. In this
case, the subtree is automatically deep copied and the tag name of its root is
updated to match the attribute name:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"yet_another_child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">new_child</span> <span class="o">=</span> <span class="n">el</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">new_child</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">new_child</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">yet_another_child</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">y</span> <span class="o">=</span> <span class="p">[</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"y"</span><span class="p">),</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"y"</span><span class="p">)</span> <span class="p">]</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">y</span> <span class="p">]</span>
<span class="go">['y', 'y']</span>
</pre></div>
<p>The latter is a short form for operations on the full slice:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">y</span><span class="p">[:]</span> <span class="o">=</span> <span class="p">[</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"y"</span><span class="p">)</span> <span class="p">]</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">y</span> <span class="p">]</span>
<span class="go">['y']</span>
</pre></div>
<p>You can also replace children that way:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">child1</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">child2</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">child3</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"new_child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">subel</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">el</span><span class="p">,</span> <span class="s">"sub"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">child</span> <span class="o">=</span> <span class="n">el</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">child</span><span class="o">.</span><span class="n">sub</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">sub</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">child</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">=</span> <span class="n">el</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">child</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span><span class="o">.</span><span class="n">sub</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">sub</span>
</pre></div>
<p>Note that special care must be taken when changing the tag name of an element:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">b</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span> <span class="o">=</span> <span class="s">"notB"</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: b</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">notB</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">notB</span>
</pre></div>
</div>
<div class="section" id="creating-objectify-trees">
<h2>Creating objectify trees</h2>
<p>As with <tt class="docutils literal">lxml.etree</tt>, you can either create an <tt class="docutils literal">objectify</tt> tree by
parsing an XML document or by building one from scratch. To parse a
document, just use the <tt class="docutils literal">parse()</tt> or <tt class="docutils literal">fromstring()</tt> functions of
the module:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">fileobject</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s">'<test/>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">tree</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">fileobject</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">tree</span><span class="o">.</span><span class="n">getroot</span><span class="p">(),</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'<test/>'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
<span class="go">True</span>
</pre></div>
<p>To build a new tree in memory, <tt class="docutils literal">objectify</tt> replicates the standard
factory function <tt class="docutils literal">Element()</tt> from <tt class="docutils literal">lxml.etree</tt>:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">obj_el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"new"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
<span class="go">True</span>
</pre></div>
<p>After creating such an Element, you can use the <a class="reference external" href="tutorial.html#the-element-class">usual API</a> of
lxml.etree to add SubElements to the tree:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">child</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="s">"newchild"</span><span class="p">,</span> <span class="n">attr</span><span class="o">=</span><span class="s">"value"</span><span class="p">)</span>
</pre></div>
<p>New subelements will automatically inherit the objectify behaviour
from their tree. However, all independent elements that you create
through the <tt class="docutils literal">Element()</tt> factory of lxml.etree (instead of objectify)
will not support the <tt class="docutils literal">objectify</tt> API by themselves:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">subel</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">obj_el</span><span class="p">,</span> <span class="s">"sub"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">subel</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">independent_el</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"new"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">isinstance</span><span class="p">(</span><span class="n">independent_el</span><span class="p">,</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedElement</span><span class="p">))</span>
<span class="go">False</span>
</pre></div>
</div>
<div class="section" id="tree-generation-with-the-e-factory">
<h2>Tree generation with the E-factory</h2>
<p>To simplify the generation of trees even further, you can use the E-factory:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">E</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">E</span><span class="o">.</span><span class="n">root</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">a</span><span class="p">(</span><span class="mi">5</span><span class="p">),</span>
<span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">b</span><span class="p">(</span><span class="mf">6.1</span><span class="p">),</span>
<span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">c</span><span class="p">(</span><span class="bp">True</span><span class="p">),</span>
<span class="gp">... </span> <span class="n">E</span><span class="o">.</span><span class="n">d</span><span class="p">(</span><span class="s">"how"</span><span class="p">,</span> <span class="n">tell</span><span class="o">=</span><span class="s">"me"</span><span class="p">)</span>
<span class="gp">... </span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns:py="http://codespeak.net/lxml/objectify/pytype"></span>
<span class="go"> <a py:pytype="int">5</a></span>
<span class="go"> <b py:pytype="float">6.1</b></span>
<span class="go"> <c py:pytype="bool">true</c></span>
<span class="go"> <d py:pytype="str" tell="me">how</d></span>
<span class="go"></root></span>
</pre></div>
<p>This allows you to write up a specific language in tags:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">ROOT</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span><span class="o">.</span><span class="n">root</span>
<span class="gp">>>> </span><span class="n">TITLE</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">E</span><span class="o">.</span><span class="n">title</span>
<span class="gp">>>> </span><span class="n">HOWMANY</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">E</span><span class="p">,</span> <span class="s">"how-many"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">ROOT</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">TITLE</span><span class="p">(</span><span class="s">"The title"</span><span class="p">),</span>
<span class="gp">... </span> <span class="n">HOWMANY</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span>
<span class="gp">... </span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns:py="http://codespeak.net/lxml/objectify/pytype"></span>
<span class="go"> <title py:pytype="str">The title</title></span>
<span class="go"> <how-many py:pytype="int">5</how-many></span>
<span class="go"></root></span>
</pre></div>
<p><tt class="docutils literal">objectify.E</tt> is an instance of <tt class="docutils literal">objectify.ElementMaker</tt>. By default, it
creates pytype annotated Elements without a namespace. You can switch off the
pytype annotation by passing False to the <tt class="docutils literal">annotate</tt> keyword argument of the
constructor. You can also pass a default namespace and an <tt class="docutils literal">nsmap</tt>:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">myE</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ElementMaker</span><span class="p">(</span><span class="n">annotate</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">namespace</span><span class="o">=</span><span class="s">"http://my/ns"</span><span class="p">,</span> <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="bp">None</span> <span class="p">:</span> <span class="s">"http://my/ns"</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">myE</span><span class="o">.</span><span class="n">root</span><span class="p">(</span> <span class="n">myE</span><span class="o">.</span><span class="n">someint</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns="http://my/ns"></span>
<span class="go"> <someint>2</someint></span>
<span class="go"></root></span>
</pre></div>
</div>
<div class="section" id="namespace-handling">
<h2>Namespace handling</h2>
<p>During tag lookups, namespaces are handled mostly behind the scenes.
If you access a child of an Element without specifying a namespace,
the lookup will use the namespace of the parent:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"{http://ns/}root"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://ns/}b"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://other/}c"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
</pre></div>
<p>Note that the <tt class="docutils literal">SubElement()</tt> factory of <tt class="docutils literal">lxml.etree</tt> does not
inherit any namespaces when creating a new subelement. Element
creation must be explicit about the namespace, and is simplified
through the E-factory as described above.</p>
<p>Lookups, however, inherit namespaces implicitly:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="o">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: {http://ns/}c</span>
</pre></div>
<p>To access an element in a different namespace than its parent, you can
use <tt class="docutils literal">getattr()</tt>:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://other/}c"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://other/}c</span>
</pre></div>
<p>For convenience, there is also a quick way through item access:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">root</span><span class="p">[</span><span class="s">"{http://other/}c"</span><span class="p">]</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">c</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://other/}c</span>
</pre></div>
<p>The same approach must be used to access children with tag names that are not
valid Python identifiers:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://ns/}tag-name"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}tag-name</span>
<span class="gp">>>> </span><span class="n">new_el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"{http://ns/}new-element"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">new_el</span><span class="p">,</span> <span class="s">"{http://ns/}child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">new_el</span><span class="p">,</span> <span class="s">"{http://ns/}child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">new_el</span><span class="p">,</span> <span class="s">"{http://ns/}child"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span> <span class="n">new_el</span><span class="p">,</span> <span class="n">new_el</span> <span class="p">]</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]))</span>
<span class="go">2</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}tag-name</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="p">))</span>
<span class="go">3</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}child</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"tag-name"</span><span class="p">][</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">child</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}child</span>
</pre></div>
<p>or for names that have a special meaning in lxml.objectify:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">XML</span><span class="p">(</span><span class="s">"<root><text>TEXT</text></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">text</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">'NoneType' object has no attribute 'text'</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="p">[</span><span class="s">"text"</span><span class="p">]</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="go">TEXT</span>
</pre></div>
</div>
</div>
<div class="section" id="asserting-a-schema">
<h1>Asserting a Schema</h1>
<p>When dealing with XML documents from different sources, you will often
require them to follow a common schema. In lxml.objectify, this
directly translates to enforcing a specific object tree, i.e. expected
object attributes are ensured to be there and to have the expected
type. This can easily be achieved through XML Schema validation at
parse time. Also see the <a class="reference external" href="validation.html">documentation on validation</a> on this
topic.</p>
<p>First of all, we need a parser that knows our schema, so let's say we
parse the schema from a file-like object (or file or filename):</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">f</span> <span class="o">=</span> <span class="n">StringIO</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
<span class="gp">... </span><span class="s"> <xsd:element name="a" type="AType"/></span>
<span class="gp">... </span><span class="s"> <xsd:complexType name="AType"></span>
<span class="gp">... </span><span class="s"> <xsd:sequence></span>
<span class="gp">... </span><span class="s"> <xsd:element name="b" type="xsd:string" /></span>
<span class="gp">... </span><span class="s"> </xsd:sequence></span>
<span class="gp">... </span><span class="s"> </xsd:complexType></span>
<span class="gp">... </span><span class="s"> </xsd:schema></span>
<span class="gp">... </span><span class="s">'''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">schema</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XMLSchema</span><span class="p">(</span><span class="nb">file</span><span class="o">=</span><span class="n">f</span><span class="p">)</span>
</pre></div>
<p>When creating the validating parser, we must make sure it <a class="reference external" href="#advance-element-class-lookup">returns
objectify trees</a>. This is best done with the <tt class="docutils literal">makeparser()</tt>
function:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">makeparser</span><span class="p">(</span><span class="n">schema</span> <span class="o">=</span> <span class="n">schema</span><span class="p">)</span>
</pre></div>
<p>Now we can use it to parse a valid document:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">xml</span> <span class="o">=</span> <span class="s">"<a><b>test</b></a>"</span>
<span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">xml</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">b</span><span class="p">)</span>
<span class="go">test</span>
</pre></div>
<p>Or an invalid document:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">xml</span> <span class="o">=</span> <span class="s">"<a><b>test</b><c/></a>"</span>
<span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="n">xml</span><span class="p">,</span> <span class="n">parser</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="gr">lxml.etree.XMLSyntaxError</span>: <span class="n">Element 'c': This element is not expected.</span>
</pre></div>
<p>Note that the same works for parse-time DTD validation, except that
DTDs do not support any data types by design.</p>
</div>
<div class="section" id="objectpath">
<h1>ObjectPath</h1>
<p>For both convenience and speed, objectify supports its own path language,
represented by the <tt class="docutils literal">ObjectPath</tt> class:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"{http://ns/}root"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">b1</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://ns/}b"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">c</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">b1</span><span class="p">,</span> <span class="s">"{http://ns/}c"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">b2</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://ns/}b"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">d</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">SubElement</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"{http://other/}d"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">path</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"root.b.c"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
<span class="go">root.b.c</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">hasattr</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}c</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"root.b.c"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}c</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"root.{http://other/}d"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://other/}d</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"root.{not}there"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: {not}there</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"{not}there"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ValueError</span>: <span class="n">root element does not match: need {not}there, got {http://ns/}root</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"root.b[1]"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"root.{http://ns/}b[1]"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
</pre></div>
<p>Apart from strings, ObjectPath also accepts lists of path segments:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">([</span><span class="s">'root'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'c'</span><span class="p">])</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}c</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">([</span><span class="s">'root'</span><span class="p">,</span> <span class="s">'{http://ns/}b[1]'</span><span class="p">])</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
</pre></div>
<p>You can also use relative paths starting with a '.' to ignore the actual root
element and only inherit its namespace:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">".b[1]"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">([</span><span class="s">''</span><span class="p">,</span> <span class="s">'b[1]'</span><span class="p">])</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}b</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">".unknown[1]"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: {http://ns/}unknown</span>
<span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">".{http://other/}unknown[1]"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: {http://other/}unknown</span>
</pre></div>
<p>For convenience, a single dot represents the empty ObjectPath (identity):</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">find</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">"."</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">{http://ns/}root</span>
</pre></div>
<p>ObjectPath objects can be used to manipulate trees:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"{http://ns/}root"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">path</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">".some.child.{http://other/}unknown"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">hasattr</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="go">False</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: {http://ns/}some</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"my value"</span><span class="p">)</span> <span class="c"># creates children as necessary</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">hasattr</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="go">my value</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">some</span><span class="o">.</span><span class="n">child</span><span class="p">[</span><span class="s">"{http://other/}unknown"</span><span class="p">]</span><span class="o">.</span><span class="n">text</span><span class="p">)</span>
<span class="go">my value</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">))</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">addattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"my new value"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">))</span>
<span class="go">2</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">text</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">]</span>
<span class="go">['my value', 'my new value']</span>
</pre></div>
<p>As with attribute assignment, <tt class="docutils literal">setattr()</tt> accepts lists:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="p">[</span><span class="s">"v1"</span><span class="p">,</span> <span class="s">"v2"</span><span class="p">,</span> <span class="s">"v3"</span><span class="p">])</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">el</span><span class="o">.</span><span class="n">text</span> <span class="k">for</span> <span class="n">el</span> <span class="ow">in</span> <span class="n">path</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="n">root</span><span class="p">)</span> <span class="p">]</span>
<span class="go">['v1', 'v2', 'v3']</span>
</pre></div>
<p>Note, however, that indexing is only supported in this context if the children
exist. Indexing of non existing children will not extend or create a list of
such children but raise an exception:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">path</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectPath</span><span class="p">(</span><span class="s">".{non}existing[1]"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">path</span><span class="o">.</span><span class="n">setattr</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="s">"my value"</span><span class="p">)</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">TypeError</span>: <span class="n">creating indexed path attributes is not supported</span>
</pre></div>
<p>It is worth noting that ObjectPath does not depend on the <tt class="docutils literal">objectify</tt> module
or the ObjectifiedElement implementation. It can also be used in combination
with Elements from the normal lxml.etree API.</p>
</div>
<div class="section" id="python-data-types">
<h1>Python data types</h1>
<p>The objectify module knows about Python data types and tries its best to let
element content behave like them. For example, they support the normal math
operators:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span>
<span class="gp">... </span> <span class="s">"<root><a>5</a><b>11</b><c>true</c><d>hoi</d></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
<span class="go">16</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+=</span> <span class="n">root</span><span class="o">.</span><span class="n">b</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="go">16</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">2</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="mi">2</span><span class="p">)</span>
<span class="go">4</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="go">3</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
<span class="go">True</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">c</span> <span class="o">=</span> <span class="bp">False</span>
<span class="gp">>>> </span><span class="k">if</span> <span class="ow">not</span> <span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"false!"</span><span class="p">)</span>
<span class="go">false!</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">+</span> <span class="s">" test !"</span><span class="p">)</span>
<span class="go">hoi test !</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">=</span> <span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">d</span> <span class="o">%</span> <span class="p">(</span><span class="mi">1234</span><span class="p">,</span> <span class="mi">12345</span><span class="p">))</span>
<span class="go">1234 - 12345</span>
</pre></div>
<p>However, data elements continue to provide the objectify API. This means that
sequence operations such as <tt class="docutils literal">len()</tt>, slicing and indexing (e.g. of strings)
cannot behave as the Python types. Like all other tree elements, they show
the normal slicing behaviour of objectify elements:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"<root><a>test</a><b>toast</b></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="s">' me'</span><span class="p">)</span> <span class="c"># behaves like a string, right?</span>
<span class="go">test me</span>
<span class="gp">>>> </span><span class="nb">len</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span> <span class="c"># but there's only one 'a' element!</span>
<span class="go">1</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="n">a</span><span class="o">.</span><span class="n">tag</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="p">]</span>
<span class="go">['a']</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">tag</span><span class="p">)</span>
<span class="go">a</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="go">test</span>
<span class="gp">>>> </span><span class="p">[</span> <span class="nb">str</span><span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">[:</span><span class="mi">1</span><span class="p">]</span> <span class="p">]</span>
<span class="go">['test']</span>
</pre></div>
<p>If you need to run sequence operations on data types, you must ask the API for
the <em>real</em> Python value. The string value is always available through the
normal ElementTree <tt class="docutils literal">.text</tt> attribute. Additionally, all data classes
provide a <tt class="docutils literal">.pyval</tt> attribute that returns the value as plain Python type:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"<root><a>test</a><b>5</b></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">text</span>
<span class="go">'test'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span>
<span class="go">'test'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">text</span>
<span class="go">'5'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">pyval</span>
<span class="go">5</span>
</pre></div>
<p>Note, however, that both attributes are read-only in objectify. If you want
to change values, just assign them directly to the attribute:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">text</span> <span class="o">=</span> <span class="s">"25"</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">TypeError</span>: <span class="n">attribute 'text' of 'StringElement' objects is not writable</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span> <span class="o">=</span> <span class="mi">25</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">TypeError</span>: <span class="n">attribute 'pyval' of 'StringElement' objects is not writable</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="mi">25</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="go">25</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">pyval</span><span class="p">)</span>
<span class="go">25</span>
</pre></div>
<p>In other words, <tt class="docutils literal">objectify</tt> data elements behave like immutable Python
types. You can replace them, but not modify them.</p>
<div class="section" id="recursive-tree-dump">
<h2>Recursive tree dump</h2>
<p>To see the data types that are currently used, you can call the module level
<tt class="docutils literal">dump()</tt> function that returns a recursive string representation for
elements:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"""</span>
<span class="gp">... </span><span class="s"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
<span class="gp">... </span><span class="s"> <a attr1="foo" attr2="bar">1</a></span>
<span class="gp">... </span><span class="s"> <a>1.2</a></span>
<span class="gp">... </span><span class="s"> <b>1</b></span>
<span class="gp">... </span><span class="s"> <b>true</b></span>
<span class="gp">... </span><span class="s"> <c>what?</c></span>
<span class="gp">... </span><span class="s"> <d xsi:nil="true"/></span>
<span class="gp">... </span><span class="s"></root></span>
<span class="gp">... </span><span class="s">"""</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 1 [IntElement]</span>
<span class="go"> * attr1 = 'foo'</span>
<span class="go"> * attr2 = 'bar'</span>
<span class="go"> a = 1.2 [FloatElement]</span>
<span class="go"> b = 1 [IntElement]</span>
<span class="go"> b = True [BoolElement]</span>
<span class="go"> c = 'what?' [StringElement]</span>
<span class="go"> d = None [NoneElement]</span>
<span class="go"> * xsi:nil = 'true'</span>
</pre></div>
<p>You can freely switch between different types for the same child:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"<root><a>5</a></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 5 [IntElement]</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="s">'nice string!'</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 'nice string!' [StringElement]</span>
<span class="go"> * py:pytype = 'str'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="bp">True</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = True [BoolElement]</span>
<span class="go"> * py:pytype = 'bool'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 1 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> a = 2 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> a = 3 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 1 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> a = 2 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> a = 3 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
</pre></div>
</div>
<div class="section" id="recursive-string-representation-of-elements">
<h2>Recursive string representation of elements</h2>
<p>Normally, elements use the standard string representation for str() that is
provided by lxml.etree. You can enable a pretty-print representation for
objectify elements like this:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">enable_recursive_str</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"""</span>
<span class="gp">... </span><span class="s"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
<span class="gp">... </span><span class="s"> <a attr1="foo" attr2="bar">1</a></span>
<span class="gp">... </span><span class="s"> <a>1.2</a></span>
<span class="gp">... </span><span class="s"> <b>1</b></span>
<span class="gp">... </span><span class="s"> <b>true</b></span>
<span class="gp">... </span><span class="s"> <c>what?</c></span>
<span class="gp">... </span><span class="s"> <d xsi:nil="true"/></span>
<span class="gp">... </span><span class="s"></root></span>
<span class="gp">... </span><span class="s">"""</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="nb">str</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 1 [IntElement]</span>
<span class="go"> * attr1 = 'foo'</span>
<span class="go"> * attr2 = 'bar'</span>
<span class="go"> a = 1.2 [FloatElement]</span>
<span class="go"> b = 1 [IntElement]</span>
<span class="go"> b = True [BoolElement]</span>
<span class="go"> c = 'what?' [StringElement]</span>
<span class="go"> d = None [NoneElement]</span>
<span class="go"> * xsi:nil = 'true'</span>
</pre></div>
<p>This behaviour can be switched off in the same way:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">enable_recursive_str</span><span class="p">(</span><span class="bp">False</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="how-data-types-are-matched">
<h1>How data types are matched</h1>
<p>Objectify uses two different types of Elements. Structural Elements (or tree
Elements) represent the object tree structure. Data Elements represent the
data containers at the leafs. You can explicitly create tree Elements with
the <tt class="docutils literal">objectify.Element()</tt> factory and data Elements with the
<tt class="docutils literal">objectify.DataElement()</tt> factory.</p>
<p>When Element objects are created, lxml.objectify must determine which
implementation class to use for them. This is relatively easy for tree
Elements and less so for data Elements. The algorithm is as follows:</p>
<ol class="arabic simple">
<li>If an element has children, use the default tree class.</li>
<li>If an element is defined as xsi:nil, use the NoneElement class.</li>
<li>If a "Python type hint" attribute is given, use this to determine the element
class, see below.</li>
<li>If an XML Schema xsi:type hint is given, use this to determine the element
class, see below.</li>
<li>Try to determine the element class from the text content type by trial and
error.</li>
<li>If the element is a root node then use the default tree class.</li>
<li>Otherwise, use the default class for empty data classes.</li>
</ol>
<p>You can change the default classes for tree Elements and empty data Elements
at setup time. The <tt class="docutils literal">ObjectifyElementClassLookup()</tt> call accepts two keyword
arguments, <tt class="docutils literal">tree_class</tt> and <tt class="docutils literal">empty_data_class</tt>, that determine the Element
classes used in these cases. By default, <tt class="docutils literal">tree_class</tt> is a class called
<tt class="docutils literal">ObjectifiedElement</tt> and <tt class="docutils literal">empty_data_class</tt> is a <tt class="docutils literal">StringElement</tt>.</p>
<div class="section" id="type-annotations">
<h2>Type annotations</h2>
<p>The "type hint" mechanism deploys an XML attribute defined as
<tt class="docutils literal">lxml.objectify.PYTYPE_ATTRIBUTE</tt>. It may contain any of the following
string values: int, long, float, str, unicode, NoneType:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">PYTYPE_ATTRIBUTE</span><span class="p">)</span>
<span class="go">{http://codespeak.net/lxml/objectify/pytype}pytype</span>
<span class="gp">>>> </span><span class="n">ns</span><span class="p">,</span> <span class="n">name</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">PYTYPE_ATTRIBUTE</span><span class="p">[</span><span class="mi">1</span><span class="p">:]</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">'}'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"""</span><span class="se">\</span>
<span class="gp">... </span><span class="s"><root xmlns:py='</span><span class="si">%s</span><span class="s">'></span>
<span class="gp">... </span><span class="s"> <a py:pytype='str'>5</a></span>
<span class="gp">... </span><span class="s"> <b py:pytype='int'>5</b></span>
<span class="gp">... </span><span class="s"> <c py:pytype='NoneType' /></span>
<span class="gp">... </span><span class="s"></root></span>
<span class="gp">... </span><span class="s">"""</span> <span class="o">%</span> <span class="n">ns</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span> <span class="o">+</span> <span class="mi">10</span><span class="p">)</span>
<span class="go">510</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">b</span> <span class="o">+</span> <span class="mi">10</span><span class="p">)</span>
<span class="go">15</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">c</span><span class="p">)</span>
<span class="go">None</span>
</pre></div>
<p>Note that you can change the name and namespace used for this
attribute through the <tt class="docutils literal">set_pytype_attribute_tag(tag)</tt> module
function, in case your application ever needs to. There is also a
utility function <tt class="docutils literal">annotate()</tt> that recursively generates this
attribute for the elements of a tree:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"<root><a>test</a><b>5</b></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 'test' [StringElement]</span>
<span class="go"> b = 5 [IntElement]</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 'test' [StringElement]</span>
<span class="go"> * py:pytype = 'str'</span>
<span class="go"> b = 5 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
</pre></div>
</div>
<div class="section" id="xml-schema-datatype-annotation">
<h2>XML Schema datatype annotation</h2>
<p>A second way of specifying data type information uses XML Schema types as
element annotations. Objectify knows those that can be mapped to normal
Python types:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
<span class="gp">... </span><span class="s"> xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
<span class="gp">... </span><span class="s"> <d xsi:type="xsd:double">5</d></span>
<span class="gp">... </span><span class="s"> <i xsi:type="xsd:int" >5</i></span>
<span class="gp">... </span><span class="s"> <s xsi:type="xsd:string">5</s></span>
<span class="gp">... </span><span class="s"> </root></span>
<span class="gp">... </span><span class="s"> '''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> d = 5.0 [FloatElement]</span>
<span class="go"> * xsi:type = 'xsd:double'</span>
<span class="go"> i = 5 [IntElement]</span>
<span class="go"> * xsi:type = 'xsd:int'</span>
<span class="go"> s = '5' [StringElement]</span>
<span class="go"> * xsi:type = 'xsd:string'</span>
</pre></div>
<p>Again, there is a utility function <tt class="docutils literal">xsiannotate()</tt> that recursively
generates the "xsi:type" attribute for the elements of a tree:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> <root><a>test</a><b>5</b><c>true</c></root></span>
<span class="gp">... </span><span class="s"> '''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 'test' [StringElement]</span>
<span class="go"> b = 5 [IntElement]</span>
<span class="go"> c = True [BoolElement]</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">xsiannotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> a = 'test' [StringElement]</span>
<span class="go"> * xsi:type = 'xsd:string'</span>
<span class="go"> b = 5 [IntElement]</span>
<span class="go"> * xsi:type = 'xsd:integer'</span>
<span class="go"> c = True [BoolElement]</span>
<span class="go"> * xsi:type = 'xsd:boolean'</span>
</pre></div>
<p>Note, however, that <tt class="docutils literal">xsiannotate()</tt> will always use the first XML Schema
datatype that is defined for any given Python type, see also
<a class="reference internal" href="#defining-additional-data-classes">Defining additional data classes</a>.</p>
<p>The utility function <tt class="docutils literal">deannotate()</tt> can be used to get rid of 'py:pytype'
and/or 'xsi:type' information:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
<span class="gp">... </span><span class="s"> xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
<span class="gp">... </span><span class="s"> <d xsi:type="xsd:double">5</d></span>
<span class="gp">... </span><span class="s"> <i xsi:type="xsd:int" >5</i></span>
<span class="gp">... </span><span class="s"> <s xsi:type="xsd:string">5</s></span>
<span class="gp">... </span><span class="s"></root>'''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> d = 5.0 [FloatElement]</span>
<span class="go"> * xsi:type = 'xsd:double'</span>
<span class="go"> * py:pytype = 'float'</span>
<span class="go"> i = 5 [IntElement]</span>
<span class="go"> * xsi:type = 'xsd:int'</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> s = '5' [StringElement]</span>
<span class="go"> * xsi:type = 'xsd:string'</span>
<span class="go"> * py:pytype = 'str'</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">deannotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> d = 5 [IntElement]</span>
<span class="go"> i = 5 [IntElement]</span>
<span class="go"> s = 5 [IntElement]</span>
</pre></div>
<p>You can control which type attributes should be de-annotated with the keyword
arguments 'pytype' (default: True) and 'xsi' (default: True).
<tt class="docutils literal">deannotate()</tt> can also remove 'xsi:nil' attributes by setting 'xsi_nil=True'
(default: False):</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"><root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"</span>
<span class="gp">... </span><span class="s"> xmlns:xsd="http://www.w3.org/2001/XMLSchema"></span>
<span class="gp">... </span><span class="s"> <d xsi:type="xsd:double">5</d></span>
<span class="gp">... </span><span class="s"> <i xsi:type="xsd:int" >5</i></span>
<span class="gp">... </span><span class="s"> <s xsi:type="xsd:string">5</s></span>
<span class="gp">... </span><span class="s"> <n xsi:nil="true"/></span>
<span class="gp">... </span><span class="s"></root>'''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">annotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> d = 5.0 [FloatElement]</span>
<span class="go"> * xsi:type = 'xsd:double'</span>
<span class="go"> * py:pytype = 'float'</span>
<span class="go"> i = 5 [IntElement]</span>
<span class="go"> * xsi:type = 'xsd:int'</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> s = '5' [StringElement]</span>
<span class="go"> * xsi:type = 'xsd:string'</span>
<span class="go"> * py:pytype = 'str'</span>
<span class="go"> n = None [NoneElement]</span>
<span class="go"> * xsi:nil = 'true'</span>
<span class="go"> * py:pytype = 'NoneType'</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">deannotate</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">xsi_nil</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> d = 5 [IntElement]</span>
<span class="go"> i = 5 [IntElement]</span>
<span class="go"> s = 5 [IntElement]</span>
<span class="go"> n = u'' [StringElement]</span>
</pre></div>
<p>Note that <tt class="docutils literal">deannotate()</tt> does not remove the namespace declarations
of the <tt class="docutils literal">pytype</tt> namespace by default. To remove them as well, and
to generally clean up the namespace declarations in the document
(usually when done with the whole processing), pass the option
<tt class="docutils literal">cleanup_namespaces=True</tt>. This option is new in lxml 2.3.2. In
older versions, use the function <tt class="docutils literal">lxml.etree.cleanup_namespaces()</tt>
instead.</p>
</div>
<div class="section" id="the-dataelement-factory">
<h2>The DataElement factory</h2>
<p>For convenience, the <tt class="docutils literal">DataElement()</tt> factory creates an Element with a
Python value in one step. You can pass the required Python type name or the
XSI type name:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"root"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_pytype</span><span class="o">=</span><span class="s">"int"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> x = 5 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_pytype</span><span class="o">=</span><span class="s">"str"</span><span class="p">,</span> <span class="n">myattr</span><span class="o">=</span><span class="s">"someval"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> x = '5' [StringElement]</span>
<span class="go"> * myattr = 'someval'</span>
<span class="go"> * py:pytype = 'str'</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">x</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">"integer"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">dump</span><span class="p">(</span><span class="n">root</span><span class="p">))</span>
<span class="go">root = None [ObjectifiedElement]</span>
<span class="go"> x = 5 [IntElement]</span>
<span class="go"> * py:pytype = 'int'</span>
<span class="go"> * xsi:type = 'xsd:integer'</span>
</pre></div>
<p>XML Schema types reside in the XML schema namespace thus <tt class="docutils literal">DataElement()</tt>
tries to correctly prefix the xsi:type attribute value for you:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">Element</span><span class="p">(</span><span class="s">"root"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">s</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">"string"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">deannotate</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">xsi</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
<span class="go"> <s xsi:type="xsd:string">5</s></span>
<span class="go"></root></span>
</pre></div>
<p><tt class="docutils literal">DataElement()</tt> uses a default nsmap to set these prefixes:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">'string'</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">namespaces</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">nsmap</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
<span class="gp">>>> </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span> <span class="ow">in</span> <span class="n">namespaces</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span><span class="p">))</span>
<span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
<span class="go">xsd - http://www.w3.org/2001/XMLSchema</span>
<span class="go">xsi - http://www.w3.org/2001/XMLSchema-instance</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
<span class="go">xsd:string</span>
</pre></div>
<p>While you can set custom namespace prefixes, it is necessary to provide valid
namespace information if you choose to do so:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">'foo:string'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="s">'foo'</span><span class="p">:</span> <span class="s">'http://www.w3.org/2001/XMLSchema'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">namespaces</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">nsmap</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
<span class="gp">>>> </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span> <span class="ow">in</span> <span class="n">namespaces</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span><span class="p">))</span>
<span class="go">foo - http://www.w3.org/2001/XMLSchema</span>
<span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
<span class="go">xsi - http://www.w3.org/2001/XMLSchema-instance</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
<span class="go">foo:string</span>
</pre></div>
<p>Note how lxml chose a default prefix for the XML Schema Instance
namespace. We can override it as in the following example:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">el</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s">'5'</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">'foo:string'</span><span class="p">,</span>
<span class="gp">... </span> <span class="n">nsmap</span><span class="o">=</span><span class="p">{</span><span class="s">'foo'</span><span class="p">:</span> <span class="s">'http://www.w3.org/2001/XMLSchema'</span><span class="p">,</span>
<span class="gp">... </span> <span class="s">'myxsi'</span><span class="p">:</span> <span class="s">'http://www.w3.org/2001/XMLSchema-instance'</span><span class="p">})</span>
<span class="gp">>>> </span><span class="n">namespaces</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">nsmap</span><span class="o">.</span><span class="n">items</span><span class="p">())</span>
<span class="gp">>>> </span><span class="n">namespaces</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
<span class="gp">>>> </span><span class="k">for</span> <span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span> <span class="ow">in</span> <span class="n">namespaces</span><span class="p">:</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"</span><span class="si">%s</span><span class="s"> - </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">prefix</span><span class="p">,</span> <span class="n">namespace</span><span class="p">))</span>
<span class="go">foo - http://www.w3.org/2001/XMLSchema</span>
<span class="go">myxsi - http://www.w3.org/2001/XMLSchema-instance</span>
<span class="go">py - http://codespeak.net/lxml/objectify/pytype</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">el</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"{http://www.w3.org/2001/XMLSchema-instance}type"</span><span class="p">))</span>
<span class="go">foo:string</span>
</pre></div>
<p>Care must be taken if different namespace prefixes have been used for the same
namespace. Namespace information gets merged to avoid duplicate definitions
when adding a new sub-element to a tree, but this mechanism does not adapt the
prefixes of attribute values:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">"""<root xmlns:schema="http://www.w3.org/2001/XMLSchema"/>"""</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns:schema="http://www.w3.org/2001/XMLSchema"/></span>
<span class="gp">>>> </span><span class="n">s</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">DataElement</span><span class="p">(</span><span class="s">"17"</span><span class="p">,</span> <span class="n">_xsi</span><span class="o">=</span><span class="s">"string"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><value xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" py:pytype="str" xsi:type="xsd:string">17</value></span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">s</span> <span class="o">=</span> <span class="n">s</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns:schema="http://www.w3.org/2001/XMLSchema"></span>
<span class="go"> <s xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" py:pytype="str" xsi:type="xsd:string">17</s></span>
<span class="go"></root></span>
</pre></div>
<p>It is your responsibility to fix the prefixes of attribute values if you
choose to deviate from the standard prefixes. A convenient way to do this for
xsi:type attributes is to use the <tt class="docutils literal">xsiannotate()</tt> utility:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">objectify</span><span class="o">.</span><span class="n">xsiannotate</span><span class="p">(</span><span class="n">root</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">etree</span><span class="o">.</span><span class="n">tostring</span><span class="p">(</span><span class="n">root</span><span class="p">,</span> <span class="n">pretty_print</span><span class="o">=</span><span class="bp">True</span><span class="p">))</span>
<span class="go"><root xmlns:schema="http://www.w3.org/2001/XMLSchema"></span>
<span class="go"> <s xmlns:py="http://codespeak.net/lxml/objectify/pytype" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" py:pytype="str" xsi:type="schema:string">17</s></span>
<span class="go"></root></span>
</pre></div>
<p>Of course, it is discouraged to use different prefixes for one and the same
namespace when building up an objectify tree.</p>
</div>
<div class="section" id="defining-additional-data-classes">
<h2>Defining additional data classes</h2>
<p>You can plug additional data classes into objectify that will be used in
exactly the same way as the predefined types. Data classes can either inherit
from <tt class="docutils literal">ObjectifiedDataElement</tt> directly or from one of the specialised
classes like <tt class="docutils literal">NumberElement</tt> or <tt class="docutils literal">BoolElement</tt>. The numeric types require
an initial call to the NumberElement method <tt class="docutils literal">self._setValueParser(function)</tt>
to set their type conversion function (string -> numeric Python type). This
call should be placed into the element <tt class="docutils literal">_init()</tt> method.</p>
<p>The registration of data classes uses the <tt class="docutils literal">PyType</tt> class:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="k">class</span> <span class="nc">ChristmasDate</span><span class="p">(</span><span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifiedDataElement</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">def</span> <span class="nf">call_santa</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">print</span><span class="p">(</span><span class="s">"Ho ho ho!"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">def</span> <span class="nf">checkChristmasDate</span><span class="p">(</span><span class="n">date_string</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">if</span> <span class="ow">not</span> <span class="n">date_string</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">'24.12.'</span><span class="p">):</span>
<span class="gp">... </span> <span class="k">raise</span> <span class="ne">ValueError</span> <span class="c"># or TypeError</span>
<span class="gp">>>> </span><span class="n">xmas_type</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">PyType</span><span class="p">(</span><span class="s">'date'</span><span class="p">,</span> <span class="n">checkChristmasDate</span><span class="p">,</span> <span class="n">ChristmasDate</span><span class="p">)</span>
</pre></div>
<p>The PyType constructor takes a string type name, an (optional) callable type
check and the custom data class. If a type check is provided it must accept a
string as argument and raise ValueError or TypeError if it cannot handle the
string value.</p>
<p>PyTypes are used if an element carries a <tt class="docutils literal">py:pytype</tt> attribute denoting its
data type or, in absence of such an attribute, if the given type check callable
does not raise a ValueError/TypeError exception when applied to the element
text.</p>
<p>If you want, you can also register this type under an XML Schema type name:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">xmlSchemaTypes</span> <span class="o">=</span> <span class="p">(</span><span class="s">"date"</span><span class="p">,)</span>
</pre></div>
<p>XML Schema types will be considered if the element has an <tt class="docutils literal">xsi:type</tt>
attribute that specifies its data type. The line above binds the XSD type
<tt class="docutils literal">date</tt> to the newly defined Python type. Note that this must be done before
the next step, which is to register the type. Then you can use it:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">register</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span>
<span class="gp">... </span> <span class="s">"<root><a>24.12.2000</a><b>12.24.2000</b></root>"</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
<span class="go">Ho ho ho!</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">b</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: call_santa</span>
</pre></div>
<p>If you need to specify dependencies between the type check functions, you can
pass a sequence of type names through the <tt class="docutils literal">before</tt> and <tt class="docutils literal">after</tt> keyword
arguments of the <tt class="docutils literal">register()</tt> method. The PyType will then try to register
itself before or after the respective types, as long as they are currently
registered. Note that this only impacts the currently registered types at the
time of registration. Types that are registered later on will not care about
the dependencies of already registered types.</p>
<p>If you provide XML Schema type information, this will override the type check
function defined above:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">fromstring</span><span class="p">(</span><span class="s">'''</span><span class="se">\</span>
<span class="gp">... </span><span class="s"> <root xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"></span>
<span class="gp">... </span><span class="s"> <a xsi:type="date">12.24.2000</a></span>
<span class="gp">... </span><span class="s"> </root></span>
<span class="gp">... </span><span class="s"> '''</span><span class="p">)</span>
<span class="gp">>>> </span><span class="k">print</span><span class="p">(</span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="p">)</span>
<span class="go">12.24.2000</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
<span class="go">Ho ho ho!</span>
</pre></div>
<p>To unregister a type, call its <tt class="docutils literal">unregister()</tt> method:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
<span class="go">Ho ho ho!</span>
<span class="gp">>>> </span><span class="n">xmas_type</span><span class="o">.</span><span class="n">unregister</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">root</span><span class="o">.</span><span class="n">a</span><span class="o">.</span><span class="n">call_santa</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AttributeError</span>: <span class="n">no such child: call_santa</span>
</pre></div>
<p>Be aware, though, that this does not immediately apply to elements to which
there already is a Python reference. Their Python class will only be changed
after all references are gone and the Python object is garbage collected.</p>
</div>
<div class="section" id="advanced-element-class-lookup">
<h2>Advanced element class lookup</h2>
<p>In some cases, the normal data class setup is not enough. Being based
on <tt class="docutils literal">lxml.etree</tt>, however, <tt class="docutils literal">lxml.objectify</tt> supports very
fine-grained control over the Element classes used in a tree. All you
have to do is configure a different <a class="reference external" href="element_classes.html">class lookup</a> mechanism (or
write one yourself).</p>
<p>The first step for the setup is to create a new parser that builds
objectify documents. The objectify API is meant for data-centric XML
(as opposed to document XML with mixed content). Therefore, we
configure the parser to let it remove whitespace-only text from the
parsed document if it is not enclosed by an XML element. Note that
this alters the document infoset, so if you consider the removed
spaces as data in your specific use case, you should go with a normal
parser and just set the element class lookup. Most applications,
however, will work fine with the following setup:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">makeparser</span><span class="p">(</span><span class="n">remove_blank_text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
<p>What this does internally, is:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">XMLParser</span><span class="p">(</span><span class="n">remove_blank_text</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
<span class="gp">>>> </span><span class="n">lookup</span> <span class="o">=</span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifyElementClassLookup</span><span class="p">()</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_element_class_lookup</span><span class="p">(</span><span class="n">lookup</span><span class="p">)</span>
</pre></div>
<p>If you want to change the lookup scheme, say, to get additional
support for <a class="reference external" href="element_classes.html#namespace-class-lookup">namespace specific classes</a>, you can register the
objectify lookup as a fallback of the namespace lookup. In this case,
however, you have to take care that the namespace classes inherit from
<tt class="docutils literal">objectify.ObjectifiedElement</tt>, not only from the normal
<tt class="docutils literal">lxml.etree.ElementBase</tt>, so that they support the <tt class="docutils literal">objectify</tt>
API. The above setup code then becomes:</p>
<div class="syntax"><pre><span class="gp">>>> </span><span class="n">lookup</span> <span class="o">=</span> <span class="n">etree</span><span class="o">.</span><span class="n">ElementNamespaceClassLookup</span><span class="p">(</span>
<span class="gp">... </span> <span class="n">objectify</span><span class="o">.</span><span class="n">ObjectifyElementClassLookup</span><span class="p">()</span> <span class="p">)</span>
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">set_element_class_lookup</span><span class="p">(</span><span class="n">lookup</span><span class="p">)</span>
</pre></div>
<p>See the documentation on <a class="reference external" href="element_classes.html">class lookup</a> schemes for more information.</p>
</div>
</div>
<div class="section" id="what-is-different-from-lxml-etree">
<h1>What is different from lxml.etree?</h1>
<p>Such a different Element API obviously implies some side effects to the normal
behaviour of the rest of the API.</p>
<ul class="simple">
<li>len(<element>) returns the sibling count, not the number of children of
<element>. You can retrieve the number of children with the
<tt class="docutils literal">countchildren()</tt> method.</li>
<li>Iteration over elements does not yield the children, but the siblings. You
can access all children with the <tt class="docutils literal">iterchildren()</tt> method on elements or
retrieve a list by calling the <tt class="docutils literal">getchildren()</tt> method.</li>
<li>The find, findall and findtext methods require a different implementation
based on ETXPath. In <tt class="docutils literal">lxml.etree</tt>, they use a Python implementation based
on the original iteration scheme. This has the disadvantage that they may
not be 100% backwards compatible, and the additional advantage that they now
support any XPath expression.</li>
</ul>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2014-03-04.
</div>
</body>
</html>
|